devflow-kit 2.4.0 → 3.0.0

package/dist/commands/self-review.md

@@ -24,16 +24,28 @@ Detect changed files and build context:
 4. Build TASK_DESCRIPTION from recent commit messages or branch name
 ### Load DECISIONS_CONTEXT
 
-Resolve the worktree root using the `devflow:worktree-support` algorithm (use WORKTREE_PATH if provided, otherwise cwd). All paths below are relative to `{worktree}`.
+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
+git -C "{start}" rev-parse --path-format=absolute --show-toplevel --git-common-dir
+```
+
+Line 1 is the checkout's toplevel, line 2 the repository's common git directory. A git older than 2.31 echoes `--path-format=absolute` back as a line of its own first. `{ledger}` is the first of these that applies:
+
+1. **The main worktree** — line 2 without its trailing `/.git`, when the output is exactly two lines each beginning with `/`, line 2 ends in `/.git`, and the directory left once it is removed is not your home directory and contains a `.devflow/` directory.
+2. **The toplevel** — line 1, or on an older git the line after the echoed flag.
+3. **The start directory itself** — when the command failed or printed no absolute toplevel (outside a git repository).
+
+This is the rule the learning hooks apply (D-LEDGER-MAIN-WORKTREE, D-PROMPT-ROOT), so you read the index the Learning agent writes.
 
 **Step 1 — Read the pre-rendered index:**
 
-Attempt to read `{worktree}/.devflow/learning/index.md`.
+Attempt to read `{ledger}/.devflow/learning/index.md`.
 
 - If the file exists and contains non-empty content: use that content as `DECISIONS_CONTEXT`.
 - If the file is absent or empty: set `DECISIONS_CONTEXT` to `(none)`.
 
-**No subprocess, no `.cjs` script.** This is a single direct file read — the index is written at render time by `render-decisions.cjs` alongside `decisions.md`/`pitfalls.md`.
+The index is one direct file read, written at render time by `render-decisions.cjs` alongside `decisions.md`/`pitfalls.md` — no `.cjs` script runs here, and the index's own footer names the files that hold each entry's full body.
 
 **Step 2 — Apply decisions using `devflow:apply-decisions`:**
 
@@ -43,7 +55,13 @@ Pass `DECISIONS_CONTEXT` to Scrutinize agent — the compact index lists active
 
 ### Load Feature Knowledge
 
-Resolve the worktree root using the `devflow:worktree-support` algorithm (use WORKTREE_PATH if provided, otherwise cwd). All paths below are relative to `{worktree}`.
+Resolve `{worktree}` as the checkout's toplevel, because feature knowledge bases are committed with the branch (D-PROMPT-ROOT): from the start directory — `WORKTREE_PATH` if provided, otherwise cwd (`devflow:worktree-support`) — run
+
+```bash
+git -C "{start}" rev-parse --show-toplevel
+```
+
+and use its one-line output. If the command fails (outside a git repository), `{worktree}` is the start directory itself. All paths below are relative to `{worktree}`.
 
 **Step 1 — Read the index cache:**
 
@@ -78,7 +96,7 @@ Concatenate the selected KNOWLEDGE.md files under slug headers:
 
 If no KBs exist, no KBs are relevant, or `.devflow/features/` is absent, set `FEATURE_KNOWLEDGE` to `(none)`.
 
-**No subprocess, no git calls, no `.cjs` script.** This entire step is direct file reads — 1 index read (or N frontmatter reads on fallback), bounded by KB count.
+**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.
 
 Pass `FEATURE_KNOWLEDGE` to Scrutinize agent.
 
@@ -165,13 +183,27 @@ Display summary:
 
 ### Feature Knowledge Write-Back (Conditional)
 
-Resolve the worktree root using the `devflow:worktree-support` algorithm (use WORKTREE_PATH if provided, otherwise cwd). All paths below are relative to `{worktree}`.
+Resolve `{worktree}` as the checkout's toplevel, because feature knowledge bases are committed with the branch (D-PROMPT-ROOT): from the start directory — `WORKTREE_PATH` if provided, otherwise cwd (`devflow:worktree-support`) — run
 
-**Step 1 — Check the opt-out gate:**
+```bash
+git -C "{start}" rev-parse --show-toplevel
+```
 
-Read `{worktree}/.devflow/config.json`. If the `knowledge` field is `false`, skip write-back entirely — the user has disabled it.
+and use its one-line output. If the command fails (outside a git repository), `{worktree}` is the start directory itself. All paths below are relative to `{worktree}`.
 
-If `.devflow/config.json` does not exist, proceed (default is enabled).
+**Step 1 — Check the opt-out gate, with `{root}` = `{worktree}`:**
+
+**Resolve the settings line** once per worktree root, reusing a line this run already resolved for the same root. `{root}` is the worktree the values are for — the repository root when the run has one worktree:
+
+```bash
+node "$HOME/.devflow/scripts/resolve-settings.cjs" "{root}" 2>/dev/null; echo "exit=$?"
+```
+
+Accept the output only when it is exactly two lines: `exit=0` last and, before it, one line of the form `TRACKER=<github|jira|linear> TRACKER_SOURCE=<project|personal|machine|default> TRACKER_WARN=<none|mismatch|invalid> SITE=<none|https://<host>> KEY=<none|<key>> REVIEW_PUBLICATION=<off|auto|full> COMPLIANCE=<off|generic|<id>[,<id>…]> MEMORY=<on|off> LEARNING=<on|off> KNOWLEDGE=<on|off>` — these fields, in this order, nothing else, where `<host>` is a lowercase dotted host name alone, `<key>` is 2–10 of `A-Z`, `0-9` and `_` starting with a letter, and each `<id>` is one of `gdpr`, `hipaa`, `pci-dss`, `soc2`, `iso-27001`, `sox`. **Anything else** (a non-zero exit, no line, extra text, or a missing, reordered or unlisted field or value) ⇒ use `TRACKER=github TRACKER_SOURCE=default TRACKER_WARN=invalid SITE=none KEY=none REVIEW_PUBLICATION=off COMPLIANCE=generic MEMORY=on LEARNING=on KNOWLEDGE=off` instead.
+
+The accepted line is the only source of these values: the script alone folds the committed `.devflow/project.json`, the personal `.devflow/config.json` and the machine manifest.
+
+If the settings line says `KNOWLEDGE=off`, skip write-back entirely. The machine switch (`devflow knowledge --disable`), the repository and the personal settings can each turn knowledge off, and none can turn it back on (D-FEATURES-NARROW-ONLY). The fail-closed line says `KNOWLEDGE=off` too, so an unresolvable line skips write-back.
 
 **Step 2 — Evaluate whether write-back is warranted:**
 
