devrites 3.2.28 → 4.0.0

package/docs/architecture.md

@@ -3,12 +3,14 @@
 DevRites combines project-local Claude Code and Codex skills with one Go control
 plane. It gives AI coding agents a defined engineering process: frame → spec →
 mandatory adaptive clarify → optional temper → define → mandatory vet → build
-one verified slice → prove with evidence → polish → review → seal → ship.
+bounded verified slices → prove with evidence → polish → review → seal → ship.
 `converge` is the recovery state for bringing live code and recorded intent
 back into agreement.
+`frame` is a machine state/checkpoint and an optional, non-gating preflight
+lens; Spec begins the required feature-definition path.
 
-For the `.devrites/` load order, file budgets, artifact schema, aliases,
-traceability rules, and phase-relative completeness model, see
+For the `.devrites/` load order, file budgets, artifact schema, supported
+cursor readers, traceability rules, and phase-relative completeness model, see
 [`engine/workspace-schema.md`](engine/workspace-schema.md).
 
 ## Layers
@@ -20,8 +22,8 @@ traceability rules, and phase-relative completeness model, see
    `rite-polish`, `rite-review`, `rite-seal`, and `rite-ship`. `rite-plan`
    repairs or reslices an active plan. The resume verb `rite-resolve` answers a
    HITL gate and clears `Awaiting human`. `rite-upgrade` is a conditional
-   maintenance route for semantically stale active workspaces, not a lifecycle
-   phase. The thin `/rite` menu and read-only `rite-status` live in the public
+   evidence-gated compatibility route for older active workspaces, not a phase.
+   The thin `/rite` menu and read-only `rite-status` live in the public
    utility layer below.
    `/rite-seal` **decides** GO/NO-GO and writes the verdict to `seal.md`;
    `/rite-ship` is the final core lifecycle rite that **executes** the
@@ -33,9 +35,11 @@ traceability rules, and phase-relative completeness model, see
    `rite-customize`, `rite-zoom-out`, `rite-prototype`, `rite-handoff`,
    `rite-pressure-test`, `rite-pov`, `rite-dogfood`, `rite-pr-feedback`, and
    `rite-autocomplete`. These are public commands. `rite-autocomplete` is the
-   unattended orchestrator. It drives the whole lifecycle (spec → … → seal →
-   ship), chooses the recommended option at each soft gate, and pauses only for
-   hard irreversible-risk, blocking, or escalating gates, or a NO-GO. The
+   unattended orchestrator. By default it drives the reversible lifecycle
+   through Seal GO and stops. Explicit `--ship` enters Ship preflight but still
+   waits for a fresh literal `GO` and native approval before mutation. It
+   chooses the recommended option at each soft gate and pauses for hard
+   irreversible-risk, blocking, or escalating gates, or a NO-GO. The
    `devrites-` prefix prevents collisions with bundled Claude Code skill names
    such as `prototype`, `handoff`, `triage`, and `diagnose`; it does not mark
    visibility. `rite-pressure-test` needs no prefix because it does not collide.
@@ -44,8 +48,7 @@ traceability rules, and phase-relative completeness model, see
    `-doubt`, `-ux-shape` (plans UX/UI into `design-brief.md` at `/rite-spec`),
    `-frontend-craft`, `-browser-proof`, `-debug-recovery`,
    `-api-interface`, `-audit` (dispatches the security / perf / simplify
-   fresh-context reviewer on an axis argument), `-prose-craft`, and
-   `-refresh-indexes`. Public skills or host auto-selection invoke these 11
+   fresh-context reviewer on an axis argument), and `-prose-craft`. Public skills invoke these
    specialists. They do not appear in the menu. The `user-invocable:` flag,
    rather than the name prefix, determines whether a skill is public.
 
@@ -58,16 +61,16 @@ traceability rules, and phase-relative completeness model, see
 4. **Supporting references**: `reference/*.md` inside each skill. Long checklists,
    templates, and anti-rationalization tables loaded on demand (progressive
    disclosure) so `SKILL.md` bodies stay small.
