@bonesofspring/ai-rules 0.2.12 → 0.2.13

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## Unreleased
 
+### Agent artifact contracts
+
+- New shared-core schema SoT: `presets/_shared/core/agent-team/agent-artifact-contracts.md` — per-slug `artifact-manifest.json` (schema v1) as context index + completion receipts; markdown remains narrative evidence.
+- Agents upsert only owned manifest entries/receipts; the orchestration runtime/hook is the sole writer of `status.json` lifecycle fields and `metrics.json`.
+- All seven Cursor/Claude stack team docs and existing task-router, task-analyst, feature-developer, build-verifier, and code-reviewer prompts declare authoritative inputs, owned outputs, and terminal receipt outcomes (orchestration runtime/hook remains the sole writer of `status.json` / `metrics.json`; hook instrumentation for metrics and receipt reconciliation is covered below).
+- Added mirrored Next `artifact-manifest.example.json` fixtures and the `apply-agent-team-p0` dogfood pilot. Existing tasks without a manifest fall back to `brief.md`, `decomposition.md`, and `pipeline.json` and report the gap.
+
+### Agent-team routing rubric
+
+- New agent-team pipelines retain top-level `profile` and emit a structured `routingDecision` with `complexity`, `riskFlags`, auditable `routingReasons`, `estimatedWorkPackages`, and `openDecisionCount`.
+- Updated all seven Cursor routers and seven Claude twins with shared low/moderate/high heuristics and concrete risk signals. Next light/standard/full fixtures demonstrate the contract; existing pipelines without the optional block remain valid.
+
 ### Agent-task metrics
 
 - Added local schema-v1 `metrics.json` ledgers for agent-team pipelines: append-only task, attempt, retry, skip, completion, and human-gate lifecycle events. Allowlisted identifiers/timestamps/outcomes only (no prompts, secrets, file paths/contents, or remote telemetry). Shared-core policy: `presets/_shared/core/agent-team/agent-task-metrics.md` (requestable via orchestrator; no new always-on rule).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bonesofspring/ai-rules",
-  "version": "0.2.12",
+  "version": "0.2.13",
   "description": "Presets of Cursor and Claude rules/commands for Revy Ross personal use",
   "license": "MIT",
   "author": "Revy Ross",

package/presets/_shared/core/agent-team/agent-artifact-contracts.md

