devrites 3.2.28 → 4.0.0

package/docs/adr/0024-native-policy-offline-installer-boundary.md

@@ -0,0 +1,111 @@
+# ADR-0024: Native policy and offline installer boundary
+
+- **Status:** Accepted
+- **Date:** 2026-08-01
+
+## Context
+
+ADR-0022 removed semantic orchestration from the Go engine but retained several
+commands that encoded workflow policy: spec grammar parsing, question-ID
+derivation, Clarify return transitions, AFK slice accounting, recovery counters,
+and install diagnostics. ADR-0023 kept those commands because their deterministic
+implementation appeared to make autonomy safer.
+
+That split still created two authorities. The skills described when and why a
+policy applied, while Go decided how Markdown should be interpreted or changed.
+Each policy change required synchronized command code, fixtures, settings,
+generated guidance, and prose. Recovery also acquired a separate JSONL counter
+even though exact failures and dead ends already belonged in evidence.
+
+Installation had a second boundary leak. The engine both applied manifest-owned
+local changes and selected/downloaded remote update material. This made a
+deterministic local installer depend on network policy already handled by the
+npm and shell entrypoints.
+
+## Decision
+
+- Keep the engine only for deterministic primitives whose safety depends on a
+  shared executable boundary: local install/update/uninstall, structural
+  readiness, structural plus evidence-freshness seal, atomic question
+  answer/drop/batch resolution, transactional close, secret scanning, version,
+  and schema/path/evidence safety.
+- Remove `check spec`, `state clarify`, `state tick-afk`, `state recovery`,
+  `state resolve next-qid`, and `doctor`. Removed forms fail visibly; there are
+  no aliases or tombstones.
+- Keep Requirement/Scenario grammar normative. At each owning gate, the root
+  re-opens the saved spec and executes one explicit checklist for headings,
+  unique IDs, SHALL/MUST, WHEN/THEN, scenarios, behavior anchoring, and delta
+  identity. Do not add a replacement parser or script.
+- Allocate `q-YYYY-MM-DD-NNN` in the root: scan every same-day question header,
+  select the next unused suffix, then re-read and recompute immediately before
+  append. Retain `state resolve` as the sole atomic answer/drop/batch writer.
+- Manage later-phase Clarify return fields in the root. Entry preserves the
+  current recognized later `phase` and non-empty `next_action`, then enters
+  Clarify in running state. Entry while already in Clarify is a no-op. A fresh,
+  contract-neutral CLEAR validates, restores, and removes both return fields
+  while preserving unrelated Markdown. Changed behavior routes through plan
+  repair instead of restoring.
+- Manage AFK slice budgets in the root. A configured budget is a nonnegative
+  integer, charged exactly once with each green pending-to-built transition,
+  never decremented below zero, and checked before another dispatch. Malformed
+  state fails closed.
+- Count recovery in the caller plus recovery loop. One causal fingerprint gets
+  at most three total failed attempts from the current context and recorded
+  Dead ends/evidence. Record each exact failure and failed idea; never run a
+  fourth. Do not create a counter file or command.
+- Keep `/rite-doctor` as a read-only native procedure. It locates the repository
+  root; inspects manifest hashes, installed host artifacts/config, ACTIVE and
+  workspace topology, and symlinks; compares manifest/package/available-binary
+  versions; and reports OK/WARN/FAIL with remediation. It never mutates or
+  acquires an engine.
+- Make Go install/update/uninstall offline and local. Shell/npm entrypoints
+  acquire and verify the bundle/source/platform binary, then supply those local
+  candidates to the engine. Engine update `--check` compares installed and local
+  candidate versions. Engine `--to` and `--pre` release selectors are removed.
+- Remove permissions for deleted command forms from installed host settings.
+
+## Superseded decisions
+
+- **ADR-0001:** supersedes the claim that the engine owns *all* deterministic
+  state transitions and derivations, including next-question ID bookkeeping.
+  Its stdlib-only binary, model-free trust boundary, and retained deterministic
+  primitives stand.
+- **ADR-0006:** supersedes the next-qid clock-seam decision and its dedicated
+  guard test because that engine form no longer exists. Static-analysis, race,
+  vulnerability, and applicable clock-seam rules stand.
+- **ADR-0008:** supersedes the allowance for updater/source-cache network I/O in
+  the engine. Acquisition now belongs to shell/npm edges; the engine is fully
+  network-free. Its no-model and auditable-boundary intent stands.
+- **ADR-0022:** narrows its retained command list by removing spec, Clarify, AFK,
+  recovery, qid-allocation, and doctor commands, and narrows install/update to
+  caller-supplied local candidates. Native orchestration, released cursor reads,
+  root safety, exact writer permissions, and fresh irreversible approval stand.
+- **ADR-0023:** supersedes its decision to retain AFK/recovery counters and the
+  engine doctor. Direct workspace reads and line-oriented output for remaining
+  checks stand.
+
+## Alternatives considered
+
+| Option | Why not |
+|---|---|
+| Keep the commands because they are deterministic | Determinism alone does not justify a second policy authority or the synchronized surface it creates. |
+| Replace each command with a shell/Python helper | Preserves the duplicate parser/counter problem with weaker portability and root safety. |
+| Move atomic resolve/close and secret scanning into prose too | Those operations protect multi-file consistency or a trust boundary and still justify executable enforcement. |
+| Let the engine fetch only updates while npm/shell fetch installs | Keeps two acquisition policies and makes offline behavior command-dependent. |
+
+## Consequences
+
+The public engine surface and Claude allowlist shrink. Skills must state the
+native policy once, link to it, and tests must reject deleted forms in canonical
+and generated artifacts. Spec grammar remains a blocking contract even without
+a parser. AFK and recovery bounds are instruction-enforced and therefore must be
+recorded and re-read explicitly rather than inferred from exit codes.
+
+Install/update/uninstall can be tested without network access. npm and shell
+entrypoints carry acquisition responsibility and must checksum remote artifacts
+before passing local paths to the engine. Existing manifests and released
+workspace cursor encodings need no migration.
+
+Regression coverage lives in `tests/native-orchestration-contract-test.sh`,
+`tests/phase-gate-routing-test.sh`, `tests/install-smoke.sh`,
+`tests/host-artifacts-test.sh`, and the Go install/root-routing tests.

