nitm-ai-dev-toolkit 5.2.0 → 5.3.0

package/src/monorepo/.claude/rules-snippets/fit-review.md

@@ -0,0 +1,62 @@
+# Goal-Fit Review Brief
+
+Read and follow this brief when a gate or command asks for a goal-fit review of a spec, a plan, or a build's scope. It adds to the reviewer rules of the calling flow.
+
+## Reviewer
+
+- Read-only. Do not edit files, stage, or commit. Do not write any file the caller did not ask for.
+- Independent of the author. Use Oracle when it is available read-only; otherwise a separate reviewer in fresh context. The author's self-review, the author's summary, and a single session playing every role do not count.
+- If no independent reviewer can run, the caller reports `BLOCKED`. Do not review in its place.
+- Review the current artifacts from scratch on every run, including resumed runs. Do not rely on an earlier reply, an earlier summary, or the author's account of what changed.
+
+## Goal sources
+
+Use only these as goal authority:
+
+1. The original user request, verbatim, and every explicit user amendment (intake answers, operator change requests, rework decisions). The caller passes them to you as text in the dispatch.
+2. Accepted constraints from earlier artifacts, when the caller passes them: for a plan review, the accepted spec's requirements, acceptance criteria, and `[DECIDED]` items; for a build review, the accepted spec and plan. Trace against these. They are not goal authority on their own.
+
+Not goal sources: a slug, a ticket key, a ticket title, the existing spec alone, the planner's or author's summary, and any reviewer finding from an earlier round.
+
+If the original request is not in the dispatch, do not infer goals from the spec or the plan. Reply `VERDICT: CHANGES` with a blocking finding: `Missing authoritative baseline: requires user decision; do not auto-repair.`
+
+Quote the original request in your report. When a lower source (a spec, a plan, or a summary) conflicts with the original request, report the conflict with both quotes. Do not silently trust the lower source.
+
+## Trace both ways
+
+- **Forward:** every goal is covered by a requirement, acceptance criterion, or step. Name the section that covers it, or report the gap.
+- **Backward:** every requirement, step, or file change traces to a goal. A change that no goal needs is scope drift.
+- Implementation details that a goal needs are allowed without their own acceptance criterion (for example, a migration that a storage goal requires). Do not demand that every mundane detail be an acceptance criterion. Name the goal that justifies such a detail.
+
+## Lenses (separate from correctness)
+
+- **Ponytail:** is this the simplest work that meets the goals? Flag speculative abstraction, dead flexibility, reinvented standard-library behavior, and steps no goal asks for. Block only when the finding adds scope or complexity the goals do not justify; otherwise note it.
+- **SOLID and SRP, proportional:** flag a responsibility split only when it harms a goal, for example one unit doing unrelated work the request keeps apart. Do not require abstractions or interfaces, and do not forbid a justified interface. Judge by the goals, not by the pattern.
+
+## Decisions and repairs
+
+- A change to a goal (dropping, narrowing, or adding one) is a user decision. So is any other question only the user can settle. A decision stays blocking until the user resolves it with an explicit amendment. Report it as a blocking finding under `VERDICT: CHANGES`, marked `requires user decision; do not auto-repair`, and also list it under **Decisions for the user**. Do not repair it, and do not assume an answer.
+- Other blocking findings are scoped repairs: name the section and the specific change. The caller passes your findings to the author as dispatch context and reviews the changed artifacts again. You do not write repair notes or repair files.
+- `VERDICT: PASS` means no blocking findings. Absence of blocking findings is not a pass. A finding that needs a user decision is blocking, so it is never a pass.
+
+## Output
+
+The first line is exactly `VERDICT: PASS` or `VERDICT: CHANGES`. `CHANGES` needs at least one blocking finding. Then use these sections:
+
+```markdown
+## Goal sources
+- Original request (quoted, short), amendments, accepted constraints. Conflicts: <quotes, or none>
+
+## Trace
+- Forward: <goal → covering section, or gap>
+- Backward: <untraced item → scope drift, or none>
+
+## Blocking findings
+- [section] Problem. Repair: <specific change>
+
+## Decisions for the user
+- <goal change or open decision, or none>
+
+## Notes (non-blocking)
+- [section] Ponytail or SRP observation. Optional.
+```

package/src/monorepo/.claude/rules-snippets/subagent-workflow.md

@@ -71,42 +71,73 @@ When dispatching implementation tasks, match the specialist to the domain:
 
 ## Orchestration Patterns
 
-### Sequential (default)
+### Delegation Default
 
-Tasks with dependencies are implemented one at a time in dependency order. Each must pass review before the next begins.
+- **Delegate by default.** Hand substantial, safely separable discovery, implementation, test, and review work to subagents. Use a single agent only for trivial work, as listed under "When to Use a Single Agent Directly".
+- **The coordinator keeps outcome responsibility.** It defines each task's scope, reconciles every result, makes sure verification runs, and reports the final outcome. A subagent reporting success is not the outcome.
+- **Work directly only** for trivial changes (one small edit, a quick answer) or when the context is too heavy to hand off cheaply, such as work that depends on large context the coordinator already holds. Say why when you skip delegation.
+- **No delegation capability.** If the host offers no subagent dispatch, say so explicitly in the report. Do permitted direct work where it is safe. Never self-review in place of an independent gate: record the gate as pending and end as BLOCKED or WAITING.
 
-### Parallel
+### Dependency Graph and Parallel Batches (REQUIRED before dispatching)
 
-Independent tasks can be dispatched to multiple specialist subagents simultaneously. Use when tasks don't share files or state.
+Before dispatching any task list, the orchestrator builds the dependency graph. No `[P]` marker is required. If a task list has `[P]` markers, treat them as hints and verify them.
 
-### Parallelization Analysis (REQUIRED before dispatching)
+1. **Read and write sets.** For each task, list the files, directories, or packages it reads and writes.
+2. **Exclusive writable scopes.** Each writer gets a scope no other concurrent task writes. Two tasks that share any writable path are dependent. A task whose write set is unknown or undeclared runs serially until its scope is established from the changed-file list.
+3. **Data dependencies.** A task that reads what another task writes waits for that task.
+4. **Ready batch.** Tasks whose dependencies are satisfied and whose writable scopes are disjoint form one batch. Dispatch the whole batch together. Dependent and shared-write tasks run in later batches, one at a time.
+5. **Route by domain.** Backend tasks → Backend Architect; frontend → Frontend Developer; API contracts → API Specialist; docs → Documenter; cross-cutting → Implementer.
+6. **Track handles.** Record each dispatched task's handle, agent, writable scope, and status until its result is reconciled.
+7. **Reconcile before dependents.** Inspect each result (changed files, summary, verification) before dispatching any task that depends on it. If a result changed a path the graph did not expect, stop the affected tasks and re-plan the batch.
+8. **Continue the chain.** When a batch's results are reconciled, compute the next ready batch and dispatch it. Do not wait for the user unless a mandatory gate applies or no authorized, unblocked work remains (see Autonomous Execution and Blockers).
 
