devrites 2.6.1 → 3.0.0

package/docs/quick-reference.md

@@ -0,0 +1,22 @@
+# DevRites quick reference
+
+DevRites installs via `npx devrites ...`; Claude Code and Codex support are generated project-local artifacts, not plugin-store installs.
+
+## Lifecycle
+
+`SPEC -> DEFINE -> VET -> BUILD -> PROVE -> POLISH -> REVIEW -> SEAL -> SHIP`
+
+Seal decides. Ship mutates git. Build one slice. Autocomplete is opt-in.
+
+## Standing checklists
+
+- Definition of Done: `pack/.claude/skills/devrites-lib/reference/standards/definition-of-done.md`
+- Review: `pack/.claude/skills/devrites-lib/reference/standards/review-checklist.md`
+- Security: `pack/.claude/skills/devrites-lib/reference/standards/security-checklist.md`
+- Test proof: `pack/.claude/skills/devrites-lib/reference/standards/test-proof-checklist.md`
+- Browser proof: `pack/.claude/skills/devrites-lib/reference/standards/browser-proof-checklist.md`
+- Ship: `pack/.claude/skills/devrites-lib/reference/standards/release/ship-checklist.md`
+
+## Host command forms
+
+Claude: `/rite <verb>` or `/rite-<verb>`. Codex: `$rite <verb>` or `$rite-<verb>`.

package/docs/release.md

