omniconductor 0.3.0

package/core/recipes/README.md

@@ -0,0 +1,46 @@
+# `core/recipes/` — Project-specific opt-in patterns
+
+Per ADR-013, CONDUCTOR ships project-specific recipes as OPT-IN. They are not loaded by default. Adopters select the recipes that match their project and the adapter wires them into the appropriate native location.
+
+## The 11 recipes
+
+| File | When to install |
+|---|---|
+| `web-mobile-parity.md` | Project has both web and mobile surfaces sharing business logic |
+| `i18n.md` | Project supports multiple locales |
+| `monorepo.md` | Project uses npm workspaces (or equivalent) with shared packages |
+| `branch-strategy.md` | Project uses a 3-branch model (or wants the example pattern) |
+| `auto-mock-data.md` | Project has a database and wants seed data autogen on schema change |
+| `coding-conventions.md` | Project wants explicit naming / TS / error-handling conventions enforced |
+| `tdd.md` | Project has a test framework and wants Red-Green-Refactor methodology enforced across feature work and bug fixes |
+| `debugging.md` | Any project — enforces root-cause-first investigation before any fix is attempted |
+| `database-discipline.md` | Project has a relational store with migrations + dev/prod split. Ships 2 recipe-scoped hookify rules (SQL access-control + SECURITY DEFINER search_path) — see ADR-028 |
+| `design-system.md` | Project maintains a design-token system (color/spacing/typography tokens). Ships 1 recipe-scoped hookify rule (raw-hex-instead-of-token) — see ADR-028 |
+| `self-improvement.md` | Project wants a periodic, human-approved Reflector that distils session lessons into memory/rules. Propose-only; nothing auto-applies. Drives the `reflector` role — see ADR-030 |
+
+## Selection patterns
+
+| Project type | Recommended recipes |
+|---|---|
+| Solo SaaS, web-only, single-locale | `coding-conventions` + `tdd` + `debugging` |
+| SaaS with mobile companion | `web-mobile-parity` + `coding-conventions` + `tdd` + `debugging` |
+| Multi-locale SaaS | `i18n` + `coding-conventions` + `tdd` + `debugging` |
+| Relational-DB-backed SaaS (migrations + dev/prod) | `database-discipline` + `coding-conventions` + `tdd` + `debugging` |
+| Token-driven design system (theming / dark-mode) | `design-system` + `coding-conventions` + `tdd` + `debugging` |
+| Full-stack SaaS with web + mobile + i18n | All 11 |
+| Greenfield experiment | None — universal-rules + roles only is enough |
+
+## How adapters consume these files
+
+Adapter `transform.sh` accepts a `--recipes=<comma-separated-list>` flag (or per-tool equivalent). Selected recipes are written to:
+
+| Adapter | Output path |
+|---|---|
+| Claude | `.claude/rules/<recipe>.md` (with `paths:` frontmatter where the recipe ships its own path scope) |
+| Cursor | `.cursor/rules/<recipe>.mdc` |
+| Copilot | `.github/instructions/<recipe>.instructions.md` |
+| Gemini | Section in `GEMINI.md` |
+| Codex | Section in `.codex/codex.md` |
+| Windsurf | `.windsurf/rules/<recipe>.md` |
+
+Recipes are layered on TOP of universal-rules. They never override; they extend.

package/core/recipes/auto-mock-data.md

