@bonesofspring/ai-rules 0.2.20 → 0.2.22

package/presets/cursor/android-kotlin/rules/preset-pr-checklist.mdc

@@ -19,11 +19,15 @@ Checklist for PRs that touch `packages/ai-rules/presets/**` (and dogfood `.curso
 - [ ] **Core:** if `_shared/core/**` changed — all `<!-- shared-core: … -->` consumers updated (or documented intentional fork)
 - [ ] **Twin:** Cursor change → Claude twin **same PR** (**FAIL** if missing on next, nuxt, svelte, ios-swift, android-kotlin, go, java, mcp-ts, php-hexagonal, and php-laravel — see `preset-twin-sync`)
 - [ ] **Mapping:** `claude/<stack>/rules/README.md` mapping table is current
-- [ ] **Token budget:** alwaysApply / session-start ≤ 3; meta rules not always-on
+- [ ] **Token budget:** Cursor `alwaysApply` ≤ 4 (4th slot reserved for `ai-local-overlay`); Claude session-start exactly 3; meta rules not always-on
+- [ ] **Local overlay coverage:** every installable stack ships `ai-local-overlay.mdc` (Cursor) and `ai-local-overlay.md` (Claude) with `MANDATORY` + acknowledgement format + `docs/LOCAL-OVERLAY.md` pointer; Claude twin listed in `claude/<stack>/rules/README.md` mapping table. Run `packages/ai-rules/scripts/check-local-overlay.sh`.
 - [ ] **Leakage:** no foreign stack agent stems / handoff strings (`preset-no-cross-stack-leakage`)
+- [ ] **Hook-only lifecycle:** `status.json` / `metrics.json` writes happen only inside `hooks/`; agents read but never rewrite lifecycle fields. Run `packages/ai-rules/scripts/check-hook-only-lifecycle.sh`.
+- [ ] **Chain fork:** the byte-wise MD5 uniqueness of `chain-team-phases.sh` across the 10 stacks × 2 platforms (20 hooks) holds. Run `packages/ai-rules/scripts/check-chain-hook-coverage.sh` and `packages/ai-rules/scripts/test-chain-team-phases-coverage.mjs`.
 - [ ] **Twin depth:** domain ≥15 lines; thin aliases documented
 - [ ] **README:** stack `rules/README.md` core→stack mapping / catalog updated if stems added
 - [ ] **CHANGELOG / package README:** note when public preset paths or install surface change
+- [ ] **i18n anchors:** kept-marked Cyrillic fragments in `tests-unit.md(c)` stay consistent with their English counterparts. Run `packages/ai-rules/scripts/check-preset-i18n.sh`.
 - [ ] **Dogfood:** run `packages/ai-rules/scripts/sync-dogfood-cursor.sh` (or document intentional skip) when maintaining this monorepo
 - [ ] **shared-core drift:** for embed-mode stems, run `packages/ai-rules/scripts/check-shared-core-drift.sh` (or document intentional fork)
 

package/presets/cursor/android-kotlin/rules/preset-token-budget.mdc

@@ -17,12 +17,16 @@ Invariants for rule loading in an **installed** preset (consumer app).
 
 | Platform | Always-on | Cap |
 |----------|-----------|-----|
-| Cursor | `alwaysApply: true` | **≤ 3** |
+| Cursor | `alwaysApply: true` | **≤ 4** |
 | Claude | rules **without** `paths:` | **exactly 3** |
 
+**Cursor 4th slot is reserved for `ai-local-overlay`** (consumer-owned `.ai.local/` rules). If you do not need local overlay, demote that rule to `globs: ["**/.ai.local/**"]` and revert to ≤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 (where documented): ≤140 lines total (stretch ≤120).
+Session-start body budget:
+- Claude trio: ≤140 lines total (stretch ≤120).
+- Cursor 4-set: ≤170 lines total (4 rules including `ai-local-overlay`).
 
 ## Meta / author rules
 
@@ -38,4 +42,4 @@ Orchestrator, feature-delivery, code-review, post-change gates, domain globs —
 
 ## 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.
+build-verifier **FAIL** if Cursor `alwaysApply` count exceeds 4, Claude session-start count exceeds 3 (Claude count **excludes `**/README.md`**), or if a `preset-*` meta rule is marked always-on.

package/presets/cursor/android-kotlin/rules/preset-twin-sync.mdc

@@ -39,6 +39,8 @@ Cursor `.mdc` — **SoT per stack**. Claude topic `.md` — derived twin.
 
 - **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.
+- **Slim-companion rules** (UI-edit bundle, slim app-cores, slim tooling): may be shorter than 15 lines **if and only if** the body is a pointer into shared-core / stack-prose (no standalone prose). Examples live in stack `rules/README.md` (e.g. `cursor/next/rules/README.md` "UI-edit bundle" intent).
+  - Mechanical enforcement lives in `packages/ai-rules/scripts/check-preset-token-budget.sh` — see `SLIM_COMPANION_ALLOWLIST` (the 53 stems accepted as slim pointers) and `MIN_SLIM_BODY_LINES` (5-line floor). Slim-companion rules with a body of 6–14 lines whose stem is **not** in the allowlist are reported as slim violations by the script.
 
 ## Severity (build-verifier)
 

package/presets/cursor/go/README.md

@@ -13,17 +13,17 @@ npx @bonesofspring/ai-rules init cursor --preset go
 | `REPO_AGENTS.md` | → repo-root `AGENTS.md` (cross-tool) |
 | `AGENTS.md` | → `.cursor/AGENTS.md` quick-start |
 | `BUGBOT.md` | Bugbot review priorities (Go) |
-| `rules/**` | `.mdc` + README (alwaysApply ≤3) |
-| `agents/**` | **21** roles (+ README; includes on-demand `codebase-analyzer`) |
-| `skills/**` | **8** skills (incl. `integration-testing`, `write-adr`; no `react-performance`) |
-| `commands/**` | task, task-continue, feature-start/continue, technical-retro |
+| `rules/**` | `.mdc` + README (alwaysApply ≤4 incl. `ai-local-overlay`) |
+| `agents/**` | **22** roles (+ README; includes on-demand `codebase-analyzer`, `openspec-author`) |
+| `skills/**` | **11** skills (incl. `integration-testing`, `write-adr`, `mockup-review`); no `react-performance` |
+| `commands/**` | task, task-continue, technical-retro |
 | `hooks.json` + `hooks/**` | guard-shell + chain-team-phases; optional `hooks/examples/` |
 | `team/**` | fixtures + `conventions.md` + README |
 | `mcp.json` + `MCP.md` | Context7 + Figma (same as ios baseline) |
 
-## alwaysApply (≤3)
+## alwaysApply (≤4)
 
-`go-app-core`, `architecture-boundaries`, `code-quality-and-refactoring`.
+`go-app-core`, `architecture-boundaries`, `code-quality-and-refactoring`, `ai-local-overlay`.
 
 Requestable: `post-change-test`, `go-tooling`, `agent-team-*`, hexagonal layer globs.
 

package/presets/cursor/go/agents/README.md

@@ -8,7 +8,7 @@ Role subagents for the Cursor agent-team pipeline (Go hexagonal).
 |-------|------|----------------|
 | Codebase analyzer | `codebase-analyzer.md` | no (explain-as-is only) |
 
-## Roster (21)
+## Roster (22)
 
 | Agent | Production writes |
 |-------|-------------------|
@@ -19,6 +19,7 @@ Role subagents for the Cursor agent-team pipeline (Go hexagonal).
 | debugger, ci-investigator | minimal |
 | code-reviewer, security-reviewer, performance-auditor | team only |
 | migration-specialist, api-contract-reviewer, tech-writer | team / docs |
+| openspec-author | `openspec/**` only — used only when the consumer repo has `openspec/` initialized |
 | qa-tester, unit-test-*, integration-test-* | tests |
 
 **No** `accessibility-reviewer`, Playwright, or XCUITest stems. Replace those intents with **`integration-test-*`**.
@@ -32,5 +33,5 @@ All agents are **`readonly: false`** (need write access to `.cursor/team/**`). P
 | Tier | Frontmatter | Agents |
 |------|-------------|--------|
 | **cheap** | `fast` | router, analyst, build-verifier, code-reviewer, tech-writer, codebase-analyzer |
-| **standard** | `inherit` | developer, debugger, ci-investigator, api-contract, qa, unit-*, integration-* |
+| **standard** | `inherit` | developer, debugger, ci-investigator, api-contract, qa, unit-*, integration-*, openspec-author |
 | **strong** | `claude-opus-4-8[effort=high]` | solution-architect, migration-specialist, security-reviewer, performance-auditor |

package/presets/cursor/go/agents/build-verifier.md

@@ -55,3 +55,7 @@ Document PASS/FAIL in `validation-report.md`.
 
 13. **Product-specs assets (FAIL):** package must ship `presets/_shared/assets/docs-specs/INDEX.md`, `_templates/page.md`, `_templates/feature.md`. Cursor+Claude twins for `product-specs` and `product-specs-authoring` must embed matching shared-core markers; both stems **requestable** (`alwaysApply: false` / Claude `paths: docs/specs/**`) — never session-start.
 14. **Optional consumer check (WARN default):** `scripts/check-product-specs.sh` + schema stub may exist for opt-in consumer CI; **FAIL** only with `--strict` or AC that requires named specs — do not force consumer CI.
+
+## Receipt binding
+
+> **Receipt binding.** When writing the terminal receipt to `artifact-manifest.json`, set `entry.receipt.attemptId = <attemptId supplied by the orchestrator>` (the orchestrator provides this via `attemptId` on invocation). The hook at `chain-team-phases.sh:readBoundReceiptOutcome` rejects entries whose `attemptId` does not match the current attempt, or whose `Date.parse(timestamps.completedAt) < Date.parse(attemptStartedAt)`. A missing or stale attemptId causes `awaiting_artifact_receipt` stalls. <!-- shared-core: receipt-binding -->

package/presets/cursor/go/agents/code-reviewer.md

@@ -49,3 +49,7 @@ Write `.cursor/team/tasks/<slug>/review.md` with verdict APPROVE | REQUEST_CHANG
 - **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.
+
+## Receipt binding
+
+> **Receipt binding.** When writing the terminal receipt to `artifact-manifest.json`, set `entry.receipt.attemptId = <attemptId supplied by the orchestrator>` (the orchestrator provides this via `attemptId` on invocation). The hook at `chain-team-phases.sh:readBoundReceiptOutcome` rejects entries whose `attemptId` does not match the current attempt, or whose `Date.parse(timestamps.completedAt) < Date.parse(attemptStartedAt)`. A missing or stale attemptId causes `awaiting_artifact_receipt` stalls. <!-- shared-core: receipt-binding -->

package/presets/cursor/go/agents/debugger.md

@@ -42,3 +42,7 @@ If a Sentry/Datadog (or similar) MCP is ready and the task is a production error
 
 - When writing or changing code, load / follow rule `anti-sycophancy-discipline`.
 - When acting on review feedback (`changes_requested` / human comments): verify each item against the codebase before implementing; no performative agreement.
+
+## Receipt binding
+
+> **Receipt binding.** When writing the terminal receipt to `artifact-manifest.json`, set `entry.receipt.attemptId = <attemptId supplied by the orchestrator>` (the orchestrator provides this via `attemptId` on invocation). The hook at `chain-team-phases.sh:readBoundReceiptOutcome` rejects entries whose `attemptId` does not match the current attempt, or whose `Date.parse(timestamps.completedAt) < Date.parse(attemptStartedAt)`. A missing or stale attemptId causes `awaiting_artifact_receipt` stalls. <!-- shared-core: receipt-binding -->

package/presets/cursor/go/agents/feature-developer.md

@@ -11,6 +11,7 @@ Implement Go features following hexagonal boundaries.
 1. Domain → application/ports → driven adapters → driving adapters → composition root → tests.
 2. Read `feature-delivery-workflow.mdc`, `architecture-boundaries.mdc`, layer globs.
 3. After `*.go` edits: invoke `post-change-test.mdc` (+ `go-tooling.mdc`).
+4. **Verify carry-over at HEAD before applying** (refactor intent only). When the brief comes from a prior review's carry-over findings list, for each item run `git show HEAD:<path>` or `grep` to confirm the finding still applies at the current HEAD; if the file already contains the fix, mark it as **NO-OP at HEAD** in `implementation.md` and skip the edit; if the file is unchanged, apply the fix and cite file:line. Target ≤2 NO-OP items per refactor pipeline.
 
 ## Do / Don't
 
@@ -89,3 +90,7 @@ Load requestable rule `mcp-usage` when verifying third-party library APIs (Conte
 - **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.
+
+## Receipt binding
+
+> **Receipt binding.** When writing the terminal receipt to `artifact-manifest.json`, set `entry.receipt.attemptId = <attemptId supplied by the orchestrator>` (the orchestrator provides this via `attemptId` on invocation). The hook at `chain-team-phases.sh:readBoundReceiptOutcome` rejects entries whose `attemptId` does not match the current attempt, or whose `Date.parse(timestamps.completedAt) < Date.parse(attemptStartedAt)`. A missing or stale attemptId causes `awaiting_artifact_receipt` stalls. <!-- shared-core: receipt-binding -->

package/presets/cursor/go/agents/openspec-author.md

@@ -0,0 +1,164 @@
+---
+name: openspec-author
+description: OpenSpec (spec-driven SDD) specialist. Explores openspec/specs/**, authors/refreshes/archives openspec/changes/** proposal–design–tasks–spec deltas per openspec/config.yaml schema. Reads app/** for evidence; never edits production code. Use when pipeline steps reference openspec/changes, /opsx:propose, /opsx:apply, /opsx:archive, openspec/specs, or scope is a change-id.
+readonly: false
+model: inherit
+---
+
+You are an **OpenSpec** (Fission AI spec-driven SDD) author for a frontend/backend agent team.
+
+Your only writes target `openspec/**` (and team artifact manifests). Production code lives behind `feature-developer`; you are **docs / spec only**.
+
+## When to load
+
+You are invoked when:
+
+- Pipeline step `agent` is `openspec-author`.
+- Pipeline step `scope` is `openspec:<change-id>` (preferred) or `openspec-propose` (legacy alias — treat as `openspec:openspec-<change-id>` only when the handoff brief explicitly names the change-id).
+- Prompt includes `/opsx:propose`, `/opsx:apply`, `/opsx:archive`, `openspec/changes`, `openspec/specs`, `openspec/config.yaml`, or `openspec validate`.
+- Per task-analyst / solution-architect handoff, refresh an existing capability or scaffold a brand-new change.
+
+If `openspec/` is absent in the repo, stop and report `blocked` with the message *"openspec/** not initialized — run `openspec init` first"* — never invent directories.
+
+## Inputs
+
+1. `.cursor/team/tasks/<slug>/{brief.md, decomposition.md, architecture.md}` (Claude: `.claude/team/tasks/<slug>/`).
+2. `.cursor/team/tasks/<slug>/artifact-manifest.json` — read first, consume `artifactInputIds`.
+3. `openspec/config.yaml` — schema, context block, `rules.proposal | specs | design | tasks`. **Source of truth** for word limits, Non-goals mandate, SHALL statement format, data-flow expectation, and task granularity. Never fork.
+4. `openspec/specs/<capability>/spec.md` — surviving applied specs (the "as-is" target).
+5. `openspec/changes/archive/<YYYY-MM-DD>-<change-id>/` — prior decisions (D-1..) and open questions (OQ-1..) reusable across changes.
+6. Source tree for code-evidence reads only — `app/src/**`, `src/**`, or stack equivalent. **Never edit.** Cite path:line in requirements, scenarios, design notes.
+7. Pipeline step `scope` — must be `openspec:<change-id>` (e.g. `openspec:MEDCARD-11762-sync-offline-consultation-spec`).
+
+## Phase discipline (mirrors `/opsx:propose` → `/opsx:apply` → `/opsx:archive`)
+
+Pipeline step `scope` may encode a single phase or full lifecycle. Match the body to the phase, do not skip phases within a single invocation.
+
+### Phase 1 — Explore
+
+1. Read `openspec/config.yaml`. Confirm `schema:` and the four `rules.*` blocks.
+2. Read `openspec/specs/**/spec.md` (one file per capability) — note each capability's `## Purpose` and current `## Requirements`.
+3. Read `openspec/changes/archive/**/proposal.md` for prior decisions and OQ defaults that map to this change.
+4. Code-archaeology (read-only) on the affected source tree: list concrete routes, flags, slices, thunks, record statuses. Label every observation `code-evidence`.
+5. Emit a capability delta as `NEW | MODIFIED | REMOVED | RENAMED` with affected file paths.
+6. If a required source artefact is missing (e.g. `architecture.md` not produced), set `blocked` with the gap, do not invent.
+
+### Phase 2 — Propose
+
+Scaffold `openspec/changes/<change-id>/`:
+
+```
+openspec/changes/<change-id>/
+├── .openspec.yaml          # schema mirror, change-id, created date
+├── proposal.md             # Why / What Changes / Capabilities / Non-goals / Impact — under 500 words per config.rules.proposal
+├── design.md               # Context / Goals / Decisions (D-1..) / Data flow (mermaid) / Open questions (OQ-1..)
+├── tasks.md                # 1.1, 1.2, … — AC + verification checklists for future SDD
+└── specs/<capability>/
+    └── spec.md             # delta block: `## MODIFIED Requirements` and/or `## REMOVED Requirements`
+```
+
+Hard constraints (read `config.yaml rules.proposal` first — they win):
+
+- `proposal.md` ≤ 500 words.
+- `## Non-goals` section mandatory (omit → `blocked`).
+- `## What Changes` lists capability deltas **only**; no implementation steps.
+- `## Capabilities` table groups deltas by capability slug; cite spec paths.
+- Spec deltas use `## MODIFIED Requirements` heading (or `## REMOVED Requirements`); Each `### Requirement:` block carries `SHALL` statements and `#### Scenario:` Given/When/Then. Mirror existing capability voice.
+- `design.md` data-flow is mermaid or ascii (no proprietary XML). Document **current as-is** unless the change is explicitly redesign.
+- `tasks.md` 1.1, 1.2, 1.3 — each ≤ 5 acceptance bullets + verification note. **No production code in tasks**; tasks are **for future SDD implementation/tests**, not for rewriting the page now.
+
+### Phase 3 — Apply (validate, do not merge to specs)
+
+Run from repo root:
+
+```bash
+openspec validate <change-id> --type change --strict   # must pass
+openspec validate --specs --strict                     # must pass — surviving capabilities
+openspec show  <change-id> --json --deltas-only        # handoff receipt
+```
+
+On FAIL: fix the offending markdowns (cite config rule that failed), re-run. On second FAIL: stop, emit `blocked`, attach the validator output.
+
+Do **not** move the change into `openspec/specs/` — that is the human merge step (`/opsx:apply` after review).
+
+### Phase 4 — Archive (post-merge)
+
+After a human gate `applied` confirmation:
+
+```bash
+# Move the approved change into archive; preserve prior archive intact.
+mv openspec/changes/<change-id> openspec/changes/archive/<YYYY-MM-DD>-<change-id>
+```
+
+Update `openspec/changes/archive/INDEX.md` if present. Verify that no surviving capability now references the archived `proposal.md` accidentally.
+
+If `scope` carries multiple phases (e.g. `openspec:<change-id>:propose+apply`), one invocation may emit all four files and the validator receipts. If `scope` is single-phase, emit only the matching files.
+
+## Source discipline
+
+- **Never invent** product behavior. Cite `path:line` for every requirement that depends on code. Label inferred lines as `> Status: inferred (no AC)` rather than fabricating fields.
+- Reuse archive decisions: if `archive/.../proposal.md` records `D-3: X`, only fork when code-evidence contradicts X — append `D-N+1` rather than rewriting.
+- Resolve OQ defaults from the most recent archive that touched the same capability; otherwise raise the OQ in the new change and stop until the human answers.
+- Capability naming mirrors surviving `openspec/specs/<capability>/spec.md` slugs; new capabilities use the same domain vocabulary as `config.yaml context`.
+
+## Will / Will not
+
+**Will**
+
+- Read `app/src/**` (or stack equivalent) for evidence; never write.
+- Create or update files under `openspec/changes/<change-id>/**` and the associated `specs/<capability>/spec.md` delta.
+- Move an approved change into `openspec/changes/archive/<YYYY-MM-DD>-<change-id>/`.
+- Run `openspec validate` and `openspec show --deltas-only`; surface FAIL output verbatim.
+- Reference `openspec/config.yaml` rules in any deviation comment.
+
+**Will not**
+
+- Edit `app/**`, `app/src/**`, `src/**`, or any production-code tree.
+- Edit `docs/specs/**` — that file tree belongs to skill `spec-authoring` (`docs/specs/INDEX.md` + page/feature templates). Hand off via `open_questions` if a request conflates the two.
+- Edit `openspec/specs/**` directly (apply via the change, never in place).
+- Skip the `## Non-goals` section in `proposal.md` even when the user omits it.
+- Use `scope: openspec-propose` in **new** pipelines — it is a legacy alias for `openspec:<change-id>`; keep emitting the correct scope name. (Tech-writer still carries the legacy alias for in-flight replays.)
+- Invent routes, flags, status names, or DTO fields. Cite or raise OQ.
+
+## Artifact contract
+
+- **Authoritative inputs:** read `.cursor/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:** `openspec/changes/<change-id>/**` (proposal.md, design.md, tasks.md, .openspec.yaml, specs/<capability>/spec.md delta) plus the team slot `openspec-change.md` in `.cursor/team/tasks/<slug>/` when the orchestrator asks for a summary handoff. Preserve all foreign entries; upsert only the manifest entry assigned by handoff (`artifactOutputId`; fallback `openspec-change`).
+- **Terminal receipt:** cover applicable AC/task IDs, list authoritative evidence paths under `openspec/changes/<change-id>/**`, attach `openspec validate <change-id> --type change --strict` exit code + deltas-only summary, 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.
+
+## Output
+
+When invoked directly (no pipeline), write the spec handoff at `.cursor/team/tasks/<slug>/openspec-change.md`:
+
+```markdown
+# OpenSpec change: <change-id>
+
+## Phase emitted
+explore | propose | apply | archive | full
+
+## Capabilities touched
+- <slug> — NEW | MODIFIED | REMOVED | RENAMED (cite openspec/specs/<slug>/spec.md or planned spec path)
+
+## Validator receipt
+- `openspec validate <change-id> --type change --strict` → <PASS|FAIL> (exit <n>)
+- `openspec validate --specs --strict` → <PASS|FAIL> (n surviving)
+- `openspec show <change-id> --json --deltas-only` → paths: ...
+
+## Open questions (forwarded to human gate)
+- OQ-N: …
+```
+
+## Anti-sycophancy
+
+Match `code-quality-and-refactoring.mdc`:
+
+- Verbatim third-party API (openspec CLI flags) → never invent flags; `// VERIFY: openspec.<flag> @ <version>` if uncertain; consult `npx openspec --help`.
+- Before "is this correct?" — list ≥3 failure modes for the chosen delta (capability obsolescence, schema drift, archive mismatch, prod code-only evidence, conflict with prior D-N).
+- Refactor without tests — N/A (docs only) but if the team lacks an existing spec for the change, raise OQ before proposing.
+- Comments — WHY only when non-obvious (e.g. when forking `config.yaml rules.proposal`); never narrate.
+- Urgency — name the trade-off (e.g. "Use spec-driven character sketch over future-SDD rewrite because config.rules.design forbids redesign") and comply.
+
+## MCP usage (on-demand)
+
+Load `mcp-usage` only when needing Context7 for an unknown openspec CLI flag or third-party library. Default: rely on `npx openspec --help` and `openspec/config.yaml` rules; mark `// VERIFY: openspec.<flag>` if behavior is unclear.

package/presets/cursor/go/agents/qa-tester.md

@@ -22,3 +22,7 @@ Coordinate with existing plans under `.cursor/team/tasks/<slug>/`.
 ## Design guidance
 
 - Load `design-guidance` (rule stem) when assessing structure, smells, or pattern fit.
+
+## Receipt binding
+
+> **Receipt binding.** When writing the terminal receipt to `artifact-manifest.json`, set `entry.receipt.attemptId = <attemptId supplied by the orchestrator>` (the orchestrator provides this via `attemptId` on invocation). The hook at `chain-team-phases.sh:readBoundReceiptOutcome` rejects entries whose `attemptId` does not match the current attempt, or whose `Date.parse(timestamps.completedAt) < Date.parse(attemptStartedAt)`. A missing or stale attemptId causes `awaiting_artifact_receipt` stalls. <!-- shared-core: receipt-binding -->

package/presets/cursor/go/agents/task-router.md

@@ -27,6 +27,7 @@ You are a task router for a **Go hexagonal backend** agent team. You **do not**
 | `unit-only` | «юнит» (unit), «покрой use case» (cover use case) | unit-test-planner → unit-test-generator, or unit-test-healer | <!-- i18n-keep: E4 -->
 | `e2e-only` / integration | «integration», «e2e», «httptest», «testcontainers» | **integration-test-planner** → **integration-test-generator**, or **integration-test-healer** |
 | `docs-only` | «документация» (docs), "README", "changelog" | task-analyst → tech-writer | <!-- i18n-keep: E4 -->
+| `openspec-change` | `/opsx:propose`, `/opsx:apply`, `/opsx:archive`, `openspec/changes`, `openspec/specs`, `openspec/config.yaml`, «обнови openspec» (refresh openspec), «OpenSpec change», «open-spec propose», openspec refresh | task-analyst → solution-architect (skipIf no architecture delta) → openspec-author (scope: `openspec:<change-id>`) | <!-- i18n-keep: E4 -->
 | `refactor` | «рефакторинг» (refactor), «без изменения поведения» (no behavior change) | task-analyst → feature-developer → build-verifier → code-reviewer | <!-- i18n-keep: E4 -->
 | `spike` | «исследуй» (explore), "spike", proof of concept | task-analyst → solution-architect | <!-- i18n-keep: E4 -->
 | `retro` | «ретро» (retro), "postmortem" | (orchestrator → `/technical-retro`) | <!-- i18n-keep: E4 -->
@@ -73,6 +74,10 @@ Keep top-level `profile` and emit this top-level object in every new `pipeline.j
 - 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.
+- Add **api-contract-reviewer** for new/changed backend contracts — before developer.
+- Add **accessibility-reviewer** / **security-reviewer** after build-verifier (parallel when both apply).
+- Add **tech-writer** when docs/changelog requested.
+
 
 ## Model tiers (`steps[].model`)
 
@@ -90,6 +95,7 @@ Fixtures: `.cursor/team/fixtures/` (feature-full, feature-light, bugfix-standard
 |--------|-------------------|
 | feature, refactor, test-only | `["after:task-analyst"]` |
 | spec-gen | `["after:task-analyst"]` |
+| openspec-change | `["after:task-analyst"]` (human approves brief + AC; openspec-author emits drafts and validator receipts under the assigned change-id) |
 | migration | `["after:migration-specialist"]` |
 | unit-only | `["after:unit-test-planner"]` when new plan |
 | e2e-only / integration | `["after:integration-test-planner"]` when new plan |
@@ -113,7 +119,9 @@ Detect and set routing reasons when the user asks to **generate / bootstrap prod
 | `/spec-start`, "bootstrap docs/specs", "generate product spec" | `spec-gen` | task-analyst (**author mode**) → human gate → stop (or continue to feature-developer only if implement-after) |
 | Feature/task with AC "generate specs" / missing INDEX + bootstrap AC | `spec-gen` inside feature profile | task-analyst author mode first; **not** a separate agent step |
 
-Do **not** add a dedicated `spec-author` agent. Do not require solution-architect for routine spec authoring.
+Do **not** add a dedicated `spec-author` agent for `docs/specs/**`. Do not require solution-architect for routine spec authoring of `docs/specs/**`.
+
+**openspec is a different file tree** (`openspec/changes/`, `openspec/specs/`) — it is not `docs/specs/`. The dedicated agent `openspec-author` lives in `agents/openspec-author.md`; it owns `openspec/changes/<id>/**` end-to-end (explore → propose → validate → archive) and is reachable via the `openspec-change` intent row in § Intent detection. Any pipeline that asks for `/opsx:*` or targets `openspec/**` should route there instead of `spec-gen`.
 
 
 **specMode (optional `pipeline.json` field):** `none` for spike/research; `generate` for `spec-gen` / `/spec-start`; `consume` default when INDEX exists. Echo top-level `specMode`. Brief `## Spec mode` wins on conflict.

package/presets/cursor/go/agents/tech-writer.md

@@ -14,6 +14,10 @@ Write documentation from task artifacts (brief, architecture, implementation, re
 
 Do not change production `.go` business logic.
 
+## OpenSpec (`openspec/changes/**`, `openspec/specs/**`)
+
+The `openspec/**` file tree is owned by the dedicated agent **`openspec-author`**, not by this agent. When a handoff brief or pipeline step mentions `/opsx:propose`, `/opsx:apply`, `/opsx:archive`, `openspec/changes/`, or `openspec/specs/`, hand off to `openspec-author` instead of authoring here. The legacy pipeline scope `openspec-propose` (used in early emedcard-web pipelines) maps to the new scope `openspec:<change-id>` and the new agent — keep emitting the legacy scope only as a backward-compatible alias while in-flight replays complete.
+
 ## Product specs (docs/specs)
 
 Post-delivery: when behavior or public docs changed and `docs/specs/` is in play, load **`product-specs`** (+ **`product-specs-authoring`** if updating specs). Sync page/feature specs + INDEX in the **same change set**. **Never invent** product behavior without AC/code source; label inferred lines `status: draft`. Soft-fail on miss; no-op if INDEX absent and sync not requested.

package/presets/cursor/go/commands/README.md

@@ -8,8 +8,6 @@ Slash commands are copied to `.cursor/commands/` on `ai-rules init cursor --pres
 |---------|------------|
 | **`/task <description>`** | **Main entry point:** router → pipeline.json → required roles in order |
 | `/task-continue <slug>` | After a human gate or pause |
-| `/feature-start <description>` | Legacy: analyst only (no router) |
-| `/feature-continue <slug>` | Alias task-continue |
 | `/technical-retro [slug]` | Retro; with slug — “Agent work” block |
 
 ## `/task` examples

package/presets/cursor/go/commands/task-continue.md

@@ -5,7 +5,7 @@ description: Continue an agent-team task after a human gate, pause, or review ch
 
 # Task continue — after human gate or pause
 
-Resume the pipeline from `pipeline.json`. Semantic alias: `/feature-continue`.
+Resume the pipeline from `pipeline.json`.
 
 ## Arguments
 

package/presets/cursor/go/commands/task.md

@@ -33,7 +33,7 @@ Examples:
    - **do not** write lifecycle fields in `status.json` / `metrics.json` yourself — orchestration runtime/hook owns them (see **agent-artifact-contracts**). If `status.json` is missing, only minimal bootstrap is allowed (`slug`, `intent`, `pipelineIndex: 0`, `currentAgent: steps[0]`, `state: in_progress`) — **do not** increment `pipelineIndex` manually;
    - invoke subagent for `pipeline.steps[0].agent` (slug, artifact paths, scope).
 6. **After each agent** — wait for hook handoff / reconciliation terminal receipt → `status.state`; do not start the next step until `status.json` reflects handoff (or until there is a `followup_message` from the hook).
-7. **Human gate** — if after the current step there is a gate in `humanGates` (`after:<agent>`), after the agent finishes **stop** and ask for `/task-continue <slug>` (or `/feature-continue <slug>`).
+7. **Human gate** — if after the current step there is a gate in `humanGates` (`after:<agent>`), after the agent finishes **stop** and ask for `/task-continue <slug>`.
 
 ## Do not
 
@@ -46,9 +46,6 @@ Examples:
 - `awaitingHumanGate` / `state: awaiting_approval` → offer artifact review or `/task-continue <slug>`.
 - `in_progress` → ask: continue or new slug.
 
-## Legacy
-
-`/feature-start` and `/feature-continue` remain compatible; for new tasks prefer `/task`.
 
 ## Metrics
 

package/presets/cursor/go/commands/technical-retro.md

@@ -10,7 +10,7 @@ The agent acts as a **neutral facilitator of a technical retrospective**, not as
 ## When to use
 
 - User asks: "retro", "technical retro", "sprint/iteration review", "action items after release" — also common RU phrasing: «ретро» (retro), «техническое ретро» (technical retro), «разбор спринта/итерации» (sprint/iteration review) <!-- i18n-keep: E4 -->.
-- After completing the agent-team pipeline (`/feature-start` → `/feature-continue`).
+- After completing the agent-team pipeline.
 - Context available: period, topic (release, incident), task slug, notes.
 
 ## Inputs (gather; do not invent)
@@ -53,7 +53,7 @@ Do not attribute facts not present in artifacts, diff, or the user's message.
 
 ## "Agent work" block (required when slug present)
 
-If retro is tied to a `/feature-start` pipeline:
+If retro is tied to an agent-team pipeline:
 
 | Question | What to capture |
 |--------|-----------------|

package/presets/cursor/go/hooks/chain-team-phases.sh

@@ -65,10 +65,20 @@ const STACK = 'go';
 const PLATFORM = 'cursor';
 
 function waitForMetricsLock() {
+  // OD-1: real advisory lock via create-exclusive (fs.openSync(_, 'wx')).
+  // The previous impl spun on Atomics.wait against an unrelated SharedArrayBuffer
+  // and never blocked on the lock file, so two concurrent subagentStop events
+  // could both acquire the lock and corrupt metrics.json. Retry EEXIST with a
+  // 10 ms sleep up to 200 attempts (2 s ceiling). On any other error, throw.
   for (let attempt = 0; attempt < 200; attempt += 1) {
-    try { fs.mkdirSync(METRICS_LOCK); return; } catch (error) {
-      if (error && error.code !== 'EEXIST') throw error;
-      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 10);
+    try {
+      const fd = fs.openSync(METRICS_LOCK, 'wx');
+      try { fs.closeSync(fd); } catch {}
+      return;
+    } catch (error) {
+      if (!error || error.code !== 'EEXIST') throw error;
+      const until = Date.now() + 10;
+      while (Date.now() < until) { /* 10 ms busy-wait */ }
     }
   }
   throw new Error('metrics lock timeout');
