devrites 1.19.0

package/SECURITY.md

@@ -0,0 +1,193 @@
+# Security policy
+
+## Reporting a vulnerability
+
+If you believe you have found a security issue in DevRites, please report it
+**privately**. Do not open a public GitHub issue.
+
+- **Preferred channel:** open a private security advisory on GitHub —
+  <https://github.com/ViktorsBaikers/DevRites/security/advisories/new>.
+- **Alternate channel:** email the maintainer via the contact link on the
+  GitHub profile <https://github.com/ViktorsBaikers>.
+
+Please include:
+
+- A clear description of the vulnerability and its impact.
+- A minimal reproduction (commands, files, or a target project layout).
+- The DevRites version (commit SHA or release tag) and Claude Code version.
+- Your name / handle for credit (optional).
+
+You should receive an acknowledgement within **5 business days** and a triage
+verdict within **14 days**. Coordinated disclosure window is **90 days** from
+the acknowledgement unless a shorter or longer window is mutually agreed.
+
+## Supported versions
+
+DevRites is pre-1.0. Only the latest minor release line receives security
+updates.
+
+| Version | Supported |
+|---|---|
+| `0.1.x` | yes |
+| earlier | no |
+
+Once a `1.0` release ships, the latest two minor lines will be supported.
+
+## DevRites security model
+
+### Scope
+
+DevRites is a Claude Code **skills pack**: Markdown skill files, a few helper
+shell scripts, a bash installer, and (in plugin form) a `.claude-plugin/`
+manifest. It ships **no binary and no network service**. The only server is an
+**optional, opt-in MCP stdio server** (`mcp/devrites-mcp.mjs`) that speaks
+JSON-RPC over stdin/stdout (no port, no socket), is not installed or registered
+by default, and only shells out to the local `devrites` CLI — read/gate ops over
+`.devrites/` plus a single `ACTIVE`-pointer write. The attack surface is the
+content of the skill files plus the installer.
+
+### Supply-chain self-scan (shipped pack)
+
+Because the skill files **are** the attack surface, CI scans the shipped pack
+(`pack/.claude/`) on every PR and fails the build (blocking, not advisory) on:
+
+- **Prompt-injection patterns** — the "ignore previous instructions" family,
+  system-prompt overrides, permission-escalation, and data-exfiltration phrasing.
+- **Hidden unicode** — bidi controls, zero-width characters, and homoglyph
+  confusables (a word mixing ASCII with look-alike Cyrillic/Greek letters) that a
+  human reviewer can't see in a diff.
+
+Run it locally with `python3 scripts/scan-pack-security.py pack/.claude`. A
+finding prints as `FINDING <file>:<line>: <class>: <excerpt>`. If the match is
+DevRites' own *defensive* content (e.g. a rule that quotes an attack string, or a
+QA checklist that demonstrates an adversarial character), add an auditable
+suppression on the line — `<!-- pack-scan-ignore: <reason> -->` — or opt a whole
+file out of one class with `<!-- pack-scan-ignore-file: injection -->`.
+Suppressions live in the file, so every exception is visible in the diff and
+reviewable; never suppress a hidden-unicode finding you can't explain.
+
+### State loading (project-local script, no `!` injection)
+
+`/rite`, `/rite-status`, and every workspace-operating skill load state by running
+a **read-only shell script via the `Bash` tool** — *not* Claude Code's
+preprocessing-only `` !`<command>` `` dynamic-context injection, which DevRites
+**removed** for cross-harness portability:
+
+```bash
+P=.claude/skills/devrites-lib/scripts/preamble.sh
+[ -f "$P" ] && bash "$P" || echo "(unavailable — read state.md directly)"
+```
+
+`preamble.sh` is a project-local read of DevRites' own `.devrites/` state: no user
+input is concatenated into a command, no network access, no write side effects.
+The gate scripts (`readiness.sh`, `evidence-fresh.sh`, `check-acceptance.sh`) are
+likewise read-only; only the explicit mutators (`resolve.sh`, `tick-afk.sh`,
+`close-out.sh`, and the CLI's `use`) write, and only under `.devrites/`.
+
+If your environment disallows skill-initiated shell execution, the scripts simply
+don't run — each skill degrades gracefully to reading `state.md` directly (the
+`|| echo "(… unavailable …)"` fallback above), and the rest of the pack is
+unaffected.
+
+### Auto-trigger is deliberate
+
+All `rite-*` skills are **auto-invocable** by Claude when their descriptions
+match the user's intent. This is a conscious DevRites design choice (see
+`DECISIONS.md` Q3). The safety nets are:
+
+- **Body discipline**: every skill stops at its phase boundary. `rite-build`
+  stops after one slice, `rite-prove` runs proofs only when all slices are
+  built, etc.
+- **Readiness gates**: each rite reads `.devrites/work/<slug>/state.md`
+  before acting; phases out of order refuse to run.
+- **Spec Drift Guard**: any deviation from the spec halts and routes to
+  `rite-plan`.
+- **Interactive type-GO confirmation** in `rite-ship` before irreversible
+  git actions (commit, push, tag) — present even with auto-trigger; `rite-seal`
+  only decides GO/NO-GO.
+
+If you prefer explicit-only invocation in a given project, add a Claude Code
+`permissions` rule disabling `Skill(rite-*)` auto-invocation in that
+project's `.claude/settings.json`.
+
+### Installer safety
+
+The bash installer (`install.sh`) refuses any target under `~/.claude`
+(`GUARD:no-global` block) and writes only to a manifest-tracked file list.
+`./uninstall.sh` removes exactly the manifested files. The
+`.devrites/` runtime state in the target project is preserved across
+uninstall.
+
+The installer touches no global state. It does not invoke `sudo`, modify
+shell rc files, fetch remote code, or alter Claude Code settings.
+
+### Plugin install path
+
+When installed via `claude plugin install devrites@devrites-marketplace`,
+the plugin runtime owns file placement. DevRites does not ship a post-install
+hook that modifies user files. The plugin manifest ships only skills and agents —
+the engineering rules are not delivered by the plugin and are never written into
+the user's `~/.claude/CLAUDE.md` (add them with a `--rules-only` bash install).
+
+### Recommended Claude Code permissions for managed deployments
+
+For organizations evaluating DevRites under a managed Claude Code policy:
+
+```jsonc
+{
+  "permissions": {
+    "Skill(rite-seal)": "ask",
+    "Bash(git push *)": "ask",
+    "Bash(git tag *)": "ask"
+  },
+  "disableSkillShellExecution": true
+}
+```
+
+The first three lines surface a confirmation prompt before any irreversible
+git action; the last disables the `/rite` and `/rite-status` dynamic-state
+read described above (DevRites still works).
+
+### Hooks (auto-approve scope + orientation)
+
+DevRites ships two `Bash`-matched hooks (`pack/.claude/hooks/`, wired via the
+plugin's `hooks.json` or a seeded `.claude/settings.json`):
+
+- **`devrites-allow.sh` (PreToolUse)** — auto-approves *only* the five **read-only**
+  helper scripts (`preamble.sh`, `progress.sh`, `readiness.sh`, `evidence-fresh.sh`,
+  `check-acceptance.sh`) so they stop prompting on every skill run. It is **fail-open**:
+  it never denies, parses the command, and emits an `allow` *only* when the command runs
+  one of those five scripts **and** contains no dangerous/exfiltration tokens
+  (`rm`, `>`/redirects, `curl`/`wget`, `sudo`, `chmod`, `$(...)`/backticks, `eval`,
+  package managers, `git push/commit/reset`, …). Mutating scripts (`resolve.sh`,
+  `tick-afk.sh`, `close-out.sh`) are **deliberately excluded** and still prompt. On any
+  parse failure or non-match it emits nothing — Claude Code's normal permission flow is
+  untouched. It widens approval for read-only orientation; it never widens it for anything
+  that writes, deletes, or reaches the network.
+- **`devrites-orient.sh` (SessionStart)** — read-only; injects the active feature's
+  `preamble.sh` digest as session context, and stays silent when no `.devrites/` workspace
+  is active. No tool approval, no writes.
+
+Delete `.claude/settings.json` (or disable the plugin) to remove both. The seeded
+settings file is never overwritten on update, so your own permission rules are safe.
+
+### Third-party trust
+
+DevRites vendors no third-party code (see `NOTICE.md`). It depends on Claude
+Code itself and, optionally and at the user's choice, on codegraph /
+graphify / browser-harness — each of which is invoked through its own
+documented interface, not bundled.
+
+### Known non-issues
+
+- **`!` injection in `/rite`** — local read of own state; safe. See above.
+- **`Write` / `Edit` tool allowance in `rite-*` skills** — required to
+  author `.devrites/` and project files. No skill grants `Bash(*)`.
+- **Auto-trigger** — deliberate design choice; mitigated as above.
+
+### CVE relevance
+
+DevRites does not ship `permissions.defaultMode: bypassPermissions` in any
+file (cf. **CVE-2026-33068**, workspace-trust bypass via committed bypass
+mode). The installer refuses to write any `defaultMode: bypassPermissions`
+into target projects.

package/bin/devrites.mjs

@@ -0,0 +1,100 @@
+#!/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.
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { existsSync, readFileSync } from 'node:fs';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const root = dirname(here); // bin/ -> package root
+
+const SUBCOMMANDS = {
+  install: 'install.sh',
+  add: 'install.sh',
+  uninstall: 'uninstall.sh',
+  remove: 'uninstall.sh',
+  update: 'update.sh',
+  upgrade: 'update.sh',
+};
+
+function pkgVersion() {
+  try {
+    return JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')).version || 'unknown';
+  } catch {
+    return 'unknown';
+  }
+}
+
+function printHelp() {
+  process.stdout.write(`devrites — install the full DevRites pack into a project
+
+Usage:
+  npx devrites [install] [flags]   Install skills + agents + rules + 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):
+  --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
+  --short-aliases=all   Also install /define /build /prove /seal
+  --no-agents           Skip the review subagents
+
+  --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.
+Requires bash (Git Bash or WSL on Windows). No-Node fallback:
+  curl -fsSL https://raw.githubusercontent.com/ViktorsBaikers/DevRites/main/install.sh | bash
+`);
+}
+
+const argv = process.argv.slice(2);
+const first = argv[0];
+
+if (first === '--version' || first === '-v') {
+  process.stdout.write(pkgVersion() + '\n');
+  process.exit(0);
+}
+if (first === '--help' || first === '-h') {
+  printHelp();
+  process.exit(0);
+}
+
+// Route the subcommand; default to install when the first arg is a flag or absent.
+let sub = 'install';
+let rest = argv;
+if (first && Object.prototype.hasOwnProperty.call(SUBCOMMANDS, first)) {
+  sub = 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 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);
+}
+
+process.exit(res.status === null ? 1 : res.status);