@@ -0,0 +1,82 @@
+---
+recipe_id: auto-mock-data
+recipe_name: "Auto-generate mock seed data on schema change"
+applies_when: "project has a relational database and wants seed data autogen"
+severity: STRONG (when installed)
+linked_rules:
+  - spec-as-you-go
+---
+
+# Recipe — Auto Mock Data
+
+> Opt-in recipe. Install when the project has a relational database (Postgres, MySQL, SQLite, etc.) and wants seed data automatically generated whenever the schema changes. Do NOT install on document-store-only projects.
+
+## 1. The rule
+
+Whenever a database table is created, modified, or removed, the corresponding mock seed SQL (or seed script) MUST be generated or updated in the SAME turn as the schema change.
+
+### 1.1 Why same-turn
+
+The orchestrator that just finished the migration has the table's column types, constraints, and example values fresh in mind. By the next session, that context is gone. Seed data generated later is generic and misses the realistic data shapes that the migration was actually for.
+
+### 1.2 What "mock seed" means
+
+- A SQL file (or seed script) that inserts representative rows for the new / changed table.
+- "Representative" = covers the access patterns the application code will use:
+  - Edge cases (null values where allowed, empty strings, max-length strings).
+  - Realistic values (not "lorem ipsum" — actual data shapes the dev / staging environment needs).
+  - Foreign-key relationships intact (seed parent rows before child rows).
+
+## 2. File organization
+
+```
+db/
+├── migrations/
+│   ├── 20260506_add_foo_table.sql
+│   └── 20260507_alter_bar_column.sql
+├── seeds/
+│   ├── foo.seed.sql
+│   └── bar.seed.sql
+└── README.md
+```
+
+Or whatever convention the project's ORM / migration tool prefers. The recipe is "seed updates land alongside schema updates", not a specific tool.
+
+## 3. The "no manual ask" sub-rule
+
+The orchestrator does NOT ask "should I add seed data?" after a migration. Seed data is a default deliverable of any schema change. The dispatch brief for a database change MUST include "and update seed data" without the user requesting it.
+
+This is the recipe's central discipline: seed data autogen is automatic, not opt-in per change.
+
+## 4. Seed quality requirements
+
+| Requirement | Why |
+|---|---|
+| At least 3 rows per new table | Single-row seeds don't exercise list / pagination paths |
+| Foreign keys intact | Broken references defeat the seed |
+| Mix of edge cases (nulls, empty strings, max lengths) | Catches column constraint mistakes |
+| Realistic values (not placeholder "test1", "test2") | Dev environment should look like prod, just smaller |
+| Idempotent inserts (`INSERT ... ON CONFLICT DO NOTHING` or equivalent) | Safe to re-run during dev environment resets |
+
+## 5. When schema is removed
+
+When a table or column is dropped:
+
+- Remove the corresponding seed entries.
+- Remove dependent seeds in other tables (foreign-key cleanup).
+- Document the removal in the migration's commit message.
+
+## 6. Production case
+
+Documented case: a new table was added without seed updates. The dev environment had the table empty. UI code that read the table with an `expects-non-empty` assumption crashed when developers tried to render the new feature locally. The seed update would have caught this immediately.
+
+## 7. Cross-tool enforcement
+
+| Mechanism | Where |
+|---|---|
+| Spec-as-you-go (universal) | Same-turn doc + seed update enforced by `spec-as-you-go.md` |
+| Migration script template | Project's migration tool template includes a "seed updated?" checkbox in commit message |
+| Pre-commit review (Q1) | Reviewer checklist: "DB schema changed → seed updated?" |
+| Rule text | This recipe loaded into the tool's rule context |
+
+The recipe does not add a new automated check; it adds a discipline that the existing checks (spec-as-you-go, Q1) catch when followed.

package/core/recipes/branch-strategy.md

