devflow-kit 3.3.0 → 3.4.0

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',

package/dist/core/fs-atomic.js

@@ -28,15 +28,20 @@ import { promises as fs } from 'fs';
  *
  * @param filePath - Absolute path to the target file.
  * @param data - UTF-8 encoded content to write.
+ * @param createMode - Permission bits the temp file is CREATED with (masked by the
+ *   umask), so a file that must be owner-only is never readable by others, not even
+ *   between the write and the rename. Omitted, the umask default applies. Either way
+ *   an existing target's mode wins (below).
  */
-export async function writeFileAtomicExclusive(filePath, data) {
+export async function writeFileAtomicExclusive(filePath, data, createMode) {
     // PID-scope the tmp name so concurrent writers from different processes
     // (e.g., two Claude Code sessions) never collide on the same .tmp path.
     // mirrors proxy-log.ts rotation at src/core/proxy-log.ts which PID-scopes
     // for the same reason.
     const tmp = `${filePath}.tmp.${process.pid}`;
+    const options = { encoding: 'utf-8', flag: 'wx', ...(createMode === undefined ? {} : { mode: createMode }) };
     try {
-        await fs.writeFile(tmp, data, { encoding: 'utf-8', flag: 'wx' });
+        await fs.writeFile(tmp, data, options);
     }
     catch (err) {
         if (err.code !== 'EEXIST')
@@ -48,7 +53,7 @@ export async function writeFileAtomicExclusive(filePath, data) {
             await fs.unlink(tmp);
         }
         catch { /* race — already removed */ }
-        await fs.writeFile(tmp, data, { encoding: 'utf-8', flag: 'wx' });
+        await fs.writeFile(tmp, data, options);
     }
     // Preserve the target's permission mode across the atomic replace.
     // A user who hardened the target (e.g. settings.json → 0600 to protect

package/dist/core/learning-variants.js

@@ -0,0 +1,213 @@
+/**
+ * Learning-variant splitter: one compiled prompt body in, its learning-on and
+ * learning-off variants out.
+ *
+ * Pure module, zero I/O. Every refusal is a Result; the exiting shell is
+ * scripts/build-mds.ts, which renders these errors into the build's single exit.
+ *
+ * D-LEARNING-VARIANTS: when learning is off on a machine, the decisions text is
+ * ABSENT from every prompt it would have reached, not merely gated at run time.
+ * The build therefore emits two variants of a prompt that carries learning text:
+ * the learning-on variant at today's path (dist/commands/x.md, dist/agents/x.md)
+ * and the learning-off variant at dist/learning-off/{commands,agents}/x.md, only
+ * for a host that has an arm. A prompt with no arm has one variant and no
+ * learning-off file.
+ *
+ * The arms are whole-line markers in the host or in a partial it expands:
+ *
+ *   <!-- learning:on -->     opens an arm that only the learning-on variant keeps
+ *   <!-- learning:off -->    opens an arm that only the learning-off variant keeps;
+ *                            directly after an on arm it is that arm's else
+ *   <!-- learning:end -->    closes the arm
+ *
+ * A marker line matches LEARNING_MARKER_RE. It may be indented and may sit inside
+ * a fenced block, a list, a define body or an agent's second frontmatter block,
+ * because MDS passes an HTML comment through untouched. The splitter runs on the
+ * COMPILED body, after the MDS compile, so it adds no compileFile call, no import
+ * into an MDS module and nothing against the per-module compile-time guard. A
+ * marker line is removed whole, with its newline. Every other line is kept byte
+ * for byte, so a blank line is content: put the blank line a paragraph needs
+ * inside the arm that owns the paragraph, and the other variant gets none of it.
+ *
+ * The markers are INTERIM. MDS 0.4.4 emits an `@if` inside a code fence or on an
+ * indented line as literal text (its lexer requires column 0), and the arms have
+ * to sit exactly there: inside fenced spawn blocks, scripts, list items and
+ * frontmatter. They are replaced by native conditionals once mdscript ships
+ * fence- and indent-aware `@if` (dean0x/mdscript#452). That swap, with the
+ * @mdscript/mds upgrade it rides on proven byte-identical in dist/ and this module
+ * deleted, is dean0x/devflow#439. The mapping is one to one: `on` becomes
+ * `@if learning:`, `off` becomes `@else:` and `end` becomes `@end`. A standalone
+ * `off` arm, with no on arm before it, becomes an `@if learning:` with an empty
+ * body followed by `@else:`.
+ *
+ * What the splitter refuses, each as a LearningSplitError with the source line:
+ *   - nesting: an `on` marker while an arm is open, or a second `off` in one arm;
+ *   - an `end` with no open arm;
+ *   - an arm still open at the end of the body;
+ *   - an empty arm (no line with content between its marker and the next);
+ *   - a stray marker: a line that names `<!-- learning:` but is not a whole-line
+ *     marker, which would otherwise ship as prompt text.
+ *
+ * Scope guarantee: this module answers one question (what are the two variants of
+ * this body?) and one cheap one for the build to ask of a body that must carry no
+ * arms (containsLearningMarker). It decides nothing about WHICH text belongs in an
+ * arm: that is authoring, and the guards over the built trees hold it.
+ */
+function Ok(value) {
+    return { ok: true, value };
+}
+function Err(error) {
+    return { ok: false, error };
+}
+/**
+ * Repo-relative root of the learning-off variants.
+ *
+ * Exported because the build's orphan prune names this directory even when no
+ * host carries an arm, which is exactly the case where every file in it is an
+ * orphan, so it cannot be derived from the plan.
+ */
+export const LEARNING_OFF_OUTPUT_DIR = 'dist/learning-off';
+/**
+ * POSIX repo-relative path of the learning-off variant of an output file.
+ *
+ * `fileName` is the already-validated basename the learning-on variant is written
+ * under (`implement.md`), so the two variants of one host always share a name.
+ */
+export function learningOffRelPath(kind, fileName) {
+    return `${LEARNING_OFF_OUTPUT_DIR}/${kind}/${fileName}`;
+}
+// ---------------------------------------------------------------------------
+// Markers
+// ---------------------------------------------------------------------------
+/**
+ * A whole-line learning marker. The group captures `on`, `off` or `end`.
+ *
+ * Anchored at both ends with no nested quantifier, so a match is linear in the
+ * line length. Leading and trailing space or tab is allowed; anything else on the
+ * line is not a marker.
+ */
+export const LEARNING_MARKER_RE = /^[ \t]*<!-- learning:(on|off|end) -->[ \t]*$/;
+/**
+ * The fragment that makes a line a marker ATTEMPT: loose on spacing and case so a
+ * malformed marker is caught rather than shipped. Every valid marker contains it.
+ */
+const MARKER_FRAGMENT_RE = /<!--\s*learning\s*:/i;
+/** True when the text names a learning marker anywhere, valid or not. */
+export function containsLearningMarker(text) {
+    return MARKER_FRAGMENT_RE.test(text);
+}
+function markerOf(line) {
+    // A CRLF body carries the carriage return on the line; it is not part of the marker.
+    const bare = line.endsWith('\r') ? line.slice(0, -1) : line;
+    const match = LEARNING_MARKER_RE.exec(bare);
+    return match === null ? null : match[1];
+}
+/** The longest stretch of a stray line a refusal quotes. */
+const STRAY_QUOTE_MAX = 80;
+/**
+ * Split a compiled body into its learning-on and learning-off variants.
+ *
+ * Total and pure: the same input gives the same output, and a refusal is a
+ * Result. The loop is one pass over the body's lines, so its bound is the body's
+ * own length.
+ *
+ * An arm needs a line with content in it. An arm that holds only blank lines is
+ * refused as empty, because it would add blank lines to one variant and nothing to
+ * the other, which is a mistake rather than a design.
+ */
+export function splitLearningVariants(body) {
+    const lines = body.split('\n');
+    const on = [];
+    const off = [];
+    let hasArms = false;
+    // The open arm, if any: which one, the line of the marker that opened it, and
+    // whether it has held a line with content yet.
+    let arm = null;
+    let armOpenedAt = 0;
+    let armHasContent = false;
+    for (let index = 0; index < lines.length; index++) {
+        const line = lines[index];
+        const lineNo = index + 1;
+        const marker = markerOf(line);
+        if (marker === null) {
+            if (MARKER_FRAGMENT_RE.test(line)) {
+                return Err({ kind: 'stray-marker', line: lineNo, text: line.trim().slice(0, STRAY_QUOTE_MAX) });
+            }
+            if (arm !== 'off')
+                on.push(line);
+            if (arm !== 'on')
+                off.push(line);
+            if (arm !== null && line.trim() !== '')
+                armHasContent = true;
+            continue;
+        }
+        hasArms = true;
+        switch (marker) {
+            case 'on':
+                if (arm !== null)
+                    return Err({ kind: 'nested-arm', line: lineNo, arm, openedAt: armOpenedAt });
+                arm = 'on';
+                armOpenedAt = lineNo;
+                armHasContent = false;
+                break;
+            case 'off':
+                if (arm === 'off')
+                    return Err({ kind: 'repeated-off', line: lineNo, openedAt: armOpenedAt });
+                // Directly after an on arm this is its else: the on arm ends here.
+                if (arm === 'on' && !armHasContent) {
+                    return Err({ kind: 'empty-arm', arm, openedAt: armOpenedAt, closedAt: lineNo });
+                }
+                arm = 'off';
+                armOpenedAt = lineNo;
+                armHasContent = false;
+                break;
+            case 'end':
+                if (arm === null)
+                    return Err({ kind: 'unopened-end', line: lineNo });
+                if (!armHasContent) {
+                    return Err({ kind: 'empty-arm', arm, openedAt: armOpenedAt, closedAt: lineNo });
+                }
+                arm = null;
+                break;
+            default: {
+                const unhandled = marker;
+                return Err({ kind: 'stray-marker', line: lineNo, text: String(unhandled) });
+            }
+        }
+    }
+    if (arm !== null)
+        return Err({ kind: 'unclosed-arm', arm, openedAt: armOpenedAt });
+    return Ok({ on: on.join('\n'), off: off.join('\n'), hasArms });
+}
+/**
+ * Render a refusal as one line a person can act on.
+ *
+ * One arm per kind with a `never` default, so a kind added to the union cannot
+ * fall through into a message that does not describe it. Shared by the build and
+ * the tests, so the text asserted is the text shipped.
+ */
+export function describeLearningSplitError(error) {
+    switch (error.kind) {
+        case 'nested-arm':
+            return (`line ${error.line}: a learning:on marker inside the ${error.arm} arm opened at line ` +
+                `${error.openedAt} — arms do not nest; close it with learning:end first`);
+        case 'repeated-off':
+            return (`line ${error.line}: a second learning:off marker inside the off arm opened at line ` +
+                `${error.openedAt} — an arm has at most one else`);
+        case 'unopened-end':
+            return `line ${error.line}: a learning:end marker with no open arm`;
+        case 'unclosed-arm':
+            return `the ${error.arm} arm opened at line ${error.openedAt} is never closed with learning:end`;
+        case 'empty-arm':
+            return (`lines ${error.openedAt}-${error.closedAt}: the ${error.arm} arm holds no line with content — ` +
+                `delete the arm or put its text inside it`);
+        case 'stray-marker':
+            return (`line ${error.line}: "${error.text}" names a learning marker but is not one — a marker ` +
+                `is a whole line, exactly <!-- learning:on -->, <!-- learning:off --> or <!-- learning:end -->`);
+        default: {
+            const unhandled = error;
+            return `unhandled learning split error ${JSON.stringify(unhandled)}`;
+        }
+    }
+}
+//# sourceMappingURL=learning-variants.js.map

package/dist/core/manifest.js

@@ -213,6 +213,68 @@ export async function syncManifestFeature(devflowDir, key, value) {
     manifest.updatedAt = new Date().toISOString();
     await writeManifest(devflowDir, manifest);
 }
+/**
+ * Drop `names` from a RAW parsed manifest's `plugins` list. Pure — returns a new
+ * object and never mutates its input. Null when there is nothing to write: the
+ * value is not a manifest-shaped object, or none of `names` is listed.
+ *
+ * Only `plugins` and `updatedAt` change; every other key is carried verbatim,
+ * `knownPlugins` included. That snapshot records which registry plugins the last
+ * install knew, and init adopts a registry plugin that is in neither list as new
+ * (`resolveSeedPlugins`), so dropping a removed plugin from it would make the next
+ * re-init install it again. Going through readManifest()/writeManifest() instead
+ * would drop every key ManifestData does not model (one a newer devflow wrote,
+ * say) and persist that reader's unrelated heals as a side effect of a removal.
+ * Entries that are not strings are neither matched nor dropped.
+ */
+export function withoutManifestPlugins(rawManifest, names, now) {
+    if (typeof rawManifest !== 'object' || rawManifest === null || Array.isArray(rawManifest))
+        return null;
+    const record = rawManifest;
+    if (!Array.isArray(record.plugins))
+        return null;
+    const doomed = new Set(names);
+    const kept = record.plugins.filter(entry => !(typeof entry === 'string' && doomed.has(entry)));
+    if (kept.length === record.plugins.length)
+        return null;
+    return { ...record, plugins: kept, updatedAt: now };
+}
+/**
+ * D-UNINSTALL-DROPS-PLUGIN: record a selective uninstall in `<devflowDir>/manifest.json`.
+ *
+ * The manifest is the install record init seeds from (a re-init keeps the prior
+ * selection), so a plugin `devflow uninstall --plugin` removed but the manifest
+ * still lists would come back on the next plain `devflow init`. This is the one
+ * writer that takes a name off that list (atomic temp + rename).
+ *
+ * A quiet no-op, not an error, when there is nothing to record: no manifest (a
+ * pre-manifest install), one that is not valid JSON or not manifest-shaped, or
+ * none of `names` listed — the file is left byte-identical. Never throws: a failed
+ * write comes back as `{ ok: false }` for the caller to report.
+ */
+export async function removeManifestPlugins(devflowDir, names) {
+    const manifestPath = path.join(devflowDir, 'manifest.json');
+    let raw;
+    try {
+        raw = JSON.parse(await fs.readFile(manifestPath, 'utf-8'));
+    }
+    catch {
+        // ENOENT, EACCES or SyntaxError — no usable manifest, so nothing to record.
+        return { ok: true, removed: [] };
+    }
+    const next = withoutManifestPlugins(raw, names, new Date().toISOString());
+    if (next === null)
+        return { ok: true, removed: [] };
+    try {
+        await writeFileAtomicExclusive(manifestPath, JSON.stringify(next, null, 2) + '\n');
+    }
+    catch (error) {
+        return { ok: false, error: error instanceof Error ? error.message : String(error) };
+    }
+    const doomed = new Set(names);
+    const before = raw.plugins;
+    return { ok: true, removed: before.filter((entry) => typeof entry === 'string' && doomed.has(entry)) };
+}
 /**
  * Merge new plugins into existing plugin list (union, no duplicates).
  * Preserves order: existing plugins first, then new ones appended.

package/dist/core/mds-variants.js

@@ -120,6 +120,13 @@ export function validateContractOutputName(name) {
  * from here keeps the table below the only place a destination is spelled.
  */
 export const AGENTS_OUTPUT_DIR = 'dist/agents';
+/**
+ * Repo-relative destination for `commands` hosts.
+ *
+ * Exported for the same reason as AGENTS_OUTPUT_DIR: the orphan prune names the
+ * directory even when no command host is planned.
+ */
+export const COMMANDS_OUTPUT_DIR = 'dist/commands';
 /**
  * The bare (unprefixed) skill that OWNS the generated references.
  *
@@ -153,7 +160,7 @@ export const SKILL_REFS_SKILL_NAME = 'git';
  */
 export const SKILL_REFS_OUTPUT_DIR = `dist/skills/${SKILL_REFS_SKILL_NAME}/references`;
 const ALLOWED_OUTPUT_DIRS = [
-    { dir: 'dist/commands', variant: 'commands' },
+    { dir: COMMANDS_OUTPUT_DIR, variant: 'commands' },
     { dir: AGENTS_OUTPUT_DIR, variant: 'agents' },
     { dir: SKILL_REFS_OUTPUT_DIR, variant: 'skill-refs' },
 ];
@@ -363,6 +370,30 @@ export const GIT_CROSS_CUTTING_DOCS = [
  * Registering a provider whose `subdir` is one of MCP_BACKED_PROVIDER_SUBDIRS is
  * also what opens the generation gate on the tool-call contract; see
  * {@link mcpContractIsGenerated}. There is no second edit and no flag.
+ *
+ * D-TRACKER-CONTRACT-ON-DEMAND. The last entry, `_contract.mds`, is the first
+ * UNGATED `kind: 'contract'` module (the tool-call contract of
+ * {@link MCP_CONTRACT_MODULE} is gated, so it is not in this array). It emits
+ * `tracker/_contract.md`: the provider resolution and the tracker input contract
+ * that used to sit in the always-loaded Git agent, where every spawn paid for
+ * them although most spawns run a PR-host operation that never touches the
+ * issue tracker. A spawn now reads the file once, only when it runs a tracker
+ * operation, before its first tracker step. The agent's retained
+ * `## Loading the mechanics` section is the one line that names it; it keeps
+ * the PR-mechanics load rule and the merged step order, which a PR-only spawn
+ * needs and which this file cannot instruct a spawn to load. It is ungated for
+ * the reason the registry's other provider-independent files are: every install
+ * carries every provider, GitHub included, so no registered provider is the
+ * condition it depends on.
+ *
+ * The budget clause: the file is a per-SPAWN term of each tracker row (GitHub,
+ * Jira, Linear), charged the way the tool-call contract is (`contractTerm` in
+ * tests/tracker/budget-model.ts) and added in `providerLoadedSet`. It is not part
+ * of `ownLoadForProvider`, of the PR-host row or of the per-operation PR-host
+ * cap. ensure-pr-ready is both a PR-host and a tracker operation, so charging it
+ * the contract there would put it over a lower-only cap; its full cost,
+ * contract included, is priced through the tracker rows, where it is already a
+ * candidate.
  */
 export const VARIANT_MODULES = [
     {
@@ -395,6 +426,12 @@ export const VARIANT_MODULES = [
         kind: 'named',
         ops: GIT_CROSS_CUTTING_DOCS,
     },
+    {
+        source: 'src/assets/mds/tracker/_contract.mds',
+        subdir: 'tracker',
+        kind: 'contract',
+        ops: ['_contract'],
+    },
 ];
 // ---------------------------------------------------------------------------
 // The tool-call contract module, and the gate on its generation