devflow-kit 3.2.0 → 3.4.0

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
+**Produces:** FILES_CHANGED, TASK_DESCRIPTION, DECISIONS_CONTEXT, FEATURE_KNOWLEDGE, FEATURE_KNOWLEDGE_RULES, HEAD_BEFORE
 
 Detect changed files and build context:
 
@@ -22,8 +22,22 @@ Detect changed files and build context:
 2. Else run `git diff --name-only HEAD` + `git diff --name-only --cached` to get staged + unstaged
 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
@@ -81,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, `{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 Scrutinize agent.
+Pass `FEATURE_KNOWLEDGE_RULES` to Scrutinize agent.
 
-**Extract:** FILES_CHANGED (list), TASK_DESCRIPTION (string), DECISIONS_CONTEXT (string, optional), FEATURE_KNOWLEDGE (string, optional)
+**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)
 
@@ -112,13 +136,14 @@ Spawn Simplify agent to refine code for clarity and consistency:
 Agent(subagent_type="Simplify", run_in_background=false):
 "TASK_DESCRIPTION: {task_description}
 FILES_CHANGED: {files_changed}
-Simplify and refine the code for clarity and consistency while preserving functionality."
+Simplify and refine the code for clarity and consistency while preserving functionality.
+Commit any improvements with a conventional-commit message."
 
 **Wait for completion.** Simplify agent commits changes directly.
 
 ### Phase 2: Scrutinize agent (9-Pillar Quality Gate)
 
-**Produces:** SCRUTINIZE_STATUS, SCRUTINIZE_CHANGES
+**Produces:** SCRUTINIZE_STATUS
 **Requires:** FILES_CHANGED, TASK_DESCRIPTION, DECISIONS_CONTEXT
 
 Spawn Scrutinize agent for quality evaluation and fixing:
@@ -127,22 +152,24 @@ 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)."
 
-**Wait for completion.** Extract: STATUS (PASS|FIXED|BLOCKED), changes_made (bool)
+**Wait for completion.** Extract: STATUS (PASS|FIXED|BLOCKED) from the `### Status` line
 
 ### Phase 3: Conditional Validation
 
 **Produces:** VALIDATION_RESULT
-**Requires:** SCRUTINIZE_CHANGES
+**Requires:** HEAD_BEFORE, SCRUTINIZE_STATUS
+
+If STATUS is BLOCKED, skip this phase: the report (Phase 4) names the blocker.
 