@@ -0,0 +1,100 @@
+---
+recipe_id: branch-strategy
+recipe_name: "3-branch deploy model (main / develop / release)"
+applies_when: "project wants a 3-branch deploy model with auto-deploy environments"
+severity: STRONG (when installed)
+linked_rules:
+  - operations
+  - quality-gates
+---
+
+# Recipe — Branch Strategy (3-branch model)
+
+> Opt-in recipe. Install when the project wants a 3-branch model (or the example pattern). Adopters with their own strategy (trunk-based, GitFlow, etc.) ignore this recipe; the universal `operations.md` rules still apply.
+
+## 1. Branch roles
+
+| Branch | Role | Auto-deploys to |
+|---|---|---|
+| `main` | Source of truth — last successful release snapshot. NO auto-deploy. | None |
+| `develop` | Integration / dev environment. Auto-deploy. | dev environment (e.g., `<project>-dev` on your hosting provider + dev DB) |
+| `release` | Pre-prod / staging. Auto-deploy. | prod environment (e.g., `<project>-prod` on your hosting provider + prod DB) |
+
+The originating project uses this model; the names (`main` / `develop` / `release`) are the reference. Adopters with `main` / `staging` / `production` semantics map equivalently.
+
+## 2. New work flow
+
+```
+main → branch off → feature/<name> (or fix/<name>, chore/<name>)
+     → PR to develop → CI green + review → merge develop
+     → PR to release → prod verification → merge release
+     → PR release → main → merge main
+```
+
+Each step has a quality gate:
+
+| Step | Gate |
+|---|---|
+| `feature/*` → `develop` PR | Q1 pre-commit + Q2 pre-merge + CI green |
+| `develop` → `release` PR | dev verification confirmed + Q2 |
+| `release` → `main` PR | prod verification confirmed (smoke tests) |
+
+## 3. Hotfix flow
+
+```
+main → branch off → hotfix/<name>
+     → PR to release → emergency review → merge
+     → cherry-pick to develop (sync)
+     → PR release → main
+```
+
+Hotfixes skip the develop integration step because the urgency demands it. The cherry-pick to develop ensures the fix is not lost when develop next merges into release.
+
+## 4. Push policy
+
+| Branch | Direct push | PR required | Force push |
+|---|---|---|---|
+| `main` | FORBIDDEN | Required | FORBIDDEN |
+| `release` | FORBIDDEN | Required | FORBIDDEN |
+| `develop` | Allowed for orchestrator (with review) | Strongly preferred | FORBIDDEN |
+| `feature/*`, `fix/*`, `chore/*`, `hotfix/*` | Allowed | Required to land | Allowed locally |
+
+GitHub branch protection (or equivalent) enforces the FORBIDDEN rows. Force push is FORBIDDEN on every protected branch — even by admins, without a documented exception.
+
+## 5. PR review (Q2 cross-link)
+
+Every code PR to `develop`, `release`, or `main` requires Q2 pre-merge code review per `quality-gates.md`. Docs-only PRs are exempt.
+
+The orchestrator runs the slash command (Claude Code) or its equivalent on PR open. The Stop-hook (Claude Code) reminds if the orchestrator forgets.
+
+## 6. Push timing
+
+> Adopters CHOOSE this convention. It is not universal.
+
+The originating project's push timing convention:
+
+- Code commits: push immediately (CI runs, deploy triggers).
+- Docs-only commits: do NOT push immediately. Batch with the next code push.
+
+### 6.1 Why batch docs
+
+Each push triggers a deploy pipeline. Docs-only pushes consume deploy budget without changing what runs in production. On platforms with deploy quotas (many hosting providers cap free-tier deploys per day), batching docs-only pushes is non-trivial savings.
+
+### 6.2 Exceptions to batch
+
+- Time-critical doc updates (a public-facing doc page must update now).
+- Docs that gate other work (CURRENT_WORK.md mid-day update so another session can resume).
+
+## 7. Cross-tool enforcement
+
+| Mechanism | Where |
+|---|---|
+| Direct-push prevention on protected branches | GitHub branch protection (or platform equivalent) |
+| Force-push prevention on protected branches | Branch protection |
+| PR review required | Branch protection (require approving review) |
+| CI green required | Branch protection (require status checks) |
+| Push timing convention | Rule text + orchestrator self-discipline |
+
+## 8. Connection to `operations.md` (universal)
+
+The universal operations rule (`P3` dev/prod sync) assumes a branch model exists. This recipe provides one example. Adopters with different conventions still satisfy P3 by ensuring env-var / migration / external-service parity at deploy time, regardless of branch names.

package/core/recipes/coding-conventions.md

