devflow-kit 3.4.0 → 3.6.0

package/dist/learning-off/commands/plan.md

@@ -165,7 +165,7 @@ If `index.md` exists and contains at least one entry line, use it for relevance
 
 **Step 2 — Fallback: glob frontmatter (if `index.md` is absent or empty):**
 
-Glob `{worktree}/.devflow/features/*/KNOWLEDGE.md`. For each file found, read only its YAML frontmatter block (between the opening and closing `---` delimiters). The frontmatter fields `name`, `description`, and `directories` are the authoritative relevance surface — `index.md` is only a cache.
+Glob `{worktree}/.devflow/features/*/KNOWLEDGE.md`. For each file found, read only its YAML frontmatter block (between the opening and closing `---` delimiters).
 
 **Step 3 — Pick relevant KBs:**
 
@@ -196,7 +196,7 @@ Headings: L5 Rules · L40 Overview · L62 Anti-Patterns · L118 Key Files
 
 A KB with no Rules section labels its entries `Rules ({section name}):` and gives them no ID. `FEATURE_KNOWLEDGE` is these blocks; `FEATURE_KNOWLEDGE_RULES` is the same blocks without the `Headings:` line. Both come from this one selection, and each spawn names the variable its recipient takes. If no KBs exist, no KBs are relevant, or `.devflow/features/` is absent, set both to `(none)`.
 
-**One git call, then direct reads — no `.cjs` script.** After resolving `{worktree}`, this step is 1 index read (or N frontmatter reads on fallback), plus one heading listing and one Rules read per selected KB, bounded by KB count.
+**One git call, then direct reads — no `.cjs` script.**
 
 Pass `FEATURE_KNOWLEDGE` to Explore and Design agents.
 
@@ -205,7 +205,7 @@ Pass `FEATURE_KNOWLEDGE` to Explore and Design agents.
 **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 |
 |-------|-------------|------|
@@ -266,15 +266,20 @@ Each Design agent receives:
 - Focus: (their assigned focus from table)
 - Exploration synthesis from Phase 4
 - Skim agent context 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}
 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}
@@ -336,7 +341,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 |
 |-------|-------------|------|
@@ -444,8 +449,9 @@ Use AskUserQuestion to present:
 
 User can:
 - **Accept** — proceed to output phases
-- **Revise** — re-run phases 10-12 with new constraints (loop back, no limit on revisions)
+- **Revise** — when fewer than 2 revisions have run, re-run phases 10-12 with new constraints. Budget: at most 2 revisions, counted over the whole run
 - **Cancel** — stop gracefully, no artifact written
+- **Restart /plan with these constraints** — offered in place of Revise once 2 revisions have run: stop gracefully, write no artifact, and print the constraints given so far for a fresh `/plan` run
 
 **MANDATORY**: Do not write design artifact until Gate 2 is confirmed.
 
@@ -460,8 +466,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`
 
@@ -590,59 +598,33 @@ Display completion summary:
 │
 ├─ Block 1: Requirements Discovery
 │  ├─ Phase 1: GATE 0 - Requirements Discovery ⛔ MANDATORY
+│  │  ├─ Git agent (fetch-issue / fetch-issues-batch) - issue mode only
 │  │  └─ AskUserQuestion: Validate interpretation
 │  ├─ Phase 2: Orient
-│  │  └─ Skim agent (codebase context)
 │  ├─ Phase 3: Explore Requirements (PARALLEL)
-│  │  ├─ Explore: User perspective
-│  │  ├─ Explore: Similar features
-│  │  ├─ Explore: Constraints
-│  │  └─ Explore: Failure modes
 │  └─ Phase 4: Synthesize Exploration
-│     └─ Synthesize agent (mode: exploration)
 │
 ├─ Block 2: Gap Analysis
 │  ├─ Phase 5: Gap Analysis (PARALLEL)
-│  │  ├─ Design agent: completeness
-│  │  ├─ Design agent: architecture
-│  │  ├─ Design agent: security
-│  │  ├─ Design agent: performance
-│  │  ├─ Design agent: compliance (only when COMPLIANCE_ACTIVE)
-│  │  ├─ Design agent: consistency (multi-issue only)
-│  │  └─ Design agent: dependencies (multi-issue only)
 │  └─ Phase 6: Synthesize Gap Analysis
-│     └─ Synthesize agent (mode: design)
 │
 ├─ Block 3: Scope Approval
 │  └─ Phase 7: GATE 1 - Validate Scope + Gaps ⛔ MANDATORY
-│     └─ AskUserQuestion: Confirm scope and gap resolutions
 │
 ├─ Block 4: Implementation Design
 │  ├─ Phase 8: Explore Implementation (PARALLEL)
-│  │  ├─ Explore: Architecture
-│  │  ├─ Explore: Integration
-│  │  ├─ Explore: Reusable code
-│  │  └─ Explore: Edge cases
 │  ├─ Phase 9: Synthesize Implementation Exploration
-│  │  └─ Synthesize agent (mode: exploration)
 │  ├─ Phase 10: Plan Implementation (PARALLEL)
-│  │  ├─ Plan: Implementation steps
-│  │  ├─ Plan: Testing strategy
-│  │  └─ Plan: Execution strategy
 │  └─ Phase 11: Synthesize Planning
-│     └─ Synthesize agent (mode: planning)
 │
 ├─ Block 5: Design Review + Approval
 │  ├─ Phase 12: Design Review
-│  │  └─ Design agent (mode: design-review)
 │  └─ Phase 13: GATE 2 - Confirm Plan + Design Review ⛔ MANDATORY
-│     └─ AskUserQuestion: Final plan approval
+│     └─ Revise ≤ 2 → back to Phase 10; after 2: Accept / Cancel / Restart /plan
 │
 ├─ Block 6: Output
 │  └─ Phase 14: Output
-│     ├─ Store design artifact ({worktree}/.devflow/docs/design/)
-│     ├─ Create tracker issue (optional)
-│     └─ Report summary + next step
+│     └─ Git agent (ensure-traceable-issue) - create or enrich tracker issue (optional)
 │
 ```
 
