devflow-kit 3.5.0 → 3.7.0

package/dist/commands/code-review.md

@@ -28,12 +28,12 @@ Run a comprehensive code review of the current branch by spawning parallel revie
    - **Exactly one listed:** load neither the skill nor the reference — that worktree is the only candidate, and Step 0c's Git agent validates its branch
 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
+3. **If only 1 reviewable worktree**: 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
 
-#### Step 0b: Resolve the compliance lens
+#### Step 0b: Resolve the compliance lens and gate level
 
-**Produces:** COMPLIANCE_ACTIVE, COMPLIANCE_FRAMEWORKS
+**Produces:** COMPLIANCE_ACTIVE, COMPLIANCE_FRAMEWORKS, GATE_LEVEL
 
 **Resolve the settings line** once per worktree root, reusing a line this run already resolved for the same root. `{root}` is the worktree the values are for — the repository root when the run has one worktree:
 
@@ -41,16 +41,16 @@ Run a comprehensive code review of the current branch by spawning parallel revie
 node "$HOME/.devflow/scripts/resolve-settings.cjs" "{root}" 2>/dev/null; echo "exit=$?"
 ```
 
-Accept the output only when it is exactly two lines: `exit=0` last and, before it, one line of the form `TRACKER=<github|jira|linear> TRACKER_SOURCE=<project|personal|machine|default> TRACKER_WARN=<none|mismatch|invalid> SITE=<none|https://<host>> KEY=<none|<key>> REVIEW_PUBLICATION=<off|auto|full> COMPLIANCE=<off|generic|<id>[,<id>…]> MEMORY=<on|off> LEARNING=<on|off> KNOWLEDGE=<on|off>` — these fields, in this order, nothing else, where `<host>` is a lowercase dotted host name alone, `<key>` is 2–10 of `A-Z`, `0-9` and `_` starting with a letter, and each `<id>` is one of `gdpr`, `hipaa`, `pci-dss`, `soc2`, `iso-27001`, `sox`. **Anything else** (a non-zero exit, no line, extra text, or a missing, reordered or unlisted field or value) ⇒ use `TRACKER=github TRACKER_SOURCE=default TRACKER_WARN=invalid SITE=none KEY=none REVIEW_PUBLICATION=off COMPLIANCE=generic MEMORY=on LEARNING=on KNOWLEDGE=off` instead.
+Accept the output only when it is exactly two lines: `exit=0` last and, before it, one line of the form `TRACKER=<github|jira|linear> TRACKER_SOURCE=<project|personal|machine|default> TRACKER_WARN=<none|mismatch|invalid> SITE=<none|https://<host>> KEY=<none|<key>> REVIEW_PUBLICATION=<off|auto|full> COMPLIANCE=<off|generic|<id>[,<id>…]> MEMORY=<on|off> LEARNING=<on|off> KNOWLEDGE=<on|off> GATE_LEVEL=<full|standard|lean>` — these fields, in this order, nothing else, where `<host>` is a lowercase dotted host name alone, `<key>` is 2–10 of `A-Z`, `0-9` and `_` starting with a letter, and each `<id>` is one of `gdpr`, `hipaa`, `pci-dss`, `soc2`, `iso-27001`, `sox`. **Anything else** (a non-zero exit, no line, extra text, or a missing, reordered or unlisted field or value) ⇒ use `TRACKER=github TRACKER_SOURCE=default TRACKER_WARN=invalid SITE=none KEY=none REVIEW_PUBLICATION=off COMPLIANCE=generic MEMORY=on LEARNING=on KNOWLEDGE=off GATE_LEVEL=full` instead.
 
-The accepted line is the only source of these values: the script alone folds the committed `.devflow/project.json`, the personal `.devflow/config.json` and the machine manifest.
+The accepted line is the only source of these values.
 
 **Resolve the compliance lens** for each worktree root, from its settings line — the line resolved above for that root, by the settings block when this run has not yet resolved it (every framework reference is installed on every machine, so no file check decides it).
 
 **Set the compliance lens** from that 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.
 
 `COMPLIANCE_ACTIVE` is `true` unless `COMPLIANCE_FRAMEWORKS` is `off`.
