@bonesofspring/ai-rules 0.2.20 → 0.2.21

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

@@ -17,8 +17,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 |
 
@@ -157,7 +155,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
 
@@ -202,4 +200,4 @@ When the work edits `packages/ai-rules/presets/**` (or dogfood `.cursor/` sync o
 - Chain hook handoffs: `integration-test-*`, `post-change-test`, `java-tooling` — never `lint:js`, Playwright, XCUITest, or `xcodebuild`.
 - Skills: `feature-delivery`, `unit-testing`, `integration-testing`, `ci-investigation`, `debug-investigation`, `code-review`, `technical-retro`, `write-adr`.
 
-**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.

package/presets/cursor/java/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/java/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/java/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/java/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 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/cursor/mcp-ts/agents/task-analyst.md

@@ -1,6 +1,6 @@
 ---
 name: task-analyst
-description: Task analysis specialist. Clarifies requirements, validates acceptance criteria, and decomposes work into concrete tasks. Use for /feature-start, task intake, or when the user asks to analyze or decompose a feature before coding. Writes only team artifacts; never writes production code.
+description: Task analysis specialist. Clarifies requirements, validates acceptance criteria, and decomposes work into concrete tasks. Use for task intake, or when the user asks to analyze or decompose a feature before coding. Writes only team artifacts; never writes production code.
 readonly: false
 ---
 

package/presets/cursor/mcp-ts/commands/README.md

@@ -6,6 +6,4 @@ Slash commands are copied to `.cursor/commands/` (Cursor) or `.claude/commands/`
 |---------|---------|
 | `/task` | Router + pipeline entry |
 | `/task-continue` | Resume after human gate |
-| `/feature-start` | Legacy analyst-only start |
-| `/feature-continue` | Alias of task-continue |
 | `/technical-retro` | Retro |

package/presets/cursor/mcp-ts/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/mcp-ts/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/mcp-ts/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".
-- 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/mcp-ts/hooks/chain-team-phases.sh

@@ -128,17 +128,10 @@ const DEFAULT_ARTIFACT_OUTPUT_IDS = {
   'task-router': 'routing',
   'task-analyst': 'analysis',
   'solution-architect': 'architecture',
-  'migration-specialist': 'migration-plan',
   debugger: 'debug',
-  'ci-investigator': 'ci',
   'feature-developer': 'implementation',
   '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',
 };
 function artifactOutputIdFor(step, agent) {
   if (step && typeof step.artifactOutputId === 'string') return step.artifactOutputId;
@@ -243,7 +236,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);
 }
 
@@ -475,9 +478,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/mcp-ts/rules/agent-team-orchestrator.mdc

@@ -17,8 +17,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 |
 
@@ -157,7 +155,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
 