@@ -659,6 +641,6 @@ Display completion summary:
 ## Error Handling
 
 - If any agent fails, report the phase, agent type, and error
-- If user selects "Revise" at Gate 2, loop back to Phase 10 with user's constraints
+- If user selects "Revise" at Gate 2 and fewer than 2 revisions have run, loop back to Phase 10 with user's constraints; after the second revision Gate 2 offers Accept, Cancel or "Restart /plan with these constraints" only
 - If user selects "Cancel" at any gate, stop gracefully without writing artifact
 - If `{worktree}/.devflow/docs/design/` does not exist, create it in Phase 14

package/dist/learning-off/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)
@@ -76,7 +74,7 @@ If `index.md` exists and contains at least one entry line, use it for relevance
 
 **Step 2 — Fallback: glob frontmatter (if `index.md` is absent or empty):**
 
-Glob `{worktree}/.devflow/features/*/KNOWLEDGE.md`. For each file found, read only its YAML frontmatter block (between the opening and closing `---` delimiters). The frontmatter fields `name`, `description`, and `directories` are the authoritative relevance surface — `index.md` is only a cache.
+Glob `{worktree}/.devflow/features/*/KNOWLEDGE.md`. For each file found, read only its YAML frontmatter block (between the opening and closing `---` delimiters).
 
 **Step 3 — Pick relevant KBs:**
 
@@ -107,7 +105,7 @@ Headings: L5 Rules · L40 Overview · L62 Anti-Patterns · L118 Key Files
 
 A KB with no Rules section labels its entries `Rules ({section name}):` and gives them no ID. `FEATURE_KNOWLEDGE` is these blocks; `FEATURE_KNOWLEDGE_RULES` is the same blocks without the `Headings:` line. Both come from this one selection, and each spawn names the variable its recipient takes. If no KBs exist, no KBs are relevant, or `.devflow/features/` is absent, set both to `(none)`.
 
-**One git call, then direct reads — no `.cjs` script.** After resolving `{worktree}`, this step is 1 index read (or N frontmatter reads on fallback), plus one heading listing and one Rules read per selected KB, bounded by KB count.
+**One git call, then direct reads — no `.cjs` script.**
 
 Pass `FEATURE_KNOWLEDGE` only to agents whose contract declares it; the Validate and Git agents this command spawns do not.
 
@@ -203,10 +201,12 @@ Arm 1 or 2 ⇒ ask once, via AskUserQuestion: "{u} untraced commits{, coverage u
 ## 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.
