@bonesofspring/ai-rules 0.2.11 → 0.2.12

package/presets/claude/next/hooks/chain-team-phases.sh

@@ -50,6 +50,8 @@ if (!slug) {
 const taskDir = path.join(TEAM_ROOT, 'tasks', slug);
 const statusPath = path.join(taskDir, 'status.json');
 const pipelinePath = path.join(taskDir, 'pipeline.json');
+const METRICS_PATH = path.join(taskDir, 'metrics.json');
+const METRICS_LOCK = `${METRICS_PATH}.lock`;
 
 if (!fs.existsSync(statusPath)) {
   process.stdout.write('{}');
@@ -57,18 +59,119 @@ if (!fs.existsSync(statusPath)) {
 }
 
 let status;
+const now = new Date().toISOString();
+const STACK = 'next';
+const PLATFORM = 'claude';
+
+function waitForMetricsLock() {
+  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);
+    }
+  }
+  throw new Error('metrics lock timeout');
+}
+let taskLockHeld = false;
+function releaseTaskLock() {
+  if (!taskLockHeld) return;
+  taskLockHeld = false;
+  try { fs.rmdirSync(METRICS_LOCK); } catch {}
+}
+waitForMetricsLock();
+taskLockHeld = true;
+process.on('exit', releaseTaskLock);
 try {
   status = JSON.parse(fs.readFileSync(statusPath, 'utf8'));
 } catch {
+  releaseTaskLock();
   process.stdout.write('{}');
   process.exit(0);
 }
