nitm-ai-dev-toolkit 5.2.1 → 5.3.0

package/CHANGELOG.md

@@ -7,19 +7,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [5.3.0] - 2026-11-14
+
+Retirement/relevance and wrapper-audit entries below were already shipped in 5.2.0.
+
 ### Added
 
+- A lightweight copy-paste universal installation prompt at the top of the README, pointing to full instructions in `INSTALL.md` for Claude Code, Codex, Replit, Lovable, and other AI coding tools. It reuses the CLI and bootstrap handoff, preserves existing configuration, and reports hosted-tool capability and activation limits.
 - `.nitm/retired.json`: a project-owned list of template paths that `install`, `patch` and `upgrade` must never re-add. Matching is exact and case-sensitive (`AGENTS.md` is not `agents.md`); `./`, doubled and inner `/` are normalised, and `..` or absolute paths are refused. Each entry has a `path`, a `reason` and a `date` (YYYY-MM-DD); a directory path covers every file under it. An optional `trackers` list overrides tracker detection (`[]` for none). The CLI reads this file and never writes it; invalid JSON stops `install`, `patch`, `upgrade` and `doctor` before anything is written, and for `upgrade` that includes the saved selection.
 - `bin/relevance.js` holds the retirement, project-detection, relevance and thin-wrapper logic. Tests: `test/relevance.test.js` and `test/relevance-patch.test.js`.
 - `scripts/check-parity.sh` fails when a bootstrap-facing file recommends a wildcard skill install (`skills add … --skill '*'`).
 
 ### Changed
 
+- Planning and Factory artifacts receive an independent goal-fit review before acceptance: Oracle when available, otherwise a read-only reviewer. Reviews check scope against user-approved goals, apply Ponytail simplicity guidance and proportional SOLID/SRP checks, and repeat after revisions or resumption. Human approval remains separate; missing independent review blocks acceptance.
+- Single-session Factory role switching, including Codex fallback, no longer satisfies spec/plan acceptance: an independent reviewer is required. Missing original requirements require operator confirmation of a recovered baseline.
+- Legacy Factory jobs without a confirmed requirements baseline pause before their next build, review, or approval dispatch for operator confirmation; their current stage is preserved.
+- Orchestration guidance defaults to delegation and dependency-aware parallel batches with exclusive writer scopes. Coordinators reconcile results, preserve resume checkpoints, and explicitly report completion, waiting, or blockers instead of silently stopping. These are prompt-level safeguards, not host recovery guarantees.
+- Lightweight swarm-style safeguards reuse existing delivery loops for non-trivial ad-hoc work, invalidate affected evidence after edits, require applicable integrated checks on the final tree, and serialize unknown write scopes. No plugin, additional agent, runtime gate, or configuration is added.
 - `create-skill`, `constitution`, `plan`, and `bootstrap-patch` gain scoped independent artifact review → repair → re-review → orchestrator acceptance gates; missing reviewers block acceptance, and human approval remains separate. Plan review checks the planning artifacts, not a code build loop.
 - `patch` and `upgrade` classify every template file against the project before writing: **add** (missing and applicable), **update** (unchanged since the toolkit wrote it, and the template changed), **current**, **needs review** (locally changed, or undecided relevance), **not relevant**, and **retired**. The plan prints, with a reason for each entry, before anything is written.
 - Relevance comes from the project. Tracker CLI skills follow the git `origin` host (GitHub, GitLab, Bitbucket) or the `trackers` list; `playwright-test` follows Playwright; `prisma-migrations` follows Prisma; `component-structure` and `ui-accessibility` follow a UI framework; the empty MCP templates are not added. When the tracker cannot be detected, tracker skills are held for review rather than guessed.
 - `patch` never overwrites a locally changed file, even with `--force`; it reports the file under needs review. `upgrade` without `--force` behaves the same. `upgrade --force` runs `install --force`, which does overwrite locally changed files. `patch` and `upgrade` update only files the toolkit wrote and the project has not changed since (manifest hash).
-- `upgrade` reads `.nitm/retired.json` before the npm lookup and before any write. While that file has entries or a `trackers` override, it refuses targets older than 5.2.0, the planned release that first honours the file, because older targets would ignore it and re-add retired paths. `RELEVANCE_MIN` in `bin/cli.js` holds that version and must match the release that ships this change.
+- `upgrade` reads `.nitm/retired.json` before the npm lookup and before any write. While that file has entries or a `trackers` override, it refuses targets older than 5.2.0, the first release that honours the file. `RELEVANCE_MIN` in `bin/cli.js` holds that version.
 - `doctor` is read-only. It counts only applicable files as missing, lists retired paths separately, lists present files that do not apply as retirement candidates, lists undecided files, and lists harness wrappers that inline policy.
 - `install` also honours `.nitm/retired.json`: a retired path is never written, including with `--force`.
 - Thin-wrapper policy in the bootstrap, patch and upgrade prompts: policy lives only in `.claude/{rules,prompt,agents}-snippets/`; a wrapper is a link, a title, at most five key points and one short summary line; an Agent Dispatch table is activation metadata. Patch and upgrade report wrappers that inline policy or diverge from their snippet and propose moving the content into the snippet. Copilot instruction creation writes the policy to a snippet first and then a thin wrapper.
