devflow-kit 2.4.0 → 2.5.0

package/src/assets/commands/plan.mds

@@ -5,6 +5,9 @@ output-dir: dist/commands
 @import { knowledge_load } from "./_partials/_knowledge.mds"
 @import { decisions_load } from "./_partials/_decisions.mds"
 @import { compliance_gate } from "./_partials/_compliance.mds"
+@import { evidence_policy } from "./_partials/_evidence_policy.mds"
+@import { test_plan_line } from "./_partials/_plan_contract.mds"
+@import { issue_ref_grammar, issue_capture_contract } from "./_partials/_tracker.mds"
 
 # Plan Command
 
@@ -24,12 +27,12 @@ The orchestrator only spawns agents and gates — all analytical work is done by
 ## Input
 
 `$ARGUMENTS` contains whatever follows `/plan`:
-- Starts with `#` followed by numbers → issue mode (parse all `#N` tokens, space-separated)
+- Opens with a candidate issue reference → issue mode (one candidate = single-ref, more than one = multi-issue)
 - Path to existing `.md` file → **error**: "Use /implement with plan documents"
 - Other text → feature description
 - Empty → use conversation context
 
-For **multi-issue** mode: collect all `#N` tokens from `$ARGUMENTS` as `ISSUE_NUMBERS`.
+{issue_ref_grammar()}
 
 ## Clarification Gates
 
@@ -61,6 +64,32 @@ Explore the user's intent through focused Socratic questioning before spawning a
 
 **Process:**
 
+**Step 0 — Fetch issue(s)** (issue mode only; skip for feature-description and empty modes):
+
+- **Single-ref** (one candidate ref in `$ARGUMENTS`):
+
+  ```
+  Agent(subagent_type="Git"):
+  "OPERATION: fetch-issue
+  ISSUE_INPUT: \{ref\}
+  Return issue title, body, labels, acceptance criteria, and dependencies."
+  ```
+
+- **Multi-ref** (more than one candidate ref):
+
+  ```
+  Agent(subagent_type="Git"):
+  "OPERATION: fetch-issues-batch
+  ISSUE_REFS: \{space-separated refs\}
+  Return issue titles, bodies, labels, acceptance criteria, and cross-issue relationships."
+  ```
+
+{issue_capture_contract()}
+
+Seed the discovery below with `ISSUE_CONTENT` and `ACCEPTANCE_CRITERIA` (every issue's, on the batch path); skip Gate 0 questions they already answer (applies the **Skip discovery when** rule above).
+
+If the Git agent returns only a `TRACEABILITY: DEGRADED (\{reason\})` line and no issue content, warn the user, carry that exact line verbatim into the report's traceability section, and proceed to Gate 0 discovery using the raw candidate token as the sole context. Never treat the `TRACEABILITY: DEGRADED` status line as issue content — no title, body, or acceptance criteria may be inferred from it.
+
 1. **First question**: Confirm your understanding of the core problem and expected outcome. Frame as multiple choice when 2-3 interpretations exist.
 2. **Follow-up questions** (if ambiguity remains): Probe constraints, scope boundaries, or tradeoffs via AskUserQuestion.
 3. **Present approaches**: When multiple valid approaches exist, present 2-3 options with explicit tradeoffs. Lead with your recommendation and why.
@@ -70,7 +99,7 @@ For multi-issue: present unified scope across all issues after individual discov
 
 If the user says "skip" or "just proceed" — skip remaining questions, present inferred understanding (core problem, users, outcome, assumptions, recommended approach) in one message for confirmation, then proceed. Gate 0 is satisfied by the confirmation, not by the discovery questions.
 
-**MANDATORY**: Do not spawn any agents until Gate 0 is confirmed.
+**MANDATORY**: Do not spawn any agents until Gate 0 is confirmed — the Step 0 issue fetch (if applicable) is the sole exception; it precedes and informs Gate 0 and must complete before Gate 0 begins.
 
 #### Phase 2: Orient + Load Decisions
 
@@ -266,7 +295,7 @@ Spawn 3 Plan agents **in a single message**, each with implementation exploratio
 | Focus | Output |
 |-------|--------|
 | Implementation steps | Ordered steps with files, dependencies, gap mitigations |
-| Testing strategy | Unit tests, integration tests, edge case tests |
+| Testing strategy | Unit tests, integration tests, edge case tests; at least one scenario per acceptance criterion, with how it is verified (CI, a local command, or manual steps) and the files it covers |
 | Execution strategy | SINGLE_CODE_AGENT vs SEQUENTIAL_CODE_AGENTS vs PARALLEL_CODE_AGENTS |
 
 Implementation steps planner: include explicit gap mitigations (from Phase 6) in the relevant steps.
@@ -317,7 +346,7 @@ Use AskUserQuestion to present:
 1. **Implementation Plan Summary**
    - Execution strategy (SINGLE_CODE_AGENT / SEQUENTIAL_CODE_AGENTS / PARALLEL_CODE_AGENTS)
    - Key implementation steps with files
-   - Test strategy
+   - Test strategy — the test plan as TP lines, at least one per acceptance criterion (shape below)
 
 2. **Design Review Findings** (from Phase 12)
    - Each anti-pattern finding with severity and proposed mitigation
@@ -329,6 +358,10 @@ Use AskUserQuestion to present:
    - Context risk level (LOW/MEDIUM/HIGH/CRITICAL)
    - Unresolved gaps carried forward
 
+**Test plan lines.** Gate 2 shows the test plan in the one shape `/implement` and the evidence scripts read. Word each scenario in plain words, with no `#`, `@` or `/`: name the files it covers in `files:`, never an issue, a person or a URL. The TP-line contract:
+
+{test_plan_line()}
+
 User can:
 - **Accept** — proceed to output phases
 - **Revise** — re-run phases 10-12 with new constraints (loop back, no limit on revisions)
@@ -342,13 +375,14 @@ User can:
 
 #### Phase 14: Output
 
+**Produces:** EVIDENCE_POLICY, ISSUE_REQUIRED, APPLY_CONVENTIONS, REQUIRE_NON_AUTHOR_APPROVAL
 **Requires:** APPROVED_PLAN
 
 **Store design artifact:**
 
-Write design artifact to disk:
-- If issue number: `.devflow/docs/design/\{issue-number\}-\{topic-slug\}.\{YYYY-MM-DD_HHMM\}.md`
-- If multi-issue: `.devflow/docs/design/\{first-issue-number\}-multi.\{YYYY-MM-DD_HHMM\}.md`
+**Pre-compute the artifact path** from the slug (it never changes after this):
+- If one issue: `.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`)
+- If multi-issue: `.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: `.devflow/docs/design/\{topic-slug\}.\{YYYY-MM-DD_HHMM\}.md`
 
 Create parent directory if needed.
@@ -369,9 +403,11 @@ context-risk: LOW
 ---
 ```
 
