devrites 2.6.1 → 3.0.1

package/scripts/build-binaries.sh

@@ -0,0 +1,75 @@
+#!/usr/bin/env bash
+# Cross-compile devrites-engine for every supported target and emit a sha256
+# sidecar per binary — the artifacts attached to the GitHub Release alongside the
+# pack tarball. Pure-Go (CGO_ENABLED=0) so every target builds
+# from one Linux runner with no cross-toolchain. The version is stamped into the
+# binary via -ldflags so `devrites-engine doctor` reports the release it came from.
+#
+# Usage: build-binaries.sh <version>          # version WITHOUT a leading "v"
+#
+# Output: dist/bin/devrites-<os>-<arch>[.exe] plus a "<sha>  <name>" .sha256 each.
+# Binary names are UNVERSIONED so the installer can fetch
+# github.com/<repo>/releases/latest/download/devrites-<os>-<arch> directly.
+set -euo pipefail
+
+VERSION="${1:-}"
+if [[ -z "$VERSION" ]]; then
+  echo "usage: build-binaries.sh <version>" >&2
+  exit 1
+fi
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+ENGINE="$ROOT/engine"
+OUT="$ROOT/dist/bin"
+MODULE="github.com/devrites/devrites"
+
+if [[ ! -d "$ENGINE" ]]; then
+  echo "build-binaries: no engine/ directory at $ENGINE" >&2
+  exit 1
+fi
+
+# The release matrix: darwin arm64/amd64, linux amd64/arm64, windows amd64.
+TARGETS=(
+  "darwin/arm64"
+  "darwin/amd64"
+  "linux/amd64"
+  "linux/arm64"
+  "windows/amd64"
+)
+
+rm -rf "$OUT"
+mkdir -p "$OUT"
+
+sha256_of() {
+  # Emit "<sha256>  <filename>" (no path) so it verifies from any cwd.
+  local f="$1"
+  if command -v shasum >/dev/null 2>&1; then
+    shasum -a 256 "$f"
+  elif command -v sha256sum >/dev/null 2>&1; then
+    sha256sum "$f"
+  else
+    echo "build-binaries: no sha256 tool found" >&2
+    return 1
+  fi
+}
+
+echo "Cross-compiling devrites v${VERSION} (CGO_ENABLED=0)"
+cd "$ENGINE"
+
+for target in "${TARGETS[@]}"; do
+  os="${target%%/*}"
+  arch="${target##*/}"
+  name="devrites-${os}-${arch}"
+  [[ "$os" == "windows" ]] && name="${name}.exe"
+
+  echo "  → ${name}"
+  CGO_ENABLED=0 GOOS="$os" GOARCH="$arch" \
+    go build -trimpath \
+      -ldflags "-s -w -X ${MODULE}/internal/version.Version=v${VERSION}" \
+      -o "$OUT/$name" .
+
+  ( cd "$OUT" && sha256_of "$name" > "${name}.sha256" )
+done
+
+echo "Built $(find "$OUT" -maxdepth 1 -name 'devrites-*' ! -name '*.sha256' | wc -l | tr -d ' ') binaries in $OUT"
+ls -lh "$OUT"

package/scripts/build-host-artifacts.sh