package/docs/architecture.md

@@ -0,0 +1,272 @@
+# DevRites Architecture
+
+DevRites is a **distributed but coordinated** set of project-local Claude Code skills
+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.
+
+## Layers
+
+1. **Public workflow skills** — `.claude/skills/rite-*`, `user-invocable: true`. Each
+   owns exactly one phase and reads/writes the `.devrites/` workspace.
+   Sequence: `rite-spec`, `rite-define`, `rite-plan`, `rite-build`,
+   `rite-prove`, `rite-polish`, `rite-review`, `rite-seal`, `rite-ship`,
+   plus the read-only `rite-status`, the resume verb `rite-resolve` (answer
+   a HITL gate and clear `Awaiting human`), and the thin `/rite` menu.
+   `/rite-seal` **decides** GO/NO-GO and writes the verdict to `seal.md`;
+   `/rite-ship` is the eighth lifecycle phase that **executes** the
+   irreversible git ladder and **closes** the task (archives the workspace,
+   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
+   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
+   `devrites-` prefix is **namespace** (collision avoidance against bundled
+   Claude Code skill names like `prototype`, `handoff`, `triage`, `diagnose`),
+   not a visibility marker; `rite-pressure-test` carries no prefix because it
+   doesn't collide.
+3. **Internal specialist skills** — `.claude/skills/devrites-*` with
+   `user-invocable: false`: `devrites-interview`, `-source-driven`,
+   `-doubt`, `-ux-shape` (plans UX/UI into `design-brief.md` at `/rite-spec`),
+   `-frontend-craft`, `-browser-proof`, `-debug-recovery`,
+   `-api-interface`, `-audit` (dispatches the security / perf / simplify
+   reviewer subagent on an axis argument). Model-invoked by public skills
+   or Claude's auto-selection; not menu noise. Whether a skill is public or
+   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
+   `/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,
+   templates, and anti-rationalization tables loaded on demand (progressive
+   disclosure) so `SKILL.md` bodies stay small.
+5. **Agents** — `.claude/agents/devrites-*` fresh-context subagents. Nine **read-only
+   reviewers**: the post-build set used by `/rite-seal` and the doubt loop
+   (`devrites-spec-reviewer`, `-code-reviewer`, `-test-analyst`, `-frontend-reviewer`,
+   `-security-auditor`, `-performance-reviewer`, `-doubt-reviewer`, `-simplifier-reviewer`),
+   plus the **pre-plan** `devrites-strategy-reviewer` used by `/rite-temper`. Plus one
+   **write-capable** executor, `devrites-slice-wright`, 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); 15 on-demand files load by the phase that needs them:
+   - **Craft:** `coding-style.md` · `patterns.md` · `error-handling.md` ·
+     `testing.md` · `documentation.md`.
+   - **Quality / safety:** `code-review.md` · `security.md` ·
+     `performance.md` · `anti-patterns.md`.
+   - **Workflow / ops:** `development-workflow.md` · `git-workflow.md` ·
+     `hooks.md` · `agents.md` · `context-hygiene.md` · `afk-hitl.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.
+
+## Design rationale
+
+### Why a shared orientation preamble (`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 ~15 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.
+
+### Why `/engine` was rejected
+A single `/engine` (or `/devrites`) mega-command would load every phase's instructions
+into one context, creating constant context pressure and hiding the intent of each
+step. It also makes "do only this phase" hard to enforce and bloats the recurring
+token cost (skill bodies stay in context once loaded). DevRites splits the lifecycle
+into small skills that load only what the current phase needs.
+
+### Why `rite-*` names
+Short, memorable, brand-aligned ("rites" = disciplined steps), and **collision-free**.
+Built-in / bundled Claude Code commands include `/plan`, `/review`, `/run`, `/verify`,
+`/code-review`, `/simplify`, `/security-review`, `/init`, `/compact`, `/debug`. The
+`rite-` prefix avoids all of them. (Collision audit: `research/claude-code-skills-notes.md`.)
+
+### Why a thin menu skill, not a mega-router
+`/rite` is **only** an entrypoint: it shows a compact phase-grouped menu, prints live
+`.devrites/ACTIVE` status via `` !`cmd` `` injection, and suggests the next command.
+It deliberately does **not** execute workflows or duplicate skill logic — that would
+recreate the mega-command problem. DevRites keeps selection thin and lets each phase
+own its context, rather than centralizing every workflow behind one command.
+
+### Why internal skills exist
+Specialist processes (doubt, source-driven, frontend craft, browser proof, audits)
+are **disciplines**, not user commands. As `user-invocable: false` skills they:
+- stay out of the command menu (less cognitive load);
+- are invoked automatically by Claude or explicitly by a public skill when their
+  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`)
+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.
+
+### Why `/rite-polish` is one skill with two progressive-disclosure halves
+Polish has two natural halves — **code** (simplify, dead code, naming, plus
+backend if BE was touched) and **UI** (normalize to the design system, then
+ship-quality detail). The earlier design split them into `rite-polish-code`
+and `rite-polish-ui` sub-skills, but a skill-on-skill dispatch is fragile
+(the caller has to re-discover the callee by description) and the two halves
+share the same operating rules. They now live as `reference/code.md` and
+`reference/ui.md` inside the same skill, loaded only when their phase
+trigger fires — the canonical progressive-disclosure pattern from
+<https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices>.
+`/rite-polish` is the orchestrator: always reads `reference/code.md`
+(Phase 1 + 2), detects UI scope from the diff and reads `reference/ui.md`
+(Phase 3 + 4) when needed. The orchestrator accepts mode tokens (`bolder`,
+`quieter`, `distill`, `harden`, `normalize-only`) that pass through to
+Phase 4.
+
+Normalization remains the entry gate of UI polish — polishing UI that hasn't
+been aligned to the project's design system is "decoration on drift," and
+the UI reference refuses to run Phase 4 before Phase 3.
+
+### Why seal and ship are separate phases (`/rite-seal`, `/rite-ship`)
+Deciding "is this safe to ship" and *actually shipping* are different acts with
+different blast radii. `/rite-seal` is a **pure decision gate**: it walks acceptance
+against evidence, fans out the fresh-context reviewers, and writes the GO / NO-GO
+verdict to `seal.md` — it runs no git. On GO it sets `state.md` `Next step:
+/rite-ship` and stops. `/rite-ship` is the eighth lifecycle phase: it refuses to run
+without a GO recorded in `seal.md`, renders the type-`GO` prompt, runs the irreversible
+git ladder (commit → push → tag/PR per the project's convention), writes `ship.md`,
+then **closes the task** — sets phase `done` and archives `.devrites/work/<slug>/` →
+`.devrites/archive/<slug>/` (every `.md` preserved, never deleted) and clears
+`.devrites/ACTIVE`. A GO seal is a verdict, not an authorization to push; keeping the
+decision and the irreversible action as two separately-auditable steps is the point.
+
+### Why `/rite-autocomplete` exists (the unattended orchestrator)
+Some features are routine enough to run end-to-end without per-phase human iteration.
+`/rite-autocomplete` drives the whole lifecycle (spec → define → build×N → prove →
+polish → review → seal → ship) by reading each phase's `SKILL.md` and executing its
+workflow, carrying state through the workspace files rather than chat. A vague prompt
+triggers an up-front `devrites-interview` — the only interactive window — after which it
+runs unattended, choosing the best option at each soft gate and recording the rationale
+in `decisions.md`. It does **not** weaken the safety gates: hard irreversible-risk
+(auth / migration / public-API / red tests), blocking / escalating gates, an open
+`gate: validating`, a NO-GO, exhausted `max_slices`, or low confidence all still pause.
+By default it stops at the final type-`GO`; the `--ship` flag (alias `--yolo`)
+auto-confirms it for a zero-touch push.
+
+### Why persistent `.devrites/` state
+Long features outlive a single context window. Durable Markdown (spec/plan/tasks/
+state/evidence/drift/decisions) lets any phase — in any session, after any compaction
+— reload exactly where work stands. This is the main thing DevRites adds over typical
+session-scoped workflows, which don't persist feature state.
+
+### Run modes — HITL & AFK
+
+DevRites runs the same lifecycle two ways, configured at two levels:
+
+- **Per-slice** (planning-time) — each `tasks.md` slice declares `Mode: AFK | HITL`.
+  HITL slices add `Gate: advisory | validating | blocking | escalating`, `SLA`, and
+  `Checkpoint` so the agent knows how disruptive the pause should be.
+- **Per-session** (run-time) — the presence of `.devrites/AFK` flips the session-level
+  default. Empty file = AFK with safe defaults; YAML body widens behavior
+  (`max_slices`, `notify`, `allow_gates`).
+
+The pause primitive is a **pre-action interrupt**, not a post-action review queue —
+inspired by LangGraph's `interrupt()` / `Command(resume=)` model. `/rite-build` writes
+an `Awaiting human` block to `state.md` and a question to `questions.md`, then stops.
+`/rite-resolve` is the canonical resume verb. Restarting a session reads the workspace
+back into a consistent state because the pause is durable Markdown, not chat memory.
+
+Why a four-gate taxonomy (instead of a single "ask the user" pause): a single gate
+becomes a queue under load. Mixing `advisory` (audit-only log) with `validating`
+(async — build continues, merge blocks) and reserving `blocking` for synchronous halts
+keeps the loop alive when the answer can wait, and pauses hard when it can't. The
+"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
+contract.
+
+## Design choices at a glance
+
+- **Surface**: 19 public `rite-*` skills (28 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
+  `rite-temper` (strategic, optional) and `rite-vet` (engineering, every plan)
+  reviews +
+  `rite-status` +
+  the `rite-plan` replan verb + the `rite-resolve` resume verb + 5 utilities
+  (`rite-zoom-out`, `rite-prototype`, `rite-handoff`, `rite-pressure-test`,
+  `rite-autocomplete` — the unattended full-lifecycle orchestrator) — plus 9
+  internal model-invoked `devrites-*` specialists, not one mega-command. The
+  `devrites-` prefix is a namespace (collision avoidance), not a
+  public/internal marker — `user-invocable:` is. All `devrites-*` skills are
+  model-invoked.
+- **Selection**: the `/rite` menu skill carries the routing table; every
+  workflow skill enforces a "right skill, right time" rule in its body.
+- **State**: durable `.devrites/` Markdown that survives compaction and new sessions.
+  `.devrites/AFK` presence is the single source of truth for run mode (HITL/AFK);
+  there is no `state.md` run-mode field to drift out of sync.
+- **Run modes**: same lifecycle runs HITL (default; pause at typed gate) or AFK
+  (drop `.devrites/AFK`; loop continues, discretionary pauses downgrade to
+  advisory log, irreversible risk always pauses).
+- **Slice rule**: build **one vertical slice, then stop** — no auto-continue.
+- **Drift**: an explicit **Spec Drift Guard** in build/prove/polish/review/seal.
+- **Design**: `devrites-frontend-craft` + a four-phase `/rite-polish` orchestrator (code + backend always; UI normalize + polish when UI is in scope).
+- **Review**: **feature-scoped** five-axis review with severity labels + fresh-context
+  subagents at the seal.
+- **Scope**: clarify → seal (decide) → ship (the irreversible git ladder —
+  commit → push → tag/PR — per the project's own convention) → close; the CI
+  pipeline stays with the project.
+- **Install**: project-local, manifest-managed; ships DevRites' own engineering rules.
+
+## Deviations from the original build brief (and why)
+
+1. **`user-invocable` semantics corrected from the docs.** The brief said set
+   `user-invocable: true` for public and `false` for internal. That is exactly right
+   for internal skills. For public skills we keep them model-invocable (no
+   `disable-model-invocation`) so phases can hand off and the selector can route;
+   per-phase side-effect discipline (e.g. "stop after one slice") is enforced in the
+   skill **body**, which is the correct mechanism (invocation flags can't express it).
+2. **`context: fork` used selectively.** Verified it is a real field (isolated
+   subagent, body-as-prompt, no conversation history). It is applied only to the three
+   self-contained read-only audit skills (`devrites-audit simplify`,
+   `devrites-audit security`, `devrites-audit perf`), which re-read
+   `.devrites/` + `git diff` themselves. Interactive skills (doubt, interview, craft)
+   are **not** forked because they need live context and user turns.
+3. **Fresh-context adversarial review via real `.claude/agents/`** rather than relying
+   on `context: fork` everywhere, because an agent can be handed the workspace path to
+   read, whereas a forked skill cannot see the conversation.
+
+Everything else follows the brief's structure, command names, state model, and
+acceptance criteria.
+
+## Repository layout
+
+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/`.

package/docs/cli-mcp.md

@@ -0,0 +1,57 @@
+# Tool-agnostic state core — the `devrites` CLI + MCP server
+
+DevRites' discipline lives in the `.devrites/` Markdown files and the state scripts under
+`devrites-lib/scripts/`, **not** in the Claude Code harness. So any tool — Cursor, Codex,
+Gemini CLI, a CI job, or a human — can drive a DevRites workflow through the same files.
+Two portable surfaces expose them.
+
+## The `devrites` CLI
+
+Installed at `.claude/skills/devrites-lib/scripts/devrites.sh` (ships on both the bash
+installer and the plugin). Run it from the project root:
+
+```bash
+D=.claude/skills/devrites-lib/scripts/devrites.sh
+bash "$D" orient            # workspace digest for the active feature (read-only)
+bash "$D" ready             # build-readiness gate      (exit 0 ready · 2/3/4/5 not)
+bash "$D" evidence-fresh    # evidence-freshness gate   (exit 0 fresh · 3 stale)
+bash "$D" acceptance        # acceptance-criteria gate  (exit 0 proven · 1 gap)
+bash "$D" active | list | use <slug>
+bash "$D" resolve <qid> "<answer>"   # answer a HITL gate
+bash "$D" help
+```
+
+Each command is a thin wrapper over an existing state script, so the **exit code is the
+gate**: a non-zero `ready` / `evidence-fresh` / `acceptance` is a hard stop, scriptable in
+any agent's loop or a pre-merge CI step. `devrites help` lists them all.
+
+## The MCP server
+
+`mcp/devrites-mcp.mjs` (in the DevRites source) is a dependency-free MCP **stdio** server
+that exposes the read/gate operations as MCP tools (`devrites_orient`, `devrites_ready`,
+`devrites_evidence_fresh`, `devrites_acceptance`, `devrites_status`, `devrites_active`,
+`devrites_list`, `devrites_use`). It shells out to the CLI, so it stays a thin surface over
+the same scripts — no SDK, no dependencies.
+
+Register it in a project's `.mcp.json`, running from the project root (it auto-finds the
+installed CLI; override the path with the `DEVRITES_CLI` env var):
+
+```json
+{
+  "mcpServers": {
+    "devrites": { "command": "node", "args": ["/abs/path/to/mcp/devrites-mcp.mjs"] }
+  }
+}
+```
+
+Now any MCP client can ask "is this feature ready to ship?" and the server runs the
+deterministic gates against `.devrites/` — the same verdict the lifecycle skills compute,
+available to tools that don't speak DevRites' skill prose.
+
+## Why this exists
+
+Spec-kit, task-master, and BMAD all run across many agents; DevRites was Claude-Code-only.
+Its workspace and rules were already tool-agnostic *data* — the CLI and MCP server are the
+thin shims that make the *workflow* drivable from anywhere, without reimplementing the
+discipline. The deterministic gates (`ready`, `evidence-fresh`, `acceptance`) are the same
+scripts the skills call, so a verdict from the CLI, the MCP server, or `/rite-seal` agrees.