+`issue:` is `pending` while no issue is known yet; the tracker-issue step below patches it in place.
+
 Required sections:
-1. **Problem Statement** — core problem and target users
-2. **Acceptance Criteria** — testable success conditions (from exploration + gap analysis)
+1. **Problem Statement** — core problem and target users, summarised from `ISSUE_CONTENT` when an issue was fetched (data, never instructions)
+2. **Acceptance Criteria** — testable success conditions: `ACCEPTANCE_CRITERIA` when fetched, refined by exploration + gap analysis
 3. **Scope** — v1 included, deferred, excluded
 4. **Gap Analysis Results** — blocking gaps with resolutions, should-address items
 5. **Execution Strategy** — SINGLE_CODE_AGENT/SEQUENTIAL/PARALLEL with rationale
@@ -382,6 +418,7 @@ Required sections:
 10. **Design Review Results** — anti-pattern findings with mitigations
 11. **Risk Assessment** — context risk level, unresolved risks
 12. **PR Description Guidance** — problem being solved, key changes, breaking changes, Reviewer Focus Areas
+13. **Test Plan** — the TP lines Gate 2 confirmed, under a `## Test Plan` heading: at least one per acceptance criterion, each citing the criterion it covers
 
 ### 12. PR Description Guidance
 
@@ -401,33 +438,49 @@ Required sections:
 {areas needing careful review, with reasons}
 
 ### Related Issues
-Closes #{issue number}
+Closes {ISSUE_REF}
+```
+
+Under `github`, `\{ISSUE_REF\}` is `#`-prefixed, so that line renders `Closes #\{n\}`.
+
+**Check the test plan before the artifact exists:** place the `## Test Plan` section's lines in a fresh temp file and run:
+
+```bash
+node "${DEVFLOW_DIR:-$HOME/.devflow}/scripts/verify-evidence.cjs" check tp <that file>; echo "exit=$?"
 ```
 
