nitm-ai-dev-toolkit 5.2.1 → 5.3.1

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

@@ -5,7 +5,7 @@ description: Opt-in software factory for feature-sized work. Runs one job throug
 
 # Factory (orchestrator)
 
-One orchestrator session runs a feature through intake → spec → plan → build → review → approve → merge. Agents get their context from files. Builders and spec writers write their own files; reviewers and the approver return their report, and you save it (see Subagent dispatch). You are the orchestrator: you ask the intake questions, dispatch agents, read their files, rewrite `job.json`, run the gates with the operator, handle tickets, and run the merge. You never write code, specs, plans, reviews, or `qa.md` yourself. Exceptions: you write `intake.md` from the operator's answers, `spec-<k>.md` and `plan-<k>.md` from the operator's change requests, `tasks.md` ticket keys, the feature folder rename and copy, the feature docs commit on the job branch, worktree and branch removal, the moves and branch deletions in Archive, the review files and `decision.md` from the reviewers' and approver's replies (see Subagent dispatch), and `decision.md` with `ESCALATE` when retries run out, `merge-conflict.md` on a merge conflict, `bootstrap.md` on a failed worktree bootstrap step, the push and merge request in `push-mr` mode (see Merge procedure), and `rework-<k>.md` from the user's note.
+One orchestrator session runs a feature through intake → spec → plan → build → review → approve → merge. Agents get their context from files. Builders and spec writers write their own files; reviewers and the approver return their report, and you save it (see Subagent dispatch). You are the orchestrator: you ask the intake questions, dispatch agents, read their files, rewrite `job.json`, run the gates with the operator, handle tickets, and run the merge. You never write code, specs, plans, reviews, or `qa.md` yourself. Exceptions: you write `intake.md` from the operator's answers, `spec-<k>.md` and `plan-<k>.md` from the operator's change requests, `tasks.md` ticket keys, the feature folder rename and copy, the feature docs commit on the job branch, worktree and branch removal, the moves and branch deletions in Archive, the review files and `decision.md` from the reviewers' and approver's replies (see Subagent dispatch), and `decision.md` with `ESCALATE` when retries run out, `merge-conflict.md` on a merge conflict, `bootstrap.md` on a failed worktree bootstrap step, the push and merge request in `push-mr` mode (see Merge procedure), and `rework-<k>.md` from the user's note, It also appends the user's QA answer, verbatim, to `build.md` (see Functional QA).
 
 The factory is opt-in and sits alongside Feature Builder and TDD. Nothing runs unless the user invokes `/factory`.
 
@@ -51,7 +51,7 @@ A first argument of `start`, `approve`, `rework`, `abandon`, `status`, `watch`,
   spec.md                    spec-writer, spec mode (from the feature spec template)
   plan.md                    spec-writer, plan mode: approach, steps, and the **Size:** line
   tasks.md                   spec-writer, plan mode, large work only
-  qa.md                      builder, on the branch: suggested manual checks (not a gate)
+  qa.md                      builder, on the branch: functional QA record (plan, runs, results) and the human handoff (see Functional QA)
 factory/
   README.md                  setup and reference
   .gitignore                 ignores jobs/ and archive/
@@ -59,10 +59,10 @@ 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
+      build.md               builder; cumulative round log; you append the user's QA answer blocks (kept on rewrite)
       round-<N>/review-<lens>.md   one per configured lens
       decision.md            approver (or you, on escalation)
       merge-conflict.md      you, on a merge conflict (blocks approve)
@@ -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,16 +188,16 @@ 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`) |
-| `awaiting-human` | Print the approver's rationale, the suggested checks from `qa.md` (see QA guidance), and the `/factory approve` command |
+| `awaiting-human` | Print the approver's rationale, the QA record and any human handoff from `qa.md` (see QA guidance), and the `/factory approve` command |
 | `needs-human`, `failed_stage` `spec` | Rerun the spec stage (see Spec), then show the spec gate |
 | `needs-human`, `failed_stage` `plan` | Rerun the plan stage (see Plan), then show the plan gate |
-| `needs-human`, otherwise | Print the reason from `decision.md`, `merge-conflict.md`, `bootstrap.md`, or `build.md`, and the options: rework, approve, or abandon |
+| `needs-human`, otherwise | Print the reason from `decision.md`, `merge-conflict.md`, `bootstrap.md`, or `build.md`, and the options: rework, approve, or abandon. If a human check is pending, print its exact handoff from `qa.md` first |
 | `abandoned` | Closed. Say so and stop. To work on the feature again, run `/factory start <slug or KEY>`, which creates a new job |
 | Archived (in `factory/archive/`, any stage) | Closed. Say so and stop (see Start step 1) |
 
@@ -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.
@@ -362,7 +383,7 @@ PATHS
 - Ports: builder <p>, ux <p+1>, ui <p+2>
 ```
 
