devflow-kit 3.2.0 → 3.4.0

package/dist/cli/commands/init.js

@@ -43,6 +43,8 @@ import { applyTrackerSentinel, parseTrackerId, rearmTrackerInference, DEFAULT_TR
 import { formatTrackerSummary, shouldRunTrackerStep, runTrackerStep, buildClackTrackerPrompts, } from './tracker-prompts.js';
 import { shouldRunAttributionStep, runAttributionStep, buildClackAttributionPrompts, applyAttributionAnswer, attributionSeedFrom, } from './attribution-prompts.js';
 import { convergeFromManifest } from '../../targets/claude-code/compliance-install.js';
+import { convergeLearningVariants } from '../../targets/claude-code/learning-install.js';
+import { auditAndRecordClaudeMd, formatClaudeMdAuditNote, formatClaudeMdAuditUnavailable, } from '../../core/claude-md-audit.js';
 import * as os from 'os';
 // Re-export pure functions for tests (canonical source is post-install.ts)
 export { substituteSettingsTemplate, mergeDenyList, discoverProjectGitRoots } from '../../targets/claude-code/post-install.js';
@@ -319,6 +321,24 @@ export function trackerOverrideMessage(provider) {
         text: `Tracker: ${formatTrackerSummary(provider)}`,
     };
 }
+/**
+ * The audit's printable outcome, the ONE function both init paths use.
+ *
+ * D-CLAUDE-MD-IMPORT-AUDIT, D-INIT-REAL-OUTCOME: the Recommended summary note prints
+ * before the install runs, and the Advanced path prints no end-of-wizard summary
+ * (D-TRACKER-CLI-SURFACE), so the audit cannot be a row of either. It is decided after
+ * the install, from the CLAUDE.md files as they are, and printed as one note by the single
+ * call site in `run`, whichever path got there: the lines are the script's own formatter's,
+ * the ones the SessionStart hook shows in its systemMessage. Nothing is printed when
+ * nothing is flagged; a failure is at most one degraded line and never changes the exit code.
+ *
+ * Pure — returns text, prints nothing.
+ */
+export function claudeMdAuditStep(outcome) {
+    if (!outcome.ok)
+        return { note: null, degraded: formatClaudeMdAuditUnavailable(outcome.error) };
+    return { note: formatClaudeMdAuditNote(outcome.value), degraded: null };
+}
 /** The real adapter — the ONE binding of each owner into the init lifecycle. */
 export function buildTrackerLifecycleIO() {
     return {
@@ -1558,6 +1578,10 @@ export const initCommand = new Command('init')
             rulesMap,
             isPartialInstall: !!options.plugin,
             spinner: s,
+            // The SETTLED switch, after the flag, the prompt and the seed have all had
+            // their say (D-LEARNING-VARIANT-INSTALL): the files installed here and the
+            // manifest written at the end of init cannot disagree about it.
+            learning: learningEnabled,
             // Non-fatal install notices with no other channel (skipped symlinks in the
             // generated reference tree, mode-normalisation failures) reach the user rather
             // than the void. Collected now, emitted after the spinner stops.
@@ -1569,6 +1593,30 @@ export const initCommand = new Command('init')
         p.log.error(`${error}`);
         process.exit(1);
     }
+    // D-LEARNING-VARIANT-INSTALL: converge the learning variants. The file copy above
+    // installed the variant of everything IT installed; on a `--plugin` install the
+    // other plugins' files, already on disk, may still be the other variant (this run
+    // may have flipped the switch), and the apply-decisions skill is removed here when
+    // the copy skipped it on a partial install. Rewrites only what is installed.
+    // Warn-not-abort: either mismatch is safe (an on variant is still gated at run
+    // time, an off variant loads no decisions). The agent mapping is reapplied below.
+    try {
+        const learningConverge = await convergeLearningVariants({
+            claudeDir,
+            devflowDir,
+            learning: learningEnabled,
+            plugins: effectivePlugins,
+            warn: (msg) => installWarnings.push(msg),
+        });
+        if (verbose && learningConverge.converged) {
+            p.log.info(`Learning ${learningEnabled ? 'on' : 'off'} variants: ` +
+                `${learningConverge.commandsRewritten.length} command(s) and ${learningConverge.agentsRewritten.length} agent(s) ` +
+                `rewritten, ${learningConverge.unchanged} already current`);
+        }
+    }
+    catch (err) {
+        installWarnings.push(`Learning variant convergence failed — ${err instanceof Error ? err.message : String(err)}`);
+    }
     // Converge compliance artifacts (always converge, never short-circuit).
     // Called unconditionally so that enabling/disabling compliance during init
     // is reflected in the installed artifacts without a separate devflow compliance run.
@@ -2263,6 +2311,20 @@ export const initCommand = new Command('init')
         agent: trackerLifecycle.agent,
     });
     logSummaryLines(trackerLines);