@@ -4,12 +4,12 @@ Releases are **fully automated** via [semantic-release](https://semantic-release
 
 1. Runs `scripts/validate.sh` + install / uninstall smoke tests.
 2. Syncs the new version into `package.json` and the README status line (`scripts/sync-version.sh`).
-3. Builds a `dist/devrites-v<version>.tar.gz` release artifact via `scripts/build-release-tarball.sh` — the extractable bundle end-users get from the `curl | bash` installer.
+3. Builds a `dist/devrites-v<version>.tar.gz` release artifact via `scripts/build-release-tarball.sh` — the extractable bundle end-users get from the `curl | bash` installer. The bundle includes `pack/generated/` host-native Claude/Codex artifacts rendered from the canonical pack.
 4. Regenerates `CHANGELOG.md` from the commits.
-5. Publishes the `devrites` package to the npm registry (`@semantic-release/npm`, needs the `NPM_TOKEN` secret) — this is what `npx devrites@latest` resolves.
+5. Publishes the `devrites` package to the npm registry (`@semantic-release/npm`, needs the `NPM_TOKEN` secret) — this is what `npx devrites@latest` resolves. `npm pack` renders the same `pack/generated/` artifacts during `prepack`; there is no `postpack` cleanup step.
 6. Commits the version bump + changelog as `chore(release): <version> [skip ci]`, creates a git tag `v<version>`, and publishes a GitHub Release with the tarball attached.
 
-Local dry-run: `npm run release:dry` (shows the version bump + draft notes without publishing). The release job is gated by passing CI — a broken `main` won't ship.
+Local dry-run: `npm run release:dry` (shows the version bump + draft notes without publishing). Before publishing, `scripts/release-check.sh` builds the evidence packet: generated pack freshness, tarball checksum presence, `npx-pack-smoke`, install/update/uninstall, `validate-pack`, behavioral eval schema, and a README/docs check that install instructions stay `npx devrites ...` only. DevRites is not shipped through Claude or Codex plugin stores. The release job is gated by passing CI — a broken `main` won't ship.
 
 ## Authoring commits that trigger releases
 

package/docs/skills.md

@@ -1,8 +1,8 @@
-# All 36 skills
+# All 42 skills
 
-The pack ships **36 skills total** — 24 user-invocable `rite-*` workflow + utility skills and 11 model-invoked `devrites-*` specialists, plus the internal `devrites-lib` library skill (`user-invocable: false`, not a command) that ships the cross-cutting scripts the workflow skills run: the read-only orientation preamble and the `readiness` / `evidence-fresh` / `acceptance` gate scripts, plus the `tick-afk` / `resolve` / `close-out` state mutators. Each skill is a structured workflow with its own operating rules, anti-rationalization tables, and red flags. Engineering rules live at `.claude/rules/`; each `rite-*` skill Reads `.claude/rules/core.md` as its first step (step 0) and pulls the other 22 rule files on demand (no carrier skill, no session-start autoload). The installer mirrors skills to `.agents/skills` for Codex, mirrors rules to `.agents/devrites/rules`, injects Codex-specific dispatch/rules guidance into those mirrors, generates `.codex/agents` from the DevRites review agents, installs Codex hooks in `.codex/hooks.json` + `.codex/hooks/`, merges DevRites guidance into `AGENTS.md`, and registers the project-local DevRites MCP server through `.codex/config.toml`. A unified `devrites` CLI and an MCP server expose the `devrites-lib` ops to any tool (see [`cli-mcp.md`](cli-mcp.md)).
+The pack ships **42 skills total** — the `rite` menu, 29 user-invocable `rite-*` workflow + utility skills, 11 model-invoked `devrites-*` specialists, plus the internal `devrites-lib` library skill (`user-invocable: false`, not a command) that ships shared references and explicit script exceptions. DevRites is distributed through the npm package (`npx devrites ...`), not through Claude or Codex plugin stores; Claude Code and Codex surfaces are generated host artifacts installed by the npm flow. The workflow control plane runs through the installed `devrites-engine` binary: orientation, read-only gates, and state mutation all use engine subcommands so Claude Code, Codex, CI, and humans get the same verdicts. Workspace-operating lifecycle skills load `core.md` in workflow step 0 and disclose phase rules and failure modes on demand; compact utilities declare their narrower contract locally. The engine-owned installer copies generated Codex mirrors to `.agents/skills`, mirrors rules to `.agents/skills/devrites-lib/reference/standards`, installs generated `.codex/agents`, and merges Codex hooks/guidance. The npm `devrites` shim bootstraps or proxies `devrites-engine` directly (see [`cli.md`](cli.md)).
 
-**Naming convention.** `rite-*` is the user-facing slash-command surface (lifecycle phases plus utilities — `rite-quick`, `rite-frame`, `rite-adopt`, `rite-learn`, `rite-doctor`, `rite-prototype`, `rite-handoff`, `rite-zoom-out`, `rite-pressure-test`). `devrites-*` is internal (model-invoked, hidden from the menu) and collision-avoiding against bundled Claude Code skill names. Visibility is governed by each skill's `user-invocable:` flag; the prefix mirrors it.
+**Naming convention.** `rite-*` is the workflow/utility namespace (lifecycle phases plus utilities — `rite-quick`, `rite-frame`, `rite-adopt`, `rite-learn`, `rite-customize`, `rite-explain`, `rite-pov`, `rite-dogfood`, `rite-pr-feedback`, `rite-doctor`, `rite-prototype`, `rite-handoff`, `rite-zoom-out`, `rite-pressure-test`). Some niche utilities are explicit-only (`disable-model-invocation: true`) to keep the always-loaded skill surface small. `devrites-*` is the collision-avoiding specialist/library namespace. Prefix alone does not determine visibility: `user-invocable:` and `disable-model-invocation:` are authoritative, as cataloged in [`command-map.md`](command-map.md).
 
 ---
 
@@ -24,43 +24,31 @@ of which satisfy the convention:
   (frontend-craft), the numbered rule list (prototype), and `## Gotchas`
   (api-interface, rite, status).
 
-**New skills SHOULD use `## Gotchas`** — 2–3 traps the model most reaches for in that
-phase (the rationalizations in `pack/.claude/rules/anti-patterns.md`, specialized), not a
+**New or materially edited skills SHOULD use `## Gotchas`** — 2–3 traps the model most reaches for in that
+phase (the rationalizations in `pack/.claude/skills/devrites-lib/reference/standards/anti-patterns.md`, specialized), not a
 restatement of the positive steps. A mechanical rename of the equivalents above to a
 single `## Gotchas` heading is a possible future normalization; the content already holds.
 
-## Commands quick reference
-
-In Claude Code, every user-invocable skill responds to **both** `/rite <verb>` (menu form — type `/rite` for the discoverable entry point) and `/rite-<verb>` (direct shortcut). Both hit the same skill; use whichever reads more naturally. In Codex, use `$rite`, `$rite-<verb>`, or `/skills` to select the mirrored skill from `.agents/skills`; when a skill dispatches a DevRites subagent, the Codex mirror instructs Codex to use the matching `.codex/agents/devrites-*.toml` custom agent. The generated `AGENTS.md` block tells Codex to read `.agents/devrites/rules/core.md` before DevRites workflow work.
-
-| Menu form | Direct shortcut | Phase | Does |
-|---|---|---|---|
-| `/rite` | — | menu | Compact menu + dispatches verb args to the matching `rite-<verb>` skill. Without args, renders the menu. |
-| `/rite spec <feature>` | `/rite-spec <feature>` | spec | **Start here.** Deep investigation → writes `spec.md`: understands the ask fully, decides **placement** (where it lives), names what it resolves, closes gaps with you (questions with options), and gathers any design references you optionally attach (screenshots / Figma / links / video — there may be none). |
-| `/rite temper` | `/rite-temper` | temper | **Optional, before define.** Strategic review of the readied spec — pick a scope mode (expand / selective / hold-rigor / reduce-to-MVP), run a pre-mortem, harden the spec, write `strategy.md`, and fold the decisions back via the Spec Drift Guard. Significance-gated (skips small work); **mandatory inside `/rite-autocomplete`**. |
-| `/rite define` | `/rite-define` | plan | Turns the approved spec into `plan.md` + vertical task slices + state. |
-| `/rite vet` | `/rite-vet` | vet | **Before build — every feature.** Engineering review of the defined plan — scope challenge (reuse / minimum-diff / complexity smell), then architecture / plan code-quality / test-coverage design / performance through senior-engineer lenses, every finding confidence-banded with a quote-the-source verification gate. Maps failure modes + parallel lanes, hardens `plan.md` / `tasks.md`, writes the build-readable `test-plan.md`; acceptance-changing deltas fold back via the Spec Drift Guard. `--cross-model` adds a different-model second opinion. Runs on every plan — depth scales to stakes (light pass on simple, full on big/risky), never skipped; **always inside `/rite-autocomplete`**. |
-| `/rite plan` | `/rite-plan` | re-plan | Decompose / reslice / repair an active plan. |
-| `/rite build` | `/rite-build` | build | Implement **exactly one** vertical slice, then stop — dispatches a fresh-context `devrites-slice-wright` to write it; gates and records the result. |
-| `/rite prove` | `/rite-prove` | prove | Tests + build + runtime + browser evidence for the current scope. |
-| `/rite polish` | `/rite-polish` | polish | Code polish always; UI normalize + polish if UI in scope. Modes: `bolder / quieter / distill / harden / normalize-only`. |
-| `/rite review` | `/rite-review` | review | Feature-scoped multi-axis review (parallel Spec + Standards axes). |
-| `/rite seal` | `/rite-seal` | seal | Final GO / NO-GO decision gate — walks acceptance vs evidence, fans out reviewers, writes the verdict to `seal.md`. Decides only; hands off to `/rite-ship`. |
-| `/rite ship` | `/rite-ship` | ship | Final phase. Requires a GO in `seal.md` → renders type-`GO`, runs the irreversible git ladder (commit → push → tag/PR), writes `ship.md`, then closes the task (archives the workspace, clears `ACTIVE`). |
-| `/rite autocomplete` | `/rite-autocomplete` | (orchestrator) | Runs the whole lifecycle unattended (spec → … → seal → ship), choosing the best option at each soft gate. `--ship` / `--yolo` auto-confirms the final type-`GO`. |
-| `/rite status` | `/rite-status` | status | Where the active feature stands. |
-| `/rite resolve <qid> "<answer>"` | `/rite-resolve <qid> "<answer>"` | resume | Answer a HITL checkpoint (or `--drop <qid>` / `--batch <file>`); clears `state.md` `Awaiting human` and resumes. |
-| `/rite zoom-out` | `/rite-zoom-out` | utility | Step up an abstraction layer when stuck — returns a map of the area (modules, callers, decisions) in the project's vocabulary. |
-| `/rite prototype` | `/rite-prototype` | utility | Throwaway code that answers ONE design question before committing — routes between a Logic harness (state/data model) and 2–4 radically different UI variations on one route. |
-| `/rite handoff` | `/rite-handoff` | utility | Compact the chat session into a handoff doc a fresh agent can pick up — syncs to the workspace, references existing artifacts by path. |
-| `/rite pressure-test` | `/rite-pressure-test` | utility | Diverge → converge on a rough idea before specifying. |
-| `/rite quick` | `/rite-quick` | express | Express lane for a **small, reversible, unambiguous** change — one-line contract → TDD build → scoped prove → review-lite → ship, no full artifact tree. Significance gate first: auth / migration / public-API / destructive / multi-slice / ambiguous → escalates to `/rite-spec`. |
-| `/rite frame` | `/rite-frame` | lens | Pre-flight + self-audit lens for ad-hoc work the lifecycle's gates never see — converts an imperative ask into a falsifiable success criterion + verify command (FRAME), then audits a raw diff against the four LLM coding failure modes (AUDIT). |
-| `/rite adopt` | `/rite-adopt` | onboard | Bring an EXISTING codebase under DevRites — reverse-derive a `spec.md` of current behavior + placement + architecture, and seed the conventions ledger from the idioms the code already follows. |
-| `/rite learn` | `/rite-learn` | utility | Cross-feature learning loop — mine shipped features for recurring mistakes + dismissed-finding classes, propose project-local lessons into `.devrites/learnings.md` (and graduate a recurring invariant to a project principle, human-gated). |
-| `/rite doctor` | `/rite-doctor` | diagnostic | Diagnose DevRites install + workspace health — install integrity, a stale `.devrites/ACTIVE`, a corrupt workspace, orphaned gates, broken hook wiring. |
-
-The 11 model-invoked internal specialists (hidden from the menu): `devrites-interview`, `-source-driven`, `-doubt`, `-ux-shape`, `-frontend-craft`, `-prose-craft`, `-browser-proof`, `-debug-recovery`, `-api-interface`, `-audit` (security / perf / simplify), `-refresh-indexes`. Plus the `devrites-lib` library skill (scripts, not a command). The `/rite` menu carries the routing, the user-invocable utilities all use the `rite-*` prefix (`rite-quick`, `rite-frame`, `rite-adopt`, `rite-learn`, `rite-doctor`, `rite-prototype`, `rite-handoff`, `rite-zoom-out`, `rite-pressure-test`, `rite-autocomplete`), and the `/rite-polish` phases live as references inside the same skill rather than as `rite-polish-code` / `rite-polish-ui`. Triggers and interactions are documented in [`command-map.md`](command-map.md); diagrams in [`flow.md`](flow.md).
+## Command invocation
+
+Every public `rite-<verb>` skill has four equivalent forms: Claude `/rite <verb>` or `/rite-<verb>`, and Codex `$rite <verb>` or `$rite-<verb>`. See the canonical [`command-map.md`](command-map.md) for the per-command inventory, triggers, and interactions.
+
+## Completion reply contract
+
+Workspace-operating `rite-*` skills render `devrites-engine progress` first, then a compact
+completion reply from
+[`reply-contract.md`](../pack/.claude/skills/devrites-lib/reference/reply-contract.md).
+The progress command owns the deterministic header, slice meter, and flow ribbon; the
+chat reply only summarizes status: `Done`, `Changed`, `Evidence`, `Open`, one `Next`
+command, `Record`, and `↻ Hygiene`. Detailed reports stay in durable workspace
+artifacts such as `spec.md`, `plan.md`, `evidence.md`, `review.md`, `seal.md`, and
+`ship.md`.
+
+Typed stop states are standardized too: `Awaiting human`, `Stopped`, `NO-GO`, `GO`,
+and `Shipped`. Utility commands that do not operate on an active workspace declare a
+reply-contract exception but still keep the same compact labels and one-next-action
+rule. `scripts/check-reply-contract.sh` enforces the reference/exception marker and
+blocks obvious multi-command `Next:` wording.
 
 ---
 
@@ -70,10 +58,11 @@ The 11 model-invoked internal specialists (hidden from the menu): `devrites-inte
 
 | Skill | What It Does | Use When |
 |---|---|---|
-| [`rite`](../pack/.claude/skills/rite/SKILL.md) | Compact menu + active-feature status + suggested next command. Does not run a workflow. | You type `/rite`, ask "what DevRites commands exist", or "where am I". |
-| [`rite-status`](../pack/.claude/skills/rite-status/SKILL.md) | Read-only report: phase, run mode (AFK/HITL), status, active slice, next action, evidence, open questions by gate, drift, risks. | You ask "where am I", "what's the status", "what's next". |
-| [`rite-resolve`](../pack/.claude/skills/rite-resolve/SKILL.md) | Answer / drop / batch-resolve open `questions.md` entries; clears `state.md` `Awaiting human` and resumes the workflow. | A HITL checkpoint is open or AFK left blocking questions; you type `/rite-resolve <qid> "<answer>"`. |
-| [`rite-doctor`](../pack/.claude/skills/rite-doctor/SKILL.md) | Diagnose DevRites install + workspace health — install integrity, stale `.devrites/ACTIVE`, corrupt workspace, orphaned gates, broken hook wiring. Read-only report. | "rite doctor", "is DevRites healthy", "why isn't the workflow picking up my feature". |
+| [`rite`](../pack/.claude/skills/rite/SKILL.md) | Compact menu + active-feature status + suggested next command. Does not run a workflow. | Explicit-only: type `/rite` or `$rite`. |
+| [`rite-status`](../pack/.claude/skills/rite-status/SKILL.md) | Read-only report: phase, run mode (AFK/HITL), status, active slice, next action, evidence, open questions by gate, drift, risks. | Explicit-only: type `/rite-status` / `/rite status`. |
+| [`rite-resolve`](../pack/.claude/skills/rite-resolve/SKILL.md) | Answer / drop / batch-resolve open `questions.md` entries; clears `state.md` `Awaiting human` and resumes the workflow. | Explicit-only: type `/rite-resolve <qid> "<answer>"`. |
+| [`rite-doctor`](../pack/.claude/skills/rite-doctor/SKILL.md) | Diagnose DevRites install, workspace, and optional index health. `--reindex` runs the internal synchronous refresh. | "rite doctor", "is DevRites healthy", "reindex". |
+| [`rite-customize`](../pack/.claude/skills/rite-customize/SKILL.md) | Guided authoring for project-local reviewer overrides and extensions; validates before stopping. | Explicit-only: `/rite-customize` / `/rite customize`. |
 
 ### Express & ad-hoc — small or unguarded work
 
@@ -103,7 +92,8 @@ The 11 model-invoked internal specialists (hidden from the menu): `devrites-inte
 | Skill | What It Does | Use When |
 |---|---|---|
 | [`rite-define`](../pack/.claude/skills/rite-define/SKILL.md) | Approved spec → `plan.md` + vertical task slices + `state.md`. | `spec.md` exists and is approved. |
-| [`rite-plan`](../pack/.claude/skills/rite-plan/SKILL.md) | Decompose / reslice / repair an active plan after drift. | Spec Drift Guard fires, or you need to repair an existing plan. |
+| [`rite-plan`](../pack/.claude/skills/rite-plan/SKILL.md) | Decompose / reslice / repair an active plan after drift; `revise` updates planning artifacts only. | Spec Drift Guard fires, or you need to repair/revise an existing plan. |
+| [`rite-converge`](../pack/.claude/skills/rite-converge/SKILL.md) | Assess live code vs `spec`/`plan`/`tasks` intent; append the remaining unbuilt work as new traceable slices (append-only, no git). | Resuming a half-built or stalled feature, or after `/rite-adopt` when code drifted from the derived spec. |
 
 ### Vet — Lock in the engineering plan before building
 
@@ -119,7 +109,7 @@ The 11 model-invoked internal specialists (hidden from the menu): `devrites-inte
 | [`devrites-source-driven`](../pack/.claude/skills/devrites-source-driven/SKILL.md) | Consult official docs / source before relying on framework behavior; record the source. | API, config, or framework behavior is assumed rather than known. |
 | [`devrites-api-interface`](../pack/.claude/skills/devrites-api-interface/SKILL.md) | Design stable API / interface contracts — REST/GraphQL, module boundaries, type contracts, FE/BE split. | A slice crosses a boundary or defines a public interface. |
 | [`devrites-debug-recovery`](../pack/.claude/skills/devrites-debug-recovery/SKILL.md) | Reproduce → ranked hypotheses → instrument → fix in scope → regression-test. Stops guess-and-retry. | Tests, builds, or runtime checks fail. |
-| [`devrites-refresh-indexes`](../pack/.claude/skills/devrites-refresh-indexes/SKILL.md) | Keep the optional code-intelligence indexes (codebase-memory-mcp, codegraph, graphify) current so the next structural lookup reads live code, not a stale graph. The Stop hook runs it automatically; this skill is the manual force. | Index looks stale, after a large change before a structural query, or "reindex" / "the graph is stale". |
+| [`devrites-refresh-indexes`](../pack/.claude/skills/devrites-refresh-indexes/SKILL.md) | Internal synchronous refresh for optional code-intelligence indexes. The Stop hook runs automatically; `/rite-doctor --reindex` owns the user route. | Structural lookup disagrees with live code, or doctor requests a refresh. |
 
 ### Prove — Real evidence, including the browser
 
@@ -161,16 +151,20 @@ The 11 model-invoked internal specialists (hidden from the menu): `devrites-inte
 | Skill | What It Does | Use When |
 |---|---|---|
 | [`rite-autocomplete`](../pack/.claude/skills/rite-autocomplete/SKILL.md) | Runs the whole lifecycle unattended (spec → … → seal → ship), choosing the best option at each soft gate and recording the rationale in `decisions.md`. A vague prompt triggers an up-front `devrites-interview`; after that it runs without per-phase iteration, pausing only on hard irreversible-risk / blocking / escalating gates, an open validating gate, NO-GO, or budget exhaustion. Default stops at the final type-`GO`; `--ship` (alias `--yolo`) auto-confirms it. | "Autocomplete", "do the whole thing", "run the full cycle", "one-shot this feature". |
-| [`rite-zoom-out`](../pack/.claude/skills/rite-zoom-out/SKILL.md) | Map an unfamiliar area — modules, callers, callees, decisions — in the project's domain glossary. | You say "zoom out", "I don't know this area", "map this area", "bigger picture". |
-| [`rite-prototype`](../pack/.claude/skills/rite-prototype/SKILL.md) | Throwaway code answering ONE design question — logic harness OR 2–4 UI variations on one route. | "Prototype this", "let me play with it", "try a few designs", question is undecidable on paper. |
-| [`rite-handoff`](../pack/.claude/skills/rite-handoff/SKILL.md) | Compact chat session → handoff doc. References existing `.devrites/work/<slug>/` artifacts by path. | "Handoff", "summarize this session", before `/clear`, fresh agent will continue. |
-| [`rite-learn`](../pack/.claude/skills/rite-learn/SKILL.md) | Cross-feature learning loop — mine shipped features for recurring mistakes + dismissed-finding classes (`learnings.sh mine`), propose project-local lessons into `.devrites/learnings.md` (loaded by the review skills before a fan-out). | After several features ship; "what have we learned", "harvest lessons", "why does this keep coming up". |
+| [`rite-zoom-out`](../pack/.claude/skills/rite-zoom-out/SKILL.md) | Map an unfamiliar area — modules, callers, callees, decisions — in the project's domain glossary. | Explicit-only: `/rite-zoom-out` / `/rite zoom-out`. |
+| [`rite-prototype`](../pack/.claude/skills/rite-prototype/SKILL.md) | Throwaway code answering ONE design question — logic harness OR 2–4 UI variations on one route. | Explicit-only: `/rite-prototype` / `/rite prototype`. |
+| [`rite-handoff`](../pack/.claude/skills/rite-handoff/SKILL.md) | Compact chat session → handoff doc. References existing `.devrites/work/<slug>/` artifacts by path. | Explicit-only: `/rite-handoff` / `/rite handoff`. |
+| [`rite-learn`](../pack/.claude/skills/rite-learn/SKILL.md) | Cross-feature learning loop — mine shipped features for recurring mistakes + dismissed-finding classes (`devrites-engine learnings mine`), propose project-local lessons into `.devrites/learnings.md` (loaded by the review skills before a fan-out). | Explicit-only: `/rite-learn` / `/rite learn`. |
+| [`rite-explain`](../pack/.claude/skills/rite-explain/SKILL.md) | The human half of the learning loop — turns a concept, diff, idea, or recent work into a dense explainer; diff inputs can instead produce a concern-ordered human review walkthrough. | Explicit-only: `/rite-explain` / `/rite explain`. |
+| [`rite-pov`](../pack/.claude/skills/rite-pov/SKILL.md) | Project-grounded verdict on a named external option — adopt / trial / hold / reject / not-our-problem after project + external floors clear. | "should we adopt X", "switch to Y", CVE/deprecation relevance, bounded external comparisons. |
+| [`rite-dogfood`](../pack/.claude/skills/rite-dogfood/SKILL.md) | Diff-scoped browser QA — map changed user journeys, run scenario matrix, fix small obvious breakages, write `dogfood.md`. | Explicit-only after prove/polish/review when browser UX confidence matters. |
+| [`rite-pr-feedback`](../pack/.claude/skills/rite-pr-feedback/SKILL.md) | Resolve PR review feedback — fetch unresolved threads, judge centrally, fix valid items, reply, resolve. | Explicit-only: `/rite-pr-feedback` / `/rite pr-feedback`. |
 
 ### Foundation — Engineering rules
 
 | Skill | What It Does | Use When |
 |---|---|---|
-| (engineering rules) | Live at `.claude/rules/` post-install — each `rite-*` skill Reads `.claude/rules/core.md` as its first step (step 0); the other 22 rule files (`coding-style.md`, `prose-style.md`, `error-handling.md`, `testing.md`, `spec-grammar.md`, `code-review.md`, `principles.md`, `security.md`, `performance.md`, `observability.md`, `developer-experience.md`, `patterns.md`, `git-workflow.md`, `hooks.md`, `documentation.md`, `development-workflow.md`, `deprecation.md`, `agents.md`, `context-hygiene.md`, `anti-patterns.md`, `afk-hitl.md`, `tooling.md`) load on demand per skill body. No carrier skill, no session-start autoload. | n/a — step-0 core / on-demand by path. |
+| (engineering rules) | Live at `.claude/skills/devrites-lib/reference/standards/` post-install — each `rite-*` skill Reads `.claude/skills/devrites-lib/reference/standards/core.md` as its first step (step 0); the remaining rule files load on demand per skill body. `README.md` is the index. No carrier skill, no session-start autoload. | n/a — step-0 core / on-demand by path. |
 
 ---
 

package/docs/usage.md

@@ -8,29 +8,36 @@ none exists it tells you to run `/rite-spec <feature>`.
 - **Full command reference** → [`command-map.md`](command-map.md)
 - **Flow diagrams** → [`flow.md`](flow.md)
 - **Architecture rationale** → [`architecture.md`](architecture.md)
+- **Workspace schema** → [`engine/workspace-schema.md`](engine/workspace-schema.md)
 
 ## The workspace
 
 `/rite-spec` creates `.devrites/work/<slug>/` and writes the spec;
-`/rite-define` adds the plan and tasks. All human-readable Markdown that
+`/rite-define` adds architecture, the plan, tasks, and traceability. All human-readable Markdown that
 survives compaction and new sessions:
 
 | File | Created by | Holds |
 |---|---|---|
+| `README.md` / `index.md` / `feature.md` | `/rite-spec` | compact workspace map: phase, status, next action, artifact map, read-next table, gates |
 | `brief.md` | `/rite-spec` | one-line objective + definition of done |
-| `spec.md` | `/rite-spec` | what to build + why, placement, acceptance, gaps/decisions |
+| `spec.md` | `/rite-spec` | product WHAT/WHY, requirements, acceptance, boundaries, measurable success |
+| `architecture.md` | `/rite-define` | owning module/layer, integration points, data/API/events, dependencies, risks |
+| `flows.md` | `/rite-spec` or `/rite-define` | optional Mermaid diagrams when sequence/state/data flow clarifies behavior |
 | `references/` + `references.md` | `/rite-spec` | saved design refs — screenshots, Figma, video, links |
 | `strategy.md` | `/rite-temper` | strategic spec review (optional): scope mode, pre-mortem, dimension scores |
 | `plan.md` | `/rite-define` | approach, dependency graph, checkpoints, rollback |
-| `tasks.md` | `/rite-define` | ordered vertical slices, each tagged `Mode: AFK \| HITL` + `Gate` / `SLA` / `Checkpoint` when HITL |
+| `tasks.md` | `/rite-define` | ordered `SLICE-###` vertical slices, each mapped to `AC-###` and tagged `Mode: AFK \| HITL` + gate fields |
+| `traceability.md` | `/rite-define` | AC/REQ → slices → tests/proofs → evidence → touched files matrix |
 | `eng-review.md` | `/rite-vet` | engineering plan review (optional): scope challenge, axis findings, failure modes, parallelization |
 | `test-plan.md` | `/rite-vet` | build-readable coverage target: coverage diagram, per-gap test requirements, acceptance→test map (read by `/rite-build` + `/rite-prove`) |
-| `state.md` | every phase | phase, status, active slice + slice mode, risk, next step (the cursor); plus `Awaiting human` block when paused (run mode is derived from `.devrites/AFK`, not stored here) |
+| `status.md` | every phase | canonical status checkpoint |
+| `state.md` | every phase | working ledger: phase, active slice + slice mode, risk, next step; plus `Awaiting human` block when paused (run mode is derived from `.devrites/AFK`, not stored here) |
 | `questions.md` | every phase | append-only Q&A — qid, slice, gate, status (`open` / `answered` / `dropped`), proposed answer, raised/answered timestamps |
 | `decisions.md` / `assumptions.md` | every phase | running logs |
 | `drift.md` | Spec Drift Guard | drift events + resolutions |
 | `touched-files.md` | `/rite-build` | what files this feature touched |
-| `evidence.md` | `/rite-build`, `/rite-prove` | recorded commands + output |
+| `evidence.md` | `/rite-build`, `/rite-prove` | canonical `EVID-###` command/action proof |
+| `proof.md` | `/rite-build`, `/rite-prove` | transition alias for `evidence.md` |
 | `browser-evidence.md` | `/rite-prove`, `/rite-polish` (UI) | screenshots, console, network, viewport runs |
 | `design-brief.md` | `devrites-frontend-craft` | shape, states, design references match |
 | `polish-report.md` | `/rite-polish` | Phase 1-4 findings + fixes |
@@ -43,11 +50,17 @@ When `/rite-ship` closes the task it **archives** the whole workspace —
 preserved, never deleted) — and clears `.devrites/ACTIVE`. The audit trail lives
 on under `.devrites/archive/<slug>/`.
 