@@ -0,0 +1,123 @@
+---
+recipe_id: coding-conventions
+recipe_name: "TypeScript-first coding conventions"
+applies_when: "TypeScript / TSX project that wants explicit naming + error-handling + type-safety conventions"
+severity: STRONG (when installed)
+linked_rules:
+  - quality-gates
+---
+
+# Recipe — Coding Conventions
+
+> Opt-in recipe. Install on TypeScript / TSX projects that want explicit naming, error-handling, and type-safety conventions. Adopters in other languages (Go, Rust, Python) skip this recipe and write their own.
+
+## 1. Naming
+
+| Kind | Convention | Example |
+|---|---|---|
+| Components / Types / Interfaces | PascalCase | `AccountCard.tsx`, `interface Account` |
+| Files (non-component) | camelCase | `accounts.ts` |
+| Functions / Variables | camelCase | `getAccounts()`, `accountId` |
+| Constants | UPPER_SNAKE_CASE | `MAX_POINTS` |
+| Folders | kebab-case | `lib/db-client/` |
+| Booleans | `is` / `has` prefix | `isLoading`, `hasError` |
+| Event handlers | `on` prefix | `onClick`, `onSubmit` |
+
+## 2. TypeScript
+
+- Always `.ts` / `.tsx`. Never `.js` / `.jsx` in source.
+- Explicit types on EVERY function parameter and return value. No "rely on inference for top-level signatures".
+- The `any` type is FORBIDDEN. When the type is genuinely unknown, use `unknown` and narrow.
+- Shared types live in the project's shared package (`packages/shared` or equivalent) when consumed by multiple apps; otherwise in a local `types/` directory.
+- `as` casts are last-resort. Prefer type guards.
+
+## 3. Error handling — Result pattern
+
+Service functions return a Result tuple, not throw exceptions:
+
+```typescript
+type Result<T> = { data: T; error: null } | { data: null; error: string };
+
+async function getAccounts(userId: string): Promise<Result<Account[]>> {
+  const { data, error } = await db.from('accounts').select().eq('user_id', userId);
+  if (error) {
+    logError(error, { context: 'getAccounts', userId });
+    return { data: null, error: error.message };
+  }
+  return { data, error: null };
+}
+```
+
+### 3.1 Why Result-pattern (not exceptions)
+
+- Forces the caller to handle the error case at the call site.
+- Type system surfaces the error path in the function signature.
+- Avoids "try/catch the world" patterns that swallow errors.
+- Stack traces are not the primary error-comm channel; the structured error string is.
+
+### 3.2 The structured logger rule
+
+Always use the project's `logError()` (or equivalent structured-logging utility) — never raw `console.error`. Why:
+
+- `logError()` includes context (user id, request id, feature flag, environment).
+- `logError()` ships to the project's observability platform (your error-aggregation service of choice).
+- Raw `console.error` gets lost in serverless function logs and produces no alert.
+
+## 4. Error UX patterns
+
+| Surface | Pattern |
+|---|---|
+| Page-level fatal error (load failed) | Project's error-banner component (e.g., `ErrorBanner`) |
+| Action feedback (save success, validation error) | Project's toast utility (e.g., `toast.success()` / `toast.error()`) |
+| Form field error | Inline error message under field |
+| API response | Result-pattern JSON: `{ data, error }` |
+
+User-facing error messages MUST be translated (i18n key, not raw error string from the service). The raw error goes to the logger; the translated message goes to the UI.
+
+## 5. Forbidden
+
+- Hardcoded secrets / API keys / tokens — load from environment at runtime.
+- Service-role / admin keys in client code — server-side only.
+- Untyped escape hatches (`any`, `as unknown as Foo`).
+- UI libraries beyond the project's approved set (the rule index lists them — typically a single primary library).
+- Hardcoded user-facing strings on multi-locale projects (use translation keys — see `recipes/i18n.md`).
+- Duplicated business logic between apps in a monorepo (it goes in shared — see `recipes/monorepo.md`).
+
+## 6. Folder conventions (TypeScript app)
+
+```
+apps/<app>/
+├── app/                ← Next.js app router (or equivalent framework structure)
+├── components/         ← Reusable UI components
+│   ├── common/         ← Cross-feature primitives (ErrorBanner, etc.)
+│   └── <feature>/      ← Feature-scoped components
+├── lib/
+│   ├── i18n/           ← Translation hook + per-app local copy
+│   └── utils/          ← Pure utilities (errorLogger, formatters, etc.)
+├── services/           ← Service-layer functions (Result pattern)
+└── types/              ← Local types (not consumed by other apps)
+```
+
+The recipe is the rule; the project's framework dictates the actual structure.
+
+## 7. Test discipline
+
+| Test type | Location | When required |
+|---|---|---|
+| Unit | `<file>.test.ts` co-located | New service function, new utility |
+| E2E functional | `apps/<app>/e2e/functional/` | New page / flow / API endpoint |
+| Visual smoke | `apps/<app>/e2e/visual/` | New page / screen |
+| Snapshot | `<feature>/__tests__/` | New email template, new render-only artifact |
+
+The full test sync rule is in `quality-gates.md` Q3. This recipe enumerates the test types specifically for the TypeScript stack.
+
+## 8. Cross-tool enforcement
+
+| Mechanism | Where |
+|---|---|
+| TypeScript strict mode | `tsconfig.json` `"strict": true` |
+| `any` ban | ESLint rule (`@typescript-eslint/no-explicit-any`) |
+| Naming conventions | ESLint rule (`@typescript-eslint/naming-convention`) |
+| Result pattern | Reviewer checklist + `coding-conventions` rule loaded into tool context |
+| Hardcoded string ban | ESLint custom rule (when present) + reviewer checklist |
+| `console.error` ban | ESLint rule + reviewer checklist |

