@bonesofspring/ai-rules 0.2.11 → 0.2.13

package/CHANGELOG.md

@@ -2,6 +2,48 @@
 
 ## 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).
+- Instrumented all Cursor/Claude `chain-team-phases.sh` forks with lock-safe temp-and-rename ledger/status writes, `status.json` `activeAttempts` / `lastCompletedAttempt` bridge, and conservative parallel attribution (payload `attemptId`, sole active attempt, or `.metrics-receipts.json` fallback—never guess from `currentAgent`). Repeated work-package retries now target the nearest preceding developer and return to the requesting verifier/reviewer; stale duplicate stops are ignored.
+- Human-gate resume is a hook action: `{"status":"completed","action":"end_human_gate","activateNext":true}` on the installed `hooks/chain-team-phases.sh` (`/task-continue`); optional wrapper `scripts/close-agent-task-human-gate.mjs`.
+- Added `aggregate-agent-task-metrics.mjs` (role/count/duration, gate wait, attribution confidence, and separate missing-ledger, malformed-JSON, duplicate-ID, unterminated, unmatched, and duplicate-terminal completeness categories), Next fixtures under `presets/cursor/next/team/fixtures/`, and a 14-fork lifecycle harness covering retry, concurrent parallel completion, skip, gate, and invalid-ledger scenarios. Technical-retro commands include a Metrics evidence section.
+
+### PHP Laravel preset (`php-laravel`)
+
+- New installable preset **`php-laravel`** (Cursor + Claude twins): Laravel backend/API projects — flat `app/` layout, Eloquent, Form Requests, Policies, Actions/Services, Service Providers, Jobs/Queues/Events; thin controllers with clean-architecture leanings (repositories only when justified).
+- Always-on trio `laravel-app-core`, `architecture-boundaries`, `code-quality-and-refactoring` (session-start body budget ≤140).
+- Rule catalog (34 stems): Laravel domain rules (`http-layer`, `form-requests`, `eloquent-persistence`, `actions-services`, `service-providers`, `policies-authorization`, `jobs-queues`, `events-listeners`, …); no `api-grpc` / `messaging-adapters` stubs (async covered by Jobs/Events); `integration-test-*` agents (no Playwright / XCUITest / a11y).
+- Gates: `php-tooling` + `post-change-test` (prefer `php artisan test` / `composer test`; Pint/PHPStan/Psalm only if configured in repo/CI).
+- Structure scripts include `php-laravel` (`STACKS` + `PHP_FORBIDDEN_*`); meta shared-core + embed adapters list php-laravel as 7th installable stack; chain forks pairwise vs all stacks including `php-hexagonal`.
+- **Coexistence:** distinct install id from **`php-hexagonal`** (framework-agnostic ports/adapters PHP); comparison table in stack READMEs — neither replaces the other.
+- Install: `npx @bonesofspring/ai-rules init cursor|claude --preset php-laravel`.
+- Dogfood: `dogfood/php-laravel` (full `laravel/framework` via create-project; Todo API; committed `composer.lock`; P1–P3 prompts).
+- Review follow-ups (non-blocking): secondary agents (`task-analyst`, `solution-architect`, test planners) may retain hexagonal vocabulary — Laravel pass scheduled; run `sync-dogfood-cursor.sh` before monorepo merge; `check:rule-eval` remains next-only.
+
+### PHP hexagonal preset (`php-hexagonal`)
+
+- New installable preset **`php-hexagonal`** (Cursor + Claude twins): PHP 8.x + Composer + PSR-4 hexagonal backends; framework-agnostic HTTP edge (Slim / Symfony HttpFoundation / Laravel HTTP as documented variants only).
+- Always-on trio `php-app-core`, `architecture-boundaries`, `code-quality-and-refactoring` (session-start body budget ≤140).
+- Rule catalog (34 stems) with thin stub for `api-grpc`; full `messaging-adapters` (java parity); `integration-test-*` agents (no Playwright / XCUITest / a11y).
+- Gates: `php-tooling` + `post-change-test` (Composer / PHPUnit / Pest discovery; PHPStan/Psalm/Pint only if configured in repo/CI).
+- Structure scripts include `php-hexagonal` (`STACKS` + `PHP_FORBIDDEN_*`); meta shared-core + embed adapters list php-hexagonal alongside go/java; chain forks pairwise vs other stacks.
+- Install: `npx @bonesofspring/ai-rules init cursor|claude --preset php-hexagonal`.
+- Dogfood: `dogfood/php-hexagonal` (domain → ports → HTTP/persistence/messaging adapters → composition → PHPUnit unit + integration).
+- Review follow-ups: README titles use install name `php-hexagonal`; dogfood twin-sync paths synced; leakage checker scans `team/fixtures` (`steps[]` FAIL / `skipped[]` anti-pattern OK); composition-root HTTP integration test; AB.md PHP sample note; `check:rule-eval` documented as next-only.
+
 ### MCP TypeScript preset (`mcp-ts`)
 
 - New installable preset **`mcp-ts`** (Cursor + Claude twins): TypeScript MCP server authoring with `@modelcontextprotocol/sdk`, stdio-first transport, Context7-only MCP, package-manager–discovered typecheck/test via `mcp-ts-tooling` / `post-change-test`.

