devflow-kit 3.3.0 → 3.5.0

package/dist/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.
@@ -85,10 +86,22 @@ Set `TARGET_DIR` to the selected review or bug-analysis directory path, and `TAR
 
 #### Step 0d: Load Project Decisions
 
-**Produces:** DECISIONS_CONTEXT, FEATURE_KNOWLEDGE, EVIDENCE_POLICY, ISSUE_REQUIRED, APPLY_CONVENTIONS, REQUIRE_NON_AUTHOR_APPROVAL, REVIEW_PUBLICATION, RESOLUTION_TS
+**Produces:** DECISIONS_CONTEXT, FEATURE_KNOWLEDGE, FEATURE_KNOWLEDGE_RULES, EVIDENCE_POLICY, ISSUE_REQUIRED, APPLY_CONVENTIONS, REQUIRE_NON_AUTHOR_APPROVAL, REVIEW_PUBLICATION, RESOLUTION_TS
+
+**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:
+
+```bash
+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.
+
+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.
 
 ### Load DECISIONS_CONTEXT
 
+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`):
 
 ```bash
@@ -112,9 +125,9 @@ Attempt to read `{ledger}/.devflow/learning/index.md`.
 
 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.
 
-**Step 2 — Apply decisions using `devflow:apply-decisions`:**
+**Step 2 — Agents apply the decisions:**
 
-When `DECISIONS_CONTEXT` is not `(none)`, follow `devflow:apply-decisions` to scan the index, identify plausibly-relevant entries, Read full entry bodies on demand, and cite verbatim IDs in downstream agent prompts and reasoning.
+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.
 
 This produces a compact index of active ADR/PF entries written at render time — Deprecated/Superseded entries are already stripped. Pass `DECISIONS_CONTEXT` to the Triage agent in Phase 2 and to Code agents in Phase 4.
 
@@ -146,22 +159,32 @@ Glob `{worktree}/.devflow/features/*/KNOWLEDGE.md`. For each file found, read on
 
 Match the current task area and description against each index line (or frontmatter `description` + `directories` on fallback). Select entries whose documented area overlaps the current task. This is a relevance judgment — prefer specificity over breadth.
 
-**Step 4 — Read selected KBs:**
+**Step 4 — Read each selected KB's Rules:**
+
+For each selected entry, `{kb}` is `{worktree}/.devflow/features/{slug}/KNOWLEDGE.md`:
 
-For each selected entry, read `{worktree}/.devflow/features/{slug}/KNOWLEDGE.md` in full. When the KB content contradicts the current code you observe, **trust the code** — the code is the freshness mechanism; the KB may lag behind.
+1. List its `##` headings with line numbers through Bash: `command grep -n '^## ' "{kb}"`. This only locates sections; the text of a KB comes from the Read view alone.
+2. Read the `## Rules` range (its line to the next heading) with the Read tool, using `offset` and `limit`, and choose the one to three bullets most relevant to the current task. The choice is yours, made per KB.
+3. If the KB has no `## Rules` section, choose one to three entries from its `## Anti-Patterns` or `## Gotchas` range the same way, and label them by that section's name instead of an ID.
 
-**Step 5 — Set FEATURE_KNOWLEDGE:**
+When a KB contradicts the code you observe, **trust the code** — the code is the freshness mechanism; the KB may lag behind. A missing Rules section, a missing heading list and `(none)` are legitimate states, not errors.
 
-Concatenate the selected KNOWLEDGE.md files under slug headers:
+**Step 5 — Set FEATURE_KNOWLEDGE and FEATURE_KNOWLEDGE_RULES:**
+
+Write one block per selected KB. Paste each bullet verbatim from the Read view, never from a shell view. The path is relative to the checkout root; an agent resolves it under `WORKTREE_PATH` when one is provided.
 
 ```
 --- Feature knowledge: {slug} ---
-{full KNOWLEDGE.md content}
+KB: .devflow/features/{slug}/KNOWLEDGE.md
+Rules:
+- **KB-AP-2** {bullet text, verbatim}
+- **KB-INV-1** {bullet text, verbatim}
+Headings: L5 Rules · L40 Overview · L62 Anti-Patterns · L118 Key Files
 ```
 
