devflow-kit 2.4.0 → 3.0.0

package/src/assets/commands/implement.mds

@@ -4,8 +4,12 @@ output-dir: dist/commands
 ---
 @import { knowledge_load, knowledge_writeback } from "./_partials/_knowledge.mds"
 @import { decisions_load } from "./_partials/_decisions.mds"
-@import { compliance_gate } from "./_partials/_compliance.mds"
-
+@import { docs_root } from "./_partials/_docs_root.mds"
+@import { evidence_policy, evidence_exception } from "./_partials/_evidence_policy.mds"
+@import { issue_ref_grammar, issue_capture_contract } from "./_partials/_tracker.mds"
+@import { test_plan_line } from "./_partials/_plan_contract.mds"
+@import { publication_gate } from "./_partials/_publication.mds"
+@import "./_partials/_compliance.mds" as compliance
 # Implement Command
 
 Orchestrate a single task through implementation by spawning specialized agents. The orchestrator only spawns agents and passes context - all work is done by agents.
@@ -23,10 +27,12 @@ Orchestrate a single task through implementation by spawning specialized agents.
 
 `$ARGUMENTS` contains whatever follows `/implement`:
 - Plan document path: `.devflow/docs/design/42-jwt-auth.2026-04-07_1430.md` (path to an existing `.md` file)
-- GitHub issue: `#42`
+- Issue reference: `#42`
 - Task description: "implement JWT auth"
 - Empty: use conversation context
 
+{{issue_ref_grammar()}}
+
 > **Tip**: For best results, run `/plan` first to produce a design artifact, then pass it to `/implement`.
 
 ## Phases
@@ -37,21 +43,34 @@ When the user explicitly asks to re-validate, re-check, or re-run quality gates
 
 1. **Branch safety check**: If on a protected branch (main, master, develop, etc.), run Phase 1 to create/switch to a work branch. If already on a work branch, skip Phase 1.
 2. **Skip Phase 2** — no Code agent needed, user already made changes.
-3. **Detect FILES_CHANGED**: `git diff --name-only \{base_branch\}...HEAD`
+3. **Detect FILES_CHANGED**: `git diff --name-only {base_branch}...HEAD`
 4. **Run Phases 3-8** — full quality gate pipeline on detected changes.
