devrites 3.0.4 → 3.0.6

package/SECURITY.md

@@ -5,7 +5,7 @@
 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 —
+- **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>.
@@ -23,34 +23,28 @@ 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.
+Only the latest published DevRites release receives security fixes. Older
+releases are unsupported; upgrade before reporting a version-specific finding
+unless the issue also reproduces on the latest release.
 
 ## DevRites security model
 
 ### Scope
 
 DevRites is a skills pack plus the local `devrites-engine` control-plane binary:
-Markdown skill files, helper scripts, a bash installer, and a thin `npx` CLI
-wrapper (`bin/devrites.mjs`) that bootstraps or proxies the engine. It ships no
-network service. The attack surface is the content of the skill files, the
-installer, generated host artifacts, hooks, and the local engine binary.
+Markdown skill files, helper scripts, Bash bootstrap shims, and a native Node
+`npx` shim (`bin/devrites.mjs`) that acquires and proxies the engine. It ships no
+network service. The attack surface is the content of the skill files, bootstrap
+and install paths, generated host artifacts, hooks, and the local engine binary.
 
 ### 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,
+- **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
+- **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.
 
@@ -58,39 +52,43 @@ 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 -->`.
+suppression on the same line with `<!-- pack-scan-ignore: <reason> -->`. To opt
+an entire file out of one class, use
+`<!-- 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 (engine subcommands, no `!` injection)
 
-`/rite`, `/rite-status`, and every workspace-operating skill load state by running
-a **read-only `devrites-engine` subcommand via the `Bash` tool** — *not* Claude Code's
+`/rite-status` and workspace-operating skills load state by running a **read-only
+`devrites-engine` subcommand through the `Bash` tool**. It does not use Claude Code's
 preprocessing-only `` !`<command>` `` dynamic-context injection, which DevRites
-**removed** for cross-harness portability:
+**removed** for cross-harness portability. The no-argument `/rite` menu runs
+`devrites-engine first-task` instead; a routed verb hands control to its owning skill.
 
 ```bash
-command -v devrites-engine >/dev/null 2>&1 && devrites-engine preamble || echo "(unavailable — read state.md directly)"
+command -v devrites-engine >/dev/null 2>&1 && devrites-engine preamble || echo "(unavailable: read state.md directly)"
 ```
 
 `devrites-engine preamble` 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 subcommands (`build-readiness`, `evidence-fresh`,
-`check-acceptance`) are likewise read-only; only explicit mutators (`resolve`,
-`tick-afk`, `close-out`, and the MCP `use` helper) write, and only under
-`.devrites/`.
+`check-acceptance`) are likewise read-only. Mutating commands are explicit and
+scoped: for example, `resolve`, `tick-afk`, and `close-out` write only DevRites
+state, while `/rite use <slug>` deliberately repoints `.devrites/ACTIVE` inline.
 
-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.
+If your environment disallows shell commands started by skills, each skill reads
+`state.md` directly through the `|| echo "(… unavailable …)"` fallback above.
+The rest of the pack continues to work.
 
-### Auto-trigger is deliberate
+### Model invocation is per skill
 
-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:
+Public skills are always user-invocable, but model invocation is set per skill.
+Skills without `disable-model-invocation: true` may be selected when their
+descriptions match the user's intent; explicit utilities carry that frontmatter
+flag and load only when the user invokes them. The checked-in frontmatter and
+[`docs/command-map.md`](docs/command-map.md) are the source of truth. The safety
+nets for model-invocable rites 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
@@ -100,31 +98,39 @@ match the user's intent. This is a conscious DevRites design choice (see
 - **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.