-Keep each worktree's values for every downstream phase of that worktree.
+Keep each worktree's values for every downstream phase.
 
 #### Step 0b-ii: Resolve the evidence policy
 
@@ -100,7 +100,7 @@ Validate branch, commit if needed, push, create PR if needed.
 Return: branch, base_branch, branch-slug, PR#"
 ```
 
-In multi-worktree mode, spawn all pre-flight agents **in a single message** (parallel).
+In multi-worktree mode, spawn all pre-flight agents **in a single message**.
 
 **If BLOCKED:** In single-worktree mode, stop and report. In multi-worktree mode, report the failure but continue with other worktrees.
 
@@ -140,7 +140,7 @@ For each worktree, perform a single pass over timestamped directories:
 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.
-5. If `--full`: still load PRIOR_RESOLUTIONS (valuable for Review agent cross-cycle awareness).
+5. If `--full`: still load PRIOR_RESOLUTIONS.
 
 #### Step 0e-ii: Convergence Assessment
 
@@ -186,7 +186,7 @@ Note: `auto` is NOT fail-open — under `auto`, the Git agent probes the reposit
 ### Phase 1: Analyze Changed Files
 
 **Produces:** REVIEW_FOCUS_LIST, DIFF_CLASS, DIFF_FILES
-**Requires:** DIFF_RANGE, REVIEW_DIR, COMPLIANCE_ACTIVE (from Step 0b)
+**Requires:** DIFF_RANGE, REVIEW_DIR, COMPLIANCE_ACTIVE, GATE_LEVEL (from Step 0b)
 
 Per worktree, in order. Each `git` command here writes to a file and prints nothing.
 
@@ -202,7 +202,7 @@ git -C "{WORKTREE_PATH}" diff --name-only --no-renames {DIFF_RANGE} > "{REVIEW_D
 wc -l < "{REVIEW_DIR}/paths.txt"
 ```
 
-Read `paths.txt` once when the count is about 40 or fewer, and in ranges of about 40 lines (Read with offset and limit) when it is more. `--no-renames` lists a moved file under its old path and its new one, so a move cannot take a file out of its own class.
+Read `paths.txt` once when the count is about 40 or fewer, and in ranges of about 40 lines (Read with offset and limit) when it is more.
 
 Set `DIFF_CLASS` by these rules, in order; the first that decides wins:
 
@@ -219,7 +219,7 @@ Each reduced class runs only its focus set, every member reading `diff.patch`:
 - `tests-only`: testing, reliability, consistency, security
 - `lockfile-only`: dependencies, security
 
-A mixed non-code diff runs the union of the sets of the classes it holds. Language and conditional triggers inside a reduced class are suppressed: they add no focus, and Step 1.2 applies to the `code` class only.
+A mixed non-code diff runs the union of the sets of the classes it holds. Language and conditional triggers inside a reduced class are suppressed.
 
 #### Step 1.2: Choose the focuses
 
@@ -243,13 +243,27 @@ When `DIFF_CLASS` is `code`, read the file types from the paths in `paths.txt` t
 | Docs or significant code | documentation |
 | 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.
+If `COMPLIANCE_ACTIVE` AND the diff touches regulated surface (data models, auth flows, logging/observability, payments, IaC, retention): on a `code` diff, add `compliance`.
 
 **Language focus stamp.** The eight language focuses — `typescript`, `react`, `accessibility`, `ui-design`, `go`, `java`, `python`, `rust` — ship with optional plugins, and the installer stamps the ones installed on this machine onto this line, rewriting it on every install and on `uninstall --plugin`:
 
 Installed language focuses: (none)
 
