@bonesofspring/ai-rules 0.2.26 → 0.2.28

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

@@ -10,6 +10,23 @@ permission:
 
 Write only team artifacts under `.ai.local/team/**`. Do not edit production code.
 
+## Rules to load (subagent context)
+
+This subagent does **not** inherit `opencode.json` `instructions`. Read these rules explicitly before acting:
+
+- `.opencode/rules/next-app-core.md`
+- `.opencode/rules/package-manager.md`
+- `.opencode/rules/code-quality-and-refactoring.md`
+- `.opencode/rules/ai-local-overlay.md`
+- `.opencode/rules/architecture-boundaries.md` — layer boundaries and allowed imports
+- `.opencode/rules/feature-delivery-workflow.md` — layer order, mockup gate, ux-design gate
+- `.opencode/rules/reference-features.md` — analog files first
+- `.opencode/rules/anti-sycophancy-discipline.md` — procedural anti-sycophancy rules
+- `.opencode/rules/post-change-lint.md` — lint/type-check after code edits
+- `.opencode/rules/mcp-usage.md` — when verifying third-party APIs (Context7)
+
+Also read matching `.ai.local/rules/*.md` (local overlay) for the active zone, and the project strict rules if present.
+
 You are a task router for a Next.js frontend agent team. You **do not** implement tasks — you classify intent and plan the agent pipeline.
 
 ## Inputs

package/presets/opencode/next/agents/tech-writer.md

@@ -11,6 +11,23 @@ permission:
 
 Write team artifacts under `.ai.local/team/**` and scoped files (`docs/**`). Do not edit production code.
 
+## Rules to load (subagent context)
+
+This subagent does **not** inherit `opencode.json` `instructions`. Read these rules explicitly before acting:
+
+- `.opencode/rules/next-app-core.md`
+- `.opencode/rules/package-manager.md`
+- `.opencode/rules/code-quality-and-refactoring.md`
+- `.opencode/rules/ai-local-overlay.md`
+- `.opencode/rules/architecture-boundaries.md` — layer boundaries and allowed imports
+- `.opencode/rules/feature-delivery-workflow.md` — layer order, mockup gate, ux-design gate
+- `.opencode/rules/reference-features.md` — analog files first
+- `.opencode/rules/anti-sycophancy-discipline.md` — procedural anti-sycophancy rules
+- `.opencode/rules/post-change-lint.md` — lint/type-check after code edits
+- `.opencode/rules/mcp-usage.md` — when verifying third-party APIs (Context7)
+
+Also read matching `.ai.local/rules/*.md` (local overlay) for the active zone, and the project strict rules if present.
+
 You are a technical writer for a Next.js frontend team.
 
 ## Inputs

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

@@ -6,6 +6,24 @@ permission:
   edit: allow
 ---
 
+## Rules to load (subagent context)
+
+This subagent does **not** inherit `opencode.json` `instructions`. Read these rules explicitly before acting:
+
+- `.opencode/rules/next-app-core.md`
+- `.opencode/rules/package-manager.md`
+- `.opencode/rules/code-quality-and-refactoring.md`
+- `.opencode/rules/ai-local-overlay.md`
+- `.opencode/rules/architecture-boundaries.md` — layer boundaries and allowed imports
+- `.opencode/rules/feature-delivery-workflow.md` — layer order, mockup gate, ux-design gate
+- `.opencode/rules/reference-features.md` — analog files first
+- `.opencode/rules/anti-sycophancy-discipline.md` — procedural anti-sycophancy rules
+- `.opencode/rules/post-change-lint.md` — lint/type-check after code edits
+- `.opencode/rules/mcp-usage.md` — when verifying third-party APIs (Context7)
+- `.opencode/rules/tests-unit.md`
+
+Also read matching `.ai.local/rules/*.md` (local overlay) for the active zone, and the project strict rules if present.
+
 You generate unit tests from project test plans.
 
 ## Inputs

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

@@ -6,6 +6,24 @@ permission:
   edit: allow
 ---
 
+## Rules to load (subagent context)
+
+This subagent does **not** inherit `opencode.json` `instructions`. Read these rules explicitly before acting:
+
+- `.opencode/rules/next-app-core.md`
+- `.opencode/rules/package-manager.md`
+- `.opencode/rules/code-quality-and-refactoring.md`
+- `.opencode/rules/ai-local-overlay.md`
+- `.opencode/rules/architecture-boundaries.md` — layer boundaries and allowed imports
+- `.opencode/rules/feature-delivery-workflow.md` — layer order, mockup gate, ux-design gate
+- `.opencode/rules/reference-features.md` — analog files first
+- `.opencode/rules/anti-sycophancy-discipline.md` — procedural anti-sycophancy rules
+- `.opencode/rules/post-change-lint.md` — lint/type-check after code edits
+- `.opencode/rules/mcp-usage.md` — when verifying third-party APIs (Context7)
+- `.opencode/rules/tests-unit.md`
+
+Also read matching `.ai.local/rules/*.md` (local overlay) for the active zone, and the project strict rules if present.
+
 You debug and fix failing unit tests.
 
 ## Inputs

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

