devrites 2.6.1 → 3.0.1

package/pack/.claude/skills/rite-build/reference/one-slice-cycle.md

@@ -19,6 +19,8 @@ DISPATCH  → hand the slice contract to devrites-slice-wright (fresh context).
 (DOUBT)   → orchestrator, on return: devrites-doubt each non-trivial decision the wright stood up
 PROVE     → orchestrator: fail-on-red check on the wright's gates; browser proof for UI
 RECORD    → orchestrator: state.md, evidence.md, touched-files.md (the canonical writer)
+(CHECKPOINT) → orchestrator: if .devrites/CHECKPOINT is set, commit the proven slice
+            local-only as WIP(<slug>) with a [devrites-context] body → survives a crash (checkpoint.md)
 STOP      → report + recommend next; do not start slice N+1
 ```
 

package/pack/.claude/skills/rite-build/reference/output.md

@@ -0,0 +1,41 @@
+# rite-build output
+
+This is the normative output contract for `/rite-build`. `../SKILL.md` points
+here so the root skill can stay focused without weakening response shape.
+
+Run `devrites-engine progress` first. It prints the deterministic header, slice
+meter, and flow ribbon. Put the compact fact lines below it using the shared
+completion reply contract
+([`devrites-lib/reference/reply-contract.md`](../../devrites-lib/reference/reply-contract.md)).
+
+**Slice built; slices remain:**
+```text
+Done: built slice <n> — <name>.
+Changed: <files touched>; state.md, touched-files.md, evidence.md
+Evidence: acceptance met; tests <cmd -> pass>; browser <summary | n/a>; drift <none|handled>
+Open: <none | blockers | questions>
+Next: /rite-build
+Record: .devrites/work/<slug>/evidence.md
+↻ Hygiene: /clear between slices; /rite-handoff if away > a few hours
+```
+
+**Slice built; all slices built:**
+```text
+Done: built slice <n> — <name>; all slices built.
+Changed: <files touched>; state.md, touched-files.md, evidence.md
+Evidence: acceptance met; tests <cmd -> pass>; browser <summary | n/a>; drift <none|handled>
+Open: <none | blockers | questions>
+Next: /rite-prove
+Record: .devrites/work/<slug>/evidence.md
+↻ Hygiene: /clear before /rite-prove; /rite-handoff if away > a few hours
+```
+
+For awaiting-human or stopped states, use the typed templates from the reply contract.
+Keep fact lines terse. The meter and ribbon carry progress; don't duplicate them in
+prose.
+
+For a **forged slice**, the `Built` line names the competition and points at the record, e.g.
+`Done: built slice 3 — csv-streaming (forged: 3 candidates, winner B).` and
+`Record: .devrites/work/<slug>/forge-report.md`.
+
+**DO NOT continue to the next slice automatically** — even at `✅ ALL BUILT`, `/rite-prove` is the user's call.

package/pack/.claude/skills/rite-build/reference/phase-contract.md

@@ -0,0 +1,258 @@
+# rite-build phase contract
+
+See also [`one-slice-cycle.md`](one-slice-cycle.md).
+
+## Execution spine
+
+Run the engine gates at these moments:
+
+```bash
+devrites-engine preamble
+devrites-engine snapshot
+devrites-engine build-readiness; echo "readiness rc=$?"
+
+devrites-engine reconcile snapshot
+devrites-engine stuck log "$(cat .devrites/ACTIVE 2>/dev/null)" dispatch "<slice id>"
+
+devrites-engine footprint log <slug> doubt "<decision id>"
+
+devrites-engine reconcile check; echo "reconcile rc=$?"
+devrites-engine test-integrity; echo "test-integrity rc=$?"
+devrites-engine package-existence; echo "package-existence rc=$?"
+
+devrites-engine conventions contradict --key <key> --slug <slug> \
+  --evidence "<what the live code does>" --drift-file .devrites/work/<slug>/drift.md
+devrites-engine footprint log <slug> wright "<slice id>"
+devrites-engine tick-afk <state.md path>
+
+devrites-engine progress
+```
+
+Conditional calls still obey the detailed rules below: doubt logging runs for
+each stood decision; convention contradiction runs only when the wright reports
+or exposes a contradiction; `tick-afk` runs only under AFK; forge follows
+[`forge.md`](forge.md) and still returns to the same doubt, record, and stop
+gates.
+
+> **Running the gate helpers.** Each gated `bash` block calls the installed engine
+> directly: `devrites-engine <command> [args]`. It **propagates its exit code**,
+> so the `rc=$?` checks below still hold; host hooks fail open when the binary is absent,
+> but phase gates should treat a missing engine as a setup problem.
+
+0. **Rules + AFK + readiness check.** Read `.claude/skills/devrites-lib/reference/standards/core.md` first. Then **run the
+   shared orientation preamble** — it prints `state.md`, the artifacts present, the run
+   mode (HITL/AFK), and the open-question tally by gate, deterministically:
+   ```bash
+   devrites-engine preamble
+   devrites-engine snapshot
+   ```
+   Treat the snapshot as the canonical machine-readable status; if you need to tell the
+   user the next command, use `nextCommands.claude` in Claude Code or `nextCommands.codex`
+   in Codex. Then **run the readiness gate** — it enforces the step-0 stop conditions by exit code,
+   not by memory:
+   ```bash
+   devrites-engine build-readiness; echo "readiness rc=$?"
+   ```
+   A non-zero `rc` is a hard STOP: `2` → `/rite-define` (plan not approved), `3` →
+   `/rite-resolve` (awaiting human), `4` → `/rite-plan` (blocked). The prose below is the
+   same gate for installs without the script.
+   Orient from its digest. If `Status == awaiting_human` → **STOP**, tell the user to run
+   `/rite-resolve <qid> "<answer>"`. If `state.md` has no `Plan approved: <iso>` field
+   → **STOP**, tell the user the plan isn't approved yet (`/rite-define` writes it when
+   the human confirms). If `.devrites/AFK` is present, re-derive the remaining AFK budget
+   from `state.md`'s `AFK slices remaining: <n>` field (initialized from `.devrites/AFK`
+   `max_slices` on the first AFK build); if it is `0` → **STOP** (forced HITL stop; raise
+   the count in `state.md` or remove the sentinel to continue). See
+   [`afk-discipline.md`](afk-discipline.md).
+1. Read `spec.md`, `plan.md`, `tasks.md`, `assumptions.md`, `drift.md`, and `test-plan.md`
+   if present (the vetted coverage target from `/rite-vet` — the slice's tests come from
+   here when it exists). `state.md` and the open-`questions.md` tally are already in the
+   preamble digest from step 0 — re-read `questions.md` only for the full text of a flagged
+   blocking question.
+   If a **blocking `[NEEDS CLARIFICATION]`** remains or the spec/plan readiness gates
+   don't pass, stop → `/rite-spec` (to resolve) or `/rite-plan` (to repair). Don't build
+   on an unresolved spec.
+2. Select the next pending slice (or the one in `$ARGUMENTS`). **Restate its goal,
+   acceptance criteria, and scope boundary** in one short block. Confirm it's still the
+   right next slice. Write the slice's `Mode` to `state.md` as `Slice mode: <HITL|AFK>` on
+   **every** selection (not only on the HITL pause path); `/rite-resolve` clears or updates
+   it on resume.
+2a. **HITL gate (pre-action pause).** Read the slice's `Mode`. If `HITL`, surface the
+    checkpoint as a ranked **option set** and resolve it **before** any code lands, per
+    [`checkpoint-protocol.md`](checkpoint-protocol.md). Branch on whether
+    a human is here:
+    - **Human present (interactive — no `.devrites/AFK`) → ask inline via `AskUserQuestion`.**
+      This is the default for an interactive build. Render 2-4 options, the recommended one
+      **first and labelled `(Recommended)`**, each with its dimension-tagged rationale + the
+      trade-off it accepts, plus the `Something else — I'll describe it` escape hatch. The
+      human picks; record the pick to `questions.md` (`answered`) + `decisions.md` (through the
+      `devrites-engine resolve` writer), clear the gate, and **continue to step 3 in place** — do **not**
+      STOP, do **not** route through `/rite-resolve`.
+    - **Human absent / AFK (`.devrites/AFK` present) → auto-pick or persist + STOP.** For a gate
+      in `allow_gates`, auto-pick the recommended option (option 1) and proceed; otherwise
+      append the `questions.md` entry, write the `Awaiting human` block to `state.md`, set
+      `Status: awaiting_human`, fire the `notify:` hook, then **STOP** — resume when the user
+      runs `/rite-resolve <qid> "<answer>"`. `blocking` / `escalating` / irreversible-risk gates
+      always take this stop path, never the AFK auto-pick.
+3. **Snapshot the tree, then dispatch the build core to `devrites-slice-wright`** — one `Task`
+   call, fresh context. **First**, capture the pre-dispatch tree so the reconcile gate (step 6)
+   can prove you never touched source — run this immediately before the `Task` call:
+   ```bash
+   devrites-engine reconcile snapshot
+   ```
+   Then log the dispatch so the stuck-loop detector can catch a slice that keeps being
+   re-dispatched without progress (it pauses the build even under AFK):
+   ```bash
+   devrites-engine stuck log "$(cat .devrites/ACTIVE 2>/dev/null)" dispatch "<slice id>"
+   ```
+   **Forge branch — only if the selected slice is `Forge: yes`.** Instead of the single dispatch
+   below, run the competitive build per [`forge.md`](forge.md): K=2-3 candidate
+   wrights, each in an **isolated git worktree** on the distinct strategy `/rite-vet` named, then a
+   fresh-context [`devrites-forge-judge`](../../../agents/devrites-forge-judge.md) scores them against
+   acceptance + `test-plan.md` + `.devrites/principles.md` + the anti-slop charter, and you land
+   exactly **one** winner's diff in the working tree, graft any cheap runner-up improvement by
+   continuing the winning wright once, and write `forge-report.md`. Forge returns the **same shape**
+   a single wright does (one structured artifact, for the winner), so steps 4-7 (doubt, fail-on-red,
+   reconcile against the winner's claimed set, record, stop) run **unchanged**. If you cannot give
+   the judge an objective scorecard (the slice lacks acceptance / `test-plan.md` coverage) or cannot
+   name two genuinely different strategies, the flag is stale — clear it and build single-path. The
+   single-writer invariant is intact: each candidate owns its own tree, exactly one author's diff
+   lands. Then **stop** here for this slice; the steps below are the default single-path dispatch.
+
+   Then assemble the slice contract and send it per
+   [`wright-dispatch.md`](wright-dispatch.md): the slice goal, acceptance
+   criteria, and **scope boundary**; the paths it may touch (`touched-files.md`); the context
+   paths to read (`spec.md`, `plan.md`, `decisions.md`, `assumptions.md`, `.devrites/principles.md`
+   when present — the binding invariants the slice must honor — plus `test-plan.md`
+   when present — its per-gap test requirements + regression-criticals for this slice are the
+   coverage the wright must write — and `design-brief.md`
+   when the slice touches UI per [`frontend-trigger.md`](frontend-trigger.md)); and the
+   `.claude/skills/devrites-lib/reference/standards/` files in scope. The wright **orients** on the project's idiom (using a
+   code-intelligence index **if available** — `codebase-memory-mcp` first, cross-checked with
+   `codegraph` (`.codegraph/` / `codegraph_*`) + `graphify` (`graphify-out/`), else standard
+   methods (LSP / `Read`/`Grep`/`Glob`); see `.claude/skills/devrites-lib/reference/standards/tooling.md` — for
+   placement/callers/impact), writes the **failing test first** when
+   behaviour changes ([`tdd.md`](tdd.md)), implements the **smallest complete** version in
+   the project's style (applying `devrites-frontend-craft` to `design-brief.md` for UI, and
+   `devrites-source-driven` — with context7 if available — for uncertain framework facts), runs the slice's **targeted tests**
+   (plus typecheck / lint / build where the project has them), and returns a structured artifact
+   — **code + tests only; it does not write the workspace files.** If the slice is UI but no `design-brief.md` exists (e.g. a spec written before
+   shaping), shape it via `devrites-ux-shape` before the wright codes. If the `Task` tool is
+   unavailable, run the wright's discipline **inline** as a flagged fallback (see the reference)
+   — same one-slice cycle, no isolation; in that case write
+   `.devrites/work/<slug>/.reconcile-inline` so the reconcile gate skips (you are legitimately
+   the writer in this fallback).
+4. **Doubt the decisions it stood up.** For each entry in the wright's `Decisions stood`
+   (branching, boundary crossing, data model, auth, public API, migration, user-flow change,
+   "this is safe/scales") apply `devrites-doubt` **before accepting the slice** — the writer
+   doesn't grade its own decisions. Each `devrites-doubt` invocation **dispatches the
+   `devrites-doubt-reviewer` subagent** (doing the adversarial pass inline is the writer grading
+   itself — the thing this step exists to forbid). **Completion criterion (checkable):** step 4
+   is done only when **every** `Decisions stood` entry carries a recorded `devrites-doubt`
+   verdict — `accept`, or `reject` + the required changes — in `decisions.md` (accepted
+   trade-offs) / `questions.md` (open gates). A `Decisions stood` entry with **no verdict on
+   record** means doubt did not run for it: **do not enter step 5 and do not mark the slice
+   `built`.** Log each dispatch so the seal can prove doubt ran (the footprint already counts a
+   `doubt` kind):
+   ```bash
+   devrites-engine footprint log <slug> doubt "<decision id>"
+   ```
+   The doubt loop honours `.devrites/AFK` (see its AFK exception): findings below the slice's gate ceiling become advisory entries in `questions.md`;
+   destructive / auth / public-API concerns always pause regardless. A non-empty `Escalation` in
+   the artifact is handled here too: irreversible-risk / blockers → blocking question + set
+   `Status: awaiting_human`; a scope-changing answer → `/rite-plan repair` (Spec Drift Guard),
+   never silently into the slice. **If an irreversible-risk item shows up under the wright's
+   `Decisions stood` rather than `Escalation`**, treat that misclassification as itself a
+   blocking protocol violation — pause and re-dispatch with the item flagged out-of-bounds, do
+   **not** doubt-and-accept it. (The wright's return is the not-yet-load-bearing moment — the
+   slice isn't `built` or merged yet — so this post-return doubt is still pre-commit.)
+   **Principle check (same standing):** a wright return that breaks a declared principle
+   (reported in its `Principles` field, or that you detect against `.devrites/principles.md`) is
+   handled here like an irreversible-risk item — block, route to a human-approved scoped
+   exception in the register or stop; never doubt-and-accept a principle violation into the slice.
+5. **Fail-on-red.** If the wright's `Gates` were red (targeted tests / types / lint) or it
+   couldn't verify: do **not** mark the slice `built`, and **do not fix the code yourself**.
+   First remedy — **continue the same wright once** (`SendMessage` to it, carrying the failing
+   gate + its real output) so it fixes in its own context. This retry is for **objective
+   failures only** — red gate / type / lint / missing test coverage / UI browser-proof fail —
+   never a contested decision (that routes to `/rite-plan repair`). **Still red after the one
+   retry** → escalate: AFK → append a blocking question to `questions.md` (gate=blocking,
+   slice's SLA) + set `Status: awaiting_human`; HITL → pause as a blocking gate. Either way,
+   `Next step: /rite-plan unblock` until resolved.
+6. **Record — you are the canonical writer.** **First, run the reconcile gate (A1):** write the
+   wright's reported `Files changed` paths (one per line) to
+   `.devrites/work/<slug>/.reconcile-claimed` (or the active legacy
+   `.devrites/features/<slug>/` workspace during migration), then:
+   ```bash
+   devrites-engine reconcile check; echo "reconcile rc=$?"
+   ```
+   **Exit 5 → hard STOP:** a source file changed outside the wright's claimed set — code was
+   edited by something other than the wright (A1 breach). Revert it and re-dispatch the wright;
+   do **not** mark the slice `built`.
+
+   **Then run the test-integrity gate (anti-reward-hacking)** — prove the slice didn't reach
+   green by weakening its tests:
+   ```bash
+   devrites-engine test-integrity; echo "test-integrity rc=$?"
+   ```
+   **Exit 3 → hard STOP:** a test was deleted, skipped, or de-asserted since the slice base — the
+   slice went green by weakening its tests, a Critical protocol violation. Revert the weakening and
+   re-dispatch the wright; do **not** mark the slice `built`.
+
+   **Then run the package-existence gate (anti-hallucination)** — every new third-party import must
+   be declared in a project manifest, not just imported:
+   ```bash
+   devrites-engine package-existence; echo "package-existence rc=$?"
+   ```
+   **Exit 3 → STOP:** an imported package is not declared in any manifest (`package.json`, `go.mod`,
+   `requirements.txt`, `pyproject.toml`, `Pipfile`, `Cargo.toml`) — the classic shape of a
+   hallucinated or typo-squatted dependency. Confirm the name on the registry and declare it via the
+   package manager, or remove the import; do **not** mark the slice `built`. The gate is deterministic
+   and fail-open (not a git repo / no manifest / stdlib-only import → rc 0).
+
+   Then, from the wright's artifact, update `state.md`,
+   `evidence.md`, `touched-files.md` (and `browser-evidence.md` for UI). Add a `## Review trail`
+   to `touched-files.md`: group the slice's important `path:line` stops by concern (design intent,
+   not file order), 1–5 concerns, each stop under 15 words. This is for a later human walkthrough;
+   keep it factual and skip invented rationale. **Persist every
+   `Decisions stood` entry from the wright's artifact to a `## Decisions stood` section in
+   `decisions.md`, one line each ending `— doubt: <accept | reject-resolved | MISSING>`** — the
+   verdict from step 4, or `MISSING` if step 4 was skipped for that entry. Write this ledger at
+   record-time **independent of the doubt step**, so a stood decision lands on disk even when it
+   was never doubted: `/rite-seal` cross-checks the ledger, and a `doubt: MISSING` entry is the
+   skipped-doubt finding that would otherwise leave no trace (the per-slice skip the footprint
+   count alone can't catch). If the wright stood no decisions, write `## Decisions stood` with
+   `- none` so the absence is recorded, not assumed. If the wright reported
+   an approach it tried and backed out of, record it under a `## Dead ends` section in
+   `decisions.md` so a retry or the next agent doesn't repeat it.
+   **If the wright's `Conventions` field reports a contradiction** (the live code now
+   disagrees with a held convention), record the drift — you own this bookkeeping:
+   ```bash
+   devrites-engine conventions contradict --key <key> --slug <slug> \
+     --evidence "<what the live code does>" --drift-file .devrites/work/<slug>/drift.md
+   ```
+   It lowers the convention's band (or retires it) and appends a `convention-drift` entry to
+   `drift.md`. The ledger is **promoted only at `/rite-seal` on GO** — build only records
+   contradictions, never new conventions. **Evidence is the
+   wright's real command output, not its say-so.** Capture per
+   [`evidence-standard.md`](evidence-standard.md). Append a footprint record for this
+   slice's wright dispatch (deterministic run-weight bookkeeping the seal reports):
+   ```bash
+   devrites-engine footprint log <slug> wright "<slice id>"
+   ```
+   If `.devrites/AFK` is present, decrement
+   the budget by running `devrites-engine tick-afk <state.md path>` —
+   it decrements `state.md`'s `AFK slices remaining` field, prints the new value, and exits `3`
+   when it hits 0. **Exit 3 → STOP** (forced HITL stop; the cap is exhausted). Never rewrite
+   `.devrites/AFK` `max_slices` in place — it is read-only initial budget.
+7. **STOP.** Render the progress footer, then report and recommend the next step. Run the
+   shared footer (mirror of the step-0 preamble) so the slice meter + flow ribbon are
+   deterministic, not model-typed:
+   ```bash
+   devrites-engine progress
+   ```
+   It reads `state.md` (already updated in step 6), so the meter reflects the slice you
+   just built. **When every slice is built** (`✅ ALL BUILT`) say so explicitly — the build
+   phase is complete, the next phase is `/rite-prove` — don't leave completion implicit.
+
+> **Mid-flight discipline.** The wright (or you, in the inline fallback) must resist doing two slices, skipping TDD, adding a defensive check, or wandering outside `touched-files.md`; you must resist skipping the post-return `devrites-doubt` because the wright "seems confident" — see [`anti-patterns.md`](anti-patterns.md). Load it the moment you reach for the excuse.

package/pack/.claude/skills/rite-build/reference/wright-dispatch.md

@@ -34,13 +34,14 @@ Workspace: .devrites/work/<slug>/
 Slice: <id — name>
 Goal: <one or two sentences>
 Acceptance criteria: <the slice's criteria, verbatim>
+UI visual acceptance: <if UI — state × viewport × input + target R-id/brief rule, verbatim from tasks.md>
 Scope boundary: <what it WILL and will NOT touch>
 Mode: <HITL | AFK>   (+ AFK budget note if a cap is set)
 
 Targets (stay inside these — from touched-files.md): <paths>
 Interfaces / signatures to match: <if any>
 Read yourself: spec.md, plan.md, decisions.md, assumptions.md, rite-polish/reference/anti-ai-slop.md<, design-brief.md if UI>
-Rules in scope (.claude/rules/): coding-style, error-handling, testing, patterns<, security if input/auth/data><, performance if hot path / query / large payload>
+Rules in scope (.claude/skills/devrites-lib/reference/standards/): coding-style, error-handling, testing, patterns<, security if input/auth/data><, performance if hot path / query / large payload>
 Test completeness: write ≥1 asserting test for EVERY interactive element + user flow in this
   slice's test-plan.md interaction inventory, each at the right level (fields/elements →
   unit/component; critical journeys → one E2E; never one-per-field). No element ships
