@bonesofspring/ai-rules 0.2.12 → 0.2.14

package/presets/claude/next/agents/unit-test-generator.md

@@ -25,16 +25,12 @@ You generate unit tests from project test plans.
 
 Run affected unit tests from `app/` when feasible. Report files changed, commands run, failures, and gaps.
 
-Update `status.json`:
-
-```json
-{
-  "slug": "<slug>",
-  "currentAgent": "unit-test-generator",
-  "state": "completed",
-  "updatedAt": "<ISO8601>"
-}
-```
+## Artifact contract
+
+- **Authoritative inputs:** read `.claude/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the manifest entries for `unit-test-plan.md`, brief/decomposition when present, and target modules.
+- **Owned outputs:** generated/updated `*.spec.ts` / `*.spec.tsx` paths; upsert only the manifest entry assigned by handoff (`artifactOutputId`; fallback `unit-test-generator`) 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.
 
 ## Design guidance
 

package/presets/claude/next/agents/unit-test-healer.md

@@ -26,16 +26,12 @@ Use **`unit-testing` skill**, **`debug-investigation` skill**, and **`rules/test
 
 Report root cause, files changed, validation result, and remaining risk.
 
-Update `status.json`:
-
-```json
-{
-  "slug": "<slug>",
-  "currentAgent": "unit-test-healer",
-  "state": "completed",
-  "updatedAt": "<ISO8601>"
-}
-```
+## Artifact contract
+
+- **Authoritative inputs:** read `.claude/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the manifest entries for failing test evidence, `unit-test-plan.md` when present, and recent diff.
+- **Owned outputs:** healed `*.spec.ts` / `*.spec.tsx` paths (and minimal production fixes only when evidenced); upsert only the manifest entry assigned by handoff (`artifactOutputId`; fallback `unit-test-healer`) 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.
 
 ## Design guidance
 

package/presets/claude/next/agents/unit-test-planner.md

@@ -46,18 +46,12 @@ Fixtures, mocks, test-store patterns to reuse.
 
 Test titles in the plan must follow Russian capitalization rules from `rules/testing/tests-unit.md`.
 
-## On completion
+## Artifact contract
 
-Update `status.json`:
-
-```json
-{
-  "slug": "<slug>",
-  "currentAgent": "unit-test-planner",
-  "state": "completed",
-  "updatedAt": "<ISO8601>"
-}
-```
+- **Authoritative inputs:** read `.claude/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the manifest entries for brief/decomposition and target modules under `app/src/**`.
+- **Owned outputs:** `unit-test-plan.md`; upsert only the manifest entry assigned by handoff (`artifactOutputId`; fallback `unit-test-planner`) 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.
 
 Do not write `*.spec.ts` files — that is `unit-test-generator`'s job.
 

package/presets/claude/next/commands/task.md

@@ -25,14 +25,16 @@ description: Route a natural-language task through the agent-team pipeline: task
 
 ## Алгоритм
 
-1. **Slug** — kebab-case из описания (≤48 символов). Создай `.claude/team/tasks/<slug>/` через запись файла (Write / Edit) — **не** полагайся на Shell `mkdir` как единственный способ создать каталог.
+1. **Slug** — kebab-case из описания (≤48 символов). Создай `.claude/team/tasks/<slug>/` через запись файла (Write / Edit); runtime/hook владеет `status.json` — **не** полагайся на Shell `mkdir` как единственный способ создать каталог.
 2. **Router** — вызови subagent **task-router** с описанием задачи и путём к slug.
 3. **План** — покажи пользователю таблицу из `pipeline.json`: intent, steps, skipped, humanGates.
 4. **Intent retro** — если `intent === "retro"`, выполни `/technical-retro` и **остановись**.
-5. **Старт** — вызови subagent для `pipeline.steps[0].agent`:
-   - передай slug, пути к артефактам, scope из step (если есть);
-   - обнови `status.json`: `pipelineIndex: 0`, `currentAgent`, `state: in_progress`.
-6. **Human gate** — если после текущего шага есть gate в `humanGates` (`after:<agent>`), после завершения агента **остановись** и попроси `/task-continue <slug>` (или `/feature-continue <slug>`).
+5. **Старт** — после router:
+   - подтверди `pipeline.json` и `active-task.json`;
+   - **не** пиши lifecycle-поля `status.json` / `metrics.json` сам — их владеет orchestration runtime/hook (см. **agent-artifact-contracts**). Если `status.json` отсутствует, допустим только минимальный bootstrap (`slug`, `intent`, `pipelineIndex: 0`, `currentAgent: steps[0]`, `state: in_progress`) — **не** увеличивай `pipelineIndex` вручную;
+   - вызови subagent для `pipeline.steps[0].agent` (slug, пути к артефактам, scope).
+6. **После каждого агента** — дождись hook handoff / reconciliation terminal receipt → `status.state`; не запускай следующий шаг, пока `status.json` не отражает handoff (или пока нет `followup_message` от hook).
+7. **Human gate** — если после текущего шага есть gate в `humanGates` (`after:<agent>`), после завершения агента **остановись** и попроси `/task-continue <slug>` (или `/feature-continue <slug>`).
 
 ## Не делать
 
