devflow-kit 2.5.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 { 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,15 @@ 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.
- */
-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.
@@ -40,13 +35,24 @@ 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
+ * 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:
@@ -54,9 +60,14 @@ const DEVFLOW_POLICY_LINE = '!.devflow/policy.json';
  *   + 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.
+ * - 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
@@ -68,9 +79,10 @@ const DEVFLOW_POLICY_LINE = '!.devflow/policy.json';
 const DEVFLOW_GITIGNORE_BLOCK_LINES = [
     '# Devflow runtime data — local by default (memory, learning, docs, locks).',
     '# 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.',
+    '# 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/*',
@@ -80,10 +92,29 @@ const DEVFLOW_GITIGNORE_BLOCK_LINES = [
     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
@@ -92,15 +123,23 @@ export const DEVFLOW_GITIGNORE_BLOCK = DEVFLOW_GITIGNORE_BLOCK_LINES.join('\n');
 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 + policy.json 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: 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
+ * 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`
@@ -108,26 +147,36 @@ const LEGACY_DEVFLOW_COMMENT = '# Devflow runtime data (local by default; remove
  *
  * `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
+ * 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`)].
  *
  * 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.
+ * 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 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.
+ *    `.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.
- * Both append forms are mirrored byte-for-byte in the shell twin
+ * 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.
  */
@@ -136,16 +185,39 @@ export function computeDevflowGitignore(existingContent) {
     const trimmed = lines.map(l => l.trim());
     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]),
     ];
     /**
-     * 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.
+     * 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 appendLines = (body, block) => `${body}${body.endsWith('\n') ? '' : '\n'}${block}\n`;
+    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
@@ -161,11 +233,12 @@ export function computeDevflowGitignore(existingContent) {
     if (trimmed.includes(DEVFLOW_GITIGNORE_SENTINEL_V3)) {
         return missingCompletionLines.length === 0
             ? null
-            : appendLines(existingContent, missingCompletionLines.join('\n'));
+            : insertInBlock(DEVFLOW_GITIGNORE_SENTINEL_V3, blockRunBefore, missingCompletionLines);
     }
-    // 3. v2 block installed — append the lines it lacks, in block order.
+    // 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)) {
-        return appendLines(existingContent, [DEVFLOW_GITIGNORE_SENTINEL_V3, ...missingCompletionLines].join('\n'));
+        return insertInBlock(DEVFLOW_GITIGNORE_SENTINEL_V2, [], [DEVFLOW_GITIGNORE_SENTINEL_V3, ...missingCompletionLines]);
     }
     // 4. No devflow block — install one, respecting any .claudeignore entry of the user's own.
     const block = hasClaudeignoreEntry
@@ -182,8 +255,12 @@ export function computeDevflowGitignore(existingContent) {
 }
 /**
  * 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.
@@ -191,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 /*)',
@@ -363,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.
@@ -539,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).
@@ -584,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
@@ -669,15 +804,11 @@ export async function removeManagedSettings(rootDir, verbose, managedPathOverrid
     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;
@@ -771,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;
 }
 /**
@@ -780,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.
  *
@@ -805,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. */
@@ -916,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');
             }
@@ -943,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');
         }
@@ -981,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');
@@ -1016,53 +1148,31 @@ export async function discoverProjectGitRoots(homeDir) {
         .map((r) => r.value);
     return gitRoots.sort();
 }
-/**
- * Update .gitignore with Devflow entries (for local scope installs).
- */
-export async function updateGitignore(gitRoot, verbose) {
-    try {
-        const gitignorePath = path.join(gitRoot, '.gitignore');
-        const entriesToAdd = getGitignoreEntries();
-        let gitignoreContent = '';
-        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}`);
-        }
-    }
-}
 /**
  * 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).
+ * 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`.
  */
-const GITIGNORE_MARKER_V5 = '.root-gitignore-configured-v5';
+const GITIGNORE_MARKER_V6 = '.root-gitignore-configured-v6';
 /**
  * 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.
+ * 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 v5 is stamped. */
+/** 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 {
@@ -1073,23 +1183,23 @@ async function removeLegacyGitignoreMarkers(devflowDir) {
 }
 /**
  * Deterministically ensure the project root .gitignore applies the `.devflow/`
- * carve-out (local by default; feature knowledge, conventions.md and the evidence
- * policy 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
+ * 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 install scope and every feature toggle)
- * whenever a git root is known.
+ * Called unconditionally (independent of every feature toggle) whenever a git
+ * root is known.
  *
- * Uses a versioned project-local marker file (`.devflow/.root-gitignore-configured-v5`)
+ * 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 v4-marked project gains the policy line and is re-stamped v5.
+ * is how a v5-marked project gains the project line and is re-stamped v6.
  *
  * Idempotent: computeDevflowGitignore returns null for a converged file, so a
  * marked install performs one read and no write. Errors are swallowed
@@ -1098,20 +1208,20 @@ async function removeLegacyGitignoreMarkers(devflowDir) {
 export async function ensureDevflowGitignore(gitRoot, verbose) {
     try {
         const devflowDir = path.join(gitRoot, '.devflow');
-        const markerV5 = path.join(devflowDir, GITIGNORE_MARKER_V5);
+        const markerV6 = path.join(devflowDir, GITIGNORE_MARKER_V6);
         const gitignorePath = path.join(gitRoot, '.gitignore');
-        // Fast-path with verification: v5 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: converged file → computeDevflowGitignore returns null → no write.
-        let v5Marked = false;
+        let v6Marked = false;
         try {
-            await fs.access(markerV5);
-            v5Marked = true;
+            await fs.access(markerV6);
+            v6Marked = true;
         }
         catch { /* absent */ }
-        if (v5Marked) {
+        if (v6Marked) {
             let existingContent = '';
             try {
                 existingContent = await fs.readFile(gitignorePath, 'utf-8');
@@ -1121,7 +1231,7 @@ 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 + evidence policy shared)');
+                    p.log.success('.gitignore configured (.devflow/ local; feature knowledge + conventions + retired policy.json + project settings shared)');
                 }
             }
             await removeLegacyGitignoreMarkers(devflowDir);
@@ -1136,12 +1246,12 @@ 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 + evidence policy shared)');
+                p.log.success('.gitignore configured (.devflow/ local; feature knowledge + conventions + retired policy.json + project settings shared)');
             }
         }
-        // Stamp v5 marker so subsequent runs fast-path; drop every legacy marker.
+        // Stamp v6 marker so subsequent runs fast-path; drop every legacy marker.
         await fs.mkdir(devflowDir, { recursive: true });
-        await fs.writeFile(markerV5, '', 'utf-8');
+        await fs.writeFile(markerV6, '', 'utf-8');
         await removeLegacyGitignoreMarkers(devflowDir);
     }
     catch (error) {
@@ -1150,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