@@ -210,6 +242,10 @@ The frontmatter in KNOWLEDGE.md is the source of truth — index.md is only a ca
 After writing, commit the two files to the current worktree branch yourself by running git via your Bash tool (do not use a script). Stage ONLY .devflow/features/index.md and .devflow/features/{slug}/KNOWLEDGE.md, then commit just those paths with a docs(knowledge): message. Do NOT push, do NOT force, do NOT stage anything else. Follow your Commit Protocol — it is non-blocking, so if any git step fails, report KB_COMMIT and finish normally."
 ```
 
+**Step 4 — Surface an uncommitted knowledge base:**
+
+When the Knowledge agent reports `KB_COMMIT: skipped (detached HEAD)`, the files were written but deliberately not committed — a commit on a detached HEAD becomes unreachable once HEAD moves. Tell the user in the workflow's final report, in one line, that the knowledge base was written but not committed, and name the uncommitted paths the agent listed, so they can commit them on a branch before the worktree is removed. Never commit them yourself.
+
 **Failure handling**: Non-blocking. If the Knowledge agent fails, log the failure and continue — the workflow outcome is not affected by write-back success.
 
 ## Architecture

package/dist/core/agent-models.js

@@ -27,7 +27,7 @@ import * as path from 'path';
 import { writeFileAtomicExclusive } from './fs-atomic.js';
 import { isDormantExternalModel } from './external-models.js';
 import { rewriteAgentFrontmatter, readFrontmatterModel, isValidModelName } from './agent-frontmatter.js';
-import { agentsDir } from './assets.js';
+import { agentSourceDirs } from './assets.js';
 import { getAllAgentNames } from './plugins.js';
 import { mdEntryName, mdFileName } from './orphan-sweep.js';
 import { isContainedIn } from './paths.js';
@@ -359,26 +359,27 @@ export function resolveEffective(agentName, mapping, shippedDefaults, proxyEnabl
 // loadShippedDefaults
 // ---------------------------------------------------------------------------
 /**
- * Load shipped default models from the source agent files.
- * Reads every file in agentsDir() and parses the frontmatter model field.
- * Unknown or malformed files are silently skipped.
+ * Parse the shipped model default out of every {name}.md in one directory.
+ *
+ * A missing or unreadable directory yields an empty map — dist/agents/ does not
+ * exist until a generator host does, and a source tree that produced no agents
+ * is caught by the registry-completeness guard rather than by a throw here.
+ * Unknown or malformed files are skipped individually.
  */
-export async function loadShippedDefaults() {
-    const sourceDir = agentsDir();
-    const defaults = {};
+async function readDirDefaults(dir) {
     let entries;
     try {
-        entries = await fs.readdir(sourceDir);
+        entries = await fs.readdir(dir);
     }
     catch {
-        return defaults;
+        return {};
     }
     const pairs = await Promise.all(entries.map(async (file) => {
         const agentName = mdEntryName(file);
         if (agentName === null)
             return null;
         try {
-            const content = await fs.readFile(path.join(sourceDir, file), 'utf-8');
+            const content = await fs.readFile(path.join(dir, file), 'utf-8');
             const result = readFrontmatterModel(content);
             if (result.ok && result.value) {
                 return [agentName, result.value];
@@ -389,6 +390,7 @@ export async function loadShippedDefaults() {
         }
         return null;
     }));
+    const defaults = {};
     for (const pair of pairs) {
         if (pair !== null) {
             defaults[pair[0]] = pair[1];
@@ -396,11 +398,51 @@ export async function loadShippedDefaults() {
     }
     return defaults;
 }
+/**
+ * Load shipped default models from the agent files.
+ *
+ * Directories are MOST-PREFERRED FIRST — the convention owned by
+ * agentSourceDirs() — and the first directory to supply a name wins, so once an
+ * agent is generated into dist/agents/ its frontmatter is the shipped default.
+ *
+ * A registry agent that no directory supplies is reported through `onWarning`
+ * as ONE aggregate message naming every missing agent and the build step. The
+ * installer throws on the same invariant; this is a read path whose callers must
+ * keep rendering (`devflow agents --list`), so it warns instead. Staying silent
+ * is what makes the gap dangerous: resolveEffective returns an undefined model,
+ * reapplyAgentMapping buckets the agent 'unchanged', and disabling the proxy
+ * leaves an externally-pinned agent unreverted with nothing said (PF-022).
+ *
+ * @param dirs - Agent directories, most-preferred first. Injectable so tests can
+ *   prove the precedence against a temp tree; all real callers use the default.
+ * @param opts - Optional warning channel; the gap is silent without one.
+ */
+export async function loadShippedDefaults(dirs = agentSourceDirs(), opts) {
+    const perDir = await Promise.all(dirs.map(readDirDefaults));
+    const defaults = {};
+    for (const dirDefaults of perDir) {
+        for (const [agentName, model] of Object.entries(dirDefaults)) {
+            if (!(agentName in defaults)) {
+                defaults[agentName] = model;
+            }
+        }
+    }
+    const missing = getAllAgentNames().filter(name => !(name in defaults));
+    if (missing.length > 0) {
+        opts?.onWarning?.(`No shipped default found for declared agent(s): ${missing.join(', ')}. ` +
+            `Run \`npm run build:mds\` if they are compiled from .mds generator hosts, otherwise ` +
+            `ensure the agent files exist in src/assets/agents/ (searched: ${dirs.join(', ')}).`);
+    }
+    return defaults;
+}
 /**
  * Idempotent convergence function: walk every installed agent file and
  * rewrite frontmatter model/effort to match the effective mapping.
  *
- * - Reads shipped defaults LIVE from src/assets/agents/ sources.
+ * - Reads shipped defaults LIVE from the agent sources — agentSourceDirs(),
+ *   dist/agents/ preferred over src/assets/agents/. An agent no source supplies
+ *   is reported through the warning channel rather than passing as 'unchanged'
+ *   with no explanation.
  * - Gets the agent name list from the registry (getAllAgentNames()) plus
  *   any mapping entries for agents not in the registry.
  * - Missing installed files → skip silently (recorded in skippedMissing).
@@ -419,7 +461,7 @@ export async function reapplyAgentMapping(opts) {
         return { updated: [], unchanged: [], skippedMissing: [], invalidMapping: [], warnings };
     }
     const mapping = mappingResult.value;
-    const shippedDefaults = await loadShippedDefaults();
+    const shippedDefaults = await loadShippedDefaults(opts.agentSourceDirs, { onWarning: warn });
     // Build the union of: all registered agent names + all names in the mapping
     // (so agents not yet in the registry but configured are also processed).
     const registryNames = new Set(getAllAgentNames());
@@ -525,6 +567,7 @@ export async function revertExternalAgents(opts) {
         installDir: opts.installDir,
         devflowDir: opts.devflowDir,
         proxyEnabled: false,
+        agentSourceDirs: opts.agentSourceDirs,
         onWarning: opts.onWarning,
     });
 }

package/dist/core/assets.js

@@ -1,5 +1,6 @@
 import { join } from 'path';
 import { getPackageRoot } from './paths.js';
+import { SKILL_REFS_OUTPUT_DIR } from './mds-variants.js';
 /**
  * Flat skills source directory: src/assets/skills/{name}/
  * All plugins' skills live here directly (no per-plugin subdirectory).
@@ -10,9 +11,13 @@ export function skillsDir() {
 /**
  * Flat agents source directory: src/assets/agents/{name}.md
  * All plugins' agents live here directly.
+ *
+ * @param root - Package root to resolve against. Injectable so a caller working
+ *   on a temp tree (the test harness) reads the layout from here rather than
+ *   spelling the path itself.
  */