-Before executing any task list, the orchestrator MUST run this analysis:
-
-1. **Scan for `[P]` markers** in the task list — these are pre-identified parallel candidates
-   - If no `[P]` markers exist, do **not** assume sequential-only work. Treat all tasks as candidates and infer parallel-safe groups via the independence test.
-2. **Build a dependency graph**: For each task, list which files it reads and writes
-3. **Apply the independence test**:
-   - Tasks that write to **different files** with **no shared state** → parallel-safe
-   - Tasks that share any writable file → sequential (dependency edge)
-   - Tasks where one reads what another writes → sequential (data dependency)
-4. **Group by domain** for specialist routing:
-   - Backend tasks → Backend Architect
-   - Frontend tasks → Frontend Developer
-   - API contract tasks → API Specialist
-   - Documentation tasks → Documenter
-   - Cross-cutting → Implementer
-5. **Dispatch decision**:
-   - **3+ independent tasks** → Use `dispatching-parallel-agents` skill, one agent per task
-   - **2 independent tasks** → Parallel dispatch (simpler coordination)
-   - **All tasks dependent** → Sequential with `subagent-driven-development` skill
-   - **Mixed** → Dispatch independent group in parallel, then continue sequential chain
+**Dispatch shape:** 3+ independent tasks → `dispatching-parallel-agents`, one agent per task. 2 independent tasks → parallel dispatch. All tasks dependent → sequential with `subagent-driven-development`. Mixed → run each ready batch in parallel, then continue the sequential chain.
 
 ```
-Example: 5 tasks → T1 (setup) → T2 [P] (backend API) + T3 [P] (frontend UI) + T4 [P] (docs) → T5 (integration tests)
-         Dispatch: T1 sequential → T2+T3+T4 parallel → T5 sequential
+Example: 5 tasks → T1 (setup) → T2 (backend API) + T3 (frontend UI) + T4 (docs) → T5 (integration tests)
+         Batches: [T1] → [T2, T3, T4] → [T5]
+         T2, T3, and T4 run together only because their writable scopes are disjoint.
 ```
 
+## Turn Completion and Waiting
+
+During active multi-step execution, never end a turn silently, and never treat dispatch or partial progress as completion. End each such turn in exactly one of these states. Informational answers need no status line:
+
+- **DONE:** the requested work is complete and verified under Quality Gates. State the outcome and the validation that ran.
+- **WAITING:** name each pending task (handle and agent) and its resume trigger, such as a subagent notification or a user reply at a named gate. List what completed and what remains.
+- **BLOCKED / NEEDS-DECISION:** state the blocker or decision, what completed, what remains, and the exact next user action.
+
+Resume mechanics depend on the host:
+
+- When the host notifies on subagent completion, reconcile the notified result and continue with the next eligible batch. Check each handle once per notification.
+- When the host cannot resume in the background, do not claim that it will. Either run the batch in the foreground and collect the results within the turn, or end as WAITING and say that the user must send a message to resume, naming the exact step.
+- Do not busy-poll. Never loop on status checks.
+
+## Autonomous Execution and Blockers
+
+During multi-step execution, work autonomously within the approved goal, scope, and permissions. Autonomy grants no extra authority.
+
+- **A blocker pauses only the affected task and its dependents.** Independent ready work within authority continues in the next batch.
+- **Record each unresolved blocker immediately** in the existing progress record or the conversation: the affected task, what is needed and why, safe options or a targeted input, and the next action. Keep it visible in progress updates and the final report. Never drop it silently.
+- **Defer non-global blockers** as follow-up questions while work can safely advance.
+- **Stop for user input** only when no authorized, unblocked work remains, or when a mandatory approval, security, or permission gate prevents the remaining work. Agents still running are WAITING, not blocked.
+- **Ask clearly.** Present the consolidated outstanding questions through the harness's native question or clarification tool when one is available. Do not assume a tool name or support. Without one, give numbered options or a fill-in block in chat.
+- **Answers can arrive early.** Do not require a blocking tool prompt while independent work continues. Report deferred questions in progress updates.
+- **Never** silently choose a consequential scope or requirement change, bypass a required human approval, or mark a partially blocked task DONE.
+
+## Long-Session Checkpoint
+
+For sessions that span several batches or a context reset:
+
+- Use existing progress records only: a progress section the plan or task list already has, Factory job notes, or task records, when they exist. Keep the approved goal, current step, active task handles, blocker, and next action in those notes or in the conversation.
+- Never add fields to structured files such as Factory `job.json`, never rewrite accepted requirements or spec/plan text, and never replace an authoritative source with a summary.
+- If no such records exist, a short checkpoint in the conversation is enough. Do not create new files for trivial work.
+- On resume, reread the accepted source (spec, plan, or task text) instead of relying on the checkpoint summary, and check the working tree before dispatching anything.
+
+## Factory Approvals
+
+Spec and plan confirmations remain mandatory human steps; final approval, escalation, and merge behavior follow the job's `APPROVAL_MODE` and `MERGE_MODE`. Delegation, batching, autonomy, and subagent sign-offs never satisfy spec or plan human confirmation, or human final approval when `APPROVAL_MODE=human`. Mode-defined approver behavior is preserved. Stop at the gate and report it as WAITING or BLOCKED.
+
 ## Quality Gates
 
 - Every implementation must pass **Reviewer** before proceeding
@@ -114,6 +145,19 @@ Example: 5 tasks → T1 (setup) → T2 [P] (backend API) + T3 [P] (frontend UI)
 - Coordinators should not skip review even for "simple" changes
 - If a reviewer requests changes, the original specialist fixes them and re-review occurs
 
