@opengsd/gsd-core 1.9.0 → 1.10.0

package/gsd-core/bin/lib/active-workstream-store.cjs

@@ -199,6 +199,30 @@ function getActiveWorkstream(cwd, opts = {}) {
     }
     return name;
 }
+/**
+ * Read-only sibling of getActiveWorkstream (#2850): identical resolution —
+ * adapter -> stored name -> validate format -> workstream dir exists — but
+ * NEVER calls adapter.clear(). getActiveWorkstream's self-heal (deleting a
+ * stale/invalid pointer) is correct for a command that is actively acting on
+ * the active workstream; it is wrong for a read-only consumer invoked on
+ * every render (e.g. the statusline hook), which must never mutate
+ * persistent, possibly cross-session state as a side effect of drawing a
+ * screen. A stale or invalid pointer simply resolves to null here — the
+ * caller decides what "unresolvable" means for its own render, and the
+ * pointer file is left exactly as it was for whatever created it to fix.
+ */
+function peekActiveWorkstream(cwd, opts = {}) {
+    const adapter = pickActiveWorkstreamAdapter(cwd, opts);
+    if (!adapter)
+        return null;
+    const name = adapter.read();
+    if (!name || !validateWorkstreamName(name))
+        return null;
+    const wsDir = node_path_1.default.join(planningRoot(cwd), 'workstreams', name);
+    if (!node_fs_1.default.existsSync(wsDir))
+        return null;
+    return name;
+}
 function setActiveWorkstream(cwd, name, opts = {}) {
     const adapter = pickActiveWorkstreamAdapter(cwd, opts);
     if (!adapter)
@@ -288,6 +312,7 @@ module.exports = {
     createMemoryPointerAdapter,
     pickActiveWorkstreamAdapter,
     getActiveWorkstream,
+    peekActiveWorkstream,
     setActiveWorkstream,
     clearActiveWorkstream,
     parseCliWorkstream,

package/gsd-core/bin/lib/agent-install-check.cjs

@@ -3,8 +3,8 @@
  * Agent Install Check — moved from core.cts (ADR-857 T0 #1268 phase rehome-core-squatters).
  *
  * Owns:
- *   - getAgentsDir(runtime?): string
- *   - checkAgentsInstalled(runtime?): AgentsInstalledResult
+ *   - getAgentsDir(runtime?, projectRoot?): string
+ *   - checkAgentsInstalled(runtime?, projectRoot?): AgentsInstalledResult
  *
  * The core.cjs re-export spine was retired in epic #1267; callers import
  * these symbols from agent-install-check.cjs directly.
@@ -18,6 +18,7 @@ const node_path_1 = __importDefault(require("node:path"));
 const modelProfiles = require("./model-profiles.cjs");
 const { MODEL_PROFILES } = modelProfiles;
 const runtime_homes_cjs_1 = require("./runtime-homes.cjs");
+const runtime_name_policy_cjs_1 = require("./runtime-name-policy.cjs");
 /**
  * Resolve the agents directory for the given runtime.
  *
@@ -26,11 +27,17 @@ const runtime_homes_cjs_1 = require("./runtime-homes.cjs");
  *   2. For claude runtime: __dirname-relative path (agents/ sibling of gsd-core/)
  *      This is correct for both repo runs and real installs (the runtime config dir's
  *      agents/ folder) because gsd-tools.cjs lives inside gsd-core/bin/ in both cases.
- *   3. For non-claude runtimes: getGlobalConfigDir(runtime)/agents
+ *   3. For non-claude runtimes with a manifest-backed project-local install:
+ *      <projectRoot>/<localConfigDir>/agents (or <projectRoot>/agents when
+ *      the runtime's local install targets the project root). Requiring the
+ *      GSD manifest prevents runtime-native project agents from shadowing a
+ *      working global GSD install. Symlinked local agent directories are ignored.
+ *   4. For non-claude runtimes: getGlobalConfigDir(runtime)/agents
  *
  * @param runtime - the active runtime name; defaults to GSD_RUNTIME env, then 'claude'
+ * @param projectRoot - canonical project root for local-install discovery
  */
-function getAgentsDir(runtime) {
+function getAgentsDir(runtime, projectRoot) {
     if (process.env['GSD_AGENTS_DIR']) {
         return process.env['GSD_AGENTS_DIR'];
     }
@@ -38,16 +45,41 @@ function getAgentsDir(runtime) {
     if (resolved === 'claude') {
         return node_path_1.default.join(__dirname, '..', '..', '..', 'agents');
     }
+    if (projectRoot) {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const { runtimes } = require('./capability-registry.cjs');
+        const runtimeConfig = runtimes[resolved]?.runtime;
+        const localConfigDirName = (0, runtime_name_policy_cjs_1.getDirName)(resolved);
+        const localConfigDir = localConfigDirName === runtime_name_policy_cjs_1.NO_LOCAL_CONFIG_DIR_SENTINEL
+            ? undefined
+            : runtimeConfig?.hostBehaviors?.localTargetIsProjectRoot
+                ? projectRoot
+                : node_path_1.default.join(projectRoot, localConfigDirName);
+        if (!localConfigDir) {
+            return node_path_1.default.join((0, runtime_homes_cjs_1.getGlobalConfigDir)(resolved), 'agents');
+        }
+        const localAgentsDir = node_path_1.default.join(localConfigDir, 'agents');
+        const manifestPath = node_path_1.default.join(localConfigDir, 'gsd-file-manifest.json');
+        try {
+            if (node_fs_1.default.lstatSync(localAgentsDir).isDirectory() && node_fs_1.default.lstatSync(manifestPath).isFile()) {
+                return localAgentsDir;
+            }
+        }
+        catch {
+            // Local discovery is best-effort; any probe failure preserves global fallback.
+        }
+    }
     return node_path_1.default.join((0, runtime_homes_cjs_1.getGlobalConfigDir)(resolved), 'agents');
 }
 /**
  * Check which GSD agents are installed on disk.
  *
  * @param runtime - the active runtime name; defaults to GSD_RUNTIME env, then 'claude'
+ * @param projectRoot - canonical project root for local-install discovery
  */
-function checkAgentsInstalled(runtime) {
+function checkAgentsInstalled(runtime, projectRoot) {
     const resolvedRuntime = runtime ?? (process.env['GSD_RUNTIME'] || 'claude');
-    const agentsDir = getAgentsDir(resolvedRuntime);
+    const agentsDir = getAgentsDir(resolvedRuntime, projectRoot);
     const expectedAgents = Object.keys(MODEL_PROFILES);
     const installed = [];
     const missing = [];

package/gsd-core/bin/lib/api-coverage.cjs

@@ -238,6 +238,30 @@ const SURFACE_DESCRIPTOR_WORDS = new Set([
  *  EXTERNAL-API surface signal. Only unambiguously-internal words: "external"
  *  is deliberately absent (an external API IS external). */
 const INTERNAL_DESCRIPTORS = new Set(['internal', 'in-house', 'local', 'first-party', 'private']);
+/** #2784: negation suppression. A clause that pairs an integration verb with an
+ *  API noun but the verb itself is directly negated (e.g. "does not integrate",
+ *  "integrates no external API") is suppressed. Two windows are checked: a
+ *  negation qualifier within 2 words directly before the verb, or "no"/"zero"/
+ *  "none" between the verb and a following noun.
+ *  KNOWN LIMIT (deliberate, not a bug to fix later): a negation further than 2
+ *  words before the verb, or a clause where the noun precedes the verb, is NOT
+ *  suppressed — e.g. "Ships without any API integration." still reports
+ *  detected:true, because "without" sits outside the verb's 2-word lookback
+ *  and the noun precedes the verb. This is intentional: detectApiIntegration
+ *  is fail-closed — an unsuppressed false positive costs a one-line
+ *  COVERAGE.md declaration, while widening the suppression window risks a
+ *  false negative that silently lets a real external-API phase past a
+ *  blocking gate.
+ *  Hoisted to module scope (#3127 regression fix): this was previously
+ *  allocated fresh on every source line, which is wasted work on documents
+ *  with many lines. */
+const NEGATION_QUALIFIERS = new Set([
+    'no', 'not', 'without', 'zero', 'neither', 'nor', 'none', "don't", "doesn't", "didn't", "won't", "can't", "cannot",
+]);
+/** Negation tokens checked BETWEEN a verb and a later noun (narrower than
+ *  NEGATION_QUALIFIERS — "not" and "without" are checked only immediately
+ *  before the verb, via NEGATION_QUALIFIERS above). */
+const NEGATION_NOUN_TOKENS = new Set(['no', 'zero', 'none']);
 /** A capitalized compound modifier ("Resolver-only", "Read-only", "E-commerce"
  *  — lowercase letter right after the hyphen) is an adjective phrase, not a
  *  service name. Real hyphenated services capitalize the second segment
@@ -421,11 +445,45 @@ function detectApiIntegration(text, terms) {
         // boundary is the whole relationship test. Nouns are NOT filtered on
         // "internal" qualification here — "integrate the internal API" is a
         // fail-closed positive; the declaration dismisses it if wrong.
+        //
+        // #2784: negation suppression. A clause that pairs an integration verb with
+        // an API noun but the verb itself is directly negated (e.g. "does not
+        // integrate", "integrates no external API") is suppressed. The check is
+        // scoped to the verb's immediate context (the word directly before the
+        // verb, or the word directly between verb and noun) — NOT a blanket
+        // clause-wide scan, because "without changing runtime dependencies" in a
+        // long clause does NOT negate the integration.
+        // KNOWN LIMIT (deliberate, not a bug to fix later): a negation further than
+        // 2 words before the verb, or a clause where the noun precedes the verb, is
+        // NOT suppressed — e.g. "Ships without any API integration." is NOT
+        // suppressed today (pinned by a test in tests/api-coverage.test.cjs).
+        // detectApiIntegration is fail-closed by design: an unsuppressed false
+        // positive costs a one-line COVERAGE.md declaration, while widening the
+        // window trades that for a silent false negative on a blocking gate.
         if (verbRe && nounRe) {
             for (const clause of clauses) {
                 const verbs = collectTermMatches(verbRe, clause.text);
                 if (verbs.length === 0)
                     continue;
+                // #2784: check if any verb is immediately preceded by a negation
+                // qualifier (within 2 words before the verb match).
+                //
+                // OFFSET NOTE: `v.start`/`n.start` (from collectTermMatches below and
+                // above) are already CLAUSE-LOCAL — collectTermMatches was called with
+                // `clause.text`, not the full line — and so is `clauseText`
+                // (`clause.text.toLowerCase()`). They must be used AS-IS to index into
+                // `clauseText`; do not re-base them against `clause.start` (that field
+                // is the clause's offset within the LINE, a different coordinate space,
+                // used only to map line-level spans like `extraNouns`/`masked` into a
+                // clause). Subtracting `clause.start` here double-offsets the slice
+                // bounds for every clause after the first on a line (#3127 follow-up).
+                const clauseText = clause.text.toLowerCase();
+                const hasNegatedVerb = verbs.some((v) => {
+                    const before = clauseText.slice(Math.max(0, v.start - 20), v.start);
+                    const beforeWords = before.split(/\s+/).filter(Boolean).slice(-2);
+                    return beforeWords.some((w) => NEGATION_QUALIFIERS.has(w.replace(/[^a-z']/g, '')));
+                });
+                // Also check if "no"/"zero"/"none" appears between the verb and the noun.
                 const nouns = collectTermMatches(nounRe, clause.text);
                 const nounTerms = new Set(nouns.map((t) => t.term));
                 for (const u of extraNouns) {
@@ -435,6 +493,68 @@ function detectApiIntegration(text, terms) {
                 }
                 if (nounTerms.size === 0)
                     continue;
+                // Check for negation between verb and noun.
+                //
+                // #3127 regression: the original form of this check was
+                // O(verbs × nouns), re-slicing and re-splitting the clause text for
+                // every (verb, noun) pair — effectively cubic in clause length (a
+                // clause of N repeated "integrate api" pairs did O(N^2) pair checks,
+                // each doing an O(N) slice/split). On a clause with 800 repeated
+                // pairs this took ~8.5s; fast-check's property test then generated
+                // documents large enough to hang the whole test file past node:test's
+                // 600s timeout. It ALSO subtracted `clause.start` from `v.start`/
+                // `n.start` before slicing `clauseText` — but `v.start`/`n.start` are
+                // already local to `clause.text` (collectTermMatches was called with
+                // clause.text, not the full line), and `clauseText` is exactly
+                // `clause.text.toLowerCase()`. So that subtraction double-offset the
+                // slice bounds for every clause after the first on a line, sliding
+                // (and for negative results, JS's negative-index slice() wraparound
+                // non-monotonically re-mapping) the window to characters unrelated to
+                // the verb/noun pair — an independent latent bug, fixed here as part
+                // of establishing a well-defined O(1) predicate (a piecewise/clamped
+                // window has no single "widest span" to reason about at all).
+                //
+                // EXACT-EQUIVALENCE, single pass: the predicate is "does any pair
+                // (v, n) with n.start > v.start have a negation token in the span
+                // (v.end, n.start)". Every such span is a SUBSET of the widest
+                // possible span for a given noun: [min(v.end) over verbs valid for
+                // that noun, n.start). And since that window only widens as a
+                // noun's start increases (more verbs become valid, and the noun
+                // bound itself grows), the single widest span across the WHOLE
+                // clause is anchored at the noun with the maximum start, using the
+                // minimum verb-end among verbs valid for THAT noun (not the global
+                // minimum verb-end, which could belong to a verb that starts after
+                // this noun and so is never a valid pairing with it — a mismatch
+                // that would either miss or falsely include a negation). If that one
+                // substring contains no negation token, no narrower pair-specific
+                // substring can either; if it does, the (minVerb, maxNoun) pair
+                // itself contains it. This drops the check to O(verbs + nouns).
+                let hasNegatedNoun = false;
+                if (nouns.length > 0) {
+                    let minVerbStart = Infinity;
+                    for (const v of verbs)
+                        if (v.start < minVerbStart)
+                            minVerbStart = v.start;
+                    let maxNounStart = -Infinity;
+                    for (const n of nouns)
+                        if (n.start > maxNounStart)
+                            maxNounStart = n.start;
+                    if (maxNounStart > minVerbStart) {
+                        let minQualifyingVerbEnd = Infinity;
+                        for (const v of verbs) {
+                            if (v.start < maxNounStart) {
+                                const vEnd = v.start + v.term.length;
+                                if (vEnd < minQualifyingVerbEnd)
+                                    minQualifyingVerbEnd = vEnd;
+                            }
+                        }
+                        const between = clauseText.slice(minQualifyingVerbEnd, maxNounStart);
+                        const betweenWords = between.split(/\s+/).filter(Boolean);
+                        hasNegatedNoun = betweenWords.some((w) => NEGATION_NOUN_TOKENS.has(w.replace(/[^a-z']/g, '')));
+                    }
+                }
+                if (hasNegatedVerb || hasNegatedNoun)
+                    continue;
                 for (const vTerm of new Set(verbs.map((t) => t.term))) {
                     for (const nTerm of nounTerms)
                         emitPair(vTerm, nTerm, rawLine);

package/gsd-core/bin/lib/audit.cjs

@@ -28,6 +28,9 @@ const { extractFrontmatter } = frontmatter;
 const phaseIdMod = require("./phase-id.cjs");
 const { PHASE_NUMBER_TOKEN_SOURCE } = phaseIdMod;
 const security_cjs_1 = require("./security.cjs");
+// The SCOPE BOUNDARY convention's filename (`agents/gsd-executor.md`), shared
+// verbatim with the #2287 phase-boundary reader in `uat.cts`.
+const DEFERRED_ITEMS_FILENAME = 'deferred-items.md';
 // Terminal UAT states: `complete` (legacy) and `resolved` (post-gap-closure
 // per workflows/execute-phase.md). Hoisted outside scanUatGaps so the Set is
 // not recreated on each loop iteration.
@@ -534,6 +537,72 @@ function scanContextQuestions(planDir) {
     }
     return results;
 }
+// ─── scanDeferredItems ────────────────────────────────────────────────────────
+/**
+ * Scan phase directories for UNRESOLVED entries in `deferred-items.md` (#2646).
+ *
+ * The SCOPE BOUNDARY convention (`agents/gsd-executor.md`) has a phase agent
+ * log an out-of-scope discovery here rather than fix it. #2287 made that file
+ * readable at the PHASE boundary (`/gsd-progress` check 7, `audit-uat`); this
+ * scanner closes the remaining reader gap one boundary up, so an entry still
+ * unresolved at MILESTONE close surfaces in the pre-close audit alongside the
+ * other eight categories and the existing `[R]/[A]/[C]` prompt applies to it.
+ * Without this, phase directories archive to `milestones/vX.Y-phases/` (#1871)
+ * and the entry leaves the live tree having never been triaged.
+ *
+ * The resolved/unresolved predicate is NOT reimplemented here: `uat.cjs`
+ * already exports `parseDeferredItems`, which owns the parsing rule (entries
+ * under a `## Deferred Items` level-2 heading, else the whole file fail-safe;
+ * RESOLVED only on an explicit case-insensitive `status: resolved` field).
+ * Duplicating that inequality is how two readers of the same file drift into
+ * disagreeing about what "open" means. The require is deliberately LAZY,
+ * inside the scan, to preserve `audit-command-router.cts`'s property that a
+ * route never loads the module it does not need.
+ */
+function scanDeferredItems(planDir) {
+    const phasesDir = node_path_1.default.join(planDir, 'phases');
+    if (!node_fs_1.default.existsSync(phasesDir))
+        return [];
+    let dirs;
+    try {
+        dirs = node_fs_1.default.readdirSync(phasesDir, { withFileTypes: true })
+            .filter(e => e.isDirectory())
+            .map(e => e.name)
+            .sort();
+    }
+    catch {
+        return [{ scan_error: true, phase: '', file: '', text: '' }];
+    }
+    // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-unsafe-assignment
+    const uat = require('./uat.cjs');
+    const results = [];
+    for (const dir of dirs) {
+        const phaseDir = node_path_1.default.join(phasesDir, dir);
+        const phaseMatch = dir.match(new RegExp(`^(${PHASE_NUMBER_TOKEN_SOURCE})`, 'i'));
+        const phaseNum = phaseMatch ? phaseMatch[1] : dir;
+        const filePath = node_path_1.default.join(phaseDir, DEFERRED_ITEMS_FILENAME);
+        if (!node_fs_1.default.existsSync(filePath))
+            continue;
+        let safeFilePath;
+        try {
+            safeFilePath = (0, security_cjs_1.requireSafePath)(filePath, planDir, 'deferred items file', { allowAbsolute: true });
+        }
+        catch {
+            continue;
+        }
+        const content = (0, shell_command_projection_cjs_1.platformReadSync)(safeFilePath);
+        if (content === null)
+            continue;
+        for (const item of uat.parseDeferredItems(content)) {
+            results.push({
+                phase: (0, security_cjs_1.sanitizeForDisplay)(phaseNum),
+                file: DEFERRED_ITEMS_FILENAME,
+                text: (0, security_cjs_1.sanitizeForDisplay)(item.name),
+            });
+        }
+    }
+    return results;
+}
 // ─── auditOpenArtifacts ───────────────────────────────────────────────────────
 /**
  * Main audit function. Scans all .planning/ artifact categories.
@@ -607,6 +676,14 @@ function auditOpenArtifacts(cwd) {
             return [{ scan_error: true, phase: '', file: '', question_count: 0, questions: [] }];
         }
     })();
+    const deferredItems = (() => {
+        try {
+            return scanDeferredItems(planDir);
+        }
+        catch {
+            return [{ scan_error: true, phase: '', file: '', text: '' }];
+        }
+    })();
     // Count real items (not scan_error sentinels)
     const countReal = (arr) => arr.filter(i => !i.scan_error && !i._remainder_count).length;
     const counts = {
@@ -618,9 +695,10 @@ function auditOpenArtifacts(cwd) {
         uat_gaps: countReal(uatGaps),
         verification_gaps: countReal(verificationGaps),
         context_questions: countReal(contextQuestions),
+        deferred_items: countReal(deferredItems),
         total: 0,
     };
-    counts.total = counts.debug_sessions + counts.quick_tasks + counts.threads + counts.todos + counts.seeds + counts.uat_gaps + counts.verification_gaps + counts.context_questions;
+    counts.total = counts.debug_sessions + counts.quick_tasks + counts.threads + counts.todos + counts.seeds + counts.uat_gaps + counts.verification_gaps + counts.context_questions + counts.deferred_items;
     return {
         scanned_at: new Date().toISOString(),
         has_open_items: counts.total > 0,
@@ -634,6 +712,7 @@ function auditOpenArtifacts(cwd) {
             uat_gaps: uatGaps,
             verification_gaps: verificationGaps,
             context_questions: contextQuestions,
+            deferred_items: deferredItems,
         },
     };
 }
@@ -738,6 +817,15 @@ function formatAuditReport(auditResult) {
             }
         }
     }
+    // Deferred items (deferred decisions — blue). Out-of-scope discoveries a
+    // phase agent recorded rather than fixed, still unresolved at close (#2646).
+    if (counts.deferred_items > 0) {
+        lines.push('');
+        lines.push(`🔵 Deferred Items (${counts.deferred_items} unresolved)`);
+        for (const item of items.deferred_items.filter(i => !i.scan_error)) {
+            lines.push(`   • Phase ${item.phase}: ${item.text}`);
+        }
+    }
     lines.push('');
     lines.push(hr);
     lines.push(`  ${counts.total} item${counts.total !== 1 ? 's' : ''} require decisions before close.`);

package/gsd-core/bin/lib/broken-windows.cjs

@@ -1,11 +1,11 @@
 "use strict";
 /**
- * Broken-windows ledger — enforced cross-phase defect register (issue #1950).
+ * Broken-windows ledger — optionally enforced cross-phase defect register (issue #1950).
  *
  * Manages `.planning/WINDOWS.md`: a cross-phase ledger of small defects (stubs,
  * TODOs, skipped tests, lint warnings, unrun verifies, unmet truths, deviations).
- * `/gsd-ship` blocks while any entry is `open`; an entry can be `waived` only
- * with a recorded reason or `fixed`.
+ * When `workflow.windows_enforce` is true, `/gsd-ship` blocks while any entry is
+ * `open`; an entry can be `waived` only with a recorded reason or `fixed`.
  *
  * LEAF MODULE — imports ONLY: node:fs, node:path. No other src/ imports.
  *
@@ -302,7 +302,12 @@ function parseFrontmatterStrict(raw) {
     }
     const yamlBody = raw.slice(headerEnd, closeIdx);
     const out = {};
-    for (const line of yamlBody.split(/\r?\n/)) {
+    for (const rawLine of yamlBody.split(/\r?\n/)) {
+        // #3116: the `\n---` scan leaves the final line's CR attached on a CRLF
+        // ledger, and `.` never matches CR, so the key: value regex below fails on
+        // it. Strip the trailing CR per line so the rest of `raw` (which
+        // parseJsonBlock also slices by byte offset) is unaffected.
+        const line = rawLine.replace(/\r$/, '');
         if (line.trim() === '')
             continue;
         const m = line.match(/^([a-zA-Z0-9_]+):\s*(.*)$/);
@@ -447,7 +452,7 @@ function renderLedger(ledger) {
     const header = [
         '# Broken Windows Ledger',
         '',
-        '> Cross-phase defect register. `/gsd-ship` blocks while `open_count > 0`.',
+        '> Cross-phase defect register. With `workflow.windows_enforce` enabled, `/gsd-ship` blocks while `open_count > 0`.',
         '> Waive with `gsd-tools windows waive <id> "<reason>"` (reason required).',
         '> Mark fixed with `gsd-tools windows fixed <id>`.',
         '',
@@ -559,7 +564,32 @@ function writeLedgerAtomic(cwd, ledger) {
     ensurePlanningDir(cwd);
     const p = ledgerPath(cwd);
     const tmp = `${p}.${process.pid}.tmp`;
-    node_fs_1.default.writeFileSync(tmp, renderLedger(ledger), 'utf8');
+    // #2893: preserve any prose below the JSON ledger block. renderLedger
+    // reconstructs frontmatter + header + table + JSON — it does not include
+    // trailing prose that users may have written below the closing fence.
+    // Without this, every append/waive/fixed silently destroys that prose.
+    let trailingProse = '';
+    try {
+        const existing = node_fs_1.default.readFileSync(p, 'utf8');
+        // #2893: search for the CLOSING fence starting AFTER the opening fence,
+        // mirroring parseJsonBlock — indexOf(JSON_FENCE_CLOSE) alone would match
+        // the opening fence ('````json' starts with '````').
+        const openIdx = existing.indexOf(JSON_FENCE_OPEN);
+        if (openIdx !== -1) {
+            const fenceEnd = existing.indexOf(JSON_FENCE_CLOSE, openIdx + JSON_FENCE_OPEN.length);
+            if (fenceEnd !== -1) {
+                const afterFence = existing.slice(fenceEnd + JSON_FENCE_CLOSE.length);
+                // Drop leading newlines; keep the rest as prose.
+                trailingProse = afterFence.replace(/^\n+/, '');
+            }
+        }
+    }
+    catch {
+        // File doesn't exist yet (first write) — no prose to preserve.
+    }
+    const rendered = renderLedger(ledger);
+    const content = trailingProse ? `${rendered}${trailingProse}` : rendered;
+    node_fs_1.default.writeFileSync(tmp, content, 'utf8');
     try {
         renameWithRetry(tmp, p);
     }