@bonesofspring/ai-rules 0.2.20 → 0.2.22

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

@@ -30,6 +30,7 @@ You are a task router for a Next.js frontend agent team. You **do not** implemen
 | `unit-only` | «unit», «юнит» (unit), «mapper tests», «покрой маппер» (cover mapper), «почини unit» (fix unit) | unit-test-planner → unit-test-generator, or unit-test-healer | <!-- i18n-keep: E4 -->
 | `e2e-only` | «e2e», «playwright», «browser test», «сценарии e2e» (e2e scenarios), «почини e2e» (fix e2e) | playwright-test-planner → playwright-test-generator, or playwright-test-healer | <!-- i18n-keep: E4 -->
 | `docs-only` | «документация» (documentation), «README», «changelog», «ADR», «migration guide» | 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` | «рефакторинг» (refactoring), «без изменения поведения» (no behavior change), «почисти» (clean up) | task-analyst → feature-developer → build-verifier → code-reviewer | <!-- i18n-keep: E4 -->
 | `spike` | «исследуй» (investigate), «оцени» (estimate), «можно ли» (is it possible), «spike», proof of concept | task-analyst → solution-architect | <!-- i18n-keep: E4 -->
 | `retro` | «ретро» (retro), «разбор» (postmortem), «postmortem» | (no pipeline — orchestrator runs `/technical-retro`) | <!-- i18n-keep: E4 -->
@@ -131,6 +132,7 @@ Cursor mapping when orchestrator invokes Task: `cheap` → pass `model: "fast"`
 | `spec-gen` | `["after:task-analyst"]` |
 | `migration` | `["after:migration-specialist"]` |
 | `docs-only` | `["after:task-analyst"]` |
+| `openspec-change` | `["after:task-analyst"]` (human approves brief + AC; openspec-author emits drafts and validator receipts under the assigned change-id) |
 | `unit-only` | `["after:unit-test-planner"]` when new plan; `[]` for healer |
 | `e2e-only` | `["after:playwright-test-planner"]` when new plan; `[]` for healer |
 | `bugfix`, `review-only`, `ci-fix` | `[]` |
@@ -162,7 +164,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 above. 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/next/agents/tech-writer.md

@@ -43,6 +43,10 @@ Conventional commit / release note snippet.
 - Do not duplicate entire decomposition — summarize outcomes and how to use/extend.
 - May create or update files under `docs/**` when the task explicitly requests it; otherwise keep primary output in team artifacts.
 
+## 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/next/agents/unit-test-generator.md

@@ -16,7 +16,7 @@ You generate unit tests from project test plans.
 ## Rules
 
 1. Follow **`unit-testing` skill** and **`tests-unit.mdc`**.
-2. Write specs colocated with source: `*.spec.ts` / `*.spec.tsx` next to the module under test.
+2. Write specs under the mirrored path `app/src/<rel>` → `app/__tests__/unit/<rel>`; do not colocate them under `app/src/**`.
 3. Use `@testing-library/react` and `userEvent` for components; project test-store/mocks for store/API.
 4. `describe` / `it` titles in **Russian**, each sentence starting with a capital letter.
 5. Do not weaken or skip scenarios from the plan without documenting a blocker in the handoff.

package/presets/cursor/next/agents/unit-test-planner.md

@@ -19,7 +19,7 @@ Use the **`unit-testing` skill** and **`tests-unit.mdc`**.
 
 1. Map acceptance criteria to test scenarios (mappers, store logic, client behavior, components).
 2. Identify gaps vs existing specs — do not duplicate covered cases.
-3. Specify file paths for planned specs (colocated with source per project convention).
+3. Specify mirrored file paths for planned specs: `app/src/<rel>` → `app/__tests__/unit/<rel>`.
 4. List behavior branches: happy path, edge cases, error paths.
 
 ## Output

package/presets/cursor/next/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 human gate or pause |
-| `/feature-start <description>` | Legacy: analyst only (no router) |
-| `/feature-continue <slug>` | Alias for task-continue |
 | `/technical-retro [slug]` | Retro; with slug — “Agent work” section |
 
 ## `/task` examples

package/presets/cursor/next/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/next/commands/task.md

@@ -36,7 +36,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
 
@@ -49,9 +49,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/next/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/next/hooks/chain-team-phases.sh

@@ -64,10 +64,20 @@ const STACK = 'next';
 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');
@@ -76,7 +86,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;
@@ -104,7 +114,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 })); }
@@ -138,6 +148,14 @@ const DEFAULT_ARTIFACT_OUTPUT_IDS = {
   'mockup-reviewer': 'mockup-review',
   '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',
+  'playwright-test-planner': 'e2e-plan',
+  'playwright-test-generator': 'e2e-spec',
+  'playwright-test-healer': 'e2e-heal',
 };
 function artifactOutputIdFor(step, agent) {
   if (step && typeof step.artifactOutputId === 'string') return step.artifactOutputId;
@@ -244,7 +262,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);
 }
 
@@ -341,6 +369,12 @@ const AGENT_HANDOFF = {
     `Use playwright MCP when available. Follow playwright-agents.mdc and debug-investigation. 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([
@@ -461,7 +495,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;
@@ -500,11 +546,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);
 }
@@ -514,9 +578,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();
 }
 

package/presets/cursor/next/rules/README.md

@@ -14,13 +14,14 @@ Special Cursor Rule format:
 ### Starting a new task
 
 - **Agent team (recommended):** `/task <description>` — router picks roles and order; on human gate — `/task-continue <slug>`. See **`agent-team-orchestrator.mdc`** and `.cursor/team/README.md`.
-- **Legacy:** `/feature-start` → `/feature-continue`.
+
 - **End-to-end layer checklist (for developer):** **`feature-delivery-workflow.mdc`**.
 
 ### Loading strategy
 
-- **`alwaysApply: true`** (Cursor) / **without `paths:`** (Claude) — only base invariants (**3**):
-  - `next-app-core`, `package-manager`, `code-quality-and-refactoring`
+- **`alwaysApply: true`** (Cursor) / **without `paths:`** (Claude) — base invariants (**Cursor ≤4**, Claude exactly 3):
+  - Cursor: `next-app-core`, `package-manager`, `code-quality-and-refactoring`, `ai-local-overlay`
+  - Claude: `next-app-core`, `package-manager`, `code-quality`
 - **On-demand / requestable** — `post-change-lint` (**required after code edits**, not always-on), `agent-team-intake` (via orchestrator/commands), `agent-team-orchestrator`, architecture, imports, UI, tests, feature-delivery-workflow, `design-guidance`, `mcp-usage`, `anti-sycophancy-discipline`, `react-next-anti-hallucination`, reference-features, product-specs, product-specs-authoring, next-app-router, `security-next`, react-a11y-coding, `technical-retro`, `mockup-review`, `ux-design`
 - **Preset author meta** (globs `packages/ai-rules/presets/**`, never alwaysApply): `preset-layering`, `preset-twin-sync`, `preset-token-budget`, `preset-pr-checklist`, `preset-no-cross-stack-leakage`
 - **Skills** — long procedures (`feature-delivery`, `spec-authoring`, `spec-discovery`, `code-review`, …)
@@ -46,6 +47,8 @@ SoT prose: `packages/ai-rules/presets/_shared/core/**` (see `_shared/README.md`)
 | `review/mockup-review.md` | `mockup-review.mdc` | Stack notes breakpoints; requestable |
 | `review/ux-design.md` | `ux-design.mdc` | Stack notes form-factor; requestable |
 | `meta/preset-*.md` | `preset-*.mdc` | author-only globs |
+| `testing/testing-principles.md` | `tests-unit.mdc` | Stack notes: `@testing-library/react`, `userEvent`, DOM matchers, `app/eslint.config.mjs` `jest/valid-title`, `app/src/mocks/**`, `app/src/lib/clients/**` |
+| `testing/testing-principles.md` | `tests-e2e-structure.mdc` | Stack notes: Playwright, `*.cases.md`, `_shared` folder, `{parent}__{element}` data-testid, `PREFIX-XXX` |
 
 Claude twins + Cursor→Claude map: `presets/claude/next/rules/README.md`.
 

package/presets/cursor/next/rules/agent-team-orchestrator.mdc

@@ -1,5 +1,5 @@
 ---
-description: Orchestrates the agent team via task-router and pipeline.json. Use for /task, /task-continue, /feature-start, task decomposition, or when the user describes a feature, bug, or review request.
+description: Orchestrates the agent team via task-router and pipeline.json. Use for /task, /task-continue, task decomposition, or when the user describes a feature, bug, or review request.
 alwaysApply: false
 ---
 
@@ -17,8 +17,6 @@ Work request without `/task` — see **`agent-team-intake.mdc`** (when to sugges
 |---------|------|
 | **`/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 |
 
@@ -57,7 +55,7 @@ Full prompts: `.cursor/agents/*.md`. Artifact conventions: `.cursor/team/README.
 
 **Behavioral UX:** `task-analyst` loads requestable skill `ux-design` for standalone intent `ux-design` and embedded required-signal / advisory UI AC. No `ux-designer` agent in v1.
 
-**Product specs:** When `/task`, `/feature-start`, or `/spec-start` touches pages/features/`docs/specs`: if INDEX exists and no generate intent → instruct next agent to load requestable **`product-specs`** (consume; soft-fail; never invent). If generate/bootstrap/`spec-gen` → load **`product-specs-authoring`** + skill **`spec-authoring`** inside **task-analyst** (not a separate pipeline step); pass created spec paths + INDEX diff in handoff; human gate must approve before feature-developer. No-op if INDEX absent and no author intent.
+**Product specs:** When `/task` or `/spec-start` touches pages/features/`docs/specs`: if INDEX exists and no generate intent → instruct next agent to load requestable **`product-specs`** (consume; soft-fail; never invent). If generate/bootstrap/`spec-gen` → load **`product-specs-authoring`** + skill **`spec-authoring`** inside **task-analyst** (not a separate pipeline step); pass created spec paths + INDEX diff in handoff; human gate must approve before feature-developer. No-op if INDEX absent and no author intent.
 
 When editing `packages/ai-rules/presets/**`, follow **`preset-pr-checklist.mdc`** (+ twin-sync / layering / token-budget / leakage meta-rules).
 
@@ -180,7 +178,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
 
@@ -196,3 +194,7 @@ Borderline work requests — see **`agent-team-intake.mdc`**.
 ## Auto-detection (optional)
 
 When user describes a **non-trivial task** (not a question), suggest `/task <message>` or run router if they agree.
+
+## Preset authoring
+
+When the work edits `packages/ai-rules/presets/**` (or dogfood `.cursor/` sync of presets), follow meta-rules: **preset-pr-checklist**, **preset-twin-sync**, **preset-layering**, **preset-token-budget**, **preset-no-cross-stack-leakage**.

package/presets/cursor/next/rules/ai-local-overlay.mdc

@@ -0,0 +1,43 @@
+---
+description: Local overlay from .ai.local/ (consumer-owned rules with priority over preset rules) — MANDATORY
+alwaysApply: true
+impact: CRITICAL
+---
+
+# Local overlay (`.ai.local/`) — MANDATORY
+
+This rule is mandatory. **You MUST** obey it on every turn, without exception.
+
+## On every turn
+
+1. **Probe** — before answering, run `ls -la .ai.local` from the repository root.
+2. **Walk** — if `.ai.local/` exists at multiple levels (monorepo), read every level from root to leaf. **Deeper wins** in practice: more specific rules appear later in the assembled context and take precedence.
+3. **Apply** — treat every `.ai.local/rules/*.md` and `.ai.local/conventions.md` as a higher-priority rule for this repo. The block below ("Authoring `.ai.local/rules/*.md`") defines the conventions.
+4. **Conflict** — if a local rule conflicts with a preset rule, **the local rule wins**. If a local rule body contains `override: kill <preset-rule-name>`, drop that preset rule from your context window entirely.
+5. **Acknowledge** — when answering a user question, briefly state which `.ai.local/` rules apply to the current task (one line is enough). Format: `Using .ai.local: <rule-name>(, <rule-name>)*`. If no `.ai.local/` exists, do NOT mention this rule.
+
+If `.ai.local/` does not exist → **no-op**, do not error. Do not produce any log line about its absence.
+
+## Authoring `.ai.local/rules/*.md` (consumer-side reference)
+
+Each `.ai.local/rules/<name>.md` is a plain-markdown rule body. The model parses it as:
+
+- Lines before `## Body` are scope metadata. Only `glob:` / `globs:` / `override:` lines are recognised.
+- Everything from `## Body` onward is the rule body.
+- `glob: always` → always-on. Counts against your context budget.
+- `globs: <comma-separated globs>` → on-demand; applies only when matching files are in focus.
+- `override: kill <preset-rule-name>` → drop that preset rule from context.
+
+Keep files ≤ 120 lines. Match the style of preset rules (short sections, bullets, code examples).
+
+## Limitations (read this)
+
+- Cursor/Claude do **not** natively read `.ai.local/`. This rule is a **prompt-only** mechanism: it asks you, the model, to read and apply the files. Reliability is high but not 100%.
+- If a user adds a file to `.ai.local/` mid-session, **restart the session** to be sure it is picked up.
+- "Priority" is **contextual**, not enforced. Always re-read the local rule before answering questions that touch it.
+
+## Pointers
+
+- Authoring guide: `docs/LOCAL-OVERLAY.md` in the `@bonesofspring/ai-rules` package.
+- Living gotchas alternative: `.cursor/team/conventions.md`.
+- Root `AGENTS.md` reinforces this rule with a `MANDATORY` section.

package/presets/cursor/next/rules/http-client.mdc

@@ -39,7 +39,7 @@ impact: HIGH
 
 ## Agent requirement
 
-- When changing the shared client implementation — **update or add behavior tests** next to the client module (`tests-unit.mdc`).
+- When changing the shared client implementation — **update or add behavior tests** under the mirrored `app/__tests__/unit/lib/clients/**` path (`tests-unit.mdc`).
 - Do not introduce a **second full HTTP stack** without an explicit task and alignment with repo architecture.
 
 ## Incorrect

package/presets/cursor/next/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/next/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/next/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/next/rules/react-ui.mdc

@@ -53,7 +53,7 @@ For a reusable component:
 
 - Multiple constants/maps or multiple functions — still **one** `.data.ts` and one `.utils.ts`; do not split by "topic" into separate files without good reason (size, different responsibility at subcomponent level).
 - If logic belongs to a **subcomponent** in a subfolder (`components/Child/Child.tsx`), the same rules apply to **`Child.data.ts`**, **`Child.utils.ts`** for that subcomponent.
-- Tests for utilities and data — nearby in `__tests__/` or with `.test.ts` suffix per `tests-unit.mdc`, same prefix (`RequestForAnalysisRecommendations.utils.test.ts`, etc.).
+- Tests for utilities and data — under the mirrored path `app/__tests__/unit/<rel>` per `tests-unit.mdc`, with the same prefix (`RequestForAnalysisRecommendations.utils.spec.ts`, etc.).
 
 # Styles and design tokens
 

package/presets/cursor/next/rules/reference-features.mdc

@@ -28,7 +28,7 @@ Replace **TBD** with real paths after team agreement (or on `ai-rules init` in t
 | Store slice | **TBD** `app/src/store/slices/<example>/` | slice, thunks, selectors, types |
 | API service | **TBD** `app/src/api/services/<example>/` | service, mappers, barrel |
 | Types module | **TBD** `app/src/types/<example>/` | domain types, JSDoc, barrel export |
-| Unit tests | **TBD** next to the reference mapper/service | `*.spec.ts`, describe/it naming |
+| Unit tests | **TBD** mirrored under `app/__tests__/unit/<rel>` | `*.spec.ts`, describe/it naming |
 | E2E area | **TBD** `app/__tests__/e2e/<Area>/` | `*.cases.md`, page objects, `_shared/` |
 
 ## How to use