fix: resolve Quick Flow review failures

AGENTS.md

@@ -43,6 +43,7 @@ This is a **Spec-Kit preset, extension, and bundle**, not an application. It def
 | `scripts/resolve-bug-context.py` | Records the standard bug extension's active bug directory in `feature.json` |
 | `scripts/check-bug-verdict.py` | Validates the standard bug extension's `test.md` result |
 | `scripts/init-quick.py` | Reads the run's `inputs.json`/`resolved-spec.txt` and creates or reuses a Quick Flow feature directory and `feature.json` pointer (`type: "quick"`) |
+| `scripts/preserve-quick-review.py` | Commits Quick Flow work before a failed review's resolution gate |
 | `scripts/resolve-pr-template.py` | Discovers a pull-request template in the downstream project using GitHub-standard search paths |
 | `scripts/load-models.py` | Resolves the per-step model config (`model.config.json`) into `load-models.output.data` for each flow |
 | `scripts/package-preset.py` | Builds the preset ZIP package |
@@ -121,7 +122,7 @@ Must preserve:
 - **Doc Reconciliation**: The post-implementation step that updates layered documentation and flags code-vs-docs conflicts.
 - **Spec-Kit Contract**: The interface between workflow steps where `stdout` of one step becomes the `args` of the next.
 - **Bugfix Flow**: A standard Spec-Kit bug workflow (`resolve → assess → fix → test → finish`) for surgical bugfixes without spec/plan/tasks generation.
-- **Quick Flow**: A lightweight workflow (`resolve → init-quick → quick-plan → plan-gate → implement → review-fix → doc-check → finish`) for trivial, well-defined changes (label renames, message additions). Generates a minimal plan reviewed at a human gate, but no spec or task-list. Self-fixing review in a single pass.
+- **Quick Flow**: A lightweight workflow (`resolve → init-quick → quick-plan → plan-gate → record-scope → implement → review-fix → resolution → doc-check → finish`) for trivial, well-defined changes (label renames, message additions). The reviewer validates the gate-approved plan scope, and a FAIL routes to explicit partial-ship, Feature Flow handoff, or abort choices.
 - **Sub-Agent Delegation**: The `sub-agent-delegation` preset's mechanism-neutral preamble, prepended to the parallelizable core commands. It maps the active integration (read from `.specify/integration.json`) to that backend's sub-agent primitive and falls back to sequential execution when none exists.
 
 ## Known Issues
@@ -134,7 +135,7 @@ Must preserve:
 - **Agent behaviors**: See `commands/speckit.extendedflow.documentation.md`, `commands/speckit.extendedflow.finish.md`, `commands/speckit.extendedflow.quick-plan.md`, `commands/speckit.extendedflow.quick-implement.md`, `commands/speckit.extendedflow.quick-review.md`, `commands/speckit.extendedflow.doc-check.md`, plus the standard `speckit.bug.assess`, `speckit.bug.fix`, and `speckit.bug.test` commands from Spec-Kit's `bug` extension. The Feature Flow's QA loop uses the standard `speckit.analyze` and `speckit.implement`/`speckit.converge` commands.
 - **Output templates**: See `templates/review-findings.md`, `templates/documentation.md`
 - **Input resolution logic**: See `scripts/resolve-spec.py`
-- **Branch creation and verdict extraction**: See `scripts/create-branch.py`, `scripts/check-converge.py`, `scripts/extract-verdict.py`, `scripts/resolve-bug-context.py`, `scripts/check-bug-verdict.py`
+- **Branch creation and verdict extraction**: See `scripts/create-branch.py`, `scripts/check-converge.py`, `scripts/extract-verdict.py`, `scripts/preserve-quick-review.py`, `scripts/resolve-bug-context.py`, `scripts/check-bug-verdict.py`
 - **PR template resolution**: See `scripts/resolve-pr-template.py`
 - **Bundle composition**: See `bundle.yml`
 - **Architecture & design rationale**: See `README.md`

README.md

@@ -49,7 +49,7 @@ Extended Flow ships a **family of composable flows** that share issue-to-PR auto
 
 - **Feature Flow** — the SDD lifecycle for new features (`specify → plan → tasks → analyze → implement → converge → documentation → finish`).
 - **Bugfix Flow** — the standard Spec-Kit bug lifecycle (`assess → fix → test → finish`), skipping spec/plan/tasks generation.