package/core/recipes/database-discipline.md

@@ -0,0 +1,65 @@
+---
+recipe_id: database-discipline
+recipe_name: "Relational DB discipline — access control, idempotent migrations, drift safety"
+applies_when: "Project has a relational store with migrations and an environment split (dev/prod)"
+severity: STRONG (when installed)
+linked_rules:
+  - quality-gates
+ships_hookify:
+  - warn-create-table-without-access-control
+  - warn-security-definer-without-search-path
+---
+
+# Recipe — Database Discipline
+
+> Opt-in recipe. Install on projects backed by a relational store that uses migrations and runs a dev/prod environment split. It encodes four disciplines that prevent the most common (and highest-severity) data-layer failures: missing access control, non-idempotent migrations, brittle seeds, and silent production drift. Projects without a relational store skip this recipe.
+
+## 1. Access control on every table
+
+Every table enables row-level (or equivalent) access control. Access without an explicit policy is a security hole, not a convenience.
+
+- Enable row-level access control on the table at creation time — never as a follow-up "we'll add it later" step.
+- Every policy names the allowed role explicitly. A policy with no role, or a permissive / PUBLIC default, grants access to everyone.
+- No table ships with a permissive default. If a row should be readable by a tier, name that tier in the policy.
+- Read-only reference tables (lookup tables, enums-as-rows) may scope SELECT broadly, but they still enable access control — broad SELECT is a deliberate policy, not an absence of one.
+
+## 2. Idempotent migrations
+
+A migration must be safe to re-run. Re-application happens routinely — replays, partial failures, parallel environments — and a non-idempotent migration turns a retry into an outage.
+
+- Create with guards: `CREATE … IF NOT EXISTS`.
+- Alter with guards: `ADD COLUMN IF NOT EXISTS`, and equivalent existence checks for indexes / constraints.
+- Insert with conflict handling: `ON CONFLICT DO NOTHING` (or an explicit upsert) for seed / lookup rows.
+- Guard any data backfill so a second run is a no-op.
+
+If running the migration twice would fail or double-write, it is not idempotent — fix it before it ships.
+
+## 3. Seed by name-lookup, not hardcoded ID
+
+Foreign-key seeds resolve their target by a stable natural key (a name, a slug, a code), never a literal ID.
+
+- IDs differ across environments — an auto-generated primary key in dev is not the same value in prod. A hardcoded ID silently points at the wrong row (or nothing) in another environment.
+- Resolve the target row by its natural key at seed time, then use the resolved ID. The natural key is the stable contract across environments; the ID is not.
+- This keeps the same seed script correct in dev, staging, and prod without per-environment edits.
+
+## 4. Pre-apply drift verification
+
+Before applying a dev-verified schema or data change to production, verify that production's current state still matches the baseline the change was built against. Production drifts (hotfixes, manual edits, concurrent writes); applying a change blind can overwrite that drift.
+
+- Re-query production's pre-state for the affected range (the rows / schema the change touches) immediately before applying.
+- Diff it against the dev baseline: row count, the set of keys, and the pre-state values.
+- On any drift → abort and surface the difference. Never overwrite a drifted production silently.
+- Apply only when parity holds. After applying, verify the post-state matches the intended result.
+
+The discipline is: dev verifies the change is correct; the pre-apply diff verifies production is still the world the change expects.
+
+## 5. Shipped hookify (Claude adapter)
+
+The Claude adapter ships two recipe-scoped hookify rules that install **only when this recipe is selected** (`--recipes=database-discipline`):
+
+| Rule | Event | Action | Catches |
+|---|---|---|---|
+| `warn-create-table-without-access-control` | file | warn | A `CREATE TABLE` in a `.sql` file with no row-level access control enabled in the same change (section 1) |
+| `warn-security-definer-without-search-path` | file | warn | A `SECURITY DEFINER` function with no explicit `SET search_path`, leaving it open to schema-shadowing privilege hijack |
+
+These are stack-shaped (SQL-specific), so they are gated behind this recipe rather than shipped always-on. See the CONDUCTOR repo's `adapters/claude/hookify-templates/.recipe-scoped` and `docs/DESIGN-DECISIONS.md` ADR-028.

package/core/recipes/debugging.md

