@bonesofspring/ai-rules 0.2.10 → 0.2.12

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

@@ -0,0 +1,41 @@
+---
+description: Preset authoring meta-rule (preset-token-budget)
+paths:
+  - packages/ai-rules/presets/**/*
+  - .claude/**/*
+  - .cursor/rules/**/*
+  - .cursor/team/tasks/**/*
+---
+
+<!-- shared-core: meta/preset-token-budget.md -->
+
+# Preset token budget
+
+Инварианты загрузки правил в **установленном** пресете (consumer app).
+
+## Hard caps
+
+| Platform | Always-on | Cap |
+|----------|-----------|-----|
+| Cursor | `alwaysApply: true` | **≤ 3** |
+| Claude | rules **without** `paths:` | **ровно 3** |
+
+**Claude Option A (README exclusion):** when counting Claude rules without `paths:` / session-start, **exclude `**/README.md`** (topic indexes are not session-start rules). The intended session-start trio remains **exactly 3**; body budget sums **only those 3** rules.
+
+Session-start body budget (где задокументировано): ≤140 строк суммарно (stretch ≤120).
+
+## Meta / author rules
+
+Rules for preset authors (`preset-layering`, `preset-twin-sync`, …):
+
+- **Never** `alwaysApply: true` on consumer installs.
+- Cursor: `globs` limited to `packages/ai-rules/presets/**` (and dogfood `.cursor/**` where useful).
+- Claude: `paths:` limited to `packages/ai-rules/presets/**` (and `.claude/**` dogfood if present).
+
+## Heavy workflows
+
+Orchestrator, feature-delivery, code-review, post-change gates, domain globs — **requestable / paths**, not always-on.
+
+## Verifier
+
+build-verifier **FAIL** if alwaysApply / session-start count exceeds 3 (Claude count **excludes `**/README.md`**), or if a `preset-*` meta rule is marked always-on.

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