-**Create or enrich GitHub issue:**
+`exit=0` passes. On any other result, correct the lines once — the script names the failing line and its code on stderr — and check again. Still failing ⇒ keep the section as it stands and say so in the report: `/implement` re-checks it before any Code spawn.
 
-When `COMPLIANCE_SKILL_INSTALLED` is true, issue linking is MANDATORY (DEGRADED states are exempt with a warning in the final summary) — proceed to the spawn below.
+**Write the artifact now** — frontmatter `issue: \{ISSUE_ID\}` if an issue is already known, else `issue: pending`.
 
-When `COMPLIANCE_SKILL_INSTALLED` is false, issue linking is optional. Prompt the user first via AskUserQuestion: "Create or enrich a GitHub issue for this plan?" — skip the spawn entirely if the user declines.
+{evidence_policy()}
+
+**Create or enrich tracker issue:**
+
+Issue linking is MANDATORY only when `EVIDENCE_POLICY` is `required` — proceed to the spawn below. DEGRADED states are exempt, with a warning in the final summary: `/implement` asks about the missing ticket before it spawns any Code agent.
+
+When `EVIDENCE_POLICY` is `standard`, issue linking is optional. Prompt the user first via AskUserQuestion: "Create or enrich a tracker issue for this plan?" — skip the spawn entirely if the user declines.
 
 Spawn a Git agent with `OPERATION: ensure-traceable-issue`:
 
 ```
 Agent(subagent_type="Git"):
 "OPERATION: ensure-traceable-issue
-ISSUE_INPUT: {issue_number_from_arguments if /plan invoked with #N, else omit}
+ISSUE_INPUT: {the raw candidate token from $ARGUMENTS if /plan was invoked with an issue reference, else omit}
 TASK_DESCRIPTION: {Gate 0 confirmed scope — one-line title}
 INITIAL_REQUEST: {the Gate 0 confirmed scope statement}
 REQUIREMENTS: {discovered requirements summary from Phase 6 gap synthesis}
 PLAN_ARTIFACT_PATH: {the design artifact path written above}
 LABELS: feature
-The Git agent will create a GitHub issue (or enrich an existing one) using the D3 template,
+The Git agent will create a tracker issue (or enrich an existing one) using the D3 template,
 post the design artifact as a collapsed details comment, and link it from the Implementation Plan section.
 Return the issue number."
 ```
 
 Capture `ISSUE_NUMBER` from the Git agent output for use in the completion report and the `/implement` hand-off suggestion.
 
+**Patch the frontmatter `issue:` line in place** — when it still reads `issue: pending` and the spawn returned an issue (`CREATED` or `ENRICHED`), replace only that one line inside the leading `---` block with `issue: \{ISSUE_NUMBER\}` — bare, no `#` (`issue: #42` parses as YAML null) — using the Edit tool. Never rename the artifact, never rewrite it, never spawn `ensure-traceable-issue` again. Declined or DEGRADED ⇒ leave `issue: pending`.
+
 Surface any `TRACEABILITY: DEGRADED (\{reason\})` lines from the Git agent output in the report.
 
 **Report:**
@@ -500,7 +553,7 @@ Display completion summary:
 ├─ Block 6: Output
 │  └─ Phase 14: Output
 │     ├─ Store design artifact (.devflow/docs/design/)
