devrites 1.19.0

package/pack/.claude/skills/rite-vet/reference/review-axes.md

@@ -0,0 +1,167 @@
+# The vet review — scope challenge, four axes, required outputs
+
+The body of `/rite-vet`. Run §0 first as a blocking gate, then the four axes one at a time,
+then the required outputs. Apply the senior-engineer lenses in [`eng-lenses.md`](eng-lenses.md)
+throughout — they're how you *see* the findings, not a separate checklist. Every finding is
+calibrated and gated (see "Confidence + verification gate" below) before it reaches the human.
+
+---
+
+## §0. Scope Challenge (blocking gate — runs before any axis)
+
+Before reviewing *how* the plan builds, challenge *whether it should build this much*. This is
+implementation-scope discipline (the spec's ambition is settled — that was `/rite-temper`).
+
+1. **What already exists?** For each sub-problem in the plan, find the existing code/flow that
+   already solves it (use a code-intelligence index if available — see `../../../rules/tooling.md`).
+   Can the plan **capture outputs from an existing
+   flow** instead of building a parallel one? Reuse → extend → build new, in that order
+   (`coding-style.md`). List every reuse opportunity the plan misses.
+2. **Minimum diff.** What's the smallest set of changes that meets the spec's *acceptance
+   criteria*? Flag any planned work that can be deferred without blocking acceptance. Be ruthless
+   about implementation scope creep — but never cut an acceptance criterion (that's a Drift Guard
+   matter, not a trim).
+3. **Complexity smell.** If `plan.md` touches **>8 files** or adds **>2 new services / modules /
+   classes**, treat it as a smell. Check the plan's complexity gate justifies it. If it doesn't
+   → **STOP**: name what's overbuilt, propose a smaller version that meets acceptance, and ask
+   via `AskUserQuestion` whether to reduce or proceed. Do not start the axes until answered.
+4. **Built-in check.** For each new pattern / infra component / concurrency approach the plan
+   introduces, verify a framework/runtime built-in doesn't already do it, and that the choice is
+   current best practice with no known footgun — dispatch `devrites-source-driven` to confirm at
+   the source and record the citation. A custom roll where a built-in exists is a scope-reduction
+   finding.
+5. **Completeness check.** Is the plan doing the complete version or a shortcut? With AI-assisted
+   coding the cost of completeness (full edge-case handling, complete error paths, real test
+   coverage) is a fraction of what it was — a shortcut that saves human-hours but only saves
+   minutes here is a false economy. Prefer the complete option; flag shortcuts that exist only to
+   save effort that AI has already made cheap.
+6. **Distribution check.** If the plan introduces a new artifact (CLI binary, package, container,
+   deployable), does it include how it gets built / published / installed? If distribution is
+   deferred, say so explicitly in "NOT in scope" — don't let it silently drop.
+
+> **STOP discipline.** If the complexity smell trips, the `AskUserQuestion` is a tool call, not
+> prose. Naming the 80%-solution in chat and continuing is the failure this gate exists to prevent.
+
+If the smell does not trip, present the §0 findings and proceed to Axis 1.
+
+---
+
+## The four axes (one at a time, ≤8 findings each)
+
+For each axis: evaluate, then **walk each finding WITH the human** via `AskUserQuestion` (one
+issue per call — see "How to ask" below). HITL pauses on each material finding; AFK auto-applies
+within the gate ceiling (`depth.md`). If an axis genuinely has no issue, say "No issues,
+moving on" and continue — don't manufacture findings.
+
+### 1. Architecture
+- Component boundaries, coupling, data-flow patterns, single points of failure.
+- Scaling characteristics; where the plan's approach breaks under real load.
+- Security architecture at the seams (auth, data access, API boundaries) — does the plan name
+  the trust boundary for each untrusted input?
+- For each new codepath / integration point: **one realistic production failure scenario** and
+  whether the plan accounts for it (feeds the failure-mode table).
+- Does any key flow deserve an ASCII diagram in the plan or an inline comment in the code the
+  build will write? Name the files that should carry one.
+
+### 2. Plan code-quality
+- Module structure the plan implies; DRY across the slices (flag planned repetition aggressively).
+- Error-handling + edge cases the plan names — and the ones it doesn't (call those out explicitly).
+- Over-engineering (premature abstraction, an extension point with no second caller) vs
+  under-engineering (fragile / hacky) relative to `patterns.md` + `coding-style.md`.
+- Tech-debt hotspots the plan walks into; existing inline diagrams in touched files that the
+  change will make stale.
+
+### 3. Test-coverage design
+The differentiator: design the tests *before* the code, so the build writes them alongside.
+- **Framework detection** — find the project's existing test runner + conventions; match them
+  (never introduce a new runner to prove one change — `testing.md`).
+- **Map acceptance → tests.** Every spec acceptance criterion must map to ≥1 planned test.
+- **Tool per path** — unit (pure logic, single function, edge cases), integration/E2E (a user
+  flow spanning 3+ components, an auth/payment/data-loss path, a mock-hides-failure boundary),
+  eval (an LLM/prompt change that needs a quality bar).
+- **Interaction inventory (UI slices) — enumerate every interactive element + flow.** List each
+  input field, checkbox, radio, select, toggle, button, and actionable link, plus each user
+  flow; assign each ≥1 asserting test **at the right level** — elements/fields → unit/component,
+  critical journeys → one E2E (never one-per-field). Every element/flow with no asserting test
+  is a GAP; no element ships unverified. Write the inventory to `test-plan.md` (table in
+  `artifacts.md`). This is `testing.md` "Completeness" made concrete for the plan.
+- **Regression rule (mandatory, no question):** when the plan modifies existing behavior and the
+  current suite doesn't cover the changed path, a regression test is added to the plan as a
+  **Critical** requirement — no `AskUserQuestion`, no skipping. Regressions are the highest-priority
+  test because they prove something broke. When unsure whether a change is a regression, write the test.
+- Produce the **coverage diagram** (shape below) and add a specific test requirement per GAP.
+
+#### Coverage diagram (write to `test-plan.md`)
+Both code paths and user flows in one view; mark E2E-worthy `[→E2E]` and eval-worthy `[→EVAL]`:
+
+```
+CODE PATHS                                          USER FLOWS
+[+] services/billing                                [+] Checkout
+  ├── processPayment()                                ├── [★★★ planned] complete purchase — checkout.e2e
+  │   ├── [★★★ planned] happy + declined + timeout    ├── [GAP] [→E2E] double-click submit
+  │   └── [GAP]         invalid currency              └── [GAP]        navigate away mid-payment
+  └── refundPayment()                               [+] Error states
+      └── [★  planned] full refund only               └── [GAP]        network-timeout UX
+
+COVERAGE: 4/9 planned (44%)  |  GAPS: 5 (2 E2E)  |  REGRESSIONS: 1 (Critical)
+```
+Legend: ★★★ behavior+edge+error · ★★ happy path · ★ smoke · [→E2E] integration · [→EVAL] LLM eval.
+**Fast path:** every acceptance criterion already maps to a planned test → "Test coverage: all
+acceptance criteria covered ✓" and continue.
+
+### 4. Performance
+- N+1 / unbounded queries and DB access patterns; memory concerns; caching opportunities;
+  high-complexity hot paths.
+- Per `performance.md`: name a number to measure or a budget — don't recommend speculative
+  micro-tuning. A perf finding is "measure X against budget Y", not "this feels slow".
+
+---
+
+## Confidence + verification gate (applies to every finding, all axes)
+Tag each finding `[severity] (confidence: N/10) <plan/task/spec ref> — finding`:
+- **9-10** verified against a quoted line · **7-8** strong pattern match → report normally.
+- **5-6** moderate → report with "verify this is real".
+- **≤4** speculative → **suppress from the walk-through**, appendix only.
+
+**The gate:** before raising a finding, quote the line(s) that motivate it. Can't quote it →
+force confidence ≤4 and suppress. This kills the "the plan doesn't handle X" finding when the
+plan *does* and you skimmed. Don't fabricate 7+ to dodge it. (Same discipline the reviewer agent
+runs — `devrites-plan-reviewer`.)
+
+---
+
+## How to ask (the interactive walk)
+Use `AskUserQuestion` per the pack's standard. Plan-review specifics:
+- **One finding = one call.** Never batch findings into one question.
+- Concrete: name the plan/task section + the quoted line.
+- 2-3 options, including "do nothing / proceed as-is" where reasonable.
+- Per option, one line: **effort** (human ~X / with the build agent ~Y), **risk**, **maintenance**.
+  If the complete option is only marginally more effort than the shortcut (AI makes it cheap),
+  recommend complete.
+- **Map to a rule.** One sentence tying the recommendation to a DevRites rule (reuse-first,
+  fail-fast, test-behavior, measure-first, minimum diff).
+- **Coverage vs kind:** if the options differ in *coverage* (more tests vs fewer, complete vs
+  happy-path), add `Completeness: N/10` per option. If they differ in *kind* (two different
+  architectures), skip the score and note "options differ in kind, not coverage". Never fabricate
+  a score on a kind question.
+- Every material finding ends as a **recorded decision** — a resolved `questions.md` qid (HITL) or
+  a `decisions.md` ADR (AFK) — so the walk leaves an auditable trail, not just chat.
+
+---
+
+## Required outputs (after the axes)
+1. **"NOT in scope"** — work considered and explicitly deferred, one-line rationale each. Folds
+   into `plan.md` §Scope boundaries + `spec.md` Non-goals (via the Guard) so it can't silently re-enter.
+2. **"What already exists"** — existing code/flows that solve sub-problems, and whether the plan
+   reuses or rebuilds them. Every missed reuse becomes a §0 finding.
+3. **Failure-mode table** — for each new codepath: a realistic failure, and whether (a) a test
+   covers it, (b) error handling exists, (c) the user sees a clear error or a silent failure. A
+   failure with **no test AND no handling AND silent** is a **Critical gap**. (Shape in
+   [`artifacts.md`](artifacts.md).)
+4. **Worktree parallelization strategy** — analyze the slices for parallel execution. **Skip** if
+   all slices touch the same module or there are <2 independent workstreams ("Sequential, no
+   parallelization opportunity"). Otherwise: a dependency table (module-level, not file-level),
+   parallel lanes (shared module → same lane/sequential; independent → separate lanes), execution
+   order, and conflict flags where two lanes touch the same module dir. This feeds `/rite-build`'s
+   isolation strategy and the autocomplete loop. (Shape in [`artifacts.md`](artifacts.md).)
+5. **Completion summary** — the one-glance recap (shape in [`artifacts.md`](artifacts.md)).

package/pack/.claude/skills/rite-zoom-out/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: rite-zoom-out
+description: Zoom out one abstraction layer in unfamiliar code — return a structural map (modules, callers, callees, ADR/decisions touching the area) in the project's vocabulary. Use when the user says "zoom out", "map this", "bigger picture", "I don't know this area", "what calls this". Not for implementing changes (read-only) or one-symbol lookups (use grep).
+user-invocable: true
+---
+
+# /rite-zoom-out — step up one abstraction layer
+
+When the agent (or the user) is staring at unfamiliar code without a working mental
+model of how it fits the larger system. Stops the "open more files" reflex by returning
+a single, structured map instead.
+
+Read `.claude/rules/core.md` first — chiefly its vocabulary / existing-conventions
+disciplines, which keep the map in the project's own language. The other rule files load
+on demand.
+
+## What this skill returns
+
+A **map, not an essay**. One pass should answer:
+
+- **The area** — what this code is for, in one sentence, using the project's own
+  vocabulary.
+- **Modules in scope** — the related files / packages / slices, with a one-line
+  purpose each.
+- **Callers (in)** — who calls into this area from outside. Keep to the highest-signal
+  3–6; collapse the rest.
+- **Calls (out)** — what this area depends on downstream.
+- **Decisions touching it** — ADRs (under `docs/adr/` if present) or notes in
+  `.devrites/work/<slug>/decisions.md` that pre-decide something here.
+- **Smallest sensible change-scope** — where a fix would naturally land, so the next
+  step doesn't drift into a project-wide refactor.
+
+## Prefer a code-intelligence index (if available)
+
+If the project has them — `codebase-memory-mcp` (`get_architecture` / `search_graph`) first,
+cross-checked with `codegraph` (`.codegraph/`) and `graphify` (`graphify-out/`) — use them. For
+codegraph, `codegraph_context` + one `codegraph_explore` return the map in two calls — vastly
+cheaper than a file-walk and more accurate for callers/callees. Fall back to standard methods
+(LSP, then `Grep` + `Read`) when no index is available. See `.claude/rules/tooling.md`.
+
+## Vocabulary discipline
+
+Use the **project's** domain language — `CONTEXT.md`, glossaries, the active feature's
+`spec.md` / `decisions.md`. Don't invent fresh names for things the project already
+names. If you notice a fuzzy or overloaded term while mapping, flag it as a FYI at the
+end; don't try to fix it here.
+
+## When NOT to use
+
+- You already have a clear mental model — zooming out is just tax.
+- The question is a literal text lookup (a string, a comment, an error message) — use
+  `Grep`.
+- You need to design or change something — that's `/rite-spec` (new feature) or
+  `/rite-define` (plan an approved spec).
+- You want a project-wide architecture audit — that's `improve-codebase-architecture`,
+  out of DevRites' feature-scoped remit.
+
+## Output shape
+
+```
+Area: <one line, project's vocabulary>
+Modules:
+  - path/x.ts — <purpose>
+  - path/y.ts — <purpose>
+Callers (in):
+  - <module> — <how it calls in>
+Calls (out):
+  - <module> — <what it calls for>
+Decisions touching it:
+  - ADR-NNNN / decisions.md entry — <one-line claim>
+Smallest sensible change-scope: <where a fix would land>
+FYI (optional): <fuzzy term / suspected drift / open question>
+```
+
+Print the path of any decisions/ADR files referenced so the user can open them.

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "devrites",
+  "version": "1.19.0",
+  "description": "DevRites — disciplined senior-engineer workflow skills pack for Claude Code",
+  "license": "SEE LICENSE IN LICENSE",
+  "homepage": "https://github.com/ViktorsBaikers/DevRites#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ViktorsBaikers/DevRites.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ViktorsBaikers/DevRites/issues"
+  },
+  "keywords": [
+    "claude-code",
+    "skills",
+    "agent-skills",
+    "workflow",
+    "senior-engineer",
+    "spec-driven",
+    "tdd",
+    "code-review",
+    "anti-slop",
+    "devrites"
+  ],
+  "bin": {
+    "devrites": "bin/devrites.mjs"
+  },
+  "files": [
+    "bin/",
+    "pack/",
+    "scripts/",
+    "install.sh",
+    "uninstall.sh",
+    "update.sh",
+    ".claude-plugin/",
+    "mcp/",
+    "docs/",
+    "README.md",
+    "LICENSE",
+    "SECURITY.md",
+    "NOTICE.md",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "prepare": "husky || true",
+    "prepack": "rm -rf scripts/__pycache__ scripts/.cache docs/internal",
+    "commitlint": "commitlint --edit",
+    "validate": "bash scripts/validate.sh",
+    "test": "for t in tests/*.sh; do echo \"== $t ==\"; bash \"$t\" || exit 1; done",
+    "release": "semantic-release",
+    "release:dry": "semantic-release --dry-run --no-ci"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^21.0.2",
+    "@commitlint/config-conventional": "^21.0.2",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/exec": "^7.1.0",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/npm": "^13.1.5",
+    "conventional-changelog-conventionalcommits": "^9.3.1",
+    "husky": "^9.1.7",
+    "semantic-release": "^25.0.5"
+  }
+}