+  git actions such as commit, push, or tag. This prompt remains after model
+  invocation; `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`.
+Claude documents the invocation controls in its official
+[skills reference](https://code.claude.com/docs/en/slash-commands). DevRites uses
+`disable-model-invocation: true` rather than an undocumented settings key.
 
 ### 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
+The Bash installer (`install.sh`) refuses any target under `~/.claude`
+(`GUARD:no-global` block). Project host files are manifest-tracked;
+`./uninstall.sh` removes exactly those managed 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.
+Skills, agents, standards, and hook configuration stay in the target project.
+The installer merges DevRites entries into project-local `.claude/settings.json`
+and `.codex/hooks.json` without replacing unrelated user settings. Its only
+sanctioned global artifact is the shared `devrites-engine` executable, installed
+to `DEVRITES_BIN_DIR`, a writable `~/.local/bin`, or a writable
+`/usr/local/bin`; `--no-binary` / `DEVRITES_NO_BINARY=1` skips it. The bootstrap
+path may fetch the release bundle and checksummed engine assets. It never invokes
+`sudo` or edits shell startup files.
 
 ### npx install path
 
 When installed via `npx devrites@latest`, the CLI (`bin/devrites.mjs`) is a thin
-shim that runs the **bundled** `install.sh` against the pack shipped inside the npm
-package — no remote code is fetched at install time, and the install is pinned to
-the requested package version. It has no runtime npm dependencies and makes no
-global writes; the same project-local guarantees as the bash installer apply.
+Node shim that delegates directly to `devrites-engine`; it does not execute
+`install.sh`. The host payload is bundled and pinned to the requested npm package
+version. To start the engine, the shim tries the matching release binary plus its
+SHA-256 sidecar, then a local Go build, then an existing engine. It has no runtime
+npm dependencies. Project-artifact and optional shared-binary boundaries are the
+same as the Bash path.
 
 ### Recommended Claude Code permissions for managed deployments
 
@@ -133,67 +139,73 @@ 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
+    "ask": [
+      "Bash(git commit *)",
+      "Bash(git push *)",
+      "Bash(git tag *)"
+    ]
+  }
 }
 ```
 
-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).
+This follows the current
+[Claude Code permissions schema](https://code.claude.com/docs/en/permissions)
+and surfaces a host confirmation before the git mutation ladder. DevRites'
+separate type-`GO` workflow gate still applies.
 
 ### Hooks (approval, orientation, and local guards)
 
-DevRites ships JSON-configured hooks installed by the npm flow into the
+DevRites ships JSON-configured hooks installed by the engine-owned flow into the
 project-local host artifacts (`.claude/settings.json` for Claude Code and
 `.codex/hooks.json` for Codex). They call `devrites-engine` behind an inline
 fail-open guard:
 
-- **`allow` (PreToolUse/Bash)** — auto-approves *only* the read-only engine
-  orientation/gate subcommands (`preamble`, `progress`, `readiness`,
-  `evidence-fresh`, `check-acceptance`) so they stop prompting on every skill run.
+- **`allow` (PreToolUse/Bash)**: auto-approves *only* the read-only engine
+  orientation/gate subcommands (`check-acceptance`, `doubt-coverage`,
+  `evidence-fresh`, `preamble`, `progress`, `readiness`, `review-integrity`),
+  `footprint render|roster`, `ledger diff|validate|list|show`, and
+  `reviewer-stats report`, so they stop prompting on every skill run.
   It never denies, and it emits `allow` only when the parsed command is one of those
   subcommands and contains no dangerous/exfiltration tokens (`rm`, redirects,
   `curl`/`wget`, `sudo`, `chmod`, command substitution, `eval`, package managers,
   `git push/commit/reset`, etc.). Mutating subcommands (`resolve`, `tick-afk`,
   `close-out`) are deliberately excluded and still prompt.
-- **Read-only context hooks** — `orient`, `cursor`, and `subagent-orient` inject
-  active-workspace context and stay silent when no `.devrites/` workspace is active.
-- **Local guard hooks** — `a1-guard`, `redwatch`, `stop-gate`, `source-cache-*`,
-  and `refresh-indexes` run through the engine and are fail-open by default. New
-  blocking guards are observe-first unless explicitly enforced with the documented
-  `DEVRITES_*` environment switches.
+- **Context and continuity hooks**: `orient`, `cursor`, `subagent-orient`,
+  `statusline`, and `handoff-snapshot` inject bounded workspace context; `event`
+  and `auq` append lifecycle/HITL events. They stay silent when no workspace is active.
+- **Local guards and caches**: `a1-guard`, `wright-scope`,
+  `reviewer-readonly`, `redwatch`, `stop-gate`, `source-cache-*`, and
+  `refresh-indexes` run through the engine. Guard hooks are fail-open or
+  observe-first unless explicitly enforced with the documented `DEVRITES_*`
+  controls; source-cache network I/O is the bounded exception in ADR-0008.
 
 Delete the project-local hook file (`.claude/settings.json` for Claude Code, or
 the DevRites-managed entries in `.codex/hooks.json` for Codex) to remove hooks.
-The seeded settings file is never overwritten on update, so your own permission
-rules are safe.
+Updates merge DevRites entries rather than replacing unrelated project settings,
+so user permission rules remain intact.
 
 ### 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 / Playwright MCP — each of which is invoked through its own
-documented interface, not bundled.
+Code itself. Codegraph, graphify, and Playwright MCP are optional user-selected
+tools that DevRites calls through their documented interfaces rather than
+bundling them.
 
 ### Agentic trust boundaries
 
 Treat every instruction-bearing file as supply chain:
 
-1. **Shipped pack** — `pack/.claude/**`, generated host artifacts, hooks, and the
+1. **Shipped pack**: `pack/.claude/**`, generated host artifacts, hooks, and the
    engine are release-managed and scanned before publish.
-2. **Project-local state** — `.devrites/work/**`, learnings, principles, and
+2. **Project-local state**: `.devrites/work/**`, learnings, principles, and
    review artifacts are evidence, not authority. Live source and engine gates win
    over stale state.
-3. **User extensions/overrides** — `.devrites/extensions/**` and
+3. **User extensions/overrides**: `.devrites/extensions/**` and
    `.devrites/overrides/**` are untrusted until `devrites-engine extensions
    validate` / `overrides validate` pass. Extensions may add checks or reviewers;
    they must not weaken type-GO, seal/ship, AFK/HITL, security, or evidence
    gates.
-4. **External capability configs** — MCP/tool configs are optional and
+4. **External capability configs**: MCP/tool configs are optional and
    project-local. `/rite-doctor`/`devrites-engine doctor` reports readiness, but
    missing tools degrade to file-system/engine gates instead of silently changing
    workflow semantics.
@@ -206,10 +218,12 @@ visibly justified.
 
 ### Known non-issues
 
-- **`!` injection in `/rite`** — local read of own state; safe. See above.
-- **`Write` / `Edit` tool allowance in `rite-*` skills** — required to
+- **Historical `!` injection in `/rite`**: no longer present; current state
+  orientation uses structurally bounded, read-only engine commands.
+- **`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.
+- **Per-skill model invocation**: deliberate and frontmatter-controlled;
+  model-invocable rites remain bounded by the gates above.
 
 ### CVE relevance
 

package/docs/adr/README.md

@@ -1,9 +1,8 @@
-# Architecture Decision Records
+# Architecture decision records
 
-An ADR captures **one** load-bearing decision: the context that forced it, the
-decision itself, the alternatives that were rejected and *why*, and the
-consequences accepted. The rejected-alternatives table is the point — it keeps
-the "why not X" from being re-litigated every quarter.
+An ADR records one architectural decision, the context behind it, the options
+that were rejected, and the consequences the team accepted. Recording why an
+option lost prevents the same debate from starting again later.
 
 `CLAUDE.md` points every agent here (`CONTEXT.md` + `docs/adr/` are the
 single-context domain record). Keep this directory the source of truth for
@@ -17,9 +16,8 @@ architecture; per-feature `decisions.md` files stay scoped to that feature.
 - Sections: **Context** → **Decision** → **Alternatives considered** (a table:
   option · why rejected) → **Consequences**.
 - **Guard test:** an accepted ADR that asserts a runtime invariant SHOULD have a
-  named regression test — `engine/tests/adr_NNNN_*_test.go` — so the decision
-  has an executable proof it still holds. Reference the ADR number in the test's
-  doc comment.
+  named regression test such as `engine/tests/adr_NNNN_*_test.go`. Reference the
+  ADR number in the test's doc comment so the decision has executable proof.
 
 ## Template
 
@@ -48,7 +46,7 @@ architecture; per-feature `decisions.md` files stay scoped to that feature.
 
 | ADR | Title | Status | Guard test |
 |-----|-------|--------|-----------|
-| [0001](0001-go-engine-as-control-plane.md) | Go engine as deterministic control plane | Accepted | — |
+| [0001](0001-go-engine-as-control-plane.md) | Go engine as deterministic control plane | Accepted | none |
 | [0002](0002-dual-host-harness.md) | Dual-host harness (Claude + Codex) | Accepted | `tests/parity_*_test.go` |
 | [0003](0003-gate-model-hitl-pause.md) | Gates block as HITL pause, never crash | Accepted | `tests/adr_0003_gate_exit_code_test.go` |
 | [0004](0004-state-schema-phases-sections.md) | Phase-relative section completeness | Accepted | `tests/adr_0004_required_by_phase_test.go` |

package/docs/agents/domain.md

@@ -1,12 +1,12 @@
-# Domain Docs
+# Domain documentation
 
 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.
+- **`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.
 
@@ -42,7 +42,7 @@ Multi-context repo (presence of `CONTEXT-MAP.md` at the root):
 
 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.
+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
 
@@ -55,4 +55,4 @@ If the concept you need isn't in the glossary yet, that's a signal — either yo
 
 If your output contradicts an existing ADR, surface it explicitly rather than silently overriding:
 
-> _Contradicts ADR-0007 (event-sourced orders) — but worth reopening because…_
+> _Contradicts ADR-0007 (event-sourced orders). Reopen it because…_

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

@@ -4,8 +4,8 @@ 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.
+1. Create `.scratch/<slug>/PRD.md` when product detail is needed and one or more numbered implementation issues under `.scratch/<slug>/issues/<NN>-<issue-slug>.md`, starting at `01`.
+2. Start `/rite-spec <slug>` from the relevant PRD/issues; copy lifecycle decisions into `.devrites/work/<slug>/`, while tracker status/comments remain in the local issue files.
+3. Run the normal lifecycle: `/rite-define` → `/rite-vet` → `/rite-build` → `/rite-prove` → `/rite-polish` → `/rite-review` → `/rite-seal` → `/rite-ship`.
+4. After a recorded type-GO, mark completed local issues `Status: resolved` and append the ship evidence; include `Closes #NNN` only when an external issue reference exists.
+5. Follow-ups become the next numbered local issue under `.scratch/<slug>/issues/` (or a new feature directory when scope differs); external auto-posting is out of scope.

package/docs/agents/issue-tracker.md

@@ -1,4 +1,4 @@
-# Issue tracker: Local Markdown
+# 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).
 

package/docs/agents/triage-labels.md

@@ -1,4 +1,4 @@
-# Triage Labels
+# 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.
 
@@ -12,4 +12,4 @@ The skills speak in terms of five canonical triage roles. This file maps those r
 
 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.
+Edit the right-hand column to match the vocabulary you use.