@@ -0,0 +1,50 @@
+---
+description: Preset authoring meta-rule (preset-twin-sync)
+paths:
+  - packages/ai-rules/presets/**/*
+  - .claude/**/*
+  - .cursor/rules/**/*
+  - .cursor/team/tasks/**/*
+---
+
+<!-- shared-core: meta/preset-twin-sync.md -->
+
+# Preset twin sync
+
+Cursor `.mdc` — **SoT per stack**. Claude topic `.md` — derived twin.
+
+## Matrix
+
+| 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` |
+| `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` |
+| `mcp-ts` | `presets/cursor/mcp-ts/rules/*.mdc` | `presets/claude/mcp-ts/rules/<topic>/` | Keep in `claude/mcp-ts/rules/README.md` |
+| `php-hexagonal` | `presets/cursor/php-hexagonal/rules/*.mdc` | `presets/claude/php-hexagonal/rules/<topic>/` | Keep in `claude/php-hexagonal/rules/README.md` |
+| `php-laravel` | `presets/cursor/php-laravel/rules/*.mdc` | `presets/claude/php-laravel/rules/<topic>/` | Keep in `claude/php-laravel/rules/README.md` |
+
+## Same-PR checklist
+
+1. Edit Cursor rule first (body + frontmatter).
+2. Update Claude twin: body + `paths:` (from Cursor `globs:` / requestable triggers); drop `alwaysApply`.
+3. Update mapping table row if stem/path changed.
+4. If body embeds core (`<!-- shared-core: … -->`), sync core consumers across stacks when core changed.
+
+## Twin depth
+
+- **Domain** rules: ≥15 body lines (FAIL if thin without documented alias reason).
+- **Thin aliases** (`agent-team-intake`, `technical-retro`): may be shorter (soft) if they only point to a command/skill.
+
+## Severity (build-verifier)
+
+- **next:** 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).
+- **mcp-ts:** missing Claude twin for a changed Cursor rule → **FAIL** (same as next / ios-swift / go / java; mapping table required).
+- **php-hexagonal:** missing Claude twin for a changed Cursor rule → **FAIL** (same as next / ios-swift / go / java / mcp-ts; mapping table required).
+- **php-laravel:** missing Claude twin for a changed Cursor rule → **FAIL** (same as next / ios-swift / go / java / mcp-ts / php-hexagonal; mapping table required).
+
+Dogfood: sync packages → root `.cursor/` after Cursor SoT changes (not the reverse). Use `packages/ai-rules/scripts/sync-dogfood-cursor.sh`.

package/presets/claude/mcp-ts/rules/tooling-and-review/security-mcp.md

@@ -0,0 +1,52 @@
+---
+description: MCP security: injection boundaries, capability minimization, SSRF/secrets
+paths:
+  - src/tools/**/*
+  - src/resources/**/*
+  - "**/auth/**/*"
+  - "**/config/**/*"
+---
+
+# Security (MCP servers)
+
+- Treat tool **arguments** as **untrusted**. Validate with schemas; canonicalize paths/URLs.
+- Minimize capabilities: no default "read any file" / "fetch any URL" without AC and allowlists.
+- Secrets: env/secret manager only; redact in logs and tool results (`mcp-auth-secrets`).
+- Least privilege: each tool gets the smallest capability adapter it needs — no ambient `process.env` dumps.
+
+## Path traversal (FAIL patterns)
+
+- Resolve with `path.resolve` (or equivalent) then require the result stays under an approved root (`path.relative` must not start with `..`).
+- Deny `../`, encoded variants (`%2e%2e`), and null-byte tricks before FS access.
+- Follow symlinks only if the **final** realpath is still inside the root — otherwise reject.
+- Unit shapes: `tool.rejectsPathTraversal`, `tool.rejectsSymlinkEscape`, `tool.acceptsInRoot`.
+
+## SSRF / outbound URL (FAIL patterns)
+
+When tools fetch URLs:
+
+- Allowlist hosts (or deny by default); block metadata IP `169.254.169.254`, link-local (`169.254.0.0/16`), loopback when not explicitly local-dev, and private ranges unless AC says otherwise.
+- Do not follow redirects to a host outside the allowlist; re-validate after each hop.
+- Prefer literal IPs from a resolved allowlist over trusting DNS alone when policy requires it.
+- Unit shapes: `tool.deniesMetadataIp`, `tool.deniesBlockedHost`, `tool.allowsAllowlistedHost`.
+
+## Prompt injection and untrusted content
+
+- Tool **descriptions** and **results** must not instruct the model to ignore safety; handlers must not execute model-supplied shell without an explicit, reviewed design.
+- Treat **retrieved** tool/resource/prompt content (and any fetched remote payload) as **untrusted data**, not as authority:
+  - It must **not** expand tool capabilities, change auth/scopes, or trigger shell/network/FS side effects merely because the content contains instructions.
+  - Handlers decide actions from validated args + trusted request context only — never from natural-language directives inside resource bodies or prior tool output.
+  - Do not echo secrets found in untrusted content into logs or subsequent tool results.
+
+## Forbidden
+
+- Shipping live credentials in examples or fixtures.
+- Echoing `process.env` or Authorization headers into tool output.
+- Fail-open auth when remote transport is enabled.
+- Broad "run arbitrary command" tools without explicit AC and sandboxing.
+- Letting tool/resource text escalate privileges or bypass schema/auth checks.
+
+## Agents
+
+- `security-reviewer` on tool/auth/config/capability changes; then `post-change-test`.
+- Phase 1: feature-developer must not skip schema validation to "move faster".

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

@@ -0,0 +1,18 @@
+---
+description: Technical retrospective facilitator (on-demand /technical-retro)
+paths:
+  - .cursor/team/**/*
+  - .claude/team/**/*
+---
+
+<!-- shared-core: review/technical-retro.md -->
+
+# Техническое ретро — rule alias
+
+Полный сценарий (включая блок **«Работа агентов»** для slug из team tasks) — в slash-команде:
+
+**`commands/technical-retro.md`** → `/technical-retro`
+
+When a task has `metrics.json`, use the local aggregation script and state the cohort, sample size, incomplete artifacts, attribution confidence, active attempt duration, and human-gate wait separately. Do not score malformed artifacts or gate wait as agent work.
+
+Используй rule только если command недоступен. Не дублируй содержимое command в ответе — следуй command-файлу и skill `technical-retro`.

package/presets/claude/mcp-ts/rules/ui-and-accessibility/README.md

@@ -0,0 +1,3 @@
+# UI and accessibility
+
+N/A — TypeScript MCP server preset. No UI/a11y rules or accessibility-reviewer agent.

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