@@ -10,6 +10,24 @@ permission:
 
 Write only team artifacts under `.ai.local/team/**`. Do not edit production code.
 
+## Rules to load (subagent context)
+
+This subagent does **not** inherit `opencode.json` `instructions`. Read these rules explicitly before acting:
+
+- `.opencode/rules/next-app-core.md`
+- `.opencode/rules/package-manager.md`
+- `.opencode/rules/code-quality-and-refactoring.md`
+- `.opencode/rules/ai-local-overlay.md`
+- `.opencode/rules/architecture-boundaries.md` — layer boundaries and allowed imports
+- `.opencode/rules/feature-delivery-workflow.md` — layer order, mockup gate, ux-design gate
+- `.opencode/rules/reference-features.md` — analog files first
+- `.opencode/rules/anti-sycophancy-discipline.md` — procedural anti-sycophancy rules
+- `.opencode/rules/post-change-lint.md` — lint/type-check after code edits
+- `.opencode/rules/mcp-usage.md` — when verifying third-party APIs (Context7)
+- `.opencode/rules/tests-unit.md`
+
+Also read matching `.ai.local/rules/*.md` (local overlay) for the active zone, and the project strict rules if present.
+
 You are a unit test planner for a Next.js frontend with Jest/Vitest and Testing Library.
 
 Use the **`unit-testing` skill** and **`tests-unit.md`**.

package/presets/opencode/next/ai-local/rules-library/agent-artifacts-no-local-paths.md

@@ -0,0 +1,38 @@
+glob: always
+
+## Body
+
+# Agent artifacts: no local machine paths
+
+When this rule applies, acknowledge: `Using .ai.local: agent-artifacts-no-local-paths(, …)*`.
+
+Committed agent artifacts leak into git history. Absolute host paths expose the developer machine layout even if the file is deleted in a later MR.
+
+## Forbidden
+
+Do **not** write host-absolute paths, including:
+
+- `/Users/<username>/…` (macOS)
+- `/home/<username>/…` (Linux)
+- `C:\Users\<username>\…` and `C:/Users/<username>/…` (Windows)
+- Any other absolute checkout root.
+
+Do **not** put those strings in `productionTarget.root`, `instructions[]`, summaries, or evidence lists.
+
+## Required instead
+
+- This repo: path from workspace root (`src/…`, `.ai.local/team/tasks/<slug>/pipeline.json`).
+- Task-local artifacts: basename is enough (`pipeline.json`, `brief.md`) when the file lives in the same task directory.
+- Sibling / other repo: **repo name** + repo-relative path. Never the filesystem location of that checkout.
+
+## Gate before finishing a write
+
+After writing or editing a team artifact, scan the file (and any JSON you are about to write) for `/Users/`, `/home/`, `C:\Users`, `C:/Users`. If any match, rewrite to repo-relative **before** considering the step done.
+
+Deleting a leaked file later does **not** remove it from git history — prevention is the only fix.
+
+## Allowed (not this ban)
+
+- Repo-relative paths, `@/` aliases, URL paths (`/api/…`).
+- Public URLs (`https://…`, `figma.com/…`).
+- Ephemeral local logs that are **not** committed.

package/presets/opencode/next/ai-local/rules-library/commit-hygiene.md

@@ -0,0 +1,17 @@
+glob: always
+
+## Body
+
+# Commit hygiene
+
+When committing or preparing a commit, acknowledge: `Using .ai.local: commit-hygiene(, …)*`.
+
+Agents do not run `git commit`/`git push`. This rule constrains the **human commit step** and the agent's end-of-turn commit guidance.
+
+## Rules
+
+- **One area per commit.** Do not mix unrelated feature areas or layers in one commit. A commit that spans more than one area tag (or >~40 files) must be split, or the split must be justified in the message.
+- **Never mix trees.** Do not put `src/**` (or any product path) in the same commit as `**/team/tasks/**`, `openspec/**`, `docs/**`, storybook baselines, or config. Artifact/doc churn and source changes go in separate commits.
+- **Owning slug required.** Every commit touching `src/**` names its task slug or ticket id in the subject/body. "cleanup", "restore", "rename", "fix review comments" are not exemptions.
+- **No debug residue.** Do not commit `= true` debug flags, commented-out blocks, or unused exports.
+- **Spike ≠ ship.** A `spike`/`research` task does not commit `src/**` behaviour.