package/docs/adr/0025-evidence-gated-workspace-upgrades.md

@@ -0,0 +1,64 @@
+# ADR-0025: Evidence-gated semantic workspace upgrades
+
+- **Status:** Accepted
+- **Date:** 2026-08-01
+
+## Context
+
+ADR-0012 separated semantic workspace upgrades from structural migration, but
+its implementation depended on a readiness-artifact version, an engine
+`upgrade-required` result, and a structural migrator. ADR-0022 and ADR-0024
+later removed those duplicate semantic and migration surfaces. Official v1/v2
+bullet and v3 table cursors are now read directly without rewriting them.
+
+The public `/rite-upgrade` route still has value for an unfinished workspace
+that cannot resume after the installed workflow changes. However, age, cursor
+encoding, or an absent version marker cannot prove semantic staleness. A generic
+"normalize old planning" instruction risks deleting valid history and duplicates
+Clarify, Plan, Converge, and Vet.
+
+## Decision
+
+- Keep `/rite-upgrade [slug]` as an explicit compatibility audit and bounded
+  orchestrator for active, unfinished workspaces produced by released packs.
+- A repair requires a cited current rule, exact contradictory or missing
+  workspace evidence, the affected gate, one owning rite, exact writable paths,
+  and the smallest behavior-neutral delta. Provenance alone never qualifies.
+- The read-only `devrites-upgrade-planner` returns exactly one fail-closed outcome:
+  `current`, `repairable`, `unsupported`, or `gap`. `current` requires evidence
+  for every applicable axis; missing inputs or unverifiable rules are `gap`.
+- `/rite-upgrade` does not reproduce semantic repair logic. It sequences the
+  existing owners—Clarify, Plan repair, Converge, and Vet—only when admitted
+  findings require them. Their normal gates and write boundaries remain active.
+- Before repair, freeze Git status and protected workspace identities. Afterward,
+  re-audit once, compare the baseline, and run structural readiness. Never edit
+  source/tests, completed work, historical evidence, existing decisions, or cursor format;
+  never start Build.
+- Installed-pack diagnosis remains `/rite-doctor`; pack replacement remains the
+  installer/update path; legacy customization import remains the literal-only
+  `/rite-customize --import-legacy` mode. None is inferred by Upgrade.
+
+This supersedes ADR-0012's readiness-artifact version, engine return code,
+structural migrator, and direct public-skill rewrite mechanics. It retains the
+decision to keep package update, workspace storage compatibility, and semantic
+workspace reconciliation separate.
+
+## Alternatives considered
+
+| Option | Why not |
+|---|---|
+| Retire `/rite-upgrade` | Removes a useful explicit entry point for diagnosing an older active workspace and forces users to guess among recovery rites. |
+| Restore semantic versions or an engine staleness parser | Recreates a second semantic authority and can certify content from metadata rather than evidence. |
+| Let Upgrade rewrite planning directly | Duplicates phase owners and creates a broad mutation path outside their gates. |
+| Replay per-release migrations | Grows a permanent chain and preserves obsolete intermediate mechanics. |
+
+## Consequences
+
+Older official workspaces remain readable without migration. Upgrade can now
+return `current` without touching them, repair only demonstrated defects through
+their canonical owner, or stop explicitly when compatibility cannot be proved.
+The command costs one fresh assessment and at most one re-audit, but it no longer
+guesses from age or silently normalizes history.
+
+Regression coverage lives in `tests/phase-gate-routing-test.sh` and generated
+host-artifact parity tests.