-- **Quick Flow** — a lightweight pipeline for trivial, well-defined changes (`plan → plan-gate → implement → review-fix → doc-check → finish`). A minimal plan is reviewed at a human gate; no spec or task-list, and the self-fixing review runs in a single pass.
+- **Quick Flow** — a lightweight pipeline for trivial, well-defined changes (`plan → plan-gate → implement → review-fix → resolution → doc-check → finish`). A minimal plan is approved at a human gate and becomes the review baseline; no spec or task-list, and the self-fixing review runs in a single pass.
 
 See [Flows](docs/flows.md) for the full diagrams and step-by-step breakdown. The family is designed to grow — future flows slot in as peers.
 
@@ -110,7 +110,7 @@ specify workflow run spec-kit-quick-flow \
   --input issue="42"
 ```
 
-**What happens:** The workflow writes a minimal plan from your instruction and pauses at a plan gate for your approval, then implements the change, runs a self-fixing review in a single pass, checks documentation impact, and commits and opens a PR. No spec or task-list generation — ideal for label changes, message additions, and other trivial tweaks.
+**What happens:** The workflow writes a minimal plan from your instruction and pauses at a plan gate for your approval. The approved scope guides implementation and review, then the flow checks documentation impact and commits and opens a PR. A genuine review FAIL preserves a WIP commit and offers explicit partial-ship, Feature Flow handoff, or abort choices. No spec or task-list generation — ideal for label changes, message additions, and other trivial tweaks.
 
 <details>
 <summary><strong>Other input modes</strong></summary>
@@ -203,7 +203,7 @@ A standard Spec-Kit bug lifecycle for surgical bugfixes. It uses `speckit.bug.as
 
 ### Quick Flow
 