+- A blank line separates the last bullet from the `Exempt` line, so Markdown renders that line as its own paragraph and not inside the bullet. Compose the block with that blank line every time.
 - `@<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.
@@ -228,6 +228,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

package/dist/learning-off/commands/research.md

@@ -63,7 +63,7 @@ If `index.md` exists and contains at least one entry line, use it for relevance
 
 **Step 2 — Fallback: glob frontmatter (if `index.md` is absent or empty):**
 
-Glob `{worktree}/.devflow/features/*/KNOWLEDGE.md`. For each file found, read only its YAML frontmatter block (between the opening and closing `---` delimiters). The frontmatter fields `name`, `description`, and `directories` are the authoritative relevance surface — `index.md` is only a cache.
+Glob `{worktree}/.devflow/features/*/KNOWLEDGE.md`. For each file found, read only its YAML frontmatter block (between the opening and closing `---` delimiters).
 
 **Step 3 — Pick relevant KBs:**
 
@@ -94,7 +94,7 @@ Headings: L5 Rules · L40 Overview · L62 Anti-Patterns · L118 Key Files
 
 A KB with no Rules section labels its entries `Rules ({section name}):` and gives them no ID. `FEATURE_KNOWLEDGE` is these blocks; `FEATURE_KNOWLEDGE_RULES` is the same blocks without the `Headings:` line. Both come from this one selection, and each spawn names the variable its recipient takes. If no KBs exist, no KBs are relevant, or `.devflow/features/` is absent, set both to `(none)`.
 
-**One git call, then direct reads — no `.cjs` script.** After resolving `{worktree}`, this step is 1 index read (or N frontmatter reads on fallback), plus one heading listing and one Rules read per selected KB, bounded by KB count.
+**One git call, then direct reads — no `.cjs` script.**
 
 Use `FEATURE_KNOWLEDGE` **locally** for research framing. Pass to each Research agent in Phase 4.
 
@@ -102,6 +102,10 @@ Use `FEATURE_KNOWLEDGE` **locally** for research framing. Pass to each Research
 
 **Produces:** RESEARCH_PLAN
 
+**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 rules below.
+
+Name the research directory by the skill's rules, once: `{topic-slug}` is its topic slug of the research question and `{YYYY-MM-DD_HHMM}` is the local time. When `{worktree}/.devflow/docs/research/{topic-slug}/{YYYY-MM-DD_HHMM}` already exists (a same-minute collision), the timestamp takes seconds instead, `YYYY-MM-DD_HHMMSS`. Every path of this run uses that one directory.
+
 Analyze the research question to infer research types needed (min 2, max 5). For each type:
 - `RESEARCH_TYPE`: `codebase | external | market | competitor | technology`
 - `RESEARCH_QUESTION`: Focused sub-question for this type
@@ -109,8 +113,6 @@ Analyze the research question to infer research types needed (min 2, max 5). For
 
 **Tool availability check**: If WebSearch/WebFetch are unavailable, restrict to `codebase` type only.
 
-Generate topic slug from the research question (kebab-case, lowercase, no articles).
-
 ### Phase 3: Orient (Conditional)
 
 **Produces:** ORIENT_OUTPUT
@@ -141,12 +143,17 @@ Each Research agent writes findings to disk at OUTPUT_PATH.
 **Produces:** RESEARCH_SUMMARY
 **Requires:** RESEARCH_OUTPUTS
 
-Spawn `Agent(subagent_type="Synthesize")` in `research` mode:
-- Reads Research agent outputs from RESEARCH_OUTPUTS paths
-- Merges findings with trust-aware aggregation
-- Writes `research-summary.md` to the same timestamped directory
+Spawn `Agent(subagent_type="Synthesize")` in `research` mode. It reads the Research agent outputs from the `RESEARCH_OUTPUTS` paths, merges them with trust-aware aggregation, and writes `research-summary.md` into `RESEARCH_BASE_DIR` — the one directory of this run, which only this spawn names:
 
-Output path: `{worktree}/.devflow/docs/research/{topic-slug}/{timestamp}/research-summary.md`
+```
+Agent(subagent_type="Synthesize", run_in_background=false):
+"Mode: research
+WORKTREE_PATH: {WORKTREE_PATH}  (omit if none was provided)
+RESEARCH_OUTPUTS: {the OUTPUT_PATH of every Research agent that wrote its file}
+RESEARCH_BASE_DIR: {worktree}/.devflow/docs/research/{topic-slug}/{YYYY-MM-DD_HHMM}
+Merge findings with trust-aware aggregation.
+Output: {worktree}/.devflow/docs/research/{topic-slug}/{YYYY-MM-DD_HHMM}/research-summary.md"
+```
 
 ### Phase 6: Present
 

package/dist/learning-off/commands/resolve.md

@@ -22,9 +22,10 @@ Process issues from code review reports: triage every issue through the blast-ra
 
 **Produces:** WORKTREES
 
-1. **Discover resolvable 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
-   - Invoke the `devflow:worktree-support` skill, then Read its `references/discovery.md` from the skill's base directory for the full 7-step algorithm; the canonical protected branch list stays in the skill
+1. **Discover resolvable worktrees**:
+   - Run `git worktree list --porcelain` and count the worktrees it lists
+   - **More than one listed:** Invoke the `devflow:worktree-support` skill, then Read its `references/discovery.md` from the skill's base directory for the full 7-step algorithm; the canonical protected branch list stays in the skill. Parse the list, filter (skip protected/detached/mid-rebase), dedup by branch, sort by recent commit
+   - **Exactly one listed:** load neither the skill nor the reference — that worktree is the only candidate, and Step 0b's Git agent validates its branch
    - Additional filter: must have unresolved reviews (latest review directory has no `resolution-summary.md`)
 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.
@@ -119,7 +120,7 @@ If `index.md` exists and contains at least one entry line, use it for relevance
 
 **Step 2 — Fallback: glob frontmatter (if `index.md` is absent or empty):**
 
-Glob `{worktree}/.devflow/features/*/KNOWLEDGE.md`. For each file found, read only its YAML frontmatter block (between the opening and closing `---` delimiters). The frontmatter fields `name`, `description`, and `directories` are the authoritative relevance surface — `index.md` is only a cache.
+Glob `{worktree}/.devflow/features/*/KNOWLEDGE.md`. For each file found, read only its YAML frontmatter block (between the opening and closing `---` delimiters).
 
 **Step 3 — Pick relevant KBs:**
 
@@ -150,7 +151,7 @@ Headings: L5 Rules · L40 Overview · L62 Anti-Patterns · L118 Key Files
 
 A KB with no Rules section labels its entries `Rules ({section name}):` and gives them no ID. `FEATURE_KNOWLEDGE` is these blocks; `FEATURE_KNOWLEDGE_RULES` is the same blocks without the `Headings:` line. Both come from this one selection, and each spawn names the variable its recipient takes. If no KBs exist, no KBs are relevant, or `.devflow/features/` is absent, set both to `(none)`.
 
-**One git call, then direct reads — no `.cjs` script.** After resolving `{worktree}`, this step is 1 index read (or N frontmatter reads on fallback), plus one heading listing and one Rules read per selected KB, bounded by KB count.
+**One git call, then direct reads — no `.cjs` script.**
 
 Pass `FEATURE_KNOWLEDGE` to the Triage agent in Phase 2.
 
@@ -172,6 +173,12 @@ Reuse this result for every worktree.
 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.
 Resolve this per worktree — unlike the evidence policy above, the settings line is per worktree root. 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.
+
+Set it per worktree, from that worktree's lens, and pass that worktree's `COMPLIANCE_DIRECTIVE` to each of its Code and Fix spawns, on a line of its own.
+
 **Mint `RESOLUTION_TS` once per run:** `date -u +%Y-%m-%dT%H:%M:%SZ`. Every worktree reuses it — the resolution comment's dedup marker is searched per PR, so one run key keeps a retry of this run deduplicated while the next /resolve on the same PR posts. Phase 5 writes it as the summary's `**Date**:` and Phase 9b-2 passes it, so the local file and the posted marker agree.
 
 ### Phase 1: Parse Issues
@@ -282,10 +289,9 @@ TASK_ID: resolve-{batch-id}
 ISSUES: {fix_now_issues_in_batch}
 SCOPE: {risk_tier_per_issue}
 PUSH: false
-CREATE_PR: false
 WORKTREE_PATH: {worktree_path}  (omit if cwd)
 FEATURE_KNOWLEDGE: {feature_knowledge}
-COMPLIANCE_FRAMEWORKS: {COMPLIANCE_FRAMEWORKS}
+{COMPLIANCE_DIRECTIVE}
 Fix only the listed pre-classified FIX_NOW issues. Do not re-litigate dispositions.
 Same-file issues → one commit. Include ## Verification block in report.
 Regression fix without failing-then-passing regression test → BLOCKED."
@@ -302,7 +308,7 @@ Collect from each Code agent:
 **Produces:** RESOLUTION_FILE (early write for compaction safety)
 **Requires:** TRIAGE_RESULTS, CODE_AGENT_RESULTS, TARGET_DIR, TARGET_DIR_REL, BRANCH_INFO, RESOLUTION_TS
 
-**Immediately write `resolution-summary.md`** to `{TARGET_DIR}` using the Write tool. Do this now — not in Phase 9 — while results are fresh in context. This ensures the record is persisted even if later phases (Simplify, Verification Gate, CI gate, Tech Debt) trigger context compaction.
+**Immediately write `resolution-summary.md`** to `{TARGET_DIR}` using the Write tool. Do this now — not in Phase 9 — while results are fresh in context. This ensures the record is persisted even if later phases (Polish, Verification Gate, CI gate, Tech Debt) trigger context compaction.
 
 Set `Tracked` for FIX_SEPARATE and TECH_DEBT items to `(pending)` — to be backfilled after Phase 9 manage-debt (or `TRACEABILITY: DEGRADED ({reason})` if manage-debt degrades).
 
@@ -310,19 +316,19 @@ DUPLICATE issues are listed **only** in `## Duplicates` — never in `## Fixed I
 
 Use the template from the Output Artifact section below.
 
