devflow-kit 3.1.0 → 3.2.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: [],
     },
     {

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/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/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/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.2.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": {

package/src/assets/agents/code.md

@@ -79,7 +79,8 @@ You receive from orchestrator:
 
 4. **Write tests**: Add tests for new functionality. Cover happy path, error cases, and edge cases. Follow existing test patterns.
 
-5. **Run tests**: Execute the test suite. Fix any failures. All tests must pass before proceeding.
+5. **Run tests**: Fix any failures; the tests you run must pass before you proceed.
+   **Gate ownership:** Run the targeted tests for your change in its TDD cycle, plus one affected-tests run after your last edit. In a fix mode, compile and run the named failing or regression tests. Never the full suite. Batch fixes: one build check per batch, not per edit. Only Validate runs the full suite.
 
 6. **Commit and push**: Create atomic commits with clear messages. Reference TASK_ID. Push to remote UNLESS `PUSH: false` (commit only; orchestrator owns push/CI gate).
 
@@ -125,24 +126,18 @@ You receive from orchestrator:
 
 8. **Generate handoff** (if HANDOFF_REQUIRED=true): Include implementation summary for next Code agent (see Output section).
 
-## Long-running commands (self-verifying builds/tests that may run >120s)
+## Running commands
 
-You run builds and tests to verify your own work — including **self-verifying that each fix compiles** when no separate Validate agent runs inside the review pass. A plain `Bash` call defaults to a 120s timeout, and inside a dynamic Workflow a sub-agent that emits no output for 180s is KILLED ("agent stalled"). For any build/test that may run silent longer than ~120s (cold `cargo build`/`cargo test`, large `tsc`, `gradle`, `go build ./...`), do NOT run it as one silent foreground command. Instead:
+Run builds, typechecks, lints and tests in the foreground, each with an explicit Bash `timeout` above its expected run time. The ceiling is 600000 ms, or `BASH_MAX_TIMEOUT_MS` when set (`echo ${BASH_MAX_TIMEOUT_MS:-600000}`).
 
-0. **Pre-load Monitor** before launching any background task: `ToolSearch(query="select:Monitor")`.
-1. Run it in the BACKGROUND with the Bash tool (`run_in_background: true`), capturing output + exit code under a unique `<slug>` reused in steps 1–3, e.g. `BASE=/tmp/df-build-<slug>`:
-   `<command> > <BASE>.log 2>&1; echo "EXIT=$?" > <BASE>.done`
-   Build commands are **NEVER** wrapped in `sh -c`, `bash -c`, or inline interpreters (`python3 -c`, `node -e`) — permission systems deny wrapper-invoked commands that would be allowed directly.
-2. Arm **ONE** Monitor: set `persistent: false`, `timeout_ms` above the expected run time (e.g. 600000), and
-   `command: until [ -f <BASE>.done ]; do echo building; sleep 25; done; echo BUILD_DONE; cat <BASE>.done`
-   The 25s heartbeat (≪ 180s) keeps you alive past the watchdog.
-   - **Exit-code honesty:** the trailing `echo` always exits 0 — the background task's own exit status is meaningless. ALWAYS read the `EXIT=` value written inside `<BASE>.done`.
-   - **Bounded polling:** arm ONE Monitor then stop. On timeout, re-arm at most 2× (never more than 3 total Monitor calls per build). After 3 Monitor calls with no finish: record state and escalate — never babysit.
-3. When the monitor reports `BUILD_DONE`: the command PASSED iff `<BASE>.done` contains `EXIT=0`. Read `<BASE>.log`, fix any failures, and only then proceed.
-
-**One build gate per phase:** batch related fixes, validate once. Run ONE light check over your whole fix batch — never several invocations per small fix. Do NOT validate after every individual mutation.
-
-For a foreground command that exceeds the 120s default but stays under 180s, pass an explicit higher `timeout` to the Bash tool (up to 600000ms). Prefer package-scoped commands (`cargo build -p <crate>`) during the engine; the full-workspace regression is the human's job after the wave.
+- Capture, then tail, in one Bash call (shell state does not persist): `LOG=$(mktemp); echo "LOG=$LOG"; <command> >"$LOG" 2>&1; rc=$?; tail -n 40 "$LOG"; echo "EXIT=$rc"`. The printed `EXIT=` value is the result; never decide one from a grep count.
+- Never background a command and wait on it, and never poll across turns: no `sleep` or `true` turns, no sentinel-file checks, no Monitor.
+- Prefer the scoped command for the change (a package, a path or a test file); for the whole set, one workspace-level command over a per-package loop.
+- A run that exceeds its timeout is BLOCKED: report its duration and log path. Do not wait on it, poll it or re-run it.
+- A run expected to exceed the ceiling is split into parts, each under about 90% of it, run in sequence. If it cannot be split, report BLOCKED with the remedy `devflow flags --set bash-max-timeout-ms=<ms>`.
+- Never re-run a command when nothing it reads has changed.
+- Never wrap a build or test command in `sh -c`, `bash -c`, `python3 -c` or `node -e`: permission rules deny wrapped commands they would allow directly.
+- The same rules hold inside a dynamic Workflow sub-agent.
 
 ## Mode: issue-fix
 
@@ -265,6 +260,8 @@ Return structured completion status:
 - {Types to import}
 ```
 
+Report cap: final message at most about 1,500 tokens; longer material goes to a `mktemp` file (via Bash or Write) and the message gives its path. Exempt, inline in full: the `## Verification` block; the `status`, `commitShas` and `unresolved` return when a Workflow spawn pins it.
+
 ## Boundaries
 
 **Escalate to orchestrator:**

package/src/assets/agents/design.md

@@ -83,6 +83,8 @@ Follow the `devflow:apply-decisions` skill to scan the `DECISIONS_CONTEXT` index
 **Overall Assessment**: {BLOCKING | SHOULD-ADDRESS | INFORMATIONAL}
 ```
 
+Report cap: final message at most about 1,500 tokens; longer material goes to a `mktemp` file (via Bash or Write) and the message gives its path. Exempt, inline in full: the `## Findings` list.
+
 ## Confidence Scale
 
 | Range | Label | Meaning |

package/src/assets/agents/diagnose.md

@@ -199,6 +199,8 @@ Report format for `{OUTPUT_PATH}`:
 **Recommendation**: {BLOCK | CHANGES_REQUESTED | APPROVED_WITH_CONDITIONS | APPROVED}
 ```
 
+Report cap: final message at most about 1,500 tokens; the report is the file at `{OUTPUT_PATH}`, other longer material goes to a `mktemp` file (via Bash or Write), and the message gives its path and counts. Exempt: none.
+
 ## Principles
 
 1. **Bugs only** — Not style, not architecture, not performance (unless causing incorrect behavior)

package/src/assets/agents/evaluate.md

@@ -44,6 +44,8 @@ You receive from orchestrator:
 6. **Check scope**: Identify out-of-scope additions not justified by design improvements
 7. **Report misalignments**: Document issues with sufficient detail for Code agent to fix
 
+**Gate ownership:** Run no build, test or lint command. Git read commands only. Only Validate runs the full suite.
+
 ## Principles
 
 1. **Intent over letter** - Validate the spirit of the request, not just literal interpretation
@@ -95,6 +97,8 @@ Return structured alignment status:
 | {item} | RESOLVED/STILL_FAILING | {details} |
 ```
 
+Report cap: final message at most about 1,500 tokens; longer material goes to a unique `mktemp`-style temp file written with Write (your Bash is git read-only) and the message gives its path. Exempt, inline in full: the `### Status` line and the `### Misalignments Found` table.
+
 ## Boundaries
 
 **Report as MISALIGNED:**

package/src/assets/agents/knowledge.md

@@ -81,6 +81,8 @@ CROSS_REFERENCES: [ADR/PF IDs whose rule the knowledge base states in words, if
 KB_COMMIT: committed <sha> | skipped (no changes) | skipped (no branch) | skipped (detached HEAD) — uncommitted: <paths> | failed (<reason>)
 ```
 
+Report cap: final message at most about 1,500 tokens; longer material goes to a `mktemp` file (via Bash or Write) and the message gives its path. Exempt, inline in full: the `KB_*` status block.
+
 ## Boundaries
 
 - **Only writes to `.devflow/features/` directory** — never modify source code