package/docs/adr/0026-content-bound-proof-and-bounded-inputs.md

@@ -0,0 +1,169 @@
+# ADR-0026: Content-bound proof and bounded inputs
+
+- **Status:** Accepted
+- **Date:** 2026-08-01
+
+## Context
+
+At baseline `403e1a60adf3ae32ee88009c417e6ffe015fc1aa`, Seal decides
+evidence freshness from modification times. It extracts every backtick-delimited
+token from `touched-files.md`, accepts absolute paths, ignores listed files that
+do not exist, and treats a missing `touched-files.md` as fresh. That comparison
+cannot establish which bytes were proved. A restored timestamp can hide a content
+change, while an unchanged file touched by tooling can invalidate sound evidence.
+
+The approved candidate can also change after Seal. Ship currently performs
+capability-ledger folding, design-memory promotion, and durable ADR promotion.
+Those writes occur after proof and review, so the committed tree can differ from
+the candidate those phases inspected.
+
+Two input boundaries have the same identity problem. Git subprocesses inherit
+repository, object, ref, config, and pathspec environment variables that can
+retarget a command despite an explicit working directory. Release acquisition
+accepts unbounded responses and retains unchecked fallbacks; archive extraction
+does not first prove one bounded, expected file tree. Checksums alone do not make
+an ambiguous target or an unbounded archive safe.
+
+A fresh audit of nine MIT-licensed workflow repositories found useful integrity
+mechanisms, but no reason to replace DevRites' lifecycle or control-plane split.
+ADR-0024 remains the authority for native semantic policy and the offline,
+stdlib-only Go engine. This decision adds one deterministic serialization
+primitive and hardens existing owners.
+
+## Decision
+
+### Preserve the existing architecture
+
+- Keep the 15 phases from Frame through Done, the public `/rite-*` commands,
+  exact named agents, one exact-path writer, the Markdown workspace, and the
+  offline stdlib-only Go control plane.
+- Add no phase, skill, agent, daemon, registry, scheduler, dependency, or second
+  state plane.
+- Amend ADR-0024 with one additive, read-only, line-oriented command:
+  `devrites-engine check candidate <slug>`. The command and Seal call the same Go
+  helper. The helper serializes and validates candidate identity; it does not
+  interpret specifications, proof quality, or workflow policy.
+- Final `check seal` also performs exact-line identity checks. It requires the
+  same candidate SHA-256 in `evidence.md`, `review.md`, and `seal.md`, plus
+  `browser-evidence.md` when that file is present. Reading those fixed digest
+  lines is deterministic binding, not semantic review or proof interpretation.
+
+### Make the manifest the sole candidate authority
+
+- `touched-files.md` owns one machine-readable `## Candidate manifest` section.
+  Each project-relative path has exactly one explicit `present` or `deleted`
+  state. A candidate with no project files uses one explicit no-project-files
+  marker.
+- An absent or malformed manifest blocks Candidate, Seal, and later Git checks
+  with a rerun or workspace-refresh message. There is no heuristic parser or
+  legacy fallback.
+- Normalize and sort manifest paths before serialization. Reject absolute paths,
+  traversal, duplicate normalized paths, control characters, ambiguous paths,
+  missing `present` files, existing `deleted` files, directories, symlinks,
+  special files, and any manifest, entry, file, or aggregate size beyond the
+  fixed documented limits.
+- Candidate identity is a versioned, length-prefixed, streaming SHA-256. Every
+  record binds state, normalized path, file type, executable bit, content length,
+  and content bytes. Deleted rows use the format's fixed absent type/mode/content
+  values. Length prefixes and a version marker prevent concatenation ambiguity.
+- Prove records the candidate digest in `evidence.md` and every applicable
+  `browser-evidence.md`. Review and Seal record the exact same digest in
+  `review.md` and `seal.md`. Unchanged content remains valid across
+  modification-time changes. Any candidate byte, path, state, type, or
+  executable-bit change blocks until proof and downstream identity records are
+  refreshed.
+
+### Close the candidate before Review
+
+- Initial Prove may precede Polish. Polish performs every candidate-affecting
+  capability-ledger fold, UI design-memory update, and durable ADR rollup, then
+  closes the candidate manifest. Any resulting digest change requires affected
+  re-proof and refreshed evidence digest before Review.
+- Review and Seal inspect that closed candidate. Ship may not change candidate
+  files before its Git ladder. Any needed candidate mutation routes back through
+  Prove, Review, and Seal.
+- Ship rechecks the manifest plus the matching evidence, browser when present,
+  review, and seal digest lines before Git. Before commit, the staged candidate
+  must match the approved manifest and digest. Before push or tag, the committed
+  candidate must match as well. These checks supplement, and never replace,
+  fresh human approval for irreversible Git actions.
+
+### Sanitize Git targeting in one shared policy
+
+- A shared Go helper filters the environment for both production Go Git
+  subprocess sites. A shared shell helper is sourced by every production shell
+  Git site.
+- Remove repository, config, object, ref, and pathspec-retargeting `GIT_*`
+  variables. Preserve unrelated Git variables rather than clearing the entire
+  namespace.
+- Treat each dynamic `GIT_CONFIG_KEY_n` and `GIT_CONFIG_VALUE_n` as one pair.
+  Filtering, preservation, and malformed-pair behavior must stay identical in Go
+  and shell and have parity tests.
+
+### Bound and verify every network acquisition
+
+- Acquire only an exact release asset with its mandatory SHA-256 sidecar. Remove
+  unchecked tag, default-branch, source-archive, and raw-script fallbacks.
+- Bound API metadata, checksum, archive, and binary transfers. Fail if secure
+  private temporary-directory creation fails; never fall back to a predictable
+  path.
+- Before extraction, verify exactly one expected archive prefix, allowed entry
+  types, member-count and expanded-size ceilings, and path containment. Extract
+  only after the complete preflight succeeds.
+- Release production must generate every required checksum sidecar and fail when
+  one is absent. Keep the curl-plus-tar bootstrap path and add no dependency.
+
+### Strengthen the native semantic owners
+
+- Capability folding preserves all prior MODIFIED scenarios and source claims
+  unless the change explicitly replaces them. A change with no capability impact
+  uses a justified, explicit no-impact form.
+- When a slice changes an API, event, or schema boundary, provider and consumer
+  tests must read the same canonical contract artifact. This rule is conditional;
+  it creates no contract registry for slices without such a boundary.
+- Proof requires positive observable or framework evidence. Skipped, vacuous,
+  compile-only, assertion-free, or non-executed checks cannot prove behavior.
+
+### Repair the two baseline gates narrowly
+
+- Classify the literal `devrites-orchestrator` profile as a non-skill in the
+  invocation-integrity check.
+- Revalidate GHSA-mh99-v99m-4gvg against the installed dependency graph. Remove
+  its exact temporary exception when a patched ancestor is available; otherwise
+  retain only the exact affected path with a short, justified expiry.
+
+## Alternatives considered
+
+| Option | Why not |
+|---|---|
+| Keep modification times as evidence identity | Timestamps neither bind bytes nor fail closed on missing paths and manifests. |
+| Let each host compute its own candidate hash | Independent Claude, Codex, shell, and Go implementations would create multiple proof authorities and parity drift. |
+| Keep capability, design-memory, and ADR writes in Ship | The committed candidate could differ from the one Prove, Review, and Seal approved. |
+| Keep unchecked tag, branch, source, or raw-script fallbacks | Availability would silently take priority over provenance and make release verification optional. |
+| Add a workflow engine, registry, scheduler, daemon, or second state store | Each duplicates an existing native host, lifecycle, or Markdown owner and adds failure modes without closing the observed integrity gaps. |
+| Adopt any reference project wholesale | Their useful mechanisms are separable; their runtimes, permissions, state models, and update policies conflict with DevRites invariants. |
+| Hash the Git index or worktree implicitly | Candidate scope would depend on ambient Git state and could include preserved user work that the slice never owned. |
+
+## Consequences
+
+Released `/rite-*` commands and workspace prose remain readable, and `check
+candidate` is additive. Old touched, evidence, review, and seal records do not
+satisfy the new fail-closed identity contract; an unfinished workspace must
+refresh its manifest and downstream digest lines before a new Seal. This is a
+deliberate compatibility cost.
+
+Proof becomes stable under harmless timestamp changes and sensitive to every
+material candidate change. Streaming and fixed bounds cap memory, disk, and
+archive work. The cost is a versioned serialization format, migration guidance,
+and shared Go/shell parity that release work must maintain.
+
+The decision's planned guard locations were
+`engine/internal/lib/candidate_test.go`,
+`engine/internal/lib/evidencefresh_test.go`,
+`engine/internal/gate/gate_test.go`, `engine/root_routing_test.go`,
+`engine/tests/parity_githelpers_test.go`,
+`tests/native-orchestration-contract-test.sh`,
+`tests/phase-gate-routing-test.sh`, `tests/install-smoke.sh`,
+`tests/update-smoke.sh`, `tests/npx-pack-smoke.sh`, and
+`tests/release-tarball-test.sh`. They now exist and own regression coverage for
+this decision.

