devflow-kit 3.7.0 → 3.8.0

package/dist/core/feature-switch.js

@@ -1,19 +1,41 @@
 import { promises as fs } from 'fs';
 import * as path from 'path';
 import { writeFileAtomicExclusive } from './fs-atomic.js';
+import { MANIFEST_LOCK_WAIT_MS, withManifestLock } from './manifest-lock.js';
 function isJsonObject(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
+/**
+ * The keys a RAW manifest may hold a machine feature under, current names first.
+ *
+ * `curation` is stored under two current keys, `curation` and `learning`: the
+ * feature was renamed, and a manifest written before the rename holds only
+ * `learning`. No precedence rule exists between the two (see
+ * {@link isMachineFeatureOn}); every write sets both. `memory` and `knowledge`
+ * have one current key.
+ */
+const CURRENT_KEYS = {
+    memory: ['memory'],
+    curation: ['curation', 'learning'],
+    knowledge: ['knowledge'],
+};
 /**
  * The pre-rename key each machine feature was stored under, where one exists:
- * `learning` was `decisions` and `knowledge` was `kb`. A manifest no
+ * `curation` was `decisions` and `knowledge` was `kb`. A manifest no
  * command has rewritten since the rename can still hold only the legacy key.
  * `memory` was never renamed.
  */
 const LEGACY_KEYS = {
-    learning: 'decisions',
+    curation: 'decisions',
     knowledge: 'kb',
 };
+/**
+ * The keys a write sets for `feature`: the feature's own key, and for `curation` its
+ * pre-rename copy too (the manifest mirror). Opt-in switches have one key.
+ */
+function writtenKeys(feature) {
+    return feature === 'behavior' ? [feature] : CURRENT_KEYS[feature];
+}
 /**
  * Whether a RAW parsed manifest leaves `feature` switched on. Pure.
  *
@@ -23,13 +45,23 @@ const LEGACY_KEYS = {
  * shell hooks, so the CLI's status and the runtime never disagree about the
  * same file.
  *
+ * The machine rule (issue #529), identical in every reader —
+ * this function, resolve-settings.cjs and the shell gates:
+ *   1. off when ANY current key (`curation`, `learning`) is a boolean `false`;
+ *   2. else on when any current key is a boolean `true`;
+ *   3. else, when neither current key is a boolean, the pre-rename key decides
+ *      if it is a boolean (`decisions` for curation, `kb` for knowledge);
+ *   4. else ON.
+ * A non-boolean value is ignored for that key only. A disagreeing pair
+ * therefore resolves to OFF: false wins, so a switch a user turned off never
+ * comes back on because the other spelling still says true.
+ *
  * D-LEARNING-LEGACY-DECISIONS (a sub-decision of D-FEATURES-NARROW-ONLY):
- * `learning` is read as `features.learning` when that is a boolean, else the
- * legacy `features.decisions` when THAT is a boolean, else ON — readManifest's
- * migration precedence exactly. The legacy key is otherwise honoured only once
- * some command happens to run readManifest and heal it, so a `decisions: false`
- * would keep learning running until then. queue_read_gates applies the same
- * precedence.
+ * the legacy `features.decisions` is read only when neither current key is a
+ * boolean — readManifest's migration precedence exactly. The legacy key is
+ * otherwise honoured only once some command happens to run readManifest and
+ * heal it, so a `decisions: false` would keep curation running until then.
+ * queue_read_gates applies the same precedence.
  *
  * D-KNOWLEDGE-LEGACY-KB (the same sub-decision for the other renamed key):
  * `knowledge` is read as `features.knowledge` when that is a boolean, else the
@@ -51,11 +83,13 @@ export function isMachineFeatureOn(rawManifest, feature) {
     const features = rawManifest.features;
     if (!isJsonObject(features))
         return true;
+    const current = CURRENT_KEYS[feature]
+        .map((key) => features[key])
+        .filter((value) => typeof value === 'boolean');
+    if (current.length > 0)
+        return !current.includes(false);
     const legacyKey = LEGACY_KEYS[feature];
-    const value = legacyKey !== undefined && typeof features[feature] !== 'boolean'
-        ? features[legacyKey]
-        : features[feature];
-    return value !== false;
+    return legacyKey === undefined || features[legacyKey] !== false;
 }
 /**
  * Set `feature` in a RAW parsed manifest. Pure — returns a new object and never
@@ -63,7 +97,9 @@ export function isMachineFeatureOn(rawManifest, feature) {
  * is no `features` record to write into).
  *
  * Only `features.<feature>` and `updatedAt` change; every other key is carried
- * verbatim. Writing `learning` leaves a legacy `decisions` key in place, and
+ * verbatim. Writing `curation` sets BOTH current keys (`curation` and its
+ * pre-rename copy `learning`) to the one value, so a disagreeing pair is
+ * overwritten, never carried. It leaves a legacy `decisions` key in place, and
  * writing `knowledge` a legacy `kb` key, inert: the boolean just written wins
  * over it (D-LEARNING-LEGACY-DECISIONS, D-KNOWLEDGE-LEGACY-KB). Going through
  * readManifest()/writeManifest() instead would refuse a manifest that reader
@@ -74,21 +110,28 @@ export function isMachineFeatureOn(rawManifest, feature) {
 export function setMachineFeature(rawManifest, feature, enabled, now) {
     if (!isJsonObject(rawManifest) || !isJsonObject(rawManifest.features))
         return null;
+    const written = {};
+    for (const key of writtenKeys(feature))
+        written[key] = enabled;
     return {
         ...rawManifest,
-        features: { ...rawManifest.features, [feature]: enabled },
+        features: { ...rawManifest.features, ...written },
         updatedAt: now,
     };
 }
 /**
  * Whether a RAW parsed manifest already records `feature` as exactly `enabled`:
- * `features.<feature>` is that boolean. Pure. Stricter than
+ * every key a write sets (`writtenKeys`) 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.
+ * a legacy key all read as a state without being recorded as it, and for
+ * `curation` a disagreeing pair, or one key alone, is a copy that disagrees or is
+ * missing: not recorded, so the write that follows puts both keys right.
  */
 function isMachineFeatureRecorded(rawManifest, feature, enabled) {
-    return isJsonObject(rawManifest) && isJsonObject(rawManifest.features) && rawManifest.features[feature] === enabled;
+    if (!isJsonObject(rawManifest) || !isJsonObject(rawManifest.features))
+        return false;
+    const features = rawManifest.features;
+    return writtenKeys(feature).every((key) => features[key] === enabled);
 }
 async function readRawManifest(devflowDir) {
     try {
@@ -136,16 +179,49 @@ export async function readOptInFeature(devflowDir, feature) {
  * D-NOOP-TOGGLE: a toggle to the value the manifest already records writes
  * nothing. The only bytes such a write could change are `updatedAt`, and that
  * field means "the manifest's content last changed", so a no-op must not move
- * it. This is the one write point of `devflow memory|learning|knowledge|behavior
+ * it. This is the one write point of `devflow memory|curation|knowledge|behavior
  * --enable/--disable`, so the rule holds for all four at once.
+ *
+ * The read and the write run under the manifest lock (manifest-lock.ts), so the
+ * heal in readManifest cannot write an older snapshot over this write. The wait is
+ * bounded, and longer than the stale age, so a lock left by a dead process is broken
+ * inside it. A lock that is still not taken after that wait cannot be broken, and
+ * the lock then protects nothing: the toggle goes ahead without it rather than refuse
+ * an explicit switch. Just before its write the toggle checks that the lock directory is
+ * still its own; when another caller took it, the toggle takes the lock again, at most
+ * {@link MANIFEST_LOCK_ATTEMPTS} times and within the same wait, and then goes ahead
+ * without it.
  */
 export async function writeMachineFeature(devflowDir, feature, enabled) {
+    const deadline = Date.now() + MANIFEST_LOCK_WAIT_MS;
+    for (let attempt = 0; attempt < MANIFEST_LOCK_ATTEMPTS; attempt++) {
+        const timeoutMs = Math.max(0, deadline - Date.now());
+        const locked = await withManifestLock(devflowDir, { timeoutMs }, (lock) => recordMachineFeature(devflowDir, feature, enabled, lock.stillHeld));
+        if (!locked.ok)
+            break;
+        if (locked.value !== LOCK_LOST)
+            return locked.value;
+    }
+    return recordMachineFeature(devflowDir, feature, enabled);
+}
+/**
+ * How many times a toggle takes the lock when it finds, just before its write, that
+ * another caller took the lock directory from it (manifest-lock.ts). The tries share
+ * the one wait, {@link MANIFEST_LOCK_WAIT_MS}. After them the toggle goes ahead without
+ * the lock, as it does when the wait ends.
+ */
+const MANIFEST_LOCK_ATTEMPTS = 3;
+/** `recordMachineFeature` did not write: the lock was taken from this toggle first. */
+const LOCK_LOST = 'lock-lost';
+async function recordMachineFeature(devflowDir, feature, enabled, stillHeld) {
     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' };
+    if (stillHeld !== undefined && !(await stillHeld()))
+        return LOCK_LOST;
     await writeFileAtomicExclusive(path.join(devflowDir, 'manifest.json'), JSON.stringify(next, null, 2) + '\n');
     return { ok: true, value: undefined };
 }

package/dist/core/fs-atomic.js

@@ -6,7 +6,7 @@ import { promises as fs } from 'fs';
  *
  * Call sites: used by the CLI's exclusive-write call sites (migrations, init, post-install,
  * uninstall, security, ambient, memory, HUD).
- * The CJS counterpart (`writeExclusive` in `src/assets/scripts/hooks/lib/learning-store.cjs`)
+ * The CJS counterpart (`writeExclusive` in `src/assets/scripts/hooks/lib/curation-store.cjs`)
  * intentionally remains a separate implementation — same semantics, different module
  * system. Any change to the retry logic here MUST be mirrored there.
  */

package/dist/core/gate-level.js

@@ -17,12 +17,20 @@ import { describeEchoedValue } from './echo-value.js';
  * diff.
  *
  * A present value that is not one of the three words is MALFORMED. A reader reads
- * it as `full` and leaves it on disk as written: no read and no unrelated write
- * heals it to absent, which would lower the level without a word.
+ * it as {@link MALFORMED_GATE_LEVEL_READS_AS} and leaves it on disk as written: no
+ * read and no unrelated write heals it to absent, which would lower the level
+ * without a word.
  */
 export const GATE_LEVELS = Object.freeze(['full', 'standard', 'lean']);
 /** The level when neither the personal file nor the manifest records one. */
 export const DEFAULT_GATE_LEVEL = 'standard';
+/**
+ * The level every reader gives a MALFORMED value: the strictest, so a typo never
+ * lowers the checking. `devflow gates` and the init prompt show it from here. The
+ * settings resolver (`resolve-settings.cjs`) folds to the same level in its own
+ * copy, and a parity test holds the two to each other.
+ */
+export const MALFORMED_GATE_LEVEL_READS_AS = 'full';
 /**
  * Largest manifest read, in bytes. Pinned by a parity test to the resolver
  * library's MAX_MANIFEST_BYTES, so the CLI and a prompt never disagree about a

package/dist/core/git.js

@@ -24,13 +24,25 @@ export function isTrunkBranch(branch) {
     return TRUNK_BRANCH_PREFIXES.some(p => branch.startsWith(p));
 }
 /**
- * Get git repository root directory (async, non-blocking)
- * Returns null if not in a git repository
+ * The repository root named by the output of `git rev-parse --show-toplevel`, or null
+ * when the output is not one clean absolute path.
  *
- * Security: Validates output to prevent command injection
+ * Security: validates output to prevent command injection
  * - Rejects paths with injection characters (newlines, semicolons, shell operators)
  * - Ensures path is absolute
  * - Resolves path canonically
+ */
+export function parseGitToplevel(stdout) {
+    const gitRootRaw = stdout.trim();
+    if (!gitRootRaw || gitRootRaw.includes('\n') || gitRootRaw.includes(';') || gitRootRaw.includes('&&')) {
+        return null;
+    }
+    const gitRoot = path.resolve(gitRootRaw);
+    return path.isAbsolute(gitRoot) ? gitRoot : null;
+}
+/**
+ * Get git repository root directory (async, non-blocking)
+ * Returns null if not in a git repository
  *
  * @param cwd - Directory to resolve the git root from. Defaults to process.cwd().
  *   Callers that already carry an explicit working directory must pass it, otherwise
@@ -42,17 +54,7 @@ export async function getGitRoot(cwd = process.cwd()) {
             cwd,
             encoding: 'utf-8'
         });
-        const gitRootRaw = stdout.trim();
-        // Validate git root path (security: prevent injection)
-        if (!gitRootRaw || gitRootRaw.includes('\n') || gitRootRaw.includes(';') || gitRootRaw.includes('&&')) {
-            return null;
-        }
-        // Validate it's an absolute path
-        const gitRoot = path.resolve(gitRootRaw);
-        if (!path.isAbsolute(gitRoot)) {
-            return null;
-        }
-        return gitRoot;
+        return parseGitToplevel(stdout);
     }
     catch {
         return null;

package/dist/core/ledger-root.js

@@ -1,12 +1,12 @@
 /**
  * @file ledger-root.ts
  *
- * Where the learning ledger lives for a working directory — the TypeScript twin of
+ * Where the curation ledger lives for a working directory — the TypeScript twin of
  * `df_resolve_roots`' DF_LEDGER_ROOT in src/assets/scripts/hooks/resolve-project-root.
  *
  * D-LEDGER-MAIN-WORKTREE: the ledger is one per REPOSITORY, not per checkout. In a
  * linked worktree the hooks queue and render into the main worktree's
- * `.devflow/learning/`, so `devflow learning` and the HUD must read and clear that
+ * `.devflow/curation/`, so `devflow curation` and the HUD must read and clear that
  * same directory — resolving the worktree's own toplevel (getGitRoot) would show an
  * empty ledger and drain a queue nothing writes to. The rule, from ONE git call:
  *
@@ -18,8 +18,11 @@
  *   - two absolute lines otherwise → the toplevel;
  *   - git before 2.31 echoes `--path-format=absolute` back as its own line → the
  *     toplevel it printed after it (the hooks fall back to the toplevel too);
- *   - git failed (not a work tree) → null: the caller keeps its non-git fallback;
- *   - any other output → getGitRoot(), the hooks' df_resolve_root fallback.
+ *   - git failed (not a work tree) → null: the caller keeps its non-git fallback; git
+ *     that did not answer within the caller's time budget → null too (`lookupLedgerRoot`
+ *     tells the two apart);
+ *   - any other output → `git rev-parse --show-toplevel` alone, the hooks' df_resolve_root
+ *     fallback, with the same time budget as the first call.
  *
  * Memory is NOT resolved here: working memory stays per checkout (getGitRoot).
  * Parity with the shell helper is pinned by tests/core/ledger-root.test.ts, which
@@ -29,9 +32,24 @@ import { execFile } from 'child_process';
 import { promises as fs } from 'fs';
 import * as os from 'os';
 import * as path from 'path';
-import { getGitRoot } from './git.js';
+import { parseGitToplevel } from './git.js';
+/**
+ * The budget of one ledger-root lookup, in ms: the HUD's per-git-command budget
+ * (src/hud/git.ts GIT_TIMEOUT). The HUD and the init move pass it as `timeoutMs`, so a
+ * project on a hung mount costs a bounded wait (one budget for each of the lookup's two
+ * git calls at most) and never stalls the rest.
+ */
+export const LEDGER_ROOT_TIMEOUT_MS = 1000;
+/**
+ * How long past its timeout a git call may stay unanswered before the lookup stops
+ * waiting for it: the timeout's own kill needs the process to die, and a process stuck
+ * in I/O on a hung mount may not.
+ */
+const KILL_GRACE_MS = 500;
 /** The one git call, as argv (no shell). */
 const LEDGER_ROOT_GIT_ARGS = ['rev-parse', '--path-format=absolute', '--show-toplevel', '--git-common-dir'];
+/** The fallback git call, as argv (no shell): the toplevel alone, as the hooks' df_resolve_root asks. */
+const TOPLEVEL_GIT_ARGS = ['rev-parse', '--show-toplevel'];
 /** What git before 2.31 prints first: the flag it does not know, echoed back. */
 const PATH_FORMAT_ECHO = '--path-format=absolute';
 /** Classify the git call's stdout. Pure. */
@@ -45,12 +63,37 @@ export function parseLedgerRootOutput(stdout) {
     }
     return { kind: 'unrecognised' };
 }
-/** stdout of the one git call from `cwd`, or null when git failed. */
-function runRevParse(cwd, timeoutMs) {
+/**
+ * Run `git <args>` from `cwd`. With a timeout the call is bounded twice: Node kills git
+ * at `timeoutMs`, and the lookup stops waiting KILL_GRACE_MS later even if git is still
+ * alive (and kills it then), so a process stuck on a hung mount cannot hold the caller.
+ * Never rejects.
+ */
+function runGit(args, cwd, timeoutMs) {
     return new Promise((resolve) => {
-        execFile('git', LEDGER_ROOT_GIT_ARGS, { cwd, timeout: timeoutMs, encoding: 'utf-8' }, (err, stdout) => {
-            resolve(err ? null : stdout);
+        let settled = false;
+        let backstop;
+        const settle = (run) => {
+            if (settled)
+                return;
+            settled = true;
+            if (backstop !== undefined)
+                clearTimeout(backstop);
+            resolve(run);
+        };
+        const child = execFile('git', [...args], { cwd, timeout: timeoutMs, encoding: 'utf-8' }, (err, stdout) => {
+            if (!err)
+                settle({ kind: 'ok', stdout });
+            else
+                settle(timeoutMs > 0 && err.killed === true ? { kind: 'timed-out' } : { kind: 'failed' });
         });
+        if (timeoutMs > 0) {
+            backstop = setTimeout(() => {
+                child.kill('SIGKILL');
+                settle({ kind: 'timed-out' });
+            }, timeoutMs + KILL_GRACE_MS);
+            backstop.unref();
+        }
     });
 }
 /** A path's physical location, or null when it cannot be resolved. */
@@ -76,27 +119,44 @@ async function mainHoldsLedger(main, home) {
     return mainReal !== null && mainReal !== homeReal;
 }
 /**
- * The learning ledger root for `cwd` — the main worktree or this checkout's
- * toplevel — or null outside a git work tree.
+ * The curation ledger root for `cwd`, saying why when there is none: git named no work
+ * tree (`no-root`), or did not answer in time (`timed-out`). Each of the two git calls
+ * (the main one and the fallback) gets `options.timeoutMs`; 0 or none waits for ever.
  */
-export async function getLedgerRoot(cwd = process.cwd(), options = {}) {
-    const stdout = await runRevParse(cwd, options.timeoutMs ?? 0);
-    if (stdout === null)
-        return null;
-    const parsed = parseLedgerRootOutput(stdout);
+export async function lookupLedgerRoot(cwd = process.cwd(), options = {}) {
+    const timeoutMs = options.timeoutMs ?? 0;
+    const run = await runGit(LEDGER_ROOT_GIT_ARGS, cwd, timeoutMs);
+    if (run.kind === 'timed-out')
+        return { kind: 'timed-out' };
+    if (run.kind === 'failed')
+        return { kind: 'no-root' };
+    const parsed = parseLedgerRootOutput(run.stdout);
     switch (parsed.kind) {
         case 'toplevel':
-            return parsed.toplevel;
-        case 'unrecognised':
-            return getGitRoot(cwd);
+            return { kind: 'root', root: parsed.toplevel };
+        case 'unrecognised': {
+            const fallback = await runGit(TOPLEVEL_GIT_ARGS, cwd, timeoutMs);
+            if (fallback.kind === 'timed-out')
+                return { kind: 'timed-out' };
+            const toplevel = fallback.kind === 'ok' ? parseGitToplevel(fallback.stdout) : null;
+            return toplevel === null ? { kind: 'no-root' } : { kind: 'root', root: toplevel };
+        }
         case 'roots': {
             if (!parsed.commonDir.endsWith('/.git'))
-                return parsed.toplevel;
+                return { kind: 'root', root: parsed.toplevel };
             const main = parsed.commonDir.slice(0, -'/.git'.length);
             if (main && await mainHoldsLedger(main, options.home ?? os.homedir()))
-                return main;
-            return parsed.toplevel;
+                return { kind: 'root', root: main };
+            return { kind: 'root', root: parsed.toplevel };
         }
     }
 }
+/**
+ * The curation ledger root for `cwd` — the main worktree or this checkout's
+ * toplevel — or null outside a git work tree (or when git did not answer in time).
+ */
+export async function getLedgerRoot(cwd = process.cwd(), options = {}) {
+    const lookup = await lookupLedgerRoot(cwd, options);
+    return lookup.kind === 'root' ? lookup.root : null;
+}
 //# sourceMappingURL=ledger-root.js.map

package/dist/core/linked-path.js

@@ -12,17 +12,17 @@ import { promises as fs } from 'fs';
  * D-CLI-NO-SYMLINK: the CLI writes or deletes under a project's `.devflow/` only
  * where neither `.devflow` nor the entry it acts on through it is a symbolic link:
  * `devflow init` stamps its carve-out marker, removes the legacy markers and
- * writes `.devflow/config.json` only then, `devflow learning --configure` writes
- * the project's `learning.json` only then, and the queue drains (`devflow learning
+ * writes `.devflow/config.json` only then, `devflow curation --configure` writes
+ * the project's `curation.json` only then, and the queue drains (`devflow curation
  * --clear|--disable`, `devflow memory --disable|--clear` and `devflow init
- * --no-learning|--no-memory`) delete nothing when `.devflow` or the queue's folder
+ * --no-curation|--no-memory`) delete nothing when `.devflow` or the queue's folder
  * is one. `devflow uninstall`, removing a legacy local install, deletes or rewrites
  * nothing under the project's `.devflow` or `.claude` where either, or anything
  * below it on the way to what it removes, is one (legacyLocalChangeGuard in
  * uninstall.ts). Reason: a repository can commit `.devflow`, or a folder or file in
  * it, as a link to any place on the machine, and a write or delete through one lands
  * wherever it points. The hooks hold the same rule (D-HOOKS-NO-SYMLINK, git-marker)
- * and so do the learning ops (D-NO-LINKED-TREE). Only paths below the project root
+ * and so do the curation ops (D-NO-LINKED-TREE). Only paths below the project root
  * are passed here: the root and the folders above it are the user's choice.
  *
  * Each path is checked with lstat, so a link is seen rather than followed. Nothing at