devflow-kit 3.1.0 → 3.3.0

package/dist/core/linked-path.js

@@ -0,0 +1,46 @@
+/**
+ * @file linked-path.ts
+ *
+ * `firstSymbolicLink`, the check the CLI makes before it writes or deletes under a
+ * project's `.devflow/`, or under its `.claude/` when uninstall removes a legacy
+ * local install (D-CLI-NO-SYMLINK).
+ */
+import { promises as fs } from 'fs';
+/**
+ * The first of `paths` that is itself a symbolic link, or null when none is.
+ *
+ * D-CLI-NO-SYMLINK: the CLI writes or deletes under a project's `.devflow/` only
+ * where neither `.devflow` nor the entry it acts on through it is a symbolic link:
+ * `devflow init` stamps its carve-out marker, removes the legacy markers and
+ * writes `.devflow/config.json` only then, `devflow learning --configure` writes
+ * the project's `learning.json` only then, and the queue drains (`devflow learning
+ * --clear|--disable`, `devflow memory --disable|--clear` and `devflow init
+ * --no-learning|--no-memory`) delete nothing when `.devflow` or the queue's folder
+ * is one. `devflow uninstall`, removing a legacy local install, deletes or rewrites
+ * nothing under the project's `.devflow` or `.claude` where either, or anything
+ * below it on the way to what it removes, is one (legacyLocalChangeGuard in
+ * uninstall.ts). Reason: a repository can commit `.devflow`, or a folder or file in
+ * it, as a link to any place on the machine, and a write or delete through one lands
+ * wherever it points. The hooks hold the same rule (D-HOOKS-NO-SYMLINK, git-marker)
+ * and so do the learning ops (D-NO-LINKED-TREE). Only paths below the project root
+ * are passed here: the root and the folders above it are the user's choice.
+ *
+ * Each path is checked with lstat, so a link is seen rather than followed. Nothing at
+ * a path, or a file where a folder was expected on the way to it, is no link; any
+ * other lstat failure is thrown, so a caller that cannot check acts on nothing.
+ */
+export async function firstSymbolicLink(paths) {
+    for (const candidate of paths) {
+        try {
+            if ((await fs.lstat(candidate)).isSymbolicLink())
+                return candidate;
+        }
+        catch (error) {
+            const code = error.code;
+            if (code !== 'ENOENT' && code !== 'ENOTDIR')
+                throw error;
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=linked-path.js.map

package/dist/core/plugins.js

@@ -72,6 +72,10 @@ export const DEVFLOW_PLUGINS = [
         commands: ['/plan'],
         agents: ['git', 'skim', 'synthesize', 'design'],
         skills: ['gap-analysis', 'design-review', 'patterns', 'worktree-support', 'feature-knowledge', 'apply-feature-knowledge'],
+        // D-CHARTER-BOUNDED-INLINE: /plan's main thread orchestrates and loads no
+        // companion skills, so `requires:` lists only skills this plugin's command,
+        // agents and skills reference. `software-design` and `test-driven-development`
+        // have no reader here; the closure guard's reverse arm rejects an unread entry.
         requires: [
             'apply-decisions',
             'architecture',
@@ -87,8 +91,6 @@ export const DEVFLOW_PLUGINS = [
             'reliability',
             'review-methodology',
             'security',
-            'software-design',
-            'test-driven-development',
             'testing',
         ],
         rules: [],
@@ -127,7 +129,11 @@ export const DEVFLOW_PLUGINS = [
         commands: ['/code-review'],
         agents: ['git', 'review', 'synthesize'],
         skills: ['architecture', 'complexity', 'consistency', 'database', 'dependencies', 'documentation', 'performance', 'regression', 'reliability', 'review-methodology', 'security', 'testing', 'worktree-support', 'apply-feature-knowledge'],
-        requires: ['apply-decisions', 'docs-framework', 'git', 'quality-gates', 'software-design'],
+        // D-CHARTER-BOUNDED-INLINE: /code-review's main thread orchestrates and loads
+        // no companion skills, so `requires:` lists only skills this plugin's command,
+        // agents and skills reference. `quality-gates` and `software-design` have no
+        // reader here; the closure guard's reverse arm rejects an unread entry.
+        requires: ['apply-decisions', 'docs-framework', 'git'],
         rules: [],
     },
     {
@@ -238,7 +244,10 @@ export const DEVFLOW_PLUGINS = [
         commands: ['/release'],
         agents: ['git', 'validate'],
         skills: ['git', 'worktree-support'],
-        requires: ['testing'],
+        // D-PRELOAD-TRIM: nothing in this plugin's corpus reads `testing` (Validate
+        // preloads only `worktree-support`), so the closure guard's reverse arm holds
+        // this list empty.
+        requires: [],
         rules: [],
     },
     {
@@ -247,7 +256,9 @@ export const DEVFLOW_PLUGINS = [
         commands: ['/self-review'],
         agents: ['simplify', 'scrutinize', 'validate', 'knowledge'],
         skills: ['quality-gates', 'software-design', 'worktree-support', 'feature-knowledge', 'apply-feature-knowledge'],
-        requires: ['apply-decisions', 'testing'],
+        // D-PRELOAD-TRIM: no agent, command or skill in this plugin's corpus names
+        // `testing` (Validate preloads only `worktree-support`), so it is not required here.
+        requires: ['apply-decisions'],
         rules: [],
     },
     {

package/dist/core/queue-drain.js

@@ -0,0 +1,31 @@
+/**
+ * @file queue-drain.ts
+ *
+ * `drainQueueFiles`, the delete the queue drains share — `drainLearningQueue`
+ * (learning-queue-cleanup.ts) and `drainMemoryQueue` (cli/commands/memory.ts) —
+ * and `formatRefusedDrain`, the line the CLI prints for a drain it refused.
+ */
+import { promises as fs } from 'fs';
+import { firstSymbolicLink } from './linked-path.js';
+/**
+ * Delete each of `files` unless one of `folders` — `.devflow` and the folder that
+ * holds the files, outermost first — is a symbolic link (D-CLI-NO-SYMLINK): through a
+ * linked folder, each delete would remove a same-named file wherever the link points.
+ * A file that is already gone is not an error; any other failure propagates, as the
+ * check's own does, so the command reports it.
+ */
+export async function drainQueueFiles(folders, files) {
+    const linkedFolder = await firstSymbolicLink(folders);
+    if (linkedFolder !== null)
+        return { drained: false, linkedFolder };
+    await Promise.all(files.map(file => fs.unlink(file).catch((error) => {
+        if (error.code !== 'ENOENT')
+            throw error;
+    })));
+    return { drained: true };
+}
+/** The warning for a drain refused at `linkedFolder`: which queue kept its files, and why. */
+export function formatRefusedDrain(queue, linkedFolder) {
+    return `The ${queue} queue was not drained: ${linkedFolder} is a symbolic link, and devflow deletes nothing through one`;
+}
+//# sourceMappingURL=queue-drain.js.map

package/dist/hud/components/learning-counts.js

@@ -5,6 +5,55 @@ import { getLedgerRoot } from '../../core/ledger-root.js';
 import { isActiveDecisionsStatus } from '../../core/observations.js';
 /** The HUD's per-git-command budget (src/hud/git.ts GIT_TIMEOUT). */
 const LEDGER_ROOT_TIMEOUT_MS = 1000;
+/**
+ * The largest ledger the statusline reads: 8 MiB, far above the roughly 0.5 MB
+ * real ledgers reach.
+ *
+ * D-HUD-LEDGER-BOUNDED: the statusline counts the ledger only when it is a regular
+ * file of at most LEDGER_MAX_BYTES, and never reads it if it is a symbolic link; a
+ * link, any other kind of file or a larger one shows no counts, as an absent
+ * ledger does. Reason: the statusline reads the ledger on every prompt, and a
+ * repository can commit it as a link to an endless source such as /dev/zero, or
+ * as a huge file, either of which would hang the statusline.
+ */
+export const LEDGER_MAX_BYTES = 8 * 1024 * 1024;
+/**
+ * The ledger's text, or null when D-HUD-LEDGER-BOUNDED refuses it or it cannot be
+ * read. lstat refuses a link without following it, the open refuses one that took
+ * the ledger's place since (O_NOFOLLOW) and never blocks on a FIFO (O_NONBLOCK),
+ * and the read takes at most the size fstat checked.
+ */
+function readBoundedLedger(ledgerPath) {
+    let fd;
+    try {
+        if (!fs.lstatSync(ledgerPath).isFile())
+            return null;
+        fd = fs.openSync(ledgerPath, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK);
+    }
+    catch {
+        return null;
+    }
+    try {
+        const stat = fs.fstatSync(fd);
+        if (!stat.isFile() || stat.size > LEDGER_MAX_BYTES)
+            return null;
+        const buf = Buffer.alloc(stat.size);
+        let total = 0;
+        while (total < buf.length) {
+            const read = fs.readSync(fd, buf, total, buf.length - total, total);
+            if (read === 0)
+                break;
+            total += read;
+        }
+        return buf.toString('utf-8', 0, total);
+    }
+    catch {
+        return null;
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
 function isLedgerCountRow(val) {
     if (typeof val !== 'object' || val === null)
         return false;
@@ -17,17 +66,14 @@ function isLedgerCountRow(val) {
 }
 /**
  * Read .devflow/learning/decisions-ledger.jsonl and count active anchored
- * rows by type. Returns null if the ledger is missing or holds no valid rows
- * (graceful fallback). Exported for use by the main HUD entry point.
+ * rows by type. Returns null if the ledger is missing, is refused by
+ * D-HUD-LEDGER-BOUNDED, or holds no valid rows (graceful fallback). Exported for
+ * use by the main HUD entry point.
  */
 export function gatherLearningCounts(cwd) {
-    let content;
-    try {
-        content = fs.readFileSync(getDecisionsLedgerPath(cwd), 'utf-8');
-    }
-    catch {
+    const content = readBoundedLedger(getDecisionsLedgerPath(cwd));
+    if (content === null)
         return null;
-    }
     const counts = { decisions: 0, pitfalls: 0 };
     let parsedAny = false;
     for (const rawLine of content.split('\n')) {

package/dist/skills/git/references/tracker/github/create-release.md

@@ -2,10 +2,10 @@
 
 Load when the resolved tracker provider is `github` and the operation is `create-release`.
 
-**Mechanics held here:** the closed-issues step only. Tag creation, release creation and notes composition stay with the operation.
+**Mechanics held here:** the shipped-issues step only. Tag creation, release creation and notes composition stay with the operation.
 
 ### Process
 
 Inside step 5 (compose release notes):
 
-   - If `SHIPPED_ISSUES` provided: append a `## Closed Issues` section with issue references — **first ≤50 issues** (the same bound `backlink-shipped-issues` applies); if truncated, add a final `…and {n} more issues` line (D4 degrade if enrichment fails)
+   - If `SHIPPED_ISSUES` provided: append a `## Shipped Issues` section with issue references — **first ≤50 issues** (the same bound `backlink-shipped-issues` applies); if truncated, add a final `…and {n} more issues` line (D4 degrade if enrichment fails)

package/dist/skills/git/references/tracker/github/gather-release-evidence.md

@@ -7,7 +7,7 @@ Load when the resolved tracker provider is `github` and the operation is `gather
 ### Process
 
 1a. **Last release tag.** Step 1's `git describe` can return a non-release marker tag. From `WORKTREE_PATH` (else cwd), run `node "$HOME/.devflow/scripts/release-trace.cjs" last-tag`: `LAST_TAG <tag>` ⇒ that tag is `{last_tag}`; `LAST_TAG none` ⇒ step 1's initial-commit rule; anything else ⇒ keep step 1's tag and report status `INDETERMINATE (last release tag unresolved)`.
-3a. **Closing-keyword rule.** A candidate follows, on the same line, a whitespace token matching `^\(?(close[sd]?|fix(e[sd])?|resolve[sd]?|refs):?$` (case-insensitive). Take the next token, plus each further token while the previous one ends in `,`. Split each on `,`, strip one leading `(` and every trailing character in `[.,;:)\]!?]`, drop empties, then apply step 5's anchored gate unchanged. Read each message as `git log --format=%B` lines.
+3a. **Closing-keyword rule.** A candidate follows, on the same line, a whitespace token matching `^\(?(close[sd]?|fix(e[sd])?|resolve[sd]?):?$` (case-insensitive). Take the next token, plus each further token while the previous one ends in `,`. Split each on `,`, strip one leading `(` and every trailing character in `[.,;:)\]!?]`, drop empties, then apply step 5's anchored gate unchanged. Read each message as `git log --format=%B` lines.
 3b. **This provider's history grammar** is `^#[1-9][0-9]{0,8}$`. A bare number is not a reference here either: a keyword-anchored candidate must carry the `#`, and step 4 renders every number it reads from a merged PR as `#{n}` before step 5's gate.
 4. If `gh` is authenticated and remote is reachable, resolve which issues the range's merged PRs close — **one listing, never one call per commit** — and merge the result with the commit-message set:
    - **Once, before the listing:** this repo's identity, `gh api 'repos/{owner}/{repo}' --jq '.owner.login + "/" + .name'`, and the tag's UTC date, `TAG_DATE=$(TZ=UTC git log -1 --date=format-local:%Y-%m-%d --format=%cd {last_tag})`, shape-gated `^[0-9]{4}-[0-9]{2}-[0-9]{2}$` — a local date can drop a PR merged just after the tag. If `TAG_DATE` fails this gate, treat it as **the listing fails** below: emit `TRACEABILITY: DEGRADED ({reason})` and go straight to that bullet's ≤25-PR fallback.

package/dist/skills/git/references/tracker/jira/create-release.md

@@ -2,13 +2,13 @@
 
 Load when the resolved tracker provider is `jira` and the operation is `create-release`.
 
-**Mechanics held here:** the closed-issues step only. Tag creation, release creation and notes composition stay with the operation and are unchanged — they are release-host mechanics, not tracker mechanics.
+**Mechanics held here:** the shipped-issues step only. Tag creation, release creation and notes composition stay with the operation and are unchanged — they are release-host mechanics, not tracker mechanics.
 
 ### Process
 
 Inside step 5 (compose release notes):
 
-   - If `SHIPPED_ISSUES` is provided: append a `## Closed Issues` section rendering each entry through `## Reference Rendering` — **first ≤50 issues** (the same bound `backlink-shipped-issues` applies); if truncated, add a final `…and {n} more issues` line (D4 degrade if enrichment fails).
+   - If `SHIPPED_ISSUES` is provided: append a `## Shipped Issues` section rendering each entry through `## Reference Rendering` — **first ≤50 issues** (the same bound `backlink-shipped-issues` applies); if truncated, add a final `…and {n} more issues` line (D4 degrade if enrichment fails).
    - Pre-flight the list against `^[A-Z][A-Z0-9_]{1,9}-[1-9][0-9]{0,8}$`, anchored at both ends, and **drop** every entry that fails, reporting each as `TRACEABILITY: DEGRADED (issue reference "{ref}" does not match jira reference grammar)` — a bare number among them goes with them, in silence: `ambiguous issue reference` answers a reference a caller named, not one line of a list nobody chose. Every entry dropped ⇒ `TRACEABILITY: DEGRADED (no parseable refs for provider {p})` and the section is omitted rather than rendered empty.
    - `## Reference Rendering` absent, or its token discarded by the gate below ⇒ render the key itself on its own line, and record the discard under `### Substitutions`.
 

package/dist/skills/git/references/tracker/jira/gather-release-evidence.md

@@ -7,7 +7,7 @@ Load when the resolved tracker provider is `jira` and the operation is `gather-r
 ### Process
 
 1a. **Last release tag.** Step 1's `git describe` can return a non-release marker tag. From `WORKTREE_PATH` (else cwd), run `node "$HOME/.devflow/scripts/release-trace.cjs" last-tag`: `LAST_TAG <tag>` ⇒ that tag is `{last_tag}`; `LAST_TAG none` ⇒ step 1's initial-commit rule; anything else ⇒ keep step 1's tag and report status `INDETERMINATE (last release tag unresolved)`.
-3a. **Closing-keyword rule.** A candidate follows, on the same line, a whitespace token matching `^\(?(close[sd]?|fix(e[sd])?|resolve[sd]?|refs):?$` (case-insensitive). Take the next token, plus each further token while the previous one ends in `,`. Split each on `,`, strip one leading `(` and every trailing character in `[.,;:)\]!?]`, drop empties, then apply step 5's anchored gate unchanged. Read each message as `git log --format=%B` lines.
+3a. **Closing-keyword rule.** A candidate follows, on the same line, a whitespace token matching `^\(?(close[sd]?|fix(e[sd])?|resolve[sd]?):?$` (case-insensitive). Take the next token, plus each further token while the previous one ends in `,`. Split each on `,`, strip one leading `(` and every trailing character in `[.,;:)\]!?]`, drop empties, then apply step 5's anchored gate unchanged. Read each message as `git log --format=%B` lines.
 4. Resolve which issues the commit range closes:
    - **There is no closing-reference capability on this provider.** Emit `TRACEABILITY: DEGRADED (unsupported by jira)` once for the whole step and fall back to the commit-message set alone — the refs parsed out of the candidate references the agent extracted from the range's commit messages.
    - **This provider's history grammar** is `^[A-Z][A-Z0-9_]{1,9}-[1-9][0-9]{0,8}$`, and its KEY segment must equal the resolved project key after ASCII-upper normalisation — a well-formed key belonging to another project is a `TRACEABILITY: DEGRADED (foreign issue reference {ref})`, not a shipped issue.

package/dist/skills/git/references/tracker/linear/create-release.md

@@ -2,13 +2,13 @@
 
 Load when the resolved tracker provider is `linear` and the operation is `create-release`.
 
-**Mechanics held here:** the closed-issues step only. Tag creation, release creation and notes composition stay with the operation and are unchanged — they are release-host mechanics, not tracker mechanics.
+**Mechanics held here:** the shipped-issues step only. Tag creation, release creation and notes composition stay with the operation and are unchanged — they are release-host mechanics, not tracker mechanics.
 
 ### Process
 
 Inside step 5 (compose release notes):
 
-   - If `SHIPPED_ISSUES` is provided: append a `## Closed Issues` section rendering each entry through `## Reference Rendering` — **first ≤50 issues** (the same bound `backlink-shipped-issues` applies); if truncated, add a final `…and {n} more issues` line (D4 degrade if enrichment fails).
+   - If `SHIPPED_ISSUES` is provided: append a `## Shipped Issues` section rendering each entry through `## Reference Rendering` — **first ≤50 issues** (the same bound `backlink-shipped-issues` applies); if truncated, add a final `…and {n} more issues` line (D4 degrade if enrichment fails).
    - **ASCII-upper-normalise every entry first.** Pre-flight the list against **either** anchored form — the team-key form `^[A-Z][A-Z0-9]{0,9}-[1-9][0-9]{0,8}$` or the internal-id form `^[0-9A-F]{8}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{12}$`, anchored at both ends, never joined into one alternation, and **drop** every entry that fails, reporting each as `TRACEABILITY: DEGRADED (issue reference "{ref}" does not match linear reference grammar)` — a bare number among them goes with them, in silence: `ambiguous issue reference` answers a reference a caller named, not one line of a list nobody chose. Every entry dropped ⇒ `TRACEABILITY: DEGRADED (no parseable refs for provider {p})` and the section is omitted rather than rendered empty.
    - `## Reference Rendering` absent, or its token discarded by the gate below ⇒ render the reference itself on its own line, and record the discard under `### Substitutions`.
 

package/dist/skills/git/references/tracker/linear/gather-release-evidence.md

@@ -7,7 +7,7 @@ Load when the resolved tracker provider is `linear` and the operation is `gather
 ### Process
 
 1a. **Last release tag.** Step 1's `git describe` can return a non-release marker tag. From `WORKTREE_PATH` (else cwd), run `node "$HOME/.devflow/scripts/release-trace.cjs" last-tag`: `LAST_TAG <tag>` ⇒ that tag is `{last_tag}`; `LAST_TAG none` ⇒ step 1's initial-commit rule; anything else ⇒ keep step 1's tag and report status `INDETERMINATE (last release tag unresolved)`.
-3a. **Closing-keyword rule.** A candidate follows, on the same line, a whitespace token matching `^\(?(close[sd]?|fix(e[sd])?|resolve[sd]?|refs):?$` (case-insensitive). Take the next token, plus each further token while the previous one ends in `,`. Split each on `,`, strip one leading `(` and every trailing character in `[.,;:)\]!?]`, drop empties, then apply step 5's anchored gate unchanged. Read each message as `git log --format=%B` lines.
+3a. **Closing-keyword rule.** A candidate follows, on the same line, a whitespace token matching `^\(?(close[sd]?|fix(e[sd])?|resolve[sd]?):?$` (case-insensitive). Take the next token, plus each further token while the previous one ends in `,`. Split each on `,`, strip one leading `(` and every trailing character in `[.,;:)\]!?]`, drop empties, then apply step 5's anchored gate unchanged. Read each message as `git log --format=%B` lines.
 4. Resolve which issues the commit range closes:
    - **There is no closing-reference capability on this provider.** Emit `TRACEABILITY: DEGRADED (unsupported by linear)` once for the whole step and fall back to the commit-message set alone — the references parsed out of the candidate references the agent extracted from the range's commit messages. The magic words this provider recognises in a pull-request body are the SERVER's own behaviour and are not a capability this operation can read back: a body that closed an issue leaves no signal here, which is precisely why this step degrades instead of guessing.
    - **This provider's history grammar is the TEAM-KEY form only** — `^[A-Z][A-Z0-9]{0,9}-[1-9][0-9]{0,8}$`, with its key segment equal to the resolved team key after ASCII-upper normalisation; a well-formed reference on another team is a `TRACEABILITY: DEGRADED (foreign issue reference {ref})`. The internal-id form is NOT admitted from history: a bare identifier carries no team, so nothing distinguishes one workspace's from another's.

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

@@ -1310,6 +1310,35 @@ function recordSweep(report, kind, sweep) {
     report.sweptOrphans.push(...sweep.removed.map(name => ({ kind, name })));
     report.sweepFailures.push(...sweep.failed.map(f => ({ kind, name: f.name, error: f.error })));
 }
+/**
+ * Remove the named `devflow:`-prefixed skill directories from `skillsDir` and
+ * report which of them were actually there to remove.
+ *
+ * `names` is registry arithmetic (the skills no selected plugin owns), so most of
+ * it is routinely absent from disk. Only the deleter can say what it deleted:
+ * `fs.rm` is called WITHOUT `force`, so an absent directory rejects with ENOENT —
+ * "nothing to remove", neither a removal nor a failure. Reporting the plan instead
+ * would tell the user about deletions that never happened.
+ *
+ * Per-item failure isolation, never throws: any other rejection is recorded in
+ * `failed` and the remaining names are still attempted.
+ */
+async function removeDeselectedSkills(skillsDir, names) {
+    const removed = [];
+    const failed = [];
+    for (const name of names) {
+        try {
+            await fs.rm(path.join(skillsDir, prefixSkillName(name)), { recursive: true });
+            removed.push(name);
+        }
+        catch (err) {
+            if (err.code === 'ENOENT')
+                continue;
+            failed.push({ name, error: err });
+        }
+    }
+    return { removed, failed };
+}
 /**
  * Install plugins via manual file copy.
  * Handles cleanup of old monolithic structure, deduplication of shared assets,
@@ -1446,15 +1475,13 @@ export async function installViaFileCopy(options) {
     // Remove the skills no selected plugin owns or requires — the deselection half
     // of the scoped install. Empty on a partial install by construction
     // (resolveSkillInstallPlan gates it), so `--plugin=X` adds and never subtracts
-    // (AC-22). Failures are per-item and non-fatal.
-    for (const skill of skillPlan.remove) {
-        try {
-            await fs.rm(path.join(claudeDir, 'skills', prefixSkillName(skill)), { recursive: true, force: true });
-            report.removedSkills.push(skill);
-        }
-        catch (err) {
-            warn(`Could not remove deselected skill "${prefixSkillName(skill)}" — ${String(err)}`);
-        }
+    // (AC-22). Failures are per-item and non-fatal. `removedSkills` lists only what
+    // was on disk and is now gone: the plan is registry arithmetic and mostly names
+    // skills that were never installed.
+    const deselected = await removeDeselectedSkills(path.join(claudeDir, 'skills'), skillPlan.remove);
+    report.removedSkills.push(...deselected.removed);
+    for (const failure of deselected.failed) {
+        warn(`Could not remove deselected skill "${prefixSkillName(failure.name)}" — ${String(failure.error)}`);
     }
     // Install commands from selected plugins using registry-driven lookup.
     // Source: dist/commands/{name}.md (single lookup directory for all commands).

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

@@ -4,6 +4,7 @@ import * as path from 'path';
 import * as p from '@clack/prompts';
 import { getManagedSettingsPath } from './claude-paths.js';
 import { writeSettingsFileAtomic } from '../../core/fs-atomic.js';
+import { firstSymbolicLink } from '../../core/linked-path.js';
 function isNodeSystemError(error) {
     return (error instanceof Error &&
         'code' in error &&
@@ -1124,6 +1125,20 @@ export async function installClaudeignore(gitRoot, rootDir, verbose) {
         return false;
     }
 }
+/**
+ * Whether `gitRoot` already holds a `.claudeignore`, as
+ * {@link installClaudeignore}'s exclusive create sees it: lstat, not stat, so a
+ * dangling symlink counts as present — the create refuses one too.
+ */
+export async function hasClaudeignore(gitRoot) {
+    try {
+        await fs.lstat(path.join(gitRoot, '.claudeignore'));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Discover git repository roots from Claude's project history.
  * Parses `<claudeDir>/history.jsonl` for unique project paths that are valid git repos.
@@ -1175,9 +1190,9 @@ export async function discoverProjectGitRoots(claudeDir) {
  */
 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.
+ * Earlier markers, the unversioned (v1) one included — every run removes all of them
+ * once v6 is stamped, a project already stamped included: an older devflow can
+ * re-stamp one beside v6, and the shell twin drops the same five, on its fast path too.
  */
 const LEGACY_GITIGNORE_MARKERS = [
     '.root-gitignore-configured-v5',
@@ -1195,6 +1210,83 @@ async function removeLegacyGitignoreMarkers(devflowDir) {
         catch { /* ok if absent */ }
     }
 }
+/** The most symbolic links followed from the root `.gitignore` to the file it names. */
+const GITIGNORE_LINK_HOPS = 40;
+/** A path part that is a `.git`, in any letter case; ASCII only, like the shell twin's `.[Gg][Ii][Tt]`. */
+const DOT_GIT_PART = /^\.git$/i;
+/** True when `file` is itself a symbolic link; false for anything else, or nothing, there. */
+async function isSymbolicLink(file) {
+    try {
+        return (await fs.lstat(file)).isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The file a write to the root `.gitignore` goes to: `gitignorePath` itself when it is
+ * not a symbolic link; the file the link resolves to when that lies inside `gitRoot`
+ * and outside any `.git` in it; null otherwise, and when the link cannot be followed.
+ *
+ * D-GITIGNORE-LINK-INSIDE: a root .gitignore that is a symbolic link is written only
+ * when the file it resolves to lies inside the project root and outside any .git
+ * folder in the project, the project's own or a nested repository's: no part of its
+ * path below the root may be named .git, in any letter case, as git itself refuses
+ * such a path. Then that file is read and written directly, never through the link.
+ * Reason: a repository can commit .gitignore as a link to any file on the machine, and
+ * the carve-out would be appended to it; a file in a .git is no file of the
+ * repository's either, but git's own hooks and config, and a line appended to a hook
+ * runs as a command the next time git runs it. The name is matched in any case because a
+ * case-insensitive file system (macOS) opens .git for .GIT, and the spelling the link
+ * gave survives resolution: realpath gives only the folders their case on disk, never
+ * the file's own name, and the shell twin's `cd -P` keeps the link's spelling
+ * throughout ({@link DOT_GIT_PART}).
+ * The shell twin, `_erg_resolve_inside` in src/assets/scripts/hooks/ensure-root-gitignore,
+ * applies the same rule the same way: the link is followed one hop at a time, at most
+ * {@link GITIGNORE_LINK_HOPS} hops, a relative target is joined to the folder the link
+ * sits in without normalising it (so `..` is resolved by the file system, as the write
+ * would resolve it), and only the last folder is resolved physically, so a missing
+ * file inside the project is created there as before.
+ */
+async function resolveGitignoreTarget(gitRoot, gitignorePath) {
+    if (!(await isSymbolicLink(gitignorePath)))
+        return gitignorePath;
+    let current = path.resolve(gitignorePath);
+    for (let hops = 0; await isSymbolicLink(current); hops++) {
+        if (hops === GITIGNORE_LINK_HOPS)
+            return null;
+        let target;
+        try {
+            target = await fs.readlink(current);
+        }
+        catch {
+            return null;
+        }
+        if (target === '')
+            return null;
+        current = target.startsWith('/') ? target : `${current.slice(0, current.lastIndexOf('/'))}/${target}`;
+    }
+    const slash = current.lastIndexOf('/');
+    const base = current.slice(slash + 1);
+    if (base === '' || base === '.' || base === '..')
+        return null;
+    let rootReal;
+    let dirReal;
+    try {
+        // fs.promises.realpath is realpath(3), so a `..` after a linked folder goes where
+        // the write would go; the synchronous JS realpath normalises `..` away first.
+        rootReal = await fs.realpath(gitRoot);
+        dirReal = await fs.realpath(current.slice(0, slash) || '/');
+    }
+    catch {
+        return null;
+    }
+    const rootPrefix = rootReal === '/' ? '/' : `${rootReal}/`;
+    const resolved = `${dirReal === '/' ? '' : dirReal}/${base}`;
+    if (!resolved.startsWith(rootPrefix))
+        return null;
+    return resolved.slice(rootPrefix.length).split('/').some(part => DOT_GIT_PART.test(part)) ? null : resolved;
+}
 /**
  * Deterministically ensure the project root .gitignore applies the `.devflow/`
  * carve-out (local by default; feature knowledge, conventions.md, the evidence
@@ -1209,48 +1301,32 @@ async function removeLegacyGitignoreMarkers(devflowDir) {
  * Called unconditionally (independent of every feature toggle) whenever a git
  * root is known.
  *
- * 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.
+ * Stamps a versioned project-local marker (`.devflow/.root-gitignore-configured-v6`),
+ * the claim the hooks' fast path reads: the shell twin and ensure-devflow-init skip
+ * the carve-out while it stands. The marker is a claim, not proof, so this function
+ * never trusts it: every run re-reads .gitignore and re-runs computeDevflowGitignore.
  *
  * 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.
+ * converged install performs one read and no write. Errors are swallowed
+ * (verbose-logged) — a gitignore write must never abort init. A `.gitignore` that
+ * is a symbolic link leading outside the project, into a `.git`, or nowhere is left
+ * untouched (D-GITIGNORE-LINK-INSIDE, {@link resolveGitignoreTarget}), and nothing is
+ * written or removed under a `.devflow`, or through a marker, that is a symbolic link
+ * (D-CLI-NO-SYMLINK, firstSymbolicLink); either skip is always reported.
  */
 export async function ensureDevflowGitignore(gitRoot, verbose) {
     try {
         const devflowDir = path.join(gitRoot, '.devflow');
         const markerV6 = path.join(devflowDir, GITIGNORE_MARKER_V6);
-        const gitignorePath = path.join(gitRoot, '.gitignore');
-        // 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 v6Marked = false;
-        try {
-            await fs.access(markerV6);
-            v6Marked = true;
-        }
-        catch { /* absent */ }
-        if (v6Marked) {
-            let existingContent = '';
-            try {
-                existingContent = await fs.readFile(gitignorePath, 'utf-8');
-            }
-            catch { /* absent */ }
-            const healContent = computeDevflowGitignore(existingContent);
-            if (healContent !== null) {
-                await fs.writeFile(gitignorePath, healContent, 'utf-8');
-                if (verbose) {
-                    p.log.success('.gitignore configured (.devflow/ local; feature knowledge + conventions + retired policy.json + project settings shared)');
-                }
-            }
-            await removeLegacyGitignoreMarkers(devflowDir);
+        const rootGitignore = path.join(gitRoot, '.gitignore');
+        const gitignorePath = await resolveGitignoreTarget(gitRoot, rootGitignore);
+        if (gitignorePath === null) {
+            p.log.warn(`.gitignore not updated: ${rootGitignore} is a symbolic link that leads outside the project, into a .git, or nowhere; devflow writes nothing through it`);
             return;
         }
+        // A merge-conflict resolution may have dropped the block from a stamped project,
+        // so the file is always read; it is written only when computeDevflowGitignore
+        // returns non-null, which a converged file never does.
         let gitignoreContent = '';
         try {
             gitignoreContent = await fs.readFile(gitignorePath, 'utf-8');
@@ -1263,9 +1339,23 @@ export async function ensureDevflowGitignore(gitRoot, verbose) {
                 p.log.success('.gitignore configured (.devflow/ local; feature knowledge + conventions + retired policy.json + project settings shared)');
             }
         }
-        // Stamp v6 marker so subsequent runs fast-path; drop every legacy marker.
+        // Everything below writes or removes under .devflow (D-CLI-NO-SYMLINK).
+        const linked = await firstSymbolicLink([devflowDir, markerV6]);
+        if (linked !== null) {
+            p.log.warn(`Nothing written under ${devflowDir}: ${linked} is a symbolic link, and devflow writes nothing through one`);
+            return;
+        }
+        // Stamp v6 where nothing stands — an exclusive create never follows a link that
+        // appears at the marker's name, and a marker already there is all the hooks need —
+        // then drop every legacy marker.
         await fs.mkdir(devflowDir, { recursive: true });
-        await fs.writeFile(markerV6, '', 'utf-8');
+        try {
+            await fs.writeFile(markerV6, '', { encoding: 'utf-8', flag: 'wx' });
+        }
+        catch (error) {
+            if (!(isNodeSystemError(error) && error.code === 'EEXIST'))
+                throw error;
+        }
         await removeLegacyGitignoreMarkers(devflowDir);
     }
     catch (error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devflow-kit",
-  "version": "3.1.0",
+  "version": "3.3.0",
   "description": "A meta-harness for Claude Code — turns a single coding agent into an engineering team: orchestration, parallel review, persistent memory, self-learning, and graph workflows",
   "type": "module",
   "bin": {