-Agents read their inputs by these absolute paths. Builders and spec writers write their output files there; reviewers and the approver return their report instead (see Subagent dispatch). The spec-writer works in the main-checkout feature folder. Reviewers and the approver read the spec and plan there. The builder reads them there and ticks `tasks.md` in the build location's copy. Reviewers read `qa.md` at the paths block's `qa.md` line, for context only.
+Agents read their inputs by these absolute paths. Builders and spec writers write their output files there; reviewers and the approver return their report instead (see Subagent dispatch). The spec-writer works in the main-checkout feature folder. Reviewers and the approver read the spec and plan there. The builder reads them there and ticks `tasks.md` in the build location's copy. Reviewers read `qa.md` at the paths block's `qa.md` line. The code lens checks its functional QA record. The other lenses read it for context only. The approver checks the record (see Functional QA).
 
 ## Loop
 
@@ -393,8 +414,8 @@ Let `N` be the current round, starting at `1` for a new job.
    A review cycle is the rounds since the job started, or since the latest `rework-<k>.md` (see Rework). "Third review round of the cycle" means two repairs have already been made in this cycle. The rework note records where its cycle starts.
 9. **Approve.** Set stage `approve`. Dispatch `reviewer` in approval mode (brief `roles/approve.md`, fresh context) with the paths block. Wait for the approver's reply and save it as `decision.md` (see Harness notes). Its first line must be `APPROVE` or `ESCALATE`. If the line is missing or invalid, re-dispatch once, then stage `needs-human`.
    - `ESCALATE` → stage `needs-human`. Tell the user the rationale. Stop.
-   - `APPROVE` and `{{APPROVAL_MODE}}` is exactly `auto` → run the merge procedure.
-   - `APPROVE` otherwise: stage `awaiting-human`. Print the suggested checks (see QA guidance). Tell the user to run `/factory approve <id>` after reviewing the branch. Stop. Any value other than exactly `auto` is treated as `human`.
+   - `APPROVE` and `{{APPROVAL_MODE}}` is exactly `auto` → run the merge procedure, unless the job has a `human` criterion (see Functional QA). Such a job stops at `awaiting-human` even under `auto`, as below.
+   - `APPROVE` otherwise: stage `awaiting-human`. Print the QA guidance, with the human handoff when there is one (see QA guidance). Tell the user to run `/factory approve <id>` after reviewing the branch. Stop. Any value other than exactly `auto` is treated as `human`.
 
 ### Repair
 
@@ -453,21 +474,36 @@ Rules:
 
 The new cycle starts with a fresh repair budget. Old rounds and reviews are kept, not overwritten.
 
