@bonesofspring/ai-rules 0.2.26 → 0.2.27

package/presets/cursor/php-laravel/AGENTS.md

@@ -24,7 +24,7 @@ Copies rules/agents/hooks/skills/commands + seeds `.ai.local/team/` + `REPO_AGEN
 
 ## Inventory
 
-- **21 agents** — see `agents/README.md` (no a11y / Playwright / XCUITest)
+- **22 agents** — see `agents/README.md` (no a11y / Playwright / XCUITest)
 - **10 skills** — `feature-delivery`, `spec-authoring`, `spec-discovery`, `unit-testing`, `integration-testing`, `ci-investigation`, `debug-investigation`, `code-review`, `technical-retro`, `write-adr`
 - **3 commands** — `/task`, `/task-continue`, `/technical-retro`
 

package/presets/cursor/php-laravel/agents/build-verifier.md

@@ -36,7 +36,7 @@ Hard gates for the **php-laravel** stack (and peers):
 | Gate | FAIL when |
 |------|-----------|
 | **twin-map** | `php-laravel` missing from `STACKS`, or Cursor↔Claude orphan/missing twins |
-| **token-budget** | Cursor `alwaysApply` ≠ 3 or Claude session-start (excl. README) ≠ 3, or trio body sum > 140 |
+| **token-budget** | Cursor/Claude always-on count outside 3–5 (extra slots = `ai-local-overlay`), or body sum > 200 |
 | **leakage** | `PHP_FORBIDDEN_*` hits (Playwright/XCUITest/`lint:js`/`accessibility-reviewer` / `mockup-reviewer` as required handoffs) |
 | **chain fork** | `hooks/chain-team-phases.sh` byte-identical to **next**, **ios-swift**, **go**, **java**, **mcp-ts**, or **php-hexagonal** (same platform) |
 

package/presets/cursor/php-laravel/commands/task.md

@@ -1,6 +1,6 @@
 ---
 name: task
-description: Route a natural-language task through the agent-team pipeline: task-router, pipeline.json, and the first planned specialist.
+description: "Route a natural-language task through the agent-team pipeline: task-router, pipeline.json, and the first planned specialist."
 ---
 
 # Task — unified entry point (router + pipeline)

package/presets/cursor/php-laravel/hooks/chain-team-phases.sh

@@ -44,7 +44,10 @@ try {
 }
 
 const slug = active.slug;
-if (!slug) {
+// Reject non-kebab / traversal slugs: the runtime writes status.json and
+// metrics.json under tasks/<slug>, so an unchecked slug could escape the tree.
+const SLUG_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+if (typeof slug !== 'string' || slug.length > 48 || !SLUG_RE.test(slug)) {
   process.stdout.write('{}');
   process.exit(0);
 }
@@ -71,6 +74,9 @@ function waitForMetricsLock() {
   // 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.
+  // A lock left behind by a killed process is reclaimed once its mtime is older
+  // than STALE_LOCK_MS, so one crash cannot brick the task forever.
+  const STALE_LOCK_MS = 30000;
   for (let attempt = 0; attempt < 200; attempt += 1) {
     try {
       const fd = fs.openSync(METRICS_LOCK, 'wx');
@@ -78,6 +84,13 @@ function waitForMetricsLock() {
       return;
     } catch (error) {
       if (!error || error.code !== 'EEXIST') throw error;
+      try {
+        const lockStat = fs.statSync(METRICS_LOCK);
+        if (Date.now() - lockStat.mtimeMs > STALE_LOCK_MS) {
+          fs.unlinkSync(METRICS_LOCK);
+          continue;
+        }
+      } catch {}
       const until = Date.now() + 10;
       while (Date.now() < until) { /* 10 ms busy-wait */ }
     }
@@ -491,7 +504,10 @@ function legacyFlow() {
 
 
 if (hookInput.action === 'end_human_gate') {
-    status.awaitingHumanGate = false;
+  // Only advance when a gate was actually open. A duplicate or retried
+  // end_human_gate must be a no-op, not a silent pipeline skip.
+  const gateWasOpen = Boolean(status.activeHumanGateEventId) || status.awaitingHumanGate === true;
+  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,
@@ -518,7 +534,7 @@ if (hookInput.action === 'end_human_gate') {
     });
     delete status.activeHumanGateEventId;
   }
-  if (hookInput.activateNext && fs.existsSync(pipelinePath)) {
+  if (gateWasOpen && hookInput.activateNext && fs.existsSync(pipelinePath)) {
     let resumePipeline = null;
     try { resumePipeline = JSON.parse(fs.readFileSync(pipelinePath, 'utf8')); } catch {}
     if (resumePipeline) {
@@ -540,6 +556,19 @@ if (hookInput.action === 'end_human_gate') {
         else out(handoffForAgent(resumeAgents[0], resumeNext.step.scope, resumeNext.step));
         process.exit(0);
       }
+      // Gate on the final step: no executable step remains. Complete the
+      // pipeline instead of leaving it in_progress forever.
+      status.state = 'completed';
+      completeTaskMetrics();
+      writeStatus({
+        pipelineIndex: resumeSteps.length,
+        phase: 'done',
+        state: 'completed',
+        currentAgent: null,
+        awaitingHumanGate: false,
+      });
+      out(`Pipeline complete for "${slug}". Run /technical-retro ${slug}.`);
+      process.exit(0);
     }
   }
   // A2 (retro §8): if gate closes the final human gate of the pipeline

package/presets/cursor/php-laravel/rules/README.md

@@ -1,6 +1,6 @@
 # Rules (preset php-laravel)
 
-## alwaysApply (3)
+## alwaysApply (3–5)
 
 | Rule | Role |
 |------|------|
@@ -8,7 +8,7 @@
 | `architecture-boundaries` | Laravel layer invariants |
 | `code-quality-and-refactoring` | Shared quality + Laravel Stack notes |
 
-**Session-start body budget:** sum of the 3 always-on bodies ≤ **140** lines (stretch ≤120).
+**Session-start body budget:** sum of the intended always-on bodies ≤ **200** lines (stretch ≤170).
 
 ## Twin depth (Cursor↔Claude)
 

package/presets/cursor/php-laravel/rules/agent-team-orchestrator.mdc

@@ -178,7 +178,7 @@ When the work edits `packages/ai-rules/presets/**` (or dogfood `.cursor/` sync o
 
 ## Stack notes
 
-### Roles (Laravel — 21 agents)
+### Roles (Laravel — 22 agents)
 
 | Kind | Agents | Writes |
 |------|--------|--------|

package/presets/cursor/php-laravel/rules/code-quality-and-refactoring.mdc

@@ -19,6 +19,12 @@ alwaysApply: true
 - **CUPID:** Composable; Unix philosophy (one responsibility); Predictable; Idiomatic (repo); Domain-based.
 - **Composition over inheritance;** Law of Demeter — no `a.b.c.d` chains; via public API / facade.
 
+# Over-abstraction guardrails
+
+- **No unnecessary constants:** do not hoist a one-off literal, string, or boolean into a named constant. Inline it, or use an existing token/enum when the value is meaningful and reused. Named constants are for shared, semantic, or repeated values.
+- **No invented utilities:** do not add a `utils`/helper for a single call site or a thin pass-through wrapper. Inline it or extend the existing helper; a new shared utility is justified only after the Rule of Three.
+- **Decompose over conditionals:** a unit (function, component, hook) that accumulates several branches (`if` / ternary / `switch`) should be split into smaller units with one reason to change instead of piling up conditions.
+
 # Refactoring during changes
 
 - Light refactor is OK if it reduces duplication, improves readability, and does not break public contracts.

package/presets/cursor/php-laravel/rules/preset-layering.mdc

@@ -18,7 +18,7 @@ Rules for **preset authors** (`packages/ai-rules/presets/**`). Not always-on in
 | Layer | Where | What to put |
 |-------|-------|-------------|
 | **Core** | `presets/_shared/core/**` | Stack-agnostic prose + checklists; no frontmatter; no paths `app/**`, `Features/**`, Playwright, xcodebuild |
-| **Stack** | `presets/{cursor\|claude\|mavis\|opencode}/<stack>/` | Domain/tooling, stack always-on trio, stack examples in **Stack notes** |
+| **Stack** | `presets/{cursor\|claude\|mavis\|opencode}/<stack>/` | Domain/tooling, stack always-on set (3–5), stack examples in **Stack notes** |
 | **Platform** | Cursor `.mdc` / Claude `.md` / Mavis `.md` / OpenCode `.md` | Frontmatter (`alwaysApply`/`globs` vs `paths:` vs OpenCode `mode`/`permission`), platform-only (`BUGBOT.md`, `CLAUDE.md`) |
 
 ## Where to put a new rule

package/presets/cursor/php-laravel/rules/preset-pr-checklist.mdc

@@ -21,7 +21,7 @@ Checklist for PRs that touch `packages/ai-rules/presets/**` (and dogfood `.curso
 - [ ] **Mavis derive:** mapped `cursor/<stack>/` change → `mavis/<stack>/` + `adapter-map.json` **same PR** when the stack is in `releasedStacks` (run `generate-mavis.mjs --stack <stack>` + `check-mavis-adapter-map.mjs`; see `preset-twin-sync` § Mavis derivation)
 - [ ] **OpenCode derive:** mapped `cursor/<stack>/` change → `opencode/<stack>/` + `adapter-map.json` **same PR** when the stack is in `releasedStacks` (run `generate-opencode.mjs --stack <stack>` + `check-opencode-adapter-map.mjs`; see `preset-twin-sync` § OpenCode derivation)
 - [ ] **Mapping:** `claude/<stack>/rules/README.md` mapping table is current
-- [ ] **Token budget:** Cursor `alwaysApply` ≤ 4 (4th slot reserved for `ai-local-overlay`); Claude session-start exactly 3; meta rules not always-on
+- [ ] **Token budget:** Cursor `alwaysApply` and Claude session-start both **3–5** (extra slots reserved for `ai-local-overlay`); body sum ≤200 (stretch ≤170); 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`.

package/presets/cursor/php-laravel/rules/preset-token-budget.mdc

@@ -17,19 +17,19 @@ Invariants for rule loading in an **installed** preset (consumer app).
 
 | Platform | Always-on | Cap |
 |----------|-----------|-----|
-| Cursor | `alwaysApply: true` | **≤ 4** |
-| Claude | rules **without** `paths:` | **exactly 3** |
-| Mavis | `adapter-map` rules with `loadMode: root-entry` | **≤ 4** |
-| OpenCode | `adapter-map` rules with `loadMode: root-entry` | **≤ 4** |
+| Cursor | `alwaysApply: true` | **3–5** |
+| Claude | rules **without** `paths:` | **3–5** |
+| Mavis | `adapter-map` rules with `loadMode: root-entry` | **3–5** |
+| OpenCode | `adapter-map` rules with `loadMode: root-entry` | **3–5** |
 
-**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.
+Caps are **aligned** across platforms: minimum **3** (base invariants), maximum **5**. Slots beyond the base invariants are reserved for `ai-local-overlay` (consumer-owned `.ai.local/` rules). If you do not need local overlay, demote that rule to `globs: ["**/.ai.local/**"]` / Claude `paths:`, or a non-root load mode on Mavis / OpenCode.
 
-**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.
+**Claude Option A (README exclusion):** when counting Claude rules without `paths:` / session-start, **exclude `**/README.md`** (topic indexes are not session-start rules). Body budget sums only the intended session-start rules (≤5).
 
 Session-start body budget:
-- Claude trio: ≤140 lines total (stretch ≤120).
-- Cursor 4-set: ≤170 lines total (4 rules including `ai-local-overlay`).
-- Mavis / OpenCode: ≤4 root-entry rule files; combined root `AGENTS.md` + platform entry ≤170 nonempty lines. Do not dump the full rule catalog into `AGENTS.md`.
+- Claude session-start: ≤200 lines total (stretch ≤170).
+- Cursor always-on: ≤200 lines total (stretch ≤170).
+- Mavis / OpenCode: ≤5 root-entry rule files; combined root `AGENTS.md` + platform entry ≤200 nonempty lines. Do not dump the full rule catalog into `AGENTS.md`.
 
 ## Meta / author rules
 
@@ -45,4 +45,4 @@ Orchestrator, feature-delivery, code-review, post-change gates, domain globs —
 
 ## Verifier
 
-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.
+build-verifier **FAIL** if Cursor `alwaysApply` count or Claude session-start count is outside **3–5** (Claude count **excludes `**/README.md`**), or if a `preset-*` meta rule is marked always-on.

package/presets/cursor/svelte/README.md

@@ -13,4 +13,4 @@ npx @bonesofspring/ai-rules init cursor --preset svelte
 | `rules/`, `agents/`, `skills/`, `commands/`, `hooks/` | `.cursor/<dir>/` |
 | `team/` | **`.ai.local/team/`** (templates; slugs preserved) |
 
-Always-on (≤4): `svelte-app-core`, `package-manager`, `code-quality-and-refactoring`, `ai-local-overlay`. Skill `svelte-performance`. Twin: `presets/claude/svelte/`. Catalog: [`rules/README.md`](./rules/README.md).
+Always-on (3–5): `svelte-app-core`, `package-manager`, `code-quality-and-refactoring`, `ai-local-overlay`. Skill `svelte-performance`. Twin: `presets/claude/svelte/`. Catalog: [`rules/README.md`](./rules/README.md).

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

@@ -38,12 +38,12 @@ 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 3–5; Claude rules without `paths:` 3–5 (**exclude `**/README.md`** — Option A). Meta `preset-*` rules must **not** be `alwaysApply: true`.
 2. **Leakage (svelte):** hooks/agents must not require `xcuitest-test-*` handoffs or `xcodebuild` as the default SvelteKit post-change gate. See `preset-no-cross-stack-leakage.mdc`.
 3. **Mapping / README:** `claude/svelte/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).
 5. **Twin presence:** Cursor rule change without Claude twin same PR → **FAIL** (next, nuxt, svelte, ios-swift, go, java, mcp-ts, php-hexagonal, and php-laravel). Domain twin body ≥15 lines; thin aliases (`agent-team-intake`, `technical-retro`) may be shorter.