@@ -0,0 +1,12 @@
+# Skills (mcp-ts Phase 1)
+
+| Skill | Use |
+|-------|-----|
+| `feature-delivery` | End-to-end MCP feature flow |
+| `unit-testing` | Schema/handler unit tests |
+| `code-review` | Diff review checklist |
+| `debug-investigation` | Bug investigation |
+
+Phase 2 may add `ci-investigation`, `technical-retro`, `write-adr`, `mcp-contract-testing` skills.
+
+Until then: `/technical-retro` uses `commands/technical-retro.md` (no skill required); review-only uses skill `code-review` on the parent (no `code-reviewer` agent).

package/presets/claude/mcp-ts/skills/code-review/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: code-review
+description: Reviews MCP TypeScript diffs for boundaries, schema contracts, capability scope, and secrets. Use for MR review or when code-review workflow is requested.
+---
+
+# Code review (mcp-ts)
+
+1. Follow `code-review-mr.mdc`, `mcp-server-boundaries.mdc`, `mcp-tool-design.mdc`, `security-mcp.mdc`.
+2. Flag monolithic entry files, schema/protocol mismatches, unscopeed capabilities, secret leakage.
+3. Phase 1: security-reviewer covers threat model; no separate `code-reviewer` agent yet — parent may apply this skill directly.

package/presets/claude/mcp-ts/skills/debug-investigation/SKILL.md

@@ -0,0 +1,11 @@
+---
+name: debug-investigation
+description: Investigates MCP server bugs with runtime evidence — schema failures, handler errors, transport startup. Use for failing tests or incorrect tool behavior.
+---
+
+# Debug investigation (mcp-ts)
+
+1. Reproduce with unit/contract fixtures before changing code.
+2. Check schema validation vs handler logic vs registration wiring.
+3. Prefer repository tests over ad-hoc Inspector-only claims.
+4. Load `anti-sycophancy-discipline` — report what was verified.

package/presets/claude/mcp-ts/skills/feature-delivery/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: feature-delivery
+description: Delivers TypeScript MCP server features end-to-end across contracts, schemas, handlers, registration, tests, and package validation. Use when implementing or extending a feature, especially through /task or feature-developer.
+---
+
+# Feature Delivery (mcp-ts)
+
+1. Read brief, AC, and decomposition.
+2. Follow `feature-delivery-workflow.mdc` + `reference-features.mdc`: contract → schema → handler → register → unit/contract tests → package validation.
+3. Keep transport/lifecycle in the entry module; tools stay in registration modules.
+4. After TS edits: **invoke** `post-change-test.mdc` (+ `mcp-ts-tooling.mdc`).
+
+## Do / Don't
+
+- **Do** Zod-first authoring with JSON Schema-compatible protocol contracts.
+- **Don't** invent SDK APIs; use VERIFY markers / Context7.
+- **Don't** use Playwright, XCUITest, Next lint, or Go tools as this stack's gate.
+
+## Scope discipline
+
+Implement only the current AC / decomposition task. See `feature-developer` → **Zero improvisation**.
+
+## Handoff
+
+Summarize by layer + validation. Update `.cursor/team/tasks/<slug>/status.json`.
+
+## Design guidance
+
+- Load `design-guidance` (rule stem) when assessing structure, smells, or pattern fit.

package/presets/claude/mcp-ts/skills/unit-testing/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: unit-testing
+description: Plans and writes unit tests for MCP schemas and handlers using the repository test runner. Use for schema/handler coverage and fixing failing unit tests.
+---
+
+# Unit testing (mcp-ts)
+
+1. Prefer table-driven tests for schema reject/accept and handler outcomes.
+2. Fake FS/network capabilities — no live MCP client required for unit scope.
+3. Follow `tests-unit.mdc` and `mcp-contract-testing.mdc`.
+4. Discover runner via `mcp-ts-tooling` (Vitest/Jest/node:test).
+
+## Out of scope (Phase 1)
+
+- Dedicated `contract-test-*` agents (Phase 2).
+- Browser e2e (Playwright) — forbidden.

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