-A language focus is spawned only when its file-type condition above fires AND its name appears in that stamped line. A focus missing from the line is never spawned, even when its trigger fires. The eight core focuses are unconditional and are never stamp-gated.
+A language focus is spawned only when its file-type condition above fires AND its name appears in that stamped line. A focus missing from the line is never spawned, even when its trigger fires. On a `code` diff, REVIEW_FOCUS_LIST starts with the eight core focuses. Step 1.2b may narrow them; they are never stamp-gated.
+
+#### Step 1.2b: Narrow by gate level
+
+**Produces:** REVIEW_FOCUS_LIST, GATE_LEVEL
+**Requires:** REVIEW_FOCUS_LIST, DIFF_CLASS, CHANGED_PATHS, GATE_LEVEL
+
+**Gate level.** Narrow REVIEW_FOCUS_LIST, for every class, by this worktree's `GATE_LEVEL`. `full` keeps it and reads nothing.
+
+At `standard` or `lean`, once per run, run `d="${CLAUDE_CONFIG_DIR:-}"; case "$d" in /*) ;; *) d="$HOME/.claude" ;; esac; printf '%s\n' "$d"` in Bash and Read `<that directory>/skills/devflow:agent-references/references/commands/code-review-levels.md` with the Read tool.
+
+- Apply each class's row to that class's own set, then take the union of the results. A row only removes focuses.
+- If the Read fails, or a row is missing or malformed, set `GATE_LEVEL` to `full` for every worktree of this run and say `level reference unreadable: full sets applied`.
+- Security runs at every level and in every class.
+- Compliance keeps the trigger above at every level.
 
 #### Step 1.3: Write the diff files
 
@@ -288,19 +302,19 @@ The core, database, dependencies, documentation and compliance focuses, and ever
 
 When the settings line says `LEARNING=off`, set `DECISIONS_CONTEXT` to `(none)` and skip this step, locating no ledger and reading no index.
 
-The decisions ledger belongs to the repository, not to one checkout: in a linked worktree it lives in the main worktree, and a session started in a subdirectory reads the copy at the repository root. Locate it with ONE git call, run from the start directory — `WORKTREE_PATH` if provided, otherwise cwd (`devflow:worktree-support`):
+The decisions ledger belongs to the repository, not to one checkout: a linked worktree reads the main worktree's copy, a subdirectory session the repository root's. Locate it with ONE git call, run from the start directory — `WORKTREE_PATH` if provided, otherwise cwd (`devflow:worktree-support`):
 
 ```bash
 git -C "{start}" rev-parse --path-format=absolute --show-toplevel --git-common-dir
 ```
 
-Line 1 is the checkout's toplevel, line 2 the repository's common git directory. A git older than 2.31 echoes `--path-format=absolute` back as a line of its own first. `{ledger}` is the first of these that applies:
+Line 1 is the checkout's toplevel, line 2 the common git directory. A git older than 2.31 echoes `--path-format=absolute` back as a line of its own first. `{ledger}` is the first that applies:
 
 1. **The main worktree** — line 2 without its trailing `/.git`, when the output is exactly two lines each beginning with `/`, line 2 ends in `/.git`, and the directory left once it is removed is not your home directory and contains a `.devflow/` directory.
 2. **The toplevel** — line 1, or on an older git the line after the echoed flag.
 3. **The start directory itself** — when the command failed or printed no absolute toplevel (outside a git repository).
 
-This is the rule the learning hooks apply (D-LEDGER-MAIN-WORKTREE, D-PROMPT-ROOT), so you read the index the Learning agent writes.
+This is the rule the learning hooks apply, so you read the index the Curate agent writes.
 
 **Step 1 — Read the pre-rendered index:**
 
@@ -309,13 +323,17 @@ Attempt to read `{ledger}/.devflow/learning/index.md`.
 - If the file exists and contains non-empty content: use that content as `DECISIONS_CONTEXT`.
 - If the file is absent or empty: set `DECISIONS_CONTEXT` to `(none)`.
 