-### Phase 6: Simplify
+### Phase 6: Polish
 
-**Produces:** SIMPLIFICATION_RESULT
+**Produces:** POLISH_RESULT
 **Requires:** CODE_AGENT_RESULTS
 
-If any fixes were made, spawn Simplify agent to refine the changed code:
+If any fixes were made, spawn Polish agent to refine the changed code:
 
 ```
-Agent(subagent_type="Simplify", run_in_background=false):
+Agent(subagent_type="Polish", run_in_background=false):
 "TASK_DESCRIPTION: Issue resolution fixes
 WORKTREE_PATH: {worktree_path}  (omit if cwd)
 FILES_CHANGED: {list of files modified by Code agents}
-Simplify and refine the fixes for clarity and consistency
+Polish and refine the fixes for clarity and consistency
 Commit any improvements with a conventional-commit message."
 ```
 
@@ -348,17 +354,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 Fix agent with fix context:
    ```
-   Agent(subagent_type="Code"):
+   Agent(subagent_type="Fix"):
    "OPERATION: validation-fix
    TASK_ID: resolve-{batch-id}-valfix-{count}
    VALIDATION_FAILURES: {parsed failures from Validate agent}
    SCOPE: Fix only the listed failures, no other changes
    PUSH: false
-   CREATE_PR: false
    WORKTREE_PATH: {worktree_path}  (omit if cwd)
-   COMPLIANCE_FRAMEWORKS: {COMPLIANCE_FRAMEWORKS}"
+   {COMPLIANCE_DIRECTIVE}"
    ```
    - Loop back to re-validate
 4. If `validation_retry_count > 2`: set VERIFICATION_STATUS = FAILED and exit the validation loop — record a blocking callout in the `## Verification` section (never a silent pass).
