@bonesofspring/ai-rules 0.2.21 → 0.2.22

package/presets/cursor/php-laravel/hooks/chain-team-phases.sh

@@ -66,10 +66,20 @@ const STACK = 'php-laravel';
 const PLATFORM = 'cursor';
 
 function waitForMetricsLock() {
+  // OD-1: real advisory lock via create-exclusive (fs.openSync(_, 'wx')).
+  // The previous impl spun on Atomics.wait against an unrelated SharedArrayBuffer
+  // and never blocked on the lock file, so two concurrent subagentStop events
+  // could both acquire the lock and corrupt metrics.json. Retry EEXIST with a
+  // 10 ms sleep up to 200 attempts (2 s ceiling). On any other error, throw.
   for (let attempt = 0; attempt < 200; attempt += 1) {
-    try { fs.mkdirSync(METRICS_LOCK); return; } catch (error) {
-      if (error && error.code !== 'EEXIST') throw error;
-      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 10);
+    try {
+      const fd = fs.openSync(METRICS_LOCK, 'wx');
+      try { fs.closeSync(fd); } catch {}
+      return;
+    } catch (error) {
+      if (!error || error.code !== 'EEXIST') throw error;
+      const until = Date.now() + 10;
+      while (Date.now() < until) { /* 10 ms busy-wait */ }
     }
   }
   throw new Error('metrics lock timeout');
@@ -78,7 +88,7 @@ let taskLockHeld = false;
 function releaseTaskLock() {
   if (!taskLockHeld) return;
   taskLockHeld = false;
-  try { fs.rmdirSync(METRICS_LOCK); } catch {}
+  try { fs.unlinkSync(METRICS_LOCK); } catch {}
 }
 waitForMetricsLock();
 taskLockHeld = true;
@@ -106,7 +116,7 @@ function mutateMetrics(mutator) {
     fs.writeFileSync(temporary, JSON.stringify(metrics, null, 2) + '\n');
     fs.renameSync(temporary, METRICS_PATH);
   } finally {
-    if (acquiredHere) { try { fs.rmdirSync(METRICS_LOCK); } catch {} }
+    if (acquiredHere) { try { fs.unlinkSync(METRICS_LOCK); } catch {} }
   }
 }
 function appendMetric(event) { mutateMetrics((metrics) => metrics.events.push({ eventId: `${metrics.task.runId}:${Date.now()}:${Math.random().toString(16).slice(2)}`, ...event })); }
@@ -481,7 +491,19 @@ function legacyFlow() {
 
 
 if (hookInput.action === 'end_human_gate') {
-  status.awaitingHumanGate = false;
+    status.awaitingHumanGate = false;
+  // A2 (retro §8): pin a single runId per pipeline so subsequent events don't
+  // fragment the metrics ledger across multiple runId sequences. Prefer
+  // metrics.json.task.runId when metrics already exist, then status.metricsRunId,
+  // then mint a fresh seed only on first ever emit.
+  try {
+    if (fs.existsSync(METRICS_PATH)) {
+      const existing = JSON.parse(fs.readFileSync(METRICS_PATH, 'utf8'));
+      if (existing && existing.task && typeof existing.task.runId === 'string') {
+        status.metricsRunId = existing.task.runId;
+      }
+    }
+  } catch {}
   if (status.state === 'awaiting_approval') {
     status.state = 'in_progress';
     status.phase = status.phase === 'human_gate' ? 'executing' : status.phase;
@@ -520,11 +542,29 @@ if (hookInput.action === 'end_human_gate') {
       }
     }
   }
-  writeStatus({
-    awaitingHumanGate: false,
-    state: status.state,
-    phase: status.phase,
-  });
+  // A2 (retro §8): if gate closes the final human gate of the pipeline
+  // (no resume happens, or current step's gate was the last), surface
+  // state="awaiting_approval" so a subsequent /task-continue doesn't misinterpret
+  // the post-gate idle state as "still in progress".
+  {
+    let gateWasTerminal = false;
+    if (!hookInput.activateNext && fs.existsSync(pipelinePath)) {
+      try {
+        const pipe = JSON.parse(fs.readFileSync(pipelinePath, 'utf8'));
+        const steps = pipe.steps || [];
+        const idx = typeof status.pipelineIndex === 'number' ? status.pipelineIndex : 0;
+        const cur = steps[idx];
+        const gates = Array.isArray(pipe.humanGates) ? pipe.humanGates : [];
+        const hasGate = (step) => Array.isArray(gates) && gates.some((g) => typeof g === 'string' && getStepAgents(step).some((a) => g === `after:${a}`));
+        if (cur && hasGate(cur)) gateWasTerminal = true;
+      } catch {}
+    }
+    writeStatus({
+      awaitingHumanGate: false,
+      state: gateWasTerminal ? 'awaiting_approval' : status.state,
+      phase: status.phase,
+    });
+  }
   process.stdout.write(JSON.stringify({ ok: true, action: 'end_human_gate', activeHumanGateEventId: status.activeHumanGateEventId || null }));
   process.exit(0);
 }