-5. **Proceed to Phase 10** (Create PR) / **Phase 11** (Report).
+5. **Proceed to Phase 10** (Create PR), **Phase 10b** (Evidence) and **Phase 11** (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, PR_DESCRIPTION_GUIDANCE, ISSUE_NUMBER
+**Produces:** TASK_ID, BASE_BRANCH, EXECUTION_PLAN, DECISIONS_CONTEXT, FEATURE_KNOWLEDGE, 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
 
 **Load Companion Skills** — Load via Skill tool: `devflow:test-driven-development`, `devflow:patterns`, `devflow:dependency-research`. If a skill fails to load, continue without it.
 
 Record the current branch name as `BASE_BRANCH` - this will be the PR target.
 
-{compliance_gate()}
+{{docs_root()}}
+
+{{evidence_policy()}}
+
+**Plan Document Handling** (when $ARGUMENTS is a path ending in `.md`):
+1. Read the plan document from the path provided
+2. Extract from YAML frontmatter: `execution-strategy`, `context-risk`, `issue` number
+3. Extract from body: Subtask Breakdown, Implementation Plan, Patterns to Follow, Acceptance Criteria
+4. If the frontmatter `issue` is present and is not `pending`: forward it verbatim as the setup-task `ISSUE_INPUT` (`pending` means /plan's issue step degraded or was declined — treat it as absent)
+5. Use extracted content as EXECUTION_PLAN for the Code agent phase (replaces exploration/planning output)
+6. Captured values override defaults from Git agent where present
+7. Extract `## PR Description Guidance` section (if present) → set `PR_DESCRIPTION_GUIDANCE` to its full content. If section not found, set `PR_DESCRIPTION_GUIDANCE` to `(none)`.
+
+If `PR_DESCRIPTION_GUIDANCE` was not set above (non-plan paths: issue input or task description), set it to `(none)`.
 
 Spawn Git agent to set up task environment. The Git agent derives the branch name automatically from the issue or task description:
 
@@ -59,42 +78,102 @@ Spawn Git agent to set up task environment. The Git agent derives the branch nam
 Agent(subagent_type="Git"):
 "OPERATION: setup-task
 BASE_BRANCH: {current branch name}
-ISSUE_INPUT: {issue number if $ARGUMENTS starts with #, otherwise omit}
-TASK_DESCRIPTION: {task description from $ARGUMENTS if not an issue number or .md path, otherwise omit}
-COMPLIANCE: {enabled if COMPLIANCE_SKILL_INSTALLED, otherwise (none)}
+ISSUE_INPUT: {$ARGUMENTS verbatim, when it is a single whitespace-delimited token that does not end in .md; when it ends in .md, the plan frontmatter's issue value verbatim unless absent or pending — otherwise omit}
+TASK_DESCRIPTION: {$ARGUMENTS verbatim, when it is two or more whitespace-delimited tokens — otherwise omit}
+ISSUE_REQUIRED: {ISSUE_REQUIRED}
+APPLY_CONVENTIONS: {APPLY_CONVENTIONS}
 PLAN_ARTIFACT_PATH: {path to plan document if $ARGUMENTS ends in .md, otherwise (none)}
 Derive branch name from issue or description, create feature branch, and fetch issue if specified.
 Return the branch setup summary."
 ```
 
+The issue token is forwarded **unclassified**, and the routing is decided by
+SHAPE alone — how many tokens `$ARGUMENTS` has, and whether it ends in `.md`.
+
+`setup-task` is the one step that has resolved a provider, and therefore the only
+one that knows what an issue reference looks like on this machine: `#123`,
+`PROJ-12` and `ENG-12` are three providers' spellings of the same thing. A
+`starts with #` test here would be a github test wearing a neutral name — it
+reclassifies every other provider's reference as a task description, so the
+branch is derived from prose and no issue is ever fetched, with nothing reporting
+a problem. Token COUNT is the gate that stays provider-neutral: every one of
+those spellings is a single token, and no free-text task description is.
+
+The two tests this command does make are its own under every provider:
+
+- **Extension.** A path ending in `.md` is a plan document, never an issue
+  reference — it goes to `PLAN_ARTIFACT_PATH` and neither of the other two keys.
+  `ISSUE_INPUT` then carries the plan's frontmatter `issue` instead, never the
+  path (Plan Document Handling step 4).
+- **Token count.** A single token is an issue reference. Two or more is prose:
+  forwarding only its FIRST token would send `/implement fix the login bug` to
+  the Git agent as `ISSUE_INPUT: fix` with no description at all, and
+  `setup-task` fetches whatever it is handed — so the command would derive a
+  branch from a failed lookup and drop the request on the floor.
+
+The cost of the count gate is a one-word task description (`/implement refactor`)
+reaching `setup-task` as an issue reference, where it fails the lookup and is
+reported. That is the direction the failure has to fall: an unfetched issue is
+visible, a silently discarded request is not.
+
 **Capture from Git agent output** (used throughout flow):
 - `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`: GitHub issue number (if provided or created by the issue-first gate in step 1c)
-- `ISSUE_CONTENT`: Full issue body including description (if provided)
-- `ACCEPTANCE_CRITERIA`: Extracted acceptance criteria from issue (if provided)
+- `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)
 
-**Plan Document Handling** (when $ARGUMENTS is a path ending in `.md`):
-1. Read the plan document from the path provided
-2. Extract from YAML frontmatter: `execution-strategy`, `context-risk`, `issue` number
-3. Extract from body: Subtask Breakdown, Implementation Plan, Patterns to Follow, Acceptance Criteria
-4. If `issue` field present in frontmatter: pass to Git agent as ISSUE_INPUT
-5. Use extracted content as EXECUTION_PLAN for the Code agent phase (replaces exploration/planning output)
-6. Captured values override defaults from Git agent where present
-7. Extract `## PR Description Guidance` section (if present) → set `PR_DESCRIPTION_GUIDANCE` to its full content. If section not found, set `PR_DESCRIPTION_GUIDANCE` to `(none)`.
+{{issue_capture_contract()}}
 
-If `PR_DESCRIPTION_GUIDANCE` was not set above (non-plan paths: issue input or task description), set it to `(none)`.
+**Ticket link, only when `ISSUE_REQUIRED` is `true`:** when the capture above holds no `ISSUE_PR_LINK` (absent, or `(none)`), ask with AskUserQuestion before any Code spawn — "No tracker issue is linked to this task. Record a self-attested exception, or stop?" — offering exactly these two options:
+- **Record an exception** — the user gives the reason as free text. Render it with the grammar below, as kind `ticket-link`; when the rendered reason is empty, ask for it once more, and stop as below if it is empty again.
+- **Stop** — report `BLOCKED (no ticket link)`, name the branch setup-task created (`TASK_ID`) and `BASE_BRANCH` so it can be reused or removed, and give the remedy: create or link the tracker issue and re-run `/implement` with its reference, or — for a team that does not want ticket links — 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.
+
+{{evidence_exception()}}
+
+**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)`.
+
+**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.
+
+Write the `## Test Plan` section: when `$ARGUMENTS` is a plan document with a `## Test Plan` section, copy that section's lines verbatim; otherwise write one TP line per acceptance criterion the plan, the issue or the task text states, numbered from `TP-1`. Never invent a criterion, and word every scenario yourself in plain words: the lines reach the PR body, so a scenario holds no `#`, `@` or `/` — no issue reference, mention, closing keyword target or URL — and the files a TP covers go in its `files:` field. Each line follows the TP-line contract:
+
+{{test_plan_line()}}
+
+Check the section:
+
+```bash
+node "$HOME/.devflow/scripts/verify-evidence.cjs" check tp "{worktree}/.devflow/docs/evidence-{branch_slug}.md"; echo "exit=$?"
+```
+
+`exit=0` passes. On any other result, rewrite the section once — the script names the failing line and its code on stderr — and check again. Still failing, or no line to write, means the test plan is **missing**: drop the `## Test Plan` section from the file.
+
+**Missing test plan, only when `EVIDENCE_POLICY` is `required`:** when the check above leaves the test plan missing, ask with AskUserQuestion before any Code spawn — "No test plan could be written for this task. Record a self-attested exception, or stop?" — offering exactly these two options:
+- **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.
+
+**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.
+- `PR_TEST_PLAN_BLOCK` — when the test plan is present and this render ends in `exit=0`, its stdout byte for byte without that `exit=` line; `(none)` otherwise:
 
-{decisions_load()}
+```bash
+node "$HOME/.devflow/scripts/verify-evidence.cjs" render --plan "{worktree}/.devflow/docs/evidence-{branch_slug}.md"; echo "exit=$?"
+```
+
+- `EVIDENCE_FILE` — `{worktree}/.devflow/docs/evidence-{branch_slug}.md`, its `## Evidence Exceptions` section now a byte copy of `PR_EXCEPTIONS` (absent when that is `(none)`).
+
+{{publication_gate()}}
+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.compliance_frameworks()}} Pass it to every Code spawn.
+
+{{decisions_load()}}
 
 Pass to Code agent (Phase 2) and Scrutinize agent (Phase 5).
 
-{knowledge_load()}
+{{knowledge_load()}}
 
 ### Phase 2: Implement
 
-**Produces:** CODE_AGENT_OUTPUT, FILES_CHANGED
-**Requires:** TASK_ID, BASE_BRANCH, EXECUTION_PLAN, PR_DESCRIPTION_GUIDANCE
+**Produces:** CODE_AGENT_OUTPUT, FILES_CHANGED, PR_URL
+**Requires:** TASK_ID, BASE_BRANCH, EXECUTION_PLAN, PR_DESCRIPTION_GUIDANCE, PR_EXCEPTIONS, PR_TEST_PLAN_BLOCK
 
 Based on Setup context (plan document, issue body, or conversation context), use the three-strategy framework:
 
@@ -123,8 +202,12 @@ 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 number or (none)}"
+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)}"
 ```
 
 ---
@@ -145,10 +228,12 @@ 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 number or (none)}
+ISSUE_NUMBER: {ISSUE_ID captured in Phase 1, or (none)}
+ISSUE_PR_LINK: {ISSUE_PR_LINK captured in Phase 1, or (none)}
 HANDOFF_REQUIRED: true
-HANDOFF_FILE: .devflow/docs/handoff-{branch_slug}.md"
+HANDOFF_FILE: {worktree}/.devflow/docs/handoff-{branch_slug}.md"
 ```
 
 **Phase 2+ Code agents** (after prior phase completes):