package/README.md

@@ -53,7 +53,7 @@ Where things go on `init`:
 
 Skills of note: `write-adr` (all stacks); `react-performance` (**next only**). Living gotchas: `team/conventions.md`. Opt-in rule samples eval: `yarn check:rule-eval` (workflow `rule-eval.yml`; not part of `check:preset-structure`).
 
-The package ships presets including **`next`** (Next.js stack), **`ios-swift`** (iOS apps on Swift / SwiftUI), **`go`** (Go backends with hexagonal architecture), **`java`** (Java / Spring Boot hexagonal backends), and **`mcp-ts`** (TypeScript MCP servers with `@modelcontextprotocol/sdk`). Other preset names: see `presets/` in the [repo](https://github.com/bonesofspring/ai-rules). Name is a single path segment, no `/` or `..`.
+The package ships presets including **`next`** (Next.js stack), **`ios-swift`** (iOS apps on Swift / SwiftUI), **`go`** (Go backends with hexagonal architecture), **`java`** (Java / Spring Boot hexagonal backends), **`mcp-ts`** (TypeScript MCP servers with `@modelcontextprotocol/sdk`), **`php-hexagonal`** (PHP / Composer hexagonal backends), and **`php-laravel`** (Laravel backend/API with Eloquent, Form Requests, Policies, Actions/Services). Other preset names: see `presets/` in the [repo](https://github.com/bonesofspring/ai-rules). Name is a single path segment, no `/` or `..`.
 
 ```bash
 npx @bonesofspring/ai-rules init cursor --preset ios-swift
@@ -64,6 +64,10 @@ npx @bonesofspring/ai-rules init cursor --preset java
 npx @bonesofspring/ai-rules init claude --preset java
 npx @bonesofspring/ai-rules init cursor --preset mcp-ts
 npx @bonesofspring/ai-rules init claude --preset mcp-ts
+npx @bonesofspring/ai-rules init cursor --preset php-hexagonal
+npx @bonesofspring/ai-rules init claude --preset php-hexagonal
+npx @bonesofspring/ai-rules init cursor --preset php-laravel
+npx @bonesofspring/ai-rules init claude --preset php-laravel
 ```
 
 Help: `ai-rules --help`.

package/bin/cli.js

@@ -74,11 +74,15 @@ Examples:
   npx @bonesofspring/ai-rules init cursor --preset go
   npx @bonesofspring/ai-rules init cursor --preset java
   npx @bonesofspring/ai-rules init cursor --preset mcp-ts
+  npx @bonesofspring/ai-rules init cursor --preset php-hexagonal
+  npx @bonesofspring/ai-rules init cursor --preset php-laravel
   npx @bonesofspring/ai-rules init claude
   npx @bonesofspring/ai-rules init claude --preset ios-swift
   npx @bonesofspring/ai-rules init claude --preset go
   npx @bonesofspring/ai-rules init claude --preset java
   npx @bonesofspring/ai-rules init claude --preset mcp-ts
+  npx @bonesofspring/ai-rules init claude --preset php-hexagonal
+  npx @bonesofspring/ai-rules init claude --preset php-laravel
   npx @bonesofspring/ai-rules clean cursor
 `);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bonesofspring/ai-rules",
-  "version": "0.2.11",
+  "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/README.md

@@ -1,6 +1,6 @@
 # Shared preset core (`presets/_shared`)
 
-Stack-agnostic **prose and checklists** for all installable presets: `next`, `ios-swift`, `go`, and `java` (`cursor/<stack>`, `claude/<stack>`).
+Stack-agnostic **prose and checklists** for all installable presets: `next`, `ios-swift`, `go`, `java`, `mcp-ts`, and `php-hexagonal` (`cursor/<stack>`, `claude/<stack>`).
 
 **Not an installable preset.** CLI `init` copies only under `presets/cursor/<name>/` or `presets/claude/<name>/` — this sibling is never shipped to consumer apps.
 

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-task-metrics.md

@@ -0,0 +1,30 @@
+# Agent-task metrics
+
+Metrics are local task artifacts for evaluating pipeline effectiveness. They are not remote telemetry and must never contain prompts, secrets, file paths or contents, user identifiers, model transcripts, or arbitrary error text.
+
+## Ledger contract
+
+Each pipeline run owns `<team>/tasks/<slug>/metrics.json`:
+
+```json
+{
+  "schemaVersion": 1,
+  "task": { "runId": "uuid", "slug": "example", "preset": "ai-rules", "stack": "next", "platform": "cursor", "intent": "feature", "profile": "standard" },
+  "events": []
+}
+```
+
+`events` is append-only. A task is one `runId`; a subtask is one invocation of `pipeline.steps[i]`. Every invocation has an `attemptId`, including each member of a parallel step. Events inherit the immutable task dimensions rather than duplicating them.
+
+Allowed event types are `task_started`, `attempt_started`, `attempt_finished`, `retry_scheduled`, `attempt_skipped`, `human_gate_started`, `human_gate_ended`, and `task_completed`. Terminal outcomes are `completed`, `changes_requested`, `validation_failed`, `skipped`, `cancelled`, or `unknown`.
+
+## Collection policy
+
+1. The router creates the ledger and task dimensions, then records `task_started` and an `attempt_started` immediately before every invocation.
+2. The completion hook uses the host clock for `attempt_finished`, `task_completed`, and gate edges. It computes `durationMs` from the stored start timestamp; agents must not calculate durations or rewrite the ledger.
+3. `status.json.activeAttempts` is a transient bridge keyed by `attemptId`; `lastCompletedAttempt` is diagnostic only. The ledger is the history authority.
+4. A retry ends its prior attempt, emits `retry_scheduled`, then creates a new attempt number. In repeated work-package pipelines, the fix targets the nearest preceding developer step and then returns to the exact verifier/reviewer step that requested the fix. A skipped step emits `attempt_skipped`. Human-gate wait is recorded with separate start/end events and never added to attempt duration.
+5. For parallel completion, the hook accepts a payload `attemptId` only when it directly names an active attempt. A supplied stale or unknown `attemptId` is ignored and must not fall back to another active attempt or advance the pipeline. Other runtime IDs have no verified start-time mapping and are not stored as `runtimeIdentity`. If no direct `attemptId` exists, attribute only when exactly one active attempt exists. Otherwise accept an explicit task-local completion receipt and mark it `source: "agent"` with `attributionConfidence: "fallback"`; never guess from `currentAgent`.
+6. Writers use a per-task lock and temporary-file rename for both ledger and status updates so concurrent completions do not lose events or state. Aggregation reports missing ledgers, malformed JSON, duplicate attempt IDs, unterminated attempts, unmatched terminals, and duplicate terminals as separate incomplete-data categories; none count as a successful task.
+
+Only allowlisted identifiers and timestamps belong in events. Use `source` (`router`, `hook`, `agent`) and `attributionConfidence` (`high`, `fallback`, `unknown`) to expose incomplete collection rather than invent precision.

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,6 +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 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
@@ -64,10 +118,21 @@ flowchart TD
   "currentAgent": "task-analyst",
   "phase": "executing",
   "state": "in_progress",
-  "awaitingHumanGate": false
+  "awaitingHumanGate": false,
+  "activeAttempts": {},
+  "lastCompletedAttempt": null,
+  "parallelCompleted": [],
+  "parallelOutcomes": {}
 }
 ```
 
+| Field | Meaning |
+|-------|---------|
+| `activeAttempts` | Transient timing bridge keyed by `attemptId` |
+| `lastCompletedAttempt` | Diagnostic pointer to the latest finished attempt |
+| `parallelCompleted` | Agents that have stopped in the current parallel step |
+| `parallelOutcomes` | Per-agent `{ outcome, attemptId, confidence }` for the current parallel join; cleared when the step advances or retries |
+
 | state | Meaning |
 |-------|---------|
 | `in_progress` | Current step running |
@@ -76,6 +141,8 @@ flowchart TD
 | `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 |
@@ -91,7 +158,7 @@ flowchart TD
 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>`.
@@ -116,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/_shared/core/meta/preset-layering.md

@@ -13,7 +13,7 @@
 ## Куда класть новое правило
 
 1. Общие принципы для всех стеков → **core** + адаптеры с `<!-- shared-core: … -->`.
-2. Только один из installable стеков (`next` / `ios-swift` / `go` / `java`) → **stack-specific** (не в `_shared`).
+2. Только один из installable стеков (`next` / `ios-swift` / `go` / `java` / `mcp-ts` / `php-hexagonal` / `php-laravel`) → **stack-specific** (не в `_shared`).
 3. Только Cursor или только Claude packaging → platform artifact / frontmatter, не дублировать семантику.
 
 ## SoT

package/presets/_shared/core/meta/preset-no-cross-stack-leakage.md

@@ -6,7 +6,7 @@
 
 - `next` 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` / `mcp-ts` must not ship Playwright, XCUITest, Next lint recipes, or `xcodebuild`/`SwiftLint` as required handoffs.
+- `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.
 - Shared core must not embed stack paths (`app/src/**`, `Features/**`, `playwright`, `xcodebuild`).
 
@@ -25,16 +25,16 @@ 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 go / java hooks/agents (FAIL)
+## Forbidden in go / java / php-hexagonal / php-laravel hooks/agents (FAIL)
 
-Shared backend-stack bans (both `go` and `java`):
+Shared backend-stack bans (`go`, `java`, `php-hexagonal`, and `php-laravel`):
 
 - `playwright-test-`, `playwright-e2e`, `user-playwright`, `app/__tests__/e2e`
 - Positive yarn recipes `lint:js` / `lint:css`
 - `xcuitest-test-`, `xcodebuild`, `SwiftLint` as required handoffs
 - Agent file `accessibility-reviewer` (no UI surface)
 
-Required instead: `integration-test-*`; build-verifier / `post-change-test` plus stack tooling — `go-tooling` (`go test`, `go vet`) or `java-tooling` (`mvn test` / `./gradlew test`).
+Required instead: `integration-test-*`; build-verifier / `post-change-test` plus stack tooling — `go-tooling` (`go test`, `go vet`), `java-tooling` (`mvn test` / `./gradlew test`), or `php-tooling` (`php artisan test` / `composer test` / `vendor/bin/phpunit`).
 
 ## Forbidden in mcp-ts hooks/agents (FAIL)
 
@@ -55,4 +55,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`, and `mcp-ts` (per platform).
+`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).

package/presets/_shared/core/meta/preset-pr-checklist.md

@@ -6,7 +6,7 @@
 
 - [ ] **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, and java — см. `preset-twin-sync`)
+- [ ] **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`)
 - [ ] **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/_shared/core/meta/preset-twin-sync.md

@@ -11,6 +11,8 @@ Cursor `.mdc` — **SoT per stack**. Claude topic `.md` — derived twin.
 | `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
 
@@ -31,5 +33,7 @@ Cursor `.mdc` — **SoT per stack**. Claude topic `.md` — derived twin.
 - **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/_shared/core/review/technical-retro.md

@@ -4,4 +4,6 @@
 
 **`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/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.
 
@@ -29,7 +29,14 @@ Hard gates: twin-map (stacks include **go**), token-budget (alwaysApply/session-
 
 Document PASS/FAIL in `validation-report.md`.
 
-1. **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.
+1. **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.
 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, and java → **FAIL** (leakage). Prefer `check:preset-leakage`.
+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,8 +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).
+
+## 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
+
+- **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.