@bonesofspring/ai-rules 0.2.20 → 0.2.22

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

@@ -16,7 +16,71 @@ 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")
-BODY_CAP = 140
+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*")
@@ -70,7 +134,7 @@ failed = 0
 
 print("Preset token / session-start budget (Option A)")
 print(f"Presets: {presets}")
-print(f"Body line cap (trio sum): {BODY_CAP}")
+print(f"Body line cap (Claude trio): {BODY_CAP}; (Cursor 4-set): {BODY_CAP_CURSOR_4}")
 print()
 
 for stack in STACKS:
@@ -87,9 +151,15 @@ for stack in STACKS:
             print(f"FAIL: meta preset-* must not be alwaysApply: {p.name}")
             failed += 1
 
-    if len(always) != 3:
-        print(f"FAIL: Cursor alwaysApply count is {len(always)}, expected exactly 3")
+    if len(always) not in (3, 4):
+        print(f"FAIL: Cursor alwaysApply count is {len(always)}, expected 3 or 4 (4th slot reserved for ai-local-overlay)")
         failed += 1
+    elif len(always) == 4:
+        # 4-set: ensure the 4th rule is ai-local-overlay (or declares itself as such).
+        extra = [p for p in always if p.stem not in {"code-quality-and-refactoring", "package-manager", "next-app-core", "nuxt-app-core", "svelte-app-core", "ios-app-core", "android-app-core", "go-app-core", "java-app-core", "mcp-ts-app-core", "php-app-core", "laravel-app-core", "architecture-boundaries", "mcp-server-boundaries"}]
+        if not any(p.stem == "ai-local-overlay" for p in always) and extra:
+            print(f"FAIL: Cursor alwaysApply=4 but no ai-local-overlay.mdc; the 4th slot is reserved for the local overlay rule")
+            failed += 1
 
     # --- Claude no-paths (excl README) ---
     session = claude_session_start(claude_rules)
@@ -108,10 +178,12 @@ for stack in STACKS:
         )
         failed += 1
 
-    # --- Body sum of intended trio (Cursor alwaysApply + Claude session) ---
-    # Prefer Cursor trio for budget; also check Claude trio independently.
+    # --- Body sum of intended session-start set (Cursor alwaysApply + Claude session) ---
+    # Cursor allows 3 or 4 rules (4th slot reserved for ai-local-overlay); Claude is exactly 3.
     for label, files in (("Cursor", always), ("Claude", session)):
-        if len(files) != 3:
+        if label == "Cursor" and len(files) not in (3, 4):
+            continue
+        if label == "Claude" and len(files) != 3:
             continue
         total = 0
         for path in files:
@@ -121,13 +193,51 @@ for stack in STACKS:
             total += n
             name = path.name if label == "Cursor" else path.relative_to(claude_rules).as_posix()
             print(f"  {label} body lines {name}: {n}")
-        print(f"  {label} trio body sum: {total}")
-        if total > BODY_CAP:
+        cap = BODY_CAP_CURSOR_4 if label == "Cursor" and len(always) == 4 else BODY_CAP
+        print(f"  {label} session-start body sum: {total} (cap {cap}, files={len(files)})")
+        if total > cap:
             print(
-                f"FAIL: {label} session-start body sum {total} > {BODY_CAP} ({stack})"
+                f"FAIL: {label} session-start body sum {total} > {cap} ({stack})"
             )
             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-rule-eval.mjs

@@ -99,6 +99,22 @@ function checkFile(relPath, minPairs, requireImpact) {
       ) && ok;
   }
 