@@ -48,7 +49,8 @@ Test completeness: write ≥1 asserting test for EVERY interactive element + use
   element/flow list from the slice's own UI surface and cover it the same way.
 
 Apply your documented discipline (orient → RED → implement smallest complete → verify →
-return). Frontend slice → build to design-brief.md with devrites-frontend-craft. Uncertain
+return). Frontend slice → build to design-brief.md with devrites-frontend-craft and close
+the slice's visual-acceptance deltas before returning. Uncertain
 framework fact → verify at the source. Code + tests only — do NOT write the workspace
 bookkeeping files; return that data. Return your structured artifact, not your transcript.
 ```
@@ -63,8 +65,7 @@ Rules:
 ## On return — the orchestrator's job (don't delegate these)
 **You never edit source here.** The wright is the only writer of code + tests; you write only
 `.devrites/` bookkeeping. Every remedy below is **continue the same wright once** or **stop +
-escalate** — never an inline patch. You snapshotted the tree before dispatch (`reconcile.sh
-snapshot`); the reconcile check in step 4 proves no source changed outside the wright's claimed
+escalate** — never an inline patch. You snapshotted the tree before dispatch (`devrites-engine reconcile snapshot`); the reconcile check in step 4 proves no source changed outside the wright's claimed
 set.
 
 1. **Doubt the surfaced decisions.** For each entry in the wright's `Decisions stood`, apply
@@ -87,16 +88,16 @@ set.
    **no asserting test** has the same standing as red: an unverified-element gap blocks the
    slice (don't mark it built). Continue the same wright to cover it, or record a blocker.
 4. **Reconcile, then record.** First prove A1 held: write the wright's `Files changed` paths
-   (one per line) to `.devrites/work/<slug>/.reconcile-claimed` and run `reconcile.sh check`.
+   (one per line) to `.devrites/work/<slug>/.reconcile-claimed` and run `devrites-engine reconcile check`.
    **Exit 5 → STOP** — a source file changed outside the wright's claimed set (A1 breach); revert
    it and re-dispatch, don't mark the slice built. Then persist the wright's artifact to
    `state.md`, `evidence.md`, `touched-files.md` (and `browser-evidence.md` for UI) per
    [`evidence-standard.md`](evidence-standard.md). Evidence is the wright's real command output,
-   not its say-so. **Persist every `Decisions stood` entry to a `## Decisions stood` section in
+   not its say-so. Add a concern-ordered `## Review trail` to `touched-files.md` from the wright's changed paths and summary so a human can review by design intent instead of file order. **Persist every `Decisions stood` entry to a `## Decisions stood` section in
    `decisions.md`, one line each ending `— doubt: <accept | reject-resolved | MISSING>`** —
    independent of the doubt step (step 1 above), so a skipped decision still lands on record for
    the seal's doubt-coverage cross-check (`- none` when the wright stood nothing). Then tick AFK if
