Skip to content

Roadmap

Where this project is and where it is going. A layered timeline of the milestones follows the milestone sections; dates are indicative, dependencies are the real content.

Timeline (indicative)

gantt
    title Roadmap: containment and agent-envelope work
    dateFormat YYYY-MM-DD
    axisFormat %b %d
    section Stabilize
    M0 Green main — pending/ selectors advisory, not errors :m0, 2026-11-02, 1w
    section 009 baseline containment
    M1 Foundations — contain.rs engine, US5+US1+US2 (T004–T015) :m1, after m0, 4w
    M2 Completion — derogations, kind orientation, US4 supersession/amendment (T016–T028) :m2, after m1, 4w
    section 010 envelope containment
    M3 Envelope engine — envelope.rs, envelope vocabulary, adapter registry (T001–T008) :m3, after m1, 3w
    section External runtime (OpenShell source)
    M4 Native adapter from a checked-in sample; expert-query kinds; BDD-vs-Z3 note :m4, after m3, 3w
    section Adoption and release
    M5 Selective-adoption phase 2, docs site, release 1.1.0 :m5, after m2, 2w
    section Governance
    M6 Exemption review, constitution process, attribution upkeep :active, after m0, 12w

Dependencies: M1 gates everything containment-related; M3 needs the M1 engine; M4 needs M3 and its own input file (task T009); M5 ships after M2 (M4 may slip past the release); M6 runs continuously. The shipped gates (features 001–008) are green; the containment features (009 baseline containment, 010 envelope containment) are merged as staged specifications with their conformance fixtures parked under conformance/pending/. Their origin is an external source, cited for attribution in both specs' research.md:

That post proves, with an SMT solver, that a permission change proposed by an agent stays inside the envelope the operator approved (Allowed(candidate) ∖ Allowed(reference) = ∅, witness on sat, fail-closed on unknown). Features 009/010 implement the same containment query over requirement models with binary decision diagrams — a deliberate divergence, recorded in decisions and their reasons — and extend it from agent runtime policy to specification revisions, project policy, supersession unions, and amendments.

Milestones

M0 — Restore a green main ✅ (done 2026-11-02, feature 011-parked-selectors)

Implemented as spec 011: missing selector files under configured parked_selector_prefixes (default conformance/pending/; this repo also lists the four planned 009/010 implementation files) are TRACE_TEST_PARKED advisories, not TRACE_TEST_FILE errors. Existing files, named-test checks, and root/traversal checks are unchanged. validate --phase final --all is green with the parked selectors named as advisories.

The 009/010 merge had left validate --phase plan|tasks|final --all red: their traceability.toml files name selectors that do not exist yet (unwritten conformance/pending/*/expected.json, src/contain.rs, src/envelope.rs, src/adapters.rs, tests/determinism.rs). The pending-corpus README states unwritten cases are "reported as missing files," so by design an in-progress feature holds the gate red — which conflicts with keeping main green for everyone else.

Work: teach the traceability gate that a selector under conformance/pending/ is declared-parked (advisory, never an error), so an in-progress feature never holds main red. Exit: validate --phase final --all green with 009/010 selectors parked and named.

M1 — 009 foundations, first usable slice ✅ (done 2026-11-02)

Shipped: contain.rs engine (manifest, per-effect shared BDD encodings with side-domain masks, budget preflight, widening/narrowing witnesses verified by the independent enumerator, policy conflict questions), revision/policy kinds, report comparisons records + summary counts, human output, and 11 blessed conformance cases now in conformance/cases/. supersession and amendment are accepted but reported uncompared until M2.

Tasks T004–T015 of specs/009-baseline-containment/tasks.md: the contain.rs engine — typed comparison manifest with source provenance, one shared bdd::Encoding per effect question with side-domain masks, state-budget preflight (refuse over-budget, never evaluate it), forward and reverse differences with canonical witnesses, JSON and human reporting. Bless and move each contain-* case from conformance/pending/ into conformance/cases/ as it goes green (T026). Exit: US5+US1+US2 cases green in the live corpus; final --all green for the 009 scope.

M2 — 009 completion ✅ (engine done 2026-11-02; Kiro-graph auto-resolution and Kiro amendment headings remain as follow-ups)

Shipped: derogations with validation/coverage/staleness, supersession as a masked union over explicit candidate lists, Spec Kit amendment pairs, full kind orientation, shared-partition and deprecated-term fixtures, determinism + differential witness tests; 20 contain-* cases live in conformance/cases/.

Tasks T016–T028: derogations (deliberate widening, fully covered ⇒ advisory only), kind orientation (policy is an upper bound, amendment is a refinement, revision asks no conflict question), and US4 content checks over Kiro supersession and amendment links, building on feature 008's active baseline. Exit: all 28 tasks done, full corpus green, docs updated.

M3 — 010 envelope engine ✅ (done 2026-11-02; native adapter remains blocked on a real sample)

Shipped: envelope.rs (interchange format 1.0 reader, reserved envelope-phase enum, tool and transition effects, unmodelled-construct naming by JSON pointer, reachability-omitted advisory), fixed adapter registry (adapters.rs), envelope kind wired through the 009 engine, 8 contain-envelope-* cases live in conformance/cases/.

Tasks T001–T008 of specs/010-envelope-containment/tasks.md (depends on M1): envelope.rs reads versioned envelope definitions into phase/tool/transition effects with PHASE-<name> identifiers, names every unmodelled construct, and discloses reachability as omitted; envelope sources carry their own vocabulary (never TERM_UNUSED); adapters.rs is a fixed registry. Exit: the contain-envelope-* cases moved into the corpus and green.

M4 — Native adapter for a real agent guardrail runtime

This is the payoff of the external source: check in a real sample policy/workflow file from a state-machine guardrail runtime (the OpenShell-style runtime the cited dev note describes) under conformance/pending/contain-envelope-native/, write the mapping table and dropped-constructs list in contracts/envelope.md, then implement the adapter (task T009 — blocked on that input, by design: never write an adapter from documentation). Also port the dev note's four expert queries (l7_bypass_credentialed, credential_reach_expansion, capability_expansion, link_local_reach) as comparison kinds, and record the BDD-vs-Z3 divergence in docs/design/decisions.md with the citation.

M5 — Adoption and release

Turn on the second adoption phase of feature 007 per project, update these docs and the site, keep conformance/PARITY.md current for a second implementation, and cut release 1.1.0 with containment. CI stays split (Dagger for Linux, native runners for Windows and macOS) because containment witnesses are exactly the cross-platform-sensitive output.

M6 — Governance hygiene

Review the recorded separation exemptions periodically, amend the constitution only through its documented process, and keep the OpenShell attribution current (add an arXiv/DOI reference if NVIDIA formalizes the work).

Rules that apply to every milestone

From the ratified constitution (.specify/memory/constitution.md): validation is read-only; the resolved scope is printed on every run; a check that did not run is reported, never folded into a pass; the behavioural contract is data; tests are written first and run red before implementation; production code contains no requirement IDs and no copied EARS sentences.

Main risks

  • State-budget blowup on shared encodings — mitigated by preflight refusal (M1).
  • Witness stability across runs and platforms — locked by tests/determinism.rs (T011).
  • Adapter drift from the native runtime — mitigated by a versioned adapter plus a dropped-constructs honesty list (M4).
  • Pending-corpus hygiene — never move an unimplemented case into cases/ (T026/T010).