nitm-ai-dev-toolkit 5.2.0 → 5.3.0

package/CHANGELOG.md

@@ -7,18 +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.
@@ -26,8 +37,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Bootstrap skill cleanup and the upgrade steps retire by recording in `.nitm/retired.json` rather than deleting. Deleting a skill directory needs separate approval and a backup.
 - Upgrade pre-commit hook: installed only with approval, in a git repository, and never over an existing `.git/hooks/pre-commit`. Project hooks (plugin-only, `${CLAUDE_PLUGIN_ROOT}`) are copied only with approval, and existing files are skipped.
 
+- `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.
 - `.opencode/commands/review-staged.md` (repo and monorepo) had lost its link to `.claude/prompt-snippets/review-staged.md`. It is a thin wrapper with the link again.
 
 ### Migration

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.0",
+  "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/agents-snippets/implementer.md

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

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

@@ -1,6 +1,6 @@
 ---
 description: Patch AI instructions by fetching updates from the toolkit repo and applying new/updated/missing guidance
-allowed-tools: "Read, Write, Edit, Bash(*)"
+allowed-tools: "Read, Write, Edit, Bash(*), Task"
 argument-hint: optional patch options
 ---
 
@@ -10,6 +10,6 @@ argument-hint: optional patch options
 | Agent | When to use |
 |-------|-------------|
 | `fixer` | Standard patch — incremental changes to existing config |
-| `planner` | Complex patch — cross-cutting changes needing analysis first |
+| `reviewer` | Independent read-only review before approval and after apply |
 
 Follow the prompt defined in [.claude/prompt-snippets/bootstrap-patch.md](../prompt-snippets/bootstrap-patch.md).

package/src/monorepo/.claude/commands/constitution.md

@@ -1,7 +1,7 @@
 ---
 description: Create or update the project constitution defining core principles and guidelines
 argument-hint: "no arguments required"
-allowed-tools: "Read, Write, Edit, Bash(*)"
+allowed-tools: "Read, Write, Edit, Bash(*), Task"
 ---
 
 # Project Constitution

package/src/monorepo/.claude/commands/create-skill.md

@@ -1,6 +1,6 @@
 ---
 description: Create a new agent skill following VS Code and agentskills.io specifications
-allowed-tools: "Read, Write, Edit, Bash(*)"
+allowed-tools: "Read, Write, Edit, Bash(*), Task"
 argument-hint: "skill name and requirements"
 tags: [skill-creation, agent-skills, documentation, automation]
 version: 1.0.0

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

@@ -1,6 +1,6 @@
 ---
 description: Implement a feature by completing tasks sequentially
-allowed-tools: "Read, Write, Edit, Bash(*)"
+allowed-tools: "Read, Write, Edit, Bash(*), Task"
 argument-hint: feature specification or task list
 ---
 
@@ -10,6 +10,6 @@ argument-hint: feature specification or task list
 | Agent | When to use |
 |-------|-------------|
 | `fixer` | Bounded feature work — spec is clear, files are known |
-| `feature-builder` | Complex feature — needs research, planning, and coordination |
+| `feature-builder` | Complex feature build — builder only; the orchestrator still runs the review |
 
 Follow the prompt defined in [.claude/prompt-snippets/implement-feature.md](../prompt-snippets/implement-feature.md).

package/src/monorepo/.claude/commands/implement-fixes.md

@@ -1,6 +1,6 @@
 ---
 description: Implement bug fixes with proper tracking and validation
-allowed-tools: "Read, Write, Edit, Bash(*)"
+allowed-tools: "Read, Write, Edit, Bash(*), Task"
 argument-hint: "bug description or fix requirements"
 ---
 

package/src/monorepo/.claude/commands/implement.md

@@ -1,7 +1,7 @@
 ---
 description: Execute implementation tasks from a task list or specification
 argument-hint: "task list or specification"
-allowed-tools: "Read, Write, Edit, Bash(*)"
+allowed-tools: "Read, Write, Edit, Bash(*), Task"
 ---
 
 # Execute Implementation Tasks

package/src/monorepo/.claude/commands/plan.md

@@ -1,6 +1,6 @@
 ---
 description: Create an implementation plan from a feature specification or requirement
-allowed-tools: "Read, Write, Edit, Bash(*)"
+allowed-tools: "Read, Write, Edit, Bash(*), Task"
 argument-hint: feature specification or requirement
 ---
 

package/src/monorepo/.claude/prompt-snippets/assign-tasks.md

@@ -47,6 +47,7 @@ When interacting with {{ISSUE_TRACKER}}, use MCP tools first (see the `issue-tra
 
 1. **Parse Document**:
    - Load the specified document (.md, .txt, .json)