package/docs/adr/0027-content-bound-build-readiness.md

@@ -0,0 +1,77 @@
+# ADR-0027: Content-bound build readiness
+
+- **Status:** Accepted
+- **Date:** 2026-08-03
+
+## Context
+
+`check readiness` verifies that the current phase has nonempty required files and
+no open human gate. It does not establish that the plan Vet reviewed is the plan
+Build will consume. A reproduced Build-phase workspace remained ready after
+`plan.md` bytes changed and its original modification time was restored.
+
+Native agents must continue to own semantic judgments such as `CLEAR`, `READY`,
+plan quality, and test adequacy. A byte-identity check does not make those
+judgments, but it can prevent an old judgment from silently attaching to new
+inputs. The identity cannot simply hash every structurally required file:
+Build intentionally updates `state.md`, `questions.md`, `decisions.md`, and
+`assumptions.md` between slices.
+
+## Decision
+
+- Add one fixed, versioned readiness identity for the stable Build contract. Its
+  required records are `spec.md`, `decision-coverage.md`, `architecture.md`,
+  `plan.md`, `tasks.md`, `traceability.md`, and `test-plan.md`. Optional records
+  bind both presence and absence for `strategy.md`, `design-brief.md`,
+  `ai-spec.md`, and `.devrites/principles.md`.
+- Exclude mutable cursor, question, decision, assumption, review, drift,
+  evidence, handoff, and final-verdict records. A material change discovered in
+  one of those records must still fold into a stable owner before Vet may renew
+  `READY`.
+- Serialize a domain/version, fixed record count and order, logical path,
+  presence state, content length, and raw bytes into SHA-256. Reject symlinks,
+  non-regular inputs, more than 1 MiB per input, and more than 8 MiB in total.
+  The engine adds no dependency, configurable graph, schema file, or second
+  state plane.
+- `devrites-engine check readiness --emit-binding <slug>` is a read-only helper
+  that prints exactly one `Readiness inputs SHA-256: <64 lowercase hex>` line.
+  Vet records that exact standalone line in `eng-review.md` only after fold-back,
+  proof preflight, semantic review, and recheck are complete.
+- Ordinary `check readiness` verifies exactly one current, non-fenced binding
+  whenever the target phase requires `eng-review.md`. `check seal` repeats the
+  same verification before final candidate-evidence checks. Missing, malformed,
+  duplicate, or stale bindings fail closed with a stable reason and route back
+  through Vet; the engine never refreshes the record automatically.
+- If Build discovers a missing or materially changed `design-brief.md`, shaping
+  completes before source work and returns through Vet before dispatch. A
+  post-readiness design contract cannot silently drive implementation.
+
+This narrowly supersedes ADR-0022's prohibition on readiness digests. It
+preserves that ADR's thin-engine boundary and prohibition on semantic prose
+parsing, agent orchestration, compatibility telemetry, and migration machinery.
+
+## Alternatives considered
+
+| Option | Why not |
+|---|---|
+| Keep structural readiness only | It permits an observed false-ready handoff after reviewed planning bytes change. |
+| Hash every phase-required workspace file | Build legitimately mutates several ledgers, causing false invalidation between slices. |
+| Use mtimes | Restored timestamps do not identify reviewed bytes. |
+| Let Vet run shell-specific hash commands | Host implementations would drift and weaken cross-platform identity. |
+| Auto-refresh the binding when stale | Re-labels changed inputs as reviewed without rerunning the semantic owner. |
+| Add a configurable artifact graph | Creates another workflow authority for one fixed lifecycle dependency. |
+
+## Consequences
+
+Readiness and Seal now detect stable planning drift independently of model
+memory and timestamps while semantic review stays native. Existing unfinished
+workspaces without the binding must return through `/rite-vet`; `/rite-upgrade`
+already routes readiness defects there. Optional contract artifacts cannot be
+added or removed after Vet without visible invalidation.
+
+The identity is a sequential read rather than an atomic filesystem snapshot.
+The ordinary gate recomputes it after the binding is written, and Seal repeats
+the check; hostile concurrent workspace mutation remains outside the local
+agent-workflow threat model.
+
+Guard test: `engine/tests/adr_0027_readiness_binding_test.go`.

