devflow-kit 2.4.0 → 3.0.0

package/src/assets/commands/bug-analysis.mds

@@ -4,8 +4,8 @@ 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 { docs_root } from "./_partials/_docs_root.mds"
+@import { evidence_policy } from "./_partials/_evidence_policy.mds"
 # Bug Analysis Command
 
 Run a proactive bug analysis on the current branch by combining static analysis tools with parallel semantic analyzers, then synthesizing results into an actionable bug report. Supports incremental analysis, timestamped report directories, and `/resolve` compatibility.
@@ -22,17 +22,29 @@ Run a proactive bug analysis on the current branch by combining static analysis
 
 ### Phase 1: Pre-flight
 
-**Produces:** BRANCH_INFO, PR_DESCRIPTION, COMPLIANCE_SKILL_INSTALLED
+**Produces:** BRANCH_INFO, PR_DESCRIPTION, EVIDENCE_POLICY, ISSUE_REQUIRED, APPLY_CONVENTIONS, REQUIRE_NON_AUTHOR_APPROVAL
+
+{{evidence_policy()}}
+
+{{docs_root()}}
+
+Render the test-plan block from `/implement`'s evidence file, and from nothing else:
+1. `branch_slug` is `git branch --show-current` with every `/` replaced by `-`.
+2. Only when `branch_slug` matches `^[A-Za-z0-9._-]{1,200}$` and the file exists, run (the path double-quoted):
+
+```bash
+node "$HOME/.devflow/scripts/verify-evidence.cjs" render --plan "{worktree}/.devflow/docs/evidence-{branch_slug}.md"; echo "exit=$?"
+```
 
-{compliance_gate()}
-Reuse this result for every downstream phase.
+3. On `exit=0`, `PR_TEST_PLAN_BLOCK` is its stdout byte for byte without that `exit=` line; in every other case it is `(none)`. Nothing here waits on it: the Git agent pastes it only behind its own check, and only into a PR it creates.
 
 Spawn Git agent:
 
 ```
 Agent(subagent_type="Git", run_in_background=false):
 "OPERATION: ensure-pr-ready
-COMPLIANCE: {COMPLIANCE_SKILL_INSTALLED ? "enabled" : "(none)"}
+PR_TEST_PLAN_BLOCK: {PR_TEST_PLAN_BLOCK verbatim, or (none)}
+APPLY_CONVENTIONS: {APPLY_CONVENTIONS}
 Validate branch, commit if needed, push, create PR if needed.
 Return: branch, base_branch, branch-slug, PR#"
 ```
@@ -54,16 +66,16 @@ If `pr_number` is absent or the command fails, set `PR_DESCRIPTION` to `(none)`.
 **Produces:** DIFF_RANGE, ANALYSIS_DIR
 **Requires:** BRANCH_INFO
 
-1. Check `.devflow/docs/bug-analysis/\{branch-slug\}/.last-analysis-head`:
+1. Check `{worktree}/.devflow/docs/bug-analysis/{branch-slug}/.last-analysis-head`:
    - **If exists AND `--full` NOT set:**
      - Read the SHA from the file
-     - Verify reachable: `git cat-file -t \{sha\}` — if exit code non-zero (rebase invalidated SHA), fall through to full
+     - Verify reachable: `git cat-file -t {sha}` — if exit code non-zero (rebase invalidated SHA), fall through to full
      - If SHA == current HEAD → "No new commits since last analysis. Use --full for a full re-analysis." Stop.
-     - Set `DIFF_RANGE` to `\{sha\}...HEAD`
+     - Set `DIFF_RANGE` to `{sha}...HEAD`
    - **If not exists, unreachable SHA, or `--full`:**
-     - Set `DIFF_RANGE` to `\{base_branch\}...HEAD`
+     - Set `DIFF_RANGE` to `{base_branch}...HEAD`
 2. Generate timestamp: `YYYY-MM-DD_HHMM`. If directory already exists (same-minute collision), append seconds (`YYYY-MM-DD_HHMMSS`).