-If no KBs exist, no KBs are relevant, or `.devflow/features/` is absent, set `FEATURE_KNOWLEDGE` to `(none)`.
+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 file reads — no `.cjs` script.** After resolving `{worktree}`, this step is 1 index read (or N frontmatter reads on fallback), bounded by KB count.
+**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.
 
 Pass `FEATURE_KNOWLEDGE` to the Triage agent in Phase 2.
 
@@ -176,23 +199,19 @@ Accept the output only when it is exactly two lines: `exit=0` last and, before i
 Set `EVIDENCE_POLICY`, `ISSUE_REQUIRED`, `APPLY_CONVENTIONS` and `REQUIRE_NON_AUTHOR_APPROVAL` from the accepted line. Pass agents only the three mechanism inputs, never `EVIDENCE_POLICY`. Report `Evidence policy: {EVIDENCE_POLICY} (source: {SOURCE})`, plus any `WARN` tokens as advisory, once in the final report.
 Reuse this result for every worktree.
 
-**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:
-
-```bash
-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.
-
-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.
-
-**Resolve `REVIEW_PUBLICATION` per worktree:** take `REVIEW_PUBLICATION` from that worktree's settings line, with `{root}` the worktree's root — multi-worktree repos may resolve different values per worktree. The line already caps the personal choice at the team's (D-PUBLICATION-CEILING), so it is `off`, `auto` or `full`, and `off` when the line was unresolvable.
+**Resolve `REVIEW_PUBLICATION` per worktree:** take `REVIEW_PUBLICATION` from that worktree's settings line — the line resolved above for `{root}`, the worktree's root, by the settings block when this run has not yet resolved that root; multi-worktree repos may resolve different values per worktree. The line already caps the personal choice at the team's (D-PUBLICATION-CEILING), so it is `off`, `auto` or `full`, and `off` when the line was unresolvable.
 
 **Evidence stub:** only when `EVIDENCE_POLICY` is `required`, a resolved `off` becomes `stub`, so a counts-only record still reaches the PR. `stub` is never a config value: the settings line never carries it.
 
 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 Code-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
@@ -307,11 +326,10 @@ 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)
 DECISIONS_CONTEXT: {decisions_context}
 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."
@@ -374,17 +392,17 @@ 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 Code-fix agent with fix context:
    ```
