nitm-ai-dev-toolkit 5.2.1 → 5.3.1

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/.agents/skills/factory/roles/spec.md

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

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

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

package/src/monorepo/.claude/prompt-snippets/implement-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

@@ -8,6 +8,7 @@ You are the orchestrator for this implementation. You derive the acceptance crit
 > with this loop. Do not route through a planning skill, and do not write a spec or plan first.
 > For 3+ independent `[P]` tasks that touch disjoint files, the loops may run concurrently with the
 > `dispatching-parallel-agents` skill. Each task still runs its own loop.
+> Nontrivial ad-hoc code changes outside these commands follow the same loop. Context-heavy nontrivial work may be built directly, but acceptance still needs an independent reviewer; without one it is BLOCKED. Trivial changes (typos, one-line edits) stay outside this loop.
 
 ## Roles
 
@@ -31,12 +32,13 @@ build → verify → review → decide ─┬─ accept   (review PASS, every re
 
 ### 1. Task, checks and baseline (orchestrator)
 
-- The original supplied task (request, task list entry, or fix description) is the requirement. Keep its text and give it to the builder and the reviewer unchanged. Do not require a new spec or plan first, and do not write one.
+- The original supplied task (request, task list entry, or fix description) is the requirement. Keep its text and give it to the builder and the reviewer unchanged. Explicit user amendments and answers given during the loop are part of the requirement too: record each one as a dated entry beside the original text (do not rewrite it), and give the builder and the reviewer the original text plus every amendment. Do not require a new spec or plan first, and do not write one.
 - Turn every requirement in the supplied task into an acceptance criterion, `AC-1`, `AC-2`, ... There is no fixed count: one criterion per requirement, however many there are. Do not add requirements the task does not state.
 - Each AC names its check. Discover the real checks; do not assume them. Read the project's manifests (for example `package.json` scripts, `Makefile`, `pyproject.toml`, `Cargo.toml`, `go.mod`), its CI configuration (for example `.github/workflows`), its README, and `AGENTS.md`. Use the commands the project actually runs.
 - A documentation criterion may be checked by direct inspection: open the file and confirm the content, and quote what you found as evidence.
-- A required check that cannot be discovered, or cannot be run, is a gap. It is not a pass, and it is not a bypass. Stop and ask the user for the command (see the Blocked exit in step 5).
-- Ask only when the task is unclear in a way that changes what gets built: two readings lead to different code, or a needed fact is missing. Ask one targeted question, offering the options, and wait.
+- 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:
   - `git rev-parse HEAD`: the base commit.
   - `git status --porcelain > <tmp>/baseline/status.txt`: which files were already changed, staged or untracked.
@@ -51,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.
@@ -59,6 +62,10 @@ 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)
 
 Every round, after verify, dispatch the reviewer on the current working tree. Give it the original supplied task text, the AC list, this round's check results, the base commit, and the baseline snapshot. Its review scope covers the whole task, and it compares content, not patches:
@@ -74,34 +81,86 @@ 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):** the builder reports `BLOCKED`, or a required check cannot be discovered or run, or no independent reviewer is available. Stop, report `BLOCKED` with the blocker and what would unblock it. Never mark blocked work accepted.
-- **Needs user decision (exit):** the task is unclear in a way only the user can settle. Stop, report `NOT ACCEPTED: needs decision` with the question. This is not acceptance.
+- **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 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.
 
-No other exit exists. An unmet requirement, a failing check, or a `not verified` result always loops back to repair. There is no round limit to escape the loop.
+**Evidence freshness.** Acceptance uses evidence from the tree it accepts. Any edit after a verify or review, whether by the builder, a repair, or the orchestrator, invalidates the evidence it affects: rerun the checks covering those ACs and re-review the changed diff. Reuse evidence that the edit cannot affect. If unsure whether an edit affects a check, treat it as affected. Do not rerun everything for an unrelated edit.
 
 ### Commit (only when the calling flow asks)
 
-The loop never commits by itself. Accepting reports the result; it does not create a commit. The calling command decides whether accepted work is committed, and only when its own flow says so and the user has not asked otherwise. When it does commit:
+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.
 
 ### Limits
 
