@bonesofspring/ai-rules 0.2.18 → 0.2.19

package/scripts/check-preset-twin-map.sh

@@ -0,0 +1,122 @@
+#!/usr/bin/env bash
+# FAIL if Cursor→Claude twin mapping is incomplete for next + ios-swift.
+# Exit 0 on OK; exit 1 on any FAIL.
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/../../.." && pwd)"
+export AI_RULES_PRESETS_ROOT="$ROOT/packages/ai-rules/presets"
+
+python3 <<'PY'
+from __future__ import annotations
+
+import os
+import re
+import sys
+from pathlib import Path
+
+presets = Path(os.environ["AI_RULES_PRESETS_ROOT"])
+STACKS = ("next", "nuxt", "svelte", "ios-swift", "android-kotlin", "go", "java", "mcp-ts", "php-hexagonal", "php-laravel")
+
+# Mapping rows: | `foo.mdc` | `topic/bar.md` |
+ROW_RE = re.compile(
+    r"^\|\s*`([^`]+?\.mdc)`\s*\|\s*`([^`]+?\.md)`\s*\|",
+    re.MULTILINE,
+)
+
+
+def parse_mapping(readme: Path) -> dict[str, str]:
+    text = readme.read_text(encoding="utf-8")
+    # Prefer the Cursor → Claude mapping section if present
+    marker = "## Cursor → Claude mapping"
+    idx = text.find(marker)
+    section = text[idx:] if idx >= 0 else text
+    # Stop at next ## heading of same or higher level if possible
+    next_h = re.search(r"\n## (?!#)", section[len(marker) :])
+    if next_h:
+        section = section[: len(marker) + next_h.start()]
+    mapping: dict[str, str] = {}
+    for m in ROW_RE.finditer(section):
+        cursor_stem = m.group(1)
+        claude_rel = m.group(2)
+        mapping[cursor_stem] = claude_rel
+    return mapping
+
+
+failed = 0
+
+print("Preset twin-map completeness")
+print(f"Presets: {presets}")
+print()
+
+for stack in STACKS:
+    cursor_rules = presets / "cursor" / stack / "rules"
+    claude_rules = presets / "claude" / stack / "rules"
+    readme = claude_rules / "README.md"
+
+    print(f"=== {stack} ===")
+    if not cursor_rules.is_dir():
+        print(f"FAIL: missing Cursor rules dir {cursor_rules}")
+        failed += 1
+        continue
+    if not readme.is_file():
+        print(f"FAIL: missing mapping README {readme}")
+        failed += 1
+        continue
+
+    mapping = parse_mapping(readme)
+    if not mapping:
+        print(f"FAIL: no Cursor→Claude mapping rows in {readme}")
+        failed += 1
+        continue
+
+    cursor_mdc = sorted(p for p in cursor_rules.glob("*.mdc") if p.is_file())
+    mapped_stems = set(mapping.keys())
+    cursor_names = {p.name for p in cursor_mdc}
+
+    missing_rows = sorted(cursor_names - mapped_stems)
+    extra_rows = sorted(mapped_stems - cursor_names)
+
+    for name in missing_rows:
+        print(f"FAIL: Cursor stem not in mapping table: {name}")
+        failed += 1
+
+    for name in extra_rows:
+        print(f"FAIL: mapping row has no Cursor .mdc: {name}")
+        failed += 1
+
+    mapped_twins: set[str] = set()
+    for cursor_name, twin_rel in sorted(mapping.items()):
+        if cursor_name not in cursor_names:
+            continue
+        twin_path = claude_rules / twin_rel
+        mapped_twins.add(twin_rel.replace("\\", "/"))
+        if not twin_path.is_file():
+            print(f"FAIL: twin missing for {cursor_name} → {twin_rel}")
+            failed += 1
+
+    # Orphan Claude topic .md (exclude **/README.md indexes)
+    orphans: list[str] = []
+    for path in sorted(claude_rules.rglob("*.md")):
+        if path.name == "README.md":
+            continue
+        rel = path.relative_to(claude_rules).as_posix()
+        if rel not in mapped_twins:
+            orphans.append(rel)
+
+    for rel in orphans:
+        print(f"FAIL: orphan Claude twin (not in mapping): {rel}")
+        failed += 1
+
+    print(
+        f"  Cursor .mdc: {len(cursor_mdc)}; mapping rows: {len(mapping)}; "
+        f"orphans: {len(orphans)}"
+    )
+    print()
+
+if failed:
+    print(f"Result: FAIL ({failed} issue(s))")
+    sys.exit(1)
+
+print("Result: OK")
+sys.exit(0)
+PY