@@ -165,13 +250,17 @@ 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 number or (none)}
+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)}
 HANDOFF_REQUIRED: {true if not last phase}
-HANDOFF_FILE: .devflow/docs/handoff-{branch_slug}.md"
+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. After each Code agent with HANDOFF_REQUIRED=true completes, write its phase summary to `.devflow/docs/handoff-\{branch_slug\}.md` using the Write tool (survives context compaction). Delete `.devflow/docs/handoff-\{branch_slug\}.md` after the final Code agent 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. After each Code agent with HANDOFF_REQUIRED=true completes, write its phase summary to `{worktree}/.devflow/docs/handoff-{branch_slug}.md` using the Write tool (survives context compaction), keeping any `## Evidence Exceptions` section byte-identical. Delete `{worktree}/.devflow/docs/handoff-{branch_slug}.md` once the PR exists — after the final Code agent, which creates it, completes (cleanup).
 
 ---
 
@@ -190,8 +279,10 @@ 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 number or (none)}"
+ISSUE_NUMBER: {ISSUE_ID captured in Phase 1, or (none)}
+ISSUE_PR_LINK: {ISSUE_PR_LINK captured in Phase 1, or (none)}"
 
 Agent(subagent_type="Code"):  # Code agent 2 (same message)
 "TASK_ID: {task-id}-part2
