devflow-kit 2.4.0 → 3.0.0

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

@@ -1,11 +1,9 @@
 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';
 import { getManagedSettingsPath } from './claude-paths.js';
-import { getGitignoreEntries, getDocsDir } from '../../core/project-paths.js';
-import { writeFileAtomicExclusive } from '../../core/fs-atomic.js';
+import { writeSettingsFileAtomic } from '../../core/fs-atomic.js';
 function isNodeSystemError(error) {
     return (error instanceof Error &&
         'code' in error &&
@@ -13,18 +11,48 @@ function isNodeSystemError(error) {
 }
 /**
  * Replace ${DEVFLOW_DIR} placeholders in a settings template.
+ *
+ * D-ONE-HOME: the settings template's install-time placeholder is the one
+ * surviving spelling of that name. It is a template token substituted here with
+ * the machine root (always ~/.devflow) — not an environment variable, and no
+ * runtime reader resolves it (tests/guards/one-home.test.ts pins both sites).
  */
 export function substituteSettingsTemplate(template, devflowDir) {
     return template.replace(/\$\{DEVFLOW_DIR\}/g, devflowDir);
 }
 /**
- * Compute which entries need appending to a .gitignore file.
- * Returns only entries not already present.
+ * 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.
  */
-export function computeGitignoreAppend(existingContent, entries) {
-    const existingLines = existingContent.split('\n').map(l => l.trim());
-    return entries.filter(entry => !existingLines.includes(entry));
-}
+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 retired evidence-policy file (D-GITIGNORE-V5,
+ * D-POLICY-JSON-RETIRED). 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';
+/**
+ * Re-includes the team-committed project settings file (D-GITIGNORE-V6). The same
+ * contract as the policy line: a COMPLETION line, never a presence sentinel — a
+ * user may author it before devflow ever runs, so its presence proves nothing about
+ * the block (avoids PF-059). It sits after the policy line and before `.claudeignore`,
+ * so a v5 block, which ends in `.claudeignore`, gains it just before that line
+ * (D-GITIGNORE-IN-BLOCK, computeDevflowGitignore). Without it
+ * `.devflow/*` ignores `.devflow/project.json`, and a team could only commit it with
+ * `git add -f`. Devflow never writes the file itself (ADR-024).
+ */
+const DEVFLOW_PROJECT_LINE = '!.devflow/project.json';
 /**
  * The shared .devflow/ gitignore block. Everything under .devflow/ is local
  * (memory, learning, docs, locks) EXCEPT:
@@ -32,6 +60,14 @@ 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 retired evidence-policy file. resolve-evidence-policy.cjs never
+ *   parses it, but where project.json has no `evidence` its presence holds the
+ *   repository at `required` (D-POLICY-JSON-RETIRED); GIT-TRACKED so a team's
+ *   committed copy stays shared until its value moves into project.json. Devflow
+ *   never writes it.
+ * - project.json: the team-committed settings (evidence, compliance, tracker, review
+ *   publication, narrow-only feature switches) both resolvers read; GIT-TRACKED for
+ *   the same reason (D-GITIGNORE-V6). 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,70 +75,192 @@ 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),',
+    '# .devflow/policy.json (retired; presence only) and .devflow/project.json (team settings).',
+    '# 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,
+    DEVFLOW_PROJECT_LINE,
+    CLAUDEIGNORE_LINE,
+];
+/** The full carve-out block, `.claudeignore` line included. */
+export const DEVFLOW_GITIGNORE_BLOCK = DEVFLOW_GITIGNORE_BLOCK_LINES.join('\n');
+/**
+ * The entries directly under a repository's `.devflow/` that the team shares
+ * through git (a trailing `/` marks a directory): the feature knowledge bases,
+ * the naming conventions, the retired evidence-policy file and the committed
+ * project settings.
+ *
+ * D-UNINSTALL-CARVE-OUT: uninstall's project-data step never deletes these — a
+ * confirmed removal takes everything else under `.devflow/` and keeps them
+ * byte-identical, because an uncommitted edit to a tracked file is not
+ * recoverable from git. Kept next to the gitignore block it mirrors: every path
+ * the block re-includes must appear here (pinned by tests/uninstall-logic.test.ts).
+ */
+export const DEVFLOW_TRACKED_PATHS = Object.freeze([
+    'features/',
+    'conventions.md',
+    'policy.json',
+    'project.json',
+]);
+/**
+ * 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)';
+/**
+ * The most lines a top-up run extends below its anchor — one per line the run may
+ * hold (the sentinel, the policy line, the project line). The shell twin's loop has
+ * the same bound.
+ */
+const BLOCK_RUN_MAX = 3;
 /**
  * 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 + project.json
+ * carve-out — or `null` when no change is needed. Idempotent: feeding its own output
+ * back returns `null`.
+ *
+ * D-GITIGNORE-V5 / D-GITIGNORE-V6: the block is detected ONLY by its own
+ * devflow-unique sentinel (`!.devflow/conventions.md`). `.claudeignore`,
+ * `!.devflow/policy.json` and `!.devflow/project.json` are COMPLETION lines — users
+ * legitimately author all three 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` and
+ * `hasProjectLine` are true when some whole line, trimmed, is exactly
+ * `!.devflow/policy.json` / `!.devflow/project.json`. The missing completion lines, in
+ * block order, are [policy line, project 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 → insert the missing completion lines into the block;
+ *    `null` when none are missing. This is the v4→v6 and v5→v6 upgrade: a v5 block
+ *    gains only the project line, just before its `.claudeignore` line, and a v4
+ *    block the policy and project lines, each keeping its old comment.
+ * 3. v2 sentinel present, no v3 → insert `!.devflow/conventions.md` followed by the
+ *    missing completion lines right after the v2 sentinel.
+ * 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 or project
+ *    line is duplicated harmlessly here, and the re-run is a no-op.
+ * 5. No completion line is ever a sentinel. The marker file
+ *    (`.devflow/.root-gitignore-configured-v6`) is a fast-path claim, never proof.
+ *
+ * D-GITIGNORE-IN-BLOCK: lines topped up into an existing block (2 and 3) go INSIDE
+ * it, where a fresh block holds them — never at the end of the file. gitignore is
+ * last-match-wins, so a `!.devflow/project.json` appended after a user's own later
+ * `.devflow/project.json` would silently override their re-ignore. The missing
+ * lines are inserted as one run, in block order, after the first sentinel line and
+ * the lines right after it that a fresh block places before the first missing line
+ * (blockRunBefore; at most three). Every other byte of the file is kept.
+ *
+ * Line matching is whole-line, whitespace-tolerant, exact text — never substring.
+ * The insert and the append form 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);
+    const hasProjectLine = trimmed.includes(DEVFLOW_PROJECT_LINE);
+    /** The block-completing lines this file lacks, in block order. */
+    const missingCompletionLines = [
+        ...(hasPolicyLine ? [] : [DEVFLOW_POLICY_LINE]),
+        ...(hasProjectLine ? [] : [DEVFLOW_PROJECT_LINE]),
+        ...(hasClaudeignoreEntry ? [] : [CLAUDEIGNORE_LINE]),
+    ];
+    /**
+     * The block lines a top-up run follows: the v3 sentinel, then whichever of the
+     * policy and project lines a fresh block places before the first missing line.
+     * Mirrors `_ERG_RUN_RE` in the shell twin.
+     */
+    const blockRunBefore = !hasPolicyLine
+        ? [DEVFLOW_GITIGNORE_SENTINEL_V3]
+        : !hasProjectLine
+            ? [DEVFLOW_GITIGNORE_SENTINEL_V3, DEVFLOW_POLICY_LINE]
+            : [DEVFLOW_GITIGNORE_SENTINEL_V3, DEVFLOW_POLICY_LINE, DEVFLOW_PROJECT_LINE];
+    /**
+     * Insert `inserted` into an existing devflow block: after the first line whose
+     * trimmed text is `anchor`, and after up to BLOCK_RUN_MAX lines right below it
+     * whose trimmed text is in `run`. Every other byte is kept. A run that ends on a
+     * last line with no newline gets one first, so the inserted lines never fuse onto
+     * it. Mirrors `_erg_insert_in_block` in the shell twin (D-GITIGNORE-IN-BLOCK).
+     */
+    const insertInBlock = (anchor, run, inserted) => {
+        let end = trimmed.indexOf(anchor);
+        for (let k = 0; k < BLOCK_RUN_MAX && end + 1 < lines.length && run.includes(trimmed[end + 1]); k++) {
+            end++;
+        }
+        if (end === lines.length - 1)
+            return `${existingContent}\n${inserted.join('\n')}\n`;
+        return [...lines.slice(0, end + 1), ...inserted, ...lines.slice(end + 1)].join('\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
+            : insertInBlock(DEVFLOW_GITIGNORE_SENTINEL_V3, blockRunBefore, missingCompletionLines);
+    }
+    // 3. v2 block installed — insert the lines it lacks, in block order, right after
+    //    its sentinel, the last carve-out line it has.
     if (trimmed.includes(DEVFLOW_GITIGNORE_SENTINEL_V2)) {
-        const sep = existingContent.endsWith('\n') ? '' : '\n';
-        return `${existingContent}${sep}${DEVFLOW_GITIGNORE_SENTINEL_V3}\n`;
+        return insertInBlock(DEVFLOW_GITIGNORE_SENTINEL_V2, [], [DEVFLOW_GITIGNORE_SENTINEL_V3, ...missingCompletionLines]);
     }
-    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.
- * Preserves existing entries (including allow and sibling keys), deduplicates,
- * and returns the merged JSON string with trailing newline.
+ * Preserves existing entries (including allow and sibling keys) except those named
+ * in `retired`, deduplicates, and returns the merged JSON string with trailing newline.
+ *
+ * `retired` is how an install converges an older one: pass retiredDenyEntries(template)
+ * so entries Devflow once shipped and has since dropped do not linger. An entry that
+ * `newDenyEntries` carries is never dropped, whatever `retired` says.
  *
  * PURE + idempotent: calling with the same inputs always yields byte-equal output.
  * Non-array `deny` (e.g. a string, null) is treated as empty — neither throws nor spreads chars.
@@ -110,22 +268,33 @@ export function computeDevflowGitignore(existingContent) {
  * @throws {SyntaxError} on malformed JSON — callers must pre-validate (e.g. via detectDenyState)
  *   or wrap in try/catch.
  */
-export function mergeDenyList(existingJson, newDenyEntries) {
+export function mergeDenyList(existingJson, newDenyEntries, retired = new Set()) {
     const existing = JSON.parse(existingJson);
     const rawDeny = existing.permissions?.deny;
     const currentDeny = Array.isArray(rawDeny) ? rawDeny : [];
-    const merged = [...new Set([...currentDeny, ...newDenyEntries])];
+    const kept = currentDeny.filter(e => !retired.has(e));
+    const merged = [...new Set([...kept, ...newDenyEntries])];
     existing.permissions = { ...(existing.permissions ?? {}), deny: merged };
     return JSON.stringify(existing, null, 2) + '\n';
 }
 /**
  * Historical superset of every deny entry Devflow has ever shipped.
- * Append every future entry here; never remove entries.
- * Used by stripUserDenyList to identify Devflow-managed entries in legacy installs.
+ * Append every future entry here; never remove entries — a retired template entry
+ * stays here so removal (stripUserDenyList, removeManagedSettings) and install
+ * convergence (retiredDenyEntries) still recognise it in an older install.
  *
  * Load-time assertion below verifies this is a superset of the current template.
  */
 // D-SECURITY-01: frozen at module load — any future template entry must appear here too.
+// D-SECURITY-02 (#399): the nine v1 piped rules (`Bash(curl * | bash*)` and kin) are
+// RETIRED — kept here, dropped from the template. Claude Code splits a Bash command at
+// `|` (and `&&`, `||`, `;`, `|&`, `&`, newlines) and matches every rule against each
+// subcommand alone, so a rule holding ` | ` can never match anything. The exact
+// shell-on-stdin denies in the v2 batch (`Bash(bash)`, `Bash(sh -s *)`, ...) match the
+// shell subcommand of such a pipeline instead.
+// Only entries a release actually shipped belong here: removal and install convergence
+// strip every entry this set names that the template does not, so a rule Devflow never
+// shipped would be taken from a user who wrote it (ADR-024, prove-you-wrote-it).
 export const DEVFLOW_HISTORICAL_DENY = Object.freeze(new Set([
     // v1 batch — 154 entries shipped in src/targets/claude-code/templates/managed-settings.json
     'Bash(rm -rf /*)',
@@ -282,7 +451,54 @@ export const DEVFLOW_HISTORICAL_DENY = Object.freeze(new Set([
     'Read(/etc/shadow)',
     'Read(/etc/sudoers)',
     'Read(/etc/passwd)',
+    // v2 batch (#399) — 25 template entries: a shell reading its script from stdin,
+    // `zsh -c` beside the v1 `sh -c`/`bash -c`, OrbStack VM control, docker
+    // pull/delete/prune and whole-disk or privileged runs.
+    'Bash(bash)',
+    'Bash(sh)',
+    'Bash(zsh)',
+    'Bash(bash - *)',
+    'Bash(sh - *)',
+    'Bash(zsh - *)',
+    'Bash(bash -s *)',
+    'Bash(sh -s *)',
+    'Bash(zsh -s *)',
+    'Bash(zsh -c *)',
+    'Bash(docker run*--privileged*)',
+    'Bash(docker run*-v /:*)',
+    'Bash(docker run*--volume /:*)',
+    'Bash(docker run*--volume=/:*)',
+    'Bash(docker pull *)',
+    'Bash(docker image pull *)',
+    'Bash(docker rm *)',
+    'Bash(docker container rm *)',
+    'Bash(docker rmi *)',
+    'Bash(docker image rm *)',
+    'Bash(docker volume rm *)',
+    'Bash(docker*prune*)',
+    'Bash(orb *)',
+    'Bash(orbctl *)',
+    'Bash(open *OrbStack*)',
 ]));
+/**
+ * The Devflow deny entries an older install may carry that the current template no
+ * longer ships: DEVFLOW_HISTORICAL_DENY minus the template. PURE.
+ *
+ * An empty template (loadTemplateDenyEntries' failure value) retires nothing — an
+ * unreadable template must never read as "Devflow dropped every entry it ever shipped".
+ *
+ * Accepted trade-off (ADR-024): a deny entry is a bare string, so a user who typed a
+ * retired entry themselves is indistinguishable from Devflow's copy and loses it on the
+ * next install, exactly as `security --disable` and uninstall already strip every
+ * historical entry. Retire an entry only when losing a user's identical copy is
+ * harmless; the #399 piped rules qualify because none could ever match (D-SECURITY-02).
+ */
+export function retiredDenyEntries(templateEntries) {
+    if (templateEntries.length === 0)
+        return new Set();
+    const current = new Set(templateEntries);
+    return new Set([...DEVFLOW_HISTORICAL_DENY].filter(e => !current.has(e)));
+}
 /**
  * Assert that DEVFLOW_HISTORICAL_DENY is a superset of the provided template entries.
  * Throws if any template entry is missing from the historical set.
@@ -458,8 +674,8 @@ export function resolveSecurityAction(flag, manifestMode, detected, isTTY) {
 }
 /**
  * Load the deny entry array from the managed-settings.json template.
- * Canonical single-source helper used by installManagedSettings, removeManagedSettings,
- * init.ts's security step, and security.ts's --enable/--disable paths.
+ * Canonical single-source helper used by installManagedSettings, init.ts's security
+ * step, and security.ts's --enable path. Removal keys on DEVFLOW_HISTORICAL_DENY instead.
  *
  * Defensive read: treats file as `Record<string, unknown>`, guards with Array.isArray,
  * coerces each element to string. Returns [] on any read or parse failure (never throws).
@@ -503,7 +719,7 @@ export async function installManagedSettings(rootDir, verbose) {
     let content;
     try {
         const existing = await fs.readFile(managedPath, 'utf-8');
-        content = mergeDenyList(existing, newDenyEntries);
+        content = mergeDenyList(existing, newDenyEntries, retiredDenyEntries(newDenyEntries));
     }
     catch {
         // File doesn't exist — use template as-is
@@ -531,11 +747,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 +776,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 {
@@ -573,15 +804,11 @@ export async function removeManagedSettings(rootDir, verbose) {
     catch {
         return false; // File doesn't exist
     }
-    // Load our deny entries to identify which to remove
-    const devflowDenyEntries = await loadTemplateDenyEntries(rootDir);
-    if (devflowDenyEntries.length === 0) {
-        return false;
-    }
+    // Key on every entry Devflow has ever shipped, not the current template: an install
+    // from an older release carries entries the template has since retired (D-SECURITY-02).
     const existing = JSON.parse(existingContent);
     const currentDeny = existing.permissions?.deny ?? [];
-    const devflowSet = new Set(devflowDenyEntries);
-    const remaining = currentDeny.filter(entry => !devflowSet.has(entry));
+    const remaining = currentDeny.filter(entry => !DEVFLOW_HISTORICAL_DENY.has(entry));
     // Determine the target action: delete file entirely or write updated content
     let shouldDelete = false;
     let updatedContent = null;
@@ -639,12 +866,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) {
@@ -675,8 +902,8 @@ export async function applyUserSecurityDenyList(settingsPath, currentTemplateDen
     catch {
         existing = '{}';
     }
-    const merged = mergeDenyList(existing, currentTemplateDeny);
-    await writeFileAtomicExclusive(settingsPath, merged);
+    const merged = mergeDenyList(existing, currentTemplateDeny, retiredDenyEntries(currentTemplateDeny));
+    await writeSettingsFileAtomic(settingsPath, merged);
     return merged;
 }
 /**
@@ -684,7 +911,7 @@ export async function applyUserSecurityDenyList(settingsPath, currentTemplateDen
  * Colocated with applyUserSecurityDenyList — the remove-side counterpart.
  *
  * Sequence: read → stripUserDenyList → guard (stripped !== existing) →
- *   writeFileAtomicExclusive → return { removed }.
+ *   writeSettingsFileAtomic → return { removed }.
  * Atomic write (temp+rename) upholds the never-truncate-on-crash invariant.
  * ENOENT is swallowed (file absent = nothing to strip). Other errors propagate.
  *
@@ -709,7 +936,7 @@ export async function stripUserSecurityDenyList(settingsPath) {
     if (stripped === existing) {
         return null;
     }
-    await writeFileAtomicExclusive(settingsPath, stripped);
+    await writeSettingsFileAtomic(settingsPath, stripped);
     return { removed };
 }
 /** True for a non-null, non-array object literal. */
@@ -820,7 +1047,7 @@ export async function installSettings(claudeDir, rootDir, devflowDir, verbose) {
             settingsExists = false;
         }
         if (!settingsExists) {
-            await fs.writeFile(settingsPath, settingsContent, 'utf-8');
+            await writeSettingsFileAtomic(settingsPath, settingsContent);
             if (verbose) {
                 p.log.success('Settings configured');
             }
@@ -847,7 +1074,7 @@ export async function installSettings(claudeDir, rootDir, devflowDir, verbose) {
             // Already fully configured — nothing to do
             return;
         }
-        await writeFileAtomicExclusive(settingsPath, JSON.stringify(existingParsed, null, 2) + '\n');
+        await writeSettingsFileAtomic(settingsPath, JSON.stringify(existingParsed, null, 2) + '\n');
         if (verbose) {
             p.log.success('Settings updated with Devflow hooks and HUD');
         }
@@ -885,11 +1112,12 @@ export async function installClaudeignore(gitRoot, rootDir, verbose) {
 }
 /**
  * Discover git repository roots from Claude's project history.
- * Parses ~/.claude/history.jsonl for unique project paths that are valid git repos.
- * @param homeDir - Override home directory (dependency injection for tests)
+ * Parses `<claudeDir>/history.jsonl` for unique project paths that are valid git repos.
+ * @param claudeDir - The Claude Code directory whose history is read — the caller
+ *   passes getClaudeDirectory() (D-CLAUDE-CONFIG-DIR), tests a sandbox.
  */
-export async function discoverProjectGitRoots(homeDir) {
-    const historyPath = path.join(homeDir ?? os.homedir(), '.claude', 'history.jsonl');
+export async function discoverProjectGitRoots(claudeDir) {
+    const historyPath = path.join(claudeDir, 'history.jsonl');
     let content;
     try {
         content = await fs.readFile(historyPath, 'utf-8');
@@ -921,73 +1149,79 @@ export async function discoverProjectGitRoots(homeDir) {
     return gitRoots.sort();
 }
 /**
- * Update .gitignore with Devflow entries (for local scope installs).
+ * 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-V6 (#392): v6 adds the `!.devflow/project.json` completion line. A
+ * v5-stamped project misses the v6 fast path once, gains that line (and nothing else
+ * — its comment and every other line stay byte-identical) and is re-stamped v6, so
+ * a team can commit `.devflow/project.json` without `git add -f`. v2–v5 inputs all
+ * converge on the same completion order: policy, project, `.claudeignore`.
  */
-export async function updateGitignore(gitRoot, verbose) {
-    try {
-        const gitignorePath = path.join(gitRoot, '.gitignore');
-        const entriesToAdd = getGitignoreEntries();
-        let gitignoreContent = '';
+const GITIGNORE_MARKER_V6 = '.root-gitignore-configured-v6';
+/**
+ * Earlier markers, the unversioned (v1) one included — every one is removed
+ * whenever the project is v6-stamped, on the fast path too: an older devflow can
+ * re-stamp one beside v6, and the shell twin drops the same five.
+ */
+const LEGACY_GITIGNORE_MARKERS = [
+    '.root-gitignore-configured-v5',
+    '.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 v6 is stamped. */
+async function removeLegacyGitignoreMarkers(devflowDir) {
+    for (const legacy of LEGACY_GITIGNORE_MARKERS) {
         try {
-            gitignoreContent = await fs.readFile(gitignorePath, 'utf-8');
-        }
-        catch { /* doesn't exist */ }
-        const linesToAdd = computeGitignoreAppend(gitignoreContent, entriesToAdd);
-        if (linesToAdd.length > 0) {
-            const newContent = gitignoreContent
-                ? `${gitignoreContent.trimEnd()}\n\n# Devflow local installation\n${linesToAdd.join('\n')}\n`
-                : `# Devflow local installation\n${linesToAdd.join('\n')}\n`;
-            await fs.writeFile(gitignorePath, newContent, 'utf-8');
-            if (verbose) {
-                p.log.success('.gitignore updated');
-            }
-        }
-    }
-    catch (error) {
-        if (verbose) {
-            p.log.warn(`Could not update .gitignore: ${error instanceof Error ? error.message : error}`);
+            await fs.rm(path.join(devflowDir, legacy), { force: true });
         }
+        catch { /* ok if absent */ }
     }
 }
-/** 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';
 /**
  * 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, the evidence
+ * policy and the project settings 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.
+ * Manages ONLY `.devflow/` — never `.claude/` — because a project's `.claude/`
+ * is its own to share or ignore. This is the init-time counterpart to the always-on
+ * 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 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-v6`)
+ * 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 v5-marked project gains the project line and is re-stamped v6.
  *
- * 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 markerV6 = path.join(devflowDir, GITIGNORE_MARKER_V6);
         const gitignorePath = path.join(gitRoot, '.gitignore');
-        // Fast-path with verification: v3 marker normally means the block is installed,
+        // Fast-path with verification: v6 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 v6Marked = false;
         try {
-            await fs.access(markerV3);
-            v3Marked = true;
+            await fs.access(markerV6);
+            v6Marked = true;
         }
         catch { /* absent */ }
-        if (v3Marked) {
+        if (v6Marked) {
             let existingContent = '';
             try {
                 existingContent = await fs.readFile(gitignorePath, 'utf-8');
@@ -997,9 +1231,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 + retired policy.json + project settings shared)');
                 }
             }
+            await removeLegacyGitignoreMarkers(devflowDir);
             return;
         }
         let gitignoreContent = '';
@@ -1011,16 +1246,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 + retired policy.json + project settings shared)');
             }
         }
-        // Stamp v3 marker so subsequent runs fast-path; drop the legacy v2 marker.
+        // Stamp v6 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(markerV6, '', 'utf-8');
+        await removeLegacyGitignoreMarkers(devflowDir);
     }
     catch (error) {
         if (verbose) {
@@ -1028,21 +1260,4 @@ export async function ensureDevflowGitignore(gitRoot, verbose) {
         }
     }
 }
-/**
- * Create .devflow/docs/ directory structure for Devflow artifacts.
- */
-export async function createDocsStructure(verbose) {
-    const docsDir = getDocsDir(process.cwd());
-    try {
-        await Promise.all([
-            fs.mkdir(path.join(docsDir, 'status', 'compact'), { recursive: true }),
-            fs.mkdir(path.join(docsDir, 'reviews'), { recursive: true }),
-            fs.mkdir(path.join(docsDir, 'releases'), { recursive: true }),
-        ]);
-        if (verbose) {
-            p.log.success('.devflow/docs/ structure ready');
-        }
-    }
-    catch { /* may already exist */ }
-}
 //# sourceMappingURL=post-install.js.map