-   Agent(subagent_type="Code"):
+   Agent(subagent_type="Code-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}"
+   DECISIONS_CONTEXT: {decisions_context}
+   {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).
@@ -394,7 +412,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 Code-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
 ```
@@ -432,7 +450,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="Code-fix")` whose prompt opens with `OPERATION: ci-fix`, with `COMPLIANCE_DIRECTIVE` (when it is not empty), `CI_FAILURES`, `DECISIONS_CONTEXT` and `PUSH: false`; `CI_FAILURES` holds the failing-check names from the line and nothing else, because the Code-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 -->
 
@@ -642,17 +660,7 @@ git -C "{start}" rev-parse --show-toplevel
 
 and use its one-line output. If the command fails (outside a git repository), `{worktree}` is the start directory itself. All paths below are relative to `{worktree}`.
 
-**Step 1 — Check the opt-out gate, with `{root}` = `{worktree}`:**
-
-**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:
-
-```bash
-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.
-
-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.
+**Step 1 — Check the opt-out gate, with `{root}` = `{worktree}`:** take the settings line resolved above for that root, resolving it with the settings block when this run has not yet.
 
 If the settings line says `KNOWLEDGE=off`, skip write-back entirely. The machine switch (`devflow knowledge --disable`), the repository and the personal settings can each turn knowledge off, and none can turn it back on (D-FEATURES-NARROW-ONLY). The fail-closed line says `KNOWLEDGE=off` too, so an unresolvable line skips write-back.
 
@@ -682,7 +690,7 @@ Write the knowledge base to:
 Then update the index cache by performing a read-modify-write on:
   {worktree}/.devflow/features/index.md
 
-Index line format: `- **{slug}** — {areas} — {Use-when description}`
+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.
 
@@ -726,10 +734,10 @@ When the Knowledge agent reports `KB_COMMIT: skipped (detached HEAD)`, the files
 │
 ├─ Phase 6: Simplify [Simplify agent]
 │
-├─ Phase 7: Verification Gate [Validate agent, haiku] + push + Code agent validation-fix loop ≤2
+├─ Phase 7: Verification Gate [Validate agent, haiku] + push + Code-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)
+│  └─ push, then ci-wait.cjs (inline, one wait ≤ 570 s) → Code-fix 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

package/dist/commands/self-review.md

@@ -14,7 +14,7 @@ Run Simplify agent and Scrutinize agent sequentially on changed files for post-i
 
 ### Phase 0: Context Gathering
 
-**Produces:** FILES_CHANGED, TASK_DESCRIPTION, DECISIONS_CONTEXT, FEATURE_KNOWLEDGE, HEAD_BEFORE
+**Produces:** FILES_CHANGED, TASK_DESCRIPTION, DECISIONS_CONTEXT, FEATURE_KNOWLEDGE, FEATURE_KNOWLEDGE_RULES, HEAD_BEFORE
 
 Detect changed files and build context:
 
@@ -23,8 +23,21 @@ Detect changed files and build context:
 3. If no changes found, report "No changes to review" and exit
 4. Build TASK_DESCRIPTION from recent commit messages or branch name
 5. Record `HEAD_BEFORE` (`git rev-parse HEAD`) now, before Simplify runs — Phase 3 compares against it
+
+**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:
+
+```bash
+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.
+
+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.
+
 ### Load DECISIONS_CONTEXT
 
+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`):
 
 ```bash
@@ -48,9 +61,9 @@ Attempt to read `{ledger}/.devflow/learning/index.md`.
 
 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.
 
-**Step 2 — Apply decisions using `devflow:apply-decisions`:**
+**Step 2 — Agents apply the decisions:**
 
-When `DECISIONS_CONTEXT` is not `(none)`, follow `devflow:apply-decisions` to scan the index, identify plausibly-relevant entries, Read full entry bodies on demand, and cite verbatim IDs in downstream agent prompts and reasoning.
+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.
 
 Pass `DECISIONS_CONTEXT` to Scrutinize agent — the compact index lists active ADR/PF entries; Scrutinize agent uses `devflow:apply-decisions` to Read full entry bodies on demand. Known pitfalls help identify reintroduced issues, prior decisions help validate architectural consistency. (Simplify agent does not consume decisions — it operates at code-shape level and Scrutinize agent runs after to catch any architectural drift.)
 
@@ -82,26 +95,36 @@ Glob `{worktree}/.devflow/features/*/KNOWLEDGE.md`. For each file found, read on
 
 Match the current task area and description against each index line (or frontmatter `description` + `directories` on fallback). Select entries whose documented area overlaps the current task. This is a relevance judgment — prefer specificity over breadth.
 
-**Step 4 — Read selected KBs:**
+**Step 4 — Read each selected KB's Rules:**
 
-For each selected entry, read `{worktree}/.devflow/features/{slug}/KNOWLEDGE.md` in full. When the KB content contradicts the current code you observe, **trust the code** — the code is the freshness mechanism; the KB may lag behind.
+For each selected entry, `{kb}` is `{worktree}/.devflow/features/{slug}/KNOWLEDGE.md`:
 
-**Step 5 — Set FEATURE_KNOWLEDGE:**
+1. List its `##` headings with line numbers through Bash: `command grep -n '^## ' "{kb}"`. This only locates sections; the text of a KB comes from the Read view alone.
+2. Read the `## Rules` range (its line to the next heading) with the Read tool, using `offset` and `limit`, and choose the one to three bullets most relevant to the current task. The choice is yours, made per KB.
+3. If the KB has no `## Rules` section, choose one to three entries from its `## Anti-Patterns` or `## Gotchas` range the same way, and label them by that section's name instead of an ID.
 
-Concatenate the selected KNOWLEDGE.md files under slug headers:
+When a KB contradicts the code you observe, **trust the code** — the code is the freshness mechanism; the KB may lag behind. A missing Rules section, a missing heading list and `(none)` are legitimate states, not errors.
+
+**Step 5 — Set FEATURE_KNOWLEDGE and FEATURE_KNOWLEDGE_RULES:**
+
+Write one block per selected KB. Paste each bullet verbatim from the Read view, never from a shell view. The path is relative to the checkout root; an agent resolves it under `WORKTREE_PATH` when one is provided.
 
 ```
 --- Feature knowledge: {slug} ---
-{full KNOWLEDGE.md content}
+KB: .devflow/features/{slug}/KNOWLEDGE.md
+Rules:
+- **KB-AP-2** {bullet text, verbatim}
+- **KB-INV-1** {bullet text, verbatim}
+Headings: L5 Rules · L40 Overview · L62 Anti-Patterns · L118 Key Files
 ```
 
-If no KBs exist, no KBs are relevant, or `.devflow/features/` is absent, set `FEATURE_KNOWLEDGE` to `(none)`.
+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 file reads — no `.cjs` script.** After resolving `{worktree}`, this step is 1 index read (or N frontmatter reads on fallback), bounded by KB count.
+**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.
 
-Pass `FEATURE_KNOWLEDGE` to Scrutinize agent.
+Pass `FEATURE_KNOWLEDGE_RULES` to Scrutinize agent.
 
-**Extract:** FILES_CHANGED (list), TASK_DESCRIPTION (string), DECISIONS_CONTEXT (string, optional), FEATURE_KNOWLEDGE (string, optional), HEAD_BEFORE (40-hex SHA)
+**Extract:** FILES_CHANGED (list), TASK_DESCRIPTION (string), DECISIONS_CONTEXT (string, optional), FEATURE_KNOWLEDGE (string, optional), FEATURE_KNOWLEDGE_RULES (string, optional), HEAD_BEFORE (40-hex SHA)
 
 ### Phase 1: Simplify agent (Code Refinement)
 
@@ -129,7 +152,7 @@ Agent(subagent_type="Scrutinize", run_in_background=false):
 "TASK_DESCRIPTION: {task_description}
 FILES_CHANGED: {files_changed}
 DECISIONS_CONTEXT: {decisions_context}
-FEATURE_KNOWLEDGE: {feature_knowledge}
+FEATURE_KNOWLEDGE: {feature_knowledge_rules}
 Evaluate against 9-pillar framework. Fix P0/P1 issues. Return structured report.
 Follow devflow:apply-decisions to scan DECISIONS_CONTEXT and Read full ADR/PF bodies on demand. Skip if (none).
 Follow devflow:apply-feature-knowledge for FEATURE_KNOWLEDGE. Skip if (none)."
@@ -195,17 +218,7 @@ git -C "{start}" rev-parse --show-toplevel
 
 and use its one-line output. If the command fails (outside a git repository), `{worktree}` is the start directory itself. All paths below are relative to `{worktree}`.
 
-**Step 1 — Check the opt-out gate, with `{root}` = `{worktree}`:**
-
-**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:
-
-```bash
-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.
-
-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.
+**Step 1 — Check the opt-out gate, with `{root}` = `{worktree}`:** take the settings line resolved above for that root, resolving it with the settings block when this run has not yet.
 
 If the settings line says `KNOWLEDGE=off`, skip write-back entirely. The machine switch (`devflow knowledge --disable`), the repository and the personal settings can each turn knowledge off, and none can turn it back on (D-FEATURES-NARROW-ONLY). The fail-closed line says `KNOWLEDGE=off` too, so an unresolvable line skips write-back.
 
@@ -235,7 +248,7 @@ Write the knowledge base to:
 Then update the index cache by performing a read-modify-write on:
   {worktree}/.devflow/features/index.md
 
-Index line format: `- **{slug}** — {areas} — {Use-when description}`
+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.
 

package/dist/core/agent-frontmatter.js

@@ -231,4 +231,105 @@ export function rewriteAgentFrontmatter(content, opts) {
     const changed = newContent !== content;
     return Ok({ content: newContent, changed });
 }
+const WHOLE_SERVER_PREFIX = 'mcp__';
+/** A server name as it appears in a whole-server entry: the charset Claude Code keeps, no `__`. */
+const WHOLE_SERVER_NAME_RE = /^[A-Za-z0-9_-]{1,64}$/;
+/**
+ * True when `tool` is a whole-server allowlist entry: `mcp__` and a server name of
+ * 1-64 characters from `[A-Za-z0-9_-]` with no `__` (D-WHOLE-SERVER-ENTRY).
+ */
+export function isWholeServerTool(tool) {
+    if (!tool.startsWith(WHOLE_SERVER_PREFIX))
+        return false;
+    const name = tool.slice(WHOLE_SERVER_PREFIX.length);
+    return WHOLE_SERVER_NAME_RE.test(name) && !name.includes('__');
+}
+/** The single-line inline form `tools: ["A", "B"]`, within a frontmatter body. */
+const INLINE_TOOLS_RE = /^tools:[ \t]*\[([^\r\n]*)\][ \t]*(?=\r?$)/m;
+function toolItems(inner) {
+    return inner.split(',').filter(item => item.trim() !== '');
+}
+function unquoteTool(item) {
+    return item.trim().replace(/^(["'])(.*)\1$/, '$2');
+}
+/**
+ * Replace the whole-server entries of the first frontmatter block's inline `tools:` line
+ * with `extraTools`, and touch nothing else.
+ *
+ * Idempotent: stamping the same list twice yields the same bytes, and stamping a new list
+ * replaces the previous one rather than adding to it. Every other entry of the line keeps
+ * its original text, and every other byte of the file (other keys, the body, CRLF or LF)
+ * is untouched. An empty `extraTools` removes the stamp.
+ *
+ * Rejects, rather than repairs: an entry that is not a whole-server entry (`invalid-tool`;
+ * it would otherwise reach the frontmatter as free text), a file with no inline
+ * `tools: [...]` line (`no-tools-line`; a block-list `tools:` is not edited) and a file
+ * with no well-formed frontmatter.
+ *
+ * Pure function — no I/O.
+ */
+export function stampAgentTools(content, extraTools) {
+    for (const tool of extraTools) {
+        if (!isWholeServerTool(tool))
+            return Err('invalid-tool');
+    }
+    const parts = parseFrontmatter(content);
+    if (!parts.ok)
+        return Err(parts.error);
+    const { fmBody, openDelim, closeDelim, afterClose, eol } = parts.value;
+    const match = INLINE_TOOLS_RE.exec(fmBody);
+    if (!match)
+        return Err('no-tools-line');
+    const rawItems = toolItems(match[1]);
+    const kept = rawItems.filter(item => !isWholeServerTool(unquoteTool(item)));
+    const stamped = [...new Set(extraTools)].map(tool => `"${tool}"`);
+    // Nothing to remove and nothing to add: the line, whatever its spacing, is already right.
+    if (kept.length === rawItems.length && stamped.length === 0)
+        return Ok({ content, changed: false });
+    // The kept entries keep their own text; only the edges lose the padding that no longer
+    // borders a neighbour, so the appended entries land after `, ` and the line stays one shape.
+    const keptText = kept
+        .map((item, i) => {
+        const lead = i === 0 ? item.trimStart() : item;
+        return i === kept.length - 1 ? lead.trimEnd() : lead;
+    })
+        .join(',');
+    const inner = [keptText, stamped.join(', ')].filter(text => text !== '').join(', ');
+    const line = `tools: [${inner}]`;
+    const newBody = fmBody.slice(0, match.index) + line + fmBody.slice(match.index + match[0].length);
+    const newContent = openDelim + newBody + eol + closeDelim + afterClose;
+    return Ok({ content: newContent, changed: newContent !== content });
+}
+/**
+ * The whole-server entries of the first frontmatter block's inline `tools:` line, in
+ * order. Ok([]) when the line carries none; an error when there is no line to read.
+ * Pure function — no I/O.
+ */
+export function readStampedTools(content) {
+    const parts = parseFrontmatter(content);
+    if (!parts.ok)
+        return Err(parts.error);
+    const match = INLINE_TOOLS_RE.exec(parts.value.fmBody);
+    if (!match)
+        return Err('no-tools-line');
+    return Ok(toolItems(match[1]).map(unquoteTool).filter(isWholeServerTool));
+}
+/**
+ * The text a converge installs for an agent: the variant `source` wearing the whole-server
+ * entries the installed copy carries. The stamp is applied at install and by
+ * `devflow tracker --servers`, never by a converge, so a converge only CARRIES it. Without
+ * the carry, switching an agent between prompt variants would drop its stamp and compare
+ * unequal to the installed copy on every run.
+ *
+ * `source` is returned unchanged when there is nothing safe to carry: either side has no
+ * well-formed inline `tools:` line, or the installed copy carries no entries.
+ * Pure function — no I/O.
+ */
+export function carryStampedTools(source, installed) {
+    const carried = readStampedTools(installed);
+    if (!carried.ok || carried.value.length === 0)
+        return source;
+    const stamped = stampAgentTools(source, carried.value);
+    return stamped.ok ? stamped.value.content : source;
+}
 //# sourceMappingURL=agent-frontmatter.js.map

package/dist/core/agent-models.js

@@ -599,6 +599,49 @@ export async function loadShippedAgentDefaults(dirs = agentSourceDirs(), opts) {
     }
     return defaults;
 }
+// ---------------------------------------------------------------------------
+// carryAgentOverrides — the frontmatter a converge keeps
+// ---------------------------------------------------------------------------
+/**
+ * D-AGENT-OVERRIDE-CARRY: the text a prompt converge installs for an agent is the
+ * variant `source` wearing the installed copy's `model:` and `effort:`.
+ *
+ * Those two lines are the only frontmatter keys reapplyAgentMapping manages, and
+ * `devflow agents` and the proxy put their values there. A converge that installed
+ * the bare variant would write every overridden agent back to its shipped model
+ * and effort and leave reapplyAgentMapping to restore it: a window with default
+ * models, and a no-op converge that rewrites everything. Carrying the two lines
+ * keeps that window shut, so a copy already holding the right variant and its
+ * overrides compares byte-equal and is not touched.
+ *
+ * The carry is an optimisation, never the authority: reapplyAgentMapping reads
+ * agent-models.json and decides what the installed frontmatter must say. It
+ * agrees with the carry whenever the installed copy was last written by it, and
+ * where they disagree the later reapply wins. Both go through
+ * rewriteAgentFrontmatter, so the model-name charset guard, the first-block scope
+ * and the EOL handling are the ones the reapply uses.
+ *
+ * `source` is returned unchanged when there is nothing safe to carry: either side
+ * has no well-formed frontmatter, the installed copy has no model, its model
+ * fails the model-name charset or its effort is not an EFFORT_LEVELS member. An
+ * installed copy with no `effort:` line carries no effort (a mapping effort of
+ * `inherit` yields exactly that).
+ *
+ * Pure function — no I/O.
+ */
+export function carryAgentOverrides(source, installed) {
+    const model = readFrontmatterModel(installed);
+    const effort = readFrontmatterEffort(installed);
+    if (!model.ok || !effort.ok || model.value === '')
+        return source;
+    if (effort.value !== '' && !isEffortLevel(effort.value))
+        return source;
+    const carried = rewriteAgentFrontmatter(source, {
+        model: model.value,
+        effort: effort.value === '' ? null : effort.value,
+    });
+    return carried.ok ? carried.value.content : source;
+}
 /**
  * Idempotent convergence function: walk every installed agent file and
  * rewrite frontmatter model/effort to match the effective mapping.

package/dist/core/assets.js

@@ -1,16 +1,21 @@
 import { join } from 'path';
 import { getPackageRoot } from './paths.js';
 import { SKILL_REFS_OUTPUT_DIR } from './mds-variants.js';
+import { LEARNING_OFF_OUTPUT_DIR } from './learning-variants.js';
 /**
  * Flat skills source directory: src/assets/skills/{name}/
  * All plugins' skills live here directly (no per-plugin subdirectory).
+ *
+ * @param root - Package root to resolve against. Injectable so a caller working
+ *   on a temp tree (the learning converge) reads the skill source from the same
+ *   root as the rest of its sources.
  */
-export function skillsDir() {
-    return join(getPackageRoot(), 'src', 'assets', 'skills');
+export function skillsDir(root = getPackageRoot()) {
+    return join(root, 'src', 'assets', 'skills');
 }
 /**
- * Flat agents source directory: src/assets/agents/{name}.md
- * All plugins' agents live here directly.
+ * Flat agents source directory: src/assets/agents/{name}.md, or {name}.mds for a
+ * generator host. All plugins' agents live here directly.
  *
  * @param root - Package root to resolve against. Injectable so a caller working
  *   on a temp tree (the test harness) reads the layout from here rather than
@@ -35,17 +40,49 @@ export function scriptsDir() {
 }
 /**
  * Compiled commands directory: dist/commands/
- * Single lookup directory for installed commands — .mds compile output
- * plus verbatim hand-authored .md copies.
+ * Single lookup directory for installed commands: one compiled file per `.mds`
+ * command host in src/assets/commands/. A host that carries a learning arm also
+ * has a learning-off variant (see learningOffDir).
  */
 export function commandsDir() {
     return join(getPackageRoot(), 'dist', 'commands');
 }
+/**
+ * Learning-off variant directory: dist/learning-off/{commands,agents}/
+ *
+ * Holds the learning-off variant of each prompt that carries a learning arm
+ * (D-LEARNING-VARIANTS), and only those. Absent until the build has run, so every
+ * reader tolerates its absence.
+ *
+ * The spelling comes from LEARNING_OFF_OUTPUT_DIR in learning-variants.ts, the
+ * build's own destination, rather than being retyped here.
+ *
+ * @param kind - Which prompt kind's variants.
+ * @param root - Package root to resolve against (see agentsDir).
+ */
+export function learningOffDir(kind, root = getPackageRoot()) {
+    return join(root, ...LEARNING_OFF_OUTPUT_DIR.split('/'), kind);
+}
+/**
+ * Command source directories, MOST-PREFERRED FIRST.
+ *
+ * D-LEARNING-VARIANT-INSTALL: with learning off the learning-off variant comes
+ * first, so a host with an arm installs its off variant and a host with none falls
+ * through to the one compiled file; with learning on the order is the normal
+ * single-directory lookup.
+ *
+ * @param learning - The machine's settled learning switch.
+ * @param root - Package root to resolve against (see agentsDir).
+ */
+export function commandSourceDirs(learning, root = getPackageRoot()) {
+    const normal = join(root, 'dist', 'commands');
+    return learning ? [normal] : [learningOffDir('commands', root), normal];
+}
 /**
  * Compiled agents directory: dist/agents/{name}.md
  *
- * Output of the .mds generator hosts. The directory is absent until at least
- * one generator host exists, so every reader must tolerate its absence.
+ * Output of the .mds generator hosts. The directory is absent until the build has
+ * run, so every reader must tolerate its absence.
  *
  * @param root - Package root to resolve against (see agentsDir).
  */
@@ -87,9 +124,17 @@ export function compiledSkillRefsDir(root = getPackageRoot()) {
  * The non-empty tuple makes an empty list a compile error at every call site:
  * an empty list would survive a `??` default and resolve to nothing.
  *
+ * D-LEARNING-VARIANT-INSTALL: `learning: false` puts dist/learning-off/agents first,
+ * for the installer and the converge only. The default (learning on) is the order
+ * every other reader wants: the shipped defaults (model, effort) are the same in
+ * both variants, so loadShippedAgentDefaults and the test harness keep reading the
+ * learning-on tree.
+ *
  * @param root - Package root to resolve against (see agentsDir).
+ * @param learning - The machine's settled learning switch; on by default.
  */
-export function agentSourceDirs(root = getPackageRoot()) {
-    return [compiledAgentsDir(root), agentsDir(root)];
+export function agentSourceDirs(root = getPackageRoot(), learning = true) {
+    const normal = [compiledAgentsDir(root), agentsDir(root)];
+    return learning ? normal : [learningOffDir('agents', root), ...normal];
 }
 //# sourceMappingURL=assets.js.map