-If Scrutinize agent made changes (STATUS == FIXED):
+Run this phase only if HEAD moved — `git rev-parse HEAD` differs from `HEAD_BEFORE`, meaning Simplify or Scrutinize committed (Simplify alone counts, whatever Scrutinize's STATUS is). Otherwise skip it. Its scope is changed-only over what the two agents changed:
 
 Agent(subagent_type="Validate", run_in_background=false):
-"FILES_CHANGED: {scrutinize_modified_files}
+"FILES_CHANGED: {output of `git diff --name-only HEAD_BEFORE..HEAD`}
 VALIDATION_SCOPE: changed-only
 Run build, typecheck, lint, test on modified files"
 
@@ -191,24 +218,14 @@ 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.
 
 **Step 2 — Evaluate whether write-back is warranted:**
 
 Only proceed if **at least one** of these is true:
-- This workflow changed files in a directory that is documented by an existing feature knowledge base (a documented area changed).
+- This workflow changed files in a directory that is documented by an existing feature knowledge base (a documented area changed). Knowledge bases are written through at that point, never on a background schedule.
 - This workflow surfaced durable, cross-cutting knowledge about a codebase area that would help future agents working in the same area — patterns, anti-patterns, integration points, gotchas not visible from a single file read.
 
 **Never spawn unconditionally.** If neither condition is met, skip write-back silently.
@@ -231,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.
 
@@ -252,6 +269,7 @@ When the Knowledge agent reports `KB_COMMIT: skipped (detached HEAD)`, the files
 │
 ├─ Phase 0: Context gathering
 │  ├─ Git diff for changed files
+│  ├─ Record HEAD_BEFORE
 │  └─ Read index.md → DECISIONS_CONTEXT
 │
 ├─ Phase 1: Simplify agent
@@ -261,7 +279,7 @@ When the Knowledge agent reports `KB_COMMIT: skipped (detached HEAD)`, the files
 │  └─ 9-pillar quality gate (may fix and commit)
 │
 ├─ Phase 3: Validate agent (conditional)
-│  └─ If Scrutinize agent made changes, verify tests pass
+│  └─ If HEAD moved since HEAD_BEFORE (Simplify or Scrutinize committed), changed-only Validate over HEAD_BEFORE..HEAD
 │
 └─ Phase 4: Report
    └─ Display summary with pillar status
@@ -280,6 +298,6 @@ When the Knowledge agent reports `KB_COMMIT: skipped (detached HEAD)`, the files
 
 1. **Orchestration only** - Command spawns agents, doesn't do the work
 2. **Sequential execution** - Simplify agent must complete before Scrutinize agent
-3. **Validation gate** - If Scrutinize agent changes code, must pass validation
+3. **Validation gate** - If Simplify agent or Scrutinize agent committed, the changes must pass validation
 4. **Honest reporting** - Display actual agent outputs
 5. **Fail fast** - Stop on BLOCKED or validation failure

package/dist/core/agent-models.js

@@ -83,13 +83,16 @@ export const EFFORT_INHERIT = 'inherit';
  * count are unaffected.
  *
  * Shipped value of `memory`: `claude-sonnet-5-5` at `high` effort. User decision
- * 2026-10-08: memory quality is worth more than the cost saving of Haiku, which
- * replaces the plan's Haiku default. The worker does not read `agents.memory`
- * yet. Until it does, background-memory-update names this model as a literal in
- * its `claude -p --model` argument, and tests/agent-models-worker.test.ts holds
- * that literal equal to this row so the two cannot drift apart. Wiring the
- * worker to this map, and `--effort` behind a CLI version probe, is a separate
- * change.
+ * 2026-10-08: memory quality is worth more than the cost saving of Haiku.
+ *
+ * D-MEMORY-WORKER-LEAN: background-memory-update reads `agents.memory` from
+ * `~/.devflow/agent-models.json` at run time, validating `model` and `effort`
+ * field by field against the domain below, and passes `--effort` when the CLI
+ * version probe puts it at or above the lean-argv floor. A field it cannot use
+ * falls back to this row. The hook spells that fallback out for bash
+ * (`MEMORY_MODEL_DEFAULT`, `MEMORY_EFFORT_DEFAULT`, the alias and effort lists and
+ * the model-name rules), and tests/agent-models-worker.test.ts holds every one
+ * equal to this row and to the domain, so the two cannot drift apart.
  */
 export const WORKER_AGENTS = {
     memory: { model: 'claude-sonnet-5-5', effort: 'high' },
@@ -596,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

package/dist/core/claude-md-audit.js

@@ -0,0 +1,190 @@
+/**
+ * The CLI's view of the CLAUDE.md import audit — a typed seam onto the package's
+ * own `claude-md-audit.cjs`, never a second implementation of it.
+ *
+ * D-CLAUDE-MD-IMPORT-AUDIT: the logic (import grammar, bounds, thresholds, display
+ * text, stamp format) lives once, in src/assets/scripts/claude-md-audit.cjs, because
+ * the SessionStart hook reaches only `~/.devflow/scripts/`, which `composeScripts`
+ * fills by copying `src/assets/scripts/` verbatim. This module is the typed facade
+ * `devflow init` calls, loaded with the evidence-policy seam's `loadScript` against
+ * an explicit surface map (D-POLICY-CJS-SEAM). The interfaces below are TRANSCRIBED
+ * from the script's JSDoc and are this side's only shape authority; the module is
+ * required from `scriptsDir()` (the package's own copy), never from the installed
+ * `~/.devflow/scripts`, which may be older than this CLI.
+ *
+ * Nothing here throws: a load failure, a script that throws and a stamp that cannot
+ * be written are `Result` errors, and init prints at most one degraded line for them
+ * and keeps its exit code.
+ *
+ * D-AUDIT-STAMP (the caller's half): the audit writes nothing; this module writes the
+ * stamp after the install, only under an existing machine root (a command never
+ * creates `~/.devflow` for it), only through a sibling temp file renamed into place
+ * ({@link writeFileAtomicExclusive}), and never through a link. Because
+ * `writeFileAtomicExclusive` does not refuse a symlink at the target, the write does
+ * its own `lstat` regular-file check first (AC-437): a stamp path that is a symbolic
+ * link or any other non-regular file is refused and nothing is written.
+ */
+import { promises as fs } from 'fs';
+import { join } from 'path';
+import { scriptsDir } from './assets.js';
+import { writeFileAtomicExclusive } from './fs-atomic.js';
+import { loadScript, } from './evidence-policy.js';
+/** The script, relative to src/assets/scripts/ (and ~/.devflow/scripts/). */
+export const CLAUDE_MD_AUDIT_SCRIPT_NAME = 'claude-md-audit.cjs';
+/** The stamp's basename under the machine root (`~/.devflow`). */
+export const CLAUDE_MD_AUDIT_STAMP_FILE = '.claude-md-audit';
+/**
+ * The prefix of the stamp's sibling temp file, `<stamp>.tmp.<pid>`: the one name
+ * the hook and {@link writeFileAtomicExclusive} both create, so a crash between the
+ * write and the rename leaves a name uninstall can sweep.
+ */
+export const CLAUDE_MD_AUDIT_STAMP_TMP_PREFIX = `${CLAUDE_MD_AUDIT_STAMP_FILE}.tmp.`;
+/** The stamp is created owner-only, the mode the hook's `umask 077` write gives it. */
+const STAMP_CREATE_MODE = 0o600;
+/** Every key of ClaudeMdAuditModule and the runtime kind the loader requires of it. */
+export const CLAUDE_MD_AUDIT_MODULE_SURFACE = Object.freeze({
+    FILE_THRESHOLD_BYTES: 'number',
+    CHAIN_THRESHOLD_BYTES: 'number',
+    MAX_HOPS: 'number',
+    MAX_PATHS_PER_ROOT: 'number',
+    SCAN_BYTES: 'number',
+    MAX_BYTES_READ: 'number',
+    MAX_STAMP_BYTES: 'number',
+    MAX_KEYS: 'number',
+    SKIP_FILE_BYTES: 'number',
+    NOT_SHOWN: 'string',
+    HOOK_MAGIC: 'string',
+    HOOK_END: 'string',
+    extractImports: 'function',
+    isDisplayable: 'function',
+    isRecordable: 'function',
+    formatFinding: 'function',
+    findingKey: 'function',
+    parseStamp: 'function',
+    renderStamp: 'function',
+    readStampFile: 'function',
+    audit: 'function',
+    main: 'function',
+});
+/**
+ * Load the audit script from `dir` (default: the package's own scripts directory)
+ * and shape-check its surface. Never throws.
+ */
+export function loadClaudeMdAuditModule(dir = scriptsDir()) {
+    return loadScript(join(dir, CLAUDE_MD_AUDIT_SCRIPT_NAME), CLAUDE_MD_AUDIT_MODULE_SURFACE);
+}
+// ── Roots ──────────────────────────────────────────────────────────────────────
+/**
+ * The gated root set, in the order the hook passes it: `CLAUDE.md` in the Claude
+ * config directory, then (only for a git project that is not HOME — the caller
+ * passes `null` otherwise) the project's `CLAUDE.md`, `.claude/CLAUDE.md` and
+ * `CLAUDE.local.md` at its toplevel. Ancestor directories, lazily loaded
+ * subdirectory files and `rules/*.md` are not roots.
+ */
+export function claudeMdAuditRoots(claudeDir, projectRoot) {
+    const roots = [join(claudeDir, 'CLAUDE.md')];
+    if (projectRoot !== null) {
+        roots.push(join(projectRoot, 'CLAUDE.md'), join(projectRoot, '.claude', 'CLAUDE.md'), join(projectRoot, 'CLAUDE.local.md'));
+    }
+    return roots;
+}
+/** The stamp's text when it is a regular file of at most MAX_STAMP_BYTES, else null (read as absent). */
+export async function readClaudeMdAuditStamp(devflowDir, maxBytes) {
+    const stampPath = join(devflowDir, CLAUDE_MD_AUDIT_STAMP_FILE);
+    try {
+        const st = await fs.lstat(stampPath);
+        if (!st.isFile() || st.size > maxBytes)
+            return null;
+        return await fs.readFile(stampPath, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Run the audit over the gated roots. Reads only; the stamp is written by
+ * {@link writeClaudeMdAuditStamp}. Never throws.
+ */
+export async function runClaudeMdAudit(opts) {
+    const loaded = loadClaudeMdAuditModule(opts.scriptsDir);
+    if (!loaded.ok)
+        return { ok: false, error: { kind: 'load', detail: loaded.error } };
+    const audit = loaded.value;
+    try {
+        const stampText = await readClaudeMdAuditStamp(opts.devflowDir, audit.MAX_STAMP_BYTES);
+        const prior = stampText === null ? [] : audit.parseStamp(stampText).keys;
+        const roots = claudeMdAuditRoots(opts.claudeDir, opts.projectRoot);
+        if (opts.showAll !== true)
+            return { ok: true, value: audit.audit({ roots, home: opts.home, keys: prior }) };
+        const result = audit.audit({ roots, home: opts.home, keys: [] });
+        const keys = [...prior.filter(key => !result.shown.includes(key)), ...result.shown].slice(-audit.MAX_KEYS);
+        return { ok: true, value: { ...result, stamp: audit.renderStamp({ roots, examined: result.examined, keys }) } };
+    }
+    catch (err) {
+        return { ok: false, error: { kind: 'failed', detail: err instanceof Error ? err.message : String(err) } };
+    }
+}
+/**
+ * Run the audit and record its stamp (D-AUDIT-STAMP): what `devflow init` does after the
+ * install. Every finding over a threshold is displayed (`showAll`), as init is a deliberate
+ * command. The stamp carries the examined paths and every key the audit displayed, so the
+ * first SessionStart afterwards repeats nothing it was just shown. A stamp that cannot be
+ * written (no machine root, a link in the way, a full disk) costs a repeated message at
+ * most, never the audit's result, so that failure is not reported. Never throws.
+ */
+export async function auditAndRecordClaudeMd(opts) {
+    const run = await runClaudeMdAudit({ ...opts, showAll: true });
+    if (run.ok)
+        await writeClaudeMdAuditStamp(opts.devflowDir, run.value.stamp);
+    return run;
+}
+/**
+ * The display lines of an audit result, as ONE note body, or null when nothing is
+ * flagged. The single formatter both init paths (Recommended and Advanced) use; the
+ * lines themselves are produced by the script's own formatter, the one the hook
+ * shows in its systemMessage.
+ */
+export function formatClaudeMdAuditNote(result) {
+    return result.lines.length === 0 ? null : result.lines.join('\n');
+}
+/** The one degraded line printed when the audit could not run. */
+export function formatClaudeMdAuditUnavailable(error) {
+    if (error.kind === 'load') {
+        return error.detail.kind === 'not-found'
+            ? 'CLAUDE.md import audit unavailable: audit script not found — reinstall devflow-kit'
+            : 'CLAUDE.md import audit unavailable: audit script failed to load — reinstall devflow-kit';
+    }
+    return 'CLAUDE.md import audit unavailable: the audit failed';
+}
+/**
+ * Write the stamp text to `<devflowDir>/.claude-md-audit` (AC-437, D-AUDIT-STAMP).
+ *
+ * Refuses, writing nothing: a machine root that does not exist; a stamp path that is
+ * a symbolic link, a directory, a FIFO or any other non-regular file (an `lstat`
+ * check made here, because the atomic writer renames over the target without
+ * looking at what it is). Otherwise the text lands in a sibling temp file renamed
+ * into place. Never throws.
+ */
+export async function writeClaudeMdAuditStamp(devflowDir, text) {
+    try {
+        const root = await fs.stat(devflowDir).catch(() => null);
+        if (root === null || !root.isDirectory())
+            return { ok: false, error: { kind: 'no-machine-root' } };
+        const stampPath = join(devflowDir, CLAUDE_MD_AUDIT_STAMP_FILE);
+        const existing = await fs.lstat(stampPath).catch((err) => {
+            if (err.code === 'ENOENT')
+                return null;
+            throw err;
+        });
+        if (existing !== null && !existing.isFile()) {
+            return { ok: false, error: { kind: 'refused', detail: existing.isSymbolicLink() ? 'the stamp path is a symbolic link' : 'the stamp path is not a regular file' } };
+        }
+        // Owner-only, as the hook writes it: the stamp names the user's project paths.
+        await writeFileAtomicExclusive(stampPath, text, STAMP_CREATE_MODE);
+        return { ok: true, value: undefined };
+    }
+    catch (err) {
+        return { ok: false, error: { kind: 'write-failed', detail: err instanceof Error ? err.message : String(err) } };
+    }
+}
+//# sourceMappingURL=claude-md-audit.js.map

package/dist/core/feature-switch.js

@@ -80,6 +80,16 @@ export function setMachineFeature(rawManifest, feature, enabled, now) {
         updatedAt: now,
     };
 }
+/**
+ * Whether a RAW parsed manifest already records `feature` as exactly `enabled`:
+ * `features.<feature>` is that boolean. Pure. Stricter than
+ * {@link isMachineFeatureOn} on purpose — an absent key, a non-boolean value and
+ * a legacy key all read as a state without being recorded as it, so writing the
+ * explicit boolean is still a change.
+ */
+function isMachineFeatureRecorded(rawManifest, feature, enabled) {
+    return isJsonObject(rawManifest) && isJsonObject(rawManifest.features) && rawManifest.features[feature] === enabled;
+}
 async function readRawManifest(devflowDir) {
     try {
         return JSON.parse(await fs.readFile(path.join(devflowDir, 'manifest.json'), 'utf-8'));
@@ -101,9 +111,18 @@ export async function readMachineFeature(devflowDir, feature) {
  * temp + rename). Refuses with `not-installed` when there is no manifest to
  * write into — a manifest is created by `devflow init`, never by a toggle,
  * because a bare `{features: {...}}` file is not a manifest any reader accepts.
+ *
+ * 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.
  */
 export async function writeMachineFeature(devflowDir, feature, enabled) {
-    const next = setMachineFeature(await readRawManifest(devflowDir), feature, enabled, new Date().toISOString());
+    const raw = await readRawManifest(devflowDir);
+    if (isMachineFeatureRecorded(raw, feature, enabled))
+        return { ok: true, value: undefined };
+    const next = setMachineFeature(raw, feature, enabled, new Date().toISOString());
     if (next === null)
         return { ok: false, error: 'not-installed' };
     await writeFileAtomicExclusive(path.join(devflowDir, 'manifest.json'), JSON.stringify(next, null, 2) + '\n');

package/dist/core/flags.js

@@ -423,6 +423,34 @@ export const FLAG_REGISTRY = [
         integer: true,
         upstreamDefault: 600000,
     },
+    {
+        // D-AUTO-COMPACT-WINDOW-OPT-IN: opt-in and unset by default (undefined → manifest null →
+        // key never written). devflow writes CLAUDE_CODE_AUTO_COMPACT_WINDOW only when the user sets
+        // this flag. Init applies a seeded record without asking, which is why the default is neutral
+        // and `recommended` stays false: a smaller window compacts sooner, and a compaction
+        // mid-command is exactly what the SessionStart resume directive (D-COMPACT-RESUME-DIRECTIVE)
+        // recovers from, so the flag is not recommended until a forced mid-/implement /compact has
+        // been seen to resume at the phase after the last finished one (plan §9, a follow-up gate).
+        // The percent-based auto-compact override is a different variable that devflow deliberately
+        // never writes or names; tests/guards/no-autocompact-pct-override.test.ts keeps it out of src/.
+        // The env name was confirmed present in Claude Code 2.1.296, where it takes precedence over
+        // the in-app setting, and an in-app message names `auto` or 100k–1M (docs/reference/
+        // claude-code-flags-probe.md). No upstreamDefault: the default window and the grammar of the
+        // variable's own value were not observed, so the description states only devflow's own
+        // accepted range, 100000–1000000.
+        id: 'auto-compact-window',
+        label: 'Auto-compact window',
+        description: 'Context window size in tokens at which Claude Code auto-compacts',
+        hint: 'Sets the auto-compact window (100000-1000000); unset keeps the default',
+        blurb: 'auto-compact window size',
+        kind: 'number',
+        target: { type: 'env', key: 'CLAUDE_CODE_AUTO_COMPACT_WINDOW' },
+        recommended: false,
+        defaultValue: undefined,
+        min: 100000, // devflow sanity bound
+        max: 1000000, // devflow sanity bound
+        integer: true,
+    },
     {
         // Writes as { command: value } per Claude Code spellcheck setting shape.
         id: 'spellcheck',