-A lightweight pipeline for trivial, well-defined changes. Produces a minimal plan that pauses at a human gate, then implements and uses a **self-fixing review** in a single pass. No spec or task-list. See [docs/flows.md](docs/flows.md#quick-flow) for the full diagram and step table.
+A lightweight pipeline for trivial, well-defined changes. Produces a minimal plan that pauses at a human gate, then implements and uses a **self-fixing review** in a single pass. Its reviewer uses the approved plan as scope, so documented deferrals do not fail review. A genuine FAIL is resolved explicitly as partial ship, Feature Flow handoff, or abort. No spec or task-list. See [docs/flows.md](docs/flows.md#quick-flow) for the full diagram and step table.
 
 ---
 

commands/speckit.extendedflow.doc-check.md

@@ -9,7 +9,7 @@ You are the documentation safety net for simple changes. Full documentation reco
 ## Inputs
 
 1. **Feature Directory** — read `.specify/feature.json` to determine the current feature directory.
-2. **Instruction** — read `specs/<feature-dir>/instruction.md` for context on what was changed.
+2. **Approved Plan** — read `specs/<feature-dir>/plan.md` for context on what was changed, including an explicitly approved partial shipment.
 3. **Code changes** — analyze the git diff to identify modified files.
 
 ## Steps

commands/speckit.extendedflow.finish.md

@@ -81,6 +81,7 @@ Read the following files from the feature directory (use `feature_directory` fro
 
 **For quick flows (`type` IS `"quick"`):**
 - `instruction.md` — Extract the original change instruction (1-2 sentences).
+- `plan.md` — Extract the approved in-scope work plus any deferred work.
 - `doc-check.md` — Extract the documentation check summary (1 sentence).
 
 If any of these files do not exist, skip them silently.
@@ -91,9 +92,11 @@ For feature flows, read `tasks.md` from the feature directory. The workflow has
 - If no unchecked tasks remain, note "Converged against spec, plan, and tasks".
 - If unchecked tasks remain, note "Implementation not fully converged".
 
-For quick flows, find the latest (highest iteration number) `review-findings-*-PASS.md` file inside the feature directory.
-- If found, extract the verdict (`PASS`) and the `## Summary` section (2-3 sentences).
-- If no PASS review findings exist, note "Quick review not yet recorded".
+For quick flows, find the latest (highest iteration number) `review-findings-*-{PASS|FAIL}.md` file inside the feature directory.
+- If it is PASS, extract the verdict and the `## Summary` section (2-3 sentences).
+- If it is FAIL, read `.specify/workflows/runs/<run_id>/state.json`. Continue only when `steps.quick-review-resolution.output.choice` is `ship-partial`; otherwise stop without cleanup, commit, or PR creation because the unresolved work must be escalated or aborted.
+- For an approved partial shipment, state that the Quick Flow review reported unresolved in-scope work, the operator explicitly selected `ship-partial`, and summarize the deferred work from `plan.md`.
+- If no review findings exist, stop without cleanup, commit, or PR creation.
 
 For bugfix flows (`type` IS `"bug"`), read `test.md` and extract its `Result` field (`verified`, `partial`, or `failed`) and summary. Do not look for a review-findings file.
 
@@ -176,7 +179,7 @@ Use the template content as the starting point. Fill the following known section
 Known section headings (case-insensitive, match `# ` or `## ` prefixes):
 - `Summary` / `Description` / `Overview` → Fill with the spec summary (feature), root-cause + fix strategy (bugfix), or original instruction (quick).
 - `Changes` / `What Changed` / `What does this PR do?` → Fill with the main implementation changes (files/modules touched).
-- `Testing` / `Test Plan` / `How to test` → Fill with the convergence status (feature), quick review verdict (PASS), or bug verification result, and a brief note on test coverage (e.g., "Full test suite passes; bug reproduction test was RED then GREEN").
+- `Testing` / `Test Plan` / `How to test` → Fill with the convergence status (feature), quick review verdict (PASS or explicitly approved partial shipment), or bug verification result, and a brief note on test coverage (e.g., "Full test suite passes; bug reproduction test was RED then GREEN").
 - `Documentation` / `Docs` → Fill with the documentation change summary from Step 2d, or "No documentation changes required."
 - `Related Issues` / `Closes` / `Fixes` → Ensure `Closes #<issue>` appears here or elsewhere in the body.
 
@@ -194,7 +197,7 @@ Generate a structured body with these sections:
 <Brief list of main implementation changes and files touched>
 
 ## Testing
-<Convergence status (feature), quick review verdict (PASS), or bug verification result. Notes on test coverage.>
+<Convergence status (feature), quick review verdict (PASS or explicitly approved partial shipment), or bug verification result. Notes on test coverage.>
 
 ## Documentation
 <Summary of doc updates, or "No documentation changes required.">`

commands/speckit.extendedflow.quick-implement.md

@@ -10,7 +10,7 @@ You are the implementer for simple changes: label renames, message additions, sm
 
 1. **Instruction text** — passed as args (from `resolve-spec.py` stdout). This is the complete change request.
 2. **Feature Directory** — read `.specify/feature.json` to determine the current feature directory (e.g., `specs/42-quick-change-login-label`).
-3. **Plan** — read `specs/<feature-dir>/plan.md` (produced by quick-plan and approved at the gate). It names the files to change and the verification approach.
+3. **Approved Plan** — read `specs/<feature-dir>/plan.md`. The plan was approved at the preceding gate.
 
 ## Outputs
 
@@ -21,15 +21,15 @@ You are the implementer for simple changes: label renames, message additions, sm
 
 1. Read `.specify/feature.json` to determine the feature directory.
 2. Write the instruction text to `specs/<feature-dir>/instruction.md`. This preserves the original request for the review agent.
-3. Read `specs/<feature-dir>/plan.md` for the approved files-to-change and verification approach.
+3. Read `specs/<feature-dir>/plan.md` and follow the plan approved at the preceding gate.
 4. Analyze the codebase to locate the relevant code for the requested change.
 5. Implement the change — make the minimal, targeted modification described in the instruction and plan.
 6. Run existing tests to verify no regressions.
 7. Run lints / type-checks to verify code quality.
 
 ## Constraints
 
-- **Follow the approved plan** — implement the change the plan describes. If the plan is wrong or incomplete, report this and stop rather than expanding scope.
+- **Follow the approved plan** — implement only the plan's `In Scope` work. Do not implement `Deferred` or `Out of Scope` items. If the plan is wrong or incomplete, report this and stop rather than expanding scope.
 - **Minimal change** — implement ONLY what the instruction requests. No refactors, no improvements beyond the request.
 - **No scope expansion** — do not add features, fix unrelated bugs, or restructure code.
 - **Preserve existing behavior** — the change must not break any existing tests or functionality.

commands/speckit.extendedflow.quick-plan.md

@@ -4,7 +4,7 @@ You are the **Quick Plan Agent** — a focused planning agent for trivial, well-
 
 ## Your Role
 
-You are the planning step for simple changes: label renames, message additions, small tweaks. The instruction you receive IS the specification — it is complete and unambiguous. You do NOT generate specs or task breakdowns, and you do NOT write code. You produce a minimal plan that names the files to touch, the exact change, and how it will be verified.
+You are the planning step for simple changes: label renames, message additions, small tweaks. The instruction you receive IS the specification — it is complete and unambiguous. You do NOT generate specs or task breakdowns, and you do NOT write code. You produce a minimal plan that names the approved scope, files to touch, exact change, and verification.
 
 ## Inputs
 
@@ -34,6 +34,9 @@ Write `specs/<feature-dir>/plan.md` with this structure:
 ## Summary
 <One sentence describing the change.>
 
+## In Scope
+<Every requested outcome that this Quick Flow will implement.>
+
 ## Files to Change
 | File | Change |
 |------|--------|
@@ -42,12 +45,19 @@ Write `specs/<feature-dir>/plan.md` with this structure:
 ## Verification
 <How the change will be verified: tests to run, lints, type-checks, manual check.>
 
+## Deferred
+<Requested work intentionally not implemented in this run, with the reason. Write "None" when empty.>
+
+## Out of Scope
+<Known branch changes or requested work this run must not implement. Write "None" when empty.>
+
 ## Risks / Assumptions
 <None, or the assumptions made and anything that may need a design decision.>
 ```
 
 ## Constraints
 
+- **Complete scope record** — `In Scope`, `Deferred`, and `Out of Scope` are mandatory. Use `None` for an empty section; never omit one.
 - **Minimal plan** — describe ONLY what the instruction requests. No refactors, no improvements beyond the request.
 - **No scope expansion** — do not plan features, unrelated bug fixes, or restructuring.
 - **No code changes** — you plan; you do not implement.

commands/speckit.extendedflow.quick-review.md

@@ -1,6 +1,6 @@
 # Spec-Kit Extended Flow Quick Review Agent
 
-You are the **Quick Review Agent** — a self-correcting quality assurance agent for trivial changes. You review the implementation against the original instruction and **fix any issues you find directly**, in a single pass.
+You are the **Quick Review Agent** — a self-correcting quality assurance agent for trivial changes. You review the implementation against the approved scope and **fix any issues you find directly**, in a single pass.
 
 ## Your Role
 
@@ -10,25 +10,27 @@ You are both reviewer and fixer, combined into one step. For trivial changes (la
 
 1. **Feature Directory** — read `.specify/feature.json` to determine the current feature directory.
 2. **Instruction** — read `specs/<feature-dir>/instruction.md` for the original change request.
-3. **Implementation** — analyze all code changes made by the quick-implement agent.
+3. **Approved Plan** — read `plan.md`, which was approved at the preceding gate.
+4. **Implementation** — analyze all code changes made by the quick-implement agent.
 
 ## Steps
 
 1. Read `.specify/feature.json` to determine the feature directory.
-2. Read `specs/<feature-dir>/instruction.md` for the authoritative change request.
-3. Analyze the code changes against the instruction:
-   - Does the implementation satisfy the instruction completely?
+2. Read `instruction.md` and `plan.md`.
+3. Treat `plan.md`'s `In Scope` section and verification requirements as the review baseline. `Deferred` and `Out of Scope` sections are context, not failures.
+4. Analyze the code changes against the approved scope:
+   - Does the implementation satisfy all in-scope outcomes?
    - Are there logic errors, typos, or missed locations?
    - Are existing tests still passing?
    - Are there any regressions?
-4. **If you find issues — fix them directly.** Make surgical corrections in the same pass.
-5. After fixing, re-verify: run tests, lints, and type-checks to confirm everything is clean.
-6. Write `review-findings-1-{VERDICT}.md` inside the feature directory using the `review-findings` template.
+5. **If you find issues — fix them directly.** Make surgical corrections in the same pass.
+6. After fixing, re-verify: run tests, lints, and type-checks to confirm everything is clean.
+7. Write `review-findings-1-{VERDICT}.md` inside the feature directory using the `review-findings` template.
 
 ## Verdict Rules
 
-- **PASS** — The implementation (after your self-corrections, if any) satisfies the instruction completely. All tests pass, no regressions.
-- **FAIL** — You found issues that you could NOT resolve yourself. This means the change is too complex for the Quick Flow and belongs in the Feature Flow.
+- **PASS** — The implementation (after your self-corrections, if any) satisfies every approved in-scope outcome. Explicitly deferred or out-of-scope items do not cause FAIL. All applicable tests pass and there are no regressions.
+- **FAIL** — You found an unresolved in-scope issue, could not verify the approved scope, or could not complete required verification. This may require Feature Flow, partial shipment, or an explicit abort decision.
 
 ## Output Requirements
 
@@ -46,7 +48,8 @@ Specifically:
 
 3. **Document findings**: Log any issues you found and how you resolved them (or why you could not).
 
-4. **On FAIL**: Explain clearly what could not be resolved and why the Feature Flow is needed.
+4. **On FAIL**: Explain clearly what could not be resolved, whether a partial shipment is safe, and why Feature Flow may be needed.
+5. **Always complete successfully after writing the file.** `FAIL` is workflow data, not a command failure. Never exit nonzero solely because the verdict is FAIL.
 
 ## Constraints