@@ -203,8 +294,10 @@ 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 number or (none)}"
+ISSUE_NUMBER: {ISSUE_ID captured in Phase 1, or (none)}
+ISSUE_PR_LINK: {ISSUE_PR_LINK captured in Phase 1, or (none)}"
 ```
 
 **Independence criteria** (all must be true for PARALLEL_CODE_AGENTS):
@@ -234,18 +327,31 @@ Run build, typecheck, lint, test. Report pass/fail with failure details."
    - Spawn Code agent with fix context:
    ```
    Agent(subagent_type="Code"):
-   "TASK_ID: \{task-id\}
+   "TASK_ID: {task-id}
    TASK_DESCRIPTION: Fix validation failures
    OPERATION: validation-fix
-   VALIDATION_FAILURES: \{parsed failures from Validate agent\}
+   VALIDATION_FAILURES: {parsed failures from Validate agent}
    SCOPE: Fix only the listed failures, no other changes
    CREATE_PR: false
-   ISSUE_NUMBER: \{issue number or (none)\}"
+   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}"
    ```
    - Loop back to Phase 3 (re-validate)
 4. If `validation_retry_count > 2`: Report failures to user and halt
 
-**If PASS:** Continue to Phase 4
+**If PASS:** append a `gate:validate` claim, then continue to Phase 4.
+
+**Evidence claims** are lines appended to the `## Claims` section of `EVIDENCE_FILE` — the file's last section, created when absent. Append only: never edit or remove a claim; the last valid one per target wins. Each line takes exactly one of these shapes, where `<head>` is the 40-hex `HEAD:` the agent's report shows:
+
+```
+- gate:validate PASS sha:<head> by:validate
+- TP-<n> <PASS|FAIL|SKIP> sha:<head> by:test exit:<0-255>
+```
+
+- `gate:validate` — after a Phase 3 or Phase 6 PASS.
+- `TP-<n>` — after every Phase 8 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.
 
 ### Phase 4: Simplify
 