-6. **Session-start body budget (soft→document, FAIL if grossly over):** sum body lines of the **3** intended always-on / session-start rules ≤ **140** (stretch ≤120); do **not** include `**/README.md`. Record the sum in validation-report.
+6. **Session-start body budget (soft→document, FAIL if grossly over):** sum body lines of the intended always-on / session-start rules ≤ **200** (stretch ≤170); do **not** include `**/README.md`. Record the sum in validation-report.
 7. **Embed drift (hard in `check:preset-structure`):** run `packages/ai-rules/scripts/check-shared-core-drift.sh` with `AI_RULES_DRIFT_FAIL=1` (bundled by the structure orchestrator). Lineage stems are excluded from body equality.
 8. **Dogfood (monorepo soft):** if root `.cursor/` is in the PR, prefer sync via `packages/ai-rules/scripts/sync-dogfood-cursor.sh`; mass deletion of tracked dogfood without migration doc → note as risk / FAIL for maintainers.
 

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

@@ -1,6 +1,6 @@
 ---
 name: task
-description: Route a natural-language task through the agent-team pipeline: task-router, pipeline.json, and the first planned specialist.
+description: "Route a natural-language task through the agent-team pipeline: task-router, pipeline.json, and the first planned specialist."
 ---
 
 # Task — single entry point (router + pipeline)

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