-5. **Agents**: `.claude/agents/devrites-*` contains **18 flat depth-one roles**:
-   17 read-only leaves and the sole source/test writer,
-   `devrites-slice-wright`. The read-only set includes three bounded work
-   leaves (`devrites-evidence-scout`, `devrites-plan-drafter`, and
-   `devrites-proof-runner`), the fresh `devrites-upgrade-planner`, plus the
-   existing reviewers, auditors, judge, and retrospector. Public rites remain
-   authoritative: leaves return typed
-   evidence, never ask the human, change phase, or write canonical
-   `.devrites/**` state. See [`orchestration.md`](orchestration.md) for the
-   dispatch, fallback, identity, and reconciliation contract.
+5. **Agents**: `.claude/agents/devrites-*` contains **17 flat depth-one roles**:
+   16 read-only leaves and `devrites-slice-wright`, the sole source/test writer
+   role. Claude and Codex make only that role writable; Codex generates the
+   other 16 profiles read-only. The read-only set includes three
+   bounded work leaves (`devrites-evidence-scout`, `devrites-plan-drafter`, and
+   `devrites-proof-runner`), the fresh upgrade assessor, plus the
+   reviewers, auditors, and retrospector. Public rites remain
+   authoritative: leaves return bounded evidence, never ask the human, change
+   phase, or write canonical `.devrites/**` state. See
+   [`orchestration.md`](orchestration.md) for the host boundary.
 6. **Engineering rules**: DevRites' own stack-agnostic rules installed to
    `.claude/skills/devrites-lib/reference/standards/`. Workspace-operating lifecycle
    skills read `core.md` in step 0; compact utilities load only their local or conditional
@@ -92,38 +95,85 @@ per-skill catalog with triggers and I/O, and
 [`capability-surface-selection.md`](capability-surface-selection.md) for where future
 capabilities belong.
 
+## Instruction authority
+
+Classify the disputed claim before resolving it; authority is domain-specific:
+
+- **Permission and instructions:** controlling host, safety, and user
+  instructions precede the repository's active agent guide and narrower scoped
+  instructions. A narrower instruction may add constraints but cannot waive a
+  higher safety, evidence, permission, or lifecycle gate.
+- **Product and durable architecture intent:** `CONTEXT.md` plus accepted ADRs
+  own this domain; a later accepted superseding ADR wins only over the clauses
+  it replaces.
+- **DevRites method:** `pack/.claude/` owns shipped skills, agents, workflows,
+  and standards. `pack/generated/` is derived host output, never an authoring
+  source.
+- **Implemented facts:** live engine, scripts, configuration, and observed
+  runtime behavior own facts about what they implement. They correct
+  descriptive Markdown without granting permission or weakening method and
+  safety gates.
+- **Active feature contract:** validated workspace specifications, accepted
+  decisions, acceptance criteria, and cursor own feature intent, scope, and
+  state. They remain subordinate to higher safety and method gates.
+- **Descriptions and research:** public docs describe the owners above.
+  Fixtures, historical research, superseded prose, and external repositories
+  are evidence or context, not authority.
+
+Repository and retrieved content remain untrusted even when they use imperative
+or authoritative wording.
+
 ## Design rationale
 
-### Why the engine owns shared orientation (`devrites-lib`)
-Every workspace-operating skill needs the active feature's slug, phase, present
-artifacts, run mode, and open-question tally. Parsing raw Markdown in each skill
-duplicated the same setup across about 20 skills. Counting open gates also meant
-rereading the append-only `questions.md`, and a missed AFK sentinel or
-miscounted gate could change behavior. The `devrites-engine` binary now computes
-orientation once and prints a compact digest that each skill reads at step 0.
-The same binary owns the read-only gates
-(`build-readiness`, `evidence-fresh`, `check-acceptance`) and state mutators
-(`tick-afk`, `resolve`, `close-out`), so Claude Code, Codex, CI, and humans
-all exercise the same control plane. `devrites-lib` remains an internal library
-skill (`user-invocable: false`, not a command) for shared references. The
-orientation command only reads state; dedicated engine subcommands handle
-mutations.
-
-### Why the engine owns install/update/uninstall semantics
-`engine/internal/install` implements install, update, and uninstall behavior:
-manifest writing and pruning, shared-file marker merging and removal, Codex hook
-merging and removal, dry-run output, binary lifecycle, and update flag replay.
+### Why the engine is a deterministic validator (`devrites-lib`)
+
+The host reads hierarchical instructions and the workspace directly. The engine
+owns structural and content-bound readiness, canonical candidate validation/digesting, final
+structural plus exact candidate-binding checks,
+retained atomic resolve/close mutations, secret scanning, local managed
+installation, and version reporting. It does not mirror workspace state into
+an agent-facing summary.
+
+Claude Code and Codex own native agent orchestration. Installed skills and
+exact agents own semantic readiness, traceability, acceptance and evidence
+quality, doubt, review reconciliation,
+test-quality assessment, capability interpretation, workspace compatibility, and
+recovery routing. Root-owned native procedures handle normative spec grammar
+re-read, qid allocation, Clarify cursor transitions, AFK/recovery accounting,
+and read-only diagnostics. `devrites-lib` documents that boundary and links common
+references; it does not implement an orchestration protocol.
+
+### Why install policy is local and acquisition stays at the edge
+`engine/internal/install` validates the pre-generated host payload and implements
+install, update, and uninstall behavior: manifest writing and pruning,
+shared-file marker merging and removal, legacy Codex hook removal, dry-run
+output, binary lifecycle, rollback, and install-flag replay. These operations
+consume only caller-supplied local source, payload, and binary candidates; the
+engine does not select releases or perform network I/O. `update --check`
+compares the installed manifest version with that local candidate. Engine
+`--to` and `--pre` selectors do not exist.
 The shell entrypoints
 (`install.sh`, `uninstall.sh`, `update.sh`) and npm entrypoint
