devrites 2.6.0 → 3.0.0

package/bin/devrites.mjs

@@ -1,27 +1,23 @@
 #!/usr/bin/env node
-// devrites — npx entry point for the DevRites installer.
-//
-// A thin shim over the bundled bash installers. The npm package ships
-// install.sh / uninstall.sh / update.sh alongside pack/ and scripts/, so the
-// installer's network-bootstrap branch is skipped and the install runs offline,
-// locked to whatever @version was invoked. The bash scripts remain the single
-// source of truth for all install logic, flags, manifest, and guards.
+// devrites - npx entry point for the engine-owned DevRites installer.
 import { spawnSync } from 'node:child_process';
-import { fileURLToPath } from 'node:url';
+import { createHash } from 'node:crypto';
+import { chmodSync, existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
-import { existsSync, readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
 
 const here = dirname(fileURLToPath(import.meta.url));
-const root = dirname(here); // bin/ -> package root
+const root = dirname(here);
 
-const SUBCOMMANDS = {
-  install: 'install.sh',
-  add: 'install.sh',
-  uninstall: 'uninstall.sh',
-  remove: 'uninstall.sh',
-  update: 'update.sh',
-  upgrade: 'update.sh',
-};
+const SUBCOMMAND_ALIASES = new Map([
+  ['install', 'install'],
+  ['add', 'install'],
+  ['update', 'update'],
+  ['upgrade', 'update'],
+  ['uninstall', 'uninstall'],
+  ['remove', 'uninstall'],
+]);
 
 function pkgVersion() {
   try {
@@ -32,36 +28,123 @@ function pkgVersion() {
 }
 
 function printHelp() {
-  process.stdout.write(`devrites — install the full DevRites pack into a project
+  process.stdout.write(`devrites - install the DevRites pack into a project
 
 Usage:
-  npx devrites [install] [flags]   Install skills + agents + rules + hooks (default)
+  npx devrites [install] [flags]   Install skills + agents + standards + hooks (default)
   npx devrites uninstall [flags]   Remove a DevRites install (preserves .devrites/ state)
   npx devrites update [flags]      Upgrade an existing install in place
 
-Common flags (passed straight through to the installer):
+Common flags:
   --target DIR          Install into DIR (default: current directory)
   --dry-run             Show the plan, change nothing
   --force               Overwrite existing non-DevRites files
-  --rules-only          Install only the engineering rules
   --no-codex            Skip Codex support files (.agents, .codex, AGENTS.md)
   --short-aliases=all   Also install /define /build /prove /seal
   --no-agents           Skip the review subagents
+  --no-skills           Skip skills and bundled engineering standards
+  --no-binary           Skip installing the global devrites-engine binary
+  --no-rules            Deprecated no-op; standards ship inside devrites-lib
+  --rules-only          Deprecated no-op; installs normally for compatibility
 
   --version             Print the devrites version
-  --help                Show this help (use "<subcommand> --help" for installer-level detail)
-
-DevRites is project-local — it never writes to ~/.claude or ~/.codex.
-Requires bash (Git Bash or WSL on Windows). No-Node fallback:
-  curl -fsSL https://raw.githubusercontent.com/ViktorsBaikers/DevRites/main/install.sh | bash
+  --help                Show this help
 `);
 }
 
+function run(command, args, options = {}) {
+  return spawnSync(command, args, { stdio: options.stdio || 'inherit', cwd: options.cwd || process.cwd(), env: options.env || process.env });
+}
+
+function firstWorking(candidates, args, env = process.env) {
+  let lastError = null;
+  for (const candidate of candidates.filter(Boolean)) {
+    const res = run(candidate, args, { env });
+    if (!res.error) process.exit(res.status === null ? 1 : res.status);
+    lastError = res.error;
+    if (res.error.code !== 'ENOENT') break;
+  }
+  return lastError;
+}
+
+async function acquireEngine() {
+  const envEngine = process.env.DEVRITES_ENGINE_CLI || process.env.DEVRITES_CLI;
+  if (envEngine && existsSync(envEngine)) return envEngine;
+
+  const localBuilt = join(root, 'engine', 'devrites-engine');
+  if (existsSync(localBuilt)) return localBuilt;
+
+  const downloaded = await downloadEngine();
+  if (downloaded) return downloaded;
+
+  const engineDir = join(root, 'engine');
+  if (existsSync(join(engineDir, 'go.mod'))) {
+    const goBin = findGo();
+    const out = join(mkdtempSync(join(tmpdir(), 'devrites-engine-')), process.platform === 'win32' ? 'devrites-engine.exe' : 'devrites-engine');
+    const tag = `v${pkgVersion().replace(/^v/, '')}`;
+    if (goBin) {
+      const env = { ...process.env, GOCACHE: join(dirname(out), 'go-cache'), CGO_ENABLED: '0' };
+      const build = run(goBin, [
+        'build',
+        '-trimpath',
+        '-ldflags',
+        `-s -w -X github.com/devrites/devrites/internal/version.Version=${tag}`,
+        '-o',
+        out,
+        '.',
+      ], { cwd: engineDir, stdio: 'ignore', env });
+      if (!build.error && build.status === 0) return out;
+    }
+  }
+
+  return 'devrites-engine';
+}
+
+function findGo() {
+  const direct = run('go', ['version'], { stdio: 'ignore' });
+  if (!direct.error && direct.status === 0) return 'go';
+  return null;
+}
+
+async function downloadEngine() {
+  const platform = process.platform === 'darwin' ? 'darwin' : process.platform === 'linux' ? 'linux' : process.platform === 'win32' ? 'windows' : null;
+  const arch = process.arch === 'x64' ? 'amd64' : process.arch === 'arm64' ? 'arm64' : null;
+  if (!platform || !arch) return null;
+  const repo = process.env.DEVRITES_REPO || 'ViktorsBaikers/DevRites';
+  const tag = process.env.DEVRITES_REF || `v${pkgVersion().replace(/^v/, '')}`;
+  const name = `devrites-${platform}-${arch}${platform === 'windows' ? '.exe' : ''}`;
+  const dir = mkdtempSync(join(tmpdir(), 'devrites-engine-'));
+  const out = join(dir, platform === 'windows' ? 'devrites-engine.exe' : 'devrites-engine');
+  const url = `https://github.com/${repo}/releases/download/${tag}/${name}`;
+  if (!await downloadURL(url, out, 0o755)) return null;
+  if (!await downloadURL(`${url}.sha256`, `${out}.sha256`)) return null;
+  const want = readFileSync(`${out}.sha256`, 'utf8').trim().split(/\s+/)[0];
+  const got = createHash('sha256').update(readFileSync(out)).digest('hex');
+  if (!want || got !== want) {
+    rmSync(out, { force: true });
+    return null;
+  }
+  chmodSync(out, 0o755);
+  return out;
+}
+
+async function downloadURL(url, out, mode = 0o644) {
+  try {
+    const res = await fetch(url);
+    if (!res.ok) throw new Error(`${res.status} ${res.statusText}`);
+    writeFileSync(out, Buffer.from(await res.arrayBuffer()), { mode });
+    return true;
+  } catch {
+    rmSync(out, { force: true });
+    return false;
+  }
+}
+
 const argv = process.argv.slice(2);
 const first = argv[0];
 
 if (first === '--version' || first === '-v') {
-  process.stdout.write(pkgVersion() + '\n');
+  process.stdout.write(`${pkgVersion()}\n`);
   process.exit(0);
 }
 if (first === '--help' || first === '-h') {
@@ -69,33 +152,34 @@ if (first === '--help' || first === '-h') {
   process.exit(0);
 }
 
-// Route the subcommand; default to install when the first arg is a flag or absent.
-let sub = 'install';
+let command = 'install';
 let rest = argv;
-if (first && Object.prototype.hasOwnProperty.call(SUBCOMMANDS, first)) {
-  sub = first;
+if (first && SUBCOMMAND_ALIASES.has(first)) {
+  command = SUBCOMMAND_ALIASES.get(first);
+  rest = argv.slice(1);
+} else if (first && !first.startsWith('-')) {
+  command = first;
   rest = argv.slice(1);
 }
 
-const script = join(root, SUBCOMMANDS[sub]);
-if (!existsSync(script)) {
-  console.error(`devrites: bundled ${SUBCOMMANDS[sub]} not found at ${script}`);
-  console.error('devrites: the package looks incomplete — reinstall, or use the curl | bash installer.');
-  process.exit(1);
+const engine = await acquireEngine();
+const payloadDir = process.env.DEVRITES_HOST_ARTIFACT_DIR || join(root, 'pack', 'generated');
+const installerCommand = command === 'install' || command === 'update' || command === 'uninstall';
+const engineEnv = { ...process.env, DEVRITES_ENGINE_CLI: engine };
+const args = [command];
+if (installerCommand) {
+  args.push('--source-dir', root);
 }
-
-const res = spawnSync('bash', [script, ...rest], { stdio: 'inherit', cwd: process.cwd() });
-
-if (res.error) {
-  if (res.error.code === 'ENOENT') {
-    console.error('devrites: `bash` was not found on your PATH.');
-    console.error('DevRites is bash-based. On Windows, run inside Git Bash or WSL,');
-    console.error('or use the no-Node installer:');
-    console.error('  curl -fsSL https://raw.githubusercontent.com/ViktorsBaikers/DevRites/main/install.sh | bash');
-    process.exit(127);
-  }
-  console.error('devrites: failed to launch installer:', res.error.message);
-  process.exit(1);
+if (command === 'install' || command === 'update') {
+  args.push('--payload-dir', payloadDir);
 }
+args.push(...rest);
 
-process.exit(res.status === null ? 1 : res.status);
+const candidates = [engine, 'devrites-engine'];
+const lastError = firstWorking(candidates, args, engineEnv);
+if (lastError && lastError.code !== 'ENOENT') {
+  console.error('devrites: failed to launch devrites-engine:', lastError.message);
+} else {
+  console.error('devrites: devrites-engine was not found and could not be acquired.');
+}
+process.exit(127);

package/docs/agents/domain.md

@@ -0,0 +1,58 @@
+# Domain Docs
+
+How the engineering skills should consume this repo's domain documentation when exploring the codebase.
+
+## Before exploring, read these
+
+- **`CONTEXT.md`** at the repo root, or
+- **`CONTEXT-MAP.md`** at the repo root if it exists — it points at one `CONTEXT.md` per context. Read each one relevant to the topic.
+- **`docs/adr/`** — read ADRs that touch the area you're about to work in. In multi-context repos, also check `src/<context>/docs/adr/` for context-scoped decisions.
+
+If any of these files don't exist, **proceed silently**. Don't flag their absence; don't suggest creating them upfront. DevRites creates or updates domain records lazily when a feature resolves a durable term, ambiguity, or decision.
+
+## File structure
+
+Single-context repo (most repos):
+
+```
+/
+├── CONTEXT.md
+├── docs/adr/
+│   ├── 0001-event-sourced-orders.md
+│   └── 0002-postgres-for-write-model.md
+└── src/
+```
+
+Multi-context repo (presence of `CONTEXT-MAP.md` at the root):
+
+```
+/
+├── CONTEXT-MAP.md
+├── docs/adr/                          ← system-wide decisions
+└── src/
+    ├── ordering/
+    │   ├── CONTEXT.md
+    │   └── docs/adr/                  ← context-specific decisions
+    └── billing/
+        ├── CONTEXT.md
+        └── docs/adr/
+```
+
+## Use the glossary's vocabulary
+
+When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined in `CONTEXT.md`. Don't drift to synonyms the glossary explicitly avoids.
+
+If the concept you need isn't in the glossary yet, that's a signal — either you're inventing language the project doesn't use (reconsider) or there's a real gap. Update `CONTEXT.md` only when the term is durable enough to help future work.
+
+## Maintain domain records only when they earn it
+
+- New durable term → add it to `CONTEXT.md` with any avoided synonyms.
+- Two terms collide → add a flagged ambiguity and the resolved canonical term.
+- Decision constrains future work → add or update an ADR.
+- One-off implementation detail → leave it out.
+
+## Flag ADR conflicts
+
+If your output contradicts an existing ADR, surface it explicitly rather than silently overriding:
+
+> _Contradicts ADR-0007 (event-sourced orders) — but worth reopening because…_

package/docs/agents/issue-driven-rites.md

@@ -0,0 +1,11 @@
+# Issue-driven rites
+
+Local issue files are the source of truth; external trackers are references only.
+
+## Flow
+
+1. Create `.scratch/<slug>/issue.md` for the problem and optional `.scratch/<slug>/prd.md` for product detail.
+2. Start `/rite-spec <slug>` from those files; copy decisions into `.devrites/work/<slug>/`, not back to the tracker.
+3. Run the normal lifecycle: `/rite-define` → `/rite-vet` → `/rite-build` → `/rite-prove` → `/rite-review` → `/rite-seal`.
+4. `/rite-ship` may include `Closes #NNN` only after a recorded type-GO.
+5. Follow-ups go to a new local `.scratch/<next-slug>/issue.md` first; external auto-posting is out of scope.

package/docs/agents/issue-tracker.md

@@ -0,0 +1,29 @@
+# Issue tracker: Local Markdown
+
+Issues and PRDs for this repo live as markdown files in `.scratch/`. For the end-to-end local issue → rites flow, see [issue-driven-rites.md](issue-driven-rites.md).
+
+## Conventions
+
+- One feature per directory: `.scratch/<feature-slug>/`
+- The PRD is `.scratch/<feature-slug>/PRD.md`
+- Implementation issues are `.scratch/<feature-slug>/issues/<NN>-<slug>.md`, numbered from `01`
+- Triage state is recorded as a `Status:` line near the top of each issue file (see `triage-labels.md` for the role strings)
+- Comments and conversation history append to the bottom of the file under a `## Comments` heading
+
+## When a skill says "publish to the issue tracker"
+
+Create a new file under `.scratch/<feature-slug>/` (creating the directory if needed).
+
+## When a skill says "fetch the relevant ticket"
+
+Read the file at the referenced path. The user will normally pass the path or the issue number directly.
+
+## Investigation maps
+
+For huge, foggy efforts, `/rite-pressure-test` may create an **investigation map** instead of pretending one session can settle the whole thing. No separate map command exists.
+
+- **Map**: `.scratch/<effort>/map.md` with `Destination`, `Decisions so far`, `Not yet specified`, and `Out of scope`.
+- **Child ticket**: `.scratch/<effort>/issues/NN-<slug>.md`, numbered from `01`, with one research/prototype/grilling/task question in the body. A `Type:` line records the ticket type; a `Status:` line records `open`/`claimed`/`resolved`.
+- **Frontier**: one ticket per session. Pick the first open, unblocked, unclaimed ticket by number.
+- **Blocking**: `Blocked by: NN, NN` near the top. A ticket is unblocked when every listed ticket is `resolved`.
+- **Resolve**: append `## Answer`, set `Status: resolved`, then add a one-line context pointer to `map.md` under `Decisions so far`.

package/docs/agents/triage-labels.md

@@ -0,0 +1,15 @@
+# Triage Labels
+
+The skills speak in terms of five canonical triage roles. This file maps those roles to the actual label strings used in this repo's issue tracker.
+
+| Label in mattpocock/skills | Label in our tracker | Meaning                                  |
+| -------------------------- | -------------------- | ---------------------------------------- |
+| `needs-triage`             | `needs-triage`       | Maintainer needs to evaluate this issue  |
+| `needs-info`               | `needs-info`         | Waiting on reporter for more information |
+| `ready-for-agent`          | `ready-for-agent`    | Fully specified, ready for an AFK agent  |
+| `ready-for-human`          | `ready-for-human`    | Requires human implementation            |
+| `wontfix`                  | `wontfix`            | Will not be actioned                     |
+
+When a skill mentions a role (e.g. "apply the AFK-ready triage label"), use the corresponding label string from this table.
+
+Edit the right-hand column to match whatever vocabulary you actually use.

package/docs/architecture.md

@@ -5,6 +5,10 @@ that make an AI coding agent behave like a disciplined senior engineer: clarify
 spec+plan → build one verified slice → prove with evidence → polish → review → seal →
 ship.
 
+For the `.devrites/` load order, file budgets, artifact schema, aliases,
+traceability rules, and phase-relative completeness model, see
+[`engine/workspace-schema.md`](engine/workspace-schema.md).
+
 ## Layers
 
 1. **Public workflow skills** — `.claude/skills/rite-*`, `user-invocable: true`. Each
@@ -19,8 +23,8 @@ ship.
    clears `ACTIVE`). Keeping the decision and the irreversible action as two
    separately-auditable steps is the point.
 2. **Public utility skills** — `.claude/skills/rite-zoom-out`,
-   `rite-prototype`, `rite-handoff`, `rite-pressure-test`, and
-   `rite-autocomplete` — public commands. `rite-autocomplete` is the
+   `rite-prototype`, `rite-handoff`, `rite-pressure-test`, `rite-pov`,
+   `rite-dogfood`, `rite-pr-feedback`, and `rite-autocomplete` — public commands. `rite-autocomplete` is the
    unattended orchestrator: it drives the whole lifecycle (spec → … → seal →
    ship) end-to-end, choosing the best option at each soft gate, pausing only
    on hard irreversible-risk / blocking / escalating gates or a NO-GO. The
@@ -38,9 +42,9 @@ ship.
    internal is governed by the `user-invocable:` flag, not by the name
    prefix.
 
-   Engineering rules live at `.claude/rules/` (each `rite-*` skill Reads
-   `.claude/rules/core.md` as its first step; the other 15 files load on
-   demand — no session-start autoload). Parallel reviewer fan-out at
+   Engineering rules live at `.claude/skills/devrites-lib/reference/standards/`.
+   Workspace-operating lifecycle rites load `core.md` first and disclose phase-specific
+   files on demand; compact utilities keep a narrower local contract. Parallel reviewer fan-out at
    `/rite-seal` is a reference file
    (`rite-seal/reference/parallel-dispatch.md`), not a skill.
 4. **Supporting references** — `reference/*.md` inside each skill. Long checklists,
@@ -58,44 +62,60 @@ ship.
    dispatched by `/rite-build` to write one slice in a clean context (the write-side mirror of
    the reviewers).
 6. **Engineering rules** — DevRites' own stack-agnostic rules installed to
-   `.claude/rules/`. Each `rite-*` skill Reads `core.md` as its first step
-   (step 0); 22 on-demand files load by the phase that needs them:
+   `.claude/skills/devrites-lib/reference/standards/`. Workspace-operating lifecycle
+   skills read `core.md` in step 0; compact utilities load only their local or conditional
+   rules. On-demand files load by the phase that needs them:
    - **Craft:** `coding-style.md` · `prose-style.md` · `patterns.md` · `error-handling.md` ·
-     `testing.md` · `spec-grammar.md` · `documentation.md`.
+     `testing.md` · `spec-grammar.md` · `documentation.md` · `skill-authoring.md`.
    - **Quality / safety:** `code-review.md` · `principles.md` · `security.md` ·
      `performance.md` · `observability.md` · `developer-experience.md` · `deprecation.md` ·
      `anti-patterns.md`.
    - **Workflow / ops:** `development-workflow.md` · `git-workflow.md` ·
-     `hooks.md` · `agents.md` · `context-hygiene.md` · `afk-hitl.md` · `tooling.md`.
+     `ci-cd.md` · `hooks.md` · `agents.md` · `context-hygiene.md` · `afk-hitl.md` ·
+     `tooling.md` · `elicitation.md`.
+   - **Checklists:** `definition-of-done.md` · `review-checklist.md` ·
+     `test-proof-checklist.md` · `browser-proof-checklist.md` · `security-checklist.md`.
    - **Index:** `README.md` (phase mapping, loading model).
 
 State lives in `.devrites/` as human-readable Markdown so it survives context
 compaction and new sessions. The optional `.devrites/AFK` sentinel toggles
 the session-level run mode (see "Run modes" below). See `usage.md` for the
-workspace file list, and [`command-map.md`](command-map.md) for the full
-per-skill catalog with triggers + I/O.
+workspace file list, [`command-map.md`](command-map.md) for the full
+per-skill catalog with triggers + I/O, and
+[`capability-surface-selection.md`](capability-surface-selection.md) for where future
+capabilities belong.
 
 ## Design rationale
 
-### Why a shared orientation preamble (`devrites-lib`)
+### Why the engine owns shared orientation (`devrites-lib`)
 Every workspace-operating skill's first move is the same: orient on the active feature —
 slug, phase, artifacts present, run mode, open-question tally — before acting. Re-deriving
 that from raw Markdown in each skill was duplicated (step-0 prose across ~20 skills),
 token-heavy (counting open gates meant re-reading the append-only `questions.md`, which
 only grows), and error-prone (a missed AFK sentinel or a miscounted gate changes behavior).
-So orientation is computed once by one read-only script, `devrites-lib/scripts/preamble.sh`,
-which prints a compact digest each skill reads at step 0. `devrites-lib` is an internal
-library skill (`user-invocable: false`, not a command) that houses the cross-cutting
-scripts — the preamble, the read-only gate scripts (`readiness.sh` / `evidence-fresh.sh` /
-`check-acceptance.sh`), the state mutators (`tick-afk.sh` / `resolve.sh` / `close-out.sh`),
-and the unified `devrites.sh` CLI that dispatches to all of them — *inside* `skills/` so
-they ship on both the bash-installer and plugin channels. Skills resolve them with a three-layout snippet (installed `.claude/` → plugin
-`${CLAUDE_SKILL_DIR}` → repo `pack/`). Bundled-script execution is reliable on the
-bash-installer channel (CWD-relative `.claude/`); Claude Code does **not** expose a stable
-script path to skill-invoked bash on the plugin channel (only to hooks — confirmed against
-`anthropics/claude-code` issues #48230 / #38699), so there the preamble is best-effort via
-`${CLAUDE_SKILL_DIR}` and degrades gracefully to reading `state.md` directly. The preamble is read-only; all mutation stays in
-the dedicated scripts.
+So orientation is computed once by the `devrites-engine` binary, which prints a compact
+digest each skill reads at step 0. The same binary owns the read-only gates
+(`build-readiness`, `evidence-fresh`, `check-acceptance`) and state mutators
+(`tick-afk`, `resolve`, `close-out`), so Claude Code, Codex, CI, and humans
+all exercise the same control plane. `devrites-lib` remains an internal library skill
+(`user-invocable: false`, not a command) for shared references. The orientation
+path is read-only; mutation stays in dedicated engine subcommands.
+
+### Why the engine owns install/update/uninstall semantics
+Install/update/uninstall behavior lives in `engine/internal/install`: manifest writing
+and pruning, shared-file marker merge/removal, Codex hook merge/removal, dry-run output,
+binary lifecycle, and update flag replay all execute through `devrites-engine`. The
+shell entrypoints (`install.sh`, `uninstall.sh`, `update.sh`) and npm entrypoint
+(`bin/devrites.mjs`) remain bootstrap shims: they acquire a release bundle or engine
+binary, then pass arguments through.
+
+Some duplication is intentionally preserved at host boundaries. Raw `curl | bash`
+install/uninstall must be self-contained enough to fetch the bundle before any sibling
+files exist. Claude assets are authored under `pack/.claude/**`; Codex assets are
+generated into `pack/generated/**` and installed to `.agents/skills`, `.codex/agents`,
+`.codex/hooks.json`, and `AGENTS.md` because Codex and Claude use
+different project-local conventions. Those generated host artifacts are delivered by the
+npm installer; Claude/Codex plugin packaging is intentionally not a distribution path.
 
 ### Why `/engine` was rejected
 A single `/engine` (or `/devrites`) mega-command would load every phase's instructions
@@ -125,15 +145,17 @@ are **disciplines**, not user commands. As `user-invocable: false` skills they:
   trigger conditions hit;
 - keep each public `SKILL.md` small by housing the heavy process elsewhere.
 
-### Why spec and plan are separate phases (`/rite-spec`, `/rite-define`, `/rite-plan`)
+### Why spec, architecture, plan, tasks, and traceability are separate artifacts
 Doing investigation, spec, plan, and slicing in one batch lets things slip — a gap goes
 unasked, placement is guessed, a slice misses a requirement. DevRites splits them so each
-is focused and gated. `/rite-spec` **investigates deeply and writes `spec.md`** (what/why,
-placement, issues, gaps closed with the user, design references) and must pass its
-readiness gate. `/rite-define` then turns that **approved spec** into `plan.md` +
-`tasks.md` (the how + vertical slices), checking every acceptance criterion maps to a
-slice. The spec is fully covered before any planning begins. `/rite-plan` is the separate
-repair/reslice/re-order tool for an *active* plan when it goes stale or drifts.
+is focused and gated. `/rite-spec` **investigates deeply and writes `spec.md`** (product
+what/why, requirements, acceptance, non-goals, measurable success) and must pass its
+readiness gate. `/rite-define` then turns that **approved spec** into `architecture.md`
+(technical map), `plan.md` (approach), `tasks.md` (vertical `SLICE-###` work), and
+`traceability.md` (AC/REQ → slice → proof → evidence → files). The spec is fully covered
+before any building begins, but it does not become a long technical omnibus. `/rite-plan`
+is the separate repair/reslice/re-order tool for an *active* plan when it goes stale or
+drifts.
 
 ### Why `/rite-polish` is one skill with two progressive-disclosure halves
 Polish has two natural halves — **code** (simplify, dead code, naming, plus
@@ -211,12 +233,12 @@ keeps the loop alive when the answer can wait, and pauses hard when it can't. Th
 "AFK never silently accepts irreversible risk" rule — destructive migrations,
 auth/authz boundaries, public API breaks, red tests/types/lint — always pauses
 regardless of the sentinel. See
-[`pack/.claude/rules/afk-hitl.md`](../pack/.claude/rules/afk-hitl.md) for the full
+[`pack/.claude/skills/devrites-lib/reference/standards/afk-hitl.md`](../pack/.claude/skills/devrites-lib/reference/standards/afk-hitl.md) for the full
 contract.
 
 ## Design choices at a glance
 
-- **Surface**: 24 public `rite-*` skills (36 total) — the thin `/rite` menu
+- **Surface**: 29 public `rite-*` skills (42 total) — the thin `/rite` menu
   (carries the routing) + 8 lifecycle phases (`rite-spec`, `rite-define`,
   `rite-build`, `rite-prove`, `rite-polish`, `rite-review`, `rite-seal`,
   `rite-ship` — seal **decides**, ship **executes + closes**) + the
@@ -224,6 +246,9 @@ contract.
   reviews + the `rite-quick` express lane and `rite-frame` pre-flight/self-audit
   lens + `rite-adopt` (onboard an existing codebase) + `rite-learn` (cross-feature
   lessons) + `rite-status` + `rite-doctor` (install health) +
+  `rite-customize` (project-local overrides/extensions) +
+  `rite-pov` (external-option verdicts) + `rite-dogfood` (browser QA) +
+  `rite-pr-feedback` (review-thread closure) +
   the `rite-plan` replan verb + the `rite-resolve` resume verb + 4 ideation /
   handoff utilities (`rite-zoom-out`, `rite-prototype`, `rite-handoff`,
   `rite-pressure-test`) + `rite-autocomplete` (the unattended full-lifecycle
@@ -275,4 +300,4 @@ acceptance criteria.
 See the top-level tree in `README.md` and the installed-target tree in `usage.md`.
 Source pack lives under `pack/.claude/` (skills, agents, and rules); the installer copies
 it into a target project's `.claude/`, including DevRites' engineering rules in
-`.claude/rules/`.
+`.claude/skills/devrites-lib/reference/standards/`.

package/docs/capability-surface-selection.md

@@ -0,0 +1,18 @@
+# Capability surface selection
+
+Pick the smallest surface that keeps the behavior deterministic:
+
+| Need | Put it in |
+|---|---|
+| Deterministic gate or state mutation | `devrites-engine` command |
+| Workflow judgment inside the current context | skill |
+| Fresh-context judgment or adversarial review | agent |
+| Optional repeated structured external tool | MCP |
+| One-shot local deterministic action | script or engine subcommand |
+
+Rules:
+
+- Install and update through npm: `npx devrites ...`. No Claude/Codex plugin path.
+- Prefer the engine for gates; prompts may call gates, not reimplement them.
+- Prefer scripts for repo-local release/build glue that is not part of the user contract.
+- Do not add a dependency for what the Go engine or shell can do in a few lines.

package/docs/cli.md

@@ -0,0 +1,53 @@
+# Tool-agnostic state core — the `devrites-engine` CLI
+
+DevRites' discipline lives in `.devrites/` Markdown files and the `devrites-engine`
+engine binary, not in one chat harness. Any tool — Claude Code, Codex, Cursor,
+Gemini CLI, CI, or a human — can drive the same deterministic gates from the
+project root.
+
+## The `devrites-engine` CLI
+
+Install DevRites normally, then run the engine from the project root:
+
+```bash
+devrites-engine preamble                 # workspace digest for the active feature
+devrites-engine snapshot [slug]          # machine-readable workspace/status snapshot
+devrites-engine build-readiness [slug]   # build-readiness gate      (exit 0 ready)
+devrites-engine evidence-fresh [slug]    # proof freshness gate      (exit 0 fresh · 3 stale)
+devrites-engine check-acceptance <dir>   # acceptance gate           (exit 0 proven · 1 gap)
+devrites-engine ledger sync <dir>        # fold a feature's spec deltas into the living capability ledger
+devrites-engine ledger list|show <cap>   # read the ledger — what the system already does
+devrites-engine context show --json      # report root, active workspace, and host command forms
+devrites-engine timeline log|list        # append/list session events, decisions, and state moves
+devrites-engine health record|list       # append/list compact workspace health history
+devrites-engine review-fingerprints [slug] # stable IDs for review findings; --write saves JSONL
+devrites-engine progress [slug]          # compact phase/slice footer
+devrites-engine resolve <qid> "<answer>" # answer a HITL gate
+devrites-engine close-out <slug>         # archive a shipped feature and clear ACTIVE
+devrites-engine help
+```
+
+The AFK-parsed read commands (`status`, `readiness`, `seal`, `spec-validate`,
+`evidence-fresh`, `preamble`, `coverage`, `analyze`, `doctor`, `ledger`) accept
+`--json`, which wraps the result in a stable envelope — see
+[`engine/agent-contract.md`](engine/agent-contract.md). `snapshot` is already a
+structured JSON contract and emits `schemaVersion: devrites.workspace.v1`
+directly rather than wrapping human text. Snapshot consumers should read
+`nextCommands.claude` or `nextCommands.codex` for the current host instead of
+hardcoding a `/rite-*` or `$rite-*` command form.
+
+The npm `devrites` shim remains the installer/updater/uninstaller entry point and
+proxies these engine subcommands when `devrites-engine` is installed. Install and
+update DevRites through `npx devrites ...`; DevRites is not distributed through
+Claude or Codex plugin stores.
+
+The exit code is the gate. A non-zero `build-readiness`,
+`evidence-fresh`, or `check-acceptance` result is a hard stop that can be used
+in an agent loop, a local script, or pre-merge CI.
+
+## Why this exists
+
+DevRites workspaces and standards are tool-agnostic data. The CLI makes that
+workflow drivable from agent loops, local scripts, CI, and humans without
+reimplementing the discipline. A verdict from the CLI or a `rite-*` workflow
+should agree because they run the same engine gates.