-The index is one direct file read, written at render time by `render-decisions.cjs` alongside `decisions.md`/`pitfalls.md` — no `.cjs` script runs here, and the index's own footer names the files that hold each entry's full body.
+The index is one direct file read, written at render time by `render-decisions.cjs` — no `.cjs` script runs here.
+
+**Step 2 — Slice the index, then hand it on:**
 
-**Step 2 — Agents apply the decisions:**
+When `DECISIONS_CONTEXT` is not `(none)`, hand it only to the agents whose contract declares it.
 
-When `DECISIONS_CONTEXT` is not `(none)`, hand it only to the agents whose contract declares it. They follow `devflow:apply-decisions`: scan the index, identify plausibly-relevant entries, Read full entry bodies on demand, and cite verbatim IDs in their reasoning. A host that uses the index in its own thread says so in its own step.
+Hand each agent that takes `DECISIONS_CONTEXT` a slice, not the whole index: the index lines whose title, scope or area touch the files and task it works on, verbatim, led by `(slice: N of M entries — full index: <absolute index path>)` and closed by the index footer. When unsure, include the line. Siblings over one diff share ONE slice.
 
-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.
+Those agents follow `devflow:apply-decisions`. A host that uses the index in its own thread says so in its own step.
+
+This produces a compact index of active ADR/PF entries. Pass `DECISIONS_CONTEXT` to all Review agents as one shared slice, cut over the diff's files. Review agents use `devflow:apply-decisions` to Read full entry bodies on demand.
 
 ### Load Feature Knowledge
 
@@ -339,7 +357,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:**
 
@@ -370,7 +388,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 all Review agents alongside `DECISIONS_CONTEXT`.
 
@@ -379,9 +397,9 @@ Pass `FEATURE_KNOWLEDGE` to all Review agents alongside `DECISIONS_CONTEXT`.
 **Produces:** REVIEW_FOCUS_OUTPUTS
 **Requires:** DIFF_RANGE, REVIEW_DIR, TIMESTAMP, DECISIONS_CONTEXT, FEATURE_KNOWLEDGE, PR_DESCRIPTION, PRIOR_RESOLUTIONS, REVIEW_FOCUS_LIST, DIFF_CLASS, DIFF_FILES
 
-Spawn Review agents **in a single message**, for the focus set `DIFF_CLASS` selects (max 20 per worktree):
+Spawn Review agents **in a single message**, one per focus in REVIEW_FOCUS_LIST (max 20 per worktree):
 
-- `code`: the 8 core reviews on the full `diff.patch`, plus the language and conditional focuses Phase 1 added.
+- `code`: the 8 core reviews on the full `diff.patch` (lean keeps 3), plus the language and conditional focuses Phase 1 added.
 - `docs-only`, `tests-only`, `lockfile-only`: only the reduced set Phase 1 names, each reading `diff.patch`; a mixed non-code diff runs the union. No language or conditional focus is spawned, whatever its trigger.
 
 | Focus | Runs | Pattern Skill | DIFF_FILE |
@@ -407,7 +425,7 @@ Spawn Review agents **in a single message**, for the focus set `DIFF_CLASS` sele
 | documentation | conditional | devflow:documentation | diff.patch |
 | compliance | diff-driven | devflow:compliance | diff.patch |
 
-Review agent count: `code` runs 8 core, +1-12 added by Phase 1 (max 20 total per worktree); a reduced class or a mix runs 2-6.
+Review agent count: at `full`, `code` runs 8 core +1-12; `standard` runs up to 2 fewer; lean `code` runs 3-4; a reduced class or a mix runs 2-6.
 
 **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:
 