-- **No independent reviewer means BLOCKED.** The orchestrator may run its own verify and report the evidence, but it cannot accept the work on its own review. Report `BLOCKED`, and stop.
+- **No independent reviewer means nothing is accepted.** The orchestrator may run its own verify and report the evidence, but it cannot accept the work on its own review. Report `BLOCKED` for acceptance. Do not treat all work as blocked when independent discovery or build can proceed (see the Blocked exit in step 5).
+- Mandatory approval, security, and permission gates are never bypassed. They apply to the affected work, or to the whole run when the gate is global.
 - A self-review is never presented as an independent review.
+- These gates are prompt instructions, not host enforcement. Resuming after a pause depends on the host; this prompt does not guarantee automatic resume.
+
+## 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.
-   Dispatch `[P]` tasks in parallel only when they touch different files with no shared state. Otherwise keep them sequential.
+   Dispatch `[P]` tasks in parallel only when they touch different files with no shared state. Otherwise keep them sequential. A task whose write set is unknown or undeclared runs serially until the builder's changed-file list establishes its scope.
 2. **Run the delivery loop** for each task, in dependency order, until it exits as accepted, blocked, or needs a user decision.
 3. **Track progress**: tick a task only after the orchestrator accepts it. Report blockers and summarize the accepted changes.
 

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

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

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

@@ -18,8 +18,15 @@ You are helping to create a feature specification based on the user's descriptio
    - Use the template structure below
    - Be specific and actionable
 
-4. **Output**:
-   - Confirm specification created
+4. **Review and Accept the Specification**:
+   - Dispatch an independent, read-only reviewer with the original request (verbatim, with any later user amendments), the feature description, and `spec.md`. Use the goal-fit brief (read and follow [fit-review](../rules-snippets/fit-review.md)): Oracle when available read-only, otherwise a separate reviewer; the author's self-review does not count.
+   - The reviewer traces requirements and acceptance criteria both ways against the original request, checks that each criterion is testable, and returns `VERDICT: PASS` or `VERDICT: CHANGES` with blocking findings and section references. A finding that needs a user decision is blocking, marked `requires user decision; do not auto-repair`; stop and ask the user.
+   - Repair blocking findings within the agreed scope, repeat the affected checks, and re-review the changed spec independently. Repeat until PASS or blocked, or until the user decides. Stop as BLOCKED with the reason when a repair changes nothing or the same finding returns unchanged. A goal change from the review is a user decision, not a repair. Open decisions block PASS until the user resolves them.
+   - Only the orchestrator accepts, after an independent PASS. If an independent reviewer is unavailable, report BLOCKED; self-review cannot substitute for independent acceptance.
+   - Acceptance is separate from human approval: the human still confirms the spec.
+
+5. **Output** (only after artifact acceptance):
+   - Confirm specification created and accepted
    - Summarize key requirements
    - Suggest next step: `/plan` to create implementation plan
 

package/src/monorepo/.claude/rules-snippets/fit-review.md