@@ -0,0 +1,25 @@
+# Team artifacts (mcp-ts)
+
+| Path | Purpose |
+|------|---------|
+| `tasks/<slug>/` | Pipeline artifacts (`brief.md`, `status.json`, …) |
+| `fixtures/` | Example pipelines for dogfood |
+| `conventions.md` | Living gotchas (consumer-owned) |
+
+Phase 1 agents: see `agents/README.md`.
+
+## Fixture policy (Phase 1)
+
+`team/fixtures/*.json` may list in `skipped[]` **only** agents that exist in the Phase 1 roster:
+
+`task-router`, `task-analyst`, `solution-architect`, `feature-developer`, `build-verifier`, `security-reviewer`.
+
+Do **not** name Phase 2 agents (`contract-test-*`, `debugger`, Playwright stems, etc.) in fixture JSON — even as skips. Defer those until the agents ship.
+
+## 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.
+
+`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`.
+
+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/mcp-ts/team/conventions.md

@@ -0,0 +1,14 @@
+# Team conventions (mcp-ts)
+
+Fill after init with living gotchas for this MCP server repo.
+
+## Suggested topics
+
+- Package manager + test/typecheck scripts actually used
+- SDK version pin and VERIFY notes
+- stdio entry / `bin` packaging
+- Capability allowlists (FS roots, outbound hosts)
+
+## Fixture policy
+
+Phase 1 fixtures: `skipped[]` may name only Phase 1 roster agents (see `team/README.md`).

package/presets/claude/mcp-ts/team/fixtures/bugfix-standard.json

@@ -0,0 +1,32 @@
+{
+  "slug": "example-schema-bugfix",
+  "intent": "bugfix",
+  "profile": "standard",
+  "summary": "Fix schema validation rejecting valid tool input",
+  "steps": [
+    {
+      "agent": "task-analyst",
+      "label": "Reproduce + AC"
+    },
+    {
+      "agent": "feature-developer",
+      "label": "Fix schema/handler + tests"
+    },
+    {
+      "agent": "build-verifier",
+      "label": "typecheck + tests"
+    }
+  ],
+  "humanGates": [],
+  "autoChain": true,
+  "skipped": [
+    {
+      "agent": "security-reviewer",
+      "reason": "Proven schema/style-only bugfix — no auth/**, secrets, or FS/net capability change (document skip; otherwise route security-reviewer)"
+    },
+    {
+      "agent": "solution-architect",
+      "reason": "Localized schema bugfix"
+    }
+  ]
+}

package/presets/claude/mcp-ts/team/fixtures/feature-full.json

@@ -0,0 +1,33 @@
+{
+  "slug": "example-add-tool-full",
+  "intent": "feature",
+  "profile": "full",
+  "summary": "Add MCP tool with schema, handler, registration, and tests",
+  "steps": [
+    {
+      "agent": "task-analyst",
+      "label": "Brief + decomposition"
+    },
+    {
+      "agent": "feature-developer",
+      "label": "contract→schema→handler→register→test→package"
+    },
+    {
+      "agent": "build-verifier",
+      "label": "typecheck + tests"
+    },
+    {
+      "agent": "security-reviewer",
+      "label": "Capability / secrets review",
+      "model": "strong"
+    }
+  ],
+  "humanGates": ["after:task-analyst"],
+  "autoChain": true,
+  "skipped": [
+    {
+      "agent": "solution-architect",
+      "reason": "Straightforward tool add; architecture spike not required"
+    }
+  ]
+}

package/presets/claude/mcp-ts/team/fixtures/feature-light.json

@@ -0,0 +1,34 @@
+{
+  "slug": "example-add-tool-light",
+  "intent": "feature",
+  "profile": "light",
+  "summary": "Add a single MCP tool with explicit AC",
+  "steps": [
+    {
+      "agent": "feature-developer",
+      "label": "Implement tool schema/handler/register",
+      "model": "cheap"
+    },
+    {
+      "agent": "build-verifier",
+      "label": "typecheck + tests",
+      "model": "cheap"
+    }
+  ],
+  "humanGates": [],
+  "autoChain": true,
+  "skipped": [
+    {
+      "agent": "task-analyst",
+      "reason": "Explicit AC and single-tool scope"
+    },
+    {
+      "agent": "security-reviewer",
+      "reason": "Light profile valid only with no FS/net/auth expansion — otherwise use standard/full and include security-reviewer"
+    },
+    {
+      "agent": "solution-architect",
+      "reason": "Light profile — no architecture spike"
+    }
+  ]
+}

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, and java). Domain twin body ≥15 lines; thin aliases may be shorter.
+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.
 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`) 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`) 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, and java → **FAIL** (leakage). Prefer `check:preset-leakage`.