+    // CLAUDE.md import audit (D-CLAUDE-MD-IMPORT-AUDIT, D-AUDIT-STAMP): after the install, on
+    // both paths, through claudeMdAuditStep. Global roots always; the project's roots when init
+    // runs inside a git repository that is not HOME, at its toplevel. The stamp is written here,
+    // now that the machine root exists, so the first SessionStart repeats nothing printed below.
+    const auditStep = claudeMdAuditStep(await auditAndRecordClaudeMd({
+        claudeDir,
+        projectRoot: gitRoot,
+        home: homeDir,
+        devflowDir,
+    }));
+    if (auditStep.note !== null)
+        p.note(auditStep.note, 'CLAUDE.md import audit');
+    if (auditStep.degraded !== null)
+        p.log.warn(auditStep.degraded);
     // External model routing status line (Advanced path / explicit --proxy flag only)
     if (proxyEnabled) {
         p.log.info(`External model routing: ${color.green('enabled')} — takes effect in new Claude Code sessions`);

package/dist/cli/commands/learning.js

@@ -4,9 +4,11 @@ import * as path from 'path';
 import * as p from '@clack/prompts';
 import color from 'picocolors';
 import { getLearningDir, getLearningTuningConfigPath, } from '../../core/project-paths.js';
+import { loadShippedAgentDefaults } from '../../core/agent-models.js';
 import { readMachineFeature, writeMachineFeature } from '../../core/feature-switch.js';
 import { loadSettingsModule, narrowedSwitchLabel, personalConfigTrackedWarning } from '../../core/evidence-policy.js';
-import { getDevFlowDirectory } from '../../targets/claude-code/claude-paths.js';
+import { getClaudeDirectory, getDevFlowDirectory } from '../../targets/claude-code/claude-paths.js';
+import { applyLearningToggle, describeLearningConverge, readRunningVersion, } from '../../targets/claude-code/learning-install.js';
 import { getLedgerRoot } from '../../core/ledger-root.js';
 import { drainLearningQueue } from '../../core/learning-queue-cleanup.js';
 import { firstSymbolicLink } from '../../core/linked-path.js';
@@ -273,15 +275,34 @@ export const CONFIGURE_SCOPE_OPTIONS = [
         hint: 'All projects (~/.devflow/learning.json); a devflow agents Learning mapping takes precedence over it',
     },
 ];
