devflow-kit 3.8.0 → 3.10.0

package/dist/skills/git/references/tracker/github/manage-debt.md

@@ -1,6 +1,11 @@
 ## Operation: manage-debt
 
-Update tech debt backlog with deferred issues from resolution and pre-existing issues from code review.
+Update tech debt backlog from `{REVIEW_DIR}/resolution-summary.md`:
+- Add only entries of `## Fix Separately` (FIX_SEPARATE) and `## Deferred to Tech Debt` (TECH_DEBT). A section ends at the next heading.
+- An empty section adds none.
+- If `resolution-summary.md` is missing, return `TRACEABILITY: DEGRADED (resolution summary missing)` and do not update the backlog.
+- Never add an item that also has an entry in `## Escalations`, `## Blocked` or `## Fixed Issues`.
+- Read no review report: in `{REVIEW_DIR}`, read only `resolution-summary.md`.
 
 **Input:** `REVIEW_DIR`, `TIMESTAMP`, `WORKTREE_PATH` (optional)
 
@@ -31,7 +36,6 @@ Load when the resolved tracker provider is `github` and the operation is `manage
 3. Extract items to add:
    - `## Fix Separately` entries from `{REVIEW_DIR}/resolution-summary.md` (FIX_SEPARATE from Triage agent)
    - `## Deferred to Tech Debt` entries from `{REVIEW_DIR}/resolution-summary.md` (TECH_DEBT from Triage agent)
-   - Pre-existing issues (Category 3) from review reports
 4. Deduplicate against existing items using semantic matching
 5. Remove items that have been fixed (verify in codebase)
 6. Compose updated issue body to `$DEVFLOW_BODY_RAW`; apply the Comment-sink scrub (D11) and post via `gh issue edit {number} --body-file "$DEVFLOW_BODY"`

package/dist/skills/git/references/tracker/jira/manage-debt.md

@@ -1,6 +1,11 @@
 ## Operation: manage-debt
 
-Update tech debt backlog with deferred issues from resolution and pre-existing issues from code review.
+Update tech debt backlog from `{REVIEW_DIR}/resolution-summary.md`:
+- Add only entries of `## Fix Separately` (FIX_SEPARATE) and `## Deferred to Tech Debt` (TECH_DEBT). A section ends at the next heading.
+- An empty section adds none.
+- If `resolution-summary.md` is missing, return `TRACEABILITY: DEGRADED (resolution summary missing)` and do not update the backlog.
+- Never add an item that also has an entry in `## Escalations`, `## Blocked` or `## Fixed Issues`.
+- Read no review report: in `{REVIEW_DIR}`, read only `resolution-summary.md`.
 
 **Input:** `REVIEW_DIR`, `TIMESTAMP`, `WORKTREE_PATH` (optional)
 
@@ -31,7 +36,6 @@ Load when the resolved tracker provider is `jira` and the operation is `manage-d
 3. Extract items to add:
    - `## Fix Separately` entries from `{REVIEW_DIR}/resolution-summary.md` (FIX_SEPARATE from Triage agent)
    - `## Deferred to Tech Debt` entries from `{REVIEW_DIR}/resolution-summary.md` (TECH_DEBT from Triage agent)
-   - Pre-existing issues (Category 3) from review reports
 4. Deduplicate against existing items using semantic matching.
 5. Remove items that have been fixed (verify in codebase).
 6. Compose the updated description and post it through the gate in `### Posting gate` below, using the *update description* capability.

package/dist/skills/git/references/tracker/linear/manage-debt.md

@@ -1,6 +1,11 @@
 ## Operation: manage-debt
 
-Update tech debt backlog with deferred issues from resolution and pre-existing issues from code review.
+Update tech debt backlog from `{REVIEW_DIR}/resolution-summary.md`:
+- Add only entries of `## Fix Separately` (FIX_SEPARATE) and `## Deferred to Tech Debt` (TECH_DEBT). A section ends at the next heading.
+- An empty section adds none.
+- If `resolution-summary.md` is missing, return `TRACEABILITY: DEGRADED (resolution summary missing)` and do not update the backlog.
+- Never add an item that also has an entry in `## Escalations`, `## Blocked` or `## Fixed Issues`.
+- Read no review report: in `{REVIEW_DIR}`, read only `resolution-summary.md`.
 
 **Input:** `REVIEW_DIR`, `TIMESTAMP`, `WORKTREE_PATH` (optional)
 