@@ -51,4 +53,4 @@ description: Route a natural-language task through the agent-team pipeline: task
 
 ## Metrics
 
-Initialize `metrics.json` before the first invocation with frozen task dimensions and `task_started`; add one `activeAttempts[attemptId]` entry plus `attempt_started` per scheduled agent. On `/task-continue`, append `human_gate_ended` (referencing the stored gate event) before activating the next attempt. Do not calculate durations in agents.
+Runtime/hook owns `metrics.json` and `status.json` attempt ledgers. Before the first invocation ensure `task_started` and one `activeAttempts[attemptId]` + `attempt_started` exist (router/runtime bootstrap — parent must not invent parallel indices). On `/task-continue`, run the installed chain hook `end_human_gate` action (or wrapper) so `human_gate_ended` lands before the next attempt. Do not calculate durations in agents.

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

@@ -122,6 +122,27 @@ function roleFor(agent) {
   if (/writer/.test(agent || '')) return 'docs';
   return 'implementation';
 }
+const DEFAULT_ARTIFACT_OUTPUT_IDS = {
+  'task-router': 'routing',
+  'task-analyst': 'analysis',
+  'solution-architect': 'architecture',
+  'migration-specialist': 'migration-plan',
+  debugger: 'debug',
+  'ci-investigator': 'ci',
+  'feature-developer': 'implementation',
+  'build-verifier': 'validation',
+  'code-reviewer': 'review',
+  'security-reviewer': 'security-review',
+  'accessibility-reviewer': 'a11y-review',
+  'performance-auditor': 'perf-report',
+  'api-contract-reviewer': 'api-contract-review',
+  'tech-writer': 'documentation',
+};
+function artifactOutputIdFor(step, agent) {
+  if (step && typeof step.artifactOutputId === 'string') return step.artifactOutputId;
+  if (step?.artifactOutputIds && typeof step.artifactOutputIds[agent] === 'string') return step.artifactOutputIds[agent];
+  return DEFAULT_ARTIFACT_OUTPUT_IDS[agent] || agent;
+}
 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;
