nitm-ai-dev-toolkit 5.3.0 → 5.3.1

package/CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+
+- Functional QA in the implement loop and Factory. Each acceptance criterion gets every feasible automated check (`local`, `covered`, or `na`), and a human check is added only where a person must judge it. Missing necessary tests and unavailable evidence stay pending or block acceptance rather than passing. A human check needs a `PASS` and an explicit `accept` for the tested tree. The Factory `qa.md` carries the functional QA record: `/factory approve` refuses failed, not-run, missing, or stale automated evidence, and a human check holds the merge even under `auto`. Human answers are kept in `build.md`. The manual checklist stays non-gating. Tests: `test/functional-qa-contract.test.js`.
+
 ## [5.3.0] - 2026-11-14
 
 Retirement/relevance and wrapper-audit entries below were already shipped in 5.2.0.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nitm-ai-dev-toolkit",
-  "version": "5.3.0",
+  "version": "5.3.1",
   "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/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/
@@ -62,7 +62,7 @@ factory/
       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)
@@ -194,10 +194,10 @@ Resume by stage:
 | `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) |
 
@@ -383,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
 
@@ -414,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
 
@@ -474,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
 
-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:
+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.
 
-- 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.
+- **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 rewrites it on repair and rework rounds. A small job can have a few lines.
+## QA guidance
+
+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.
+
+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
 
@@ -498,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
 
@@ -569,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>` |
@@ -668,7 +685,7 @@ The loop is the same in every harness. Use a parallel lens batch where the harne
 
 ## 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/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` 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 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.
 
@@ -13,6 +13,8 @@ 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. 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>
@@ -70,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/monorepo/.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,16 +110,20 @@ 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.
 - Run test, lint, and build for the affected apps and packages, using the filtered form from `AGENTS.md`. If a shared package changed, also run its downstream consumers.
 - 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/monorepo/.agents/skills/factory/roles/review-code.md

@@ -6,7 +6,7 @@ You review one round of a job's branch for correctness, simplicity, reuse, conve
 
 - `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.
 
@@ -20,6 +20,7 @@ Use the [requesting code review](../../requesting-code-review/SKILL.md) checklis
 
 - **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`, the `AGENTS.md` of each affected app or package, and `.claude/rules-snippets/` standards.
@@ -55,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/monorepo/.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/monorepo/.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, including shared UI packages. 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/monorepo/.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/monorepo/.claude/prompt-snippets/implement-fixes.md

@@ -49,7 +49,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

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

