@bonesofspring/ai-rules 0.2.20 → 0.2.21

package/CHANGELOG.md

@@ -2,6 +2,34 @@
 
 ## Unreleased
 
+### Chain-team-phases hook coverage + pipeline race fixes
+
+- `chain-team-phases.sh` (all 20 stack × platform hooks) now covers every agent that ships in its stack's `agents/` directory:
+  - `DEFAULT_ARTIFACT_OUTPUT_IDS` and `AGENT_HANDOFF` are kept symmetric via a new hard gate **`scripts/check-chain-hook-coverage.sh`** (wired into `check:preset-structure`).
+  - Missing entries that previously caused pipelines to silently stall in `awaiting_artifact_receipt` are now filled in: `openspec-author` (`openspec-change`), `qa-tester` (`qa`), `unit-test-{planner,generator,healer}` (`unit-test-{plan,spec,heal}`), `playwright-test-*` (`e2e-{plan,spec,heal}`), `instrumentation-test-*` (`instr-test-*`), `integration-test-*` (`integration-test-*`), `xcuitest-test-*` (`xcuitest-*`), and `debugger` (`debug`).
+  - Dead `accessibility-reviewer` / `mockup-reviewer` entries removed from backend stacks (`go`, `java`, `php-hexagonal`, `php-laravel`, `mcp-ts`) per `preset-no-cross-stack-leakage`.
+  - The 20 `chain-team-phases.sh` files (10 stacks × 2 platforms) are byte-wise unique — MD5 verified — per `preset-no-cross-stack-leakage.mdc:97-99` (Chain fork).
+- `writeStatus()` now opens the temp file, writes, `fsyncSync()`s, then renames. Closes the race where a `subagentStop` could let the orchestrator read stale `status.json` and bypass a `humanGates` transition.
+- A malformed `pipeline.json` carrying a modern `intent` field no longer falls through to `legacyFlow()` (which silently dropped `openspec-author`, `qa-tester`, and the test trio). The hook now writes `state: blocked`, emits a `pipeline_parse_error` metric event, and surfaces a `followup_message` naming the parse error and instructing `/task-continue <slug>`.
+- Shared core: `_shared/core/agent-team/agent-artifact-contracts.md` and `agent-task-metrics.md` updated with the new default producer → entry rows and the `pipeline_parse_error` event type.
+- New test harness **`scripts/test-chain-team-phases-coverage.mjs`** (and `test:agent-task-metrics-hooks.mjs` count fix from 14 → 20 hooks): drives `openspec-author`, `qa-tester`, pipeline misparse, legacy fallback, and writeStatus durability across all 20 hooks. Wired into `check:preset-structure`.
+- Dogfooded `.cursor/hooks/chain-team-phases.sh` synced from the next preset via `sync-dogfood-cursor.sh`.
+- Consumers: re-run `npx @bonesofspring/ai-rules init cursor|claude --preset <stack>` after publish to pick up the hook updates; if you maintain a custom `chain-team-phases.sh`, run `bash scripts/check-chain-hook-coverage.sh` after editing.
+
+### New `openspec-author` agent — openspec/** lifecycle
+
+- New dedicated agent **`openspec-author`** for the OpenSpec (Fission AI `@fission-ai/openspec`) file tree: `openspec/changes/**` (proposal/design/tasks/spec deltas) and `openspec/specs/**` refresh. Owns the full lifecycle `explore → propose → apply → archive` against `openspec/config.yaml`. Reads `app/**` for evidence, never edits production code. Readonly role on `docs/specs/**` — that tree still belongs to `tech-writer`.
+- New router intent **`openspec-change`** in `task-router` (Cursor + Claude, all 9 installable stacks with `docs-only` intent: `next`, `nuxt`, `svelte`, `ios-swift`, `android-kotlin`, `go`, `java`, `php-hexagonal`, `php-laravel`). Default step: `task-analyst → solution-architect (skipIf no architecture delta) → openspec-author (scope: "openspec:<change-id>")`. Human gate `["after:task-analyst"]`.
+- `tech-writer` carries a redirect note: when a handoff brief or pipeline step mentions `/opsx:propose`, `/opsx:apply`, `/opsx:archive`, `openspec/changes/`, or `openspec/specs/`, hand off to `openspec-author`. The legacy pipeline scope `openspec-propose` is retained as a backward-compatible alias and routes through the new agent.
+- Consumer migration: `emedcard-web` pipelines (`online-consultation-spec`, `openspec-sync-medcard-11762`) updated to `openspec-author` + `scope: "openspec:<change-id>"`.
+- Consumers: re-run `npx @bonesofspring/ai-rules init cursor|claude --preset <stack>` after publish to install the new agent and router intent.
+
+### Remove deprecated `/feature-start` and `/feature-continue`
+
+- Remove deprecated `/feature-start` and `/feature-continue` commands across all stack presets; use `/task` and `/task-continue` instead.
+- 40 preset command files deleted from this monorepo (`packages/ai-rules/presets/{claude,cursor}/<stack>/commands/{feature-start,feature-continue}.md`, 10 stacks × 2 platforms × 2 commands). The equivalent deletions in three sub-repo dogfood mirrors (`dogfood/go-hexagonal`, `dogfood/java-spring-hexagonal`, `dogfood/mcp-ts-sample`) are part of the same change set but live in separate git trees. Cross-references in `commands/README.md`, `agents/README.md`, `team/README.md`, `rules/README.md`, `AGENTS.md` / `CLAUDE.md`, `agent-team-orchestrator`, and `commands/{task,task-continue,technical-retro}.md` updated.
+- Consumers: re-run `npx @bonesofspring/ai-rules init cursor|claude --preset <stack>` after publish; both legacy commands are no longer installed.
+
 ### Superpowers B1–B5 (all installable stacks)
 
 - All 10 stacks (Cursor + Claude): **verification-before-completion** lineage snippet on `build-verifier` / `feature-developer` only. `debugger` keeps inline 3-fix + `fixApplied` re-run (skill cross-ref) — not the verification stem. **receiving-code-review** embed on `code-review` skill; implementer one-liner on `feature-developer`, `debugger`, and `ci-investigator` (where those agents exist). Debug skill 4-phase + 3-fix architecture gate; task-analyst/router classify spike / bounded / architectural onto **existing** pipeline profiles.