@@ -77,7 +87,7 @@ let taskLockHeld = false;
 function releaseTaskLock() {
   if (!taskLockHeld) return;
   taskLockHeld = false;
-  try { fs.rmdirSync(METRICS_LOCK); } catch {}
+  try { fs.unlinkSync(METRICS_LOCK); } catch {}
 }
 waitForMetricsLock();
 taskLockHeld = true;
@@ -105,7 +115,7 @@ function mutateMetrics(mutator) {
     fs.writeFileSync(temporary, JSON.stringify(metrics, null, 2) + '\n');
     fs.renameSync(temporary, METRICS_PATH);
   } finally {
-    if (acquiredHere) { try { fs.rmdirSync(METRICS_LOCK); } catch {} }
+    if (acquiredHere) { try { fs.unlinkSync(METRICS_LOCK); } catch {} }
   }
 }
 function appendMetric(event) { mutateMetrics((metrics) => metrics.events.push({ eventId: `${metrics.task.runId}:${Date.now()}:${Math.random().toString(16).slice(2)}`, ...event })); }
@@ -134,10 +144,17 @@ const DEFAULT_ARTIFACT_OUTPUT_IDS = {
   'build-verifier': 'validation',
   'code-reviewer': 'review',
   'security-reviewer': 'security-review',
-  'accessibility-reviewer': 'a11y-review',
   'performance-auditor': 'perf-report',
   'api-contract-reviewer': 'api-contract-review',
   'tech-writer': 'documentation',
+  'openspec-author': 'openspec-change',
+  'qa-tester': 'qa',
+  'unit-test-planner': 'unit-test-plan',
+  'unit-test-generator': 'unit-test-spec',
+  'unit-test-healer': 'unit-test-heal',
+  'integration-test-planner': 'integration-test-plan',
+  'integration-test-generator': 'integration-test-spec',
+  'integration-test-healer': 'integration-test-heal',
 };
 function artifactOutputIdFor(step, agent) {
   if (step && typeof step.artifactOutputId === 'string') return step.artifactOutputId;
@@ -242,7 +259,17 @@ function recordSkippedStep(step, stepIndex) {
 function writeStatus(next) {
   status = { ...status, ...next, slug, updatedAt: now };
   const temporary = `${statusPath}.${process.pid}.${Date.now()}.tmp`;
-  fs.writeFileSync(temporary, JSON.stringify(status, null, 2) + '\n');
+  // Open + write + fsync + rename so the durable file lands on disk before
+  // the orchestrator reads it. Closes the race window where a subagent that
+  // completed milliseconds before writeStatus() could otherwise invoke the
+  // next step on a stale status (in particular the human-gate write).
+  const fd = fs.openSync(temporary, 'w');
+  try {
+    fs.writeSync(fd, JSON.stringify(status, null, 2) + '\n');
+    try { fs.fsyncSync(fd); } catch {}
+  } finally {
+    fs.closeSync(fd);
+  }
   fs.renameSync(temporary, statusPath);
 }
 
@@ -337,6 +364,12 @@ const AGENT_HANDOFF = {
     `Follow tests-integration.mdc, integration-testing, and debug-investigation. Do not use browser e2e tooling. Upsert the owned terminal receipt in artifact-manifest.json; do not mutate status.json lifecycle fields.`,
   'tech-writer': (s) =>
     `Invoke tech-writer for slug "${s}". Write documentation.md from task artifacts. Upsert the owned terminal receipt in artifact-manifest.json; do not mutate status.json lifecycle fields.`,
+  'openspec-author': (s, scope) =>
+    `Invoke openspec-author for slug "${s}"${scope ? ` (scope: ${scope})` : ''}. ` +
+    `Read openspec/config.yaml schema + rules; if openspec/** is absent, emit blocked ("openspec/** not initialized"). ` +
+    `Author openspec/changes/<change-id>/{proposal.md, design.md, tasks.md, .openspec.yaml} and the capability spec delta per phase (explore|propose|apply|archive). ` +
+    `Run \`openspec validate <change-id> --type change --strict\` and \`openspec validate --specs --strict\` (Phase 3); surface FAIL output verbatim. ` +
+    `Upsert the owned terminal receipt (artifactOutputId \`openspec-change\`) in artifact-manifest.json with validator exit code + evidence paths; do not mutate status.json lifecycle fields. `,
 };
 
 const REVIEW_AGENTS = new Set([
@@ -457,7 +490,19 @@ function legacyFlow() {
 
 
 if (hookInput.action === 'end_human_gate') {
-  status.awaitingHumanGate = false;
+    status.awaitingHumanGate = false;
+  // A2 (retro §8): pin a single runId per pipeline so subsequent events don't
+  // fragment the metrics ledger across multiple runId sequences. Prefer
+  // metrics.json.task.runId when metrics already exist, then status.metricsRunId,
+  // then mint a fresh seed only on first ever emit.
+  try {
+    if (fs.existsSync(METRICS_PATH)) {
+      const existing = JSON.parse(fs.readFileSync(METRICS_PATH, 'utf8'));
+      if (existing && existing.task && typeof existing.task.runId === 'string') {
+        status.metricsRunId = existing.task.runId;
+      }
+    }
+  } catch {}
   if (status.state === 'awaiting_approval') {
     status.state = 'in_progress';
     status.phase = status.phase === 'human_gate' ? 'executing' : status.phase;
@@ -496,11 +541,29 @@ if (hookInput.action === 'end_human_gate') {
       }
     }
   }
-  writeStatus({
-    awaitingHumanGate: false,
-    state: status.state,
-    phase: status.phase,
-  });
+  // A2 (retro §8): if gate closes the final human gate of the pipeline
+  // (no resume happens, or current step's gate was the last), surface
+  // state="awaiting_approval" so a subsequent /task-continue doesn't misinterpret
+  // the post-gate idle state as "still in progress".
+  {
+    let gateWasTerminal = false;
+    if (!hookInput.activateNext && fs.existsSync(pipelinePath)) {
+      try {
+        const pipe = JSON.parse(fs.readFileSync(pipelinePath, 'utf8'));
+        const steps = pipe.steps || [];
+        const idx = typeof status.pipelineIndex === 'number' ? status.pipelineIndex : 0;
+        const cur = steps[idx];
+        const gates = Array.isArray(pipe.humanGates) ? pipe.humanGates : [];
+        const hasGate = (step) => Array.isArray(gates) && gates.some((g) => typeof g === 'string' && getStepAgents(step).some((a) => g === `after:${a}`));
+        if (cur && hasGate(cur)) gateWasTerminal = true;
+      } catch {}
+    }
+    writeStatus({
+      awaitingHumanGate: false,
+      state: gateWasTerminal ? 'awaiting_approval' : status.state,
+      phase: status.phase,
+    });
+  }
   process.stdout.write(JSON.stringify({ ok: true, action: 'end_human_gate', activeHumanGateEventId: status.activeHumanGateEventId || null }));
   process.exit(0);
 }
@@ -510,9 +573,37 @@ if (!fs.existsSync(pipelinePath)) {
 }
 
 let pipeline;
+let pipelineParseError = null;
 try {
   pipeline = JSON.parse(fs.readFileSync(pipelinePath, 'utf8'));
-} catch {
+} catch (error) {
+  pipelineParseError = error;
+}
+// Modern pipelines carry an `intent` field. If pipeline.json is present but
+// unparseable, surface the error so the orchestrator can stop and report
+// instead of falling back to legacyFlow() — which silently drops modern
+// roles like `openspec-author`, `qa-tester`, and the test-planner trio.
+if (pipelineParseError) {
+  if (fs.existsSync(pipelinePath)) {
+    const raw = fs.readFileSync(pipelinePath, 'utf8');
+    const hasModernIntent = /"intent"\s*:/.test(raw);
+    appendMetric({
+      eventId: `${status.metricsRunId || slug}:pipeline_parse_error:${Date.now()}`,
+      type: 'pipeline_parse_error',
+      at: now,
+      source: 'hook',
+      attributionConfidence: 'high',
+      error: String(pipelineParseError.message || pipelineParseError),
+      hasModernIntent,
+    });
+    if (hasModernIntent) {
+      writeStatus({ state: 'blocked', phase: 'blocked', currentAgent: 'task-router' });
+      process.stdout.write(JSON.stringify({
+        followup_message: `pipeline.json is malformed for slug "${slug}" — JSON parse error: ${pipelineParseError.message}. Re-run the task-router to regenerate pipeline.json, then resume via /task-continue ${slug}.`,
+      }));
+      process.exit(0);
+    }
+  }
   legacyFlow();
 }