+Backward compatibility: older `.devrites/features/<slug>/` workspaces remain
+readable; migration should add the canonical `.devrites/work` shape without
+deleting the old files. `feature.md`/`index.md` can still act as the workspace
+map, and `proof.md` can still act as the proof alias for `evidence.md`.
+
 Project-root sentinel (outside the workspace):
 
 | File | Created by | Holds |
 |---|---|---|
-| `.devrites/AFK` | you (presence = AFK mode active) | optional YAML: `max_slices`, `notify`, `allow_gates`. Empty file = AFK with defaults. See [`pack/.claude/rules/afk-hitl.md`](../pack/.claude/rules/afk-hitl.md). |
+| `.devrites/AFK` | you (presence = AFK mode active) | optional YAML: `max_slices`, `notify`, `allow_gates`. Empty file = AFK with defaults. See [`pack/.claude/skills/devrites-lib/reference/standards/afk-hitl.md`](../pack/.claude/skills/devrites-lib/reference/standards/afk-hitl.md). |
+| `.devrites/CHECKPOINT` | you or `/rite-autocomplete` (presence = checkpoint mode) | empty sentinel. When set, `/rite-build` commits each proven slice local-only as `WIP(<slug>)` so a crash mid-build loses neither source nor reasoning; `/rite-ship` collapses the WIP run into the one feature commit. See [`pack/.claude/skills/rite-build/reference/checkpoint.md`](../pack/.claude/skills/rite-build/reference/checkpoint.md). |
 
 The shape of this directory is also documented in
 [`flow.md` § Workspace state model](flow.md#7-workspace-state-model).
@@ -209,7 +222,7 @@ Run before `/clear` if leaving for > a few hours.
   → reads tasks.md slice 03; Mode: HITL, Gate: blocking
   → STOPS before writing any code:
 
-    Slice 03 — list endpoint is HITL (blocking, SLA 15m).
+    SLICE-003 — list endpoint is HITL (blocking, SLA 15m).
     Checkpoint: Composite (user_id, created_at) index, or two single-col indexes?
     Proposed approach: composite — single read path, both columns used together
     in the most common filter; downside is rebuild cost on bulk updates.
@@ -266,7 +279,7 @@ EOF
 The loop refuses to mark a slice `built` if tests / types / lint go red — it
 writes a blocking question and stops regardless of `allow_gates`. AFK never
 silently accepts irreversible risk; see
-[`pack/.claude/rules/afk-hitl.md`](../pack/.claude/rules/afk-hitl.md) for the
+[`pack/.claude/skills/devrites-lib/reference/standards/afk-hitl.md`](../pack/.claude/skills/devrites-lib/reference/standards/afk-hitl.md) for the
 full list.
 
 ## 11) Full unattended lifecycle — `/rite-autocomplete`

package/engine/.gosec.json

@@ -0,0 +1,5 @@
+{
+  "G301": "0755",
+  "G302": "0755",
+  "G306": "0644"
+}

package/engine/Makefile

@@ -0,0 +1,64 @@
+BINARY  := devrites
+DIST    := dist
+GOFILES := $(shell find . -name '*.go' -not -path './$(DIST)/*')
+# darwin/amd64 kept for Intel Macs; the five targets the release matrix ships.
+PLATFORMS := darwin/arm64 darwin/amd64 linux/amd64 linux/arm64 windows/amd64
+
+.PHONY: build fmt-check test test-race vet quality staticcheck govulncheck gosec cover crosscompile clean
+
+STATICCHECK_VERSION := 2025.1.1
+GOVULNCHECK_VERSION := v1.5.0
+GOSEC_VERSION := v2.27.1
+STATICCHECK := go run honnef.co/go/tools/cmd/staticcheck@$(STATICCHECK_VERSION)
+GOVULNCHECK := go run golang.org/x/vuln/cmd/govulncheck@$(GOVULNCHECK_VERSION)
+GOSEC := go run github.com/securego/gosec/v2/cmd/gosec@$(GOSEC_VERSION)
+
+build:
+	CGO_ENABLED=0 go build -o $(BINARY) .
+
+fmt-check:
+	@test -z "$$(gofmt -l $(GOFILES))" || (echo "gofmt required:"; gofmt -l $(GOFILES); exit 1)
+
+test:
+	go test ./...
+
+# Race-enabled run — the engine has concurrent index/source-cache paths; the
+# detector is free signal on every test that touches them.
+test-race:
+	go test -race -count=1 ./...
+
+vet:
+	go vet ./...
+
+# quality is the full local gate — mirror it in CI so a green `make quality`
+# means a green pipeline (the date-sensitive parity golden aside; see ADR-0006).
+quality: fmt-check vet staticcheck govulncheck gosec test-race
+
+staticcheck:
+	$(STATICCHECK) ./...
+
+govulncheck:
+	$(GOVULNCHECK) ./...
+
+gosec:
+	$(GOSEC) -conf .gosec.json -exclude=G204,G304,G702,G703 ./...
+
+# Coverage baseline. No hard floor is wired yet (see ADR-0006): the number is
+# understated because most engine behaviour is exercised through CLI-level
+# integration tests in tests/, which don't attribute to per-package coverage.
+cover:
+	go test ./... -coverprofile=coverage.out -covermode=atomic
+	go tool cover -func=coverage.out | tail -1
+
+# Prove the pure-Go binary cross-compiles to every shipped target with no CGo.
+crosscompile:
+	@mkdir -p $(DIST)
+	@for p in $(PLATFORMS); do \
+		os=$${p%/*}; arch=$${p#*/}; ext=""; \
+		[ "$$os" = windows ] && ext=".exe"; \
+		echo "building $$os/$$arch"; \
+		CGO_ENABLED=0 GOOS=$$os GOARCH=$$arch go build -o $(DIST)/$(BINARY)-$$os-$$arch$$ext . || exit 1; \
+	done
+
+clean:
+	rm -rf $(BINARY) $(DIST)

package/engine/commands.go

@@ -0,0 +1,195 @@
+package main
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"github.com/devrites/devrites/internal/devritespaths"
+	"github.com/devrites/devrites/internal/doctor"
+	"github.com/devrites/devrites/internal/migrate"
+	"github.com/devrites/devrites/internal/state"
+)
+
+// resolveRootLenient resolves the .devrites root for the workspace-orientation
+// commands (preamble / progress / stuck), which must degrade gracefully outside a
+// workspace rather than erroring like the gates do. When no .devrites is found it
+// returns a nonexistent <cwd>/.devrites so the command reads an empty workspace
+// and no-ops (preamble's "No active workspace", progress's silence).
+func resolveRootLenient() string {
+	if root, err := state.ResolveRoot(os.Getenv("DEVRITES_ROOT")); err == nil {
+		return root
+	}
+	cwd, err := os.Getwd()
+	if err != nil {
+		return ".devrites"
+	}
+	return filepath.Join(cwd, devritespaths.DevritesRootName)
+}
+
+func readFile(path string) string {
+	raw, err := os.ReadFile(path)
+	if err != nil {
+		return ""
+	}
+	return string(raw)
+}
+
+func gitDir(projectDir string) string {
+	path := filepath.Join(projectDir, ".git")
+	if info, err := os.Stat(path); err == nil && info.IsDir() {
+		return path
+	}
+	line := strings.TrimSpace(readFile(path))
+	if target, ok := strings.CutPrefix(line, "gitdir:"); ok {
+		target = strings.TrimSpace(target)
+		if filepath.IsAbs(target) {
+			return target
+		}
+		return filepath.Clean(filepath.Join(projectDir, target))
+	}
+	return path
+}
+
+func gitOperation(projectDir string) string {
+	dir := gitDir(projectDir)
+	if _, err := os.Stat(filepath.Join(dir, "MERGE_HEAD")); err == nil {
+		return "merge"
+	}
+	for _, name := range []string{"rebase-merge", "rebase-apply"} {
+		if info, err := os.Stat(filepath.Join(dir, name)); err == nil && info.IsDir() {
+			return "rebase"
+		}
+	}
+	return ""
+}
+
+// cmdDoctor reports the binary / pack / state-schema version triangle and its
+// skew verdict. It exits non-zero only when the state schema is a newer major
+// than the binary can safely parse (a genuine refuse); a mere pack-vs-binary
+// skew is a warning that still exits 0.
+func cmdDoctor(args []string, stdout, stderr io.Writer) int {
+	if len(args) != 0 {
+		fmt.Fprintln(stderr, "usage: devrites-engine doctor")
+		return exitUsage
+	}
+	root, err := state.ResolveRoot(os.Getenv("DEVRITES_ROOT"))
+	if err != nil {
+		fmt.Fprintf(stderr, "devrites: %v\n", err)
+		return exitUsage
+	}
+	// The project directory is the parent of the .devrites root — that is where
+	// an installed pack's version marker (.claude/devrites.version, package.json)
+	// lives.
+	projectDir := filepath.Dir(root)
+	report, err := doctor.Diagnose(projectDir, root)
+	if err != nil {
+		fmt.Fprintf(stderr, "devrites: %v\n", err)
+		return exitUsage
+	}
+	fmt.Fprint(stdout, report.Render())
+	if op := gitOperation(projectDir); op != "" {
+		fmt.Fprintf(stdout, "git-state: %s in progress — resolve with .claude/skills/devrites-lib/reference/standards/git-workflow.md#merge-conflict-recovery\n", op)
+	}
+	for _, warning := range extensionProvenanceWarnings(root) {
+		fmt.Fprintf(stdout, "warning: %s\n", warning)
+	}
+	if slug := strings.TrimSpace(readFile(filepath.Join(root, "ACTIVE"))); slug != "" {
+		if snap, err := state.Snapshot(root, slug); err == nil {
+			fmt.Fprintln(stdout)
+			fmt.Fprintln(stdout, "readiness-dashboard:")
+			fmt.Fprintf(stdout, "  active: %s (%s, %s)\n", snap.Slug, snap.Phase, snap.RunMode)
+			fmt.Fprintf(stdout, "  evidence: %s\n", snap.Evidence.Status)
+			fmt.Fprintf(stdout, "  drift: %s\n", snap.Drift.Status)
+			fmt.Fprintf(stdout, "  review: %s\n", snap.Review.Status)
+			fmt.Fprintf(stdout, "  harness: %s — %s\n", snap.Harness.Status, snap.Harness.Detail)
+			fmt.Fprintf(stdout, "  extensions: %s (%d)\n", snap.Extensions.Status, snap.Extensions.Count)
+			fmt.Fprintf(stdout, "  worktree: %s (%d changed)\n", snap.DirtyWorkspace.Status, snap.DirtyWorkspace.Changed)
+			fmt.Fprintln(stdout, "  capabilities:")
+			for _, cap := range snap.Capabilities {
+				fmt.Fprintf(stdout, "    - %s: %s · used by %s · fallback: %s · risk: %s\n", cap.Name, cap.Status, cap.UsedBy, cap.Fallback, cap.Risk)
+			}
+		}
+	}
+	if report.Refuse {
+		return exitBlocked
+	}
+	return exitOK
+}
+
+// cmdMigrate normalizes workspaces to the current schema. It is idempotent
+// (a second run is a no-op) and backs up the pre-migration state first.
+func extensionProvenanceWarnings(root string) []string {
+	dir := filepath.Join(root, "extensions")
+	entries, err := os.ReadDir(dir)
+	if err != nil {
+		return nil
+	}
+	var warnings []string
+	for _, entry := range entries {
+		if !entry.IsDir() || strings.HasPrefix(entry.Name(), ".") {
+			continue
+		}
+		edir := filepath.Join(dir, entry.Name())
+		hasArtifact := readFile(filepath.Join(edir, "skill", "SKILL.md")) != "" || readFile(filepath.Join(edir, "agent.md")) != "" || readFile(filepath.Join(edir, "component.yaml")) != ""
+		if hasArtifact && readFile(filepath.Join(edir, "provenance.json")) == "" {
+			warnings = append(warnings, fmt.Sprintf("extension %s has no provenance.json", entry.Name()))
+		}
+	}
+	return warnings
+}
+
+func cmdMigrate(args []string, stdout, stderr io.Writer) int {
+	if len(args) != 0 {
+		fmt.Fprintln(stderr, "usage: devrites-engine migrate")
+		return exitUsage
+	}
+	root, err := state.ResolveRoot(os.Getenv("DEVRITES_ROOT"))
+	if err != nil {
+		fmt.Fprintf(stderr, "devrites: %v\n", err)
+		return exitUsage
+	}
+	result, err := migrate.Run(root)
+	if err != nil {
+		fmt.Fprintf(stderr, "devrites: migrate failed: %v\n", err)
+		return 1
+	}
+	if result.Skipped {
+		fmt.Fprintln(stdout, "migrate: already up to date (no workspace normalization needed)")
+		return exitOK
+	}
+	fmt.Fprintf(stdout, "migrated %d feature(s): %v\n", len(result.Migrated), result.Migrated)
+	fmt.Fprintf(stdout, "backup: %s\n", result.BackupDir)
+	return exitOK
+}
+
+func cmdSnapshot(args []string, stdout, stderr io.Writer) int {
+	if len(args) > 1 {
+		fmt.Fprintln(stderr, "usage: devrites-engine snapshot [slug]")
+		return exitUsage
+	}
+	root, err := state.ResolveRoot(os.Getenv("DEVRITES_ROOT"))
+	if err != nil {
+		fmt.Fprintf(stderr, "devrites: %v\n", err)
+		return exitUsage
+	}
+	slug := ""
+	if len(args) == 1 {
+		slug = args[0]
+	}
+	snapshot, err := state.Snapshot(root, slug)
+	if err != nil {
+		fmt.Fprintf(stderr, "devrites: %v\n", err)
+		return exitUsage
+	}
+	data, err := json.MarshalIndent(snapshot, "", "  ")
+	if err != nil {
+		fmt.Fprintf(stderr, "devrites: cannot render snapshot JSON: %v\n", err)
+		return exitUsage
+	}
+	_, _ = stdout.Write(append(data, '\n'))
+	return exitOK
+}