@@ -433,16 +451,16 @@ Follow devflow:apply-feature-knowledge for FEATURE_KNOWLEDGE — feature-specifi
 IMPORTANT: Write report to {worktree_path}/.devflow/docs/reviews/{branch-slug}/{timestamp}/{focus}.md using Write tool"
 ```
 
-In multi-worktree mode, process worktrees **sequentially** (one worktree at a time). Complete Phases 1-4 for each worktree before starting the next. This prevents agent overload — spawning 8-20 Review agents per worktree across multiple worktrees simultaneously overwhelms the system.
+In multi-worktree mode, process worktrees **sequentially**: complete Phases 1-4 for one worktree before starting the next, so Review spawns never pile up.
 
 ### Phase 3: Synthesis → Review Comment (Sequential)
 
 **Produces:** REVIEW_SUMMARY, PR_COMMENT
-**Requires:** REVIEW_FOCUS_OUTPUTS, REVIEW_DIR, PR_INFO
+**Requires:** REVIEW_FOCUS_OUTPUTS, REVIEW_DIR, PR_INFO, GATE_LEVEL, REVIEW_FOCUS_LIST
 
 **WAIT** for Phase 2. For each worktree, run steps 3a and 3b in sequence:
 
-**Step 3a — Synthesize agent** per worktree (wait for completion before 3b):
+**Step 3a — Synthesize agent** per worktree:
 ```
 Agent(subagent_type="Synthesize", run_in_background=false):
 "Mode: review
@@ -450,6 +468,8 @@ WORKTREE_PATH: {worktree_path}  (omit if cwd)
 REVIEW_BASE_DIR: {worktree_path}/.devflow/docs/reviews/{branch-slug}/{timestamp}
 TIMESTAMP: {timestamp}
 CYCLE_NUMBER: {cycle_number}
+GATE_LEVEL: {GATE_LEVEL}
+FOCUSES: {REVIEW_FOCUS_LIST}
 PRIOR_RESOLUTIONS: <prior-resolution-summary>{prior_resolutions}</prior-resolution-summary>
 Include Convergence Status section in review-summary.md.
 Aggregate findings, determine merge recommendation.
@@ -482,8 +502,6 @@ Per worktree, after successful completion:
    - 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.
-
 ## Architecture
 
 ```
@@ -491,29 +509,27 @@ In multi-worktree mode, report results per worktree.
 │
 ├─ Phase 0: Worktree Discovery & Pre-flight
 │  ├─ Step 0a: git worktree list → filter reviewable
-│  ├─ Step 0b: Resolve the compliance lens
+│  ├─ Step 0b: Resolve the compliance lens and gate level
 │  ├─ 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
-│  ├─ Step 0e-ii: Convergence assessment (warn if FP ratio > 70%)
+│  ├─ Step 0e-ii: Convergence assessment (warn only)
 │  └─ Step 0f: Resolve REVIEW_PUBLICATION per worktree (publication gate)
 │
 ├─ Per worktree (SEQUENTIAL — one worktree at a time):
 │  │
 │  ├─ Phase 1: Analyze changed files
 │  │  ├─ Classify the diff (paths.txt → DIFF_CLASS)
-│  │  ├─ Choose the focuses (code class: file types + the language stamp)
+│  │  ├─ Choose the focuses (code: file types + the language stamp; all: the gate level)
 │  │  └─ Write diff.patch and diff-{focus}.patch, by redirect
 │  │
-│  ├─ Phase 2: Reviews (PARALLEL within worktree)
-│  │  ├─ code: Review agents security, architecture, performance, complexity,
-│  │  │        consistency, regression, testing, reliability (diff.patch)
-│  │  ├─ code: + language (diff-{focus}.patch) and conditional Review agents
+│  ├─ Phase 2: Reviews (PARALLEL within worktree), one per REVIEW_FOCUS_LIST focus
+│  │  ├─ code: core (diff.patch), language (diff-{focus}.patch), conditional
 │  │  └─ docs-only / tests-only / lockfile-only: the reduced set (diff.patch)
 │  │
 │  ├─ Phase 3: Synthesis → Review Comment (SEQUENTIAL within worktree)
 │  │  ├─ Step 3a: Synthesize agent (mode: review, writes review-summary.md)
-│  │  └─ Step 3b: Git agent (post-review-summary, D7 marker-dedup, REVIEW_PUBLICATION)
+│  │  └─ Step 3b: Git agent (post-review-summary)
 │  │
 │  └─ Phase 4: Write .last-review-head + display results
 ```