@@ -296,7 +402,7 @@ Verify Scrutinize agent's fixes didn't break anything."
 
 **If FAIL:** Report to user - Scrutinize agent broke tests, needs manual intervention.
 
-**If PASS:** Continue to Phase 7
+**If PASS:** append a `gate:validate` claim (Phase 3's **Evidence claims**), then continue to Phase 7.
 
 ### Phase 7: Alignment Check
 
@@ -324,18 +430,20 @@ Validate alignment with request and plan. Report ALIGNED or MISALIGNED with deta
    - Spawn Code agent to fix misalignments:
    ```
    Agent(subagent_type="Code"):
-   "TASK_ID: \{task-id\}
+   "TASK_ID: {task-id}
    TASK_DESCRIPTION: Fix alignment issues
    OPERATION: alignment-fix
-   MISALIGNMENTS: \{structured misalignments from Evaluate agent\}
+   MISALIGNMENTS: {structured misalignments from Evaluate agent}
    SCOPE: Fix only the listed misalignments, no other changes
    CREATE_PR: false
-   ISSUE_NUMBER: \{issue number or (none)\}"
+   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}"
    ```
    - Spawn Validate agent to verify fix didn't break tests:
    ```
    Agent(subagent_type="Validate", model="haiku"):
-   "FILES_CHANGED: \{files modified by fix Code agent\}
+   "FILES_CHANGED: {files modified by fix Code agent}
    VALIDATION_SCOPE: changed-only"
    ```
    - If Validate agent FAIL: Report to user
@@ -345,7 +453,7 @@ Validate alignment with request and plan. Report ALIGNED or MISALIGNED with deta
 ### Phase 8: QA Testing
 
 **Produces:** QA_RESULT
-**Requires:** FILES_CHANGED, EXECUTION_PLAN
+**Requires:** FILES_CHANGED, EXECUTION_PLAN, TEST_PLAN
 
 After Evaluate agent passes, spawn Test agent for scenario-based acceptance testing:
 
@@ -355,9 +463,12 @@ Agent(subagent_type="Test"):
 EXECUTION_PLAN: {execution plan from Phase 1}
 FILES_CHANGED: {list of files from Code agent output}
 ACCEPTANCE_CRITERIA: {extracted criteria if available}
+TEST_PLAN: {the TP lines of the evidence file's ## Test Plan section, or (none)}
 Design and execute scenario-based acceptance tests. Report PASS or FAIL with evidence."
 ```
 
+After every Test agent run — PASS or FAIL, first run or retry — append its TP claims (Phase 3's **Evidence claims**).
+
 **If PASS:** Continue to Phase 9
 
 **If FAIL:**
@@ -367,18 +478,20 @@ Design and execute scenario-based acceptance tests. Report PASS or FAIL with evi
    - Spawn Code agent to fix QA failures:
    ```
    Agent(subagent_type="Code"):
-   "TASK_ID: \{task-id\}
+   "TASK_ID: {task-id}
    TASK_DESCRIPTION: Fix QA test failures
    OPERATION: qa-fix
-   QA_FAILURES: \{structured failures from Test agent\}
+   QA_FAILURES: {structured failures from Test agent}
    SCOPE: Fix only the listed failures, no other changes
    CREATE_PR: false
-   ISSUE_NUMBER: \{issue number or (none)\}"
+   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}"
    ```
    - Spawn Validate agent to verify fix didn't break tests:
    ```
    Agent(subagent_type="Validate", model="haiku"):
-   "FILES_CHANGED: \{files modified by fix Code agent\}
+   "FILES_CHANGED: {files modified by fix Code agent}
    VALIDATION_SCOPE: changed-only"
    ```
    - If Validate agent FAIL: Report to user
@@ -390,39 +503,86 @@ Design and execute scenario-based acceptance tests. Report PASS or FAIL with evi
 **Produces:** CI_STATUS
 **Requires:** PR_URL, FILES_CHANGED
 
-Strategy-conditional: run for **SINGLE_CODE_AGENT** (PR exists from Phase 2), skip for **SEQUENTIAL_CODE_AGENTS** / **PARALLEL_CODE_AGENTS** (PR not yet created).
+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).
 
 <!-- PATTERN: ci-status-gate -->
 1. Spawn `Agent(subagent_type="Git")` with `OPERATION: check-ci-status` and `PR_NUMBER` from PR_URL.
 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.
-4. **If PENDING** → poll every 60 seconds (global budget, see step 6). Re-spawn Git agent each poll. If PASSING → proceed. If still PENDING after budget exhausted → report "CI still running — verify manually before merging" and proceed.
-5. **If FAILING** → report failing checks. Spawn `Agent(subagent_type="Code")` to fix CI failures based on check names and failure context. After fix, push and re-check. Max 2 fix attempts. If still failing → report failures and proceed.
-6. **Total budget**: max 10 polls and max 2 fix attempts across all check/fix cycles combined. If budget exhausted, report current status and proceed.
+4. **If PENDING** → poll every 60 seconds (global budget, see step 7). Re-spawn Git agent each poll. If PASSING → proceed. If still PENDING after budget exhausted → report "CI still running — verify manually before merging" and proceed.
+5. **If INDETERMINATE** → poll as PENDING within the same budget. If still INDETERMINATE after budget exhausted → report "CI status unknown — verify manually before merging" and proceed.
+6. **If FAILING** → report failing checks. Spawn `Agent(subagent_type="Code")` with `COMPLIANCE_FRAMEWORKS` to fix CI failures based on check names and failure context. After fix, push and re-check. Max 2 fix attempts. If still failing → report failures and proceed.
+7. **Total budget**: max 10 polls and max 2 fix attempts across all check/fix cycles combined. If budget exhausted, report current status and proceed.
 <!-- /PATTERN: ci-status-gate -->
 
 ### Phase 10: Create PR
 
 **Produces:** PR_URL
-**Requires:** BASE_BRANCH, TASK_ID
+**Requires:** BASE_BRANCH, TASK_ID, PR_EXCEPTIONS, PR_TEST_PLAN_BLOCK
 
-**For SEQUENTIAL_CODE_AGENTS or PARALLEL_CODE_AGENTS**: The last sequential Code agent (with CREATE_PR: true) handles PR creation. For parallel Code agents, create unified PR using `devflow:git` skill patterns. Push branch and run `gh pr create` with comprehensive description, targeting `BASE_BRANCH`.
+**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.
 
-If `PR_DESCRIPTION_GUIDANCE` is not `(none)`, use it to compose the PR body (see Code agent Responsibility 7 for field-to-section mapping).
+**For PARALLEL_CODE_AGENTS**: spawn one Code agent to create the unified PR:
+
+```
+Agent(subagent_type="Code"):
+"TASK_ID: {task-id}
+TASK_DESCRIPTION: Create the unified PR for the parallel implementation
+OPERATION: pr-create
+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}"
+```
 
-When `ISSUE_NUMBER` is known, ensure the PR body includes a `## Related Issues` section with `Closes #\{ISSUE_NUMBER\}`.
+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
+
+**Produces:** EVIDENCE_RESULT
+**Requires:** PR_URL, 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.
+
+**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:
+
+```bash
+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.
+
+```
+Agent(subagent_type="Git"):
+"OPERATION: update-pr-evidence
+PR_NUMBER: {number from PR_URL}
+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.
+
 ### Phase 11: Report
 
