devflow-kit 3.4.0 → 3.5.0

package/dist/commands/research.md

@@ -78,9 +78,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.
 
 Use `DECISIONS_CONTEXT` locally when framing research — prior decisions and pitfalls suggest areas to investigate. Follow `devflow:apply-decisions` to Read full entry bodies on demand. Pass `DECISIONS_CONTEXT` to each Research agent in Phase 4 so their findings can account for relevant decisions.
 
@@ -145,6 +145,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
@@ -152,8 +156,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
@@ -185,12 +187,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/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.
@@ -124,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.
 
@@ -205,6 +206,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 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
@@ -319,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."
@@ -386,18 +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)
    DECISIONS_CONTEXT: {decisions_context}
-   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).
@@ -407,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
 ```
@@ -445,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`, `DECISIONS_CONTEXT` 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 -->
 
@@ -729,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

@@ -61,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.)
 

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/compliance-compose.js

@@ -172,13 +172,15 @@ function collectMissingFragmentWarnings(fnName, activeFrameworks, fragments, omi
  *
  * Every framework reference is installed on every machine
  * (D-COMPLIANCE-INSTALL-ALWAYS), so file presence no longer says which
- * frameworks apply. The caller hands the agent `COMPLIANCE_FRAMEWORKS` — the
- * `COMPLIANCE` field of the settings line, which folds this machine's selection
- * with the repository's `.devflow/project.json` — and those ids alone are in force.
+ * frameworks apply. The command names the ids in the agent's prompt
+ * (D-COMPLIANCE-INJECT: the compliance directive) — the `COMPLIANCE` field of the
+ * settings line, which folds this machine's selection with the repository's
+ * `.devflow/project.json` — and those ids alone are in force. No agent takes a
+ * named lens input, so the stamp names the prompt, not a variable.
  */
 const RUNTIME_SELECTION_LINES = [
     'Every `references/{id}.md` is installed, so presence decides nothing: the ids you were given',
-    "(`COMPLIANCE_FRAMEWORKS`, this machine's plus the repository's) are the frameworks in force.",
+    "(named in your prompt; this machine's plus the repository's) are the frameworks in force.",
     'Load `references/{id}.md` for each given id and no other; `none` means generic controls only.',
     'Apply generic controls always.',
     '',

package/dist/core/feature-switch.js

@@ -106,6 +106,27 @@ async function readRawManifest(devflowDir) {
 export async function readMachineFeature(devflowDir, feature) {
     return isMachineFeatureOn(await readRawManifest(devflowDir), feature);
 }
+/**
+ * Whether a RAW parsed manifest has an opt-in `feature` switched on. Pure.
+ *
+ * D-BEHAVIOR-OPT-IN: only an explicit boolean `true` is on. A missing key, a
+ * non-boolean value, a manifest without a `features` record and anything that is not an
+ * object all read as OFF — fail-closed, the mirror of {@link isMachineFeatureOn}. Like
+ * that reader it is deliberately not built on readManifest(): a read-only status must
+ * not heal-write, and a manifest missing a required field is still a manifest here.
+ */
+export function isOptInFeatureOn(rawManifest, feature) {
+    if (!isJsonObject(rawManifest) || !isJsonObject(rawManifest.features))
+        return false;
+    return rawManifest.features[feature] === true;
+}
+/**
+ * Read an opt-in machine switch from `<devflowDir>/manifest.json`. Read-only (no heal
+ * write); an absent, unreadable or malformed manifest reads as OFF.
+ */
+export async function readOptInFeature(devflowDir, feature) {
+    return isOptInFeatureOn(await readRawManifest(devflowDir), feature);
+}
 /**
  * Write the machine-wide switch to `<devflowDir>/manifest.json` (atomic
  * temp + rename). Refuses with `not-installed` when there is no manifest to
@@ -115,8 +136,8 @@ export async function readMachineFeature(devflowDir, feature) {
  * D-NOOP-TOGGLE: a toggle to the value the manifest already records writes
  * nothing. The only bytes such a write could change are `updatedAt`, and that
  * field means "the manifest's content last changed", so a no-op must not move
- * it. This is the one write point of `devflow memory|learning|knowledge
- * --enable/--disable`, so the rule holds for all three at once.
+ * it. This is the one write point of `devflow memory|learning|knowledge|behavior
+ * --enable/--disable`, so the rule holds for all four at once.
  */
 export async function writeMachineFeature(devflowDir, feature, enabled) {
     const raw = await readRawManifest(devflowDir);

package/dist/core/flags.js

@@ -88,6 +88,45 @@ export const FLAG_REGISTRY = [
         recommended: true,
         defaultValue: true,
     },
+    {
+        // D-SUBAGENT-CACHE-5M: subagents write their prompt cache with the 5-minute TTL
+        // while the main session keeps the 1-hour TTL of `prompt-caching-1h` (untouched).
+        //
+        // Why: the wave-4 token audit (2026-10-10) found 99.998% of subagent cache writes
+        // are 1-hour writes, yet fewer than 0.1% of subagent requests idle longer than
+        // 5 minutes - a subagent finishes or is resumed long before a 5-minute entry
+        // lapses, so the 1-hour premium buys nothing. Modelled effect of 5m: -8.9% on
+        // subagent cache-equivalent cost, -7.7% on total.
+        //
+        // Mechanism (VENDOR BEHAVIOUR, probed 2026-10-11 on Claude Code 2.1.296 in a
+        // sandboxed session): with ENABLE_PROMPT_CACHING_1H=true and this setting at
+        // "5m", subagent requests wrote only ephemeral_5m cache (36,387 tokens, none at
+        // 1h) while the main session wrote 100% 1h (35,209). Precedence of the subagent
+        // TTL in the binary, highest first: an env var that forces 5m, env
+        // CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL, this setting, a per-agent frontmatter
+        // `experimental.cacheTtl`, ENABLE_PROMPT_CACHING_1H. The 1-hour TTL is ignored
+        // while a subscription is in overage. A Claude Code that predates the setting
+        // ignores the key, so subagents then follow ENABLE_PROMPT_CACHING_1H as before.
+        // Re-probe when the precedence matters again; this is an observation, not a spec.
+        //
+        // Rejected: per-agent `experimental.cacheTtl` - it would spread one policy over
+        // every agent file; one devflow-managed flag keeps the policy in one place.
+        //
+        // Delete guard: only "5m" is deleted on disable or uninstall, so a user's own
+        // "1h" stays (D-GUARD-SCALAR). Adoption: init seeds this flag OFF when a value
+        // that is not "5m" is already on disk (D-ADOPT-RESPECTS-USER, respectUserOwnedSettings).
+        id: 'subagent-cache-5m',
+        label: 'Subagent 5-min cache',
+        description: 'Write subagent prompt-cache entries with the 5-minute TTL; the main session keeps 1 hour',
+        hint: 'Subagents rarely idle past 5 min, so 5-min cache writes cost less',
+        blurb: '5-min cache TTL for subagents',
+        kind: 'boolean',
+        target: { type: 'setting', key: 'subagentPromptCacheTtl' },
+        onPayload: '5m',
+        settingDeleteGuard: '5m',
+        recommended: true,
+        defaultValue: true,
+    },
     {
         id: 'show-turn-duration',
         label: 'Show turn duration',
@@ -969,6 +1008,78 @@ export function settingHoldsManagedShape(settingsJson, flagId) {
         return false;
     }
 }
+/**
+ * D-ADOPT-RESPECTS-USER predicate: the mirror of `settingHoldsManagedShape`.
+ *
+ * Returns true when the settings.json string carries a value at the guarded flag's
+ * target key that is NOT the flag's managed shape - a value the user (or another
+ * tool) owns, which enabling the flag would overwrite. Presence is decided with
+ * `hasOwnProperty`, so an explicit `null` counts as a value; the shape decision is
+ * delegated to `settingValueHoldsManagedShape`, never compared here.
+ *
+ * Returns false when:
+ *   - settingsJson is malformed
+ *   - root is not a plain object
+ *   - flagId is not in the registry
+ *   - the flag has no settingDeleteGuard, or is not a setting-target boolean
+ *   - the key is absent
+ *   - the on-disk value holds the managed shape
+ */
+export function settingHoldsUserValue(settingsJson, flagId) {
+    try {
+        const parsed = JSON.parse(settingsJson);
+        if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
+            return false;
+        const flag = FLAG_REGISTRY_MAP.get(flagId);
+        if (!flag || flag.kind !== 'boolean' || flag.target.type !== 'setting')
+            return false;
+        if (flag.settingDeleteGuard === undefined)
+            return false;
+        const root = parsed;
+        if (!Object.prototype.hasOwnProperty.call(root, flag.target.key))
+            return false;
+        return !settingValueHoldsManagedShape(flag, root[flag.target.key]);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * D-ADOPT-RESPECTS-USER: seed a guarded setting flag OFF when adopting it ON would
+ * overwrite a value the user already owns.
+ *
+ * A flag the manifest does not record is adopted at its `defaultValue`. For a flag whose
+ * target is a settings.json key with a `settingDeleteGuard`, adopting ON writes its
+ * managed payload over whatever is on disk (the guard protects deletion, not writes).
+ * When the key already holds a value that is not the managed shape - a user's own `"1h"`
+ * under `subagentPromptCacheTtl` - that write would silently replace a deliberate choice.
+ * Such a flag is set `false` instead; with the record then claiming `false`, the converge
+ * pipeline neither writes nor deletes the user's value.
+ *
+ * Scope: only flags ABSENT from `manifestFlags` (or all of them on a fresh install, when
+ * it is null). A flag the manifest records keeps its value in `flags`, so an explicit
+ * enable still wins. `devflow init --reset` hands this an empty settings snapshot
+ * (resolveResetGatedInputs), so nothing is detected and the factory default stands. The rule is generic over guarded
+ * setting flags: no flag id is special-cased, and `settingHoldsUserValue` is the one place
+ * that decides "the disk holds something that is not ours". For a flag whose default is
+ * already OFF (suppress-attribution) it changes nothing.
+ *
+ * Two callers apply the same rule: the init seed, and the flags TUI's starting rows (an
+ * upgrade that has not run init yet would otherwise offer a Save that overwrites the value).
+ *
+ * Pure function - the settings snapshot is read by the caller and passed in.
+ */
+export function respectUserOwnedSettings(flags, manifestFlags, settingsSnapshot) {
+    const result = { ...flags };
+    for (const flag of FLAG_REGISTRY) {
+        const adoptedAtDefault = manifestFlags === null || !(flag.id in manifestFlags);
+        if (!adoptedAtDefault)
+            continue;
+        if (settingHoldsUserValue(settingsSnapshot, flag.id))
+            result[flag.id] = false;
+    }
+    return result;
+}
 /**
  * D-ATTR-GUARD: returns true when it is safe to delete a flag's target key from
  * settings. For flags with a settingDeleteGuard the key is only deleted when the

package/dist/core/manifest.js

@@ -62,12 +62,15 @@ function parseManifestFlags(features, knownFlags) {
  * - features.knownFlags stripped from result (folded into FlagsRecord key-presence)
  * - features.proxy absent → false
  * - features.compliance absent/malformed → {enabled:false, frameworks:[]}
+ * - features.behavior absent → false; malformed → false, healed on disk (D-BEHAVIOR-OPT-IN)
  * - features.tracker absent/malformed → {provider:'github'}
+ * - features.tracker.servers absent → the default list; invalid → the default list, reported
+ *   through `opts.onWarning` when the caller supplies one (this reader has no output channel)
  *
  * D39: heal-write failure returns the migrated in-memory manifest (not null).
  * The on-disk format remains unhealed; next read triggers another attempt.
  */
-export async function readManifest(devflowDir) {
+export async function readManifest(devflowDir, opts) {
     const manifestPath = path.join(devflowDir, 'manifest.json');
     try {
         const content = await fs.readFile(manifestPath, 'utf-8');
@@ -129,7 +132,10 @@ export async function readManifest(devflowDir) {
             features.decisions !== undefined ||
             flagsWereLegacy ||
             features.knownFlags !== undefined ||
-            features.viewMode !== undefined;
+            features.viewMode !== undefined ||
+            // D-BEHAVIOR-OPT-IN: a malformed switch (present, not a boolean) is rewritten as
+            // the false it reads as; an absent one is not a defect and owes no write.
+            (features.behavior !== undefined && typeof features.behavior !== 'boolean');
         const SECURITY_MODES = ['none', 'user', 'managed'];
         const manifest = {
             version: data.version,
@@ -158,12 +164,14 @@ export async function readManifest(devflowDir) {
                 proxy: typeof features.proxy === 'boolean' ? features.proxy : false,
                 // Self-heal: absent/malformed compliance → {enabled:false, frameworks:[]}
                 compliance: normalizeComplianceFeature(features.compliance),
+                // D-BEHAVIOR-OPT-IN: absent/malformed → false (opt-in; the inverse of knowledge/learning).
+                behavior: features.behavior === true,
                 // Self-heal: absent/malformed/unknown tracker → {provider:'github'} (AC-3.21).
                 // Deliberately NOT in the hard-null set above — see the field's doc comment.
                 // Healing here is silent and emits no DEGRADED: that is the correct
                 // self-heal behaviour, and a different condition from a per-repo config
                 // value outside the domain (which does emit `unknown tracker provider`).
-                tracker: normalizeTrackerFeature(features.tracker),
+                tracker: normalizeTrackerFeature(features.tracker, opts?.onWarning),
             },
             installedAt: data.installedAt,
             updatedAt: data.updatedAt,