devflow-kit 2.3.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`.
- *
- * - 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).
+ * `.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`)].
+ *
+ * 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) {
@@ -712,10 +808,95 @@ export async function stripUserSecurityDenyList(settingsPath) {
     await writeFileAtomicExclusive(settingsPath, stripped);
     return { removed };
 }
+/** True for a non-null, non-array object literal. */
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Every `command` string carried by a hook matcher, tolerating foreign shapes.
+ * Returns an empty array for anything that is not `{ hooks: [{ command: string }] }`.
+ */
+function hookCommandsOf(matcher) {
+    if (!isPlainObject(matcher) || !Array.isArray(matcher.hooks))
+        return [];
+    return matcher.hooks
+        .filter(isPlainObject)
+        .map((h) => h.command)
+        .filter((c) => typeof c === 'string');
+}
+/**
+ * Merge Devflow's template hook entries and top-level fields into an existing
+ * parsed settings object. Idempotent by exact command string — a hook that is
+ * already present is skipped. Sets `statusLine` only when the user has no existing
+ * value. Attribution is NOT injected here — managed by the flags pipeline (D27).
+ * Mutates `existing` in place.
+ *
+ * D-SETTINGS-1: merge strategy — never replace; only add devflow entries that are absent.
+ * Returns { changed: true } when any field was added.
+ *
+ * `existing` comes from a hand-editable file, so every branch is shape-guarded:
+ * a `hooks` value (or per-event value) that is not the expected object/array shape
+ * is left untouched rather than overwritten or thrown on (applies PF-023 — validate
+ * at the sink that mutates).
+ *
+ * Exported for testing.
+ */
+export function mergeDevflowSettingsTemplate(existing, template) {
+    let changed = false;
+    // Merge hook entries — idempotent by exact command string
+    const tmplHooks = isPlainObject(template.hooks) ? template.hooks : {};
+    const existingHooksRaw = existing.hooks;
+    if (existingHooksRaw === undefined || isPlainObject(existingHooksRaw)) {
+        const existingHooks = existingHooksRaw ?? {};
+        let hooksChanged = false;
+        for (const [event, matchers] of Object.entries(tmplHooks)) {
+            if (!Array.isArray(matchers))
+                continue;
+            for (const matcher of matchers) {
+                const cmd = hookCommandsOf(matcher)[0];
+                if (!cmd)
+                    continue;
+                const current = existingHooks[event];
+                if (current !== undefined && !Array.isArray(current))
+                    break; // foreign shape — leave the event alone
+                const eventArr = current ?? [];
+                if (eventArr.some((m) => hookCommandsOf(m).includes(cmd)))
+                    continue;
+                eventArr.push(matcher);
+                existingHooks[event] = eventArr;
+                hooksChanged = true;
+            }
+        }
+        // Attach only when something was actually added — never introduce an empty
+        // `hooks` key into a settings.json that had none.
+        if (hooksChanged) {
+            existing.hooks = existingHooks;
+            changed = true;
+        }
+    }
+    // Set statusLine only if the user has none
+    if (existing.statusLine === undefined && template.statusLine !== undefined) {
+        existing.statusLine = template.statusLine;
+        changed = true;
+    }
+    // attribution: owned exclusively by the flags pipeline (applyFlags/stripFlags, D27) — a second writer here would race it.
+    return { changed };
+}
 /**
  * Install or update settings.json with Devflow configuration.
- * Prompts interactively in TTY mode when settings already exist.
- * In non-TTY mode, skips override (safe default).
+ *
+ * Strategy (D-SETTINGS-1: merge, never overwrite wholesale):
+ * - Fresh file: write the template directly.
+ * - Existing file: MERGE devflow hook entries and fields into the parsed object.
+ *   Idempotent by exact command string — existing hooks are never duplicated or removed.
+ *   Preserves every user key (env, permissions, apiKeyHelper, model, etc.) untouched.
+ * - Parse failure: warn and skip; file left byte-identical (never clobber a broken file).
+ *
+ * The merge is additive only, so it runs without a confirmation prompt: init is called
+ * from inside an active spinner (a prompt would render on top of it), and declining
+ * could not protect the file anyway — init's own settings pass rewrites the hook set
+ * unconditionally right afterwards. A prompt whose answer changes nothing is worse
+ * than no prompt.
  *
  * The deny list is handled by init's dedicated security step
  * (applyUserSecurityDenyList / installManagedSettings) after installSettings completes.
@@ -741,38 +922,30 @@ export async function installSettings(claudeDir, rootDir, devflowDir, verbose) {
             }
             return;
         }
-        // Settings exist — check if they already have hooks
-        let hasHooks = false;
+        // Settings exist — parse and merge (never overwrite wholesale)
+        let existingParsed;
         try {
-            const existing = JSON.parse(await fs.readFile(settingsPath, 'utf-8'));
-            hasHooks = !!existing.hooks;
+            existingParsed = JSON.parse(await fs.readFile(settingsPath, 'utf-8'));
         }
-        catch { /* parse error = treat as no hooks */ }
-        if (hasHooks) {
-            // Settings already configured with hooks — nothing to do
+        catch {
+            // Parse failure — warn and skip; file left byte-identical (D-SETTINGS-1)
+            if (verbose) {
+                p.log.warn('settings.json could not be parsed — Devflow hooks not added. ' +
+                    'Fix the JSON manually and re-run devflow init.');
+            }
             return;
         }
-        // Settings exist without hooks — prompt in TTY, warn in non-TTY
-        if (process.stdin.isTTY) {
-            const confirmed = await p.confirm({
-                message: 'settings.json exists without hooks (Working Memory needs hooks). Override?',
-                initialValue: true,
-            });
-            if (p.isCancel(confirmed)) {
-                p.cancel('Installation cancelled.');
-                process.exit(0);
-            }
-            if (confirmed) {
-                await fs.writeFile(settingsPath, settingsContent, 'utf-8');
-                p.log.success('Settings overridden');
-            }
-            else {
-                p.log.info('Keeping existing settings');
-            }
+        const templateParsed = JSON.parse(settingsContent);
+        // Merge template into existing (mutates existingParsed in place).
+        // If nothing needs to be added the write is skipped entirely.
+        const { changed } = mergeDevflowSettingsTemplate(existingParsed, templateParsed);
+        if (!changed) {
+            // Already fully configured — nothing to do
+            return;
         }
-        else {
-            p.log.warn('Settings exist without hooks. Working Memory requires hooks.');
-            p.log.info('Re-run interactively to configure, or manually add hooks to settings.json');
+        await writeFileAtomicExclusive(settingsPath, JSON.stringify(existingParsed, null, 2) + '\n');
+        if (verbose) {
+            p.log.success('Settings updated with Devflow hooks and HUD');
         }
     }
     catch (error) {
@@ -872,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');
@@ -920,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 = '';
@@ -934,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) {