-**Requires:** VALIDATION_RESULT, ALIGNMENT_RESULT, QA_RESULT, PR_URL
+**Requires:** VALIDATION_RESULT, ALIGNMENT_RESULT, QA_RESULT, PR_URL, EVIDENCE_RESULT
 
 Display completion summary with phase status, PR info, and next steps.
 
-If any Git agent output emitted `TRACEABILITY: DEGRADED (\{reason\})` lines during the run, surface them verbatim in the report under a `### Traceability` subsection so the user can act on them.
+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`.
+
+If any Git agent output emitted `TRACEABILITY: DEGRADED ({reason})` lines during the run, or Phase 10b's push recorded one, surface them verbatim in the report under a `### Traceability` subsection so the user can act on them.
 
-{knowledge_writeback()}
+If Phase 1 recorded an evidence exception, show its `## Evidence Exceptions` lines in the report.
+
+{{knowledge_writeback()}}
 
 ## Architecture
 
@@ -430,11 +590,13 @@ If any Git agent output emitted `TRACEABILITY: DEGRADED (\{reason\})` lines duri
 /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-11
+│  └─ Branch safety → skip Phase 2 → detect FILES_CHANGED → Phases 3-8 → Phase 10, 10b, 11
 │
 ├─ Phase 1: Setup
