devrites 1.19.0

package/scripts/devrites-detect.sh

@@ -0,0 +1,175 @@
+#!/usr/bin/env bash
+# scripts/devrites-detect.sh — deterministic anti-slop detector.
+#
+# Greps the current git diff (or a passed file list) for ~25 actionable
+# anti-slop patterns from rite-polish/reference/anti-ai-slop.md +
+# devrites-frontend-craft/reference/quality-standards.md. No LLM needed.
+#
+# Exits 0 if no findings, 1 if any (so a pre-push hook can block).
+# Use --advisory to always exit 0 (CI does this).
+#
+# Usage:
+#   scripts/devrites-detect.sh                # diff vs upstream / HEAD~
+#   scripts/devrites-detect.sh file1 file2    # check specific files
+#   scripts/devrites-detect.sh --advisory     # report-only, never fail
+
+set -euo pipefail
+
+ADVISORY=0
+FILES=()
+
+for arg in "$@"; do
+  case "$arg" in
+    --advisory) ADVISORY=1 ;;
+    *)          FILES+=("$arg") ;;
+  esac
+done
+
+# Resolve which files to scan: explicit args, else diff against the base.
+if [[ ${#FILES[@]} -eq 0 ]]; then
+  BASE=""
+  for candidate in origin/main origin/master main master HEAD~1; do
+    if git rev-parse --verify "$candidate" >/dev/null 2>&1; then
+      BASE="$candidate"
+      break
+    fi
+  done
+  if [[ -n "$BASE" ]]; then
+    mapfile -t FILES < <(git diff --name-only --diff-filter=ACMR "$BASE" 2>/dev/null || true)
+  fi
+fi
+
+# Filter into two scan lists: code/UI source (most rules) and markdown
+# (em-dash overuse only). Meta / reference docs are excluded from the markdown
+# scan because they discuss the patterns under audit.
+SCAN=()
+SCAN_MD=()
+for f in "${FILES[@]}"; do
+  [[ -z "$f" ]] && continue
+  [[ ! -f "$f" ]] && continue
+  case "$f" in
+    *.lock|*.png|*.jpg|*.jpeg|*.gif|*.svg|*.ico|*.woff*|*.ttf|*.zip|*.gz) continue ;;
+    *vendor/*|*node_modules/*|*dist/*|*build/*|*.min.*)                   continue ;;
+  esac
+  case "$f" in
+    *.md)
+      case "$f" in
+        REVIEW.md|CHANGELOG.md|res.md)                                 continue ;;
+        .review-notes/*|*/.review-notes/*)                             continue ;;
+        pack/.claude/rules/*|*/pack/.claude/rules/*)                   continue ;;
+        pack/.claude/skills/*|*/pack/.claude/skills/*)                 continue ;;
+      esac
+      SCAN_MD+=("$f")
+      ;;
+    *)
+      SCAN+=("$f")
+      ;;
+  esac
+done
+
+if [[ ${#SCAN[@]} -eq 0 && ${#SCAN_MD[@]} -eq 0 ]]; then
+  echo "devrites-detect: no files to scan."
+  exit 0
+fi
+
+# Each rule: pattern (ERE), severity, message.
+# Severity = critical (auth/safety), high (slop tell), low (style nit).
+RULES=(
+  # --- UI anti-slop (CSS-ish) ---
+  '#000([^0-9a-f]|$)|#fff([^0-9a-f]|$)|#000000|#ffffff'                            'high'  'Pure #000 / #fff — use near-black / near-white tokens.'
+  '#6366f1|#8b5cf6|#a855f7|#d946ef|#ec4899'                                        'high'  'Purple/blue gradient hex range — likely default AI palette.'
+  'background-clip:[[:space:]]*text|-webkit-background-clip:[[:space:]]*text'      'high'  'Gradient text decoration — likely AI slop.'
+  'backdrop-filter:[[:space:]]*blur'                                               'high'  'Glassmorphism `backdrop-filter: blur(...)` — banned default surface.'
+  'border-left:[[:space:]]*[1-6]px[[:space:]]+solid|border-l-[2-8]'                'low'   'Side-stripe accent border — common templating tell; confirm vs design system.'
+  'cubic-bezier\([^)]*0\.34[[:space:]]*,[[:space:]]*1\.56'                         'high'  'Bounce/elastic easing curve — banned unless design system uses it.'
+  'animation-duration:[[:space:]]*[5-9][0-9]{2}ms[[:space:]]*;[[:space:]]*animation-delay'  'low'   'Long animation durations stacked — verify motion budget.'
+  'z-index:[[:space:]]*[0-9]{4,}'                                                  'high'  'Raw z-index in the 1000s — use semantic z scale.'
+  'font-family:[[:space:]]*"?(DM Sans|Plus Jakarta|Fraunces|Newsreader)'           'high'  'Reflex font choice — use the project type system.'
+  'text-transform:[[:space:]]*uppercase[[:space:]]*;[^}]*letter-spacing'           'low'   'All-CAPS with letter-spacing — verify register; banned for body text.'
+  # --- Code anti-slop ---
+  '\bconsole\.log\('                                                               'high'  'console.log left in code — remove before polish.'
+  'if[[:space:]]*\([[:space:]]*[a-zA-Z_][a-zA-Z0-9_]*[[:space:]]*&&[[:space:]]*[a-zA-Z_][a-zA-Z0-9_]*\.length[[:space:]]*>[[:space:]]*0' 'high' 'Over-defensive `x && x.length > 0` — validate at boundaries.'
+  '\bcatch[[:space:]]*\([[:space:]]*\)[[:space:]]*\{[^}]*\}'                       'high'  'Blanket catch with no narrow handling — likely swallowing errors.'
+  '\bcatch[[:space:]]*\([[:space:]]*[A-Za-z][A-Za-z0-9_]*[[:space:]]*\)[[:space:]]*\{[[:space:]]*\}'  'high'  'Empty catch body — silently swallows errors. Catch narrow; recover or rethrow.'
+  '//[[:space:]]*helper function|//[[:space:]]*increment'                          'low'   'Tutorial-style comment — restates code; remove.'
+  '\bfunction[[:space:]]+(process|handle|do)(Data|Item|Thing|It)?\b'               'high'  'Generic AI naming (`processData` / `handleItem` / `doIt`) — name for intent.'
+  '\bfunction[[:space:]]+get[A-Z][a-zA-Z]*\([^)]*\)[[:space:]]*\{[[:space:]]*return[[:space:]]+[A-Z][a-zA-Z]+\.find'  'low'   'Useless wrapper around a single ORM call — inline.'
+  '//[[:space:]]*TODO:[[:space:]]*(improve|cleanup|refactor)[[:space:]]+(this|later)'  'low'   '"TODO: improve this later" — without owner/issue, this rots.'
+  '\btemp\s*=|\bresult\s*=|\bdata\s*=[^=]'                                         'low'   'Generic local name (temp/result/data) — name for intent.'
+  '\binterface[[:space:]]+I[A-Z][a-zA-Z]+\b'                                       'low'   '`IFoo` prefix on interfaces — most modern style guides prefer `Foo`.'
+  '/\*\s*eslint-disable\s*\*/'                                                     'high'  'Global eslint-disable — explain or remove.'
+  # --- Security ---
+  '\bnew Function\('                                                               'critical' '`new Function(...)` — dynamic code construction.'
+  '\beval\s*\('                                                                    'critical' '`eval(...)` — avoid.'
+  '\bdangerouslySetInnerHTML\b'                                                    'high'  'dangerouslySetInnerHTML — confirm XSS-safe.'
+  'process\.env\.[A-Z_]+(.{0,40}(?:console|res\.send|res\.json))'                  'high'  'env var possibly echoed to response/log — re-check for secret leakage.'
+  # --- Performance pitfalls ---
+  '\.forEach\([^)]+\)\s*\.\s*forEach\('                                            'low'   'Nested `forEach` — accidental quadratic loop?'
+)
+
+# Markdown-only rules. Run against SCAN_MD, not SCAN.
+# Em-dash overuse: 2+ em-dashes (U+2014) on the same line — the per-line proxy
+# for the "multiple em-dashes per paragraph" rule in anti-ai-slop.md.
+MD_RULES=(
+  $'.*\xe2\x80\x94.*\xe2\x80\x94'  'high'  'Em-dash overuse on one line (2+ em-dashes) — a common AI tell; prefer comma, period, or parenthetical.'
+)
+
+FOUND=0
+
+# Code rules against code files.
+if [[ ${#SCAN[@]} -gt 0 ]]; then
+  N=${#RULES[@]}
+  i=0
+  while (( i < N )); do
+    pat="${RULES[$i]}"
+    sev="${RULES[$((i+1))]}"
+    msg="${RULES[$((i+2))]}"
+    i=$((i+3))
+
+    HITS="$(grep -HnIE --color=never "$pat" "${SCAN[@]}" 2>/dev/null || true)"
+    [[ -z "$HITS" ]] && continue
+
+    while IFS= read -r line; do
+      [[ -z "$line" ]] && continue
+      FOUND=$((FOUND + 1))
+      printf '[%s] %s — %s\n' "$sev" "$line" "$msg"
+    done <<<"$HITS"
+  done
+fi
+
+# Markdown rules against markdown files.
+if [[ ${#SCAN_MD[@]} -gt 0 ]]; then
+  N=${#MD_RULES[@]}
+  i=0
+  while (( i < N )); do
+    pat="${MD_RULES[$i]}"
+    sev="${MD_RULES[$((i+1))]}"
+    msg="${MD_RULES[$((i+2))]}"
+    i=$((i+3))
+
+    HITS="$(grep -HnIE --color=never "$pat" "${SCAN_MD[@]}" 2>/dev/null || true)"
+    [[ -z "$HITS" ]] && continue
+
+    while IFS= read -r line; do
+      [[ -z "$line" ]] && continue
+      FOUND=$((FOUND + 1))
+      printf '[%s] %s — %s\n' "$sev" "$line" "$msg"
+    done <<<"$HITS"
+  done
+fi
+
+TOTAL=$(( ${#SCAN[@]} + ${#SCAN_MD[@]} ))
+
+echo
+if [[ $FOUND -eq 0 ]]; then
+  echo "devrites-detect: clean — scanned $TOTAL files (${#SCAN[@]} code, ${#SCAN_MD[@]} md)."
+  exit 0
+fi
+
+echo "devrites-detect: $FOUND finding(s) across $TOTAL files (${#SCAN[@]} code, ${#SCAN_MD[@]} md)."
+
+if [[ $ADVISORY -eq 1 ]]; then
+  exit 0
+fi
+
+exit 1

package/scripts/eval-runner.py

@@ -0,0 +1,273 @@
+#!/usr/bin/env python3
+"""DevRites trigger-eval runner.
+
+Wraps the Anthropic SDK to actually execute a trigger eval against a Claude
+model. Off by default in CI (schema-only validation lives in
+`scripts/run-evals.sh`); this runner is invoked explicitly when
+`CLAUDE_API_KEY` is set.
+
+Inputs
+------
+A trigger-eval JSON of the shape DevRites ships under `evals/`:
+
+    {
+      "skill": "rite-spec",
+      "description": "...",
+      "queries": [
+        {"text": "...", "expected": "should_trigger"|"should_not_trigger", "rationale": "..."}
+      ]
+    }
+
+Plus the pack at `pack/.claude/skills/` (so the runner can read the candidate
+skills' descriptions and present them to the model).
+
+What it does per query
+----------------------
+1. Loads each skill's `name` + `description` from `pack/.claude/skills/*/SKILL.md`.
+2. Sends the query as a `user` message to Claude with a system prompt
+   instructing it to pick exactly one skill name from the candidate list, or
+   "none" if no skill applies. We do NOT ask the model to invoke a tool — we
+   ask it to predict which skill the harness would have triggered. That keeps
+   the eval cheap (no agentic loop, one round-trip per query) and faithful to
+   what skill discovery actually decides.
+3. Compares the predicted skill name to the expected verdict:
+   - `should_trigger`  → predicted name must equal the eval's `skill` field.
+   - `should_not_trigger` → predicted name must NOT equal the eval's `skill`.
+
+Outputs
+-------
+A per-query line and a final accuracy summary. Exit code 1 if accuracy is
+below `--min-accuracy` (default 0.85).
+
+Usage
+-----
+    CLAUDE_API_KEY=sk-... ./scripts/eval-runner.py evals/rite-spec.json
+    CLAUDE_API_KEY=sk-... ./scripts/eval-runner.py --min-accuracy 0.9 evals/*.json
+
+The runner is intentionally thin (~200 lines). It is not the eval-viewer in
+Anthropic's `skill-creator` — it just provides the missing "did the model
+pick the right skill" signal so we can answer that question without firing
+up the full Claude Code harness.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+SKILLS_DIR = ROOT / "pack" / ".claude" / "skills"
+
+SYSTEM_TEMPLATE = """\
+You are the DevRites skill router. Your job is to predict which DevRites
+skill (if any) should fire for a given user message.
+
+Each candidate skill is described below. Read the descriptions carefully —
+DevRites' triggers are encoded in them.
+
+For the user message at the end, respond with exactly one line of the form:
+
+    name: <skill-name>
+
+…where <skill-name> is the name of the skill that should fire, or the
+literal token `none` if no DevRites skill applies. Do not explain. Do not
+suggest. Do not output anything except that one line.
+
+# Candidate skills
+
+{skills}
+"""
+
+
+@dataclass
+class Skill:
+    name: str
+    description: str
+
+
+@dataclass
+class Query:
+    text: str
+    expected: str
+    rationale: str
+
+
+@dataclass
+class Outcome:
+    query: Query
+    predicted: str
+    correct: bool
+    false_positive: bool  # expected should_not_trigger but skill fired
+    false_negative: bool  # expected should_trigger but skill didn't fire
+
+
+def load_skills() -> list[Skill]:
+    skills: list[Skill] = []
+    for skill_dir in sorted(SKILLS_DIR.iterdir()):
+        skill_md = skill_dir / "SKILL.md"
+        if not skill_md.is_file():
+            continue
+        body = skill_md.read_text(encoding="utf-8")
+        # Lightweight YAML frontmatter parse — we only need name + description.
+        m = re.match(r"^---\n(.*?)\n---", body, re.DOTALL)
+        if not m:
+            continue
+        front = m.group(1)
+        name_m = re.search(r"^name:\s*(\S+)", front, re.MULTILINE)
+        desc_m = re.search(r"^description:\s*(.+)$", front, re.MULTILINE)
+        if not name_m or not desc_m:
+            continue
+        skills.append(Skill(name=name_m.group(1), description=desc_m.group(1).strip()))
+    return skills
+
+
+def render_system(skills: list[Skill]) -> str:
+    lines = []
+    for s in skills:
+        lines.append(f"- **{s.name}** — {s.description}")
+    return SYSTEM_TEMPLATE.format(skills="\n".join(lines))
+
+
+def load_eval(path: Path) -> tuple[str, list[Query]]:
+    data = json.loads(path.read_text(encoding="utf-8"))
+    queries = [
+        Query(text=q["text"], expected=q["expected"], rationale=q.get("rationale", ""))
+        for q in data["queries"]
+    ]
+    return data["skill"], queries
+
+
+def predict(client, model: str, system: str, query_text: str) -> str:
+    response = client.messages.create(
+        model=model,
+        max_tokens=64,
+        system=system,
+        messages=[{"role": "user", "content": query_text}],
+    )
+    text = "".join(block.text for block in response.content if getattr(block, "text", None))
+    m = re.search(r"^\s*name:\s*([A-Za-z0-9_\-]+)", text, re.MULTILINE)
+    if not m:
+        return "none"
+    name = m.group(1).strip().lower()
+    return name
+
+
+def score(target_skill: str, predicted: str, expected: str) -> bool:
+    predicted = predicted.lower()
+    target = target_skill.lower()
+    if expected == "should_trigger":
+        return predicted == target
+    if expected == "should_not_trigger":
+        return predicted != target
+    raise ValueError(f"unknown expected verdict: {expected!r}")
+
+
+def run_one(client, model: str, system: str, eval_path: Path) -> tuple[int, int, list[Outcome]]:
+    target_skill, queries = load_eval(eval_path)
+    outcomes: list[Outcome] = []
+    correct = 0
+    for q in queries:
+        predicted = predict(client, model, system, q.text)
+        ok = score(target_skill, predicted, q.expected)
+        fp = (q.expected == "should_not_trigger" and not ok)
+        fn = (q.expected == "should_trigger" and not ok)
+        outcomes.append(Outcome(query=q, predicted=predicted, correct=ok, false_positive=fp, false_negative=fn))
+        if ok:
+            correct += 1
+    return correct, len(queries), outcomes
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    parser.add_argument("eval_files", nargs="+", type=Path, help="Eval JSON files to execute")
+    parser.add_argument("--model", default=os.environ.get("DEVRITES_EVAL_MODEL", "claude-haiku-4-5-20251001"))
+    parser.add_argument("--min-accuracy", type=float, default=0.90,
+                        help="Per-eval minimum correct/total (default: 0.90 ≈ 18/20)")
+    parser.add_argument("--max-false-positives", type=int, default=2,
+                        help="Per-eval max should_not_trigger queries that fired (default: 2)")
+    parser.add_argument("--verbose", action="store_true", help="Print every per-query line")
+    parser.add_argument("--summary-file", type=Path, default=None,
+                        help="Write a machine-readable summary (one JSON line per eval) to this file")
+    args = parser.parse_args()
+
+    if not os.environ.get("CLAUDE_API_KEY"):
+        sys.stderr.write("error: CLAUDE_API_KEY is not set; cannot run live eval.\n")
+        return 2
+
+    try:
+        import anthropic
+    except ImportError:
+        sys.stderr.write(
+            "error: anthropic SDK not installed. Run `pip install anthropic` first.\n"
+        )
+        return 2
+
+    client = anthropic.Anthropic(api_key=os.environ["CLAUDE_API_KEY"])
+    skills = load_skills()
+    system = render_system(skills)
+
+    total_correct = 0
+    total_queries = 0
+    total_fp = 0
+    total_fn = 0
+    per_file_failed = 0
+    summary_lines: list[str] = []
+
+    for eval_path in args.eval_files:
+        if not eval_path.is_file():
+            sys.stderr.write(f"skip: {eval_path} not a file\n")
+            continue
+        print(f"== {eval_path} ==")
+        correct, n, outcomes = run_one(client, args.model, system, eval_path)
+        fp = sum(1 for o in outcomes if o.false_positive)
+        fn = sum(1 for o in outcomes if o.false_negative)
+        total_correct += correct
+        total_queries += n
+        total_fp += fp
+        total_fn += fn
+        accuracy = correct / n if n else 0.0
+        if args.verbose:
+            for o in outcomes:
+                marker = "✓" if o.correct else "✗"
+                tag = "FP" if o.false_positive else ("FN" if o.false_negative else "  ")
+                print(f"  {marker} {tag} [{o.query.expected:20s}] predicted={o.predicted:24s} : {o.query.text[:60]}")
+        print(f"  accuracy: {correct}/{n} = {accuracy:.0%}  (FP={fp}, FN={fn})")
+        failed_reasons = []
+        if accuracy < args.min_accuracy:
+            failed_reasons.append(f"accuracy {accuracy:.0%} < {args.min_accuracy:.0%}")
+        if fp > args.max_false_positives:
+            failed_reasons.append(f"false-positives {fp} > {args.max_false_positives}")
+        if failed_reasons:
+            per_file_failed += 1
+            print(f"  FAIL: {'; '.join(failed_reasons)}")
+        if args.summary_file:
+            summary_lines.append(json.dumps({
+                "file": str(eval_path),
+                "skill": load_eval(eval_path)[0],
+                "correct": correct,
+                "total": n,
+                "accuracy": round(accuracy, 4),
+                "false_positives": fp,
+                "false_negatives": fn,
+                "passed": not failed_reasons,
+            }))
+
+    overall = total_correct / total_queries if total_queries else 0.0
+    print()
+    print(f"Overall: {total_correct}/{total_queries} = {overall:.0%}  (FP={total_fp}, FN={total_fn}, model={args.model})")
+    if args.summary_file:
+        args.summary_file.write_text("\n".join(summary_lines) + "\n", encoding="utf-8")
+        print(f"Summary written to {args.summary_file}")
+    if per_file_failed:
+        print(f"{per_file_failed} eval file(s) below threshold")
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/grade-feature.sh

@@ -0,0 +1,104 @@
+#!/usr/bin/env bash
+# Deterministic OUTCOME grader for a finished DevRites feature workspace.
+#
+# The trigger evals (evals/*.json) test whether the right SKILL *fires*. This
+# grades whether a finished run actually reached a *shippable* state — the
+# product claim DevRites sells ("won't claim done without proof"). It reads only
+# committed Markdown artifacts (no API key, no Claude Code harness), so it runs
+# in CI against a golden fixture and is the kind of deterministic grader
+# Anthropic's eval guidance recommends for coding agents.
+#
+# Live evidence-freshness (mtime: does proof post-date code?) is NOT graded here
+# — git fixtures don't preserve mtimes; that gate is enforced on a live
+# workspace by pack/.claude/skills/devrites-lib/scripts/evidence-fresh.sh.
+#
+# Usage: grade-feature.sh <workspace-dir>
+#   e.g. evals/golden/shippable-feature | .devrites/work/<slug> | .devrites/archive/<slug>
+#
+# Invariants (from rite-seal/reference/{seal-template,go-no-go,final-evidence}.md):
+#   1. seal.md present with "Verdict: GO" (not NO-GO)
+#   2. seal.md "## Acceptance Criteria" has no unchecked "- [ ]" item
+#   3. seal.md "## Blockers" is empty / "none"
+#   4. evidence.md present and non-empty
+#   5. review.md present
+#   6. questions.md has no entry with gate: validating + status: open (NO-GO by definition)
+#   7. state.md Phase in {seal, ship, done}; Status not awaiting_human / blocked
+#
+# Exit codes: 0 shippable; 1 one or more invariants failed; 2 bad usage.
+
+set -euo pipefail
+
+ws="${1:-}"
+if [ -z "$ws" ] || [ ! -d "$ws" ]; then
+  printf 'usage: grade-feature.sh <workspace-dir>\n' >&2
+  exit 2
+fi
+
+seal="$ws/seal.md"; ev="$ws/evidence.md"; rev="$ws/review.md"
+q="$ws/questions.md"; st="$ws/state.md"
+problems=()
+
+# 1 / 2 / 3 — seal verdict, acceptance, blockers
+if [ ! -f "$seal" ]; then
+  problems+=("seal.md missing — feature never sealed")
+else
+  grep -qiE '^[[:space:]]*Verdict:[[:space:]]*GO[[:space:]]*$' "$seal" \
+    || problems+=("seal.md Verdict is not GO")
+  unchecked=$(awk '/^## /{insec=($0 ~ /^## Acceptance Criteria/)} insec && /^- \[ \]/{c++} END{print c+0}' "$seal")
+  [ "${unchecked:-0}" -gt 0 ] && problems+=("seal.md has ${unchecked} unchecked acceptance criterion(s)")
+  if awk '
+      /^## /{ insec=($0 ~ /^## Blockers/); next }
+      insec { l=$0; gsub(/^[[:space:]]+|[[:space:]]+$/,"",l)
+              if (l=="") next
+              ll=tolower(l); if (ll ~ /^-?[[:space:]]*(none|n\/a)$/) next
+              nz=1 }
+      END { exit(nz?0:1) }' "$seal"; then
+    problems+=("seal.md lists unresolved blockers")
+  fi
+fi
+
+# 4 — evidence
+{ [ -f "$ev" ] && [ -s "$ev" ]; } || problems+=("evidence.md missing or empty — acceptance unproven")
+
+# 5 — review
+[ -f "$rev" ] || problems+=("review.md missing — feature not reviewed")
+
+# 6 — open validating gate (merge-blocking by definition)
+if [ -f "$q" ]; then
+  if awk '
+      /^## q-/{ if(inq && s=="open" && g=="validating") bad=1; inq=1; s=""; g=""; next }
+      inq && /^status:/{ v=$0; sub(/^status:[[:space:]]*/,"",v); s=v }
+      inq && /^gate:/  { v=$0; sub(/^gate:[[:space:]]*/,"",v);   g=v }
+      END{ if(inq && s=="open" && g=="validating") bad=1; exit(bad?0:1) }' "$q"; then
+    problems+=("open 'gate: validating' question — merge-blocking by definition (NO-GO)")
+  fi
+fi
+
+# 7 — state phase / status
+if [ -f "$st" ]; then
+  sfield() { awk -v k="$1" 'match($0,"^[[:space:]]*-?[[:space:]]*" k ":[[:space:]]*"){r=substr($0,RLENGTH+1); sub(/[[:space:]]*(#|\|).*$/,"",r); sub(/[[:space:]]+$/,"",r); print r; exit}' "$st"; }
+  ph="$(sfield Phase)"; stt="$(sfield Status)"
+  case "$ph" in seal|ship|done) ;; *) problems+=("state.md Phase='${ph}' (expected seal/ship/done)") ;; esac
+  case "$stt" in awaiting_human|blocked) problems+=("state.md Status='${stt}' (not shippable)") ;; esac
+else
+  problems+=("state.md missing")
+fi
+
+# 8 — executable acceptance criteria: every spec [ACn] proven + checked in seal
+SELF="$(cd "$(dirname "$0")" && pwd)"
+AC="$SELF/../pack/.claude/skills/devrites-lib/scripts/check-acceptance.sh"
+[ -f "$AC" ] || AC=".claude/skills/devrites-lib/scripts/check-acceptance.sh"
+if [ -f "$AC" ]; then
+  if ! acout=$(bash "$AC" "$ws" 2>&1); then
+    problems+=("acceptance: $(printf '%s' "$acout" | tail -1 | sed 's/^check-acceptance: //')")
+  fi
+fi
+
+slug="$(basename "$ws")"
+if [ "${#problems[@]}" -eq 0 ]; then
+  printf 'GO    %s — shippable: sealed GO, acceptance proven, no blockers, no open validating gate.\n' "$slug"
+  exit 0
+fi
+printf 'NO-GO %s — %d blocker(s):\n' "$slug" "${#problems[@]}"
+for p in "${problems[@]}"; do printf '  - %s\n' "$p"; done
+exit 1

package/scripts/install-lib.sh

@@ -0,0 +1,83 @@
+#!/usr/bin/env bash
+# install-lib.sh — shared helpers for install.sh / uninstall.sh.
+# Sourced, not executed. Bash 3.2 compatible (no assoc arrays, no mapfile).
+
+# ---- logging -------------------------------------------------------------
+if [ -t 1 ]; then
+  DR_B="$(printf '\033[1m')"; DR_R="$(printf '\033[0m')"
+  DR_Y="$(printf '\033[33m')"; DR_G="$(printf '\033[32m')"; DR_C="$(printf '\033[36m')"
+else
+  DR_B=""; DR_R=""; DR_Y=""; DR_G=""; DR_C=""
+fi
+dr_say()  { printf '%s\n' "$*"; }
+dr_info() { printf '%s%s%s\n' "$DR_C" "$*" "$DR_R"; }
+dr_ok()   { printf '%s%s%s\n' "$DR_G" "$*" "$DR_R"; }
+dr_warn() { printf '%swarning:%s %s\n' "$DR_Y" "$DR_R" "$*" >&2; }
+dr_err()  { printf 'error: %s\n' "$*" >&2; }
+dr_die()  { dr_err "$*"; exit 1; }
+
+# ---- paths ---------------------------------------------------------------
+# Canonical absolute path of an existing directory.
+dr_abspath_dir() {
+  ( cd "$1" 2>/dev/null && pwd -P ) || return 1
+}
+# Canonical absolute path of a path whose parent exists (file may not).
+dr_canon() {
+  _p="$1"
+  case "$_p" in
+    /*) : ;;
+    *)  _p="$PWD/$_p" ;;
+  esac
+  _d="$( cd "$(dirname "$_p")" 2>/dev/null && pwd -P )" || return 1
+  printf '%s/%s\n' "$_d" "$(basename "$_p")"
+}
+
+# ---- manifest ------------------------------------------------------------
+# Manifest = newline list of target-relative paths, plus comment header lines.
+DR_MANIFEST_NAME=".claude/devrites.manifest"
+
+# True if a target-relative path is listed in the manifest file.
+dr_manifest_contains() {
+  _mf="$1"; _rel="$2"
+  [ -f "$_mf" ] || return 1
+  # exact line match, ignoring comment/blank lines
+  grep -v '^#' "$_mf" 2>/dev/null | grep -v '^[[:space:]]*$' \
+    | grep -Fxq "$_rel"
+}
+
+# ---- misc ----------------------------------------------------------------
+dr_lc() { printf '%s' "$1" | tr '[:upper:]' '[:lower:]'; }
+
+# Is $1 (canonical) equal to, or inside, the user's global ~/.claude?
+# Used to refuse global writes. No write verbs here — read-only comparison.
+dr_is_global_claude() {
+  _t="$1"
+  _home_claude="$HOME/.claude"
+  [ "$_t" = "$_home_claude" ] && return 0
+  case "$_t/" in
+    "$_home_claude"/*) return 0 ;;
+  esac
+  return 1
+}
+
+# ---- alias wrapper template ----------------------------------------------
+# Generate a thin SKILL.md that delegates to a DevRites skill. Used by:
+#   - install.sh (--short-aliases=all → /define, /build, /prove, /seal)
+#   - scripts/pin.sh (user-pinned ad-hoc shortcuts)
+# Args: $1=alias-name, $2=target-skill-name (e.g. rite-build), $3=output-file
+dr_gen_alias_wrapper() {
+  _name="$1"; _to="$2"; _out="$3"
+  cat > "$_out" <<EOF
+---
+name: $_name
+description: Alias of DevRites /$_to. Use when the user runs /$_name. Delegates to /$_to.
+argument-hint: "[args]"
+user-invocable: true
+---
+
+# /$_name — alias of /$_to
+
+This command **delegates to DevRites \`/$_to\`**. State that to the user, then load and
+run \`$_to/SKILL.md\` with the given arguments, following it exactly.
+EOF
+}