@@ -144,11 +165,61 @@ function resolvedAttempt() {
   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 readBoundReceiptOutcome(agent, step, resolved) {
+  if (!agent || !resolved) return { outcome: null, receiptRequired: false };
+  const manifestPath = path.join(taskDir, 'artifact-manifest.json');
+  if (!fs.existsSync(manifestPath)) return { outcome: null, receiptRequired: false };
+  try {
+    const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+    const artifacts = Array.isArray(manifest.artifacts) ? manifest.artifacts : [];
+    const expectedOutputId = artifactOutputIdFor(step, agent);
+    const attemptStartedAt = Date.parse(resolved.entry.startedAt);
+    const owned = artifacts
+      .filter((entry) => {
+        if (!entry || entry.producer !== agent || !entry.receipt || typeof entry.receipt.outcome !== 'string') return false;
+        const boundByAttempt = typeof entry.receipt.attemptId === 'string' && entry.receipt.attemptId === resolved.attemptId;
+        const boundByOutput = entry.receipt.attemptId == null && entry.id === expectedOutputId;
+        if (!boundByAttempt && !boundByOutput) return false;
+        const terminalAt = Date.parse(entry.timestamps?.completedAt || entry.timestamps?.updatedAt || '');
+        return Number.isFinite(terminalAt) && (!Number.isFinite(attemptStartedAt) || terminalAt >= attemptStartedAt);
+      })
+      .sort((a, b) => {
+        const ta = Date.parse(a.timestamps?.completedAt || a.timestamps?.updatedAt || 0) || 0;
+        const tb = Date.parse(b.timestamps?.completedAt || b.timestamps?.updatedAt || 0) || 0;
+        return tb - ta;
+      });
+    return { outcome: owned[0]?.receipt?.outcome || null, receiptRequired: true };
+  } catch {
+    return { outcome: null, receiptRequired: false };
+  }
+}
+function reconcileStatusFromManifest(agent, step, resolved) {
+  const terminal = new Set(['completed', 'blocked', 'changes_requested', 'validation_failed']);
+  const { outcome, receiptRequired } = readBoundReceiptOutcome(agent, step, resolved);
+  if (terminal.has(outcome)) {
+    status.state = outcome;
+    return outcome;
+  }
+  if (receiptRequired) {
+    status.state = 'awaiting_artifact_receipt';
+    status.phase = 'blocked';
+    return status.state;
+  }
+  if (terminal.has(status.state)) return status.state;
+  // Host reported subagent completed and no blocking receipt → treat as completed for metrics/advance.
+  if (hookInput.status === 'completed') {
+    status.state = 'completed';
+    return 'completed';
+  }
+  return status.state;
+}
+
 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;
+  const outcome = ['completed', 'blocked', 'changes_requested', 'validation_failed'].includes(status.state) ? status.state : 'unknown';
+  appendMetric({ type: 'attempt_finished', at: now, attemptId: resolved.attemptId, outcome, 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, outcome };
 }
 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() {
@@ -217,54 +288,54 @@ function findNextExecutableStep(steps, startIdx, dir) {
 const AGENT_HANDOFF = {
   'task-analyst': (s) =>
     `Invoke task-analyst for slug "${s}". Write brief.md and decomposition.md under .claude/team/tasks/${s}/. ` +
-    `Set status.json: phase executing, state awaiting_approval if human gate applies. Do not use legacy phase analysis.`,
+    `Upsert the analysis receipt in artifact-manifest.json; do not mutate status.json lifecycle fields. Do not use legacy phase analysis.`,
   debugger: (s) =>
     `Invoke debugger subagent for slug "${s}". Investigate root cause; write debug-report.md with fixApplied: true/false. ` +
-    `Update status.json when done.`,
+    `Upsert the owned terminal receipt in artifact-manifest.json; do not mutate status.json lifecycle fields.`,
   'solution-architect': (s) =>
-    `Invoke solution-architect for slug "${s}". Read brief.md; write architecture.md. Update status.json when done.`,
+    `Invoke solution-architect for slug "${s}". Read brief.md; write architecture.md. Upsert the owned terminal receipt in artifact-manifest.json; do not mutate status.json lifecycle fields.`,
   'migration-specialist': (s) =>
-    `Invoke migration-specialist for slug "${s}". Read brief.md; write migration-plan.md. Update status.json when done.`,
+    `Invoke migration-specialist for slug "${s}". Read brief.md; write migration-plan.md. Upsert the owned terminal receipt in artifact-manifest.json; do not mutate status.json lifecycle fields.`,
   'api-contract-reviewer': (s) =>
-    `Invoke api-contract-reviewer (readonly) for slug "${s}". Write api-contract-review.md. Update status.json when done.`,
+    `Invoke api-contract-reviewer (readonly) for slug "${s}". Write api-contract-review.md. Upsert the owned terminal receipt in artifact-manifest.json; do not mutate status.json lifecycle fields.`,
   'ci-investigator': (s) =>
     `Invoke ci-investigator for slug "${s}". Diagnose CI failure; write ci-report.md; apply minimal fix. ` +
-    `Use ci-investigation skill. Update status.json when done.`,
+    `Use ci-investigation skill. Upsert the owned terminal receipt in artifact-manifest.json; do not mutate status.json lifecycle fields.`,
   'feature-developer': (s) =>
     `Invoke feature-developer for slug "${s}". Read brief.md, decomposition.md, validation-report.md, review.md, architecture.md, migration-plan.md, api-contract-review.md, debug-report.md if present. ` +
-    `Follow architecture/feature-delivery-workflow.md and architecture/reference-features.md. Include unit tests for mappers/logic before handoff. Update status.json when done.`,
+    `Follow architecture/feature-delivery-workflow.md and architecture/reference-features.md. Include unit tests for mappers/logic before handoff. Upsert the owned terminal receipt in artifact-manifest.json; do not mutate status.json lifecycle fields.`,
   'build-verifier': (s) =>
     `Invoke build-verifier (readonly) for slug "${s}". Run lint:js, lint:css, type-check, and targeted unit tests from app/. ` +
-    `Write validation-report.md. Set state completed or validation_failed. Do not edit production code.`,
+    `Write validation-report.md and emit receipt outcome completed or validation_failed. Do not edit production code.`,
   'accessibility-reviewer': (s) =>
-    `Invoke accessibility-reviewer (readonly) for slug "${s}". Review UI diff; write a11y-review.md. Update status.json when done.`,
+    `Invoke accessibility-reviewer (readonly) for slug "${s}". Review UI diff; write a11y-review.md. Upsert the owned terminal receipt in artifact-manifest.json; do not mutate status.json lifecycle fields.`,
   'performance-auditor': (s) =>
-    `Invoke performance-auditor (readonly) for slug "${s}". Write perf-report.md. Update status.json when done.`,
+    `Invoke performance-auditor (readonly) for slug "${s}". Write perf-report.md. Upsert the owned terminal receipt in artifact-manifest.json; do not mutate status.json lifecycle fields.`,
   'code-reviewer': (s) =>
     `Invoke code-reviewer subagent (readonly) for slug "${s}". Review git diff vs brief.md per tooling-and-review/code-review-mr.md. ` +
-    `Update status.json when done.`,
+    `Upsert the owned terminal receipt in artifact-manifest.json; do not mutate status.json lifecycle fields.`,
   'security-reviewer': (s) =>
-    `Invoke security-reviewer (readonly) for slug "${s}". Write security-review.md. Update status.json when done.`,
+    `Invoke security-reviewer (readonly) for slug "${s}". Write security-review.md. Upsert the owned terminal receipt in artifact-manifest.json; do not mutate status.json lifecycle fields.`,
   'qa-tester': (s, scope) =>
     `Invoke qa-tester for slug "${s}"${scope ? ` (scope: ${scope})` : ''}. ` +
-    `Add/update tests per brief. Follow testing/playwright-agents.md. Update status.json when done.`,
+    `Add/update tests per brief. Follow testing/playwright-agents.md. Upsert the owned terminal receipt in artifact-manifest.json; do not mutate status.json lifecycle fields.`,
   'unit-test-planner': (s) =>
-    `Invoke unit-test-planner for slug "${s}". Write unit-test-plan.md. Use unit-testing skill. Update status.json when done.`,
+    `Invoke unit-test-planner for slug "${s}". Write unit-test-plan.md. Use unit-testing skill. Upsert the owned terminal receipt in artifact-manifest.json; do not mutate status.json lifecycle fields.`,
   'unit-test-generator': (s) =>
-    `Invoke unit-test-generator for slug "${s}". Implement specs from unit-test-plan.md. Use unit-testing skill. Update status.json when done.`,
+    `Invoke unit-test-generator for slug "${s}". Implement specs from unit-test-plan.md. Use unit-testing skill. Upsert the owned terminal receipt in artifact-manifest.json; do not mutate status.json lifecycle fields.`,
   'unit-test-healer': (s) =>
-    `Invoke unit-test-healer for slug "${s}". Fix failing unit tests. Use unit-testing and debug-investigation skills. Update status.json when done.`,
+    `Invoke unit-test-healer for slug "${s}". Fix failing unit tests. Use unit-testing and debug-investigation skills. Upsert the owned terminal receipt in artifact-manifest.json; do not mutate status.json lifecycle fields.`,
   'playwright-test-planner': (s) =>
     `Invoke playwright-test-planner for slug "${s}". Create/update app/__tests__/e2e/**/*.cases.md. ` +
-    `Follow testing/playwright-agents.md and the playwright-e2e skill. Update status.json when done.`,
+    `Follow testing/playwright-agents.md and the playwright-e2e skill. Upsert the owned terminal receipt in artifact-manifest.json; do not mutate status.json lifecycle fields.`,
   'playwright-test-generator': (s) =>
     `Invoke playwright-test-generator for slug "${s}". Generate/update *.spec.ts from matching *.cases.md. ` +
-    `Use playwright MCP when available. Follow testing/playwright-agents.md and the playwright-e2e skill. Update status.json when done.`,
+    `Use playwright MCP when available. Follow testing/playwright-agents.md and the playwright-e2e skill. Upsert the owned terminal receipt in artifact-manifest.json; do not mutate status.json lifecycle fields.`,
   'playwright-test-healer': (s) =>
     `Invoke playwright-test-healer for slug "${s}". Fix failing/flaky e2e while preserving cases.md assertions. ` +
-    `Use playwright MCP when available. Follow testing/playwright-agents.md and debug-investigation. Update status.json when done.`,
+    `Use playwright MCP when available. Follow testing/playwright-agents.md and debug-investigation. Upsert the owned terminal receipt in artifact-manifest.json; do not mutate status.json lifecycle fields.`,
   'tech-writer': (s) =>
-    `Invoke tech-writer for slug "${s}". Write documentation.md from task artifacts. Update status.json when done.`,
+    `Invoke tech-writer for slug "${s}". Write documentation.md from task artifacts. Upsert the owned terminal receipt in artifact-manifest.json; do not mutate status.json lifecycle fields.`,
 };
 
 const REVIEW_AGENTS = new Set([
@@ -277,15 +348,20 @@ const REVIEW_AGENTS = new Set([
 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 attemptId: ${matches[0][0]}; write owned artifact-manifest receipt outcome. If the hook cannot identify a parallel stop, append a minimal { attemptId, outcome } receipt to .metrics-receipts.json; do not mutate status.json or 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) {
+function artifactHandoff(step, agent) {
+  const inputIds = Array.isArray(step?.artifactInputIds) ? step.artifactInputIds.join(', ') : 'manifest defaults';
+  return ` Artifact inputs: ${inputIds}; owned output ID: ${artifactOutputIdFor(step, agent)}. Bind the terminal receipt to the supplied attemptId.`;
+}
+
+function handoffForAgent(agent, scope, step = null) {
   const fn = AGENT_HANDOFF[agent];
-  const handoff = fn ? fn(slug, scope) : `Invoke ${agent} subagent for slug "${slug}". Update status.json when done.`;
-  return handoff + metricsHandoff(agent);
+  const handoff = fn ? fn(slug, scope) : `Invoke ${agent} subagent for slug "${slug}". Upsert the owned terminal receipt in artifact-manifest.json; do not mutate status.json lifecycle fields.`;
+  return handoff + artifactHandoff(step, agent) + metricsHandoff(agent);
 }
 
 function handoffForParallelStep(step) {
@@ -295,7 +371,8 @@ function handoffForParallelStep(step) {
     .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 owned receipt; the hook records parallelCompleted from stops. Do not mutate status.json lifecycle fields. ` +
+    `Artifact inputs: ${Array.isArray(step.artifactInputIds) ? step.artifactInputIds.join(', ') : 'manifest defaults'}; owned output IDs: ${agents.map((agent) => `${agent}=${artifactOutputIdFor(step, agent)}`).join('; ')}. ` +
     `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.`
   );
 }
@@ -334,8 +411,12 @@ function legacyFlow() {
     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)) {
+  if (status.state === 'changes_requested') {
     const reviewer = status.currentAgent;
+    if (!reviewer) {
+      process.stdout.write('{}');
+      process.exit(0);
+    }
     scheduleLegacyRetry('feature-developer', reviewer);
     writeStatus({
       currentAgent: 'feature-developer',
@@ -409,7 +490,7 @@ if (hookInput.action === 'end_human_gate') {
           parallelCompleted: [],
         });
         if (resumeNext.step.parallel && resumeAgents.length > 1) out(handoffForParallelStep(resumeNext.step));
-        else out(handoffForAgent(resumeAgents[0], resumeNext.step.scope));
+        else out(handoffForAgent(resumeAgents[0], resumeNext.step.scope, resumeNext.step));
         process.exit(0);
       }
     }
@@ -438,6 +519,19 @@ 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 completingAgentHint = (() => {
+  const resolved = resolvedAttempt();
+  if (resolved?.entry?.agent) return resolved.entry.agent;
+  if (status.currentAgent) return status.currentAgent;
+  return getStepAgents(initialStep)[0];
+})();
+const reconcilingAttempt = resolvedAttempt();
+reconcileStatusFromManifest(completingAgentHint, initialStep, reconcilingAttempt);
+if (status.state === 'awaiting_artifact_receipt') {
+  writeStatus({});
+  process.stdout.write('{}');
+  process.exit(0);
+}
 const finishedAttempt = finishActiveAttempt();
 if (!finishedAttempt && (hookInput.attemptId || activeAttemptCountBeforeFinish > 0)) {
   process.stdout.write('{}');
@@ -445,6 +539,7 @@ if (!finishedAttempt && (hookInput.attemptId || activeAttemptCountBeforeFinish >
 }
 endHumanGateIfResumed();
 if (steps.length === 0 || pipeline.autoChain === false) {
+  writeStatus({});
   process.stdout.write('{}');
   process.exit(0);
 }
@@ -470,8 +565,75 @@ function scheduleRetry(agent, retryAfterFix, predecessor, explicitStepIndex = nu
   return stepIndex;
 }
 
-if (status.state === 'changes_requested' && REVIEW_AGENTS.has(status.currentAgent)) {
-  const reviewer = status.currentAgent;
+const idx = typeof status.pipelineIndex === 'number' ? status.pipelineIndex : 0;
+const currentStep = steps[idx];
+const completedAgent = finishedAttempt?.entry?.agent || status.currentAgent || getStepAgents(currentStep)[0];
+const stepAgents = getStepAgents(currentStep);
+
+if (currentStep?.parallel && stepAgents.length > 1) {
+  const done = [...(status.parallelCompleted || [])];
+  const outcomes = { ...(status.parallelOutcomes || {}) };
+  if (finishedAttempt && completedAgent) {
+    if (!done.includes(completedAgent)) done.push(completedAgent);
+    outcomes[completedAgent] = {
+      outcome: finishedAttempt.outcome || status.state,
+      attemptId: finishedAttempt.attemptId,
+      confidence: finishedAttempt.confidence,
+    };
+  }
+  writeStatus({ parallelCompleted: done, parallelOutcomes: outcomes });
+  const remaining = stepAgents.filter((agent) => !done.includes(agent));
+  if (remaining.length > 0) {
+    process.stdout.write('{}');
+    process.exit(0);
+  }
+
+  const blockedProducer = stepAgents.find((agent) => outcomes[agent]?.outcome === 'blocked');
+  if (blockedProducer) {
+    writeStatus({ parallelCompleted: [], parallelOutcomes: {}, state: 'blocked', phase: 'blocked', currentAgent: blockedProducer });
+    process.stdout.write('{}');
+    process.exit(0);
+  }
+
+  const retryReviewer = stepAgents.find((agent) => outcomes[agent]?.outcome === 'changes_requested');
+  if (retryReviewer) {
+    const retryAfterFixStepIndex = idx;
+    const predecessor = outcomes[retryReviewer]
+      ? {
+          attemptId: outcomes[retryReviewer].attemptId,
+          confidence: outcomes[retryReviewer].confidence,
+        }
+      : finishedAttempt;
+    const developerIndex = scheduleRetry('feature-developer', retryReviewer, predecessor);
+    writeStatus({
+      pipelineIndex: developerIndex,
+      currentAgent: 'feature-developer',
+      state: 'in_progress',
+      phase: 'executing',
+      retryAfterFix: retryReviewer,
+      retryAfterFixStepIndex,
+      parallelCompleted: [],
+      parallelOutcomes: {},
+    });
+    out(handoffForAgent('feature-developer', steps[developerIndex]?.scope, steps[developerIndex]) + ` After fixes, re-run ${retryReviewer}.`);
+    process.exit(0);
+  }
+
+  writeStatus({ parallelCompleted: [], parallelOutcomes: {}, state: 'completed' });
+}
+
+if (status.state === 'blocked') {
+  writeStatus({ state: 'blocked', phase: 'blocked', currentAgent: completedAgent });
+  process.stdout.write('{}');
+  process.exit(0);
+}
+
+if (status.state === 'changes_requested') {
+  const reviewer = status.currentAgent || finishedAttempt?.entry?.agent;
+  if (!reviewer) {
+    process.stdout.write('{}');
+    process.exit(0);
+  }
   const retryAfterFixStepIndex = typeof status.pipelineIndex === 'number' ? status.pipelineIndex : 0;
   const developerIndex = scheduleRetry('feature-developer', reviewer, finishedAttempt);
   writeStatus({
@@ -482,7 +644,7 @@ if (status.state === 'changes_requested' && REVIEW_AGENTS.has(status.currentAgen
     retryAfterFix: reviewer,
     retryAfterFixStepIndex,
   });
-  out(handoffForAgent('feature-developer') + ` After fixes, re-run ${reviewer}.`);
+  out(handoffForAgent('feature-developer', steps[developerIndex]?.scope, steps[developerIndex]) + ` After fixes, re-run ${reviewer}.`);
   process.exit(0);
 }
 
@@ -497,7 +659,7 @@ if (status.state === 'validation_failed' && status.currentAgent === 'build-verif
     retryAfterFix: 'build-verifier',
     retryAfterFixStepIndex,
   });
-  out(handoffForAgent('feature-developer') + ' Read validation-report.md. After fixes, re-run build-verifier.');
+  out(handoffForAgent('feature-developer', steps[developerIndex]?.scope, steps[developerIndex]) + ' Read validation-report.md. After fixes, re-run build-verifier.');
   process.exit(0);
 }
 
@@ -505,35 +667,16 @@ if (status.state === 'completed' && status.retryAfterFix) {
   const retry = status.retryAfterFix;
   const retryIndex = scheduleRetry(retry, null, finishedAttempt, status.retryAfterFixStepIndex);
   writeStatus({ pipelineIndex: retryIndex, currentAgent: retry, state: 'in_progress', retryAfterFix: null, retryAfterFixStepIndex: null });
-  out(handoffForAgent(retry));
+  out(handoffForAgent(retry, steps[retryIndex]?.scope, steps[retryIndex]));
   process.exit(0);
 }
 
-const idx = typeof status.pipelineIndex === 'number' ? status.pipelineIndex : 0;
-const currentStep = steps[idx];
 if (!currentStep) {
   writeStatus({ phase: 'done', state: 'completed', currentAgent: null });
   out(`Pipeline complete for "${slug}". Run /technical-retro ${slug}.`);
   process.exit(0);
 }
 
-const completedAgent = finishedAttempt?.entry?.agent || status.currentAgent || getStepAgents(currentStep)[0];
-const stepAgents = getStepAgents(currentStep);
-
-if (currentStep.parallel && stepAgents.length > 1) {
-  const done = [...(status.parallelCompleted || [])];
-  if (completedAgent && !done.includes(completedAgent)) {
-    done.push(completedAgent);
-  }
-  writeStatus({ parallelCompleted: done });
-  const remaining = stepAgents.filter((a) => !done.includes(a));
-  if (remaining.length > 0) {
-    process.stdout.write('{}');
-    process.exit(0);
-  }
-  writeStatus({ parallelCompleted: [] });
-}
-
 if (hasGateAfterStep(currentStep, pipeline.humanGates)) {
   beginHumanGate();
   writeStatus({
@@ -575,6 +718,6 @@ writeStatus({
 if (nextStep.parallel && nextAgents.length > 1) {
   out(handoffForParallelStep(nextStep));
 } else {
-  out(handoffForAgent(nextAgents[0], nextStep.scope));
+  out(handoffForAgent(nextAgents[0], nextStep.scope, nextStep));
 }
 NODE

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

@@ -50,7 +50,7 @@ Work request без `/task` — см. **`tooling-and-review/agent-team-intake.md
 | `playwright-test-healer` | tests only | failing/flaky e2e fixes |
 | `tech-writer` | docs only | docs-only, feature/migration docs |
 
-Full prompts: `.claude/agents/*.md`. Artifact conventions: `.claude/team/README.md`.
+Full prompts: `.claude/agents/*.md`. Artifact conventions: `.claude/team/README.md`; schema SoT: **agent-artifact-contracts**.
 
 ## Dynamic pipeline
 
@@ -76,9 +76,21 @@ flowchart TD
 
 **Source of truth for order:** `pipeline.json` → `steps[]`. Never hardcode analyst → dev → review → QA when `pipeline.json` exists.
 
+New pipelines retain top-level `profile` and include `routingDecision` with `complexity`, `riskFlags`, non-empty `routingReasons`, `estimatedWorkPackages`, and `openDecisionCount`. The stack `task-router` owns heuristics; this metadata is auditable evidence and does not change hook semantics.
+
 ## 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`.
+Use the local `metrics.json` ledger described by **agent-task-metrics**: the orchestration runtime initializes attempts before invocation, hooks record host-clock ends, and agents never guess a parallel completion from `currentAgent`.
+
+## Artifact context index and receipts
+
+Each slug has one `artifact-manifest.json`: `.cursor/team/tasks/<slug>/` or `.claude/team/tasks/<slug>/`. Schema SoT: **agent-artifact-contracts**.
+
+- Read the manifest before broad prior-artifact discovery. Each step receives authoritative input entry IDs, owns named output entry IDs, and finishes with one terminal receipt linked to AC/task IDs.
+- Markdown remains detailed evidence; the manifest records producer, status, authoritative paths, timestamps, outcome, and evidence paths.
+- Agents upsert only entries they own and preserve foreign entries. Parallel agents use distinct IDs; the parent/orchestrator serializes manifest merges.
+- The orchestration runtime/hook is the single writer for `status.json` lifecycle fields and `metrics.json`. Agents read status for eligibility but never rewrite state, gate, retry, attempt, timestamp, or metrics fields.
+- Missing/stale manifests are reported as a handoff gap; fall back to `brief.md`, `decomposition.md`, and `pipeline.json` rather than inventing authority.
 
 ## status.json (pipeline mode)
 
@@ -90,10 +102,23 @@ Use the local `metrics.json` ledger described by **agent-task-metrics**: initial
   "currentAgent": "task-analyst",
   "phase": "executing",
   "state": "in_progress",
-  "awaitingHumanGate": false
+  "awaitingHumanGate": false,
+  "activeAttempts": {},
+  "lastCompletedAttempt": null,
+  "parallelCompleted": [],
+  "parallelOutcomes": {}
 }
 ```
 
+| Field | Meaning |
+|-------|---------|
+| `activeAttempts` | Transient timing bridge keyed by `attemptId` |
+| `lastCompletedAttempt` | Diagnostic pointer to the latest finished attempt |
+| `parallelCompleted` | Agents that have stopped in the current parallel step |
+| `parallelOutcomes` | Per-agent `{ outcome, attemptId, confidence }` for the current parallel join; cleared when the step advances or retries |
+
+On each `subagentStop`, the hook reconciles `status.state` from the completing producer's terminal `artifact-manifest.json` receipt when agents left lifecycle fields untouched. Wait for that handoff before invoking the next step.
+
 | state | Meaning |
 |-------|---------|
 | `in_progress` | Current step running |
@@ -140,7 +165,7 @@ Use the available Claude Code subagent / Agent tool. Pass: slug, artifact paths,
    - **`strong`** → `opus` (matches strong-agent frontmatter). Prefer explicit per-invocation `model` when frontmatter pins are flaky.
 3. Parallel steps: apply the step-level `model` to each agent (or omit → each frontmatter).
 
-After each agent completes, ensure `status.json` has `state: completed` (or `awaiting_approval` if gate applies).
+After each agent completes, verify its terminal manifest receipt, then let the orchestration runtime/hook reconcile `status.json` (`completed`, a blocking outcome, or `awaiting_approval`) from that receipt. Do not ask the agent to mutate shared lifecycle fields, and do not invoke the next specialist until the hook has written the handoff / updated `status.json`.
 
 ## Legacy mode
 

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

@@ -9,6 +9,7 @@ paths:
 
 <!-- shared-core: meta/preset-layering.md -->
 
+
 # Preset layering
 
 Правила для **авторов пресетов** (`packages/ai-rules/presets/**`). Не always-on в consumer apps.
@@ -24,7 +25,7 @@ paths:
 ## Куда класть новое правило
 
 1. Общие принципы для всех стеков → **core** + адаптеры с `<!-- shared-core: … -->`.
-2. Только один из installable стеков (`next` / `ios-swift` / `go` / `java` / `mcp-ts` / `php-hexagonal` / `php-laravel`) → **stack-specific** (не в `_shared`).
+2. Только один из installable стеков (`next` / `nuxt` / `svelte` / `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

@@ -9,6 +9,7 @@ paths:
 
 <!-- shared-core: meta/preset-no-cross-stack-leakage.md -->
 
+
 # Preset no cross-stack leakage
 
 Запрет протекания stack-specific имён, путей и handoff stems между пресетами.
@@ -16,6 +17,8 @@ paths:
 ## Principles
 
 - `next` must not require iOS-only agents/tooling (`xcuitest-*`, `xcodebuild` as required handoff, Keychain-only rules).
+- `nuxt` must not require iOS-only agents/tooling (`xcuitest-*`, `xcodebuild` as required handoff, Keychain-only rules).
+- `svelte` 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` / `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.
@@ -36,6 +39,18 @@ 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 nuxt hooks/agents (FAIL when present as required)
+
+- `xcuitest-test-` as handoff stems
+- Requiring `xcodebuild` / SwiftLint as the default post-change gate for Nuxt app work
+- Frontend profile mirrors `next`: Playwright / `lint:js` / `lint:css` allowed
+
+## Forbidden in svelte hooks/agents (FAIL when present as required)
+
+- `xcuitest-test-` as handoff stems
+- Requiring `xcodebuild` / SwiftLint as the default post-change gate for SvelteKit app work
+- Frontend profile mirrors `next` / `nuxt`: Playwright / `lint:js` / `lint:css` allowed
+
 ## Forbidden in go / java / php-hexagonal / php-laravel hooks/agents (FAIL)
 
 Shared backend-stack bans (`go`, `java`, `php-hexagonal`, and `php-laravel`):
@@ -66,4 +81,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`, `mcp-ts`, `php-hexagonal`, and `php-laravel` (per platform).
+`hooks/chain-team-phases.sh` must differ **byte-wise** pairwise among `next`, `nuxt`, `svelte`, `ios-swift`, `go`, `java`, `mcp-ts`, `php-hexagonal`, and `php-laravel` (per platform).