+## Model Capacity Fallback
+
+When a subagent stops on a model capacity, quota, session limit, or reset-wait failure (most often Claude), switch its **model** and keep its **agent**. This is automatic for those failures; do not ask first.
+
+- **Same agent, same role.** Re-dispatch the same agent with the same task, permissions, and context (and session, where the harness supports it). Do not substitute an equivalent agent.
+- **Model order, one attempt each.** Try the next model in the configured fallback order for that agent. When the order is exhausted, try the harness's known available default, unless it was already tried. Then stop; do not cycle back.
+- **Never** retry the same unavailable model, and never wait blindly for a quota reset.
+- **Only supported switching.** Change the model through per-call selection the runtime supports, using only fallback models and defaults that are already configured or exposed. Do not invent model IDs, and do not edit persistent or global config, accounts, or billing.
+- **Blocker when nothing is left.** If no configured fallback or default is available, or per-call selection is unsupported, the affected task is reported BLOCKED with the question of which model to use. Its dependents stop; independent authorized work continues (see Autonomous Execution and Blockers).
+- **Inspect before resuming.** Check what the failed attempt left in the working tree, then resume from that partial work. Never run two writers on the same files at once.
+- **Keep review independent.** The reviewer stays a separate agent from the builder, even when the builder moves to a fallback model.
+- **Disclose.** The final report names the original model, each fallback attempted, and the model that finished the work.
+
 ## Skills Integration
 
 These skills complement subagent workflows:

package/src/monorepo/.cursor/commands/bootstrap-patch.md

@@ -10,7 +10,7 @@ argument-hint: "optional patch options"
 | Agent | When to use |
 |-------|-------------|
 | `fixer` | Standard patch — incremental changes to existing config |
-| `planner` | Complex patch — cross-cutting changes needing analysis first |
+| `reviewer` | Independent read-only review before approval and after apply |
 
 Patch AI instructions by comparing against the latest toolkit templates and applying updates.
 

package/src/monorepo/.cursor/commands/implement-feature.md

@@ -10,7 +10,7 @@ argument-hint: "feature specification or task list"
 | Agent | When to use |
 |-------|-------------|
 | `fixer` | Bounded feature work — spec is clear, files are known |
-| `feature-builder` | Complex feature — needs research, planning, and coordination |
+| `feature-builder` | Complex feature build — builder only; the orchestrator still runs the review |
 
 Implement a feature by completing tasks sequentially with proper tracking and review gates.
 

package/src/monorepo/.github/prompts/bootstrap-patch.prompt.md

@@ -10,6 +10,6 @@ argument-hint: "optional patch options"
 | Agent | When to use |
 |-------|-------------|
 | `fixer` | Standard patch — incremental changes to existing config |
-| `planner` | Complex patch — cross-cutting changes needing analysis first |
+| `reviewer` | Independent read-only review before approval and after apply |
 
 **CRITICAL: READ:** [.claude/prompt-snippets/bootstrap-patch.md](../../.claude/prompt-snippets/bootstrap-patch.md).

package/src/monorepo/.github/prompts/constitution.prompt.md

@@ -1,5 +1,6 @@
 ---
 description: Create or update the project constitution
+tools: ["read", "search", "edit", "agent"]
 argument-hint: "no arguments required"
 ---
 

package/src/monorepo/.github/prompts/create-skill.prompt.md

@@ -1,5 +1,6 @@
 ---
 description: Create a new agent skill following VS Code and agentskills.io specifications
+tools: ["read", "search", "edit", "agent"]
 tags: [skill-creation, agent-skills, documentation, automation]
 version: 1.0.0
 argument-hint: "skill name and requirements"

package/src/monorepo/.github/prompts/implement-feature.prompt.md

@@ -10,6 +10,6 @@ argument-hint: "feature specification or task list"
 | Agent | When to use |
 |-------|-------------|
 | `fixer` | Bounded feature work — spec is clear, files are known |
-| `feature-builder` | Complex feature — needs research, planning, and coordination |
+| `feature-builder` | Complex feature build — builder only; the orchestrator still runs the review |
 
 **CRITICAL: READ:** [.claude/prompt-snippets/implement-feature.md](../../.claude/prompt-snippets/implement-feature.md).

package/src/monorepo/.github/prompts/plan.prompt.md

@@ -1,5 +1,6 @@
 ---
 description: Create an implementation plan for a feature
+tools: ["read", "search", "edit", "agent"]
 argument-hint: "feature specification or requirement"
 ---
 

package/src/monorepo/.opencode/commands/bootstrap-patch.md

@@ -9,7 +9,7 @@ description: "Patch AI instructions by fetching updates from the toolkit repo an
 | Agent | When to use |
 |-------|-------------|
 | `fixer` | Standard patch — incremental changes to existing config |
-| `planner` | Complex patch — cross-cutting changes needing analysis first |
+| `reviewer` | Independent read-only review before approval and after apply |
 
 ## Arguments
 

package/src/monorepo/.opencode/commands/implement-feature.md

@@ -9,7 +9,7 @@ description: "Implement a feature by completing tasks sequentially"
 | Agent | When to use |
 |-------|-------------|
 | `fixer` | Bounded feature work — spec is clear, files are known |
-| `feature-builder` | Complex feature — needs research, planning, and coordination |
+| `feature-builder` | Complex feature build — builder only; the orchestrator still runs the review |
 
 ## Arguments
 

package/src/monorepo/AGENTS.md