-(`bin/devrites.mjs`) remain bootstrap shims. They acquire a release bundle or
-engine binary, then pass arguments through.
+(`bin/devrites.mjs`) are acquisition adapters. They acquire and verify the
+exact-release bundle or binary, then pass local paths and user flags through to
+the deterministic engine operation. Network paths require exact SemVer,
+HTTPS-only redirects, exact-filename SHA-256 sidecars, private temporary
+directories, bounded transfers, and full archive preflight. They provide no
+unchecked raw, source-archive, tag, or default-branch fallback.
+
+Package and release builds populate `pack/generated/{claude,codex}`, so normal
+installs consume a pre-generated payload. In a source checkout, the shell
+install and update shims may regenerate missing payload components before
+handing the local payload to the engine. The engine itself only validates and
+copies that payload; it never generates host artifacts, and invalid payloads
+fail closed.
 
 Directly managed manifest entries carry SHA-256 ownership records. Before the
 first refresh, prune, or uninstall mutation, the engine classifies every
 affected path. It preserves customized or legacy entries without hashes unless
 `--force` is explicit, and it checks each path again immediately before a
-destructive action. Marker-owned shared files retain their block or hook merge
-policy. The engine rejects existing symlinks, junctions, and resolved target
+destructive action. Marker-owned shared files retain their block merge policy.
+The engine rejects existing symlinks, junctions, and resolved target
 escapes even under force.
 
 Binary replacement is a separate transaction. Before replacement, the binary
@@ -133,31 +183,36 @@ same check in a new process. On failure, the engine atomically restores the old
 bytes and mode or removes a bad first install. It does not use `PATH` to
 establish binary identity.
 
+Production Git call sites use one isolation policy in Go and one parity helper
+in shell. They remove environment variables that can retarget the repository,
+worktree, index, objects, refs, config, or pathspec while preserving unrelated
+Git variables; callers do not maintain independent deny lists.
+
 Some duplication is intentionally preserved at host boundaries. Raw `curl | bash`
 install/uninstall must be self-contained enough to fetch the bundle before any sibling
 files exist. Claude assets are authored under `pack/.claude/**`; Codex assets are
 generated into `pack/generated/**` and installed to `.agents/skills`, `.codex/agents`,
-`.codex/hooks.json`, and `AGENTS.md` because Codex and Claude use
+`.codex/config.toml`, and `AGENTS.md` because Codex and Claude use
 different project-local conventions. Those generated host artifacts are delivered by the
 npm installer; Claude/Codex plugin packaging is intentionally not a distribution path.
 
-### Why semantic upgrade is separate from update and migration
+### Why semantic upgrade is evidence-gated, not a migration
 
-Three operations solve different problems. `devrites-engine update` refreshes
-the installed binary and pack. `devrites-engine migrate` normalizes workspace
-layout and structural state schema. Neither one can claim that an active plan
-still follows the current planning rules.
+The shell/npm update entrypoint acquires a candidate and uses the local engine
+update operation to refresh the installed binary and pack. An active
+unfinished workspace may still fail a current contract. `/rite-upgrade [slug]`
+first asks the exact read-only `devrites-upgrade-planner` for a typed, cited
+assessment. Age and cursor encoding do not prove staleness. A repair must name
+the current rule, workspace evidence, affected gate, owner, paths, and minimum
+delta; Clarify, Plan repair, Converge, Vet, Prove, Polish, Review, or Seal then
+performs it under normal gates. Candidate repair runs current real proof and
+never synthesizes a historical pass; ambiguous legacy candidate scope is a gap.
 
