@bonesofspring/ai-rules 0.2.25 → 0.2.27

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

@@ -5,10 +5,10 @@ mode: subagent
 permission:
   edit:
     "*": deny
-    ".opencode/team/**": allow
+    ".ai.local/team/**": allow
 ---
 
-Write only team artifacts under `.opencode/team/**`. Do not edit production code.
+Write only team artifacts under `.ai.local/team/**`. Do not edit production code.
 
 You are a unit test planner for a Next.js frontend with Jest/Vitest and Testing Library.
 
@@ -16,7 +16,7 @@ Use the **`unit-testing` skill** and **`tests-unit.md`**.
 
 ## Inputs
 
-1. `.opencode/team/tasks/<slug>/brief.md` and `decomposition.md`.
+1. `.ai.local/team/tasks/<slug>/brief.md` and `decomposition.md`.
 2. Changed or target modules under `app/src/**`.
 3. Existing `*.spec.ts` / `*.spec.tsx` in the same areas.
 
@@ -29,7 +29,7 @@ Use the **`unit-testing` skill** and **`tests-unit.md`**.
 
 ## Output
 
-Write `.opencode/team/tasks/<slug>/unit-test-plan.md`:
+Write `.ai.local/team/tasks/<slug>/unit-test-plan.md`:
 
 ```markdown
 # Unit test plan: <slug>
@@ -54,7 +54,7 @@ Test titles in the plan must follow Russian capitalization rules from `tests-uni
 
 ## Artifact contract
 