package/presets/opencode/next/ai-local/rules-library/mcp-required-for-ui-layout.md

@@ -0,0 +1,41 @@
+globs: src/ui/**
+
+## Body
+
+# MCP access gate for UI layout work (strict)
+
+Before **any** markup/layout implementation or refactor under `src/ui/**` (JSX structure, Linaria/styled-components, breakpoints, spacing, alignment, CTA placement, card/panel geometry), the agent MUST verify the **session MCP catalog** — it is the source of truth, not this file, not `opencode.json`, not `.opencode/MCP.md`.
+
+Acknowledge: `Using .ai.local: mcp-required-for-ui-layout(, …)*`.
+
+## Categorical ban — layout implementation without Figma MCP **and** Storybook MCP
+
+Implementing or refactoring UI markup/layout is **FORBIDDEN** unless BOTH servers are fully available and usable **in the current session**:
+
+1. **Figma MCP** — can read the real design node: `get_design_context` / `get_metadata` / `get_screenshot` / `get_variable_defs` for the target frame(s). A static image, exported PNG, or someone's description is **not** full access.
+2. **Storybook MCP** — can read story instructions and run the visual/test gate. With `@storybook/addon-mcp` (served by the running dev server at `/mcp`) the real tools are: `get-storybook-story-instructions`, `stories-preview`, `test-run` (docs: `docs-list` / `docs-show`). Tool names differ per MCP implementation — discover them from the session catalog; do not assume names.
+
+If either server is missing, `error`, `needsAuth`, or `loading`:
+
+- **STOP.** Do not edit layout/markup/styles. Do not "approximate from memory".
+- Report exactly: `Blocked: <figma|storybook> MCP unavailable — layout implementation banned (mcp-required-for-ui-layout).`
+- Ask the operator to configure/authenticate the MCP, or to **explicitly change this rule**. The agent MUST NOT self-waive.
+
+A running Storybook dev server (e.g. `localhost:6006`) reached through a browser MCP (chrome-devtools / Playwright) is **not** a substitute for Storybook MCP tooling.
+
+## Playwright MCP — mandatory warning + confirmation
+
+If Playwright MCP is unavailable during UI work:
+
+- Emit a **visible warning** in the turn output (do not bury it).
+- Do **not** start layout work or its verification until the operator confirms (`yes` / `no`).
+- Rationale: Playwright is the fallback for composed-frame, breakpoint, and interaction checks that Storybook MCP cannot cover.
+
+## Scope
+
+- **Banned:** writing/editing layout, markup, styles, breakpoints, spacing, alignment, CTA placement under `src/ui/**`.
+- **Allowed without the gate:** read-only investigation, comparing an existing implementation against a mockup, writing review artifacts (`mockup-review.md`, `perf-report.md`, …). The ban is on implementation, not on analysis.
+
+## Reference
+
+Project strict rule: `.ai.local/rules/00-strict-rules.md`. Adapt the path for your repo (this seed uses `.ai.local`).

package/presets/opencode/next/ai-local/rules-library/no-test-driven-behavior-change.md

@@ -0,0 +1,14 @@
+globs: src/**/*.{ts,tsx}
+
+## Body
+
+# Tests adapt to the product, not the reverse
+
+When editing `src`, tests, or stories, acknowledge: `Using .ai.local: no-test-driven-behavior-change(, …)*`.
+
+## Rules
+
+- Do not change production behaviour (`src/**`) to make a test, story, or e2e case reachable. Fix the test, the fixture, or the mock instead.
+- If a test reveals a genuine product gap, file it as a task; do not silently ship the behaviour change inside a "test stabilisation" commit.
+- Never rewrite `*.cases.md` / QA prose to match an unintended behaviour change. Prose changes that hide a behaviour change are a `blocker` for `code-reviewer`.
+- Removing a `test`/`snapshot` tag or commenting out `play` to go green is forbidden.

package/presets/opencode/next/ai-local/rules-library/pre-pr-checklist.md

@@ -0,0 +1,16 @@
+glob: always
+
+## Body
+
+# Pre-PR checklist
+
+Before opening a PR / finishing a branch, acknowledge: `Using .ai.local: pre-pr-checklist(, …)*`.
+
+## Checklist
+
+- [ ] Commits split: source / artifacts / docs; one area each; no mixed trees
+- [ ] `git status` clean of temp dumps, `* (1).*` copies, debug flags
+- [ ] Lint + type-check + targeted unit + storybook vitest green
+- [ ] e2e plan executed for user-flow AC; mock-path regexes match ≥1 route
+- [ ] L2/L3 `proposal.md` claims reconcile with the shipped diff
+- [ ] Review artifacts cite the reviewed revision (sha)