-`/rite-upgrade [slug]` owns that semantic reconciliation. Build readiness uses
-the `devrites.readiness-artifacts.v2` contract declared by
-`decision-coverage.md`, `eng-review.md`, and `test-plan.md`; it returns code `8`
-when those existing artifacts are stale. The rite then asks a fresh read-only
-`devrites-upgrade-planner` to classify the gap before the root changes anything.
-It preserves completed source, slice bodies, decisions, and evidence, repairs
-only active unfinished planning, removes obsolete proof recipes and local
-wrappers, and reruns the current readiness gates. Already-current workspaces
-that pass readiness, completed workspaces, and archives remain untouched. See
-[ADR-0012](adr/0012-semantic-workspace-upgrades.md).
+The engine has no structural migration command or compatibility telemetry. It
+directly reads the official v1/v2 bullet and v3 table `state.md` cursors without
+rewriting them. Wider pre-release compatibility experiments are not runtime
+contracts. See [ADR-0025](adr/0025-evidence-gated-workspace-upgrades.md) and
+[ADR-0022](adr/0022-native-orchestration-thin-engine.md).
 
 ### Why `/engine` was rejected
 A single `/engine` (or `/devrites`) command would load every phase's
@@ -171,13 +226,11 @@ The team chose `rite-` because it is short, easy to remember, and matches the
 product's use of "rites" for disciplined steps. The prefix also avoids
 collisions. Built-in or bundled Claude Code commands include `/plan`, `/review`,
 `/run`, `/verify`, `/code-review`, `/simplify`, `/security-review`, `/init`,
-`/compact`, and `/debug`. (Collision audit:
-`research/claude-code-skills-notes.md`.)
+`/compact`, and `/debug`.
 
 ### Why a thin menu skill, not a mega-router
-`/rite` is an entrypoint. It shows a compact phase-grouped menu, prints
-recommended-start guidance from `devrites-engine first-task`, and dispatches a
-named verb to its owning skill. Menu mode does not read raw workspace state;
+`/rite` is an entrypoint. It shows a compact phase-grouped menu and dispatches a
+named verb to its owning skill. Menu mode does not infer workspace state;
 `/rite-status` owns detailed status. `/rite` does not duplicate workflow logic,
 which keeps selection small and leaves each phase in control of its context.
 
@@ -197,19 +250,29 @@ slice. Each concern therefore has its own artifact and gate. `/rite-spec`
 investigates the request and codebase in depth, then writes `spec.md` with the
 product what and why, requirements, acceptance criteria, non-goals, and
 measurable success. The spec
-must pass its readiness gate. `/rite-clarify` then audits the full actor,
+must pass native semantic review. `/rite-clarify` then audits the full actor,
 journey, data, interface, and operations topology and writes
 `decision-coverage.md`. A complete spec needs no questions.
 `/rite-define` turns that **approved, clarified spec** into `architecture.md`
 (technical map), `plan.md` (approach), `tasks.md` (vertical `SLICE-###` work), and
-`traceability.md` (AC/REQ → slice → proof → evidence → files). `/rite-vet` then records
-`Implementation readiness: READY` before build. Both verdict artifacts are
-semantically validated and bound to their canonical inputs by SHA-256 digest;
-marker text alone or a stale digest cannot pass. This checks the full spec
-before Build without turning `spec.md` into a long technical document.
+`traceability.md` (AC/REQ → slice → proof → evidence → files). `/rite-vet` uses
+the exact plan reviewer and records `Implementation readiness: READY` before
+build. The active skills and reviewers verify those claims against all relevant
+artifacts; the engine checks required-file structure and binds the stable Build
+inputs to that review without interpreting their prose. This checks the full
+spec before Build without turning `spec.md` into a long technical document.
 `/rite-plan` separately repairs, reslices, or reorders an active plan when it
 goes stale or drifts.
 