-## QA guidance (non-gating)
+## Functional QA
+
+Functional QA means the changed behavior was run, not only built. The rules are the shared loop's [Functional QA](../../../.claude/prompt-snippets/implement.md#functional-qa): automated checks for every AC, a human check only where a person must judge, the plan before the build, recorded runs, safety, identity and freshness, and the handoff. This section adds the Factory mechanics. Gates use only the existing verdicts and stages.
+
+- **Plan.** Before writing code, the builder writes the QA table into `qa.md` in the build location: one row per AC and check, with its kind (`local`, `covered`, `human`, or `na`), its exact command or fixture, and its expected result. A human check is an extra row on its AC, never a replacement for the automated rows. Observed and Result start as `-` and `planned`.
+- **Run.** The order is fixed: the code commit, then the runs on that commit, then the evidence commit. After the final code commit, the builder runs each automated check and each cited `covered` test, fills in Observed and Result, records `Tested commit: <hash>` (the code commit), and commits `qa.md` with the work. A `human` row is never recorded as passed.
+- **Review.** The code lens re-runs each automated command from the table and each cited `covered` test, and compares the results with the recorded ones (see the code brief). A failed row, a missing feasible automated check, or a label without its reason is a `VERDICT: CHANGES` item, repaired within the usual three review rounds. A check that could not run because a credential, data, or environment is missing is a blocking item titled `Not verified: functional QA <AC-n>: <reason>`. It sends the job to `needs-human`, and nothing is repaired for it.
+- **Approve.** The approver checks the record (see its brief) and escalates on a failed, missing, or not-run automated check, or on stale evidence. Evidence is stale when the build location has uncommitted changes, or when a committed change since `Tested commit` touches a file that an automated check runs or covers. The only exempt change is a record-only edit to `qa.md`, one that changes the Observed, Result, or Tested commit cells and nothing else. Changes to files that no check runs or covers do not stale the record. A changed criterion, command, expected result, or evidence line does. The approver does not count human rows or the manual checklist.
+- **Human checks.** For an AC with a human check, the handoff is the `## Manual checks` section of `qa.md`: numbered steps, each with its AC and expected result, plus the fields from implement.md's Functional QA (tested commit, setup and test accounts by name, seeded prerequisites, what was already tested, cleanup, and the response template). The orchestrator prints it at `awaiting-human`, even under `auto`, and the job waits there. Acceptance needs `PASS` and an explicit `accept` for the tested commit named in the handoff (Approve step 6). `not run` with `accept` stays pending. `reject` or `FAIL` means rework. The answer is saved verbatim in `build.md` as a `## Human QA answer` block. After any rework or any change to a checked file, the tested commit changes, and a new handoff is printed. Ask the user with the harness's native question tool when one exists, and only when no independent authorized work remains or a gate needs the answer; otherwise ask in chat at that point. Resume restores the exact pending handoff from `qa.md`, not a summary of it.
+- **Unavailable user.** Nothing repeats or loops. The job stays at `awaiting-human`, the handoff stays in `qa.md`, the status table shows it, and other jobs continue. Absence is never signoff.
+- **Where the evidence lives.** `qa.md` is on the job branch in the build location: the worktree path from the paths block, or the main checkout for an in-place job. The orchestrator reads it there before the merge, and from the main checkout's feature folder after it. Answers are in `build.md` in the job folder, which git ignores, so they survive worktree removal. The builder keeps those blocks when it rewrites `build.md`.
+- **Missing record.** A missing `qa.md`, or a missing `## Functional QA` section, escalates when the job has any automated or human check. Otherwise it is only noted.
+- **Optional checks.** They are listed under `## Not covered by automated tests`, each with its reason. They never block.
 
-The builder writes `qa.md` in the feature folder of its build location (the worktree's copy, or the main checkout's for an in-place job). It is committed with the work. It is the operator's checklist for a human look before approval:
+## QA guidance
 
-- How to run the feature: setup, dev-server command and port, seed data, flags.
-- Numbered manual checks, each tied to an `AC-n` in `spec.md`, with the expected result.
-- "Not covered by automated tests" items.
+The builder writes `qa.md`, committed with the work. It holds the functional QA record, the human handoff when there is one, and the operator's checklist. It rewrites it on repair and rework rounds. A small job can have a few lines.
 