@@ -0,0 +1,114 @@
+# Agent artifact contracts
+
+Each pipeline slug has one context index and receipt ledger:
+
+- Cursor: `.cursor/team/tasks/<slug>/artifact-manifest.json`
+- Claude: `.claude/team/tasks/<slug>/artifact-manifest.json`
+
+Markdown remains the narrative evidence. The manifest identifies authoritative inputs and outputs; it does not duplicate report contents or replace `pipeline.json`, `status.json`, or `metrics.json`.
+
+## Schema v1
+
+```json
+{
+  "schemaVersion": 1,
+  "slug": "example-slug",
+  "updatedAt": "2026-07-31T12:00:00.000Z",
+  "artifacts": [
+    {
+      "id": "analysis",
+      "producer": "task-analyst",
+      "status": "completed",
+      "authoritativePaths": ["brief.md", "decomposition.md"],
+      "acceptanceCriteriaIds": ["AC-1"],
+      "taskIds": ["T1"],
+      "timestamps": {
+        "createdAt": "2026-07-31T11:55:00.000Z",
+        "updatedAt": "2026-07-31T12:00:00.000Z",
+        "completedAt": "2026-07-31T12:00:00.000Z"
+      },
+      "receipt": {
+        "outcome": "completed",
+        "summary": "Acceptance criteria and implementation tasks are ready.",
+        "evidencePaths": ["brief.md", "decomposition.md"]
+      }
+    }
+  ]
+}
+```
+
+### Required fields
+
+| Location | Field | Contract |
+|----------|-------|----------|
+| root | `schemaVersion` | Integer `1` |
+| root | `slug` | Matches the task directory |
+| root | `updatedAt` | ISO 8601 timestamp of the latest manifest update |
+| artifact | `id` | Stable, slug-local kebab-case identifier |
+| artifact | `producer` | Agent or orchestrator role that owns this entry |
+| artifact | `status` | `planned` \| `in_progress` \| `completed` \| `blocked` \| `superseded` |
+| artifact | `authoritativePaths` | Non-empty paths relative to the slug directory; the current sources of truth |
+| artifact | `acceptanceCriteriaIds` | Explicit IDs from `brief.md`; `[]` only when the task has no applicable AC |
+| artifact | `taskIds` | Explicit IDs from `decomposition.md`; `[]` only when no decomposition task applies |
+| artifact | `timestamps` | `createdAt`, `updatedAt`, and `completedAt` for terminal entries; ISO 8601 |
+| artifact | `receipt` | Required when `status` is terminal (`completed`, `blocked`, or `superseded`) |
+
+Unknown fields are ignored in schema v1 for forward compatibility. Producers must preserve entries and fields they do not own.
+
+## Context index conventions
+
+1. Before work, read the manifest first, then only the listed authoritative inputs needed by the current pipeline step.
+2. Pipeline steps may declare `artifactInputIds: string[]` and, for a single producer, `artifactOutputId: string`. Parallel steps use `artifactOutputIds: Record<agent, id>` so every producer has a distinct entry. The hook includes these assignments in the handoff.
+3. When these optional fields are omitted, use the default producer → entry map below. Repeated checkpoints for the same producer must set distinct output IDs; the fallback default is only safe when that producer has one active checkpoint in the pipeline.
+4. If the manifest is absent or unreadable, fall back to `brief.md`, `decomposition.md`, and `pipeline.json`, then report the gap.
+5. `authoritativePaths` points to current files, not globs and not historical alternatives. Mark an old entry `superseded` before replacing its authority.
+6. Every applicable acceptance criterion and decomposition task ID is traceable to at least one terminal entry.
+7. The manifest contains no prompts, secrets, report bodies, model claims, durations, or remote telemetry.
+
+## Completion receipts
+
+A producer finishes its step by upserting only its owned artifact entry and terminal receipt:
+
+- `outcome`: `completed` | `blocked` | `changes_requested` | `validation_failed`
+- `attemptId`: optional stable attempt ID supplied by the hook; when present it must match the active attempt
+- `summary`: one short factual sentence
+- `evidencePaths`: authoritative files that support the outcome
+
+`changes_requested` and `validation_failed` use artifact `status: "blocked"` while retaining their distinct receipt outcome. A later successful attempt updates the same owned entry to `completed`; timestamps and evidence must reflect the latest result. Do not infer success from a Markdown filename alone.
+
+`blocked` is terminal for the producer attempt but non-advancing for the pipeline: the hook persists `status.state` / `phase` as `blocked` and emits no next-agent handoff. A receipt must either carry the active `attemptId` or belong to the step's assigned output entry. Its terminal timestamp must be at or after the active attempt's `startedAt`; otherwise the hook keeps the attempt active in `awaiting_artifact_receipt` and does not advance or retry.
+
+## Ownership and writes
+
+- Agents own their output artifacts and their manifest entries/receipts. They merge by stable `id` and preserve all foreign entries.
+- The router owns `pipeline.json` and its routing manifest entry. The analyst owns analysis entries; implementers own implementation entries; reviewers and verifiers own their report entries.
+- The orchestration runtime/hook is the single writer for `status.json` lifecycle fields and `metrics.json`. Agents read status for eligibility but do not rewrite `pipelineIndex`, `currentAgent`, `state`, gates, retry fields, active attempts, timestamps, or metrics.
+- On `subagentStop`, the hook reconciles the completing producer's attempt-bound or assigned-output receipt and maps `completed` / `blocked` / `changes_requested` / `validation_failed` onto `status.state` before metrics terminal events and retry/advance logic. Tasks without a readable manifest retain the host-completion fallback. Parent orchestrators must not start the next step until reconciliation lands.
+- A producer never edits another producer's receipt. Corrections create a new owned entry or supersede an earlier entry owned by the same producer.
+- Parallel producers need distinct entry IDs. Their parent/orchestrator serializes manifest merges; agents must not use the shared manifest as a concurrency lock.
+
+## Default producer → entry map
+
+| Producer | Default entry `id` | Typical authoritative paths |
+|----------|--------------------|-----------------------------|
+| `task-router` | `routing` | `pipeline.json` |
+| `task-analyst` | `analysis` | `brief.md`, `decomposition.md` |
+| `solution-architect` | `architecture` | `architecture.md` |
+| `migration-specialist` | `migration-plan` | `migration-plan.md` |
+| `debugger` | `debug` | `debug-report.md` |
+| `ci-investigator` | `ci` | `ci-report.md` |
+| `feature-developer` | `implementation` | `implementation.md` (+ changed code/tests as listed) |
+| `build-verifier` | `validation` | `validation-report.md` |
+| `code-reviewer` | `review` | `review.md` |
+| `security-reviewer` | `security-review` | `security-review.md` |
+| `accessibility-reviewer` | `a11y-review` | `a11y-review.md` |
+| `performance-auditor` | `perf-report` | `perf-report.md` |
+| `api-contract-reviewer` | `api-contract-review` | `api-contract-review.md` |
+| `qa-tester` / unit or e2e planners | stack-native test IDs | plan/spec paths named in the agent prompt |
+| `tech-writer` | `documentation` | `documentation.md` |
+
+Use these defaults unless a step's `artifactOutputId` / `artifactOutputIds` assigns a distinct owned ID (parallel reviewers must not share one `id`). `artifactInputIds` defaults to the applicable authoritative entries already present in the manifest.
+
+## Minimal terminal handoff
+
+Report the owned entry ID, outcome, authoritative paths, covered AC/task IDs, and remaining gaps. The hook advances pipeline state from the terminal receipt; the agent receipt is evidence that drives the state transition, not a substitute for writing `status.json`.