@@ -0,0 +1,62 @@
+# Goal-Fit Review Brief
+
+Read and follow this brief when a gate or command asks for a goal-fit review of a spec, a plan, or a build's scope. It adds to the reviewer rules of the calling flow.
+
+## Reviewer
+
+- Read-only. Do not edit files, stage, or commit. Do not write any file the caller did not ask for.
+- Independent of the author. Use Oracle when it is available read-only; otherwise a separate reviewer in fresh context. The author's self-review, the author's summary, and a single session playing every role do not count.
+- If no independent reviewer can run, the caller reports `BLOCKED`. Do not review in its place.
+- Review the current artifacts from scratch on every run, including resumed runs. Do not rely on an earlier reply, an earlier summary, or the author's account of what changed.
+
+## Goal sources
+
+Use only these as goal authority:
+
+1. The original user request, verbatim, and every explicit user amendment (intake answers, operator change requests, rework decisions). The caller passes them to you as text in the dispatch.
+2. Accepted constraints from earlier artifacts, when the caller passes them: for a plan review, the accepted spec's requirements, acceptance criteria, and `[DECIDED]` items; for a build review, the accepted spec and plan. Trace against these. They are not goal authority on their own.
+
+Not goal sources: a slug, a ticket key, a ticket title, the existing spec alone, the planner's or author's summary, and any reviewer finding from an earlier round.
+
+If the original request is not in the dispatch, do not infer goals from the spec or the plan. Reply `VERDICT: CHANGES` with a blocking finding: `Missing authoritative baseline: requires user decision; do not auto-repair.`
+
+Quote the original request in your report. When a lower source (a spec, a plan, or a summary) conflicts with the original request, report the conflict with both quotes. Do not silently trust the lower source.
+
+## Trace both ways
+
+- **Forward:** every goal is covered by a requirement, acceptance criterion, or step. Name the section that covers it, or report the gap.
+- **Backward:** every requirement, step, or file change traces to a goal. A change that no goal needs is scope drift.
+- Implementation details that a goal needs are allowed without their own acceptance criterion (for example, a migration that a storage goal requires). Do not demand that every mundane detail be an acceptance criterion. Name the goal that justifies such a detail.
+
+## Lenses (separate from correctness)
+
+- **Ponytail:** is this the simplest work that meets the goals? Flag speculative abstraction, dead flexibility, reinvented standard-library behavior, and steps no goal asks for. Block only when the finding adds scope or complexity the goals do not justify; otherwise note it.
+- **SOLID and SRP, proportional:** flag a responsibility split only when it harms a goal, for example one unit doing unrelated work the request keeps apart. Do not require abstractions or interfaces, and do not forbid a justified interface. Judge by the goals, not by the pattern.
+
+## Decisions and repairs
+
+- A change to a goal (dropping, narrowing, or adding one) is a user decision. So is any other question only the user can settle. A decision stays blocking until the user resolves it with an explicit amendment. Report it as a blocking finding under `VERDICT: CHANGES`, marked `requires user decision; do not auto-repair`, and also list it under **Decisions for the user**. Do not repair it, and do not assume an answer.
+- Other blocking findings are scoped repairs: name the section and the specific change. The caller passes your findings to the author as dispatch context and reviews the changed artifacts again. You do not write repair notes or repair files.
+- `VERDICT: PASS` means no blocking findings. Absence of blocking findings is not a pass. A finding that needs a user decision is blocking, so it is never a pass.
+
+## Output
+
+The first line is exactly `VERDICT: PASS` or `VERDICT: CHANGES`. `CHANGES` needs at least one blocking finding. Then use these sections:
+
+```markdown
+## Goal sources
+- Original request (quoted, short), amendments, accepted constraints. Conflicts: <quotes, or none>
+
+## Trace
+- Forward: <goal → covering section, or gap>
+- Backward: <untraced item → scope drift, or none>
+
+## Blocking findings
+- [section] Problem. Repair: <specific change>
+
+## Decisions for the user
+- <goal change or open decision, or none>
+
+## Notes (non-blocking)
+- [section] Ponytail or SRP observation. Optional.
+```

package/src/monorepo/.claude/rules-snippets/subagent-workflow.md

@@ -71,42 +71,73 @@ When dispatching implementation tasks, match the specialist to the domain:
 
 ## Orchestration Patterns
 
-### Sequential (default)
+### Delegation Default
 
-Tasks with dependencies are implemented one at a time in dependency order. Each must pass review before the next begins.
+- **Delegate by default.** Hand substantial, safely separable discovery, implementation, test, and review work to subagents. Use a single agent only for trivial work, as listed under "When to Use a Single Agent Directly".
+- **The coordinator keeps outcome responsibility.** It defines each task's scope, reconciles every result, makes sure verification runs, and reports the final outcome. A subagent reporting success is not the outcome.
+- **Work directly only** for trivial changes (one small edit, a quick answer) or when the context is too heavy to hand off cheaply, such as work that depends on large context the coordinator already holds. Say why when you skip delegation.
+- **No delegation capability.** If the host offers no subagent dispatch, say so explicitly in the report. Do permitted direct work where it is safe. Never self-review in place of an independent gate: record the gate as pending and end as BLOCKED or WAITING.
 
-### Parallel
+### Dependency Graph and Parallel Batches (REQUIRED before dispatching)
 
-Independent tasks can be dispatched to multiple specialist subagents simultaneously. Use when tasks don't share files or state.
+Before dispatching any task list, the orchestrator builds the dependency graph. No `[P]` marker is required. If a task list has `[P]` markers, treat them as hints and verify them.
 