@@ -0,0 +1,100 @@
+#!/usr/bin/env bash
+# build-host-artifacts.sh — render host-native Claude and Codex artifacts from
+# the canonical pack.
+#
+# Default output is pack/generated/ so npm pack can ship prebuilt surfaces.
+# Tests may set DEVRITES_HOST_ARTIFACT_DIR to a temporary directory.
+set -u
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+PACK_SRC="$ROOT/pack/.claude"
+OUT_ROOT="${DEVRITES_HOST_ARTIFACT_DIR:-$ROOT/pack/generated}"
+
+[ -d "$PACK_SRC/skills" ] || { echo "build-host-artifacts: missing $PACK_SRC/skills" >&2; exit 1; }
+[ -d "$PACK_SRC/agents" ] || { echo "build-host-artifacts: missing $PACK_SRC/agents" >&2; exit 1; }
+
+TMP_GEN_DIR="$(mktemp -d 2>/dev/null || echo "${TMPDIR:-/tmp}/devrites-host-artifacts.$$")"
+cleanup() { rm -rf "$TMP_GEN_DIR"; }
+trap cleanup EXIT
+
+# shellcheck source=codex-generate.sh
+. "$ROOT/scripts/codex-generate.sh"
+
+copy_tree() {
+  _src="$1"; _dest="$2"
+  mkdir -p "$(dirname "$_dest")"
+  rm -rf "$_dest"
+  cp -R "$_src" "$_dest"
+}
+
+render_codex_skill_tree() {
+  _sd="$1"; _dest="$2"
+  mkdir -p "$_dest"
+  while IFS= read -r f; do
+    _r="${f#$_sd/}"
+    _out="$_dest/$_r"
+    mkdir -p "$(dirname "$_out")"
+    case "$_r" in
+      SKILL.md)
+        _internal=0
+        _implicit_disabled=0
+        if awk 'NR==1&&$0=="---"{fm=1;next} fm&&$0=="---"{exit} fm&&/^user-invocable:[[:space:]]*false/{u=1} END{exit !u}' "$f"; then
+          _internal=1
+        fi
+        if awk 'NR==1&&$0=="---"{fm=1;next} fm&&$0=="---"{exit} fm&&/^disable-model-invocation:[[:space:]]*true/{u=1} END{exit !u}' "$f"; then
+          _implicit_disabled=1
+        fi
+        gen_codex_skill_file "$f" "$_out" "$_internal"
+        if [ "$_internal" -eq 1 ] || [ "$_implicit_disabled" -eq 1 ]; then
+          mkdir -p "$_dest/agents"
+          printf 'policy:\n  allow_implicit_invocation: false\n' > "$_dest/agents/openai.yaml"
+        fi
+        ;;
+      *.md)
+        gen_codex_markdown_file "$f" "$_out"
+        ;;
+      *)
+        cp "$f" "$_out"
+        ;;
+    esac
+  done < <(find "$_sd" -type f)
+}
+
+rm -rf "$OUT_ROOT"
+mkdir -p "$OUT_ROOT/claude" "$OUT_ROOT/codex"
+
+# Claude artifacts are host-native copies of the canonical pack.
+copy_tree "$PACK_SRC/skills" "$OUT_ROOT/claude/skills"
+copy_tree "$PACK_SRC/agents" "$OUT_ROOT/claude/agents"
+rm -rf "$OUT_ROOT/claude/agents/.impeccable"
+cp "$PACK_SRC/settings.json" "$OUT_ROOT/claude/settings.json"
+
+# Codex artifacts are generated host-native mirrors.
+mkdir -p "$OUT_ROOT/codex/skills" "$OUT_ROOT/codex/agents"
+while IFS= read -r d; do
+  name="$(basename "$d")"
+  render_codex_skill_tree "$d" "$OUT_ROOT/codex/skills/$name"
+done < <(find "$PACK_SRC/skills" -mindepth 1 -maxdepth 1 -type d)
+
+while IFS= read -r f; do
+  name="$(basename "$f" .md)"
+  gen_codex_agent "$f" "$OUT_ROOT/codex/agents/$name.toml"
+done < <(find "$PACK_SRC/agents" -maxdepth 1 -type f -name '*.md')
+
+gen_codex_agents_bridge "$OUT_ROOT/codex/AGENTS.md"
+gen_codex_hooks_json "$OUT_ROOT/codex/hooks.json"
+
+cat > "$OUT_ROOT/README.md" <<'EOF'
+# Generated DevRites Host Artifacts
+
+This directory is generated by `scripts/build-host-artifacts.sh`.
+
+- `claude/` contains Claude Code-native skills, agents, and settings.
+- `codex/` contains Codex-native skill mirrors, custom-agent TOML, hook
+  blocks, and AGENTS bridge content.
+
+Do not edit these files by hand. Edit `pack/.claude/` or
+`scripts/codex-generate.sh`, then rebuild.
+EOF
+
+echo "build-host-artifacts: wrote $OUT_ROOT"

