devrites 7.1.1 → 7.2.0

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

@@ -0,0 +1,198 @@
+# Slice-wright dispatch
+
+> Root-only: not inlined in --role bundles.
+
+`/rite-build` gives one bounded task to exact `devrites-slice-wright`.
+Root owns scope/artifacts/inspection; never writes source/tests.
+Wright alone writes; no agents.
+
+## Host gate
+
+Apply [source-writing boundary](../../devrites-lib/reference/standards/agents.md#source-writing-boundary):
+Claude grants only the exact wright `acceptEdits`; Codex uses its workspace root,
+the exact `:workspace` wright, and read-only specialists. Never bypass/substitute
+the wright or recreate an engine bridge.
+
+## Standalone correction
+
+`/rite-quick`, `/rite-dogfood`, `/rite-harness`, and `/rite-pr-feedback` fixes have no `tasks.md`
+slice, so skip Prepare's `check slice`, `context --slice`, and the build `dispatch`
+wave. Give the wright an inline contract: goal, acceptance check, exact
+project-relative paths, and proof command. With an active workspace, `claim add`
+those paths first. On return, compare its file list and `git diff --name-only`
+with the paths; reject any extra path.
+
+## Isolated writer-worktree pilot
+
+Use native isolation only when the current host exposes an explicit named-writer
+worktree plus result reconciliation; separate agent threads or inherited sandboxes do
+not qualify. Codex CLI custom subagents therefore use `same-worktree` unless a future
+supported interface passes this capability gate—never create a manual worktree from the
+read-only root to imitate it. Also require `git rev-parse
+--show-superproject-working-tree` to be empty; resolved git/common dirs; committed,
+clean candidate/index; all inputs at `HEAD`; no other writer; and green cheap isolated
+baseline proof. Otherwise use serial same-worktree dispatch—never stash, commit, or
+discard user work to qualify. Ask host for an explicit current-`HEAD` base when
+supported. Regardless of host defaults, the wright's first command must prove actual `git rev-parse HEAD` equals supplied
+`worktree_base`. Mismatch returns a gap with no write before project reads or baseline proof.
+
+The isolated wright returns one local unpushed `transfer_commit` (contract
+`WIP(<slug>):` subject, no slice id), its `worktree_base`, and exact files.
+That commit is worker-branch transport, not the control-branch checkpoint. Root proves descendant base, exact `git diff --name-only`
+`` `<base>..<transfer>` ``, no `.devrites/**`/submodule/symlink/unrelated delta, unchanged
+source base, and no user-work overwrite. Use only host-native explicit reconciliation;
+never ad hoc copy, cherry-pick, or merge from read-only root. Land on control
+only per [`checkpoint.md`](checkpoint.md).
+
+Conflict, extra/missing commit, moved base, or cleanup failure is `gap`/STOP:
+preserve the worktree and commit. Without explicit reconciliation, use same-worktree serial.
+Parallel isolated-writer worktrees remain forbidden until this serial pilot measures
+transfer, conflict, proof, and review outcomes on both hosts; opt-in `/rite-build --parallel N`
+(2≤N≤10) path-disjoint fan-out is the only sanctioned parallel mode. Same-worktree multi-writer / root-emulated
+worktrees stay forbidden.
+
+## Prepare
+
+1. Run `devrites-engine check slice <slug> <SLICE-ID>` first — it fails a
+   malformed contract (missing goal, empty/invalid Writer allowlist,
+   unresolvable `Satisfies` AC ids, empty proof field) before a wright
+   context is spent; a failure is a gap, not a dispatch. A slice with a
+   `pre-dispatch <SLICE-ID>` preflight row next runs
+   `devrites-engine check preconditions <slug> --slice <SLICE-ID>` before
+   `dispatch open`; non-zero is the same gap. Then derive the
+   smallest exact project-relative source/test path list; reject
+   directories/globs, traversal, symlink escapes, duplicates, and `.devrites/**`.
+   A target composed only of vetted executable workflow artifacts routes to the
+   controlling root under
+   [`workflow-artifacts.md`](../../devrites-lib/reference/standards/workflow-artifacts.md);
+   its rejection here is not a blocker. Vet already closed the slice's write
+   set; re-check only consumers of files earlier slices changed since the
+   readiness binding, and fold a gap through `/rite-plan` before dispatch.
+2. Goal, verbatim acceptance, exclusions, context, `test-plan.md` proof
+   commands, and applicable standards reach the wright through the slice bundle
+   its contract names; only a native-worktree pilot contract adds the exact
+   `WIP(<slug>):` subject (no slice id). Build the wright's read-set with
+   `devrites-engine context --skills-root .dsh/skills <slug> --phase build --role slice-wright --slice <SLICE-ID> --trigger <set>`
+   and hand it the bundle path (over-budget artifacts arrive as anchor indexes;
+   read owning sections live). Evaluate each trigger condition and pass those
+   that fire (TDD slice → `tdd`, AFK run → `afk`, UI work → `frontend`, …).
+   The command prints `unselected=[...]`; an omitted applicable trigger is a gap.
+   For each triggered
+   topology/data/integration standard, add as anchored `--focus` rows only the feature-specific owner/invariant,
+   failure or partial-state case, recovery rule, and required proof from the vetted plan.
+   Do not paste the whole standard or silently omit an applicable risk.
+   Quote, as a `--focus` row, every active `decisions.md` carry-forward constraint whose `Files:`
+   overlap the task paths (or that names no files).
+   A new path requires a new bounded contract; the wright cannot widen the task.
+   The contract lists the slice's `Tests/proof` as writer-safe checks (syntax/type/lint,
+   unit and self-check suites, a narrow smoke of the changed path); `--checks` adds
+   gate IDs. Never forbid them: a blind wright's failures surface a review
+   round later. Artifact-producing, consumptive, or full canonical feature
+   gates stay root-owned, never in `--checks`; when `gates.md` has a `RUN: writer`
+   gate, the checks include `devrites-engine gates precheck <slug> --worktree <path> --slice <SLICE-ID>`
+   (those gates, minus ones only other unbuilt slices own, plus `check windows`;
+   never evidence, root still runs every gate).
+3. Run `devrites-engine check diff-scope <slug> --snapshot` before dispatch so
+   unrelated work remains distinguishable (it fingerprints every dirty path). For an isolated pilot, also record committed base SHA and exact
+   baseline status before asking the host for isolation. **Failing case:** paths that
+   were dirty at that baseline are listed as slice-owned after dispatch.
+
+## Run
+
+Same-worktree (non-isolated) dispatch claims before writing: the `dispatch open`
+below adds `--claim-session <id>`, one `--claim <path>` per task path, and
+`--claim-ttl <minutes>` sized to the write; it runs the
+`claim check --session <id> <task-paths>` test, and a live foreign holder fails the
+open with no wave and no claim and stops the dispatch, per
+[`agents.md`](../../devrites-lib/reference/standards/agents.md). `.devrites/**`
+is never a task path; see [Workflow Artifact admission](../../devrites-lib/reference/standards/workflow-artifacts.md).
+Render the contract with `devrites-engine packet <slug> --wave <wave> --phase build
+--role slice-wright --slice <SLICE-ID> [--checks <G-ID,...>] [--focus <file>]` (it
+writes the linted same-worktree `packets/<wave>.contract.md`; a native-worktree pilot
+writes its own contract with `Isolation`, `worktree_base`, and subject) and hand the wright that text verbatim. Reviewers read
+that file, so `--focus` rows state each defect to fix with its anchor, never a reviewer's verdict,
+count, or pass status ("code review is no-findings" voids the next review). Ask the host
+for the exact writer in fresh context; a repair round on the same slice whose
+returned wright the host can still continue goes to that wright on its existing
+handle instead, so it does not re-read the slice from scratch. Wait, and track it
+through the launch barrier — `devrites-engine dispatch <slug> open --phase build --wave
+<slice-id> --role slice-wright --slice <SLICE-ID> --contract <file>` (it refuses a
+contract that forbids writer-safe checks or names none), then `start` with the host handle
+(the last start seals the wave) and `return` on completion (auto-records dispatch/return metrics). Every 5 wright
+rounds on one slice, `open` blocks for a reslice review. First re-admit each
+finding still driving rounds under the Proportionality rule of
+[agents.md § Result admission](../../devrites-lib/reference/standards/agents.md#result-admission): one without a broken anchor or a reachable trigger becomes a
+Suggestion and drives no further round. Then propose an
+acceptance-preserving split (`root_no_change_analysis` → `FOLD` per
+[acceptance-preserving-reslice](../../devrites-lib/reference/standards/acceptance-preserving-reslice.md);
+open findings move to the new slice owning their paths), or record
+`## <DRIFT-ID> — <SLICE-ID> reslice review` with why no smaller split exists and
+a spec trace of the slice's obligations (hardening no AC/INV/PROH requires moves to
+a sibling slice dependents do not need, still gated before Seal), and
+reopen with `--reslice-review <DRIFT-ID>`. Use
+at most one writer across all linked worktrees for this workspace. Never run two
+writers in one worktree, run isolated and same-worktree writers concurrently, or
+substitute a generic agent. Opt-in `/rite-build --parallel N` fans out only under
+[`parallel-batch.md`](parallel-batch.md).
+
+The `return` that completes the wave releases its claim; `dispatch abandon --release`
+releases it on any other host-confirmed terminal path (a stop, a launch refused with no
+handle, or a timed-out child later confirmed terminal). A `claim add` claim releases
+with `devrites-engine claim release --session <id> --id <claim-id>` on every terminal path:
+successful return, rejected result, stop, or a launch the host refused with no handle. A
+timeout or unknown outcome keeps the claim ([`parallel-dispatch.md`](../../devrites-lib/reference/parallel-dispatch.md#cancellation-and-terminal-reconciliation)).
+TTL is crash recovery, not normal cleanup.
+An `unattributed root edit` exit 3 (root-edit tripwire) routes the path through a wright wave naming it in
+`--claim`, or, given evidence (owner work, gate output, a standalone wright, Polish ADR/`DESIGN.md`),
+`dispatch <slug> attribute --reason <evidence> --path <path>`.
+
+## Inspect and prove
+
+1. Compare the returned file list and `git diff --name-only` with task paths.
+   `devrites-engine check diff-scope <slug> --allow <task-paths> --baseline` is the
+   mechanical subset gate (a step-3 path whose bytes are unchanged is not a
+   violation; a changed one still is) — run it before any reviewer dispatch; a violation
+   restores through the bounded wright without spending review, but only for a
+   path the wright's `files_changed` or diff trace attributes to it. An
+   unattributed extra path that was clean at the step-3 baseline is preserved
+   (never restored), recorded as drift, and stops for the human. **Failing case:**
+   a user edits `README.md` during a same-tree dispatch and the wright reverts it.
+   Reject a result that omits any required key — the bookkeeping arrays count
+   whether empty or filled — or adds a path. Root never widens scope or edits
+   source.
+2. Run `devrites-engine check windows <slug>` on the wright's diff (`--worktree`
+   in the same tree, plus `--since-dispatch <wave>` naming a repair round's wave;
+   `--base <B> --cwd <worktree>` for a parallel transfer commit). Each unwaived hit is repaired through the bounded wright or gets a
+   reasoned `windows.md` row before review; never waive to reach green. Then
+   inspect the test diff for deletion, skipping, focus markers, or loosened
+   assertions. Dedicated test analysis treats weakening as Critical.
+   Confirm a test for a data/integration/topology risk can actually exhibit that risk;
+   mocks that erase it and one-root proof offered for another root are unproven.
+3. Apply [independent Build review](phase-contract.md#independent-build-review)
+   and, in the same window, run only repository proof already approved by
+   `test-plan.md` against the same frozen candidate; neither waits for the
+   other. Human choices return; technical failures follow
+   [the canonical retry contract](../../devrites-lib/reference/standards/afk-hitl.md#retry-cap-no-progress-loops-and-self-resolve).
+   Derive accounting from recorded reproductions, corrections, and decisive rechecks.
+4. After proof, inspect `git diff --name-only` again in case a proof tool changed
+   source; a change rejects that candidate and voids the concurrent review. A
+   repair wright voids both; rerun both on the new candidate.
+   **Do not land on control until review and proof are both green.** Isolated
+   `transfer_commit` stays on the worker branch; same-worktree diffs stay
+   uncommitted. Serial: [`checkpoint.md`](checkpoint.md), then host may remove the
+   worktree. Parallel: `record-green`, then `parallel integrate
+   --slice <id> --apply-to-control`; `parallel cleanup` removes worktrees.
+5. Reconcile returned reuse, conventions, principles, sources, assumptions,
+   decisions, dead ends, follow-ups, gates, and touched files. Persist the
+   relevant facts in canonical artifacts, not the wholesale report. A plan-gap
+   escalation without the checked-assumption list (verified|falsified) is
+   malformed; root sweeps the unchecked remainder per
+   [`spec-drift-guard.md`](spec-drift-guard.md) before repair.
+6. **Learning edge.** A correction accepted with a confirmed cause (a review,
+   gate, or proof rejection plus its fix) becomes a carry-forward constraint so
+   later slices start where this one ended: append one line under
+   `decisions.md` `## Carry-forward constraints` —
+   `- <rule> — from <SLICE-ID> (<evidence ref>); Files: <paths>`. Record the
+   derived rule, not the output, at the scope its evidence supports: "this
+   button is blue" never becomes "buttons are blue". Never edit `tasks.md` mid-build (it is a
+   readiness input). **Failing case:** slice 3 repeats a defect slice 2 fixed.

package/pack/generated/dsh/skills/rite-clarify/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: rite-clarify
+description: Audit a completed spec for missing decisions before strategy or architecture. Use after /rite-spec when coverage is incomplete or stale; not for spec writing.
+argument-hint: "[feature-slug]"
+user-invocable: true
+---
+
+<!-- loads: {"always":["devrites-lib/reference/standards/core.md","devrites-lib/reference/standards/code-navigation.md","devrites-lib/reference/standards/code-index.md","devrites-lib/reference/standards/afk-hitl.md","rite-clarify/reference/decision-coverage.md","rite-clarify/reference/anti-patterns.md"],"triggers":{"agents":["devrites-lib/reference/standards/agents.md"]},"workspace":["brief.md","spec.md","state.md","decisions.md","assumptions.md","questions.md","decision-coverage.md"],"workspaceByRole":{"evidence-scout":["brief.md","spec.md","state.md","questions.md"]},"rootOnly":["devrites-lib/reference/standards/code-index.md","devrites-lib/reference/standards/afk-hitl.md"]} -->
+> Read-set manifest: `devrites-engine context --skills-root .dsh/skills <slug> --phase clarify` bundles every file named below into one deduplicated read. Trigger names map to the conditional rules in the sections that follow.
+
+
+# /rite-clarify: resolve product decisions
+
+Run this required pass between spec and strategy. If the spec covers every material
+decision, ask no questions. Otherwise stay until each material decision has an
+owner. This phase settles behavior and constraints; `/rite-define` settles
+implementation.
+
+Reuse [`devrites-interview`](../devrites-interview/SKILL.md) in `/clarify mode`. Write
+`decision-coverage.md` as scan evidence, not an interview transcript.
+
+## Rules consulted
+
+Read [`core.md`](../devrites-lib/reference/standards/core.md), its [`afk-hitl.md`](../devrites-lib/reference/standards/afk-hitl.md), and
+[`reference/decision-coverage.md`](reference/decision-coverage.md). Fresh evidence
+dispatch uses
+[`agents.md`](../devrites-lib/reference/standards/agents.md).
+
+## Rules
+
+- Search code/docs/contracts first. Facts and reversible implementation/test choices
+  are agent-owned; ask only about product, scope, policy, irreversible risk, or human-only access.
+- Enumerate the full topology before details so no sibling surface is omitted.
+- Ask one coherent human-owned decision packet at a time. One packet may close several rows
+  only when owner and trade-off match; never ask permission for routine repair/retry.
+- One scan may cap at five packets for cognitive load, but readiness has no question cap:
+  re-scan until clear.
+- Material assumptions carry evidence, confidence, owner, validation, and consequence.
+- Refuse the rationalizations in [`anti-patterns`](reference/anti-patterns.md).
+
+## Workflow
+
+1. **Orient.** Read `.devrites/ACTIVE`, `state.md`, and `spec.md`. Require
+   `state.md` `spec_gate: passed` (legacy `Spec gate: passed` line accepted); otherwise stop at `/rite-spec`. Apply the native cursor
+   protocol below before changing workspace artifacts.
+2. **Enumerate the topology.** From the spec, live code, contracts, references,
+   and recorded decisions, list every material stakeholder/priority, invariant, actor,
+   journey/component, state, data lifecycle, integration, failure/recovery path,
+   operation, proof surface, applicability row, and must-NOT boundary.
+3. **Scan coverage.** Apply `devrites-interview` in clarify mode and mark each
+   material surface `closed`, `agent-owned`, `not-applicable`,
+   `deferred-nonblocking`, or `open` with evidence and an owner. Use native repository search
+   first. Ask the host to run `devrites-evidence-scout` only for a bounded missing
+   fact, then reconcile its cited result.
+4. **Close decisions.** Record facts and reversible technical choices directly.
+   Ask one coherent option packet only for product, scope, policy, irreversible
+   risk, or human-only access. Persist answers in the owning artifacts and repeat
+   the scan until no blocking `open` row or unowned material assumption
+   remains.
+5. **Write the verdict.** Write `Decision coverage: CLEAR` only after re-reading all inputs and confirming
+   every material row has current evidence and an owner. Normal flow sets `phase=clarify` and
+   `next_action=/rite-temper`. A low-stakes spec — the significance trigger temper itself
+   skips (rite-temper step 1) — sets `next_action=/rite-define` instead. A contract-neutral later-phase return uses
+   the native restore below; changed behavior or acceptance routes to
+   `/rite-plan repair` instead. Stop without starting the next phase.
+
+## Native clarify cursor protocol
+
+The controlling root edits only cursor rows in `state.md`; it must preserve unrelated Markdown and the file's existing table/bullet presentation.
+
+- **Normal entry from Spec:** set `phase=clarify`, `status=running`, and
+  `next_action=/rite-clarify <slug>`; omit both return fields.
+- **Already in Clarify:** no-op. Do not overwrite an existing valid return
+  cursor.
+- **Later-phase entry:** only `temper`, `define`, `plan`, `vet`, `build`,
+  `converge`, `prove`, `polish`, `review`, `seal`, or `ship` may return. First
+  copy the current `phase` and non-empty `next_action` to `return_phase` and
+  `return_next_action`; then set `phase=clarify`, `status=running`, and
+  `next_action=/rite-clarify <slug>`. Missing/unknown cursor values fail closed
+  before any write.
+- **Contract-neutral restore:** after a fresh `Decision coverage: CLEAR`, require
+  `phase=clarify`, both return fields, a recognized later `return_phase`, and a
+  non-empty `return_next_action`. Restore those values to `phase` and
+  `next_action`, set `status=running`, and remove both return fields in the same
+  rewrite. Re-read the cursor and confirm the return rows are absent.
+- **Contract changed:** do not restore the saved cursor. Record drift and route
+  through `/rite-plan repair`, which owns the changed plan and next action.
+
+Never normalize or rewrite the rest of `state.md` while applying this protocol.
+
+## Output
+
+```text
+Done: decision coverage closed for <slug>; <n> topology surfaces scanned.
+Changed: decision-coverage.md, spec.md, decisions.md, assumptions.md, questions.md
+Evidence: Decision coverage: CLEAR; human packets <n>; agent-owned facts <n>
+Open: none blocking; deferred-nonblocking <n>
+Next: /rite-temper (or /rite-define for a low-stakes spec temper skips)
+Record: .devrites/work/<slug>/decision-coverage.md
+↻ Hygiene: /clear — decision coverage is persisted in decision-coverage.md
+```
+
+If not clear, name the exact rows and next genuine decision packet. An objective spec defect
+or factual search task never routes through `/rite-resolve`.

package/pack/generated/dsh/skills/rite-clarify/reference/anti-patterns.md

@@ -0,0 +1,24 @@
+# /rite-clarify anti-patterns
+
+Load this when tempted to skip clarify, assume product choices, or write
+`Decision coverage: CLEAR` before every material row has an owner.
+
+Pack-wide rationalizations: see
+[standards/anti-patterns.md](../../devrites-lib/reference/standards/anti-patterns.md).
+
+## Phase-specific rationalizations
+
+| Excuse | Rebuttal |
+| --- | --- |
+| "We already discussed this in chat." | Chat is not durable decision coverage. Scan topology and record owners in workspace artifacts. |
+| "The answer is obvious — assume it." | Product, scope, policy, and irreversible-risk choices are human-owned unless already recorded in an accepted decision. |
+| "Most rows are clear — good enough for AFK." | `open` material rows block CLEAR and block AFK arming. |
+| "Skip clarify for this small change." | Clarify is mandatory and adaptive; it may ask no questions, but it still runs the scan. |
+| "I'll clarify during build if needed." | Unowned decisions discovered in build are expensive drift. Close them before plan/vet. |
+
+## Red flags in your own output
+
+- `Decision coverage: CLEAR` with `open` material rows still open.
+- Product/policy choices recorded without a human packet or cited prior decision.
+- AFK armed or `/rite-define` started before CLEAR is durable.
+- Clarify skipped because the user said they were "in a hurry".

package/pack/generated/dsh/skills/rite-clarify/reference/decision-coverage.md

@@ -0,0 +1,56 @@
+# Decision coverage contract
+
+`decision-coverage.md` proves a topology-first scan ran; reference canonical IDs instead of
+duplicating their prose.
+
+## Coverage taxonomy
+
+For each material surface scan: outcome/scope/must-NOT; behavior, permissions, and all states;
+domain/data lifecycle/invariants/order/concurrency; interfaces/integrations and failure
+contracts; security/privacy/compliance/accessibility/performance/reliability/compatibility;
+configuration/observability/support/rollout/rollback; and executable acceptance proof,
+environment, credentials/approvals, and evidence limits.
+
+## Status vocabulary
+
+- `closed`: the canonical artifact records the decision.
+- `agent-owned`: a reversible technical choice is explicitly delegated to define/vet.
+- `not-applicable`: evidence shows the dimension does not apply.
+- `deferred-nonblocking`: pre-code evidence is impossible or the item is an explicit
+  non-goal; owner and validation gate are named.
+- `open`: the decision is unresolved.
+
+`open`, unknown, or ownerless rows never produce `CLEAR`.
+
+## Artifact shape
+
+```markdown
+# Decision coverage
+
+Decision coverage: <CLEAR | NEEDS CLARIFICATION>
+
+## Topology
+| Surface | Kind | Related IDs | Evidence |
+| --- | --- | --- | --- |
+
+## Coverage matrix
+| Surface | Dimension | Status | Canonical reference | Owner / validation gate | Consequence if wrong |
+| --- | --- | --- | --- | --- | --- |
+
+## Assumption audit
+| Assumption | Evidence | Confidence | Owner | Validation | Consequence if wrong |
+| --- | --- | --- | --- | --- | --- |
+
+## Residual uncertainty
+| Item | Why nonblocking | Owner | Validation gate |
+| --- | --- | --- | --- |
+
+## Readiness verdict
+No `open` row, unowned material assumption, or unresolved blocking/escalating
+question remains.
+```
+
+Combine rows only when one decision and owner genuinely close them. Re-read the current
+`brief.md`, `spec.md`, `decisions.md`, `assumptions.md`, and `questions.md` before writing
+`CLEAR`; the matrix itself is the freshness check. Any open blocking, validating, or
+escalating question prevents `CLEAR`.

package/pack/generated/dsh/skills/rite-converge/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: rite-converge
+description: Converge intent and live code. Use when resuming a half-built feature, after `/rite-adopt` drift, or live code may have diverged from the plan. Not for initial planning.
+argument-hint: "[feature-slug]"
+user-invocable: true
+---
+
+<!-- loads: {"always":["devrites-lib/reference/standards/core.md","devrites-lib/reference/standards/code-navigation.md","devrites-lib/reference/standards/code-index.md","devrites-lib/reference/standards/spec-grammar.md","devrites-lib/reference/standards/agents.md","devrites-lib/reference/standards/tooling.md","devrites-lib/reference/standards/testing.md","rite-converge/reference/convergence-assessment.md","rite-converge/reference/anti-patterns.md","rite-build/reference/spec-drift-guard.md"],"triggers":{"applicability":["devrites-lib/reference/standards/repository-topology.md","devrites-lib/reference/standards/data-integrity.md","devrites-lib/reference/standards/integration-reliability.md"],"principles":["devrites-lib/reference/standards/principles.md"],"workflow-artifacts":["devrites-lib/reference/workspace-artifact-schema.md"]},"workspace":["brief.md","spec.md","state.md","decisions.md","assumptions.md","questions.md","decision-coverage.md","architecture.md","plan.md","tasks.md","traceability.md","eng-review.md","test-plan.md","gates.md","evidence.md"],"workspaceByRole":{"evidence-scout":["spec.md","plan.md","tasks.md","state.md","evidence.md"]},"rootOnly":["devrites-lib/reference/standards/code-index.md","devrites-lib/reference/standards/tooling.md"]} -->
+> Read-set manifest: `devrites-engine context --skills-root .dsh/skills <slug> --phase converge` bundles every file named below into one deduplicated read. Trigger names map to the conditional rules in the sections that follow.
+
+
+# /rite-converge: compare live code with intent
+
+Read `spec.md`, `plan.md`, and `tasks.md` as the **sole source of intent** (with
+`.devrites/principles.md` as governing constraints), assess what the **live codebase**
+implements, and **append every unmet piece as a new traceable `SLICE-###`** at the
+bottom of `tasks.md` so `/rite-build` can finish it. Use this for a resumed half-built
+feature, an adopted 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.
+
+> **This is not a diff tool.** `/rite-converge` compares current code with intent. It
+> does not use git history or compare branches. For a change-scoped
+> review use `/rite-review`; to prove a finished feature use `/rite-prove`.
+
+## Rules consulted (read on demand from `.dsh/skills/devrites-lib/reference/standards/`)
+
+Pull on demand:
+
+- [`principles.md`](../devrites-lib/reference/standards/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`](../devrites-lib/reference/standards/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.
+- [`code-navigation.md`](../devrites-lib/reference/standards/code-navigation.md): find each unit's code with codebase-memory `search_graph`
+  and `get_code_snippet`, check cited paths with `check_index_coverage`, then fall back to LSP/file search. Read live code, not artifact claims.
+- [`testing.md`](../devrites-lib/reference/standards/testing.md): a criterion with code but no covering test is *partial*, not done.
+- [`repository-topology.md`](../devrites-lib/reference/standards/repository-topology.md), [`data-integrity.md`](../devrites-lib/reference/standards/data-integrity.md), [`integration-reliability.md`](../devrites-lib/reference/standards/integration-reliability.md): only for
+  triggered applicability rows; missing failure/recovery behavior is partial or absent.
+
+## 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`.
+- **Use artifacts as intent.** The spec, plan, tasks, and 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
+  ([`spec-drift-guard.md`](../rite-build/reference/spec-drift-guard.md)) + a recorded decision; never paper over a spec
+  bug by appending a task that changes correct code to match 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.
+- **Unadmitted bytes from a lost wright.** When a stalled slice's wright never returned an
+  admitted result, act only after its terminal state is proven
+  ([`parallel-dispatch.md`](../devrites-lib/reference/parallel-dispatch.md) § Cancellation);
+  unproven stays a gap. Then inspect task-path bytes changed since the recorded pre-dispatch
+  `git diff --name-only` baseline (none recorded → every changed task path counts). They are
+  never cited `built`, never discarded (user work): classify the slice `partial (unadmitted
+  bytes)` and name those paths in the appended slice. A change outside task paths stops for the human.
+- **Scout observes; root classifies and writes.** Use
+  [`agents.md`](../devrites-lib/reference/standards/agents.md). The evidence scout returns
+  live-code citations only; the controlling chat owns built/partial/absent calls and append-only
+  workspace changes.
+
+## Workflow
+
+0. **Read `.dsh/skills/devrites-lib/reference/standards/core.md`** first (the always-on
+   operating rules), then resolve the active slug, require its `state.md`, and
+   read the cursor directly.
+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.
+   Require `decision-coverage.md` with `Decision coverage: CLEAR`; otherwise STOP →
+   `/rite-clarify`.
+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. **Reconcile the map, then read the code.** Compare `spec.md`, `tasks.md`,
+   `test-plan.md`, and `traceability.md` directly: every buildable AC/REQ maps to an
+   existing slice, every slice maps back to real acceptance, every slice's recorded
+   proof still agrees with its `test-plan.md` row, and the mapped prose preserves the
+   requirement's meaning. Record orphaned, invented, duplicate, or contradictory
+   mappings as gaps. Then read the live code
+   (codebase-memory per [`code-navigation.md`](../devrites-lib/reference/standards/code-navigation.md)); artifact mappings never prove implementation.
+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.
+   Dispatch up to three independent inventory partitions to `devrites-evidence-scout` on the
+   same live-code snapshot — build each scout's read-set once with
+   `devrites-engine context --skills-root .dsh/skills <slug> --phase converge --role evidence-scout --out
+   ctx/converge-evidence-scout.p<n>.bundle.md` and hand it the bundle path; run the wave
+   through `devrites-engine dispatch <slug> open|start|seal|return` with one lane label
+   per partition (`--role evidence-scout.p1 --role evidence-scout.p2 ...`, per
+   [`parallel-dispatch.md`](../devrites-lib/reference/parallel-dispatch.md)), which
+   auto-records dispatch/return metrics. Await their
+   dossiers, then reconcile the cited facts in the root
+   context. **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), 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); update `traceability.md` directly with rows for only the appended slices,
+   preserving every existing row. Appending a slice changes the plan input, so invalidate the prior vet:
+   update `state.md` to `Phase: plan`, `Next step: /rite-vet`, and set an existing
+   `eng-review.md` field to `Implementation readiness: NEEDS REPLAN`. When nothing was unmet,
+   leave the plan/vet verdict untouched and set `Next step: /rite-prove`. Append
+   `decisions.md` for any material call. When slices were appended, run
+   `devrites-engine check task-graph <slug>` before invoking Vet; failure stays in
+   Converge for correction and never spends a Vet reviewer context.
+7. **STOP.** Report units assessed, built / partial / absent / unrequested counts, slices appended, and any
+   principle violation found. A direct invocation that appended slices becomes
+   the caller for the mandated next step: save a return cursor
+   (`return_phase`/`return_next_action`) naming this Converge pass as the
+   caller, invoke `/rite-vet` inline, and consume its results — an agent-owned
+   `NEEDS REPLAN` routes to `/rite-plan` repair internally under the
+   fingerprint caps; its return lands here, never on the user. Stop only at
+   Vet's boundary (READY readback; next step `/rite-build` for the appended
+   slices). Nothing appended → recommend `/rite-prove`.
+
+## Completion evidence (fail-closed)
+
+Before reporting "clean" or recommending `/rite-prove`, confirm:
+
+- [ ] Every buildable AC/REQ in the assessment inventory has a built/partial/absent
+      classification with live-code citation
+- [ ] Every plan touch-point and existing-slice Produces is classified with live-code citation
+- [ ] Every declared principle is checked; violations are recorded as top-severity gaps
+- [ ] `tasks.md` is byte-for-byte unchanged when clean, or append-only when gaps exist
+- [ ] `traceability.md` updated only for appended slices
+- [ ] No narrative "done" without the checklist above
+
+**Failing case:** all units marked built but one AC lacks a test or runtime citation →
+report partial, append slice, route `/rite-vet`.
+
+## 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.** Do not rewrite an existing slice, edit source, mark a
+> happy-path-only implementation as built, or add work for a spec you suspect is wrong.
+> See [`reference/anti-patterns.md`](reference/anti-patterns.md).

package/pack/generated/dsh/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.