feat(dev-auto): preserve the attempted change on intent-gap halts (#2564)

The intent_gap branch reverted code changes before halting, destroying
information: the attempted diff shows the human exactly which reading
the agent implemented, which is concrete evidence for repairing the
intent — and occasionally the guessed reading is simply right.

Save the attempt as a patch file in {implementation_artifacts} before
reverting, reference it from the triage log, and include its path in
the halt output. Restart stays default-clean (blocked keeps discard
semantics; the tree is reverted as before); if the human decides the
attempted reading was correct, git apply + status in-review resumes
review on it instead of paying for a full re-run.

Also unify the blocking-condition vocabulary: 'intent gaps' (step-02)
and 'intent gap in intent contract' (step-04) both become 'intent gap'
— one condition, one meaning; the artifact shows which phase raised it.

Document the artifact, the recovery affordance, and the unified
condition in the integration reference (docs/reference/dev-auto.md).

Author: alexeyv

docs/reference/dev-auto.md

@@ -104,13 +104,14 @@ On blocked completion, the workflow writes:
 Typical blocking conditions include:
 
 - `unclear intent`
-- `intent gaps`
+- `intent gap`
 - `no subagents`
 - `missing spec_file before implementation`
 - `implementation verification failed`
-- `intent gap in intent contract`
 - `review repair loop exceeded 5 iterations (non-convergence)`
 
+An `intent gap` means the captured intent cannot answer a question the run hit — it can halt the planning step (before any code exists) or the review step. When review halts on it, the working tree is reverted as usual, but the attempted change is first saved as a patch file in `{implementation_artifacts}`, referenced from the spec's triage log and the halt output. The patch shows which reading of the intent the run implemented — concrete evidence for repairing the intent. If the attempted reading turns out to be correct, `git apply` the patch and set the spec status to `in-review` to resume review on it instead of re-running from scratch.
+
 ## Output Artifacts
 
 The workflow always tries to leave behind a durable artifact describing what happened.
@@ -145,6 +146,7 @@ Depending on the route, the workflow may also write:
 
 - `{implementation_artifacts}/epic-<N>-context.md`
 - `{implementation_artifacts}/deferred-work.md`
+- A patch file preserving the attempted change when the review step halts on `intent gap` (path recorded in the spec's triage log)
 
 ## Orchestrator Responsibilities
 

src/bmm-skills/4-implementation/bmad-dev-auto/step-02-plan.md

@@ -15,7 +15,7 @@ deferred_work_file: '{implementation_artifacts}/deferred-work.md'
 2. Investigate codebase. _Read the code yourself for narrow, localized tasks. Isolate deep exploration in subagents: instruct them to give you distilled summaries only, and plan from those summaries._
 3. Read `./spec-template.md` fully. Fill it out based on the intent and investigation. If `{preserved_intent_contract}` is non-empty, substitute it for the `<intent-contract>` block in your filled spec before writing. Write the result to `{spec_file}`.
 4. Self-review against READY FOR DEVELOPMENT standard.
-5. If intent gaps exist, do not fantasize and do not leave open questions. Multiple defensible readings of the intent that lead to observably different outcomes, with nothing in the intent to select between them, are an intent gap — do not resolve one by picking a reading. HALT with status `blocked`, blocking condition `intent gaps`, and include the unanswered questions and evidence gathered.
+5. If intent gaps exist, do not fantasize and do not leave open questions. Multiple defensible readings of the intent that lead to observably different outcomes, with nothing in the intent to select between them, are an intent gap — do not resolve one by picking a reading. HALT with status `blocked`, blocking condition `intent gap`, and include the unanswered questions and evidence gathered.
 6. Warning check. If step-01 carried `multiple-goals`, add it to `{spec_file}` frontmatter `warnings`. If `{spec_file}` exceeds 1600 tokens, add `oversized` to frontmatter `warnings`. Continue either way.
 
 ### READY-FOR-DEVELOPMENT GATE

src/bmm-skills/4-implementation/bmad-dev-auto/step-04-review.md

@@ -63,7 +63,7 @@ Execute all remaining layers in parallel wherever their execution methods allow:
      - none
    ```
 5. Process findings in cascading order. If intent_gap exists, lower findings are moot; follow the intent_gap branch below. If bad_spec exists, lower findings are moot since code will be re-derived. If neither exists, process patch and defer normally. Before each bad_spec loopback, read `{spec_file}` frontmatter `review_loop_iteration` (missing means `0`), increment it by 1, and write it back. If it exceeds 5, append the triage-log entry for this pass with `addressed_findings: none`, then HALT with status `blocked` and blocking condition `review repair loop exceeded 5 iterations (non-convergence)`.
-   - **intent_gap** — Root cause is inside `<intent-contract>`. Revert code changes. Append the triage-log entry for this pass with `addressed_findings: none`, then HALT with status `blocked`, blocking condition `intent gap in intent contract`, and include the intent-gap findings.
+   - **intent_gap** — Root cause is inside `<intent-contract>`. Save the attempted change as a patch file in `{implementation_artifacts}` and reference it from the triage-log entry, then revert code changes. Append the triage-log entry for this pass with `addressed_findings: none`, then HALT with status `blocked`, blocking condition `intent gap`, and include the unresolved questions and the saved patch path.
    - **bad_spec** — Root cause is outside `<intent-contract>`. Do not modify content inside `<intent-contract>`. Before reverting code: extract KEEP instructions for positive preservation (what worked well and must survive re-derivation). Revert code changes. Read the `## Spec Change Log` in `{spec_file}` and strictly respect all logged constraints when amending the sections outside `<intent-contract>` that contain the root cause. Append a new change-log entry recording: the triggering finding, what was amended, the known-bad state avoided, and the KEEP instructions. Append the triage-log entry for this pass, listing every bad_spec finding that triggered the spec amendment and implementation loopback under `addressed_findings`. Read fully and follow `./step-03-implement.md` to re-derive the code, then this step will run again.
    - **patch** — Auto-fix. These are the only findings that survive loopbacks. After auto-fixing, append the triage-log entry for this pass, listing every patch fixed in this pass under `addressed_findings`.
    - **defer** — Append one new entry to `{deferred_work_file}` using this format. Do not modify existing entries or look for duplicates.