@@ -368,7 +373,7 @@ Run build, typecheck, lint, test. Report pass/fail with failure details."
 Record `## Verification` outcome in resolution-summary.md (runs unconditionally after the validation loop exits):
 - Rewrite the `## Verification` section with | Command | Result | table + `Final gate: PASS | FAILED after N attempts`
 
-Push all commits to remote once (Code agents and validation-fix Code agents ran with PUSH: false — runs whether the gate PASSED or FAILED, so the branch is always visible before Phase 9 or CI runs):
+Push all commits to remote once (Code and Fix agents ran with PUSH: false — runs whether the gate PASSED or FAILED, so the branch is always visible before Phase 9 or CI runs):
 ```bash
 git -C {worktree} push
 ```
@@ -406,7 +411,7 @@ Phase 7 has pushed already, so this is a no-op unless the head moved since. `exi
 3. **If NO_PR or NO_CI** → skip: "No PR/CI configured, skipping CI validation." Proceed to next phase.
 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` 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="Fix")` whose prompt opens with `OPERATION: ci-fix`, with `COMPLIANCE_DIRECTIVE` (when it is not empty), `CI_FAILURES` and `PUSH: false`; `CI_FAILURES` holds the failing-check names from the line and nothing else, because the 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, per worktree. When one is spent, report the current status and proceed.
 <!-- /PATTERN: ci-status-gate -->
 
@@ -516,19 +521,13 @@ Capture the Git agent's `**Publication**:` and `**Status**:` lines as `PR_COMMEN
 
 **Step 9b-3: Refresh the test-plan evidence**
 
-Run this step only when Step 9b-0 ran — the head moved — and its `EVIDENCE` line did not read `total:0` with `exceptions:none` (nothing to record); otherwise record `EVIDENCE_REFRESH` as `SKIPPED ({reason})`. Spawn Git agent:
+Run this step only when Step 9b-0 ran — the head moved — and its `EVIDENCE` line did not read `total:0` with `exceptions:none` (nothing to record); otherwise record `EVIDENCE_REFRESH` as `SKIPPED ({reason})`. Run the script inline — it is the whole `update-pr-evidence` operation, with no Git agent spawn — through the Bash tool with `timeout: 180000`:
 