@@ -0,0 +1,143 @@
+---
+recipe_id: debugging
+recipe_name: "Systematic Debugging (Root-Cause-First)"
+applies_when: "any bug, test failure, unexpected behavior, or production incident — whenever the temptation to 'just try something' arises"
+severity: STRONG (when installed)
+linked_rules:
+  - meta-discipline
+  - spec-as-you-go
+---
+
+# Recipe — Systematic Debugging
+
+> Opt-in recipe. Install on any project where bugs are a reality (i.e., all of them). Especially valuable on codebases where time pressure makes guess-and-check feel faster — it isn't.
+
+## When to Apply
+
+Any technical issue where behavior diverges from expectation:
+
+- Test failures (unit, integration, E2E)
+- Production bugs
+- Unexpected output or side effects
+- Build or compilation failures
+- Performance regressions
+- Integration failures between services
+
+**Apply especially when:**
+
+- Under time pressure — urgency makes guessing tempting, which is when it causes the most damage
+- "One quick fix" seems obvious — obvious fixes treat symptoms
+- You have already tried at least one fix — if the first fix failed, the root cause is not what you thought
+- You do not fully understand why the issue occurs
+
+## Pattern — Four Phases
+
+Phases are sequential. Do not advance to the next phase until the current phase is complete.
+
+### Phase 1 — Reproduce
+
+Establish a deterministic, minimal reproduction. A bug you cannot reproduce consistently cannot be verified as fixed.
+
+Steps:
+1. Read the full error message and stack trace — they frequently contain the exact file, line, and cause
+2. Write down the exact steps that trigger the issue
+3. Confirm the issue occurs every time those steps are followed
+4. If not reproducible: add logging at component boundaries to gather evidence before continuing
+
+For multi-component systems (API → service → database, CI → build → signing), add boundary logging at each layer before forming any hypothesis:
+
+```bash
+# Example: trace where in a pipeline a value goes wrong
+echo "=== component A output: ${VALUE:+SET}${VALUE:-UNSET} ==="
+# ... run the pipeline ...
+echo "=== component B received: $RECEIVED ==="
+```
+
+Run once to gather evidence. Identify which layer breaks. Then investigate that specific layer.
+
+### Phase 2 — Isolate
+
+Narrow the search space before forming a hypothesis.
+
+Steps:
+1. Find working code similar to the broken code in the same codebase
+2. Compare working vs. broken — list every difference, however small
+3. Check recent changes: `git log --oneline -20`, `git diff HEAD~5`
+4. Identify what changed that could cause this (new dependency, config change, environment difference)
+5. Use `git bisect` for regressions that appeared between two known-good commits
+
+```bash
+# Binary search for the commit that introduced a regression
+git bisect start
+git bisect bad HEAD
+git bisect good <last-known-good-commit>
+# git bisect will check out commits; run your test and mark good/bad
+git bisect run npx vitest run path/to/failing.test.ts
+```
+
+### Phase 3 — Hypothesize and Verify
+
+Form one specific hypothesis. Test it minimally.
+
+1. Write down: "I believe X is the root cause because Y"
+2. Make the smallest possible change that would confirm or refute this hypothesis
+3. Run the test — did it work?
+   - Yes → proceed to Phase 4
+   - No → form a NEW hypothesis; do NOT layer additional changes on top of the failed one
+4. If you genuinely do not know: say so, add more logging, return to Phase 1 with new evidence
+
+One variable at a time. Multiple simultaneous changes make it impossible to know which change fixed (or broke) something.
+
+### Phase 4 — Fix and Regression-Test
+
+Fix only the confirmed root cause. Then lock it in with a test.
+
+1. Write a failing test that reproduces the bug (apply `core/recipes/tdd.md`)
+2. Implement the minimal fix
+3. Confirm the test passes
+4. Run the full suite — confirm no regression introduced
+5. If the fix does not work: return to Phase 1 with new evidence
+
+**If three or more fixes have failed:** stop attempting fixes. The root cause may be architectural — a coupling or shared-state assumption that no local fix can address. Discuss with your team before attempting another fix.
+
+After a confirmed fix, update the relevant spec or known-issues section (spec-as-you-go). Bugs that recur after being fixed typically had no regression test and no spec update.
+
+## Tool Reference
+
+| Tool | Use |
+|---|---|
+| `git bisect` | Binary-search commits to find regression introduction point |
+| `git stash` | Temporarily remove local changes to verify they are or are not the cause |
+| `git diff HEAD~N` | See what changed in the last N commits |
+| Structured logging | Add `console.log` / logger at component boundaries during Phase 1; remove before commit |
+| Debugger / breakpoints | Confirm data values at specific points in the call stack |
+| Minimal reproduction test | Isolate the failing behavior in the smallest possible test case |
+
+## Conductor Integration
+
+**meta-discipline (M1 — verify before claim)**: A fix is not complete until the test passes and the full suite is green. Do not report "fixed" before verifying.
+
+**spec-as-you-go (W3)**: Bug fixes update the spec. If the bug was a known edge case not previously documented, add it to the spec's known-issues section. If the fix changes behavior, update the relevant spec section.
+
+**workflow.md W2 (build phase)**: When a build-phase failure occurs, invoke this recipe before proposing any code change. The recipe gates Phase 4 on Phases 1-3 being complete.
+
+**tdd.md**: Phase 4 of this recipe directly invokes the TDD cycle — write the failing test first, then fix. The two recipes are complementary: TDD prevents bugs; this recipe resolves them when they occur anyway.
+
+## Anti-Patterns
+
+| Anti-pattern | Why it fails |
+|---|---|
+| "Just try X and see if it works" | Sets a guess-and-check precedent. First guess being right is luck; subsequent guesses are compounding debt. |
+| Suppress the error with try/catch | Treats the symptom. The root cause continues to fire; you just stopped hearing about it. |
+| Multiple simultaneous fixes | If the bug disappears, you cannot know which fix resolved it. If it persists, you have added noise. |
+| Asking an LLM before gathering evidence | Without a minimal reproduction and specific error output, LLM responses are pattern-matched hallucinations, not diagnosis. |
+| Time-pressure skip of Phase 1-2 | Systematic debugging is faster than guess-and-check. Urgency is when discipline matters most, not when to abandon it. |
+| Fix without a regression test | The bug will recur. A fix with no test is a temporary suppression. |
+| "One more fix attempt" after two failures | Three failures indicate the hypothesis model is wrong, not that a better fix exists within the same model. |
+
+## Cross-References
+
+- `core/universal-rules/meta-discipline.md` — M1 verify before claim: fix is not done until verified
+- `core/universal-rules/spec-as-you-go.md` — bug fixes update specs and known-issues sections
+- `core/recipes/tdd.md` — Phase 4 creates the failing test; TDD cycle drives the fix
+- Root-cause-first / four-phase debugging is long-standing public practice; this recipe is independently written. Its structure was informed in part by the **Superpowers** project (idea-level; no text reproduced) — see `THIRD_PARTY_NOTICES.md`.