+  // Order check: each Incorrect heading must precede its matching Correct heading.
+  // Without this, an agent reading the rule may learn a "correct" pattern before
+  // seeing the "incorrect" example it contrasts with.
+  if (incorrectCount > 0 && correctCount > 0) {
+    const incRe = /^#{2,3}\s+Incorrect\s*$/gim;
+    const corRe = /^#{2,3}\s+Correct\s*$/gim;
+    const firstInc = text.search(incRe);
+    const firstCor = text.search(corRe);
+    if (firstInc >= 0 && firstCor >= 0 && firstInc >= firstCor) {
+      ok =
+        fail(
+          `${relPath}: first "Incorrect" heading (offset ${firstInc}) must precede first "Correct" heading (offset ${firstCor})`,
+        ) && ok;
+    }
+  }
+
   const incorrectBodies = sectionBodies(text, 'Incorrect');
   const correctBodies = sectionBodies(text, 'Correct');
   for (let i = 0; i < Math.min(incorrectBodies.length, correctBodies.length); i++) {

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

@@ -7,48 +7,26 @@ set -euo pipefail
 ROOT="$(cd "$(dirname "$0")/../../.." && pwd)"
 export AI_RULES_PRESETS_ROOT="$ROOT/packages/ai-rules/presets"
 
-python3 <<'PY'
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+EMBED_LIST_FILE="$SCRIPT_DIR/_lib/embed-stems.json"
+
+python3 - "$EMBED_LIST_FILE" <<'PY'
 from __future__ import annotations
 
+import json
 import os
 import re
 import sys
 from pathlib import Path
 
+embed_list_file = Path(sys.argv[1])
+_stems = json.loads(embed_list_file.read_text(encoding="utf-8"))
+EMBED = _stems["embed"]
+LINEAGE = _stems["lineage"]
+
 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",
-    # Whole-file embed: skill debug-investigation = core + ## Stack notes only.
-    "quality/debug-investigation.md",
-]
-
-LINEAGE = [
-    "architecture/feature-delivery-workflow.md",
-    "architecture/reference-features.template.md",
-    "agent-team/agent-team-orchestrator.md",
-    # Section snippets in fat agents/skills — body is not the whole file.
-    "quality/verification-before-completion.md",
-    "review/receiving-code-review.md",
-    "agent-team/task-classification.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*$")
 

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

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

@@ -13,18 +13,35 @@ import path from 'node:path';
 
 function parseArgs(argv) {
   const options = { cwd: process.cwd(), platform: 'cursor', slug: null };
+  // Read the next token from argv for value-taking flags. Returns the value or null
+  // when the flag is missing its value; the caller exits with a friendly error.
+  function nextValue(flag, i) {
+    const next = argv[i + 1];
+    if (next === undefined || next.startsWith('-')) {
+      console.error(`Missing value for ${flag} (use ${flag} <value>)`);
+      process.exit(2);
+    }
+    return next;
+  }
   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') {
+    if (arg === '--cwd') {
+      options.cwd = path.resolve(nextValue(arg, i));
+      i += 1;
+    } else if (arg === '--platform') {
+      options.platform = nextValue(arg, i);
+      i += 1;
+    } else if (arg === '--slug') {
+      options.slug = nextValue(arg, i);
+      i += 1;
+    } 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]);
+      const teamRoot = path.resolve(nextValue(arg, i));
       options.cwd = path.resolve(teamRoot, '..', '..');
       options.platform = path.basename(path.dirname(teamRoot)) === '.claude' ? 'claude' : 'cursor';
+      i += 1;
     } else {
       console.error(`Unknown argument: ${arg}`);
       process.exit(2);

package/scripts/sync-shared-core-embeds.sh

@@ -8,35 +8,24 @@ set -euo pipefail
 ROOT="$(cd "$(dirname "$0")/../../.." && pwd)"
 export AI_RULES_PRESETS_ROOT="$ROOT/packages/ai-rules/presets"
 
-python3 <<'PY'
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+EMBED_LIST_FILE="$SCRIPT_DIR/_lib/embed-stems.json"
+
+python3 - "$EMBED_LIST_FILE" <<'PY'
 from __future__ import annotations
 
+import json
 import os
 import re
+import sys
 from pathlib import Path
 
+embed_list_file = Path(sys.argv[1])
+EMBED = json.loads(embed_list_file.read_text(encoding="utf-8"))["embed"]
+
 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",
-]
-
 MARKER_LINE_RE = re.compile(r"^<!--\s*shared-core:\s*([^>]+?)\s*-->\s*$")
 
 

package/scripts/test-agent-task-metrics-hooks.mjs

@@ -14,7 +14,7 @@ const hooks = [
   ...fs.readdirSync(path.join(presetsDirectory, 'claude')).map((stack) => path.join(presetsDirectory, 'claude', stack, 'hooks', 'chain-team-phases.sh')),
 ];
 
-assert.equal(hooks.length, 14, 'expected every packaged Cursor and Claude hook');
+assert.equal(hooks.length, 20, 'expected every packaged Cursor and Claude hook (10 stacks × 2 platforms)');
 
 function readJson(filePath) {
   return JSON.parse(fs.readFileSync(filePath, 'utf8'));
@@ -892,4 +892,102 @@ for (const hook of hooks) {
   }
 }
 
