devrites 3.0.7 → 3.1.0

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to DevRites are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and DevRites adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Releases are generated automatically by [semantic-release](https://semantic-release.gitbook.io/) from Conventional Commits on `main`.
 
+## [3.1.0](https://github.com/ViktorsBaikers/DevRites/compare/v3.0.7...v3.1.0) (2026-07-24)
+
+### Added
+
+* **devrites:** harden planning and agent orchestration ([50be03b](https://github.com/ViktorsBaikers/DevRites/commit/50be03b90f1d5004ea010cf68ff07b74bab491c6))
+
+### Fixed
+
+* **ci:** correct invocation and eval discovery gates ([0a0d7d2](https://github.com/ViktorsBaikers/DevRites/commit/0a0d7d27546b90a7f5a2dd72bc9326f29416cc54))
+* **devrites:** clear security and Windows mode gates ([59fcfc6](https://github.com/ViktorsBaikers/DevRites/commit/59fcfc6c1806975e36a69cde4e8a2c504657161a))
+* **devrites:** restore static and Windows engine gates ([8aeb479](https://github.com/ViktorsBaikers/DevRites/commit/8aeb4793adf0ce57ba4dba7ddcb7e56f9f612f40))
+
 ## [3.0.7](https://github.com/ViktorsBaikers/DevRites/compare/v3.0.6...v3.0.7) (2026-07-22)
 
 ### Fixed

package/README.md

@@ -14,14 +14,18 @@ continues.
 
 The core path is:
 
-`SPEC -> DEFINE -> VET -> BUILD -> PROVE -> POLISH -> REVIEW -> SEAL -> SHIP`
+`SPEC -> CLARIFY -> [TEMPER] -> DEFINE -> VET -> BUILD -> PROVE -> POLISH -> REVIEW -> SEAL -> SHIP`
+
+Clarify is mandatory but adaptive, so it asks no questions when the contract
+is complete. Temper adds an optional strategic review. Vet is the only final
+readiness phase before Build.
 
 Seal decides whether the feature is ready without changing git. Ship owns the
 final commit, push, and tag, and it requires a typed `GO` confirmation.
 Unattended runs may create local WIP checkpoint commits along the way, but only
 Ship collapses and pushes them.
 
-**Status:** [`v3.0.7`](https://github.com/ViktorsBaikers/DevRites/releases/tag/v3.0.7): see [`CHANGELOG.md`](CHANGELOG.md) for release notes.
+**Status:** [`v3.1.0`](https://github.com/ViktorsBaikers/DevRites/releases/tag/v3.1.0): see [`CHANGELOG.md`](CHANGELOG.md) for release notes.
 
 ## Quick start
 
@@ -67,27 +71,25 @@ Claude Code supports both `/rite <verb>` and `/rite-<verb>`. Codex uses the same
 forms with `$`: `$rite <verb>` and `$rite-<verb>`. The menu and direct forms run
 the same skill.
 
-| Stage | Direct command | What happens |
-|---|---|---|
-| Spec | [`/rite-spec <feature>`](pack/.claude/skills/rite-spec/SKILL.md) | Investigates the request and codebase, closes product gaps, and writes `spec.md`. |
-| Define | [`/rite-define`](pack/.claude/skills/rite-define/SKILL.md) | Turns the spec into architecture, a plan, traceability, and vertical task slices. |
-| Vet | [`/rite-vet`](pack/.claude/skills/rite-vet/SKILL.md) | Reviews every plan before implementation. The depth scales with the risk. |
-| Build | [`/rite-build`](pack/.claude/skills/rite-build/SKILL.md) | Implements and verifies exactly one slice, then stops. Repeat for each slice. |
-| Prove | [`/rite-prove`](pack/.claude/skills/rite-prove/SKILL.md) | Runs the completed feature's tests, build, runtime checks, and browser proof when UI is involved. |
-| Polish | [`/rite-polish`](pack/.claude/skills/rite-polish/SKILL.md) | Cleans up the touched code and normalizes the UI when needed. |
-| Review | [`/rite-review`](pack/.claude/skills/rite-review/SKILL.md) | Runs feature-scoped review across the relevant engineering axes. |
-| Seal | [`/rite-seal`](pack/.claude/skills/rite-seal/SKILL.md) | Produces a final `GO` or `NO-GO` decision without changing git. |
-| Ship | [`/rite-ship`](pack/.claude/skills/rite-ship/SKILL.md) | On `GO`, asks for typed confirmation, performs the approved git actions, and archives the workspace. |
+| # | Stage | Direct command | What happens |
+|---:|---|---|---|
+| 1 | Spec | [`/rite-spec <feature>`](pack/.claude/skills/rite-spec/SKILL.md) | Inspects the request and codebase, asks about product gaps, and writes `spec.md`. |
+| 2 | Clarify | [`/rite-clarify`](pack/.claude/skills/rite-clarify/SKILL.md) | Checks the whole feature for missing decisions before planning. It asks no questions when everything is clear. |
+| 3 | Temper | [`/rite-temper`](pack/.claude/skills/rite-temper/SKILL.md) | Challenges scope and failure modes before Define. It is optional for small work and always runs in `/rite-autocomplete`. |
+| 4 | Define | [`/rite-define`](pack/.claude/skills/rite-define/SKILL.md) | Turns the approved spec into architecture, a plan, traceability, and vertical task slices. |
+| 5 | Vet | [`/rite-vet`](pack/.claude/skills/rite-vet/SKILL.md) | Reviews every plan before implementation. The review depth scales with the risk. |
+| 6 | Build | [`/rite-build`](pack/.claude/skills/rite-build/SKILL.md) | Implements and verifies one slice, then stops. Run it again for each remaining slice. |
+| 7 | Converge | [`/rite-converge`](pack/.claude/skills/rite-converge/SKILL.md) | Runs only when recovery is needed. It compares the code with the recorded intent, adds missing slices, and sends the changed plan back to Vet. |
+| 8 | Prove | [`/rite-prove`](pack/.claude/skills/rite-prove/SKILL.md) | Runs the completed feature's tests, build, runtime checks, and browser proof when the feature has a UI. |
+| 9 | Polish | [`/rite-polish`](pack/.claude/skills/rite-polish/SKILL.md) | Cleans up the touched code and normalizes the UI when needed. |
+| 10 | Review | [`/rite-review`](pack/.claude/skills/rite-review/SKILL.md) | Reviews the completed feature against its spec and engineering standards. |
+| 11 | Seal | [`/rite-seal`](pack/.claude/skills/rite-seal/SKILL.md) | Writes the final `GO` or `NO-GO` decision without changing git. |
+| 12 | Ship | [`/rite-ship`](pack/.claude/skills/rite-ship/SKILL.md) | On `GO`, asks for typed confirmation, performs the approved git actions, and archives the workspace. |
 
 Some work needs a different route:
 
 - [`/rite-quick`](pack/.claude/skills/rite-quick/SKILL.md) handles a small,
   reversible change without creating a full feature workspace.
-- [`/rite-temper`](pack/.claude/skills/rite-temper/SKILL.md) challenges the
-  scope and failure modes of a larger spec before Define.
-- [`/rite-converge`](pack/.claude/skills/rite-converge/SKILL.md) compares a
-  resumed, adopted, or stalled feature with the live code and adds the missing
-  work as new slices.
 - [`/rite-autocomplete`](pack/.claude/skills/rite-autocomplete/SKILL.md) runs
   the lifecycle unattended. With `--ship`, it auto-confirms the final typed
   `GO`; without that flag, it stops and waits for you.
@@ -113,9 +115,12 @@ the original decisions and proof.
   work/<slug>/
     brief.md
     spec.md
+    decision-coverage.md
     architecture.md
     plan.md
     tasks.md
+    eng-review.md
+    test-plan.md
     state.md
     decisions.md
     questions.md
@@ -127,17 +132,20 @@ the original decisions and proof.
   archive/<slug>/
 ```
 
-Some phases add focused artifacts such as `strategy.md`, `test-plan.md`,
-`design-brief.md`, `browser-evidence.md`, `polish-report.md`, `drift.md`, or
-`handoff.md`. See the [workspace contract](docs/orchestration.md) for the full
-state model.
+Some phases add focused artifacts such as `strategy.md`, `design-brief.md`,
+`browser-evidence.md`, `polish-report.md`, `drift.md`, or `handoff.md`. See the
+[workspace contract](docs/engine/workspace-schema.md) for the full state model.
 
 ## Safety rules
 
-- **Plan before code.** Spec, Define, and Vet settle the intended behavior and
-  implementation path before Build starts.
+- **Settle before code.** Spec and Clarify settle the behavior contract. Define
+  and Vet settle the implementation path before Build starts. The engine checks
+  the meaning and input digests of fresh `CLEAR` and `READY` artifacts; marker
+  text alone does not pass.
 - **Build one slice.** `/rite-build` implements one vertical slice and records
-  its proof before returning control.
+  its proof before returning control. Before dispatching the sole writer, the
+  root writes an exact `.wright-allowlist`. Reconciliation and integrity gates
+  use the same pre-slice baseline.
 - **Stop on drift.** If implementation no longer matches the plan, the Spec
   Drift Guard records the mismatch in `drift.md` and routes through
   [`/rite-plan repair`](pack/.claude/skills/rite-plan/SKILL.md).
@@ -178,10 +186,11 @@ The workflow treats this file as configuration and never rewrites it.
 engine decrements that state after each built slice. Delete `.devrites/AFK` to
 return to HITL.
 
-AFK still pauses for blocking or escalating gates, destructive migrations,
-auth or authorization changes, public API breaks, external service contract
-changes, filesystem destruction outside the workspace, and red tests, types,
-or lint. The full pause and gate contract is in
+AFK still pauses for product, scope, or policy choices, irreversible risk,
+and access or actions available only to a human. Agents use bounded recovery
+for red tests, type or lint errors, runtime failures, and missing technical
+coverage. If that recovery budget runs out, they record a technical blocker
+instead of asking a question. The full pause and gate contract is in
 [`afk-hitl.md`](pack/.claude/skills/devrites-lib/reference/standards/afk-hitl.md).
 
 ## Install, update, and remove
@@ -207,7 +216,7 @@ Useful install flags:
 |---|---|
 | `--target DIR` | Use another project directory. |
 | `--dry-run` | Show planned file operations without changing anything. |
-| `--force` | Replace conflicting files that DevRites does not own. |
+| `--force` | Replace or remove foreign or customized managed files. The installer still rejects symlinks and path escapes. |
 | `--no-codex` | Skip `.agents`, `.codex`, and `AGENTS.md` integration. |
 | `--no-agents` | Skip the review agents. |
 | `--no-skills` | Skip skills and their bundled standards. |
@@ -232,11 +241,22 @@ curl -fsSL https://raw.githubusercontent.com/ViktorsBaikers/DevRites/main/instal
 curl -fsSL https://raw.githubusercontent.com/ViktorsBaikers/DevRites/main/install.sh | bash -s -- --dry-run
 ```
 
-The installer records every managed project file in
-`.claude/devrites.manifest`. Update and uninstall use that manifest, preserve
-`.devrites/`, and avoid removing files they do not own. The optional shared
-`devrites-engine` binary is the only artifact that may be installed outside the
-project.
+The installer records every managed project file and its SHA-256 in
+`.claude/devrites.manifest`. Before an update or uninstall changes anything, it
+checks every managed path. It preserves customized files and tells the user to
+retry with `--force` before making any changes; legacy manifests without hashes
+also require `--force`.
+`--force --dry-run` lists the exact destructive actions. Marker-merged files
+keep user content outside the DevRites block, and `.devrites/` runtime state
+remains in place. The installer refuses symlinks, junctions, and paths that
+escape the target.
+
+The optional shared `devrites-engine` binary is the only artifact installed
+outside the project. Before replacement, the release binary at its staged path
+must report the requested version. After installation, the binary at its final
+path must report that version in a new process. The installer keeps a backup in
+the same directory until the second check passes. On failure, it restores the
+previous binary or removes a bad first install.
 
 ## Claude Code and Codex integration
 
@@ -255,14 +275,14 @@ through Claude Code or Codex plugin stores.
 
 ## Skills and agents
 
-The pack ships 42 skills: 30 public and 12 internal. The public surface contains
-the `rite` menu and 29 `rite-*` workflows and utilities. Eleven `devrites-*`
+The pack ships 43 skills: 31 public and 12 internal. The public surface contains
+the `rite` menu and 30 `rite-*` workflows and utilities. Eleven `devrites-*`
 specialists load when a matching task needs them; `devrites-lib` carries the
 shared contracts and engineering standards.
 
-Fourteen agents ship with the pack. Thirteen are read-only reviewers or
-analysts, including `devrites-retrospector`, which reads the shipped archive.
-`devrites-slice-wright` is the only agent allowed to edit a feature slice.
+Seventeen fresh-context agents ship with the pack. Sixteen are read-only,
+including the evidence scout, plan drafter, proof runner, reviewers, judges,
+and retrospector. `devrites-slice-wright` is the only source/test writer.
 
 The authoritative [skills catalogue](docs/skills.md) lists every skill and
 agent. The [flow diagrams](docs/flow.md) show routing, reviewer fan-out, and
@@ -293,13 +313,13 @@ traces. DevRites detects these tools but does not install them.
 ## Security model
 
 Installed host artifacts stay in the project. The npm shim prefers an explicitly
-configured engine or a local `engine/devrites-engine`, can download a
-checksummed release binary, can build a temporary engine from the local Go
-source, and finally falls back to an existing `devrites-engine` on `PATH`. Use `--no-binary` or
-`DEVRITES_NO_BINARY=1` if you do not want the installer to keep the shared
-binary outside the project. `devrites-engine update` also prefers the
-checksummed platform release binary and only builds from source as a fallback,
-without reading Git metadata from the target project.
+configured engine or a local `engine/devrites-engine`. If neither is available,
+it can download a checksummed release binary or build a temporary engine from
+the local Go source before falling back to `devrites-engine` on `PATH`. Use
+`--no-binary` or `DEVRITES_NO_BINARY=1` to avoid keeping a shared binary outside
+the project. `devrites-engine update` also prefers the checksummed platform
+release and builds from source only as a fallback. It does not read Git metadata
+from the target project.
 
 Workflow state is read through the engine rather than shell injection. The
 installer never writes `defaultMode: bypassPermissions`. Skills use networked

package/SECURITY.md

@@ -61,19 +61,19 @@ reviewable; never suppress a hidden-unicode finding you can't explain.
 ### State loading (engine subcommands, no `!` injection)
 
 `/rite-status` and workspace-operating skills load state by running a **read-only
-`devrites-engine` subcommand through the `Bash` tool**. It does not use Claude Code's
-preprocessing-only `` !`<command>` `` dynamic-context injection, which DevRites
-**removed** for cross-harness portability. The no-argument `/rite` menu runs
+`devrites-engine` subcommand through the `Bash` tool**. DevRites does not use
+Claude Code's preprocessing-only `` !`<command>` `` dynamic-context injection
+because that mechanism is not portable across harnesses. The no-argument `/rite` menu runs
 `devrites-engine first-task` instead; a routed verb hands control to its owning skill.
 
 ```bash
 command -v devrites-engine >/dev/null 2>&1 && devrites-engine preamble || echo "(unavailable: read state.md directly)"
 ```
 
-`devrites-engine preamble` is a project-local read of DevRites' own `.devrites/`
-state: no user input is concatenated into a command, no network access, no write
-side effects. The gate subcommands (`build-readiness`, `evidence-fresh`,
-`check-acceptance`) are likewise read-only. Mutating commands are explicit and
+`devrites-engine preamble` reads the project's `.devrites/` state. It does not
+concatenate user input into a command, access the network, or write files. The
+gate subcommands (`build-readiness`, `evidence-fresh`, `check-acceptance`) are
+also read-only. Mutating commands are explicit and
 scoped: for example, `resolve`, `tick-afk`, and `close-out` write only DevRites
 state, while `/rite use <slug>` deliberately repoints `.devrites/ACTIVE` inline.
 
@@ -81,7 +81,7 @@ If your environment disallows shell commands started by skills, each skill reads
 `state.md` directly through the `|| echo "(… unavailable …)"` fallback above.
 The rest of the pack continues to work.
 
-### Model invocation is per skill
+### User and model invocation are separate
 
 Public skills are always user-invocable, but model invocation is set per skill.
 Skills without `disable-model-invocation: true` may be selected when their
@@ -115,22 +115,21 @@ uninstall.
 
 Skills, agents, standards, and hook configuration stay in the target project.
 The installer merges DevRites entries into project-local `.claude/settings.json`
-and `.codex/hooks.json` without replacing unrelated user settings. Its only
-sanctioned global artifact is the shared `devrites-engine` executable, installed
-to `DEVRITES_BIN_DIR`, a writable `~/.local/bin`, or a writable
+and `.codex/hooks.json` without replacing unrelated user settings. The shared
+`devrites-engine` executable is the only allowed artifact outside the project.
+It is installed to `DEVRITES_BIN_DIR`, a writable `~/.local/bin`, or a writable
 `/usr/local/bin`; `--no-binary` / `DEVRITES_NO_BINARY=1` skips it. The bootstrap
 path may fetch the release bundle and checksummed engine assets. It never invokes
 `sudo` or edits shell startup files.
 
 ### npx install path
 
-When installed via `npx devrites@latest`, the CLI (`bin/devrites.mjs`) is a thin
-Node shim that delegates directly to `devrites-engine`; it does not execute
-`install.sh`. The host payload is bundled and pinned to the requested npm package
-version. To start the engine, the shim tries the matching release binary plus its
-SHA-256 sidecar, then a local Go build, then an existing engine. It has no runtime
-npm dependencies. Project-artifact and optional shared-binary boundaries are the
-same as the Bash path.
+With `npx devrites@latest`, the CLI (`bin/devrites.mjs`) calls
+`devrites-engine` directly instead of running `install.sh`. The bundled host
+payload is pinned to the requested npm package version. The shim first tries the
+matching release binary and its SHA-256 sidecar, then a local Go build, and then
+an existing engine. It has no runtime npm dependencies. The same project and
+shared-binary boundaries apply to the Bash installer.
 
 ### Recommended Claude Code permissions for managed deployments
 
@@ -148,17 +147,16 @@ For organizations evaluating DevRites under a managed Claude Code policy:
 }
 ```
 
-This follows the current
-[Claude Code permissions schema](https://code.claude.com/docs/en/permissions)
-and surfaces a host confirmation before the git mutation ladder. DevRites'
+Under the current
+[Claude Code permissions schema](https://code.claude.com/docs/en/permissions),
+the host asks for confirmation before the git mutation ladder. DevRites'
 separate type-`GO` workflow gate still applies.
 
 ### Hooks (approval, orientation, and local guards)
 
-DevRites ships JSON-configured hooks installed by the engine-owned flow into the
-project-local host artifacts (`.claude/settings.json` for Claude Code and
-`.codex/hooks.json` for Codex). They call `devrites-engine` behind an inline
-fail-open guard:
+The engine installs JSON-configured hooks in the project-local host artifacts:
+`.claude/settings.json` for Claude Code and `.codex/hooks.json` for Codex. Both
+files call `devrites-engine` behind an inline fail-open guard:
 
 - **`allow` (PreToolUse/Bash)**: auto-approves *only* the read-only engine
   orientation/gate subcommands (`check-acceptance`, `doubt-coverage`,
@@ -193,13 +191,13 @@ bundling them.
 
 ### Agentic trust boundaries
 
-Treat every instruction-bearing file as supply chain:
+Treat every instruction-bearing file as a supply-chain input:
 
 1. **Shipped pack**: `pack/.claude/**`, generated host artifacts, hooks, and the
    engine are release-managed and scanned before publish.
-2. **Project-local state**: `.devrites/work/**`, learnings, principles, and
-   review artifacts are evidence, not authority. Live source and engine gates win
-   over stale state.
+2. **Project-local state**: `.devrites/work/**`, learnings, unvalidated
+   principles, and review artifacts are evidence, not authority. Live source and
+   engine gates win over stale state.
 3. **User extensions/overrides**: `.devrites/extensions/**` and
    `.devrites/overrides/**` are untrusted until `devrites-engine extensions
    validate` / `overrides validate` pass. Extensions may add checks or reviewers;
@@ -210,6 +208,10 @@ Treat every instruction-bearing file as supply chain:
    missing tools degrade to file-system/engine gates instead of silently changing
    workflow semantics.
 
+<!-- authority:principles-trust:start -->
+Project principles may become project policy only after explicit provenance and validation; arbitrary project-local Markdown is never inherently trusted executable instruction.
+<!-- authority:principles-trust:end -->
+
 Never copy untrusted issue text, web content, or model output into a skill,
 agent, hook, MCP config, or generated artifact without reviewing it as executable
 instructions. Hidden unicode, prompt-injection phrasing, personal absolute paths,

package/docs/adr/0001-go-engine-as-control-plane.md

@@ -30,7 +30,7 @@ framework.
 | Option | Why not |
 |--------|---------|
 | Bookkeeping inside the agent prompt | Non-deterministic, context-hungry, unauditable — the exact failure this system exists to remove. |
-| Node/TS engine (like the reference system GSD Core) | Drags a package tree + supply-chain surface; the pure-Go single binary has none and cross-compiles to every target from one runner. |
+| Node/TS engine | Drags a package tree + supply-chain surface; the pure-Go single binary has none and cross-compiles to every target from one runner. |
 | Cobra / urfave CLI framework | A dependency and a config surface for a switch statement the stdlib already handles. |
 
 ## Consequences

package/docs/adr/0002-dual-host-harness.md

@@ -22,7 +22,7 @@ enumerated in code, not open-ended. `harness-matrix --check` keeps
 
 | Option | Why not |
 |--------|---------|
-| A generic declarative capability/adapter registry now (the GSD Core model) | Real ceiling-raiser for N hosts, but a large refactor unjustified at N=2. Recorded as a Proposed follow-up, not built. See the adoption study in `docs/research/gsd-core-adoption.md` §3.1. |
+| A generic declarative capability/adapter registry now | Real ceiling-raiser for N hosts, but a large refactor unjustified at N=2. Recorded as a Proposed follow-up, not built. |
 | Claude-only | Codex users are already real; single-host would strand them. |
 | Per-host forks of the logic | Duplicates the lifecycle core across edges — the thing the adapter exists to prevent. |
 

package/docs/adr/0004-state-schema-phases-sections.md

@@ -40,8 +40,7 @@ additively.
 - Completeness is a table lookup, not a judgment call — cheap and reproducible.
 - Small files stay context-cheap and make "what's missing" self-evident.
 - `SchemaVersion = 1` is young; migration is single-version. Hardening the
-  writer into one pure transition function is a recorded follow-up
-  (`docs/research/gsd-core-adoption.md` §3.2).
+  writer into one pure transition function is a recorded follow-up.
 - The typed registry in `engine/internal/state/schema.go` is the lifecycle
   authority. Its invariant tests lock order, aliases, commands, requirements,
   and cross-format manifest freshness.

package/docs/adr/0006-clock-seam-and-engine-ci-gates.md

@@ -5,16 +5,15 @@
 
 ## Context
 
-Two gaps surfaced while studying a more mature peer system (GSD Core; see
-`docs/research/gsd-core-adoption.md`):
+Two gaps surfaced during a control-plane reliability audit:
 
 1. **Unwired static analysis.** `engine/Makefile` defined `staticcheck` and
    `govulncheck` targets, but CI ran only `gofmt` + `go vet`. No `-race`, no
    custom analysis on the trust-root binary.
 2. **A wall-clock leak.** `resolve next-qid` derived today's date from a raw
    `time.Now()` with no seam, so its golden snapshot was pinned to the date it
-   was recorded and failed **every other day** — a latent red the peer system's
-   clock-seam lint would have caught at author time.
+   was recorded and failed **every other day** — a clock-seam check would have
+   caught the latent failure at author time.
 
 ## Decision
 

package/docs/adr/0009-prebuild-decision-coverage-and-readiness.md

@@ -0,0 +1,67 @@
+# ADR-0009: Pre-build decision coverage and implementation readiness
+
+- **Status:** Accepted
+- **Date:** 2026-07-23
+
+> This ADR amends the lifecycle order in
+> [ADR-0004](0004-state-schema-phases-sections.md) without changing its
+> phase-relative completeness model.
+
+## Context
+
+Real feature runs reached `/rite-build` with product/constraint gaps and incomplete
+tooling/proof prerequisites. The build then repeatedly asked for `rite-resolve` or
+`rite-plan repair`, including approval for bounded technical recovery that an agent should
+own. Earlier phases had good local checklists, but no mandatory whole-feature decision
+coverage artifact, and the engine's build-readiness gate checked only `state.md`.
+
+DevRites already had a reusable clarification protocol in `devrites-interview`; the missing
+piece was lifecycle ownership and an executable gate, not another interview implementation.
+
+The design review retained multi-dimensional readiness checks, fact-first
+clarification, behavior scenarios, cross-artifact consistency, goal-backward
+plan checking, and an explicit implementation-readiness assessment.
+
+We deliberately reject asking the human to approve every technical finding and unbounded
+interview ceremony. Those patterns reproduce the interruption fatigue this change fixes.
+
+## Decision
+
+1. Add one public phase between spec and temper:
+   `frame → spec → clarify → temper → define → plan → vet → build → converge → prove → polish → review → seal → ship → done`.
+2. `/rite-clarify` is mandatory but adaptive. It enumerates the feature topology, searches
+   facts before asking, reuses `devrites-interview`, and takes a zero-question fast path when
+   the written contract is already complete.
+3. Clarification writes `decision-coverage.md`. Buildable work must contain
+   `Decision coverage: CLEAR`; Partial, Missing, unowned, or blocking rows cannot pass.
+4. Keep `/rite-vet` as the single final pre-build gate rather than adding a duplicate
+   readiness phase. It performs goal-backward implementation-readiness checks and writes
+   exactly one typed verdict:
+   `READY`, `NEEDS CLARIFICATION`, or `NEEDS REPLAN`.
+5. The engine requires both `Decision coverage: CLEAR` and
+   `Implementation readiness: READY` (plus `test-plan.md`) at build entry. Missing
+   clarification routes to `/rite-clarify`; missing vet readiness routes to `/rite-vet`.
+   Neither route manufactures a human question.
+6. Later-phase workspaces may retrofit decision coverage without cursor regression when the
+   contract is unchanged. A changed requirement or acceptance criterion still uses the Spec
+   Drift Guard and replanning.
+
+## Alternatives considered
+
+| Option | Why not |
+|---|---|
+| Strengthen spec/define/vet prose only | Still leaves no auditable proof that the whole feature topology was scanned and no deterministic build-entry gate. |
+| Add a new final `/rite-ready` phase | Duplicates `/rite-vet`, adds ceremony, and splits one readiness source of truth across two phases. |
+| Make clarification optional for small work | Optional gates are exactly how omissions survive; an adaptive zero-question pass has negligible cost while retaining the invariant. |
+| Ask every unresolved item during build | Defers cheap decisions to the most expensive point and turns routine technical recovery into human authorization. |
+
+## Consequences
+
+- Planning cannot begin without explicit decision coverage, and build cannot begin without
+  both clarification and engineering-readiness verdicts.
+- Small/well-specified work gains one cheap deterministic pass, not an interview tax.
+- Existing active workspaces missing the new artifacts receive actionable `/rite-clarify`
+  and `/rite-vet` routes rather than false `/rite-resolve` prompts.
+- `engine/internal/state/schema.go` remains the typed lifecycle/workspace authority. This
+  topology is schema v2; migration upgrades declarations without fabricating readiness
+  evidence, and generated manifests/host artifacts change with the authority.

package/docs/adr/0010-agent-first-fresh-context-orchestration.md

@@ -0,0 +1,71 @@
+# ADR-0010: Agent-first fresh-context orchestration
+
+- **Status:** Accepted
+- **Date:** 2026-07-23
+
+## Context
+
+Lifecycle skills were still doing large searches, planning, proof, and repair work in the
+orchestrator's chat context. That increased context pressure and made delegation
+host-dependent: Codex could treat an unavailable custom role as if no spawn primitive
+existed, while one skill described an unnamed nested writer. Reviewer hooks also guarded
+only selected Bash commands, and the slice writer claimed its own file scope.
+
+The design review for
+[ADR-0009](0009-prebuild-decision-coverage-and-readiness.md) also retained
+file-backed fresh task packets, separated planner/checker/executor responsibilities,
+bounded research fan-out, explicit concurrency limits, typed reconciliation, and
+restartable artifact boundaries. We reject persistent swarms and parallel shared-tree
+writers.
+
+## Decision
+
+1. Public `rite-*` skills remain the root orchestrators. They alone own human interaction,
+   product/risk decisions, canonical `.devrites/` writes, phase routing, reconciliation,
+   gates, and irreversible actions.
+2. Heavy bounded work uses ephemeral fresh-context leaf agents at depth one. Normally no
+   more than three read-only leaves run concurrently; file overlap, dependencies, or
+   process/file-descriptor pressure reduce the wave to serial execution.
+3. Add three read-only roles:
+   `devrites-evidence-scout`, `devrites-plan-drafter`, and
+   `devrites-proof-runner`. Existing independent reviewers remain critics, not authors.
+4. `devrites-slice-wright` remains the only source/test writer. Writers never share a
+   working tree; accepted proof, polish, or review corrections become one bounded wright
+   contract.
+5. Dispatch uses file-backed `agent-packet/v1` and `agent-result/v1` envelopes with a run
+   ID, authoritative artifact paths, exact scope, budgets, immutable base/diff/touched-file
+   hashes, side effects, and typed terminal status. The orchestrator rejects malformed,
+   stale, or out-of-scope returns before persistence.
+6. Host fallback is ordered: named project role; generic fresh `explorer`/`worker`
+   reading the same role contract only when the host preserves its enforced read/write
+   boundary (or isolates the writer); inline discipline when no safe fresh-context rung
+   exists. Inline output is labelled non-independent and cannot silently satisfy an
+   independence gate.
+7. Agent security is fail-closed for declared leaf runs. Every role except the exact wright
+   is read-only; the wright consumes an orchestrator-created exact path allowlist. Nested
+   dispatch, self-claimed scope, installs, git publication, live migrations, and
+   `.devrites/` writes are forbidden to leaves.
+8. Objective failures use bounded technical recovery without asking the human to authorize
+   another attempt. Only product/scope/policy choices, irreversible risk, and human-only
+   access/actions create a human gate.
+
+## Alternatives considered
+
+| Option | Why not |
+|---|---|
+| Keep heavy work in the main chat | Reintroduces context accumulation and makes fresh independent judgment optional. |
+| One agent per lifecycle phase with write access | Duplicates orchestration authority and creates competing canonical writers. |
+| Persistent team/swarm with nested workers | Adds mailbox/watchdog state, amplifies resource pressure, and violates depth-one ownership. |
+| Parallel source writers on one tree | Makes authorship, implicit decisions, rollback, and reconciliation ambiguous. |
+| Inline fallback whenever a custom role is unavailable | Confuses “role unavailable” with “spawn unavailable” and falsely labels self-review independent. |
+
+## Consequences
+
+- Main-chat context holds routing and decisions, while agents reread canonical artifacts
+  from scratch and return compact typed results.
+- Delegation has deterministic authority, fallback, retry, and stale-result behavior on
+  both Claude and Codex.
+- Read-only fan-out can improve throughput, but resource limits are an upper bound rather
+  than a target.
+- Agent profiles, host generation, hooks, packet schemas, and composition tests must evolve
+  together; generated host artifacts remain derived from `pack/.claude`.

package/docs/adr/0011-define-plan-transition-rights.md

@@ -0,0 +1,28 @@
+# ADR-0011: Separate Define authoring from the Plan checkpoint
+
+- **Status:** Accepted
+- **Date:** 2026-07-23
+
+## Context
+
+The typed lifecycle gave both `define` and `plan` the same requirements and
+`/rite-define` resume command. Current skills already use `/rite-define` for
+first-pass plan authoring and `/rite-plan` only to repair or reslice an existing
+plan, so the duplicate state behavior made resume routing ambiguous.
+
+## Decision
+
+- `define` is in-progress plan authoring and resumes `/rite-define`.
+- `plan` is the approved or repaired plan checkpoint and resumes `/rite-vet`.
+- `/rite-plan` remains an explicit repair/reslice operation; it is not the
+  checkpoint's normal resume command.
+- Keep the `plan` phase ID and all phase aliases. Existing schema-v2 and legacy
+  workspaces therefore remain readable without migration.
+- The typed phase registry owns a unique transition-right sentence for every
+  state; the generated manifest and current lifecycle docs derive from it.
+
+## Consequences
+
+An interrupted approved plan continues into engineering review instead of
+re-entering plan authoring. Repair still uses `/rite-plan`, and no compatible
+workspace is rewritten merely because resume routing became unambiguous.

package/docs/adr/README.md

@@ -54,3 +54,6 @@ architecture; per-feature `decisions.md` files stay scoped to that feature.
 | [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` |

package/docs/agents/triage-labels.md

@@ -2,13 +2,13 @@
 
 The skills speak in terms of five canonical triage roles. This file maps those roles to the actual label strings used in this repo's issue tracker.
 
-| Label in mattpocock/skills | Label in our tracker | Meaning                                  |
-| -------------------------- | -------------------- | ---------------------------------------- |
-| `needs-triage`             | `needs-triage`       | Maintainer needs to evaluate this issue  |
-| `needs-info`               | `needs-info`         | Waiting on reporter for more information |
-| `ready-for-agent`          | `ready-for-agent`    | Fully specified, ready for an AFK agent  |
-| `ready-for-human`          | `ready-for-human`    | Requires human implementation            |
-| `wontfix`                  | `wontfix`            | Will not be actioned                     |
+| Canonical role    | Label in our tracker | Meaning                                  |
+| ----------------- | -------------------- | ---------------------------------------- |
+| `needs-triage`    | `needs-triage`       | Maintainer needs to evaluate this issue  |
+| `needs-info`      | `needs-info`         | Waiting on reporter for more information |
+| `ready-for-agent` | `ready-for-agent`    | Fully specified, ready for an AFK agent  |
+| `ready-for-human` | `ready-for-human`    | Requires human implementation            |
+| `wontfix`         | `wontfix`            | Will not be actioned                     |
 
 When a skill mentions a role (e.g. "apply the AFK-ready triage label"), use the corresponding label string from this table.