+/** The models `devflow learning --configure` offers, each with what it is good for. */
+const LEARNING_MODEL_CHOICES = [
+    { value: 'opus', label: 'Opus', note: 'highest quality for detection + curation judgment' },
+    { value: 'sonnet', label: 'Sonnet', note: 'good balance of quality and speed' },
+    { value: 'haiku', label: 'Haiku', note: 'fastest, lowest cost' },
+];
+/**
+ * D-LEARNING-SHIPPED-ROW: the model offered as "Recommended" is the one the Learning
+ * agent ships with, the `model:` line of its frontmatter. It is read from there and
+ * written nowhere else, so a change of the shipped tier moves the recommendation with
+ * it and this list never has to be edited. A shipped model outside the three offered
+ * (or none) recommends nothing.
+ */
+export function learningModelOptions(shippedModel) {
+    return LEARNING_MODEL_CHOICES.map(choice => ({
+        value: choice.value,
+        label: choice.label,
+        hint: choice.value === shippedModel
+            ? `Recommended — ${choice.note}`
+            : choice.note.charAt(0).toUpperCase() + choice.note.slice(1),
+    }));
+}
 async function handleConfigure() {
     p.intro(color.bgCyan(color.black(' Learning Configuration ')));
+    const shippedModel = (await loadShippedAgentDefaults()).learning?.model;
     const model = await p.select({
         message: 'Model for decision detection',
-        options: [
-            { value: 'opus', label: 'Opus', hint: 'Recommended — highest quality for detection + curation judgment' },
-            { value: 'sonnet', label: 'Sonnet', hint: 'Good balance of quality and speed' },
-            { value: 'haiku', label: 'Haiku', hint: 'Fastest, lowest cost' },
-        ],
+        options: learningModelOptions(shippedModel),
     });
     if (p.isCancel(model)) {
         p.cancel('Configuration cancelled.');
@@ -406,11 +427,44 @@ async function handleClear() {
     if (!drain.drained)
         p.log.warn(formatRefusedDrain('learning', drain.linkedFolder));
 }
+/**
+ * Make the installed prompts match the switch just written
+ * (D-LEARNING-VARIANT-INSTALL): the learning-on or learning-off commands and
+ * agents, and the apply-decisions skill. The same convergence `devflow init` runs,
+ * followed by reapplying the saved agent model mapping so `devflow agents`
+ * overrides survive.
+ *
+ * Warn-not-fail: the switch itself is already recorded, and either mismatch is
+ * safe (an on variant is still gated at run time, an off variant loads no
+ * decisions), so a problem here never changes the exit code.
+ */
+async function convergeInstalledVariants(enabled) {
+    try {
+        const outcome = await applyLearningToggle({
+            claudeDir: getClaudeDirectory(),
+            devflowDir: getDevFlowDirectory(),
+            learning: enabled,
+            runningVersion: await readRunningVersion(),
+            warn: (msg) => p.log.warn(msg),
+        });
+        if (outcome.kind === 'skipped') {
+            p.log.warn(outcome.message);
+            return;
+        }
+        const changed = describeLearningConverge(outcome.result, enabled);
+        if (changed !== null)
+            p.log.info(color.dim(`Installed prompts: ${changed}`));
+    }
+    catch (err) {
+        p.log.warn(`Could not update the installed prompts for the new learning setting — run ${color.cyan('devflow init')}: ${String(err)}`);
+    }
+}
 /**
  * `--enable` / `--disable`: the machine-wide switch (D-FEATURES-NARROW-ONLY),
  * converged exactly as `devflow init --learning / --no-learning` converges it —
- * the manifest value, and on disable a drained queue in the current project.
- * Never requires a git root: the switch is not a per-project setting.
+ * the manifest value, the installed prompt variants and skill
+ * (D-LEARNING-VARIANT-INSTALL), and on disable a drained queue in the current
+ * project. Never requires a git root: the switch is not a per-project setting.
  */
 async function handleToggle(enabled) {
     const recorded = await writeMachineFeature(getDevFlowDirectory(), 'learning', enabled);
@@ -419,6 +473,7 @@ async function handleToggle(enabled) {
         process.exitCode = 1;
         return;
     }
+    await convergeInstalledVariants(enabled);
     if (enabled) {
         p.log.success('Learning enabled in every project (a repository can opt out)');
         p.log.info(color.dim('Architectural decisions and pitfalls will be detected from your sessions'));

package/dist/cli/commands/uninstall.js

@@ -8,7 +8,7 @@ import { getInstallationPaths, getClaudeDirectory, getHomeDirectory, getManagedS
 import { getGitRoot } from '../../core/git.js';
 import { isSameLocation } from '../../core/same-location.js';
 import { DEVFLOW_PLUGINS, SKILL_NAMESPACE, getAllSkillNames, getAllAgentNames, getAllCommandNames, parsePluginSelection, resolveFeatureRedirect, prefixSkillName, unprefixSkillName, skillsOf, FEATURE_OWNED_SKILLS } from '../../core/plugins.js';
-import { readManifest } from '../../core/manifest.js';
+import { readManifest, removeManifestPlugins } from '../../core/manifest.js';
 import { sweepOrphanedAssets, mdFileName, mdEntryName } from '../../core/orphan-sweep.js';
 import { LEGACY_SKILL_NAMES } from '../../targets/claude-code/legacy.js';
 import { removeAmbientHook } from './ambient.js';
@@ -21,6 +21,7 @@ import { applyProxyTeardownToSettings } from './proxy.js';
 import { readProxyState, proxyJsonExists } from '../../core/proxy-state.js';
 import { hudCacheDir } from '../../core/cache.js';
 import { TRACKER_ATTEMPTS_NAMES, TRACKER_CLAIM_FILE, TRACKER_CONVENTIONS_DIR, TRACKER_ENABLED_FILE, TRACKER_LEGACY_ATTEMPTS_FILE, TRACKER_LEGACY_CONVENTIONS_FILE, TRACKER_PROVIDER_IDS, TRACKER_STAGED_PREFIX, } from '../../core/tracker.js';
+import { CLAUDE_MD_AUDIT_STAMP_FILE, CLAUDE_MD_AUDIT_STAMP_TMP_PREFIX } from '../../core/claude-md-audit.js';
 import { revertExternalAgents } from '../../core/agent-models.js';
 import { detectShell, getProfilePath } from '../../core/safe-delete.js';
 import { isAlreadyInstalled, removeFromProfile } from '../../core/safe-delete-install.js';
@@ -30,6 +31,7 @@ import { stripFlags } from '../../core/flags.js';
 import { stripDevflowTeammateModeFromJson } from '../../core/teammate-mode-cleanup.js';
 import { getPackageRoot, isContainedIn } from '../../core/paths.js';
 import { firstSymbolicLink } from '../../core/linked-path.js';
+import { restampInstalledCommands } from '../../targets/claude-code/language-stamp.js';
 /**
  * Where a retired repo-local install lives: `<gitRoot>/.claude` and `<gitRoot>/.devflow`.
  *
@@ -607,6 +609,12 @@ export function installArtifactPaths(devflowDir) {
         ...TRACKER_ATTEMPTS_NAMES.map(name => ({ relPath: name })),
         { relPath: TRACKER_LEGACY_ATTEMPTS_FILE },
         { relPath: TRACKER_ENABLED_FILE },
+        // The CLAUDE.md import audit's stamp (D-AUDIT-STAMP): machine state the SessionStart
+        // hook and `devflow init` write, holding paths, existence flags and finding keys and no
+        // user-authored content. Its sibling temp file, `<stamp>.tmp.<pid>`, is a prefix family:
+        // a SIGKILL between the write and the rename leaves one behind.
+        { relPath: CLAUDE_MD_AUDIT_STAMP_FILE },
+        { relPath: CLAUDE_MD_AUDIT_STAMP_TMP_PREFIX, isPrefix: true },
         // The agent's scrubbed staging file, one per invocation under a mktemp name
         // it removes from a trap — a SIGKILL outruns the trap and leaves it behind.
         // A prefix, because the names exist only on disk. Content is a scrubbed copy
@@ -912,6 +920,39 @@ export async function runSelectivePhaseForScope(opts) {
         catch { /* agents dir absent or revert failed — non-fatal */ }
     }
     await removeSelectedPlugins(claudeDir, selectedPlugins, verbose, installedPlugins, mayChange);
+    // D-LANGUAGE-FOCUS-STAMP: re-stamp the installed /code-review from the selection that REMAINS.
+    // A language plugin owns a skill and no command, so removing it deletes the skill while its
+    // name would stay on the stamped line, and /code-review would spawn a focus whose skill is gone.
+    // The remaining selection is the retained set the removal above used (installedPlugins minus the
+    // selected plugins, D-RETAIN-FROM-MANIFEST), so the stamp and the skills on disk cannot disagree.
+    // Narrowly scoped: only the stamped line of a command that is still installed is rewritten, and
+    // nothing else converges here. A damaged copy is a warning, never a failure.
+    {
+        const removed = new Set(selectedPlugins.map(sp => sp.name));
+        await restampInstalledCommands({
+            claudeDir,
+            effectivePlugins: installedPlugins.filter(plugin => !removed.has(plugin.name)),
+            warn: (msg) => p.log.warn(msg),
+            mayChange,
+        });
+    }
+    // D-UNINSTALL-DROPS-PLUGIN: the manifest is the install record `devflow init` seeds its plugin
+    // selection from (a re-init keeps the prior selection), so a plugin removed here but still listed
+    // would be installed again by the next plain init. Take the selected names off the list;
+    // knownPlugins and every other key stay.
+    // Behind the scope guard like every other write here. A failed write is a warning, never a failure.
+    {
+        const manifestPath = path.join(devflowDir, 'manifest.json');
+        if (await mayChange(manifestPath)) {
+            const recorded = await removeManifestPlugins(devflowDir, selectedPlugins.map(sp => sp.name));
+            if (!recorded.ok) {
+                p.log.warn(`Could not drop the plugin from manifest.json — a later devflow init would install it again: ${recorded.error}`);
+            }
+            else if (verbose && recorded.removed.length > 0) {
+                p.log.success(`Removed ${recorded.removed.join(', ')} from manifest.json`);
+            }
+        }
+    }
     // Clean up ambient hook if ambient plugin is being removed
     if (selectedPlugins.some(sp => sp.name === 'devflow-ambient')) {
         const settingsPath = path.join(claudeDir, 'settings.json');

package/dist/commands/bug-analysis.md

@@ -177,12 +177,24 @@ If no tool produced findings: set `STATIC_FINDINGS` to `(none)`.
 
 ### Phase 3: Context Loading
 
-**Produces:** DECISIONS_CONTEXT, FEATURE_KNOWLEDGE, PLAN_CONTEXT, ACCEPTANCE_RULES
+**Produces:** DECISIONS_CONTEXT, FEATURE_KNOWLEDGE, FEATURE_KNOWLEDGE_RULES, PLAN_CONTEXT, ACCEPTANCE_RULES
 
 #### Decisions Index
 
+**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
@@ -240,22 +252,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`:
+
+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.
 
-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.
+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:**
+**Step 5 — Set FEATURE_KNOWLEDGE and FEATURE_KNOWLEDGE_RULES:**
 
-Concatenate the selected KNOWLEDGE.md files under slug headers:
+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.
 
 #### Plan Artifact