devflow-kit 2.5.0 → 3.0.0

package/dist/core/hook-log-dirs.js

@@ -0,0 +1,104 @@
+import { promises as fs } from 'fs';
+import * as path from 'path';
+/**
+ * @file hook-log-dirs.ts
+ *
+ * The cap on the hooks' per-directory log folders.
+ *
+ * D-LOG-DIR-CAP: every hook logs under `~/.devflow/logs/<slug>/`, one directory
+ * per working directory a session ran in (`log-paths`' devflow_log_dir). Left
+ * uncapped they pile up — a machine was found holding 31k of them, most left by
+ * test runs in throwaway temp directories — so `devflow init` keeps the
+ * {@link MAX_HOOK_LOG_DIRS} most recently written and removes the rest, oldest
+ * first. A folder's recency is the newest mtime among the folder and the log
+ * files in it: a log that is only ever appended to leaves the folder's own mtime
+ * where the file's creation put it, so the folder mtime alone would rank the
+ * busiest project as the oldest.
+ *
+ * Every pass is bounded — at most {@link MAX_LOG_DIRS_SCANNED} folders read and
+ * {@link MAX_LOG_DIRS_PRUNED_PER_RUN} removed. The two bounds are equal, so one
+ * init clears every folder it scanned beyond the cap: a 31k backlog costs that
+ * init about seven seconds (roughly 2.2 s per 10,000 removals), and only a
+ * backlog larger than the scan bound is finished by the next init. The pass is
+ * the one-time cleanup of an existing backlog and the standing cap alike.
+ * Only directories are touched: files at the logs root (`proxy.log`) and symbolic
+ * links are left alone.
+ */
+/** How many hook log folders survive a prune — the most recently written ones. */
+export const MAX_HOOK_LOG_DIRS = 200;
+/** The most folders one prune reads; beyond it the rest wait for a later run. */
+export const MAX_LOG_DIRS_SCANNED = 100_000;
+/** The most folders one prune removes — every scanned folder, so one run clears what it read. */
+export const MAX_LOG_DIRS_PRUNED_PER_RUN = MAX_LOG_DIRS_SCANNED;
+/** The most entries read inside one folder to find its newest log. */
+const MAX_FILES_READ_PER_DIR = 64;
+/** Folders stat'ed or removed at once. */
+const IO_CHUNK = 64;
+/** The newest mtime among `dir` and the entries in it; -Infinity when unreadable. */
+async function recencyOf(dir) {
+    let newest;
+    try {
+        newest = (await fs.lstat(dir)).mtimeMs;
+    }
+    catch {
+        return -Infinity;
+    }
+    let names;
+    try {
+        names = (await fs.readdir(dir)).slice(0, MAX_FILES_READ_PER_DIR);
+    }
+    catch {
+        return newest;
+    }
+    const times = await Promise.all(names.map(name => fs.lstat(path.join(dir, name)).then(st => st.mtimeMs, () => -Infinity)));
+    return Math.max(newest, ...times);
+}
+/** Apply `fn` to every item, `IO_CHUNK` at a time. Bounded by `items.length`. */
+async function inChunks(items, fn) {
+    const out = [];
+    for (let i = 0; i < items.length; i += IO_CHUNK) {
+        out.push(...await Promise.all(items.slice(i, i + IO_CHUNK).map(fn)));
+    }
+    return out;
+}
+/**
+ * Remove the oldest hook log folders under `logsDir` beyond the cap
+ * (D-LOG-DIR-CAP). Never throws: a missing logs directory is nothing to do, and
+ * a folder that cannot be removed is counted as still over the cap.
+ */
+export async function pruneHookLogDirs(logsDir, opts = {}) {
+    const keep = opts.keep ?? MAX_HOOK_LOG_DIRS;
+    const maxRemovals = opts.maxRemovals ?? MAX_LOG_DIRS_PRUNED_PER_RUN;
+    const maxScanned = opts.maxScanned ?? MAX_LOG_DIRS_SCANNED;
+    if (!path.isAbsolute(logsDir) || path.basename(logsDir) !== 'logs') {
+        return { ok: false, error: `not a devflow logs directory: ${logsDir}` };
+    }
+    if (keep < 0 || maxRemovals < 0 || maxScanned < 0) {
+        return { ok: false, error: 'prune bounds must be non-negative' };
+    }
+    let entries;
+    try {
+        entries = await fs.readdir(logsDir, { withFileTypes: true });
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return { ok: true, value: { removed: 0, overCap: 0 } };
+        return { ok: false, error: err instanceof Error ? err.message : String(err) };
+    }
+    const dirs = entries
+        .filter(e => e.isDirectory())
+        .slice(0, maxScanned)
+        .map(e => path.join(logsDir, e.name));
+    if (dirs.length <= keep)
+        return { ok: true, value: { removed: 0, overCap: 0 } };
+    const recencies = await inChunks(dirs, recencyOf);
+    const oldestFirst = dirs
+        .map((dir, i) => ({ dir, recency: recencies[i] }))
+        .sort((a, b) => a.recency - b.recency);
+    const overCap = oldestFirst.slice(0, oldestFirst.length - keep);
+    const batch = overCap.slice(0, maxRemovals);
+    const outcomes = await inChunks(batch, ({ dir }) => fs.rm(dir, { recursive: true, force: true }).then(() => true, () => false));
+    const removed = outcomes.filter(Boolean).length;
+    return { ok: true, value: { removed, overCap: overCap.length - removed } };
+}
+//# sourceMappingURL=hook-log-dirs.js.map