package/presets/_shared/core/agent-team/agent-team-orchestrator.md

@@ -28,7 +28,7 @@ Roster of specialists is **stack-specific** (agent names and write scopes differ
 
 **Cursor frontmatter:** all team pipeline agents use `readonly: false` so they can write team artifacts. Production/app restrictions live in the agent prompt body — do **not** set `readonly: true`.
 
-Full prompts: stack `agents/*.md`. Artifact conventions: stack `team/README.md`.
+Full prompts: stack `agents/*.md`. Artifact conventions: stack `team/README.md`; schema SoT: **agent-artifact-contracts**.
 
 ## Dynamic pipeline
 
@@ -54,12 +54,60 @@ flowchart TD
 
 **Source of truth for order:** `pipeline.json` → `steps[]`. Never hardcode analyst → dev → review → QA when `pipeline.json` exists.
 
+## Routing decision contract
+
+Keep top-level `profile` (`light` | `standard` | `full`) and add a top-level `routingDecision` object:
+
+```json
+{
+  "profile": "standard",
+  "routingDecision": {
+    "complexity": "moderate",
+    "riskFlags": ["behavior-regression"],
+    "routingReasons": [
+      "The failure needs root-cause analysis before a bounded fix.",
+      "Behavior changes require validation and independent review."
+    ],
+    "estimatedWorkPackages": 1,
+    "openDecisionCount": 0
+  }
+}
+```
+
+| Field | Contract |
+|-------|----------|
+| `complexity` | `low` \| `moderate` \| `high`; classify scope and coordination, not perceived coding difficulty |
+| `riskFlags` | Array of concrete signals such as `public-contract`, `cross-layer`, `security-sensitive`, `migration`, `destructive`, `concurrency-state`, `external-dependency`, `unclear-acceptance-criteria`, `broad-test-surface`, `behavior-regression` |
+| `routingReasons` | Non-empty, auditable facts from the request; each reason explains a profile, gate, specialist, skip, or checkpoint choice |
+| `estimatedWorkPackages` | Integer ≥1; count meaningful independently verifiable delivery scopes, not files or agents |
+| `openDecisionCount` | Integer ≥0; unresolved product/architecture/contract choices at routing time |
+
+Rubric:
+
+- `low`: one bounded scope, explicit acceptance criteria, reversible change, no risk flags or open decisions. Use `light` only when stack verification policy permits.
+- `moderate`: several files or adjacent concerns, a regression/refactor with known boundaries, or one contained risk flag. Usually `standard`.
+- `high`: cross-layer/public-contract work, migration/destructive/security/concurrency risk, broad test surface, multiple work packages, or unclear acceptance criteria. Usually `full`.
+- Increase the profile when risk, open decisions, or required checkpoints demand it; do not lower complexity merely because the implementation is familiar.
+- Do not write generic reasons such as “standard by default.” Name the observed signal and the routing consequence.
+
+Existing pipelines without `routingDecision` remain valid; routers emit it for new pipelines. The block is documentary routing evidence in P0 and does not change hook behavior.
+
 ## Metrics lifecycle
 
-For local metrics policy and the `metrics.json` ledger, see **agent-task-metrics**. The router records `task_started` and one `attempt_started` before each invocation; the hook records host-clock terminal and human-gate events. Keep active attempt identities in `status.json.activeAttempts` so parallel completions can be bound safely.
+For local metrics policy and the `metrics.json` ledger, see **agent-task-metrics**. The orchestration runtime records `task_started` and one `attempt_started` before each invocation; the hook records host-clock terminal and human-gate events. Keep active attempt identities in `status.json.activeAttempts` so parallel completions can be bound safely.
 
 Do not calculate durations in agents. For parallel steps, never attribute a stop using `currentAgent` alone: use a stable runtime identity, the sole active attempt, or an explicit receipt marked with fallback confidence.
 
+## Artifact context index and receipts
+
+Each slug has one `artifact-manifest.json`: `.cursor/team/tasks/<slug>/` or `.claude/team/tasks/<slug>/`. The full schema and completion conventions live in **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 points to authoritative paths and records producer, status, 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 unrelated 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)
 
 ```json
@@ -72,10 +120,19 @@ Do not calculate durations in agents. For parallel steps, never attribute a stop
   "state": "in_progress",
   "awaitingHumanGate": false,
   "activeAttempts": {},
-  "lastCompletedAttempt": null
+  "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 |
+
 | state | Meaning |
 |-------|---------|
 | `in_progress` | Current step running |
@@ -84,6 +141,8 @@ Do not calculate durations in agents. For parallel steps, never attribute a stop
 | `changes_requested` | Reviewer blocked; re-run developer (`retryAfterFix`) |
 | `validation_failed` | build-verifier failed; re-run developer then build-verifier |
 
+On each `subagentStop`, the hook reconciles `status.state` from the completing producer's terminal `artifact-manifest.json` receipt (`completed` \| `changes_requested` \| `validation_failed`) when agents left lifecycle fields untouched. Parent orchestrators must wait for that handoff before invoking the next step.
+
 ## Pipeline step options
 
 | Field | Use |
@@ -99,7 +158,7 @@ Do not calculate durations in agents. For parallel steps, never attribute a stop
 2. Read `pipeline.json` before every subagent invocation.
 3. One role per Task call — **except** parallel steps: multiple Task calls in one message.
 4. **Never** skip `humanGates` without `/task-continue` or explicit user approval.
-5. Persist handoffs to disk (`brief.md`, `decomposition.md`, `debug-report.md`, `validation-report.md`, `architecture.md`, `migration-plan.md`, `ci-report.md`, `a11y-review.md`, `perf-report.md`, `security-review.md`, `api-contract-review.md`, `unit-test-plan.md`, `documentation.md`, `review.md`).
+5. Persist handoffs to disk (`brief.md`, `decomposition.md`, `debug-report.md`, `validation-report.md`, `architecture.md`, `migration-plan.md`, `ci-report.md`, `a11y-review.md`, `perf-report.md`, `security-review.md`, `api-contract-review.md`, `unit-test-plan.md`, `documentation.md`, `review.md`) and update the producer-owned terminal receipt in `artifact-manifest.json`.
 6. On `changes_requested` from reviewers: hook sets `retryAfterFix` → developer → same reviewer.
 7. On `validation_failed` from `build-verifier`: hook sets `retryAfterFix: build-verifier` → developer → build-verifier.
 8. When all steps complete, suggest `/technical-retro <slug>`.
@@ -124,7 +183,7 @@ Use Task tool or `/agent-name`. Pass: slug, artifact paths, step `scope` if set.
    - **`strong`** → **never** pass `fast`; rely on agent pin or parent Max model.
 3. Parallel steps: apply the step-level `model` to **each** agent in the array (or omit → each agent’s own 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/go/agents/build-verifier.md

@@ -12,8 +12,8 @@ You are the build verifier for **Go hexagonal** services (and for **ai-rules pre
 1. Run from module root: `go test ./...`, `go vet ./...`.
 2. If present: `golangci-lint` / `staticcheck` per repo docs (`go-tooling`, `post-change-test`).
 3. Optional `-race` when concurrency touched.
-4. Write `.cursor/team/tasks/<slug>/validation-report.md` with commands + results.
-5. On failure: set status `validation_failed` — do **not** patch production code (developer retries).
+4. Write `.claude/team/tasks/<slug>/validation-report.md` with commands + results.
+5. On failure: emit receipt outcome `validation_failed` — do **not** patch production code (developer retries).
 
 **Never** require Playwright, XCUITest, `lint:js`/`lint:css`, or `xcodebuild`/`SwiftLint` as the Go gate.
 
@@ -33,3 +33,10 @@ Document PASS/FAIL in `validation-report.md`.
 2. **Hooks cookbook:** default `hooks.json` must **not** reference `hooks/examples/` → **FAIL** if it does.
 3. **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`.
 4. **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`.
+
+## Artifact contract
+
+- **Authoritative inputs:** read `.claude/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the manifest entries for brief/decomposition, implementation evidence, pipeline scope, and changed files.
+- **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/go/agents/code-reviewer.md