package/core/recipes/design-system.md

@@ -0,0 +1,30 @@
+---
+recipe_id: design-system
+recipe_name: "Design-token discipline"
+applies_when: "Project has a design-token system (color/spacing/typography tokens)"
+severity: STRONG (when installed)
+ships_hookify:
+  - warn-raw-hex-instead-of-token
+---
+
+# Recipe — Design-Token Discipline
+
+> Opt-in recipe. Install on projects that maintain a design-token system (color / spacing / typography tokens). Projects with no token system skip this recipe.
+
+## 1. Tokens, not literals
+
+Component styling references design tokens (color / spacing / typography), never raw hex colors or magic pixel values. A raw literal defeats theming: it cannot follow a dark-mode switch, a brand re-skin, or a density change, and it silently drifts from the rest of the system. Every visual value a component renders should resolve through a named token, so a single token edit propagates everywhere consistently.
+
+## 2. Out of scope for this recipe
+
+Which UI library, which icon pack, and which specific token names a project uses are **project-local** decisions, not framework policy (ADR-018). CONDUCTOR does not ship a banlist of libraries or a fixed set of token names — those belong in the adopter project. This recipe enforces only the *principle*: a token over a literal. The adopter supplies the concrete token vocabulary; the recipe supplies the discipline.
+
+## 3. Shipped hookify
+
+This recipe ships one recipe-scoped hookify rule, emitted only when `design-system` is selected via `--recipes`:
+
+| Template | Event | Action | Trigger |
+|---|---|---|---|
+| `warn-raw-hex-instead-of-token` | file | warn | An inline raw hex color (`#rrggbb`) added to a `.tsx` / `.jsx` / `.css` / `.scss` file |
+
+The rule warns (it never blocks): an intentional one-off outside the token system stays possible, but the author is prompted to justify it rather than drift by accident.