package/presets/opencode/next/ai-local/rules-library/router-pages.md

@@ -0,0 +1,23 @@
+override: kill next-app-router
+globs: src/pages/**/*.{ts,tsx},src/ui/**/*.{ts,tsx},next.config.ts
+
+## Body
+
+# Routing — Pages Router (not App Router)
+
+When doing routing / page / navigation work, acknowledge: `Using .ai.local: router-pages(, …)*`.
+
+This rule drops the preset's `next-app-router` rule from context for repos using the **Next.js Pages Router**. Enable by moving this file into `.ai.local/rules/` (it is staged-inactive in `.ai.local/rules-library/` by default).
+
+## Rules
+
+- Route files live in `src/pages/<route>/index.tsx` (or `<route>.tsx`), thin wrappers.
+- Domain UI lives in `src/ui/pages/<Name>Page`; route files do not contain layout/business logic.
+- Navigation: `next/router` (`useRouter`) and `next/link`. **Never** `next/navigation`.
+- `_app.tsx` / `_document.tsx` stay in `src/pages/`.
+
+## Forbidden
+
+- Creating App Router files (`src/app/**`, `page.tsx`, `layout.tsx`, `loading.tsx`, `error.tsx`, `route.ts`).
+- Importing `next/navigation` or App Router server APIs (`cookies()`, `headers()`, `redirect()`).
+- `getServerSideProps` / `getStaticProps` — the app is a client-rendered static export; data goes through the store/`@/api`.

package/presets/opencode/next/ai-local/rules-library/single-source-copy-constants.md

@@ -0,0 +1,16 @@
+globs: src/**/*.{ts,tsx}
+
+## Body
+
+# Single source for copy, constants, enums, routes
+
+When editing `src/**`, acknowledge: `Using .ai.local: single-source-copy-constants(, …)*`.
+
+Copy (button labels, headings, alt text, aria-labels), constants, enums, and route paths live in **one** owner module. Components import from that module — they do not redeclare literals.
+
+## Rules
+
+- User-visible copy: inline unless the same string is used in ≥2 distinct places OR is consumed by tests/stories that need a shared reference. Multi-instance refactors belong to a dedicated task.
+- Numeric / pixel / token aliases: inline directly; do not re-wrap into a named constant when used exactly once in the same file.
+- Counters and derived single-use values: inline (`array.length`, computed expressions).
+- Layout sizes of one component (skeleton `height`/`width`/`maxWidth`, one-off `px`) stay as literals in the JSX prop or in `styles.ts`. Do not hoist them into named constants or a `*.data.ts`, even when the same number is repeated in that component's JSX and its styles.

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

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

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

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

package/presets/opencode/next/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/opencode/next/opencode.json

@@ -1,5 +1,24 @@
 {
   "$schema": "https://opencode.ai/config.json",
+  "instructions": [
+    ".opencode/AGENTS.md",
+    ".opencode/rules/next-app-core.md",
+    ".opencode/rules/package-manager.md",
+    ".opencode/rules/code-quality-and-refactoring.md",
+    ".opencode/rules/ai-local-overlay.md"
+  ],
+  "permission": {
+    "bash": {
+      "*": "allow",
+      "git commit *": "deny",
+      "git push *": "deny",
+      "npm *": "ask",
+      "npx *": "ask",
+      "pnpm *": "ask",
+      "bun *": "ask",
+      "npx jest*": "deny"
+    }
+  },
   "mcp": {
     "context7": {
       "type": "local",

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

@@ -4,8 +4,13 @@ Plain Markdown. OpenCode does **not** auto-load these files. Root `AGENTS.md`
 and `.opencode/AGENTS.md` list four essential paths to Read immediately; the
 rest are lazy-loaded when the task matches.
 
-Do not put this catalog into `opencode.json` `instructions` as the only
-always-on path (V2 may ignore that field).
+Subagent tasks (`Task`/`@name`) start blank and never read these rule files;
+the **authoritative** mechanism is the `## Rules to load (subagent context)`
+block injected into every `.opencode/agents/*.md`. The preset also adds a
+compact `opencode.json` `instructions` list (alwaysOn paths +
+`.opencode/AGENTS.md`) as a hedge for the parent context, with
+`bin/opencode-install.js` filling-if-absent on re-init; do **not** treat
+`instructions` as the only always-on path (V2 may ignore the field).
 
 ## Essential (entry-critical)
 

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.