nitm-ai-dev-toolkit 5.2.1 → 5.3.0

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
@@ -122,7 +153,7 @@ When a subagent stops on a model capacity, quota, session limit, or reset-wait f
 - **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, stop, report the blocker, and ask the user which model to use.
+- **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.

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
 

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/prompt-snippets/implement-feature.md

@@ -32,6 +32,7 @@ Implement a feature by completing tasks sequentially with proper tracking.
    - Group tasks by domain (backend, frontend, docs, tests)
    - Tasks that touch **different files with no shared state** → run their loops in parallel
    - Tasks with dependencies or shared files → keep sequential
+   - Tasks with an unknown or undeclared write set → keep sequential until the scope is established
    - Use `dispatching-parallel-agents` skill when 3+ independent tasks exist
 
 3. **Create Feature Branch** (before any build):
@@ -80,7 +81,7 @@ Implement a feature by completing tasks sequentially with proper tracking.
 
 6. **Create Pull Request** (only after the feature review is accepted):
 
-   a. **Final Validation**: the accepted verify results from step 5 (every required check ran and passed).
+   a. **Final Validation**: after all tasks are reconciled, run the project's full required regression checks once on the final integrated tree (implement.md step 3): the repo-defined full suite, lint, typecheck, and build, where they exist. Every required check must pass on this tree. Any edit after this run requires revalidation.
 
    b. **Commit and push**: if accepted feature-review changes are still uncommitted, commit them once, staging only the feature's paths, and skip the commit when nothing is staged. Do not create repair-only commits.
 

package/src/repo/.claude/prompt-snippets/implement.md

@@ -8,6 +8,7 @@ You are the orchestrator for this implementation. You derive the acceptance crit
 > with this loop. Do not route through a planning skill, and do not write a spec or plan first.
 > For 3+ independent `[P]` tasks that touch disjoint files, the loops may run concurrently with the
 > `dispatching-parallel-agents` skill. Each task still runs its own loop.
+> Nontrivial ad-hoc code changes outside these commands follow the same loop. Context-heavy nontrivial work may be built directly, but acceptance still needs an independent reviewer; without one it is BLOCKED. Trivial changes (typos, one-line edits) stay outside this loop.
 
 ## Roles
 
