@bonesofspring/ai-rules 0.2.12 → 0.2.14

package/presets/claude/mcp-ts/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).

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

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

package/presets/claude/mcp-ts/rules/tooling-and-review/preset-token-budget.md

@@ -9,6 +9,7 @@ paths:
 
 <!-- shared-core: meta/preset-token-budget.md -->
 
+
 # Preset token budget
 
 Инварианты загрузки правил в **установленном** пресете (consumer app).

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

@@ -9,6 +9,7 @@ paths:
 
 <!-- shared-core: meta/preset-twin-sync.md -->
 
+
 # Preset twin sync
 
 Cursor `.mdc` — **SoT per stack**. Claude topic `.md` — derived twin.
@@ -18,6 +19,8 @@ Cursor `.mdc` — **SoT per stack**. Claude topic `.md` — derived twin.
 | Stack | Cursor SoT | Claude derive | Mapping table |
 |-------|------------|---------------|---------------|
 | `next` | `presets/cursor/next/rules/*.mdc` | `presets/claude/next/rules/<topic>/` | **Required** in `claude/next/rules/README.md` |
+| `nuxt` | `presets/cursor/nuxt/rules/*.mdc` | `presets/claude/nuxt/rules/<topic>/` | **Required** in `claude/nuxt/rules/README.md` |
+| `svelte` | `presets/cursor/svelte/rules/*.mdc` | `presets/claude/svelte/rules/<topic>/` | **Required** in `claude/svelte/rules/README.md` |
 | `ios-swift` | `presets/cursor/ios-swift/rules/*.mdc` | `presets/claude/ios-swift/rules/<topic>/` | Keep in `claude/ios-swift/rules/README.md` |
 | `go` | `presets/cursor/go/rules/*.mdc` | `presets/claude/go/rules/<topic>/` | Keep in `claude/go/rules/README.md` |
 | `java` | `presets/cursor/java/rules/*.mdc` | `presets/claude/java/rules/<topic>/` | Keep in `claude/java/rules/README.md` |
@@ -40,6 +43,8 @@ Cursor `.mdc` — **SoT per stack**. Claude topic `.md` — derived twin.
 ## Severity (build-verifier)
 
 - **next:** missing Claude twin for a changed Cursor rule → **FAIL** (mapping table required).
+- **nuxt:** missing Claude twin for a changed Cursor rule → **FAIL** (mapping table required).
+- **svelte:** missing Claude twin for a changed Cursor rule → **FAIL** (mapping table required).
 - **ios-swift:** missing Claude twin for a changed Cursor rule → **FAIL**.
 - **go:** missing Claude twin for a changed Cursor rule → **FAIL** (same as next / ios-swift; mapping table required).
 - **java:** missing Claude twin for a changed Cursor rule → **FAIL** (same as next / ios-swift / go; mapping table required).

package/presets/claude/mcp-ts/team/README.md

@@ -16,10 +16,21 @@ Phase 1 agents: see `agents/README.md`.
 
 Do **not** name Phase 2 agents (`contract-test-*`, `debugger`, Playwright stems, etc.) in fixture JSON — even as skips. Defer those until the agents ship.
 
+## Artifact manifest and receipts
+
+Each slug stores one context index at `.claude/team/tasks/<slug>/artifact-manifest.json`. Schema v1 is defined by shared core `agent-team/agent-artifact-contracts.md`: every entry declares its producer, status, authoritative paths, acceptance-criteria IDs, decomposition task IDs, timestamps, and a terminal completion receipt.
+
+Producer/consumer rules:
+
+- Read the manifest first and use only the authoritative inputs needed by the current step; fall back to `brief.md`, `decomposition.md`, and `pipeline.json` when it is missing or stale, and report that gap.
+- Producers upsert only their stable entry IDs, preserve foreign entries, and finish with `completed`, `blocked`, `changes_requested`, or `validation_failed` receipt evidence.
+- The router owns `pipeline.json` and its routing entry; analyst, developer, verifier, and reviewer own their named outputs and receipts. Consumers do not edit another producer's receipt.
+- Agents do not mutate `status.json` or `metrics.json`. The orchestration runtime/hook is their single writer. Parallel receipt merges are serialized by the parent/orchestrator.
+
 ## Local metrics ledger
 
