devrites 3.0.6 → 3.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devrites",
-  "version": "3.0.6",
+  "version": "3.1.0",
   "description": "DevRites: a disciplined senior-engineer workflow pack for Claude Code and Codex",
   "license": "SEE LICENSE IN LICENSE",
   "homepage": "https://github.com/ViktorsBaikers/DevRites#readme",

package/scripts/build-release-tarball.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
-# Build the DevRites release tarball: the artifact attached to the GitHub Release
-# by semantic-release. Extracting yields a `devrites-v<version>/` directory with
-# everything an end-user needs (pack/, install.sh, uninstall.sh, scripts/, docs).
+# Build the archive that semantic-release attaches to a GitHub Release.
+# It extracts to `devrites-v<version>/` with the pack, engine, scripts,
+# documentation, and install tools.
 #
 # Usage: build-release-tarball.sh <version>
 set -euo pipefail
@@ -11,20 +11,31 @@ if [[ -z "$VERSION" ]]; then
   echo "usage: build-release-tarball.sh <version>" >&2
   exit 1
 fi
+if [[ ! "$VERSION" =~ ^[0-9A-Za-z][0-9A-Za-z._+-]*$ ]]; then
+  echo "error: version must be a portable release asset name" >&2
+  exit 1
+fi
 
-ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
 DIST="${DEVRITES_RELEASE_DIST_DIR:-$ROOT/dist}"
 NAME="devrites-v${VERSION}"
-STAGE="$DIST/$NAME"
 
 cd "$ROOT"
+mkdir -p "$DIST"
+DIST="$(cd "$DIST" && pwd -P)"
+case "$DIST/" in
+  "$ROOT/pack/"* | "$ROOT/engine/"* | "$ROOT/scripts/"* | "$ROOT/mcp/"* | "$ROOT/docs/"*)
+    echo "error: release output directory overlaps the release payload" >&2
+    exit 1
+    ;;
+esac
+STAGE="$(mktemp -d "$DIST/.devrites-release-stage.XXXXXX")"
+cleanup() { rm -rf "$STAGE"; }
+trap cleanup EXIT
 
 echo "Building release tarball: ${NAME}.tar.gz"
 
