devflow-kit 3.4.0 → 3.5.0

package/dist/commands/implement.md

@@ -46,13 +46,13 @@ When the user explicitly asks to re-validate, re-check, or re-run quality gates
 2. **Skip Phase 2** — no Code agent needed, user already made changes.
 3. **Detect FILES_CHANGED**: `git diff --name-only {base_branch}...HEAD`
 4. **Run Phases 3-8** — Simplify, Self-Review, Alignment, the one full Validate, QA Testing and the conditional Re-Validate, on the detected changes.
-5. **Proceed to Phase 10** (Create PR), **Phase 10b** (Evidence) and **Phase 11** (Report).
+5. **Proceed to Phase 9** (Open PR), **Phase 11** (Evidence) and **Phase 12** (Report).
 
 If the user prompt does NOT match re-validation, proceed with the full pipeline below.
 
 ### Phase 1: Setup
 
-**Produces:** TASK_ID, BASE_BRANCH, EXECUTION_PLAN, DECISIONS_CONTEXT, FEATURE_KNOWLEDGE, FEATURE_KNOWLEDGE_RULES, PR_DESCRIPTION_GUIDANCE, ISSUE_NUMBER, EVIDENCE_POLICY, ISSUE_REQUIRED, APPLY_CONVENTIONS, REQUIRE_NON_AUTHOR_APPROVAL, PR_EXCEPTIONS, TEST_PLAN, EVIDENCE_FILE, PR_TEST_PLAN_BLOCK, REVIEW_PUBLICATION
+**Produces:** TASK_ID, BASE_BRANCH, EXECUTION_PLAN, DECISIONS_CONTEXT, FEATURE_KNOWLEDGE, FEATURE_KNOWLEDGE_RULES, PR_DESCRIPTION_GUIDANCE, ISSUE_NUMBER, ISSUE_PR_LINK, EVIDENCE_POLICY, ISSUE_REQUIRED, APPLY_CONVENTIONS, REQUIRE_NON_AUTHOR_APPROVAL, PR_EXCEPTIONS, TEST_PLAN, EVIDENCE_FILE, PR_TEST_PLAN_BLOCK, REVIEW_PUBLICATION
 
 Record the current branch name as `BASE_BRANCH` - this will be the PR target.
 