package/scripts/build-release-tarball.sh

@@ -13,7 +13,7 @@ if [[ -z "$VERSION" ]]; then
 fi
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd)"
-DIST="$ROOT/dist"
+DIST="${DEVRITES_RELEASE_DIST_DIR:-$ROOT/dist}"
 NAME="devrites-v${VERSION}"
 STAGE="$DIST/$NAME"
 
@@ -27,6 +27,7 @@ mkdir -p "$STAGE"
 # Files and directories shipped to end-users.
 PAYLOAD=(
   pack
+  engine
   scripts
   mcp
   docs
@@ -45,10 +46,23 @@ PAYLOAD=(
 
 for item in "${PAYLOAD[@]}"; do
   if [[ -e "$item" ]]; then
-    cp -R "$item" "$STAGE/"
+    if [[ "$item" == "engine" ]] && git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+      while IFS= read -r -d '' path; do
+        if [[ "$path" == engine/testdata/golden/* ]]; then
+          continue
+        fi
+        mkdir -p "$STAGE/$(dirname "$path")"
+        cp "$path" "$STAGE/$path"
+      done < <(git ls-files -z -- "$item")
+    else
+      cp -R "$item" "$STAGE/"
+    fi
   fi
 done
 
+# Ship the same prebuilt host-native artifacts that npm pack includes.
+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.
 rm -rf "$STAGE/docs/internal" "$STAGE/scripts/.cache" 2>/dev/null || true
 

package/scripts/check-cross-refs.py

@@ -14,11 +14,17 @@ existed. Three checks, tuned for near-zero false positives:
 
 Scans pack/.claude/. Exit 1 on any dead reference. Read-only.
 """
+import argparse
 import os
 import re
 import sys
 
-ROOT = os.path.join("pack", ".claude")
+parser = argparse.ArgumentParser()
+parser.add_argument("--root", default=".", help="repository root containing pack/.claude")
+args = parser.parse_args()
+
+REPO_ROOT = os.path.normpath(args.root)
+ROOT = os.path.join(REPO_ROOT, "pack", ".claude")
 SKILLS_ROOT = os.path.join(ROOT, "skills")
 
 # Runtime artifacts live under .devrites/ (per-feature work/<slug>/ files, plus the
@@ -36,13 +42,19 @@ WORKSPACE_ARTIFACTS = {
     "devex.md", "retro.md",
     # spec-quality checklists (.devrites/work/<slug>/checklists/<domain>.md)
     "functional.md", "data-model.md", "interaction.md", "non-functional.md", "edge-cases.md",
+    # feature manifest (work/<slug>/feature.md) + the planning/proof artifacts the
+    # lifecycle generates: rite-define writes architecture.md + traceability.md, rite-spec
+    # writes flows.md + index.md, and proof.md is the SectionProof file (see engine state schema).
+    "feature.md", "architecture.md", "traceability.md", "flows.md", "index.md", "proof.md",
+    # Named outputs created in the user's workspace by their owning workflow.
+    "agent.md", "dogfood.md", "walkthrough.md", "ai-spec.md",
 }
 
 # Files the skills legitimately tell Claude to read in the USER's project / the repo,
 # which are not part of the shipped pack.
 PROJECT_DOCS = {
     "CLAUDE.md", "AGENTS.md", "DESIGN.md", "PRODUCT.md", "CONTEXT.md", "NOTES.md",
-    "README.md", "CHANGELOG.md", "CONTRIBUTING.md", "cli-mcp.md",
+    "README.md", "CHANGELOG.md", "CONTRIBUTING.md", "cli.md",
     "ADR-NNN.md",  # generated per-decision ADR in the user repo (docs/adr/), promoted at /rite-ship
 }
 
@@ -51,7 +63,9 @@ def resolve(here, link):
     """Resolve a link. `.claude/...`-rooted paths are install-root-relative (= pack/
     in this repo); everything else is relative to the containing file."""
     if link.startswith(".claude/"):
-        return os.path.normpath(os.path.join("pack", link))
+        return os.path.normpath(os.path.join(REPO_ROOT, "pack", link))
+    if link.startswith("docs/"):
+        return os.path.normpath(os.path.join(REPO_ROOT, link))
     return os.path.normpath(os.path.join(here, link))
 
 md_files = []

package/scripts/check-generated-skill-budget.mjs

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+// Guard generated host skill payloads against accidental context bloat.
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join, relative } from 'node:path';
+
+const root = new URL('..', import.meta.url).pathname.replace(/\/$/, '');
+const base = process.argv[2] || join(root, 'pack', '.claude', 'skills');
+const totalLimit = Number(process.env.DEVRITES_SKILL_TOTAL_BUDGET || 900_000);
+const fileLimit = Number(process.env.DEVRITES_SKILL_FILE_BUDGET || 64_000);
+const referenceFileLimit = Number(process.env.DEVRITES_REFERENCE_FILE_BUDGET || 32_000);
+let total = 0;
+let failures = 0;
+
+function fail(msg) {
+  console.error(`FAIL: ${msg}`);
+  failures++;
+}
+
+if (!existsSync(base)) {
+  console.log(`skill-budget: skip missing ${base}`);
+  process.exit(0);
+}
+function markdownFiles(dir) {
+  const files = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const file = join(dir, entry.name);
+    if (entry.isDirectory()) files.push(...markdownFiles(file));
+    else if (entry.isFile() && entry.name.endsWith('.md')) files.push(file);
+  }
+  return files;
+}
+
+for (const file of markdownFiles(base)) {
+  const bytes = Buffer.byteLength(readFileSync(file));
+  total += bytes;
+  const limit = file.endsWith('/SKILL.md') ? fileLimit : referenceFileLimit;
+  if (bytes > limit) fail(`${relative(root, file)} is ${bytes} bytes (max ${limit})`);
+}
+if (total > totalLimit) fail(`${relative(root, base)} markdown payload is ${total} bytes (max ${totalLimit})`);
+console.log(`skill-budget: ${total} markdown bytes under ${relative(root, base) || base}`);
+process.exit(failures ? 1 : 0);

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

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+// Per-file and aggregate byte ratchet for canonical prompt/instruction docs.
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
+
+const defaultRoot = new URL('..', import.meta.url).pathname.replace(/\/$/, '');
+const argv = process.argv.slice(2);
+function option(name, fallback) {
+  const i = argv.indexOf(name);
+  return i >= 0 ? argv[i + 1] : fallback;
+}
+const root = resolve(option('--root', defaultRoot));
+const baselinePath = resolve(option('--baseline', join(root, 'tests', 'instruction-size-baseline.json')));
+const write = argv.includes('--write');
+
+function lfBytes(text) {
+  return Buffer.byteLength(text.replace(/\r\n/g, '\n'));
+}
+
+function markdownFiles(dir) {
+  if (!existsSync(dir)) return [];
+  const files = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const file = join(dir, entry.name);
+    if (entry.isDirectory()) files.push(...markdownFiles(file));
+    else if (entry.isFile() && entry.name.endsWith('.md')) files.push(file);
+  }
+  return files;
+}
+
+function collect() {
+  const roots = [
+    join(root, 'pack', '.claude', 'skills'),
+    join(root, 'pack', '.claude', 'agents'),
+    join(root, 'pack', '.claude', 'rules'),
+  ];
+  const out = {};
+  for (const file of roots.flatMap(markdownFiles)) {
+    out[relative(root, file)] = lfBytes(readFileSync(file, 'utf8'));
+  }
+  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 current = { version: 2, total_bytes: totalBytes, files };
+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)`);
+  process.exit(0);
+}
+
+if (!existsSync(baselinePath)) {
+  console.error(`FAIL: missing ${relative(root, baselinePath)}; run node scripts/check-instruction-size-baseline.mjs --write`);
+  process.exit(1);
+}
+const baseline = JSON.parse(readFileSync(baselinePath, 'utf8'));
+if (baseline.version !== 2 || !baseline.files || !Number.isInteger(baseline.total_bytes)) {
+  console.error(`FAIL: ${relative(root, baselinePath)} uses an obsolete schema; regenerate it with --write`);
+  process.exit(1);
+}
+let failures = 0;
+function fail(msg) {
+  console.error(`FAIL: ${msg}`);
+  failures++;
+}
+for (const file of Object.keys(files)) {
+  if (!(file in baseline.files)) fail(`${file} missing from baseline (${files[file]} bytes)`);
+  else if (files[file] > baseline.files[file]) fail(`${file} grew by ${files[file] - baseline.files[file]} bytes (${baseline.files[file]} -> ${files[file]})`);
+}
+for (const file of Object.keys(baseline.files)) {
+  if (!(file in files)) fail(`${file} in baseline but file is gone`);
+}
+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`);
+process.exit(failures ? 1 : 0);

package/scripts/check-invocation-integrity.py

@@ -0,0 +1,113 @@
+#!/usr/bin/env python3
+"""Invocation-integrity gate — every skill/rule an agent or skill NAMES must resolve, both harnesses.
+
+`check-cross-refs.py` validates markdown links. This validates the thing it can't: a **bare
+skill-name invocation** (`$devrites-frontend-craft`, `Skill(devrites-source-driven)`, "invoke the
+`devrites-api-interface` skill") and a **rule read** (`.claude/skills/devrites-lib/reference/standards/security.md`) must each point
+at something that actually exists — on Claude Code AND on the Codex-translated tree — or the agent
+calls into the void at runtime. Also asserts the Claude→Codex skill/rule mirror is complete.
+
+Self-contained: installs DevRites into a temp dir to get the Codex tree, sweeps, cleans up.
+Run: python3 scripts/check-invocation-integrity.py    (exit 0 clean, 1 on any unresolved reference)
+"""
+import os, re, sys, glob, subprocess, tempfile, shutil
+
+REPO = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+PACK = os.path.join(REPO, "pack/.claude")
+
+# devrites-* tokens that are scripts/hooks/mcp, not skills — legitimate non-skill references.
+NONSKILL = {
+    "devrites-mcp", "devrites-lib", "devrites-reviewer-readonly", "devrites-wright-scope",
+    "devrites-a1-guard", "devrites-allow", "devrites-redwatch", "devrites-orient",
+    "devrites-statusline", "devrites-stop-gate", "devrites-cursor", "devrites-refresh-indexes",
+    "devrites-source-cache", "devrites-source-cache-pre", "devrites-source-cache-post",
+    "devrites-subagent-orient", "devrites-detect", "devrites-prose-craft-report",
+    # the control-plane binary, invoked by name in skill/agent prose ("devrites-engine seal")
+    "devrites-engine",
+    # a git commit-trailer marker ("[devrites-context]" body in a WIP checkpoint), not a skill
+    "devrites-context",
+}
+# names a skill deliberately mentions as NON-existent (self-documenting prose).
+DOCUMENTED_NONEXISTENT = {"rite-use"}
+
+SKILL_TOK = re.compile(r"\$?\b(devrites-[a-z0-9-]+|rite-[a-z0-9-]+)\b")
+RULE_REF = re.compile(r"(?:\.claude/skills/devrites-lib/reference/standards|\.agents/skills/devrites-lib/reference/standards)/([a-z0-9-]+)\.md")
+CODEX_SLASH_RITE = re.compile(r"(^|[^A-Za-z0-9_./-])/(rite(?:-[a-z0-9-]+)?)([^A-Za-z0-9_-]|$)")
+
+
+def names(pattern, strip):
+    return {os.path.basename(p)[:-strip] if strip else os.path.basename(p) for p in glob.glob(pattern)}
+
+
+def scan(path, valid_names, valid_rules, problems):
+    try:
+        txt = open(path, encoding="utf-8").read()
+    except Exception:
+        return
+    for name in set(SKILL_TOK.findall(txt)):
+        if name in valid_names or name in NONSKILL or name in DOCUMENTED_NONEXISTENT:
+            continue
+        problems.append(f"{os.path.relpath(path, REPO)}: unresolved skill/agent name '{name}'")
+    for r in set(RULE_REF.findall(txt)):
+        if r not in valid_rules:
+            problems.append(f"{os.path.relpath(path, REPO)}: rule ref '{r}.md' not present")
+
+
+def scan_codex_sigils(path, problems):
+    try:
+        txt = open(path, encoding="utf-8").read()
+    except Exception:
+        return
+    for lineno, line in enumerate(txt.splitlines(), 1):
+        if CODEX_SLASH_RITE.search(line):
+            problems.append(f"{os.path.relpath(path, REPO)}:{lineno}: Codex mirror uses /rite invocation; use $rite")
+
+
+def main():
+    target = tempfile.mkdtemp()
+    try:
+        env = os.environ.copy()
+        env["DEVRITES_NO_BINARY"] = "1"
+        r = subprocess.run(["bash", os.path.join(REPO, "install.sh"), "--target", target, "--no-binary"],
+                           capture_output=True, text=True, env=env)
+        if r.returncode != 0:
+            print("FAIL: install failed\n" + r.stderr[-2000:]); return 1
+
+        claude_skills = names(f"{PACK}/skills/*", 0)
+        claude_rules = names(f"{PACK}/skills/devrites-lib/reference/standards/*.md", 3)
+        claude_agents = names(f"{PACK}/agents/*.md", 3)
+        codex_skills = names(f"{target}/.agents/skills/*", 0)
+        codex_rules = names(f"{target}/.agents/skills/devrites-lib/reference/standards/*.md", 3)
+        codex_agents = names(f"{target}/.codex/agents/*.toml", 5)
+
+        problems, mirror = [], []
+        if claude_skills != codex_skills:
+            mirror.append(f"skills not mirrored: {sorted(claude_skills ^ codex_skills)}")
+        if claude_rules != codex_rules:
+            mirror.append(f"rules not mirrored: {sorted(claude_rules ^ codex_rules)}")
+
+        # Claude side
+        for f in glob.glob(f"{PACK}/agents/*.md") + glob.glob(f"{PACK}/skills/**/*.md", recursive=True):
+            scan(f, claude_skills | claude_agents, claude_rules, problems)
+        # Codex side
+        for f in glob.glob(f"{target}/.codex/agents/*.toml") + glob.glob(f"{target}/.agents/skills/**/SKILL.md", recursive=True):
+            scan(f, codex_skills | codex_agents, codex_rules, problems)
+            scan_codex_sigils(f, problems)
+
+        print(f"invocation-integrity: {len(claude_skills)} skills / {len(claude_rules)} rules / "
+              f"{len(claude_agents)} agents, mirrored to Codex; scanned agents + skills, both harnesses.")
+        for m in mirror:
+            print("  MIRROR: " + m)
+        for p in sorted(set(problems)):
+            print("  DEAD: " + p)
+        if problems or mirror:
+            print("INVOCATION-INTEGRITY: FAIL")
+            return 1
+        print("INVOCATION-INTEGRITY: PASS — every named skill/rule resolves on both harnesses.")
+        return 0
+    finally:
+        shutil.rmtree(target, ignore_errors=True)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/check-no-global-writes.sh

@@ -36,6 +36,28 @@ for f in $SCRIPTS; do
 done
 [ "$fail" -eq 0 ] && echo "ok: no write operations target global agent homes"
 
+# 3) no write operation may target a system bin directory EXCEPT the one sanctioned
+#    engine-binary path (the devrites-engine control-plane binary; issue 10). Anything else
+#    writing to /usr/bin, /usr/local/bin, /bin, /sbin, or ~/.local/bin is a global
+#    write the installer must not do. The carve-out is exactly a `devrites-engine` (or
+#    `devrites.exe`) leaf under /usr/local/bin or ~/.local/bin — never /usr/bin.
+BIN_RE='((\$HOME|~)/\.local/bin|/usr/local/bin|/usr/bin|/bin|/sbin)'
+# Sanctioned: the write's bin path ends in .../devrites-engine (optionally .exe) and sits
+# under /usr/local/bin or ~/.local/bin. The trailing boundary keeps `devrites-lib`
+# or `devritesX` from sneaking through.
+SANCTIONED_RE='((\$HOME|~)/\.local/bin|/usr/local/bin)/devrites-engine(\.exe)?([^A-Za-z0-9._-]|$)'
+for f in $SCRIPTS; do
+  [ -f "$f" ] || continue
+  hits="$(grep -nE "$BIN_RE" "$f" | grep -vE '^\s*[0-9]+:\s*#' | grep -E "$WRITE_RE" \
+    | grep -vE "$SANCTIONED_RE" || true)"
+  if [ -n "$hits" ]; then
+    echo "FAIL: possible global bin write in ${f#$ROOT/} (only /usr/local/bin/devrites-engine or ~/.local/bin/devrites-engine is sanctioned):"
+    printf '%s\n' "$hits" | sed 's/^/    /'
+    fail=1
+  fi
+done
+[ "$fail" -eq 0 ] && echo "ok: no write operations target system bin dirs (except the sanctioned devrites-engine binary)"
+
 if [ "$fail" -eq 0 ]; then
   echo "PASS: no global-write risks detected"
 else

package/scripts/check-no-personal-paths.py

@@ -0,0 +1,50 @@
+#!/usr/bin/env python3
+"""Fail if shipped DevRites artifacts contain maintainer-local absolute paths."""
+import os
+import re
+import sys
+
+ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
+TARGETS = ["README.md", "docs", "pack", "scripts", "install.sh", "update.sh", "uninstall.sh", "package.json"]
+PATTERNS = [
+    re.compile(r"/Users/(?!runner|homebrew|shared/)[A-Za-z0-9._-]+"),
+    re.compile(r"/home/(?!runner|circleci|github|vscode|node)[A-Za-z0-9._-]+"),
+    re.compile(r"C:\\\\Users\\\\(?!runner|Public)[A-Za-z0-9._-]+", re.I),
+]
+TEXT_EXTS = {"", ".md", ".sh", ".py", ".js", ".mjs", ".json", ".yaml", ".yml", ".toml", ".txt"}
+ALLOW = {"scripts/check-no-personal-paths.py"}
+
+findings = []
+for target in TARGETS:
+    path = os.path.join(ROOT, target)
+    if not os.path.exists(path):
+        continue
+    files = []
+    if os.path.isdir(path):
+        for base, dirs, names in os.walk(path):
+            dirs[:] = [d for d in dirs if d not in {"node_modules", ".git", "__pycache__"}]
+            files += [os.path.join(base, n) for n in names]
+    else:
+        files = [path]
+    for file in files:
+        rel = os.path.relpath(file, ROOT)
+        if rel in ALLOW:
+            continue
+        if os.path.splitext(file)[1].lower() not in TEXT_EXTS:
+            continue
+        try:
+            text = open(file, encoding="utf-8").read()
+        except (OSError, UnicodeDecodeError):
+            continue
+        for lineno, line in enumerate(text.splitlines(), 1):
+            if "no-personal-paths-ignore" in line:
+                continue
+            for rx in PATTERNS:
+                if rx.search(line):
+                    findings.append(f"{rel}:{lineno}: {line.strip()[:140]}")
+
+if findings:
+    print("personal-path findings:")
+    print("\n".join(findings))
+    sys.exit(1)
+print("no-personal-paths: PASS")

package/scripts/check-reference-governance.mjs

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+// Ensure supporting skill references are reachable or explicitly time-bounded.
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { basename, dirname, join, normalize, relative, resolve, sep } from 'node:path';
+
+const defaultRoot = new URL('..', import.meta.url).pathname.replace(/\/$/, '');
+const argv = process.argv.slice(2);
+function option(name, fallback) {
+  const i = argv.indexOf(name);
+  return i >= 0 ? argv[i + 1] : fallback;
+}
+const skillsDir = resolve(option('--skills-dir', join(defaultRoot, 'pack', '.claude', 'skills')));
+const allowlistPath = resolve(option('--allowlist', join(defaultRoot, 'tests', 'reference-orphan-allowlist.json')));
+
+function markdownFiles(dir) {
+  const files = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const file = join(dir, entry.name);
+    if (entry.isDirectory()) files.push(...markdownFiles(file));
+    else if (entry.isFile() && entry.name.endsWith('.md')) files.push(normalize(file));
+  }
+  return files;
+}
+
+const files = markdownFiles(skillsDir);
+const fileSet = new Set(files);
+const byBase = new Map();
+for (const file of files) byBase.set(basename(file), [...(byBase.get(basename(file)) || []), file]);
+const entries = files.filter((file) => basename(file) === 'SKILL.md');
+const reachable = new Set(entries);
+const queue = [...entries];
+const markdownLink = /\]\(([^)#]+\.md)(?:#[^)]*)?\)/g;
+const backtickPath = /`([A-Za-z0-9._/\-]+\.md)`/g;
+
+function candidates(from, token) {
+  if (/^(?:https?:|mailto:)/.test(token)) return [];
+  if (token.startsWith('.claude/skills/')) return [join(skillsDir, token.slice('.claude/skills/'.length))];
+  if (token.includes('/')) return [resolve(dirname(from), token)];
+  return byBase.get(token) || [];
+}
+
+while (queue.length) {
+  const from = queue.shift();
+  const text = readFileSync(from, 'utf8');
+  const tokens = [
+    ...[...text.matchAll(markdownLink)].map((match) => match[1]),
+    ...[...text.matchAll(backtickPath)].map((match) => match[1]),
+  ];
+  for (const token of tokens) {
+    for (const candidate of candidates(from, token)) {
+      const file = normalize(candidate);
+      if (fileSet.has(file) && !reachable.has(file)) {
+        reachable.add(file);
+        queue.push(file);
+      }
+    }
+  }
+}
+
+const allowlist = existsSync(allowlistPath) ? JSON.parse(readFileSync(allowlistPath, 'utf8')) : {};
+const today = new Date().toISOString().slice(0, 10);
+let failures = 0;
+function fail(message) { console.error(`FAIL: ${message}`); failures++; }
+for (const [file, exception] of Object.entries(allowlist)) {
+  if (!exception || !exception.owner || !exception.reason || !/^\d{4}-\d{2}-\d{2}$/.test(exception.expires || '')) {
+    fail(`${file}: orphan exception requires owner, reason, and YYYY-MM-DD expires`);
+  } else if (exception.expires < today) {
+    fail(`${file}: orphan exception expired ${exception.expires}`);
+  }
+}
+const orphans = files.filter((file) => basename(file) !== 'SKILL.md' && !reachable.has(file));
+for (const file of orphans) {
+  const rel = relative(skillsDir, file).split(sep).join('/');
+  if (!(rel in allowlist)) fail(`${rel}: unreachable reference`);
+}
+for (const file of Object.keys(allowlist)) {
+  if (!orphans.some((orphan) => relative(skillsDir, orphan).split(sep).join('/') === file)) {
+    fail(`${file}: orphan exception is stale; reference is reachable or gone`);
+  }
+}
+console.log(`reference-governance: ${files.length - entries.length} references, ${orphans.length} orphan(s)`);
+process.exit(failures ? 1 : 0);