-export function agentsDir() {
-    return join(getPackageRoot(), 'src', 'assets', 'agents');
+export function agentsDir(root = getPackageRoot()) {
+    return join(root, 'src', 'assets', 'agents');
 }
 /**
  * Flat rules source directory: src/assets/rules/{name}.md
@@ -36,4 +41,55 @@ export function scriptsDir() {
 export function commandsDir() {
     return join(getPackageRoot(), 'dist', 'commands');
 }
+/**
+ * Compiled agents directory: dist/agents/{name}.md
+ *
+ * Output of the .mds generator hosts. The directory is absent until at least
+ * one generator host exists, so every reader must tolerate its absence.
+ *
+ * @param root - Package root to resolve against (see agentsDir).
+ */
+export function compiledAgentsDir(root = getPackageRoot()) {
+    return join(root, 'dist', 'agents');
+}
+/**
+ * Compiled skill-reference directory: dist/skills/git/references/
+ *
+ * Output of the `.mds` reference modules — the generated `devflow:git` mechanics
+ * files, one per (provider, operation) pair under `tracker/{provider}/`. Like
+ * compiledAgentsDir(), the directory is absent until the build has run, so every
+ * reader must tolerate its absence.
+ *
+ * The spelling comes from SKILL_REFS_OUTPUT_DIR in src/core/mds-variants.ts —
+ * the build's own allowlist table — rather than being retyped here, so the
+ * destination has exactly one definition.
+ *
+ * @param root - Package root to resolve against (see agentsDir).
+ */
+export function compiledSkillRefsDir(root = getPackageRoot()) {
+    return join(root, ...SKILL_REFS_OUTPUT_DIR.split('/'));
+}
+/**
+ * Agent source directories, MOST-PREFERRED FIRST.
+ *
+ * The single owner of the dist-first agent-resolution policy: a generator
+ * host's compiled artifact in dist/agents/ supersedes a hand-authored file of
+ * the same name in src/assets/agents/. Every consumer reads the order from
+ * here — the installer's first-hit-wins resolve, loadShippedDefaults's
+ * first-wins merge, and the test harness's resolveAgentSource — so the
+ * convention is stated once and cannot drift apart between call sites.
+ *
+ * Order is invisible to the type system: a list spelled least-preferred-first
+ * still typechecks and silently inverts the answer. Consumers therefore take
+ * this list as-is and never re-spell it; tests/guards/agent-source-precedence
+ * pins that they agree.
+ *
+ * The non-empty tuple makes an empty list a compile error at every call site:
+ * an empty list would survive a `??` default and resolve to nothing.
+ *
+ * @param root - Package root to resolve against (see agentsDir).
+ */
+export function agentSourceDirs(root = getPackageRoot()) {
+    return [compiledAgentsDir(root), agentsDir(root)];
+}
 //# sourceMappingURL=assets.js.map

package/dist/core/compliance-compose.js

@@ -167,44 +167,44 @@ function collectMissingFragmentWarnings(fnName, activeFrameworks, fragments, omi
     }
     return warnings;
 }