-│     ├─ Create GitHub issue (optional)
+│     ├─ Create tracker issue (optional)
 │     └─ Report summary + next step
 │
 ```

package/src/assets/commands/release.md

@@ -54,11 +54,21 @@ Load feature knowledge: Attempt to read `.devflow/features/index.md` (the regene
 
 Pass both to all subsequent agents via their input contracts.
 
-### Phase 1c: Resolve Compliance Context
+### Phase 1c: Resolve the Evidence Policy
 
-**Produces:** COMPLIANCE_SKILL_INSTALLED
+**Produces:** EVIDENCE_POLICY, ISSUE_REQUIRED, APPLY_CONVENTIONS, REQUIRE_NON_AUTHOR_APPROVAL
 
-**Resolve `COMPLIANCE_SKILL_INSTALLED` once per run:** Check whether `~/.claude/skills/devflow:compliance/SKILL.md` exists (one file-existence check, read-only, silent). Set `COMPLIANCE_SKILL_INSTALLED = true` if the file exists, `false` otherwise. Reuse this result for all subsequent phases. The compliance gate determines whether release evidence is gathered and shipped-issue back-links are posted.
+**Resolve the evidence policy once per run**, from the repository root, before any step reads the values:
+
+```bash
+node "${DEVFLOW_DIR:-$HOME/.devflow}/scripts/resolve-evidence-policy.cjs" 2>/dev/null; echo "exit=$?"
+```
+
+Accept the output only when it is exactly two lines: `exit=0` last and, before it, one line of the form `EVIDENCE_POLICY=<required|standard> SOURCE=<file|worktree|default|invalid|error> REF=<branch|none>[ WARN=<remote-unavailable|invalid-file|raised-by-compliance|pr-changes-policy>[,…]] ISSUE_REQUIRED=<true|false> APPLY_CONVENTIONS=<true|false> REQUIRE_NON_AUTHOR_APPROVAL=<true|false>` — these fields, in this order, nothing else, where `<branch>` is a branch name such as `main`. **Anything else** (a non-zero exit, no line, extra text, or a missing, reordered or unlisted field or value) ⇒ use `EVIDENCE_POLICY=required SOURCE=error REF=none ISSUE_REQUIRED=true APPLY_CONVENTIONS=true REQUIRE_NON_AUTHOR_APPROVAL=true` instead.
+
+Set `EVIDENCE_POLICY`, `ISSUE_REQUIRED`, `APPLY_CONVENTIONS` and `REQUIRE_NON_AUTHOR_APPROVAL` from the accepted line. Pass agents only the three mechanism inputs, never `EVIDENCE_POLICY`. Report `Evidence policy: {EVIDENCE_POLICY} (source: {SOURCE})`, plus any `WARN` tokens as advisory, once in the final report.
+
+Reuse this result for all subsequent phases: it decides whether a real release gathers and traces its evidence (Phases 4–5), passes it to the release notes (step 4), and back-links shipped issues and associates them with the release (steps 4b–4c).
 
 ### Phase 2: Detect Release Process (First Run Only)
 
@@ -90,13 +100,13 @@ Lazy-init `.release/` directory. Create `.release/.gitignore` with `.progress.js
 
 ### Phase 4: Pre-release Checks
 
-**Produces:** PRE_RELEASE_RESULT, VERSION
-**Requires:** RELEASE_CONFIG
+**Produces:** PRE_RELEASE_RESULT, VERSION, RELEASE_EVIDENCE
+**Requires:** RELEASE_CONFIG, EVIDENCE_POLICY
 
 **Version determination** (in order):
 1. Explicit version from args → use directly
 2. Bump type from args → compute from current version
-3. `semver-auto` strategy → analyze commits since last tag
+3. `semver-auto` strategy → analyze commits since the last release tag: the tag that `node "${DEVFLOW_DIR:-$HOME/.devflow}/scripts/release-trace.cjs" last-tag`, run from the repository root, prints as `LAST_TAG <tag>` (`LAST_TAG none` ⇒ the initial commit) — never `git describe`, which can return a local marker tag
 4. None → use AskUserQuestion
 
 Pre-release checks:
@@ -106,14 +116,45 @@ Pre-release checks:
 
 Spawn `Agent(subagent_type="Validate")` for build + test.
 
-Write `.release/.progress.json` checkpoint.
+**Gather release evidence** — under either policy when `DRY_RUN` is true, otherwise only when `EVIDENCE_POLICY` is `required`: spawn `Agent(subagent_type="Git")` with `gather-release-evidence` operation; pass `WORKTREE_PATH` if provided. Keep `COMMIT_LIST`, `SHIPPED_ISSUES`, `### TRACE_MAP` and `### Status:` as RELEASE_EVIDENCE. The Git agent applies its own bounds (≤100 commits, ≤50 issues, 500 traced commits) and degrades gracefully per D4.
+
+Unless `DRY_RUN` is true, write `.release/.progress.json` checkpoint, with RELEASE_EVIDENCE when it was gathered — a dry run leaves nothing to resume.
 
