Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ If blocked, pick the simplest viable default, record it in `DECISIONS.md`, and m
`CONSTITUTION.md` holds the full invariants; do not modify it without a `DECISIONS.md` entry. No "temporary hacks" that violate it.

## Active track
- **Now:** S12.4 HIL appliance v0 physical loop (serial observer first, then power/reset actuation), feeding S13 metal HIL graduation. S14 USB xHCI + HID is deferred to a design pass.
- **Now:** S12.4 HIL appliance v0 physical loop (serial observer first, then power/reset actuation), feeding the preferred appliance-mediated S13 metal HIL graduation path. Standalone golden-machine `PASS/METAL` must be provenance-stamped separately. S14 USB xHCI + HID is deferred to a design pass.
- **Authoritative pair:** `CURRENT_STATUS.md` + `NEXT_TASKS.md` (deferred decisions in `ROADMAP.md` §13). `SLICES.md` has slice history.
- **Keep green:** `just s11`, `just s12`, `just s13`, and `just foundry-org-governance-g0` when touching org/research planning.

Expand Down
8 changes: 8 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,12 @@
## [Unreleased]

### Changed
- Made HIL metal evidence path-disclosing: per-gate HIL JSON now carries
`claim_path` plus appliance metadata, and docs distinguish standalone
`operator-golden-machine` PASS/METAL from `appliance-mediated` graduation.
- Corrected POSIX runner security claims to match the default
host-portable-rlimits-only runtime profile; seccomp/chroot/namespace helpers
remain tested but are not default-wired.
- Reworked the documentation entry points so `CURRENT_STATUS.md` records landed
state, `NEXT_TASKS.md` is an executable queue, and `ROADMAP.md` stays
directional.
Expand All @@ -14,6 +20,8 @@
S13, HIL appliance, security, risk, and contributor documentation.

### Added
- Added Foundry checks for per-gate HIL `claim_path` evidence and for the POSIX
runner default sandbox profile contract.
- G0 RamenOrg / research-backed OS scaffold:
- Added `docs/plans/2026-06-23-research-backed-ramenorg.md` to make RamenOrg and research-backed development first-class planning tracks without displacing S12.4/S13 HIL work.
- Added `docs/org/` with RamenOrg constitution, role charter, authority levels, heartbeats, `WorkOrderV0`, `HandoffPacketV0`, `BoardVoteV0`, and claim safety.
Expand Down
11 changes: 8 additions & 3 deletions CURRENT_STATUS.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,9 +7,11 @@
## Active Execution Track

S12.4 is building the physical HIL appliance loop: serial observation first,
then power/reset actuation. Once that loop is stable, S13 metal HIL graduation
runs through the appliance on Tier-1 or lab hardware. S14 USB xHCI and HID stays
deferred until the appliance loop is proven.
then power/reset actuation. Once that loop is stable, the preferred S13 metal
HIL graduation path runs through the appliance on Tier-1 or lab hardware.
Standalone golden-machine graduation remains a distinct `PASS/METAL` path only
when per-gate evidence stamps `claim_path: operator-golden-machine`. S14 USB
xHCI and HID stays deferred until the appliance loop is proven.

The next executable step is maintained in [NEXT_TASKS.md](NEXT_TASKS.md).
Medium-range sequencing and deferred decisions live in [ROADMAP.md](ROADMAP.md).
Expand Down Expand Up @@ -39,6 +41,9 @@ see [EVIDENCE_LEVELS.md](EVIDENCE_LEVELS.md).
- S12.4.0 HIL appliance manifest, evidence wrapper, and inventory gate.
- S12.4.1 serial-observer scaffold with run-id validation, empty-transcript
rejection, and replay/live evidence separation.
- Per-gate HIL evidence now stamps `claim_path` and appliance metadata so
standalone golden-machine runs cannot be mistaken for appliance-mediated
graduation.
- S13.0 persistent-storage contract and `harness.block` IDL.
- S13.2-S13.5 virtio-blk Oracle capture and replay scoreboards.
- S13.6 runtime `harness.block` sector I/O in QEMU.
Expand Down
40 changes: 39 additions & 1 deletion DECISIONS.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# DECISIONS (ADR-lite)