package/scripts/build-release-tarball.sh

@@ -0,0 +1,74 @@
+#!/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).
+#
+# Usage: build-release-tarball.sh <version>
+set -euo pipefail
+
+VERSION="${1:-}"
+if [[ -z "$VERSION" ]]; then
+  echo "usage: build-release-tarball.sh <version>" >&2
+  exit 1
+fi
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+DIST="$ROOT/dist"
+NAME="devrites-v${VERSION}"
+STAGE="$DIST/$NAME"
+
+cd "$ROOT"
+
+echo "Building release tarball: ${NAME}.tar.gz"
+
+rm -rf "$STAGE"
+mkdir -p "$STAGE"
+
+# Files and directories shipped to end-users.
+PAYLOAD=(
+  pack
+  .claude-plugin
+  scripts
+  mcp
+  docs
+  install.sh
+  uninstall.sh
+  update.sh
+  README.md
+  CHANGELOG.md
+  LICENSE
+  SECURITY.md
+  NOTICE.md
+  CODE_OF_CONDUCT.md
+  CODEOWNERS
+  package.json
+)
+
+for item in "${PAYLOAD[@]}"; do
+  if [[ -e "$item" ]]; then
+    cp -R "$item" "$STAGE/"
+  fi
+done
+
+# Drop dev-only artifacts that may have been copied transitively.
+rm -rf "$STAGE/docs/internal" "$STAGE/scripts/.cache" 2>/dev/null || true
+
+tar -C "$DIST" -czf "$DIST/${NAME}.tar.gz" "$NAME"
+rm -rf "$STAGE"
+
+# 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.
+(
+  cd "$DIST"
+  if command -v shasum >/dev/null 2>&1; then
+    shasum -a 256 "${NAME}.tar.gz" > "${NAME}.tar.gz.sha256"
+  elif command -v sha256sum >/dev/null 2>&1; then
+    sha256sum "${NAME}.tar.gz" > "${NAME}.tar.gz.sha256"
+  else
+    echo "warning: no sha256 tool found; skipping ${NAME}.tar.gz.sha256" >&2
+  fi
+)
+
+echo "  → $DIST/${NAME}.tar.gz"
+ls -lh "$DIST/${NAME}.tar.gz"
+[[ -f "$DIST/${NAME}.tar.gz.sha256" ]] && { echo "  → $DIST/${NAME}.tar.gz.sha256"; cat "$DIST/${NAME}.tar.gz.sha256"; } || true