-`--dry-run`: report what would happen and **halt after this phase**.
+`--dry-run`: report what would happen and, when evidence was gathered, the Phase 5 traceability arms, the untraced list and the exempt counts — never asking — then **halt after this phase**.
 
 ### Phase 5: Build Release Plan
 
-**Produces:** RELEASE_PLAN
-**Requires:** PRE_RELEASE_RESULT, RELEASE_CONFIG, VERSION
+**Produces:** RELEASE_PLAN, TRACEABILITY_EXCEPTIONS
+**Requires:** PRE_RELEASE_RESULT, RELEASE_CONFIG, VERSION, RELEASE_EVIDENCE
+
+**Traceability** (only when `EVIDENCE_POLICY` is `required`), before the confirm below. Classify RELEASE_EVIDENCE by its `### Status:` value — `READY`, `PARTIAL`, `TRUNCATED`, `DEGRADED` or `INDETERMINATE` — and by the first `### TRACE_MAP` line, `TRACE from:<ref> scanned:<n> traced:<n> untraced:<n> exempt:<n> unmatched:<n> bound:<ok|hit>`. Let *u* be its `untraced` count, and re-check traced + untraced + exempt = scanned yourself. Every arm that matches applies:
+
+1. **Coverage unknown** — no gather ran, its output is missing or unparseable, there is no `TRACE` line, the sum does not hold, `bound:hit`, status `INDETERMINATE`, or a status that is none of the five.
+2. **Untraced** — *u* > 0.
+3. **Partial** — status `PARTIAL`, `TRUNCATED` or `DEGRADED`: warn and continue; this arm never blocks on its own. A tracker with no closing-reference capability always lands here.
+4. **Clean** — status `READY` and *u* = 0, and no arm above.
+
+Arm 1 or 2 ⇒ first show the attestation list, copied from `### TRACE_MAP`: every listed `untraced` line's `<sha12>` and author (≤100), the `…and <n> more` line that closes the untraced list when there is one, and each exempt kind's count with every listed exempt SHA — the commits **Record** attests to, and those the `Exempt` line prints.
+
+Arm 1 or 2 ⇒ ask once, via AskUserQuestion: "{u} untraced commits{, coverage unknown: {cause}}. Record self-attested traceability exceptions, or halt?", with exactly two options:
+- **Record** — ask for the reason in the user's own words; if it renders empty, ask once more, then halt. Compose `TRACEABILITY_EXCEPTIONS` below and add it to `.release/.progress.json`.
+- **Halt** — stop now: nothing has been committed, tagged or published.
+
+`TRACEABILITY_EXCEPTIONS` is this block, and no commit subject is ever written into it:
+
+```markdown
+## Traceability exceptions
+- `untraced` <sha12> (<author>) self-attested by @<login> at <utc>: <reason>
+- `coverage` <bound-hit|trace-unavailable|gather-indeterminate|untraced-beyond-list> self-attested by @<login> at <utc>: <reason>
+Exempt (not attested): release <n> · revert <n> · bot <n> — <sha12>, …
+```
+
+- One `untraced` line per listed untraced commit (≤100), its `<sha12>` and `<author>` copied from that `### TRACE_MAP` line. One `coverage` line per arm-1 cause — `bound-hit` for `bound:hit`, `gather-indeterminate` for status `INDETERMINATE` or none of the five, `trace-unavailable` for any other — plus `untraced-beyond-list` when an `…and <n> more` line closes the untraced list. The `Exempt` line counts each exempt kind (its listed lines plus its `…and <n> more`) and names every listed exempt SHA.
+- `@<login>` is `@` followed by the output of `gh api user --jq .login` when that output matches `^[A-Za-z0-9][A-Za-z0-9-]{0,38}$`. On any other output, or a failed call, it is `(login unavailable)` instead, with no `@`.
+- `<utc>` is the output of `date -u +%Y-%m-%dT%H:%M:%SZ`.
+- `<reason>` is the user's own words, made inert: replace every character outside printable ASCII (newlines and tabs included) with a space, remove every `<`, `>`, `` ` ``, `[`, `]`, `\`, `/`, `#`, `@`, `&` and `$`, collapse runs of spaces, trim, keep the first 200 characters, and trim again. A reason that is empty after this is no reason.
+
+No ask, but the trace lists an exempt commit ⇒ `TRACEABILITY_EXCEPTIONS` is the heading and the `Exempt` line alone, added to `.release/.progress.json` the same way: an exemption is self-asserted, so it is printed, never hidden.
 
 Build ordered execution plan from RELEASE_CONFIG. For monorepo: respect dependency ordering, present package selection to user.
 