@@ -77,7 +77,7 @@ For CLI command reference, see the matching skill: `.agents/skills/{acli,gh-cli,
 
 #### 1. Proactive Clarification
 
-- **Identify Ambiguity**: Stop and ask if a task lacks clear acceptance criteria, inputs, or expected outputs.
+- **Identify Ambiguity**: Ask a targeted question if a task lacks clear acceptance criteria, inputs, or expected outputs. It blocks only that task and its dependents; independent work with clear requirements continues (see the "Autonomy with blockers" bullet under Operating Rules).
 - **Resolve Conflicts**: Flag conflicting instructions between the user prompt, existing code, and documentation before writing code.
 - **Expose Assumptions**: State your assumptions clearly and ask for validation before proceeding with high-impact changes.
 
@@ -268,7 +268,10 @@ Use custom agents when you want explicit coordinator and worker roles. Use workf
 - Do not make an implementation subagent read the plan file on its own; pass the relevant task directly.
 - In `subagent-driven-development`, keep the review order strict: spec compliance first, then code quality.
 - If a reviewer finds issues, fix them and re-run the same review before moving on.
-- Do not run multiple implementation subagents in parallel when they could touch shared packages, shared docs, or the same app surface.
+- Parallel implementation subagents need exclusive writable scopes. If scopes could overlap (shared packages, shared docs, or the same app surface), or one task reads another's output, run them sequentially. See `.claude/rules-snippets/subagent-workflow.md` for the dependency graph and batch rules.
+- Delegate substantial, separable work by default; the coordinator stays responsible for the outcome and reconciles each result before dispatching dependents.
+- **Never end silently** — During active multi-step execution, end each turn as DONE, WAITING (pending task handle and resume trigger), or BLOCKED / NEEDS-DECISION (what completed, what remains, exact next user action). Dispatch or partial progress is not completion. Spec and plan confirmations remain mandatory human steps; final approval, escalation, and merge behavior follow the job's `APPROVAL_MODE` and `MERGE_MODE`. Delegation or autonomy alone never satisfies a gate.
+- **Autonomy with blockers** — Work autonomously within the approved goal, scope, and permissions. A blocker pauses only its task and dependents: record it, defer non-global questions, and continue independent authorized work. Stop for the user only when no authorized work remains or a mandatory gate applies, and ask through the harness's native question tool when one exists.
 - For cross-app work, research boundaries first, sequence shared package changes before app-specific changes, and review downstream impact explicitly.
 
 #### Recommended Flow
@@ -343,8 +346,8 @@ Workers are dispatched by coordinators and are not directly user-invocable.
 - Admin dashboards, RBAC, reporting, monitoring → Admin Portal
 - General implementation → Implementer
 
-**Sequential**: Tasks with dependencies are implemented one at a time.
-**Parallel**: Independent tasks (e.g., changes in different apps) can be dispatched to multiple subagents simultaneously.
+**Sequential**: Dependent tasks, and tasks that share a writable file or package, run one at a time in dependency order.
+**Parallel**: Ready tasks with exclusive writable scopes (e.g., changes in different apps) run together as one batch. Reconcile each batch's results before dispatching the next.
 
 **Monorepo-specific**: When implementing features that span multiple apps, coordinate carefully:
 
@@ -366,7 +369,7 @@ Subagents are typically **agent-initiated** — the coordinator decides when to
 
 ### Factory (opt-in)
 
-An optional file-driven pipeline for feature-sized work, alongside Feature Builder and TDD. Start it with `/factory <request>` in Claude Code, Copilot, Cursor, or OpenCode. The orchestrator reads the project and asks only the glaring questions before it creates anything, then asks you to continue or change the answers. Resume a feature with `/factory start <KEY | slug | job-id>`. Codex runs the orchestrator skill directly. Each job belongs to a feature folder in `docs/features/`, stops at a spec gate and a plan gate for your confirmation before any ticket or build, builds in its own git worktree unless you ask for `--in-place`, and moves its tickets when the project tracks them. The orchestrator is [.agents/skills/factory/SKILL.md](.agents/skills/factory/SKILL.md). It runs on the native `planner` (spec and plan), `implementer` (build, repair, and rework), and `reviewer` (the code, security, ux, and ui lenses, and approval) agents. Each role's Factory rules are in its brief in `.agents/skills/factory/roles/`. Setup, placeholders, and approval modes are in [factory/README.md](factory/README.md). Jobs name the affected apps and packages in their spec, and checks run for those with the filtered commands in [Commands](#commands).
+An optional file-driven pipeline for feature-sized work, alongside Feature Builder and TDD. Start it with `/factory <request>` in Claude Code, Copilot, Cursor, or OpenCode. The orchestrator reads the project and asks only the glaring questions before it creates anything, then asks you to continue or change the answers. Resume a feature with `/factory start <KEY | slug | job-id>`. Codex runs the orchestrator skill directly. Each job belongs to a feature folder in `docs/features/`, stops at a spec gate and a plan gate for your confirmation before any ticket or build, builds in its own git worktree unless you ask for `--in-place`, and moves its tickets when the project tracks them. The orchestrator is [.agents/skills/factory/SKILL.md](.agents/skills/factory/SKILL.md). It runs on the native `planner` (spec and plan), `implementer` (build, repair, and rework), and `reviewer` (the code, security, ux, and ui lenses, and approval) agents. Each role's Factory rules are in its brief in `.agents/skills/factory/roles/`. Spec and plan goal-fit must be confirmed by an independent Oracle or read-only reviewer, not the spec or plan author. Single-session role switching, including the Codex fallback, does not satisfy that and blocks these gates. Spec and plan confirmations stay mandatory human steps in every approval mode. Setup, placeholders, and approval modes are in [factory/README.md](factory/README.md). Jobs name the affected apps and packages in their spec, and checks run for those with the filtered commands in [Commands](#commands).
 
 ## Documentation Requirements
 
@@ -382,6 +385,10 @@ Documentation updates are **mandatory before committing** any feature or fix. Se
 - Reference `docs/constitution.md` for project principles and governance
 - Include all doc changes in the same commit/PR as the code
 
+**Supplied-task exception (`implement`, `implement-feature`, `implement-fixes` only):** the task supplied to these commands replaces the spec and plan prerequisites. Do not create or require `spec.md` or `plan.md` for the feature or fix unless the user asks for them. Every other applicable item in the [documentation checklist](.claude/rules-snippets/documentation.md) still applies, including the fix log, `CHANGELOG.md`, `docs/api/`, and `README.md`.
+
+**Requirement-only planning exception:** For `/plan` without an existing specification, preserve the original supplied requirements and acceptance criteria in `plan.md` under **Requirements Source** and **Acceptance Criteria**; do not require or create `spec.md`. `/tasks` and `/assign-tasks` consume that plan source when no specification exists; keep acceptance criteria out of the slim task checklist. This exception overrides the spec prerequisite and mandatory spec-first sequence above and in the documentation checklist only for these planning artifacts. It does not authorize implementation, replace artifact review, waive required human approvals, or change any other documentation duties. The separate implementation-command supplied-task exception remains unchanged.
+
 ## Related Documentation
 
 - [README.md](README.md) - Project overview

package/src/monorepo/factory/README.md

@@ -55,7 +55,7 @@ The orchestrator and agents are the same in every harness. Each harness has its
 | GitHub Copilot | `/factory` prompt (`.github/prompts/factory.prompt.md`) | `.github/agents/` |
 | Cursor | `/factory` (`.cursor/commands/factory.md`) | `.cursor/agents/` |
 | OpenCode | `/factory` (`.opencode/commands/factory.md`) | `.opencode/agents/` |
-| Codex | The factory skill (`.agents/skills/factory/SKILL.md`) | None. Runs each role brief directly, one role at a time in one session (see Harness notes in SKILL.md) |
+| Codex | The factory skill (`.agents/skills/factory/SKILL.md`) | No native agent definitions. Role briefs run directly; spec and plan acceptance requires an independent review session. Single-session role switching cannot satisfy that gate (see Harness notes in SKILL.md). |
 
 In OpenCode with the Slim plugin, `oracle` and `designer` are optional alternatives to `reviewer`, if you configure them as edit-denied. The default is the native agents.
 
@@ -83,6 +83,8 @@ Sizing is decided in `plan.md`:
 
 Every job stops twice, in every approval mode, before anything is ticketed or built:
 
+Before either confirmation, an independent read-only Oracle, or reviewer when Oracle is unavailable, checks goal fit. Revisions and resumed gates are reviewed again. Missing independent review blocks acceptance, including single-session Codex use; it does not block discussing unresolved decisions. If the original requirements cannot be recovered, the operator must confirm the recovered baseline rather than treating an agent-written summary as the original request.
+
 1. **Spec gate** (`awaiting-spec`). You read the spec summary, the acceptance criteria count, each open `[PRODUCT DECISION]` item, and open questions. Answer every open decision before you confirm: answers go in your change request, are saved as `spec-<k>.md`, and the spec writer records each one as `[DECIDED]`.
 2. **Plan gate** (`awaiting-plan`). You read the plan, the tasks, the size, the tracking proposal, and the build mode. Confirm, request changes (saved as `plan-<k>.md`), or change size, tracking, or build mode. Requests that touch the spec go back through the spec gate.
 

package/src/repo/.agents/skills/dispatching-parallel-agents/SKILL.md

@@ -139,7 +139,7 @@ For full-stack or cross-cutting features, dispatch domain specialists in paralle
 | Multi-subsystem fix | Backend Architect (service A) + Backend Architect (service B) | Independent service bugs                                     |
 | Cross-app monorepo  | Specialist per app                                            | Same feature in `apps/web` + `apps/api` (no shared packages) |
 
-**Safe to parallelize:** Agents touch different files/directories with no shared state.
+**Safe to parallelize:** Agents have exclusive writable scopes (no shared files/directories) and no shared state. Build the dependency graph first; see `.claude/rules-snippets/subagent-workflow.md`.
 **Still sequential:** Tasks that share files, database migrations, or API contracts that one depends on.
 
 ## When NOT to Use

package/src/repo/.agents/skills/factory/SKILL.md

@@ -59,7 +59,7 @@ factory/
   jobs/                      runtime state, ignored by git
     <NNN-slug>/
       job.json               orchestrator only; rewrite the whole file
-      intake.md              you, from the intake questions and answers (only when asked)
+      intake.md              you: the original request verbatim under `## Original request`, the questions and answers (when asked), and `## Baseline confirmed` (when needed)
       spec-<k>.md            you, from the operator's change request at the spec gate
       plan-<k>.md            you, from the operator's change request at the plan gate
       build.md               builder; cumulative round log