+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`.
 
 ### Soft notes

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

@@ -106,3 +106,7 @@ Write `.claude/team/tasks/<slug>/pipeline.json` and initial `status.json` (write
 5. Invoke `steps[0].agent` now (unless `retro` → `/technical-retro`).
 
 Do not invoke implementation agents yourself.
+
+## Metrics initialization
+
+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.

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

@@ -22,22 +22,19 @@ description: Continue an agent-team task after a human gate, pause, or review ch
 ## Алгоритм
 
 1. Запиши `.claude/team/active-task.json` → `{ "slug": "<slug>" }`.
-2. Сбрось gate: `awaitingHumanGate: false`.
-3. Определи **следующий шаг**:
-   - После approval analyst/architect: `pipelineIndex + 1` → следующий agent в `steps`.
-   - После `changes_requested`: снова **feature-developer** (тот же index или найди developer в steps).
-4. Обнови `status.json`:
-   ```json
-   {
-     "pipelineIndex": <n>,
-     "currentAgent": "<steps[n].agent>",
-     "phase": "executing",
-     "state": "in_progress",
-     "awaitingHumanGate": false
-   }
-   ```
-5. Вызови subagent для `currentAgent` с контекстом slug и артефактов.
-6. Если hook `chain-team-phases.sh` включён в проекте и `autoChain: true`, он продолжит цепочку по `pipeline.json`; иначе продолжай следующий шаг вручную.
+2. **Human gate resume** (`awaitingHumanGate` / `awaiting_approval`):
+   1. **Do not** manually increment `pipelineIndex` or invent `currentAgent` first.
+   2. Close the gate + activate the next attempt via the **installed** hook (single authority for ledger + status):
+
+```bash
+printf '%s\n' '{"status":"completed","action":"end_human_gate","activateNext":true}' | bash .claude/hooks/chain-team-phases.sh
+```
+
+   3. Re-read `status.json` (and the hook `followup_message`).
+   4. Invoke the subagent named in `status.currentAgent` / followup — do **not** advance the pipeline a second time.
+3. **Review `changes_requested`** (not a human gate): set `currentAgent` to `feature-developer` (same index / find developer in steps), `state: in_progress`, then invoke developer. Do **not** call `end_human_gate` unless `activeHumanGateEventId` is set.
+4. **Other resume**: restore `pipelineIndex` / `currentAgent` from status and invoke that agent.
+5. After the invoked agent completes, `chain-team-phases.sh` on `subagentStop` continues the chain when `autoChain: true`.
 
 ## Артефакты для handoff
 
@@ -47,3 +44,7 @@ description: Continue an agent-team task after a human gate, pause, or review ch
 | build-verifier | git diff, decomposition.md |
 | code-reviewer | brief.md, validation-report.md, git diff |
 | qa-tester | brief.md, decomposition.md, scope from pipeline step |
+
+## Metrics
+
+On human-gate resume, the hook action above appends `human_gate_ended` under the per-task lock **before** any new `attempt_started`. Agents must not calculate durations.

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

@@ -48,3 +48,7 @@ description: Route a natural-language task through the agent-team pipeline: task
 ## Legacy
 
 `/feature-start` и `/feature-continue` остаются совместимыми; для новых задач предпочитай `/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.

package/presets/claude/next/commands/technical-retro.md

@@ -56,3 +56,7 @@ description: Facilitate a technical retrospective for a period, incident, releas
 - Не приписывать команде цитаты или факты, которых не было во входе.
 - Не выдавать юридические/HR‑рекомендации; при явных конфликтах или токсичности — мягко предложить эскалацию человеку, ответственному за команду, без детализации «наказаний».
 - Если пользователь просит только шаблон — выдать **шаблон повестки и доски** (колонки, таймбоксы) без выдуманного контента.
+
+### Metrics evidence
+
+When `metrics.json` exists, run the local aggregation script and report the cohort, sample size, incomplete artifacts, attribution confidence, active attempt duration, and human-gate wait separately. Do not treat gate wait or malformed ledgers as agent duration.