package/docs/adr/README.md

@@ -46,15 +46,30 @@ architecture; per-feature `decisions.md` files stay scoped to that feature.
 
 | ADR | Title | Status | Guard test |
 |-----|-------|--------|-----------|
-| [0001](0001-go-engine-as-control-plane.md) | Go engine as deterministic control plane | Accepted | none |
+| [0001](0001-go-engine-as-control-plane.md) | Go engine as deterministic control plane | Accepted in part; all-state-transition/derivation scope superseded by 0024 | none |
 | [0002](0002-dual-host-harness.md) | Dual-host harness (Claude + Codex) | Accepted | `tests/parity_*_test.go` |
-| [0003](0003-gate-model-hitl-pause.md) | Gates block as HITL pause, never crash | Accepted | `tests/adr_0003_gate_exit_code_test.go` |
-| [0004](0004-state-schema-phases-sections.md) | Phase-relative section completeness | Accepted | `tests/adr_0004_required_by_phase_test.go` |
-| [0005](0005-hooks-as-engine-subcommands.md) | Hooks are engine subcommands, not shell scripts | Accepted | `tests/parity_*_test.go` |
-| [0006](0006-clock-seam-and-engine-ci-gates.md) | Clock seam + Go static-analysis CI gates | Accepted | `tests/adr_0006_clock_seam_test.go` |
-| [0007](0007-canonical-live-workspace-filenames.md) | Canonical live workspace filenames | Accepted | `internal/migrate/migrate_test.go`, `tests/migrate_cli_test.go` |
-| [0008](0008-sanctioned-engine-network-boundary.md) | Sanctioned engine network boundary | Accepted | `tests/meta_test.go` |
-| [0009](0009-prebuild-decision-coverage-and-readiness.md) | Pre-build decision coverage and implementation readiness | Accepted | `internal/state/state_test.go`, `tests/parity_buildreadiness_test.go` |
-| [0010](0010-agent-first-fresh-context-orchestration.md) | Agent-first fresh-context orchestration | Accepted | `tests/hook_test.go`, `tests/codex-agent-generation-test.sh` |
-| [0011](0011-define-plan-transition-rights.md) | Separate Define authoring from the Plan checkpoint | Accepted | `internal/state/state_test.go`, `tests/adr_0011_define_plan_test.go` |
-| [0012](0012-semantic-workspace-upgrades.md) | Separate semantic workspace upgrades from structural migration | Accepted | `tests/parity_buildreadiness_test.go` |
+| [0003](0003-gate-model-hitl-pause.md) | Gates block as HITL pause, never crash | Accepted | `engine/tests/adr_0003_gate_exit_code_test.go` |
+| [0004](0004-state-schema-phases-sections.md) | Phase-relative section completeness | Accepted | `engine/tests/adr_0004_required_by_phase_test.go`, `engine/internal/state/state_test.go` |
+| [0005](0005-hooks-as-engine-subcommands.md) | Hooks are engine subcommands, not shell scripts | Accepted; active hook clause superseded by 0018 | historical |
+| [0006](0006-clock-seam-and-engine-ci-gates.md) | Clock seam + Go static-analysis CI gates | Accepted in part; next-qid seam/guard superseded by 0024, CI clauses retained | historical |
+| [0007](0007-canonical-live-workspace-filenames.md) | Canonical live workspace filenames | Accepted; unsupported alias/migration clauses superseded by 0022 | `engine/internal/state/state_test.go`, `engine/internal/lib/cursor_compat_test.go` |
+| [0008](0008-sanctioned-engine-network-boundary.md) | Sanctioned engine network boundary | Accepted in part; engine network allowance superseded by 0024 | `engine/tests/meta_test.go` |
+| [0009](0009-prebuild-decision-coverage-and-readiness.md) | Pre-build decision coverage and implementation readiness | Accepted; semantic engine-gate implementation superseded by 0022 | historical |
+| [0010](0010-agent-first-fresh-context-orchestration.md) | Agent-first fresh-context orchestration | Accepted | `tests/native-orchestration-contract-test.sh`, `tests/codex-agent-generation-test.sh` |
+| [0011](0011-define-plan-transition-rights.md) | Separate Define authoring from the Plan checkpoint | Accepted | `engine/internal/state/state_test.go`, `engine/tests/adr_0011_define_plan_test.go` |
+| [0012](0012-semantic-workspace-upgrades.md) | Separate semantic workspace upgrades from structural migration | Accepted in intent; detection and repair mechanics superseded by 0025 | historical |
+| [0013](0013-native-codex-agent-orchestration.md) | Native Codex agent orchestration | Accepted; Codex writer clause superseded by 0016 | `tests/codex-agent-generation-test.sh`, `tests/codex-generator-test.sh` |
+| [0014](0014-native-host-hook-boundary.md) | Native host capability boundary | Superseded by 0015 | historical |
+| [0015](0015-read-only-root-native-orchestration.md) | Read-only root with native host orchestration | Accepted; Codex root/writer clauses superseded by 0017; exact-path/hook/reconcile clauses superseded by 0018 | `engine/internal/install/install_test.go`, `tests/codex-agent-generation-test.sh` |
+| [0016](0016-codex-writer-fail-closed.md) | Codex source writing fails closed | Superseded by 0017 | historical |
+| [0017](0017-native-codex-writer-agent.md) | Native Codex writer-agent execution | Accepted; exact-path/reconcile clauses superseded by 0018 | `tests/codex-agent-generation-test.sh`, `tests/codex-generator-test.sh`, `tests/codex-runtime-smoke.sh` |
+| [0018](0018-native-sandbox-instruction-writer-boundary.md) | Native sandbox and instruction writer boundary | Accepted in part; native sandbox/writer boundary retained, superseded clauses resolved by 0022 | `engine/internal/install/install_test.go`, `tests/codex-agent-generation-test.sh` |
+| [0019](0019-native-boundary-with-deterministic-gates.md) | Native boundary with deterministic gates | Accepted in part; semantic gates superseded by 0022, native writer and fresh approval retained | `engine/internal/gate/gate_test.go` |
+| [0020](0020-thin-engine-native-orchestration-boundary.md) | Thin engine and native host orchestration | Accepted in part; engine-surface/migration scope superseded by 0022, native orchestration retained | `tests/native-orchestration-contract-test.sh`, `engine/root_routing_test.go` |
+| [0021](0021-observable-workspace-compatibility.md) | Observable and reversible workspace compatibility | Superseded by 0022 | historical |
+| [0022](0022-native-orchestration-thin-engine.md) | Native orchestration with a thin deterministic engine | Accepted in part; snapshot/JSON-output clauses superseded by 0023; retained policy-command/install clauses narrowed by 0024 | `engine/root_routing_test.go`, `engine/internal/gate/gate_test.go`, `engine/internal/lib/cursor_compat_test.go`, `tests/native-orchestration-contract-test.sh` |
+| [0023](0023-native-workspace-reads-line-output.md) | Native workspace reads and line-oriented engine output | Accepted in part; AFK/recovery/doctor retention superseded by 0024 | `engine/root_routing_test.go`, `engine/internal/gate/gate_test.go`, `tests/native-orchestration-contract-test.sh`, `tests/npx-pack-smoke.sh` |
+| [0024](0024-native-policy-offline-installer-boundary.md) | Native policy and offline installer boundary | Accepted | `tests/native-orchestration-contract-test.sh`, `tests/phase-gate-routing-test.sh`, `tests/install-smoke.sh`, `tests/host-artifacts-test.sh` |
+| [0025](0025-evidence-gated-workspace-upgrades.md) | Evidence-gated semantic workspace upgrades | Accepted | `tests/phase-gate-routing-test.sh`, `tests/host-artifacts-test.sh` |
+| [0026](0026-content-bound-proof-and-bounded-inputs.md) | Content-bound proof and bounded inputs | Accepted | `engine/internal/lib/candidate_test.go`, `engine/internal/lib/evidencefresh_test.go`, `engine/internal/gate/gate_test.go`, `engine/root_routing_test.go`, `engine/tests/parity_githelpers_test.go`, `tests/native-orchestration-contract-test.sh`, `tests/phase-gate-routing-test.sh`, `tests/install-smoke.sh`, `tests/update-smoke.sh`, `tests/npx-pack-smoke.sh`, `tests/release-tarball-test.sh` |
+| [0027](0027-content-bound-build-readiness.md) | Content-bound build readiness | Accepted | `engine/tests/adr_0027_readiness_binding_test.go` |