-The builder rewrites it on repair and rework rounds. A small job can have a few lines.
+When the job reaches `awaiting-human` or `needs-human`, and after an auto merge, print (from the build location before the merge, from the main checkout's feature folder after it):
+
+- First, the mandatory items: every `## Not verified` item from the latest round's reviews, and every failed, not-run, or stale automated check from the record. These are blocking and never sit under the optional line.
+- If a human check is pending: `Human QA required before /factory approve: answer the handoff below`, then the handoff.
+- The `## Functional QA` table with its results.
+- Under the line `Suggested checks before /factory approve — not a gate`, the `## Not covered by automated tests` items.
+- If `qa.md` is missing: `No qa.md: no QA record or suggested checks.`
 
 Rules:
 
-- `qa.md` never affects a verdict. Reviewers may read it for context. The approver ignores it.
-- A missing `qa.md` is noted, never blocking.
-- When the job reaches `awaiting-human` or `needs-human`, and after an auto merge, print `qa.md` (from the build location before the merge, from the main checkout's feature folder after it). Then print the `## Not verified` items from the latest round's reviews. Put this line before them: `Suggested checks before /factory approve — not a gate`. If `qa.md` is missing, print `No qa.md: no suggested checks.` in its place.
+- Only the checklist and the limitations are optional. They never change a verdict.
+- A missing `qa.md`, or a missing `## Functional QA` section, escalates only when the job has an automated or human check. Otherwise it is noted.
 
 ## Approve
 
@@ -477,8 +513,10 @@ Rules:
 2. Otherwise refuse unless stage is `awaiting-human` or `needs-human`. The user's explicit command is the approval. Do not re-run the approver.
 3. Refuse unless the first line of `build.md` is exactly `STATUS: READY`. A job that failed before its build has no `build.md`: say so, and point to `/factory start <job-id>` (for a failed spec or plan step) or `/factory abandon <job-id>`.
 4. Refuse while `merge-conflict.md` exists in the job folder. The user resolves the conflict on the branch, then removes that file.
-5. Print the reason the job stopped before merging, so the user sees what they approve: the `ESCALATE` rationale in `decision.md`, the `Not verified` items, or the failed agent. For `awaiting-human`, print the approver's rationale.
-6. Run the merge procedure for `{{MERGE_MODE}}`. In `push-mr`, a job with `mr` set takes the finish path there instead.
+5. **Required QA evidence.** Refuse, in every mode and from `needs-human` too, while the functional QA record in `qa.md` shows a failed, not-run, or missing automated check or covered test, or stale evidence (see Functional QA, Approve). Name the row and what the user must supply. Do not waive this with the approve command: the fix is rework, or a builder repair followed by review. The existing overrides for other items are unchanged.
+6. **Human QA.** Only when the job has a `human` check (see Functional QA). The command alone is not enough for it. If no answer is recorded for the tested commit, print the handoff from `qa.md` and ask in chat for the answer in the response template, then stop. When the answer comes, append it verbatim to `build.md` as a `## Human QA answer (<tested commit>)` block. Proceed only when every human check reads `PASS` with an explicit `accept` for that commit. A `FAIL` or `reject` does not merge: tell the user to run `/factory rework <job-id> <note>` naming the row. `defer`, `not run`, or no answer leaves the job at `awaiting-human`. A job with no `human` check skips this step.
+7. Print the reason the job stopped before merging, so the user sees what they approve: the `ESCALATE` rationale in `decision.md`, the `Not verified` items, or the failed agent. For `awaiting-human`, print the approver's rationale.
+8. Run the merge procedure for `{{MERGE_MODE}}`. In `push-mr`, a job with `mr` set takes the finish path there instead.
 
 ## Abandon
 
@@ -548,7 +586,7 @@ Closed jobs (`merged` or `abandoned`) are hidden by default. Print one line in t
 | `plan` | Wait, or `/factory start <id>` to resume if the session ended |
 | `awaiting-plan` | `/factory start <id>` to review the plan and confirm it |
 | `build`, `review`, `approve` | Wait, or `/factory start <id>` to resume if the session ended |
-| `awaiting-human` | Review the branch and its `qa.md` (suggested checks, not a gate), then `/factory approve <id>`. In `push-mr` with `mr` set: merge the request on the forge, then `/factory approve <id>` to finish. Print the request URL |
+| `awaiting-human` | Review the branch and the QA record in `qa.md`. Answer any pending `human` check in its handoff, then `/factory approve <id>`. A `reject` means `/factory rework <id> <note>`. In `push-mr` with `mr` set: merge the request on the forge, then `/factory approve <id>` to finish. Print the request URL |
 | `needs-human` | Read the reason. A failed spec or plan step: `/factory start <id>` reruns it. After a build: `/factory rework <id> <note>` or `/factory approve <id>`. Either way, `/factory abandon <id>` closes the job |
 | `abandoned` | Nothing: the job is closed. To work on the feature again, `/factory start <slug or KEY>` creates a new job |
 | `merged` | Nothing, unless tickets are not Done yet: `/factory approve <id>` |
@@ -604,6 +642,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,11 +681,11 @@ 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
 
-File-write boundaries are prompt conventions, not enforced isolation. Nothing physically stops an agent from writing outside its file. The real gates are the spec and plan gates, the reviewer verdicts, the approver's rules and dry-run merge check, and the merge procedure's preconditions and test run. Ticket updates are best-effort and never gate the pipeline. `qa.md` is advisory and gates nothing.
+File-write boundaries are prompt conventions, not enforced isolation. Nothing physically stops an agent from writing outside its file. The real gates are the spec and plan gates, the reviewer verdicts, the approver's rules and dry-run merge check, and the merge procedure's preconditions and test run. Ticket updates are best-effort and never gate the pipeline. The `## Functional QA` record in `qa.md` gates through the code lens and the approver. The manual checklist gates nothing. A pending `human` check gates the merge only through approval (see Functional QA).
 
 ## Related
 

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

@@ -4,7 +4,7 @@ You decide whether a job goes to merge or to a human. You are the approval gate
 
 ## Inputs
 
-- The whole job history: `spec.md` (feature folder, paths block), `build.md`, `rework-*.md` if any, every `round-*/review-*.md`, and the job's `job.json`.
+- The whole job history: `spec.md` and `plan.md` (feature folder, paths block), the QA record in `qa.md` (paths block's `qa.md` line, its `## Functional QA` section), 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,9 @@ 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.
+
+Then check the `## Functional QA` record in `qa.md` against [SKILL Functional QA](../SKILL.md#functional-qa). Escalate when an automated check is `fail` or `not run`, when an automated row has no evidence from the tested commit, when a necessary automated check or covered test is missing, or when the record is stale. The record is stale when the build location has uncommitted changes (`git -C <worktree> status --porcelain` is not empty), or when a committed change since the tested commit touches a file that an automated check runs or covers (`git -C <worktree> diff --name-only <Tested commit> factory/<id>`). The only exempt change is a record-only edit to `qa.md`. Do not count human rows or the manual checklist.
 4. **Dry-run merge.** Check for conflicts without changing anything:
    ```
    git -C <main checkout> merge-tree --write-tree {{DEFAULT_BRANCH}} factory/<id>
@@ -28,6 +30,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
@@ -69,4 +72,4 @@ The first line must be exactly `APPROVE` or `ESCALATE`, followed by the rational
 - Do not edit code, reviews, `build.md`, `job.json`, `tasks.md`, or any other file.
 - Do not merge, push, or change branches.
 - Do not transition tickets. The orchestrator owns ticket status, and the approver never touches the tracker.
-- `qa.md` is not a gate. Do not count its checks in the decision, and do not escalate because it is missing.
+- The manual checklist in `qa.md` is not a gate, and its absence does not escalate. The `## Functional QA` record is evidence you check in step 3. A `human` check is not yours to decide: the orchestrator holds the job for the user's answer, so do not escalate or approve on it.

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

@@ -34,6 +34,8 @@ Follow the [test-driven development](../../test-driven-development/SKILL.md) ski
 
 Before you claim any acceptance criterion is met, follow [verification before completion](../../verification-before-completion/SKILL.md): run the check and record the command and its result as evidence.
 
+Functional QA follows [Functional QA](../SKILL.md#functional-qa). Write the QA plan into `qa.md` before you write code, and run and record the checks after your final code commit. Do not claim a `human` row passed.
+
 ## Output
 
 You write two files.
@@ -62,22 +64,44 @@ You write two files.
 
    The first line must be exactly `STATUS: READY` or `STATUS: BLOCKED`.
 
-2. `qa.md` in the feature folder of the build location (committed on the branch). Rewrite it whole, so it matches the code as it is now. Use this skeleton:
+2. `qa.md` in the feature folder of the build location (committed on the branch). Write the QA plan before the code. After the final code commit, rewrite it whole, so it matches the code as it is now. Use this skeleton:
 
    ```markdown
    # QA: <feature title>
 
+   ## Functional QA
+
+   Tested commit: `<code commit hash, after the final code commit>`
+
+   | AC | Class | Command or fixture | Expected | Observed | Result |
+   | --- | --- | --- | --- | --- | --- |
+   | AC-1 | local | `<exact command>` | <expected result> | - | planned |
+   | AC-2 | covered | `<test file>` `<test name>` | <expected result> | - | planned |
+   | AC-3 | human | see Manual checks | <expected result> | - | planned |
+
    ## How to run
 
    - Setup: `<command from AGENTS.md>`
    - Dev server: `<command>` on port <builder port>, passed with `<flag or env var from AGENTS.md>`
    - Seed data: <what the dev environment provides, or "none">
    - Flags or config: <or "none">
+   - Test accounts: <names only; credentials stay in the project's local secret store>
+   - Cleanup: <how to stop what you started, and how to reset the fixture>
+   - Already tested by the agent: <the rows that passed, with their results>. Needs the user: <the human rows>.
+
+   ## Manual checks (human)
 
-   ## Manual checks
+   Only for `human` rows. Each check is numbered, names its AC, and gives a result a person can see.
 
-   1. AC-1: <what to do>. Expected: <what a person can observe>.
-   2. AC-2: <what to do>. Expected: <result>.
+   1. AC-3: <what to do>. Expected: <what a person can observe>.
+
+   Answer each case in this template, in the user's own words after it:
+
+   ```
+   QA-<n>: PASS | FAIL | not run
+   Actual or error evidence: <what you saw>
+   Acceptance: accept | reject | defer
+   ```
 
    ## Not covered by automated tests
 
@@ -86,15 +110,19 @@ You write two files.
 
    Rules for `qa.md`:
 
-   - Each manual check names an `AC-n` from `spec.md`, and an expected result a person can see or confirm. Leave out criteria that the automated tests cover fully, unless a person still needs to look.
-   - It is a checklist, not a report. Do not record results.
+   - Plan first: the table is written before any code. Each row names its AC, its class (`local`, `covered`, `human`, or `na`), and the exact command, test, or fixture. An `na` row states its reason in Expected.
+   - Record after the final code commit: Observed holds what you saw. Result is `pass`, `fail`, `not run: <reason>`, or `NA: <reason>`. A missing credential, seed data, or environment is `not run: <reason>`. A missing necessary test is written first where you can, or recorded as `not run: no test` with its reason.
+   - Never record a `human` row as passed. The user answers those.
+- Keep every section of `build.md` you did not write this round, including the orchestrator's `## Human QA answer` blocks. Rewrite the round log around them, never over them.
+   - Safety: use local isolated fixtures and the project's local test accounts only. Do not touch production, external services, or real data, and do not cause external side effects. Start only the local processes a check needs. Stop the ones you started, and leave existing servers running. Never weaken authentication or add a bypass.
+   - Optional checks go under "Not covered by automated tests", each with its reason. They never block.
    - Keep it short. A small job needs a few lines.
 
 ## Rules
 
 - Address every `CHANGES` item in repair mode. Fix it, or justify in the log why it should stand. Silence is not an option.
-- Use `STATUS: BLOCKED` only when the spec cannot be built as written (contradiction, missing decision, unavailable dependency). Say exactly what the human must decide. Do not block on things you can work around.
+- Use `STATUS: BLOCKED` only when the spec cannot be built as written (contradiction, missing decision, unavailable dependency, or a necessary QA test that cannot be written). Say exactly what the human must decide. Do not block on things you can work around.
 - Report an acceptance criterion as pass only with evidence. A criterion you did not check is `not verified`, and say so.
 - Tick `tasks.md` in the build location as you finish each task: change `- [ ]` to `- [x]` on that line once its acceptance criteria pass and the work is committed. Leave the rest of the line, including any ticket key, unchanged. Do not tick a task you did not finish.
 - Do not add dependencies, abstractions, or files the spec does not need.
-- Do not merge, approve, or edit reviewer files. `qa.md` never gates anything, so do not write it to pass a check.
+- Do not merge, approve, or edit reviewer files. Never write a QA result you did not observe. The QA record gates through the code reviewer and the approver, so a result written to pass a check is a fault.

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

@@ -4,9 +4,9 @@ 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.
+- `qa.md` at the paths block's `qa.md (absolute, build location)` line, if it exists: the builder's functional QA record (`## Functional QA`) and manual checks. Check the record as the Functional QA review below says. The manual checks are context only and never change 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.
 - The project's `AGENTS.md` for test, lint, and build commands.
 
@@ -19,6 +19,8 @@ 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.
+- **Functional QA:** check the `## Functional QA` record against [SKILL Functional QA](../SKILL.md#functional-qa). Each AC lists every feasible automated check with its label: `local` for observable behavior, `covered` for a cited existing test, and `na` with a reason. A `human` check is added on top where a person must judge. It never replaces an automated check. Re-run each `local` command and each cited `covered` test in the table, and compare the result with the recorded one. Every automated row needs a `pass` from the tested commit. A missing feasible automated check, a result that does not reproduce, a `fail`, or a label without its reason is a blocking item with its fix. A check that could not run for a missing credential, data, or environment is a blocking item titled `Not verified: functional QA <AC-n>: <reason>`.
 - **Simplicity:** use the [ponytail-review](../../ponytail-review/SKILL.md) lens. Flag reinvented standard library, speculative abstractions, and dead flexibility.
 - **Reuse:** the change should extend existing utilities rather than duplicate them.
 - **Conventions:** the project's `AGENTS.md` and `.claude/rules-snippets/` standards.
@@ -54,4 +56,5 @@ The first line must be exactly `VERDICT: PASS` or `VERDICT: CHANGES`.
 - `CHANGES` needs at least one blocking item. Each blocking item is specific (file and line), actionable, and about correctness, a failing check, a missing acceptance criterion, or a clear convention break.
 - Taste goes under non-blocking notes. Taste never blocks a PASS.
 - A failing test, lint, or build command is a blocking item unless the failure is in code the branch does not touch and is shown on the default branch too.
+- An automated QA row (`local` or `covered`) that fails on re-run is a blocking item. A row that could not run for a missing credential, data, or environment is the `Not verified: functional QA` item above, not a repair.
 - Do not edit code, tests, or any file. Do not fix problems yourself.

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

@@ -6,7 +6,7 @@ You audit one round of a job's branch for security problems. You are the `securi
 
 - The branch diff: `git -C <worktree> diff {{DEFAULT_BRANCH}}...factory/<id>`.
 - `spec.md` in the feature folder (paths block), for what the feature is meant to do.
-- `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.
+- `qa.md` at the paths block's `qa.md (absolute, build location)` line, if it exists: the builder's functional QA record and manual checks. Use it for context only. The QA gate belongs to the code lens and the approver, so it never changes your verdict.
 - Round `N > 1`: your own previous review, `round-<N-1>/review-security.md`.
 
 ## Method

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

@@ -15,7 +15,7 @@ You look at a job's feature running in the build location and review the visual
 - `build.md` for what the builder says it changed.
 - The project's `AGENTS.md` for the dev command, how to pass the port, and the design system or component library in use.
 - Existing components the feature should match. Find them in the codebase, not from memory.
-- `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.
+- `qa.md` at the paths block's `qa.md (absolute, build location)` line, if it exists: the builder's functional QA record and manual checks. Use it for context only. The QA gate belongs to the code lens and the approver, so it never changes your verdict.
 - Round `N > 1`: your own previous review, `round-<N-1>/review-ui.md`.
 
 ## Method

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

@@ -14,7 +14,7 @@ You look at a job's feature running in the build location and review the user ex
 - `spec.md` in the feature folder (paths block), for the acceptance criteria and user flows.
 - `build.md` for what the builder says it changed.
 - The project's `AGENTS.md` for the dev command and how to pass the port.
-- `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.
+- `qa.md` at the paths block's `qa.md (absolute, build location)` line, if it exists: the builder's functional QA record and manual checks. Use it for context only. The QA gate belongs to the code lens and the approver, so it never changes your verdict.
 - Round `N > 1`: your own previous review, `round-<N-1>/review-ux.md`.
 
 ## Method

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

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

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

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

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

@@ -51,7 +51,7 @@ Implement bug fixes and corrections with proper validation and documentation.
 4. **Verify, Review and Decide** (repeat implement.md steps 3, 4 and 5 until an exit):
    - Verify: rerun the reproducing test and confirm it passes now, run every check that covers an AC, and run the full test suite for regressions.
    - Review: the independent read-only reviewer checks the fix, the reproducing test, and the untracked files.
-   - Decide: repair goes back to the same builder. Repeat until `ACCEPTED`, `BLOCKED`, or `NOT ACCEPTED: needs decision`. There is no round limit. A review PASS alone never accepts.
+   - Decide: repair goes back to the same builder. Repeat until `ACCEPTED`, `BLOCKED`, or `NOT ACCEPTED: needs decision` (which includes a pending human QA check, reason `awaiting human QA`). There is no round limit. A review PASS alone never accepts.
 
 5. **Commit and Push** (only after `ACCEPTED`, and only when there are accepted changes): stage only the fix's paths, never `git add -A` or a foreign change. Skip the commit when nothing is staged.
    ```bash