+function mutateMetrics(mutator) {
+  const acquiredHere = !taskLockHeld;
+  if (acquiredHere) waitForMetricsLock();
+  try {
+    let metrics;
+    try { metrics = JSON.parse(fs.readFileSync(METRICS_PATH, 'utf8')); } catch {
+      const runId = status.metricsRunId || `${slug}-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+      status.metricsRunId = runId;
+      metrics = { schemaVersion: 1, task: { runId, slug, preset: 'ai-rules', stack: STACK, platform: PLATFORM, intent: status.intent || 'unknown', profile: 'unknown' }, events: [] };
+      metrics.events.push({ eventId: `${runId}:task_started`, type: 'task_started', at: now, source: 'hook', attributionConfidence: 'high' });
+    }
+    mutator(metrics);
+    const temporary = `${METRICS_PATH}.${process.pid}.${Date.now()}.tmp`;
+    fs.writeFileSync(temporary, JSON.stringify(metrics, null, 2) + '\n');
+    fs.renameSync(temporary, METRICS_PATH);
+  } finally {
+    if (acquiredHere) { try { fs.rmdirSync(METRICS_LOCK); } catch {} }
+  }
+}
+function appendMetric(event) { mutateMetrics((metrics) => metrics.events.push({ eventId: `${metrics.task.runId}:${Date.now()}:${Math.random().toString(16).slice(2)}`, ...event })); }
+function nextAttemptOrdinal(stepIndex, agent) {
+  try {
+    const metrics = JSON.parse(fs.readFileSync(METRICS_PATH, 'utf8'));
+    return metrics.events.reduce((highest, event) => event.type === 'attempt_started' && event.stepIndex === stepIndex && event.agent === agent ? Math.max(highest, Number(event.attempt) || 0) : highest, 0) + 1;
+  } catch { return 1; }
+}
+function roleFor(agent) {
+  if (/analyst|architect|router|migration/.test(agent || '')) return 'planning';
+  if (/verifier/.test(agent || '')) return 'validation';
+  if (/reviewer|auditor/.test(agent || '')) return 'review';
+  if (/test|qa/.test(agent || '')) return 'testing';
+  if (/writer/.test(agent || '')) return 'docs';
+  return 'implementation';
+}
+function activateAttempts(step, stepIndex) {
+  const active = { ...(status.activeAttempts || {}) }; const agents = getStepAgents(step);
+  const parallelGroupId = step.parallel && agents.length > 1 ? `${status.metricsRunId || slug}:step-${stepIndex}` : null;
+  for (const agent of agents) {
+    const attempt = nextAttemptOrdinal(stepIndex, agent); const runId = status.metricsRunId || `${slug}-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+    status.metricsRunId = runId; const attemptId = `${runId}:step-${stepIndex}:${agent}:attempt-${attempt}`;
+    if (active[attemptId]) continue;
+    active[attemptId] = { agent, stepIndex, attempt, startedAt: now, parallelGroupId };
+    appendMetric({ type: 'attempt_started', at: now, attemptId, stepIndex, stepLabel: step.label || null, agent, role: roleFor(agent), attempt, parallelGroupId, source: 'hook', attributionConfidence: 'high' });
+  }
+  status.activeAttempts = active;
+}
+function resolvedAttempt() {
+  const active = status.activeAttempts || {}; const entries = Object.entries(active);
+  const stableAttemptId = hookInput.attemptId;
+  if (stableAttemptId) {
+    return active[stableAttemptId] ? { attemptId: stableAttemptId, entry: active[stableAttemptId], confidence: 'high' } : null;
+  }
+  if (entries.length === 1) return { attemptId: entries[0][0], entry: entries[0][1], confidence: 'high' };
+  try { const receipts = JSON.parse(fs.readFileSync(path.join(taskDir, '.metrics-receipts.json'), 'utf8')); const receipt = Array.isArray(receipts) ? receipts.find((item) => active[item.attemptId]) : null; if (receipt) return { attemptId: receipt.attemptId, entry: active[receipt.attemptId], confidence: 'fallback', source: 'agent' }; } catch {}
+  return null;
+}
+function finishActiveAttempt() {
+  const resolved = resolvedAttempt(); if (!resolved) return null;
+  const durationMs = Date.parse(now) - Date.parse(resolved.entry.startedAt);
+  appendMetric({ type: 'attempt_finished', at: now, attemptId: resolved.attemptId, outcome: ['completed', 'changes_requested', 'validation_failed'].includes(status.state) ? status.state : 'unknown', durationMs: Number.isFinite(durationMs) && durationMs >= 0 ? durationMs : null, retryAfterFix: status.retryAfterFix || null, source: resolved.source || 'hook', attributionConfidence: resolved.confidence });
+  const active = { ...(status.activeAttempts || {}) }; delete active[resolved.attemptId]; status.activeAttempts = active; status.lastCompletedAttempt = { attemptId: resolved.attemptId, completedAt: now }; return resolved;
+}
+function beginHumanGate() { const eventId = `${status.metricsRunId || slug}:gate:${Date.now()}`; appendMetric({ eventId, type: 'human_gate_started', at: now, source: 'hook', attributionConfidence: 'high' }); status.activeHumanGateEventId = eventId; }
+function endHumanGateIfResumed() {
+  if (!status.activeHumanGateEventId || status.awaitingHumanGate || status.state === 'awaiting_approval') return;
+  appendMetric({ type: 'human_gate_ended', at: now, gateStartedEventId: status.activeHumanGateEventId, source: 'hook', attributionConfidence: 'high' });
+  delete status.activeHumanGateEventId;
+}
+function completeTaskMetrics() { appendMetric({ type: 'task_completed', at: now, outcome: status.state === 'completed' ? 'completed' : 'unknown', source: 'hook', attributionConfidence: 'high' }); }
+function recordSkippedStep(step, stepIndex) {
+  for (const agent of getStepAgents(step)) {
+    const runId = status.metricsRunId || `${slug}-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+    status.metricsRunId = runId;
+    const attempt = nextAttemptOrdinal(stepIndex, agent);
+    appendMetric({ type: 'attempt_skipped', at: now, attemptId: `${runId}:step-${stepIndex}:${agent}:attempt-${attempt}`, stepIndex, stepLabel: step.label || null, agent, role: roleFor(agent), attempt, outcome: 'skipped', source: 'hook', attributionConfidence: 'high' });
+  }
+}
 
-const now = new Date().toISOString();
 
 function writeStatus(next) {
   status = { ...status, ...next, slug, updatedAt: now };
-  fs.writeFileSync(statusPath, JSON.stringify(status, null, 2) + '\n');
+  const temporary = `${statusPath}.${process.pid}.${Date.now()}.tmp`;
+  fs.writeFileSync(temporary, JSON.stringify(status, null, 2) + '\n');
+  fs.renameSync(temporary, statusPath);
 }
 
 function out(message) {
@@ -105,9 +208,8 @@ function skipIfMatches(skipIf, dir) {
 
 function findNextExecutableStep(steps, startIdx, dir) {
   for (let i = startIdx; i < steps.length; i++) {
-    if (!skipIfMatches(steps[i].skipIf, dir)) {
-      return { step: steps[i], index: i };
-    }
+    if (!skipIfMatches(steps[i].skipIf, dir)) return { step: steps[i], index: i };
+    recordSkippedStep(steps[i], i);
   }
   return null;
 }
@@ -172,16 +274,29 @@ const REVIEW_AGENTS = new Set([
   'api-contract-reviewer',
 ]);
 
+function metricsHandoff(agent) {
+  const matches = Object.entries(status.activeAttempts || {}).filter(([, entry]) => entry.agent === agent);
+  if (matches.length === 1) {
+    return ` Metrics attemptId: ${matches[0][0]}; update normal status only. If the hook cannot identify a parallel stop, append a minimal { attemptId, outcome } receipt to .metrics-receipts.json; do not calculate duration.`;
+  }
+  return ' Metrics: use the supplied attemptId when available; for a parallel completion, write a minimal { attemptId, outcome } receipt to .metrics-receipts.json rather than relying on currentAgent. Do not calculate duration.';
+}
+
 function handoffForAgent(agent, scope) {
   const fn = AGENT_HANDOFF[agent];
-  return fn ? fn(slug, scope) : `Invoke ${agent} subagent for slug "${slug}". Update status.json when done.`;
+  const handoff = fn ? fn(slug, scope) : `Invoke ${agent} subagent for slug "${slug}". Update status.json when done.`;
+  return handoff + metricsHandoff(agent);
 }
 
 function handoffForParallelStep(step) {
   const agents = getStepAgents(step);
+  const attemptIds = Object.entries(status.activeAttempts || {})
+    .filter(([, entry]) => agents.includes(entry.agent))
+    .map(([attemptId, entry]) => `${entry.agent}=${attemptId}`);
   return (
     `Invoke IN PARALLEL (one message, multiple Task calls): ${agents.join(' AND ')} for slug "${slug}". ` +
-    `Each agent writes its artifact and appends itself to status.json parallelCompleted when done.`
+    `Each agent writes its artifact and appends itself to status.json parallelCompleted when done. ` +
+    `Metrics attemptIds: ${attemptIds.join('; ')}. If the hook cannot identify a parallel stop, append a minimal { attemptId, outcome } receipt to .metrics-receipts.json; do not calculate duration.`
   );
 }
 
@@ -213,34 +328,38 @@ function legacyFlow() {
     out(handoffForAgent('qa-tester'));
     process.exit(0);
   }
+  function scheduleLegacyRetry(agent, retryAfterFix) {
+    const stepIndex = typeof status.pipelineIndex === 'number' ? status.pipelineIndex : 0;
+    const predecessorAttemptId = status.lastCompletedAttempt?.attemptId || null;
+    appendMetric({ type: 'retry_scheduled', at: now, attemptId: predecessorAttemptId, nextAgent: agent, retryAfterFix: retryAfterFix || null, source: 'hook', attributionConfidence: 'unknown' });
+    activateAttempts({ agent }, stepIndex);
+  }
   if (status.state === 'changes_requested' && REVIEW_AGENTS.has(status.currentAgent)) {
+    const reviewer = status.currentAgent;
+    scheduleLegacyRetry('feature-developer', reviewer);
     writeStatus({
       currentAgent: 'feature-developer',
       state: 'in_progress',
       phase: 'executing',
-      retryAfterFix: status.currentAgent,
+      retryAfterFix: reviewer,
     });
-    out(
-      handoffForAgent('feature-developer') +
-        ` After fixes, re-run ${status.currentAgent}.`,
-    );
+    out(handoffForAgent('feature-developer') + ` After fixes, re-run ${reviewer}.`);
     process.exit(0);
   }
   if (status.state === 'validation_failed' && status.currentAgent === 'build-verifier') {
+    scheduleLegacyRetry('feature-developer', 'build-verifier');
     writeStatus({
       currentAgent: 'feature-developer',
       state: 'in_progress',
       phase: 'executing',
       retryAfterFix: 'build-verifier',
     });
-    out(
-      handoffForAgent('feature-developer') +
-        ` Read validation-report.md. After fixes, re-run build-verifier.`,
-    );
+    out(handoffForAgent('feature-developer') + ' Read validation-report.md. After fixes, re-run build-verifier.');
     process.exit(0);
   }
   if (status.state === 'completed' && status.retryAfterFix) {
     const retry = status.retryAfterFix;
+    scheduleLegacyRetry(retry, null);
     writeStatus({ currentAgent: retry, state: 'in_progress', retryAfterFix: null });
     out(handoffForAgent(retry));
     process.exit(0);
@@ -254,6 +373,56 @@ function legacyFlow() {
   process.exit(0);
 }
 
+
+if (hookInput.action === 'end_human_gate') {
+  status.awaitingHumanGate = false;
+  if (status.state === 'awaiting_approval') {
+    status.state = 'in_progress';
+    status.phase = status.phase === 'human_gate' ? 'executing' : status.phase;
+  }
+  if (status.activeHumanGateEventId) {
+    appendMetric({
+      type: 'human_gate_ended',
+      at: now,
+      gateStartedEventId: status.activeHumanGateEventId,
+      source: 'orchestrator',
+      attributionConfidence: 'high',
+    });
+    delete status.activeHumanGateEventId;
+  }
+  if (hookInput.activateNext && fs.existsSync(pipelinePath)) {
+    let resumePipeline = null;
+    try { resumePipeline = JSON.parse(fs.readFileSync(pipelinePath, 'utf8')); } catch {}
+    if (resumePipeline) {
+      const resumeSteps = resumePipeline.steps || [];
+      const resumeStart = (typeof status.pipelineIndex === 'number' ? status.pipelineIndex : 0) + 1;
+      const resumeNext = findNextExecutableStep(resumeSteps, resumeStart, taskDir);
+      if (resumeNext) {
+        const resumeAgents = getStepAgents(resumeNext.step);
+        activateAttempts(resumeNext.step, resumeNext.index);
+        writeStatus({
+          pipelineIndex: resumeNext.index,
+          currentAgent: resumeAgents[0],
+          phase: 'executing',
+          state: 'in_progress',
+          awaitingHumanGate: false,
+          parallelCompleted: [],
+        });
+        if (resumeNext.step.parallel && resumeAgents.length > 1) out(handoffForParallelStep(resumeNext.step));
+        else out(handoffForAgent(resumeAgents[0], resumeNext.step.scope));
+        process.exit(0);
+      }
+    }
+  }
+  writeStatus({
+    awaitingHumanGate: false,
+    state: status.state,
+    phase: status.phase,
+  });
+  process.stdout.write(JSON.stringify({ ok: true, action: 'end_human_gate', activeHumanGateEventId: status.activeHumanGateEventId || null }));
+  process.exit(0);
+}
+
 if (!fs.existsSync(pipelinePath)) {
   legacyFlow();
 }
@@ -266,6 +435,15 @@ try {
 }
 
 const steps = pipeline.steps || [];
+const initialIdx = typeof status.pipelineIndex === 'number' ? status.pipelineIndex : 0;
+const initialStep = steps[initialIdx];
+const activeAttemptCountBeforeFinish = Object.keys(status.activeAttempts || {}).length;
+const finishedAttempt = finishActiveAttempt();
+if (!finishedAttempt && (hookInput.attemptId || activeAttemptCountBeforeFinish > 0)) {
+  process.stdout.write('{}');
+  process.exit(0);
+}
+endHumanGateIfResumed();
 if (steps.length === 0 || pipeline.autoChain === false) {
   process.stdout.write('{}');
   process.exit(0);
@@ -276,38 +454,57 @@ if (status.awaitingHumanGate || status.state === 'awaiting_approval') {
   process.exit(0);
 }
 
+function nearestPrecedingStepIndex(agent, fromIndex, fallback) {
+  for (let index = fromIndex - 1; index >= 0; index -= 1) {
+    if (getStepAgents(steps[index]).includes(agent)) return index;
+  }
+  const match = steps.findIndex((step) => getStepAgents(step).includes(agent));
+  return match >= 0 ? match : fallback;
+}
+function scheduleRetry(agent, retryAfterFix, predecessor, explicitStepIndex = null) {
+  const currentIndex = typeof status.pipelineIndex === 'number' ? status.pipelineIndex : 0;
+  const stepIndex = Number.isInteger(explicitStepIndex) ? explicitStepIndex : nearestPrecedingStepIndex(agent, currentIndex, currentIndex);
+  const predecessorAttemptId = predecessor?.attemptId || status.lastCompletedAttempt?.attemptId || null;
+  appendMetric({ type: 'retry_scheduled', at: now, attemptId: predecessorAttemptId, nextAgent: agent, retryAfterFix: retryAfterFix || null, source: 'hook', attributionConfidence: predecessor ? predecessor.confidence : 'unknown' });
+  activateAttempts(steps[stepIndex] || { agent }, stepIndex);
+  return stepIndex;
+}
+
 if (status.state === 'changes_requested' && REVIEW_AGENTS.has(status.currentAgent)) {
   const reviewer = status.currentAgent;
+  const retryAfterFixStepIndex = typeof status.pipelineIndex === 'number' ? status.pipelineIndex : 0;
+  const developerIndex = scheduleRetry('feature-developer', reviewer, finishedAttempt);
   writeStatus({
+    pipelineIndex: developerIndex,
     currentAgent: 'feature-developer',
     state: 'in_progress',
     phase: 'executing',
     retryAfterFix: reviewer,
+    retryAfterFixStepIndex,
   });
-  out(
-    handoffForAgent('feature-developer') +
-      ` After fixes, re-run ${reviewer}.`,
-  );
+  out(handoffForAgent('feature-developer') + ` After fixes, re-run ${reviewer}.`);
   process.exit(0);
 }
 
 if (status.state === 'validation_failed' && status.currentAgent === 'build-verifier') {
+  const retryAfterFixStepIndex = typeof status.pipelineIndex === 'number' ? status.pipelineIndex : 0;
+  const developerIndex = scheduleRetry('feature-developer', 'build-verifier', finishedAttempt);
   writeStatus({
+    pipelineIndex: developerIndex,
     currentAgent: 'feature-developer',
     state: 'in_progress',
     phase: 'executing',
     retryAfterFix: 'build-verifier',
+    retryAfterFixStepIndex,
   });
-  out(
-    handoffForAgent('feature-developer') +
-      ` Read validation-report.md. After fixes, re-run build-verifier.`,
-  );
+  out(handoffForAgent('feature-developer') + ' Read validation-report.md. After fixes, re-run build-verifier.');
   process.exit(0);
 }
 
 if (status.state === 'completed' && status.retryAfterFix) {
   const retry = status.retryAfterFix;
-  writeStatus({ currentAgent: retry, state: 'in_progress', retryAfterFix: null });
+  const retryIndex = scheduleRetry(retry, null, finishedAttempt, status.retryAfterFixStepIndex);
+  writeStatus({ pipelineIndex: retryIndex, currentAgent: retry, state: 'in_progress', retryAfterFix: null, retryAfterFixStepIndex: null });
   out(handoffForAgent(retry));
   process.exit(0);
 }
@@ -320,7 +517,7 @@ if (!currentStep) {
   process.exit(0);
 }
 
-const completedAgent = status.currentAgent || getStepAgents(currentStep)[0];
+const completedAgent = finishedAttempt?.entry?.agent || status.currentAgent || getStepAgents(currentStep)[0];
 const stepAgents = getStepAgents(currentStep);
 
 if (currentStep.parallel && stepAgents.length > 1) {
@@ -338,6 +535,7 @@ if (currentStep.parallel && stepAgents.length > 1) {
 }
 
 if (hasGateAfterStep(currentStep, pipeline.humanGates)) {
+  beginHumanGate();
   writeStatus({
     awaitingHumanGate: true,
     state: 'awaiting_approval',
@@ -349,6 +547,7 @@ if (hasGateAfterStep(currentStep, pipeline.humanGates)) {
 
 const next = findNextExecutableStep(steps, idx + 1, taskDir);
 if (!next) {
+  completeTaskMetrics();
   writeStatus({
     pipelineIndex: steps.length,
     phase: 'done',
@@ -363,6 +562,7 @@ if (!next) {
 const { step: nextStep, index: nextIdx } = next;
 const nextAgents = getStepAgents(nextStep);
 
+activateAttempts(nextStep, nextIdx);
 writeStatus({
   pipelineIndex: nextIdx,
   currentAgent: nextAgents[0],

package/presets/claude/next/rules/README.md

@@ -103,3 +103,9 @@
 | `tooling-and-review/` | Quality, review, lint, agent-team, retro, **preset meta** |
 
 **Коллизии:** импорт типов и API — **`architecture/public-imports.md`**.
+
+## Metrics policy mapping
+
+| Shared core | Runtime integration | Loading |
+|-------------|---------------------|---------|
+| `agent-team/agent-task-metrics.md` | `agent-team-orchestrator` + `hooks/chain-team-phases.sh` | requestable/on-demand; never session-start |

package/presets/claude/next/rules/tooling-and-review/agent-team-orchestrator.md

@@ -76,6 +76,10 @@ flowchart TD
 
 **Source of truth for order:** `pipeline.json` → `steps[]`. Never hardcode analyst → dev → review → QA when `pipeline.json` exists.
 
+## Metrics lifecycle
+
+Use the local `metrics.json` ledger described by **agent-task-metrics**: initialize attempts before invocation, let hooks record host-clock ends, and never guess a parallel completion from `currentAgent`.
+
 ## status.json (pipeline mode)
 
 ```json

package/presets/claude/next/rules/tooling-and-review/preset-layering.md

@@ -24,7 +24,7 @@ paths:
 ## Куда класть новое правило
 
 1. Общие принципы для всех стеков → **core** + адаптеры с `<!-- shared-core: … -->`.
-2. Только один из installable стеков (`next` / `ios-swift` / `go` / `java`) → **stack-specific** (не в `_shared`).
+2. Только один из installable стеков (`next` / `ios-swift` / `go` / `java` / `mcp-ts` / `php-hexagonal` / `php-laravel`) → **stack-specific** (не в `_shared`).
 3. Только Cursor или только Claude packaging → platform artifact / frontmatter, не дублировать семантику.
 
 ## SoT

package/presets/claude/next/rules/tooling-and-review/preset-no-cross-stack-leakage.md

@@ -17,7 +17,7 @@ paths:
 
 - `next` must not require iOS-only agents/tooling (`xcuitest-*`, `xcodebuild` as required handoff, Keychain-only rules).
 - `ios-swift` must not ship Playwright handoffs or Next lint recipes as required commands.
-- `go` / `java` / `mcp-ts` must not ship Playwright, XCUITest, Next lint recipes, or `xcodebuild`/`SwiftLint` as required handoffs.
+- `go` / `java` / `php-hexagonal` / `php-laravel` / `mcp-ts` must not ship Playwright, XCUITest, Next lint recipes, or `xcodebuild`/`SwiftLint` as required handoffs.
 - `mcp-ts` must not ship Go tool commands (`go test`, `go vet`, `golangci-lint`) or `integration-test-*` agents as required delivery gates.
 - Shared core must not embed stack paths (`app/src/**`, `Features/**`, `playwright`, `xcodebuild`).
 
@@ -36,16 +36,16 @@ Required instead: `xcuitest-test-*` stems; build-verifier mentions `xcodebuild`
 - `xcuitest-test-` as handoff stems
 - Requiring `xcodebuild` / SwiftLint as the default post-change gate for Next app work
 
-## Forbidden in go / java hooks/agents (FAIL)
+## Forbidden in go / java / php-hexagonal / php-laravel hooks/agents (FAIL)
 
-Shared backend-stack bans (both `go` and `java`):
+Shared backend-stack bans (`go`, `java`, `php-hexagonal`, and `php-laravel`):
 
 - `playwright-test-`, `playwright-e2e`, `user-playwright`, `app/__tests__/e2e`
 - Positive yarn recipes `lint:js` / `lint:css`
 - `xcuitest-test-`, `xcodebuild`, `SwiftLint` as required handoffs
 - Agent file `accessibility-reviewer` (no UI surface)
 
-Required instead: `integration-test-*`; build-verifier / `post-change-test` plus stack tooling — `go-tooling` (`go test`, `go vet`) or `java-tooling` (`mvn test` / `./gradlew test`).
+Required instead: `integration-test-*`; build-verifier / `post-change-test` plus stack tooling — `go-tooling` (`go test`, `go vet`), `java-tooling` (`mvn test` / `./gradlew test`), or `php-tooling` (`php artisan test` / `composer test` / `vendor/bin/phpunit`).
 
 ## Forbidden in mcp-ts hooks/agents (FAIL)
 
@@ -66,4 +66,4 @@ Required instead: package-manager–discovered typecheck/test (`mcp-ts-tooling`,
 
 ## Chain fork
 
-`hooks/chain-team-phases.sh` must differ **byte-wise** pairwise among `next`, `ios-swift`, `go`, `java`, and `mcp-ts` (per platform).
+`hooks/chain-team-phases.sh` must differ **byte-wise** pairwise among `next`, `ios-swift`, `go`, `java`, `mcp-ts`, `php-hexagonal`, and `php-laravel` (per platform).

package/presets/claude/next/rules/tooling-and-review/preset-pr-checklist.md

@@ -17,7 +17,7 @@ paths:
 
 - [ ] **SoT:** правки в `packages/…` (не только root `.cursor/`)
 - [ ] **Core:** если менялся `_shared/core/**` — обновлены все `<!-- shared-core: … -->` consumers (или documented intentional fork)
-- [ ] **Twin:** Cursor change → Claude twin **same PR** (**FAIL** if missing on next, ios-swift, go, and java — см. `preset-twin-sync`)
+- [ ] **Twin:** Cursor change → Claude twin **same PR** (**FAIL** if missing on next, ios-swift, go, java, mcp-ts, php-hexagonal, and php-laravel — см. `preset-twin-sync`)
 - [ ] **Mapping:** `claude/<stack>/rules/README.md` mapping table актуален
 - [ ] **Token budget:** alwaysApply / session-start ≤ 3; meta rules not always-on
 - [ ] **Leakage:** нет чужих stack agent stems / handoff strings (`preset-no-cross-stack-leakage`)

package/presets/claude/next/rules/tooling-and-review/preset-twin-sync.md

@@ -22,6 +22,8 @@ Cursor `.mdc` — **SoT per stack**. Claude topic `.md` — derived twin.
 | `go` | `presets/cursor/go/rules/*.mdc` | `presets/claude/go/rules/<topic>/` | Keep in `claude/go/rules/README.md` |
 | `java` | `presets/cursor/java/rules/*.mdc` | `presets/claude/java/rules/<topic>/` | Keep in `claude/java/rules/README.md` |
 | `mcp-ts` | `presets/cursor/mcp-ts/rules/*.mdc` | `presets/claude/mcp-ts/rules/<topic>/` | Keep in `claude/mcp-ts/rules/README.md` |
+| `php-hexagonal` | `presets/cursor/php-hexagonal/rules/*.mdc` | `presets/claude/php-hexagonal/rules/<topic>/` | Keep in `claude/php-hexagonal/rules/README.md` |
+| `php-laravel` | `presets/cursor/php-laravel/rules/*.mdc` | `presets/claude/php-laravel/rules/<topic>/` | Keep in `claude/php-laravel/rules/README.md` |
 
 ## Same-PR checklist
 
@@ -42,5 +44,7 @@ Cursor `.mdc` — **SoT per stack**. Claude topic `.md` — derived twin.
 - **go:** missing Claude twin for a changed Cursor rule → **FAIL** (same as next / ios-swift; mapping table required).
 - **java:** missing Claude twin for a changed Cursor rule → **FAIL** (same as next / ios-swift / go; mapping table required).
 - **mcp-ts:** missing Claude twin for a changed Cursor rule → **FAIL** (same as next / ios-swift / go / java; mapping table required).
+- **php-hexagonal:** missing Claude twin for a changed Cursor rule → **FAIL** (same as next / ios-swift / go / java / mcp-ts; mapping table required).
+- **php-laravel:** missing Claude twin for a changed Cursor rule → **FAIL** (same as next / ios-swift / go / java / mcp-ts / php-hexagonal; mapping table required).
 
 Dogfood: sync packages → root `.cursor/` after Cursor SoT changes (not the reverse). Use `packages/ai-rules/scripts/sync-dogfood-cursor.sh`.

package/presets/claude/next/rules/tooling-and-review/technical-retro.md

@@ -13,4 +13,6 @@ paths:
 
 **`commands/technical-retro.md`** → `/technical-retro`
 
+When a task has `metrics.json`, use the local aggregation script and state the cohort, sample size, incomplete artifacts, attribution confidence, active attempt duration, and human-gate wait separately. Do not score malformed artifacts or gate wait as agent work.
+
 Используй rule только если command недоступен. Не дублируй содержимое command в ответе — следуй command-файлу и skill `technical-retro`.

package/presets/claude/next/team/README.md

@@ -12,6 +12,7 @@
     <slug>/
       pipeline.json
       status.json
+      metrics.json             # schema-v1 append-only event ledger (see Local metrics ledger)
       brief.md
       decomposition.md
       debug-report.md          # fixApplied: true/false
@@ -71,6 +72,8 @@
   "awaitingHumanGate": false,
   "parallelCompleted": [],
   "retryAfterFix": null,
+  "activeAttempts": {},
+  "lastCompletedAttempt": null,
   "updatedAt": "2026-05-29T12:00:00.000Z"
 }
 ```
@@ -103,3 +106,19 @@ Legacy: `/feature-start`, `/feature-continue`.
 ## Git
 
 Commit task artifacts if you want them to survive `ai-rules clean claude`. Or copy finished tasks to `docs/agent-workflow/tasks/<slug>/`.
+
+## Local metrics ledger
+
+`metrics.json` is an append-only schema-v1 event ledger for one task run. It contains only allowlisted IDs, task dimensions, timestamps, outcomes, and attribution confidence—never prompts, secrets, file paths, or contents. Policy SoT: `presets/_shared/core/agent-team/agent-task-metrics.md`. The router writes `task_started` / `attempt_started`; the hook records host-clock completion and human-gate edges under a per-task lock with temp-and-rename.
+
+`status.json.activeAttempts` is a transient timing bridge keyed by `attemptId`; `lastCompletedAttempt` is diagnostic. For parallel stops, the hook must use a stable payload identity or the sole active attempt. Otherwise an explicit `.metrics-receipts.json` receipt is fallback data marked `source: agent`, `attributionConfidence: fallback`; it must never guess from `currentAgent`.
+
+After a human gate, `/task-continue` closes wait via the installed hook (do not hand-edit `pipelineIndex` first):
+
+```bash
+printf '%s\n' '{"status":"completed","action":"end_human_gate","activateNext":true}' | bash .claude/hooks/chain-team-phases.sh
+```
+
+That appends `human_gate_ended` before the next `attempt_started`. Cursor twin uses the same payload against `.cursor/hooks/chain-team-phases.sh`. Other installable stacks ship the same ledger contract in their `team/README.md`.
+
+Aggregate with `node packages/ai-rules/scripts/aggregate-agent-task-metrics.mjs --team-root .claude/team`. It reports role/agent count, completed count, total/average duration, distinct completed run IDs, separate human-gate wait, and incomplete artifacts. For retros, see `/technical-retro` → **Metrics evidence**.

package/presets/claude/php-hexagonal/CLAUDE.md

@@ -0,0 +1,31 @@
+# PHP hexagonal (Claude)
+
+Preset for PHP backends using ports & adapters (PSR / Composer-first).
+
+**Repo-root agents:** see [`AGENTS.md`](../../AGENTS.md) at the project root.
+
+- Session-start: `php-app-core`, `architecture/boundaries`, `code-quality` (exactly 3).
+- Delivery: `architecture/feature-delivery.md` + skill `feature-delivery`.
+- After PHP edits: `tooling-and-review/post-change-test.md` (+ `php-tooling`).
+- Integration tests: agents `integration-test-*` + skill `integration-testing` (never Playwright/XCUITest).
+- Unit tests: agents `unit-test-*` + skill `unit-testing` (PHPUnit).
+- ADR: skill `write-adr` (on-demand).
+- How does X work: agent `codebase-analyzer` (explain-as-is; no `/task`).
+
+## Inventory
+
+- **21 agents** — `agents/README.md` (no a11y / Playwright / XCUITest)
+- **8 skills** — feature-delivery, unit-testing, integration-testing, ci-investigation, debug-investigation, code-review, technical-retro, write-adr
+- **5 commands** — `/task`, `/task-continue`, `/feature-start`, `/feature-continue`, `/technical-retro`
+
+## Dogfood (5 scenarios)
+
+Host: `dogfood/php-hexagonal`.
+
+1. `/task` — domain use case through ports, adapters, Composition on the sample.
+2. HTTP DTO mapping bug — debugger + `TodoController` unit.
+3. Repository contract — integration-test trio (sample: in-memory persistence).
+4. PHPUnit unit test for use case with port fake/mock.
+5. Secrets/authz logging — `security-reviewer` + `security-php`.
+
+Init: `npx @bonesofspring/ai-rules init claude --preset php-hexagonal` (also copies `REPO_AGENTS.md` → root `AGENTS.md`).

package/presets/claude/php-hexagonal/MCP.md

@@ -0,0 +1,15 @@
+# MCP (preset `php-hexagonal`, Claude)
+
+Копируется в project `.mcp.json` при `ai-rules init claude --preset php-hexagonal`.
+
+## Servers
+
+| Name | Package | Зачем |
+|------|---------|--------|
+| `context7` | `@upstash/context7-mcp` | Актуальная документация PHP / Composer / популярных библиотек |
+
+Figma и browser e2e MCP (Playwright / Chrome DevTools) **не** входят в php-hexagonal-пресет (backend-only).
+
+Секреты в файл не кладём. Опционально: `CONTEXT7_API_KEY` в окружении.
+
+После init: включить MCP серверы в Claude Code. `init` перезаписывает одноимённый `mcp.json`.

package/presets/claude/php-hexagonal/README.md

@@ -0,0 +1,26 @@
+# Preset `php-hexagonal` (Claude)
+
+Installable Claude Code preset for **PHP hexagonal** services (PSR / Composer-first).
+
+```bash
+npx @bonesofspring/ai-rules init claude --preset php-hexagonal
+```
+
+## Layout
+
+| Path | Role |
+|------|------|
+| `rules/<topic>/` | Derived twins + mapping table in `rules/README.md` |
+| `rules/ui-and-accessibility/` | N/A stub (backend) |
+| `agents/` | 21 agents + README (no a11y / Playwright / XCUITest) |
+| `skills/` | 8 skills + README |
+| `commands/` | 5 slash commands |
+| `team/` | conventions + fixtures |
+| `hooks/` | Shell guard + team chain (byte-forked); **no `hooks.json`** (Claude platform limit) |
+| `REPO_AGENTS.md` | → consumer root `AGENTS.md` |
+| `CLAUDE.md` | Thin Claude entry + inventory / dogfood — **Claude-only** |
+| `MCP.md` / `mcp.json` | Context7 only |
+
+**Platform asymmetry:** `CLAUDE.md` is Claude-only. Cursor SoT has `BUGBOT.md` + `hooks.json` (not shipped here).
+
+Cursor SoT: `presets/cursor/php-hexagonal/`. Contribution: `docs/PRESET-CONTRIBUTION.md`.

package/presets/claude/php-hexagonal/REPO_AGENTS.md

@@ -0,0 +1,46 @@
+# PHP — agent instructions
+
+Cross-tool repo-root guide for the **php-hexagonal** preset (PSR / Composer-first). Tool-specific maps stay under `.cursor/AGENTS.md` and `.claude/CLAUDE.md`.
+
+## Cross-tool setup
+
+- Treat this file as the **shared** entry for any agent (Cursor, Claude Code, or other).
+- Install:
+
+```bash
+npx @bonesofspring/ai-rules init cursor --preset php-hexagonal
+npx @bonesofspring/ai-rules init claude --preset php-hexagonal
+```
+
+`init` overwrites this file from the preset (`REPO_AGENTS.md` → `AGENTS.md`).
+
+## Commands (test / verify)
+
+Detect Composer from the repo (`composer.json` / `composer.lock`). Prefer Composer scripts when present.
+
+| Gate | Typical command |
+|------|-----------------|
+| Tests | `composer test` or `vendor/bin/phpunit` (Pest if that is the repo default) |
+| Static analysis (if configured) | `vendor/bin/phpstan` / `vendor/bin/psalm` |
+| Format (if configured) | `vendor/bin/php-cs-fixer` / `vendor/bin/pint` |
+| Post-change | requestable `post-change-test` + `php-tooling` |
+
+Static analysis / format — only tools already configured in the repo/CI.
+
+## Security basics
+
+- Do not commit secrets (`.env`, tokens, credentials).
+- Review destructive git before running; respect shell hooks.
+
+## Tool entry points
+
+| Tool | Map |
+|------|-----|
+| Cursor | `.cursor/AGENTS.md` |
+| Claude Code | `.claude/CLAUDE.md` |
+
+Rules: `.cursor/rules/` or `.claude/rules/`. Integration tests: `integration-test-*` (never Playwright/XCUITest).
+
+## Living conventions
+
+Gotchas and team decisions: `.cursor/team/conventions.md` and/or `.claude/team/conventions.md` (fill after init; fixtures ship with the preset).