@@ -31,12 +32,12 @@ build → verify → review → decide ─┬─ accept   (review PASS, every re
 
 ### 1. Task, checks and baseline (orchestrator)
 
-- The original supplied task (request, task list entry, or fix description) is the requirement. Keep its text and give it to the builder and the reviewer unchanged. Do not require a new spec or plan first, and do not write one.
+- The original supplied task (request, task list entry, or fix description) is the requirement. Keep its text and give it to the builder and the reviewer unchanged. Explicit user amendments and answers given during the loop are part of the requirement too: record each one as a dated entry beside the original text (do not rewrite it), and give the builder and the reviewer the original text plus every amendment. Do not require a new spec or plan first, and do not write one.
 - Turn every requirement in the supplied task into an acceptance criterion, `AC-1`, `AC-2`, ... There is no fixed count: one criterion per requirement, however many there are. Do not add requirements the task does not state.
 - Each AC names its check. Discover the real checks; do not assume them. Read the project's manifests (for example `package.json` scripts, `Makefile`, `pyproject.toml`, `Cargo.toml`, `go.mod`), its CI configuration (for example `.github/workflows`), its README, and `AGENTS.md`. Use the commands the project actually runs.
 - A documentation criterion may be checked by direct inspection: open the file and confirm the content, and quote what you found as evidence.
-- A required check that cannot be discovered, or cannot be run, is a gap. It is not a pass, and it is not a bypass. Stop and ask the user for the command (see the Blocked exit in step 5).
-- Ask only when the task is unclear in a way that changes what gets built: two readings lead to different code, or a needed fact is missing. Ask one targeted question, offering the options, and wait.
+- A required check that cannot be discovered, or cannot be run, is a gap. It is not a pass, and it is not a bypass. It blocks acceptance of the affected task and of any aggregate run that needs it. Ask the user for the command as one targeted question and keep that question in the progress report. Independent tasks whose checks do not depend on the gap continue (see the Blocked exit in step 5).
+- Ask only when a requirement is unclear in a way that changes what gets built: two readings lead to different code, or a needed fact is missing. Ask one targeted question with its options. A task-scoped question blocks only that task and its dependents: independent tasks with clear requirements continue, and the question stays in the progress report (see [subagent-workflow.md](../rules-snippets/subagent-workflow.md), Autonomous Execution and Blockers). If the whole request is unclear, stop and ask before any build.
 - Take a baseline snapshot once, before any build. It is a plain copy of the state the task starts from, kept in a temporary directory outside the repository:
   - `git rev-parse HEAD`: the base commit.
   - `git status --porcelain > <tmp>/baseline/status.txt`: which files were already changed, staged or untracked.
@@ -59,6 +60,8 @@ build → verify → review → decide ─┬─ accept   (review PASS, every re
 
 Every round, run every check that covers an AC, using the commands from step 1. Treat the builder's report as a lead, not as evidence. For each AC, record `pass` with the command and result from this round, or `not verified` or `fail` with the reason. Docs criteria are recorded with the quoted content.
 
+Checks are scoped: each repair and each task runs the checks for its own ACs. After all writers are reconciled, run the project's full required regression checks once: the repo-defined full suite, lint, typecheck, and build, where they exist. Use only commands the project defines; do not invent them. A failed required check is a repair. A required check that does not exist or cannot run is BLOCKED (see step 5).
+
 ### 4. Review (reviewer, read-only)
 
 Every round, after verify, dispatch the reviewer on the current working tree. Give it the original supplied task text, the AC list, this round's check results, the base commit, and the baseline snapshot. Its review scope covers the whole task, and it compares content, not patches:
@@ -74,6 +77,7 @@ The reviewer's rules:
 - The first line of the reply is exactly `VERDICT: PASS` or `VERDICT: CHANGES`.
 - `VERDICT: CHANGES` needs at least one blocking item, each with `file:line`, the problem, and the specific fix. Blocking means a correctness issue, a failing check, a requirement with no test or evidence, or a clear convention break. Taste goes in non-blocking notes.
 - Check each requirement of the original task, not only the diff. A requirement with no coverage is a blocking item.
+- Scope drift, both ways: trace the diff against the original supplied task. A change that no requirement needs is a blocking item unless the reviewer confirms it is a necessary implementation detail for a stated goal and says why. Goals are the original supplied task plus the user amendments recorded in step 1: do not require or assume a spec or plan (supplied-task exception). Simplicity and SRP notes stay non-blocking unless they add scope the task does not ask for.
 
 ### 5. Decide (orchestrator)
 
@@ -81,11 +85,13 @@ Pick one outcome per round:
 
 - **Repair (back to step 2):** the review is `VERDICT: CHANGES`, **or** any AC is `not verified` or `fail`, **or** a required check failed or did not run. Send the open items to the builder, then run steps 3, 4 and 5 again on the current tree.
 - **Accept (exit):** all of these hold on this round's verify and review: the review is `VERDICT: PASS`; every requirement has an AC marked `pass` with evidence from this round; every required check ran and passed; an independent reviewer produced the verdict; and the builder did not report `BLOCKED`. Then report `ACCEPTED` with the AC evidence. A review PASS alone never accepts.
-- **Blocked (exit):** the builder reports `BLOCKED`, or a required check cannot be discovered or run, or no independent reviewer is available. Stop, report `BLOCKED` with the blocker and what would unblock it. Never mark blocked work accepted.
-- **Needs user decision (exit):** the task is unclear in a way only the user can settle. Stop, report `NOT ACCEPTED: needs decision` with the question. This is not acceptance.
+- **Blocked (exit for the affected work):** the builder reports `BLOCKED`, a required check cannot be discovered or run, or no independent reviewer is available. Report `BLOCKED` with the blocker and what would unblock it. Never mark blocked work accepted. Work that depends on it stops; independent authorized work with its own checks and reviewer continues. Without an independent reviewer nothing is accepted, but discovery and builds that do not need acceptance may continue and be reported as awaiting review. Stop the run only when no authorized work remains or a mandatory approval, security, or permission gate applies.
+- **Needs user decision (exit for the affected work):** the task is unclear in a way only the user can settle. Stop work on that task and its dependents, report `NOT ACCEPTED: needs decision` with the question, and continue independent authorized work. This is not acceptance.
 
 No other exit exists. An unmet requirement, a failing check, or a `not verified` result always loops back to repair. There is no round limit to escape the loop.
 
+**Evidence freshness.** Acceptance uses evidence from the tree it accepts. Any edit after a verify or review, whether by the builder, a repair, or the orchestrator, invalidates the evidence it affects: rerun the checks covering those ACs and re-review the changed diff. Reuse evidence that the edit cannot affect. If unsure whether an edit affects a check, treat it as affected. Do not rerun everything for an unrelated edit.
+
 ### Commit (only when the calling flow asks)
 
 The loop never commits by itself. Accepting reports the result; it does not create a commit. The calling command decides whether accepted work is committed, and only when its own flow says so and the user has not asked otherwise. When it does commit:
@@ -95,13 +101,15 @@ The loop never commits by itself. Accepting reports the result; it does not crea
 
 ### Limits
 
-- **No independent reviewer means BLOCKED.** The orchestrator may run its own verify and report the evidence, but it cannot accept the work on its own review. Report `BLOCKED`, and stop.
+- **No independent reviewer means nothing is accepted.** The orchestrator may run its own verify and report the evidence, but it cannot accept the work on its own review. Report `BLOCKED` for acceptance. Do not treat all work as blocked when independent discovery or build can proceed (see the Blocked exit in step 5).
+- Mandatory approval, security, and permission gates are never bypassed. They apply to the affected work, or to the whole run when the gate is global.
 - A self-review is never presented as an independent review.
+- These gates are prompt instructions, not host enforcement. Resuming after a pause depends on the host; this prompt does not guarantee automatic resume.
 
 ## Your Task
 
 1. **Analyze**: identify the files to create or modify, the dependencies between tasks, and the `[P]` tasks.
-   Dispatch `[P]` tasks in parallel only when they touch different files with no shared state. Otherwise keep them sequential.
+   Dispatch `[P]` tasks in parallel only when they touch different files with no shared state. Otherwise keep them sequential. A task whose write set is unknown or undeclared runs serially until the builder's changed-file list establishes its scope.
 2. **Run the delivery loop** for each task, in dependency order, until it exits as accepted, blocked, or needs a user decision.
 3. **Track progress**: tick a task only after the orchestrator accepts it. Report blockers and summarize the accepted changes.
 

package/src/repo/.claude/prompt-snippets/plan.md

@@ -55,8 +55,8 @@ Plan how to implement the supplied feature or requirement; a prior specification
    - `docs/features/{{ISSUE_ID}}-{{FEATURE_NAME}}/api-contract.md` - API specifications
 
 5. **Review and Accept Planning Artifacts**:
-   - The orchestrator dispatches an independent, read-only reviewer with the original request, requirements/context, plan and any additional artifact paths. Review the actual artifacts for completeness, dependencies/order, actionability, and coverage of the request; return `VERDICT: PASS` or `VERDICT: CHANGES` with blocking findings and section references.
-   - Repair blocking findings within the agreed scope, repeat affected artifact checks, and re-review the changed artifacts independently. Repeat until PASS or blocked; unresolved decisions go to the user.
+   - The orchestrator dispatches an independent, read-only reviewer with the original request, requirements/context, plan and any additional artifact paths. Use the goal-fit brief (read and follow [fit-review](../rules-snippets/fit-review.md)): Oracle when available read-only, otherwise a separate reviewer; the author's self-review does not count. Review the actual artifacts for completeness, dependencies/order, actionability, and coverage of the request, and trace goals and plan items both ways. Return `VERDICT: PASS` or `VERDICT: CHANGES` with blocking findings and section references. A finding that needs a user decision is blocking, marked `requires user decision; do not auto-repair`; stop and ask the user.
+   - Repair blocking findings within the agreed scope, repeat affected artifact checks, and re-review the changed artifacts independently. Repeat until PASS or blocked, or until the user decides. Stop as BLOCKED with the reason when a repair changes nothing or the same finding returns unchanged. A goal change from the review is a user decision, not a repair. Open decisions block PASS until the user resolves them.
    - Only the orchestrator accepts, after an independent PASS and evidence for every requirement and applicable artifact check. If an independent reviewer is unavailable, report BLOCKED; self-review cannot substitute for independent acceptance.
    - This is a lightweight artifact review, not a code build loop: do not implement the plan, run runtime build/TDD/git procedures, or add commit, push, or apply steps. Keep any required human approval separate from artifact acceptance.
 

package/src/repo/.claude/prompt-snippets/specify.md

@@ -65,12 +65,19 @@ Start a new feature by creating a specification. This is the first step in the d
    - [ ] [Questions needing clarification]
    ```
 
-5. **Create Git Branch** (optional):
+5. **Review and Accept the Specification**:
+   - Dispatch an independent, read-only reviewer with the original request (verbatim, with any later user amendments), the feature description, any intake answers, and `spec.md`. Use the goal-fit brief (read and follow [fit-review](../rules-snippets/fit-review.md)): Oracle when available read-only, otherwise a separate reviewer; the author's self-review does not count.
+   - The reviewer traces requirements and acceptance criteria both ways against the original request, checks that each criterion is testable, and returns `VERDICT: PASS` or `VERDICT: CHANGES` with blocking findings and section references. A finding that needs a user decision is blocking, marked `requires user decision; do not auto-repair`; stop and ask the user.
+   - Repair blocking findings within the agreed scope, repeat the affected checks, and re-review the changed spec independently. Repeat until PASS or blocked, or until the user decides. Stop as BLOCKED with the reason when a repair changes nothing or the same finding returns unchanged. A goal change from the review is a user decision, not a repair. Open decisions block PASS until the user resolves them.
+   - Only the orchestrator accepts, after an independent PASS. If an independent reviewer is unavailable, report BLOCKED; self-review cannot substitute for independent acceptance.
+   - Acceptance is separate from human approval: the human still confirms the spec.
+
+6. **Create Git Branch** (optional):
    ```bash
    git checkout -b feature/{{FEATURE_NAME}}
    ```
 
-6. **Report Completion**:
+7. **Report Completion** only after artifact acceptance:
    - Feature directory path
    - Spec file path
    - Branch name (if created)