**Last Updated:** 2026-06-23
**Last Updated:** 2026-06-24
**Status:** Active

## 2026-02-03 — Monorepo with hard boundaries
Expand Down Expand Up @@ -170,6 +170,44 @@ Manual reboot/capture workflows do not scale to agentic OS development or hardwa

**CI policy:** Default CI validates docs/manifests only. Hardware controller checks require `RAMEN_HIL_APPLIANCE=1`. Graduation runs require `RAMEN_HIL_APPLIANCE=1 RAMEN_HIL_GRADUATION=1` and disallow stale serial-log replay.

## 2026-06-24 — HIL metal claims must disclose the run path
The evidence taxonomy allows standalone Tier-1 golden-machine `PASS/METAL`
when `RAMEN_HIL_GRADUATION=1`, live serial capture, target-emitted
`hil_evidence:` markers, and per-gate evidence JSON are present. The active
S12.4/S13 execution queue still prefers appliance-mediated graduation before
claiming the S13 slice complete.

**Chosen:** Keep standalone golden-machine graduation legitimate, but make the
path machine-readable. Per-gate HIL JSON now carries `claim_path`:
`operator-golden-machine` for standalone live graduation and
`appliance-mediated` when `RAMEN_HIL_APPLIANCE=1`. Appliance-mediated runs also
include an `appliance` object with controller identity and evidence references.

**Rejected:** Silently treating every `PASS/METAL` as appliance-mediated, or
requiring the appliance for all future `PASS/METAL` claims before S12.4.2 power
actuation has landed.

**Gate:** `just hil-appliance` validates both claim paths in per-gate evidence
fixtures.

## 2026-06-24 — POSIX runner default profile is rlimits-only
The POSIX compatibility runner remains a development scaffold. Its default
`posix_run_v0_sandboxed` profile uses a host-portable configuration:
`seccomp=false`, `namespaces=false`, `chroot=false`, and `rlimits=true`.
Seccomp, namespace, and chroot helpers remain implemented and tested in
`sandbox.rs`, but are not wired into the default runner path because they are
not portable on unprivileged CI hosts.

**Chosen:** Report the actual profile in runtime logs and documentation instead
of claiming full sandbox containment. Keep `RAMEN_POSIX_RUNNER_ACK_RISK=1` as
the explicit execution gate and track full default sandboxing as future work.

**Rejected:** Enabling seccomp/chroot/namespaces in this honesty patch without a
new portable pre-exec design and gate-first rollout.

**Gate:** `just foundry-s7-posix-runner-security` now checks the logged default
profile and a unit contract for the rlimits-only configuration.

## 2026-06-23 — RamenOrg starts as an Org Kernel, not an ambient AI board
The project already uses agents heavily, but the founder is still often acting as
the message bus between planning, implementation, review, evidence, and status
Expand Down
42 changes: 38 additions & 4 deletions EVIDENCE_LEVELS.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Evidence Levels

**Last Updated:** 2026-06-22
**Last Updated:** 2026-06-24
**Status:** Authoritative for HIL gate reporting

Foundry gates may print `PASS`, but **PASS is not one thing**. Use these levels in gates, docs, and evidence JSON.
Expand All @@ -13,7 +13,7 @@ Foundry gates may print `PASS`, but **PASS is not one thing**. Use these levels
| `PASS/HIL-LOG` | Operator-provided serial log replay (`RAMEN_HIL_SERIAL_LOG`) | Development convenience; **not** metal graduation |
| `PASS/HIL-LIVE` | Serial captured from `RAMEN_HIL_SERIAL_DEV` during this gate run | Lab evidence; still weaker than graduation |
| `PASS/HIL-APPLIANCE` | Live serial captured by the appliance plus controller power/reset transcript | Appliance-mediated lab evidence; bridge toward autonomous CI |
| `PASS/METAL` | `RAMEN_HIL_GRADUATION=1` + live serial + `hil_evidence:` provenance markers + evidence JSON bundle | Tier-1 / golden-machine graduation |
| `PASS/METAL` | `RAMEN_HIL_GRADUATION=1` + live serial + `hil_evidence:` provenance markers + evidence JSON bundle with `claim_path` | Tier-1 / golden-machine graduation |