@@ -33,8 +33,15 @@ Apply skill `code-review` and `code-review-mr.mdc`. Weigh `architecture-boundari
 
 ## Artifact
 
-Write `.claude/team/tasks/<slug>/review.md` with verdict APPROVE | REQUEST_CHANGES, findings by severity, AC coverage. Update `status.json` accordingly.
+Write `.claude/team/tasks/<slug>/review.md` with verdict APPROVE | REQUEST_CHANGES, findings by severity, AC coverage. Update the owned terminal receipt accordingly.
 
 ## 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/go/agents/feature-developer.md

@@ -36,7 +36,7 @@ Implement Go features following hexagonal boundaries.
 
 When editing ai-rules `presets/**/go/**`, keep Cursor/Claude twins in sync and preserve chain fork ≠ next/ios-swift.
 
-Update `.claude/team/tasks/<slug>/implementation.md` and `status.json`.
+Update `.claude/team/tasks/<slug>/implementation.md` and the owned implementation receipt.
 
 ## Design guidance
 
@@ -45,3 +45,10 @@ Update `.claude/team/tasks/<slug>/implementation.md` and `status.json`.
 ## Anti-sycophancy discipline
 
 - When writing or changing code, load / follow rule `anti-sycophancy-discipline`.
+
+## 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/go/agents/task-analyst.md

@@ -18,8 +18,15 @@ Use domain, application/ports, driving/driven adapters, composition root — not
 
 ## Gates
 
-Set `awaiting_approval` when humanGates require it after analysis.
+Emit an analysis receipt; the runtime applies any configured human gate.
 
 ## 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/go/agents/task-router.md

@@ -10,7 +10,7 @@ You are a task router for a **Go hexagonal backend** agent team. You **do not**
 ## Inputs
 
 - User task description (from `/task` or orchestrator).
-- Optional: existing files under `.cursor/team/tasks/<slug>/`.
+- Optional: existing files under `.claude/team/tasks/<slug>/`.
 - Pipeline JSON schema — **`agents/README.md`**.
 
 ## Intent detection
@@ -39,6 +39,27 @@ You are a task router for a **Go hexagonal backend** agent team. You **do not**
 
 **Never skip `build-verifier`** after developer when Go sources changed.
 
+## 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 contract, security, migration/destructive or concurrency/state risk, broad integration-test 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.
+
 ## Model tiers (`steps[].model`)
 
 Optional: `"model": "cheap" | "standard" | "strong"`. Same policy as other presets:
@@ -47,7 +68,7 @@ Optional: `"model": "cheap" | "standard" | "strong"`. Same policy as other prese
 - `full` / `spike` / security|perf specialists → `strong` on architect, migration, security, perf steps
 - never `strong` on build-verifier / tech-writer / task-router
 
-Fixtures: `.cursor/team/fixtures/` (feature-full, feature-light, bugfix-standard).
+Fixtures: `.claude/team/fixtures/` (feature-full, feature-light, bugfix-standard).
 
 ## humanGates (defaults)
 
@@ -62,12 +83,19 @@ Fixtures: `.cursor/team/fixtures/` (feature-full, feature-light, bugfix-standard
 
 ## Output
 
-Write `.cursor/team/tasks/<slug>/pipeline.json` and initial `status.json` via the **Write** tool (creates parents; do not Shell-`mkdir`); set `.cursor/team/active-task.json`.
+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
 
 Intent + steps table + skipped + gates → invoke `steps[0].agent` (unless retro).
 
-## 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/go/commands/task.md

@@ -24,14 +24,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>`).
 
 ## Не делать
 
@@ -50,4 +52,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.