@@ -30,6 +40,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `implement`, `implement-feature` and `implement-fixes` (repo and monorepo) share one delivery loop in `prompt-snippets/implement.md`: the orchestrator sets acceptance checks, a builder builds, a read-only reviewer returns `VERDICT: PASS` or `VERDICT: CHANGES`, and only the orchestrator accepts. Builders no longer accept or tick their own work. Feature and fixes flows review before committing or pushing. Claude commands allow `Task` and Copilot prompts grant `agent` so the orchestrator can dispatch. The loop repeats (build, verify, review, decide) until accepted, blocked, or a user decision is needed; there is no round limit. Acceptance needs a `VERDICT: PASS` from an independent reviewer and evidence for every requirement and required check; a missing reviewer, an undiscoverable check or a blocker stops the loop as BLOCKED. Review compares each file with a saved baseline snapshot (tracked changes via `git diff --binary HEAD`, preexisting files via their saved copies), reads new untracked files, and uses the merge-base diff for features. Accepting only reports; a commit happens only where the calling flow asks, and stages just the accepted paths. `AGENTS.md` and the documentation checklist carry a narrow supplied-task exception: these commands do not require spec or plan documents. Fixes initialize the branch and baseline before one builder reproduces the bug. The generic and feature prompts no longer invoke `subagent-driven-development`. No spec or plan is required before a build. Tests: `test/implement-loop.test.js`.
 - Subagent workflow (`.claude/rules-snippets/subagent-workflow.md`, repo and monorepo) gains a model capacity fallback: when a subagent stops on a capacity, quota or reset-wait failure, it keeps the same agent and tries the configured fallback models once each, then stops and reports. Covered by `test/model-capacity-fallback.test.js`.
 
+- Autonomous execution continues independent work within the approved goal and permissions. A blocker pauses only its task and dependents: it is recorded as a visible follow-up question, and non-global questions are deferred. The agent stops only when no authorized progress remains or a required gate prevents it, then asks one consolidated set of questions through the harness's native question tool, or in chat when none exists. Existing approvals and gates are unchanged.
+
 ### Fixed
 
 - Feature delivery loops initialize task-local requirements, acceptance criteria and checks before each task, reserving the full feature criteria for aggregate review. Requirement-only plans retain requirements and acceptance criteria for `/tasks` and `/assign-tasks` when no specification exists, in both template layouts.

package/README.md