package/scripts/check-product-specs.sh

@@ -0,0 +1,90 @@
+#!/usr/bin/env bash
+# Optional consumer/opt-in check for docs/specs frontmatter + INDEX links.
+# Default: WARN (exit 0 with messages). --strict: FAIL (exit 1) on issues.
+# Not required for consumer CI unless AC/--strict says so.
+# Does not load or evaluate schemas/frontmatter-v1.schema.json (documentation artifact only).
+set -euo pipefail
+
+ROOT="."
+STRICT=0
+for arg in "$@"; do
+  case "$arg" in
+    --strict) STRICT=1 ;;
+    -*)
+      echo "Unknown flag: $arg" >&2
+      exit 2
+      ;;
+    *) ROOT="$arg" ;;
+  esac
+done
+
+SPECS="$ROOT/docs/specs"
+INDEX="$SPECS/INDEX.md"
+WARNINGS=0
+FAILURES=0
+
+log() { printf '%s\n' "$*"; }
+fail() { log "FAIL: $*"; FAILURES=$((FAILURES + 1)); }
+
+if [[ ! -d "$SPECS" ]]; then
+  log "OK: no docs/specs/ (optional tree)"
+  exit 0
+fi
+
+if [[ ! -f "$INDEX" ]]; then
+  fail "docs/specs/ exists but INDEX.md missing"
+else
+  while IFS= read -r line; do
+    [[ "$line" =~ ^\| ]] || continue
+    path=$(echo "$line" | grep -oE 'docs/specs/[^|[:space:]]+\.md' | head -1 || true)
+    [[ -n "${path:-}" ]] || continue
+    if [[ ! -f "$ROOT/$path" ]]; then
+      fail "INDEX path missing: $path"
+    fi
+  done < "$INDEX"
+fi
+
+REQUIRED_KEYS=(id type domain routes ui store api aliases e2e)
+REQUIRED_PAGE_HEADINGS=("## Overview" "## Entry / actors" "## Primary flows" "## States" "## Acceptance criteria")
+REQUIRED_FEATURE_HEADINGS=("## Overview" "## Shared behavior / constraints" "## Related pages")
+
+shopt -s nullglob
+for f in "$SPECS"/domains/*/*.md; do
+  body=$(cat "$f")
+  if [[ "$body" != ---* ]]; then
+    fail "missing frontmatter: $f"
+    continue
+  fi
+  fm=$(awk 'BEGIN{p=0} /^---$/{p++; next} p==1{print} p==2{exit}' "$f")
+  for key in "${REQUIRED_KEYS[@]}"; do
+    if ! grep -qE "^${key}:" <<<"$fm"; then
+      fail "missing frontmatter key '$key': $f"
+    fi
+  done
+  type=$(grep -E '^type:' <<<"$fm" | head -1 | sed 's/^type:[[:space:]]*//;s/[[:space:]]*$//' || true)
+  if [[ "$type" == "page" ]]; then
+    for h in "${REQUIRED_PAGE_HEADINGS[@]}"; do
+      if ! grep -qF "$h" <<<"$body"; then
+        fail "missing heading '$h': $f"
+      fi
+    done
+  elif [[ "$type" == "feature" ]]; then
+    for h in "${REQUIRED_FEATURE_HEADINGS[@]}"; do
+      if ! grep -qF "$h" <<<"$body"; then
+        fail "missing heading '$h': $f"
+      fi
+    done
+  fi
+done
+
+if (( FAILURES > 0 )); then
+  log "Found $FAILURES failure(s), $WARNINGS warning(s)"
+  if (( STRICT == 1 )); then
+    exit 1
+  fi
+  log "(non-strict) exiting 0 — re-run with --strict to fail CI"
+  exit 0
+fi
+
+log "OK: docs/specs checks passed ($WARNINGS warning(s))"
+exit 0