@@ -31,7 +36,6 @@ Load when the resolved tracker provider is `linear` and the operation is `manage
 3. Extract items to add:
    - `## Fix Separately` entries from `{REVIEW_DIR}/resolution-summary.md` (FIX_SEPARATE from Triage agent)
    - `## Deferred to Tech Debt` entries from `{REVIEW_DIR}/resolution-summary.md` (TECH_DEBT from Triage agent)
-   - Pre-existing issues (Category 3) from review reports
 4. Deduplicate against existing items using semantic matching.
 5. Remove items that have been fixed (verify in codebase).
 6. Compose the updated description and post it through the gate in `### Posting gate` below, using the *update description* capability.

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

@@ -22,6 +22,7 @@
 import { promises as fs } from 'fs';
 import * as path from 'path';
 import { installRuleFile } from './installer.js';
+import { newLinkReport, refuseUnrealFolder, warnLinkReport } from './linked-folder.js';
 // ── Types ──────────────────────────────────────────────────────────────────
 export const BEHAVIOR_RULE_NAME = 'behavior';
 // ── Path helpers ───────────────────────────────────────────────────────────
@@ -47,46 +48,59 @@ async function pathExists(p) {
  *   enabled + !rulesEnabled  → rule file removed
  *   !enabled                 → rule file removed
  *
+ * `rules/devflow` that is a link, or not a folder, is refused: the rule is neither written nor
+ * removed there, and the folder is named in `refusedFolders` and in a warning. A rule file that is a
+ * link is replaced by a real file, or unlinked on removal, and never written through.
+ *
  * Never throws. A relative `claudeDir` is refused with a warning rather than resolved
  * against the working directory, because the removal arm deletes a path.
  */
 export async function convergeBehaviorRule(opts) {
     const { claudeDir, devflowDir, enabled, rulesEnabled, warn } = opts;
+    const links = newLinkReport();
+    const finish = (state) => {
+        warnLinkReport(links, warn);
+        return { ...state, replacedLinks: links.replacedLinks, refusedFolders: links.refusedFolders };
+    };
     if (!path.isAbsolute(claudeDir)) {
         warn(`behavior: claudeDir is not an absolute path ("${claudeDir}") — skipping convergence`);
-        return { installed: false, removed: false, converged: false };
+        return finish({ installed: false, removed: false, converged: false });
     }
     const target = behaviorRulePath(claudeDir);
+    // A link at the folder sends the write and the removal into another place, so the folder is proven first.
+    if (await refuseUnrealFolder(links, path.dirname(target))) {
+        return finish({ installed: await pathExists(target), removed: false, converged: false });
+    }
     if (enabled && rulesEnabled) {
         try {
             await fs.mkdir(path.dirname(target), { recursive: true });
-            const outcome = await installRuleFile(BEHAVIOR_RULE_NAME, devflowDir, path.dirname(target));
+            const outcome = await installRuleFile(BEHAVIOR_RULE_NAME, devflowDir, path.dirname(target), links);
             if (outcome === 'skipped') {
                 warn('behavior: rule install failed — the file could not be copied');
-                return { installed: false, removed: false, converged: false };
+                return finish({ installed: false, removed: false, converged: false });
             }
             if (outcome === 'source-invalid-shadow:empty-shadow-file' || outcome === 'source-invalid-shadow:not-a-file') {
                 warn("behavior: the shadow is invalid — Devflow's version was installed");
-                return { installed: true, removed: false, converged: false };
+                return finish({ installed: true, removed: false, converged: false });
             }
-            return { installed: true, removed: false, converged: true };
+            return finish({ installed: true, removed: false, converged: true });
         }
         catch (err) {
             warn(`behavior: rule install failed — ${String(err)}`);
-            return { installed: false, removed: false, converged: false };
+            return finish({ installed: false, removed: false, converged: false });
         }
     }
     // Off, or rules off: no rule. Probe first so the caller can report a removal;
     // absence is already the desired end state.
     if (!(await pathExists(target)))
-        return { installed: false, removed: false, converged: true };
+        return finish({ installed: false, removed: false, converged: true });
     try {
         await fs.rm(target, { force: true });
-        return { installed: false, removed: true, converged: true };
+        return finish({ installed: false, removed: true, converged: true });
     }
     catch (err) {
         warn(`behavior: failed to remove rule — ${String(err)}`);
-        return { installed: true, removed: false, converged: false };
+        return finish({ installed: true, removed: false, converged: false });
     }
 }
 // ── Manifest-slice wrapper ─────────────────────────────────────────────────

package/dist/targets/claude-code/charter-render.js

@@ -0,0 +1,374 @@
+/**
+ * Install-time render of the ambient orchestrator charter, and the implement sentinel.
+ *
+ * D-CHARTER-INSTALL-RENDER: the packaged charter (src/assets/scripts/hooks/assets/orchestrator-charter.md)
+ * is the FULL text. It routes to workflows and agents that a machine may not install, so `devflow init`
+ * writes a copy with the lines of every uninstalled owner deleted, and the session-start hook injects that
+ * copy whole. Decided here:
+ *
+ *   - The render only deletes. It inserts no text and reads no name into the output: the inventory (which
+ *     commands and agents the selection installs) is used for presence checks alone. The full source is
+ *     also the fallback, so a render that cannot run installs the full charter and warns; it never aborts
+ *     the install.
+ *   - The span table is the whole contract between the charter text and this module. Every span is counted
+ *     in the ORIGINAL source before any removal, and a span that occurs 0 or more than 1 times fails the
+ *     render, so wording drift in the charter surfaces at install time and in the test, never as a
+ *     silently wrong charter. The edits are ranges of the original source applied once, and two chosen
+ *     ranges that share bytes fail the render rather than cut through each other.
+ *   - The two debug-command spans overlap on `, else ` by design (`devflow:debug, else Explore ...`). They
+ *     share one owner with opposite polarity, so a render removes exactly one of them: the fallback
+ *     sentence when debug is installed, the command mention when it is not.
+ *   - devflow-ambient's agents count as installed whatever the selection says. The charter belongs to that
+ *     plugin, and the hooks inject it only while ambient mode is on, which is when `devflow init` installs
+ *     the plugin; `devflow ambient --enable` warns when it is not installed.
+ *   - The sentinel (`hooks/assets/implement-installed`) exists exactly when devflow-implement is installed.
+ *     The per-prompt preamble branches on its existence with a shell builtin, so the plan-handoff directive
+ *     runs only where the workflow it names exists. This module is the only writer of the charter and the
+ *     sentinel at install time; the verbatim script copy skips both.
+ *   - `mode: 'uninstall'` is the uninstall mode. An uninstall re-renders a charter that is installed from the
+ *     manifest record and may take the sentinel away, but never creates a file. With no record to render
+ *     from, `removeHandoffSentinel` takes the sentinel away alone and the charter stays as it is.
+ *   - A change guard is asked about a file before the file is read, and every write or removal follows it.
+ *   - After a package upgrade the installed charter stays as rendered until the next `devflow init`.
+ *
+ * Never throws: every failure is a warning and a `failed` outcome, because the install must not die on a
+ * charter. Silent on success.
+ */
+import { promises as fs } from 'fs';
+import * as path from 'path';
+import { scriptsDir as packagedScriptsDir } from '../../core/assets.js';
+import { writeFileAtomicExclusive } from '../../core/fs-atomic.js';
+import { DEVFLOW_PLUGINS, registeredPluginNames } from '../../core/plugins.js';
+/** The charter, relative to the scripts directory (packaged and installed alike). */
+export const CHARTER_RELPATH = 'hooks/assets/orchestrator-charter.md';
+/** The sentinel, relative to the scripts directory. It exists exactly when devflow-implement is installed. */
+export const HANDOFF_SENTINEL_RELPATH = 'hooks/assets/implement-installed';
+/** The plugin whose agents the charter always treats as installed. */
+const AMBIENT_PLUGIN = 'devflow-ambient';
+/** The permission bits of an installed charter or sentinel: the hooks directory is installed executable. */
+const INSTALLED_MODE = 0o755;
+/** The command whose presence the sentinel records. */
+const HANDOFF_COMMAND = 'implement';
+/** The workflow list's items, in the order the charter joins them with `, `. */
+export const CHARTER_WORKFLOW_ITEMS = [
+    { text: 'devflow:implement', owner: { kind: 'command', name: 'implement' } },
+    { text: 'devflow:plan', owner: { kind: 'command', name: 'plan' } },
+    { text: 'devflow:research', owner: { kind: 'command', name: 'research' } },
+    { text: 'devflow:explore', owner: { kind: 'command', name: 'explore' } },
+    { text: 'devflow:code-review', owner: { kind: 'command', name: 'code-review' } },
+    { text: 'devflow:resolve', owner: { kind: 'command', name: 'resolve' } },
+    {
+        text: 'devflow:bug-analysis (hunt bugs in a branch before merge)',
+        owner: { kind: 'command', name: 'bug-analysis' },
+    },
+];
+/** The joined list as the charter spells it: it occurs once, on the workflow bullet. */
+export const CHARTER_WORKFLOW_LIST = CHARTER_WORKFLOW_ITEMS.map(item => item.text).join(', ');
+/** Every other span: removal-only, each tied to one owner. */
+export const CHARTER_SPANS = [
+    {
+        shape: 'text',
+        text: 'Fix (`OPERATION:` `validation-fix`, `alignment-fix`, `qa-fix` or `ci-fix`), else ',
+        owner: { kind: 'agent', name: 'fix' },
+        removedWhen: 'absent',
+    },
+    {
+        shape: 'text',
+        text: 'devflow:debug, else ',
+        owner: { kind: 'command', name: 'debug' },
+        removedWhen: 'absent',
+    },
+    {
+        shape: 'text',
+        text: ', else Explore investigates and Code fixes',
+        owner: { kind: 'command', name: 'debug' },
+        removedWhen: 'present',
+    },
+    {
+        shape: 'text',
+        text: '; never the Debug agent',
+        owner: { kind: 'agent', name: 'debug' },
+        removedWhen: 'absent',
+    },
+    {
+        shape: 'line',
+        text: '- Plan handoff: ',
+        owner: { kind: 'command', name: HANDOFF_COMMAND },
+        removedWhen: 'absent',
+    },
+];
+/**
+ * The commands and agents a plugin selection installs.
+ *
+ * Only names in DEVFLOW_PLUGINS count: a manifest is file content, so an unknown, deleted or hostile name
+ * selects nothing, and a name that reaches here from a legacy install maps to its current plugin
+ * ({@link registeredPluginNames}). Every caller reaches this check, so it holds whatever the caller filtered.
+ * devflow-ambient's agents are always included. The names are used for presence checks only and never reach
+ * the rendered text.
+ */
+export function charterInventory(pluginNames) {
+    const selected = new Set(registeredPluginNames(pluginNames));
+    const commands = new Set();
+    const agents = new Set();
+    for (const plugin of DEVFLOW_PLUGINS) {
+        if (plugin.name === AMBIENT_PLUGIN) {
+            for (const agent of plugin.agents)
+                agents.add(agent);
+        }
+        if (!selected.has(plugin.name))
+            continue;
+        for (const command of plugin.commands)
+            commands.add(command.startsWith('/') ? command.slice(1) : command);
+        for (const agent of plugin.agents)
+            agents.add(agent);
+    }
+    return { commands, agents };
+}
+/** How many times `needle` occurs in `haystack`, overlapping occurrences included. Bounded by the haystack length. */
+function occurrencesOf(haystack, needle) {
+    if (needle.length === 0)
+        return 0;
+    let count = 0;
+    for (let from = haystack.indexOf(needle); from !== -1; from = haystack.indexOf(needle, from + 1))
+        count++;
+    return count;
+}
+/** The range of the whole line that holds `index`, its newline included. */
+function lineRangeAt(source, index) {
+    const start = index === 0 ? 0 : source.lastIndexOf('\n', index - 1) + 1;
+    const newline = source.indexOf('\n', index);
+    return { start, end: newline === -1 ? source.length : newline + 1 };
+}
+/** The one place `span` sits in `source`, or the way it fails to. */
+function locateSpan(source, span) {
+    if (span.shape === 'text') {
+        const count = occurrencesOf(source, span.text);
+        if (count !== 1)
+            return { reason: count === 0 ? 'missing' : 'repeated' };
+        const start = source.indexOf(span.text);
+        return { start, end: start + span.text.length };
+    }
+    const starts = [];
+    let lineStart = 0;
+    for (const line of source.split('\n')) {
+        if (line.startsWith(span.text))
+            starts.push(lineStart);
+        lineStart += line.length + 1;
+    }
+    if (starts.length !== 1)
+        return { reason: starts.length === 0 ? 'missing' : 'repeated' };
+    return lineRangeAt(source, starts[0]);
+}
+/**
+ * `source` with the spans of every uninstalled owner deleted.
+ *
+ * Pure. Counts every span in the original source first and fails on a span that occurs 0 or more than 1
+ * times; a render that cannot be trusted returns `{ok: false}` and the caller keeps the full source. The
+ * workflow list keeps its installed items in order (with none kept, the whole bullet line goes), every
+ * other span goes when its owner is absent (or, for the debug fallback, present).
+ */
+export function renderCharter(source, installedCommands, installedAgents) {
+    const installed = (owner) => (owner.kind === 'command' ? installedCommands : installedAgents).has(owner.name);
+    // 1. Place every span in the original source, before anything is removed.
+    const listCount = occurrencesOf(source, CHARTER_WORKFLOW_LIST);
+    if (listCount !== 1) {
+        return { ok: false, reason: listCount === 0 ? 'missing' : 'repeated', span: CHARTER_WORKFLOW_LIST };
+    }
+    const listStart = source.indexOf(CHARTER_WORKFLOW_LIST);
+    const placed = [];
+    for (const span of CHARTER_SPANS) {
+        const at = locateSpan(source, span);
+        if ('reason' in at)
+            return { ok: false, reason: at.reason, span: span.text };
+        placed.push({ span, at });
+    }
+    // 2. Decide the edits, all against the original source.
+    const edits = [];
+    const kept = CHARTER_WORKFLOW_ITEMS.filter(item => installed(item.owner));
+    if (kept.length === 0) {
+        edits.push({ ...lineRangeAt(source, listStart), replacement: '', span: CHARTER_WORKFLOW_LIST });
+    }
+    else if (kept.length < CHARTER_WORKFLOW_ITEMS.length) {
+        edits.push({
+            start: listStart,
+            end: listStart + CHARTER_WORKFLOW_LIST.length,
+            replacement: kept.map(item => item.text).join(', '),
+            span: CHARTER_WORKFLOW_LIST,
+        });
+    }
+    for (const { span, at } of placed) {
+        const present = installed(span.owner);
+        if (span.removedWhen === 'absent' ? !present : present) {
+            edits.push({ start: at.start, end: at.end, replacement: '', span: span.text });
+        }
+    }
+    // 3. Apply them once, left to right. Two edits that share bytes cannot both be right.
+    edits.sort((a, b) => a.start - b.start);
+    let out = '';
+    let at = 0;
+    for (const edit of edits) {
+        if (edit.start < at)
+            return { ok: false, reason: 'overlap', span: edit.span };
+        out += source.slice(at, edit.start) + edit.replacement;
+        at = edit.end;
+    }
+    return { ok: true, content: out + source.slice(at) };
+}
+/** The file's bytes, or null when there is no such file. Any other failure throws to the caller's catch. */
+async function readIfPresent(file) {
+    try {
+        return await fs.readFile(file);
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return null;
+        throw err;
+    }
+}
+/** Whether the change guard lets this run touch `file`; with no guard, every file may change. */
+async function permitted(file, mayChange) {
+    return mayChange === undefined || (await mayChange(file));
+}
+/** `warn`, made safe to call: a closed sink must not fail the install. */
+function quietly(warn) {
+    return msg => {
+        try {
+            warn(msg);
+        }
+        catch { /* a closed sink must not fail the install */ }
+    };
+}
+/** Write `text` unless `current` already holds exactly those bytes, atomically and executable. The caller has asked the change guard. */
+async function writeIfChanged(file, current, text) {
+    if (current !== null && current.equals(Buffer.from(text, 'utf-8')))
+        return 'unchanged';
+    await fs.mkdir(path.dirname(file), { recursive: true });
+    await writeFileAtomicExclusive(file, text, INSTALLED_MODE);
+    // A create mode passes through the umask, while composeScripts sets every file under hooks/ to 0755 on
+    // the next run whatever the umask is. Set the mode here too, or a second init changes it on disk.
+    if (process.platform !== 'win32')
+        await fs.chmod(file, INSTALLED_MODE);
+    return 'rewritten';
+}
+/**
+ * Remove the sentinel behind the change guard, without reading it; a file that is already gone is not an
+ * error. A failure is a warning and `failed`.
+ */
+async function removeSentinel(sentinelTarget, mayChange, warn) {
+    try {
+        if (!(await permitted(sentinelTarget, mayChange)))
+            return 'failed';
+        await fs.unlink(sentinelTarget);
+        return 'rewritten';
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return 'absent';
+        warn(`charter render: could not sync the implement sentinel (${sentinelTarget}) — ${String(err)}`);
+        return 'failed';
+    }
+}
+/** Why a render failed, in a sentence for the warning. */
+function describeFailure(result) {
+    const problem = {
+        missing: 'is missing from',
+        repeated: 'occurs more than once in',
+        overlap: 'overlaps another span in',
+    }[result.reason];
+    return `the span "${result.span}" ${problem} the packaged charter, so the full charter was installed.`;
+}
+/**
+ * Write the charter rendered for `plugins`, and sync the implement sentinel with it.
+ *
+ * Called by installScripts after the script copy (which installViaFileCopy and `init --hud-only` both
+ * run), and by the selective uninstall phase. The two files are independent: each has its own try/catch,
+ * so a failure on one never costs the other. Each file is checked with the change guard before it is read.
+ * Bytes are compared with the bytes on disk at the moment of writing, so a rerun that changes nothing
+ * writes nothing.
+ */
+export async function installRenderedCharter(opts) {
+    const { scriptsDir: target, plugins, mayChange, mode } = opts;
+    const warn = quietly(opts.warn);
+    // Precondition, asserted in production code: a relative scriptsDir would resolve against the working directory.
+    if (!path.isAbsolute(target)) {
+        warn(`charter render: scriptsDir is not an absolute path ("${target}") — the installed charter was not rendered`);
+        return { charter: 'failed', sentinel: 'failed' };
+    }
+    const inventory = charterInventory(plugins.map(plugin => (typeof plugin === 'string' ? plugin : plugin.name)));
+    const charterTarget = path.join(target, CHARTER_RELPATH);
+    const sentinelTarget = path.join(target, HANDOFF_SENTINEL_RELPATH);
+    const packagedRoot = () => {
+        try {
+            return opts.packagedScriptsDir ?? packagedScriptsDir();
+        }
+        catch (err) {
+            warn(`charter render: cannot find the packaged scripts — ${String(err)}`);
+            return null;
+        }
+    };
+    const installCharter = async () => {
+        try {
+            if (!(await permitted(charterTarget, mayChange)))
+                return 'failed';
+            const current = await readIfPresent(charterTarget);
+            if (current === null && mode === 'uninstall')
+                return 'absent';
+            const root = packagedRoot();
+            if (root === null)
+                return 'failed';
+            const source = await fs.readFile(path.join(root, CHARTER_RELPATH), 'utf-8');
+            const rendered = renderCharter(source, inventory.commands, inventory.agents);
+            if (!rendered.ok)
+                warn(`charter render: ${describeFailure(rendered)}`);
+            return await writeIfChanged(charterTarget, current, rendered.ok ? rendered.content : source);
+        }
+        catch (err) {
+            warn(`charter render: could not install the charter (${charterTarget}) — ${String(err)}`);
+            return 'failed';
+        }
+    };
+    const syncSentinel = async () => {
+        if (!inventory.commands.has(HANDOFF_COMMAND))
+            return removeSentinel(sentinelTarget, mayChange, warn);
+        try {
+            if (!(await permitted(sentinelTarget, mayChange)))
+                return 'failed';
+            const current = await readIfPresent(sentinelTarget);
+            if (mode === 'uninstall')
+                return current === null ? 'absent' : 'unchanged';
+            const root = packagedRoot();
+            if (root === null)
+                return 'failed';
+            const text = await fs.readFile(path.join(root, HANDOFF_SENTINEL_RELPATH), 'utf-8');
+            return await writeIfChanged(sentinelTarget, current, text);
+        }
+        catch (err) {
+            warn(`charter render: could not sync the implement sentinel (${sentinelTarget}) — ${String(err)}`);
+            return 'failed';
+        }
+    };
+    const charter = await installCharter();
+    const sentinel = await syncSentinel();
+    return { charter, sentinel };
+}
+/**
+ * Take the implement sentinel away when the removed plugins include the owner of the handoff command, and
+ * touch nothing else. For an uninstall with no manifest record: the charter has nothing to be rendered
+ * from and stays as it is, but the sentinel needs no record, and without it the per-prompt preamble falls
+ * back to the generic reminder instead of naming a workflow that is gone.
+ *
+ * `rewritten` when the sentinel was removed, `absent` when there was none, `unchanged` when the removed
+ * plugins leave implement installed, `failed` when the guard refused or a warning says what went wrong.
+ * Never throws.
+ */
+export async function removeHandoffSentinel(opts) {
+    const warn = quietly(opts.warn);
+    if (!path.isAbsolute(opts.scriptsDir)) {
+        warn(`charter render: scriptsDir is not an absolute path ("${opts.scriptsDir}") — the implement sentinel was not removed`);
+        return 'failed';
+    }
+    if (!charterInventory(opts.removedPlugins).commands.has(HANDOFF_COMMAND))
+        return 'unchanged';
+    return removeSentinel(path.join(opts.scriptsDir, HANDOFF_SENTINEL_RELPATH), opts.mayChange, warn);
+}
+//# sourceMappingURL=charter-render.js.map

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

@@ -25,6 +25,7 @@ import { skillsDir, rulesDir } from '../../core/assets.js';
 import { ALWAYS_PRESENT_REFS, COMPLIANCE_FRAMEWORKS, normalizeFrameworks } from '../../core/compliance.js';
 import { parseComplianceFragment, composeComplianceSkill, composeComplianceRule } from '../../core/compliance-compose.js';
 import { validateSkillShadow, validateRuleShadow } from './installer.js';
+import { newLinkReport, refuseUnrealFolder, removeReportingLink, warnLinkReport, writeFileReplacingLink } from './linked-folder.js';
 // ── Path helpers ───────────────────────────────────────────────────────────
 /** Every registry framework id — the reference set every install carries. */
 const ALL_FRAMEWORK_IDS = COMPLIANCE_FRAMEWORKS.map(fw => fw.id);
@@ -92,10 +93,11 @@ async function loadComplianceFragments(canonicalSrc, frameworks, warn) {
  * `fragments` is loaded once by convergeComplianceArtifacts and shared with the rule
  * installer — the SKILL.md and the rule compose from the same parsed set.
  *
- * Build under a .tmp sibling, remove old target, rename.
+ * Build under a .tmp sibling, remove old target, rename. An old target that is a link is unlinked,
+ * never followed, so what it points to is left as it was; the link is recorded in `links`.
  * Unexpected I/O failures are reported via warn; never thrown.
  */
-async function installSkillDir(claudeDir, devflowDir, stampFrameworks, fragments, warn) {
+async function installSkillDir(claudeDir, devflowDir, stampFrameworks, fragments, warn, links) {
     const canonicalSrc = path.join(skillsDir(), 'compliance');
     const target = skillTarget(claudeDir);
     const tmpTarget = `${target}.tmp`;
@@ -148,9 +150,11 @@ async function installSkillDir(claudeDir, devflowDir, stampFrameworks, fragments
                 warn(`compliance: reference "${fw}.md" not installed — ${String(err)}`);
             }
         }
-        // Swap: remove old target, rename tmp into place (two calls, not atomic).
-        await fs.rm(target, { recursive: true, force: true });
+        // Swap: remove old target, rename tmp into place (two calls, not atomic). The link is recorded
+        // once the real folder stands in its place, so the report matches its wording.
+        const unlinked = await removeReportingLink(target);
         await fs.rename(tmpTarget, target);
+        links.replacedLinks.push(...unlinked);
     }
     catch (err) {
         // Clean up tmp on failure (best-effort) so no orphan is left behind.
@@ -174,9 +178,11 @@ async function installSkillDir(claudeDir, devflowDir, stampFrameworks, fragments
  * source (never the shadow — fragments are registry-owned) and shared with the skill
  * installer.
  *
- * I/O failures are reported via warn; never thrown.
+ * I/O failures are reported via warn; never thrown. The caller has proved that `rules/devflow` is a
+ * real folder or absent. A link at the rule file is replaced by the rename of the atomic write,
+ * never followed, and recorded in `links`.
  */
-async function installRuleFile(claudeDir, devflowDir, frameworks, fragments, warn) {
+async function installRuleFile(claudeDir, devflowDir, frameworks, fragments, warn, links) {
     const ruleShadowFile = path.join(devflowDir, 'rules', 'compliance.md');
     const canonicalRuleSrc = path.join(rulesDir(), 'compliance.md');
     const target = ruleTarget(claudeDir);
@@ -188,7 +194,7 @@ async function installRuleFile(claudeDir, devflowDir, frameworks, fragments, war
         for (const w of warnings)
             warn(`compliance: ${w}`);
         await fs.mkdir(path.dirname(target), { recursive: true });
-        await fs.writeFile(target, composed, 'utf-8');
+        await writeFileReplacingLink(target, composed, links);
     }
     catch (err) {
         warn(`compliance: rule install failed — ${String(err)}`);
@@ -219,7 +225,7 @@ export async function convergeComplianceArtifacts(opts) {
     // locations. Warn and bail rather than running fs.rm with a potentially wrong path.
     if (!path.isAbsolute(claudeDir)) {
         warn(`compliance: claudeDir is not an absolute path ("${claudeDir}") — skipping convergence`);
-        return { removedPreexisting: false, converged: false };
+        return { removedPreexisting: false, converged: false, replacedLinks: [], refusedFolders: [] };
     }
     // Trust boundary. `frameworks` reaches here straight from the manifest on every
     // caller's bare --enable path, and normalizeComplianceFeature only type-checks it.
@@ -244,10 +250,24 @@ export async function convergeComplianceArtifacts(opts) {
     // The skill and the rule are independent operations. An error in
     // installSkillDir is caught internally and reported via trackingWarn, so
     // execution always continues to the rule step.
-    await installSkillDir(claudeDir, devflowDir, stampFrameworks, fragments, trackingWarn);
+    const links = newLinkReport();
+    await installSkillDir(claudeDir, devflowDir, stampFrameworks, fragments, trackingWarn, links);
+    // The rule folder is proven before the rule is written or removed: a link there sends both into
+    // another place. The skill folder is swapped whole above, and a swap never follows a link.
+    const finish = (removedPreexisting) => {
+        warnLinkReport(links, warn);
+        return {
+            removedPreexisting,
+            converged: converged && links.refusedFolders.length === 0,
+            replacedLinks: links.replacedLinks,
+            refusedFolders: links.refusedFolders,
+        };
+    };
+    if (await refuseUnrealFolder(links, path.dirname(ruleTarget(claudeDir))))
+        return finish(false);
     if (enabled && rulesEnabled) {
-        await installRuleFile(claudeDir, devflowDir, safeFrameworks, fragments, trackingWarn);
-        return { removedPreexisting: false, converged };
+        await installRuleFile(claudeDir, devflowDir, safeFrameworks, fragments, trackingWarn, links);
+        return finish(false);
     }
     // Compliance off, or rules off: no rule. Probe first so a disable convergence
     // can report that it removed one; absence is already the desired end state.
@@ -260,7 +280,7 @@ export async function convergeComplianceArtifacts(opts) {
             trackingWarn(`compliance: failed to remove rule — ${String(err)}`);
         }
     }
-    return { removedPreexisting: !enabled && ruleExisted, converged };
+    return finish(!enabled && ruleExisted);
 }
 // ── Manifest-slice wrapper ─────────────────────────────────────────────────
 /**