## Graduation mode

Expand All @@ -23,14 +23,29 @@ Set for serious metal runs:
export RAMEN_HIL_GOLDEN_MACHINE=1
export RAMEN_HIL_GRADUATION=1
export RAMEN_HIL_SERIAL_DEV=/dev/ttyUSB0
# optional: export RAMEN_HIL_APPLIANCE=1
# optional: export RAMEN_HIL_APPLIANCE=1 # stamps claim_path=appliance-mediated
# optional: export RAMEN_HIL_APPLIANCE_ID=pi-hil-01
# optional: export RAMEN_HIL_MACHINE_ID=amd-ryzen-lab # default: intel-nuc-12-reference
```

`RAMEN_HIL_GRADUATION=1` **disallows** `RAMEN_HIL_SERIAL_LOG` (stale/copied logs).

When `RAMEN_HIL_APPLIANCE=1`, the evidence bundle must also include controller identity and power/reset events from `hardware/hil_appliance_v0.toml`.
Every HIL evidence JSON must include `claim_path` so a standalone operator
golden-machine graduation cannot be mistaken for an appliance-mediated run:

- `operator-golden-machine` — `PASS/METAL` from live serial and target-emitted
provenance markers without the appliance controller.
- `appliance-mediated` — `PASS/METAL` from live serial and target-emitted
provenance markers while `RAMEN_HIL_APPLIANCE=1`.
- `development-log-replay`, `operator-live`, `appliance-live`, and
`qemu-or-scaffold` — lower-evidence paths that must not be reported as metal
graduation.

When `RAMEN_HIL_APPLIANCE=1`, the per-gate evidence bundle must also include an
`appliance` object with controller identity and controller evidence references
from `hardware/hil_appliance_v0.toml`. Power/reset events may be empty during
the serial-observer-only S12.4.1 scaffold, but must be populated once actuation
is part of the run.

## Serial provenance markers

Expand Down Expand Up @@ -66,6 +81,24 @@ HIL gates write JSON under `out/evidence/`:

The appliance wrapper may correlate per-gate evidence files via `gate_evidence`, but it must not replace those gate-owned evidence files.

Per-gate HIL JSON includes:

```json
{
"evidence_level": "PASS/METAL",
"claim_path": "operator-golden-machine",
"appliance": {
"enabled": false,
"appliance_id": "",
"target_id": "",
"controller_evidence": "",
"controller_log": "",
"controller_log_sha256": "",
"power_events": []
}
}
```

## Claim safety (S13)

| Safe claim | Unsafe claim |
Expand All @@ -75,5 +108,6 @@ The appliance wrapper may correlate per-gate evidence files via `gate_evidence`,
| A/B UEFI metadata recognized (S13.8 scaffold) | Atomic update/rollback proved on metal |
| Appliance captured target-emitted evidence | Appliance observations are target truth |
| S13.7/S13.8 **gate scaffolds** complete | S13 slice **complete** |
| S13 `PASS/METAL` with `claim_path=operator-golden-machine` | S13 appliance-mediated graduation complete |

S13 is **complete** only after `PASS/METAL` on Tier-1 class hardware for both S13.7 and S13.8 with the full two-boot atomic-update protocol (future hardening). Appliance evidence improves reproducibility but does not replace target-emitted provenance markers.
7 changes: 5 additions & 2 deletions NEXT_TASKS.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,13 +8,13 @@

## Active Execution Track

**Now:** Implement the S12.4 HIL appliance v0 physical loop: stabilize the serial observer, then add the power/reset actuator. Run S13 metal HIL graduation through the appliance once that loop is stable.
**Now:** Implement the S12.4 HIL appliance v0 physical loop: stabilize the serial observer, then add the power/reset actuator. Run S13 metal HIL graduation through the appliance once that loop is stable; standalone golden-machine `PASS/METAL` remains valid only when evidence JSON stamps `claim_path: operator-golden-machine`.

| Priority | Task | Completion signal |
|----------|------|-------------------|
| P0 | S12.4.1 HIL appliance serial observer | `RAMEN_HIL_APPLIANCE=1 just hil-appliance` captures live serial and emits valid controller evidence |
| P1 | S12.4.2 HIL appliance power/reset actuator | Power and reset scripts are fail-safe, dry-run tested, and represented in controller evidence JSON |
| P2 | S13 metal HIL graduation through the appliance | `RAMEN_HIL_APPLIANCE=1 RAMEN_HIL_GRADUATION=1 just s13-hil` produces valid live provenance |
| P2 | S13 metal HIL graduation through the appliance | `RAMEN_HIL_APPLIANCE=1 RAMEN_HIL_GRADUATION=1 just s13-hil` produces valid live provenance with `claim_path: appliance-mediated` |
| P3 | S12 physical graduation through the appliance | `RAMEN_HIL_APPLIANCE=1 RAMEN_HIL_GOLDEN_MACHINE=1 just s12-hil` produces valid live provenance |
| P4 | S14 USB xHCI and HID design pass | Approved short plan, IDL boundary, and Foundry gate definition before implementation |

Expand All @@ -28,6 +28,9 @@
- `just hil-appliance` remains green in its default docs/manifest mode and its
opt-in appliance mode.
- No `PASS/METAL` claim is emitted without the required target provenance.
- S13 per-gate evidence distinguishes standalone
`claim_path: operator-golden-machine` from appliance-mediated
`claim_path: appliance-mediated` runs.

### P1 Acceptance Criteria

Expand Down
7 changes: 4 additions & 3 deletions SECURITY_STATUS.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ implementations.
| Artifact identity | Strict content IDs and signature-aware Store paths |
| Store access | Credential/capability checks and domain-scoped visibility |
| Native execution | Typed manifests and capability-broker grants |
| POSIX compatibility | Explicit opt-in plus Linux sandbox controls where supported |
| POSIX compatibility | Explicit opt-in plus a host-portable rlimits-only default profile; seccomp/chroot/namespace helpers are tested but not default-wired |
| Kernel fast paths | Capability kind, generation, and rights validation |
| Wire formats | Versioned IDL and fail-closed length/encoding checks |
| Shared memory | Typed control plane, kernel validation, and domain accounting |
Expand All @@ -40,8 +40,9 @@ The detailed POSIX operating constraints remain in
- **Static kernel limits:** fixed-size capability, shared-memory, and allocator
structures can still produce controlled denial of service.
- **Hardware trust:** S12/S13 do not yet have full `PASS/METAL` evidence.
- **Compatibility isolation:** seccomp, namespaces, and chroot are platform-
dependent layers, not proof of containment against kernel compromise.
- **Compatibility isolation:** the default POSIX runner profile is rlimits-only;
seccomp, namespaces, and chroot are helper controls, not current default
containment.
- **Security assurance:** no formal verification, independent audit, or stable
release threat model has been completed.

Expand Down
9 changes: 8 additions & 1 deletion docs/HIL_APPLIANCE_EVIDENCE_V0.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# HIL Appliance Evidence V0

**Last Updated:** 2026-06-22
**Last Updated:** 2026-06-24
**Status:** Scaffold schema for S12.4 / S13.9
**Gate:** `tools/ci/foundry_hil_appliance_s12_4.sh`

Expand Down Expand Up @@ -32,13 +32,20 @@ hil_appliance_<run_id>.json

Per-gate evidence remains claim-bearing. Appliance evidence records the run context and correlates logs, power events, and controller observations. See `EVIDENCE_LEVELS.md` for the canonical claim-safety language.

Per-gate HIL evidence also carries `claim_path`. Appliance wrapper evidence uses
`PASS/HIL-APPLIANCE`; per-gate S13 metal evidence uses `PASS/METAL` with
`claim_path: appliance-mediated` when the appliance is present, or
`claim_path: operator-golden-machine` for standalone live golden-machine
graduation.

## Required JSON shape

```json
{
"schema_version": 1,
"evidence_kind": "hil_appliance_run_v0",
"evidence_level": "PASS/HIL-APPLIANCE",
"claim_path": "appliance-mediated",
"run_id": "hil_appliance_20260622T131700Z_pi-hil-01_s13-hil",
"appliance_id": "pi-hil-01",
"target_id": "intel-nuc-12-reference",
Expand Down
Loading
Loading