+   - For `tasks.md`, load sibling `spec.md` when present; otherwise load sibling `plan.md` under **Requirements Source** and **Acceptance Criteria** as the requirements source. For a requirement document supplied directly, use its requirements and acceptance criteria. If the source or criteria are missing or unclear, ask the user before creating tickets; do not require creating a specification.
    - Detect document structure (headers, lists, task categories)
    - For `tasks.md`, detect the format first:
      - **Slim** (has `- [ ] T<n>` or `- [x] T<n>` lines): each such line is one task. The text after the ID is the summary. Sub-bullets, if any, are subtasks. A line already has a ticket only when it ends with ` — {{PROJECT_KEY}}-<digits>`; skip it then. Any other ` — ` suffix (e.g. ` — depends on T3`) is a note, not a key: keep the line
@@ -70,7 +71,7 @@ When interacting with {{ISSUE_TRACKER}}, use MCP tools first (see the `issue-tra
    - **Task**: Implementation work, 2-8 story points (avoid < 2 SP tasks)
    - **Subtask**: Only for complex tasks needing breakdown, 1-3 story points
 
-4. **Estimate Effort** (`tasks.md` has no effort field: take hours from `plan.md` for the matching work, or estimate from the scope in `spec.md`):
+4. **Estimate Effort** (`tasks.md` has no effort field: take hours from `plan.md` for the matching work, or estimate from the selected requirements source):
    - 0.5-1 hours → Merge with related task (too small alone)
    - 2-3 hours → 2 story points
    - 4-6 hours → 3-5 story points
@@ -82,7 +83,7 @@ When interacting with {{ISSUE_TRACKER}}, use MCP tools first (see the `issue-tra
    - Link child issues to parents
    - Set assignees, labels, and story points
    - Create dependency links where noted
-   - Ticket description: the task summary plus the acceptance criteria from `spec.md` for that deliverable
+   - Ticket description: the task summary plus the acceptance criteria from the selected requirements source for that deliverable (`spec.md` when present, otherwise `plan.md` for a task checklist, or the directly supplied requirement document). Preserve the original criteria and constraints; include a source path/issue key and section reference. Do not copy acceptance criteria into `tasks.md`.
    - **Slim `tasks.md`**: append ` — <KEY>` at the end of the task's line, after any notes (`- [ ] T1 Schema + migration — PROJ-124`)
    - **Legacy `tasks.md`**: never write back. Record heading → ticket key in the report instead
 

package/src/monorepo/.claude/prompt-snippets/bootstrap-patch.md

@@ -184,26 +184,28 @@ The CLI runs the same patch flow without an AI session: `npx nitm-ai-dev-toolkit
 
     ### Summary
 
-    - **Auto-apply**: X add + Y update entries, as printed by `patch`
+    - **Apply after review and user approval**: X add + Y update entries, as printed by `patch`
     - **Review needed**: Z needs-review files and W wrapper proposals
     - **Not written**: N not-relevant or retired entries
     - **No action**: W files already current
     ```
 
-5.  **Confirm and Apply**:
+    **Independent review loop (before approval/apply, including dry-run):**
+    - The orchestrator derives acceptance checks from the user's request and the safeguards above; no new spec, plan, persistent state, or configuration is required. The patch author prepares/repairs the proposal and reports evidence, but cannot approve its own work.
+    - The orchestrator dispatches an independent read-only `reviewer` (or available read-only agent), not the patch author or its self-review. Give it the original request, target/source version evidence, current project files, proposed diffs/report (including merges and removals), and check results. Review scope, relevance/retirement decisions, preserved customizations, trust/version gates, and backup/approval requirements.
+    - The reviewer returns `VERDICT: PASS` or `VERDICT: CHANGES`; each blocking finding names the file, problem, and required repair. Send findings or failed checks back to the patch author, repair the proposal, verify it, and re-review the revised proposal. Repeat until PASS or BLOCKED; never proceed merely because a round limit was reached.
+    - Only the orchestrator accepts the proposal, after independently inspecting the evidence for every acceptance check and the current review PASS. A reviewer PASS alone is not acceptance and never replaces user approval. If an independent reviewer or required evidence/check is unavailable, report **BLOCKED** with what would unblock it; do not apply or claim completion.
+
+5.  **Confirm and Apply** (only the accepted proposal):
     - If `--dry-run` flag: Output the report without making changes
-    - Otherwise: Present the report and ask the user to confirm with (Y/n)
+    - Otherwise: Present the reviewed report and ask the user to confirm with (Y/n). Before writes, back up affected existing files/config and confirm the source, project state, and patch still match the reviewed proposal; if they changed, regenerate and repeat review and user approval. Apply only approved changes.
     - On confirmation:
       a. **Add and update**: run `npx nitm-ai-dev-toolkit patch`. It writes only the add and update entries it printed; do not copy template files by hand
       b. **Retirements**: after approval, record each path in `.nitm/retired.json` with a reason and date. Do not delete files to retire them
-      c. **Needs review**: propose a merge per file (structural additions, preserved project values) and apply it only after the operator approves that file. Wrappers that inline policy: propose moving the content into the snippet and reducing the wrapper to a thin link (see Thin Wrapper Policy in `bootstrap.md`)
+      c. **Needs review**: include each proposed merge (structural additions, preserved project values) in Step 4's report and independent review, and apply it only after the operator approves that file. Wrappers that inline policy: propose moving the content into the snippet and reducing the wrapper to a thin link (see Thin Wrapper Policy in `bootstrap.md`)
       d. **OpenCode plugins**: Apply only the approved obsolete Ponytail cleanup above after backing up the known obsolete toolkit copies and local config; preserve all unrelated local/global plugins. Never add Ponytail to project config.
       e. **Toolkit version**: Keep the `.toolkit-version` value the CLI writes for the verified target version (the installed package version, 4.0.0 or later; never hard-coded) only after the approved migration and OpenCode preflight pass (or OpenCode is confirmed out of scope).
-      f. **Git commit**: Stage and commit all changes with message:
-      ```bash
-      git add -A
-      git commit -m "chore: patch AI instructions from toolkit [$(date +%Y-%m-%d)]"
-      ```
+      f. **Git commit**: Do not auto-commit. Only if the user explicitly requests a commit, and only after Step 7 acceptance, stage just this patch's approved paths; never stage unrelated changes.
 
 6.  **Cleanup**:
 
@@ -215,6 +217,9 @@ The CLI runs the same patch flow without an AI session: `npx nitm-ai-dev-toolkit
     - Verify no `{{PLACEHOLDER}}` syntax was accidentally re-introduced
     - Confirm all files are valid (no broken frontmatter, no syntax errors)
     - List any new placeholders that need manual `bootstrap` to fill
+    - Inspect the actual applied diff/files against the approved proposal and backups: verify preserved project values/config, relevance/retirements, approved merges/removals, and the target version marker. Run the applicable syntax/frontmatter checks and report commands/results, not assumed runtime validation.
+    - Dispatch the independent read-only reviewer on the actual applied outcome, approval scope, and validation evidence using the same verdict contract above. On findings or failed checks, repair only within the approved scope, rerun validation, and re-review; any new/unapproved change must return through proposal review and user approval before writes.
+    - Only the orchestrator reports **ACCEPTED** when the current outcome has review PASS and verified evidence for every acceptance check. Missing reviewer/evidence means **BLOCKED**, never completion. For `--dry-run`, accept only the reviewed preview and explicitly report that nothing was applied or post-apply verified. Acceptance never authorizes extra writes, deletions, or a commit.
 
 ## Smart Merge Strategy
 
@@ -239,4 +244,4 @@ When a file has been bootstrapped (placeholders replaced with real values), the
 - **Non-destructive by default**: Always show changes before applying
 - **Preserve customizations**: Never lose project-specific configuration
 - **Incremental**: Only apply what's changed, don't re-bootstrap everything
-- **Auditable**: Commit message includes date for tracking patch history
+- **Auditable**: Report approved paths, review verdicts, and verification evidence; commit only on explicit request

package/src/monorepo/.claude/prompt-snippets/constitution.md

@@ -2,7 +2,7 @@ You are helping to create or update the project constitution at `docs/constituti
 
 ## Your Task
 
-1. **Load existing constitution** (if it exists) at `docs/constitution.md`.
+1. **Load existing constitution** (if it exists) at `docs/constitution.md`. Retain its original content for comparison during review.
 
 2. **Collect project information**:
    - Project name and description
@@ -25,6 +25,12 @@ You are helping to create or update the project constitution at `docs/constituti
 
 5. **Save** the constitution to `docs/constitution.md`.
 
+6. **Review and accept the artifact** before reporting completion:
+   - The orchestrator dispatches an independent, read-only reviewer with the original request, gathered requirements, original constitution (or confirmation this is new), saved constitution, and validation results. Review the actual artifact for contradictions, unintended policy changes, and requirements coverage; return `VERDICT: PASS` or `VERDICT: CHANGES` with blocking findings and section references.
+   - Repair blocking findings within the agreed scope, repeat affected validation checks, and re-review the changed artifact independently. Repeat until PASS or blocked; unresolved policy decisions go to the user, not an invented amendment.
+   - Only the orchestrator accepts, after an independent PASS and evidence that every requirement and applicable validation check is satisfied. If an independent reviewer is unavailable, report BLOCKED; self-review cannot substitute for independent acceptance.
+   - Keep human/team approval and the constitution's amendment governance separate from artifact acceptance. This review adds no commit, push, or apply step.
+
 ## Constitution Template
 
 ```markdown

package/src/monorepo/.claude/prompt-snippets/create-skill.md

@@ -299,6 +299,16 @@ After validation, create the skill:
    - `assets/`
 4. **Add resource files**: Based on skill requirements
 
+## Artifact Review and Acceptance
+
+Before Post-Creation or a success summary, the orchestrator must:
+
+1. Dispatch an independent, read-only reviewer with the original request, gathered requirements, created skill and resource paths, and validation results. Review the actual files for naming/frontmatter, structure, reference resolution, and coverage of the requested capability; return `VERDICT: PASS` or `VERDICT: CHANGES` with blocking findings and file references.
+2. Repair blocking findings within the agreed scope, repeat affected validation checks, and re-review the changed artifacts independently. Repeat until PASS or blocked; ask the user rather than inventing requirements or expanding scope.
+3. Accept only after the independent reviewer returns PASS and the orchestrator verifies every requirement and applicable validation check against evidence. If an independent reviewer is unavailable, report BLOCKED; self-review cannot substitute for independent acceptance.
+
+Keep any required human approval separate from artifact acceptance. This review adds no commit, push, or apply step.
+
 ## Post-Creation
 
 After creating the skill: