devflow-kit 2.4.0 → 2.5.0

package/dist/targets/claude-code/legacy.js

@@ -7,6 +7,11 @@
  * Users who skip major versions should run uninstall + reinstall.
  *
  * Organized by era to make scanning for duplicates tractable.
+ *
+ * These lists are FROZEN deletion manifests for names that once shipped: the
+ * `*_V2` suffix is the frozen spelling of an era, not a version to bump, and a
+ * name is removed from a list only when its pruning window has passed — never
+ * renamed to match a current registry name (avoids PF-012).
  */
 /** Pre-v1.0.0: devflow- prefixed skill names from the original install scheme. */
 const LEGACY_SKILLS_PRE_V1 = [

package/dist/targets/claude-code/post-install.js

@@ -1,5 +1,5 @@
 import { promises as fs, writeFileSync, unlinkSync } from 'fs';
-import { execSync } from 'child_process';
+import { execFileSync } from 'child_process';
 import * as path from 'path';
 import * as os from 'os';
 import * as p from '@clack/prompts';
@@ -25,6 +25,28 @@ export function computeGitignoreAppend(existingContent, entries) {
     const existingLines = existingContent.split('\n').map(l => l.trim());
     return entries.filter(entry => !existingLines.includes(entry));
 }
+/**
+ * Sentinel line whose presence means the current (v3-and-later) carve-out block is
+ * installed. Devflow-unique: no user writes `!.devflow/conventions.md` by hand.
+ */
+const DEVFLOW_GITIGNORE_SENTINEL_V3 = '!.devflow/conventions.md';
+/** Sentinel line whose presence means the v2 carve-out block is installed (no conventions.md line). */
+const DEVFLOW_GITIGNORE_SENTINEL_V2 = '!.devflow/features/*/KNOWLEDGE.md';
+/**
+ * The block's final line: ignore the devflow-managed `.claudeignore` file.
+ * NOT a sentinel — users legitimately author this line themselves.
+ */
+const CLAUDEIGNORE_LINE = '.claudeignore';
+/** A user's explicit un-ignore of `.claudeignore`; never overridden. */
+const CLAUDEIGNORE_NEGATION = '!.claudeignore';
+/**
+ * Re-includes the team-owned evidence policy file (D-GITIGNORE-V5). A COMPLETION
+ * line, never a presence sentinel: users may author it themselves, so its presence
+ * proves nothing about the devflow block (avoids PF-059). It sits after `.devflow/*`
+ * (which it overrides under last-match-wins) and before `.claudeignore`, so the
+ * block's final line stays `.claudeignore`.
+ */
+const DEVFLOW_POLICY_LINE = '!.devflow/policy.json';
 /**
  * The shared .devflow/ gitignore block. Everything under .devflow/ is local
  * (memory, learning, docs, locks) EXCEPT:
@@ -32,6 +54,9 @@ export function computeGitignoreAppend(existingContent, entries) {
  *   + committed (the Knowledge agent commits them at workflow end).
  * - conventions.md: naming-convention authority written by the Git learn-conventions
  *   operation; GIT-TRACKED so the team shares a single naming source.
+ * - policy.json: the team-owned evidence policy, read from the default branch by
+ *   resolve-evidence-policy.cjs; GIT-TRACKED so a team can commit it without `git add -f`.
+ *   Devflow never writes it.
  *
  * Re-including files under an ignored tree needs a `dir/*` + `!dir/keep` pair at
  * each level — a bare `.devflow/` excludes the directory so git never descends and
@@ -39,65 +64,121 @@ export function computeGitignoreAppend(existingContent, entries) {
  *
  * Kept BYTE-IDENTICAL to the block emitted by src/assets/scripts/hooks/ensure-root-gitignore
  * so the init-time path and the always-on hook path produce the same file.
- *
- * D-GITIGNORE-V3: v3 of the carve-out block (adds !.devflow/conventions.md).
  */
-export const DEVFLOW_GITIGNORE_BLOCK = [
+const DEVFLOW_GITIGNORE_BLOCK_LINES = [
     '# Devflow runtime data — local by default (memory, learning, docs, locks).',
-    '# Two exceptions are shared via git: feature knowledge bases under .devflow/features/',
-    '# (index.md and every {slug}/KNOWLEDGE.md) and .devflow/conventions.md (naming',
-    '# authority). To stop sharing, re-add `.devflow/features/` or `.devflow/conventions.md`',
-    '# to your own .gitignore.',
+    '# Shared via git: feature knowledge bases under .devflow/features/ (index.md and',
+    '# every {slug}/KNOWLEDGE.md), .devflow/conventions.md (naming authority) and',
+    '# .devflow/policy.json (evidence policy). To stop sharing the first two, re-add',
+    '# `.devflow/features/` or `.devflow/conventions.md` to your own .gitignore.',
     '.devflow/*',
     '!.devflow/features/',
     '.devflow/features/*',
     '!.devflow/features/index.md',
     '!.devflow/features/*/',
     '.devflow/features/*/*',
-    '!.devflow/features/*/KNOWLEDGE.md',
-    '!.devflow/conventions.md',
-].join('\n');
-/** Sentinel line whose presence means the v3 carve-out block is installed. */
-const DEVFLOW_GITIGNORE_SENTINEL_V3 = '!.devflow/conventions.md';
-/** Sentinel line whose presence means the v2 carve-out block is installed (no conventions.md line). */
-const DEVFLOW_GITIGNORE_SENTINEL_V2 = '!.devflow/features/*/KNOWLEDGE.md';
+    DEVFLOW_GITIGNORE_SENTINEL_V2,
+    DEVFLOW_GITIGNORE_SENTINEL_V3,
+    DEVFLOW_POLICY_LINE,
+    CLAUDEIGNORE_LINE,
+];
+/** The full carve-out block, `.claudeignore` line included. */
+export const DEVFLOW_GITIGNORE_BLOCK = DEVFLOW_GITIGNORE_BLOCK_LINES.join('\n');
+/**
+ * The carve-out block without its final `.claudeignore` line — emitted instead of
+ * the full block when the target .gitignore already carries a `.claudeignore` or
+ * `!.claudeignore` entry of the user's own.
+ */
+export const DEVFLOW_GITIGNORE_BLOCK_WITHOUT_CLAUDEIGNORE = DEVFLOW_GITIGNORE_BLOCK_LINES.slice(0, -1).join('\n');
 /** The legacy wholesale comment our pre-carve-out writers emitted. */
 const LEGACY_DEVFLOW_COMMENT = '# Devflow runtime data (local by default; remove to share via git)';
 /**
  * PURE: given existing .gitignore content, return the content that ignores
- * `.devflow/` with the feature-knowledge + conventions.md carve-out — or `null`
- * when no change is needed. Idempotent: feeding its own output back returns `null`.
+ * `.devflow/` with the feature-knowledge + conventions.md + policy.json carve-out —
+ * or `null` when no change is needed. Idempotent: feeding its own output back returns `null`.
+ *
+ * D-GITIGNORE-V5: the block is detected ONLY by its own devflow-unique sentinel
+ * (`!.devflow/conventions.md`). `.claudeignore` and `!.devflow/policy.json` are
+ * COMPLETION lines — users legitimately author both themselves — so each is topped up
+ * when missing and never read as proof the block exists. A presence check on a
+ * user-authored line inverts both halves of the contract: projects that already carry
+ * that line are told the block is installed when it is not, and a user's
+ * `!.claudeignore` un-ignore is silently reversed by re-appending `.claudeignore`
+ * under last-match-wins (avoids PF-059).
+ *
+ * `hasClaudeignoreEntry` is true when some whole line, trimmed, is exactly
+ * `.claudeignore` OR `!.claudeignore`. Treating both forms as "present" both honours
+ * an un-ignore and makes every branch converge on re-run. `hasPolicyLine` is true when
+ * some whole line, trimmed, is exactly `!.devflow/policy.json`. The missing completion
+ * lines, in block order, are [policy line, `.claudeignore` (only when
+ * `!hasClaudeignoreEntry`)].
  *
- * - v3 sentinel already present → `null` (already at current format).
- * - User-authored `/.devflow/` (leading slash) present → `null` (respect manual config).
- * - v2 sentinel present but not v3 → UPGRADE: append just `!.devflow/conventions.md`.
- * - Legacy bare `.devflow/` present → strip it (+ our old comment), append the full block.
- * - Otherwise → append the full block (or the block alone when content is empty).
+ * 1. A `/.devflow/` line present → `null` (user opt-out; respect manual config).
+ * 2. v3 sentinel present → append the missing completion lines; `null` when none are
+ *    missing. This is the v4→v5 upgrade: a v4 block gains only the policy line, after
+ *    its `.claudeignore` line, and keeps its old comment.
+ * 3. v2 sentinel present, no v3 → append `!.devflow/conventions.md` followed by the
+ *    missing completion lines.
+ * 4. Legacy bare `.devflow/` present → strip it (+ our old comment), then append the
+ *    block; no block at all → append the block. The block is emitted MINUS its final
+ *    `.claudeignore` line when `hasClaudeignoreEntry`. A user's own policy line is
+ *    duplicated harmlessly here, and the re-run is a no-op.
+ * 5. Neither completion line is ever a sentinel. The marker file
+ *    (`.devflow/.root-gitignore-configured-v5`) is a fast-path claim, never proof.
+ *
+ * Line matching is whole-line, whitespace-tolerant, exact text — never substring.
+ * Both append forms are mirrored byte-for-byte in the shell twin
+ * (src/assets/scripts/hooks/ensure-root-gitignore), which is what the cross-implementation
+ * parity table in tests/shell-hooks.test.ts pins.
  */
 export function computeDevflowGitignore(existingContent) {
     const lines = existingContent.split('\n');
     const trimmed = lines.map(l => l.trim());
-    if (trimmed.includes(DEVFLOW_GITIGNORE_SENTINEL_V3))
-        return null;
-    if (trimmed.some(l => l === '/.devflow/'))
+    const hasClaudeignoreEntry = trimmed.some(l => l === CLAUDEIGNORE_LINE || l === CLAUDEIGNORE_NEGATION);
+    const hasPolicyLine = trimmed.includes(DEVFLOW_POLICY_LINE);
+    /** The block-completing lines this file lacks, in block order. */
+    const missingCompletionLines = [
+        ...(hasPolicyLine ? [] : [DEVFLOW_POLICY_LINE]),
+        ...(hasClaudeignoreEntry ? [] : [CLAUDEIGNORE_LINE]),
+    ];
+    /**
+     * Continue an existing devflow block with the lines it is missing. One newline
+     * guard, no blank separator — the appended lines belong to the block above them.
+     */
+    const appendLines = (body, block) => `${body}${body.endsWith('\n') ? '' : '\n'}${block}\n`;
+    /**
+     * Start a new block after unrelated content: one blank separator line. Existing
+     * trailing newlines are preserved verbatim (no trimEnd, no blank-line dedupe) so
+     * the shell twin's `tail -c 1` guard produces the identical bytes.
+     */
+    const appendBlock = (body, block) => body.length === 0
+        ? `${block}\n`
+        : `${body}${body.endsWith('\n') ? '' : '\n'}\n${block}\n`;
+    // 1. User opt-out wins over every sentinel.
+    if (trimmed.includes('/.devflow/'))
         return null;
-    // v2→v3 upgrade: v2 sentinel present, v3 sentinel absent → append the missing line only.
-    // Preserve existing trailing newlines byte-for-byte (matches shell twin's tail -c 1 guard).
+    // 2. Block installed (v3 and later) — top up only the completion lines it lacks.
+    if (trimmed.includes(DEVFLOW_GITIGNORE_SENTINEL_V3)) {
+        return missingCompletionLines.length === 0
+            ? null
+            : appendLines(existingContent, missingCompletionLines.join('\n'));
+    }
+    // 3. v2 block installed — append the lines it lacks, in block order.
     if (trimmed.includes(DEVFLOW_GITIGNORE_SENTINEL_V2)) {
-        const sep = existingContent.endsWith('\n') ? '' : '\n';
-        return `${existingContent}${sep}${DEVFLOW_GITIGNORE_SENTINEL_V3}\n`;
+        return appendLines(existingContent, [DEVFLOW_GITIGNORE_SENTINEL_V3, ...missingCompletionLines].join('\n'));
     }
-    const append = (body) => body.trimEnd()
-        ? `${body.trimEnd()}\n\n${DEVFLOW_GITIGNORE_BLOCK}\n`
-        : `${DEVFLOW_GITIGNORE_BLOCK}\n`;
-    if (trimmed.some(l => l === '.devflow/')) {
+    // 4. No devflow block — install one, respecting any .claudeignore entry of the user's own.
+    const block = hasClaudeignoreEntry
+        ? DEVFLOW_GITIGNORE_BLOCK_WITHOUT_CLAUDEIGNORE
+        : DEVFLOW_GITIGNORE_BLOCK;
+    if (trimmed.includes('.devflow/')) {
         // Upgrade our legacy wholesale entry: drop the bare line + old comment, append block.
         const kept = lines
             .filter(l => l.trim() !== '.devflow/' && l.trim() !== LEGACY_DEVFLOW_COMMENT)
             .join('\n');
-        return append(kept);
+        return appendBlock(kept, block);
     }
-    return append(existingContent);
+    return appendBlock(existingContent, block);
 }
 /**
  * Merge Devflow deny entries into an existing settings JSON object.
@@ -531,11 +612,14 @@ export async function installManagedSettings(rootDir, verbose) {
         return false;
     }
     try {
-        execSync(`sudo mkdir -p '${managedDir}'`, { stdio: 'inherit' });
-        // Write via sudo tee to avoid shell quoting issues with the JSON content
+        execFileSync('sudo', ['mkdir', '-p', managedDir], { stdio: 'inherit' });
+        // Stage the JSON in a file and copy it with sudo. Every sudo call takes an
+        // argv (execFileSync, no shell), so no path is ever re-parsed by a shell — a
+        // package root under a home directory holding a quote cannot break or extend
+        // the root command.
         const tmpFile = path.join(rootDir, '.managed-settings-tmp.json');
         await fs.writeFile(tmpFile, content, 'utf-8');
-        execSync(`sudo cp '${tmpFile}' '${managedPath}'`, { stdio: 'inherit' });
+        execFileSync('sudo', ['cp', tmpFile, managedPath], { stdio: 'inherit' });
         await fs.rm(tmpFile, { force: true });
         if (verbose) {
             p.log.success(`Managed settings written to ${managedPath} (via sudo)`);
@@ -557,14 +641,26 @@ export async function installManagedSettings(rootDir, verbose) {
  * 1. Try direct write/delete
  * 2. If EACCES and TTY, ask user before sudo
  * 3. Non-TTY: return false (caller logs preservation message)
+ *
+ * `managedPathOverride` exists so a test can point the removal at a temp file;
+ * production callers omit it and get the platform's system path. It is a
+ * parameter, deliberately not an environment variable: this function may run
+ * `sudo rm` / `sudo cp` on the path, and an env-selectable target would let
+ * whoever controls the environment aim a root write the user consented to for
+ * "managed settings" at any file.
  */
-export async function removeManagedSettings(rootDir, verbose) {
+export async function removeManagedSettings(rootDir, verbose, managedPathOverride) {
     let managedPath;
-    try {
-        managedPath = getManagedSettingsPath();
+    if (managedPathOverride !== undefined) {
+        managedPath = managedPathOverride;
     }
-    catch {
-        return false;
+    else {
+        try {
+            managedPath = getManagedSettingsPath();
+        }
+        catch {
+            return false;
+        }
     }
     let existingContent;
     try {
@@ -639,12 +735,12 @@ export async function removeManagedSettings(rootDir, verbose) {
     }
     try {
         if (shouldDelete) {
-            execSync(`sudo rm '${managedPath}'`, { stdio: 'inherit' });
+            execFileSync('sudo', ['rm', managedPath], { stdio: 'inherit' });
         }
         else {
             const tmpFile = path.join(rootDir, '.managed-settings-tmp.json');
             await fs.writeFile(tmpFile, updatedContent, 'utf-8');
-            execSync(`sudo cp '${tmpFile}' '${managedPath}'`, { stdio: 'inherit' });
+            execFileSync('sudo', ['cp', tmpFile, managedPath], { stdio: 'inherit' });
             await fs.rm(tmpFile, { force: true });
         }
         if (verbose) {
@@ -949,45 +1045,73 @@ export async function updateGitignore(gitRoot, verbose) {
         }
     }
 }
-/** Current carve-out marker version. Bump when the block format changes. */
-const GITIGNORE_MARKER_V3 = '.root-gitignore-configured-v3';
-/** Previous marker — removed when upgrading to v3. */
-const GITIGNORE_MARKER_V2 = '.root-gitignore-configured-v2';
+/**
+ * Current carve-out marker version. Bump when the block format changes — together
+ * with the shell twin's stamp (ensure-root-gitignore) and the ensure-devflow-init
+ * fast path, in one commit (D-GITIGNORE-V5).
+ */
+const GITIGNORE_MARKER_V5 = '.root-gitignore-configured-v5';
+/**
+ * Earlier markers, the unversioned (v1) one included — every one is removed
+ * whenever the project is v5-stamped, on the fast path too: an older devflow can
+ * re-stamp one beside v5, and the shell twin drops the same four.
+ */
+const LEGACY_GITIGNORE_MARKERS = [
+    '.root-gitignore-configured-v4',
+    '.root-gitignore-configured-v3',
+    '.root-gitignore-configured-v2',
+    '.root-gitignore-configured',
+];
+/** Remove every legacy marker; an absent one is a no-op. Call only once v5 is stamped. */
+async function removeLegacyGitignoreMarkers(devflowDir) {
+    for (const legacy of LEGACY_GITIGNORE_MARKERS) {
+        try {
+            await fs.rm(path.join(devflowDir, legacy), { force: true });
+        }
+        catch { /* ok if absent */ }
+    }
+}
 /**
  * Deterministically ensure the project root .gitignore applies the `.devflow/`
- * carve-out (local by default, feature knowledge + conventions.md shared via git).
+ * carve-out (local by default; feature knowledge, conventions.md and the evidence
+ * policy shared via git).
  *
  * Manages ONLY `.devflow/` — never `.claude/` — because user-scope installs must
  * not gitignore `.claude/`. This is the init-time counterpart to the always-on
- * src/assets/scripts/hooks/ensure-root-gitignore shell helper; both write the identical
- * DEVFLOW_GITIGNORE_BLOCK, so the two paths are byte-compatible and mutually
- * idempotent. Called unconditionally (independent of install scope and every
- * feature toggle) whenever a git root is known.
+ * src/assets/scripts/hooks/ensure-root-gitignore shell helper; both resolve the same
+ * shape for a given .gitignore — DEVFLOW_GITIGNORE_BLOCK, or
+ * DEVFLOW_GITIGNORE_BLOCK_WITHOUT_CLAUDEIGNORE when the project owns that entry — and
+ * emit identical bytes, so the two paths are byte-compatible and mutually idempotent.
+ * Called unconditionally (independent of install scope and every feature toggle)
+ * whenever a git root is known.
  *
- * Uses a versioned marker file (`.devflow/.root-gitignore-configured-v3`) for fast-path
- * detection — the same pattern as the shell twin. Bumping the version forces existing
- * installs to re-run once and upgrade their block (v2→v3: adds conventions.md line).
+ * Uses a versioned project-local marker file (`.devflow/.root-gitignore-configured-v5`)
+ * for fast-path detection — the same pattern as the shell twin. The marker is a claim,
+ * not proof, so even a marked install re-reads .gitignore and re-runs
+ * computeDevflowGitignore; bumping the version forces a re-run once per install, which
+ * is how a v4-marked project gains the policy line and is re-stamped v5.
  *
- * Idempotent: already-v3 installs return immediately (marker fast-path). Errors are
- * swallowed (verbose-logged) — a gitignore write must never abort init.
+ * Idempotent: computeDevflowGitignore returns null for a converged file, so a
+ * marked install performs one read and no write. Errors are swallowed
+ * (verbose-logged) — a gitignore write must never abort init.
  */
 export async function ensureDevflowGitignore(gitRoot, verbose) {
     try {
         const devflowDir = path.join(gitRoot, '.devflow');
-        const markerV3 = path.join(devflowDir, GITIGNORE_MARKER_V3);
+        const markerV5 = path.join(devflowDir, GITIGNORE_MARKER_V5);
         const gitignorePath = path.join(gitRoot, '.gitignore');
-        // Fast-path with verification: v3 marker normally means the block is installed,
+        // Fast-path with verification: v5 marker normally means the block is installed,
         // but the marker is a claim, not proof — a merge-conflict resolution may have
         // dropped the block. Even when the marker exists, read .gitignore (one cheap
         // read) and run computeDevflowGitignore; write only when it returns non-null.
-        // Idempotent: sentinel present → computeDevflowGitignore returns null → no write.
-        let v3Marked = false;
+        // Idempotent: converged file → computeDevflowGitignore returns null → no write.
+        let v5Marked = false;
         try {
-            await fs.access(markerV3);
-            v3Marked = true;
+            await fs.access(markerV5);
+            v5Marked = true;
         }
         catch { /* absent */ }
-        if (v3Marked) {
+        if (v5Marked) {
             let existingContent = '';
             try {
                 existingContent = await fs.readFile(gitignorePath, 'utf-8');
@@ -997,9 +1121,10 @@ export async function ensureDevflowGitignore(gitRoot, verbose) {
             if (healContent !== null) {
                 await fs.writeFile(gitignorePath, healContent, 'utf-8');
                 if (verbose) {
-                    p.log.success('.gitignore configured (.devflow/ local; feature knowledge + conventions shared)');
+                    p.log.success('.gitignore configured (.devflow/ local; feature knowledge + conventions + evidence policy shared)');
                 }
             }
+            await removeLegacyGitignoreMarkers(devflowDir);
             return;
         }
         let gitignoreContent = '';
@@ -1011,16 +1136,13 @@ export async function ensureDevflowGitignore(gitRoot, verbose) {
         if (newContent !== null) {
             await fs.writeFile(gitignorePath, newContent, 'utf-8');
             if (verbose) {
-                p.log.success('.gitignore configured (.devflow/ local; feature knowledge + conventions shared)');
+                p.log.success('.gitignore configured (.devflow/ local; feature knowledge + conventions + evidence policy shared)');
             }
         }
-        // Stamp v3 marker so subsequent runs fast-path; drop the legacy v2 marker.
+        // Stamp v5 marker so subsequent runs fast-path; drop every legacy marker.
         await fs.mkdir(devflowDir, { recursive: true });
-        await fs.writeFile(markerV3, '', 'utf-8');
-        try {
-            await fs.rm(path.join(devflowDir, GITIGNORE_MARKER_V2), { force: true });
-        }
-        catch { /* ok if absent */ }
+        await fs.writeFile(markerV5, '', 'utf-8');
+        await removeLegacyGitignoreMarkers(devflowDir);
     }
     catch (error) {
         if (verbose) {

package/dist/targets/claude-code/tracker-install.js

@@ -0,0 +1,161 @@
+/**
+ * Tracker artifact installer for the Claude Code target.
+ *
+ * Convergence function for the ONE artifact whose presence advertises the
+ * selected tracker provider: the Tracker agent file. The generated reference
+ * subtree converges too, but through {@link overlayInstalledReferences} in
+ * installer.ts — that is the installer's one overlay spelling, and a mode flag
+ * on this function would have made it a second (design review M2).
+ *
+ * Applies ADR-013: I/O orchestration in src/targets/; pure helpers in src/core/.
+ * Applies PF-009: warn-not-throw, so one failing artifact never aborts an install.
+ * Applies PF-015: the biconditional converges in BOTH directions — selecting a
+ * provider installs the agent, returning to github removes it.
+ */
+import { promises as fs } from 'fs';
+import * as path from 'path';
+import { agentSourceDirs } from '../../core/assets.js';
+import { mdFileName } from '../../core/orphan-sweep.js';
+/**
+ * The agent whose presence is conditional on the provider.
+ *
+ * It stays DECLARED in `devflow-core-skills.agents` and is filtered at install
+ * time rather than being lifted into a feature-owned set: the compliance
+ * precedent does not transfer, because compliance's plugin was deleted while
+ * `devflow-core-skills` is a live, non-optional owner. A feature-owned set would
+ * cost three new union sites and a rewrite of the pinned agent-roster floor to
+ * solve a problem the agent SWEEP does not have — the sweep keys on the full
+ * registry, so it never sees this file as an orphan.
+ *
+ * Exported because the filter has more than one reader and may have only one
+ * authority (D-TRACKER-AGENT-OWNER): {@link convergeTrackerArtifacts} below,
+ * which decides whether the file exists, and, in installer.ts, both the generic
+ * agent copy loop — which has to skip the one agent it does not own — and the
+ * full-install pre-clean, which has to empty the agent directory around it. A
+ * second literal at any of those sites is the shape this export exists to forbid.
+ */
+export const TRACKER_AGENT_NAME = 'tracker';
+// ── Internals ──────────────────────────────────────────────────────────────
+/**
+ * The provider whose mechanics need no Tracker agent.
+ *
+ * GitHub conventions are not inferred: the Git agent runs `gh`, whose issue
+ * grammar this repo already speaks. The agent exists to infer conventions from a
+ * connected tool-call server, which is a thing only the other providers have.
+ */
+const AGENTLESS_PROVIDER = 'github';
+function agentTarget(claudeDir) {
+    return path.join(claudeDir, 'agents', 'devflow', mdFileName(TRACKER_AGENT_NAME));
+}
+async function pathExists(p) {
+    try {
+        await fs.access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** First path in `candidates` that exists, or undefined when none do. */
+async function firstExisting(candidates) {
+    for (const candidate of candidates) {
+        if (await pathExists(candidate))
+            return candidate;
+    }
+    return undefined;
+}
+/**
+ * Would copying `source` over `target` change anything?
+ *
+ * Asked once, between resolving the source and copying it, so a run that would write a
+ * byte-identical copy of the installed agent reports `unchanged` instead of `installed`
+ * — the same question the reference overlay asks per unit, for the same reason: a
+ * summary that can only ever say "installed" says nothing, and a steady-state re-init
+ * announcing "tracker agent installed" is the noise this closes (QA S2).
+ *
+ * It does NOT weaken the self-heal. A hand-edited or truncated agent differs from its
+ * source, so it is copied and reported as written; only an identical file is skipped,
+ * and skipping a copy of what is already there changes nothing on disk.
+ *
+ * Any error — an absent target, an unreadable one — answers "no". The fallback is the
+ * copy that was going to happen anyway, so a failure to compare costs a write, never
+ * correctness.
+ */
+async function copyWouldChangeNothing(source, target) {
+    try {
+        const [from, to] = await Promise.all([fs.readFile(source), fs.readFile(target)]);
+        return from.equals(to);
+    }
+    catch {
+        return false;
+    }
+}
+// ── Convergence ────────────────────────────────────────────────────────────
+/**
+ * Converge the Tracker agent file onto the resolved provider.
+ *
+ * Convergence matrix:
+ *   provider !== github → copy the agent in, unless the installed file is already
+ *                         byte-identical to the source. Compared rather than trusted
+ *                         for existing, so a truncated or hand-edited file self-heals;
+ *                         compared rather than re-copied blind, so a run that changes
+ *                         nothing reports `unchanged` and the summary stays quiet
+ *                         (see {@link copyWouldChangeNothing})
+ *   provider === github → remove it, absent or not
+ *
+ * Never throws. A caller gates on `converged`; it does not catch. The one
+ * refusal that is not an I/O degradation — a claudeDir that is not absolute —
+ * is reported the same way rather than thrown, because it reaches here from a
+ * manifest read and an install must not die on it.
+ */
+export async function convergeTrackerArtifacts(opts) {
+    const { claudeDir, provider, warn } = opts;
+    // Precondition, asserted in production code rather than only in tests: an
+    // empty or relative claudeDir would make the target resolve somewhere
+    // unexpected, and the removal branch runs fs.rm against it.
+    if (!path.isAbsolute(claudeDir)) {
+        warn(`tracker: claudeDir is not an absolute path ("${claudeDir}") — skipping convergence`);
+        return { converged: false, agentPresent: false, agent: 'unchanged' };
+    }
+    const target = agentTarget(claudeDir);
+    if (provider === AGENTLESS_PROVIDER) {
+        const existed = await pathExists(target);
+        if (!existed)
+            return { converged: true, agentPresent: false, agent: 'unchanged' };
+        try {
+            await fs.rm(target, { force: true });
+        }
+        catch (err) {
+            warn(`tracker: failed to remove the Tracker agent (${target}) — ${String(err)}`);
+            return { converged: false, agentPresent: true, agent: 'unchanged' };
+        }
+        return { converged: true, agentPresent: false, agent: 'removed' };
+    }
+    const dirs = opts.agentSourceDirs ?? agentSourceDirs();
+    const candidates = dirs.map(dir => path.join(dir, mdFileName(TRACKER_AGENT_NAME)));
+    const source = await firstExisting(candidates);
+    if (source === undefined) {
+        warn(`tracker: agent source not found for "${TRACKER_AGENT_NAME}" (searched: ${candidates.join(', ')}) — ` +
+            `run \`npm run build:mds\` if it is compiled from an .mds generator host`);
+        // Probed rather than assumed: a previous run may have left a copy that is
+        // still spawnable, and that is the difference between "this run did nothing"
+        // and "there is nothing there".
+        return { converged: false, agentPresent: await pathExists(target), agent: 'unchanged' };
+    }
+    // Already converged — nothing to write, and nothing for the summary to announce.
+    // The directory is not created either: an identical file at the target means it is
+    // already there (see {@link copyWouldChangeNothing}).
+    if (await copyWouldChangeNothing(source, target)) {
+        return { converged: true, agentPresent: true, agent: 'unchanged' };
+    }
+    try {
+        await fs.mkdir(path.dirname(target), { recursive: true });
+        await fs.copyFile(source, target);
+    }
+    catch (err) {
+        warn(`tracker: failed to install the Tracker agent (${target}) — ${String(err)}`);
+        return { converged: false, agentPresent: await pathExists(target), agent: 'unchanged' };
+    }
+    return { converged: true, agentPresent: true, agent: 'installed' };
+}
+//# sourceMappingURL=tracker-install.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devflow-kit",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "description": "A meta-harness for Claude Code — turns a single coding agent into an engineering team: orchestration, parallel review, persistent memory, self-learning, and graph workflows",
   "type": "module",
   "bin": {
@@ -26,7 +26,8 @@
     "version:bump": "npx tsx scripts/bump-version.ts",
     "test": "vitest run",
     "test:watch": "vitest",
-    "test:integration": "vitest run --config vitest.integration.config.ts"
+    "test:integration": "vitest run --config vitest.integration.config.ts",
+    "test:golden:update": "npx tsx scripts/update-golden.ts"
   },
   "keywords": [
     "claude",
@@ -63,7 +64,7 @@
     "@clack/prompts": "^0.9.1",
     "commander": "^12.0.0",
     "picocolors": "^1.1.1",
-    "subswitch": "0.4.0"
+    "subswitch": "0.5.0"
   },
   "devDependencies": {
     "@mdscript/mds": "0.2.0",