-`metrics.json` is an append-only schema-v1 event ledger for one task run. It contains only allowlisted IDs, task dimensions, timestamps, outcomes, and attribution confidence—never prompts, secrets, file paths, or contents. The router writes `task_started` / `attempt_started`; the hook records host-clock completion and human-gate edges under a per-task lock with temp-and-rename.
+`metrics.json` is an append-only schema-v1 event ledger for one task run. It contains only allowlisted IDs, task dimensions, timestamps, outcomes, and attribution confidence—never prompts, secrets, file paths, or contents. The orchestration runtime writes `task_started` / `attempt_started`; the hook records host-clock completion and human-gate edges under a per-task lock with temp-and-rename.
 
-`status.json.activeAttempts` is a transient timing bridge keyed by `attemptId`; `lastCompletedAttempt` is diagnostic. For parallel stops, the hook must use a stable payload identity or the sole active attempt. Otherwise an explicit `.metrics-receipts.json` receipt is fallback data marked `source: agent`, `attributionConfidence: fallback`; it must never guess from `currentAgent`.
+`status.json.activeAttempts` is a transient timing bridge keyed by `attemptId`; `lastCompletedAttempt` is diagnostic; `parallelOutcomes` holds per-agent outcomes for the current parallel join until the step advances. For parallel stops, the hook must use a stable payload identity or the sole active attempt. Otherwise an explicit `.metrics-receipts.json` receipt is fallback data marked `source: agent`, `attributionConfidence: fallback`; it must never guess from `currentAgent`.
 
 Aggregate with `node packages/ai-rules/scripts/aggregate-agent-task-metrics.mjs --team-root .claude/team`. It reports role/agent count, completed count, total/average duration, distinct completed run IDs, separate human-gate wait, and incomplete artifacts.

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

@@ -47,19 +47,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, implementation or UI diff scope, and prior review artifacts when present.
+- **Owned outputs:** `a11y-review.md`; upsert only the manifest entry assigned by handoff (`artifactOutputId`; fallback `a11y-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": "accessibility-reviewer",
-  "state": "completed",
-  "updatedAt": "<ISO8601>"
-}
-```
-
-If **FAIL**, set `"state": "changes_requested"` and list specific fixes for `feature-developer`.
+If **FAIL**, emit receipt outcome `changes_requested` and list specific fixes for `feature-developer`.
 
 Do not modify production code or tests.

package/presets/claude/next/agents/api-contract-reviewer.md

@@ -51,19 +51,13 @@ Link or path to spec/ticket.
 For feature-developer before or during implementation.
 ```
 
-## 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, architecture when present, and changed types/API/mocks against the contract docs.
+- **Owned outputs:** `api-contract-review.md`; upsert only the manifest entry assigned by handoff (`artifactOutputId`; fallback `api-contract-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": "api-contract-reviewer",
-  "state": "completed",
-  "updatedAt": "<ISO8601>"
-}
-```
-
-If **MISALIGNED**, set `"state": "changes_requested"` when blocking implementation.
+If **MISALIGNED**, emit receipt outcome `changes_requested` when blocking implementation.
 
 Do not modify production code.

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

@@ -35,14 +35,14 @@ When validating **preset packaging** changes (paths under `packages/ai-rules/pre
 2. **Leakage (next):** hooks/agents must not require `xcuitest-test-*` handoffs or `xcodebuild` as the default Next post-change gate. See `tooling-and-review/preset-no-cross-stack-leakage.md`.
 3. **Mapping / README:** `rules/README.md` must include a Cursor→Claude mapping table; document core→stack mapping when `_shared` consumers exist.
 4. **shared-core consumers:** if `_shared/core/**` changed, every file with matching `<!-- shared-core: … -->` in this PR must be updated (or intentional fork documented).
-5. **Twin presence:** Cursor rule change without Claude twin same PR → **FAIL** (next, ios-swift, go, java, mcp-ts, php-hexagonal, and php-laravel). Domain twin body ≥15 lines; thin aliases may be shorter.
+5. **Twin presence:** Cursor rule change without Claude twin same PR → **FAIL** (next, nuxt, svelte, ios-swift, go, java, mcp-ts, php-hexagonal, and php-laravel). Domain twin body ≥15 lines; thin aliases may be shorter.
 6. **Session-start body budget:** sum body lines of the **3** intended session-start rules ≤ **140** (stretch ≤120); do **not** include `**/README.md` — record in validation-report; FAIL if grossly over.
 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|nuxt|svelte|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`.
+11. **Performance skill by stack:** next → `react-performance`; nuxt → `vue-performance`. **No react-performance/vue-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`.
 
 ### Soft notes
@@ -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.