@@ -42,7 +42,10 @@ try {
 }
 
 const slug = active.slug;
-if (!slug) {
+// Reject non-kebab / traversal slugs: the runtime writes status.json and
+// metrics.json under tasks/<slug>, so an unchecked slug could escape the tree.
+const SLUG_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+if (typeof slug !== 'string' || slug.length > 48 || !SLUG_RE.test(slug)) {
   process.stdout.write('{}');
   process.exit(0);
 }
@@ -69,6 +72,9 @@ function waitForMetricsLock() {
   // 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.
+  // A lock left behind by a killed process is reclaimed once its mtime is older
+  // than STALE_LOCK_MS, so one crash cannot brick the task forever.
+  const STALE_LOCK_MS = 30000;
   for (let attempt = 0; attempt < 200; attempt += 1) {
     try {
       const fd = fs.openSync(METRICS_LOCK, 'wx');
@@ -76,6 +82,13 @@ function waitForMetricsLock() {
       return;
     } catch (error) {
       if (!error || error.code !== 'EEXIST') throw error;
+      try {
+        const lockStat = fs.statSync(METRICS_LOCK);
+        if (Date.now() - lockStat.mtimeMs > STALE_LOCK_MS) {
+          fs.unlinkSync(METRICS_LOCK);
+          continue;
+        }
+      } catch {}
       const until = Date.now() + 10;
       while (Date.now() < until) { /* 10 ms busy-wait */ }
     }
@@ -495,7 +508,10 @@ function legacyFlow() {
 
 
 if (hookInput.action === 'end_human_gate') {
-    status.awaitingHumanGate = false;
+  // Only advance when a gate was actually open. A duplicate or retried
+  // end_human_gate must be a no-op, not a silent pipeline skip.
+  const gateWasOpen = Boolean(status.activeHumanGateEventId) || status.awaitingHumanGate === true;
+  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,
@@ -522,7 +538,7 @@ if (hookInput.action === 'end_human_gate') {
     });
     delete status.activeHumanGateEventId;
   }
-  if (hookInput.activateNext && fs.existsSync(pipelinePath)) {
+  if (gateWasOpen && hookInput.activateNext && fs.existsSync(pipelinePath)) {
     let resumePipeline = null;
     try { resumePipeline = JSON.parse(fs.readFileSync(pipelinePath, 'utf8')); } catch {}
     if (resumePipeline) {
@@ -544,6 +560,19 @@ if (hookInput.action === 'end_human_gate') {
         else out(handoffForAgent(resumeAgents[0], resumeNext.step.scope, resumeNext.step));
         process.exit(0);
       }
+      // Gate on the final step: no executable step remains. Complete the
+      // pipeline instead of leaving it in_progress forever.
+      status.state = 'completed';
+      completeTaskMetrics();
+      writeStatus({
+        pipelineIndex: resumeSteps.length,
+        phase: 'done',
+        state: 'completed',
+        currentAgent: null,
+        awaitingHumanGate: false,
+      });
+      out(`Pipeline complete for "${slug}". Run /technical-retro ${slug}.`);
+      process.exit(0);
     }
   }
   // A2 (retro §8): if gate closes the final human gate of the pipeline

package/presets/cursor/svelte/rules/code-quality-and-refactoring.mdc

@@ -19,6 +19,12 @@ alwaysApply: true
 - **CUPID:** Composable; Unix philosophy (one responsibility); Predictable; Idiomatic (repo); Domain-based.
 - **Composition over inheritance;** Law of Demeter — no `a.b.c.d` chains; via public API / facade.
 
+# Over-abstraction guardrails
+
+- **No unnecessary constants:** do not hoist a one-off literal, string, or boolean into a named constant. Inline it, or use an existing token/enum when the value is meaningful and reused. Named constants are for shared, semantic, or repeated values.
+- **No invented utilities:** do not add a `utils`/helper for a single call site or a thin pass-through wrapper. Inline it or extend the existing helper; a new shared utility is justified only after the Rule of Three.
+- **Decompose over conditionals:** a unit (function, component, hook) that accumulates several branches (`if` / ternary / `switch`) should be split into smaller units with one reason to change instead of piling up conditions.
+
 # Refactoring during changes
 
 - Light refactor is OK if it reduces duplication, improves readability, and does not break public contracts.

package/presets/cursor/svelte/rules/layer-barrel-exports.mdc

@@ -1,6 +1,6 @@
 ---
 description: Two-level barrel exports for layers with a regulated public API
-globs: **/index.ts
+globs: "**/index.ts"
 alwaysApply: false
 impact: MEDIUM
 ---

package/presets/cursor/svelte/rules/preset-layering.mdc

@@ -1,5 +1,5 @@
 ---
-description: Preset authoring: Core → Stack → Platform layering. Use when editing packages/ai-rules/presets/**.
+description: "Preset authoring: Core → Stack → Platform layering. Use when editing packages/ai-rules/presets/**."
 globs:
   - packages/ai-rules/presets/**/*
   - .cursor/rules/**/*
@@ -18,7 +18,7 @@ Rules for **preset authors** (`packages/ai-rules/presets/**`). Not always-on in
 | Layer | Where | What to put |
 |-------|-------|-------------|
 | **Core** | `presets/_shared/core/**` | Stack-agnostic prose + checklists; no frontmatter; no paths `app/**`, `Features/**`, Playwright, xcodebuild |
-| **Stack** | `presets/{cursor\|claude\|mavis\|opencode}/<stack>/` | Domain/tooling, stack always-on trio, stack examples in **Stack notes** |
+| **Stack** | `presets/{cursor\|claude\|mavis\|opencode}/<stack>/` | Domain/tooling, stack always-on set (3–5), stack examples in **Stack notes** |
 | **Platform** | Cursor `.mdc` / Claude `.md` / Mavis `.md` / OpenCode `.md` | Frontmatter (`alwaysApply`/`globs` vs `paths:` vs OpenCode `mode`/`permission`), platform-only (`BUGBOT.md`, `CLAUDE.md`) |
 
 ## Where to put a new rule

package/presets/cursor/svelte/rules/preset-no-cross-stack-leakage.mdc

@@ -1,5 +1,5 @@
 ---
-description: Preset authoring: forbid cross-stack agent/path leakage in hooks and agents.
+description: "Preset authoring: forbid cross-stack agent/path leakage in hooks and agents."
 globs:
   - packages/ai-rules/presets/**/*
   - .cursor/rules/**/*

package/presets/cursor/svelte/rules/preset-pr-checklist.mdc

@@ -1,5 +1,5 @@
 ---
-description: Preset authoring: PR checklist for twin sync, budget, leakage, README. Use on preset PRs.
+description: "Preset authoring: PR checklist for twin sync, budget, leakage, README. Use on preset PRs."
 globs:
   - packages/ai-rules/presets/**/*
   - .cursor/rules/**/*
@@ -21,7 +21,7 @@ Checklist for PRs that touch `packages/ai-rules/presets/**` (and dogfood `.curso
 - [ ] **Mavis derive:** mapped `cursor/<stack>/` change → `mavis/<stack>/` + `adapter-map.json` **same PR** when the stack is in `releasedStacks` (run `generate-mavis.mjs --stack <stack>` + `check-mavis-adapter-map.mjs`; see `preset-twin-sync` § Mavis derivation)
 - [ ] **OpenCode derive:** mapped `cursor/<stack>/` change → `opencode/<stack>/` + `adapter-map.json` **same PR** when the stack is in `releasedStacks` (run `generate-opencode.mjs --stack <stack>` + `check-opencode-adapter-map.mjs`; see `preset-twin-sync` § OpenCode derivation)
 - [ ] **Mapping:** `claude/<stack>/rules/README.md` mapping table is current
-- [ ] **Token budget:** Cursor `alwaysApply` ≤ 4 (4th slot reserved for `ai-local-overlay`); Claude session-start exactly 3; meta rules not always-on
+- [ ] **Token budget:** Cursor `alwaysApply` and Claude session-start both **3–5** (extra slots reserved for `ai-local-overlay`); body sum ≤200 (stretch ≤170); 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`.

package/presets/cursor/svelte/rules/preset-token-budget.mdc

@@ -1,5 +1,5 @@
 ---
-description: Preset authoring: ≤3 always-on / session-start; meta rules never alwaysApply.
+description: "Preset authoring: ≤3 always-on / session-start; meta rules never alwaysApply."
 globs:
   - packages/ai-rules/presets/**/*
   - .cursor/rules/**/*
@@ -17,19 +17,19 @@ Invariants for rule loading in an **installed** preset (consumer app).
 
 | Platform | Always-on | Cap |
 |----------|-----------|-----|
-| Cursor | `alwaysApply: true` | **≤ 4** |
-| Claude | rules **without** `paths:` | **exactly 3** |
-| Mavis | `adapter-map` rules with `loadMode: root-entry` | **≤ 4** |
-| OpenCode | `adapter-map` rules with `loadMode: root-entry` | **≤ 4** |
+| Cursor | `alwaysApply: true` | **3–5** |
+| Claude | rules **without** `paths:` | **3–5** |
+| Mavis | `adapter-map` rules with `loadMode: root-entry` | **3–5** |
+| OpenCode | `adapter-map` rules with `loadMode: root-entry` | **3–5** |
 
-**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.
+Caps are **aligned** across platforms: minimum **3** (base invariants), maximum **5**. Slots beyond the base invariants are reserved for `ai-local-overlay` (consumer-owned `.ai.local/` rules). If you do not need local overlay, demote that rule to `globs: ["**/.ai.local/**"]` / Claude `paths:`, or a non-root load mode on Mavis / OpenCode.
 
-**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.
+**Claude Option A (README exclusion):** when counting Claude rules without `paths:` / session-start, **exclude `**/README.md`** (topic indexes are not session-start rules). Body budget sums only the intended session-start rules (≤5).
 
 Session-start body budget:
-- Claude trio: ≤140 lines total (stretch ≤120).
-- Cursor 4-set: ≤170 lines total (4 rules including `ai-local-overlay`).
-- Mavis / OpenCode: ≤4 root-entry rule files; combined root `AGENTS.md` + platform entry ≤170 nonempty lines. Do not dump the full rule catalog into `AGENTS.md`.
+- Claude session-start: ≤200 lines total (stretch ≤170).
+- Cursor always-on: ≤200 lines total (stretch ≤170).
+- Mavis / OpenCode: ≤5 root-entry rule files; combined root `AGENTS.md` + platform entry ≤200 nonempty lines. Do not dump the full rule catalog into `AGENTS.md`.
 
 ## Meta / author rules
 
@@ -45,4 +45,4 @@ Orchestrator, feature-delivery, code-review, post-change gates, domain globs —
 
 ## Verifier
 
-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.
+build-verifier **FAIL** if Cursor `alwaysApply` count or Claude session-start count is outside **3–5** (Claude count **excludes `**/README.md`**), or if a `preset-*` meta rule is marked always-on.

package/presets/cursor/svelte/rules/preset-twin-sync.mdc

@@ -1,5 +1,5 @@
 ---
-description: Preset authoring: Cursor SoT → Claude twin same PR. Use when editing preset rules.
+description: "Preset authoring: Cursor SoT → Claude twin same PR. Use when editing preset rules."
 globs:
   - packages/ai-rules/presets/**/*
   - .cursor/rules/**/*

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

@@ -17,7 +17,7 @@ alwaysApply: false
 
 Before implementing, find a feature of the same type and **mirror its structure**; do not invent a new file organization.
 
-Taxonomy / shared core: [`presets/_shared/README.md`](../../../../_shared/README.md) · [Preset contribution guide](../../../../docs/PRESET-CONTRIBUTION.md).
+Taxonomy / shared core: [`presets/_shared/README.md`](../../../_shared/README.md) · [Preset contribution guide](../../../../docs/PRESET-CONTRIBUTION.md).
 
 ## Reference table
 

package/presets/cursor/svelte/rules/svelte-ui.mdc

@@ -15,6 +15,13 @@ alwaysApply: false
 - A11y: `svelte-a11y-coding`.
 - UI boundaries: `architecture-boundaries-ui` — no DTO in markup; map in `src/lib/api/**`.
 
+# Conditional rendering
+
+- Prefer **decomposition over conditionals**: markup with several `{#if}` / `{:else if}` / `{:else}` branches should become a thin parent that renders child components, not one growing block.
+- Keep the condition in the parent; children receive resolved props.
+- No nested ternaries in markup. For loading / empty / error, use dedicated `EmptyState` / `ErrorState` components or snippets.
+- A `variant` / `mode` prop that renders two unrelated layouts is **two** components, not one.
+
 ## Incorrect
 
 ```svelte

package/presets/mavis/android-kotlin/adapter-map.json

@@ -3,7 +3,7 @@
   "platform": "mavis",
   "stack": "android-kotlin",
   "semanticSource": "cursor/android-kotlin",
-  "sourceRevision": "b95856ccfe78ceb122438c2ce91d1315f9710b442b270670d12ef7bb2aac921a",
+  "sourceRevision": "94c31b7b1327d457759e866babcbceceff211ba6691ba6114c32b5ca8e1282fd",
   "entries": [
     {
       "source": "AGENTS.md",

package/presets/mavis/android-kotlin/agents/build-verifier.md

@@ -30,7 +30,7 @@ When validating **android-kotlin preset** changes (or `scope: preset-structure-v
 
 ### FAIL (android-kotlin packaging)
 
-1. **Token budget:** Cursor `alwaysApply: true` count ≤ **3**; Claude rules without `paths:` === **3** (**exclude `**/README.md`**). Meta `preset-*` rules must **not** be always-on.
+1. **Token budget:** Cursor `alwaysApply: true` count 3–5; Claude rules without `paths:` 3–5 (**exclude `**/README.md`**). Meta `preset-*` rules must **not** be always-on.
 2. **Chain fork:** `hooks/chain-team-phases.sh` byte-≠ every other stack (Cursor + Claude).
 3. **Forbidden handoff strings** in android-kotlin `chain-team-phases.sh` (Cursor + Claude): `playwright-test-`, `playwright-agents`, `playwright-e2e`, `user-playwright`, `app/__tests__/e2e`, `xcuitest-test-`, positive `xcodebuild` / `SwiftLint` as required handoffs, positive yarn `lint:js` / `lint:css`.
 4. **Required handoff stems:** `AGENT_HANDOFF` includes `instrumentation-test-planner` (or generator/healer); `build-verifier` prose mentions `gradle-tooling` and/or `post-change-build`.
@@ -38,7 +38,7 @@ When validating **android-kotlin preset** changes (or `scope: preset-structure-v
 6. **Twin presence (hard):** Cursor rule → Claude twin + mapping row — **FAIL** if missing.
 7. **Mapping / README:** `claude/android-kotlin/rules/README.md` mapping table present.
 8. **shared-core consumers:** if `_shared/core/**` changed, matching embeds updated (or intentional fork documented).
-9. **Session-start body budget:** sum of the 3 always-on / session-start bodies ≤ **140** lines.
+9. **Session-start body budget:** sum of the intended always-on / session-start bodies ≤ **200** lines.
 10. **Embed drift:** `packages/ai-rules/scripts/check-shared-core-drift.sh` with `AI_RULES_DRIFT_FAIL=1`.
 11. **Root AGENTS template:** ship `REPO_AGENTS.md` → **FAIL** if missing.
 12. **Hooks cookbook:** `hooks.json` must **not** reference `hooks/examples/`.

package/presets/mavis/android-kotlin/commands/spec-start.md

@@ -4,7 +4,7 @@ Routes intent **`spec-gen`** (or bootstrap) → **task-analyst** in **author mod
 
 ## What to do
 
-1. Extract description from arguments after the spec-start procedure in `.mavis/commands/spec-start.md` (domain, page/feature ids, sources).
+1. Extract description from arguments after `/spec-start` (domain, page/feature ids, sources).
 2. Generate a **slug** (kebab-case, ≤48 chars), e.g. `spec-<domain>-<id>`.
 3. Ensure `.ai.local/team/tasks/<slug>/` exists (Write artifacts; not Shell mkdir).
 4. Write `.ai.local/team/active-task.json` → `{ "slug": "<slug>" }`.
@@ -16,7 +16,7 @@ Routes intent **`spec-gen`** (or bootstrap) → **task-analyst** in **author mod
 
 - Show created/updated spec paths and INDEX diff.
 - Ask user to approve drafts (`status: draft` → promote) or send edits.
-- Continue: continue `<slug>` using `.mavis/commands/task-continue.md` only after approval when implementation follows; otherwise stop after docs.
+- Continue: `/task-continue <slug>` only after approval when implementation follows; otherwise stop after docs.
 
 ## Notes
 

package/presets/mavis/android-kotlin/commands/task.md

@@ -1,10 +1,10 @@
 # Task — single entry point (router + pipeline)
 
-Main command for filing work. Parent agent = orchestrator (`agent-team-orchestrator.md`). Intake for work requests without the task procedure in `.mavis/commands/task.md` — `agent-team-intake.md`.
+Main command for filing work. Parent agent = orchestrator (`agent-team-orchestrator.md`). Intake for work requests without `/task` — `agent-team-intake.md`.
 
 ## Arguments
 
-Everything after the task procedure in `.mavis/commands/task.md` is a natural-language task description.
+Everything after `/task` is a natural-language task description.
 
 Examples:
 
@@ -25,13 +25,13 @@ Examples:
 1. **Slug** — kebab-case from the description (≤48 characters). Create `.ai.local/team/tasks/<slug>/` via **Write** (e.g. placeholder `pipeline.json` or empty marker) — the runtime/hook owns `status.json` — **not** via Shell `mkdir` (sandbox → `Operation not permitted`).
 2. **Router** — invoke subagent **task-router** with the task description and slug path.
 3. **Plan** — show the user the table from `pipeline.json`: intent, steps, skipped, humanGates.
-4. **Intent retro** — if `intent === "retro"`, run the technical-retro procedure in `.mavis/commands/technical-retro.md` and **stop**.
+4. **Intent retro** — if `intent === "retro"`, run `/technical-retro` and **stop**.
 5. **Start** — after the router:
    - confirm `pipeline.json` and `active-task.json`;
    - do **not** write `status.json` / `metrics.json` lifecycle fields yourself — the orchestration runtime/hook owns them (see **agent-artifact-contracts**). If `status.json` is missing, only a minimal bootstrap is allowed (`slug`, `intent`, `pipelineIndex: 0`, `currentAgent: steps[0]`, `state: in_progress`) — do **not** increment `pipelineIndex` manually;
    - invoke the subagent for `pipeline.steps[0].agent` (slug, artifact paths, scope).
 6. **After each agent** — wait for hook handoff / reconciliation of the terminal receipt → `status.state`; do not start the next step until `status.json` reflects the handoff (or until there is a hook `followup_message`).
-7. **Human gate** — if after the current step there is a gate in `humanGates` (`after:<agent>`), after the agent finishes **stop** and ask for continue `<slug>` using `.mavis/commands/task-continue.md`.
+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
 
@@ -41,9 +41,9 @@ Examples:
 
 ## If the slug is taken
 
-- `awaitingHumanGate` / `state: awaiting_approval` → offer artifact review or continue `<slug>` using `.mavis/commands/task-continue.md`.
+- `awaitingHumanGate` / `state: awaiting_approval` → offer artifact review or `/task-continue <slug>`.
 - `in_progress` → ask: continue or new slug.
 
 ## Metrics
 
-Runtime/hook owns `metrics.json` and `status.json` attempt ledgers. Before the first invocation ensure `task_started` and one `activeAttempts[attemptId]` + `attempt_started` exist (router/runtime bootstrap — parent must not invent parallel indices). On the task-continue procedure in `.mavis/commands/task-continue.md`, run the installed chain hook `end_human_gate` action (or wrapper) so `human_gate_ended` lands before the next attempt. Do not calculate durations in agents.
+Runtime/hook owns `metrics.json` and `status.json` attempt ledgers. Before the first invocation ensure `task_started` and one `activeAttempts[attemptId]` + `attempt_started` exist (router/runtime bootstrap — parent must not invent parallel indices). On `/task-continue`, run the installed chain hook `end_human_gate` action (or wrapper) so `human_gate_ended` lands before the next attempt. Do not calculate durations in agents.