@@ -135,6 +135,7 @@ visible, a silently discarded request is not.
 - `TASK_ID`: The branch name created by Git agent (use as TASK_ID for rest of flow)
 - `BASE_BRANCH`: Branch this feature was created from (for PR target)
 - `ISSUE_NUMBER`: the provider-canonical issue identifier for this task — the same value the Git agent emits as `ISSUE_ID` (if provided, or created by the Git agent's issue-first step in setup-task)
+- `branch_slug`: `TASK_ID` with every `/` replaced by `-`. It names `handoff-{branch_slug}.md` and `evidence-{branch_slug}.md` only when it matches `^[A-Za-z0-9._-]{1,200}$`; any other branch name stops the run here, telling the user it cannot name those files.
 
 **Capture from the Git agent's Output block, as written:** `ISSUE_REF` (the rendered reference in the `## Issue {ISSUE_REF}:` heading), `ISSUE_ID` (the `- **Issue ID**:` line under `### Handoff Values`), `ISSUE_CONTENT` (the body between the `<untrusted-issue-body>` markers), `ACCEPTANCE_CRITERIA`, `ISSUE_PR_LINK` (the `- **PR link line**:` line) and `ISSUE_BRANCH_TOKEN` (the `- **Branch token**:` line). Read every value from the block that emits it; never re-derive one value from another, and never infer any of them from a `TRACEABILITY: DEGRADED ({reason})` status line — a DEGRADED line is a status, not issue content.
 
@@ -160,7 +161,7 @@ Note: `ISSUE_CONTENT` stays inside its `<untrusted-issue-body>` markers wherever
 
 Note: the section reaches a public PR body. The Code agent re-checks every line against this shape before it pastes, and the body's D11 scrub is the reason's secret scrub — rendering filters no secrets. A rendered reason carries no HTML or comment markers, link or image syntax, @-mentions, `#N` or full-URL references (no `/` survives), entities or shell-expansion characters; plain emphasis and `www.` or `GH-N` autolinks can remain — the requester authors the reason.
 
-**Record the exception at once**, before any Code spawn: write the rendered section as the `## Evidence Exceptions` section of `{worktree}/.devflow/docs/handoff-{branch_slug}.md`, creating the file if absent, and set `PR_EXCEPTIONS` to that section. The file is its one home until the PR exists: every later write to the file keeps the section byte-identical, every PR-creating Code spawn passes it verbatim as `PR_EXCEPTIONS`, and the file is deleted only once the PR exists — after the PR-creating Phase 2 Code agent under SINGLE_CODE_AGENT and SEQUENTIAL_CODE_AGENTS, after Phase 10 under PARALLEL_CODE_AGENTS. With no exception recorded, `PR_EXCEPTIONS` is `(none)`.
+**Record the exception at once**, before any Code spawn: write the rendered section as the `## Evidence Exceptions` section of `{worktree}/.devflow/docs/handoff-{branch_slug}.md`, creating the file if absent, and set `PR_EXCEPTIONS` to that section. The file is its one home until the PR exists: every later write to the file keeps the section byte-identical, the Phase 9 Git spawn passes it verbatim as `PR_EXCEPTIONS`, and the file is deleted only once the PR exists — after Phase 9, under every strategy. With no exception recorded, `PR_EXCEPTIONS` is `(none)`.
 
 **Test plan.** Before any Code spawn, give the task a test plan in the evidence file `{worktree}/.devflow/docs/evidence-{branch_slug}.md` (`EVIDENCE_FILE`) — unlike the handoff file, it stays after the PR exists. It holds up to three sections, in this order and nothing else: `## Test Plan`; `## Evidence Exceptions`, a byte copy of `PR_EXCEPTIONS` present only while that is not `(none)`; and `## Claims`, always last, so every claim is appended at the end of the file. Create the file if absent; if it exists, replace its `## Test Plan` and `## Evidence Exceptions` sections and keep `## Claims` byte-identical.
 
@@ -185,7 +186,7 @@ node "$HOME/.devflow/scripts/verify-evidence.cjs" check tp "{worktree}/.devflow/
 - **Record an exception** — the user gives the reason as free text. Render it with the exception grammar above, as kind `test-plan`; when the rendered reason is empty, ask for it once more, and stop as below if it is empty again. Add the rendered line to the `## Evidence Exceptions` section of `{worktree}/.devflow/docs/handoff-{branch_slug}.md` — after any `ticket-link` line, creating the section and the file when absent — and set `PR_EXCEPTIONS` to that section, under the same rules as the record above.
 - **Stop** — report `BLOCKED (no test plan)`, name `TASK_ID` and `BASE_BRANCH` so the branch can be reused or removed, and give the remedy: state the acceptance criteria in the task, the issue or a `/plan` document (its `## Test Plan` section is copied) and re-run `/implement`, or — for a team that does not want test plans enforced — commit `.devflow/project.json` as `{"version":1,"evidence":"standard"}` on the default branch; a machine with compliance enabled still resolves `required` whatever that file says. Spawn nothing further.
 
-When `EVIDENCE_POLICY` is `standard`, a missing test plan is never asked about: carry `Test plan: missing` to the Phase 11 report.
+When `EVIDENCE_POLICY` is `standard`, a missing test plan is never asked about: carry `Test plan: missing` to the Phase 12 report.
 
 **Test-plan outputs**, set once before any Code spawn:
 - `TEST_PLAN` — the TP lines of the evidence file's `## Test Plan` section, or `(none)` when the test plan is missing.
@@ -212,7 +213,13 @@ The accepted line is the only source of these values: the script alone folds the
 **Evidence stub:** only when `EVIDENCE_POLICY` is `required`, a resolved `off` becomes `stub`, so a counts-only record still reaches the PR. `stub` is never a config value: the settings line never carries it.
 
 Note: `auto` is NOT fail-open — under `auto`, the Git agent probes the repository visibility and treats any error or unrecognised value as PUBLIC (mode STUB). What each value does is decided by the Git agent's publication gate (`references/publication-gate.md` step 2); this partial only resolves the value.
-Phase 10b passes the resolved value to `update-pr-evidence`, which decides what each value means for the evidence comment. From the same line: `COMPLIANCE_FRAMEWORKS` is the settings line's `COMPLIANCE` with `generic` written `none`: `off`, `none`, or the framework ids the machine and this repository declare. Pass it to every Code spawn.
+Phase 11 passes the resolved value to `update-pr-evidence`, which decides what each value means for the evidence comment. From the same line: `COMPLIANCE_FRAMEWORKS` is the settings line's `COMPLIANCE` with `generic` written `none`: `off`, `none`, or the framework ids the machine and this repository declare.
+
+**Set the compliance directive** from `COMPLIANCE_FRAMEWORKS`. `COMPLIANCE_DIRECTIVE` is empty when `COMPLIANCE_FRAMEWORKS` is `off`: a spawn line that holds only `{COMPLIANCE_DIRECTIVE}` is then left out, so a lens-off spawn carries nothing about compliance. Otherwise `COMPLIANCE_DIRECTIVE` is this one line, with `<ids>` replaced by the value of `COMPLIANCE_FRAMEWORKS`:
+
+> When the task touches regulated surface (data models, auth flows, logging/observability, payments, IaC, retention), invoke Skill(skill="devflow:compliance") and load references/{id}.md only for the ids in <ids> (none: generic controls only); never fabricate guidance for a framework you were not given.
+
+Pass `COMPLIANCE_DIRECTIVE` to every Code and Code-fix spawn, on a line of its own.
 
 ### Load DECISIONS_CONTEXT
 
@@ -241,9 +248,9 @@ Attempt to read `{ledger}/.devflow/learning/index.md`.
 
 The index is one direct file read, written at render time by `render-decisions.cjs` alongside `decisions.md`/`pitfalls.md` — no `.cjs` script runs here, and the index's own footer names the files that hold each entry's full body.
 
-**Step 2 — Apply decisions using `devflow:apply-decisions`:**
+**Step 2 — Agents apply the decisions:**
 
-When `DECISIONS_CONTEXT` is not `(none)`, follow `devflow:apply-decisions` to scan the index, identify plausibly-relevant entries, Read full entry bodies on demand, and cite verbatim IDs in downstream agent prompts and reasoning.
+When `DECISIONS_CONTEXT` is not `(none)`, hand it only to the agents whose contract declares it. They follow `devflow:apply-decisions`: scan the index, identify plausibly-relevant entries, Read full entry bodies on demand, and cite verbatim IDs in their reasoning. A host that uses the index in its own thread says so in its own step.
 
 Pass `DECISIONS_CONTEXT` to Code agent (Phase 2) and Scrutinize agent (Phase 4).
 
@@ -304,8 +311,8 @@ A KB with no Rules section labels its entries `Rules ({section name}):` and give
 
 ### Phase 2: Implement
 
-**Produces:** CODE_AGENT_OUTPUT, FILES_CHANGED, PR_URL
-**Requires:** TASK_ID, BASE_BRANCH, EXECUTION_PLAN, PR_DESCRIPTION_GUIDANCE, PR_EXCEPTIONS, PR_TEST_PLAN_BLOCK
+**Produces:** CODE_AGENT_OUTPUT, FILES_CHANGED
+**Requires:** TASK_ID, BASE_BRANCH, EXECUTION_PLAN
 
 Based on Setup context (plan document, issue body, or conversation context), use the three-strategy framework:
 
@@ -331,16 +338,9 @@ TASK_DESCRIPTION: {description}
 BASE_BRANCH: {base branch}
 EXECUTION_PLAN: {full plan from setup context}
 PATTERNS: {patterns from plan document or empty}
-CREATE_PR: true
-DOMAIN: {detected domain or 'fullstack'}
 FEATURE_KNOWLEDGE: {feature_knowledge}
 DECISIONS_CONTEXT: {decisions_context}
-COMPLIANCE_FRAMEWORKS: {COMPLIANCE_FRAMEWORKS}
-PR_DESCRIPTION_GUIDANCE: {pr_description_guidance}
-ISSUE_NUMBER: {ISSUE_ID captured in Phase 1, or (none)}
-ISSUE_PR_LINK: {ISSUE_PR_LINK captured in Phase 1, or (none)}
-PR_EXCEPTIONS: {the ## Evidence Exceptions section of {worktree}/.devflow/docs/handoff-{branch_slug}.md verbatim, or (none)}
-PR_TEST_PLAN_BLOCK: {PR_TEST_PLAN_BLOCK from Phase 1 verbatim, or (none)}"
+{COMPLIANCE_DIRECTIVE}"
 ```
 
 ---
@@ -358,14 +358,9 @@ TASK_DESCRIPTION: {phase 1 description}
 BASE_BRANCH: {base branch}
 EXECUTION_PLAN: {phase 1 steps}
 PATTERNS: {patterns from plan document or empty}
-CREATE_PR: false
-DOMAIN: {phase 1 domain, e.g., 'backend'}
 FEATURE_KNOWLEDGE: {feature_knowledge}
 DECISIONS_CONTEXT: {decisions_context}
-COMPLIANCE_FRAMEWORKS: {COMPLIANCE_FRAMEWORKS}
-PR_DESCRIPTION_GUIDANCE: {pr_description_guidance}
-ISSUE_NUMBER: {ISSUE_ID captured in Phase 1, or (none)}
-ISSUE_PR_LINK: {ISSUE_PR_LINK captured in Phase 1, or (none)}
+{COMPLIANCE_DIRECTIVE}
 HANDOFF_REQUIRED: true
 HANDOFF_FILE: {worktree}/.devflow/docs/handoff-{branch_slug}.md"
 ```
@@ -379,23 +374,16 @@ TASK_DESCRIPTION: {phase N description}
 BASE_BRANCH: {base branch}
 EXECUTION_PLAN: {phase N steps}
 PATTERNS: {patterns from plan document or empty}
-CREATE_PR: {true if last phase, false otherwise}
-DOMAIN: {phase N domain, e.g., 'frontend'}
 PRIOR_PHASE_SUMMARY: {summary from previous Code agent}
 FILES_FROM_PRIOR_PHASE: {list of files created}
 FEATURE_KNOWLEDGE: {feature_knowledge}
 DECISIONS_CONTEXT: {decisions_context}
-COMPLIANCE_FRAMEWORKS: {COMPLIANCE_FRAMEWORKS}
-PR_DESCRIPTION_GUIDANCE: {pr_description_guidance}
-ISSUE_NUMBER: {ISSUE_ID captured in Phase 1, or (none)}
-ISSUE_PR_LINK: {ISSUE_PR_LINK captured in Phase 1, or (none)}
-PR_EXCEPTIONS: {the ## Evidence Exceptions section of {worktree}/.devflow/docs/handoff-{branch_slug}.md verbatim, or (none)}
-PR_TEST_PLAN_BLOCK: {PR_TEST_PLAN_BLOCK from Phase 1 verbatim, or (none)}
+{COMPLIANCE_DIRECTIVE}
 HANDOFF_REQUIRED: {true if not last phase}
 HANDOFF_FILE: {worktree}/.devflow/docs/handoff-{branch_slug}.md"
 ```
 
-**Handoff Protocol**: Each sequential Code agent receives the prior Code agent's implementation summary via PRIOR_PHASE_SUMMARY and FILES_FROM_PRIOR_PHASE. The Code agent's built-in branch orientation step handles git log scanning, file reading, and pattern discovery automatically. Each Code agent with HANDOFF_REQUIRED=true appends its own `## Phase {N} Implementation Summary` section, at most 8,192 bytes, to `{worktree}/.devflow/docs/handoff-{branch_slug}.md` (survives context compaction), never rewriting an earlier section and keeping any `## Evidence Exceptions` section byte-identical; the next Code agent reads only the section of the phase immediately before its own through HANDOFF_FILE. The orchestrator writes no phase section. Delete `{worktree}/.devflow/docs/handoff-{branch_slug}.md` once the PR exists — after the final Code agent, which creates it, completes (cleanup).
+**Handoff Protocol**: Each sequential Code agent receives the prior Code agent's implementation summary via PRIOR_PHASE_SUMMARY and FILES_FROM_PRIOR_PHASE. The Code agent's built-in branch orientation step handles git log scanning, file reading, and pattern discovery automatically. Each Code agent with HANDOFF_REQUIRED=true appends its own `## Phase {N} Implementation Summary` section, at most 8,192 bytes, to `{worktree}/.devflow/docs/handoff-{branch_slug}.md` (survives context compaction), never rewriting an earlier section and keeping any `## Evidence Exceptions` section byte-identical; the next Code agent reads only the section of the phase immediately before its own through HANDOFF_FILE. The orchestrator writes no phase section. Delete `{worktree}/.devflow/docs/handoff-{branch_slug}.md` once the PR exists — after Phase 9 (cleanup).
 
 ---
 
@@ -411,14 +399,9 @@ TASK_DESCRIPTION: {independent subtask 1}
 BASE_BRANCH: {base branch}
 EXECUTION_PLAN: {subtask 1 steps}
 PATTERNS: {patterns}
-CREATE_PR: false
-DOMAIN: {subtask 1 domain}
 FEATURE_KNOWLEDGE: {feature_knowledge}
 DECISIONS_CONTEXT: {decisions_context}
-COMPLIANCE_FRAMEWORKS: {COMPLIANCE_FRAMEWORKS}
-PR_DESCRIPTION_GUIDANCE: {pr_description_guidance}
-ISSUE_NUMBER: {ISSUE_ID captured in Phase 1, or (none)}
-ISSUE_PR_LINK: {ISSUE_PR_LINK captured in Phase 1, or (none)}"
+{COMPLIANCE_DIRECTIVE}"
 
 Agent(subagent_type="Code"):  # Code agent 2 (same message)
 "OPERATION: implement
@@ -427,14 +410,9 @@ TASK_DESCRIPTION: {independent subtask 2}
 BASE_BRANCH: {base branch}
 EXECUTION_PLAN: {subtask 2 steps}
 PATTERNS: {patterns}
-CREATE_PR: false
-DOMAIN: {subtask 2 domain}
 FEATURE_KNOWLEDGE: {feature_knowledge}
 DECISIONS_CONTEXT: {decisions_context}
-COMPLIANCE_FRAMEWORKS: {COMPLIANCE_FRAMEWORKS}
-PR_DESCRIPTION_GUIDANCE: {pr_description_guidance}
-ISSUE_NUMBER: {ISSUE_ID captured in Phase 1, or (none)}
-ISSUE_PR_LINK: {ISSUE_PR_LINK captured in Phase 1, or (none)}"
+{COMPLIANCE_DIRECTIVE}"
 ```
 
 **Independence criteria** (all must be true for PARALLEL_CODE_AGENTS):
@@ -500,19 +478,16 @@ Validate alignment with request and plan. Report ALIGNED or MISALIGNED with deta
 1. Extract misalignment details from Evaluate agent output
 2. Increment `alignment_fix_count`
 3. If `alignment_fix_count <= 2`:
-   - Spawn Code agent to fix misalignments:
+   - Spawn Code-fix agent to fix misalignments:
    ```
-   Agent(subagent_type="Code"):
+   Agent(subagent_type="Code-fix"):
    "OPERATION: alignment-fix
    TASK_ID: {task-id}
    TASK_DESCRIPTION: Fix alignment issues
    MISALIGNMENTS: {structured misalignments from Evaluate agent}
    SCOPE: Fix only the listed misalignments, no other changes
-   CREATE_PR: false
    DECISIONS_CONTEXT: {decisions_context}
-   ISSUE_NUMBER: {ISSUE_ID captured in Phase 1, or (none)}
-   ISSUE_PR_LINK: {ISSUE_PR_LINK captured in Phase 1, or (none)}
-   COMPLIANCE_FRAMEWORKS: {COMPLIANCE_FRAMEWORKS}"
+   {COMPLIANCE_DIRECTIVE}"
    ```
    - Loop back to Phase 5 (re-check alignment). The fix is not validated here: the Phase 6 run covers it.
 4. If `alignment_fix_count > 2`: Report misalignments to user for decision
@@ -535,19 +510,16 @@ Run build, typecheck, lint, test. Report pass/fail with failure details."
 1. Extract failure details from Validate agent output
 2. Increment `validation_retry_count`
 3. If `validation_retry_count <= 2`:
-   - Spawn Code agent with fix context:
+   - Spawn Code-fix agent with fix context:
    ```
-   Agent(subagent_type="Code"):
+   Agent(subagent_type="Code-fix"):
    "OPERATION: validation-fix
    TASK_ID: {task-id}
    TASK_DESCRIPTION: Fix validation failures
    VALIDATION_FAILURES: {parsed failures from Validate agent}
    SCOPE: Fix only the listed failures, no other changes
-   CREATE_PR: false
    DECISIONS_CONTEXT: {decisions_context}
-   ISSUE_NUMBER: {ISSUE_ID captured in Phase 1, or (none)}
-   ISSUE_PR_LINK: {ISSUE_PR_LINK captured in Phase 1, or (none)}
-   COMPLIANCE_FRAMEWORKS: {COMPLIANCE_FRAMEWORKS}"
+   {COMPLIANCE_DIRECTIVE}"
    ```
    - Loop back to Phase 6 (re-validate at the new HEAD, full scope)
 4. If `validation_retry_count > 2`: Report failures to user and halt
@@ -563,7 +535,7 @@ Run build, typecheck, lint, test. Report pass/fail with failure details."
 
 - `gate:validate` — after a Phase 6 or Phase 8 PASS.
 - `TP-<n>` — after every Phase 7 run, one line per `### Test Plan Evidence` row whose TP is in `TEST_PLAN`, with the row's outcome; the line ends at `by:test` when the row's Exit is not a number from 0 to 255.
-- Append nothing from a report whose `HEAD:` is not a single 40-hex SHA — a reported before/after change included — and say so in the Phase 11 report.
+- Append nothing from a report whose `HEAD:` is not a single 40-hex SHA — a reported before/after change included — and say so in the Phase 12 report.
 
 ### Phase 7: QA Testing
 
@@ -590,22 +562,19 @@ After every Test agent run — PASS or FAIL, first run or retry — append its T
 1. Extract failure details from Test agent output
 2. Increment `qa_retry_count`
 3. If `qa_retry_count <= 2`:
-   - Spawn Code agent to fix QA failures:
+   - Spawn Code-fix agent to fix QA failures:
    ```
-   Agent(subagent_type="Code"):
+   Agent(subagent_type="Code-fix"):
    "OPERATION: qa-fix
    TASK_ID: {task-id}
    TASK_DESCRIPTION: Fix QA test failures
    QA_FAILURES: {structured failures from Test agent}
    SCOPE: Fix only the listed failures, no other changes
-   CREATE_PR: false
    DECISIONS_CONTEXT: {decisions_context}
-   ISSUE_NUMBER: {ISSUE_ID captured in Phase 1, or (none)}
-   ISSUE_PR_LINK: {ISSUE_PR_LINK captured in Phase 1, or (none)}
-   COMPLIANCE_FRAMEWORKS: {COMPLIANCE_FRAMEWORKS}"
+   {COMPLIANCE_DIRECTIVE}"
    ```
    - Loop back to Phase 7 (re-run Test agent). The fix is not validated here: Phase 8 covers it.
-4. If `qa_retry_count > 2`: Report QA failures to user for decision. The run stops at the report (Phase 11), so Phases 8 and 9 do not run.
+4. If `qa_retry_count > 2`: Report QA failures to user for decision. The run stops at the report (Phase 12), so Phases 8 to 11 do not run.
 
 ### Phase 8: Re-Validate (only if a qa-fix committed)
 
@@ -625,12 +594,37 @@ Verify the qa-fix commits did not break anything."
 
 **If PASS:** append a `gate:validate` claim (Phase 6's **Evidence claims**), then continue to Phase 9.
 
-### Phase 9: CI Status Gate
+### Phase 9: Open PR
+
+**Produces:** PR_NUMBER
+**Requires:** BASE_BRANCH, TASK_ID, ISSUE_NUMBER, ISSUE_PR_LINK, PR_EXCEPTIONS, PR_TEST_PLAN_BLOCK, PR_DESCRIPTION_GUIDANCE, APPLY_CONVENTIONS, CODE_AGENT_OUTPUT
+
+Run once, after the gates, under every strategy. This phase sits outside the strategy branches, so no run reaches the end with commits and no PR. No Code agent opens a PR: the Git agent does, and it pastes `ISSUE_PR_LINK`, `PR_EXCEPTIONS` and `PR_TEST_PLAN_BLOCK` through their paste gates and scrubs the body (D11) before `gh pr create`. This command renders no link line and creates no PR itself: the Git agent's Phase-1 rendering is the only one, forwarded verbatim.
+
+```
+Agent(subagent_type="Git"):
+"OPERATION: ensure-pr-ready
+WORKTREE_PATH: {worktree}
+BASE_BRANCH: {base branch}
+TASK_ID: {task-id}
+ISSUE_NUMBER: {ISSUE_ID captured in Phase 1, or (none)}
+ISSUE_PR_LINK: {ISSUE_PR_LINK captured in Phase 1, or (none)}
+PR_EXCEPTIONS: {the ## Evidence Exceptions section of {worktree}/.devflow/docs/handoff-{branch_slug}.md verbatim, or (none)}
+PR_TEST_PLAN_BLOCK: {PR_TEST_PLAN_BLOCK verbatim, or (none)}
+PR_DESCRIPTION_GUIDANCE: {pr_description_guidance from Phase 1 unless it is (none), then the Code agents' reports from CODE_AGENT_OUTPUT in spawn order — Implementation, Commits and Key Decisions, and a sequential agent's ## Phase {N} Implementation Summary}
+APPLY_CONVENTIONS: {APPLY_CONVENTIONS}
+COMMIT_UNCOMMITTED: false
+Open the pull request for this branch and return the pre-flight summary."
+```
+
+`COMMIT_UNCOMMITTED: false` keeps the Git agent from committing a stray file: the Code, Simplify, Scrutinize and fix agents commit their own work. Capture the `- **PR**: #{number}` line of its `### Branch` as `PR_NUMBER`, its `### Uncommitted files` list and its `TRACEABILITY: DEGRADED ({reason})` lines for the Phase 12 report. If it returns `### Status: BLOCKED` or no PR number, report its reason to the user and stop at the report (Phase 12); Phases 10 and 11 do not run.
+
+### Phase 10: CI Status Gate
 
 **Produces:** CI_STATUS
-**Requires:** PR_URL, FILES_CHANGED
+**Requires:** PR_NUMBER, FILES_CHANGED
 
-Strategy-conditional: run when the PR already exists — **SINGLE_CODE_AGENT** and **SEQUENTIAL_CODE_AGENTS** (the Phase 2 Code agent with `CREATE_PR: true` creates it); skip for **PARALLEL_CODE_AGENTS** (its unified PR is created in Phase 10).
+Run under every strategy: Phase 9 opened the PR.
 
 **Push first, outside the gate block.** The gate reads CI for the pushed head, and the Simplify, Scrutinize and fix commits reach the PR only by a push. Push once — never force, and no retry:
 
@@ -638,52 +632,24 @@ Strategy-conditional: run when the PR already exists — **SINGLE_CODE_AGENT** a
 git push origin HEAD; echo "exit=$?"
 ```
 
-`exit=0` continues to the gate. Any other result, a rejected non-fast-forward push included, records `TRACEABILITY: DEGRADED (ci push failed)` for the Phase 11 report, reports "CI status unknown — verify manually before merging" and proceeds to Phase 10 without waiting. `PR_NUMBER` is the number in `PR_URL`.
+`exit=0` continues to the gate. Any other result, a rejected non-fast-forward push included, records `TRACEABILITY: DEGRADED (ci push failed)` for the Phase 12 report, reports "CI status unknown — verify manually before merging" and proceeds to Phase 11 without waiting.
 
 <!-- PATTERN: ci-status-gate -->
 1. Wait: run `cd {worktree} && HEAD_SHA=$(git rev-parse HEAD) && node "$HOME/.devflow/scripts/ci-wait.cjs" --pr {PR_NUMBER} --head "$HEAD_SHA"` through the Bash tool with `timeout: 600000`. Each run is one wait of at most 570 seconds and prints one line, `CI <STATUS> pr=… head=… failing=… pending=… waited=…` (INDETERMINATE adds `reason=…`). A missing or unparseable line, a status outside the six below, or a non-zero exit is INDETERMINATE.
-2. **If PASSING** → proceed to Phase 10.
-3. **If NO_PR or NO_CI** → skip: "No PR/CI configured, skipping CI validation." Proceed to Phase 10.
+2. **If PASSING** → proceed to Phase 11.
+3. **If NO_PR or NO_CI** → skip: "No PR/CI configured, skipping CI validation." Proceed to Phase 11.
 4. **If PENDING** and fewer than 3 waits have run → wait again (step 1). After the third wait → report "CI still running — verify manually before merging" and proceed.
 5. **If INDETERMINATE** and fewer than 3 waits have run → wait again (step 1). After the third wait → report "CI status unknown — verify manually before merging" and proceed.
-6. **If FAILING** and fewer than 2 fixes have run → report the failing checks from the line. Spawn `Agent(subagent_type="Code")` whose prompt opens with `OPERATION: ci-fix`, with `COMPLIANCE_FRAMEWORKS`, `CI_FAILURES`, `DECISIONS_CONTEXT` and `PUSH: false`; `CI_FAILURES` holds the failing-check names from the line and nothing else, because the Code agent fetches the full names and reads the logs itself and this command reads none. After a fix, push with the command above and, if a wait remains, wait again (step 1); a failed push records `TRACEABILITY: DEGRADED (ci push failed)`, reports "CI status unknown — verify manually before merging" and stops waiting. After the second fix still FAILING → report the failing checks and proceed.
+6. **If FAILING** and fewer than 2 fixes have run → report the failing checks from the line. Spawn `Agent(subagent_type="Code-fix")` whose prompt opens with `OPERATION: ci-fix`, with `COMPLIANCE_DIRECTIVE` (when it is not empty), `CI_FAILURES`, `DECISIONS_CONTEXT` and `PUSH: false`; `CI_FAILURES` holds the failing-check names from the line and nothing else, because the Code-fix agent fetches the full names and reads the logs itself and this command reads none. After a fix, push with the command above and, if a wait remains, wait again (step 1); a failed push records `TRACEABILITY: DEGRADED (ci push failed)`, reports "CI status unknown — verify manually before merging" and stops waiting. After the second fix still FAILING → report the failing checks and proceed.
 7. **Budget**: at most 3 waits and 2 fixes in all. When one is spent, report the current status and proceed.
 <!-- /PATTERN: ci-status-gate -->
 
-### Phase 10: Create PR
-
-**Produces:** PR_URL
-**Requires:** BASE_BRANCH, TASK_ID, PR_EXCEPTIONS, PR_TEST_PLAN_BLOCK
-
-**For SEQUENTIAL_CODE_AGENTS**: the PR already exists — the last Phase 2 Code agent (`CREATE_PR: true`) created it, and Phase 9 has gated its CI.
-
-**For PARALLEL_CODE_AGENTS**: spawn one Code agent to create the unified PR:
-
-```
-Agent(subagent_type="Code"):
-"OPERATION: pr-create
-TASK_ID: {task-id}
-TASK_DESCRIPTION: Create the unified PR for the parallel implementation
-BASE_BRANCH: {base branch}
-CREATE_PR: true
-PR_DESCRIPTION_GUIDANCE: {pr_description_guidance}
-ISSUE_NUMBER: {ISSUE_ID captured in Phase 1, or (none)}
-ISSUE_PR_LINK: {ISSUE_PR_LINK captured in Phase 1, or (none)}
-PR_EXCEPTIONS: {the ## Evidence Exceptions section of {worktree}/.devflow/docs/handoff-{branch_slug}.md verbatim, or (none)}
-PR_TEST_PLAN_BLOCK: {PR_TEST_PLAN_BLOCK from Phase 1 verbatim, or (none)}
-COMPLIANCE_FRAMEWORKS: {COMPLIANCE_FRAMEWORKS}"
-```
-
-Its Responsibility 7 composes the body, pastes `ISSUE_PR_LINK`, `PR_EXCEPTIONS` and `PR_TEST_PLAN_BLOCK` through their paste gates and scrubs the body (D11) before `gh pr create`. This command renders no link line and creates no PR itself: the Git agent's Phase-1 rendering is the only one, forwarded verbatim.
-
-**For SINGLE_CODE_AGENT**: PR is created by the Code agent (CREATE_PR: true) — the Code agent's Responsibility 7 handles Related Issues inclusion when ISSUE_NUMBER is provided.
-
-### Phase 10b: Evidence
+### Phase 11: Evidence
 
 **Produces:** EVIDENCE_RESULT
-**Requires:** PR_URL, EVIDENCE_FILE, REVIEW_PUBLICATION
+**Requires:** PR_NUMBER, EVIDENCE_FILE, REVIEW_PUBLICATION
 
-Run once, after Phase 10, under every strategy: the PR exists by now under all three — from Phase 2 for SINGLE_CODE_AGENT and SEQUENTIAL_CODE_AGENTS, from Phase 10 for PARALLEL_CODE_AGENTS. Skip it only when no PR was created. PARALLEL_CODE_AGENTS ran no CI gate, so its `ci` TPs usually read `INDETERMINATE` until a later refresh.
+Run once, after Phase 10, under every strategy: the PR exists by now, opened in Phase 9. The re-validation path has no CI gate and runs this phase straight after Phase 9. Skip it only when Phase 9 stopped the run. A `ci` TP reads `INDETERMINATE` only when the CI gate could not tell or did not run.
 
 **Push first.** Every claim is keyed to the HEAD an agent reported, and a Scrutinize or fix agent may have committed without pushing; a claim whose SHA is not in the PR reads `UNVERIFIED`. So push the branch once before the spawn — never force, and no retry:
 
@@ -691,29 +657,31 @@ Run once, after Phase 10, under every strategy: the PR exists by now under all t
 git push origin HEAD; echo "exit=$?"
 ```
 
-`exit=0` continues to the spawn. Any other result, a rejected non-fast-forward push included, does not block: record `TRACEABILITY: DEGRADED (evidence push failed)` for the Phase 11 report and spawn anyway.
+`exit=0` continues to the spawn. Any other result, a rejected non-fast-forward push included, does not block: record `TRACEABILITY: DEGRADED (evidence push failed)` for the Phase 12 report and spawn anyway.
 
 ```
 Agent(subagent_type="Git"):
 "OPERATION: update-pr-evidence
-PR_NUMBER: {number from PR_URL}
+PR_NUMBER: {PR_NUMBER}
 EVIDENCE_FILE: .devflow/docs/evidence-{branch_slug}.md
 REVIEW_PUBLICATION: {REVIEW_PUBLICATION resolved in Phase 1, or auto}
 WORKTREE_PATH: {worktree}
 Update the PR's test-plan block and post its evidence comment."
 ```
 
-Omit the `EVIDENCE_FILE` line when that file does not exist. Capture the op's `## PR Evidence` block — its `EVIDENCE` line and its `**Body**:` / `**Comment**:` line — as `EVIDENCE_RESULT`, or its `TRACEABILITY: DEGRADED ({reason})` line. It never blocks: whatever it returns, continue to Phase 11.
+Omit the `EVIDENCE_FILE` line when that file does not exist. Capture the op's `## PR Evidence` block — its `EVIDENCE` line and its `**Body**:` / `**Comment**:` line — as `EVIDENCE_RESULT`, or its `TRACEABILITY: DEGRADED ({reason})` line. It never blocks: whatever it returns, continue to Phase 12.
 
-### Phase 11: Report
+### Phase 12: Report
 
-**Requires:** VALIDATION_RESULT, ALIGNMENT_RESULT, QA_RESULT, PR_URL, EVIDENCE_RESULT
+**Requires:** VALIDATION_RESULT, ALIGNMENT_RESULT, QA_RESULT, PR_NUMBER, EVIDENCE_RESULT
 
 Display completion summary with phase status, PR info, and next steps.
 
-Show the test plan's evidence from Phase 10b: `Test plan: {VERIFIED-CI + ATTESTED-LOCAL}/{total} verified (VERIFIED-CI {n}, ATTESTED-LOCAL {n})`, read from the `EVIDENCE` line and never inferred, then its `**Body**:` / `**Comment**:` line verbatim. Without an `EVIDENCE` line, show `Test plan: evidence unavailable`; with no test plan, `Test plan: missing`.
+Show the test plan's evidence from Phase 11: `Test plan: {VERIFIED-CI + ATTESTED-LOCAL}/{total} verified (VERIFIED-CI {n}, ATTESTED-LOCAL {n})`, read from the `EVIDENCE` line and never inferred, then its `**Body**:` / `**Comment**:` line verbatim. Without an `EVIDENCE` line, show `Test plan: evidence unavailable`; with no test plan, `Test plan: missing`.
+
+If any Git agent output emitted `TRACEABILITY: DEGRADED ({reason})` lines during the run, or Phase 10's push or Phase 11's push recorded one, surface them verbatim in the report under a `### Traceability` subsection so the user can act on them.
 
-If any Git agent output emitted `TRACEABILITY: DEGRADED ({reason})` lines during the run, or Phase 9's push or Phase 10b's push recorded one, surface them verbatim in the report under a `### Traceability` subsection so the user can act on them.
+If Phase 9 listed uncommitted files, show them as a `### Uncommitted files` subsection: the user commits them or discards them.
 
 If Phase 1 recorded an evidence exception, show its `## Evidence Exceptions` lines in the report.
 
@@ -778,7 +746,7 @@ When the Knowledge agent reports `KB_COMMIT: skipped (detached HEAD)`, the files
 /implement (orchestrator - spawns agents only)
 │
 ├─ Re-validation Path (when user says "re-validate"/"re-check"/"re-run gates")
-│  └─ Branch safety → skip Phase 2 → detect FILES_CHANGED → Phases 3-8 → Phase 10, 10b, 11
+│  └─ Branch safety → skip Phase 2 → detect FILES_CHANGED → Phases 3-8 → Phase 9, 11, 12
 │
 ├─ Phase 1: Setup
 │  └─ Plan document parsing (if .md path provided) - extracts execution plan, strategy, frontmatter issue
@@ -787,7 +755,7 @@ When the Knowledge agent reports `KB_COMMIT: skipped (detached HEAD)`, the files
 │  └─ Test plan (evidence file) - copy or author TP lines, check them, render the PR block; missing under a required policy: record a test-plan exception or stop
 │
 ├─ Phase 2: Implement (3-strategy framework)
-│  ├─ SINGLE_CODE_AGENT (80%): One Code agent, full plan, CREATE_PR: true
+│  ├─ SINGLE_CODE_AGENT (80%): One Code agent, full plan
 │  ├─ SEQUENTIAL_CODE_AGENTS (15%): N Code agents with handoff summaries
 │  └─ PARALLEL_CODE_AGENTS (5%): N Code agents in single message (rare)
 │
@@ -799,33 +767,31 @@ When the Knowledge agent reports `KB_COMMIT: skipped (detached HEAD)`, the files
 │
 ├─ Phase 5: Alignment Check
 │  └─ Evaluate agent (validates alignment - reports only, no fixes)
-│  └─ If MISALIGNED: Code agent fix loop (max 2 iterations) → re-check alignment
+│  └─ If MISALIGNED: Code-fix agent loop (max 2 iterations) → re-check alignment
 │
 ├─ Phase 6: Validate (the one full-suite slot)
 │  └─ Validate agent (build, typecheck, lint, test over the branch diff)
-│  └─ If FAIL: Code agent fix loop (max 2 retries) → re-validate at the new HEAD
+│  └─ If FAIL: Code-fix agent loop (max 2 retries) → re-validate at the new HEAD
 │  └─ If PASS: record VALIDATED_HEAD, gate:validate claim → evidence file
 │
 ├─ Phase 7: QA Testing
 │  └─ Test agent (scenario-based acceptance tests, TEST_PLAN) → one claim per TP row → evidence file
-│  └─ If FAIL: Code agent fix loop (max 2 retries) → re-test
+│  └─ If FAIL: Code-fix agent loop (max 2 retries) → re-test
 │
 ├─ Phase 8: Re-Validate (only if a qa-fix committed)
 │  └─ Validate agent (changed-only over VALIDATED_HEAD..HEAD) → gate:validate claim
 │
-├─ Phase 9: CI Status Gate (SINGLE_CODE_AGENT + SEQUENTIAL_CODE_AGENTS; skipped for PARALLEL_CODE_AGENTS)
-│  └─ Push the branch, then ci-wait.cjs (inline, one wait ≤ 570 s) → Code agent on FAILING (3 waits + 2 fixes)
+├─ Phase 9: Open PR (every strategy, outside the strategy branches)
+│  └─ Git agent (operation: ensure-pr-ready) - commits nothing (COMMIT_UNCOMMITTED: false), pushes, opens the PR with the pasted link line, exceptions and test-plan block, D11-scrubbed body
 │
-├─ Phase 10: Create PR (if needed)
-│  └─ SINGLE_CODE_AGENT: already created by the Phase 2 Code agent
-│  └─ SEQUENTIAL: already created by the last Phase 2 Code agent
-│  └─ PARALLEL: Code agent (pr-create) creates unified PR
+├─ Phase 10: CI Status Gate (every strategy)
+│  └─ Push the branch, then ci-wait.cjs (inline, one wait ≤ 570 s) → Code-fix agent on FAILING (3 waits + 2 fixes)
 │
-├─ Phase 10b: Evidence (every strategy, once the PR exists)
+├─ Phase 11: Evidence (every strategy, once the PR exists)
 │  └─ Push the branch (never force; a failure is DEGRADED, not a stop)
 │  └─ Git agent (update-pr-evidence) - test-plan block + evidence comment; never blocks
 │
-├─ Phase 11: Report
+├─ Phase 12: Report
 │
 └─ Feature Knowledge Write-Back (Conditional)
    └─ Knowledge agent (if documented area changed AND knowledge enabled)
@@ -833,7 +799,7 @@ When the Knowledge agent reports `KB_COMMIT: skipped (detached HEAD)`, the files
 
 ## Principles
 
-1. **Orchestration only** - Command spawns agents, never does work itself; the inline calls are the bounded plumbing the charter allows: the Phase 9 and Phase 10b pushes, the Phase 9 ci-wait call and the evidence script checks
+1. **Orchestration only** - Command spawns agents, never does work itself; the inline calls are the bounded plumbing the charter allows: the Phase 10 and Phase 11 pushes, the Phase 10 ci-wait call and the evidence script checks
 2. **Plan-first** - Plan documents from `/plan` skip exploration/planning overhead entirely
 3. **Coherence-first** - Single Code agent produces more consistent code (default ~80% of tasks)
 4. **Agent ownership** - Each agent owns its output completely
@@ -842,9 +808,9 @@ When the Knowledge agent reports `KB_COMMIT: skipped (detached HEAD)`, the files
 7. **Simplification pass** - Code refined for clarity before PR
 8. **Strict delegation** - Never perform agent work in main session. "Spawn X" means call Agent tool with X, not do X's work yourself
 9. **Validate agent owns validation** - Never run `npm test`, `npm run build`, or similar in main session; always delegate to Validate agent
-10. **Code agent owns fixes** - Never implement fixes in main session; spawn Code agent for validation failures and alignment fixes
+10. **Code-fix agent owns fixes** - Never implement fixes in main session; spawn Code-fix agent for validation failures and alignment fixes
 11. **Loop limits** - Max 2 validation retries, max 2 alignment fix iterations, max 2 QA retries before escalating to user; the CI gate allows at most 3 waits and 2 fixes
-12. **CI awareness** - CI status is checked before merge for SINGLE_CODE_AGENT and SEQUENTIAL_CODE_AGENTS, whose PR exists from Phase 2; skipped for PARALLEL_CODE_AGENTS, whose PR is created in Phase 10; test-plan evidence (Phase 10b) is recorded under every strategy once the PR exists
+12. **CI awareness** - CI status is checked before merge under every strategy, once Phase 9 has opened the PR; test-plan evidence (Phase 11) is recorded under every strategy once the PR exists
 
 ## Error Handling
 

package/dist/commands/plan.md

@@ -171,9 +171,9 @@ Attempt to read `{ledger}/.devflow/learning/index.md`.
 
 The index is one direct file read, written at render time by `render-decisions.cjs` alongside `decisions.md`/`pitfalls.md` — no `.cjs` script runs here, and the index's own footer names the files that hold each entry's full body.
 
-**Step 2 — Apply decisions using `devflow:apply-decisions`:**
+**Step 2 — Agents apply the decisions:**
 
-When `DECISIONS_CONTEXT` is not `(none)`, follow `devflow:apply-decisions` to scan the index, identify plausibly-relevant entries, Read full entry bodies on demand, and cite verbatim IDs in downstream agent prompts and reasoning.
+When `DECISIONS_CONTEXT` is not `(none)`, hand it only to the agents whose contract declares it. They follow `devflow:apply-decisions`: scan the index, identify plausibly-relevant entries, Read full entry bodies on demand, and cite verbatim IDs in their reasoning. A host that uses the index in its own thread says so in its own step.
 
 This produces a compact index of active ADR/PF entries. Pass the Skim agent context to all subsequent agents. Pass `DECISIONS_CONTEXT` to the Design agents of the gap-analysis phase — prior decisions constrain design, known pitfalls inform gap analysis. Design agents use `devflow:apply-decisions` to Read full entry bodies on demand.
 
@@ -239,7 +239,7 @@ Pass `FEATURE_KNOWLEDGE` to Explore and Design agents. Pass `DECISIONS_CONTEXT`
 **Produces:** EXPLORE_OUTPUTS
 **Requires:** SKIM_CONTEXT
 
-Spawn 4 Explore agents **in a single message**, each with Skim agent context and `FEATURE_KNOWLEDGE: {feature_knowledge}` (from Phase 2). Include the instruction: "The FEATURE_KNOWLEDGE is a baseline — VALIDATE, EXTEND, and CORRECT it. For anything it already covers, cite its KB IDs (`{slug} KB-AP-n`) instead of restating the text. Focus on areas the feature knowledge doesn't cover and changes since it was last updated." Ask each agent for a final report of at most about 1,500 tokens: findings with file:line references, not file dumps.
+Spawn 4 `Agent(subagent_type="Explore")` agents **in a single message**, each with Skim agent context and `FEATURE_KNOWLEDGE: {feature_knowledge}` (from Phase 2). Include the instruction: "The FEATURE_KNOWLEDGE is a baseline — VALIDATE, EXTEND, and CORRECT it. For anything it already covers, cite its KB IDs (`{slug} KB-AP-n`) instead of restating the text. Focus on areas the feature knowledge doesn't cover and changes since it was last updated." Ask each agent for a final report of at most about 1,500 tokens: findings with file:line references, not file dumps.
 
 | Focus | Thoroughness | Find |
 |-------|-------------|------|
@@ -301,16 +301,21 @@ Each Design agent receives:
 - Exploration synthesis from Phase 4
 - Skim agent context from Phase 2
 - `DECISIONS_CONTEXT` (index from Phase 2)
-- `COMPLIANCE_FRAMEWORKS` (compliance focus only)
+- `COMPLIANCE_FOCUS_DIRECTIVE` (compliance focus only)
 - Multi-issue: all issue bodies
 
+**Set the compliance focus directive** from `COMPLIANCE_FRAMEWORKS`. `COMPLIANCE_FOCUS_DIRECTIVE` is this one line, with `<ids>` replaced by the value of `COMPLIANCE_FRAMEWORKS`; only the compliance focus's spawn carries it:
+
+> For this compliance focus, invoke Skill(skill="devflow:compliance") and load references/{id}.md only for the ids in <ids> (none: generic controls only); never fabricate guidance for a framework you were not given.
+
 ```
 Agent(subagent_type="Design"):
 "Mode: gap-analysis
 Focus: {completeness|architecture|security|performance|compliance|consistency|dependencies}
 DECISIONS_CONTEXT: {decisions_context}
 FEATURE_KNOWLEDGE: {feature_knowledge}
-COMPLIANCE_FRAMEWORKS: {COMPLIANCE_FRAMEWORKS}  (compliance focus only)
+{COMPLIANCE_FOCUS_DIRECTIVE}  (compliance focus only)
+Resolve `${CLAUDE_CONFIG_DIR:-$HOME/.claude}` in Bash, then Read `<that directory>/skills/devflow:gap-analysis/references/compliance.md` with the Read tool and apply it as your focus patterns.  (compliance focus only)
 Artifacts:
   Feature/Issues: {feature description or issue bodies}
   Exploration synthesis: {Phase 4 output}
@@ -372,7 +377,7 @@ User can:
 **Produces:** IMPL_EXPLORE_OUTPUTS
 **Requires:** SKIM_CONTEXT, ACCEPTED_SCOPE
 
-Spawn 4 Explore agents **in a single message**, each with Skim agent context + accepted scope. Ask each agent for a final report of at most about 1,500 tokens: findings with file:line references, not file dumps.
+Spawn 4 `Agent(subagent_type="Explore")` agents **in a single message**, each with Skim agent context + accepted scope. Ask each agent for a final report of at most about 1,500 tokens: findings with file:line references, not file dumps.
 
 | Focus | Thoroughness | Find |
 |-------|-------------|------|
@@ -496,8 +501,10 @@ User can:
 
 **Store design artifact:**
 
-**Pre-compute the artifact path** from the slug (it never changes after this):
-- If one issue: `{worktree}/.devflow/docs/design/{ISSUE_ID}-{topic-slug}.{YYYY-MM-DD_HHMM}.md` (the `docs-framework` skill's design-document pattern, e.g. `42-jwt-auth.2026-04-07_1430.md`)
+**Load `devflow:docs-framework`** — Load via Skill tool: `devflow:docs-framework`, here and not earlier, so a run that stops before this phase never pays for it. If it fails to load, continue with the paths below.
+
+**Pre-compute the artifact path** (it never changes after this) by the skill's rules: `{topic-slug}` is its topic slug of the feature title, the same value as the artifact's `slug:` frontmatter, and `{YYYY-MM-DD_HHMM}` is the local time, computed once:
+- If one issue: `{worktree}/.devflow/docs/design/{ISSUE_ID}-{topic-slug}.{YYYY-MM-DD_HHMM}.md` (e.g. `42-jwt-auth.2026-04-07_1430.md`)
 - If multi-issue: `{worktree}/.devflow/docs/design/multi-{topic-slug}.{YYYY-MM-DD_HHMM}.md`, frontmatter `issue: pending` — a batch fetch returns no issue ID to name it by
 - If no issue: `{worktree}/.devflow/docs/design/{topic-slug}.{YYYY-MM-DD_HHMM}.md`
 

package/dist/commands/release.md

@@ -40,8 +40,6 @@ Parse from `COMMAND_INPUT`:
 
 **Produces:** RELEASE_CONFIG, CONFIG_STATE (`learned` | `fresh`)
 
-**Load Companion Skills** — Load via Skill tool: `devflow:git`. If a skill fails to load, continue without it.
-
 **Continuation detection**: Check `.release/.progress.json`. If exists, an interrupted release is in progress. Offer user:
 - **Resume**: continue from last checkpoint (skip phases already completed)
 - **Restart**: clean start (delete `.release/.progress.json` and begin from Phase 1)
@@ -256,6 +254,9 @@ Confirm with user via AskUserQuestion before executing:
 Sequential execution with progress checkpoints:
 1. **Version bumps** — write new version to configured files
 2. **Changelog update** — move Unreleased section to versioned entry (if configured)
+
+**Load Companion Skills** (D-RELEASE-GIT-LOAD-LATE) — Load via Skill tool: `devflow:git`, here and not earlier: steps 1–2 only write files and `--dry-run` halts after Phase 4, so neither carries the skill. A resume that skips step 3 loads it before its next main-thread git write. If a skill fails to load, continue without it.
+
 3. **Release commit** — `chore(release): v{VERSION}` (conventional commit)
 4. **Tag and GitHub Release** — spawn `Agent(subagent_type="Git")` with `create-release` operation (the agent reads `.devflow/conventions.md` for tag format and release title conventions; compliance defaults when absent); only when `EVIDENCE_POLICY` is `required`, also pass `COMMIT_LIST` and `SHIPPED_ISSUES` from RELEASE_EVIDENCE, and `TRACEABILITY_EXCEPTIONS` when composed (Record, or the no-ask exempt rule), as inputs so the agent includes them in the release notes body.
 4b. **Back-link shipped issues** (only when `EVIDENCE_POLICY` is `required`) — spawn `Agent(subagent_type="Git")` with `backlink-shipped-issues` operation, passing `VERSION` and `SHIPPED_ISSUES`; posts a marker-deduped comment on each issue (bounds and throttle enforced by the operation); degrade gracefully (D4) on any API failure — never block the release