@@ -522,44 +538,27 @@ In multi-worktree mode, report results per worktree.
 
 | Case | Handling |
 |------|----------|
-| No new commits since last review | Skip review, report: "No new commits since last review. Use --full for a full re-review." |
-| Rebase invalidates `.last-review-head` SHA | `git cat-file -t` check fails → fallback to full diff |
-| Same-minute review collision | `mkdir` fails → retry with seconds appended (`YYYY-MM-DD_HHMMSS`) |
-| Worktree in detached HEAD | Filtered out (no branch name → not reviewable) |
-| Worktree mid-rebase or mid-merge | Filtered out by status check |
-| Two worktrees on same branch | Deduplicate by branch — review once, use first worktree's path |
-| Worktree on protected branch | Filtered out (not reviewable) |
-| 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 |
+| `--full` in multi-worktree mode | Applies to all worktrees (global modifier). It sets the diff range, never the gate level |
 | 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 |
-| Docs-only diff | `docs-only`: documentation, consistency, security on `diff.patch`; no language or conditional focus |
-| Tests-only diff | `tests-only`: testing, reliability, consistency, security on `diff.patch`; no language or conditional focus |
-| Lockfile-only diff | `lockfile-only`: dependencies, security on `diff.patch` |
-| Mixed non-code diff (docs with tests, tests with a lockfile) | The union of the matching sets, on `diff.patch` |
-| A path matching no class pattern, or an empty path list | `code` (fail-safe): the 8 core focuses on the full diff |
-| A file moved across classes | `--no-renames` lists the old and the new path, so a code path makes the diff `code` |
-| Path listing above about 40 lines | The count is printed; `paths.txt` is read in ranges of about 40 lines |
+| Docs-only diff | Its Step 1.1 set, narrowed by level |
+| Tests-only diff | Its Step 1.1 set, narrowed by level |
+| Lockfile-only diff | Its Step 1.1 set, narrowed by level |
+| Mixed non-code diff | The union of the matching sets |
+| A path matching no class pattern, or an empty path list | `code` (fail-safe) |
+| A file moved across classes | `--no-renames` lists both paths, so a code path makes the diff `code` |
+| Path listing above about 40 lines | Read in ranges (Step 1.1) |
 | Language files changed, plugin not installed | The focus is absent from the stamped line: not spawned |
 | 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) — 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 `{worktree}/.devflow/docs/reviews/{branch-slug}/` contains flat `*.md` files (no timestamped subdirectories), new runs create timestamped subdirectories. Old flat files remain untouched.
+- **Gate level**: `full` runs the sets named here; the default `standard` and `lean` narrow them. `devflow gates --set full` keeps them.
 
 ## Principles
 
 1. **Orchestration only** - Command spawns agents, doesn't do git/review work itself. The exceptions are the read-only Phase 0 probes (`git worktree list`, `git -C ... branch --show-current`, `git -C ... cat-file -t`), the bounded Phase 1 path listing (a redirect into `paths.txt`, a `wc -l` count and ranged reads) and the redirect-only patch writes (`diff.patch`, `diff-{focus}.patch`). Redirect-only writes print nothing, so no diff content reaches this thread
 2. **Parallel, not background** - Multiple agents in one message, but `run_in_background=false` so phases complete before proceeding
 3. **Git agent for git work** - All git operations go through Git agent, except the exceptions named in Principle 1; redirect-only writes print nothing
-4. **Clear ownership** - Each agent owns its output completely
-5. **Honest reporting** - Display agent outputs directly
-6. **Incremental by default** - Only review new changes unless `--full` specified
-7. **Auto-discover worktrees** - One command handles all reviewable branches
+4. **Honest reporting** - Display agent outputs directly
+5. **Incremental by default** - Only review new changes unless `--full` specified

package/dist/commands/debug.md