-```
-Agent(subagent_type="Git"):
-"OPERATION: update-pr-evidence
-PR_NUMBER: {pr_number}
-EVIDENCE_FILE: {TARGET_DIR_REL}/evidence.md
-REVIEW_PUBLICATION: {9b-2's publication mode}
-WORKTREE_PATH: {worktree_path}  (omit if cwd)
-Refresh the PR's test-plan block and post its evidence comment."
+```bash
+cd {worktree} && node "$HOME/.devflow/scripts/verify-evidence.cjs" publish --pr {pr_number} --evidence "{TARGET_DIR_REL}/evidence.md" --publication {9b-2's publication mode}; echo "exit=$?"
 ```
 
-Omit the `EVIDENCE_FILE` line when Step 9b-0 appended no claim. `REVIEW_PUBLICATION` is the mode 9b-2 reported on its `**Publication**:` line — `FULL…` → `full`, `STUB…` → `stub`, `OFF…` → `off` — else `{REVIEW_PUBLICATION}` as resolved in Step 0d. Capture its `EVIDENCE` line and its `**Body**:` / `**Comment**:` line, or its `TRACEABILITY: DEGRADED ({reason})` line, as `EVIDENCE_REFRESH`. It never blocks.
+Drop the `--evidence` pair when Step 9b-0 appended no claim. Run it only when `TARGET_DIR_REL` matches `^[A-Za-z0-9._/-]+$` — it carries the branch name, which a fork author picks — and `{pr_number}` is digits only; treat any other value as a failed run. The publication value is the mode 9b-2 reported on its `**Publication**:` line — `FULL…` → `full`, `STUB…` → `stub`, `OFF…` → `off` — else `{REVIEW_PUBLICATION}` as resolved in Step 0d. Capture its stdout as `EVIDENCE_REFRESH`: the `## PR Evidence` block's `EVIDENCE` line and its `**Body**:` / `**Comment**:` line, with any `TRACEABILITY: DEGRADED ({reason})` lines after them (exit 0), or the one line `TRACEABILITY: DEGRADED (evidence unavailable)` (exit 2). Empty stdout or any other exit is `TRACEABILITY: DEGRADED (evidence unavailable)`. It never blocks.
 
 ### Phase 9c: Merge Readiness (Report-only)
 
@@ -537,19 +536,17 @@ Omit the `EVIDENCE_FILE` line when Step 9b-0 appended no claim. `REVIEW_PUBLICAT
 
 Run this phase only when `REQUIRE_NON_AUTHOR_APPROVAL` is `true`; otherwise skip it and report it as SKIPPED.
 
-Spawn Git agent:
+Run the script inline — it is the whole `check-merge-readiness` operation, with no Git agent spawn — through the Bash tool with `timeout: 180000`:
 
-```
-Agent(subagent_type="Git"):
-"OPERATION: check-merge-readiness
-PR_NUMBER: {pr_number}
-REQUIRE_NON_AUTHOR_APPROVAL: {REQUIRE_NON_AUTHOR_APPROVAL}
-WORKTREE_PATH: {worktree_path}  (omit if cwd)"
+```bash
+cd {worktree} && node "$HOME/.devflow/scripts/verify-evidence.cjs" readiness --pr {pr_number} --require-non-author-approval true; echo "exit=$?"
 ```
 
+Pass `--require-non-author-approval true`: `REQUIRE_NON_AUTHOR_APPROVAL` is `true` here, or this phase would not run. `{pr_number}` is digits only. Its stdout is the `## Merge Readiness` block (exit 0), or the same block with `**Status**: DEGRADED ({reason})` and a `TRACEABILITY: DEGRADED ({reason})` line after it (exit 2); empty stdout or any other exit is `TRACEABILITY: DEGRADED (readiness unavailable)`.
+
 Include merge readiness verdict (READY / NOT_READY / DEGRADED) and its `- Test plan:` detail line in Phase 10 report. Never block on this result — report-only.
 
-If Git agent returns `TRACEABILITY: DEGRADED`: warn, proceed to Phase 10.
+If the script prints a `TRACEABILITY: DEGRADED` line: warn, proceed to Phase 10.
 
 ### Phase 10: Report
 
@@ -642,16 +639,12 @@ FILES_CHANGED: {list of files changed}
 Write the knowledge base to:
   {worktree}/.devflow/features/{slug}/KNOWLEDGE.md
 
-Then update the index cache by performing a read-modify-write on:
+Then update the index cache:
   {worktree}/.devflow/features/index.md
 
 Index line format: `- **{slug}** — {areas} — {Use-when description}` — at most 300 characters, the description at most 220; reword a longer one, never cut it.
 
-If the line for this slug already exists in index.md, replace it. If it does not exist, append it. If index.md does not exist, create it with just this line.
-
-The frontmatter in KNOWLEDGE.md is the source of truth — index.md is only a cache. Write the two files directly — no intermediate result JSON files, no external scripts.
-
-After writing, commit the two files to the current worktree branch yourself by running git via your Bash tool (do not use a script). Stage ONLY .devflow/features/index.md and .devflow/features/{slug}/KNOWLEDGE.md, then commit just those paths with a docs(knowledge): message. Do NOT push, do NOT force, do NOT stage anything else. Follow your Commit Protocol — it is non-blocking, so if any git step fails, report KB_COMMIT and finish normally."
+Then commit the two files as your Commit Protocol directs."
 ```
 
 **Step 4 — Surface an uncommitted knowledge base:**
@@ -666,44 +659,24 @@ When the Knowledge agent reports `KB_COMMIT: skipped (detached HEAD)`, the files
 /resolve (orchestrator - spawns agents only)
 │
 ├─ Phase 0: Worktree Discovery & Pre-flight
-│  ├─ Step 0a: git worktree list → filter resolvable
-│  ├─ Step 0b: Git agent (validate-branch) per worktree [parallel] ← + DIFF_FILES
-│  ├─ Step 0c: Target latest review directory per worktree
-│  └─ Step 0d: Load project context → EVIDENCE_POLICY + REVIEW_PUBLICATION
-│
 ├─ Phase 1: Parse issues from TARGET_DIR + extract confidence %
-│
 ├─ Phase 1b: Fetch external threads (evidence policy required)
-│  └─ Git agent (fetch-review-threads) → THREAD_MAP
-│
 ├─ Phase 2: Global Triage [Triage agent, opus, single agent]
-│  └─ ALL issues → verdict ledger by disposition (incl. DUPLICATE with duplicate_of)
-│
 ├─ Phase 3: Batch FIX_NOW issues (skip if empty; DUPLICATE issues never dispatched)
-│  └─ same-file sequential, distinct-file parallel, max 5/batch
-│
 ├─ Phase 4: Fix [Code agent × N, OPERATION: issue-fix, PUSH: false]
-│  └─ Returns Verification block per batch
-│
 ├─ Phase 5: Write resolution-summary.md (compaction safety; Tracked = "(pending)" or "(pending — TRACEABILITY: DEGRADED)" if manage-debt degrades)
-│
-├─ Phase 6: Simplify [Simplify agent]
-│
-├─ Phase 7: Verification Gate [Validate agent, haiku] + push + Code agent validation-fix loop ≤2
-│
+├─ Phase 6: Polish [Polish agent]
+├─ Phase 7: Verification Gate [Validate agent, haiku] + push + Fix agent validation-fix loop ≤2
 ├─ Phase 8: CI Status Gate (conditional — skipped if no fixes or verification FAILED)
-│  └─ push, then ci-wait.cjs (inline, one wait ≤ 570 s) → Code agent on FAILING (3 waits + 2 fixes per worktree)
-│
 ├─ Phase 9: Git agent (manage-debt) — FIX_SEPARATE + TECH_DEBT → backfill Tracked={ISSUE_REF} (or TRACEABILITY: DEGRADED on failure)
-│  SEQUENTIAL across worktrees
 │
 ├─ Phase 9b: Thread resolution + resolution comment
 │  ├─ Step 9b-0: verify-evidence.cjs --stale-out → ≤1 Test agent on the stale TPs (wrapped) — only after this run's push
 │  ├─ Step 9b-1: Git agent (resolve-review-threads) — evidence policy required
 │  ├─ Step 9b-2: Git agent (post-resolution-summary, REVIEW_PUBLICATION) — always-on
-│  └─ Step 9b-3: Git agent (update-pr-evidence) — only when the head moved
+│  └─ Step 9b-3: verify-evidence.cjs publish (inline, no Git spawn) — only when the head moved
 │
-├─ Phase 9c: Git agent (check-merge-readiness) — non-author approval required, report-only
+├─ Phase 9c: verify-evidence.cjs readiness (inline, no Git spawn) — non-author approval required, report-only
 │
 └─ Phase 10: Display results (resolution-summary.md written in Phase 5)
 ```
@@ -717,21 +690,11 @@ When the Knowledge agent reports `KB_COMMIT: skipped (detached HEAD)`, the files
 | Fix attempt fails | Revert changes, mark BLOCKED, continue others |
 | Issue dependencies | Sequential chain, skip dependents if predecessor blocked |
 | No actionable issues | Report "No issues to resolve" |
-| Incomplete review directory (no review-summary.md) | Skip — resolve only targets complete reviews |
 | Latest review already resolved | Check bug-analysis fallback (Step 0c-5b); if also absent, skip worktree and suggest `/code-review` or `/bug-analysis` |
-| Legacy flat layout (no subdirectories) | Read flat *.md files directly (backwards compatible) |
 | `--review {timestamp}` in multi-worktree mode | Not supported — use `--path` + `--review` to target specific worktree + review |
-| Worktree pre-flight fails | Report failure, continue with other worktrees |
-| Empty FIX_NOW list | Skip Phases 3-4/6-8; still write full summary + run manage-debt if FIX_SEPARATE/TECH_DEBT exist |
-| ESCALATED security issues | Surfaced in ## Escalations + display callout; never routed to manage-debt |
-| DUPLICATE verdict without duplicate_of, or chained to another DUPLICATE | Treated as Triage failure — same retry-then-abort as a vanished id |
-| DUPLICATE issues in THREAD_MAP | Map ext-{N} to primary's verdict/verification status for thread reply |
-| Verification Gate FAILED after 2 attempts | Recorded as FAILED in ## Verification + blocking callout; CI gate skipped; proceed to Phase 9 (manage-debt) then Phase 10 (display) |
 | gh/GitHub absent | manage-debt degrades (`TRACEABILITY: DEGRADED ({reason})`); Tracked stays `(pending — TRACEABILITY: DEGRADED ({reason}))` — recorded, not dropped |
 | `EVIDENCE_POLICY` is `standard` | Phases 1b and 9b-step-1 are skipped; post-resolution-summary (Phase 9b step 2) still runs if a PR is known |
 | `REQUIRE_NON_AUTHOR_APPROVAL` is `false` | Phase 9c is skipped and reported as SKIPPED |
-| THREAD_MAP empty or DEGRADED | Phase 9b-1 skipped; resolution comment (Phase 9b-2) still posted if PR known |
-| No PR exists for post-resolution-summary | Git agent returns TRACEABILITY: DEGRADED; resolution-summary.md already on disk — not a blocker |
 | Public repo (`auto` mode) | Git agent probes visibility, posts counts-only STUB comment; full resolution report stays local |
 | `reviewPublication: off` | Git agent skips posting the resolution comment (OFF) — except that, only when `EVIDENCE_POLICY` is `required`, Step 0d passes `stub` and a counts-only STUB comment posts |
 | Fork PR this run cannot push to (no maintainer edits, no push access of its own) | validate-branch emits `TRACEABILITY: DEGRADED (cannot push to fork)` → `fork_no_push`: Phase 7 skips the push, Phase 8 is skipped, 9b-1 records FIXED threads as DEGRADED instead of citing unpushed commits; 9b-2 still posts the resolution comment; the head did not move, so 9b-0 and 9b-3 are skipped |
@@ -742,14 +705,8 @@ When the Knowledge agent reports `KB_COMMIT: skipped (detached HEAD)`, the files
 
 1. **Orchestration only** - Command spawns agents, doesn't do git/resolve work itself
 2. **No agent grades its own homework** - Triage agent validates, Code agents fix, Validate agent verifies
-3. **Global triage first** - Single Triage agent sees all issues for cross-issue consistency; no issue may vanish
-4. **Git agent for git work** - All git operations go through Git agent
-5. **Parallel execution** - Distinct-file Code agent batches run in parallel; same-file batches sequential
-6. **Honest reporting** - Verification failure is recorded and displayed, never silenced
-7. **Complete tracking** - Every issue gets exactly one verdict in the ledger
-8. **Latest review by default** - Only process the most recent complete review
-9. **Auto-discover worktrees** - One command handles all resolvable branches
-10. **Traceability-aware** - Policy-gated ops (thread fetch/resolve, merge readiness) are skipped cleanly when the evidence policy does not ask for them; resolution comment (Phase 9b-2) is always-on; test-plan evidence is re-verified (≤1 Test agent) and refreshed only when this run moved the head (Steps 9b-0, 9b-3)
+3. **Git agent for git work** - All git operations go through Git agent; the CI wait, the evidence refresh and the merge-readiness check are inline scripts (plumbing, no model work)
+4. **Traceability-aware** - Policy-gated ops (thread fetch/resolve, merge readiness) are skipped cleanly when the evidence policy does not ask for them; resolution comment (Phase 9b-2) is always-on; test-plan evidence is re-verified (≤1 Test agent) and refreshed only when this run moved the head (Steps 9b-0, 9b-3)
 
 ## Output Artifact