@@ -125,17 +166,19 @@ Confirm with user via AskUserQuestion before executing:
 ### Phase 6: Execute Release
 
 **Produces:** RELEASE_RESULT
-**Requires:** RELEASE_PLAN, VERSION
+**Requires:** RELEASE_PLAN, VERSION, EVIDENCE_POLICY, RELEASE_EVIDENCE, TRACEABILITY_EXCEPTIONS
 
 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)
-2b. **Gather release evidence** (compliance-gated: only when COMPLIANCE_SKILL_INSTALLED) — spawn `Agent(subagent_type="Git")` with `gather-release-evidence` operation; pass `WORKTREE_PATH` if provided. Consume the returned `COMMIT_LIST` and `SHIPPED_ISSUES` for use in steps 4 and 4b. The Git agent applies bounds (≤100 commits, ≤50 issues) and degrades gracefully per D4.
 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); when COMPLIANCE_SKILL_INSTALLED, also pass `COMMIT_LIST` and `SHIPPED_ISSUES` as inputs so the agent includes them in the release notes body.
-4b. **Back-link shipped issues** (compliance-gated: only when COMPLIANCE_SKILL_INSTALLED) — 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
+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
+4c. **Associate shipped issues with the release** (only when `EVIDENCE_POLICY` is `required` and `SHIPPED_ISSUES` is non-empty) — spawn `Agent(subagent_type="Git")` with `associate-release` operation, passing `VERSION` and `SHIPPED_ISSUES`; it adds each issue to the release's tracker marker and never replaces another; degrade gracefully (D4) — never block the release
 5. **Publish** — CI-driven (report) or manual (provide instructions)
-6. **Post-release steps** — version bump to next dev, close milestone, etc.
+6. **Post-release steps** — version bump to next dev
+
+**Resume:** a checkpoint missing the RELEASE_EVIDENCE its Phase 4 gate called for is gathered again, with Phase 5's traceability step re-run, only before step 4; after step 4, report `evidence lost on resume` and continue — never block.
 
 Delete `.release/.progress.json` on success.
 
@@ -153,7 +196,7 @@ If the orchestrator receives a `WORKTREE_PATH` context, pass it through to all s
 
 On completion:
 - Git tag created: `v{VERSION}` (or configured tag format)
-- GitHub Release created with release notes
+- GitHub Release created with release notes — `## Traceability exceptions` last, when composed (Record, or the no-ask exempt rule)
 - Changelog updated (if configured)
 - Version files bumped
 - `.release/RELEASE-FLOW.md` created (first run only)
@@ -177,13 +220,15 @@ On completion:
 │
 ├─ Phase 4: Pre-release Checks
 │  ├─ Validate agent (build + test)
+│  ├─ Git agent: gather release evidence + trace map (dry run, or evidence policy required)
 │  └─ Write progress checkpoint
 │
 ├─ Phase 5: Build Release Plan
+│  ├─ Traceability: classify the trace map; record exceptions or halt (evidence policy required)
 │  └─ Confirm with user before executing
 │
 ├─ Phase 6: Execute Release
-│  ├─ Version bumps → Changelog → Commit → Git agent (tag + release) → Publish → Post-release
+│  ├─ Version bumps → Changelog → Commit → Git agent (tag + release) → Back-link → Associate → Publish → Post-release
 │  └─ Progress checkpoints between each step
 │
 └─ Phase 7: Suggest Improvements
@@ -201,6 +246,8 @@ On completion:
 
 - Validate agent fails (build/test): halt, report failures, do not proceed
 - User declines release plan: halt gracefully
+- User halts at the traceability question: stop — nothing has been committed, tagged or published
+- Git agent reports DEGRADED while gathering, back-linking or associating: warn and continue — never halt the release
 - Git agent fails (tag/release): halt, report error, suggest manual steps
 - Mid-release failure: progress checkpoint enables resume on next run
 - Version file not found: halt, report which file is missing, ask user to update RELEASE-FLOW.md