@bonesofspring/ai-rules 0.2.21 → 0.2.22

package/presets/claude/next/skills/unit-testing/SKILL.md

@@ -1,13 +1,15 @@
 ---
 name: unit-testing
-description: Plans, generates, and heals unit tests for mappers, thunks, HTTP client behavior, and React components using colocated *.spec.ts files and tests-unit rules. Use for unit test planning, generation, or fixing failing unit tests.
+description: Plans, generates, and heals unit tests for mappers, thunks, HTTP client behavior, and React components using mirrored paths under app/__tests__/unit and tests-unit rules. Use for unit test planning, generation, or fixing failing unit tests.
 ---
 
 # Unit Testing
 
 ## Project Layout
 
-- Specs colocated with source: `*.spec.ts` / `*.spec.tsx` next to the module under test.
+- Test root: `app/__tests__/unit`.
+- Mirror formula: `app/src/<rel>` → `app/__tests__/unit/<rel>` (drop `app/src`, preserve the relative path).
+- Place specs at the deepest mirrored folder of the module under test; do not colocate tests under `app/src/**`.
 - Legacy `*.test.ts` / `*.test.tsx` — do not rename without a separate task.
 - Runner: Jest or Vitest as configured in the target repo; components use `@testing-library/react`.
 
@@ -17,11 +19,11 @@ Follow **`rules/testing/tests-unit.md`**.
 
 Write or update `.claude/team/tasks/<slug>/unit-test-plan.md`.
 
-Each scenario needs a Russian `it()` title (capital letter after each sentence). Cover mappers, thunks, client behavior branches, and component interactions per AC.
+Each scenario needs a Russian `it()` title (capital letter after each sentence). Cover mappers, thunks, client behavior branches, and component interactions per AC. Record the mirrored target path under `app/__tests__/unit/`.
 
 ## Generator
 
-Implement specs from `unit-test-plan.md`. Reuse project test-store, HTTP mocks, and existing test utilities. Do not change production code.
+Implement specs from `unit-test-plan.md` under the mirrored `app/__tests__/unit/` path. Import the source under test through the `@/` alias. Reuse project test-store, HTTP mocks, and existing test utilities. Do not change production code.
 
 ## Healer
 

package/presets/claude/nuxt/agents/build-verifier.md