@@ -14,6 +14,21 @@ This repository serves as a **template source** for AI development instructions
 - **Native Codex setup** using `AGENTS.md`, `.agents/skills/`, and an optional comment-only `.codex/config.toml`
 - **Skills recommendations** from [skills.sh](https://skills.sh/) for enhanced AI capabilities
 
+## Quick start: paste into your AI tool
+
+Open your project in Claude Code, Codex, Replit, Lovable, Cursor, Copilot, OpenCode, or another AI coding tool and paste the prompt below. No toolkit slash command is needed.
+
+```text
+Install and configure the NITM AI-Assisted Development Toolkit in this project.
+Read and follow the installation instructions at:
+https://github.com/ninjasitm/ai-assisted-dev-toolkit/blob/main/INSTALL.md
+If you cannot access that file, ask me to paste its contents before proceeding.
+```
+
+Full instructions, prerequisites, and hosted-tool limitations: [INSTALL.md](INSTALL.md).
+
+For manual copying instead, see [Usage](#usage). For installer options and existing installations, see [CLI (npx)](#cli-npx).
+
 ## Repository Structure
 
 ```
@@ -574,6 +589,11 @@ The coordinator decides when to delegate. You don't need to manually invoke suba
 | **Frontend Developer** | Domain      | read, search, edit, terminal | `true`           | UI components and frontend performance        |
 
 **Coordinator agents** (Feature Builder, TDD) appear in the agents dropdown and orchestrate worker agents.
+
+For substantial work, coordinators delegate by default and dispatch ready, independent tasks in parallel batches with exclusive writer scopes. They reconcile results before dependent work and report whether execution is complete, waiting, or blocked, including the next action. Resume checkpoints preserve progress without replacing approved requirements. Background continuation depends on the host; these instructions cannot recover a crashed or disconnected session.
+
+Lightweight swarm-style safeguards reuse the existing agents and delivery loop, including non-trivial ad-hoc code changes. Unknown write scopes run serially. Edits invalidate affected checks and review evidence; acceptance needs current evidence and independent approval, plus applicable project-defined integrated checks on the final tree. These gates are instructions, not runtime enforcement. No Swarm plugin or additional configuration is installed.
+
 **Worker agents** (`user-invocable: false`) are only accessible as subagents — they don't appear in the dropdown.
 **Domain agents** (Admin Portal, API Specialist, Backend Architect, Documenter, Frontend Developer) are user-invocable specialists for specific development domains.
 **Researcher** is both user-invocable and usable as a subagent.
@@ -709,6 +729,10 @@ It runs alongside Feature Builder and TDD and does not replace them. Nothing run
 
 **Two gates are mandatory.** Every job stops at `awaiting-spec` after the spec, and at `awaiting-plan` after the plan. At the spec gate you confirm the spec or request changes. At the plan gate you review the tasks, the size, the tracking proposal, and the build mode, then confirm or request changes. Leave either gate for later with `/factory start <job-id>`. Nothing is ticketed or built before you confirm the plan.
 
+Before these approvals, an independent, read-only Oracle (when available) or reviewer assesses goal fit, scope, unnecessary complexity, and proportional SOLID/SRP concerns. `/plan` and `/specify` use the same assessment. Changed or resumed artifacts are reassessed; unresolved findings or unavailable independent review block acceptance, not discussion with the user. Review never substitutes for your approval or authorizes extra scope.
+
+Single-session role switching, including the Codex fallback, cannot satisfy independent goal-fit review: those gates stay blocked until an independent reviewer is available.
+
 **The builder also writes `qa.md`.** It lists how to run the feature, numbered manual checks tied to the acceptance criteria, and what the automated tests do not cover. The orchestrator shows it before approval as suggested checks. It is not a gate.
 
 **The approval gate is on by default.** With `{{APPROVAL_MODE}}` set to `human`, an approved job stops at `awaiting-human` until you run `/factory approve <job-id>`. Set `{{APPROVAL_MODE}}` to `auto` to merge on approval instead. The approver still escalates changes to auth, payments, migrations, and similar high-risk areas. Merges are local, and the factory never pushes.

package/bin/cli.js

@@ -121,7 +121,7 @@ const KNOWN_HISTORICAL = {
 const DRY_RUN_UPGRADE_MIN = '5.0.1';
 // First release whose patch and install honour .nitm/retired.json and the relevance plan. Upgrade refuses
 // older targets while that file has entries or a tracker override, because those targets would ignore it.
-// Set to the version that ships this change; keep in step with the CHANGELOG [Unreleased] release.
+// First supported release: 5.2.0.
 const RELEVANCE_MIN = '5.2.0';
 const VERSION_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nitm-ai-dev-toolkit",
-  "version": "5.2.1",
+  "version": "5.3.0",
   "description": "Scaffold AI agent config (Cursor, GitHub Copilot, Claude Code, OpenCode, Codex) into any repo, then hand off to your AI agent to finish setup.",
   "bin": {
     "nitm-ai-dev-toolkit": "bin/cli.js"

package/src/monorepo/.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/monorepo/.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/monorepo/.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/monorepo/.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`, the `AGENTS.md` of each affected app or package, and `.claude/rules-snippets/` standards.

package/src/monorepo/.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. The `AGENTS.md` of each affected app or package, for its patterns and commands.
@@ -115,5 +115,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.
 - Name every affected app and package in the plan's Steps and in the spec's Affected Code (`apps/<app>/...` or `packages/<pkg>/...`). If a shared package changes, list its downstream consumers too, so the build and reviews test them.
+- 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/monorepo/.claude/prompt-snippets/implement-feature.md

@@ -30,6 +30,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):
@@ -77,7 +78,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/monorepo/.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/monorepo/.claude/prompt-snippets/plan.md

@@ -44,8 +44,8 @@ You are helping to create an implementation plan for a feature or requirement.
    - List any open questions or decisions needed
 
 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/monorepo/.claude/prompt-snippets/specify.md

@@ -18,8 +18,15 @@ You are helping to create a feature specification based on the user's descriptio
    - Use the template structure below
    - Be specific and actionable
 
-4. **Output**:
-   - Confirm specification created
+4. **Review and Accept the Specification**:
+   - Dispatch an independent, read-only reviewer with the original request (verbatim, with any later user amendments), the feature description, 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.
+
+5. **Output** (only after artifact acceptance):
+   - Confirm specification created and accepted
    - Summarize key requirements
    - Suggest next step: `/plan` to create implementation plan
 

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.
+```