package/engine/go.mod

@@ -0,0 +1,5 @@
+module github.com/devrites/devrites
+
+go 1.26
+
+toolchain go1.26.5

package/engine/harnessmatrix.go

@@ -0,0 +1,60 @@
+package main
+
+import (
+	"fmt"
+	"io"
+	"os"
+	"strings"
+
+	"github.com/devrites/devrites/internal/harness"
+)
+
+// cmdHarnessMatrix renders the harness adapter-compliance matrix, or (with
+// --check FILE) verifies the generated block committed in FILE still matches the
+// engine's frozen matrix. The check is the drift guard: an edit to the matrix
+// data without regenerating the doc — or vice versa — fails CI.
+//
+// Exit: 0 rendered / in-sync · 2 usage · 3 drift (regenerate + commit).
+func cmdHarnessMatrix(args []string, stdout, stderr io.Writer) int {
+	block := harness.RenderMatrix()
+
+	if len(args) == 0 {
+		fmt.Fprintln(stdout, block)
+		return exitOK
+	}
+	if len(args) != 2 || args[0] != "--check" {
+		fmt.Fprintln(stderr, "usage: devrites-engine harness-matrix [--check <file>]")
+		return exitUsage
+	}
+	path := args[1]
+	data, err := os.ReadFile(path)
+	if err != nil {
+		fmt.Fprintf(stderr, "devrites: harness-matrix: %v\n", err)
+		return exitUsage
+	}
+	got, ok := extractBlock(string(data), harness.MatrixBeginMarker, harness.MatrixEndMarker)
+	if !ok {
+		fmt.Fprintf(stderr, "harness-matrix: no generated block found in %s (expected the BEGIN/END markers)\n", path)
+		return exitBlocked
+	}
+	if strings.TrimSpace(got) != strings.TrimSpace(block) {
+		fmt.Fprintf(stderr, "harness-matrix: %s is out of date — run `devrites-engine harness-matrix` and commit the regenerated block.\n", path)
+		return exitBlocked
+	}
+	fmt.Fprintf(stdout, "harness-matrix: %s is in sync.\n", path)
+	return exitOK
+}
+
+// extractBlock returns the text from begin to end inclusive, or ok=false if
+// either marker is absent or out of order.
+func extractBlock(s, begin, end string) (string, bool) {
+	i := strings.Index(s, begin)
+	if i < 0 {
+		return "", false
+	}
+	j := strings.Index(s[i:], end)
+	if j < 0 {
+		return "", false
+	}
+	return s[i : i+j+len(end)], true
+}