@@ -147,7 +147,7 @@ A job is **closed** when its stage is `merged` or `abandoned`. Every other job i
    2. Make changes: the operator types them.
 
    Changes → revise the Q&A with the operator's text, show it, and ask again. Nothing is created until the operator picks 1.
-4. **Continue as Start.** Treat the answers as clarifications of the request. Run Start from step 1 with the request text. Once the job folder exists (Start step 4), write `factory/jobs/<id>/intake.md` with the questions as asked and the answers, verbatim, one question and answer each. Skip the file when nothing was asked. The spec writer reads it (paths block). If Start resumes an open job instead of creating one, say the answers were not applied. Changes after the spec go through the spec gate, the plan gate, or `/factory rework`.
+4. **Continue as Start.** Treat the answers as clarifications of the request. Run Start from step 1 with the request text. Once the job folder exists (Start step 4), add the questions as asked and the answers to `factory/jobs/<id>/intake.md`, verbatim, one question and answer each. Skip this when nothing was asked. The spec writer reads it (paths block). If Start resumes an open job instead of creating one, say the answers were not applied. Changes after the spec go through the spec gate, the plan gate, or `/factory rework`.
 
 `--in-place` on the command, or the operator's answer saying so, sets `worktree` to `false` on the new job (see In-place mode).
 
@@ -188,9 +188,9 @@ Resume by stage:
 | Stage | Resume action |
 | --- | --- |
 | `spec` | Rerun `planner` in spec mode (brief `roles/spec.md`), then show the spec gate |
-| `awaiting-spec` | Show the spec gate |
+| `awaiting-spec` | Show the spec gate (it runs the fit review first) |
 | `plan` | Rerun `planner` in plan mode (brief `roles/spec.md`), then show the plan gate |
-| `awaiting-plan` | Show the plan gate |
+| `awaiting-plan` | Show the plan gate (it runs the fit review first) |
 | `build` | Rerun `implementer` (brief `roles/build.md`) in the mode the files call for: rework if a `rework-<k>.md` is newer than `build.md`, repair if the last review round has `CHANGES`, otherwise build |
 | `review` | Rerun the review round `round` |
 | `approve` | Rerun the approval (`reviewer` in approval mode, brief `roles/approve.md`) |
