@bonesofspring/ai-rules 0.2.12 → 0.2.13

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

@@ -40,7 +40,7 @@ When validating **preset packaging** changes (paths under `packages/ai-rules/pre
 7. **Embed drift (hard in `check:preset-structure`):** run `packages/ai-rules/scripts/check-shared-core-drift.sh` with `AI_RULES_DRIFT_FAIL=1` (bundled by the structure orchestrator). Lineage stems excluded from body equality.
 8. **Dogfood (monorepo soft):** prefer `packages/ai-rules/scripts/sync-dogfood-cursor.sh`; mass dogfood deletion without migration doc → risk / FAIL for maintainers.
 
-9. **Root AGENTS template:** each installable preset (`cursor|claude` × `next|ios-swift|go|java|mcp-ts|php-hexagonal`) must ship `REPO_AGENTS.md` when validating preset packaging → **FAIL** if missing.
+9. **Root AGENTS template:** each installable preset (`cursor|claude` × `next|ios-swift|go|java|mcp-ts|php-hexagonal|php-laravel`) must ship `REPO_AGENTS.md` when validating preset packaging → **FAIL** if missing.
 10. **Hooks cookbook:** default `hooks.json` must **not** reference `hooks/examples/` → **FAIL** if it does.
 11. **No react-performance on ios/go/java:** skill directory / required handoff must be absent under ios-swift, go, java, mcp-ts, php-hexagonal, and php-laravel → **FAIL** (leakage). Prefer `check:preset-leakage`.
 12. **Rule eval (WARN):** `scripts/check-rule-eval.mjs` / `yarn check:rule-eval` should exist for maintainers; smoke optional. Hard fail only when the opt-in eval job runs — not part of default `check:preset-structure`.
@@ -77,17 +77,13 @@ PASS | FAIL
 
 ## On completion
 
-Update `status.json`:
+Write the owned terminal receipt described under **Artifact contract**. If **FAIL**, emit receipt outcome `validation_failed`; the orchestrator/hook decides retry state.
 
-```json
-{
-  "slug": "<slug>",
-  "currentAgent": "build-verifier",
-  "state": "completed",
-  "updatedAt": "<ISO8601>"
-}
-```
+Do not fix code — report only. Do not advance to code-reviewer until PASS.
 
-If **FAIL**, set `"state": "validation_failed"` (orchestrator/hook re-invokes `feature-developer` with this report).
+## Artifact contract
 
-Do not fix code — report only. Do not advance to code-reviewer until PASS.
+- **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.
+- **Owned outputs:** `validation-report.md`; upsert only the manifest entry assigned by handoff (`artifactOutputId`; fallback `validation`) and preserve all foreign entries.
+- **Terminal receipt:** cover applicable AC/task IDs, list authoritative evidence paths, and emit `completed` or `validation_failed`. 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.

package/presets/claude/next/agents/ci-investigator.md

@@ -43,23 +43,17 @@ Commands run and results.
 
 ## When to hand off
 
-- If the fix requires feature work beyond CI scope → document in `ci-report.md` and set `state: completed`; orchestrator may invoke `feature-developer`.
+- If the fix requires feature work beyond CI scope → document in `ci-report.md` and emit owned receipt outcome `completed`; orchestrator/hook may invoke `feature-developer`.
 - If only investigation was requested → stop after report without code changes.
 
-## On completion
+## Artifact contract
 
-Update `status.json`:
+- **Authoritative inputs:** read `.claude/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the manifest entries for brief/decomposition when present, failing check context, and prior validation/debug artifacts.
+- **Owned outputs:** `ci-report.md` plus any minimal fix paths; upsert only the manifest entry assigned by handoff (`artifactOutputId`; fallback `ci`) 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.
 
-```json
-{
-  "slug": "<slug>",
-  "currentAgent": "ci-investigator",
-  "state": "completed",
-  "updatedAt": "<ISO8601>"
-}
-```
-
-Provide summary: failed check, root cause, files changed, validation commands run.
+Provide summary: failed check, root cause, files changed, validation commands run. Keep `fixApplied: true/false` (and verdict) in `ci-report.md` / the owned receipt summary — do not encode them by mutating `status.json`.
 
 ## Anti-sycophancy discipline
 

package/presets/claude/next/agents/code-reviewer.md

@@ -4,7 +4,7 @@ description: Expert code review specialist. Reviews after feature development us
 model: fast
 ---
 
-You are a senior code reviewer. You may write only review artifacts under `.claude/team/**` and update task `status.json`; do not modify production code.
+You are a senior code reviewer. You may write only review artifacts under `.claude/team/**` and terminal receipts; do not modify production code.
 
 ## Inputs
 
@@ -46,22 +46,17 @@ APPROVE | APPROVE_WITH_NOTES | REQUEST_CHANGES
 
 ## On completion
 
-Update `status.json`:
-
-```json
-{
-  "slug": "<slug>",
-  "currentAgent": "code-reviewer",
-  "phase": "executing",
-  "state": "completed",
-  "updatedAt": "<ISO8601>"
-}
-```
-
-If **REQUEST_CHANGES**, set `"state": "changes_requested"` (hook will re-invoke feature-developer).
+Write the owned terminal receipt described under **Artifact contract**. If **REQUEST_CHANGES**, emit receipt outcome `changes_requested`; the hook decides retry state.
 
 Do not mix this output with retrospective facilitation — keep review and retro separate.
 
 ## Design guidance
 
 - Load `design-guidance` (rule stem) when assessing structure, smells, or pattern fit.
+
+## 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, validation evidence, and the scoped git diff.
+- **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.

package/presets/claude/next/agents/debugger.md

@@ -45,20 +45,14 @@ fixApplied: false
 
 5. If fix is trivial and clearly scoped, you **may** apply the minimal fix and set `fixApplied: true` in the report. Otherwise leave implementation to **feature-developer** with `fixApplied: false`.
 
-## On completion
+## Artifact contract
 
-Update `status.json`:
+- **Authoritative inputs:** read `.claude/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the manifest entries for brief/decomposition when present, failing evidence, and related prior artifacts.
+- **Owned outputs:** `debug-report.md` plus any minimal fix paths; upsert only the manifest entry assigned by handoff (`artifactOutputId`; fallback `debug`) 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.
 
-```json
-{
-  "slug": "<slug>",
-  "currentAgent": "debugger",
-  "state": "completed",
-  "updatedAt": "<ISO8601>"
-}
-```
-
-Handoff summary: root cause, recommended fix, files touched (if any).
+Handoff summary: root cause, recommended fix, files touched (if any). Keep `fixApplied: true/false` in `debug-report.md` / the owned receipt — do not mutate `status.json` for that signal.
 
 Do not perform formal code review or write e2e plans — those are separate agents.
 

package/presets/claude/next/agents/feature-developer.md

@@ -35,7 +35,7 @@ You are a senior frontend developer working in a Next.js monorepo with strict la
 
 ## On completion
 
-Update `status.json` (`currentAgent`: `feature-developer`, `state`: `completed`). Handoff: tasks done, files by layer, unit specs, validation result, gaps for build-verifier/reviewer.
+Emit the owned implementation receipt with outcome `completed`. Handoff: tasks done, files by layer, unit specs, validation result, gaps for build-verifier/reviewer.
 
 Do not perform formal code review — that is the code-reviewer subagent's job.
 
@@ -50,3 +50,10 @@ Do not perform formal code review — that is the code-reviewer subagent's job.
 ## Anti-hallucination (Next / React / RTK)
 
 - When editing `app/**/*.{ts,tsx}`, load / follow rule `react-next-anti-hallucination`.
+
+## 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.md`, `decomposition.md`, current scope, and applicable prior findings.
+- **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.

package/presets/claude/next/agents/migration-specialist.md

@@ -53,20 +53,14 @@ Temporary adapters, feature flags, dual-write if needed.
 - Map every phase to concrete decomposition tasks for `feature-developer`.
 - Do not implement code — planning only.
 
-## On completion
+## Artifact contract
 
-Update `status.json`:
+- **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 stack/version context from the repo.
+- **Owned outputs:** `migration-plan.md`; upsert only the manifest entry assigned by handoff (`artifactOutputId`; fallback `migration-plan`) 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.
 
-```json
-{
-  "slug": "<slug>",
-  "currentAgent": "migration-specialist",
-  "state": "completed",
-  "updatedAt": "<ISO8601>"
-}
-```
-
-Hand off: orchestrator runs human gate (if configured), then `feature-developer` executes phases from the plan.
+Hand off: orchestrator/hook runs human gate (if configured), then `feature-developer` executes phases from the plan.
 
 ## Design guidance
 

package/presets/claude/next/agents/performance-auditor.md

@@ -50,18 +50,12 @@ Bundle chunks, Lighthouse hints, or measured timings.
 Ordered list for feature-developer if fixes are requested.
 ```
 
-## On completion
+## Artifact contract
 
-Update `status.json`:
-
-```json
-{
-  "slug": "<slug>",
-  "currentAgent": "performance-auditor",
-  "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 when present and the scoped git diff / routes under audit.
+- **Owned outputs:** `perf-report.md`; upsert only the manifest entry assigned by handoff (`artifactOutputId`; fallback `perf-report`) 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.
 
 For standalone `perf-audit` intent, suggest `/technical-retro` or a follow-up `/task` to implement fixes.
 

package/presets/claude/next/agents/qa-tester.md

@@ -35,18 +35,12 @@ When the task is mostly e2e, prefer invoking the dedicated `playwright-test-plan
 - Run relevant unit tests for changed modules.
 - Run affected e2e specs if feasible; report failures clearly.
 
-## On completion
-
-Update `status.json`:
-
-```json
-{
-  "slug": "<slug>",
-  "currentAgent": "qa-tester",
-  "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 brief/decomposition, reviewer notes when present, and prior implementation/validation artifacts.
+- **Owned outputs:** changed/added test paths (and any QA notes written under the slug dir); upsert only the manifest entry assigned by handoff (`artifactOutputId`; fallback `qa-tester`) 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.
 
 Provide summary:
 

package/presets/claude/next/agents/security-reviewer.md

@@ -48,19 +48,13 @@ PASS | PASS_WITH_NOTES | FAIL
 |------|--------|-------|
 ```
 
-## On completion
+## Artifact contract
 
-Update `status.json`:
+- **Authoritative inputs:** read `.claude/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the manifest entries for brief/decomposition, prior `review.md` when present, and the scoped git diff.
+- **Owned outputs:** `security-review.md`; upsert only the manifest entry assigned by handoff (`artifactOutputId`; fallback `security-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.
 
-```json
-{
-  "slug": "<slug>",
-  "currentAgent": "security-reviewer",
-  "state": "completed",
-  "updatedAt": "<ISO8601>"
-}
-```
-
-If **FAIL**, set `"state": "changes_requested"`.
+If **FAIL**, emit receipt outcome `changes_requested`.
 
 Do not modify production code.

package/presets/claude/next/agents/solution-architect.md

@@ -52,20 +52,14 @@ Write `.claude/team/tasks/<slug>/architecture.md`:
 - Flag when decomposition should change — list suggested updates for analyst/developer.
 - Do **not** write production code or tests.
 
-## On completion
+## Artifact contract
 
-Update `status.json`:
+- **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 applicable prior analysis artifacts.
+- **Owned outputs:** `architecture.md`; upsert only the manifest entry assigned by handoff (`artifactOutputId`; fallback `architecture`) 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.
 
-```json
-{
-  "slug": "<slug>",
-  "currentAgent": "solution-architect",
-  "state": "completed",
-  "updatedAt": "<ISO8601>"
-}
-```
-
-For `spike` intent with human gate after architect: set `"state": "awaiting_approval"` if design needs user sign-off.
+For `spike` intent needing user sign-off: emit receipt outcome `completed` (or `blocked` if design cannot proceed) and state the approval need in the receipt summary — the orchestration runtime/hook owns human-gate lifecycle (`awaiting_approval`), not this agent.
 
 Handoff: summary of design decisions and recommended next steps for developer.
 

package/presets/claude/next/agents/task-analyst.md

@@ -73,22 +73,9 @@ Create or update files under `.claude/team/tasks/<slug>/`:
 - `rules/architecture/feature-delivery-workflow.md` for layer order
 ```
 
-### `status.json`
+### Runtime state
 
-```json
-{
-  "slug": "<slug>",
-  "intent": "<from pipeline.json>",
-  "pipelineIndex": 0,
-  "currentAgent": "task-analyst",
-  "phase": "executing",
-  "state": "awaiting_approval",
-  "awaitingHumanGate": true,
-  "updatedAt": "<ISO8601>"
-}
-```
-
-If `pipeline.json` has `humanGates` including `after:task-analyst`, set `awaitingHumanGate: true`.
+The orchestration runtime/hook owns `status.json`; the analyst does not create or mutate lifecycle fields.
 
 Also write `.claude/team/active-task.json`:
 
@@ -104,7 +91,7 @@ Use kebab-case from the task title (e.g. `order-history-date-filter`). Max 48 ch
 
 When DoR is reached and artifacts are saved:
 
-1. Set `status.json` → `"phase": "executing"`, `"state": "awaiting_approval"`.
+1. Emit the analysis receipt; the runtime applies the configured human gate.
 2. Summarize brief and task count for the user.
 3. **Stop** and ask the user to review artifacts. Tell them to run `/task-continue <slug>` after approval or reply with corrections.
 
@@ -113,3 +100,10 @@ Do not invoke the developer or any implementation subagent.
 ## Design guidance (optional)
 
 - Optional: Load `design-guidance` (rule stem) when assessing structure, smells, or pattern fit — only when decomposing refactor/architecture tasks (not default).
+
+## Artifact contract
+
+- **Authoritative inputs:** read `.claude/team/tasks/<slug>/artifact-manifest.json` first; consume `pipeline.json`, the manifest routing entry, user-approved decisions, and any authoritative architecture/approval entries.
+- **Owned outputs:** `brief.md` and `decomposition.md`; upsert only the manifest entry assigned by handoff (`artifactOutputId`; fallback `analysis`) 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.

package/presets/claude/next/agents/task-router.md

@@ -55,6 +55,27 @@ Set optional top-level `"profile": "full" | "standard" | "light"` in `pipeline.j
 
 Fixtures: `.claude/team/fixtures/` (feature-full, feature-light, bugfix-standard).
 
+## Routing decision rubric
+
+Keep top-level `profile` and emit this top-level object in every new `pipeline.json`:
+
+```json
+"routingDecision": {
+  "complexity": "low | moderate | high",
+  "riskFlags": [],
+  "routingReasons": ["Concrete request signal and its routing consequence."],
+  "estimatedWorkPackages": 1,
+  "openDecisionCount": 0
+}
+```
+
+- `low`: one bounded layer/file set, explicit AC, reversible, no risk flags/open decisions → `light` when verification policy permits.
+- `moderate`: adjacent concerns or a regression/refactor with known boundaries → usually `standard`.
+- `high`: cross-layer/public API, security, migration/destructive or concurrency/state risk, broad e2e surface, unclear AC, or multiple work packages → usually `full`.
+- 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.
+
 ## Adjust steps (when context is clear)
 
 - Skip **task-analyst** if AC/scope fully specified → document in `skipped`.
@@ -95,7 +116,7 @@ Claude Code mapping when orchestrator invokes Agent tool: `cheap` → `haiku` (o
 
 ## Output
 
-Write `.claude/team/tasks/<slug>/pipeline.json` and initial `status.json` (write files; do not Shell-`mkdir` alone); set `.claude/team/active-task.json` → `{ "slug": "<slug>" }`. Minimal template — см. **`agents/README.md`**.
+Write `.claude/team/tasks/<slug>/pipeline.json` and initialize the routing entry in `artifact-manifest.json`; set `.claude/team/active-task.json`. The orchestration runtime creates and owns `status.json`.
 
 ## Handoff to orchestrator
 
@@ -107,6 +128,13 @@ Write `.claude/team/tasks/<slug>/pipeline.json` and initial `status.json` (write
 
 Do not invoke implementation agents yourself.
 
-## Metrics initialization
+## Runtime initialization
+
+Return the routing receipt to the orchestrator. The orchestration runtime/hook exclusively initializes and updates `status.json`, `metrics.json`, attempt identities, and gate lifecycle; the router does not write those shared runtime files.
+
+## Artifact contract
 
-Alongside `pipeline.json` and `status.json`, create `metrics.json` with `schemaVersion: 1`, immutable task dimensions, `task_started`, and a generated `runId`. Before the parent invokes each agent, append `attempt_started` and set `status.activeAttempts[attemptId]` with agent, step index, attempt number, and host-clock `startedAt`. For parallel work create one entry per agent; do not use `currentAgent` to identify their completion.
+- **Authoritative inputs:** read `.claude/team/tasks/<slug>/artifact-manifest.json` first; consume the user request and any existing authoritative task/decision entries.
+- **Owned outputs:** `pipeline.json` and the routing manifest entry; upsert only the manifest entry assigned by handoff (`artifactOutputId`; fallback `routing`) 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.

package/presets/claude/next/agents/tech-writer.md

@@ -42,19 +42,12 @@ Conventional commit / release note snippet.
 - Do not duplicate entire decomposition — summarize outcomes and how to use/extend.
 - May create or update files under `docs/**` when the task explicitly requests it; otherwise keep primary output in team artifacts.
 
-## On completion
-
-Update `status.json`:
-
-```json
-{
-  "slug": "<slug>",
-  "currentAgent": "tech-writer",
-  "phase": "executing",
-  "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 brief/decomposition and available architecture/migration/review artifacts.
+- **Owned outputs:** `documentation.md` (and any explicitly requested docs paths); upsert only the manifest entry assigned by handoff (`artifactOutputId`; fallback `documentation`) 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.
 
 Suggest `/technical-retro <slug>` when this is the final pipeline step.
 

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.