devflow-kit 3.0.1 → 3.2.0

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

@@ -77,9 +77,9 @@ export async function validateRuleShadow(shadowFile) {
  *
  * D: Missing declared source is a build/packaging failure — throws rather than
  * silently returning 'skipped' (mirrors command hard-error pattern). Per-item
- * copy failures (EACCES, ENOSPC, etc.) are still isolated (avoids PF-009
- * blast-radius: one bad copy does not abort the whole batch).
- * Invalid shadows still warn-and-install-source (applies ADR-010).
+ * copy failures (EACCES, ENOSPC, etc.) are still isolated
+ * (one bad copy does not abort the whole batch).
+ * Invalid shadows still warn-and-install-source.
  */
 export async function installRuleFile(ruleName, devflowDir, rulesTarget) {
     const shadowFile = path.join(devflowDir, 'rules', mdFileName(ruleName));
@@ -114,7 +114,7 @@ export async function installRuleFile(ruleName, devflowDir, rulesTarget) {
         throw new Error(`Rule source not found for declared rule "${ruleName}": ${ruleSource}. ` +
             `Ensure the rule file exists in src/assets/rules/.`);
     }
-    // Copy is isolated per PF-009: a copy failure degrades to 'skipped' so one
+    // Copy is isolated: a copy failure degrades to 'skipped' so one
     // bad rule does not abort the entire installAllRules Promise.all batch.
     try {
         await fs.copyFile(ruleSource, targetFile);
@@ -236,8 +236,8 @@ export async function chmodRecursive(dir, mode, _depth = 0) {
  * converges to empty. The list is also the one thing that lets the pre-clean keep a
  * nested directory whole ({@link overlayOwnedSkillPaths}), so a directory missing from
  * it fails safe — kept file by file, like the root — rather than keeping its stale files
- * forever (avoids PF-074). The cost is one entry per new wholly-generated directory, and
- * that entry is the whole edit: everything downstream reads the list (avoids PF-015).
+ * forever. The cost is one entry per new wholly-generated directory, and
+ * that entry is the whole edit: everything downstream reads the list.
  */
 const CONVERGED_SUBTREES = [TRACKER_DESTINATION_ROOT, PR_HOST_DESTINATION_ROOT];
 /** Is this top-level directory under the references root one the prune converges? */
@@ -248,7 +248,7 @@ function isConvergedSubtree(top) {
  * One spelling of a unit's name, for every message about it.
  *
  * Pure function — the installer owns the unit types, so it owns how they are named,
- * rather than leaving each render site to invent its own wording (avoids PF-013).
+ * rather than leaving each render site to invent its own wording.
  */
 export function overlayUnitLabel(unit) {
     switch (unit.kind) {
@@ -317,7 +317,7 @@ function isProviderSubdir(subdir) {
  * tracker/{provider}`, so a `tracker/` entry mis-bucketed as a provider renames the
  * whole subtree into place BEFORE the provider units promote back into it, and the
  * installed tree ends up complete under either rule. The classification itself is the
- * observation that separates them (avoids PF-018).
+ * observation that separates them.
  */
 export function planOverlayUnits(manifest) {
     const bySubdir = new Map();
@@ -486,8 +486,8 @@ function subtreesTouchedBy(referencesTarget, unit) {
  * degradation, and shipping an installer that silently omits the mechanics the agent is
  * told to load would move the failure to every user's first spawn.
  *
- * Applies PF-011 (build under a `.tmp` sibling, pre-cleaning an orphan from a prior
- * crashed run). Applies PF-009 for everything else: a copy that fails aborts this unit
+ * Builds under a `.tmp` sibling, pre-cleaning an orphan from a prior crashed run.
+ * Every other failure is isolated to its unit: a copy that fails aborts this unit
  * and no other.
  */
 async function buildUnitStagingTree(unit, sourceRoot, referencesTarget, warn) {
@@ -685,7 +685,7 @@ async function promoteDirectoryUnit(unit, referencesTarget, stagingDir, record)
     // while the report — and the summary line init.ts renders from it — still claims
     // the previously installed files were left unchanged. The backup is what makes
     // that claim true, so a failed promotion is recoverable rather than a silent
-    // deletion (avoids PF-009: a reported failure must describe the state it left).
+    // deletion (a reported failure must describe the state it left).
     //
     // The `.old` backup is pre-cleaned like the `.tmp` tree. A crash that strands
     // either is converged away by a later run's tracker-subtree prune (both names end
@@ -804,7 +804,7 @@ async function classifyUntouchedUnit(unit, referencesTarget) {
  * not cover — and the same root cause the agent resolver in `installViaFileCopy` already
  * throws for, so the two build artifacts are guarded at the same strength.
  *
- * Deliberately ONE `stat` before the unit loop rather than a check inside it (PF-009):
+ * Deliberately ONE `stat` before the unit loop rather than a check inside it:
  * the fan-out has no per-item failure isolation, so a per-unit refusal would let one
  * unbuilt provider abort every other unit's install. A unit directory that is absent
  * under a root that exists stays a per-unit report, exactly as today.
@@ -852,7 +852,7 @@ async function requireGeneratedTree(sourceRoot, manifest) {
  *
  * The skip is not silent. The unswept subtree is reported through `failed` — the same
  * channel that module uses for its own depth-bound breach — so nothing claims
- * convergence over ground it did not cover (avoids PF-009, PF-015). Orphans under that
+ * convergence over ground it did not cover. Orphans under that
  * subtree survive this install and the next one converges them.
  *
  * A subtree whose root is not a real directory ({@link convergedRootFault}) is skipped
@@ -974,8 +974,8 @@ async function pruneConvergedSubtrees(referencesTarget, manifest, overlayFailure
  * @param opts.warn - Receives non-fatal notices (skipped symlinks, mode normalisation).
  *
  * @throws on three conditions, each of them a build artifact that was never produced
- *   rather than an I/O degradation. Every other failure is reported, never thrown
- *   (PF-009), and the three are ordered here as the function reaches them:
+ *   rather than an I/O degradation. Every other failure is reported, never thrown,
+ *   and the three are ordered here as the function reaches them:
  *   1. `opts.manifest` omitted AND the reference-module registry does not expand —
  *      raised by {@link generatedReferenceManifest} while resolving the default. A
  *      caller that passes its own manifest cannot reach this one.
@@ -1048,12 +1048,12 @@ export async function overlayGeneratedReferences(opts) {
     // this run installed. copyDirectory preserves source modes, so a hand-authored
     // reference checked in with an odd mode installs with it; a reference is read-only
     // instruction text and 0644 is what every one of them should be. Best-effort: a
-    // filesystem that does not honour mode bits must not fail an install (PF-009).
+    // filesystem that does not honour mode bits must not fail an install.
     //
     // This is the one step that reaches a file the overlay does not own, and it is why the
     // boundary is stated as "never replace or delete" rather than "never touch": the MODE of
     // a hand-authored reference — and of whatever a shadowed skill supplied outside
-    // `tracker/` — is normalised here. ADR-024 corollary (b) permits exactly that: the
+    // `tracker/` — is normalised here. The prove-you-wrote-it rule permits exactly that: the
     // ownership guard protects deletion, not overwrite.
     //
     // It is also the one walk that can breach chmodRecursive's descent bound. The catch is
@@ -1096,9 +1096,9 @@ const SKILL_REFERENCES_DIRNAME = 'references';
  * Deciding the subtree arm by {@link CONVERGED_SUBTREES} rather than by nesting is what
  * makes the two lists agree by construction: a directory is kept whole exactly when a
  * prune owns it, so a fan-out directory registered without a converged entry fails safe
- * instead of surviving every install (avoids PF-074).
+ * instead of surviving every install.
  *
- * Pure function (applies ADR-013). Exported for the one property no installed-tree arm
+ * Pure function. Exported for the one property no installed-tree arm
  * can reach: the build emits no nested directory outside the converged list, so the
  * fail-safe arm is only observable on a manifest the registry does not produce.
  */
@@ -1284,7 +1284,7 @@ async function firstExisting(candidates) {
  * One readdir of the SHADOW tree, intersected with the registry. Deliberately
  * not a readdir of the installed skills directory: that tree is the thing being
  * converged, and reading it to decide what to remove is how a directory a user
- * put there by hand becomes a deselection (applies ADR-024).
+ * put there by hand becomes a deselection.
  *
  * Whether a shadow is VALID is a separate question, answered per skill by
  * validateSkillShadow at install time. This only answers "did the user write
@@ -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,
@@ -1336,7 +1365,7 @@ export async function installViaFileCopy(options) {
     // Pure and registry-driven: the removal set is `skillsOf(all) \ skillsOf(selected)
     // \ FEATURE_OWNED`, never a readdir of the installed skills directory, so an
     // unrelated `devflow:` directory a user put there by hand is not swept as a
-    // deselection (applies ADR-024).
+    // deselection.
     //
     // Computed BEFORE shadows are resolved: a shadow is applied only to a skill the
     // selection installs, so the install set is the question that has to be settled
@@ -1383,7 +1412,7 @@ export async function installViaFileCopy(options) {
     // knownNames spans ALL plugins (getAllSkillNames) so skills from uninstalled
     // plugins survive a partial run. Bare (pre-namespace) dirs are intentionally
     // untouched — they are handled by the frozen LEGACY_SKILLS_* lists in legacy.ts
-    // (avoids PF-012: those lists are deletion manifests for pre-namespace paths and
+    // (those lists are deletion manifests for pre-namespace paths and
     // must not be modified). Shadow dirs (~/.devflow/skills/) are keyed by bare
     // registry name and are unaffected by this sweep.
     // knownNames unions FEATURE_OWNED_SKILLS so feature-owned skills (e.g. devflow:compliance)
@@ -1396,7 +1425,7 @@ export async function installViaFileCopy(options) {
     // ~/.claude/skills/{name} are owned solely by the frozen LEGACY_SKILL_NAMES
     // pass in init.ts (runs immediately after this call). A bare dir whose name
     // matches a current registry skill is by construction foreign to Devflow and
-    // must not be touched here (avoids PF-012).
+    // must not be touched here.
     //
     // The pre-clean is SCOPED to what this run reinstalls and the orphan sweep
     // above is UNSCOPED (the full registry). The opposite scoping is deliberate,
@@ -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 (applies PF-009).
-    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/legacy.js

@@ -11,7 +11,7 @@
  * These lists are FROZEN deletion manifests for names that once shipped: the
  * `*_V2` suffix is the frozen spelling of an era, not a version to bump, and a
  * name is removed from a list only when its pruning window has passed — never
- * renamed to match a current registry name (avoids PF-012).
+ * renamed to match a current registry name.
  */
 /** Pre-v1.0.0: devflow- prefixed skill names from the original install scheme. */
 const LEGACY_SKILLS_PRE_V1 = [

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

@@ -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 &&
@@ -37,7 +38,7 @@ const CLAUDEIGNORE_NEGATION = '!.claudeignore';
 /**
  * Re-includes the retired evidence-policy file (D-GITIGNORE-V5,
  * D-POLICY-JSON-RETIRED). A COMPLETION line, never a presence sentinel: users may author it themselves, so its presence
- * proves nothing about the devflow block (avoids PF-059). It sits after `.devflow/*`
+ * proves nothing about the devflow block. It sits after `.devflow/*`
  * (which it overrides under last-match-wins) and before `.claudeignore`, so the
  * block's final line stays `.claudeignore`.
  */
@@ -46,11 +47,11 @@ 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`,
+ * the block. 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).
+ * `git add -f`. Devflow never writes the file itself.
  */
 const DEVFLOW_PROJECT_LINE = '!.devflow/project.json';
 /**
@@ -143,7 +144,7 @@ const BLOCK_RUN_MAX = 3;
  * user-authored line inverts both halves of the contract: projects that already carry
  * that line are told the block is installed when it is not, and a user's
  * `!.claudeignore` un-ignore is silently reversed by re-appending `.claudeignore`
- * under last-match-wins (avoids PF-059).
+ * under last-match-wins.
  *
  * `hasClaudeignoreEntry` is true when some whole line, trimmed, is exactly
  * `.claudeignore` OR `!.claudeignore`. Treating both forms as "present" both honours
@@ -301,7 +302,7 @@ export function mergeDenyList(existingJson, newDenyEntries, retired = new Set())
 // holds it. (Claude Code's own suggestion, `-v /*`, would deny every absolute mount.)
 // 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).
+// shipped would be taken from a user who wrote it (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 /*)',
@@ -500,7 +501,7 @@ export const DEVFLOW_HISTORICAL_DENY = Object.freeze(new Set([
  * 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
+ * Accepted trade-off: 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
@@ -981,7 +982,7 @@ function hookCommandsOf(matcher) {
  *
  * `existing` comes from a hand-editable file, so every branch is shape-guarded:
  * a `hooks` value (or per-event value) that is not the expected object/array shape
- * is left untouched rather than overwritten or thrown on (applies PF-023 — validate
+ * is left untouched rather than overwritten or thrown on (validate
  * at the sink that mutates).
  *
  * Exported for testing.
@@ -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/dist/targets/claude-code/tracker-install.js

@@ -6,8 +6,8 @@
  * installer.ts — a mode flag on this function would have made it a second
  * (design review M2).
  *
- * Applies ADR-013: I/O orchestration in src/targets/; pure helpers in src/core/.
- * Applies PF-009: warn-not-throw, so one failing artifact never aborts an install.
+ * I/O orchestration in src/targets/; pure helpers in src/core/.
+ * Warn-not-throw, so one failing artifact never aborts an install.
  */
 import { promises as fs } from 'fs';
 import * as path from 'path';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devflow-kit",
-  "version": "3.0.1",
+  "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

@@ -61,12 +61,9 @@ You receive from orchestrator:
    - Cross-reference changed files against EXECUTION_PLAN to identify what's relevant to your task
    - Read those relevant files to understand interfaces, types, naming conventions, error handling, and testing patterns established by prior work
    - If PRIOR_PHASE_SUMMARY is provided, use it to validate your understanding — actual code is authoritative, summaries are supplementary
-   - If `DECISIONS_CONTEXT` is provided, follow `devflow:apply-decisions` to scan the index and Read full bodies on demand. Otherwise, if `.devflow/learning/decisions.md` exists, read it directly. Apply prior architectural decisions relevant to this task.
-   - If `DECISIONS_CONTEXT` is `(none)` or absent: if `.devflow/learning/pitfalls.md` exists, scan for pitfalls in files you're about to modify.
+   - If `DECISIONS_CONTEXT` is provided, follow `devflow:apply-decisions` on it. Otherwise read the decisions index — `.devflow/learning/index.md` at the repository's main worktree (`git rev-parse --path-format=absolute --git-common-dir`; when it ends in `/.git` the index lives under its parent) — and follow `devflow:apply-decisions` on it; skip it when absent, empty or `(none)`. State every decision or pitfall you apply in words in code, comments, tests and commit messages, never by its ID.
    - If `HANDOFF_FILE` is provided, read it for prior phase context. Cross-reference against actual code — code is authoritative, handoff is supplementary.
 
-When you apply a decision from `.devflow/learning/decisions.md` or avoid a pitfall from `.devflow/learning/pitfalls.md`, cite the entry ID in your final summary (e.g., 'applying ADR-003' or 'per PF-002') so usage can be tracked for capacity reviews.
-
 2. **Load domain skills**: Before any analysis, invoke the Skill tool for the domain skills matching the language and stack of the code being touched:
    - `backend` (TypeScript): `Skill(skill="devflow:typescript")`
    - `backend` (Go): `Skill(skill="devflow:go")`
@@ -82,7 +79,8 @@ When you apply a decision from `.devflow/learning/decisions.md` or avoid a pitfa
 
 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).
 
@@ -128,24 +126,18 @@ When you apply a decision from `.devflow/learning/decisions.md` or avoid a pitfa
 
 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)
-
-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:
+## Running commands
 
-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.
+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}`).
 
-**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
 
@@ -268,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

@@ -23,13 +23,13 @@ The orchestrator provides:
 
 **Worktree Support**: If `WORKTREE_PATH` is provided, follow the `devflow:worktree-support` skill for path resolution. If omitted, use cwd.
 
-- **DECISIONS_CONTEXT** (optional): Compact index of active ADR/PF entries for this worktree (pre-rendered to `.devflow/learning/index.md`). `(none)` when absent. Use `devflow:apply-decisions` to Read full bodies on demand.
+- **DECISIONS_CONTEXT** (optional): Compact index of active ADR/PF entries for this repository (pre-rendered to `.devflow/learning/index.md` in its main worktree). `(none)` when absent. Use `devflow:apply-decisions` to Read full bodies on demand.
 - **COMPLIANCE_FRAMEWORKS** (compliance focus): `none` (generic controls) or the framework ids in force. Load `references/{id}.md` only for these ids.
 - **FEATURE_KNOWLEDGE** (optional): Pre-computed feature area context for pattern-aware gap analysis. Incorporate feature area patterns and architecture into gap analysis — design additions that fit existing structure. Follow `devflow:apply-feature-knowledge`.
 
 ## Apply Decisions
 
-Follow the `devflow:apply-decisions` skill to scan the `DECISIONS_CONTEXT` index, Read full ADR/PF bodies on demand, and cite `applies ADR-NNN` / `avoids PF-NNN` in findings. Skip when `DECISIONS_CONTEXT` is empty or `(none)`.
+Follow the `devflow:apply-decisions` skill to scan the `DECISIONS_CONTEXT` index and Read full ADR/PF bodies on demand. A finding that rests on a decision or pitfall states that rule in words, never its ID: findings feed plans and tickets that are posted to the tracker. Skip when `DECISIONS_CONTEXT` is empty or `(none)`.
 
 ## Modes
 
@@ -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 |