-### Parallelization Analysis (REQUIRED before dispatching)
+1. **Read and write sets.** For each task, list the files, directories, or packages it reads and writes.
+2. **Exclusive writable scopes.** Each writer gets a scope no other concurrent task writes. Two tasks that share any writable path are dependent. A task whose write set is unknown or undeclared runs serially until its scope is established from the changed-file list.
+3. **Data dependencies.** A task that reads what another task writes waits for that task.
+4. **Ready batch.** Tasks whose dependencies are satisfied and whose writable scopes are disjoint form one batch. Dispatch the whole batch together. Dependent and shared-write tasks run in later batches, one at a time.
+5. **Route by domain.** Backend tasks → Backend Architect; frontend → Frontend Developer; API contracts → API Specialist; docs → Documenter; cross-cutting → Implementer.
+6. **Track handles.** Record each dispatched task's handle, agent, writable scope, and status until its result is reconciled.
+7. **Reconcile before dependents.** Inspect each result (changed files, summary, verification) before dispatching any task that depends on it. If a result changed a path the graph did not expect, stop the affected tasks and re-plan the batch.
+8. **Continue the chain.** When a batch's results are reconciled, compute the next ready batch and dispatch it. Do not wait for the user unless a mandatory gate applies or no authorized, unblocked work remains (see Autonomous Execution and Blockers).
 
-Before executing any task list, the orchestrator MUST run this analysis:
-
-1. **Scan for `[P]` markers** in the task list — these are pre-identified parallel candidates
-   - If no `[P]` markers exist, do **not** assume sequential-only work. Treat all tasks as candidates and infer parallel-safe groups via the independence test.
-2. **Build a dependency graph**: For each task, list which files it reads and writes
-3. **Apply the independence test**:
-   - Tasks that write to **different files** with **no shared state** → parallel-safe
-   - Tasks that share any writable file → sequential (dependency edge)
-   - Tasks where one reads what another writes → sequential (data dependency)
-4. **Group by domain** for specialist routing:
-   - Backend tasks → Backend Architect
-   - Frontend tasks → Frontend Developer
-   - API contract tasks → API Specialist
-   - Documentation tasks → Documenter
-   - Cross-cutting → Implementer
-5. **Dispatch decision**:
-   - **3+ independent tasks** → Use `dispatching-parallel-agents` skill, one agent per task
-   - **2 independent tasks** → Parallel dispatch (simpler coordination)
-   - **All tasks dependent** → Sequential with `subagent-driven-development` skill
-   - **Mixed** → Dispatch independent group in parallel, then continue sequential chain
+**Dispatch shape:** 3+ independent tasks → `dispatching-parallel-agents`, one agent per task. 2 independent tasks → parallel dispatch. All tasks dependent → sequential with `subagent-driven-development`. Mixed → run each ready batch in parallel, then continue the sequential chain.
 
 ```
-Example: 5 tasks → T1 (setup) → T2 [P] (backend API) + T3 [P] (frontend UI) + T4 [P] (docs) → T5 (integration tests)
-         Dispatch: T1 sequential → T2+T3+T4 parallel → T5 sequential
+Example: 5 tasks → T1 (setup) → T2 (backend API) + T3 (frontend UI) + T4 (docs) → T5 (integration tests)
+         Batches: [T1] → [T2, T3, T4] → [T5]
+         T2, T3, and T4 run together only because their writable scopes are disjoint.
 ```
 