-- **Authoritative inputs:** read `.opencode/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the manifest entries for brief/decomposition and target modules under `app/src/**`.
+- **Authoritative inputs:** read `.ai.local/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the manifest entries for brief/decomposition and target modules under `app/src/**`.
 - **Owned outputs:** `unit-test-plan.md`; upsert only the manifest entry assigned by handoff (`artifactOutputId`; fallback `unit-test-planner`) and preserve all foreign entries.
 - **Terminal receipt:** cover applicable AC/task IDs, list authoritative evidence paths, and emit `completed` or `blocked`. Bind it to the supplied `attemptId` when present.
 - **Shared state:** never create or mutate `status.json` or `metrics.json`; the orchestration runtime/hook owns lifecycle, gates, retries, attempts, and timestamps.

package/presets/opencode/next/ai-local/conventions.md

@@ -0,0 +1,21 @@
+# Living conventions
+
+Consumer-owned store for post-init gotchas, patterns, and decisions. **Not** always-on. Fill after `ai-rules init`. Root `AGENTS.md` only points here.
+
+## Gotchas
+
+<!-- e.g. fragile flows, “never do X in this repo” -->
+
+-
+
+## Patterns
+
+<!-- local patterns beyond reference-features table -->
+
+-
+
+## Decisions
+
+<!-- short pointers to ADRs / product choices that affect code -->
+
+-

package/presets/opencode/next/commands/README.md

@@ -40,10 +40,10 @@ Slash commands are copied to `.opencode/commands/` on `ai-rules init opencode --
 
 ## Related files
 
-- Subagents: `../agents/` (**22** roles, including `task-router.md`, `codebase-analyzer.md`)
+- Subagents: `../agents/` (**24** roles, including `task-router.md`, `codebase-analyzer.md`)
 - Orchestrator: `../rules/agent-team-orchestrator.md`
 - Skills: `../skills/` (`feature-delivery`, `code-review`, `debug-investigation`, `ci-investigation`, `unit-testing`, `playwright-e2e`, `technical-retro`)
-- Artifacts: `../team/README.md` (`pipeline.json`, `status.json`)
+- Artifacts: `.ai.local/team/README.md` (`pipeline.json`, `status.json`)
 - Hooks: `../hooks/chain-team-phases.sh` only (semi-auto runner; no `hooks.json`)
 
 Create and edit commands via `/commands` in Cursor or directly in this preset folder.

package/presets/opencode/next/commands/spec-start.md

@@ -1,5 +1,5 @@
 ---
-description: Bootstrap or generate docs/specs (INDEX + page/feature) via task-analyst author mode. Optional docs-only path with human gate.
+description: "Bootstrap or generate docs/specs (INDEX + page/feature) via task-analyst author mode. Optional docs-only path with human gate."
 ---
 
 ## Invocation arguments
@@ -14,8 +14,8 @@ Routes intent **`spec-gen`** (or bootstrap) → **task-analyst** in **author mod
 
 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 `.opencode/team/tasks/<slug>/` exists (Write artifacts; not Shell mkdir).
-4. Write `.opencode/team/active-task.json` → `{ "slug": "<slug>" }`.
+3. Ensure `.ai.local/team/tasks/<slug>/` exists (Write artifacts; not Shell mkdir).
+4. Write `.ai.local/team/active-task.json` → `{ "slug": "<slug>" }`.
 5. Write minimal `pipeline.json`: task-analyst → (optional stop) → feature-developer only if user asked implement-after. **No separate spec-author agent.**
 6. Invoke **task-analyst** with: author mode; load **`product-specs`** + **`product-specs-authoring`** + skill **`spec-authoring`**; Bootstrap if `docs/specs/` absent, else Generate. Optional: if arguments/AC ask research-before-spec, also load skill **`spec-discovery`** (not default).
 7. Wait for analyst. **Do not** invoke feature-developer until human gate passes.

package/presets/opencode/next/commands/task-continue.md

@@ -1,5 +1,5 @@
 ---
-description: Continue an agent-team task after a human gate, pause, or review changes request using pipeline.json and status.json.
+description: "Continue an agent-team task after a human gate, pause, or review changes request using pipeline.json and status.json."
 ---
 
 ## Invocation arguments
@@ -16,7 +16,7 @@ Resume the pipeline from `pipeline.json`.
 
 ## Preconditions
 
-1. Read `.opencode/team/tasks/<slug>/pipeline.json` and `status.json`.
+1. Read `.ai.local/team/tasks/<slug>/pipeline.json` and `status.json`.
 2. Continue if:
    - `awaitingHumanGate: true` or `state: awaiting_approval`, **or**
    - `state: changes_requested` (after review), **or**
@@ -24,7 +24,7 @@ Resume the pipeline from `pipeline.json`.
 
 ## Algorithm
 
-1. Write `.opencode/team/active-task.json` → `{ "slug": "<slug>" }`.
+1. Write `.ai.local/team/active-task.json` → `{ "slug": "<slug>" }`.
 2. **Human gate resume** (`awaitingHumanGate` / `awaiting_approval`):
    1. **Do not** manually increment `pipelineIndex` or invent `currentAgent` first.
    2. Close the gate + activate the next attempt via the **installed** hook (single authority for ledger + status):

package/presets/opencode/next/commands/task.md

@@ -1,5 +1,5 @@
 ---
-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."
 ---
 
 ## Invocation arguments
@@ -30,7 +30,7 @@ Examples:
 
 ## Procedure
 
-1. **Slug** — kebab-case from the description (≤48 characters). Create `.opencode/team/tasks/<slug>/` via **Write** (e.g. placeholder `pipeline.json` or empty marker) — runtime/hook owns `status.json` — **not** via Shell `mkdir` (sandbox → `Operation not permitted`).
+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) — 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 `/technical-retro` and **stop**.

package/presets/opencode/next/commands/technical-retro.md

@@ -1,5 +1,5 @@
 ---
-description: Facilitate a technical retrospective for a period, incident, release, or completed agent-team task slug.
+description: "Facilitate a technical retrospective for a period, incident, release, or completed agent-team task slug."
 ---
 
 ## Invocation arguments
@@ -29,10 +29,10 @@ Request when missing:
 
 Read from the repository:
 
-- `.opencode/team/tasks/<slug>/pipeline.json`
-- `.opencode/team/tasks/<slug>/brief.md`
-- `.opencode/team/tasks/<slug>/decomposition.md`
-- `.opencode/team/tasks/<slug>/status.json`
+- `.ai.local/team/tasks/<slug>/pipeline.json`
+- `.ai.local/team/tasks/<slug>/brief.md`
+- `.ai.local/team/tasks/<slug>/decomposition.md`
+- `.ai.local/team/tasks/<slug>/status.json`
 - Git diff / `git status` for changed files
 
 Do not attribute facts not present in artifacts, diff, or the user's message.

package/presets/opencode/next/hooks/README.md

@@ -11,7 +11,7 @@ printf '%s\n' '{"status":"completed","attemptId":"<runtime-attempt-id>"}' \
   | bash .opencode/hooks/chain-team-phases.sh
 ```
 
-`<runtime-attempt-id>` comes from `.opencode/team/tasks/<slug>/status.json`.
+`<runtime-attempt-id>` comes from `.ai.local/team/tasks/<slug>/status.json`.
 Do not invent it. Agents never write lifecycle fields in `status.json` or
 `metrics.json`.
 

package/presets/opencode/next/hooks/chain-team-phases.sh

@@ -10,7 +10,7 @@ INPUT="$input" node <<'NODE'
 const fs = require('fs');
 const path = require('path');
 
-const TEAM_ROOT = path.join(process.cwd(), '.opencode', 'team');
+const TEAM_ROOT = path.join(process.cwd(), '.ai.local', 'team');
 
 const inputRaw = process.env.INPUT || '';
 let hookInput;
@@ -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);
 }
@@ -61,7 +64,7 @@ if (!fs.existsSync(statusPath)) {
 let status;
 const now = new Date().toISOString();
 const STACK = 'next';
-const PLATFORM = 'cursor';
+const PLATFORM = 'opencode';
 
 function waitForMetricsLock() {
   // OD-1: real advisory lock via create-exclusive (fs.openSync(_, 'wx')).
@@ -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 */ }
     }