package/scripts/check-cross-refs.py

@@ -0,0 +1,121 @@
+#!/usr/bin/env python3
+"""Cross-reference linter for the DevRites pack.
+
+Catches the maintenance-drift class the skills audit surfaced: a SKILL.md or
+reference file pointing at another file that has moved, been renamed, or never
+existed. Three checks, tuned for near-zero false positives:
+
+  1. Markdown links to local .md targets  — `](path.md)` resolved relative to the
+     containing file; the target must exist.
+  2. Bare backtick .md filenames          — `` `name.md` `` must exist SOMEWHERE in
+     the pack (by basename). Catches references to a file that exists nowhere.
+  3. "canonical version: `path`" claims    — the named path (relative to the skills
+     root) must exist. Catches a file disclaiming itself secondary to a missing one.
+
+Scans pack/.claude/. Exit 1 on any dead reference. Read-only.
+"""
+import os
+import re
+import sys
+
+ROOT = os.path.join("pack", ".claude")
+SKILLS_ROOT = os.path.join(ROOT, "skills")
+
+# Runtime artifacts live under .devrites/ (per-feature work/<slug>/ files, plus the
+# project-level conventions ledger), not in the pack. References to them by filename are
+# legitimate, not dead refs.
+WORKSPACE_ARTIFACTS = {
+    "spec.md", "plan.md", "tasks.md", "state.md", "decisions.md", "assumptions.md",
+    "questions.md", "drift.md", "evidence.md", "browser-evidence.md", "touched-files.md",
+    "review.md", "seal.md", "ship.md", "brief.md", "design-brief.md", "strategy.md",
+    "polish-report.md", "handoff.md", "eng-review.md", "test-plan.md", "references.md",
+    "conventions.md", "coverage.md", "analysis.md", "learnings.md",
+    # spec-quality checklists (.devrites/work/<slug>/checklists/<domain>.md)
+    "functional.md", "data-model.md", "interaction.md", "non-functional.md", "edge-cases.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",
+    "ADR-NNN.md",  # generated per-decision ADR in the user repo (docs/adr/), promoted at /rite-ship
+}
+
+
+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(here, link))
+
+md_files = []
+all_basenames = set()
+for base, _dirs, files in os.walk(ROOT):
+    for f in files:
+        if f.endswith(".md"):
+            p = os.path.join(base, f)
+            md_files.append(p)
+            all_basenames.add(f)
+
+LINK_RE = re.compile(r"\]\(([^)]+)\)")
+BACKTICK_MD_RE = re.compile(r"`([A-Za-z0-9._/\-]+\.md)`")
+SEE_RE = re.compile(r"\(see\s+`?([A-Za-z0-9._/\-]+\.md)`?[^)]*\)")
+CANONICAL_RE = re.compile(r"[Cc]anonical version:\s*`?\s*`?([A-Za-z0-9._/\-]+\.md)`")
+
+errors = []
+
+for path in md_files:
+    with open(path, encoding="utf-8") as fh:
+        text = fh.read()
+    here = os.path.dirname(path)
+
+    # 1. markdown links to .md
+    for link in LINK_RE.findall(text):
+        link = link.strip()
+        if link.startswith(("http://", "https://", "mailto:", "#")):
+            continue
+        target = link.split("#", 1)[0]
+        if not target.endswith(".md"):
+            continue
+        resolved = resolve(here, target)
+        if not os.path.isfile(resolved):
+            errors.append(f"{path}: markdown link -> {link} (resolved {resolved}) does not exist")
+
+    # 2. bare backtick filenames must exist somewhere in the pack (by basename),
+    #    excluding runtime workspace artifacts and user-project docs.
+    for tok in BACKTICK_MD_RE.findall(text):
+        base = os.path.basename(tok)
+        if base in WORKSPACE_ARTIFACTS or base in PROJECT_DOCS or base in all_basenames:
+            continue
+        if "/" in tok:  # a path inside the pack must actually resolve
+            if not os.path.isfile(resolve(here, tok)):
+                errors.append(f"{path}: backtick `{tok}` does not resolve")
+            continue
+        errors.append(f"{path}: backtick `{tok}` — no `{base}` exists anywhere in the pack")
+
+    # 4. "(see X.md)" prose pointers: slash form resolves (install-aware);
+    #    bare form must exist in the pack (or be a workspace artifact / project doc).
+    for tok in SEE_RE.findall(text):
+        base = os.path.basename(tok)
+        if "/" in tok:
+            resolved = resolve(here, tok)
+            if not os.path.isfile(resolved):
+                errors.append(f"{path}: (see {tok}) (resolved {resolved}) does not exist")
+        elif base not in WORKSPACE_ARTIFACTS and base not in PROJECT_DOCS and base not in all_basenames:
+            errors.append(f"{path}: (see {tok}) — no `{base}` exists anywhere in the pack")
+
+    # 3. "canonical version: `path`" must resolve against the skills root
+    for claim in CANONICAL_RE.findall(text):
+        resolved = os.path.normpath(os.path.join(SKILLS_ROOT, claim))
+        if not os.path.isfile(resolved):
+            errors.append(f"{path}: 'canonical version' -> {claim} (resolved {resolved}) does not exist")
+
+if errors:
+    print(f"check-cross-refs: {len(errors)} dead reference(s):\n")
+    for e in sorted(errors):
+        print("  " + e)
+    sys.exit(1)
+
+print(f"check-cross-refs: OK — {len(md_files)} markdown files, no dead references.")

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

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+# check-no-global-writes.sh — static guard that the installer/uninstaller never
+# writes to the user's global ~/.claude, and that the global guard is present.
+# Exits non-zero on violation.
+
+set -u
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+fail=0
+
+SCRIPTS="$ROOT/install.sh $ROOT/uninstall.sh"
+for f in "$ROOT"/scripts/*.sh; do SCRIPTS="$SCRIPTS $f"; done
+
+# 1) the no-global guard marker must exist in install.sh
+if ! grep -q 'GUARD:no-global' "$ROOT/install.sh"; then
+  echo "FAIL: install.sh is missing the GUARD:no-global guard"
+  fail=1
+else
+  echo "ok: install.sh contains the no-global guard"
+fi
+
+# 2) no write operation may target ~/.claude or \$HOME/.claude.
+#    Write verbs are actual file-writing commands / redirections. ('install' is
+#    intentionally excluded: the installer uses cp/mkdir, and "install" appears in
+#    prose like "install into a project", which is not a write.)
+WRITE_RE='(\bmkdir\b|\bcp\b|\btee\b|\brsync\b|\bmv\b|\bln\b|>>?)'
+GLOBAL_RE='(\$HOME/\.claude|~/\.claude)'
+for f in $SCRIPTS; do
+  [ -f "$f" ] || continue
+  # lines that contain a global-claude path AND a write verb, excluding comments
+  hits="$(grep -nE "$GLOBAL_RE" "$f" | grep -vE '^\s*[0-9]+:\s*#' | grep -E "$WRITE_RE" || true)"
+  if [ -n "$hits" ]; then
+    echo "FAIL: possible global write in ${f#$ROOT/}:"
+    printf '%s\n' "$hits" | sed 's/^/    /'
+    fail=1
+  fi
+done
+[ "$fail" -eq 0 ] && echo "ok: no write operations target ~/.claude"
+
+if [ "$fail" -eq 0 ]; then
+  echo "PASS: no global-write risks detected"
+else
+  echo "FAILED: global-write check"
+fi
+exit "$fail"

package/scripts/check-rule-uniqueness.sh

@@ -0,0 +1,73 @@
+#!/usr/bin/env bash
+# scripts/check-rule-uniqueness.sh — assert each canonical principle heading
+# appears in exactly one canonical file under pack/.claude/.
+#
+# Drift catcher: if someone re-duplicates a principle's full treatment, this
+# script fails and names the offenders. Cross-link summaries are fine — they
+# don't use the canonical heading.
+#
+# Usage:
+#   scripts/check-rule-uniqueness.sh
+# Exits non-zero if any principle is duplicated or missing from its canonical
+# home. Add new entries to PRINCIPLES below as principles get a canonical
+# home.
+
+set -u
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+PACK="$ROOT/pack/.claude"
+
+# Format: <grep-pattern>|<canonical-relative-path>
+PRINCIPLES=(
+  '^## Reuse before you write|pack/.claude/rules/coding-style.md'
+  '^## Trust boundary (three tiers)|pack/.claude/rules/security.md'
+)
+
+fail=0
+
+for entry in "${PRINCIPLES[@]}"; do
+  pattern="${entry%%|*}"
+  canonical="${entry##*|}"
+  # Use literal-string grep (-F) to avoid regex meta-char surprises in headings.
+  # Match anchored to line start by adding the '## ' prefix ourselves.
+  needle="${pattern#^}"
+  matches="$(grep -rln -F -- "$needle" "$PACK"/rules "$PACK"/skills "$PACK"/agents 2>/dev/null | sort -u)"
+  count="$(printf '%s\n' "$matches" | grep -c .)"
+  if [ "$count" -eq 1 ] && [ "$matches" = "$ROOT/$canonical" ]; then
+    printf 'ok: unique heading "%s" (canonical: %s)\n' "$needle" "$canonical"
+  else
+    printf 'FAIL: heading "%s" should appear only in %s; found in:\n' "$needle" "$canonical" >&2
+    printf '%s\n' "$matches" | sed 's|^|    |' >&2
+    fail=1
+  fi
+done
+
+# Anti-rationalization table: core.md keeps a minimal 5-row subset that MUST be
+# byte-identical to the matching rows in anti-patterns.md (the single source of
+# the full table). The unique-heading check above can't see this — the rows live
+# under the same heading in both files — so assert the 5 shared excuse strings
+# (the excuse-column text, stable across both files) appear verbatim in both.
+# These cover the five rows core.md duplicates:
+#   tests-later / small-refactor / special-case / user-will-tell / lint-and-build.
+CORE="$PACK/rules/core.md"
+ANTI="$PACK/rules/anti-patterns.md"
+SHARED_EXCUSES=(
+  '"I'\''ll add the tests later."'
+  '"It'\''s only a small refactor while I'\''m in here."'
+  '"This is a special case, the pattern doesn'\''t apply."'
+  '"The user will tell me if something is wrong."'
+  '"Lint and build pass — that proves quality."'
+)
+for excuse in "${SHARED_EXCUSES[@]}"; do
+  in_core=0; in_anti=0
+  grep -qF -- "$excuse" "$CORE" 2>/dev/null && in_core=1
+  grep -qF -- "$excuse" "$ANTI" 2>/dev/null && in_anti=1
+  if [ "$in_core" -eq 1 ] && [ "$in_anti" -eq 1 ]; then
+    printf 'ok: shared excuse present in core.md + anti-patterns.md: %s\n' "$excuse"
+  else
+    printf 'FAIL: shared excuse must appear verbatim in BOTH core.md and anti-patterns.md: %s (core=%d anti=%d)\n' \
+      "$excuse" "$in_core" "$in_anti" >&2
+    fail=1
+  fi
+done
+
+exit "$fail"