+## Turn Completion and Waiting
+
+During active multi-step execution, never end a turn silently, and never treat dispatch or partial progress as completion. End each such turn in exactly one of these states. Informational answers need no status line:
+
+- **DONE:** the requested work is complete and verified under Quality Gates. State the outcome and the validation that ran.
+- **WAITING:** name each pending task (handle and agent) and its resume trigger, such as a subagent notification or a user reply at a named gate. List what completed and what remains.
+- **BLOCKED / NEEDS-DECISION:** state the blocker or decision, what completed, what remains, and the exact next user action.
+
+Resume mechanics depend on the host:
+
+- When the host notifies on subagent completion, reconcile the notified result and continue with the next eligible batch. Check each handle once per notification.
+- When the host cannot resume in the background, do not claim that it will. Either run the batch in the foreground and collect the results within the turn, or end as WAITING and say that the user must send a message to resume, naming the exact step.
+- Do not busy-poll. Never loop on status checks.
+
+## Autonomous Execution and Blockers
+
+During multi-step execution, work autonomously within the approved goal, scope, and permissions. Autonomy grants no extra authority.
+
+- **A blocker pauses only the affected task and its dependents.** Independent ready work within authority continues in the next batch.
+- **Record each unresolved blocker immediately** in the existing progress record or the conversation: the affected task, what is needed and why, safe options or a targeted input, and the next action. Keep it visible in progress updates and the final report. Never drop it silently.
+- **Defer non-global blockers** as follow-up questions while work can safely advance.
+- **Stop for user input** only when no authorized, unblocked work remains, or when a mandatory approval, security, or permission gate prevents the remaining work. Agents still running are WAITING, not blocked.
+- **Ask clearly.** Present the consolidated outstanding questions through the harness's native question or clarification tool when one is available. Do not assume a tool name or support. Without one, give numbered options or a fill-in block in chat.
+- **Answers can arrive early.** Do not require a blocking tool prompt while independent work continues. Report deferred questions in progress updates.
+- **Never** silently choose a consequential scope or requirement change, bypass a required human approval, or mark a partially blocked task DONE.
+
+## Long-Session Checkpoint
+
+For sessions that span several batches or a context reset:
+
+- Use existing progress records only: a progress section the plan or task list already has, Factory job notes, or task records, when they exist. Keep the approved goal, current step, active task handles, blocker, and next action in those notes or in the conversation.
+- Never add fields to structured files such as Factory `job.json`, never rewrite accepted requirements or spec/plan text, and never replace an authoritative source with a summary.
+- If no such records exist, a short checkpoint in the conversation is enough. Do not create new files for trivial work.
+- On resume, reread the accepted source (spec, plan, or task text) instead of relying on the checkpoint summary, and check the working tree before dispatching anything.
+
+## Factory Approvals
+
+Spec and plan confirmations remain mandatory human steps; final approval, escalation, and merge behavior follow the job's `APPROVAL_MODE` and `MERGE_MODE`. Delegation, batching, autonomy, and subagent sign-offs never satisfy spec or plan human confirmation, or human final approval when `APPROVAL_MODE=human`. Mode-defined approver behavior is preserved. Stop at the gate and report it as WAITING or BLOCKED.
+
 ## Quality Gates
 
 - Every implementation must pass **Reviewer** before proceeding
@@ -122,7 +153,7 @@ When a subagent stops on a model capacity, quota, session limit, or reset-wait f
 - **Model order, one attempt each.** Try the next model in the configured fallback order for that agent. When the order is exhausted, try the harness's known available default, unless it was already tried. Then stop; do not cycle back.
 - **Never** retry the same unavailable model, and never wait blindly for a quota reset.
 - **Only supported switching.** Change the model through per-call selection the runtime supports, using only fallback models and defaults that are already configured or exposed. Do not invent model IDs, and do not edit persistent or global config, accounts, or billing.
-- **Blocker when nothing is left.** If no configured fallback or default is available, or per-call selection is unsupported, stop, report the blocker, and ask the user which model to use.
+- **Blocker when nothing is left.** If no configured fallback or default is available, or per-call selection is unsupported, the affected task is reported BLOCKED with the question of which model to use. Its dependents stop; independent authorized work continues (see Autonomous Execution and Blockers).
 - **Inspect before resuming.** Check what the failed attempt left in the working tree, then resume from that partial work. Never run two writers on the same files at once.
 - **Keep review independent.** The reviewer stays a separate agent from the builder, even when the builder moves to a fallback model.
 - **Disclose.** The final report names the original model, each fallback attempted, and the model that finished the work.

package/src/monorepo/AGENTS.md