-   `.devrites/AFK` is present (`tick-afk.sh`; exit 3 → STOP).
+   `.devrites/AFK` is present (`devrites-engine tick-afk`; exit 3 → STOP).
 
 ## Forge — competing candidates (the deliberate exception)
 
@@ -126,10 +127,10 @@ fallback in
 [`../../devrites-lib/reference/parallel-dispatch.md`](../../devrites-lib/reference/parallel-dispatch.md).
 
 ## Optional pre-block hook (defense in depth)
-`reconcile.sh` is the **post-hoc** gate — it always runs and catches an A1 breach at record time.
-A companion **pre-block** hook, `.claude/hooks/devrites-a1-guard.sh` (a `PreToolUse` matcher on
+`devrites-engine reconcile` is the **post-hoc** gate — it always runs and catches an A1 breach at record time.
+A companion **pre-block** hook, `devrites-engine hook a1-guard` (a `PreToolUse` matcher on
 `Edit|Write|MultiEdit`), stops the breach *before* the write lands. It is armed only inside the
-mid-build window (between `reconcile.sh snapshot` and a clean `check`, keyed on `.reconcile-base`),
+mid-build window (between `devrites-engine reconcile snapshot` and a clean `check`, keyed on `.reconcile-base`),
 allows the wright (subagent calls carry `agent_id`), the inline fallback (`.reconcile-inline`),
 and any `.devrites/` write — so it never touches `/rite-polish`, `/rite-quick`, or ordinary
 manual edits. It ships **observe-only** (logs would-be blocks to `.a1-guard.log`, never blocks);

package/pack/.claude/skills/rite-converge/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: rite-converge
+description: Converge intent and live code. Use when resuming a half-built feature, after `/rite-adopt` drift, or the user asks "what's left to build". Not for initial planning.
+argument-hint: "[feature-slug]"
+user-invocable: true
+---
+
+# /rite-converge — make the code and the intent converge
+
+Read `spec.md` + `plan.md` + `tasks.md` as the **sole source of intent** (with
+`.devrites/principles.md` as governing constraints), assess what the **live codebase**
+actually implements, and **append every unmet piece as a new traceable `SLICE-###`** at the
+bottom of `tasks.md` so `/rite-build` can finish it. The recovery bridge for work that fell
+out of sync with its plan: a half-built feature picked up cold, a `/rite-adopt`'d codebase
+that drifted from its derived spec, or a build that stalled mid-slice. **Read the active
+workspace first**; if there's no `spec.md`/`plan.md`/`tasks.md`, tell the user which
+prerequisite skill to run.
+
+> **Not a diff tool.** `/rite-converge` assesses the **present state** of the code against
+> intent — no git, no branch comparison, no history. "What does this codebase do *now* vs
+> what the artifacts asked for" — not "what changed since commit X". For a change-scoped
+> review use `/rite-review`; to prove a finished feature use `/rite-prove`.
+
+## Rules consulted (read on demand from `.claude/skills/devrites-lib/reference/standards/`)
+Pull on demand:
+- `principles.md` — the project invariants (`.devrites/principles.md`); code that violates a
+  MUST principle is the highest-severity gap and produces a remediation slice.
+- `spec-grammar.md` — buildable acceptance criteria vs `## Success metrics` (outcome KPIs the
+  code can't make true and this pass never enqueues); structured `### Requirement:` /
+  `#### Scenario:` blocks, each scenario one behavior to check as built / partial / absent.
+- `tooling.md` — prefer a code-intelligence index (codebase-memory-mcp → codegraph → graphify,
+  else LSP / Read/Grep/Glob) to read the live code, not assumptions.
+- `testing.md` — a criterion with code but no covering test is *partial*, not done.
+
+## Operating rules
+- **APPEND-ONLY, never rewrite.** The only write to `tasks.md` is **appending** new
+  `SLICE-###` entries. Never rewrite, renumber, reorder, or delete an existing slice
+  (including slices a prior convergence appended). Never edit `spec.md` or `plan.md`. Never
+  touch application code — completing the appended slices is `/rite-build`'s job, not this
+  skill's.
+- **Clean means byte-for-byte unchanged.** When the code already satisfies everything, leave
+  `tasks.md` untouched — no empty convergence header — and report a clean result. Recommend
+  `/rite-prove`.
+- **Intent is the artifacts, not your memory.** The spec/plan/tasks (+ principles) are the
+  contract. If assessing reveals the *spec* is wrong (the code is right and the requirement is
+  stale), that's **Spec Drift** — stop and route it through the Spec Drift Guard
+  (`rite-build/reference/spec-drift-guard.md`) + a recorded decision; never paper over a spec
+  bug by appending a task that "fixes" the code to a wrong requirement.
+- **Partial is not done.** Code that exists but is untested, half-wired, or covers only the
+  happy path is an unmet gap — enqueue the remainder, don't round it up.
+- **Principles are non-negotiable.** A live violation of a declared invariant with no recorded
+  exception is the top-severity gap, walked first. Absent/empty principles file → none declared
+  → skip the check gracefully, never block for its absence.
+
+## Workflow
+0. **Read `.claude/skills/devrites-lib/reference/standards/core.md`** first (the always-on
+   operating rules), then run `devrites-engine preamble` for deterministic workspace orientation.
+1. **Confirm the gate.** Require `spec.md` + `plan.md` + `tasks.md` in the active workspace. If
+   any is missing, **STOP** and name the prerequisite (`/rite-spec` for a missing spec,
+   `/rite-define` for a missing plan/tasks, `/rite-adopt` to onboard existing code). Do not
+   produce partial output.
+2. **Load intent** — [`reference/convergence-assessment.md`](reference/convergence-assessment.md).
+   From `spec.md`: buildable `AC-###` / `### Requirement:` scenarios (skip `## Success metrics`);
+   from `plan.md`: architecture decisions + named touch-points (files/components the plan says
+   get built); from `tasks.md`: existing slices + their `Satisfies:`; from
+   `.devrites/principles.md`: the invariants.
+   **Completion:** every buildable criterion, touch-point, slice output, and principle is in the assessment inventory.
+3. **Run the mechanical backbone**, then read the code. `devrites-engine analyze` gives coverage +
+   consistency; `devrites-engine coverage` gives the AC→slice→proven matrix. They catch *unmapped*
+   criteria; they do **not** see whether mapped code is actually built and correct — for that,
+   read the live code (code-intelligence index per `tooling.md`).
+   ```bash
+   S="$(cat .devrites/ACTIVE 2>/dev/null)"
+   devrites-engine analyze "$S"; echo "analyze rc=$?"
+   devrites-engine coverage "$S" > /dev/null; echo "coverage rc=$?"
+   ```
+4. **Assess each unit as built / partial / absent** against the live code (the rubric is in
+   [`reference/convergence-assessment.md`](reference/convergence-assessment.md)): every
+   acceptance criterion / scenario, every plan touch-point, and every existing slice's stated
+   Produces. A principle violated in the current code is its own top-severity gap.
+   **Completion:** every inventory unit is classified once with live-code evidence.
+5. **Enqueue the remainder as new slices.** For each *partial* or *absent* unit, append a
+   `## SLICE-###` (continue the numbering after the highest existing id) in the `rite-define`
+   slice grammar, each with a `Satisfies:` line tracing to the AC/REQ it closes and a
+   `Convergence: <iso>` marker line. Dependency-order them after the existing slices; a
+   principle-remediation slice sorts first. **If every unit is built → append nothing.**
+   **Completion:** every partial/absent unit has one traceable appended slice, or the file is byte-for-byte unchanged.
+6. **Write append-only + bookkeeping.** Append the slice batch to `tasks.md` (nothing else in
+   that file changes); refresh `traceability.md` (`devrites-engine coverage` → new rows for the
+   appended slices); update `state.md` (`Phase: converge`, `Next step: /rite-build`; or, when
+   nothing was unmet, `Next step: /rite-prove`). Append `decisions.md` for any material call.
+7. **STOP.** Report units assessed, built / partial / absent counts, slices appended, and any
+   principle violation found; recommend `/rite-build` (or `/rite-prove` if the code already
+   converged).
+
+## Appended slice format
+Use the complete
+[`canonical slice grammar`](../devrites-lib/reference/workspace-artifact-schema.md#canonical-slice-grammar)
+with one added `Convergence:` field after `Satisfies:`:
+```markdown
+<!-- Convergence 2026-07-07: slices below appended by /rite-converge — live code assessed against intent. -->
+## SLICE-014 <name of the unmet capability>
+Satisfies: AC-007            # the criterion / scenario this closes
+Convergence: 2026-07-07      # marks this as a convergence-appended slice, not an original
+<all remaining canonical slice fields>
+```
+
+> **Mid-flight discipline.** When tempted to rewrite an existing slice instead of appending, to
+> edit the code directly "while you're in there", to mark a happy-path-only implementation as
+> built, or to enqueue a task that bends the code to a spec you suspect is wrong — see
+> [`reference/anti-patterns.md`](reference/anti-patterns.md). Load it the moment you reach for
+> the excuse.
+
+## Output
+
+**Progress first** — run `devrites-engine progress`, then use the shared completion reply contract
+([`devrites-lib/reference/reply-contract.md`](../devrites-lib/reference/reply-contract.md)).
+Default success shape:
+```
+Done: convergence assessed for <slug>; <n> slices appended.
+Changed: tasks.md <appended|unchanged>, traceability.md, state.md
+Evidence: units <built>/<total> built · <partial> partial · <absent> absent · principle violations 0
+Open: none
+Next: /rite-build
+Record: .devrites/work/<slug>/tasks.md
+↻ Hygiene: /clear before /rite-build
+```
+When nothing was unmet, render the same green form with `Next: /rite-prove`.
+If spec drift or another blocker remains, use the shared `Stopped / blocked` form
+and route `Fix:` to `/rite-plan`; do not recommend `/rite-build`.
+**DO NOT write application code, rewrite existing slices, or edit spec.md/plan.md here** — convergence assesses and enqueues; `/rite-build` implements.

package/pack/.claude/skills/rite-converge/reference/anti-patterns.md

@@ -0,0 +1,35 @@
+# /rite-converge anti-patterns
+
+Load the moment you reach for one of these excuses.
+
+## Common rationalizations
+
+- *"I'll just fix this existing slice instead of appending a new one."* — No. The append-only
+  rule is what makes convergence **re-runnable** and its output **auditable**: a reader diffs
+  `tasks.md` and sees exactly what this pass added. Rewriting an existing slice destroys that
+  and can silently drop coverage. Append; never edit an existing `SLICE-###`.
+- *"The gap is tiny — I'll just patch the code while I'm here."* — No. Convergence **assesses
+  and enqueues**; `/rite-build` implements. The moment you edit application code you've skipped
+  the build's slice discipline, tests, and reviewer. Enqueue it, however small.
+- *"It's basically built — I'll call it done."* — Happy-path-only, untested, or half-wired is
+  **partial**, not built (`convergence-assessment.md`). Rounding partial up to built is how a
+  feature ships with the edge cases that were the whole reason for the scenario.
+- *"The code does X, the spec says Y — I'll enqueue a slice to make the code match the spec."* —
+  Only if you're sure the **spec** is right. If the code is right and the requirement is stale,
+  that's **Spec Drift** — route it through the guard, don't launder a spec bug into a code task.
+- *"The spec has no `AC-###` ids, so there's nothing to converge."* — Assess plan touch-points
+  and existing-slice Produces directly against the code; a coverage id is convenient, not
+  required. (And flag the untagged spec so `/rite-spec` can add ids.)
+- *"I'll rewrite the whole tasks.md to be clean while I'm at it."* — That is a **reslice**, and
+  it belongs to `/rite-plan`, not here. Convergence only ever *appends*.
+
+## Red flags in your own output
+
+- An edit to `tasks.md` that touches a line **above** the appended batch → you rewrote history.
+  Revert; append only.
+- Any change to `spec.md`, `plan.md`, or a source file in this pass → out of scope.
+- An appended slice with no `Satisfies:` line → it traces to nothing; either tie it to a
+  criterion/touch-point or it isn't convergence work.
+- A "clean" report that still left a `## Convergence` header or marker in `tasks.md` → clean
+  must be **byte-for-byte unchanged**.
+- Reusing or renumbering an existing `SLICE-###` id → ids are append-only and stable.

package/pack/.claude/skills/rite-converge/reference/convergence-assessment.md

@@ -0,0 +1,61 @@
+# Convergence assessment — built / partial / absent
+
+The rubric `/rite-converge` applies to every unit of intent. Load when running step 2–5.
+
+## The unit set
+
+Assess three kinds of unit against the live code:
+
+1. **Acceptance criteria / scenarios** — each buildable `AC-###` and each `#### Scenario:`
+   (WHEN/THEN) in `spec.md`. `## Success metrics` lines are **not** units — they carry no
+   `AC-###` id, no slice can satisfy them, and this pass never enqueues one (`spec-grammar.md`).
+2. **Plan touch-points** — the files/components/modules `plan.md` says get built or edited, and
+   each existing slice's stated **Produces** (the interface it was meant to expose).
+3. **Principles** — each invariant in `.devrites/principles.md`, checked against the code as it
+   stands.
+
+## The three verdicts
+
+For each unit, decide **built / partial / absent** — and only *partial* and *absent* enqueue a
+slice.
+
+| Verdict | Test | Action |
+|---|---|---|
+| **built** | The behavior exists in the code **and** a test covers it (a criterion with code but no covering test is not built — `testing.md`). | Nothing — do not append. |
+| **partial** | Some of it exists: happy path only, un-wired, untested, a TODO stub, or an edge case from the scenario's WHEN/THEN missing. | Append a slice for the **remainder**, its `Known-Gotchas` naming what's already there so `/rite-build` extends rather than rebuilds. |
+| **absent** | No code implements it. | Append a full slice. |
+
+Read the code to decide — do not infer from the plan. Use the code-intelligence index
+(codebase-memory-mcp → codegraph → graphify, else LSP / grep) so the verdict reflects live
+code, not the artifacts' claims. `devrites-engine analyze` / `devrites-engine coverage` tell you what's
+*mapped*; only reading the code tells you what's *built*.
+
+## Principle violations
+
+A live violation of a declared invariant (secret in logs, money as float, a datastore added
+with no ADR) is the **top-severity** gap regardless of coverage. It sorts **first** in the
+appended batch as a remediation slice, and — because reshaping to honor an invariant can be an
+irreversible-risk change — it pauses for a human even under AFK. Absent/empty principles file →
+none declared → skip, never block.
+
+## Spec drift vs code gap
+
+Before appending a slice, separate the two failure directions:
+
+- **Code gap** — the spec is right, the code falls short. → append a slice. (This skill's job.)
+- **Spec drift** — the code is right, the requirement is stale or wrong. → **do not** append a
+  slice that bends correct code to a wrong spec. Stop, route through the Spec Drift Guard
+  (`rite-build/reference/spec-drift-guard.md`) + a recorded decision, and let `/rite-plan
+  repair` reshape intent. Convergence enqueues work; it never launders a spec bug into a code
+  task.
+
+## Numbering + ordering the appended batch
+
+- **Continue the ids** — the highest existing `SLICE-###` + 1, ascending. Never reuse or
+  renumber an existing id.
+- **Order after the existing slices**, dependency-first among the new ones (`depends_on`);
+  a principle-remediation slice sorts before feature gaps.
+- **Mark each** with `Convergence: <iso>` so a later reader (and `/rite-status`) can tell an
+  original slice from a converged-in one.
+- **Nothing unmet → append nothing.** No batch header, no marker, `tasks.md` byte-for-byte
+  unchanged.