@@ -318,7 +331,7 @@ function findNextExecutableStep(steps, startIdx, dir) {
 
 const AGENT_HANDOFF = {
   'task-analyst': (s) =>
-    `Invoke task-analyst for slug "${s}". Write brief.md and decomposition.md under .opencode/team/tasks/${s}/. ` +
+    `Invoke task-analyst for slug "${s}". Write brief.md and decomposition.md under .ai.local/team/tasks/${s}/. ` +
     `Upsert the analysis receipt in artifact-manifest.json; do not mutate status.json lifecycle fields. Do not use legacy phase analysis.`,
   debugger: (s) =>
     `Invoke debugger subagent for slug "${s}". Investigate root cause; write debug-report.md with fixApplied: true/false. ` +
@@ -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
@@ -655,9 +684,10 @@ function nearestPrecedingStepIndex(agent, fromIndex, fallback) {
 }
 function scheduleRetry(agent, retryAfterFix, predecessor, explicitStepIndex = null) {
   const currentIndex = typeof status.pipelineIndex === 'number' ? status.pipelineIndex : 0;
-  const stepIndex = Number.isInteger(explicitStepIndex)
-    ? explicitStepIndex
-    : nearestPrecedingStepIndex(agent, currentIndex, currentIndex);
+  const explicitOk = Number.isInteger(explicitStepIndex) && getStepAgents(steps[explicitStepIndex]).includes(agent);
+  const stepIndex = explicitOk ? explicitStepIndex : nearestPrecedingStepIndex(agent, currentIndex, -1);
+  // Refuse to activate an agent the pipeline never planned; callers fall back to a human gate.
+  if (stepIndex < 0) return -1;
   const predecessorAttemptId = predecessor?.attemptId || status.lastCompletedAttempt?.attemptId || null;
   appendMetric({ type: 'retry_scheduled', at: now, attemptId: predecessorAttemptId, nextAgent: agent, retryAfterFix: retryAfterFix || null, source: 'hook', attributionConfidence: predecessor ? predecessor.confidence : 'unknown' });
   activateAttempts(steps[stepIndex] || { agent }, stepIndex);
@@ -716,6 +746,18 @@ if (currentStep?.parallel && stepAgents.length > 1) {
         }
       : finishedAttempt;
     const developerIndex = scheduleRetry('feature-developer', retryReviewer, predecessor);
+    if (developerIndex < 0) {
+      beginHumanGate();
+      writeStatus({
+        awaitingHumanGate: true,
+        state: 'awaiting_approval',
+        currentAgent: retryReviewer,
+        parallelCompleted: [],
+        parallelOutcomes: {},
+      });
+      out(`${retryReviewer} requested changes for slug "${slug}" but this pipeline has no feature-developer step. Read the review artifact. Resume only via /task-continue.`);
+      process.exit(0);
+    }
     writeStatus({
       pipelineIndex: developerIndex,
       currentAgent: 'feature-developer',
@@ -758,6 +800,12 @@ if (status.state === 'changes_requested') {
   }
   const retryAfterFixStepIndex = typeof status.pipelineIndex === 'number' ? status.pipelineIndex : 0;
   const developerIndex = scheduleRetry('feature-developer', reviewer, finishedAttempt);
+  if (developerIndex < 0) {
+    beginHumanGate();
+    writeStatus({ awaitingHumanGate: true, state: 'awaiting_approval', currentAgent: reviewer });
+    out(`${reviewer} requested changes for slug "${slug}" but this pipeline has no feature-developer step. Read the review artifact. Resume only via /task-continue.`);
+    process.exit(0);
+  }
   writeStatus({
     pipelineIndex: developerIndex,
     currentAgent: 'feature-developer',
@@ -773,6 +821,12 @@ if (status.state === 'changes_requested') {
 if (status.state === 'validation_failed' && status.currentAgent === 'build-verifier') {
   const retryAfterFixStepIndex = typeof status.pipelineIndex === 'number' ? status.pipelineIndex : 0;
   const developerIndex = scheduleRetry('feature-developer', 'build-verifier', finishedAttempt);
+  if (developerIndex < 0) {
+    beginHumanGate();
+    writeStatus({ awaitingHumanGate: true, state: 'awaiting_approval', currentAgent: 'build-verifier' });
+    out(`Validation failed for slug "${slug}" but this pipeline has no feature-developer step. Read validation-report.md. Resume only via /task-continue.`);
+    process.exit(0);
+  }
   writeStatus({
     pipelineIndex: developerIndex,
     currentAgent: 'feature-developer',
@@ -788,9 +842,13 @@ if (status.state === 'validation_failed' && status.currentAgent === 'build-verif
 if (status.state === 'completed' && status.retryAfterFix) {
   const retry = status.retryAfterFix;
   const retryIndex = scheduleRetry(retry, null, finishedAttempt, status.retryAfterFixStepIndex);
-  writeStatus({ pipelineIndex: retryIndex, currentAgent: retry, state: 'in_progress', retryAfterFix: null, retryAfterFixStepIndex: null });
-  out(handoffForAgent(retry, steps[retryIndex]?.scope, steps[retryIndex]));
-  process.exit(0);
+  if (retryIndex >= 0) {
+    writeStatus({ pipelineIndex: retryIndex, currentAgent: retry, state: 'in_progress', retryAfterFix: null, retryAfterFixStepIndex: null });
+    out(handoffForAgent(retry, steps[retryIndex]?.scope, steps[retryIndex]));
+    process.exit(0);
+  }
+  // The reviewer to re-run is no longer in steps[]; drop the marker and advance normally.
+  writeStatus({ retryAfterFix: null, retryAfterFixStepIndex: null });
 }
 
 if (!currentStep) {

package/presets/opencode/next/rules/agent-team-orchestrator.md

@@ -2,7 +2,7 @@
 
 # Agent team orchestrator
 
-Parent agent = **manager**. Router plans; specialists execute. Artifacts: `.opencode/team/tasks/<slug>/` (Claude: `.claude/team/tasks/<slug>/`).
+Parent agent = **manager**. Router plans; specialists execute. Artifacts: `.ai.local/team/tasks/<slug>/`.
 
 Work request without `/task` — see **agent-team-intake** (when to suggest the router instead of coding directly).
 
@@ -27,7 +27,7 @@ Roster of specialists is **stack-specific** (agent names and write scopes differ
 | Tests | unit planner/generator/healer; e2e/UI planner/generator/healer (stack-native) |
 | Docs | `tech-writer` |
 
-**OpenCode frontmatter:** all team pipeline agents use `mode: subagent` and `permission.edit` so they can write team artifacts (`edit: allow` for implementers; deny except `.opencode/team/**` for reviewers/planners). Production/app restrictions live in the agent prompt body. See `agents/README.md`.
+**OpenCode frontmatter:** all team pipeline agents use `mode: subagent` and `permission.edit` so they can write team artifacts (`edit: allow` for implementers; deny except `.ai.local/team/**` for reviewers/planners). Production/app restrictions live in the agent prompt body. See `agents/README.md`.
 
 Full prompts: stack `agents/*.md`. Artifact conventions: stack `team/README.md`; schema SoT: **agent-artifact-contracts**.
 
@@ -105,7 +105,7 @@ Do not calculate durations in agents. For parallel steps, never attribute a stop
 
 ## Artifact context index and receipts
 
-Each slug has one `artifact-manifest.json`: `.opencode/team/tasks/<slug>/` or `.claude/team/tasks/<slug>/`. The full schema and completion conventions live in **agent-artifact-contracts**.
+Each slug has one `artifact-manifest.json` at `.ai.local/team/tasks/<slug>/`. The full schema and completion conventions live in **agent-artifact-contracts**.
 
 - Read the manifest before broad prior-artifact discovery. Each step receives authoritative input entry IDs, owns named output entry IDs, and finishes with one terminal receipt linked to AC/task IDs.
 - Markdown remains detailed evidence; the manifest points to authoritative paths and records producer, status, timestamps, outcome, and evidence paths.

package/presets/opencode/next/rules/ai-local-overlay.md

@@ -6,7 +6,7 @@ This rule is mandatory. **You MUST** obey it on every turn, without exception.
 
 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.
+3. **Apply** — treat every `.ai.local/rules/*.md` and `.ai.local/conventions.md` as a higher-priority rule for this repo. Do **not** load `.ai.local/team/**` as rules (shared pipeline artifacts). 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.
 
@@ -33,5 +33,5 @@ Keep files ≤ 120 lines. Match the style of preset rules (short sections, bulle
 ## Pointers
 
 - Authoring guide: `docs/LOCAL-OVERLAY.md` in the `@bonesofspring/ai-rules` package.
-- Living gotchas alternative: `.opencode/team/conventions.md`.
+- Living gotchas: `.ai.local/conventions.md`. Pipeline artifacts: `.ai.local/team/` (do not load as rules).
 - Root `AGENTS.md` reinforces this rule with a `MANDATORY` section.

package/presets/opencode/next/rules/api-services.md

@@ -14,8 +14,8 @@
 - For each domain area (for example, orders, billing, account settings):
   - a separate directory in `app/src/api/services/<ServiceName or feature>/**` following repository convention.
 - Inside a module:
-  - files with API calls (`index.ts` or `*.service.ts`);
-  - mapper files (`*responseMappers.ts`);
+  - files with API calls — follow the repo's shape: `index.ts` / `*.service.ts`, **or** a per-domain module exporting an object (`XxxApiMethods` in `<Domain>.apiMethods.ts` with `<Domain>.endpoints.ts` and `<Domain>.responseTypes.ts`) as in neighboring services;
+  - mapper files (`*responseMappers.ts`) — pure `format…` / `map…` functions named as in the repo;
   - request/response-specific types (if not moved to `app/src/types/**` with export through the `@/types` barrel).
   - when needed — local `index.ts` / barrel inside the module for structure **within** `app/src/api/**`; **outside** this layer UI, store, and other code import only from the root barrel `app/src/api/index.ts` (`import … from '@/api'`, **`public-imports.md`**).
 
@@ -63,10 +63,12 @@ export const getCard = async (id: string) => {
 
 ```ts
 import type { TCard } from '@/types'
-import { mapCardResponse } from './cardResponseMappers'
+import { formatCardResponse } from './cardResponseMappers'
 
 export const getCard = async (id: string): Promise<TCard> => {
   const { data } = await cardsClient.get(`/cards/${id}`)
-  return mapCardResponse(data)
+  return formatCardResponse(data)
 }
 ```
+
+Mapper function verb (`format…` vs `map…`) follows the repo — match neighboring mappers.

package/presets/opencode/next/rules/code-quality-and-refactoring.md

@@ -14,6 +14,12 @@
 - **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.
@@ -38,3 +44,10 @@ Essentials below. Full procedural set (~17 rules) → load **`anti-sycophancy-di
 Style enforcement (formatter / linter / post-change gate) lives in the **stack toolchain** — see each adapter’s **Stack notes**.
 
 > Stack-specific lint gates, examples, and toolchain — in the preset adapter **Stack notes** section.
+
+## Stack notes
+
+- Before adding a new UI control, check existing UI code and project packages.
+- Public API: index/barrel files and explicitly exported entities (`public-imports.mdc`, `layer-barrel-exports.mdc`).
+- Allowed examples: shared hook/utility; typing `any`/`unknown`; splitting a large component; CSS tokens instead of “magic” values.
+- Lint/stylelint — only **`post-change-lint.mdc`**; ESLint config: `app/eslint.config.mjs`. Disabling a rule (`eslint-disable`) — only **locally** (line/small block) with a short “why” comment. Style prose in domain rules stays thin — prefer ESLint/Stylelint over duplicating formatter recipes.

package/presets/opencode/next/rules/code-review-mr.md

@@ -38,3 +38,16 @@ Procedure details live in skill `code-review`. Required shape:
 - Rank by severity: **`blocker` | `important` | `nit`** (list blocker → nit).
 - Vague («looks risky») is not a finding — cite evidence or ask for surrounding file context.
 - End with a verdict on its own line: **`Safe to merge | needs changes | reject`**.
+
+## Stack notes
+
+On-demand rule for review flows. **Procedure and output format:** skill `code-review`.
+
+### Checklist references
+
+- Architecture layers: `architecture-boundaries.mdc`, `next-app-core.mdc`; network: `http-client.mdc`
+- Imports: `public-imports.mdc`, `layer-barrel-exports.mdc`
+- UI: `react-ui.mdc`
+- Security: `security-next.mdc`
+- Tests: `tests-unit.mdc`, `playwright-agents.mdc`, `tests-e2e-structure.mdc`
+- Lint gate before final report: `post-change-lint.mdc`

package/presets/opencode/next/rules/design-guidance.md

@@ -97,3 +97,8 @@ Do not introduce a second stem (`refactoring-smells` / `design-patterns-for-agen
 - Ubiquitous language: `feature-delivery-workflow` (lineage).
 - MR checklist (smells in scope; pattern name only if repo uses it): `code-review-mr`.
 - Token / twin policy for authors: `preset-token-budget`, `preset-twin-sync` (meta, not consumer always-on).
+
+## Stack notes
+
+- Prefer hooks/mappers over HOC or new pattern names when the repo already extracts that way.
+- Suggest Strategy/Adapter only when ports or policy branching already exist in `app/src/**`.

package/presets/opencode/next/rules/feature-delivery-workflow.md

@@ -47,3 +47,88 @@ flowchart LR
 ## Zone → rules matrix
 
 Filled in the stack adapter: concrete globs/paths and `.mdc` / topic `.md` names.
+
+## Stack notes
+
+When the prompt or `brief.md` contains a `figma.com` URL, **mockup review** (`mockup-reviewer` / skill `mockup-review`) must complete — or the user must continue past FAIL/`BLOCKED_MCP` via `/task-continue` — **before UI implementation**. Non-UI tasks no-op this gate. When required-signal and **no** `figma.com`, **`ux-design.md`** (on the analysis manifest entry) must exist and not be `INCOMPLETE` before UI work — else **blocked**, hand back to `task-analyst`. Parallel to the mockup gate.
+
+## Style discovery (mandatory)
+
+Before writing a new file in a layer, open **1–2 analog files** in the same layer and mirror: export shape, name prefixes (`T` / `I` where the repo uses them), file suffixes (`.apiMethods.ts`, `.endpoints.ts`, `.data.ts`, `.hooks.ts`, `styles.ts`), mapper / selector / thunk naming, and barrel shape. Record the analogs in the handoff. Where this preset's examples differ from the repo, **the repo wins**.
+
+Typical feature with backend data and shared state. Layer details — `architecture-boundaries.mdc`, `next-app-core.mdc`.
+
+## Checklist (work order)
+
+1. **Domain types** — `app/src/types/**`, export via barrel (`public-imports.mdc`, **`layer-barrel-exports.mdc`**); JSDoc — `types-jsdoc.mdc`.
+2. **API contract** — DTOs where the repo uses them; domain types in `@/types`.
+3. **Mappers** — DTO → domain in `*responseMappers.ts` (`api-services.mdc`).
+4. **Services** — clients `app/src/api/clients/**`, barrel `@/api` (`api-services.mdc`, `http-client.mdc`, **`layer-barrel-exports.mdc`**). No `fetch` from UI/store.
+5. **State** — `createSlice` / `createAsyncThunk` (`store-rtk.mdc`); thunk → services from `@/api`.
+6. **UI** — types from `@/types`, no DTOs (`react-ui.mdc`, `architecture-boundaries-ui.mdc`, `no-props-spread.mdc`).
+7. **Mocks** — per repo layout; register in `app/src/mocks/handlers.ts` (see below).
+8. **Tests** — unit for mappers (`tests-unit.mdc`); e2e from `*.cases.md` (`tests-e2e-structure.mdc`, `playwright-agents.mdc`).
+9. **Completion** — **`post-change-lint.mdc`**: `lint:js` + `lint:css` + `type-check`; package manager — `package-manager.mdc`. When the current WP spans **more than one** layer or module, `implementation.md` includes a **Code Map** (3–8 annotated paths) and **Suggested Review Order** (`concern | path:line | ≤15 word note`). Omit both for a single-file or single-layer WP.
+
+## Data flow (orientation)
+
+```mermaid
+flowchart LR
+  subgraph transport [Transport]
+    HttpClient[HttpClient]
+  end
+  DTO[DTO] --> Mappers[Mappers]
+  Mappers --> Domain[Domain types]
+  Domain --> Service[API service]
+  Service --> HttpClient
+  Service --> Thunk[Thunk]
+  Thunk --> Store[Store]
+  Store --> UI[UI]
+```
+
+## Registration by layer
+
+1. **Types** — `app/src/types/**`; domain model is the source of truth for UI and store.
+2. **API** — `app/src/api/services/<ServiceRoot>/<Segment>/`; public exports (incl. **path constants** for mocks) → **`app/src/api/index.ts`**.
+3. **Mocks (MSW)** — `app/src/mocks/data/<feature>/`; handlers in **`app/src/mocks/handlers.ts`**. Paths from `@/api`; do not duplicate URL strings. Check browser worker and Node `setupServer` if both are used.
+4. **Store** — `app/src/store/slices/<FeatureName>/`; reducer in **`app/src/store/reducers.ts`**. Middleware → `app/src/store/middleware/**`, register in **`app/src/store/index.ts`**.
+5. **UI** — `app/src/ui/pages/<FeatureName>Page/**` and/or `components/**`; data via store/hooks.
+6. **Unit** — `*.spec.ts(x)`; mappers and non-trivial logic are required.
+7. **E2E** — `app/__tests__/e2e/<Area>/<plan>.cases.md` + `*.spec.ts`.
+
+## Partial scenarios
+
+| Task | Minimum actions |
+|------|-----------------|
+| API + types only | Types, service, mappers, `@/api` barrel; unit for mapper. |
+| Mocks only | Path in `@/api`; handlers + `mocks/handlers.ts`. |
+| Store only | Thunk via `@/api`; slice + `reducers.ts`. |
+| UI only | Store state; no HTTP/DTO. |
+| E2E only | `*.cases.md` + spec; page object. |
+
+## Anti-patterns
+
+- DTO in UI or untyped store.
+- HTTP client from a component/thunk bypassing the service.
+- Deep-import `@/api/services/**` from UI/store.
+- `{...props}` into components — `no-props-spread.mdc`.
+- **Ubiquitous language:** Domain/type names reflect the feature’s subject domain — do not mix transport/framework terms into the domain without need.
+- Load `design-guidance` (rule stem) when assessing structure, smells, or pattern fit.
+- Do not mutate pipeline `status.json` / `metrics.json`; the orchestration hook is the single writer. Skills upsert the owned terminal receipt in `artifact-manifest.json`.
+
+## Matrix: zone → rules
+
+| Zone | Rules |
+|------|-------|
+| `app/src/api/clients/**`, `app/src/lib/clients/**` | `http-client.mdc`, `tests-unit.mdc` (behavior) |
+| `app/src/api/services/**` | `api-services.mdc`, `layer-barrel-exports.mdc`, `http-client.mdc` |
+| `app/src/store/**` | `store-rtk.mdc`, `architecture-boundaries.mdc`, `public-imports.mdc` |
+| `app/src/ui/**` | `react-ui.mdc`, `no-props-spread.mdc`, `public-imports.mdc` |
+| `app/src/types/**` | `public-imports.mdc`, `types-jsdoc.mdc`, `layer-barrel-exports.mdc` |
+| `app/__tests__/e2e/**` | `tests-e2e-structure.mdc`, `playwright-agents.mdc` |
+
+When adding or extending a feature, **walk the checklist** and the rules from the table for affected zones.
+
+## Related
+
+- Product behavior discovery: requestable **`product-specs`** (`docs/specs/INDEX.md`) — do not paste the discovery algorithm here.

package/presets/opencode/next/rules/mcp-usage.md

@@ -84,3 +84,12 @@ Policy is stack-class-specific — see adapter **Stack notes**. If a Figma **plu
 - Treating overlay absence as blocked (except user-required SoT)
 - Tracker/admin write tools without an explicit ask
 - Calling overlay MCP “just in case” on unrelated tasks
+
+## Stack notes
+
+- Pipeline **`mockup-reviewer`** is the only agent that reads Figma for mockup review. See `mockup-review`.
+- Shipped besides Context7: browser automation MCP (`playwright` / `playwright-test` / `user-playwright`) and `chrome-devtools`.
+- **Split:** Playwright MCP → e2e agents (planner/generator/healer), selector checks, spec reproduction. Chrome DevTools MCP → `debugger` / `performance-auditor` against a **running app** (console, network, traces). Not a substitute for e2e.
+- **Storybook overlay** (not shipped): aliases `storybook`, `user-storybook`, `plugin-storybook`, `storybook-mcp-addon`. Needs Storybook running (often `http://localhost:6006/mcp`). Discover docs/dev/testing toolsets. If down, read story/source files. Block only if the user required Storybook MCP as SoT.
+- `init` **merges** `mcpServers`: preset keys update; extra local servers are kept. User-level MCP is never touched.
+- If a Figma plugin is already connected, do not also require the project `figma` server.

package/presets/opencode/next/rules/mockup-review.md

@@ -105,3 +105,7 @@ PASS | PASS_WITH_NOTES | FAIL | BLOCKED_MCP
 ## AC coverage
 | Criterion | Status | Notes |
 ```
+
+## Stack notes
+
+Illustrative web buckets (not enforced pixels): ~375 / ~768 / ~1280 mapped to small / medium / large.

package/presets/opencode/next/rules/next-app-core.md

@@ -5,8 +5,9 @@ Concrete versions come **from `package.json` and configs of the target repositor
 # Project structure
 
 - `app/` — Next.js root; `app/src/**` — code; `app/__tests__/e2e/**` — e2e.
-- `app/tsconfig.json`: `baseUrl: "."`, `paths: { "@/*": ["./src/*"] }`.
+- `app/tsconfig.json`: `paths: { "@/*": ["./src/*"] }` (`baseUrl` may be absent with TS ≥5 / `moduleResolution: bundler` — check the file, do not add it blindly).
 - **Requirement:** `@/*` instead of relative imports that climb the tree.
+- **Router mode:** detect from the repo before adding routes — App Router (`app/src/app/**`, `page.tsx`) vs Pages Router (`app/src/pages/**`, `_app.tsx`). Do **not** assume App Router; follow the mode already in use (`next-app-router.md`, `navigation-router-stack.md`).
 
 # Architectural layers
 

package/presets/opencode/next/rules/preset-layering.md

@@ -9,7 +9,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/opencode/next/rules/preset-pr-checklist.md

@@ -9,10 +9,10 @@ Checklist for PRs that touch `packages/ai-rules/presets/**` (and dogfood `.curso
 - [ ] **SoT:** edits in `packages/…` (not only root `.cursor/`)
 - [ ] **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`)
-- [ ] **Mavis derive:** mapped `cursor/<stack>/` change → `mavis/<stack>/` + `adapter-map.json` **same PR** when the stack is in `releasedStacks` (run `generate-mavis-next.mjs` + `check-mavis-adapter-map.mjs` for `next`; 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-next.mjs` + `check-opencode-adapter-map.mjs` for `next`; see `preset-twin-sync` § OpenCode derivation)
+- [ ] **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`.