@@ -77,7 +77,7 @@ For CLI command reference, see the matching skill: `.agents/skills/{acli,gh-cli,
 
 #### 1. Proactive Clarification
 
-- **Identify Ambiguity**: Stop and ask if a task lacks clear acceptance criteria, inputs, or expected outputs.
+- **Identify Ambiguity**: Ask a targeted question if a task lacks clear acceptance criteria, inputs, or expected outputs. It blocks only that task and its dependents; independent work with clear requirements continues (see the "Autonomy with blockers" bullet under Operating Rules).
 - **Resolve Conflicts**: Flag conflicting instructions between the user prompt, existing code, and documentation before writing code.
 - **Expose Assumptions**: State your assumptions clearly and ask for validation before proceeding with high-impact changes.
 
@@ -268,7 +268,10 @@ Use custom agents when you want explicit coordinator and worker roles. Use workf
 - Do not make an implementation subagent read the plan file on its own; pass the relevant task directly.
 - In `subagent-driven-development`, keep the review order strict: spec compliance first, then code quality.
 - If a reviewer finds issues, fix them and re-run the same review before moving on.
-- Do not run multiple implementation subagents in parallel when they could touch shared packages, shared docs, or the same app surface.
+- Parallel implementation subagents need exclusive writable scopes. If scopes could overlap (shared packages, shared docs, or the same app surface), or one task reads another's output, run them sequentially. See `.claude/rules-snippets/subagent-workflow.md` for the dependency graph and batch rules.
+- Delegate substantial, separable work by default; the coordinator stays responsible for the outcome and reconciles each result before dispatching dependents.
+- **Never end silently** — During active multi-step execution, end each turn as DONE, WAITING (pending task handle and resume trigger), or BLOCKED / NEEDS-DECISION (what completed, what remains, exact next user action). Dispatch or partial progress is not completion. Spec and plan confirmations remain mandatory human steps; final approval, escalation, and merge behavior follow the job's `APPROVAL_MODE` and `MERGE_MODE`. Delegation or autonomy alone never satisfies a gate.
+- **Autonomy with blockers** — Work autonomously within the approved goal, scope, and permissions. A blocker pauses only its task and dependents: record it, defer non-global questions, and continue independent authorized work. Stop for the user only when no authorized work remains or a mandatory gate applies, and ask through the harness's native question tool when one exists.
 - For cross-app work, research boundaries first, sequence shared package changes before app-specific changes, and review downstream impact explicitly.
 
 #### Recommended Flow
@@ -343,8 +346,8 @@ Workers are dispatched by coordinators and are not directly user-invocable.
 - Admin dashboards, RBAC, reporting, monitoring → Admin Portal
 - General implementation → Implementer
 
-**Sequential**: Tasks with dependencies are implemented one at a time.
-**Parallel**: Independent tasks (e.g., changes in different apps) can be dispatched to multiple subagents simultaneously.
+**Sequential**: Dependent tasks, and tasks that share a writable file or package, run one at a time in dependency order.
+**Parallel**: Ready tasks with exclusive writable scopes (e.g., changes in different apps) run together as one batch. Reconcile each batch's results before dispatching the next.
 
 **Monorepo-specific**: When implementing features that span multiple apps, coordinate carefully:
 
@@ -366,7 +369,7 @@ Subagents are typically **agent-initiated** — the coordinator decides when to
 
 ### Factory (opt-in)
 
-An optional file-driven pipeline for feature-sized work, alongside Feature Builder and TDD. Start it with `/factory <request>` in Claude Code, Copilot, Cursor, or OpenCode. The orchestrator reads the project and asks only the glaring questions before it creates anything, then asks you to continue or change the answers. Resume a feature with `/factory start <KEY | slug | job-id>`. Codex runs the orchestrator skill directly. Each job belongs to a feature folder in `docs/features/`, stops at a spec gate and a plan gate for your confirmation before any ticket or build, builds in its own git worktree unless you ask for `--in-place`, and moves its tickets when the project tracks them. The orchestrator is [.agents/skills/factory/SKILL.md](.agents/skills/factory/SKILL.md). It runs on the native `planner` (spec and plan), `implementer` (build, repair, and rework), and `reviewer` (the code, security, ux, and ui lenses, and approval) agents. Each role's Factory rules are in its brief in `.agents/skills/factory/roles/`. Setup, placeholders, and approval modes are in [factory/README.md](factory/README.md). Jobs name the affected apps and packages in their spec, and checks run for those with the filtered commands in [Commands](#commands).
+An optional file-driven pipeline for feature-sized work, alongside Feature Builder and TDD. Start it with `/factory <request>` in Claude Code, Copilot, Cursor, or OpenCode. The orchestrator reads the project and asks only the glaring questions before it creates anything, then asks you to continue or change the answers. Resume a feature with `/factory start <KEY | slug | job-id>`. Codex runs the orchestrator skill directly. Each job belongs to a feature folder in `docs/features/`, stops at a spec gate and a plan gate for your confirmation before any ticket or build, builds in its own git worktree unless you ask for `--in-place`, and moves its tickets when the project tracks them. The orchestrator is [.agents/skills/factory/SKILL.md](.agents/skills/factory/SKILL.md). It runs on the native `planner` (spec and plan), `implementer` (build, repair, and rework), and `reviewer` (the code, security, ux, and ui lenses, and approval) agents. Each role's Factory rules are in its brief in `.agents/skills/factory/roles/`. Spec and plan goal-fit must be confirmed by an independent Oracle or read-only reviewer, not the spec or plan author. Single-session role switching, including the Codex fallback, does not satisfy that and blocks these gates. Spec and plan confirmations stay mandatory human steps in every approval mode. Setup, placeholders, and approval modes are in [factory/README.md](factory/README.md). Jobs name the affected apps and packages in their spec, and checks run for those with the filtered commands in [Commands](#commands).
 
 ## Documentation Requirements
 

package/src/monorepo/factory/README.md

@@ -55,7 +55,7 @@ The orchestrator and agents are the same in every harness. Each harness has its
 | GitHub Copilot | `/factory` prompt (`.github/prompts/factory.prompt.md`) | `.github/agents/` |
 | Cursor | `/factory` (`.cursor/commands/factory.md`) | `.cursor/agents/` |
 | OpenCode | `/factory` (`.opencode/commands/factory.md`) | `.opencode/agents/` |
-| Codex | The factory skill (`.agents/skills/factory/SKILL.md`) | None. Runs each role brief directly, one role at a time in one session (see Harness notes in SKILL.md) |
+| Codex | The factory skill (`.agents/skills/factory/SKILL.md`) | No native agent definitions. Role briefs run directly; spec and plan acceptance requires an independent review session. Single-session role switching cannot satisfy that gate (see Harness notes in SKILL.md). |
 
 In OpenCode with the Slim plugin, `oracle` and `designer` are optional alternatives to `reviewer`, if you configure them as edit-denied. The default is the native agents.
 
@@ -83,6 +83,8 @@ Sizing is decided in `plan.md`:
 
 Every job stops twice, in every approval mode, before anything is ticketed or built:
 
+Before either confirmation, an independent read-only Oracle, or reviewer when Oracle is unavailable, checks goal fit. Revisions and resumed gates are reviewed again. Missing independent review blocks acceptance, including single-session Codex use; it does not block discussing unresolved decisions. If the original requirements cannot be recovered, the operator must confirm the recovered baseline rather than treating an agent-written summary as the original request.
+
 1. **Spec gate** (`awaiting-spec`). You read the spec summary, the acceptance criteria count, each open `[PRODUCT DECISION]` item, and open questions. Answer every open decision before you confirm: answers go in your change request, are saved as `spec-<k>.md`, and the spec writer records each one as `[DECIDED]`.
 2. **Plan gate** (`awaiting-plan`). You read the plan, the tasks, the size, the tracking proposal, and the build mode. Confirm, request changes (saved as `plan-<k>.md`), or change size, tracking, or build mode. Requests that touch the spec go back through the spec gate.
 
@@ -90,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`.
 
@@ -126,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 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 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 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
 
@@ -151,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/dispatching-parallel-agents/SKILL.md

@@ -139,7 +139,7 @@ For full-stack or cross-cutting features, dispatch domain specialists in paralle
 | Multi-subsystem fix | Backend Architect (service A) + Backend Architect (service B) | Independent service bugs                                     |
 | Cross-app monorepo  | Specialist per app                                            | Same feature in `apps/web` + `apps/api` (no shared packages) |
 
-**Safe to parallelize:** Agents touch different files/directories with no shared state.
+**Safe to parallelize:** Agents have exclusive writable scopes (no shared files/directories) and no shared state. Build the dependency graph first; see `.claude/rules-snippets/subagent-workflow.md`.
 **Still sequential:** Tasks that share files, database migrations, or API contracts that one depends on.
 
 ## When NOT to Use