@@ -188,4 +186,4 @@ When the work edits `packages/ai-rules/presets/**` (or dogfood `.cursor/` sync o
 - **Review-only:** pipeline step = `security-reviewer` for threat/capability diffs; parent applies skill `code-review` for schema/contract/style (no `code-reviewer` agent in Phase 1).
 - After TS changes, pipeline includes **build-verifier** with repository typecheck/test via `post-change-test` / `mcp-ts-tooling`.
 
-**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.

package/presets/cursor/mcp-ts/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/mcp-ts/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/mcp-ts/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/mcp-ts/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 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/cursor/next/README.md

@@ -15,17 +15,19 @@ Copies:
 | `REPO_AGENTS.md` | → repo-root `AGENTS.md` (cross-tool) |
 | `AGENTS.md` | → `.cursor/AGENTS.md` quick-start |
 | `BUGBOT.md` | Cursor Bugbot review priorities (Next) |
-| `rules/**` | `.mdc` + README (alwaysApply ≤3); golden rules with Incorrect/Correct + `impact:` |
-| `agents/**` | **22** roles (+ README; includes on-demand `codebase-analyzer`) |
-| `skills/**` | 9 skills (incl. `playwright-e2e`, `write-adr`, `react-performance`) |
-| `commands/**` | task, task-continue, feature-start/continue, technical-retro |
+| `rules/**` | `.mdc` + README (alwaysApply ≤4 incl. `ai-local-overlay`); golden rules with Incorrect/Correct + `impact:` |
+| `agents/**` | **24** roles (+ README; includes on-demand `codebase-analyzer`, `openspec-author`) |
+| `skills/**` | **13** skills (incl. `playwright-e2e`, `write-adr`, `react-performance`, `mockup-review`, `ux-design`, `spec-authoring`, `spec-discovery`) |
+| `commands/**` | task, task-continue, technical-retro |
 | `hooks.json` + `hooks/**` | guard-shell + chain-team-phases; optional `hooks/examples/` cookbook |
 | `team/**` | fixtures + `conventions.md` + README |
 | `mcp.json` + `MCP.md` | Context7 + Figma MCP → `.cursor/mcp.json` |
 
-## alwaysApply (≤3)
+## alwaysApply (≤4)
 
-`next-app-core`, `package-manager`, `code-quality-and-refactoring`.
+`next-app-core`, `package-manager`, `code-quality-and-refactoring`, `ai-local-overlay`.
+
+The 4th slot is reserved for `ai-local-overlay` (consumer-owned `.ai.local/` rules). Demote it to `globs` if your repo does not use `.ai.local/`. See [`../../docs/LOCAL-OVERLAY.md`](../../docs/LOCAL-OVERLAY.md).
 
 Requestable (not always-on): `post-change-lint`, `agent-team-*`, `code-review-mr`, `feature-delivery-workflow`, `reference-features`, domain globs.
 

package/presets/cursor/next/REPO_AGENTS.md

@@ -46,3 +46,11 @@ Rules: `.cursor/rules/` or `.claude/rules/`. Skills: `.cursor/skills/` or `.clau
 ## Living conventions
 
 Gotchas, local patterns, and team decisions: **`.cursor/team/conventions.md`** and/or **`.claude/team/conventions.md`** (fill after init; not overwritten on every dogfood sync when already present).
+
+## Local overlay (`.ai.local/`) — MANDATORY
+
+A `.ai.local/` directory MAY exist at the repo root or at any nesting depth in monorepos. **All agents MUST read and apply it on every turn.** Rules there override preset rules; in conflicts, the local rule wins. `override: kill <preset-rule-name>` drops the named preset rule from the agent's context entirely.
+
+Plain markdown rules under `.ai.local/rules/*.md` are read by the agent with higher priority than preset rules. Living gotchas live in `.ai.local/conventions.md`.
+
+Authoring guide: `docs/LOCAL-OVERLAY.md` in the `@bonesofspring/ai-rules` package. The `ai-local-overlay` rule (always-on for Cursor, on-demand for Claude) is the mechanism; this `MANDATORY` section is the reinforcement.

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

@@ -54,6 +54,7 @@ Role-based subagents for the Cursor team pipeline.
 | Agent | File | Production code |
 |-------|------|----------------|
 | Tech writer | `tech-writer.md` | docs only |
+| OpenSpec author | `openspec-author.md` | `openspec/**` only (proposal/design/tasks/spec deltas; reads `app/**` for evidence) |
 
 Copied to `.cursor/agents/` on `ai-rules init cursor --preset next`.
 
@@ -70,7 +71,7 @@ Default SoT — YAML `model` in each agent file. Optional `steps[].model` (`chea
 | Tier | Default frontmatter | Agents |
 |------|---------------------|--------|
 | **cheap** | `fast` | `task-router`, `task-analyst`, `build-verifier`, `code-reviewer`, `tech-writer`, `codebase-analyzer` |
-| **standard** | `inherit` | `feature-developer`, `debugger`, `ci-investigator`, `api-contract-reviewer`, `accessibility-reviewer`, `qa-tester`, `unit-test-*`, `playwright-test-*` |
+| **standard** | `inherit` | `feature-developer`, `debugger`, `ci-investigator`, `api-contract-reviewer`, `accessibility-reviewer`, `qa-tester`, `unit-test-*`, `playwright-test-*`, `openspec-author` |
 | **strong** | `claude-opus-4-8[effort=high]` | `solution-architect`, `migration-specialist`, `security-reviewer`, `performance-auditor`, `mockup-reviewer` |
 
 **Notes**
@@ -86,7 +87,6 @@ Default SoT — YAML `model` in each agent file. Optional `steps[].model` (`chea
 |---------|------------|
 | `/task <desc>` | Router → dynamic pipeline → first agent |
 | `/task-continue <slug>` | After human gate |
-| `/feature-start`, `/feature-continue` | Legacy (compatibility) |
 
 Rule: `agent-team-orchestrator.mdc`. Plan: `pipeline.json` in `.cursor/team/tasks/<slug>/`.
 

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

@@ -38,7 +38,7 @@ When validating **preset packaging** changes (paths under `packages/ai-rules/pre
 
 ### FAIL (all stacks)
 
-1. **Token budget:** Cursor `alwaysApply: true` count ≤ **3**; Claude rules without `paths:` === **3** (**exclude `**/README.md`** — Option A). Meta `preset-*` rules must **not** be `alwaysApply: true`.
+1. **Token budget:** Cursor `alwaysApply: true` count ≤ **4** (4th slot reserved for `ai-local-overlay`); Claude rules without `paths:` === **3** (**exclude `**/README.md`** — Option A). Meta `preset-*` rules must **not** be `alwaysApply: true`.
 2. **Leakage (next):** hooks/agents must not require `xcuitest-test-*` handoffs or `xcodebuild` as the default Next post-change gate. See `preset-no-cross-stack-leakage.mdc`.
 3. **Mapping / README:** `claude/next/rules/README.md` must include a Cursor→Claude mapping table; stack `rules/README.md` should document core→stack mapping when `_shared` consumers exist.
 4. **shared-core consumers:** if `_shared/core/**` changed, every file with matching `<!-- shared-core: … -->` in this PR must be updated (or intentional fork documented in validation-report).
@@ -66,6 +66,16 @@ When validating **preset packaging** changes (paths under `packages/ai-rules/pre
 - Thin aliases may be &lt;15 body lines.
 - Embed vs lineage modes: see `docs/PRESET-CONTRIBUTION.md` and `_shared/README.md`.
 
+### Local overlay compliance (soft gate)
+
+When the agent's transcript touches files in the repo, do a **soft check** on `.ai.local/`:
+
+1. **Existence probe.** If `.ai.local/` exists at the repo root or any nesting depth, the agent's transcript must contain an acknowledgement line of the form `Using .ai.local: <rule-name>(, <rule-name>)*` (the `ai-local-overlay` rule mandates this format). Missing acknowledgement → **soft WARN**.
+2. **Override honours.** If a local rule contains `override: kill <preset-rule-name>`, the agent's reasoning must not invoke the killed preset rule. Violation → **soft WARN**.
+3. **No drift on init.** If `.ai.local/` exists and `init` would overwrite a file under `.ai.local/rules/`, warn the user — `init` does not touch `.ai.local/` today, but if a future `init` change does, this gate is the surface to flag it.
+
+Soft WARNs do **not** fail the pipeline. They appear in the validation report under `## Soft notes` and are reviewed by the human gate. Repeated soft WARNs across runs on the same repo → log a recommendation to promote the local rule to a preset rule (`docs/LOCAL-OVERLAY.md` § "When to upgrade to a preset change").
+
 ### ios-swift-only checks
 
 Not required for next-only PRs. When both stacks touched, also apply ios-swift verifier checks (chain fork, Playwright leakage, XCUITest stems) — **FAIL**.

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

@@ -1,6 +1,6 @@
 ---
 name: feature-developer
-description: Feature implementation specialist for Next.js stack. 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 Next.js stack. 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
 ---