package/scripts/check-rule-eval.mjs

@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+/**
+ * Opt-in eval: Incorrect/Correct pairs + impact frontmatter for **next** golden rules.
+ * Scope is next-only (eval/next/manifest.json). Other presets (go/java/php-hexagonal/…)
+ * are out of scope until they ship their own eval/<stack>/ manifest.
+ * Usage (cwd packages/ai-rules): node scripts/check-rule-eval.mjs
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = path.join(__dirname, '..');
+const MANIFEST = path.join(PKG_ROOT, 'eval/next/manifest.json');
+
+const IMPACT_RE = /^impact:\s*(CRITICAL|HIGH|MEDIUM|LOW)\s*$/m;
+
+function fail(msg) {
+  console.error(`FAIL: ${msg}`);
+  return false;
+}
+
+function warn(msg) {
+  console.warn(`WARN: ${msg}`);
+}
+
+function countHeadings(text, kind) {
+  const re =
+    kind === 'Incorrect'
+      ? /^#{2,3}\s+Incorrect\s*$/gim
+      : /^#{2,3}\s+Correct\s*$/gim;
+  const m = text.match(re);
+  return m ? m.length : 0;
+}
+
+function sectionBodies(text, kind) {
+  const headingRe =
+    kind === 'Incorrect'
+      ? /^#{2,3}\s+Incorrect\s*$/gim
+      : /^#{2,3}\s+Correct\s*$/gim;
+
+  const bodies = [];
+  let match;
+  const re = new RegExp(headingRe.source, 'gim');
+  while ((match = re.exec(text)) !== null) {
+    const start = match.index + match[0].length;
+    let end = text.length;
+    if (kind === 'Incorrect') {
+      const correctRe = /^#{2,3}\s+Correct\s*$/gim;
+      correctRe.lastIndex = start;
+      const c = correctRe.exec(text);
+      if (c) end = c.index;
+      else {
+        const anyH = /^#{2,3}\s+/gm;
+        anyH.lastIndex = start;
+        const h = anyH.exec(text);
+        if (h) end = h.index;
+      }
+    } else {
+      const anyH = /^#{2,3}\s+/gm;
+      anyH.lastIndex = start;
+      const h = anyH.exec(text);
+      if (h) end = h.index;
+    }
+    bodies.push(text.slice(start, end));
+  }
+  return bodies;
+}
+
+function hasNonEmptyFence(section) {
+  const fenceRe = /```[^\n]*\n([\s\S]*?)```/g;
+  let m;
+  while ((m = fenceRe.exec(section)) !== null) {
+    if (m[1].trim().length > 0) return true;
+  }
+  return false;
+}
+
+function checkFile(relPath, minPairs, requireImpact) {
+  const file = path.join(PKG_ROOT, relPath);
+  if (!fs.existsSync(file)) {
+    return { ok: fail(`missing file ${relPath}`), incorrectCount: 0, correctCount: 0 };
+  }
+  const text = fs.readFileSync(file, 'utf8');
+  let ok = true;
+
+  if (requireImpact && !IMPACT_RE.test(text)) {
+    ok = fail(`${relPath}: missing or invalid impact frontmatter`);
+  }
+
+  const incorrectCount = countHeadings(text, 'Incorrect');
+  const correctCount = countHeadings(text, 'Correct');
+  const pairs = Math.min(incorrectCount, correctCount);
+
+  if (pairs < minPairs) {
+    ok =
+      fail(
+        `${relPath}: need ≥${minPairs} Incorrect/Correct pair(s), found incorrect=${incorrectCount} correct=${correctCount}`,
+      ) && ok;
+  }
+
+  const incorrectBodies = sectionBodies(text, 'Incorrect');
+  const correctBodies = sectionBodies(text, 'Correct');
+  for (let i = 0; i < Math.min(incorrectBodies.length, correctBodies.length); i++) {
+    if (!hasNonEmptyFence(incorrectBodies[i])) {
+      ok = fail(`${relPath}: Incorrect #${i + 1} has no non-empty fenced block`) && ok;
+    }
+    if (!hasNonEmptyFence(correctBodies[i])) {
+      ok = fail(`${relPath}: Correct #${i + 1} has no non-empty fenced block`) && ok;
+    }
+  }
+
+  return { ok, incorrectCount, correctCount };
+}
+
+function main() {
+  if (!fs.existsSync(MANIFEST)) {
+    console.error(`FAIL: manifest not found: ${MANIFEST}`);
+    process.exit(1);
+  }
+  const manifest = JSON.parse(fs.readFileSync(MANIFEST, 'utf8'));
+  let failed = 0;
+
+  console.log(`Rule eval (${manifest.stack}) — ${manifest.rules.length} stem(s)`);
+  for (const rule of manifest.rules) {
+    const minPairs = rule.minPairs ?? 1;
+    const requireImpact = Boolean(rule.requireImpact);
+    console.log(`\n=== ${rule.stem} ===`);
+    const c = checkFile(rule.cursor, minPairs, requireImpact);
+    const cl = checkFile(rule.claude, minPairs, requireImpact);
+    if (c.incorrectCount !== cl.incorrectCount || c.correctCount !== cl.correctCount) {
+      warn(
+        `${rule.stem}: heading count differs cursor(I=${c.incorrectCount},C=${c.correctCount}) vs claude(I=${cl.incorrectCount},C=${cl.correctCount})`,
+      );
+    }
+    if (!c.ok || !cl.ok) failed++;
+    else console.log(`PASS: ${rule.stem}`);
+  }
+
+  console.log();
+  if (failed) {
+    console.error(`Result: FAIL (${failed} stem(s))`);
+    process.exit(1);
+  }
+  console.log('Result: OK');
+  process.exit(0);
+}
+
+main();

package/scripts/check-shared-core-drift.sh

@@ -0,0 +1,148 @@
+#!/usr/bin/env bash
+# Soft-check embed-mode shared-core adapters vs core prose.
+# Lineage-mode stems are listed and skipped (marker presence only).
+# Exit 0 always for soft mode; exit 1 if AI_RULES_DRIFT_FAIL=1 and drift found.
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/../../.." && pwd)"
+export AI_RULES_PRESETS_ROOT="$ROOT/packages/ai-rules/presets"
+
+python3 <<'PY'
+from __future__ import annotations
+
+import os
+import re
+import sys
+from pathlib import Path
+
+presets = Path(os.environ["AI_RULES_PRESETS_ROOT"])
+core_root = presets / "_shared" / "core"
+
+EMBED = [
+    "quality/code-quality-and-refactoring.md",
+    "quality/anti-sycophancy-discipline.md",
+    "quality/design-guidance.md",
+    "quality/mcp-usage.md",
+    "meta/preset-layering.md",
+    "meta/preset-twin-sync.md",
+    "meta/preset-token-budget.md",
+    "meta/preset-pr-checklist.md",
+    "meta/preset-no-cross-stack-leakage.md",
+    "review/code-review-mr.md",
+    "review/technical-retro.md",
+    "review/mockup-review.md",
+    "review/ux-design.md",
+    "agent-team/agent-team-intake.md",
+    "architecture/product-specs.md",
+    "architecture/product-specs-authoring.md",
+]
+
+LINEAGE = [
+    "architecture/feature-delivery-workflow.md",
+    "architecture/reference-features.template.md",
+    "agent-team/agent-team-orchestrator.md",
+]
+
+# Full-line sync marker only (do not strip prose that *mentions* the marker).
+MARKER_LINE_RE = re.compile(r"^<!--\s*shared-core:\s*[^>]+?\s*-->\s*$")
+
+
+def strip_frontmatter(text: str) -> str:
+    if not text.startswith("---\n"):
+        return text
+    end = text.find("\n---\n", 4)
+    if end < 0:
+        return text
+    return text[end + 5 :]
+
+
+def normalize_adapter(text: str) -> str:
+    text = strip_frontmatter(text)
+    lines: list[str] = []
+    skip_stack = False
+    for line in text.splitlines():
+        if MARKER_LINE_RE.match(line.strip()):
+            continue
+        if line.startswith("## Stack notes"):
+            skip_stack = True
+        if skip_stack:
+            continue
+        lines.append(line.rstrip())
+    while lines and not lines[0]:
+        lines.pop(0)
+    while lines and not lines[-1]:
+        lines.pop()
+    return "\n".join(lines) + ("\n" if lines else "")
+
+
+def normalize_core(text: str) -> str:
+    lines = [line.rstrip() for line in text.splitlines()]
+    while lines and not lines[0]:
+        lines.pop(0)
+    while lines and not lines[-1]:
+        lines.pop()
+    return "\n".join(lines) + ("\n" if lines else "")
+
+
+def consumers(stem: str) -> list[Path]:
+    out: list[Path] = []
+    needle = f"shared-core: {stem}"
+    for base in (presets / "cursor", presets / "claude"):
+        for path in base.rglob("*"):
+            if path.suffix not in {".md", ".mdc"}:
+                continue
+            try:
+                if needle in path.read_text(encoding="utf-8"):
+                    out.append(path)
+            except OSError:
+                continue
+    return out
+
+
+print("Shared-core drift check (embed mode)")
+print(f"Core: {core_root}")
+print()
+
+drift = 0
+checked = 0
+
+for stem in EMBED:
+    core_file = core_root / stem
+    if not core_file.is_file():
+        print(f"WARN: missing core {stem}")
+        continue
+    core_n = normalize_core(core_file.read_text(encoding="utf-8"))
+    for adapter in consumers(stem):
+        checked += 1
+        ad_n = normalize_adapter(adapter.read_text(encoding="utf-8"))
+        if ad_n != core_n:
+            print(f"DRIFT (embed): {adapter}")
+            print(f"  vs core: {stem}")
+            drift += 1
+
+print()
+print("Lineage-mode (marker only; body not compared):")
+lineage_ok = 0
+for stem in LINEAGE:
+    count = len(consumers(stem))
+    print(f"  {stem} → {count} consumers")
+    if count < 1:
+        print(f"  WARN: no consumers for lineage stem {stem}")
+    else:
+        lineage_ok += 1
+
+print()
+print(
+    f"Checked embed adapters: {checked}; drift: {drift}; "
+    f"lineage stems ok: {lineage_ok}/{len(LINEAGE)}"
+)
+
+if drift:
+    print("Result: DRIFT (soft — document intentional fork or re-sync embed bodies)")
+    if os.environ.get("AI_RULES_DRIFT_FAIL") == "1":
+        sys.exit(1)
+    sys.exit(0)
+
+print("Result: OK")
+sys.exit(0)
+PY

package/scripts/close-agent-task-human-gate.mjs

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+/**
+ * Thin wrapper around the installed chain-team-phases hook action `end_human_gate`.
+ * Prefer invoking the hook directly from /task-continue (see command Metrics section).
+ *
+ * Usage:
+ *   node close-agent-task-human-gate.mjs [--cwd <repo>] [--platform cursor|claude] [--slug <slug>]
+ */
+
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+function parseArgs(argv) {
+  const options = { cwd: process.cwd(), platform: 'cursor', slug: null };
+  for (let i = 2; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--cwd') options.cwd = path.resolve(argv[++i]);
+    else if (arg === '--platform') options.platform = argv[++i];
+    else if (arg === '--slug') options.slug = argv[++i];
+    else if (arg === '--activate-next') {
+      /* always activate via hook payload */
+    } else if (arg === '--team-root') {
+      // Compatibility with earlier docs: derive platform + cwd from team root.
+      const teamRoot = path.resolve(argv[++i]);
+      options.cwd = path.resolve(teamRoot, '..', '..');
+      options.platform = path.basename(path.dirname(teamRoot)) === '.claude' ? 'claude' : 'cursor';
+    } else {
+      console.error(`Unknown argument: ${arg}`);
+      process.exit(2);
+    }
+  }
+  return options;
+}
+
+const options = parseArgs(process.argv);
+const toolRoot = path.join(options.cwd, `.${options.platform}`);
+const hookPath = path.join(toolRoot, 'hooks', 'chain-team-phases.sh');
+if (!fs.existsSync(hookPath)) {
+  console.error(`Installed hook not found: ${hookPath}`);
+  process.exit(1);
+}
+
+if (options.slug) {
+  const activePath = path.join(toolRoot, 'team', 'active-task.json');
+  fs.mkdirSync(path.dirname(activePath), { recursive: true });
+  fs.writeFileSync(activePath, `${JSON.stringify({ slug: options.slug }, null, 2)}\n`);
+}
+
+const payload = JSON.stringify({
+  status: 'completed',
+  action: 'end_human_gate',
+  activateNext: true,
+});
+
+const output = execFileSync('bash', [hookPath], {
+  cwd: options.cwd,
+  encoding: 'utf8',
+  input: payload,
+});
+process.stdout.write(output || '{}\n');