+/**
+ * How a consumer picks framework references at run time (D-COMPLIANCE-REPO-LENS).
+ *
+ * Every framework reference is installed on every machine
+ * (D-COMPLIANCE-INSTALL-ALWAYS), so file presence no longer says which
+ * frameworks apply. The caller hands the agent `COMPLIANCE_FRAMEWORKS` — the
+ * `COMPLIANCE` field of the settings line, which folds this machine's selection
+ * with the repository's `.devflow/project.json` — and those ids alone are in force.
+ */
+const RUNTIME_SELECTION_LINES = [
+    'Every `references/{id}.md` is installed, so presence decides nothing: the ids you were given',
+    "(`COMPLIANCE_FRAMEWORKS`, this machine's plus the repository's) are the frameworks in force.",
+    'Load `references/{id}.md` for each given id and no other; `none` means generic controls only.',
+    'Apply generic controls always.',
+    '',
+    'NEVER fabricate framework-specific guidance for a framework you were not given.',
+];
 /**
  * Build the ${DEVFLOW_COMPLIANCE_ACTIVE} substitution — the body of the
  * Active Frameworks section.
  *
- * Active: lists frameworks + instructs loading reference files.
- * Zero: informs that generic controls only apply.
- *
- * File presence corroborates: note preserved so the agent keeps checking files.
+ * The stamp names the machine's own selection; zero frameworks is the neutral
+ * stamp a compliance-off machine's skill carries. Either way the section ends in
+ * RUNTIME_SELECTION_LINES, because the frameworks a run applies are the ids its
+ * caller passes, not the stamp.
  *
  * C5: a framework with no fragment still appears here — only its mapping row,
  * checklist item and reference row are omitted.
  *
- * Frameworks the registry cannot label are dropped entirely: neither the label nor the
- * `references/{id}.md` path is emitted (see resolveRegistryFrameworks).
+ * Frameworks the registry cannot label are dropped entirely: no label is emitted
+ * (see resolveRegistryFrameworks).
  */
 function buildActiveSection(activeFrameworks) {
     const resolved = resolveRegistryFrameworks(activeFrameworks);
-    if (resolved.length === 0) {
-        return [
-            'No framework-specific reference files are active. Apply generic controls only.',
-            '',
-            'NEVER fabricate framework-specific guidance for absent `references/{id}.md` files.',
-            'If no reference file is present for a framework, apply generic controls only.',
-        ].join('\n');
-    }
-    const labels = resolved.map(fw => fw.label);
-    const refList = resolved.map(fw => `\`references/${fw.id}.md\``).join(' and ');
-    return [
-        `**Active: ${labels.join(', ')}.**`,
-        '',
-        `Load ${refList} for framework-specific controls. Apply generic controls always.`,
-        '',
-        'File presence in the installed skill directory is the authoritative signal: if a',
-        '`references/{id}.md` file is absent, treat that framework as inactive regardless of',
-        'this list.',
-        '',
-        'NEVER fabricate framework-specific guidance for absent `references/{id}.md` files.',
-    ].join('\n');
+    const stamp = resolved.length === 0
+        ? 'The machine declares no framework.'
+        : `**Machine frameworks: ${resolved.map(fw => fw.label).join(', ')}.**`;
+    return [stamp, '', ...RUNTIME_SELECTION_LINES].join('\n');
 }
 /**
  * Build the ${DEVFLOW_COMPLIANCE_MAPPING} substitution — the ENTIRE Framework