@bonesofspring/ai-rules 0.2.20 → 0.2.21

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

@@ -16,7 +16,8 @@ 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)
 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 +71,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 +88,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 +115,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,10 +130,11 @@ 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
 

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/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'));

package/scripts/test-chain-team-phases-coverage.mjs

@@ -0,0 +1,411 @@
+#!/usr/bin/env node
+// Targeted tests for chain-team-phases.sh fixes that prevent `/task` pipelines
+// from silently skipping or stalling on modern roles.
+//
+// Coverage:
+//   1. openspec-author handoff path: the AGENT_HANDOFF['openspec-author']
+//      entry must be emitted so the orchestrator invokes the agent; the
+//      DEFAULT_ARTIFACT_OUTPUT_IDS['openspec-author'] entry must match the
+//      manifest's `openspec-change` receipt so the hook advances instead of
+//      stalling in `awaiting_artifact_receipt`.
+//   2. QA / unit / playwright / instrumentation / integration / xcuitest
+//      agents must have both AGENT_HANDOFF and DEFAULT_ARTIFACT_OUTPUT_IDS
+//      entries (the symmetric check is in check-chain-hook-coverage.sh; here
+//      we drive a full pipeline step to make sure receipts reconcile).
+//   3. Pipeline.json parse error: a malformed pipeline.json that still
+//      carries an `intent` field must NOT fall through to legacyFlow; the
+//      hook must write `state: blocked` and emit a followup_message that
+//      mentions `pipeline.json` so the orchestrator surfaces the error.
+//   4. Legacy flow fallback: a missing pipeline.json must still invoke
+//      legacyFlow() (analysis → development → review → testing chain).
+//   5. writeStatus durability: status.json must be durable (fsync) before the
+//      hook returns. We assert that a second reader immediately after the
+//      hook returns sees the new state.
+
+import assert from 'node:assert/strict';
+import { execFileSync, spawn } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const scriptDirectory = path.dirname(fileURLToPath(import.meta.url));
+const packageDirectory = path.resolve(scriptDirectory, '..');
+const presetsDirectory = path.join(packageDirectory, 'presets');
+
+const hooks = [
+  ...fs.readdirSync(path.join(presetsDirectory, 'cursor')).map((stack) => path.join(presetsDirectory, 'cursor', stack, 'hooks', 'chain-team-phases.sh')),
+  ...fs.readdirSync(path.join(presetsDirectory, 'claude')).map((stack) => path.join(presetsDirectory, 'claude', stack, 'hooks', 'chain-team-phases.sh')),
+];
+
+assert.equal(hooks.length, 20, `expected 20 packaged hooks (10 stacks × 2 platforms), got ${hooks.length}`);
+
+// mcp-ts does not ship openspec-author (per preset-no-cross-stack-leakage).
+const HOOKS_WITH_OPENSPEC = hooks.filter((hook) => !hook.includes(`${path.sep}mcp-ts${path.sep}`));
+assert.equal(HOOKS_WITH_OPENSPEC.length, 18, 'expected 18 hooks to cover openspec-author');
+
+function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+
+function writeJson(filePath, value) {
+  fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+function invokeHook(hook, workingDirectory, attemptId, payload = {}) {
+  return execFileSync('bash', [hook], {
+    cwd: workingDirectory,
+    encoding: 'utf8',
+    input: JSON.stringify({ status: 'completed', attemptId, ...payload }),
+  });
+}
+
+function platformFor(hook) {
+  return hook.includes(`${path.sep}cursor${path.sep}`) ? 'cursor' : 'claude';
+}
+
+function writeTask(root, hook, slug, pipeline, status, metrics, artifacts = {}) {
+  const platform = platformFor(hook);
+  const teamRoot = path.join(root, `.${platform}`, 'team');
+  const taskDirectory = path.join(teamRoot, 'tasks', slug);
+  fs.mkdirSync(taskDirectory, { recursive: true });
+  writeJson(path.join(teamRoot, 'active-task.json'), { slug });
+  writeJson(path.join(taskDirectory, 'pipeline.json'), pipeline);
+  writeJson(path.join(taskDirectory, 'status.json'), status);
+  writeJson(path.join(taskDirectory, 'metrics.json'), metrics);
+  for (const [name, content] of Object.entries(artifacts)) {
+    fs.writeFileSync(path.join(taskDirectory, name), content);
+  }
+  return { taskDirectory, platform };
+}
+
+const todayIso = '2026-08-21T00:00:00.000Z';
+const earlierIso = '2026-08-21T00:00:01.000Z';
+
+// ---------------------------------------------------------------------------
+// Test 1 — openspec-author handoff: the hook must emit a followup_message that
+// references openspec-author and the openspec-change scope, and the default
+// artifact id must match the manifest receipt for `state` to advance.
+// ---------------------------------------------------------------------------
+for (const hook of HOOKS_WITH_OPENSPEC) {
+  const root = fs.mkdtempSync(path.join(packageDirectory, '.openspec-handoff-'));
+  try {
+    const runId = 'openspec-handoff-run';
+    const platform = platformFor(hook);
+    const analystAttemptId = `${runId}:step-0:task-analyst:attempt-1`;
+    const { taskDirectory } = writeTask(
+      root,
+      hook,
+      'openspec-handoff',
+      {
+        intent: 'openspec-change',
+        profile: 'standard',
+        steps: [
+          { agent: 'task-analyst', label: 'Analyze' },
+          { agent: 'openspec-author', label: 'Author spec change', scope: 'openspec:MEDCARD-11762' },
+        ],
+        humanGates: [],
+      },
+      {
+        slug: 'openspec-handoff',
+        intent: 'openspec-change',
+        pipelineIndex: 0,
+        currentAgent: 'task-analyst',
+        phase: 'executing',
+        state: 'completed',
+        activeAttempts: {
+          [analystAttemptId]: {
+            agent: 'task-analyst',
+            stepIndex: 0,
+            attempt: 1,
+            startedAt: todayIso,
+            parallelGroupId: null,
+          },
+        },
+        metricsRunId: runId,
+      },
+      {
+        schemaVersion: 1,
+        task: { runId, slug: 'openspec-handoff', preset: 'ai-rules', stack: 'test', platform, intent: 'openspec-change', profile: 'standard' },
+        events: [
+          { eventId: `${runId}:task_started`, type: 'task_started', at: todayIso },
+          { eventId: `${runId}:analyst-start`, type: 'attempt_started', attemptId: analystAttemptId, agent: 'task-analyst', stepIndex: 0, attempt: 1, at: todayIso },
+        ],
+      },
+    );
+
+    const handoffRaw = invokeHook(hook, root, analystAttemptId);
+    const handoff = JSON.parse(handoffRaw).followup_message;
+    assert.match(handoff, /openspec-author/, `${hook}: handoff did not mention openspec-author`);
+    assert.match(handoff, /openspec:MEDCARD-11762/, `${hook}: handoff did not echo the openspec scope`);
+
+    const statusAfter = readJson(path.join(taskDirectory, 'status.json'));
+    assert.equal(statusAfter.pipelineIndex, 1, `${hook}: hook did not advance past the analyst step`);
+    assert.equal(statusAfter.currentAgent, 'openspec-author', `${hook}: next agent was not openspec-author`);
+    const activeAttempts = Object.values(statusAfter.activeAttempts || {});
+    assert.ok(activeAttempts.some((entry) => entry.agent === 'openspec-author'), `${hook}: openspec-author attempt was not activated`);
+
+    // Now finish the openspec-author attempt with a properly bound receipt
+    // (id: openspec-change) and assert the hook advances to the next step.
+    const openspecAttempt = Object.entries(statusAfter.activeAttempts).find(([, entry]) => entry.agent === 'openspec-author');
+    const openspecAttemptId = openspecAttempt[0];
+    // Use a timestamp after the attempt's actual startedAt — the hook filters
+    // out manifest receipts whose completedAt predates the attempt's start.
+    const freshIso = new Date().toISOString();
+    fs.writeFileSync(
+      path.join(taskDirectory, 'artifact-manifest.json'),
+      JSON.stringify(
+        {
+          schemaVersion: 1,
+          slug: 'openspec-handoff',
+          updatedAt: freshIso,
+          artifacts: [
+            {
+              id: 'openspec-change',
+              producer: 'openspec-author',
+              status: 'completed',
+              authoritativePaths: ['openspec/changes/MEDCARD-11762/proposal.md'],
+              acceptanceCriteriaIds: ['AC-1'],
+              taskIds: ['T1'],
+              timestamps: { createdAt: freshIso, updatedAt: freshIso, completedAt: freshIso },
+              receipt: {
+                outcome: 'completed',
+                attemptId: openspecAttemptId,
+                summary: 'Proposal + design + tasks emitted; openspec validate --strict PASS',
+                evidencePaths: ['openspec/changes/MEDCARD-11762/proposal.md'],
+              },
+            },
+          ],
+        },
+        null,
+        2,
+      ) + '\n',
+    );
+    writeJson(path.join(taskDirectory, 'status.json'), { ...statusAfter, state: 'completed' });
+    const finishRaw = invokeHook(hook, root, openspecAttemptId);
+    const finishHandoff = JSON.parse(finishRaw).followup_message;
+    assert.match(finishHandoff, /Pipeline complete/, `${hook}: pipeline should complete after openspec-author finishes`);
+    const finalStatus = readJson(path.join(taskDirectory, 'status.json'));
+    assert.equal(finalStatus.phase, 'done', `${hook}: phase did not transition to done`);
+    assert.equal(finalStatus.state, 'completed', `${hook}: state did not reach completed after openspec-author`);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Test 2 — qa-tester + unit-test-* handoff: a QA step in a pipeline must
+// advance. Before the fix, DEFAULT_ARTIFACT_OUTPUT_IDS lacked the QA entries
+// so `artifactOutputIdFor` returned the agent name itself; manifest receipts
+// landed under the right id (qa / unit-test-spec) and the hook stalled in
+// awaiting_artifact_receipt.
+// ---------------------------------------------------------------------------
+for (const hook of hooks) {
+  const root = fs.mkdtempSync(path.join(packageDirectory, '.qa-tester-handoff-'));
+  try {
+    const platform = platformFor(hook);
+    const runId = 'qa-tester-run';
+    const devAttemptId = `${runId}:step-0:feature-developer:attempt-1`;
+    const { taskDirectory } = writeTask(
+      root,
+      hook,
+      'qa-tester-handoff',
+      {
+        intent: 'test-only',
+        profile: 'standard',
+        steps: [
+          { agent: 'feature-developer', label: 'Implement' },
+          { agent: 'qa-tester', label: 'QA' },
+        ],
+        humanGates: [],
+      },
+      {
+        slug: 'qa-tester-handoff',
+        intent: 'test-only',
+        pipelineIndex: 0,
+        currentAgent: 'feature-developer',
+        phase: 'executing',
+        state: 'completed',
+        activeAttempts: {
+          [devAttemptId]: {
+            agent: 'feature-developer',
+            stepIndex: 0,
+            attempt: 1,
+            startedAt: todayIso,
+            parallelGroupId: null,
+          },
+        },
+        metricsRunId: runId,
+      },
+      {
+        schemaVersion: 1,
+        task: { runId, slug: 'qa-tester-handoff', preset: 'ai-rules', stack: 'test', platform, intent: 'test-only', profile: 'standard' },
+        events: [
+          { eventId: `${runId}:task_started`, type: 'task_started', at: todayIso },
+          { eventId: `${runId}:dev-start`, type: 'attempt_started', attemptId: devAttemptId, agent: 'feature-developer', stepIndex: 0, attempt: 1, at: todayIso },
+        ],
+      },
+    );
+    const handoff = JSON.parse(invokeHook(hook, root, devAttemptId)).followup_message;
+    assert.match(handoff, /qa-tester/, `${hook}: handoff did not mention qa-tester`);
+    const statusAfter = readJson(path.join(taskDirectory, 'status.json'));
+    assert.equal(statusAfter.pipelineIndex, 1, `${hook}: hook did not advance to qa-tester step`);
+    assert.equal(statusAfter.currentAgent, 'qa-tester', `${hook}: currentAgent was not qa-tester`);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Test 3 — pipeline.json parse error with intent: the hook must surface the
+// error and write state: blocked; legacyFlow must NOT be silently used.
+// ---------------------------------------------------------------------------
+for (const hook of hooks) {
+  const root = fs.mkdtempSync(path.join(packageDirectory, '.pipeline-misparse-'));
+  try {
+    const platform = platformFor(hook);
+    const runId = 'misparse-run';
+    const devAttemptId = `${runId}:step-0:feature-developer:attempt-1`;
+    const taskDirectory = path.join(root, `.${platform}`, 'team', 'tasks', 'misparse');
+    fs.mkdirSync(taskDirectory, { recursive: true });
+    fs.writeFileSync(path.join(root, `.${platform}`, 'team', 'active-task.json'), JSON.stringify({ slug: 'misparse' }));
+    // Malformed pipeline.json with `intent` field — must NOT fall back to legacy.
+    fs.writeFileSync(
+      path.join(taskDirectory, 'pipeline.json'),
+      '{ "intent": "openspec-change", "steps": [\n  { "agent": "openspec-author" }\n', // truncated JSON
+    );
+    writeJson(path.join(taskDirectory, 'status.json'), {
+      slug: 'misparse',
+      intent: 'openspec-change',
+      pipelineIndex: 0,
+      currentAgent: 'feature-developer',
+      phase: 'executing',
+      state: 'completed',
+      activeAttempts: {
+        [devAttemptId]: {
+          agent: 'feature-developer',
+          stepIndex: 0,
+          attempt: 1,
+          startedAt: todayIso,
+          parallelGroupId: null,
+        },
+      },
+      metricsRunId: runId,
+    });
+    writeJson(path.join(taskDirectory, 'metrics.json'), {
+      schemaVersion: 1,
+      task: { runId, slug: 'misparse', preset: 'ai-rules', stack: 'test', platform, intent: 'openspec-change', profile: 'standard' },
+      events: [
+        { eventId: `${runId}:task_started`, type: 'task_started', at: todayIso },
+        { eventId: `${runId}:start`, type: 'attempt_started', attemptId: devAttemptId, agent: 'feature-developer', stepIndex: 0, attempt: 1, at: todayIso },
+      ],
+    });
+
+    const raw = invokeHook(hook, root, devAttemptId);
+    const parsed = JSON.parse(raw);
+    const followup = parsed.followup_message || '';
+    assert.match(followup, /pipeline\.json is malformed/, `${hook}: hook did not surface parse error in followup_message (got: ${followup})`);
+    const status = readJson(path.join(taskDirectory, 'status.json'));
+    assert.equal(status.state, 'blocked', `${hook}: malformed pipeline with intent did not block the pipeline (got: ${status.state})`);
+    assert.equal(status.phase, 'blocked', `${hook}: phase did not transition to blocked`);
+    const metrics = readJson(path.join(taskDirectory, 'metrics.json'));
+    assert.ok(
+      metrics.events.some((event) => event.type === 'pipeline_parse_error'),
+      `${hook}: pipeline_parse_error metric event was not emitted`,
+    );
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Test 4 — legacyFlow fallback: when pipeline.json is absent, the hook must
+// continue to use legacyFlow (analysis → development → review → testing).
+// ---------------------------------------------------------------------------
+for (const hook of hooks) {
+  const root = fs.mkdtempSync(path.join(packageDirectory, '.legacy-fallback-'));
+  try {
+    const platform = platformFor(hook);
+    const taskDirectory = path.join(root, `.${platform}`, 'team', 'tasks', 'legacy-slug');
+    fs.mkdirSync(taskDirectory, { recursive: true });
+    fs.writeFileSync(path.join(root, `.${platform}`, 'team', 'active-task.json'), JSON.stringify({ slug: 'legacy-slug' }));
+    // No pipeline.json — legacy flow triggers.
+    writeJson(path.join(taskDirectory, 'status.json'), {
+      slug: 'legacy-slug',
+      intent: 'feature',
+      phase: 'development',
+      state: 'completed',
+      currentAgent: 'feature-developer',
+      pipelineIndex: 0,
+    });
+    const raw = invokeHook(hook, root, null);
+    const parsed = JSON.parse(raw);
+    const followup = parsed.followup_message || '';
+    assert.match(followup, /build-verifier/, `${hook}: legacy fallback did not invoke build-verifier (got: ${followup})`);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Test 5 — writeStatus durability: after the hook returns, the new
+// status.json must already be on disk and reflect the post-step state. This
+// is the property that lets the orchestrator's next read see the human-gate
+// transition (no stale-read race).
+// ---------------------------------------------------------------------------
+for (const hook of HOOKS_WITH_OPENSPEC) {
+  const root = fs.mkdtempSync(path.join(packageDirectory, '.write-status-durability-'));
+  try {
+    const runId = 'durability-run';
+    const platform = platformFor(hook);
+    const analystAttemptId = `${runId}:step-0:task-analyst:attempt-1`;
+    const { taskDirectory } = writeTask(
+      root,
+      hook,
+      'durability-slug',
+      {
+        intent: 'feature',
+        profile: 'standard',
+        steps: [
+          { agent: 'task-analyst', label: 'Analyze' },
+          { agent: 'openspec-author', label: 'Spec change' },
+        ],
+        humanGates: ['after:task-analyst'],
+      },
+      {
+        slug: 'durability-slug',
+        intent: 'feature',
+        pipelineIndex: 0,
+        currentAgent: 'task-analyst',
+        phase: 'executing',
+        state: 'completed',
+        activeAttempts: {
+          [analystAttemptId]: {
+            agent: 'task-analyst',
+            stepIndex: 0,
+            attempt: 1,
+            startedAt: todayIso,
+            parallelGroupId: null,
+          },
+        },
+        metricsRunId: runId,
+      },
+      {
+        schemaVersion: 1,
+        task: { runId, slug: 'durability-slug', preset: 'ai-rules', stack: 'test', platform, intent: 'feature', profile: 'standard' },
+        events: [
+          { eventId: `${runId}:task_started`, type: 'task_started', at: todayIso },
+          { eventId: `${runId}:start`, type: 'attempt_started', attemptId: analystAttemptId, agent: 'task-analyst', stepIndex: 0, attempt: 1, at: todayIso },
+        ],
+      },
+    );
+    // Sync + invoke hook; immediately read status.json without fsync of our own.
+    invokeHook(hook, root, analystAttemptId);
+    const onDisk = JSON.parse(fs.readFileSync(path.join(taskDirectory, 'status.json'), 'utf8'));
+    assert.equal(onDisk.awaitingHumanGate, true, `${hook}: human gate was not durably written to status.json`);
+    assert.equal(onDisk.state, 'awaiting_approval', `${hook}: state did not durably transition to awaiting_approval`);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+}
+
+console.log(`Verified openspec-author handoff, qa-tester handoff, pipeline misparse blocking, legacy fallback, and writeStatus durability in ${hooks.length} hooks.`);