package/scripts/sync-dogfood-cursor.sh

@@ -0,0 +1,70 @@
+#!/usr/bin/env bash
+# Sync monorepo dogfood root `.cursor/` from Cursor next preset (packages SoT).
+# Also syncs repo-root AGENTS.md from REPO_AGENTS.md when present.
+# Usage (from repo root or any cwd):
+#   ./packages/ai-rules/scripts/sync-dogfood-cursor.sh
+#   AI_RULES_DOGFOOD_PRESET=ios-swift ./packages/ai-rules/scripts/sync-dogfood-cursor.sh
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/../../.." && pwd)"
+PRESET_NAME="${AI_RULES_DOGFOOD_PRESET:-next}"
+SRC="$ROOT/packages/ai-rules/presets/cursor/$PRESET_NAME"
+DST="$ROOT/.cursor"
+
+if [[ ! -d "$SRC" ]]; then
+  echo "error: preset not found: $SRC" >&2
+  exit 1
+fi
+
+echo "Dogfood sync: $SRC → $DST (preset=$PRESET_NAME)"
+
+mkdir -p "$DST"
+
+# Platform files at preset root
+for f in AGENTS.md BUGBOT.md MCP.md hooks.json mcp.json README.md; do
+  if [[ -f "$SRC/$f" ]]; then
+    cp "$SRC/$f" "$DST/$f"
+  fi
+done
+
+# Repo-root AGENTS.md (cross-tool) from REPO_AGENTS.md
+if [[ -f "$SRC/REPO_AGENTS.md" ]]; then
+  cp "$SRC/REPO_AGENTS.md" "$ROOT/AGENTS.md"
+  echo "Copied REPO_AGENTS.md → $ROOT/AGENTS.md"
+fi
+
+# Directory trees (preserve local team/tasks)
+for dir in agents commands hooks rules skills; do
+  if [[ -d "$SRC/$dir" ]]; then
+    mkdir -p "$DST/$dir"
+    rsync -a --delete "$SRC/$dir/" "$DST/$dir/"
+  fi
+done
+
+if [[ -d "$SRC/team" ]]; then
+  mkdir -p "$DST/team"
+  # Sync fixtures + README; never delete local tasks/
+  if [[ -d "$SRC/team/fixtures" ]]; then
+    mkdir -p "$DST/team/fixtures"
+    rsync -a --delete "$SRC/team/fixtures/" "$DST/team/fixtures/"
+  fi
+  if [[ -f "$SRC/team/README.md" ]]; then
+    cp "$SRC/team/README.md" "$DST/team/README.md"
+  fi
+  if [[ -f "$SRC/team/.gitkeep" ]]; then
+    mkdir -p "$DST/team/tasks"
+    cp "$SRC/team/.gitkeep" "$DST/team/tasks/.gitkeep" 2>/dev/null || true
+  fi
+  # Living conventions: seed if absent; preserve consumer edits
+  if [[ -f "$SRC/team/conventions.md" ]]; then
+    if [[ ! -f "$DST/team/conventions.md" ]]; then
+      cp "$SRC/team/conventions.md" "$DST/team/conventions.md"
+      echo "Seeded team/conventions.md"
+    else
+      echo "Tip: skipped team/conventions.md (already present — living dogfood notes preserved)"
+    fi
+  fi
+fi
+
+echo "Done. Review: git status -- .cursor/ AGENTS.md"
+echo "Tip: run packages/ai-rules/scripts/check-shared-core-drift.sh after core edits."