omniconductor 0.3.0

package/core/universal-rules/meta-discipline.md

@@ -0,0 +1,292 @@
+---
+rule_id: meta-discipline
+rule_name: "Originality, ambiguity handling, never-skip, token economy, model routing"
+severity: ABSOLUTE
+applies_to: ["all-tools"]
+violation_count: 8+
+enforcement:
+  - hook: pretool-agent-routing
+  - llm-self-discipline
+linked_rules:
+  - workflow
+  - quality-gates
+  - operations
+---
+
+# Meta-Discipline — How CONDUCTOR Stays CONDUCTOR
+
+> Bundles M1 (framework originality), M2 (token economy reference), M3 (model routing reference), M5 (ABSOLUTE rules never skip — cross-link), and the ambiguity policy (ACT-WITH-DECLARATION default + AMB-1..7 triggers).
+
+## 1. Process Over Speed (W5 cross-link)
+
+User shortcut phrases never grant permission to skip workflow steps. See `workflow.md` section 4 for the full rule. This file restates it because process-over-speed is the meta-rule that protects every other rule.
+
+---
+
+## 2. Framework Originality (M1)
+
+CONDUCTOR core assets MUST NOT borrow names, terminology, or structural conventions from other agent frameworks. The originating project records this as an explicit ABSOLUTE rule:
+
+> "Looks similar in concept" is fine. "Took mine" is not.
+
+In practice, this means:
+
+- Do NOT use external framework names (the names of competing or inspirational multi-agent / agent-CLI frameworks) anywhere in `core/`, `roles/`, `recipes/`, or `hooks/`.
+- Do NOT copy directory structures from external frameworks (e.g., a `crews/` folder borrowed from a known framework).
+- Do NOT use external framework's role vocabulary verbatim (e.g., specific agent role names that are trademarked patterns of other tools).
+- DO compare and reference external frameworks in design documents (`docs/`) where the comparison is the point — but those references stay out of universal rule bodies.
+
+### 2.1 Why
+
+The user's framework is their craft. Borrowing names dilutes provenance and creates licensing / attribution ambiguity. CONDUCTOR pays in invented terminology so adopters get a clean, self-contained vocabulary.
+
+### 2.2 CONDUCTOR's own vocabulary (use these)
+
+- **orchestrator** — the user-facing leader thread.
+- **role** — a specialized sub-task profile (planner / builder / reviewer / helper / designer / scribe).
+- **dispatch** — the act of delegating a task to a role.
+- **dispatch brief** — the ≤2K-token instruction object passed at dispatch.
+- **stop condition** — explicit done-criteria for a dispatched task.
+- **flat-with-leader** — orchestration topology where roles never dispatch each other; only the orchestrator dispatches.
+- **Single-Agent Mode** — fallback for tools without native sub-agent support; orchestrator + helper collapse into one thread.
+- **AMB triggers** — the 7-item ambiguity catalog that forces ASK behavior.
+- **ACT-WITH-DECLARATION** — proceed-with-best-guess + surface the assumption.
+- **universal rule** vs **recipe** — universal rules apply to every adopter; recipes are opt-in.
+
+### 2.3 Verification
+
+Originality is verified by grep at every CONDUCTOR commit:
+
+```bash
+# Run from conductor repo root.
+# Should return zero matches inside core/, roles/, recipes/, hooks/.
+grep -RIE 'MetaGPT|AutoGen|CrewAI|LangGraph|ChatDev|Aider|Cursor|Continue|Cline|SWE-agent' core/ roles/ recipes/ hooks/
+```
+
+References to these names live ONLY in the CONDUCTOR repo's `docs/CONDUCTOR-V0.2-DESIGN.md` and `docs/DESIGN-DECISIONS.md` where comparison is the point.
+
+---
+
+## 3. Ambiguity Handling — ACT-WITH-DECLARATION default + AMB triggers force ASK
+
+### 3.1 Default behavior
+
+Unless an AMB trigger fires, the orchestrator proceeds with best-guess interpretation AND surfaces the assumption in the response prefix:
+
+```
+Assumption: I'm interpreting "footer cleanup" as web only (<web-app>/...).
+Plan: ...
+```
+
+This format gives the user a one-glance catch — they can correct in a single follow-up turn before any cost is sunk.
+
+### 3.2 AMB triggers — when to switch to ASK
+
+If ANY of the following fire, the orchestrator MUST switch from ACT-WITH-DECLARATION to ASK:
+
+| Trigger ID | Pattern | Example | Required action |
+|---|---|---|---|
+| AMB-1 | Deictic references — "this", "like before", "similar to that one" | "this needs to be cleaner" | ASK + present 3 candidate referents as multiple-choice |
+| AMB-2 | Unspecified scope — single vs all, web vs mobile, dev vs prod | "fix the footer" | ASK + (web only / mobile only / both) |
+| AMB-3 | External system invocation that is non-trivially reversible | DB migration, payment ops, mass email | ASK once: "dev only / prod only / both?" |
+| AMB-4 | Merge or push to a protected branch | `gh pr merge`, `git push origin main` | ASK + explicit confirmation required |
+| AMB-5 | Design decisions (color, layout, copy tone) | "make this button more modern" | ASK + 2-3 visual / copy alternatives |
+| AMB-6 | Library or dependency addition | "add an image cropper" | ASK + 3 candidates + trade-off table |
+| AMB-7 | User manual action required (env vars, dashboard config) | "you need to set up the webhook" | ASK + numbered steps + wait for user confirmation |
+
+### 3.3 ASK template (multiple-choice)
+
+When ASK fires, the orchestrator uses this template — NOT open-ended questions:
+
+```markdown
+**Situation**: <one-sentence ambiguity summary>
+
+**Option A**: <action A> — Trade-off: <pros / cons>
+**Option B**: <action B> — Trade-off: <pros / cons>
+**Option C**: <action C> — Trade-off: <pros / cons>
+**Other**: free-form one-line response if A/B/C don't fit
+
+**Recommended default**: <A | B | C> — reason: <one-line>
+```
+
+### 3.4 Why multiple-choice
+
+- User cognitive load drops: 5-second decision vs 30+-second free response.
+- Trade-offs are pre-analyzed, raising decision quality.
+- Fewer follow-up turns (the orchestrator already considered the obvious alternatives).
+
+### 3.5 The "verify before recommending" sub-rule
+
+When ASK fires for AMB-6 (dependency) or AMB-5 (design), the orchestrator MUST verify each candidate before recommending:
+
+- Library candidates: confirm name + maintenance status + license.
+- Design candidates: render or describe each visually.
+
+A recommendation without verification = an opinion, not a recommendation. Mark it as such if you can't verify.
+
+---
+
+## 4. ABSOLUTE Rules Never Skip (W6 cross-link)
+
+No user instruction grants exemption from rules marked `severity: ABSOLUTE`. See `workflow.md` section 5 for the full rule. The orchestrator that catches itself about to skip MUST surface the violation explicitly (R5 surface obligation).
+
+This rule is restated here because meta-discipline is the file most adopters read first when porting CONDUCTOR to a new tool — and ABSOLUTE-never-skip is the single most-violated rule in production history.
+
+---
+
+## 5. Token Economy (M2)
+
+> Goal: minimize wasted context. Applies to orchestrator and every role.
+
+### 5.1 Read discipline (large files)
+
+- **Check size first** before opening. Use `wc -l` or grep with line numbers.
+- **Prefer Grep over Read** for symbol lookup. Use `-A` / `-B` context. Read only when 50+ contiguous lines are needed.
+- **Range reads (offset / limit) are mandatory** for files > 200 lines. Default `limit: 100`; expand only if proven necessary.
+- **Never `cat` a whole rules file or large spec.** Grep for the section first, then range-read.
+
+### 5.2 Hidden injection awareness
+
+Some tools auto-inject skill / library docs when certain file paths are touched. These injections add hidden tokens (often 200-600 per Read). Be deliberate:
+
+- Skip auto-inject when Grep is sufficient.
+- When a Read is unavoidable, batch related Reads in a single response so cache reuses the prefix.
+
+### 5.3 Sub-agent dispatch discipline
+
+- Cap dispatch briefs at ~2K tokens. Reference files by path; do not paste content.
+- Tell the dispatched role the EXACT files to read. Don't make the role grep blindly.
+- Specify background execution for any task expected to take > 2 minutes wall-clock.
+
+### 5.4 Cache-friendly prompt order (Claude adapter)
+
+When prompt caching is available (Claude / Anthropic SDK):
+
+```
+[Cache prefix — low-frequency change]
+1. Universal rules (5 bundles)
+2. Project CLAUDE.md
+3. Selected recipes
+
+[cache_control: { type: "ephemeral" } boundary]
+
+[Per-turn — high-frequency change]
+4. Recent turn history
+5. Tool results
+6. User's new message
+```
+
+Full guide: the CONDUCTOR repo's `docs/PROMPT-CACHING-GUIDE.md` (not installed into your project).
+
+### 5.5 Tool description compression
+
+When > 30 tools are loaded, the description footprint becomes a measurable cost. Use deferred / lazy-loaded tool patterns where supported.
+
+### 5.6 Touched-file rule scoping
+
+Use `paths:` (Claude) / `globs:` (Cursor) / `applyTo:` (Copilot) to scope rule files to the source areas they govern. A rule that fires only when a relevant file is touched is cheaper than a rule loaded into every turn.
+
+### 5.7 Auto-compact threshold
+
+When the conversation context approaches the model's window cap, summarize older turns into a compact note and free the budget. Some tools auto-compact at ~80%; others rely on the orchestrator to trigger it.
+
+### 5.8 .ignorefile maintenance
+
+Each tool has its own ignore file (`.claudeignore`, `.cursorignore`, `.aiderignore`, etc.). Keep these in sync — they prevent expensive accidental Reads of build outputs, large lockfiles, or vendored code.
+
+---
+
+## 6. Model Routing (M3)
+
+The orchestrator classifies every task and selects model tier explicitly. The user does NOT specify the model per request — that responsibility belongs to the orchestrator.
+
+### 6.1 Tier 1 — Conceptual / complex (Opus-tier)
+
+Trigger if any of:
+
+- Design concept change ("revamp X", "new pattern", palette swap).
+- Architecture redesign or primitive redesign.
+- Multi-file migration (5+ files, cross-cutting).
+- Cross-platform parity work (web ↔ mobile, desktop ↔ web, etc.).
+- Multi-surface root-cause hunt.
+- System-level decision (data model, auth flow, billing logic).
+- Anti-pattern audit + refactor.
+- Documentation work that synthesizes multiple concerns.
+
+### 6.2 Tier 2 — Routine (Sonnet-tier, default for most work)
+
+- Single-file or single-component tweak.
+- New page using established shell.
+- Icon / copy / translation swap.
+- Minor responsive / padding fix.
+- Simple CRUD following established service-layer pattern.
+- Spec text update.
+- Translation key propagation across N locales (pattern established).
+
+### 6.3 Tier 3 — Trivial (Haiku-tier)
+
+- Read a file, return a specific value.
+- Rename a variable in 1 file.
+- Trivial text edits.
+
+### 6.4 Override rule of thumb
+
+> When in doubt, **upgrade one tier**. Cost difference is modest; risk of Sonnet misinterpreting conceptual work is large.
+
+### 6.5 Surface the choice
+
+When ambiguous, the orchestrator surfaces its model choice in the dispatch announcement:
+
+> "Dispatching to `builder` (Opus) — multi-file refactor across 5 components."
+
+This gives the user a chance to override before tokens are spent.
+
+### 6.6 Per-tool applicability
+
+| Tool | Model routing applies? |
+|---|---|
+| Claude Code | Yes (Agent tool's `model` parameter; PreToolUse hook validates explicit choice) |
+| Cursor | Yes (Composer model picker — orchestrator chooses by rule) |
+| Copilot | Limited (model selection is account-level, less per-task control) |
+| Gemini / Codex / Windsurf | Limited (single-model context typical) |
+
+On limited-routing tools, the orchestrator still classifies the task — even if it can't change the model — because the tier informs effort level (low / medium / high reasoning) and dispatch budget.
+
+---
+
+## 7. Orchestration Topology — Flat-with-Leader (M5)
+
+CONDUCTOR adopts a flat-with-leader topology:
+
+- The orchestrator (main thread) is the only user-facing leader.
+- All role agents are dispatched 1:1 by the orchestrator. They do NOT call each other.
+- A role agent that needs multi-step work returns intermediate results; the orchestrator decides the next dispatch.
+
+### 7.1 Why no nested dispatch
+
+- Solo dev mental model: one leader, several helpers.
+- Nested dispatch causes context to accumulate at every layer → token blow-up.
+- Production experience: nested dispatch attempts surfaced bugs faster than they delivered features.
+
+### 7.2 Enforcement
+
+On Claude Code, the `pretool-agent-routing` hook validates that:
+- `subagent_type` is one of the registered roles (not `general-purpose`).
+- `model` is explicitly set.
+- The dispatcher is the orchestrator (not another role).
+
+On other tools, the rule text serves as the constraint.
+
+---
+
+## 8. Cross-tool enforcement summary
+
+| Discipline | Claude Code | Cursor | Copilot | Gemini | Codex | Windsurf |
+|---|---|---|---|---|---|---|
+| Originality grep | Pre-commit script (orchestrator's responsibility) | Same | Same | Same | Same | Same |
+| AMB-1..7 trigger ASK | Rule text + LLM self-discipline | Same | Same | Same | Same | Same |
+| Token-economy Read discipline | Rule text + Stop-hook reminder when wasteful patterns spike | Rule text | Rule text | Rule text | Rule text | Rule text |
+| Model routing | PreToolUse hook validates explicit `model` | Composer picker manual | Account-level only | Single model | Single model | Single model |
+| Flat-with-leader | PreToolUse hook validates dispatcher | Single-Agent Mode (no sub-agents) | Same | Same | Same | Same |
+
+The honest summary: meta-discipline is enforced by rule text on every tool, with hook-based extras on Claude Code only.

package/core/universal-rules/operations.md

@@ -0,0 +1,162 @@
+---
+rule_id: operations
+rule_name: "Session continuity, completed-task delete, dev/prod sync"
+severity: ABSOLUTE
+applies_to: ["all-tools"]
+violation_count: 4+
+enforcement:
+  - hook: stop-session-log-check
+  - llm-self-discipline
+linked_rules:
+  - workflow
+  - spec-as-you-go
+---
+
+# Operations — Session Continuity + Sync Hygiene
+
+> Bundles O2 (session continuity / CURRENT_WORK first-read), O3 (completed-task delete), P3 (dev/prod sync). These rules govern how the project state is communicated across sessions and across environments.
+
+## 1. Session Continuity (O2)
+
+### 1.1 First-read on every session start
+
+The first file the orchestrator reads on every new session is `docs/CURRENT_WORK.md`. No exceptions. Even if the user's request is unrelated to active work, CURRENT_WORK.md is read first to establish context.
+
+### 1.2 Why
+
+CURRENT_WORK.md is the project's single source of "what is happening right now". Without it:
+- Orchestrator duplicates work that another session already finished.
+- Orchestrator pushes code that conflicts with in-progress work elsewhere.
+- The user re-explains everything every session.
+
+With it:
+- New session starts with full context in ~150 lines (the file's enforced size cap).
+- In-progress / blocked / done states are visible.
+- Next-step is explicit.
+
+### 1.3 What CURRENT_WORK.md contains
+
+Required sections (in order):
+
+1. **Current state** (date, phase, last commit hash, version).
+2. **Immediate next action** — what the next session should do.
+3. **In progress** — task list with owner + status + last update timestamp.
+4. **Recently completed** — last 3-5 deliverables (with commit refs). Older entries archive.
+5. **Known issues / blockers** — anything that prevents next-action.
+6. **Decision log** (optional) — recent ADR-style decisions for fast catch-up.
+
+### 1.4 Size cap and archive
+
+CURRENT_WORK.md MUST stay under 200 lines (target: 150). When it exceeds 200:
+
+- Archive the bottom half into `docs/sessions/<YYYY-MM-DD>.md`.
+- Leave only the most-recent 5-10 entries in CURRENT_WORK.md.
+- The session archive is a permanent reference but no longer auto-loaded.
+
+### 1.5 Stop-hook (Claude only)
+
+`stop-session-log-check` (installed by the Claude adapter) blocks session-end if:
+
+- Recent commits exist (≥ 1 in the last 30 minutes), AND
+- CURRENT_WORK.md was not modified in the last 30 minutes.
+
+The block emits a reason; orchestrator updates CURRENT_WORK.md and proceeds. On non-Claude tools, this rule's text serves as the reminder.
+
+---
+
+## 2. Completed-Task Delete (O3)
+
+When a task in CURRENT_WORK.md, REMAINING_TASKS.md, or TASKS.md transitions to `completed`, it MUST be removed from the active list within the next session boundary.
+
+### 2.1 What "next session boundary" means
+
+- If task completes mid-session: mark `completed` immediately, then DELETE before declaring the turn done.
+- If task completes at session end: mark `completed`, then on the next session resume, the orchestrator deletes it as part of the first-read checklist.
+
+### 2.2 Why delete (not retain)
+
+Active task lists with completed items become unreadable. The completed item history lives in:
+- Git commit log (the actual durable record).
+- Session archive (`docs/sessions/<date>.md`).
+- "Recently completed" section of CURRENT_WORK.md (last 3-5 only).
+
+Retaining all completed items in the active list defeats the file's purpose.
+
+### 2.3 Exceptions
+
+- Completed milestones with cross-cutting impact may stay in CURRENT_WORK.md "Recently completed" for one session before archiving.
+- Items that surface a new follow-up task: delete the old, add the new — do not chain.
+
+### 2.4 Origin
+
+Production case: TASKS.md grew to 400+ lines, with 60% of entries marked `completed` over months. New contributors couldn't find what was actually pending. The corrective rule made `completed` a transient state, not a permanent annotation.
+
+---
+
+## 3. Dev / Prod Sync (P3)
+
+When the project has multiple environments (dev / staging / prod), every feature that works in dev MUST work identically in prod once shipped. This rule applies to:
+
+- Code (auto-handled by deploy pipeline if branch-strategy is followed).
+- Database schema (migrations applied to all environments before code that depends on them ships).
+- Environment variables (registered in all environments before referencing code is deployed).
+- External service configurations (webhooks, OAuth callbacks, API keys per environment).
+- Cron / scheduled jobs (if dev runs them, prod runs them too — or both don't).
+
+### 3.1 The "dev works, prod broken" failure mode
+
+The single most common production incident pattern: a feature passes dev verification, ships to prod, fails because the prod environment is missing one or more of:
+
+- A required environment variable (forgot to register in prod dashboard).
+- A database migration (applied to dev but not prod).
+- A webhook URL update (third-party still pointing to old endpoint).
+- A feature flag (default OFF in prod, but on in dev).
+
+This failure mode is preventable by treating "dev / prod parity" as a checklist item before shipping.
+
+### 3.2 Pre-deploy parity checklist
+
+Before merging code to a release branch:
+
+- [ ] All new env vars registered in prod environment (with same names).
+- [ ] All new DB migrations applied to prod (or queued in deploy pipeline).
+- [ ] All third-party service configs updated for prod URL (webhook URLs especially — note the apex-domain trap below).
+- [ ] All feature flags decided for prod (default state explicit).
+- [ ] Cron / scheduled jobs registered in prod scheduler.
+
+### 3.3 Common traps
+
+**Trap 1 — Apex vs subdomain in webhook URLs.** Many third-party services do NOT follow HTTP redirects. If your apex domain redirects to `www.` (or vice versa), a webhook registered with the redirecting form silently fails — every event is "delivered" by the third-party but never reaches your handler. Always register webhook URLs with the canonical (non-redirecting) form.
+
+**Trap 2 — Env var registered but not redeployed.** Most platforms require a redeploy after env var registration before the new value is visible to running code. Build artifacts produced before the env was registered will not see it. Always trigger a fresh build after env changes.
+
+**Trap 3 — Migration applied without code, or code without migration.** Either order causes downtime. Apply schema changes that are backward-compatible first, then deploy code, then apply schema cleanups (drop old columns, etc.). When in doubt, dual-write briefly.
+
+### 3.4 When P3 does not apply
+
+If your project is single-environment (no separate prod), this rule is informational only. The rest of the universal-rules still apply.
+
+---
+
+## 4. Branch strategy (informational link)
+
+CONDUCTOR's universal rules don't mandate a specific branch strategy — they assume one exists. The opt-in `recipes/branch-strategy.md` documents a common 3-branch pattern (main / develop / release) used by the originating project. Adopters with their own strategy ignore the recipe; the operations rules above still hold.
+
+---
+
+## 5. Push timing (informational)
+
+The `recipes/branch-strategy.md` recipe also documents a "push timing" convention: docs-only changes are NOT pushed immediately; they batch with the next code push. This avoids polluting deploy pipelines with docs-only triggers. This is a project-specific preference, not a universal rule. Adopters choose.
+
+---
+
+## 6. Cross-tool enforcement
+
+| Mechanism | Tools that enforce automatically |
+|---|---|
+| `stop-session-log-check` (CURRENT_WORK staleness) | Claude Code |
+| Branch protection (force-push block, PR required) | GitHub branch protection (any tool) |
+| Pre-deploy CI checklist | CI pipeline (any tool) |
+| Rule text reminder | All tools |
+
+For non-Claude tools, the orchestrator self-checks at session start and session end.

package/core/universal-rules/quality-gates.md

@@ -0,0 +1,191 @@
+---
+rule_id: quality-gates
+rule_name: "Pre-commit + pre-merge review + test sync + verify-after-changes"
+severity: ABSOLUTE
+applies_to: ["all-tools"]
+violation_count: 3+
+enforcement:
+  - hook: stop-r6-review-check
+  - llm-self-discipline
+  - external: ci-pipeline
+linked_rules:
+  - workflow
+  - spec-as-you-go
+---
+
+# Quality Gates — Two-Stage Review + Test Sync + Verify
+
+> Bundles Q1 (pre-commit code review), Q2 (pre-merge code review), Q3 (test coverage sync), Q4 (verify-after-changes). Every code change passes through this gate before being declared done.
+
+## 1. Pre-Commit Code Review (Q1)
+
+Before a code change is committed, an automated reviewer MUST inspect the diff. Block on HIGH-confidence issues (severity ≥ 75 / 100). Lower-severity issues become PR comments.
+
+### 1.1 Reviewer selection (model routing)
+
+| Diff size / nature | Reviewer model |
+|---|---|
+| Single file, established pattern | Sonnet-tier |
+| Multi-file (3+) or cross-cutting | Opus-tier |
+| Type-design heavy | Specialized "type-design" reviewer if available |
+| Error-handling heavy | Specialized "silent-failure" reviewer if available |
+
+When in doubt, upgrade one tier. The cost difference between Sonnet and Opus reviewer is modest compared to the cost of merging a HIGH-severity bug.
+
+### 1.2 Exemptions (NOT subject to pre-commit review)
+
+- 100% docs-only changes (`docs/**`, `*.md` only).
+- Lockfile auto-generated bumps.
+- Generated type files (output of codegen tooling).
+
+Mixed PRs (docs + code) are NOT exempt. Any code in the diff triggers review.
+
+### 1.3 What "block on HIGH-confidence" means
+
+If the reviewer reports any issue with confidence ≥ 75 and severity ≥ HIGH:
+
+- Commit MUST NOT proceed.
+- Orchestrator addresses the issue (fix code, justify in commit message, or escalate to user).
+- Re-run reviewer on the updated diff.
+- Only when no HIGH-confidence issues remain: commit.
+
+LOW / MEDIUM issues become commit-message footer notes or follow-up tasks in CURRENT_WORK.md.
+
+---
+
+## 2. Pre-Merge Code Review (Q2)
+
+After commit + push + open PR, a SECOND review pass runs on the open PR before merge. This is distinct from Q1 — Q1 reviews the local diff before commit; Q2 reviews the merged-state PR (including CI signals + reviewer comments).
+
+### 2.1 Trigger
+
+PR opened on a non-direct-push branch (typically anything that is not `main` / `release` / `develop` per the project's branch strategy). See `recipes/branch-strategy.md` for branch naming patterns.
+
+### 2.2 Cool-down (Claude adapter only)
+
+The `stop-r6-review-check` hook (when installed by the Claude adapter) reminds the orchestrator to run pre-merge review at most once per 30 minutes per PR. This avoids reminder spam on rapid push cycles.
+
+### 2.3 Exemptions
+
+Same as Q1 (docs-only, lockfile, generated files). Additionally, PRs that have already passed pre-merge review are not re-reviewed unless new commits are pushed.
+
+### 2.4 Cross-tool degradation
+
+| Tool | Q2 mechanism |
+|---|---|
+| Claude Code | Slash command (`/code-review`) + Stop-hook reminder |
+| Cursor | Cursor command palette + manual rule reminder |
+| Copilot | GitHub PR comment review (Copilot Code Review native) + manual reminder |
+| Gemini / Codex / Windsurf | Manual reminder via rule text |
+
+---
+
+## 3. Test Coverage Sync (Q3)
+
+Every new feature, changed behavior, or new public API MUST have a corresponding test added or updated in the SAME PR.
+
+### 3.1 What test belongs to what change
+
+| Code change | Test type | Test location pattern |
+|---|---|---|
+| New page / route | E2E functional | `<test-root>/functional/<area>.spec.*` |
+| New API endpoint | E2E functional (auth + response shape) | Same as above |
+| New UI screen | Visual smoke | `<test-root>/visual/<area>.spec.*` |
+| Existing page UX change | Update existing functional spec (selectors, flow) | Same |
+| New service function | Unit test (happy + error path) | `<service>/__tests__/<service>.spec.*` |
+| New email template / similar render | Snapshot test | `<template-dir>/__tests__/<template>.spec.*` |
+
+### 3.2 Skip / "incomplete" classification
+
+A PR that adds a new feature without an accompanying test is treated as INCOMPLETE. Pre-commit review (Q1) catches this when the diff contains source changes but no test changes. Pre-merge review (Q2) catches it when CI runs.
+
+### 3.3 The "verify before push" command pair
+
+Before push:
+
+1. Run unit tests (project-specific command, e.g. `npx vitest run`).
+2. Run functional E2E (project-specific command, e.g. `npm run test:functional`).
+
+If either is red, the work is not done. The orchestrator does not push and does not declare the task complete.
+
+---
+
+## 4. Verify-After-Changes (Q4)
+
+Every code or configuration change MUST be verified by running the application or relevant subset before reporting "done" to the user.
+
+### 4.1 Verification levels by change type
+
+| Change | Verification |
+|---|---|
+| Code | Run unit tests + relevant functional E2E + manual sanity (when UI). |
+| Build config | Run `build` command, verify no errors. |
+| Environment variable | Verify in dev environment (or staging) that the var loads and the dependent path works. |
+| Database schema | Apply migration on dev DB, run mock-data seeds, run a query. |
+| External service config | Trigger the integration end-to-end (test webhook, send test email, etc.). |
+
+### 4.2 Reporting "done" to the user
+
+The orchestrator MUST NOT say "fixed" / "implemented" / "deployed" without prior verification evidence. Acceptable evidence:
+
+- Test runner output (snippet pasted into the response).
+- Build command exit code 0 (with command name).
+- HTTP request result (status + relevant body field).
+- Screenshot or render snapshot (if UI).
+- Database query result.
+
+A response that says "this should fix it" is not a completion report — it's a hypothesis. Mark it as such if you cannot verify.
+
+### 4.3 The "evidence before assertions" principle
+
+Borrowed from disciplined debugging practice: evidence ALWAYS precedes the success claim. The orchestrator that claims success without evidence is treated equivalently to silent rule violation (see workflow.md W6).
+
+### 4.4 Sub-agent completion reports are claims, not evidence
+
+When a sub-agent returns a "done" / "implemented" summary, that summary is a **claim**, not evidence. Before relaying completion to the user, the orchestrator MUST:
+
+1. `git diff` the sub-agent's changes and grep for the specific pattern the task required (the new structure / function / renamed symbol — not just "files changed").
+2. Where the change is observable at runtime (UI render, endpoint response, query result), observe it.
+3. Only then relay completion, citing the diff + observation.
+
+A green build or a passing test is a precondition for this check, never a substitute for it. See §4.5 below.
+
+### 4.5 Anti-pattern — false completion from a green build
+
+The failure mode §4.3–4.4 exist to prevent: a green build, a passing test suite, or a sub-agent's "done" summary is treated as proof that the *intended* change happened. It is not. A build can be green while the requested change never landed — a token-only edit went in instead of the structural change, the file that mattered was never touched, or a sub-agent edited the wrong surface. **build-green ≠ change-applied.**
+
+**Detection:** a "fixed / implemented / done / deployed" claim whose only cited evidence is build/test status or a sub-agent's prose, with no diff inspection or runtime observation of the intended change.
+
+**Fix:** (1) `git diff` and grep for the *concrete pattern the task required* — the new structure, function, or renamed symbol, not "files changed"; if the grep does not find it, the change was not applied regardless of build status. (2) Observe it at runtime where applicable (render the page, hit the endpoint, run the query). (3) Only then claim completion, citing the diff + observation. On the Claude adapter, the Stop guard `block-completion-claim-without-push` is the mechanical backstop.
+
+---
+
+## 5. Pre-commit checklist (operator-facing)
+
+Before any commit:
+
+- [ ] Type checks pass.
+- [ ] No hardcoded secrets / API keys in diff.
+- [ ] Approved UI library only (project-specific — see recipe).
+- [ ] Service-layer pattern preserved.
+- [ ] Result-pattern API responses preserved (where applicable).
+- [ ] Row-level-security or equivalent access control assumed by design.
+- [ ] Folder structure unchanged (no rogue new top-level directories).
+- [ ] Spec(s) updated (`spec-as-you-go.md`).
+- [ ] E2E test added / updated (Q3).
+- [ ] Naming conventions followed.
+- [ ] No duplicated business logic across surfaces (web ↔ mobile, etc.).
+- [ ] **Q1 — Pre-commit review passed.**
+
+---
+
+## 6. Cross-tool enforcement summary
+
+| Gate | Claude Code | Cursor | Copilot | Gemini | Codex | Windsurf |
+|---|---|---|---|---|---|---|
+| Q1 pre-commit review (auto) | Manual invoke + Stop-hook reminder | Manual | GitHub Copilot CR | Manual | Manual | Manual |
+| Q2 pre-merge review (auto) | Slash command + Stop-hook | Manual | GitHub native | Manual | Manual | Manual |
+| Q3 test coverage sync | Rule text + checklist | Same | Same | Same | Same | Same |
+| Q4 verify-after-changes | Rule text + LLM self-discipline | Same | Same | Same | Same | Same |
+
+The honest summary: only Claude Code has a pre-existing automated reminder mechanism. On other tools, the rule text + the operator's discipline carry the weight. CONDUCTOR does not pretend otherwise.