-3. Create timestamped analysis directory: `mkdir -p .devflow/docs/bug-analysis/\{branch-slug\}/\{timestamp\}/`
+3. Create timestamped analysis directory: `mkdir -p "{worktree}/.devflow/docs/bug-analysis/{branch-slug}/{timestamp}/"`
 4. Set `ANALYSIS_DIR` to that path.
 
 #### Step 2b: Check Changed Files
@@ -148,9 +160,9 @@ Parse `CODEQL_SARIF` → extract findings. If database creation fails, `CODEQL_E
 
 | Tool | File:Line | CWE | Severity | Title | Description |
 |------|-----------|-----|----------|-------|-------------|
-| \{tool\} | \{file\}:\{line\} | \{CWE or —\} | \{CRITICAL/HIGH/MEDIUM/LOW\} | \{title\} | \{description truncated to 200 chars\} |
+| {tool} | {file}:{line} | {CWE or —} | {CRITICAL/HIGH/MEDIUM/LOW} | {title} | {description truncated to 200 chars} |
 
-Write ALL raw findings to `\{ANALYSIS_DIR\}/static-findings.md`. Set `STATIC_FINDINGS` to the top-50 table.
+Write ALL raw findings to `{ANALYSIS_DIR}/static-findings.md`. Set `STATIC_FINDINGS` to the top-50 table.
 
 If no tool produced findings: set `STATIC_FINDINGS` to `(none)`.
 
@@ -160,15 +172,15 @@ If no tool produced findings: set `STATIC_FINDINGS` to `(none)`.
 
 #### Decisions Index
 
-{decisions_load()}
+{{decisions_load()}}
 
 #### Feature Knowledge
 
-{knowledge_load()}
+{{knowledge_load()}}
 
 #### Plan Artifact
 
-1. List `.devflow/docs/design/*.md` — sort descending by filename (timestamps are naturally sortable), scan the 10 most recent
+1. List `{worktree}/.devflow/docs/design/*.md` — sort descending by filename (timestamps are naturally sortable), scan the 10 most recent
 2. Read the most recent file if it exists
 3. Extract `## Acceptance Criteria` section → parse into table: `| ID | Criterion | Type | Testable Condition |`
 4. Set `PLAN_CONTEXT` to plan summary; `ACCEPTANCE_RULES` to the table
@@ -238,7 +250,7 @@ Output: {ANALYSIS_DIR}/bug-analysis-summary.md"
 
 **Requires:** BRANCH_INFO, ANALYSIS_DIR
 
-1. Write current HEAD SHA to `.devflow/docs/bug-analysis/\{branch-slug\}/.last-analysis-head`
+1. Write current HEAD SHA to `{worktree}/.devflow/docs/bug-analysis/{branch-slug}/.last-analysis-head`
 2. Report to user:
 
 ```
@@ -289,7 +301,7 @@ Run `/resolve` to process and fix these findings.
 ├─ Phase 3: Context Loading
 │  ├─ index.md (pre-rendered) → DECISIONS_CONTEXT
 │  ├─ Feature knowledge load → FEATURE_KNOWLEDGE
-│  └─ .devflow/docs/design/*.md → PLAN_CONTEXT + ACCEPTANCE_RULES
+│  └─ {worktree}/.devflow/docs/design/*.md → PLAN_CONTEXT + ACCEPTANCE_RULES
 │
 ├─ Phase 4: File Analysis
 │  └─ Detect active focuses (security + functional always; integration + usability conditional)
@@ -347,7 +359,7 @@ Before reporting results, verify every phase was executed:
 - [ ] Phase 3: Context Loading → DECISIONS_CONTEXT captured, FEATURE_KNOWLEDGE loaded (or `(none)`), PLAN_CONTEXT and ACCEPTANCE_RULES captured (or `(none)`)
 - [ ] Phase 4: File Analysis → ACTIVE_FOCUSES determined (security + functional always present)
 - [ ] Phase 5: Parallel Bug Analysis → ANALYZER_OUTPUTS captured per active focus; all reports written to ANALYSIS_DIR
-- [ ] Phase 6: Synthesis → BUG_ANALYSIS_SUMMARY written to `\{ANALYSIS_DIR\}/bug-analysis-summary.md`
+- [ ] Phase 6: Synthesis → BUG_ANALYSIS_SUMMARY written to `{ANALYSIS_DIR}/bug-analysis-summary.md`
 - [ ] Phase 7: Finalize → `.last-analysis-head` updated; results displayed to user
 
 If any phase is unchecked, execute it before proceeding.

package/src/assets/commands/code-review.mds

@@ -5,8 +5,8 @@ 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 { publication_gate } from "./_partials/_publication.mds"
-
 # Code Review Command
 
 Run a comprehensive code review of the current branch by spawning parallel review agents, then synthesizing results into PR comments. Supports incremental reviews, timestamped report directories, and multi-worktree auto-discovery.
@@ -30,18 +30,24 @@ Run a comprehensive code review of the current branch by spawning parallel revie
 
 1. **Discover reviewable worktrees** using the `devflow:worktree-support` skill discovery algorithm:
    - Run `git worktree list --porcelain` → parse, filter (skip protected/detached/mid-rebase), dedup by branch, sort by recent commit
-   - See `~/.claude/skills/devflow:worktree-support/SKILL.md` for the full 7-step algorithm and canonical protected branch list
+   - See the `devflow:worktree-support` skill for the full 7-step algorithm and canonical protected branch list
 2. **If `--path` flag provided:** use only that worktree, skip discovery
    **`--path` validation**: Before proceeding, verify the path exists as a directory and appears in `git worktree list` output. If not: report error and stop.
 3. **If only 1 reviewable worktree** (the common case): proceed as single-worktree flow — zero behavior change
-4. **If multiple reviewable worktrees:** report "Found N worktrees with reviewable branches: \{list with paths and branches\}" and proceed with multi-worktree flow
+4. **If multiple reviewable worktrees:** report "Found N worktrees with reviewable branches: {list with paths and branches}" and proceed with multi-worktree flow
+
+#### Step 0b: Resolve the compliance lens
+
+**Produces:** COMPLIANCE_ACTIVE, COMPLIANCE_FRAMEWORKS
+
+{{compliance_gate()}}
+Keep each worktree's values for every downstream phase of that worktree.
 
-#### Step 0b: Resolve COMPLIANCE_SKILL_INSTALLED
+#### Step 0b-ii: Resolve the evidence policy
 
-**Produces:** COMPLIANCE_SKILL_INSTALLED
+**Produces:** EVIDENCE_POLICY, ISSUE_REQUIRED, APPLY_CONVENTIONS, REQUIRE_NON_AUTHOR_APPROVAL
 
-{compliance_gate()}
-Reuse this result for every worktree and every downstream phase.
+{{evidence_policy()}}
 
 #### Step 0c: Per-Worktree Pre-Flight (Git Agent)
 
@@ -49,11 +55,21 @@ Reuse this result for every worktree and every downstream phase.
 **Requires:** WORKTREES
 
 Discover PR description guidance from plan artifact (per worktree):
-1. List `\{worktree\}/.devflow/docs/design/*.md` files
+1. List `{worktree}/.devflow/docs/design/*.md` files
 2. Sort by timestamp in filename (descending -- timestamps are YYYY-MM-DD_HHMM, naturally sortable)
 3. Read the most recent file, extract `## PR Description Guidance` section
 4. If no plan files exist or section not found, set `PR_DESCRIPTION_GUIDANCE` to `(none)`
 
+Render the test-plan block (per worktree) from `/implement`'s evidence file, and from nothing else:
+1. `branch_slug` is `git -C "{worktree}" branch --show-current` with every `/` replaced by `-`.
+2. Only when `branch_slug` matches `^[A-Za-z0-9._-]{1,200}$` and the file exists, run (the path double-quoted):
+
+```bash
+node "$HOME/.devflow/scripts/verify-evidence.cjs" render --plan "{worktree}/.devflow/docs/evidence-{branch_slug}.md"; echo "exit=$?"
+```
+
+3. On `exit=0`, `PR_TEST_PLAN_BLOCK` is its stdout byte for byte without that `exit=` line; in every other case it is `(none)`. Nothing here waits on it: the Git agent pastes it only behind its own check, and only into a PR it creates.
+
 For each reviewable worktree, spawn Git agent:
 
 ```
@@ -61,7 +77,8 @@ Agent(subagent_type="Git", run_in_background=false):
 "OPERATION: ensure-pr-ready
 WORKTREE_PATH: {worktree_path}  (omit if cwd)
 PR_DESCRIPTION_GUIDANCE: {pr_description_guidance}
-COMPLIANCE: {COMPLIANCE_SKILL_INSTALLED ? "enabled" : "(none)"}
+PR_TEST_PLAN_BLOCK: {PR_TEST_PLAN_BLOCK verbatim, or (none)}
+APPLY_CONVENTIONS: {APPLY_CONVENTIONS}
 Validate branch, commit if needed, push, create PR if needed.
 Return: branch, base_branch, branch-slug, PR#"
 ```
@@ -86,15 +103,15 @@ If `pr_number` is absent or the command fails, set `PR_DESCRIPTION` to `(none)`.
 For each worktree:
 
 1. Generate timestamp: `YYYY-MM-DD_HHMM`. If directory already exists (same-minute collision), append seconds (`YYYY-MM-DD_HHMMSS`).
-2. Create timestamped review directory: `mkdir -p \{worktree\}/.devflow/docs/reviews/\{branch-slug\}/\{timestamp\}/`
-3. Check if `\{worktree\}/.devflow/docs/reviews/\{branch-slug\}/.last-review-head` exists:
+2. Create timestamped review directory: `mkdir -p {worktree}/.devflow/docs/reviews/{branch-slug}/{timestamp}/`
+3. Check if `{worktree}/.devflow/docs/reviews/{branch-slug}/.last-review-head` exists:
    - **If yes AND `--full` NOT set:**
      - Read the SHA from the file
-     - Verify reachable: `git -C \{worktree\} cat-file -t \{sha\}` (handles rebases — if unreachable, fallback to full)
+     - Verify reachable: `git -C {worktree} cat-file -t {sha}` (handles rebases — if unreachable, fallback to full)
      - Check if SHA == current HEAD → if so, skip review: "No new commits since last review. Use --full for a full re-review."
-     - Set `DIFF_RANGE` to `\{last-review-sha\}...HEAD`
+     - Set `DIFF_RANGE` to `{last-review-sha}...HEAD`
    - **If no (first review), or `--full`:**
-     - Set `DIFF_RANGE` to `\{base_branch\}...HEAD`
+     - Set `DIFF_RANGE` to `{base_branch}...HEAD`
 
 #### Step 0e-i: Load Prior Resolution and Count Cycles
 
@@ -102,10 +119,10 @@ For each worktree:
 **Requires:** BRANCH_INFO
 
 For each worktree, perform a single pass over timestamped directories:
-1. List timestamped directories in `\{worktree\}/.devflow/docs/reviews/\{branch-slug\}/` sorted descending: `ls -1d \{worktree\}/.devflow/docs/reviews/\{branch-slug\}/20* 2>/dev/null | sort -r`
+1. List timestamped directories in `{worktree}/.devflow/docs/reviews/{branch-slug}/` sorted descending: `ls -1d {worktree}/.devflow/docs/reviews/{branch-slug}/20* 2>/dev/null | sort -r`
 2. Iterate once: accumulate CYCLE_NUMBER count for each directory containing `resolution-summary.md`; capture the first (most-recent) such directory as PRIOR_DIR.
 3. If CYCLE_NUMBER = 0: set PRIOR_RESOLUTIONS=(none), CYCLE_NUMBER=1, proceed.
-4. Otherwise: set CYCLE_NUMBER = count + 1. Read `\{PRIOR_DIR\}/resolution-summary.md` as PRIOR_RESOLUTIONS.
+4. Otherwise: set CYCLE_NUMBER = count + 1. Read `{PRIOR_DIR}/resolution-summary.md` as PRIOR_RESOLUTIONS.
 5. If `--full`: still load PRIOR_RESOLUTIONS (valuable for Review agent cross-cycle awareness).
 
 #### Step 0e-ii: Convergence Assessment
@@ -116,7 +133,7 @@ For each worktree, perform a single pass over timestamped directories:
 MAX_REVIEW_CYCLES = 10
 
 1. If CYCLE_NUMBER > MAX_REVIEW_CYCLES:
-   Warn in output: "⚠️ Review pipeline has run \{CYCLE_NUMBER-1\} cycles (exceeds MAX_REVIEW_CYCLES=10). Consider merging or manual inspection."
+   Warn in output: "⚠️ Review pipeline has run {CYCLE_NUMBER-1} cycles (exceeds MAX_REVIEW_CYCLES=10). Consider merging or manual inspection."
    Continue with review.
 2. Parse Statistics table from PRIOR_RESOLUTIONS:
    - Extract False Positive, Fixed, Deferred counts
@@ -125,7 +142,7 @@ MAX_REVIEW_CYCLES = 10
    - If denominator = 0: fp_ratio = 0, skip warning
    - If parsing fails: fp_ratio = 0, skip warning; note in output: "Warning: Could not parse Statistics table from prior resolution. FP ratio unavailable — convergence tracking degraded."
 3. If fp_ratio > 0.7 AND CYCLE_NUMBER >= 3:
-   Warn in output: "⚠️ Convergence: \{ratio\}% false positives in cycle \{N-1\}. Consider merging or manual inspection."
+   Warn in output: "⚠️ Convergence: {ratio}% false positives in cycle {N-1}. Consider merging or manual inspection."
    Continue with review.
 
 **Decision table — Step 0e-ii paths:**
@@ -139,16 +156,16 @@ MAX_REVIEW_CYCLES = 10
 #### Step 0f: Resolve Publication Mode (Per Worktree)
 
 **Produces:** REVIEW_PUBLICATION
-**Requires:** WORKTREES
+**Requires:** WORKTREES, EVIDENCE_POLICY
 
 For each reviewable worktree, call:
 
-{publication_gate()}
+{{publication_gate()}}
 
 ### Phase 1: Analyze Changed Files
 
 **Produces:** REVIEW_FOCUS_LIST
-**Requires:** DIFF_RANGE, COMPLIANCE_SKILL_INSTALLED (from Step 0b)
+**Requires:** DIFF_RANGE, COMPLIANCE_ACTIVE (from Step 0b)
 
 Per worktree, detect file types in diff using `DIFF_RANGE` to determine conditional reviews.
 
@@ -165,21 +182,29 @@ Per worktree, detect file types in diff using `DIFF_RANGE` to determine conditio
 | DB/migration files | database |
 | Dependency files changed | dependencies |
 | Docs or significant code | documentation |
-| COMPLIANCE_SKILL_INSTALLED AND diff touches regulated surface | compliance |
+| COMPLIANCE_ACTIVE AND diff touches regulated surface | compliance |
+
+If `COMPLIANCE_ACTIVE` AND the diff touches regulated surface (data models, auth flows, logging/observability, payments, IaC, retention): add `compliance` to REVIEW_FOCUS_LIST for this worktree.
+
+**Language focus presence gate.** The eight language focuses — `typescript`, `react`, `accessibility`, `ui-design`, `go`, `java`, `python`, `rust` — ship with optional plugins, so their pattern skills are installed only when the user selected that plugin. Gate them by presence: for each language focus the table above would add, check whether `{claude_dir}/skills/devflow:{focus}/SKILL.md` exists, `{claude_dir}` being Claude Code's directory as the installer resolves it — `CLAUDE_CONFIG_DIR` when that is set to an absolute path, else `$HOME/.claude` (D-CLAUDE-DIR-PROMPTS). Run one read-only, silent check per candidate focus:
+
+```bash
+d="${CLAUDE_CONFIG_DIR:-}"; case "$d" in /*) ;; *) d="$HOME/.claude" ;; esac; test -f "$d/skills/devflow:{focus}/SKILL.md"; echo "exit=$?"
+```
 
-If `COMPLIANCE_SKILL_INSTALLED` AND the diff touches regulated surface (data models, auth flows, logging/observability, payments, IaC, retention): add `compliance` to REVIEW_FOCUS_LIST for this worktree.
+Only `exit=0` means the skill is installed. On any other result, do NOT add that focus to `REVIEW_FOCUS_LIST` and do NOT spawn a Review agent for it — the file-type condition alone never spawns a language focus. The eight core focuses are unconditional and are never presence-gated.
 
 ### Phase 1b: Load Decisions Index
 
-**Produces:** DECISIONS_CONTEXT, FEATURE_KNOWLEDGE, COMPLIANCE_SKILL_INSTALLED (carried from Step 0b)
+**Produces:** DECISIONS_CONTEXT, FEATURE_KNOWLEDGE, COMPLIANCE_FRAMEWORKS (carried from Step 0b)
 
 **Load Companion Skills** — Load via Skill tool: `devflow:quality-gates`, `devflow:software-design`. If a skill fails to load, continue without it.
 
-{decisions_load()}
+{{decisions_load()}}
 
 This produces a compact index of active ADR/PF entries. Pass `DECISIONS_CONTEXT` to all Review agents. Review agents use `devflow:apply-decisions` to Read full entry bodies on demand.
 
-{knowledge_load()}
+{{knowledge_load()}}
 
 Pass `FEATURE_KNOWLEDGE` to all Review agents alongside `DECISIONS_CONTEXT`.
 
@@ -200,14 +225,14 @@ Spawn Review agents **in a single message**. Always run 8 core reviews; conditio
 | regression | ✓ | devflow:regression |
 | testing | ✓ | devflow:testing |
 | reliability | ✓ | devflow:reliability |
-| typescript | conditional | devflow:typescript |
-| react | conditional | devflow:react |
-| accessibility | conditional | devflow:accessibility |
-| ui-design | conditional | devflow:ui-design |
-| go | conditional | devflow:go |
-| java | conditional | devflow:java |
-| python | conditional | devflow:python |
-| rust | conditional | devflow:rust |
+| typescript | presence-gated | devflow:typescript |
+| react | presence-gated | devflow:react |
+| accessibility | presence-gated | devflow:accessibility |
+| ui-design | presence-gated | devflow:ui-design |
+| go | presence-gated | devflow:go |
+| java | presence-gated | devflow:java |
+| python | presence-gated | devflow:python |
+| rust | presence-gated | devflow:rust |
 | database | conditional | devflow:database |
 | dependencies | conditional | devflow:dependencies |
 | documentation | conditional | devflow:documentation |
@@ -227,6 +252,7 @@ DECISIONS_CONTEXT: {decisions_context}
 FEATURE_KNOWLEDGE: {feature_knowledge}
 PR_DESCRIPTION: <pr-description>{pr_description}</pr-description>
 PRIOR_RESOLUTIONS: <prior-resolution-summary>{prior_resolutions}</prior-resolution-summary>
+COMPLIANCE_FRAMEWORKS: {COMPLIANCE_FRAMEWORKS}  (compliance focus only)
 If PRIOR_RESOLUTIONS is not (none), follow Cross-Cycle Awareness in review.md.
 Follow devflow:apply-decisions to scan the index and Read full ADR/PF bodies on demand.
 Follow devflow:apply-feature-knowledge for FEATURE_KNOWLEDGE — feature-specific patterns and anti-patterns inform findings.
@@ -261,7 +287,7 @@ Output: {worktree_path}/.devflow/docs/reviews/{branch-slug}/{timestamp}/review-s
 Agent(subagent_type="Git", run_in_background=false):
 "OPERATION: post-review-summary
 PR_NUMBER: {pr_number}
-REVIEW_SUMMARY_PATH: {worktree_path}/.devflow/docs/reviews/{branch-slug}/{timestamp}/review-summary.md
+REVIEW_SUMMARY_PATH: .devflow/docs/reviews/{branch-slug}/{timestamp}/review-summary.md
 CYCLE_NUMBER: {cycle_number}
 REVIEW_TIMESTAMP: {timestamp}
 REVIEW_PUBLICATION: {REVIEW_PUBLICATION}
@@ -274,12 +300,12 @@ Posts the consolidated review-summary comment (marker-deduped by the operation o
 **Requires:** BRANCH_INFO, REVIEW_DIR
 
 Per worktree, after successful completion:
-1. Write current HEAD SHA to `\{worktree_path\}/.devflow/docs/reviews/\{branch-slug\}/.last-review-head`
+1. Write current HEAD SHA to `{worktree_path}/.devflow/docs/reviews/{branch-slug}/.last-review-head`
 2. Display results from all agents:
    - Merge recommendation (from Synthesize agent)
    - Issue counts by category (🔴 blocking / ⚠️ should-fix / ℹ️ pre-existing)
    - Review comment status: POSTED / POSTED+TRUNCATED (body exceeded 60k after redaction) / SKIPPED (D7 dedup) / DEGRADED (from Git)
-   - Publication status: FULL (private repo) | FULL (config override) | STUB (public repository) | OFF (publication disabled by config) (from Git agent)
+   - Publication status: FULL (private repo) | FULL (config override) | STUB (public repository) | OFF (publication disabled by config) | STUB (visibility undeterminable) | STUB (evidence policy) (from Git agent)
    - Artifact paths
 
 In multi-worktree mode, report results per worktree.
@@ -291,7 +317,7 @@ In multi-worktree mode, report results per worktree.
 │
 ├─ Phase 0: Worktree Discovery & Pre-flight
 │  ├─ Step 0a: git worktree list → filter reviewable
-│  ├─ Step 0b: Resolve COMPLIANCE_SKILL_INSTALLED
+│  ├─ Step 0b: Resolve the compliance lens
 │  ├─ Step 0c: Git agent (ensure-pr-ready) per worktree [parallel]
 │  ├─ Step 0d: Incremental detection + timestamp setup per worktree
 │  ├─ Step 0e-i: Load prior resolution-summary.md
@@ -330,19 +356,19 @@ In multi-worktree mode, report results per worktree.
 | Worktree pre-flight fails | Report failure, continue with other worktrees |
 | `--full` in multi-worktree mode | Applies to all worktrees (global modifier) |
 | Many worktrees (5+) | Report count and proceed — user manages their worktree count |
-| Review comment already posted | Git agent matches `<!-- devflow:review-summary cycle:\{N\} ts:\{REVIEW_TIMESTAMP\}` pair → skip silently (D7); a re-review in the same cycle (different timestamp) posts its own comment |
+| Review comment already posted | Git agent matches its own marker on the `{cycle, timestamp}` pair → skip silently (D7); a re-review in the same cycle (different timestamp) posts its own comment. The marker's format belongs to the operation; this caller passes the pair and never restates the literal |
 | First review (no prior resolution) | PRIOR_RESOLUTIONS=(none), no convergence check |
 | fp_ratio denominator = 0 | fp_ratio = 0, no warning |
 | `--full` flag | Bypass incremental detection (Step 0d), still load PRIOR_RESOLUTIONS for cross-cycle awareness |
 | Parsing failure on resolution-summary.md | fp_ratio = 0, convergence tracking degraded (see Step 0e-ii) |
 | Concurrent sessions | Advisory only, each session computes independently |
 | Public repo (`auto` mode) | Git agent probes visibility, posts counts-only STUB comment; full report stays local |
-| `reviewPublication: off` | Git agent skips posting the review comment (OFF) |
+| `reviewPublication: off` | Git agent skips posting the review comment (OFF) — except that, only when `EVIDENCE_POLICY` is `required`, Step 0f passes `stub` and a counts-only STUB comment posts |
 
 ## Backwards Compatibility
 
 - **Single worktree**: Auto-discovery finds only one worktree → proceeds exactly as before. Zero behavior change.
-- **Legacy flat layout**: If `.devflow/docs/reviews/\{branch-slug\}/` contains flat `*.md` files (no timestamped subdirectories), new runs create timestamped subdirectories. Old flat files remain untouched.
+- **Legacy flat layout**: If `{worktree}/.devflow/docs/reviews/{branch-slug}/` contains flat `*.md` files (no timestamped subdirectories), new runs create timestamped subdirectories. Old flat files remain untouched.
 
 ## Principles
 

package/src/assets/commands/debug.mds

@@ -4,7 +4,7 @@ output-dir: dist/commands
 ---
 @import { knowledge_writeback } from "./_partials/_knowledge.mds"
 @import { decisions_load } from "./_partials/_decisions.mds"
-
+@import { issue_ref_grammar, issue_capture_contract } from "./_partials/_tracker.mds"
 # Debug Command
 
 Investigate bugs by spawning parallel agents, each pursuing a different hypothesis. Evidence is aggregated and synthesized to identify the root cause.
@@ -14,14 +14,14 @@ Investigate bugs by spawning parallel agents, each pursuing a different hypothes
 ```
 /debug "description of bug or issue"
 /debug "function returns undefined when called with empty array"
-/debug #42   (investigate bug from GitHub issue)
+/debug #42   (investigate bug from issue reference)
 ```
 
 ## Input
 
 `$ARGUMENTS` contains whatever follows `/debug`:
 - Bug description: "login fails after session timeout"
-- GitHub issue: "#42"
+- Issue reference: "#42"
 - Empty: use conversation context
 
 ## Phases
@@ -32,7 +32,7 @@ Investigate bugs by spawning parallel agents, each pursuing a different hypothes
 
 **Load Companion Skills** — Load via Skill tool: `devflow:test-driven-development`, `devflow:software-design`, `devflow:testing`. If a skill fails to load, continue without it.
 
-{decisions_load()}
+{{decisions_load()}}
 
 The orchestrator uses `DECISIONS_CONTEXT` locally when generating hypotheses (Phase 2) — prior pitfalls and decisions can suggest specific root causes to investigate. Follow `devflow:apply-decisions` to Read full entry bodies on demand. **Do NOT pass `DECISIONS_CONTEXT` to Explore investigators** — decisions context stays in the orchestrator; investigators examine code directly.
 
@@ -43,15 +43,21 @@ The orchestrator uses `DECISIONS_CONTEXT` locally when generating hypotheses (Ph
 **Produces:** HYPOTHESES, BUG_CONTEXT
 **Requires:** DECISIONS_CONTEXT
 
-If `$ARGUMENTS` starts with `#`, fetch the GitHub issue:
+If `$ARGUMENTS` opens with a candidate issue reference, fetch the issue:
+
+{{issue_ref_grammar()}}
 
 ```
 Agent(subagent_type="Git"):
 "OPERATION: fetch-issue
-ISSUE: {issue number}
+ISSUE_INPUT: {issue reference}
 Return issue title, body, labels, and any linked error logs."
 ```
 
+{{issue_capture_contract()}}
+
+If the Git agent returns only a TRACEABILITY: DEGRADED line and no issue content, report that line verbatim to the user and use AskUserQuestion to request the bug description before generating any hypotheses — do not fabricate a description from the raw candidate token alone.
+
 Analyze the bug description (from arguments or issue) and identify 3-5 plausible hypotheses. Each hypothesis must be:
 - **Specific**: Points to a concrete mechanism (not "something is wrong")
 - **Testable**: Can be confirmed or disproved by reading code/logs
@@ -175,7 +181,7 @@ Ask user via AskUserQuestion: "Want me to implement this fix?"
 - **YES** → Load `devflow:patterns` and `devflow:test-driven-development` skills, implement the fix, then spawn `Agent(subagent_type="Simplify")` on changed files.
 - **NO** → Done. Report stands as documentation.
 
-{knowledge_writeback()}
+{{knowledge_writeback()}}
 
 ## Architecture