@@ -96,6 +96,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 `.claude/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/claude/nuxt/agents/code-reviewer.md

@@ -54,6 +54,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/claude/nuxt/agents/debugger.md

@@ -80,3 +80,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/claude/nuxt/agents/feature-developer.md

@@ -12,6 +12,7 @@ You are a senior frontend developer working in a Nuxt 3 monorepo with strict lay
 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
 
@@ -39,6 +40,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/claude/nuxt/agents/qa-tester.md

@@ -52,3 +52,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/claude/nuxt/hooks/chain-team-phases.sh

@@ -64,10 +64,20 @@ const STACK = 'nuxt';
 const PLATFORM = 'claude';
 
 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 })); }
@@ -483,7 +493,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;
@@ -522,11 +544,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/claude/nuxt/rules/tooling-and-review/preset-twin-sync.md

@@ -36,7 +36,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/claude/php-hexagonal/agents/build-verifier.md

@@ -65,3 +65,7 @@ Document PASS/FAIL in `validation-report.md`.
 
 13. **Product-specs assets (FAIL):** package must ship `presets/_shared/assets/docs-specs/INDEX.md`, `_templates/page.md`, `_templates/feature.md`. Cursor+Claude twins for `product-specs` and `product-specs-authoring` must embed matching shared-core markers; both stems **requestable** (`alwaysApply: false` / Claude `paths: docs/specs/**`) — never session-start.
 14. **Optional consumer check (WARN default):** `scripts/check-product-specs.sh` + schema stub may exist for opt-in consumer CI; **FAIL** only with `--strict` or AC that requires named specs — do not force consumer CI.
+
+## 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/claude/php-hexagonal/agents/code-reviewer.md

@@ -49,3 +49,7 @@ Write `.claude/team/tasks/<slug>/review.md` with verdict APPROVE | REQUEST_CHANG
 - **Owned outputs:** `review.md`; upsert only the manifest entry assigned by handoff (`artifactOutputId`; fallback `review`) and preserve all foreign entries.
 - **Terminal receipt:** cover applicable AC/task IDs, list authoritative evidence paths, and emit `completed` or `changes_requested`. Bind it to the supplied `attemptId` when present.
 - **Shared state:** never create or mutate `status.json` or `metrics.json`; the orchestration runtime/hook owns lifecycle, gates, retries, attempts, and timestamps.
+
+## 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/claude/php-hexagonal/agents/debugger.md

@@ -42,3 +42,7 @@ If a Sentry/Datadog (or similar) MCP is ready and the task is a production error
 
 - 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/claude/php-hexagonal/agents/feature-developer.md

@@ -11,6 +11,7 @@ Implement PHP features following hexagonal boundaries.
 1. Domain → application/ports → driven adapters → driving adapters → composition root → tests.
 2. Read `feature-delivery-workflow.mdc`, `architecture-boundaries.mdc`, layer globs.
 3. After `*.php` edits: invoke `post-change-test.mdc` (+ `php-tooling.mdc`).
+4. **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, 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.
 
 ## Do / Don't
 
@@ -89,3 +90,7 @@ Load requestable rule `mcp-usage` when verifying third-party library APIs (Conte
 - **Owned outputs:** `implementation.md` plus changed implementation/test paths; upsert only the manifest entry assigned by handoff (`artifactOutputId`; fallback `implementation`) and preserve all foreign entries.
 - **Terminal receipt:** cover applicable AC/task IDs, list authoritative evidence paths, and emit `completed` or `blocked`. Bind it to the supplied `attemptId` when present.
 - **Shared state:** never create or mutate `status.json` or `metrics.json`; the orchestration runtime/hook owns lifecycle, gates, retries, attempts, and timestamps.
+
+## 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/claude/php-hexagonal/agents/qa-tester.md

@@ -22,3 +22,7 @@ Coordinate with existing plans under `.claude/team/tasks/<slug>/`.
 ## 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/claude/php-hexagonal/agents/task-router.md

@@ -74,6 +74,10 @@ Keep top-level `profile` and emit this top-level object in every new `pipeline.j
 - Use concrete flags: `public-contract`, `cross-layer`, `security-sensitive`, `migration`, `destructive`, `concurrency-state`, `external-dependency`, `unclear-acceptance-criteria`, `broad-test-surface`, `behavior-regression`.
 - `routingReasons` must be non-empty and explain profile, gates, specialists, skips, or checkpoints; never write “standard by default.”
 - `estimatedWorkPackages` is an integer ≥1; `openDecisionCount` is an integer ≥0. Do not lower complexity because implementation is familiar.
+- Add **api-contract-reviewer** for new/changed backend contracts — before developer.
+- Add **accessibility-reviewer** / **security-reviewer** after build-verifier (parallel when both apply).
+- Add **tech-writer** when docs/changelog requested.
+
 
 ## Model tiers (`steps[].model`)
 

package/presets/claude/php-hexagonal/hooks/chain-team-phases.sh

@@ -66,10 +66,20 @@ const STACK = 'php-hexagonal';
 const PLATFORM = 'claude';
 
 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/claude/php-hexagonal/rules/tooling-and-review/preset-twin-sync.md

@@ -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/claude/php-laravel/agents/build-verifier.md

@@ -65,3 +65,7 @@ Document PASS/FAIL in `validation-report.md`.
 
 13. **Product-specs assets (FAIL):** package must ship `presets/_shared/assets/docs-specs/INDEX.md`, `_templates/page.md`, `_templates/feature.md`. Cursor+Claude twins for `product-specs` and `product-specs-authoring` must embed matching shared-core markers; both stems **requestable** (`alwaysApply: false` / Claude `paths: docs/specs/**`) — never session-start.
 14. **Optional consumer check (WARN default):** `scripts/check-product-specs.sh` + schema stub may exist for opt-in consumer CI; **FAIL** only with `--strict` or AC that requires named specs — do not force consumer CI.
+
+## 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/claude/php-laravel/agents/code-reviewer.md

@@ -49,3 +49,7 @@ Write `.claude/team/tasks/<slug>/review.md` with verdict APPROVE | REQUEST_CHANG
 - **Owned outputs:** `review.md`; upsert only the manifest entry assigned by handoff (`artifactOutputId`; fallback `review`) and preserve all foreign entries.
 - **Terminal receipt:** cover applicable AC/task IDs, list authoritative evidence paths, and emit `completed` or `changes_requested`. Bind it to the supplied `attemptId` when present.
 - **Shared state:** never create or mutate `status.json` or `metrics.json`; the orchestration runtime/hook owns lifecycle, gates, retries, attempts, and timestamps.
+
+## 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/claude/php-laravel/agents/debugger.md

@@ -42,3 +42,7 @@ If a Sentry/Datadog (or similar) MCP is ready and the task is a production error
 
 - 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/claude/php-laravel/agents/feature-developer.md

@@ -11,6 +11,7 @@ Implement Laravel features following Laravel-first layer boundaries.
 1. Routes → Form Request / Policy → Action/Service → Eloquent → Controller/Resource → optional Job/Event → tests.
 2. Read `feature-delivery-workflow.mdc`, `architecture-boundaries.mdc`, layer globs.
 3. After `*.php` edits: invoke `post-change-test.mdc` (+ `php-tooling.mdc`) → `php artisan test` / `composer test`.
+4. **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, 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.
 
 ## Do / Don't
 
@@ -89,3 +90,7 @@ Load requestable rule `mcp-usage` when verifying third-party library APIs (Conte
 - **Owned outputs:** `implementation.md` plus changed implementation/test paths; upsert only the manifest entry assigned by handoff (`artifactOutputId`; fallback `implementation`) and preserve all foreign entries.
 - **Terminal receipt:** cover applicable AC/task IDs, list authoritative evidence paths, and emit `completed` or `blocked`. Bind it to the supplied `attemptId` when present.
 - **Shared state:** never create or mutate `status.json` or `metrics.json`; the orchestration runtime/hook owns lifecycle, gates, retries, attempts, and timestamps.
+
+## 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/claude/php-laravel/agents/qa-tester.md

@@ -28,3 +28,7 @@ Coordinate with existing plans under `.claude/team/tasks/<slug>/`.
 ## 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/claude/php-laravel/agents/task-router.md

@@ -93,6 +93,7 @@ Keep top-level `profile` and emit this top-level object in every new `pipeline.j
 - Use concrete flags: `public-contract`, `cross-layer`, `security-sensitive`, `migration`, `destructive`, `concurrency-state`, `external-dependency`, `unclear-acceptance-criteria`, `broad-test-surface`, `behavior-regression`.
 - `routingReasons` must be non-empty and explain profile, gates, specialists, skips, or checkpoints; never write “standard by default.”
 - `estimatedWorkPackages` is an integer ≥1; `openDecisionCount` is an integer ≥0. Do not lower complexity because implementation is familiar.
+- Add **api-contract-reviewer** for new/changed backend contracts — before developer.
 
 ## Model tiers (`steps[].model`)
 

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

@@ -66,10 +66,20 @@ const STACK = 'php-laravel';
 const PLATFORM = 'claude';
 
 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/claude/php-laravel/rules/tooling-and-review/preset-twin-sync.md

@@ -38,7 +38,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/claude/svelte/agents/build-verifier.md

@@ -96,6 +96,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 `.claude/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/claude/svelte/agents/code-reviewer.md

@@ -54,6 +54,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/claude/svelte/agents/debugger.md

@@ -80,3 +80,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/claude/svelte/agents/feature-developer.md

@@ -12,6 +12,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
 
@@ -39,6 +40,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/claude/svelte/agents/qa-tester.md

@@ -52,3 +52,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 -->