package/presets/cursor/php-laravel/rules/preset-twin-sync.mdc

@@ -40,7 +40,7 @@ Cursor `.mdc` — **SoT per stack**. Claude topic `.md` — derived twin.
 - **Domain** rules: ≥15 body lines (FAIL if thin without documented alias reason).
 - **Thin aliases** (`agent-team-intake`, `technical-retro`): may be shorter (soft) if they only point to a command/skill.
 - **Slim-companion rules** (UI-edit bundle, slim app-cores, slim tooling): may be shorter than 15 lines **if and only if** the body is a pointer into shared-core / stack-prose (no standalone prose). Examples live in stack `rules/README.md` (e.g. `cursor/next/rules/README.md` "UI-edit bundle" intent).
-  - **Mechanical enforcement is pending.** Today build-verifier excludes only `agent-team-intake` / `technical-retro` / `preset-layering`; slim-companion rules currently pass under the same human-judgement path as thin aliases. Follow-up: add `allow_slim_stems` to `packages/ai-rules/scripts/check-preset-token-budget.sh` analogous to `trio_stems_allowlist`.
+  - Mechanical enforcement lives in `packages/ai-rules/scripts/check-preset-token-budget.sh` — see `SLIM_COMPANION_ALLOWLIST` (the 53 stems accepted as slim pointers) and `MIN_SLIM_BODY_LINES` (5-line floor). Slim-companion rules with a body of 6–14 lines whose stem is **not** in the allowlist are reported as slim violations by the script.
 
 ## Severity (build-verifier)
 

package/presets/cursor/svelte/agents/build-verifier.md

@@ -97,6 +97,8 @@ Write the owned terminal receipt described under **Artifact contract**. If **FAI
 
 Do not fix code — report only. Do not advance to code-reviewer until PASS.
 