@@ -36,6 +36,7 @@ build → verify → review → decide ─┬─ accept   (review PASS, every re
 - Turn every requirement in the supplied task into an acceptance criterion, `AC-1`, `AC-2`, ... There is no fixed count: one criterion per requirement, however many there are. Do not add requirements the task does not state.
 - Each AC names its check. Discover the real checks; do not assume them. Read the project's manifests (for example `package.json` scripts, `Makefile`, `pyproject.toml`, `Cargo.toml`, `go.mod`), its CI configuration (for example `.github/workflows`), its README, and `AGENTS.md`. Use the commands the project actually runs.
 - A documentation criterion may be checked by direct inspection: open the file and confirm the content, and quote what you found as evidence.
+- Each AC also gets its functional QA checks: every feasible automated check, plus a human check only where a person must judge it. Write the QA plan before the build: the exact command or fixture, and the expected result. See [Functional QA](#functional-qa).
 - A required check that cannot be discovered, or cannot be run, is a gap. It is not a pass, and it is not a bypass. It blocks acceptance of the affected task and of any aggregate run that needs it. Ask the user for the command as one targeted question and keep that question in the progress report. Independent tasks whose checks do not depend on the gap continue (see the Blocked exit in step 5).
 - Ask only when a requirement is unclear in a way that changes what gets built: two readings lead to different code, or a needed fact is missing. Ask one targeted question with its options. A task-scoped question blocks only that task and its dependents: independent tasks with clear requirements continue, and the question stays in the progress report (see [subagent-workflow.md](../rules-snippets/subagent-workflow.md), Autonomous Execution and Blockers). If the whole request is unclear, stop and ask before any build.
 - Take a baseline snapshot once, before any build. It is a plain copy of the state the task starts from, kept in a temporary directory outside the repository:
@@ -52,6 +53,7 @@ build → verify → review → decide ─┬─ accept   (review PASS, every re
 - For a bug, first write a failing test that reproduces it, and watch it fail for the right reason. Then make the minimal change that passes it. For a feature, follow TDD: failing test, minimal code, then refactor. Keep the diff as small as the task allows.
 - Leave all its changes uncommitted and unstaged, including new files, so the review sees them. Do not commit.
 - Report each AC as `pass` with the command and result, or `not verified` with the reason. List every changed and new file.
+- Report each automated QA check with its exact command, expected result, and observed result. Write a failing test for a necessary automated check that does not exist yet, and report it when it cannot be written.
 - Report `BLOCKED` with the decision the human must make if the task cannot be built as written.
 
 **Later rounds (repair):** dispatch the same builder again with only the open items: every blocking review item, every AC that is not `pass`, and every check that failed or did not run. It must fix each item, or say in its report why it should stand. It must not expand scope.
@@ -60,6 +62,8 @@ build → verify → review → decide ─┬─ accept   (review PASS, every re
 
 Every round, run every check that covers an AC, using the commands from step 1. Treat the builder's report as a lead, not as evidence. For each AC, record `pass` with the command and result from this round, or `not verified` or `fail` with the reason. Docs criteria are recorded with the quoted content.
 
+Also run the automated QA checks for every AC on the current tree, including each `covered` test the AC cites. Record each result as described in [Functional QA](#functional-qa). Human checks go to the handoff; do not run them yourself.
+
 Checks are scoped: each repair and each task runs the checks for its own ACs. After all writers are reconciled, run the project's full required regression checks once: the repo-defined full suite, lint, typecheck, and build, where they exist. Use only commands the project defines; do not invent them. A failed required check is a repair. A required check that does not exist or cannot run is BLOCKED (see step 5).
 
 ### 4. Review (reviewer, read-only)
@@ -77,24 +81,25 @@ The reviewer's rules:
 - The first line of the reply is exactly `VERDICT: PASS` or `VERDICT: CHANGES`.
 - `VERDICT: CHANGES` needs at least one blocking item, each with `file:line`, the problem, and the specific fix. Blocking means a correctness issue, a failing check, a requirement with no test or evidence, or a clear convention break. Taste goes in non-blocking notes.
 - Check each requirement of the original task, not only the diff. A requirement with no coverage is a blocking item.
+- QA evidence and labels: check the functional QA rows against [Functional QA](#functional-qa). An automated check with no `pass` from this round's tree, a necessary automated check that is missing, a `covered` check with no cited test, or an `na` with no reason is a blocking item. A human check a person must judge is not a reviewer blocking item.
 - Scope drift, both ways: trace the diff against the original supplied task. A change that no requirement needs is a blocking item unless the reviewer confirms it is a necessary implementation detail for a stated goal and says why. Goals are the original supplied task plus the user amendments recorded in step 1: do not require or assume a spec or plan (supplied-task exception). Simplicity and SRP notes stay non-blocking unless they add scope the task does not ask for.
 
 ### 5. Decide (orchestrator)
 
 Pick one outcome per round:
 
-- **Repair (back to step 2):** the review is `VERDICT: CHANGES`, **or** any AC is `not verified` or `fail`, **or** a required check failed or did not run. Send the open items to the builder, then run steps 3, 4 and 5 again on the current tree.
-- **Accept (exit):** all of these hold on this round's verify and review: the review is `VERDICT: PASS`; every requirement has an AC marked `pass` with evidence from this round; every required check ran and passed; an independent reviewer produced the verdict; and the builder did not report `BLOCKED`. Then report `ACCEPTED` with the AC evidence. A review PASS alone never accepts.
-- **Blocked (exit for the affected work):** the builder reports `BLOCKED`, a required check cannot be discovered or run, or no independent reviewer is available. Report `BLOCKED` with the blocker and what would unblock it. Never mark blocked work accepted. Work that depends on it stops; independent authorized work with its own checks and reviewer continues. Without an independent reviewer nothing is accepted, but discovery and builds that do not need acceptance may continue and be reported as awaiting review. Stop the run only when no authorized work remains or a mandatory approval, security, or permission gate applies.
-- **Needs user decision (exit for the affected work):** the task is unclear in a way only the user can settle. Stop work on that task and its dependents, report `NOT ACCEPTED: needs decision` with the question, and continue independent authorized work. This is not acceptance.
+- **Repair (back to step 2):** the review is `VERDICT: CHANGES`, **or** any AC is `not verified` or `fail`, **or** a required check failed or did not run, **or** an automated QA check failed, or a necessary automated test is missing and can be written. Send the open items to the builder, then run steps 3, 4 and 5 again on the current tree.
+- **Accept (exit):** all of these hold on this round's verify and review: the review is `VERDICT: PASS`; every requirement has an AC marked `pass` with evidence from this round; every required check ran and passed; every automated QA check passed on this round's tree; an independent reviewer produced the verdict; the builder did not report `BLOCKED`; and every human check has a `PASS` result and an explicit `accept` from the user for the tree it tested. Then report `ACCEPTED` with the AC evidence. A review PASS alone never accepts, and a pending human check is never treated as accepted.
+- **Blocked (exit for the affected work):** the builder reports `BLOCKED`, a required check cannot be discovered, a necessary QA test cannot be written, or no independent reviewer is available. Report `BLOCKED` with the blocker and what would unblock it. Never mark blocked work accepted. Work that depends on it stops; independent authorized work with its own checks and reviewer continues. Without an independent reviewer nothing is accepted, but discovery and builds that do not need acceptance may continue and be reported as awaiting review. Stop the run only when no authorized work remains or a mandatory approval, security, or permission gate applies.
+- **Needs user decision (exit for the affected work):** the task is unclear in a way only the user can settle, a check needs a credential, data, or environment only the user can provide, or a human check waits for the user's answer. Stop work on that task and its dependents, report `NOT ACCEPTED: needs decision` with the question, and continue independent authorized work. For a pending human check, the reason is `awaiting human QA`, and the report carries the exact handoff from [Functional QA](#functional-qa). This is not acceptance.
 
-No other exit exists. An unmet requirement, a failing check, or a `not verified` result always loops back to repair. There is no round limit to escape the loop.
+No other exit exists. An unmet requirement or a failing check loops back to repair. A `not verified` result loops back to repair only when the missing piece is code or test work the builder can do. A `not verified` result that waits on evidence only the user or the environment can supply, or on a pending human answer, is the needs-decision exit. There is no round limit to escape the loop.
 
 **Evidence freshness.** Acceptance uses evidence from the tree it accepts. Any edit after a verify or review, whether by the builder, a repair, or the orchestrator, invalidates the evidence it affects: rerun the checks covering those ACs and re-review the changed diff. Reuse evidence that the edit cannot affect. If unsure whether an edit affects a check, treat it as affected. Do not rerun everything for an unrelated edit.
 
 ### Commit (only when the calling flow asks)
 
-The loop never commits by itself. Accepting reports the result; it does not create a commit. The calling command decides whether accepted work is committed, and only when its own flow says so and the user has not asked otherwise. When it does commit:
+The loop never commits by itself. Accepting reports the result; it does not create a commit. The calling command decides whether accepted work is committed, and only when its own flow says so and the user has not asked otherwise. Pending human QA does not change that policy. It blocks acceptance, completion, and merge of the affected work. It neither grants nor removes a commit or push that the calling flow or an explicit checkpoint authorizes. When it does commit:
 
 - Stage only the paths this task changed, taken from the builder's list and checked against the baseline. Never `git add -A`, and never stage a preexisting or foreign change.
 - Skip the commit when nothing is staged. Do not create empty commits, and do not create a separate commit for each repair round.
@@ -106,6 +111,52 @@ The loop never commits by itself. Accepting reports the result; it does not crea
 - A self-review is never presented as an independent review.
 - These gates are prompt instructions, not host enforcement. Resuming after a pause depends on the host; this prompt does not guarantee automatic resume.
 
+## Functional QA
+
+Acceptance needs evidence that the changed behavior works. A process that starts, a page that loads, or a passing build is not evidence.
+
+**Checks per AC.** Every AC gets every feasible automated check. A human check never replaces one.
+
+- `local`: the changed behavior is observable (UI, API, CLI, or library). Run it locally with the project's documented commands and fixtures. Cover the happy path, the error path that matters, and a regression check for what the change could break, in proportion to the risk.
+- `covered`: existing automated E2E or functional tests already exercise this behavior at the needed depth. Cite the test file and name, and run it. Do not add a duplicate manual check.
+- `na`: no observable behavior, such as a docs-only change. State the reason.
+
+**Human validation.** Add a `human` check to an AC when a person must judge it: a new user-facing flow, or a judgement call that no safe automated check settles. It supplements the automated checks for that AC. Human validation is not required for every change, and an AC without it is not thereby unverified.
+
+Optional extra checks are explicit limitations with a reason. They never block acceptance.
+
+**Plan before build.** For each AC, record its automated checks and any human check: the exact command or fixture, and the expected result. Write the plan before the build and give it to the builder.
+
+**Record every run.** Each check records its exact command, the expected result, the observed result, and one outcome: `pass`, `fail`, `not run: <reason>`, or `NA: <reason>`. Run the automated checks on the current tree. Report a `covered` test with its result.
+
+**Missing tests, credentials, and environments.** A missing necessary automated test blocks acceptance of the affected AC. The builder writes it in the next repair. If it cannot be written, the task is `BLOCKED`. A missing credential, seed data, or safe environment is never a pass: ask one targeted question, record the check as `not run` with its reason, and defer it. Such a check is pending, not failed, so it does not send the task to repair. Independent ACs continue.
+
+**Safety.** Use local isolated fixtures and legitimate local test accounts from the project's documented setup. Without the user's authorization, do not touch production systems, external services, or real user data, and do not run destructive commands or cause external side effects. Start only the local processes a check needs. Stop the ones the agent started when the check is done, and leave existing servers running. Never weaken authentication, disable a check, or add a bypass to make a result pass.
+
+**Identity and freshness.** Evidence is tied to the tree it ran on: its commit and, for uncommitted work, a QA-time snapshot. The baseline (step 1) stays exactly as it was taken before the build, for the review's comparison of preexisting state. It is not the QA identity. At QA and handoff time, capture the current task-scoped diff and the contents of every new file, save them in the progress record, and reference that snapshot from the QA record. Resume compares the current scope with the QA-time snapshot before reusing any evidence. An edit to a file that a check runs or covers invalidates that check, including an uncommitted edit. Rerun the invalidated checks, and reuse evidence that the edit cannot affect. An affected human check gets a new handoff.
+
+**Human handoff.** Ask through 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. If the user is away or has said they will check in later, persist the handoff in the progress record, or in the feature's existing `qa.md` when there is one, and continue independent authorized work. The absence of an answer is never signoff. Pending work is not accepted, completed, or merged. Commits and pushes follow the calling command's existing policy and any explicit checkpoint the user authorized; pending QA neither grants nor removes them.
+
+The handoff lists, in order:
+
+1. The tested tree: branch and commit (`git rev-parse --short HEAD`), the QA-time snapshot reference when there are uncommitted changes (see Identity and freshness), and the AC or flow under test.
+2. Setup: the documented setup and start commands, the URL or port, and the test accounts, named but not written out. Credentials stay in the project's local secret store, never in the handoff.
+3. Seeded prerequisites.
+4. Numbered actions, each with its expected observable outcome.
+5. What the agent already tested, with the results, and what needs the user.
+6. Safe cleanup.
+7. The response template, one block per case:
+
+   ```
+   QA-<n>: PASS | FAIL | not run
+   Actual or error evidence: <what you saw>
+   Acceptance: accept | reject | defer
+   ```
+
+**Acceptance of a human check.** It needs both a `PASS` result and an explicit `accept` for the tree the handoff named. `not run` with `accept` stays pending, because the person did not see a result. `FAIL` or `reject` sends the AC to repair, then to a new automated run and a new handoff. `defer` stays pending. The orchestrator never signs off for the user and never treats its own evidence as the user's answer.
+
+Resume restores the exact pending handoff from the progress record, not a summary of it.
+
 ## Your Task
 
 1. **Analyze**: identify the files to create or modify, the dependencies between tasks, and the `[P]` tasks.

package/src/monorepo/factory/README.md

@@ -92,8 +92,8 @@ Session ended at a gate? `/factory start <job-id | slug | KEY>` shows that gate
 
 ## Approval modes
 
-- **`human`** (default). An approved job stops at `awaiting-human`. Read the branch and `qa.md`, then run `/factory approve <job-id>`.
-- **`auto`**. An approved job merges automatically. The approver still escalates anything touching auth, payments, data security, deployment, migrations, email, production data, new dependencies, or unresolved product decisions. Its tickets stay In Review until you run `/factory approve <job-id>`, which then moves them to Done.
+- **`human`** (default). An approved job stops at `awaiting-human`. Read the branch and the QA handoff in `qa.md`, answer any pending human check, then run `/factory approve <job-id>`.
+- **`auto`**. An approved job merges automatically. The approver still escalates anything touching auth, payments, data security, deployment, migrations, email, production data, new dependencies, or unresolved product decisions. A job with a human QA check still stops at `awaiting-human`, because that check is required validation. Its tickets stay In Review until you run `/factory approve <job-id>`, which then moves them to Done.
 
 Any value other than exactly `auto` is treated as `human`.
 
@@ -128,9 +128,15 @@ Set `MERGE_MODE`. The approval gates are the same in both modes.
 
 `push-mr` suits forge-reviewed setups, where required reviews or CI gates sit on the forge after your approval. It never force-pushes and never merges locally. Under `auto`, approve opens the request without a pause, but the forge merge and the second `/factory approve` stay yours.
 
-## Suggested checks (`qa.md`)
+## Functional QA (`qa.md`)
 
-The builder writes `qa.md` in the feature folder, on the job's branch. It has how to run the feature (dev server, port, seed data, flags), numbered manual checks tied to acceptance criteria, and what the automated tests do not cover. When a job waits for you, the orchestrator prints it with the reviewers' `Not verified` items under the line `Suggested checks before /factory approve — not a gate`. It is a checklist. It never affects a verdict, and a missing `qa.md` is only noted.
+The builder writes the QA plan into `qa.md` in the feature folder, on the job's branch, before it writes code. After the final code commit it records each check: the command, the expected result, the observed result, and `pass`, `fail`, `not run` (with the reason), or `NA`. Acceptance criteria that need a person are marked `human`, and their handoff lists the numbered steps, the expected results, and the response template.
+
+- **Automated checks** run for every criterion on the job's tree. A failed check goes back to the builder. A check that could not run because a credential, data, or environment is missing stops the job for you, as a `Not verified` item.
+- **Human checks** are added only where a person must judge: a new flow, or a judgement no safe automated check settles. They supplement the automated checks. The job waits at `awaiting-human`, even in `auto`. Answer the handoff with `PASS` and `accept`. `/factory approve` saves your answer in `build.md` and merges only when every human check reads `PASS` with `accept`. A failure or rejection means `/factory rework <job-id> <note>`.
+- **Optional checks** are listed as limitations. They never block.
+
+The approver reads the functional QA record and escalates on a failed, missing, or stale check. The manual checklist never affects a verdict, and a missing `qa.md` is only noted when the job has no `local` or `human` criteria. When a job waits for you, the orchestrator prints the record and the reviewers' `Not verified` items under the line `Suggested checks before /factory approve — not a gate`.
 
 ## Tickets
 
@@ -153,7 +159,7 @@ The parent and every sub-task move together. The orchestrator uses the project's
 4. **Plan.** `planner` in plan mode writes `plan.md` (with the size) and `tasks.md` for large work.
 5. **Plan gate.** You confirm the plan, or request changes. Nothing is ticketed or built before you confirm.
 6. **Tickets and build location.** If tracked, the parent and sub-tasks are created and their keys are written into `tasks.md`. The folder is renamed to carry the key. Then a builder gets its own git worktree on branch `factory/<id>` (bootstrapped first, see Build location), or the in-place branch. The job's feature docs are committed on that branch.
-7. **Build.** The builder follows TDD, ticks `tasks.md` as it completes tasks, writes `build.md`, and writes `qa.md`.
+7. **Build.** The builder follows TDD, ticks `tasks.md` as it completes tasks, writes `build.md`, and writes `qa.md` (its functional QA plan before the code, and its results after).
 8. **Review.** Every configured lens reviews the branch, and each reviewer's report is saved as `round-N/review-<lens>.md` with `VERDICT: PASS` or `VERDICT: CHANGES`.
 9. **Repair.** Any `CHANGES` sends the builder back to fix it. Two repairs at most, so three review rounds. Then the job escalates to you.
 10. **Approve.** `reviewer` in approval mode (fresh context) returns `APPROVE` or `ESCALATE`, and the orchestrator writes it to `decision.md`.

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/
@@ -62,7 +62,7 @@ factory/
       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)
@@ -194,10 +194,10 @@ Resume by stage:
 | `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) |
 
@@ -383,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
 
@@ -414,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
 
@@ -474,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
 
-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:
+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.
 
-- 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.
+- **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 rewrites it on repair and rework rounds. A small job can have a few lines.
+## QA guidance
+
+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.
+
+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
 
@@ -498,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
 
@@ -569,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>` |
@@ -668,7 +685,7 @@ The loop is the same in every harness. Use a parallel lens batch where the harne
 
 ## 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` 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 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.
 
@@ -13,6 +13,8 @@ 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. 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>
@@ -70,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

@@ -6,7 +6,7 @@ You review one round of a job's branch for correctness, simplicity, reuse, conve
 
 - `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.
 
@@ -20,6 +20,7 @@ Use the [requesting code review](../../requesting-code-review/SKILL.md) checklis
 
 - **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.
@@ -55,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/.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

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

@@ -36,6 +36,7 @@ build → verify → review → decide ─┬─ accept   (review PASS, every re
 - Turn every requirement in the supplied task into an acceptance criterion, `AC-1`, `AC-2`, ... There is no fixed count: one criterion per requirement, however many there are. Do not add requirements the task does not state.
 - Each AC names its check. Discover the real checks; do not assume them. Read the project's manifests (for example `package.json` scripts, `Makefile`, `pyproject.toml`, `Cargo.toml`, `go.mod`), its CI configuration (for example `.github/workflows`), its README, and `AGENTS.md`. Use the commands the project actually runs.
 - A documentation criterion may be checked by direct inspection: open the file and confirm the content, and quote what you found as evidence.
+- Each AC also gets its functional QA checks: every feasible automated check, plus a human check only where a person must judge it. Write the QA plan before the build: the exact command or fixture, and the expected result. See [Functional QA](#functional-qa).
 - A required check that cannot be discovered, or cannot be run, is a gap. It is not a pass, and it is not a bypass. It blocks acceptance of the affected task and of any aggregate run that needs it. Ask the user for the command as one targeted question and keep that question in the progress report. Independent tasks whose checks do not depend on the gap continue (see the Blocked exit in step 5).
 - Ask only when a requirement is unclear in a way that changes what gets built: two readings lead to different code, or a needed fact is missing. Ask one targeted question with its options. A task-scoped question blocks only that task and its dependents: independent tasks with clear requirements continue, and the question stays in the progress report (see [subagent-workflow.md](../rules-snippets/subagent-workflow.md), Autonomous Execution and Blockers). If the whole request is unclear, stop and ask before any build.
 - Take a baseline snapshot once, before any build. It is a plain copy of the state the task starts from, kept in a temporary directory outside the repository:
@@ -52,6 +53,7 @@ build → verify → review → decide ─┬─ accept   (review PASS, every re
 - For a bug, first write a failing test that reproduces it, and watch it fail for the right reason. Then make the minimal change that passes it. For a feature, follow TDD: failing test, minimal code, then refactor. Keep the diff as small as the task allows.
 - Leave all its changes uncommitted and unstaged, including new files, so the review sees them. Do not commit.
 - Report each AC as `pass` with the command and result, or `not verified` with the reason. List every changed and new file.
+- Report each automated QA check with its exact command, expected result, and observed result. Write a failing test for a necessary automated check that does not exist yet, and report it when it cannot be written.
 - Report `BLOCKED` with the decision the human must make if the task cannot be built as written.
 
 **Later rounds (repair):** dispatch the same builder again with only the open items: every blocking review item, every AC that is not `pass`, and every check that failed or did not run. It must fix each item, or say in its report why it should stand. It must not expand scope.
@@ -60,6 +62,8 @@ build → verify → review → decide ─┬─ accept   (review PASS, every re
 
 Every round, run every check that covers an AC, using the commands from step 1. Treat the builder's report as a lead, not as evidence. For each AC, record `pass` with the command and result from this round, or `not verified` or `fail` with the reason. Docs criteria are recorded with the quoted content.
 
+Also run the automated QA checks for every AC on the current tree, including each `covered` test the AC cites. Record each result as described in [Functional QA](#functional-qa). Human checks go to the handoff; do not run them yourself.
+
 Checks are scoped: each repair and each task runs the checks for its own ACs. After all writers are reconciled, run the project's full required regression checks once: the repo-defined full suite, lint, typecheck, and build, where they exist. Use only commands the project defines; do not invent them. A failed required check is a repair. A required check that does not exist or cannot run is BLOCKED (see step 5).
 
 ### 4. Review (reviewer, read-only)
@@ -77,24 +81,25 @@ The reviewer's rules:
 - The first line of the reply is exactly `VERDICT: PASS` or `VERDICT: CHANGES`.
 - `VERDICT: CHANGES` needs at least one blocking item, each with `file:line`, the problem, and the specific fix. Blocking means a correctness issue, a failing check, a requirement with no test or evidence, or a clear convention break. Taste goes in non-blocking notes.
 - Check each requirement of the original task, not only the diff. A requirement with no coverage is a blocking item.
+- QA evidence and labels: check the functional QA rows against [Functional QA](#functional-qa). An automated check with no `pass` from this round's tree, a necessary automated check that is missing, a `covered` check with no cited test, or an `na` with no reason is a blocking item. A human check a person must judge is not a reviewer blocking item.
 - Scope drift, both ways: trace the diff against the original supplied task. A change that no requirement needs is a blocking item unless the reviewer confirms it is a necessary implementation detail for a stated goal and says why. Goals are the original supplied task plus the user amendments recorded in step 1: do not require or assume a spec or plan (supplied-task exception). Simplicity and SRP notes stay non-blocking unless they add scope the task does not ask for.
 
 ### 5. Decide (orchestrator)
 
 Pick one outcome per round:
 
-- **Repair (back to step 2):** the review is `VERDICT: CHANGES`, **or** any AC is `not verified` or `fail`, **or** a required check failed or did not run. Send the open items to the builder, then run steps 3, 4 and 5 again on the current tree.
-- **Accept (exit):** all of these hold on this round's verify and review: the review is `VERDICT: PASS`; every requirement has an AC marked `pass` with evidence from this round; every required check ran and passed; an independent reviewer produced the verdict; and the builder did not report `BLOCKED`. Then report `ACCEPTED` with the AC evidence. A review PASS alone never accepts.
-- **Blocked (exit for the affected work):** the builder reports `BLOCKED`, a required check cannot be discovered or run, or no independent reviewer is available. Report `BLOCKED` with the blocker and what would unblock it. Never mark blocked work accepted. Work that depends on it stops; independent authorized work with its own checks and reviewer continues. Without an independent reviewer nothing is accepted, but discovery and builds that do not need acceptance may continue and be reported as awaiting review. Stop the run only when no authorized work remains or a mandatory approval, security, or permission gate applies.
-- **Needs user decision (exit for the affected work):** the task is unclear in a way only the user can settle. Stop work on that task and its dependents, report `NOT ACCEPTED: needs decision` with the question, and continue independent authorized work. This is not acceptance.
+- **Repair (back to step 2):** the review is `VERDICT: CHANGES`, **or** any AC is `not verified` or `fail`, **or** a required check failed or did not run, **or** an automated QA check failed, or a necessary automated test is missing and can be written. Send the open items to the builder, then run steps 3, 4 and 5 again on the current tree.
+- **Accept (exit):** all of these hold on this round's verify and review: the review is `VERDICT: PASS`; every requirement has an AC marked `pass` with evidence from this round; every required check ran and passed; every automated QA check passed on this round's tree; an independent reviewer produced the verdict; the builder did not report `BLOCKED`; and every human check has a `PASS` result and an explicit `accept` from the user for the tree it tested. Then report `ACCEPTED` with the AC evidence. A review PASS alone never accepts, and a pending human check is never treated as accepted.
+- **Blocked (exit for the affected work):** the builder reports `BLOCKED`, a required check cannot be discovered, a necessary QA test cannot be written, or no independent reviewer is available. Report `BLOCKED` with the blocker and what would unblock it. Never mark blocked work accepted. Work that depends on it stops; independent authorized work with its own checks and reviewer continues. Without an independent reviewer nothing is accepted, but discovery and builds that do not need acceptance may continue and be reported as awaiting review. Stop the run only when no authorized work remains or a mandatory approval, security, or permission gate applies.
+- **Needs user decision (exit for the affected work):** the task is unclear in a way only the user can settle, a check needs a credential, data, or environment only the user can provide, or a human check waits for the user's answer. Stop work on that task and its dependents, report `NOT ACCEPTED: needs decision` with the question, and continue independent authorized work. For a pending human check, the reason is `awaiting human QA`, and the report carries the exact handoff from [Functional QA](#functional-qa). This is not acceptance.
 
-No other exit exists. An unmet requirement, a failing check, or a `not verified` result always loops back to repair. There is no round limit to escape the loop.
+No other exit exists. An unmet requirement or a failing check loops back to repair. A `not verified` result loops back to repair only when the missing piece is code or test work the builder can do. A `not verified` result that waits on evidence only the user or the environment can supply, or on a pending human answer, is the needs-decision exit. There is no round limit to escape the loop.
 
 **Evidence freshness.** Acceptance uses evidence from the tree it accepts. Any edit after a verify or review, whether by the builder, a repair, or the orchestrator, invalidates the evidence it affects: rerun the checks covering those ACs and re-review the changed diff. Reuse evidence that the edit cannot affect. If unsure whether an edit affects a check, treat it as affected. Do not rerun everything for an unrelated edit.
 
 ### Commit (only when the calling flow asks)
 
-The loop never commits by itself. Accepting reports the result; it does not create a commit. The calling command decides whether accepted work is committed, and only when its own flow says so and the user has not asked otherwise. When it does commit:
+The loop never commits by itself. Accepting reports the result; it does not create a commit. The calling command decides whether accepted work is committed, and only when its own flow says so and the user has not asked otherwise. Pending human QA does not change that policy. It blocks acceptance, completion, and merge of the affected work. It neither grants nor removes a commit or push that the calling flow or an explicit checkpoint authorizes. When it does commit:
 
 - Stage only the paths this task changed, taken from the builder's list and checked against the baseline. Never `git add -A`, and never stage a preexisting or foreign change.
 - Skip the commit when nothing is staged. Do not create empty commits, and do not create a separate commit for each repair round.
@@ -106,6 +111,52 @@ The loop never commits by itself. Accepting reports the result; it does not crea
 - A self-review is never presented as an independent review.
 - These gates are prompt instructions, not host enforcement. Resuming after a pause depends on the host; this prompt does not guarantee automatic resume.
 
+## Functional QA
+
+Acceptance needs evidence that the changed behavior works. A process that starts, a page that loads, or a passing build is not evidence.
+
+**Checks per AC.** Every AC gets every feasible automated check. A human check never replaces one.
+
+- `local`: the changed behavior is observable (UI, API, CLI, or library). Run it locally with the project's documented commands and fixtures. Cover the happy path, the error path that matters, and a regression check for what the change could break, in proportion to the risk.
+- `covered`: existing automated E2E or functional tests already exercise this behavior at the needed depth. Cite the test file and name, and run it. Do not add a duplicate manual check.
+- `na`: no observable behavior, such as a docs-only change. State the reason.
+
+**Human validation.** Add a `human` check to an AC when a person must judge it: a new user-facing flow, or a judgement call that no safe automated check settles. It supplements the automated checks for that AC. Human validation is not required for every change, and an AC without it is not thereby unverified.
+
+Optional extra checks are explicit limitations with a reason. They never block acceptance.
+
+**Plan before build.** For each AC, record its automated checks and any human check: the exact command or fixture, and the expected result. Write the plan before the build and give it to the builder.
+
+**Record every run.** Each check records its exact command, the expected result, the observed result, and one outcome: `pass`, `fail`, `not run: <reason>`, or `NA: <reason>`. Run the automated checks on the current tree. Report a `covered` test with its result.
+
+**Missing tests, credentials, and environments.** A missing necessary automated test blocks acceptance of the affected AC. The builder writes it in the next repair. If it cannot be written, the task is `BLOCKED`. A missing credential, seed data, or safe environment is never a pass: ask one targeted question, record the check as `not run` with its reason, and defer it. Such a check is pending, not failed, so it does not send the task to repair. Independent ACs continue.
+
+**Safety.** Use local isolated fixtures and legitimate local test accounts from the project's documented setup. Without the user's authorization, do not touch production systems, external services, or real user data, and do not run destructive commands or cause external side effects. Start only the local processes a check needs. Stop the ones the agent started when the check is done, and leave existing servers running. Never weaken authentication, disable a check, or add a bypass to make a result pass.
+
+**Identity and freshness.** Evidence is tied to the tree it ran on: its commit and, for uncommitted work, a QA-time snapshot. The baseline (step 1) stays exactly as it was taken before the build, for the review's comparison of preexisting state. It is not the QA identity. At QA and handoff time, capture the current task-scoped diff and the contents of every new file, save them in the progress record, and reference that snapshot from the QA record. Resume compares the current scope with the QA-time snapshot before reusing any evidence. An edit to a file that a check runs or covers invalidates that check, including an uncommitted edit. Rerun the invalidated checks, and reuse evidence that the edit cannot affect. An affected human check gets a new handoff.
+
+**Human handoff.** Ask through 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. If the user is away or has said they will check in later, persist the handoff in the progress record, or in the feature's existing `qa.md` when there is one, and continue independent authorized work. The absence of an answer is never signoff. Pending work is not accepted, completed, or merged. Commits and pushes follow the calling command's existing policy and any explicit checkpoint the user authorized; pending QA neither grants nor removes them.
+
+The handoff lists, in order:
+
+1. The tested tree: branch and commit (`git rev-parse --short HEAD`), the QA-time snapshot reference when there are uncommitted changes (see Identity and freshness), and the AC or flow under test.
+2. Setup: the documented setup and start commands, the URL or port, and the test accounts, named but not written out. Credentials stay in the project's local secret store, never in the handoff.
+3. Seeded prerequisites.
+4. Numbered actions, each with its expected observable outcome.
+5. What the agent already tested, with the results, and what needs the user.
+6. Safe cleanup.
+7. The response template, one block per case:
+
+   ```
+   QA-<n>: PASS | FAIL | not run
+   Actual or error evidence: <what you saw>
+   Acceptance: accept | reject | defer
+   ```
+
+**Acceptance of a human check.** It needs both a `PASS` result and an explicit `accept` for the tree the handoff named. `not run` with `accept` stays pending, because the person did not see a result. `FAIL` or `reject` sends the AC to repair, then to a new automated run and a new handoff. `defer` stays pending. The orchestrator never signs off for the user and never treats its own evidence as the user's answer.
+
+Resume restores the exact pending handoff from the progress record, not a summary of it.
+
 ## Your Task
 
 1. **Analyze**: identify the files to create or modify, the dependencies between tasks, and the `[P]` tasks.

package/src/repo/factory/README.md

@@ -86,8 +86,8 @@ Session ended at a gate? `/factory start <job-id | slug | KEY>` shows that gate
 
 ## Approval modes
 
-- **`human`** (default). An approved job stops at `awaiting-human`. Read the branch and `qa.md`, then run `/factory approve <job-id>`.
-- **`auto`**. An approved job merges automatically. The approver still escalates anything touching auth, payments, data security, deployment, migrations, email, production data, new dependencies, or unresolved product decisions. Its tickets stay In Review until you run `/factory approve <job-id>`, which then moves them to Done.
+- **`human`** (default). An approved job stops at `awaiting-human`. Read the branch and the QA handoff in `qa.md`, answer any pending human check, then run `/factory approve <job-id>`.
+- **`auto`**. An approved job merges automatically. The approver still escalates anything touching auth, payments, data security, deployment, migrations, email, production data, new dependencies, or unresolved product decisions. A job with a human QA check still stops at `awaiting-human`, because that check is required validation. Its tickets stay In Review until you run `/factory approve <job-id>`, which then moves them to Done.
 
 Any value other than exactly `auto` is treated as `human`.
 
@@ -122,9 +122,15 @@ Set `MERGE_MODE`. The approval gates are the same in both modes.
 
 `push-mr` suits forge-reviewed setups, where required reviews or CI gates sit on the forge after your approval. It never force-pushes and never merges locally. Under `auto`, approve opens the request without a pause, but the forge merge and the second `/factory approve` stay yours.
 
-## Suggested checks (`qa.md`)
+## Functional QA (`qa.md`)
 
-The builder writes `qa.md` in the feature folder, on the job's branch. It has how to run the feature (dev server, port, seed data, flags), numbered manual checks tied to acceptance criteria, and what the automated tests do not cover. When a job waits for you, the orchestrator prints it with the reviewers' `Not verified` items under the line `Suggested checks before /factory approve — not a gate`. It is a checklist. It never affects a verdict, and a missing `qa.md` is only noted.
+The builder writes the QA plan into `qa.md` in the feature folder, on the job's branch, before it writes code. After the final code commit it records each check: the command, the expected result, the observed result, and `pass`, `fail`, `not run` (with the reason), or `NA`. Acceptance criteria that need a person are marked `human`, and their handoff lists the numbered steps, the expected results, and the response template.
+
+- **Automated checks** run for every criterion on the job's tree. A failed check goes back to the builder. A check that could not run because a credential, data, or environment is missing stops the job for you, as a `Not verified` item.
+- **Human checks** are added only where a person must judge: a new flow, or a judgement no safe automated check settles. They supplement the automated checks. The job waits at `awaiting-human`, even in `auto`. Answer the handoff with `PASS` and `accept`. `/factory approve` saves your answer in `build.md` and merges only when every human check reads `PASS` with `accept`. A failure or rejection means `/factory rework <job-id> <note>`.
+- **Optional checks** are listed as limitations. They never block.
+
+The approver reads the functional QA record and escalates on a failed, missing, or stale check. The manual checklist never affects a verdict, and a missing `qa.md` is only noted when the job has no `local` or `human` criteria. When a job waits for you, the orchestrator prints the record and the reviewers' `Not verified` items under the line `Suggested checks before /factory approve — not a gate`.
 
 ## Tickets
 
@@ -147,7 +153,7 @@ The parent and every sub-task move together. The orchestrator uses the project's
 4. **Plan.** `planner` in plan mode writes `plan.md` (with the size) and `tasks.md` for large work.
 5. **Plan gate.** You confirm the plan, or request changes. Nothing is ticketed or built before you confirm.
 6. **Tickets and build location.** If tracked, the parent and sub-tasks are created and their keys are written into `tasks.md`. The folder is renamed to carry the key. Then a builder gets its own git worktree on branch `factory/<id>` (bootstrapped first, see Build location), or the in-place branch. The job's feature docs are committed on that branch.
-7. **Build.** The builder follows TDD, ticks `tasks.md` as it completes tasks, writes `build.md`, and writes `qa.md`.
+7. **Build.** The builder follows TDD, ticks `tasks.md` as it completes tasks, writes `build.md`, and writes `qa.md` (its functional QA plan before the code, and its results after).
 8. **Review.** Every configured lens reviews the branch, and each reviewer's report is saved as `round-N/review-<lens>.md` with `VERDICT: PASS` or `VERDICT: CHANGES`.
 9. **Repair.** Any `CHANGES` sends the builder back to fix it. Two repairs at most, so three review rounds. Then the job escalates to you.
 10. **Approve.** `reviewer` in approval mode (fresh context) returns `APPROVE` or `ESCALATE`, and the orchestrator writes it to `decision.md`.