-rm -rf "$STAGE"
-mkdir -p "$STAGE"
-
-# Files and directories shipped to end-users.
+# Release contents.
 PAYLOAD=(
   pack
   engine
@@ -60,17 +71,23 @@ for item in "${PAYLOAD[@]}"; do
   fi
 done
 
-# Ship the same prebuilt host-native artifacts that npm pack includes.
+# Include the same prebuilt host artifacts as the npm package.
 DEVRITES_HOST_ARTIFACT_DIR="$STAGE/pack/generated" bash "$ROOT/scripts/build-host-artifacts.sh" >/dev/null
 
-# Drop dev-only artifacts that may have been copied transitively.
+# Remove development files copied with the payload.
 rm -rf "$STAGE/docs/internal" "$STAGE/scripts/.cache" 2>/dev/null || true
 
-tar -C "$DIST" -czf "$DIST/${NAME}.tar.gz" "$NAME"
-rm -rf "$STAGE"
+(
+  cd "$ROOT/engine"
+  go run ./cmd/releasepack \
+    -root "$STAGE" \
+    -output "$DIST/${NAME}.tar.gz" \
+    -prefix "$NAME" \
+    -epoch "${SOURCE_DATE_EPOCH:-0}"
+)
 
-# Emit a sibling checksum so install.sh can verify the artifact when present.
-# Write just "<sha256>  <filename>" (no path) so it verifies from any cwd.
+# Write a sibling checksum for install.sh to verify when available.
+# Store only "<sha256>  <filename>" so verification works from any directory.
 (
   cd "$DIST"
   if command -v shasum >/dev/null 2>&1; then

package/scripts/check-authority-drift.py

@@ -0,0 +1,125 @@
+#!/usr/bin/env python3
+"""Compare generated JSON authorities with their short documentation blocks."""
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+
+def table(headers, rows):
+    return "\n".join(
+        [
+            "| " + " | ".join(headers) + " |",
+            "| " + " | ".join("---" for _ in headers) + " |",
+            *["| " + " | ".join(row) + " |" for row in rows],
+        ]
+    )
+
+
+def replace_block(path, name, wanted, write):
+    text = path.read_text()
+    start = f"<!-- authority:{name}:start -->"
+    end = f"<!-- authority:{name}:end -->"
+    pattern = re.compile(re.escape(start) + r"\n.*?\n" + re.escape(end), re.DOTALL)
+    replacement = f"{start}\n{wanted}\n{end}"
+    if not pattern.search(text):
+        raise ValueError(f"{path}: missing {name} authority markers")
+    if pattern.search(text).group(0) == replacement:
+        return
+    if write:
+        path.write_text(pattern.sub(replacement, text, count=1))
+        return
+    raise ValueError(f"{path}: {name} authority block is stale")
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--root", type=Path, default=Path(__file__).resolve().parents[1])
+    parser.add_argument("--write", action="store_true")
+    args = parser.parse_args()
+    root = args.root.resolve()
+
+    manifest = json.loads((root / "engine/internal/state/workflow_manifest.json").read_text())
+    readiness = json.loads((root / "engine/internal/lib/readiness_contract.json").read_text())
+    phases = manifest["phases"]
+    reasons = readiness["reasons"]
+    policy = manifest["authorityPolicy"]
+
+    ids = [phase["id"] for phase in phases]
+    rights = [phase["transitionRight"] for phase in phases]
+    if len(ids) != len(set(ids)) or len(rights) != len(set(rights)):
+        raise ValueError("workflow manifest has duplicate phase IDs or transition rights")
+    resumes = {phase["id"]: phase.get("resumeVerb", "") for phase in phases}
+    if resumes.get("define") != "define" or resumes.get("plan") != "vet":
+        raise ValueError("workflow manifest violates ADR-0011 define/plan routing")
+    codes = [reason["code"] for reason in reasons]
+    if len(codes) != len(set(codes)):
+        raise ValueError("readiness contract has duplicate exit codes")
+
+    lifecycle = "`" + " → ".join(phase.upper() for phase in ids) + "`"
+    phase_rows = []
+    for phase in phases:
+        required = ", ".join(f"`{section}`" for section in phase.get("requiredSections", [])) or "*(none)*"
+        resume = f"`/rite-{phase['resumeVerb']}`" if phase.get("resumeVerb") else "*(terminal)*"
+        phase_rows.append([f"`{phase['id']}`", resume, required, phase["transitionRight"]])
+    reason_rows = [
+        [
+            f"`{reason['code']}`",
+            f"`{reason['id']}`",
+            reason["condition"],
+            f"`/rite-{reason['remediationVerb']}`" if reason["remediationVerb"] else "*(none)*",
+        ]
+        for reason in reasons
+    ]
+    tracking = (
+        "Git-tracked shared state: "
+        + ", ".join(f"`{path}`" for path in policy["trackedState"])
+        + ". Per-clone runtime state: "
+        + ", ".join(f"`{path}`" for path in policy["localState"])
+        + "."
+    )
+    clarify_rows = [[f"`{item['field']}`", item["policy"]] for item in manifest["clarifyReturnFields"]]
+
+    blocks = [
+        ("docs/quick-reference.md", "lifecycle", lifecycle),
+        ("docs/engine/state-schema.md", "schema-version", f"`schemaVersion: {manifest['schemaVersion']}`."),
+        (
+            "docs/engine/state-schema.md",
+            "phase-contract",
+            table(["phase", "normal resume", "required sections", "transition right"], phase_rows),
+        ),
+        ("docs/engine/state-schema.md", "state-tracking", tracking),
+        (
+            "docs/engine/state-schema.md",
+            "clarify-return-fields",
+            table(["field", "policy"], clarify_rows),
+        ),
+        (
+            "docs/cli.md",
+            "readiness-reasons",
+            table(["exit", "reason", "condition", "remediation"], reason_rows),
+        ),
+        ("SECURITY.md", "principles-trust", policy["principlesTrust"]),
+        (
+            "pack/.claude/skills/devrites-lib/reference/standards/core.md",
+            "principles-trust",
+            policy["principlesTrust"],
+        ),
+    ]
+    for relative, name, wanted in blocks:
+        replace_block(root / relative, name, wanted, args.write)
+
+    state_schema = (root / "docs/engine/state-schema.md").read_text()
+    if re.search(r"schema(?:Version| version| v)[: ]+1\b", state_schema, re.IGNORECASE):
+        raise ValueError("docs/engine/state-schema.md still claims schema v1")
+    print("authority-drift: current docs match workflow and readiness authorities")
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except (KeyError, OSError, ValueError, json.JSONDecodeError) as exc:
+        print(f"authority-drift: {exc}", file=sys.stderr)
+        sys.exit(1)

package/scripts/check-instruction-size-baseline.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// Per-file and aggregate byte ratchet for canonical prompt/instruction docs.
+// Track canonical instruction files individually and skills as a group.
 import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
 import { dirname, join, relative, resolve } from 'node:path';
 
@@ -12,6 +12,7 @@ function option(name, fallback) {
 const root = resolve(option('--root', defaultRoot));
 const baselinePath = resolve(option('--baseline', join(root, 'tests', 'instruction-size-baseline.json')));
 const write = argv.includes('--write');
+const ratchetLimit = 855_000;
 
 function lfBytes(text) {
   return Buffer.byteLength(text.replace(/\r\n/g, '\n'));
@@ -28,12 +29,7 @@ function markdownFiles(dir) {
   return files;
 }
 
-function collect() {
-  const roots = [
-    join(root, 'pack', '.claude', 'skills'),
-    join(root, 'pack', '.claude', 'agents'),
-    join(root, 'pack', '.claude', 'rules'),
-  ];
+function collect(roots) {
   const out = {};
   for (const file of roots.flatMap(markdownFiles)) {
     out[relative(root, file)] = lfBytes(readFileSync(file, 'utf8'));
@@ -41,13 +37,25 @@ function collect() {
   return Object.fromEntries(Object.entries(out).sort(([a], [b]) => a.localeCompare(b)));
 }
 
-const files = collect();
-const totalBytes = Object.values(files).reduce((sum, bytes) => sum + bytes, 0);
+const skillRoot = join(root, 'pack', '.claude', 'skills');
+const files = collect([
+  skillRoot,
+  join(root, 'pack', '.claude', 'agents'),
+  join(root, 'pack', '.claude', 'rules'),
+]);
+const skillFiles = collect([skillRoot]);
+const totalBytes = Object.values(skillFiles).reduce((sum, bytes) => sum + bytes, 0);
 const current = { version: 2, total_bytes: totalBytes, files };
+if (totalBytes > ratchetLimit) {
+  console.error(`FAIL: canonical skill Markdown is ${totalBytes} bytes (ratchet ${ratchetLimit})`);
+  process.exit(1);
+}
 if (write) {
   mkdirSync(dirname(baselinePath), { recursive: true });
   writeFileSync(baselinePath, JSON.stringify(current, null, 2) + '\n');
-  console.log(`instruction-size: wrote ${relative(root, baselinePath)} (${Object.keys(files).length} files, ${totalBytes} bytes)`);
+  console.log(
+    `instruction-size: wrote ${relative(root, baselinePath)} (${Object.keys(files).length} instruction files, ${totalBytes} skill bytes)`,
+  );
   process.exit(0);
 }
 
@@ -75,5 +83,5 @@ for (const file of Object.keys(baseline.files)) {
 if (totalBytes > baseline.total_bytes) {
   fail(`aggregate instruction payload grew by ${totalBytes - baseline.total_bytes} bytes (${baseline.total_bytes} -> ${totalBytes})`);
 }
-console.log(`instruction-size: ${Object.keys(files).length} files checked, ${totalBytes} bytes`);
+console.log(`instruction-size: ${Object.keys(files).length} instruction files checked, ${totalBytes} skill bytes`);
 process.exit(failures ? 1 : 0);

package/scripts/check-invocation-integrity.py

@@ -26,6 +26,8 @@ NONSKILL = {
     "devrites-engine",
     # a git commit-trailer marker ("[devrites-context]" body in a WIP checkpoint), not a skill
     "devrites-context",
+    # typed contract schemas and a generated-hook diagnostic marker, not skills
+    "devrites-forge", "devrites-git-authority", "devrites-codex-leaf-guard",
 }
 # names a skill deliberately mentions as NON-existent (self-documenting prose).
 DOCUMENTED_NONEXISTENT = {"rite-use"}

package/scripts/codex-generate.sh

@@ -8,16 +8,28 @@ gen_codex_markdown_file() {
   local _src="$1" _out="$2"
   mkdir -p "$(dirname "$_out")"
   sed -E \
+    -e 's#(pack/)?\.claude/agents/devrites-\{security-auditor,performance-reviewer,simplifier-reviewer\}\.md#.codex/agents/devrites-security-auditor.toml`, `.codex/agents/devrites-performance-reviewer.toml`, or `.codex/agents/devrites-simplifier-reviewer.toml#g' \
+    -e 's#(\.\./)+agents/devrites-\{security-auditor,performance-reviewer,simplifier-reviewer\}\.md#.codex/agents/devrites-security-auditor.toml`, `.codex/agents/devrites-performance-reviewer.toml`, or `.codex/agents/devrites-simplifier-reviewer.toml#g' \
     -e 's#pack/\.claude/skills/devrites-lib/scripts/#.agents/skills/devrites-lib/scripts/#g' \
     -e 's#pack/\.claude/skills/#.agents/skills/#g' \
-    -e 's#pack/\.claude/agents/(devrites-[A-Za-z0-9_-]+)\.md#.codex/agents/\1.toml#g' \
+    -e 's#pack/\.claude/agents/([A-Za-z0-9_-]+)\.md#.codex/agents/\1.toml#g' \
     -e 's#pack/\.claude/agents/#.codex/agents/#g' \
     -e 's#\.claude/skills/devrites-lib/scripts/#.agents/skills/devrites-lib/scripts/#g' \
     -e 's#\.claude/skills/#.agents/skills/#g' \
-    -e 's#\.claude/agents/(devrites-[A-Za-z0-9_-]+)\.md#.codex/agents/\1.toml#g' \
+    -e 's#\.claude/agents/([A-Za-z0-9_-]+)\.md#.codex/agents/\1.toml#g' \
     -e 's#\.claude/agents/#.codex/agents/#g' \
-    -e 's#\.\./\.\./\.\./agents/(devrites-[A-Za-z0-9_-]+)\.md#.codex/agents/\1.toml#g' \
-    -e 's#\.\./\.\./agents/(devrites-[A-Za-z0-9_-]+)\.md#.codex/agents/\1.toml#g' \
+    -e 's#(\.\./)+agents/([A-Za-z0-9_-]+)\.md#.codex/agents/\2.toml#g' \
+    -e 's#\.codex/agents/([A-Za-z0-9_-]+)\.md#.codex/agents/\1.toml#g' \
+    -e 's#Host mapping: Claude Code uses `Agent` \(`Task` is its legacy alias\); Codex uses#Host mapping: Codex fresh-context dispatch uses#g' \
+    -e 's#`Agent` call#`spawn_agent` call#g' \
+    -e 's#Task breakdown#Work-item breakdown#g' \
+    -e 's#(^|[^A-Za-z0-9_])Task([^A-Za-z0-9_]|$)#\1spawn_agent\2#g' \
+    -e 's#dispatch `devrites-source-driven`#invoke `devrites-source-driven`#g' \
+    -e 's#Dispatch `devrites-source-driven`#Invoke `devrites-source-driven`#g' \
+    -e 's#pass-through dispatch to the matching `rite-<verb>` skill#pass-through invocation of the matching `rite-<verb>` skill#g' \
+    -e 's#verb dispatches to the matching `rite-<verb>` skill#verb invokes the matching `rite-<verb>` skill#g' \
+    -e 's#the dispatch map only#the invocation map only#g' \
+    -e 's#→ dispatch per the table above#→ invoke the matching skill per the table above#g' \
     -e 's#(^|[^A-Za-z0-9_./-])/(rite(-[a-z0-9-]+)?)([^A-Za-z0-9_-]|$)#\1$\2\4#g' \
     "$_src" > "$_out"
 }
@@ -26,11 +38,11 @@ gen_codex_skill_file() {
   _src="$1"; _out="$2"; _internal="${3:-0}"
   _tmp="$TMP_GEN_DIR/codex-skill-raw-$(basename "$(dirname "$_src")").md"
   mkdir -p "$(dirname "$_out")"
-  # Internal (explicit-only) skills: replace the frontmatter description with a short stub in the
-  # Codex mirror. Codex uses the description ONLY to build its 2% skills-list for implicit matching;
-  # an explicit-only skill is never matched, so its full description is pure budget waste. Stubbing
-  # the 12 internal skills frees that budget so the user-facing rite-* descriptions fit un-shortened
-  # and keep matching reliably. Explicit `$name` invocation and the full SKILL.md body are untouched.
+  # Give the 12 internal skills a short description in the Codex mirror. Codex
+  # uses descriptions for its 2% implicit-matching budget, but these skills are
+  # invoked by name. Shorter internal descriptions leave that budget for the
+  # public rite-* skills. Keep explicit invocation and each SKILL.md body
+  # unchanged.
   awk -v internal="$_internal" '
     BEGIN { fm = 0; inserted = 0 }
     NR == 1 && $0 == "---" { print; fm = 1; next }
@@ -47,9 +59,13 @@ gen_codex_skill_file() {
       print ""
       print "- Load DevRites engineering standards from `.agents/skills/devrites-lib/reference/standards/`. Read `.agents/skills/devrites-lib/reference/standards/core.md` before workflow work, then load the other `.agents/skills/devrites-lib/reference/standards/*.md` files exactly when this skill asks for them."
       print "- Use the installed `devrites-engine` binary as the canonical runtime helper surface for orientation, gates, and state mutation."
-      print "- When this skill asks for a DevRites specialist or writer agent, **explicitly** spawn the matching Codex custom agent from `.codex/agents/devrites-*.toml` through Codex subagents (`spawn_agent`), then wait for its result and reconcile it as the skill instructs. Do not do the review inline just because the instruction to spawn is embedded here: Codex under-fires embedded spawn/skill instructions (openai/codex #23496), so treat the spawn as required, not optional."
-      print "- The independence of a fresh-context subagent is the point. If Codex genuinely cannot spawn subagents in the current surface, run the documented inline fallback and **label the result an inline fallback, not an independent review**: an inline pass shares the calling context and is weaker evidence."
-      print "- Codex project hooks are installed in `.codex/hooks.json`. Review and trust them with `/hooks` before relying on hook enforcement."
+      print "- **Invocation and dispatch are different:** invoke means run a skill in this context; dispatch means start a fresh agent with `spawn_agent`, await it, and reconcile its result. Never describe inline skill work as a dispatch."
+      print "- For every DevRites specialist or writer dispatch, first call `spawn_agent` with the named `devrites-<role>` custom role. The matching project contract is `.codex/agents/devrites-<role>.toml`."
+      print "- If `spawn_agent` is callable but a named read-only role is unavailable, use generic `explorer` only when the host proves that run has a runtime-enforced read-only sandbox. Tell it to read `.codex/agents/devrites-<role>.toml`, follow its `developer_instructions`, and execute the unchanged packet. A missing read-only custom role is not evidence that spawning is unavailable."
+      print "- Never dispatch generic `worker` for `devrites-slice-wright` unless the host proves that worker run carries exact DevRites identity and the same `.wright-allowlist` enforcement as the named role. Codex reports a generic run as `agent_type=worker`, so the generated global hooks cannot prove that binding. Reject that unsafe rung and use the documented labelled inline wright path with `.reconcile-inline` plus the full reconcile gate."
+      print "- If the host cannot prove the generic explorer is runtime read-only, reject that rung too. Only when no spawn primitive exists or a higher-priority policy rejects a safe spawn may the root run the documented discipline inline. Label it `independence: fallback`, never call it independent, and apply every fallback risk gate. An unbound generic wright or unconfined generic explorer is such a safety rejection, not evidence that no agents exist."
+      print "- Wait for every required fresh-context dispatch before reconciling or advancing. A backgrounded or lost result is incomplete."
+      print "- Codex project hooks are installed in `.codex/hooks.json`; declared-leaf hooks are scoped inside `.codex/agents/devrites-*.toml`. Review and trust them with `/hooks` before relying on hook enforcement."
       print "- When this skill asks a HITL question via `AskUserQuestion`: Codex'\''s equivalent (`request_user_input`) exists only in Plan mode. Outside Plan mode, render the option set as a plain numbered list in chat and **end the turn** so the human answers: NEVER silently pick an option yourself; auto-picking is AFK'\''s contract, gated by the `.devrites/AFK` sentinel."
       print ""
       fm = 0
@@ -62,7 +78,7 @@ gen_codex_skill_file() {
         print ""
         print "## Codex compatibility"
         print ""
-        print "Load DevRites engineering standards from `.agents/skills/devrites-lib/reference/standards/`, use matching `.codex/agents/devrites-*.toml` custom agents for DevRites subagent dispatch, and trust `.codex/hooks.json` with `/hooks` before relying on hooks."
+        print "Load DevRites engineering standards from `.agents/skills/devrites-lib/reference/standards/`. Invocation runs a skill inline; dispatch starts a fresh agent with `spawn_agent` and must be awaited. Try the named `devrites-<role>` first. A missing read-only role may fall back to generic `explorer` reading `.codex/agents/devrites-<role>.toml` only when the host proves runtime-enforced read-only sandboxing. Never use generic `worker` for the wright unless exact DevRites identity and `.wright-allowlist` enforcement are proven; Codex `agent_type=worker` does not prove them, so use the labelled inline `.reconcile-inline` path with full reconciliation. Other inline fallback requires spawning itself to be unavailable or a safe spawn to be rejected by higher-priority policy. Trust `.codex/hooks.json` and the inline hooks in `.codex/agents/devrites-*.toml` with `/hooks` before relying on hooks."
       }
     }
   ' "$_src" > "$_tmp"
@@ -73,6 +89,17 @@ toml_escape() {
   printf '%s' "$1" | sed 's/\\/\\\\/g; s/"/\\"/g'
 }
 
+gen_codex_leaf_hook_toml() {
+  local _active_agent="$1" _required_var="$2" _subcommand="$3" _status="$4" _command
+  _command="cd \"\$(git rev-parse --show-toplevel 2>/dev/null || pwd)\" 2>/dev/null || { printf '%s\\n' 'DevRites: cannot resolve the project root for a declared Codex leaf. (devrites-codex-leaf-guard)' >&2; exit 2; }; DEVRITES_AGENT_RUN=1 DEVRITES_ACTIVE_AGENT=${_active_agent} ${_required_var}=1 devrites-engine hook ${_subcommand} --harness=codex; rc=\$?; case \"\$rc\" in 0) exit 0 ;; 2) exit 2 ;; *) printf '%s\\n' 'DevRites: declared Codex leaf guard unavailable or crashed; install or repair devrites-engine. (devrites-codex-leaf-guard)' >&2; exit 2 ;; esac"
+  printf '\n[[hooks.PreToolUse]]\n'
+  printf 'matcher = "Bash|Shell|sh|exec_command|run_command|Edit|Write|MultiEdit|NotebookEdit|apply_patch|exec|js|python|computer|computer_use|write_stdin|run_code|Agent|Task|spawn_agent|delegate|dispatch_agent|create_agent"\n\n'
+  printf '[[hooks.PreToolUse.hooks]]\n'
+  printf 'type = "command"\n'
+  printf "command = '''%s'''\n" "$_command"
+  printf 'statusMessage = "%s"\n' "$_status"
+}
+
 # Generate a Codex custom-agent TOML file from a Claude Code markdown agent.
 # Codex does not consume .claude/agents/*.md directly; it loads project agents
 # from .codex/agents/*.toml.
@@ -106,6 +133,22 @@ gen_codex_agent() {
     gen_codex_markdown_file "$_body_tmp" "$_body_codex"
     cat "$_body_codex"
     printf "\n%s\n" "'''"
+    case "$_name" in
+      devrites-slice-wright)
+        gen_codex_leaf_hook_toml \
+          "$_name" \
+          "DEVRITES_WRIGHT_AGENT_REQUIRED" \
+          "wright-scope" \
+          "DevRites: checking slice-wright boundary"
+        ;;
+      *)
+        gen_codex_leaf_hook_toml \
+          "$_name" \
+          "DEVRITES_REVIEWER_AGENT_REQUIRED" \
+          "reviewer-readonly" \
+          "DevRites: checking reviewer read-only boundary"
+        ;;
+    esac
   } > "$_out"
 }
 
@@ -126,13 +169,16 @@ This project has DevRites installed for both Claude Code and Codex.
 - DevRites runtime helpers run through the installed `devrites-engine` binary.
 - Before using any DevRites workflow skill, read `.agents/skills/devrites-lib/reference/standards/core.md`. Load other `.agents/skills/devrites-lib/reference/standards/*.md` files when the skill or rule index asks for them. These are DevRites engineering standards, not Codex exec-policy `.rules` files.
 - Custom Codex subagents generated from the DevRites review agents live in `.codex/agents`.
-- When DevRites skill prose asks for a DevRites specialist or writer agent, use the matching Codex custom agent from `.codex/agents/devrites-*.toml` through Codex subagents. If Codex subagents are unavailable in the current surface, run the skill's documented inline fallback and say that the result was not an independent subagent review.
+- In DevRites guidance, **invoke** means run a skill inline in the current context; **dispatch** means start a fresh agent with `spawn_agent`, wait for it, and reconcile its result.
+- For a DevRites dispatch, first use the named `devrites-<role>` custom role. If a read-only role is unavailable but `spawn_agent` still works, use generic `explorer` only when the host proves runtime-enforced read-only sandboxing; tell it to read `.codex/agents/devrites-<role>.toml` before executing the unchanged packet.
+- Do not use generic `worker` for the wright unless exact DevRites identity and `.wright-allowlist` enforcement are proven. Codex exposes that fallback as `agent_type=worker`, which the generated leaf hooks intentionally do not treat as a declared DevRites run. Reject the unsafe worker rung and use the documented labelled inline `.reconcile-inline` path with full reconciliation.
+- Other inline work is allowed only when no spawn primitive exists or higher-priority policy rejects a safe spawn; label it `independence: fallback`, never independent. A missing read-only custom role alone is not such a rejection, but an unconfined generic explorer is.
 - Claude Code agent hook metadata is not active in Codex. The generated Codex agents preserve read-only intent with Codex sandbox settings where possible; still follow DevRites' scope and no-mutation rules explicitly.
 
 ## Workflow contract
 
 - Keep all feature state in `.devrites/work/<slug>/` and preserve `.devrites/ACTIVE`.
-- Follow the DevRites lifecycle: frame -> spec -> temper -> define -> plan -> vet -> build -> converge -> prove -> polish -> review -> seal -> ship -> done.
+- Follow the DevRites lifecycle: frame -> spec -> clarify -> temper -> define -> plan -> vet -> build -> converge -> prove -> polish -> review -> seal -> ship -> done.
 - Claims of completion need recorded evidence in the feature workspace, not confidence alone.
 <!-- END DEVRITES CODEX -->
 EOF
@@ -145,18 +191,13 @@ gen_codex_hooks_json() {
   "hooks": {
     "PreToolUse": [
       {
-        "matcher": "Bash",
+        "matcher": "Bash|Shell|sh|exec_command|run_command",
         "hooks": [
           {
             "type": "command",
-            "command": "command -v devrites-engine >/dev/null 2>&1 || exit 0; cd \"$(git rev-parse --show-toplevel 2>/dev/null || pwd)\" 2>/dev/null || exit 0; exec env DEVRITES_REVIEWER_AGENT_REQUIRED=1 devrites-engine hook reviewer-readonly --harness=codex",
-            "statusMessage": "DevRites: checking reviewer read-only boundary"
-          }
-        ]
-      },
-      {
-        "matcher": "Bash",
-        "hooks": [
+            "command": "command -v devrites-engine >/dev/null 2>&1 || exit 0; cd \"$(git rev-parse --show-toplevel 2>/dev/null || pwd)\" 2>/dev/null || exit 0; exec devrites-engine hook git-guard --harness=codex",
+            "statusMessage": "DevRites: checking destructive Git authority"
+          },
           {
             "type": "command",
             "command": "command -v devrites-engine >/dev/null 2>&1 || exit 0; cd \"$(git rev-parse --show-toplevel 2>/dev/null || pwd)\" 2>/dev/null || exit 0; exec devrites-engine hook allow --harness=codex",
@@ -171,11 +212,6 @@ gen_codex_hooks_json() {
             "type": "command",
             "command": "command -v devrites-engine >/dev/null 2>&1 || exit 0; cd \"$(git rev-parse --show-toplevel 2>/dev/null || pwd)\" 2>/dev/null || exit 0; exec devrites-engine hook a1-guard --harness=codex",
             "statusMessage": "DevRites: checking build write boundary"
-          },
-          {
-            "type": "command",
-            "command": "command -v devrites-engine >/dev/null 2>&1 || exit 0; cd \"$(git rev-parse --show-toplevel 2>/dev/null || pwd)\" 2>/dev/null || exit 0; exec env DEVRITES_WRIGHT_AGENT_REQUIRED=1 devrites-engine hook wright-scope --harness=codex",
-            "statusMessage": "DevRites: checking slice file scope"
           }
         ]
       }
@@ -293,8 +329,8 @@ gen_codex_hooks_json() {
   }
 }
 EOF
-# NOTE: no SessionEnd entry: Codex does not emit a SessionEnd hook event (its lifecycle events
-# are SessionStart/SubagentStart/PreToolUse/PermissionRequest/PostToolUse/PreCompact/PostCompact/
-# UserPromptSubmit/SubagentStop/Stop). The `hook event session-end` trace is Claude-only; re-add
-# here if Codex ever ships the event.
+# Codex has no SessionEnd hook event. Its lifecycle events are
+# SessionStart/SubagentStart/PreToolUse/PermissionRequest/PostToolUse/PreCompact/
+# PostCompact/UserPromptSubmit/SubagentStop/Stop. The `hook event session-end`
+# trace remains Claude-only until Codex adds that event.
 }