@@ -38,9 +38,9 @@ $ARGUMENTS
 node "$HOME/.devflow/scripts/resolve-settings.cjs" "{root}" 2>/dev/null; echo "exit=$?"
 ```
 
-Accept the output only when it is exactly two lines: `exit=0` last and, before it, one line of the form `TRACKER=<github|jira|linear> TRACKER_SOURCE=<project|personal|machine|default> TRACKER_WARN=<none|mismatch|invalid> SITE=<none|https://<host>> KEY=<none|<key>> REVIEW_PUBLICATION=<off|auto|full> COMPLIANCE=<off|generic|<id>[,<id>…]> MEMORY=<on|off> LEARNING=<on|off> KNOWLEDGE=<on|off>` — these fields, in this order, nothing else, where `<host>` is a lowercase dotted host name alone, `<key>` is 2–10 of `A-Z`, `0-9` and `_` starting with a letter, and each `<id>` is one of `gdpr`, `hipaa`, `pci-dss`, `soc2`, `iso-27001`, `sox`. **Anything else** (a non-zero exit, no line, extra text, or a missing, reordered or unlisted field or value) ⇒ use `TRACKER=github TRACKER_SOURCE=default TRACKER_WARN=invalid SITE=none KEY=none REVIEW_PUBLICATION=off COMPLIANCE=generic MEMORY=on LEARNING=on KNOWLEDGE=off` instead.
+Accept the output only when it is exactly two lines: `exit=0` last and, before it, one line of the form `TRACKER=<github|jira|linear> TRACKER_SOURCE=<project|personal|machine|default> TRACKER_WARN=<none|mismatch|invalid> SITE=<none|https://<host>> KEY=<none|<key>> REVIEW_PUBLICATION=<off|auto|full> COMPLIANCE=<off|generic|<id>[,<id>…]> MEMORY=<on|off> LEARNING=<on|off> KNOWLEDGE=<on|off> GATE_LEVEL=<full|standard|lean>` — these fields, in this order, nothing else, where `<host>` is a lowercase dotted host name alone, `<key>` is 2–10 of `A-Z`, `0-9` and `_` starting with a letter, and each `<id>` is one of `gdpr`, `hipaa`, `pci-dss`, `soc2`, `iso-27001`, `sox`. **Anything else** (a non-zero exit, no line, extra text, or a missing, reordered or unlisted field or value) ⇒ use `TRACKER=github TRACKER_SOURCE=default TRACKER_WARN=invalid SITE=none KEY=none REVIEW_PUBLICATION=off COMPLIANCE=generic MEMORY=on LEARNING=on KNOWLEDGE=off GATE_LEVEL=full` instead.
 
-The accepted line is the only source of these values: the script alone folds the committed `.devflow/project.json`, the personal `.devflow/config.json` and the machine manifest.
+The accepted line is the only source of these values.
 
 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.
 
@@ -54,19 +54,19 @@ Phase 7 passes `COMPLIANCE_DIRECTIVE` to the Code agent that implements the fix,
 
 When the settings line says `LEARNING=off`, set `DECISIONS_CONTEXT` to `(none)` and skip this step, locating no ledger and reading no index.
 
-The decisions ledger belongs to the repository, not to one checkout: in a linked worktree it lives in the main worktree, and a session started in a subdirectory reads the copy at the repository root. Locate it with ONE git call, run from the start directory — `WORKTREE_PATH` if provided, otherwise cwd (`devflow:worktree-support`):
+The decisions ledger belongs to the repository, not to one checkout: a linked worktree reads the main worktree's copy, a subdirectory session the repository root's. Locate it with ONE git call, run from the start directory — `WORKTREE_PATH` if provided, otherwise cwd (`devflow:worktree-support`):
 
 ```bash
 git -C "{start}" rev-parse --path-format=absolute --show-toplevel --git-common-dir
 ```
 