+│  └─ Plan document parsing (if .md path provided) - extracts execution plan, strategy, frontmatter issue
 │  └─ Git agent (operation: setup-task) - creates feature branch, fetches issue
-│  └─ Plan document parsing (if .md path provided) - extracts execution plan, strategy
+│  └─ Ticket-link ask (no linked ticket, issue required) - record a self-attested exception or stop
+│  └─ 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
@@ -444,6 +606,7 @@ If any Git agent output emitted `TRACEABILITY: DEGRADED (\{reason\})` lines duri
 ├─ Phase 3: Validate
 │  └─ Validate agent (build, typecheck, lint, test)
 │  └─ If FAIL: Code agent fix loop (max 2 retries) → re-validate
+│  └─ If PASS: gate:validate claim → evidence file
 │
 ├─ Phase 4: Simplify
 │  └─ Simplify agent (refines code clarity and consistency)
@@ -459,16 +622,20 @@ If any Git agent output emitted `TRACEABILITY: DEGRADED (\{reason\})` lines duri
 │  └─ If MISALIGNED: Code agent fix loop (max 2 iterations) → Validate agent → re-check
 │
 ├─ Phase 8: QA Testing
-│  └─ Test agent (scenario-based acceptance tests)
+│  └─ Test agent (scenario-based acceptance tests, TEST_PLAN) → one claim per TP row → evidence file
 │  └─ If FAIL: Code agent fix loop (max 2 retries) → Validate agent → re-test
 │
-├─ Phase 9: CI Status Gate (SINGLE_CODE_AGENT only)
+├─ Phase 9: CI Status Gate (SINGLE_CODE_AGENT + SEQUENTIAL_CODE_AGENTS; skipped for PARALLEL_CODE_AGENTS)
 │  └─ Git agent (check-ci-status) → poll/fix cycle (10 polls + 2 fix budget)
 │
 ├─ Phase 10: Create PR (if needed)
-│  └─ SINGLE_CODE_AGENT: handled by Code agent
-│  └─ SEQUENTIAL: handled by last Code agent
-│  └─ PARALLEL: orchestrator creates unified PR
+│  └─ 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 10b: 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
 │
@@ -489,7 +656,7 @@ If any Git agent output emitted `TRACEABILITY: DEGRADED (\{reason\})` lines duri
 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
 11. **Loop limits** - Max 2 validation retries, max 2 alignment fix iterations before escalating to user
-12. **CI awareness** - CI status is checked before merge for SINGLE_CODE_AGENT strategy
+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
 
 ## Error Handling