+New or materially revised specs declare one `Capability impact:`. MODIFIED
+capability deltas preserve every prior scenario and normative/source-grounded
+claim unless an accepted `DEC-###` explicitly authorizes replacement. A changed
+API, event, schema, or other provider/consumer boundary gets one canonical
+`Shared contract proof` artifact plus provider- and consumer-side asserting
+tests that both consume it; no boundary change uses one justified no-impact
+statement. These contracts stay in `spec.md`, `plan.md`, and the existing
+traceability/proof artifacts rather than creating another registry.
+
 ### Why `/rite-polish` is one skill with two progressive-disclosure halves
 Polish has two natural halves: **code** (simplify, dead code, naming, plus
 backend if BE was touched) and **UI** (normalize to the design system, then
@@ -230,17 +293,31 @@ Normalization remains the entry gate for UI polish. The UI reference refuses
 to run Phase 4 before Phase 3 because detail work would otherwise reinforce
 patterns that do not match the project's design system.
 
+Polish also owns every candidate-affecting capability-ledger fold, optional
+`DESIGN.md` update, and durable ADR promotion. It refreshes affected proof and
+closes the manifest before Review; Ship does none of these writes.
+
 ### Why seal and ship are separate phases (`/rite-seal`, `/rite-ship`)
 Deciding whether a change is safe to ship has a smaller blast radius than
-shipping it. `/rite-seal` checks acceptance against evidence, dispatches the
-fresh-context reviewers, writes the GO or NO-GO verdict to `seal.md`, and runs
-no git commands. On GO, it sets `state.md` to `Next step: /rite-ship` and stops.
-`/rite-ship` refuses to run without a GO in `seal.md`. It renders the type-`GO`
-prompt, runs the irreversible git ladder (commit → push → tag/PR under the
-project's convention), and writes `ship.md`. It then sets phase `done`, moves
+shipping it. `/rite-seal` asks exact fresh-context agents to judge acceptance,
+evidence quality, tests, doubt, and the applicable review axes; the root
+reconciles their results, requires positive discriminating proof, binds the
+review and verdict to the closed candidate, runs the structural-plus-binding
+engine check,
+writes the GO or NO-GO verdict to `seal.md`, and runs no git commands. On GO,
+it sets `state.md` to `Next step: /rite-ship` and stops.
+`/rite-ship` refuses to run without a GO in `seal.md` and remains
+candidate-read-only. Before type-`GO`, it performs only read-only candidate,
+history, existing-index, and plan checks, then discloses the exact one-use Git
+attempt. After a fresh literal `GO`, it optionally collapses eligible
+checkpoints, stages exact manifest paths, validates staged scope, bytes,
+bindings, and secrets, commits, and reverifies the committed candidate. It runs
+push, tag, or PR actions only when the disclosed project convention requires
+them and they are approved, then writes `ship.md`. It sets phase `done` and
+moves
 `.devrites/work/<slug>/` to `.devrites/archive/<slug>/` with every `.md` file
-preserved, and clears `.devrites/ACTIVE`. The GO verdict does not authorize a
-push; the separate Ship step does.
+preserved, and clears `.devrites/ACTIVE`. The Seal GO verdict authorizes no Git
+mutation; only Ship's freshly approved disclosed attempt does.
 
 ### Why `/rite-autocomplete` exists (the unattended orchestrator)
 Some features are routine enough to run without human input at every phase.
@@ -255,18 +332,19 @@ in `decisions.md`. It does **not** weaken the safety gates: genuine
 product/scope/policy decisions, irreversible risk, human-only access/actions,
 an open human-owned gate, a NO-GO, exhausted `max_slices`, or low confidence
 still pause. Agents use bounded recovery for red tests, runtime failures, and
-missing technical coverage. By default the workflow stops at the final
-type-`GO`; the `--ship` flag (alias `--yolo`) confirms it and pushes without
-another prompt.
+missing technical coverage. By default the workflow stops at Seal GO with `/rite-ship` as the next step.
+The `--ship` flag (alias `--yolo`) continues through Ship preflight, discloses
+the exact Git plan, and still stops for a fresh literal `GO` plus native host
+approval.
 
 ### Why persistent `.devrites/` state
 Long features outlive a single context window. Durable Markdown for the spec,
 plan, tasks, state, evidence, drift, and decisions lets any phase reload the
 current position in any session, even after compaction. Later-phase
-clarification stores `return_phase` and `return_next_action` in `state.md`;
-technical recovery stores a fingerprinted three-attempt budget in
-`recovery-attempts.jsonl`. Session-scoped workflows cannot provide the same
-resume behavior because they do not persist feature state.
+clarification stores `return_phase` and `return_next_action` in `state.md` and
+the root restores them only when the contract remains neutral. Recovery counts
+the caller and recovery loop's failed attempts from current context plus
+durable Dead ends/evidence, with no separate counter artifact.
 
 ### Run modes: HITL & AFK
 
@@ -299,13 +377,13 @@ contract.
 
 ## Design choices at a glance
 
-- **Surface**: 31 public `rite-*` skills (44 total), plus the thin `/rite`
-  menu: 32 public and 12 internal. The lifecycle
+- **Surface**: 31 public `rite-*` skills (43 total), plus the thin `/rite`
+  menu: 32 public and 11 internal. The lifecycle
   includes mandatory adaptive Clarify, optional Temper, mandatory Vet, and
-  Converge recovery; Seal **decides** and Ship **executes + closes**. Eleven
-  `devrites-*` specialists are model-invoked and `devrites-lib` is the shared
-  non-command library. Visibility comes from `user-invocable:`, not the
-  namespace prefix.
+  Converge recovery; Seal **decides** and Ship **executes + closes**. Ten
+  `devrites-*` specialist skills are model-invoked; `devrites-lib` is the
+  eleventh internal skill and the shared non-command library. Visibility comes
+  from `user-invocable:`, not the namespace prefix.
 - **Selection**: the `/rite` menu skill carries the routing table; every
   workflow skill enforces a "right skill, right time" rule in its body.
 - **State**: durable `.devrites/` Markdown that survives compaction and new sessions.
@@ -314,29 +392,39 @@ contract.
 - **Run modes**: same lifecycle runs HITL (default; pause at typed gate) or AFK
   (drop `.devrites/AFK`; loop continues, discretionary pauses downgrade to
   advisory log, irreversible risk always pauses).
-- **Slice rule**: build **one vertical slice, then stop**. There is no automatic continuation.
+- **Slice rule**: in HITL, a direct `/rite-build` builds **one vertical slice,
+  then stops**. An explicit `.devrites/AFK` sentinel is the bounded low-risk
+  exception that may chain slices under its cap and pause rules.
+  `/rite-autocomplete` owns full-lifecycle repetition.
 - **Drift**: an explicit **Spec Drift Guard** in build/prove/polish/review/seal.
 - **Design**: `devrites-frontend-craft` + a four-phase `/rite-polish` orchestrator (code + backend always; UI normalize + polish when UI is in scope).
-- **Agents**: 18 fresh-context roles at flat depth one: 17 read-only leaves and
-  one wright. Dispatch order is named, then guarded generic; if neither can
-  spawn, the workflow stops for HITL.
+- **Agents**: 17 fresh-context roles at flat depth one: 16 read-only leaves and
+  one wright. Dispatch uses the exact named project role; if it cannot spawn,
+  the workflow stops for HITL.
 - **Review**: **feature-scoped** multi-axis review with severity labels and
   fresh-context agents at the seal.
-- **Scope**: clarify → seal (decide) → ship (commit → push → tag or PR,
-  following the project's convention) → close. The CI
+- **Scope**: clarify → seal (decide) → ship (read-only preflight → type-GO →
+  commit → optional approved push/tag/PR by project convention) → close. The CI
   pipeline stays with the project.
-- **Install**: project-local, manifest-managed host artifacts; the optional
+- **Install**: project-local, manifest-managed host artifacts; shell/npm owns
+  acquisition, the engine performs offline local mutation, and the optional
   shared engine binary is the only allowed global artifact.
 
+Candidate identity and bounded-input rationale are recorded in
+[ADR-0026](adr/0026-content-bound-proof-and-bounded-inputs.md). The
+[nine-source benchmark and adoption matrix](upstream-workflow-benchmark-2026-08-01.md)
+is a dated 2026-08-01 research snapshot: it records the commits and conclusions
+audited then, but it is not current authority. DevRites keeps its lifecycle and
+canonical owners rather than adopting another project's runtime or terminology.
+
 ## Deviations from the original build brief (and why)
 
 1. **Invocation semantics are explicit in frontmatter.** `user-invocable`
    controls whether a skill is a public command; `disable-model-invocation`
    independently marks explicit-only public utilities and the internal
-   `devrites-lib` library. `required-agent-roles` is the canonical list of
-   unconditional fresh-agent roles for one invocation (`none` is explicit);
-   Codex derives its fail-closed dispatch receipt from the installed mirror.
-   Model-invocable phases can still hand off and route;
+   `devrites-lib` library. Required and conditional agent dispatch stays in the
+   skill body, where the workflow step is already defined. Model-invocable
+   phases can still hand off and route;
    per-phase side-effect discipline (for example, "stop after one slice") is
    enforced in the skill **body**, because invocation flags cannot express it.
 2. **`context: fork` used selectively.** Verified it is a real field (isolated
@@ -356,6 +444,6 @@ acceptance criteria.
 
 See the top-level tree in `README.md` and the installed-target tree in `usage.md`.
 The canonical source pack lives under `pack/.claude/` (skills, agents, rules,
-and Claude hook wiring). The build renders `pack/generated/` host artifacts;
+and Claude permission wiring). The build renders `pack/generated/` host artifacts;
 the installer writes Claude assets under project `.claude/` and Codex assets
 under `.agents/`, `.codex/`, and the managed `AGENTS.md` block.

package/docs/candidate-integrity.md

@@ -0,0 +1,138 @@
+# Candidate integrity
+
+DevRites proves one explicit project candidate rather than an ambient Git diff.
+The candidate is the strict manifest in
+`.devrites/work/<slug>/touched-files.md`; its content-bound identity is computed
+only by `devrites-engine`.
+
+The canonical grammar and artifact budgets live in
+[`workspace-artifact-schema.md`](../pack/.claude/skills/devrites-lib/reference/workspace-artifact-schema.md).
+The architectural rationale is [ADR-0026](adr/0026-content-bound-proof-and-bounded-inputs.md).
+
+## Manifest
+
+`touched-files.md` contains exactly one `## Touched files` heading and exactly
+one authoritative `## Candidate manifest` heading. `## Touched files` describes
+the scope without repeating candidate paths; the manifest alone owns candidate
+scope. Its body is either the exact line `No project files.` or a table whose
+rows are sorted by `File`:
+
+```markdown
+| State | File | Slice | Reason |
+| --- | --- | --- | --- |
+| present | `path/to/file` | SLICE-001 | Observable reason |
+```
+
+`State` is `present` or `deleted`. Paths are project-relative UTF-8, already
+strictly sorted by normalized `File`, unique both exactly and under case
+folding, portable, and wrapped in one backtick pair. Components reject
+Windows-reserved characters and device names even when followed by an
+extension, plus a trailing dot or space. The optional `## Review trail` can
+point a human to `path:line` stops, but it cannot add to or redefine candidate
+scope.
+
+Repository-internal paths are never candidates. Under `.devrites`, only the
+exact durable owners `.devrites/principles.md` and `.devrites/specs/**` are
+admitted; all other siblings fail closed, including:
+
+- `.devrites/work/**`
+- `.devrites/ACTIVE`
+- `.devrites/AFK`
+- `.devrites/CHECKPOINT`
+- `.devrites/archive/**`
+- `.git/**`
+
+Other durable project files are candidates when the feature changes them,
+including `DESIGN.md` and `docs/adr/**`.
+
+## Check and bindings
+
+Run:
+
+```bash
+devrites-engine check candidate <slug>
+```
+
+A pass exits `0` and prints exactly two line-oriented fields:
+
+```text
+candidate-sha256: <64 lowercase hex>
+candidate-files: <manifest row count>
+```
+
+Invalid usage or root selection exits `2`. An invalid slug/workspace, malformed
+manifest, unsafe path, missing `present` file, existing `deleted` file, rejected
+file type, or size breach exits `3` with `candidate: BLOCKED: <reason>` on
+stderr. Fix the reported workspace or candidate; phases do not reinterpret a
+rejected manifest.
+
+The digest is recorded exactly once, as an unindented standalone line, in
+`evidence.md`, `review.md`, and `seal.md`, plus `browser-evidence.md` when that
+file exists:
+
+```text
+Candidate SHA-256: <64 lowercase hex>
+```
+
+The digest binds its domain and version plus every row's state, normalized path, regular/absent type,
+executable bit, byte length, and content. Content drift therefore blocks even
+when modification times are restored; a harmless touch with unchanged content
+does not.
+
+This worktree digest is not an atomic filesystem snapshot against a malicious
+concurrent same-size rewrite. It detects ordinary drift and bounded type/size
+changes; Ship's exact Git-index scope, byte, binding, and secret checks own the
+final freeze immediately before commit.
+
+## Lifecycle ownership
+
+| Phase | Candidate responsibility |
+|---|---|
+| Build | Maintain the manifest from each green slice's actual scoped diff. |
+| Prove | Check before and after approved commands, require the same digest, and bind real evidence (plus browser evidence when present). |
+| Polish | Apply every code/UI correction, capability-ledger fold, design-memory update, and durable ADR promotion; update the manifest and rerun affected proof before closing the candidate. |
+| Review | Review the closed bytes and bind `review.md` to their digest. A correction returns through affected Prove and a fresh Review. |
+| Seal | Bind `seal.md`, recheck every binding, and run `check seal`. A correction returns through Prove and Review. |
+| Ship | Remain candidate-read-only. Only ship/state/archive bookkeeping may change; candidate or manifest changes return through Prove, Review, and Seal. |
+
+Capability-ledger, `DESIGN.md`, and ADR rollups happen in Polish before Review,
+not in Ship.
+
+## Git scope at Ship
+
+Before type-`GO`, Ship is read-only: it protects existing staged work, verifies
+the candidate, Seal, bindings, and worktree, analyzes checkpoint history, and
+discloses the exact optional collapse and stage commands. Only literal `GO`
+permits those disclosed index/history mutations. Ship then compares the
+NUL-delimited `git diff --cached --name-status --no-renames -z` set with the
+manifest: `present` maps only to `A` or `M`, and `deleted` only to `D`. Missing,
+extra, renamed, duplicated, differently classified, or unstaged candidate
+changes block. Candidate, Seal bindings, staged bytes, and the staged secret
+scan all rerun immediately before commit; drift invalidates the one-use approval.
+
+Immediately after the authorized commit and before push or tag, Ship compares
+the commit's exact state/path set and bytes with the same manifest, then reruns
+Candidate and Seal. A mismatch stops; it is never reinterpreted as equivalent.
+Fresh literal `GO` and native host approval remain required for each disclosed
+Git attempt.
+
+## Older workspaces
+
+Released v1/v2/v3 unfinished workspaces use read-only `/rite-upgrade`. A missing
+or malformed manifest or binding is a current-contract defect, not permission to
+guess historical bytes. When legacy scope, the live diff, tasks, and traceability
+agree unambiguously, Upgrade routes current owners through Prove, Polish, Review,
+and Seal as applicable. They run fresh real proof and never synthesize an old
+pass. Ambiguous legacy scope remains a `gap` and stops without mutation.
+
+## Limits
+
+The engine accepts a manifest of at most 1 MiB and 4,096 rows. A path may be at
+most 4,096 bytes, each present regular file at most 64 MiB, and all present
+files together at most 256 MiB. Directories, symlinks, special files, traversal,
+absolute paths, duplicates, case-fold collisions, reserved components, and
+control characters fail closed. The engine proves deterministic identity and
+exact bindings, not the semantic quality of a specification, test, review, or
+release decision. See the
+[canonical schema](../pack/.claude/skills/devrites-lib/reference/workspace-artifact-schema.md)
+for current limits and [`SECURITY.md`](../SECURITY.md) for trust boundaries.

package/docs/capability-surface-selection.md

@@ -4,17 +4,27 @@ Pick the smallest surface that keeps the behavior deterministic:
 
 | Need | Put it in |
 |---|---|
-| Deterministic gate or state mutation | `devrites-engine` command |
-| Workflow judgment inside the current context | skill |
+| Cross-host structural check, atomic state mutation, install, or secret safety | an existing documented `devrites-engine` primitive |
+| Repository build/lint/schema/release validation | repository script or CI |
+| Semantic readiness, traceability, acceptance, capability, or recovery judgment | skill |
 | Fresh-context judgment or adversarial review | agent |
+| Agent discovery, dispatch, scheduling, waiting, or follow-up | native host |
 | Optional repeated structured external tool | MCP |
-| One-shot local deterministic action | script or engine subcommand |
+| One-shot repository-local deterministic action | script |
 
 Rules:
 
 - npm (`npx devrites ...`) is the canonical distribution path. The supported
   `curl | bash` bootstrap exists for environments without Node; neither path is
   a Claude/Codex plugin or marketplace install.
-- Prefer the engine for gates; prompts may call gates, not reimplement them.
+- The engine surface is closed around the inventory in [`cli.md`](cli.md).
+  Add a command only when both hosts need the same deterministic runtime
+  primitive and no existing command, standard library, native host feature, or
+  repository script owns it; semantic judgment is not such a primitive.
+- Never build an engine broker around native agents. Skills name the exact role;
+  Claude or Codex owns spawn fields, scheduling, waiting, and result delivery.
 - Prefer scripts for repo-local release/build glue that is not part of the user contract.
-- Do not add a dependency for what the Go engine or shell can do in a few lines.
+- Persisted schemas may carry versions; native agent orchestration does not get
+  a DevRites API version, tier protocol, receipt, polling loop, or fallback.
+- Prefer deletion and the standard library; do not add a dependency for a few
+  deterministic lines.