package/docs/agents/domain.md

@@ -48,7 +48,8 @@ If the concept you need isn't in the glossary yet, that's a signal: either you'r
 
 - New durable term → add it to `CONTEXT.md` with any avoided synonyms.
 - Two terms collide → add a flagged ambiguity and the resolved canonical term.
-- Decision constrains future work → add or update an ADR.
+- Decision constrains future work → update a Proposed/unaccepted ADR, or add a
+  new superseding ADR plus index entry when an accepted decision changes.
 - One-off implementation detail → leave it out.
 
 ## Flag ADR conflicts

package/docs/agents/issue-driven-rites.md

@@ -6,6 +6,6 @@ Local issue files are the source of truth; external trackers are references only
 
 1. Create `.scratch/<slug>/PRD.md` when product detail is needed and one or more numbered implementation issues under `.scratch/<slug>/issues/<NN>-<issue-slug>.md`, starting at `01`.
 2. Start `/rite-spec <slug>` from the relevant PRD/issues; copy lifecycle decisions into `.devrites/work/<slug>/`, while tracker status/comments remain in the local issue files.
-3. Run the normal lifecycle: `/rite-define` → `/rite-vet` → `/rite-build` → `/rite-prove` → `/rite-polish` → `/rite-review` → `/rite-seal` → `/rite-ship`.
+3. Run the normal lifecycle: `/rite-clarify` → optional `/rite-temper` → `/rite-define` → `/rite-vet` → `/rite-build` → `/rite-prove` → `/rite-polish` → `/rite-review` → `/rite-seal` → `/rite-ship`.
 4. After a recorded type-GO, mark completed local issues `Status: resolved` and append the ship evidence; include `Closes #NNN` only when an external issue reference exists.
 5. Follow-ups become the next numbered local issue under `.scratch/<slug>/issues/` (or a new feature directory when scope differs); external auto-posting is out of scope.