package/dist/core/learning-tuning-config.js

@@ -57,13 +57,15 @@ function readConfigFile(filePath) {
  * Priority (highest wins): project config → global config → defaults.
  *
  * - Global:  `~/.devflow/learning.json`
- * - Project: `<cwd>/.devflow/learning/learning.json`
+ * - Project: `<ledgerRoot>/.devflow/learning/learning.json` — pass the ledger root
+ *   (getLedgerRoot), where session-start-context reads it and `devflow learning
+ *   --configure` writes it (D-LEDGER-MAIN-WORKTREE).
  *
  * Invalid JSON in either file is silently ignored and treated as absent.
  */
-export function loadLearningTuningConfig(cwd) {
+export function loadLearningTuningConfig(ledgerRoot) {
     const globalConfigPath = path.join(getDevFlowDirectory(), 'learning.json');
-    const projectConfigPath = getLearningTuningConfigPath(cwd);
+    const projectConfigPath = getLearningTuningConfigPath(ledgerRoot);
     let config = { ...DEFAULTS };
     const globalJson = readConfigFile(globalConfigPath);
     if (globalJson !== null) {

package/dist/core/ledger-root.js

@@ -0,0 +1,102 @@
+/**
+ * @file ledger-root.ts
+ *
+ * Where the learning 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
+ * 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:
+ *
+ *   git rev-parse --path-format=absolute --show-toplevel --git-common-dir
+ *
+ *   - exactly two absolute lines, the common dir ends in `/.git`, `<main>/.devflow`
+ *     is a directory and `<main>` is not HOME (physical paths, like the hooks'
+ *     df_is_project_root) → `<main>`;
+ *   - 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.
+ *
+ * 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
+ * runs df_resolve_roots on the same fixtures.
+ */
+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';
+/** The one git call, as argv (no shell). */
+const LEDGER_ROOT_GIT_ARGS = ['rev-parse', '--path-format=absolute', '--show-toplevel', '--git-common-dir'];
+/** 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. */
+export function parseLedgerRootOutput(stdout) {
+    const lines = stdout.replace(/\n$/, '').split('\n');
+    if (lines.length === 2 && lines.every(l => path.isAbsolute(l))) {
+        return { kind: 'roots', toplevel: lines[0], commonDir: lines[1] };
+    }
+    if (lines.length === 3 && lines[0] === PATH_FORMAT_ECHO && path.isAbsolute(lines[1])) {
+        return { kind: 'toplevel', toplevel: lines[1] };
+    }
+    return { kind: 'unrecognised' };
+}
+/** stdout of the one git call from `cwd`, or null when git failed. */
+function runRevParse(cwd, timeoutMs) {
+    return new Promise((resolve) => {
+        execFile('git', LEDGER_ROOT_GIT_ARGS, { cwd, timeout: timeoutMs, encoding: 'utf-8' }, (err, stdout) => {
+            resolve(err ? null : stdout);
+        });
+    });
+}
+/** A path's physical location, or null when it cannot be resolved. */
+async function physical(target) {
+    try {
+        return await fs.realpath(target);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Whether the main worktree `main` holds the ledger: it has a `.devflow/` directory
+ * and is not HOME. An unresolvable `main` is refused (the ledger stays in this
+ * checkout); an unresolvable HOME cannot equal it, so it refuses nothing — both as
+ * df_is_project_root decides.
+ */
+async function mainHoldsLedger(main, home) {
+    const stat = await fs.stat(path.join(main, '.devflow')).catch(() => null);
+    if (!stat?.isDirectory())
+        return false;
+    const [mainReal, homeReal] = await Promise.all([physical(main), physical(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.
+ */
+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);
+    switch (parsed.kind) {
+        case 'toplevel':
+            return parsed.toplevel;
+        case 'unrecognised':
+            return getGitRoot(cwd);
+        case 'roots': {
+            if (!parsed.commonDir.endsWith('/.git'))
+                return parsed.toplevel;
+            const main = parsed.commonDir.slice(0, -'/.git'.length);
+            if (main && await mainHoldsLedger(main, options.home ?? os.homedir()))
+                return main;
+            return parsed.toplevel;
+        }
+    }
+}
+//# sourceMappingURL=ledger-root.js.map

package/dist/core/manifest.js

@@ -75,7 +75,6 @@ export async function readManifest(devflowDir) {
         const features = data.features;
         if (!data.version ||
             !Array.isArray(data.plugins) ||
-            !data.scope ||
             typeof features !== 'object' ||
             features === null ||
             typeof features.ambient !== 'boolean' ||
@@ -84,7 +83,7 @@ export async function readManifest(devflowDir) {
             typeof data.updatedAt !== 'string') {
             return null;
         }
-        // D-FEATURES-ABSENT-ON (a sub-decision of D-FEATURES-MACHINE-WIDE,
+        // D-FEATURES-ABSENT-ON (a sub-decision of D-FEATURES-NARROW-ONLY,
         // src/core/feature-switch.ts): knowledge and learning are machine-wide
         // switches, and every runtime gate — queue_read_gates in the hooks,
         // isMachineFeatureOn in the CLI, the knowledge write-back prose gate — reads
@@ -135,7 +134,8 @@ export async function readManifest(devflowDir) {
         const manifest = {
             version: data.version,
             plugins: data.plugins,
-            scope: data.scope,
+            // D-MANIFEST-SCOPE-PINNED: the on-disk value is not consulted.
+            scope: 'user',
             knownPlugins,
             features: {
                 ambient: features.ambient,
@@ -194,7 +194,9 @@ export async function readManifest(devflowDir) {
 export async function writeManifest(devflowDir, data) {
     await fs.mkdir(devflowDir, { recursive: true });
     const manifestPath = path.join(devflowDir, 'manifest.json');
-    await writeFileAtomicExclusive(manifestPath, JSON.stringify(data, null, 2) + '\n');
+    // D-MANIFEST-SCOPE-PINNED: every write records 'user', whatever the caller holds.
+    const pinned = { ...data, scope: 'user' };
+    await writeFileAtomicExclusive(manifestPath, JSON.stringify(pinned, null, 2) + '\n');
 }
 /**
  * Update a single feature field in the manifest. No-op when no manifest exists.

package/dist/core/mds-variants.js

@@ -306,11 +306,10 @@ export const PR_HOST_OPS = [
  * from the module that writes there: it is a fact about where PR mechanics live
  * in the reference tree, not something the registry can work out.
  *
- * Not to be confused with {@link PR_HOST_TRACKER_SUBDIR} (`tracker/github`),
- * which is the TRACKER directory every install carries because PR hosting is on
- * GitHub. This one is the provider-independent `pr/` directory itself — it is
- * under no provider, and every install carries it for the same reason: a jira or
- * linear user still opens pull requests.
+ * It is the provider-independent `pr/` directory, a sibling of the `tracker/`
+ * tree rather than a directory inside it: it is under no provider, and every
+ * install carries it because a jira or linear user still opens pull requests on
+ * GitHub.
  */
 export const PR_HOST_DESTINATION_ROOT = 'pr';
 /**
@@ -418,20 +417,6 @@ export const VARIANT_MODULES = [
 export const MCP_BACKED_PROVIDER_SUBDIRS = ['tracker/jira', 'tracker/linear'];
 /** The destination directory every tracker provider module lands under. */
 export const TRACKER_DESTINATION_ROOT = 'tracker';
-/**
- * The tracker destination every install carries, whatever the user selected.
- *
- * Not a default and not a fallback: PR hosting stays on GitHub under every
- * issue-tracker provider, so a jira or linear user still runs `gh pr` mechanics
- * and still needs the GitHub tree reachable. It is the FLOOR of
- * {@link installedReferenceManifest}'s union.
- *
- * Stated rather than derived, because the fact is about where pull requests
- * live, not about anything the registry knows. A derivation from "the one
- * CLI-backed module" would read as a rule and silently promote the next
- * CLI-backed provider into everyone's install.
- */
-export const PR_HOST_TRACKER_SUBDIR = `${TRACKER_DESTINATION_ROOT}/github`;
 /**
  * The provider-independent tool-call contract document.
  *
@@ -668,93 +653,44 @@ export function expandVariants(modules = resolveVariantModules()) {
  * build's own refusal sinks use (scripts/build-mds.ts).
  */
 export function generatedReferenceManifest() {
-    const expanded = expandVariants();
-    if (!expanded.ok) {
-        throw new Error(`Reference module registry does not expand — ${JSON.stringify(expanded.error)}. ` +
-            `VARIANT_MODULES in src/core/mds-variants.ts is invalid.`);
-    }
-    return expanded.value.map(pair => pair.relPath);
+    return expandedManifest(resolveVariantModules());
 }
 /**
- * The references ONE install carries, for one resolved tracker provider — the
- * narrower manifest the overlay converges to.
- *
- * D-INSTALL-SET: the BUILD emits every provider ({@link generatedReferenceManifest},
- * 42 files) because the tarball must be able to serve any selection without a
- * rebuild. An INSTALL carries `{github} ∪ {selected provider}`:
- *
- *   - the GitHub tree is the FLOOR under every provider, not an optional extra.
- *     PR hosting stays on GitHub whatever the issue tracker is, so those
- *     mechanics stay reachable for a jira or linear user;
- *   - the cross-cutting documents (`subdir: ''`) are provider-independent and
- *     always land;
- *   - the PR-host tree ({@link PR_HOST_DESTINATION_ROOT}) is provider-independent
- *     for the same reason the GitHub tree is a floor — pull requests, PR reviews
- *     and PR checks stay on GitHub under every issue tracker — but it sits under
- *     no provider directory, so it is named here rather than reached through the
- *     provider union;
- *   - a provider directory the user did not select is 11 files nothing they can
- *     reach ever loads (applies ADR-003 — ship the end state, not every state).
- *
- * `tracker/_mcp.md` rides the same gate its GENERATION does
- * ({@link MCP_BACKED_PROVIDER_SUBDIRS}): it is the transport contract for
- * providers reached by tool call, and GitHub's mechanics are `gh` commands. One
- * predicate, asked of the selection here and of the registry in
- * {@link mcpContractIsGenerated}, so opening the gate and shipping the provider
- * stay the same edit.
- *
- * Derived from the registry rather than a provider table: a provider registered
- * with a `tracker/{id}` subdir is installable by construction, and a literal
- * here would be a second roster to keep in step with VARIANT_MODULES.
+ * The references ONE install carries — the manifest the overlay converges to.
+ *
+ * D-INSTALL-ALL-PROVIDERS: an install carries exactly what the build emits
+ * ({@link generatedReferenceManifest}): every provider's tree, the PR-host tree,
+ * the cross-cutting documents and `tracker/_mcp.md`, whatever the machine selected.
+ * The provider is no longer a property of the install. A repository selects its
+ * own tracker in its committed `.devflow/project.json`, so one machine meets more
+ * than one provider and a Git spawn must find the mechanics of whichever one the
+ * repository resolves — an install scoped to the machine's selection would leave
+ * every such repository degraded until someone re-ran init for a provider that is
+ * not theirs. The trees are INERT until a spawn resolves a provider and names
+ * one of its files, so carrying all of them costs disk, never context.
+ *
+ * The overlay still PRUNES everything under its converged subtrees this manifest
+ * does not name, so a retired generated document leaves on the next install.
  *
  * Asserts rather than degrades on a registry that does not expand, exactly as
  * its sibling does (design review M3): the registry is a compile-time constant,
- * so a refusal is a programming error rather than an install-time degradation —
- * no caller could sensibly continue, and every caller would otherwise carry the
- * same impossible branch.
- *
- * @param opts.provider - The resolved tracker provider id, used as the
- *   `tracker/{id}` sub-directory key.
- * @param opts.modules - Registry to expand (defaults to the shipped one).
- *   Injectable so both the refusal arm and a provider set this build does not
- *   produce are provable without editing the registry.
+ * so a refusal is a programming error rather than an install-time degradation.
+ *
+ * @param opts.modules - Registry to expand (defaults to the shipped one, with the
+ *   gated contract module resolved). Injectable so the refusal arm is provable
+ *   without editing the registry.
  */
-export function installedReferenceManifest(opts) {
-    const modules = opts.modules ?? resolveVariantModules();
+export function installedReferenceManifest(opts = {}) {
+    return expandedManifest(opts.modules ?? resolveVariantModules());
+}
+/** Every relPath a registry expands to, or the assertion both manifests share. */
+function expandedManifest(modules) {
     const expanded = expandVariants(modules);
     if (!expanded.ok) {
         throw new Error(`Reference module registry does not expand — ${JSON.stringify(expanded.error)}. ` +
             `VARIANT_MODULES in src/core/mds-variants.ts is invalid.`);
     }
-    const providerSubdir = `${TRACKER_DESTINATION_ROOT}/${opts.provider}`;
-    const wanted = new Set(['', PR_HOST_DESTINATION_ROOT, PR_HOST_TRACKER_SUBDIR, providerSubdir]);
-    const installed = expanded.value
-        .filter(pair => wanted.has(subdirOfRelPath(pair.relPath)))
-        .map(pair => pair.relPath);
-    const gated = MCP_BACKED_PROVIDER_SUBDIRS;
-    if (gated.includes(providerSubdir)) {
-        const contract = contractRelPath(expanded.value);
-        if (contract !== undefined)
-            installed.push(contract);
-    }
-    return installed;
-}
-/** The directory part of a manifest-relative path; `''` for a file at the root. */
-function subdirOfRelPath(relPath) {
-    const cut = relPath.lastIndexOf('/');
-    return cut < 0 ? '' : relPath.slice(0, cut);
-}
-/**
- * The tool-call contract's emitted path, as this registry expands it — read from
- * the expansion rather than composed from the module's fields, so the name can
- * only ever be the one the build actually writes.
- *
- * Takes the already-expanded pairs rather than re-expanding: the caller has
- * already validated the same registry expands cleanly, so a second call would
- * only duplicate that work and reintroduce a refusal branch that can never fire.
- */
-function contractRelPath(pairs) {
-    return pairs.find(pair => pair.module === MCP_CONTRACT_MODULE.source)?.relPath;
+    return expanded.value.map(pair => pair.relPath);
 }
 // ---------------------------------------------------------------------------
 // Section splitting — which slice of a module's compiled body belongs to which op
@@ -792,8 +728,9 @@ export const VARIANT_SECTION_MARKER_RE = /^<!-- op: (_?[a-z0-9][a-z0-9._-]{0,63}
  *
  * empty-section is the third arm, and it exists because the other two cannot see
  * it: an op with a marker and no body compiles cleanly and emits a zero-byte
- * reference, which reads downstream as "mechanics unavailable" with no build
- * signal at all (the GAP-44 shape — omission is caught, emptiness is not).
+ * reference, which the agent then loads as an operation with no instructions,
+ * with no build signal at all (the GAP-44 shape — omission is caught, emptiness
+ * is not).
  *
  * Total on success, and immutable: the caller gets back a readonly array of its
  * OWN records, in its own order, each carrying its section. Nothing is looked up

package/dist/core/migrations.js

@@ -10,10 +10,10 @@
  */
 import { promises as fs } from 'fs';
 import * as path from 'path';
-import * as os from 'os';
 import { writeFileAtomicExclusive } from './fs-atomic.js';
 import { getMemoryDir } from './project-paths.js';
 import { LEGACY_AGENT_KEYS, canonicaliseAgentKeys, parseAgentMappingEnvelope } from './agent-models.js';
+import { migrateLegacyTrackerConventions } from './tracker.js';
 /**
  * D31: Registry pattern over scattered `if (!applied.includes(...))` conditionals.
  *
@@ -94,23 +94,48 @@ export const MIGRATIONS = [
             return { infos, warnings };
         },
     },
+    {
+        id: 'tracker-conventions-per-provider-v1',
+        description: 'Move ~/.devflow/tracker.md to ~/.devflow/tracker/{provider}.md, the provider its frontmatter names',
+        scope: 'global',
+        // D-TRACKER-PER-PROVIDER-CONVENTIONS: conventions became per provider, so the
+        // single machine-wide file moves to the file of the provider it was learned
+        // for. The move and every refusal to move are migrateLegacyTrackerConventions'
+        // (src/core/tracker.ts); this entry maps its outcome onto the runner's
+        // contract. A file it leaves in place is REPORTED, once, and the migration is
+        // marked applied — the file is user content and nothing a re-run could do
+        // differently. An I/O failure THROWS instead: a throwing migration is not
+        // marked applied, so the runner retries it on the next `devflow init` rather
+        // than recording a move that never happened (the retry-forever path the
+        // KNOWN ISSUE above describes is bounded here by what can fail — a rename and
+        // an rm inside ~/.devflow).
+        async run(ctx) {
+            const outcome = await migrateLegacyTrackerConventions(ctx.devflowDir);
+            switch (outcome.kind) {
+                case 'none':
+                    return { infos: [], warnings: [] };
+                case 'moved':
+                    return { infos: [`Moved the ${outcome.provider} tracker conventions to ${outcome.to}`], warnings: [] };
+                case 'kept':
+                    return { infos: [], warnings: [`tracker-conventions-per-provider-v1: ${outcome.reason}`] };
+                case 'failed':
+                    throw new Error(outcome.error);
+                default: {
+                    const _exhaustive = outcome;
+                    return _exhaustive;
+                }
+            }
+        },
+    },
 ];
 const MIGRATIONS_FILE = 'migrations.json';
 /**
- * D30: State lives at `~/.devflow/migrations.json` (scope-independent) rather
- * than the install manifest because:
- *
- * - The install manifest is scope-specific: user-scope manifests live at
- *   `~/.devflow/manifest.json` while local-scope manifests live at
- *   `.devflow/manifest.json` inside the repo. A migration that runs on user-scope
- *   init wouldn't be recorded in a local-scope manifest, so the migration would
- *   re-run on the next local-scope init.
- * - Migration state is machine-wide: once a global migration runs on a machine it
- *   should never re-run regardless of which project or scope triggered devflow init.
- * - `~/.devflow/migrations.json` is always writable (home-dir location), whereas
- *   local-scope devflowDir may be inside a read-only checkout.
+ * D30: State lives at `~/.devflow/migrations.json` rather than in the install
+ * manifest because migration state is machine-wide: once a global migration runs
+ * on a machine it should never re-run regardless of which project triggered
+ * devflow init.
  *
- * @param devflowDir - absolute path to `~/.devflow` (always the home-dir location)
+ * @param devflowDir - absolute path to the resolved machine root (`~/.devflow`)
  */
 export async function readAppliedMigrations(devflowDir) {
     const filePath = path.join(devflowDir, MIGRATIONS_FILE);
@@ -227,7 +252,7 @@ async function runGlobalMigration(migration, ctx) {
  * additional projects) can retry the failed projects.
  *
  * D37: runPerProjectMigration is unreachable in production — MIGRATIONS holds
- * only a global migration (`canonicalise-agent-keys-v1`). The vacuous-truth
+ * only global migrations. The vacuous-truth
  * analysis is preserved for correctness: if a per-project migration is ever
  * added, an empty discoveredProjects list marks it applied (empty-discovery-marks-applied
  * intended); the applied-set write is skipped only when newlyApplied is empty,
@@ -267,19 +292,20 @@ async function runPerProjectMigration(migration, ctx, discoveredProjects) {
  * Run all unapplied migrations from MIGRATIONS.
  *
  * D32: Always-run-unapplied semantics (no fresh-vs-upgrade branch).
- * MIGRATIONS currently holds one global migration (`canonicalise-agent-keys-v1`);
- * on a fresh machine the loop executes once and writes migrations.json. On
- * subsequent runs the ID is already in the applied set and the loop is a no-op.
+ * MIGRATIONS currently holds only global migrations; on a fresh machine each
+ * executes once and the applied set is written to migrations.json. On subsequent
+ * runs every ID is already in the applied set and the loop is a no-op.
  *
- * @param ctx - devflowDir (memoryDir and projectRoot filled per-project)
+ * @param ctx - devflowDir, the resolved machine root (`~/.devflow`) that also holds
+ *   migrations.json; memoryDir and projectRoot are filled per-project
  * @param discoveredProjects - absolute paths to discovered Claude-enabled project roots
  * @param registryOverride - override MIGRATIONS for testing (defaults to module-level MIGRATIONS)
  */
 export async function runMigrations(ctx, discoveredProjects, registryOverride) {
     const registry = registryOverride ?? MIGRATIONS;
-    // Always read from home-dir devflow location so state is machine-wide
-    const homeDevflowDir = path.join(os.homedir(), '.devflow');
-    const appliedArray = await readAppliedMigrations(homeDevflowDir);
+    // D-ONE-HOME: state lives in the caller's resolved machine root, never a
+    // second, independently derived home path (D30: machine-wide state).
+    const appliedArray = await readAppliedMigrations(ctx.devflowDir);
     // Convert to Set once for O(1) lookups throughout the loop (issue #9)
     const applied = new Set(appliedArray);
     const newlyApplied = [];
@@ -323,7 +349,7 @@ export async function runMigrations(ctx, discoveredProjects, registryOverride) {
     }
     // Write state once at end, accumulating all newly applied IDs (issue #5 — O(N²) → O(1))
     if (newlyApplied.length > 0) {
-        await writeAppliedMigrations(homeDevflowDir, [...appliedArray, ...newlyApplied]);
+        await writeAppliedMigrations(ctx.devflowDir, [...appliedArray, ...newlyApplied]);
     }
     return { newlyApplied, failures, infos, warnings };
 }

package/dist/core/plugins.js

@@ -492,7 +492,8 @@ export const FEATURE_OWNED_RULES = ['compliance'];
  * command-less plugin, so a reference to one is a reference to something the
  * user may deliberately not have. The referencing prompts are written to probe
  * first and proceed without it — `/code-review` checks
- * `~/.claude/skills/devflow:{focus}/SKILL.md` before spawning that focus, the
+ * `skills/devflow:{focus}/SKILL.md` under Claude Code's directory (`CLAUDE_CONFIG_DIR`
+ * when absolute, else `~/.claude` — D-CLAUDE-DIR-PROMPTS) before spawning that focus, the
  * Review and Code agents continue when the Skill invocation fails. Putting them
  * in a `requires` would reinstate the universal install for exactly the eight
  * skills the selection prompt exists to let a user decline (AC-25).
@@ -832,9 +833,9 @@ export const WORKFLOW_ORDER = [
 ];
 /**
  * Plugin names excluded from the init multiselect buckets.
- * These are always installed regardless of user selection:
+ * init adds them itself rather than offering them:
  *   - devflow-core-skills  (always installed, non-optional)
- *   - devflow-ambient      (always installed, non-optional)
+ *   - devflow-ambient      (installed iff ambient mode is on — D-AMBIENT-FOLLOWS-SWITCH)
  *
  * Invariant: EXCLUDED ∩ optional === ∅ — no optional plugin may be excluded from
  * the init UI without a re-init carry mechanism to preserve it across full reinstalls.
@@ -847,7 +848,7 @@ export const EXCLUDED = new Set(['devflow-core-skills', 'devflow-ambient']);
  *
  * Excluded from both buckets (not selectable at init):
  *   - devflow-core-skills  (always installed)
- *   - devflow-ambient      (always installed)
+ *   - devflow-ambient      (installed iff ambient mode is on)
  *
  * Pure function — does not mutate the input array; preserves DEVFLOW_PLUGINS
  * ordering within each bucket; deterministic; no I/O.

package/dist/core/project-paths.js

@@ -139,21 +139,4 @@ export function getResearchDir(projectRoot) {
 export function getHandoffPath(projectRoot, branchSlug) {
     return path.join(projectRoot, '.devflow', 'docs', `handoff-${branchSlug}.md`);
 }
-// ---------------------------------------------------------------------------
-// Gitignore entries (returned as string arrays for updateGitignore callers)
-// ---------------------------------------------------------------------------
-/**
- * The canonical list of generic gitignore entries Devflow adds to a project's
- * root .gitignore for LOCAL-scope installs. Currently just `.claude/`.
- *
- * `.devflow/` is intentionally NOT here: it is managed by ensureDevflowGitignore
- * (TS) / ensure-root-gitignore (hook), which write the feature-knowledge carve-out
- * for ALL scopes. Adding a bare `.devflow/` here would append a wholesale-ignore
- * line after the carve-out and re-bury it (last match wins in .gitignore).
- *
- * CJS mirror: src/assets/scripts/hooks/lib/project-paths.cjs getGitignoreEntries().
- */
-export function getGitignoreEntries() {
-    return ['.claude/'];
-}
 //# sourceMappingURL=project-paths.js.map

package/dist/core/same-location.js

@@ -0,0 +1,25 @@
+import { promises as fs } from 'fs';
+import * as path from 'path';
+/**
+ * Whether two paths name one location — realpaths where they exist, so a symlinked
+ * HOME, or macOS's /var → /private/var temp tree, still matches. The shell hooks make
+ * the same physical comparison in git-marker's df_is_project_root (D-HOOKS-GIT-ONLY).
+ */
+export async function isSameLocation(a, b) {
+    const canonical = (target) => fs.realpath(target).catch(() => path.resolve(target));
+    const [left, right] = await Promise.all([canonical(a), canonical(b)]);
+    return left === right;
+}
+/**
+ * D-INIT-NOT-HOME: the CLI half of D-HOOKS-GIT-ONLY. A git repository rooted at
+ * HOME (a dotfiles repo) is not a project: its `<root>/.devflow` is the machine
+ * root ~/.devflow, and its `.gitignore` and `.claudeignore` are the user's own
+ * home-directory files. So no command writes per-repository files there — the
+ * same rule the hooks' df_is_project_root applies — and `roots` is returned
+ * without any entry that is HOME.
+ */
+export async function withoutHomeRoots(roots, homeDir) {
+    const verdicts = await Promise.all(roots.map(root => isSameLocation(root, homeDir)));
+    return roots.filter((_, i) => !verdicts[i]);
+}
+//# sourceMappingURL=same-location.js.map