-Line 1 is the checkout's toplevel, line 2 the repository's common git directory. A git older than 2.31 echoes `--path-format=absolute` back as a line of its own first. `{ledger}` is the first of these that applies:
+Line 1 is the checkout's toplevel, line 2 the common git directory. A git older than 2.31 echoes `--path-format=absolute` back as a line of its own first. `{ledger}` is the first that applies:
 
 1. **The main worktree** — line 2 without its trailing `/.git`, when the output is exactly two lines each beginning with `/`, line 2 ends in `/.git`, and the directory left once it is removed is not your home directory and contains a `.devflow/` directory.
 2. **The toplevel** — line 1, or on an older git the line after the echoed flag.
 3. **The start directory itself** — when the command failed or printed no absolute toplevel (outside a git repository).
 
-This is the rule the learning hooks apply (D-LEDGER-MAIN-WORKTREE, D-PROMPT-ROOT), so you read the index the Learning agent writes.
+This is the rule the learning hooks apply, so you read the index the Curate agent writes.
 
 **Step 1 — Read the pre-rendered index:**
 
@@ -75,11 +75,15 @@ Attempt to read `{ledger}/.devflow/learning/index.md`.
 - If the file exists and contains non-empty content: use that content as `DECISIONS_CONTEXT`.
 - If the file is absent or empty: set `DECISIONS_CONTEXT` to `(none)`.
 
-The index is one direct file read, written at render time by `render-decisions.cjs` alongside `decisions.md`/`pitfalls.md` — no `.cjs` script runs here, and the index's own footer names the files that hold each entry's full body.
+The index is one direct file read, written at render time by `render-decisions.cjs` — no `.cjs` script runs here.
 
-**Step 2 — Agents apply the decisions:**
+**Step 2 — Slice the index, then hand it on:**
 
-When `DECISIONS_CONTEXT` is not `(none)`, hand it only to the agents whose contract declares it. They follow `devflow:apply-decisions`: scan the index, identify plausibly-relevant entries, Read full entry bodies on demand, and cite verbatim IDs in their reasoning. A host that uses the index in its own thread says so in its own step.
+When `DECISIONS_CONTEXT` is not `(none)`, hand it only to the agents whose contract declares it.
+
+Hand each agent that takes `DECISIONS_CONTEXT` a slice, not the whole index: the index lines whose title, scope or area touch the files and task it works on, verbatim, led by `(slice: N of M entries — full index: <absolute index path>)` and closed by the index footer. When unsure, include the line. Siblings over one diff share ONE slice.
+
+Those agents follow `devflow:apply-decisions`. A host that uses the index in its own thread says so in its own step.
 
 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.
 
@@ -234,7 +238,7 @@ Produce the final report:
 
 Ask user via AskUserQuestion: "Want me to implement this fix?"
 
-- **YES** → implement the fix through the Code agent, never in this thread, then spawn `Agent(subagent_type="Simplify")` on the changed files. /debug loads no feature knowledge, so the fix gets none:
+- **YES** → implement the fix through the Code agent, never in this thread, then spawn `Agent(subagent_type="Polish")` on the changed files. /debug loads no feature knowledge, so the fix gets none:
 
   ```
   Agent(subagent_type="Code"):
@@ -282,21 +286,17 @@ FEATURE_SLUG: {slug derived from primary changed directory, kebab-case}
 FEATURE_NAME: {human-readable name}
 DIRECTORIES: {list of primary directories touched by this workflow}
 FILES_CHANGED: {list of files changed}
-DECISIONS_CONTEXT: {DECISIONS_CONTEXT if available, else (none)}
+DECISIONS_CONTEXT: {the slice for these directories, else (none)}
 
 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:**
@@ -328,7 +328,7 @@ When the Knowledge agent reports `KB_COMMIT: skipped (detached HEAD)`, the files
 ├─ Phase 6: Root cause report with confidence level
 │
 ├─ Phase 7: Offer Fix
-│  └─ AskUserQuestion → Code agent (fix) + Simplify agent, or done
+│  └─ AskUserQuestion → Code agent (fix) + Polish agent, or done
 │
 └─ Feature Knowledge Write-Back (Conditional)
    └─ Knowledge agent (if investigation surfaced durable cross-cutting knowledge)