@@ -212,7 +212,7 @@ A job with no work started (stage before `build`, so no build has begun and no `
 3. Slug = the feature folder name without its key prefix (`onboarding-bootstrap` for `PROJ-1234-onboarding-bootstrap`). Stable across the key rename.
 4. `mkdir factory/jobs/<NNN-slug>` (no `-p`). If it already exists, bump `NNN` and retry. `mkdir` without `-p` is the claim.
 5. Write `job.json` with stage `spec`, `feature_dir`, `issue_key` (the key from Resolve, or `null`), `size` `unclear`, `tracking` `none`, `worktree` (`false` for `--in-place` or when the operator asked for it at intake, `true` otherwise), and `worktree_path` `null`.
-6. If intake asked questions, write `intake.md` (see Intake).
+6. Write `intake.md` (see Intake): when the request text was typed, the original request verbatim under `## Original request`. For a key or slug start, write no original request section; the Fit review baseline step asks the operator for it. Add the questions and answers when intake asked.
 
 ## Spec
 
@@ -220,18 +220,19 @@ Set stage `spec`. Dispatch `planner` in spec mode (brief `roles/spec.md`) with t
 
 ## Spec gate (mandatory)
 
-Runs in every `APPROVAL_MODE`, before any plan is written. Show the operator in chat:
+Runs in every `APPROVAL_MODE`, before any plan is written. Every time the gate is shown (first time, after each change request, and on resume), run the fit review first (see Fit review). Show the operator in chat:
 
 - The spec's Summary, the number of acceptance criteria, each open `[PRODUCT DECISION]` item, and Open Questions.
+- The fit review's verdict, its blocking findings, and its decisions for the user.
 
 Then ask in chat, as a numbered choice:
 
-1. Confirm the spec. Offered only when no `[PRODUCT DECISION]` item is open.
+1. Confirm the spec. Offered only when no `[PRODUCT DECISION]` item is open and the current fit review is an explicit `VERDICT: PASS`.
 2. Request changes: the operator types the change. Each open `[PRODUCT DECISION]` item needs an answer in the change text.
 
 Handle the answer:
 
-- **Confirm** → continue to Plan. If decision items are still open, do not continue: list them and ask again.
+- **Confirm** → continue to Plan. If decision items are still open, or the current fit review is not an explicit `VERDICT: PASS`, do not continue: list them and ask again.
 - **Request changes:** write the operator's text verbatim to `spec-<k>.md` in the job folder (`k` = next free index). Set stage `spec`, rerun `planner` in spec mode (brief `roles/spec.md`) with the paths block and `spec-<k>.md`. It updates `spec.md`. Set stage `awaiting-spec` and show the gate again. The spec writer records each answered decision as `[DECIDED] <answer>`.
 
 If the session ends at this gate, `/factory start <job-id|slug|KEY>` shows it again (see Start).
@@ -247,21 +248,22 @@ Read the `**Size:**` line of `plan.md`:
 
 Proposed tracking: `tracked` only when size is `large` and the project's `AGENTS.md` Project Management section names a real tracker. Unfilled placeholders mean no tracker. Otherwise propose `none`.
 
-Set stage `awaiting-plan` and show the plan gate.
+Set stage `awaiting-plan`. The plan gate runs the fit review before it is shown.
 
 ## Plan gate (mandatory)
 
-Every job stops at `awaiting-plan` before anything is ticketed or built, in every `APPROVAL_MODE`. Show the operator in chat:
+Every job stops at `awaiting-plan` before anything is ticketed or built, in every `APPROVAL_MODE`. Every time the gate is shown (first time, after each change request, and on resume), run the fit review first (see Fit review), against the goal sources (see Fit review), the accepted spec, and the plan. Show the operator in chat:
 
 - The plan's approach and steps from `plan.md`.
 - The size and the reason from `plan.md`.
+- The fit review's verdict, its blocking findings, and its decisions for the user.
 - For large work, the lines of `tasks.md`.
 - The tracking proposal: create tickets in the tracker under the parent (the job's key, or a new parent), or no tickets (`tasks.md` only), or no tickets at all.
 - The build mode: `worktree` (default) or `in-place`, as set in `job.json`.
 
 Then ask in chat, as a numbered choice:
 
-1. Confirm the plan.
+1. Confirm the plan. Offered only when the current fit review is an explicit `VERDICT: PASS`.
 2. Request changes: the operator types the change.
 3. If size is `unclear`: answer `small` or `large`.
 4. Change tracking: `tracked` or `none`.
@@ -269,7 +271,7 @@ Then ask in chat, as a numbered choice:
 
 Handle the answer:
 
-- **Confirm** with size known → continue to Tracking. If size is still `unclear`, ask again.
+- **Confirm** with size known → continue to Tracking. If size is still `unclear`, or the current fit review is not an explicit `VERDICT: PASS`, ask again.
 - **Request changes:** write the operator's text verbatim to `plan-<k>.md` (`k` = next free index). Set stage `plan`, rerun `planner` in plan mode (brief `roles/spec.md`) with the paths block and `plan-<k>.md`. Show the gate again. If the change touches the spec itself, send it through the spec gate instead: write it to `spec-<k>.md`, rerun spec mode, show the spec gate, then plan again.
 - **Change size only:** the operator's answer to choice 3 sets `size` in `job.json`. The plan does not change.
 - **Change tracking only:** update `tracking` in `job.json`. Do not rerun the spec writer.
@@ -277,6 +279,25 @@ Handle the answer:
 
 If the session ends at the gate, nothing is lost. `/factory start <job-id|slug|KEY>` returns to this gate (see Start).
 
+## Fit review (spec and plan gates)
+
+Read and follow the goal-fit brief: [fit-review](../../../.claude/rules-snippets/fit-review.md). It is a read-only goal-fit review, separate from the reviewer lenses. It runs every time a spec or plan gate is shown: after each planner run, after each change request, after each repair, and on resume.
+
+- **Baseline first.** No review runs without the original request. Check `intake.md` for an `## Original request` section or a `## Baseline confirmed` section. If neither exists (a key or slug start, a legacy job, or a sparse one), the orchestrator promotes nothing. It shows the candidate sources it found (the existing `intake.md`, the tracker description when `issue_key` is set, and the existing `spec.md`), each labelled as a candidate and not a requirement. It asks the operator, as a numbered choice: (1) confirm one candidate as the original request, or (2) paste the original request. It writes the confirmed text to `intake.md` under `## Baseline confirmed`, naming its source. Until then the gate reports `NEEDS-DECISION: baseline missing`, and Confirm is not offered.
+- **Goal sources in every dispatch.** Pass them as text, not as paths alone: the verbatim original request (from `## Original request` or `## Baseline confirmed`), and every explicit amendment (the intake answers, and the operator's `spec-<k>.md`, `plan-<k>.md`, and `rework-<k>.md`). For a plan review, also pass the accepted spec. The accepted spec and plan are traced against these; they are not goal authority. A slug, a key, a tracker title, the existing spec on its own, and any reviewer finding are never goal sources.
+- **Reviewer.** Dispatch `oracle` when the harness has it configured read-only. Otherwise dispatch `reviewer` in fresh context. The task line is `goal-fit review: spec` or `goal-fit review: plan`, then the paths block, the goal sources, and the brief. Give the reviewer the artifacts, never the planner's summary.
+- **Independence.** The planner's own output, the orchestrator's reading, and a single session playing every role do not count. With no independent reviewer, the gate reports `BLOCKED: no independent reviewer`, shows the artifact, and does not offer Confirm. Request changes and abandon stay available.
+- **Reply.** The first line decides:
+  - `VERDICT: PASS`: the gate may offer Confirm.
+  - `VERDICT: CHANGES` with a finding marked `requires user decision; do not auto-repair`: stop as `NEEDS-DECISION`. Show the marked findings with the gate. Confirm is not offered. Nothing is repaired until the user answers with an explicit amendment (a change request), and the artifact is reviewed again.
+  - `VERDICT: CHANGES` with only repairable findings: run the repair loop below.
+  - No valid first line: re-dispatch once. If it still has none, set `needs-human` with `failed_stage` `spec` or `plan`, as for any spec or plan agent that returns no output.
+- **Repair loop.** On `CHANGES` with only repairable findings, pass the blocking findings to the planner as dispatch context under the heading `Fit repair findings (reviewer findings, not operator requests, not goal authority)`. Write no `spec-<k>.md`, `plan-<k>.md`, or fit file for them. Rerun the planner, then review the changed artifacts again. The loop has no round limit. It repeats until `PASS`, `NEEDS-DECISION`, or `BLOCKED`. Stop as `BLOCKED` with the reason when a repair changes nothing, when the same blocking finding returns unchanged after a repair, or when the planner reports a finding it cannot address. On `BLOCKED`, show the open findings. Confirm is not offered. Request changes and abandon stay available.
+- **Timeouts.** A timed-out fit reviewer is never re-dispatched (see Harness notes). Set stage `needs-human`, `failed_stage` `spec` or `plan`, and the reason `fit reviewer timed out after <N> min; it may still be running`. Tell the operator to confirm the reviewer has stopped before `/factory start`. Confirm is not offered.
+- **Confirm needs an explicit PASS.** Confirm is offered only when the reply on this gate visit starts with `VERDICT: PASS`. The absence of blocking findings is not a PASS.
+- **BLOCKED at the gate versus agent failure.** A `BLOCKED` gate (baseline, independence, or an unproductive loop) leaves the stage at `awaiting-spec` or `awaiting-plan`. A failed agent or a timeout uses `needs-human`, as above.
+- **Later visits.** Once a `BLOCKED` or `needs-human` outcome is resolved (the baseline confirmed, a reviewer available, or a change request given), the next gate visit runs the review again from the start.
+
 ## Tracking
 
 Runs once, after the operator confirms the plan and before the build location is created. Skip it when `tracking` is `none`. Keys written in earlier attempts make each step idempotent, so a rerun picks up where it stopped. A re-plan keeps the keys already written: a line with a key is never ticketed again, and tickets for lines a re-plan removes are left as they are and reported.
@@ -604,6 +625,8 @@ The age rule is the same as Archive: by default only jobs whose `updatedAt` is m
 
 Dispatch with the paths block first, then the task line, then the role brief and the files to read. The task line names the mode when the agent has one (spec or plan for the spec writer; build, repair, or rework for the builder; the lens for a reviewer; approval for the approver).
 
+Every dispatch of the planner, builder, reviewers, and approver also passes the goal sources as text, not as paths alone: the confirmed original request and every explicit user amendment (see Fit review: Baseline first and Goal sources). This applies to first runs, reruns, repairs, rework, and resumes alike. If a job has no confirmed baseline, run the Baseline first procedure of Fit review before dispatching, and do not invent goals or omit these inputs. Reviewer findings passed as dispatch context are never goal sources.
+
 Factory adds no agents of its own. Each role runs on a native agent (`planner`, `implementer`, or `reviewer`), and the Factory rules for that role (outputs, evidence, verdict format, escalation triggers) live in its brief in this skill's `roles/` folder. Every dispatch tells the agent to read the matching brief first. The role brief overrides the dispatched agent's default output format and file-writing rules, and the first line of the reply must follow the brief.
 
 | Role | Native agent | Task line | Brief | Fresh context | Output |
@@ -641,7 +664,7 @@ The loop is the same in every harness. Use a parallel lens batch where the harne
 - **Timeout.** The default is 15 minutes per agent. The operator can set another value for one run by saying so in the request, for example `timeout 30 min`.
 - **A timed-out agent is never re-dispatched.** It may still be running, and a second run could write the same file. Stage `needs-human` with the reason "`<agent>` timed out after `<N>` min; it may still be running". For a spec or plan agent, also set `failed_stage`. Tell the operator to check the job folder and the build location, and to confirm the agent has stopped, before `/factory start` or `/factory rework`.
 
-**Single-session mode (Codex).** Codex has no agent files, so one session plays every role. The orchestrator switches roles one at a time. For each role it reads only that role's brief and input files, writes only that role's output (a reviewer or the approver returns its report, and you save it), and keeps the same write boundaries. The rule "never write code" applies per role: as orchestrator it writes only orchestrator files, and it writes code only as the builder, and only in the build location. Lenses run in order (stage A, then stage B). The security reviewer judges the diff, not the builder's account. A timed-out role is handled as above; a role that ends without its file is re-run once, then `needs-human`.
+**Single-session mode (Codex).** Codex has no agent files, so one session plays every role. The orchestrator switches roles one at a time. For each role it reads only that role's brief and input files, writes only that role's output (a reviewer or the approver returns its report, and you save it), and keeps the same write boundaries. The rule "never write code" applies per role: as orchestrator it writes only orchestrator files, and it writes code only as the builder, and only in the build location. Lenses run in order (stage A, then stage B). The security reviewer judges the diff, not the builder's account. A timed-out role is handled as above; a role that ends without its file is re-run once, then `needs-human`. Fit review is the exception: one session is not independent, so the spec and plan gates report `BLOCKED` instead (see Fit review).
 
 ## Limits
 

package/src/repo/.agents/skills/factory/roles/approve.md

@@ -4,7 +4,7 @@ You decide whether a job goes to merge or to a human. You are the approval gate
 
 ## Inputs
 
-- The whole job history: `spec.md` (feature folder, paths block), `build.md`, `rework-*.md` if any, every `round-*/review-*.md`, and the job's `job.json`.
+- The whole job history: `spec.md` and `plan.md` (feature folder, paths block), the goal sources in your dispatch (the original request, explicit amendments, and rework decisions, verbatim), `build.md`, `rework-*.md` if any, every `round-*/review-*.md`, and the job's `job.json`.
 - The final diff: `git -C <worktree> diff {{DEFAULT_BRANCH}}...factory/<id>`.
 - The project's `AGENTS.md` for test commands.
 
@@ -12,7 +12,7 @@ You decide whether a job goes to merge or to a human. You are the approval gate
 
 1. **Read the history.** Read everything listed above. Note any rework and what it asked for.
 2. **Final-round reviews.** Confirm every review in the latest round has `VERDICT: PASS`. If any is `CHANGES` or missing, the decision is `ESCALATE`.
-3. **Spot-check one acceptance criterion.** Pick at least one `AC-n` from `spec.md`. Verify it independently: run its check yourself in the build location, or read the code and the test that covers it. Do not trust the builder's evidence alone.
+3. **Spot-check one acceptance criterion.** Pick at least one `AC-n` from `spec.md`. Verify it independently: run its check yourself in the build location, or read the code and the test that covers it. Do not trust the builder's evidence alone. Also check the branch diff against `plan.md`'s steps and the goal sources: any change that hits the untraced-change trigger in step 5 is an escalation.
 4. **Dry-run merge.** Check for conflicts without changing anything:
    ```
    git -C <main checkout> merge-tree --write-tree {{DEFAULT_BRANCH}} factory/<id>
@@ -28,6 +28,7 @@ You decide whether a job goes to merge or to a human. You are the approval gate
    - Production data writes, including backfills and one-off scripts.
    - New dependencies (any added line in a manifest or lockfile).
    - Open product decisions: any `[PRODUCT DECISION]` item still in `spec.md`. Items the operator answered at the spec gate read `[DECIDED] <answer>` and do not escalate. `build.md` cannot settle a product decision.
+    - Untraced change: any changed file or behavior in the final diff that traces to neither an explicit user amendment or rework decision in your dispatch, nor an accepted spec requirement or plan step, and has no justified necessary implementation detail recorded in the round reviews. List each file and line. Drift is not a note: it escalates.
 6. **Decide.** `APPROVE` only if steps 2–4 pass and step 5 hits nothing. Otherwise `ESCALATE`.
 
 ## Output

package/src/repo/.agents/skills/factory/roles/review-code.md

@@ -4,7 +4,7 @@ You review one round of a job's branch for correctness, simplicity, reuse, conve
 
 ## Inputs
 
-- `spec.md` in the feature folder (paths block), and `build.md` in the job folder.
+- `spec.md` and `plan.md` in the feature folder (paths block), the goal sources in your dispatch (the original request and explicit user amendments, verbatim), and `build.md` in the job folder.
 - The branch diff: `git -C <worktree> diff {{DEFAULT_BRANCH}}...factory/<id>`.
 - `qa.md` at the paths block's `qa.md (absolute, build location)` line, if it exists: the builder's suggested manual checks. Use it for context only. It never changes your verdict.
 - Round `N > 1`: your own previous review, `round-<N-1>/review-code.md`. Check whether earlier blocking items were fixed, and say so.
@@ -19,6 +19,7 @@ Run each command the project documents in `AGENTS.md` from the build location: t
 Use the [requesting code review](../../requesting-code-review/SKILL.md) checklist for process. Then cover:
 
 - **Correctness:** logic, edge cases, error handling at boundaries, every acceptance criterion in `spec.md` covered by a test or check.
+- **Scope trace, both ways:** trace the branch diff to `spec.md`'s requirements and acceptance criteria, `plan.md`'s steps, and the goal sources in your dispatch. Every changed file or behavior must trace to a user-authorized goal (the original request or an explicit amendment), to an accepted requirement or planned step, or be a necessary implementation detail for a stated goal (name the goal). A requirement or planned step with no change is a gap. An untraced change with no such reason is scope drift and a blocking item.
 - **Simplicity:** use the [ponytail-review](../../ponytail-review/SKILL.md) lens. Flag reinvented standard library, speculative abstractions, and dead flexibility.
 - **Reuse:** the change should extend existing utilities rather than duplicate them.
 - **Conventions:** the project's `AGENTS.md` and `.claude/rules-snippets/` standards.

package/src/repo/.agents/skills/factory/roles/spec.md

@@ -6,7 +6,7 @@ You turn a feature request into a testable spec, and then into a plan. You are o
 
 Read these, in this order:
 
-1. The feature request in your prompt.
+1. The feature request in your prompt, and the goal sources the orchestrator passes in your dispatch: the original request, verbatim, and any explicit user amendments. The original request is the primary goal source. If a copy in the prompt differs from it, report the difference and follow the verbatim text.
 2. The project's `AGENTS.md` (conventions and commands).
 3. The existing code the feature touches. Inspect it. Do not write a spec or plan from the request alone.
 4. [Feature spec template](../../../../templates/feature-spec.template.md) for the section structure.
@@ -113,5 +113,7 @@ On a re-plan, keep each existing task line that still applies, with its T-number
 
 - A change note with `spec-<k>.md` or `plan-<k>.md` is the operator's request. Apply it, and keep everything else the operator already accepted.
 - When a change note answers a `[PRODUCT DECISION]` item, rewrite that item to start with `[DECIDED]` and the operator's answer, for example `[DECIDED] Free tier: 3 seats.`. Items the note does not answer stay `[PRODUCT DECISION]`. Never mark an item decided yourself.
+- Goal-fit findings passed in your dispatch are reviewer findings. They are not operator requests and not goal authority. Fix only the listed findings, in their sections, and write nothing else. Do not drop or narrow a goal to satisfy a finding. If a finding would need a goal changed, leave the goal as written and add it to Open Questions as a decision for the operator.
+- In plan mode, trace each step to an acceptance criterion, a requirement, or the request. A step no goal needs is out of scope. Implementation details a goal needs are fine without their own criterion.
 - Keep `spec.md` and `plan.md` free of tooling chatter. They are feature docs that merge with the code.
 - Do not modify code, tests, `build.md`, `job.json`, `qa.md`, or any file outside the feature folder. Your writes are `spec.md` (spec mode), or `plan.md` and `tasks.md` (plan mode), in the feature folder only.

package/src/repo/.claude/agents-snippets/implementer.md

@@ -19,7 +19,11 @@ You are an implementation specialist. Your job is to write production-quality co
 - Write tests alongside implementation
 - Use existing patterns and utilities — don't reinvent
 - Keep changes focused on the assigned task
-- If something is unclear, **ask** before proceeding
+- If the task is unclear in a way that changes what you build, **ask** before proceeding. Otherwise build the task as written.
+- **You build; you do not accept.** Your self-review and report are evidence for the orchestrator, not approval. An independent reviewer and the orchestrator decide.
+- Leave your changes uncommitted and do not tick tasks. Commit or tick only when your calling flow asks, and only after acceptance.
+- Report each acceptance criterion as `pass` with the command and its result, or `not verified` with the reason.
+- In repair mode, answer every blocking review item: fix it, or say in your report why it should stand.
 
 ## Output