+**Receipt binding.** When writing the terminal receipt to `artifact-manifest.json`, set `entry.receipt.attemptId = <attemptId supplied by the orchestrator>` (the orchestrator provides this via `attemptId` on invocation). The hook at `chain-team-phases.sh:readBoundReceiptOutcome` rejects entries whose `attemptId` does not match the current attempt, or whose `Date.parse(timestamps.completedAt) < Date.parse(attemptStartedAt)`. A missing or stale attemptId causes `awaiting_artifact_receipt` stalls. <!-- shared-core: receipt-binding -->
+
 ## Artifact contract
 
 - **Authoritative inputs:** read `.cursor/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the manifest entries for brief/decomposition, implementation evidence, pipeline scope, and changed files.

package/presets/cursor/svelte/agents/code-reviewer.md

@@ -55,6 +55,8 @@ Write the owned terminal receipt described under **Artifact contract**. If **REQ
 
 Do not mix this output with retrospective facilitation — keep review and retro separate.
 
+**Receipt binding.** When writing the terminal receipt to `artifact-manifest.json`, set `entry.receipt.attemptId = <attemptId supplied by the orchestrator>` (the orchestrator provides this via `attemptId` on invocation). The hook at `chain-team-phases.sh:readBoundReceiptOutcome` rejects entries whose `attemptId` does not match the current attempt, or whose `Date.parse(timestamps.completedAt) < Date.parse(attemptStartedAt)`. A missing or stale attemptId causes `awaiting_artifact_receipt` stalls. <!-- shared-core: receipt-binding -->
+
 ## Design guidance
 
 - Load `design-guidance` (rule stem) when assessing structure, smells, or pattern fit.

package/presets/cursor/svelte/agents/debugger.md

@@ -81,3 +81,7 @@ Do not perform formal code review or write e2e plans — those are separate agen
 
 - When writing or changing code, load / follow rule `anti-sycophancy-discipline`.
 - When acting on review feedback (`changes_requested` / human comments): verify each item against the codebase before implementing; no performative agreement.
+
+## Receipt binding
+
+> **Receipt binding.** When writing the terminal receipt to `artifact-manifest.json`, set `entry.receipt.attemptId = <attemptId supplied by the orchestrator>` (the orchestrator provides this via `attemptId` on invocation). The hook at `chain-team-phases.sh:readBoundReceiptOutcome` rejects entries whose `attemptId` does not match the current attempt, or whose `Date.parse(timestamps.completedAt) < Date.parse(attemptStartedAt)`. A missing or stale attemptId causes `awaiting_artifact_receipt` stalls. <!-- shared-core: receipt-binding -->

package/presets/cursor/svelte/agents/feature-developer.md

@@ -13,6 +13,7 @@ You are a senior frontend developer working in a SvelteKit monorepo with strict
 2. Read `status.json` — proceed if `in_progress`, `approved`, or `retryAfterFix`.
 3. Read `pipeline.json` for step context and scope.
 4. Follow the **`feature-delivery` skill** (layer order, reference features, validation handoff).
+5. **Verify carry-over at HEAD before applying** (refactor intent only). When the brief comes from a prior review's carry-over findings list, for each item run `git show HEAD:<path>` or `grep` to confirm the finding still applies at the current HEAD; if the file already contains the fix (carry-over was closed in a prior uncommitted batch), mark it as **NO-OP at HEAD** in `implementation.md` and skip the edit; if the file is unchanged, apply the fix and cite file:line. Target ≤2 NO-OP items per refactor pipeline.
 
 ## Task execution rules
 
@@ -40,6 +41,8 @@ Emit the owned implementation receipt with outcome `completed`. Handoff: tasks d
 
 Do not perform formal code review — that is the code-reviewer subagent's job.
 
+**Receipt binding.** When writing the terminal receipt to `artifact-manifest.json`, set `entry.receipt.attemptId = <attemptId supplied by the orchestrator>` (the orchestrator provides this via `attemptId` on invocation). The hook at `chain-team-phases.sh:readBoundReceiptOutcome` rejects entries whose `attemptId` does not match the current attempt, or whose `Date.parse(timestamps.completedAt) < Date.parse(attemptStartedAt)`. A missing or stale attemptId causes `awaiting_artifact_receipt` stalls. <!-- shared-core: receipt-binding -->
+
 ## Design guidance
 
 - Load `design-guidance` (rule stem) when assessing structure, smells, or pattern fit.

package/presets/cursor/svelte/agents/qa-tester.md

@@ -53,3 +53,7 @@ Provide summary:
 ## Design guidance
 
 - Load `design-guidance` (rule stem) when assessing structure, smells, or pattern fit.
+
+## Receipt binding
+
+> **Receipt binding.** When writing the terminal receipt to `artifact-manifest.json`, set `entry.receipt.attemptId = <attemptId supplied by the orchestrator>` (the orchestrator provides this via `attemptId` on invocation). The hook at `chain-team-phases.sh:readBoundReceiptOutcome` rejects entries whose `attemptId` does not match the current attempt, or whose `Date.parse(timestamps.completedAt) < Date.parse(attemptStartedAt)`. A missing or stale attemptId causes `awaiting_artifact_receipt` stalls. <!-- shared-core: receipt-binding -->

package/presets/cursor/svelte/hooks/chain-team-phases.sh

@@ -64,10 +64,20 @@ const STACK = 'svelte';
 const PLATFORM = 'cursor';
 
 function waitForMetricsLock() {
+  // OD-1: real advisory lock via create-exclusive (fs.openSync(_, 'wx')).
+  // The previous impl spun on Atomics.wait against an unrelated SharedArrayBuffer
+  // and never blocked on the lock file, so two concurrent subagentStop events
+  // could both acquire the lock and corrupt metrics.json. Retry EEXIST with a
+  // 10 ms sleep up to 200 attempts (2 s ceiling). On any other error, throw.
   for (let attempt = 0; attempt < 200; attempt += 1) {
-    try { fs.mkdirSync(METRICS_LOCK); return; } catch (error) {
-      if (error && error.code !== 'EEXIST') throw error;
-      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 10);
+    try {
+      const fd = fs.openSync(METRICS_LOCK, 'wx');
+      try { fs.closeSync(fd); } catch {}
+      return;
+    } catch (error) {
+      if (!error || error.code !== 'EEXIST') throw error;
+      const until = Date.now() + 10;
+      while (Date.now() < until) { /* 10 ms busy-wait */ }
     }
   }
   throw new Error('metrics lock timeout');
@@ -76,7 +86,7 @@ let taskLockHeld = false;
 function releaseTaskLock() {
   if (!taskLockHeld) return;
   taskLockHeld = false;
-  try { fs.rmdirSync(METRICS_LOCK); } catch {}
+  try { fs.unlinkSync(METRICS_LOCK); } catch {}
 }
 waitForMetricsLock();
 taskLockHeld = true;
@@ -104,7 +114,7 @@ function mutateMetrics(mutator) {
     fs.writeFileSync(temporary, JSON.stringify(metrics, null, 2) + '\n');
     fs.renameSync(temporary, METRICS_PATH);
   } finally {
-    if (acquiredHere) { try { fs.rmdirSync(METRICS_LOCK); } catch {} }
+    if (acquiredHere) { try { fs.unlinkSync(METRICS_LOCK); } catch {} }
   }
 }
 function appendMetric(event) { mutateMetrics((metrics) => metrics.events.push({ eventId: `${metrics.task.runId}:${Date.now()}:${Math.random().toString(16).slice(2)}`, ...event })); }
@@ -485,7 +495,19 @@ function legacyFlow() {
 
 
 if (hookInput.action === 'end_human_gate') {
-  status.awaitingHumanGate = false;
+    status.awaitingHumanGate = false;
+  // A2 (retro §8): pin a single runId per pipeline so subsequent events don't
+  // fragment the metrics ledger across multiple runId sequences. Prefer
+  // metrics.json.task.runId when metrics already exist, then status.metricsRunId,
+  // then mint a fresh seed only on first ever emit.
+  try {
+    if (fs.existsSync(METRICS_PATH)) {
+      const existing = JSON.parse(fs.readFileSync(METRICS_PATH, 'utf8'));
+      if (existing && existing.task && typeof existing.task.runId === 'string') {
+        status.metricsRunId = existing.task.runId;
+      }
+    }
+  } catch {}
   if (status.state === 'awaiting_approval') {
     status.state = 'in_progress';
     status.phase = status.phase === 'human_gate' ? 'executing' : status.phase;
@@ -524,11 +546,29 @@ if (hookInput.action === 'end_human_gate') {
       }
     }
   }
-  writeStatus({
-    awaitingHumanGate: false,
-    state: status.state,
-    phase: status.phase,
-  });
+  // A2 (retro §8): if gate closes the final human gate of the pipeline
+  // (no resume happens, or current step's gate was the last), surface
+  // state="awaiting_approval" so a subsequent /task-continue doesn't misinterpret
+  // the post-gate idle state as "still in progress".
+  {
+    let gateWasTerminal = false;
+    if (!hookInput.activateNext && fs.existsSync(pipelinePath)) {
+      try {
+        const pipe = JSON.parse(fs.readFileSync(pipelinePath, 'utf8'));
+        const steps = pipe.steps || [];
+        const idx = typeof status.pipelineIndex === 'number' ? status.pipelineIndex : 0;
+        const cur = steps[idx];
+        const gates = Array.isArray(pipe.humanGates) ? pipe.humanGates : [];
+        const hasGate = (step) => Array.isArray(gates) && gates.some((g) => typeof g === 'string' && getStepAgents(step).some((a) => g === `after:${a}`));
+        if (cur && hasGate(cur)) gateWasTerminal = true;
+      } catch {}
+    }
+    writeStatus({
+      awaitingHumanGate: false,
+      state: gateWasTerminal ? 'awaiting_approval' : status.state,
+      phase: status.phase,
+    });
+  }
   process.stdout.write(JSON.stringify({ ok: true, action: 'end_human_gate', activeHumanGateEventId: status.activeHumanGateEventId || null }));
   process.exit(0);
 }

package/presets/cursor/svelte/rules/preset-twin-sync.mdc

@@ -40,7 +40,7 @@ Cursor `.mdc` — **SoT per stack**. Claude topic `.md` — derived twin.
 - **Domain** rules: ≥15 body lines (FAIL if thin without documented alias reason).
 - **Thin aliases** (`agent-team-intake`, `technical-retro`): may be shorter (soft) if they only point to a command/skill.
 - **Slim-companion rules** (UI-edit bundle, slim app-cores, slim tooling): may be shorter than 15 lines **if and only if** the body is a pointer into shared-core / stack-prose (no standalone prose). Examples live in stack `rules/README.md` (e.g. `cursor/next/rules/README.md` "UI-edit bundle" intent).
-  - **Mechanical enforcement is pending.** Today build-verifier excludes only `agent-team-intake` / `technical-retro` / `preset-layering`; slim-companion rules currently pass under the same human-judgement path as thin aliases. Follow-up: add `allow_slim_stems` to `packages/ai-rules/scripts/check-preset-token-budget.sh` analogous to `trio_stems_allowlist`.
+  - Mechanical enforcement lives in `packages/ai-rules/scripts/check-preset-token-budget.sh` — see `SLIM_COMPANION_ALLOWLIST` (the 53 stems accepted as slim pointers) and `MIN_SLIM_BODY_LINES` (5-line floor). Slim-companion rules with a body of 6–14 lines whose stem is **not** in the allowlist are reported as slim violations by the script.
 
 ## Severity (build-verifier)
 

package/scripts/check-preset-structure.sh

@@ -36,6 +36,7 @@ run_gate "hook-only-lifecycle" "$SCRIPT_DIR/check-hook-only-lifecycle.sh"
 run_gate "local-overlay" "$SCRIPT_DIR/check-local-overlay.sh"
 run_gate "shared-core-drift" "$SCRIPT_DIR/check-shared-core-drift.sh" AI_RULES_DRIFT_FAIL=1
 run_gate "chain-hook-coverage" "$SCRIPT_DIR/check-chain-hook-coverage.sh"
+run_gate "task-router-intents" "$SCRIPT_DIR/check-task-router-intents.sh"
 run_gate "i18n" "$SCRIPT_DIR/check-preset-i18n.sh" AI_RULES_I18N_FAIL=1 AI_RULES_I18N_SOFT=0
 
 echo ">>> cli-mcp-merge"
@@ -65,6 +66,15 @@ else
 fi
 echo
 
+echo ">>> task-router-intents fixtures"
+if node "$SCRIPT_DIR/test-task-router-intents-fixtures.mjs"; then
+  echo "<<< task-router-intents fixtures: OK"
+else
+  echo "<<< task-router-intents fixtures: FAIL"
+  status=1
+fi
+echo
+
 # Soft WARN: dogfood product-specs (never fails the orchestrator).
 # Default check-product-specs exits 0 even when issues are found unless --strict.
 # Use --strict here only to surface problems as WARN in logs; do not flip status.

package/scripts/check-preset-token-budget.sh

@@ -18,6 +18,69 @@ presets = Path(os.environ["AI_RULES_PRESETS_ROOT"])
 STACKS = ("next", "nuxt", "svelte", "ios-swift", "android-kotlin", "go", "java", "mcp-ts", "php-hexagonal", "php-laravel")
 BODY_CAP = 140  # applied to 3-rule trios (Claude session-start, Cursor trio when len==3)
 BODY_CAP_CURSOR_4 = 170  # Cursor now allows 4 always-on (next-app-core, package-manager, code-quality, ai-local-overlay)
+# Slim-companion rules (UI-edit bundle, slim app-cores, slim tooling) may be
+# shorter than 15 lines **if and only if** their stem is in the allow-list and
+# body is <= MIN_SLIM_BODY_LINES. A slim rule whose body grows past this cap
+# without being promoted to a domain rule FAILs the check. Reference:
+# presets/_shared/core/meta/preset-twin-sync.md "Twin depth" section.
+# Cursor and Claude share stems by convention; the list is stem-only and
+# applied per platform.
+SLIM_COMPANION_ALLOWLIST = frozenset({
+    "agent-team-intake",
+    "agent-team-orchestrator",
+    "ai-local-overlay",
+    "api-grpc",
+    "architecture-boundaries-ui",
+    "css-property-order-stylelint",
+    "design-guidance",
+    "domain-layer",
+    "e2e",
+    "feature-delivery-workflow",
+    "http-client",
+    "integration",
+    "ios-app-core",
+    "mcp-usage",
+    "messaging-adapters",
+    "mockup-review",
+    "module-public-api",
+    "navigation-coordinators",
+    "navigation-router-stack",
+    "navigation",
+    "navigation-router-ui",
+    "next-app-router",
+    "no-props-spread",
+    "no-type-assertion-as-import-export",
+    "no-v-bind-spread",
+    "package-manager",
+    "persistence",
+    "persistence-data",
+    "playwright-agents",
+    "post-change-build",
+    "post-change-lint",
+    "post-change-test",
+    "preset-layering",
+    "preset-no-cross-stack-leakage",
+    "preset-pr-checklist",
+    "preset-token-budget",
+    "preset-twin-sync",
+    "react-a11y-coding",
+    "script-setup-conventions",
+    "security-android",
+    "security-go",
+    "security-ios",
+    "security-next",
+    "security-php",
+    "state-and-viewmodels",
+    "technical-retro",
+    "tests-e2e",
+    "tests-integration",
+    "tests-unit",
+    "unit",
+    "ux-design",
+    "vue-a11y-coding",
+    "xcode-tooling",
+})
+MIN_SLIM_BODY_LINES = 5
 MARKER_LINE_RE = re.compile(r"^<!--\s*shared-core:\s*[^>]+?\s*-->\s*$")
 ALWAYS_APPLY_RE = re.compile(r"(?m)^alwaysApply:\s*true\s*$")
 PATHS_RE = re.compile(r"(?m)^paths:\s*")
@@ -138,6 +201,43 @@ for stack in STACKS:
             )
             failed += 1
 
+    # --- Slim-companion enforcement (per stack, both platforms) ---
+    # All .mdc (Cursor) / .md (Claude) rules under the stack's rules/ directory
+    # are scanned. A rule whose body is > MIN_SLIM_BODY_LINES AND whose stem
+    # is NOT in SLIM_COMPANION_ALLOWLIST must be promoted to a domain rule
+    # (>=15 body lines per preset-twin-sync.md "Twin depth"). FAIL otherwise.
+    slim_violations: list[str] = []
+    for rules_dir in (cursor_rules, claude_rules):
+        if not rules_dir.exists():
+            continue
+        pattern = "*.mdc" if rules_dir is cursor_rules else "*.md"
+        for rule_path in sorted(rules_dir.rglob(pattern)):
+            if rule_path.name == "README.md":
+                continue
+            text = rule_path.read_text(encoding="utf-8")
+            _, body = strip_frontmatter(text)
+            n = body_nonempty_lines(body)
+            if n <= MIN_SLIM_BODY_LINES:
+                continue
+            # Skip rules explicitly in the slim-companion allow-list (they are
+            # allowed to be short pointers regardless of body length).
+            if rule_path.stem in SLIM_COMPANION_ALLOWLIST:
+                continue
+            # Domain rules (>=15 lines) are fine; we only flag the 6..14 line
+            # "slim-but-not-allowed" bucket.
+            if n >= 15:
+                continue
+            slim_violations.append(
+                f"{rule_path.relative_to(presets).as_posix()} ({n} lines, slim but not in allow-list)"
+            )
+    if slim_violations:
+        print(f"  Slim-companion allow-list violations ({len(slim_violations)}):")
+        for v in slim_violations[:10]:
+            print(f"    FAIL: {v}")
+        if len(slim_violations) > 10:
+            print(f"    ... and {len(slim_violations) - 10} more")
+        failed += len(slim_violations)
+
     print()
 
 if failed:

package/scripts/check-task-router-intents.sh

@@ -0,0 +1,141 @@
+#!/usr/bin/env bash
+# Cross-check `task-router.md` intent rows against `agents/*.md` `name:` frontmatter.
+#
+# Two-sided verification:
+#  1. Every agent file (frontmatter `name:` other than `task-router` itself) must
+#     be referenced somewhere in the stack's `task-router.md` so the router knows
+#     how to invoke it. Missing mention ⇒ FAIL (the agent will silently never
+#     receive a handoff).
+#  2. Every agent stem referenced in `task-router.md` (in the `Default steps`
+#     column, the `Model tiers` table, or other inline mentions) must have a
+#     corresponding `agents/<stem>.md` file. Missing agent ⇒ FAIL (the router
+#     emits an intent that no agent can satisfy).
+#
+# The check is per `(platform, stack)` pair and runs all 20 ships (cursor + claude
+# × 10 stacks). Exits non-zero on any FAIL.
+#
+# Stack-specific exemptions:
+#  - mcp-ts does not ship `playwright-test-*`, `xcuitest-test-*`, `unit-test-*`
+#    in the standard mix; intent rows that reference those agents are flagged
+#    only on stacks that ship the corresponding `agents/<stem>.md` file.
+#  - Stack leakage (positive agent stems on the wrong stack) is enforced in
+#    `check-preset-leakage.sh`; this check covers task-router sync only.
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/../../.." && pwd)"
+# Allow callers (notably the fixture test) to redirect the presets root via
+# the env var. Default to the real repo path.
+export AI_RULES_PRESETS_ROOT="${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"])
+PLATFORMS = ("cursor", "claude")
+STACKS = ("next", "nuxt", "svelte", "ios-swift", "android-kotlin", "go", "java", "mcp-ts", "php-hexagonal", "php-laravel")
+
+# Agents that are shipped for orchestration purposes but do not need to appear
+# in task-router.md intent rows (router-only / analyzer-only / orchestrator-only).
+ROUTER_EXEMPT_FROM_INTENT = frozenset({
+    "task-router",         # this file
+    "codebase-analyzer",   # ad-hoc explain-as-is agent
+    "agent-team-intake",   # one-off intake, not a pipeline target
+})
+
+# Agent-stem regex: kebab-case, lowercase, may include digits and dots (x.y).
+# Two patterns: (a) hyphen/dot-bounded names like `feature-developer`, `unit.test`,
+# (b) single-word agents that are present in `shipped_names`. Both feed the
+# `agent_like` filter.
+AGENT_NAME_RE = re.compile(r"\b([a-z][a-z0-9]*(?:[-.][a-z0-9]+)+)\b")
+SINGLE_WORD_AGENT_RE = re.compile(r"\b([a-z][a-z0-9]+)\b")
+FRONTMATTER_NAME_RE = re.compile(r"^name:\s*([a-z][a-z0-9]*(?:[-.][a-z0-9]+)+)\s*$", re.MULTILINE)
+
+failures: list[str] = []
+checks = 0
+
+for platform in PLATFORMS:
+    for stack in STACKS:
+        agents_dir = presets / platform / stack / "agents"
+        if not agents_dir.is_dir():
+            continue
+        task_router = agents_dir / "task-router.md"
+        if not task_router.is_file():
+            failures.append(f"{platform}/{stack}: missing task-router.md")
+            continue
+
+        # 1) All agent `name:` frontmatter in this stack's agents dir.
+        shipped_names: set[str] = set()
+        for path in sorted(agents_dir.glob("*.md")):
+            text = path.read_text(encoding="utf-8")
+            m = FRONTMATTER_NAME_RE.search(text)
+            if m:
+                shipped_names.add(m.group(1))
+            # Also pick up the file stem as a fallback (in case frontmatter is missing).
+            if path.stem not in shipped_names and path.stem != "README":
+                shipped_names.add(path.stem)
+
+        # 2) All agent stems referenced in task-router.md (anywhere in body).
+        router_text = task_router.read_text(encoding="utf-8")
+        # Restrict to body (drop YAML frontmatter).
+        body = router_text
+        if router_text.startswith("---\n"):
+            end = router_text.find("\n---\n", 4)
+            if end >= 0:
+                body = router_text[end + 5 :]
+        referenced_in_router: set[str] = set(AGENT_NAME_RE.findall(body))
+        # Single-word tokens that match a shipped agent (e.g. `debugger`,
+        # `codebase-analyzer`, `ci-investigator`) are valid router mentions even
+        # without a hyphen/dot boundary.
+        for token in SINGLE_WORD_AGENT_RE.findall(body):
+            if token in shipped_names:
+                referenced_in_router.add(token)
+        agent_like: set[str] = referenced_in_router - ROUTER_EXEMPT_FROM_INTENT
+
+        # Subset of shipped agents that are not router-exempt AND not referenced.
+        shipped_pipeline_agents = shipped_names - ROUTER_EXEMPT_FROM_INTENT
+        # 1-sided check (FAIL when shipped but not mentioned).
+        not_referenced = sorted(shipped_pipeline_agents - agent_like)
+        for name in not_referenced:
+            checks += 1
+            # The README is not an agent.
+            if name == "README":
+                continue
+            # Skip agents only used as commands or skills (e.g. technical-retro,
+            # agent-team-intake when still present). These are explicitly
+            # exempt — but we already filter ROUTER_EXEMPT_FROM_INTENT, so any
+            # remaining mismatch is a real gap.
+            failures.append(
+                f"{platform}/{stack}: ships agent '{name}.md' but task-router.md does not mention '{name}'"
+            )
+
+        # 2-sided check (FAIL when mentioned in router but not shipped).
+        not_shipped = sorted(agent_like - shipped_names)
+        for name in not_shipped:
+            checks += 1
+            # Allow mentions of common stacks/tools that aren't agents (filter).
+            # Common false positives: branch names, mixed-case strings, etc.
+            # The regex already constrains to lowercase kebab/dot; further filter
+            # by requiring the suffix to look like an agent suffix.
+            if name in {"feature-developer", "build-verifier", "code-reviewer"}:
+                # These should be shipped; surface as FAIL.
+                failures.append(
+                    f"{platform}/{stack}: task-router.md references '{name}' but agents/{name}.md is missing"
+                )
+            # Otherwise ignore (likely prose token or matcher noise).
+
+if failures:
+    print(f"FAIL: task-router vs agents drift ({len(failures)} issue(s) / {checks} checks):")
+    for f in failures[:30]:
+        print(f"  - {f}")
+    if len(failures) > 30:
+        print(f"  ... and {len(failures) - 30} more")
+    sys.exit(1)
+
+print(f"OK: task-router.md intent rows match agents/*.md ({checks} checks across {len(PLATFORMS) * len(STACKS)} (platform, stack) pairs)")
+sys.exit(0)
+PY