-console.log(`Verified retry, parallel, skip, gate, manifest-reconcile, and aggregation lifecycle in ${hooks.length} hooks.`);
+// ---------------------------------------------------------------------------
+// Test — OD-1: parallel-stop lock race. The hook's waitForMetricsLock must
+// actually block a second writer when the lock file is held. We pre-acquire
+// `metrics.json.lock` (fs.openSync(_, 'wx') — same primitive the hook uses)
+// in the test, then invoke the hook concurrently; the hook must NOT acquire
+// the lock until the test releases it. Without the real lock primitive the
+// hook would race through, run the metrics write, and leave a corrupt ledger.
+// ---------------------------------------------------------------------------
+for (const hook of hooks) {
+  const root = fs.mkdtempSync(path.join(packageDirectory, '.agent-task-metrics-lock-race-'));
+  try {
+    const platform = hook.includes(`${path.sep}cursor${path.sep}`) ? 'cursor' : 'claude';
+    const runId = 'lock-race-run';
+    const attemptId = `${runId}:step-0:feature-developer:attempt-1`;
+    const taskDirectory = writeTask(
+      root,
+      hook,
+      'lock-race',
+      { autoChain: true, steps: [{ agent: 'feature-developer' }] },
+      {
+        slug: 'lock-race',
+        intent: 'feature',
+        pipelineIndex: 0,
+        currentAgent: 'feature-developer',
+        phase: 'executing',
+        state: 'completed',
+        activeAttempts: {
+          [attemptId]: {
+            agent: 'feature-developer',
+            stepIndex: 0,
+            attempt: 1,
+            startedAt: '2026-01-01T00:00:00.000Z',
+            parallelGroupId: null,
+          },
+        },
+        metricsRunId: runId,
+      },
+      {
+        schemaVersion: 1,
+        task: { runId, slug: 'lock-race', preset: 'ai-rules', stack: 'test', platform, intent: 'feature', profile: 'test' },
+        events: [
+          { eventId: `${runId}:task_started`, type: 'task_started', at: '2026-01-01T00:00:00.000Z' },
+          { eventId: `${runId}:start`, type: 'attempt_started', attemptId, agent: 'feature-developer', stepIndex: 0, attempt: 1, at: '2026-01-01T00:00:00.000Z' },
+        ],
+      },
+    );
+    const metricsPath = path.join(taskDirectory, 'metrics.json');
+    const lockPath = `${metricsPath}.lock`;
+
+    // Pre-acquire the lock the same way the hook does (fs.openSync 'wx').
+    const holderFd = fs.openSync(lockPath, 'wx');
+
+    // Spawn the hook while the lock is held. The hook must wait.
+    const child = spawn('bash', [hook], { cwd: root, stdio: ['pipe', 'pipe', 'pipe'] });
+    let stderr = '';
+    let stdout = '';
+    child.stderr.setEncoding('utf8');
+    child.stdout.setEncoding('utf8');
+    child.stderr.on('data', (chunk) => { stderr += chunk; });
+    child.stdout.on('data', (chunk) => { stdout += chunk; });
+    child.stdin.end(JSON.stringify({ status: 'completed', attemptId }));
+
+    // Give the child time to enter waitForMetricsLock and hit the EEXIST retry path.
+    const holdMs = 60;
+    await new Promise((resolve) => setTimeout(resolve, holdMs));
+    assert.ok(
+      child.exitCode === null,
+      `${hook}: hook exited prematurely while lock was held (stdout=${stdout.slice(0, 200)} stderr=${stderr.slice(0, 200)})`,
+    );
+
+    // Release the lock — child should now proceed.
+    const releaseAt = Date.now();
+    fs.closeSync(holderFd);
+    fs.unlinkSync(lockPath);
+
+    const exitCode = await new Promise((resolve, reject) => {
+      child.on('error', reject);
+      child.on('close', resolve);
+    });
+    const elapsed = Date.now() - releaseAt;
+    assert.equal(exitCode, 0, `${hook}: hook did not exit 0 after lock release (stderr=${stderr.slice(0, 400)})`);
+
+    // The hook's waitForMetricsLock busy-waits on EEXIST in 10 ms slices; with a
+    // 60 ms hold the child should have been blocked for >= holdMs and run to
+    // completion in well under the 2 s ceiling. Both assertions guard against
+    // regressions to the fake Atomics.wait impl (which never blocked).
+    assert.ok(elapsed >= 1, `${hook}: hook finished suspiciously fast after lock release (${elapsed} ms)`);
+    assert.ok(elapsed < 1500, `${hook}: hook took ${elapsed} ms after lock release — lock impl may be stuck`);
+    const ledger = readJson(metricsPath);
+    const finished = ledger.events.find(
+      (event) => event.type === 'attempt_finished' && event.attemptId === attemptId,
+    );
+    assert.ok(finished, `${hook}: lock-race did not emit attempt_finished; ledger=${JSON.stringify(ledger.events.map((e) => e.type))}`);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+}
+
+console.log(`Verified retry, parallel, skip, gate, manifest-reconcile, lock-race, and aggregation lifecycle in ${hooks.length} hooks.`);