devrites 2.6.1 → 3.0.0

package/docs/engine/state-schema.md

@@ -0,0 +1,134 @@
+# `.devrites/` state schema (v1)
+
+The `devrites-engine` binary reads a project's workflow state from plain files under
+`.devrites/`. Those files are the source of truth and are hand-editable — a
+human edit always wins.
+
+`schemaVersion: 1`.
+
+For the layered load-order diagram, budget table, manifest/alias model, and
+phase-required section matrix, see [`workspace-schema.md`](workspace-schema.md).
+
+## Layout
+
+```
+.devrites/
+  work/
+    <slug>/
+      README.md       workspace map — phase, status, next action, read-next
+      brief.md        objective, non-goals, success definition
+      spec.md         product WHAT/WHY, requirements, acceptance, boundaries
+      architecture.md feature technical map
+      plan.md         approach and slice strategy
+      tasks.md        SLICE-### vertical slices
+      traceability.md AC/REQ -> slices -> tests/evidence/files
+      decisions.md    DEC-### decision log
+      assumptions.md  assumption register
+      questions.md    Q-### question register
+      state.md        compact cursor
+      evidence.md     EVID-### command/action proof
+      touched-files.md implementation file map
+  specs/              capability ledger — the living "what the system does now"
+    <capability>/
+      spec.md         proven Requirement blocks for this capability
+```
+
+Each feature is a directory of **small single-concern files**. Splitting the
+work this way (rather than one long document) keeps every file context-cheap and
+makes completeness self-evident: an empty or missing section is visibly empty.
+
+### Capability ledger — `specs/`
+
+`work/<slug>/` is **ephemeral** (archived on ship); `specs/` is **durable**. It is
+the cumulative record of proven behavior, one `spec.md` per capability, so a new
+feature starts from the system's current contract instead of re-deriving it from
+code. A feature's spec carries deltas (`## ADDED/MODIFIED/REMOVED Requirements —
+capability: <c>`); on ship, `devrites-engine ledger sync` folds them in — ADDED
+appends, MODIFIED replaces by header identity, REMOVED deletes. Living outside
+`work/`, the ledger survives close-out's archival — and unlike the rest of
+`.devrites/`, it is **git-tracked** (`.devrites/*` + `!.devrites/specs/`), so the
+proven contract is shared, not per-clone. Grammar and delta rules:
+[`spec-grammar.md`](../../pack/.claude/skills/devrites-lib/reference/standards/spec-grammar.md).
+
+Backward compatibility: `.devrites/features/<slug>/` remains readable as a legacy
+workspace location. `feature.md` / `index.md` may stand in for `README.md`, and
+`proof.md` may stand in for `evidence.md`.
+
+### `feature.md`
+
+The per-feature index. Its YAML frontmatter carries:
+
+| field           | meaning                                        |
+| --------------- | ---------------------------------------------- |
+| `slug`          | feature identifier (matches the directory)     |
+| `title`         | human-readable title                           |
+| `phase`         | current workflow phase (see below)             |
+| `schemaVersion` | schema version the file was written against    |
+
+A feature exists iff its `feature.md` exists. A `feature.md` with no `phase`, or
+an unknown `phase`, is an error.
+
+## Sections
+
+The legacy engine completeness sections, in canonical order:
+
+`spec` · `plan` · `decisions` · `tasks` · `proof` · `status`
+
+A section is **present** (has real content) when its `<section>.md` file exists
+and, after removing any leading YAML frontmatter, ATX (`#`) headings, and
+whitespace, some content remains. A stub that is only a heading counts as
+**empty** — scaffolding a file never fakes completeness.
+
+The 2026 Markdown workspace schema is stricter and lives in
+[`workspace-schema.md`](workspace-schema.md): it validates required phase-owned
+artifacts, stable IDs (`AC-###`, `SLICE-###`, `EVID-###`), traceability, evidence,
+compactness budgets, Mermaid fences, and stale local links.
+
+## Phases and required sections
+
+Phases follow the rite-\* arc. Completeness is **phase-relative**: each phase
+requires only the sections needed to leave it, and the set grows additively down
+the arc. A section that is not yet required (e.g. `proof` during the `spec`
+phase) never blocks.
+
+| phase   | required sections                                     |
+| ------- | ----------------------------------------------------- |
+| `frame` | *(none)*                                              |
+| `spec`  | `spec`                                                |
+| `plan`  | `spec`, `plan`                                         |
+| `build` | `spec`, `plan`, `decisions`, `tasks`                  |
+| `prove` | `spec`, `plan`, `decisions`, `tasks`, `proof`         |
+| `vet`   | `spec`, `plan`, `decisions`, `tasks`, `proof`         |
+| `seal`  | `spec`, `plan`, `decisions`, `tasks`, `proof`, `status` |
+| `ship`  | `spec`, `plan`, `decisions`, `tasks`, `proof`, `status` |
+
+## `devrites-engine status <slug>`
+
+Prints the feature's phase and, for each section, its present/empty state and
+whether the current phase requires it, then a completeness verdict computed over
+the required sections only. Output is deterministic and greppable:
+
+```
+feature: auth-tokens
+phase: build
+  spec       present  required
+  plan       present  required
+  decisions  present  required
+  tasks      empty    required
+  proof      empty
+  status     present
+result: incomplete (missing: tasks)
+```
+
+- Found feature → exit `0`, whether complete or incomplete (`status` reports, it
+  does not gate — gating is issue 04).
+- Unknown or missing slug → non-zero exit with a clear message on stderr.
+
+The engine makes **zero model or network calls**; `status` is a pure read of the
+files under `DEVRITES_ROOT` (or the nearest `.devrites/` above the working
+directory). A hand edit wins immediately because there is no status cache.
+
+`.devrites/` is ignored **except** the capability ledger at `specs/`, which is
+committed shared truth — the recommended pattern is `.devrites/*` +
+`!.devrites/specs/` (so `work/`, `archive/`, and `ACTIVE` stay per-clone runtime
+state while `specs/` is tracked).

package/docs/engine/workspace-schema.md

@@ -0,0 +1,150 @@
+# DevRites Workspace Artifact Schema
+
+DevRites workspaces are durable source-of-truth folders for a feature. Chat is
+temporary; the workspace must be enough for a fresh human or AI to resume without
+guessing. The schema follows three rules:
+
+- Keep each Markdown file single-purpose and compact.
+- Read the index first, then load only the files needed for the current phase.
+- Trace every acceptance criterion through slices, proof, evidence, and touched files.
+
+Root selection has two axes:
+
+- `DEVRITES_ROOT` selects the project root or `.devrites/` directory. When unset, the engine walks up
+  from cwd to the nearest `.devrites/`.
+- `.devrites/ACTIVE` selects the active feature workspace.
+- `DEVRITES_WORKSPACE` optionally names an explicit workspace path for CI/agents and overrides
+  `.devrites/ACTIVE` for commands that default to the active feature.
+
+Canonical live workspace:
+
+```text
+.devrites/
+  ACTIVE
+  work/
+    <slug>/
+      README.md                 # compact workspace map; feature.md/index.md aliases allowed
+      brief.md                  # request, objective, non-goals, success definition
+      spec.md                   # product WHAT/WHY and acceptance contract
+      architecture.md           # feature technical map
+      flows.md                  # optional Mermaid diagrams
+      decisions.md              # ADR-style decision log
+      assumptions.md            # assumptions and validation status
+      questions.md              # open/resolved human questions
+      plan.md                   # technical approach and slice strategy
+      tasks.md                  # vertical slices
+      traceability.md           # AC/REQ -> slices -> tests/evidence/files matrix
+      state.md                  # compact cursor
+      evidence.md               # command/action proof; proof.md alias allowed
+      browser-evidence.md       # optional UI/runtime browser proof
+      drift.md                  # optional spec/plan drift register
+      touched-files.md          # implementation file list
+      design-brief.md           # optional UI design contract
+      handoff.md                # optional cold-resume summary
+      references.md
+      references/
+  archive/
+    <slug>/
+```
+
+Backward compatibility: `.devrites/features/<slug>/` remains readable as an alias
+for `.devrites/work/<slug>/`; `feature.md` and `index.md` remain valid workspace
+maps; `proof.md` remains a proof alias for `evidence.md`. Migration should add the
+canonical files without deleting aliases.
+
+## Read Order
+
+| Phase / role | Read first | Then read | Usually skip |
+| --- | --- | --- | --- |
+| Spec | `README.md`, `brief.md` | `spec.md`, `references.md`, `questions.md` | `plan.md`, `evidence.md` |
+| Define / plan | `README.md`, `state.md` | `spec.md`, `architecture.md`, `decisions.md`, `assumptions.md` | `evidence.md` |
+| Vet | `README.md`, `traceability.md` | `plan.md`, `tasks.md`, `architecture.md`, `decisions.md` | browser proof unless UI |
+| Build | `state.md`, `tasks.md` | `plan.md`, `architecture.md`, `traceability.md`, `questions.md` | full evidence history |
+| Prove | `traceability.md`, `tasks.md` | `evidence.md`, `browser-evidence.md`, `touched-files.md` | long plan rationale |
+| Review / seal | `README.md`, `traceability.md` | `spec.md`, `evidence.md`, `decisions.md`, `drift.md`, `touched-files.md` | raw logs unless needed |
+| Handoff | `README.md`, `state.md` | `handoff.md`, then linked source files | duplicated summaries |
+
+## Artifact Contracts
+
+| Artifact | Required? | Owner phase | Read trigger | Budget | Required headings | Validation rules |
+| --- | --- | --- | --- | --- | --- | --- |
+| `README.md` / `index.md` / `feature.md` | required | `/rite-spec` | always first | 120 lines | current phase, status, next action, artifact map, read-next table, blocking gates, last updated | Must not duplicate full spec/plan/evidence. |
+| `brief.md` | required | `/rite-spec` | clarify objective | 80 lines | Objective, Non-goals, Success definition | One-screen request and scope summary. |
+| `spec.md` | required | `/rite-spec` | product contract | 260 lines | Problem, Goal, Non-goals, Users / actors, Requirements, Acceptance criteria, Edge Coverage, Prohibitions (must-NOT), Edge cases, Measurable success, Scope boundaries | Must use stable `REQ-###` and `AC-###`; no deep implementation details. |
+| `architecture.md` | required from plan | `/rite-define` | placement/integration work | 180 lines | Owning module / layer, Integration points, Data / API / events, Dependencies, Risks, Affected boundaries | Carries topology and boundaries, not product acceptance. |
+| `flows.md` | optional | `/rite-spec` or `/rite-define` | lifecycle/state/sequence/data flow is hard to infer | 160 lines | diagram-specific headings | Mermaid only when it clarifies behavior; each diagram states why it matters and related IDs. |
+| `decisions.md` | required | all phases | non-trivial product/technical choice | 200 lines | Decision log | Entries use `DEC-###`, status, context, options, decision, consequences, related IDs. |
+| `assumptions.md` | required | all phases | assumption is not yet verified | 160 lines | Assumption register | Confidence, owner, and validation status are explicit. |
+| `questions.md` | required | all phases | human input or gate | 180 lines | Question register | `Q-###`; no open blocking/escalating questions before plan/build/prove gates. |
+| `ai-spec.md` | conditional | `/rite-spec` or `/rite-define` | AI/LLM annex | 160 lines | AI surface, model/runtime choice, evals, guardrails, monitoring | Required only for model calls, RAG, agents, evals, or LLM output. |
+| `plan.md` | required from plan | `/rite-define` | implementation approach | 220 lines | Approach, Slice strategy, Validation strategy, Rollback | HOW lives here, not in `spec.md`. `Validation strategy` names the Key links — cross-slice wiring `/rite-prove` walks (or `none` for single-slice features). |
+| `tasks.md` | required from plan | `/rite-define` | build one slice | 280 lines | Slice index | Each `SLICE-###` has goal, AC IDs, likely files, tests/proof, mode, gate, dependencies, done condition. |
+| `traceability.md` | required from plan | `/rite-define` | coverage/review/seal | 220 lines | Coverage matrix | Matrix maps AC/REQ ID, slice IDs, test/proof, evidence ID, touched files, status. |
+| `state.md` | required | all phases | current cursor | 120 lines | Cursor | Compact table/key-value cursor; not an append-only narrative. |
+| `evidence.md` / `proof.md` | required from prove | `/rite-build`, `/rite-prove` | proof and seal | 280 lines | Evidence log | `EVID-###`, command/action, result, related AC/slice IDs, limitations. Each acceptance criterion carries a proof class — `test` / `command` / `browser` / `judgment` (untagged reads `judgment`; `judgment` needs its one-line why). |
+| `browser-evidence.md` | UI only | `/rite-prove`, `/rite-polish` | UI/browser proof | 220 lines | Browser evidence, Visual Verdict | Must reference real route/viewports/actions and related IDs. |
+| `drift.md` | drift only | Spec Drift Guard | spec/plan reality mismatch | 160 lines | Drift register | `DRIFT-###`, status, evidence found, resolution, related IDs. |
+| `touched-files.md` | required from build/prove | `/rite-build` | impact/evidence freshness | 160 lines | Touched files | File, slice ownership, and reason per row. |
+| `design-brief.md` | UI only | `devrites-ux-shape` | UI build/proof | 160 lines | Design direction, States, Interaction model | UI target only; no implementation task list. |
+| `handoff.md` | optional | `/rite-handoff` | cold resume | 120 lines | Resume, Read next, Next action | Links to source artifacts instead of copying them. |
+| `references.md` + `references/` | optional | `/rite-spec` | external/user-supplied material | 160 lines | Reference index | Links must resolve or be external URLs. |
+
+Files may exceed budgets only with a visible `Budget override: <reason>` line.
+
+## Required vs Optional
+
+Required at `/rite-spec`: workspace map, `brief.md`, `spec.md`, `state.md`,
+`decisions.md`, `assumptions.md`, `questions.md`.
+
+Required at `/rite-define` and later: all spec files plus `architecture.md`,
+`plan.md`, `tasks.md`, and `traceability.md`.
+
+Required at `/rite-prove` and later: all plan files plus `evidence.md` (or
+`proof.md`) and `touched-files.md`.
+
+Optional/conditional files are generated only by their producing phase:
+`flows.md` when diagrams clarify behavior, `design-brief.md` and
+`browser-evidence.md` for UI, `drift.md` for drift, `handoff.md` for handoff,
+and `references.md` / `references/` when references exist.
+
+## Compactness Rules
+
+- Put summaries first and deep details behind file links.
+- Use tables for matrices, gates, and checklists.
+- Do not repeat boilerplate across files.
+- Do not copy evidence output into `handoff.md`; link to `evidence.md`.
+- Do not copy architecture diagrams into `spec.md`; link to `architecture.md` or `flows.md`.
+- Do not copy full acceptance criteria into `plan.md`; reference `AC-###`.
+- Do not append long narrative logs to `state.md`; keep only the current cursor.
+- Prefer Mermaid only for useful boundary, sequence, state, lifecycle, or data-flow diagrams.
+
+## Stable IDs
+
+Use these forms in generated artifacts:
+
+| Kind | Format | Home |
+| --- | --- | --- |
+| Requirement | `REQ-001` | `spec.md` |
+| Acceptance criterion | `AC-001` | `spec.md` |
+| Slice | `SLICE-001` | `tasks.md` |
+| Decision | `DEC-001` | `decisions.md` |
+| Question | `Q-001` | `questions.md` |
+| Drift event | `DRIFT-001` | `drift.md` |
+| Evidence | `EVID-001` | `evidence.md`, `browser-evidence.md` |
+
+## Validation
+
+`scripts/validate-workspace-schema.py` validates generated workspaces. The
+project-wide validation path runs it against representative fixtures.
+
+The validator checks:
+
+- required files and headings for the current phase;
+- stable IDs and old `AC1` / `Slice 1` style regressions;
+- acceptance criteria referenced by at least one slice;
+- completed slices referenced by evidence;
+- no unresolved blocking/escalating questions before plan/build/prove gates;
+- high-traffic file budgets unless explicitly justified;
+- plausible Mermaid fences;
+- local Markdown links that point to existing files;
+- evidence IDs mapped in `traceability.md` once proof exists.

package/docs/extensions.md

@@ -0,0 +1,178 @@
+# Extending DevRites — project extensions & reviewer overrides
+
+DevRites ships a fixed, authored pack of rites, reviewers, and standards. The extension sync
+surface is currently **Claude Code-only**; Codex extension mirrors are not generated. Two project-local
+surfaces let a Claude Code project tune the pack **without forking it** — both live in the data plane
+(`.devrites/`), both are git-diffable, and both are held to the same contracts the shipped pack is.
+
+They answer two different questions:
+
+| Surface | Question it answers | Lives in |
+|---|---|---|
+| **Extensions** | "Add a *new* rite or reviewer / domain." | `.devrites/extensions/<name>/` |
+| **Overrides** | "Reshape a *shipped* reviewer's emphasis." | `.devrites/overrides/<agent>.md` |
+
+The guiding invariant for both: **a shipped gate is never weakened by a customization.** An
+extension earns parity by passing the same validator as the pack; an override may raise the bar,
+never lower it. The deterministic engine gates (`seal`, `review-integrity`, `check-acceptance`, …)
+do not read either surface — they stay authoritative regardless of what a project adds.
+
+---
+
+## Extensions — add a rite or reviewer
+
+A project extension is a directory under `.devrites/extensions/`:
+
+```
+.devrites/extensions/<name>/
+  skill/SKILL.md      (optional) a user rite/skill — needs name + description frontmatter
+  agent.md            (optional) a user reviewer agent — needs name + description frontmatter
+  component.yaml      (optional) npx-managed component manifest + safety bounds
+  provenance.json     (optional) source/author/review metadata for shared extensions
+  extension.yaml      (optional) metadata: aliases (prior names, so a rename doesn't orphan)
+```
+
+An extension provides a skill, an agent, or both. It is held to the same schema as the shipped
+pack — a malformed extension is refused, not silently half-installed.
+
+### Commands
+
+```bash
+devrites-engine extensions list       # enumerate extensions and what each provides
+devrites-engine extensions validate   # schema-check every extension (exit 1 on a violation)
+devrites-engine extensions sync        # mirror valid extensions into .claude/ for Claude Code
+```
+
+- **`validate`** checks each declared skill/agent carries `name:` + `description:` frontmatter, that
+  an extension provides at least one artifact, and that no two extensions claim the same skill/agent
+  name. If `component.yaml` is present, it must declare an npm-managed, project-local component:
+  `distribution: npx-managed`, `scope: project-local`, project-local write roots only, and safety
+  fields that do **not** weaken gates, bypass `type-GO`, or run executables. If `provenance.json`
+  is present it must be valid JSON with `source`, `author`, `created_at`, and optional
+  `confidence` (`0..1`) / `reviewed_by`; `/rite-doctor` warns when an extension ships artifacts
+  without provenance. V2 manifests may
+  also declare `tier`, `requires`, `owns`, and `surface`; dependencies must be acyclic, and anything
+  in `owns` that collides with the first-party `rite-`/`devrites-` namespaces is refused. If a
+  malformed extension declares a review/gate-like surface, validation warns that the surface is
+  inactive until the schema is fixed — fail-open, but loud.
+- **`sync`** validates first, then mirrors `skill/` → `.claude/skills/<name>/` and `agent.md` →
+  `.claude/agents/<name>.md`, where the Claude harness discovers them. Idempotent. It refuses to
+  sync a set that fails validation.
+- **`aliases`** (in `extension.yaml`) carry an extension's prior names forward across a rename, so a
+  project's references don't orphan.
+
+### Component manifest
+
+Public schemas live in [`../schemas/`](../schemas/): `extension-component.schema.json` and
+`provenance.schema.json` for extension metadata, plus workspace/hook schemas for editor tooling.
+
+`component.yaml` is the DevRites-native answer to Spec Kit-style extension/preset/bundle metadata.
+It is **not** a plugin package descriptor; it documents what the npm-installed engine may copy or
+validate inside the current project.
+
+```yaml
+schema_version: "1.1"
+kind: extension
+id: audit-lite              # must match .devrites/extensions/<name>/ when present
+version: 0.1.0
+tier: standard              # core | standard | full
+requires: []                # other local extension ids; acyclic
+owns:
+  skills: [audit-lite]
+  agents: []
+surface:
+  clusters: [review]
+safety:
+  may_weaken_gates: false
+  executable: false
+```
+
+Legacy `component:` / `permissions:` manifests still validate. The validator refuses global homes
+(`~/.claude/**`, `~/.codex/**`), plugin-store distribution names, non-project scopes, unknown/cyclic
+extension dependencies, first-party ownership collisions, and any manifest that claims it can weaken
+a gate, run executables, or bypass `type-GO`.
+
+### Declarative checks
+
+`component.yaml` may declare **checks** — non-executable, one-line instructions the data plane
+surfaces at a lifecycle gate:
+
+```yaml
+checks:
+  - at: seal
+    instruction: Run the license scan and record the result in evidence.md
+    doc: docs/license-scan.md   # optional pointer to the project's own procedure
+```
+
+- A check is an **instruction the in-session model addresses**, never a command the engine runs —
+  the deterministic engine gates still do not read extensions, and `executable: false` still holds.
+- Checks are **additive-only**: they can raise the bar at a gate, never lower one (same rule as
+  overrides). `/rite-seal` treats a declared `at: seal` check that is neither addressed nor
+  skip-justified in `seal.md` as an **Important** finding on the review's completeness.
+- Checks in an extension that fails validation are inactive — fail-open, but `extensions validate`
+  says so loudly.
+
+### Workflow
+
+Use `/rite-customize extension <name>` for guided authoring, or do it by hand:
+
+1. Author the extension under `.devrites/extensions/<name>/`.
+2. `devrites-engine extensions validate` until clean.
+3. `devrites-engine extensions sync` to mirror it into `.claude/`.
+4. `/rite-doctor` validates extensions on every health check and hands you the fix if one regresses.
+
+### Harness scope
+
+`sync` targets the **Claude Code-only** layout (`.claude/skills`, `.claude/agents`), which that host
+auto-discovers. It does not generate Codex mirrors, so project extensions are unavailable to Codex
+unless an operator maintains an equivalent Codex surface independently. The `.md` → `.codex/agents/*.toml` conversion,
+path rewriting, hook/config blocks, and skills-list description stubbing are deliberately limited to
+the generated shipped pack artifacts so extension sync does not become a second Codex generator.
+
+---
+
+## Overrides — reshape a shipped reviewer
+
+An override is a single Markdown file named for the agent it targets:
+
+```
+.devrites/overrides/devrites-code-reviewer.md
+.devrites/overrides/devrites-security-auditor.md
+```
+
+Each shipped reviewer, after loading its governing standards, reads
+`.devrites/overrides/<its-name>.md` if present and applies it as **project overrides** — extra
+emphasis or house rules this project wants enforced. For example, a `devrites-code-reviewer.md`
+override that says "always flag any use of the deprecated `legacyClient` as Important."
+
+### The one rule
+
+An override may **add** checks or **raise** weight. It may **never** relax a gate, waive a standard,
+or lower a severity floor — a Critical stays a Critical. Overrides are reviewer *input*, not
+permission. The engine gates don't read them at all, so an override literally cannot disable a gate;
+the linter exists to catch one that *tries to talk a reviewer into it*.
+
+### Commands
+
+Use `/rite-customize override <agent>` for guided authoring, or manage files directly:
+
+```bash
+devrites-engine overrides list       # enumerate override files and the agent each targets
+devrites-engine overrides validate   # flag empty overrides and any that read like a gate waiver (exit 1)
+```
+
+`validate` trips on subversion phrasing ("ignore the gate", "treat any Critical as a Suggestion",
+"waive review") and on an override targeting an agent that isn't installed (an orphan warning).
+`/rite-doctor` runs it on every health check.
+
+### Template overrides
+
+Future template/preset work uses `.devrites/overrides/templates/*.md` as the project-local override
+layer. `devrites-engine overrides validate` already applies the same anti-subversion scan to those
+files and adds required-term checks for high-risk lifecycle templates:
+
+- `seal.md` must still mention `type-GO` and `NO-GO`.
+- `ship.md` must still mention `type-GO`.
+
+This keeps the extension point useful without letting a project template erase the gates that make
+DevRites safe.

package/docs/flow.md

@@ -25,6 +25,8 @@ flowchart LR
     Build -->|HITL gate fires| Await{{Awaiting human<br/>state.md + questions.md}}
     Await -->|"/rite-resolve &lt;qid&gt; &lt;answer&gt;"| Build
     Build -->|all slices built| Prove[/rite-prove/]
+    Define -.->|resumed / adopted / stalled<br/>code vs intent| Converge[/rite-converge/]
+    Converge -.->|appends remaining slices| Build
     Prove -->|evidence captured| Polish[/rite-polish/]
     Polish -->|polish-report.md| Review[/rite-review/]
     Review -->|review.md<br/>Critical == 0| Seal[/rite-seal/]
@@ -107,8 +109,7 @@ flowchart LR
 The seal fans out **all** relevant reviewers in parallel and reconciles their
 findings, then **decides** GO / NO-GO and stops. It no longer runs git — on GO
 it hands off to `/rite-ship`, which renders the type-GO prompt and runs the
-irreversible commit · push · tag · archive. The advisory `/20` score has been
-removed — the gate is severity + acceptance + drift.
+irreversible commit · push · tag · archive. The old advisory score has been removed — the gate is severity + acceptance + drift.
 
 ```mermaid
 flowchart TB
@@ -149,41 +150,43 @@ flowchart TB
     class VV artifact
 ```
 
-## 5. `devrites-debug-recovery` six-phase loop
+## 5. `devrites-debug-recovery` seven-step loop
 
 Failure recovery — the loop construction in Phase 1 is the load-bearing piece.
 
 ```mermaid
 flowchart LR
-    F([failing test /<br/>build / runtime]) --> L1[Phase 1<br/>Build the loop]
-    L1 -->|fast deterministic signal| R[Phase 2<br/>Reproduce]
-    R -->|exact error text| H[Phase 3<br/>Ranked hypotheses 3-5]
-    H -->|show user before testing| I[Phase 4<br/>Instrument]
-    I -->|change one variable| Fix[Phase 5<br/>Fix + regression test]
-    Fix --> C[Phase 6<br/>Cleanup + classify]
+    F([failing test /<br/>build / runtime]) --> L1[Step 1<br/>Build the loop]
+    L1 -->|fast deterministic signal| R[Step 2<br/>Reproduce]
+    R -->|exact error text| H[Step 3<br/>Ranked hypotheses 3-5]
+    H --> T[Step 4<br/>Trace when ambiguous]
+    T -->|discriminating probe| I[Step 5<br/>Instrument]
+    I -->|change one variable| Fix[Step 6<br/>Fix + regression test]
+    Fix --> C[Step 7<br/>Cleanup + classify]
     L1 -.->|can't build loop| Ask([STOP — ask user])
 
     classDef phase fill:#1f2937,stroke:#60a5fa,color:#f9fafb
     classDef stop fill:#7f1d1d,stroke:#f87171,color:#fee2e2
-    class L1,R,H,I,Fix,C phase
+    class L1,R,H,T,I,Fix,C phase
     class Ask stop
 ```
 
-Each phase's detail lives in a separate reference file under
+Each step's detail lives in a separate reference file under
 `pack/.claude/skills/devrites-debug-recovery/reference/` so the SKILL.md body
 stays small.
 
 ## 6. Engineering-rules carrier
 
-Each `rite-*` skill Reads `.claude/rules/core.md` (the always-on subset) as
-its first step (step 0); the other rule files load on demand. Per-phase
+Workspace-operating lifecycle skills read
+`.claude/skills/devrites-lib/reference/standards/core.md` in step 0; compact utilities
+keep their narrower contract local. The other rule files load on demand. Per-phase
 skills pull additional rule files via plain `Read` as their workflow
 demands. No carrier skill, no session-start autoload.
 
 ```mermaid
 flowchart TD
-    R[rite-* skill<br/>step 0] -->|always-on| Core[.claude/rules/core.md]
-    R -->|on demand index| Idx[(.claude/rules/README.md<br/>19 specialist rule files)]
+    R[rite-* skill<br/>step 0] -->|always-on| Core[.claude/skills/devrites-lib/reference/standards/core.md]
+    R -->|on demand index| Idx[(.claude/skills/devrites-lib/reference/standards/README.md<br/>on-demand rule files)]
     Idx --> CS[coding-style.md]
     Idx --> EH[error-handling.md]
     Idx --> T[testing.md]
@@ -282,7 +285,7 @@ erDiagram
 
 The exact list of files per workspace and what each holds is in
 [`usage.md`](usage.md#the-workspace). The full pause/resume contract is in
-[`pack/.claude/rules/afk-hitl.md`](../pack/.claude/rules/afk-hitl.md).
+[`pack/.claude/skills/devrites-lib/reference/standards/afk-hitl.md`](../pack/.claude/skills/devrites-lib/reference/standards/afk-hitl.md).
 
 ## 8. Public vs internal namespace
 

package/docs/harness-compliance.md

@@ -0,0 +1,45 @@
+# Harness adapter compliance
+
+DevRites drives more than one agent runtime from a single `devrites-engine`
+binary, but the runtimes do not expose identical enforcement surfaces. This page
+states — per surface — whether each supported harness enforces it natively,
+through an adapter, or only by instruction the model may ignore. It is the honest
+answer to "does DevRites work the same on Codex as on Claude Code?"
+
+Host support is enumerated in `engine/internal/harness/harness.go`, with the
+frozen capability matrix in `compliance.go`. New hosts must pass
+[`porting-to-a-new-harness.md`](porting-to-a-new-harness.md), including the
+React todo-list routing transcript, before they are listed here.
+
+The table below is **generated**. Its tiers describe whether the host exposes and wires the
+event surface; they do not by themselves mean that every hook blocks. `a1-guard`,
+`reviewer-readonly`, `wright-scope`, and `stop-gate` are observe-only by default and become
+blocking only when the documented strict-enforcement environment switch is enabled.
+
+The single source of truth is the frozen matrix
+in `engine/internal/harness/compliance.go`; regenerate this block with:
+
+```sh
+devrites-engine harness-matrix          # print the block
+```
+
+CI runs `devrites-engine harness-matrix --check docs/harness-compliance.md`, so
+the table and the code can never silently drift apart.
+
+<!-- BEGIN harness-matrix (generated by `devrites-engine harness-matrix`) -->
+
+| Surface | Claude Code | Codex | Phase impact | Fallback | Doctor check | Confidence | Notes |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| SessionStart orientation | Native | Native | all phases | manual preamble/snapshot | yes | high | Both wire the orient hook; identical additionalContext envelope. |
+| PreToolUse policy (allow, a1-guard, reviewer-readonly, wright-scope) | Conditional | Conditional | build/review safety | observe-only findings + human review | yes | high | Both deliver the event, but these policies are non-blocking by default; DEVRITES_HOOK_PROFILE=strict enables every guard, or each guard can be enabled through its documented specific variable. |
+| PostToolUse sentinel (redwatch) | Native | Native | prove/build rest points | manual red/green check | yes | high | Fail-on-red sentinel wired on both. |
+| Stop gate | Conditional | Conditional | all rest points | observe-only finding + manual host-specific rite-status | yes | high | Both deliver Stop; stop-gate blocks with DEVRITES_STOP_GATE=enforce or DEVRITES_HOOK_PROFILE=strict. |
+| SubagentStart discipline injection | Native | Native | review/build fan-out | agent file preamble | yes | high | subagent-orient wired on both. |
+| Skill invocation | Native | Adapter-backed | all public rites | explicit file read | yes | high | Claude: native /rite. Codex: $rite over the mirrored .agents/skills tree. |
+| Reviewer subagent dispatch | Native | Instruction-backed | review/seal confidence | labelled inline pass | partial | medium | Codex under-fires embedded spawns (openai/codex#23496); falls back to .codex/agents + a labelled inline pass. |
+| Standards step-0 load | Native | Instruction-backed | all phases | explicit standards read | partial | medium | Claude: skill Reads core.md. Codex: an AGENTS.md directive to read it. |
+| Project activation | Native | Conditional | Codex-only startup | inspect hooks/config, decide trust, then rerun doctor | yes | medium | Codex silently skips every .codex/ layer in an untrusted project; trust remains an operator decision after inspection. |
+
+Tiers: **Native** (the harness exposes and delivers the surface directly; policy notes state whether it blocks) · **Adapter-backed** (supported through a translation shim) · **Instruction-backed** (no runtime surface — rides on a directive the model may under-fire) · **Conditional** (native but gated on an operator precondition).
+
+<!-- END harness-matrix -->

package/docs/orchestration.md

@@ -2,7 +2,7 @@
 
 How DevRites coordinates multiple agents — the patterns it uses, the ones it deliberately avoids,
 and where Claude Code's Agent Teams and worktree isolation fit. The rule that governs this lives in
-[`pack/.claude/rules/agents.md`](../pack/.claude/rules/agents.md); this doc is the map.
+[`pack/.claude/skills/devrites-lib/reference/standards/agents.md`](../pack/.claude/skills/devrites-lib/reference/standards/agents.md); this doc is the map.
 
 ## The model
 
@@ -12,8 +12,10 @@ DevRites separates three roles and never blurs them:
   the gates and the `.devrites/` workspace, dispatches the other agents, and is the *single
   canonical writer* of workspace state.
 - **Reviewers** — fresh-context, **read-only** subagents under `.claude/agents/`. Each gets the
-  workspace path + the diff and returns labelled findings; read-only is enforced at the tool layer
-  (`devrites-reviewer-readonly.sh`), not merely promised.
+  workspace path + the diff and returns labelled findings. The generated host hooks observe this
+  boundary by default; set the documented strict-enforcement environment switch when a blocking
+  tool-layer boundary is required. Without strict mode, the agent contract and reconciliation gate
+  remain part of the control, rather than a fail-closed sandbox guarantee.
 - **Executor** — `devrites-slice-wright`, the one **write-capable** agent. It implements a single
   fully-specified slice in a fresh context and returns code + tests; it never writes the `.devrites/`
   bookkeeping (the orchestrator does).
@@ -75,7 +77,7 @@ Two Claude Code capabilities sit adjacent to DevRites' model; the stance on each
 
 ## See also
 
-- [`pack/.claude/rules/agents.md`](../pack/.claude/rules/agents.md) — the reviewer / executor roster
+- [`pack/.claude/skills/devrites-lib/reference/standards/agents.md`](../pack/.claude/skills/devrites-lib/reference/standards/agents.md) — the reviewer / executor roster
   and the when-to-fan-out rules.
 - [`architecture.md`](architecture.md) — the full layer model.
 - [`flow.md`](flow.md) — phase-by-phase flow and the public/internal namespace.

package/docs/porting-to-a-new-harness.md

@@ -0,0 +1,27 @@
+# Porting DevRites to a new harness
+
+DevRites is distributed through `npx devrites` and installs project-local artifacts. Do not add a harness through a Claude/Codex plugin or marketplace path.
+
+Before adding a host, add its thin adapter to `engine/internal/harness/harness.go`,
+update the frozen matrix in `compliance.go`, and prove the host can run DevRites
+without per-session opt-in.
+
+## Hard acceptance test
+
+In a clean trusted project, ask:
+
+> Let’s make a react todo list.
+
+The harness must invoke DevRites and route to `/rite-spec` (or the host's explicit DevRites spec workflow) before writing app code. Attach the transcript to the PR.
+
+## Port checklist
+
+- Skill discovery path is project-local and installed by `npx devrites`.
+- Session/project orientation runs automatically at startup/compact/resume, or the missing surface is recorded in `docs/harness-compliance.md`.
+- `devrites-engine` hooks/gates are wired, or each degraded gate has an honest fallback and confidence label.
+- Subagent support is mapped; if unavailable, reviewers/wrights use the documented inline fallback and label it.
+- Install, update, and uninstall paths stay project-local; no global writes.
+- Generated artifacts and `docs/harness-compliance.md` are updated from the same source of truth.
+- Routing eval includes the React todo-list acceptance prompt.
+
+Skip badge-chasing: add a host only when a real user will exercise it and the acceptance transcript passes.