package/README.md

@@ -72,7 +72,21 @@ Presets support **behavior specs** under `docs/specs/**` (INDEX, frontmatter v1,
 
 **Optional validation** (from `packages/ai-rules/`): `yarn check:product-specs <repo-root>` (WARN) or `--strict` (FAIL). Monorepo dogfood example: `dogfood/mcp-ts-sample/docs/specs/`.
 
-The package ships presets including **`next`** (Next.js stack), **`nuxt`** (Nuxt 3 / Vue 3 / Pinia), **`svelte`** (SvelteKit / Svelte 5 / TypeScript / `store-svelte`), **`ios-swift`** (iOS apps on Swift / SwiftUI), **`android-kotlin`** (Android multimodule Kotlin / Compose / Gradle), **`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 `.`.
+## OpenSpec (`openspec/**`)
+
+OpenSpec (Fission AI `@fission-ai/openspec`) is a **separate spec-driven tree** that lives alongside `docs/specs/`:
+
+| Tree | Owned by | Where |
+|------|----------|-------|
+| `docs/specs/**` | `tech-writer` (product specs) | Generated/consumed by `task-analyst` + `tech-writer` |
+| `openspec/changes/**` | **`openspec-author`** (new agent) | `proposal.md` / `design.md` / `tasks.md` / `specs/**` deltas per `openspec/config.yaml` schema |
+| `openspec/specs/**` | **`openspec-author`** (new agent) | Applied capabilities; refreshed when a change is archived |
+
+The dedicated agent **`openspec-author`** owns the full lifecycle: `explore → propose → apply → archive`. It is reachable from the new router intent `openspec-change` (`/opsx:propose`, `/opsx:apply`, `/opsx:archive`, `openspec/changes`, `openspec/specs`, "OpenSpec change", "обнови openspec"). Default pipeline: `task-analyst → solution-architect (skipIf no architecture delta) → openspec-author (scope: "openspec:<change-id>")`. Scope is always `openspec:<change-id>` — the legacy `scope: openspec-propose` alias is kept on `tech-writer` for backward compatibility.
+
+`openspec-author` is installed for **all 9 installable stacks that ship a `docs-only` intent** (everything except `mcp-ts`): `next`, `nuxt`, `svelte`, `ios-swift`, `android-kotlin`, `go`, `java`, `php-hexagonal`, `php-laravel`. Read-only against `app/**` and `docs/specs/**` — the agent only emits the openspec tree and reads production code for evidence.
+
+The package ships presets including **`next`** (Next.js stack), **`nuxt`** (Nuxt 3 / Vue 3 / Pinia), **`svelte`** (SvelteKit / Svelte 5 / TypeScript / `store-svelte`), **`ios-swift`** (iOS apps on Swift / SwiftUI), **`android-kotlin`** (Android multimodule Kotlin / Compose / Gradle), **`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). Preset name is a single path segment (letters, digits, `.`, `_`, `-`); `..` is rejected.
 
 ```bash
 npx @bonesofspring/ai-rules init cursor --preset nuxt
@@ -102,7 +116,8 @@ Help: `ai-rules --help`.
 Presets are developed in this monorepo under `presets/`. If you add or change rules, agents, or platform artifacts:
 
 - **Taxonomy & layers:** [`presets/_shared/README.md`](presets/_shared/README.md) — shared core (`_shared/core`), stack adapters, platform packaging (includes requestable embed stem `architecture/product-specs` for consumer `docs/specs` INDEX discovery)
-- **Contribution guide:** [`docs/PRESET-CONTRIBUTION.md`](docs/PRESET-CONTRIBUTION.md) — SoT, twin sync, embed vs lineage, token budget (≤3 always-on), PR checklist, new stack preset, platform-only files (`BUGBOT.md`, `CLAUDE.md`)
+- **Contribution guide:** [`docs/PRESET-CONTRIBUTION.md`](docs/PRESET-CONTRIBUTION.md) — SoT, twin sync, embed vs lineage, token budget (Cursor ≤4 / Claude exactly 3 always-on), PR checklist, new stack preset, platform-only files (`BUGBOT.md`, `CLAUDE.md`)
+- **Local overlay (`.ai.local/`):** [`docs/LOCAL-OVERLAY.md`](docs/LOCAL-OVERLAY.md) — consumer-owned rules with priority over preset rules; works for Cursor and Claude Code from the same files
 - **Dogfood / drift scripts:** [`scripts/sync-dogfood-cursor.sh`](scripts/sync-dogfood-cursor.sh) (also syncs root `AGENTS.md` from `REPO_AGENTS.md`; seeds `team/conventions.md` if absent), [`scripts/check-shared-core-drift.sh`](scripts/check-shared-core-drift.sh). Published npm `files` include `scripts/` so consumers can run `check-product-specs.sh` from the package.
 - **Preset structure CI gates** (exit non-zero on FAIL): `yarn check:preset-structure` (or `bash scripts/check-preset-structure.sh`) — twin map, session-start budget (Option A), leakage, shared-core drift (`AI_RULES_DRIFT_FAIL=1`)
 - **Opt-in rule eval:** `yarn check:rule-eval` + `.github/workflows/rule-eval.yml` (`workflow_dispatch` + paths-scoped PR) — **not** wired into `check:preset-structure`

package/bin/cli.js

@@ -428,6 +428,12 @@ function presetHasAnySource(base, cfg) {
 }
 
 function resolveTargetCwd(cwdOption) {
+  // Reject empty string explicitly: `path.resolve('')` silently returns cwd,
+  // turning `--cwd ""` into a footgun that mutates the wrong directory.
+  if (cwdOption !== undefined && cwdOption === '') {
+    console.error('--cwd requires a non-empty path (use --cwd <dir> or omit for current directory)');
+    process.exit(1);
+  }
   const cwd = cwdOption ? path.resolve(cwdOption) : process.cwd();
   if (!fs.existsSync(cwd)) {
     console.error(`Target directory does not exist: ${cwd}`);
@@ -496,24 +502,41 @@ function cmdInit(tool, preset, cwdOption) {
   fs.mkdirSync(toolRootAbs, { recursive: true });
 
   let copiedSteps = 0;
+  // Track newly created paths so we can roll back on partial failure.
+  // Only deletes paths that did not exist before this run — never consumer files.
+  const toolRootExisted = fs.existsSync(toolRootAbs);
+  const createdPaths = new Set();
+  const docsSpecsDir = path.join(cwd, 'docs', 'specs');
+  const docsSpecsExisted = fs.existsSync(docsSpecsDir);
+
+  const trackDir = (dir) => {
+    if (!fs.existsSync(dir)) return;
+    createdPaths.add(dir);
+  };
 
   try {
     if (tool === 'claude' && cfg.claudeMdSrc) {
       const mdFrom = path.join(base, cfg.claudeMdSrc);
       if (fs.existsSync(mdFrom)) {
-        fs.copyFileSync(mdFrom, path.join(toolRootAbs, 'CLAUDE.md'));
+        const destAbs = path.join(toolRootAbs, 'CLAUDE.md');
+        fs.copyFileSync(mdFrom, destAbs);
+        createdPaths.add(destAbs);
         console.log(`Copied CLAUDE.md → ${path.join(toolRoot, 'CLAUDE.md')}`);
         copiedSteps++;
       }
     }
 
     if (fs.existsSync(rulesSrc)) {
-      copyDir(rulesSrc, path.join(cwd, cfg.rulesDir));
+      const dest = path.join(cwd, cfg.rulesDir);
+      trackDir(dest);
+      copyDir(rulesSrc, dest);
       console.log(`Copied rules → ${cfg.rulesDir}`);
       copiedSteps++;
     }
     if (fs.existsSync(commandsSrc)) {
-      copyDir(commandsSrc, path.join(cwd, cfg.commandsDir));
+      const dest = path.join(cwd, cfg.commandsDir);
+      trackDir(dest);
+      copyDir(commandsSrc, dest);
       console.log(`Copied commands → ${cfg.commandsDir}`);
       copiedSteps++;
     }
@@ -521,7 +544,9 @@ function cmdInit(tool, preset, cwdOption) {
     for (const name of getOptionalDirs(cfg)) {
       const src = path.join(base, name);
       if (fs.existsSync(src)) {
-        copyDir(src, path.join(toolRootAbs, name));
+        const dest = path.join(toolRootAbs, name);
+        trackDir(dest);
+        copyDir(src, dest);
         console.log(`Copied ${name}/ → ${toolRoot}/${name}/`);
         copiedSteps++;
       }
@@ -530,7 +555,9 @@ function cmdInit(tool, preset, cwdOption) {
     if (tool === 'cursor' && cfg.hooksJsonSrc) {
       const hooksFrom = path.join(base, cfg.hooksJsonSrc);
       if (fs.existsSync(hooksFrom)) {
-        fs.copyFileSync(hooksFrom, path.join(toolRootAbs, 'hooks.json'));
+        const destAbs = path.join(toolRootAbs, 'hooks.json');
+        fs.copyFileSync(hooksFrom, destAbs);
+        createdPaths.add(destAbs);
         console.log(`Copied hooks.json → ${toolRoot}/hooks.json`);
         copiedSteps++;
       }
@@ -540,6 +567,11 @@ function cmdInit(tool, preset, cwdOption) {
       const mcpFrom = path.join(base, cfg.mcpJsonSrc);
       if (fs.existsSync(mcpFrom)) {
         const mcpDestAbs = path.join(cwd, cfg.mcpJsonDest);
+        // installMcpJson may write or merge; only track newly created destinations
+        // so we do not delete user-edited mcp.json on rollback.
+        if (!fs.existsSync(mcpDestAbs)) {
+          createdPaths.add(mcpDestAbs);
+        }
         installMcpJson(mcpFrom, mcpDestAbs, cfg.mcpJsonDest);
         copiedSteps++;
       }
@@ -548,7 +580,9 @@ function cmdInit(tool, preset, cwdOption) {
     for (const name of cfg.toolRootFiles || []) {
       const from = path.join(base, name);
       if (fs.existsSync(from)) {
-        fs.copyFileSync(from, path.join(toolRootAbs, name));
+        const destAbs = path.join(toolRootAbs, name);
+        fs.copyFileSync(from, destAbs);
+        createdPaths.add(destAbs);
         console.log(`Copied ${name} → ${toolRoot}/${name}`);
         copiedSteps++;
       }
@@ -558,6 +592,9 @@ function cmdInit(tool, preset, cwdOption) {
       const from = path.join(base, srcName);
       if (fs.existsSync(from)) {
         const destAbs = path.join(cwd, destRel);
+        if (!fs.existsSync(destAbs)) {
+          createdPaths.add(destAbs);
+        }
         fs.mkdirSync(path.dirname(destAbs), { recursive: true });
         fs.copyFileSync(from, destAbs);
         console.log(`Copied ${srcName} → ${destRel}`);
@@ -566,10 +603,15 @@ function cmdInit(tool, preset, cwdOption) {
     }
 
     if (seedDocsSpecsIfAbsent(packageRoot, cwd)) {
+      // Track docs/specs seed only if the directory did not exist before this run.
+      if (!docsSpecsExisted) {
+        createdPaths.add(docsSpecsDir);
+      }
       copiedSteps++;
     }
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
+    rollbackInit(createdPaths, toolRootExisted, toolRootAbs);
     console.error(`init failed: ${msg}`);
     process.exit(1);
   }
@@ -587,6 +629,41 @@ function cmdInit(tool, preset, cwdOption) {
   console.log(`Done. ${toolRoot} installed at ${toolRootAbs} (preset: ${presetName})`);
 }
 
+/**
+ * Remove files and directories created by cmdInit. Only deletes paths we know
+ * we created (or that did not exist before the run); never touches consumer files.
+ */
+function rollbackInit(createdPaths, toolRootExisted, toolRootAbs) {
+  // Sort deepest-first so files inside a directory are removed before the directory itself.
+  const paths = [...createdPaths].sort((a, b) => b.length - a.length);
+  const removed = [];
+  for (const p of paths) {
+    try {
+      if (!fs.existsSync(p)) continue;
+      const stat = fs.lstatSync(p);
+      if (stat.isDirectory()) {
+        fs.rmSync(p, { recursive: true, force: true });
+      } else {
+        fs.unlinkSync(p);
+      }
+      removed.push(p);
+    } catch {
+      // Best-effort: log nothing in rollback path, the caller already reported the failure.
+    }
+  }
+  // Only remove the tool root directory itself if we created it (i.e. it did not exist before).
+  if (!toolRootExisted && fs.existsSync(toolRootAbs)) {
+    try {
+      fs.rmSync(toolRootAbs, { recursive: true, force: true });
+    } catch {
+      // Ignore — the caller already reported the failure.
+    }
+  }
+  if (removed.length > 0) {
+    console.error(`Rolled back ${removed.length} path(s) created before failure.`);
+  }
+}
+
 function cmdClean(tool, cwdOption) {
   const cfg = PRESETS[tool];
   if (!cfg) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bonesofspring/ai-rules",
-  "version": "0.2.20",
+  "version": "0.2.21",
   "description": "Presets of Cursor and Claude rules/commands for Revy Ross personal use",
   "license": "MIT",
   "author": "Revy Ross",
@@ -31,12 +31,15 @@
     "check:preset-token-budget": "bash scripts/check-preset-token-budget.sh",
     "check:preset-leakage": "bash scripts/check-preset-leakage.sh",
     "check:hook-only-lifecycle": "bash scripts/check-hook-only-lifecycle.sh",
+    "check:local-overlay": "bash scripts/check-local-overlay.sh",
     "check:preset-i18n": "AI_RULES_I18N_FAIL=1 AI_RULES_I18N_SOFT=0 bash scripts/check-preset-i18n.sh",
     "check:shared-core-drift": "bash scripts/check-shared-core-drift.sh",
     "check:product-specs": "bash scripts/check-product-specs.sh",
     "check:product-specs:dogfood": "bash scripts/check-product-specs.sh ../../dogfood/mcp-ts-sample",
     "check:rule-eval": "node scripts/check-rule-eval.mjs",
-    "test:cli-mcp-merge": "node scripts/test-cli-mcp-merge.mjs"
+    "test:cli-mcp-merge": "node scripts/test-cli-mcp-merge.mjs",
+    "test:chain-coverage": "node scripts/test-chain-team-phases-coverage.mjs",
+    "test:agent-task-metrics-hooks": "node scripts/test-agent-task-metrics-hooks.mjs"
   },
   "engines": {
     "node": ">=18"

package/presets/_shared/README.md

@@ -36,10 +36,11 @@ Do **not** expect lineage adapters to byte-match core. Embed adapters should mat
 
 | Dir | Contents |
 |-----|----------|
-| `core/quality/` | Boy-scout + Principles (always-on slim); requestable `anti-sycophancy-discipline` (~17 rules); requestable `design-guidance` (smells ≤12 + GoF ≤8); requestable `mcp-usage`; embed `debug-investigation`; lineage `verification-before-completion` |
+| `core/quality/` | Boy-scout + Principles (always-on slim); requestable `anti-sycophancy-discipline` (~17 rules); requestable `design-guidance` (smells ≤12 + GoF ≤8); requestable `mcp-usage`; embed `debug-investigation`; inline-embed `verification-before-completion` (no standalone adapter — shipped via `agents/feature-developer.md` + `agents/build-verifier.md` + `skills/debug-investigation/SKILL.md`) |
 | `core/agent-team/` | Orchestrator + intake (pipeline language); lineage `task-classification` |
 | `core/architecture/` | Feature-delivery abstract + reference-features template + product-specs (+ product-specs-authoring) + assets/docs-specs templates |
 | `core/review/` | Code-review MR + technical-retro alias + mockup-review checklist + ux-design checklist; lineage `receiving-code-review` |
+| `core/testing/` | Test principles: behavior vs. implementation, locale-aware titles, isolation/mocks, fixture reuse, e2e scenario ↔ test traceability, page objects, PREFIX-XXX identifiers, selector priority |
 | `core/meta/` | Author-facing preset meta-rules |
 
 ## CLI note

package/presets/_shared/assets/docs-specs/INDEX.md

@@ -4,6 +4,9 @@ Discovery table for `docs/specs/**`. Agents start here when the file exists.
 
 | id | type | domain | title | path | routes | aliases | status |
 |----|------|--------|-------|------|--------|---------|--------|
-| <!-- example-row: example-page | page | example | Example page | docs/specs/domains/example/example-page.md | /example | ExamplePage | draft --> |
+
+```text
+<!-- example-row: example-page | page | example | Example page | docs/specs/domains/example/example-page.md | /example | ExamplePage | draft -->
+```
 
 <!-- Add one row per page/feature spec. Keep `id` and `path` in sync with frontmatter. -->

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

@@ -107,9 +107,22 @@ A producer finishes its step by upserting only its owned artifact entry and term
 | `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` |
+| `openspec-author` | `openspec-change` | `openspec/changes/<change-id>/**`, optional `.cursor/team/tasks/<slug>/openspec-change.md` |
+| `qa-tester` | `qa` | stack-native (e.g. `qa-report.md`, `qa-screenshot.png`) |
+| `unit-test-planner` | `unit-test-plan` | `unit-test-plan.md` |
+| `unit-test-generator` | `unit-test-spec` | `*.spec.ts` / `*.test.ts` / `*Tests.swift` |
+| `unit-test-healer` | `unit-test-heal` | same as `unit-test-generator` |
+| `playwright-test-planner` | `e2e-plan` | `app/__tests__/e2e/**/*.cases.md` |
+| `playwright-test-generator` | `e2e-spec` | `app/__tests__/e2e/**/*.spec.ts` |
+| `playwright-test-healer` | `e2e-heal` | same as `playwright-test-generator` |
+| `instrumentation-test-*` | `instr-test-plan` / `instr-test-spec` / `instr-test-heal` | Android instrumentation tests |
+| `integration-test-*` | `integration-test-plan` / `integration-test-spec` / `integration-test-heal` | backend integration tests |
+| `xcuitest-test-*` | `xcuitest-plan` / `xcuitest-spec` / `xcuitest-heal` | iOS XCUITest plans/specs |
 
 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.
 
+> **Leakage note:** `openspec-author` ships only in presets that bundle an `openspec-author.md` agent. `mcp-ts` (no UI/contracts author) does **not** ship the agent file or the default entry — do not backfill it into mcp-ts hooks. UI-only agents (`accessibility-reviewer`, `mockup-reviewer`) must **not** appear in `DEFAULT_ARTIFACT_OUTPUT_IDS` for backend stacks (`go`, `java`, `php-*`, `mcp-ts`) even as dead ids — drop them when copying a hook from a UI preset.
+
 **v1 UX artifact:** when `task-analyst` produces `ux-design.md`, append it to the **`analysis`** entry `authoritativePaths` and `evidencePaths`. Do **not** add a default producer row for `ux-designer` in v1.
 
 ## specMode

package/presets/_shared/core/agent-team/agent-task-metrics.md

@@ -16,7 +16,7 @@ Each pipeline run owns `<team>/tasks/<slug>/metrics.json`:
 
 `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`.
+Allowed event types are `task_started`, `attempt_started`, `attempt_finished`, `retry_scheduled`, `attempt_skipped`, `human_gate_started`, `human_gate_ended`, `pipeline_parse_error`, and `task_completed`. Terminal outcomes are `completed`, `changes_requested`, `validation_failed`, `skipped`, `cancelled`, or `unknown`.
 
 ## Collection policy
 

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

@@ -10,8 +10,6 @@ Work request without `/task` — see **agent-team-intake** (when to suggest the
 |---------|------|
 | **`/task <desc>`** | **Preferred** — router → dynamic pipeline → first agent |
 | `/task-continue <slug>` | After human gate or pause |
-| `/feature-start <desc>` | Legacy: analyst-only start (no router) |
-| `/feature-continue <slug>` | Alias of task-continue |
 | `/spec-start [desc]` | Generate/bootstrap `docs/specs` — router intent `spec-gen` → analyst author mode → human gate |
 | `/technical-retro [slug]` | Retro with agent team block |
 
@@ -188,7 +186,7 @@ After each agent completes, verify its terminal manifest receipt, then let the o
 
 ## Legacy mode
 
-If `pipeline.json` is missing (old `/feature-start` tasks), fall back to fixed phases: analysis → development → review → testing. Hook supports both.
+If `pipeline.json` is missing, fall back to fixed phases: analysis → development → review → testing. Hook supports both.
 
 ## Skip pipeline when
 

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

@@ -8,11 +8,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/_shared/core/meta/preset-token-budget.md

@@ -6,12 +6,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
 
@@ -27,4 +31,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/_shared/core/meta/preset-twin-sync.md

@@ -28,6 +28,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 is pending.** Today build-verifier excludes only `agent-team-intake` / `technical-retro` / `preset-layering`; slim-companion rules currently pass under the same human-judgement path as thin aliases. Follow-up: add `allow_slim_stems` to `packages/ai-rules/scripts/check-preset-token-budget.sh` analogous to `trio_stems_allowlist`.
 
 ## Severity (build-verifier)
 

package/presets/_shared/core/testing/testing-principles.md

@@ -0,0 +1,70 @@
+# Testing principles
+
+Stack-agnostic; concrete paths, runners, and selectors live in the stack adapter (`## Stack notes`).
+
+## Behavior vs. implementation
+
+- Verify **behavior and business rules**, not implementation or internal details.
+
+## File naming
+
+- For **new** tests use `*.spec.ts` / `*.spec.tsx`. Do not rename existing `*.test.ts` / `*.test.tsx` without a separate task (legacy).
+
+## Runner and matchers
+
+- Use the project's runner (Jest or Vitest are common); components — the project's Testing Library integration. Reuse existing matchers — no new micro-framework.
+
+## Test title locale
+
+- Consumer apps **may use the project locale** (often Russian) — clear business phrases stating what is checked and the expected outcome.
+- When ESLint enforces the locale (e.g. `jest/valid-title`): each sentence must start with a **capital letter** (including after `.`, `!`, `?`); a space after `.` followed by a lowercase letter is forbidden ("capital after period" violation).
+
+Good (Russian locale in consumer app):
+
+- `it('Возвращает пустой список. Пользователь не авторизован', () => {})` <!-- i18n-keep: E5 --> (Returns empty list. User is not authorized)
+
+Bad (no capital after period; or wrong locale for configured ESLint):
+
+- `it('Возвращает пустой список. пользователь не авторизован', () => {})` <!-- i18n-keep: E5 -->
+- `it('Returns empty list when user is guest', () => {})` (wrong locale if ESLint enforces Russian)
+
+## Isolation and mocks
+
+- Mock at the **public-contract boundary**; use the project's accepted HTTP/API/store mock approach. Do not mock what is part of the feature's public contract if that breaks the test's meaning.
+
+## Coverage of cross-cutting modules
+
+- When changing a **shared cross-cutting module** (e.g. HTTP client body parsing, headers, error / auth handling) — **update or add behavior tests** covering success, error, and edge branches relevant to the module under change.
+
+## Data transformation coverage
+
+- Data transformation functions with computed fields and branches must have unit tests covering edge cases (boundary values, missing fields, unexpected value combinations).
+
+## Reuse fixtures over ad-hoc random data
+
+- Prefer shared fixtures / handlers from the project's accepted mocks module; do not duplicate interfaces in tests. Use the API response types (DTO types) and the **target domain types** from the project's public type surface.
+
+## E2E: one canonical scenario plan per feature
+
+- For each feature keep a **single canonical scenario plan** (distinct from implementation specs; the stack adapter names the file — typically `*.cases.md`).
+
+## E2E: scenario ↔ test traceability
+
+- Every scenario has a corresponding test. **Do not weaken** assertions to match an outdated implementation — tests must reflect business expectations from the plan. Colocate plan and executable tests in the same directory.
+
+## E2E: page objects / shared helpers
+
+- Prefer page objects and shared helpers over scattered selectors and per-test setup duplication.
+
+## E2E: stable identifiers (PREFIX-XXX)
+
+- When scenarios need stable IDs, prefix the title with `PREFIX-XXX`: `PREFIX` = first letters of words in the entity under test (Latin uppercase); `XXX` = sequential number with three digits and leading zeros. Within one `PREFIX`, numbers must form a consistent sequence with no duplicates.
+- Example: `test('OH-001 Отображается список заказов', async ({ page }) => { ... })` <!-- i18n-keep: E5 --> (Order list is displayed)
+
+## E2E: selector priority
+
+- Prefer role/label selectors for accessibility and forms; fall back to `data-testid` for stable elements. Use a **hierarchical naming convention** on page roots and key interactive elements (stack adapter defines the scheme — typically `{parent}__{element}`).
+
+## E2E: keep plans and selectors in sync with UI
+
+- When changing UI: update selectors in page objects and cross-check with the scenario plan. When adding/changing tests: read the matching plan and sync scenario titles first.

package/presets/claude/android-kotlin/agents/README.md

@@ -30,13 +30,14 @@ When copying next pipeline templates: put Playwright / XCUITest / integration-te
 | code-reviewer, accessibility-reviewer, security-reviewer, performance-auditor, mockup-reviewer | team only |
 | qa-tester, unit-test-*, instrumentation-test-* | tests only |
 | tech-writer | docs only |
+| openspec-author | `openspec/**` only — used only when the consumer repo has `openspec/` initialized |
 
 ## Model tiers (mirror ios-swift)
 
 | Tier | Model hint | Typical agents |
 |------|------------|----------------|
 | **cheap** | `fast` / cheap | build-verifier, some generators/healers |
-| **standard** | `inherit` | feature-developer, debugger, ci-investigator, a11y, qa, unit-*, instrumentation-* |
+| **standard** | `inherit` | feature-developer, debugger, ci-investigator, a11y, qa, unit-*, instrumentation-*, openspec-author |
 | **strong** | `strong` | solution-architect, security-reviewer, mockup-reviewer (when scheduled) |
 
 ## Pipeline schema

package/presets/claude/android-kotlin/agents/feature-developer.md

@@ -1,6 +1,6 @@
 ---
 name: feature-developer
-description: Feature implementation specialist for Android Kotlin/Jetpack Compose. Implements tasks from decomposition.md following feature-delivery workflow. Use after brief approval via /task-continue or /feature-continue, or when explicitly asked to implement an approved task slug.
+description: Feature implementation specialist for Android Kotlin/Jetpack Compose. Implements tasks from decomposition.md following feature-delivery workflow. Use after brief approval via /task-continue, or when explicitly asked to implement an approved task slug.
 readonly: false
 model: inherit
 ---