@latysh-development/monolith 0.0.0-stage → 0.1.0-alpha.0

package/dist/brief/render.js

@@ -0,0 +1,407 @@
+/**
+ * `render(model, maxChars)` — the Rendering stage of the brief pipeline.
+ *
+ * Pure and synchronous: same BriefModel + same maxChars always produces the
+ * byte-identical string (section 11 — determinism). No Date.now(), no
+ * random IDs, no locale-dependent sorting; every list collect() hands in is
+ * already in a fixed, stably-sorted order.
+ *
+ * Budget accounting (section 10) in two phases to avoid a circular
+ * dependency between "does P0 fit" and "what does the Completeness line
+ * say" (rule: no diagnostic/marker line may be added without being counted
+ * in the budget that decided what else fits):
+ *
+ *   Phase 1 — build all P0 content (identity, State Keeper status,
+ *   collect-time diagnostics, every active mission identifier, every
+ *   mandatory protocol pointer) with NO budget limit — P0 is never
+ *   truncated or hidden (rule 5/7). If P0 alone (plus the reserved,
+ *   fixed-size Completeness line) exceeds maxChars, that is reported via
+ *   BUDGET_EXCEEDED_BY_REQUIRED (which also states explicitly that P1–P3
+ *   are skipped entirely as a result — review finding F-5) and nothing
+ *   else is attempted.
+ *
+ *   Phase 2 — whatever chars remain after P0 + the reserved Completeness
+ *   line are handed to P1 (Checkpoints, then Story — Checkpoints first so
+ *   a long Story can never silently starve "Next steps" out of the budget;
+ *   review finding F-5), then P2, then P3, in that fixed order. Each
+ *   section either fits whole, or (list sections) includes as many whole
+ *   items as fit plus an explicit "N more omitted" marker, or (the Story
+ *   excerpt) is field-truncated with an explicit `[truncated N chars]`
+ *   marker, or — if not even that fits — falls back to a short, fixed-size
+ *   local omission marker so a section can never disappear from the output
+ *   without some local trace of its omission (review finding F-5; the only
+ *   residual case where a section can still vanish with zero local marker
+ *   is when `remaining` is too small even for that minimal marker, which
+ *   is itself already covered by the global Completeness: INCOMPLETE
+ *   signal). Every one of these outcomes is itself measured and subtracted
+ *   from the remaining budget before the next section is attempted —
+ *   nothing is added "for free" after the fact.
+ *
+ * Completeness contract (N-3): `Completeness: COMPLETE` means no
+ * *substantive data* was lost, not that every section heading is present.
+ * An optional section that has nothing to show (an empty list, rendered
+ * only as "(none)") and the static P3 pointer block may be dropped under a
+ * tight budget without flipping the result to INCOMPLETE — dropping them
+ * loses no information. A section that holds data is never dropped
+ * silently: it is shown whole, shown partially with an explicit marker, or
+ * replaced by a pointer-bearing omission marker, and either of the latter
+ * two forces INCOMPLETE. P0 is never dropped. All project-controlled
+ * strings, provenance pointers included, pass through
+ * `sanitizeSingleLine` (N-1).
+ */
+import { ACTIVE_MD_REL } from './constants.js';
+import { sanitizeSingleLine, sanitizeMultiLine } from './sanitize.js';
+// Shorthand for the existing single-line sanitizer — applied to every string
+// that originates in project files or configuration (N-1), including
+// provenance pointers, which embed config-controlled paths.
+const san = sanitizeSingleLine;
+export const DEFAULT_MAX_CHARS = 6000;
+const RECENT_FINISHED_MISSIONS_RENDER_LIMIT = 5;
+const COMPLETE_LINE = 'Completeness: COMPLETE';
+const INCOMPLETE_LINE = 'Completeness: INCOMPLETE';
+const RESERVED_COMPLETENESS_LEN = Math.max(COMPLETE_LINE.length, INCOMPLETE_LINE.length) + 1;
+const BUDGET_EXCEEDED_LINE = 'BUDGET_EXCEEDED_BY_REQUIRED: required (P0) content exceeds --max-chars; shown in full regardless ' +
+    '(--max-chars is not honored in this case). Optional sections (Current Story, Active Mission ' +
+    'Checkpoints, Accepted ADR Index, Recently Finished Missions) are skipped entirely as a result.';
+function formatDiagnosticsBlock(diagnostics, extraLine) {
+    const lines = diagnostics.map((d) => `  [${d.severity.toUpperCase()}] ${d.code}: ${sanitizeSingleLine(d.message)}`);
+    if (extraLine)
+        lines.push(`  [ERROR] ${extraLine}`);
+    const body = lines.length > 0 ? lines.join('\n') + '\n' : '  (none)\n';
+    return `\n## Diagnostics\n${body}`;
+}
+function formatStateKeeperBlock(sk) {
+    const versionNote = sk.schemaVersionOnDisk !== undefined ? ` schemaVersionOnDisk=${sk.schemaVersionOnDisk}` : '';
+    return `\n## State Keeper\n  status: ${sk.status}${versionNote}\n  (source: ${san(sk.provenance.source)})\n`;
+}
+function formatMission(m) {
+    return `  - ${san(m.id)} [${m.status}] ${san(m.title)} (${san(m.system)}) — started ${san(m.startedAt)}\n`;
+}
+function formatActiveMissionsBlock(missions, provenance) {
+    const body = missions.length > 0 ? missions.map(formatMission).join('') : '  (none)\n';
+    return `\n## Active Missions (${missions.length})\n${body}  (source: ${san(provenance.source)})\n`;
+}
+function formatDocRef(d) {
+    return `  - ${san(d.id)}: ${san(d.title)} (${san(d.path)})\n`;
+}
+function formatProtocolsBlock(items, provenance) {
+    const body = items.length > 0 ? items.map(formatDocRef).join('') : '  (none)\n';
+    return `\n## Mandatory Protocols (${items.length})\n${body}  (source: ${san(provenance.source)})\n`;
+}
+function formatIdentityTitle(model) {
+    return `\n# MONOLITH Brief — ${san(model.identity.name)}\n(monolithRoot: ${san(model.identity.monolithRoot)}, source: ${san(model.identity.provenance.source)})\n`;
+}
+const ACTIVE_STORY_LABEL = {
+    'none-recorded': 'none recorded (this does not mean the project is complete)',
+    recorded: 'recorded in active.md',
+    unknown: 'unknown',
+};
+/**
+ * SELF-AWARENESS-001: the Freshness block. Part of P0 — it is never truncated,
+ * and it never influences `Completeness`. Every string that originates in
+ * project files or git history passes through the sanitizer.
+ */
+function formatFreshnessBlock(f) {
+    const lines = ['', '## Freshness', `  Status: ${f.status}`];
+    if (f.lastStateUpdate) {
+        lines.push(`  Last state update: ${san(f.lastStateUpdate.sha.slice(0, 7))} (${san(f.lastStateUpdate.date.slice(0, 10))}, git)`);
+    }
+    lines.push(`  Active Story: ${ACTIVE_STORY_LABEL[f.activeStory]}`);
+    if (f.reasons.length > 0) {
+        lines.push('  Evidence:');
+        for (const r of f.reasons)
+            lines.push(`    - [${r.code}] ${san(r.message)}`);
+    }
+    if (f.warnings.length > 0) {
+        lines.push('  Warnings:');
+        for (const w of f.warnings)
+            lines.push(`    - ${san(w)}`);
+    }
+    lines.push(`  Recommendation: ${san(f.recommendation)}`);
+    return lines.join('\n') + '\n';
+}
+function buildCoreP0(model, includeBudgetExceeded) {
+    return (formatIdentityTitle(model) +
+        (model.freshness ? formatFreshnessBlock(model.freshness) : '') +
+        formatStateKeeperBlock(model.stateKeeper) +
+        formatDiagnosticsBlock(model.diagnostics, includeBudgetExceeded ? BUDGET_EXCEEDED_LINE : null) +
+        formatActiveMissionsBlock(model.missions.active, model.missions.provenance) +
+        formatProtocolsBlock(model.mandatoryProtocols.items, model.mandatoryProtocols.provenance));
+}
+/**
+ * Truncates `text` to fit within `maxBodyLen`, appending an explicit,
+ * pointer-bearing `[truncated N chars — see <pointer>]` marker where N is
+ * the actual number of characters removed.
+ *
+ * Review finding F-4: N depends on the marker's own length (removing more
+ * chars to make room for a longer "N" can itself change how many digits N
+ * has), so a single-pass `text.length - maxBodyLen` estimate under-reports
+ * N by exactly the marker's length. This resolves it as a small fixed-point
+ * computation: rebuild the marker from the current estimate, re-derive how
+ * much is actually kept, and repeat until N stops changing (converges in at
+ * most a couple of iterations — the only way it can change at all is a
+ * digit-count crossing in N, which an 8-iteration cap comfortably covers).
+ *
+ * The cut point is also nudged left by one character if it would otherwise
+ * split a UTF-16 surrogate pair, and N is recomputed once more for that
+ * final cut point so it stays exact even in that case.
+ */
+function truncateToBudget(text, maxBodyLen, pointer) {
+    if (text.length <= maxBodyLen)
+        return text;
+    const buildMarker = (removed) => `\n[truncated ${removed} chars — see ${pointer}]`;
+    let removed = text.length - maxBodyLen;
+    let keepLen = 0;
+    for (let i = 0; i < 8; i++) {
+        const marker = buildMarker(removed);
+        keepLen = Math.max(0, maxBodyLen - marker.length);
+        const nextRemoved = text.length - keepLen;
+        if (nextRemoved === removed)
+            break;
+        removed = nextRemoved;
+    }
+    if (keepLen > 0 && keepLen < text.length) {
+        const code = text.charCodeAt(keepLen - 1);
+        if (code >= 0xd800 && code <= 0xdbff)
+            keepLen -= 1; // don't split a surrogate pair
+    }
+    const finalRemoved = text.length - keepLen;
+    return text.slice(0, keepLen) + buildMarker(finalRemoved);
+}
+/**
+ * Absolute last-resort fallback (review finding F-5): a label- and
+ * pointer-free marker so short it fits almost any nonzero `remaining`
+ * budget. Each section tries its own more informative (labeled,
+ * pointer-bearing) fallback first; this is only reached when even that
+ * doesn't fit. The only way a section can still end up with zero local
+ * trace is `remaining` being smaller than this marker itself — by that
+ * point the budget is so exhausted that the global `Completeness:
+ * INCOMPLETE` line is the only thing that could fit anyway.
+ */
+const BARE_OMIT_MARKER = '\n[omitted — budget]\n';
+function buildStorySection(model, remaining) {
+    const header = '\n## Current Story\n';
+    const pointer = san(model.story.provenance?.source ?? ACTIVE_MD_REL);
+    const minimalFallback = `\n[Story omitted — budget; see ${pointer}]\n`;
+    let body;
+    if (!model.story.fileExists) {
+        body = '  (active.md not found)\n';
+    }
+    else if (!model.story.hasCurrentStorySection) {
+        body = '  (no "Current Story" section found)\n';
+    }
+    else if (model.story.excerpt === '') {
+        body = '  (section present but empty)\n';
+    }
+    else {
+        body = `${sanitizeMultiLine(model.story.excerpt ?? '')}\n`;
+    }
+    const provenanceLine = model.story.provenance ? `  (source: ${san(model.story.provenance.source)})\n` : '';
+    const full = header + body + provenanceLine;
+    if (full.length <= remaining) {
+        return { text: full, consumed: full.length, lossFlag: false };
+    }
+    if (model.story.excerpt) {
+        const sanitizedExcerpt = sanitizeMultiLine(model.story.excerpt);
+        const fixedOverhead = header.length + 1 + provenanceLine.length;
+        const budgetForBody = remaining - fixedOverhead;
+        if (budgetForBody > 0) {
+            const truncatedBody = truncateToBudget(sanitizedExcerpt, budgetForBody, pointer);
+            const truncatedFull = header + truncatedBody + '\n' + provenanceLine;
+            if (truncatedFull.length <= remaining) {
+                return { text: truncatedFull, consumed: truncatedFull.length, lossFlag: true };
+            }
+        }
+    }
+    const omitLine = `\n## Current Story\n  [omitted — budget] see ${pointer}\n`;
+    if (omitLine.length <= remaining) {
+        return { text: omitLine, consumed: omitLine.length, lossFlag: true };
+    }
+    if (minimalFallback.length <= remaining) {
+        return { text: minimalFallback, consumed: minimalFallback.length, lossFlag: true };
+    }
+    if (BARE_OMIT_MARKER.length <= remaining) {
+        return { text: BARE_OMIT_MARKER, consumed: BARE_OMIT_MARKER.length, lossFlag: true };
+    }
+    return { text: '', consumed: 0, lossFlag: true };
+}
+function formatCheckpointItem(cp) {
+    const lines = [`  - Mission ${san(cp.missionId)}:`];
+    if (!cp.latest) {
+        lines.push('    Next steps: UNKNOWN (no checkpoints)');
+    }
+    else {
+        lines.push(`    checkpoint: ${san(cp.latest.id)} (createdAt ${san(cp.latest.createdAt)})`);
+        lines.push(`    summary: ${san(cp.latest.summary)}`);
+        if (cp.latest.remainingSteps.length === 0) {
+            lines.push('    Next steps: none recorded');
+        }
+        else {
+            lines.push('    Next steps:');
+            for (const step of cp.latest.remainingSteps)
+                lines.push(`      - ${san(step)}`);
+        }
+    }
+    lines.push(`    (source: ${san(cp.provenance.source)})`);
+    return lines.join('\n') + '\n';
+}
+function buildCheckpointsSection(model, remaining) {
+    if (model.checkpoints.length === 0)
+        return { text: '', consumed: 0, lossFlag: false };
+    const header = '\n## Active Mission Checkpoints\n';
+    const items = model.checkpoints.map(formatCheckpointItem);
+    const minimalFallback = '\n[Active Mission Checkpoints omitted — budget; run `monolith mission checkpoints <id>`]\n';
+    const makeMarker = (n) => `  ...and ${n} more mission(s)' checkpoint details omitted (budget) — run \`monolith mission checkpoints <id>\`.\n`;
+    let used = header.length;
+    const included = [];
+    for (const item of items) {
+        if (used + item.length <= remaining) {
+            included.push(item);
+            used += item.length;
+        }
+        else {
+            break;
+        }
+    }
+    let omitted = items.length - included.length;
+    let marker = '';
+    if (omitted > 0) {
+        marker = makeMarker(omitted);
+        while (included.length > 0 && used + marker.length > remaining) {
+            const removedItem = included.pop();
+            used -= removedItem.length;
+            omitted = items.length - included.length;
+            marker = makeMarker(omitted);
+        }
+    }
+    const fits = omitted === 0 || used + marker.length <= remaining;
+    if (fits) {
+        if (included.length === 0 && !marker)
+            return { text: '', consumed: 0, lossFlag: false };
+        const text = header + included.join('') + marker;
+        return { text, consumed: text.length, lossFlag: omitted > 0 };
+    }
+    if (minimalFallback.length <= remaining) {
+        return { text: minimalFallback, consumed: minimalFallback.length, lossFlag: true };
+    }
+    if (BARE_OMIT_MARKER.length <= remaining) {
+        return { text: BARE_OMIT_MARKER, consumed: BARE_OMIT_MARKER.length, lossFlag: true };
+    }
+    return { text: '', consumed: 0, lossFlag: true };
+}
+/**
+ * Generic fitter for a deterministically-ordered list of small, atomic text
+ * items: include as many whole items as fit, in order, then an explicit
+ * "N more omitted" marker for the rest, then a provenance footer (section 9
+ * — every content section names its source). Items are never cut mid-item;
+ * the footer is reserved up front so it is never silently dropped while
+ * items still fit. If not even the whole-items-plus-marker form fits, falls
+ * back to a short, fixed-size `minimalFallback` marker rather than
+ * disappearing without any local trace (review finding F-5).
+ */
+function fitItemList(header, items, footer, remaining, omittedMarkerFn, minimalFallback) {
+    const noneBody = '  (none)\n';
+    if (items.length === 0) {
+        const full = header + noneBody + footer;
+        if (full.length <= remaining)
+            return { text: full, consumed: full.length, lossFlag: false };
+        const withoutFooter = header + noneBody;
+        if (withoutFooter.length <= remaining)
+            return { text: withoutFooter, consumed: withoutFooter.length, lossFlag: false };
+        return { text: '', consumed: 0, lossFlag: false };
+    }
+    const itemBudget = Math.max(0, remaining - footer.length);
+    let used = header.length;
+    const included = [];
+    for (const item of items) {
+        if (used + item.length <= itemBudget) {
+            included.push(item);
+            used += item.length;
+        }
+        else {
+            break;
+        }
+    }
+    let omitted = items.length - included.length;
+    let marker = '';
+    if (omitted > 0) {
+        marker = omittedMarkerFn(omitted);
+        while (included.length > 0 && used + marker.length > itemBudget) {
+            const removedItem = included.pop();
+            used -= removedItem.length;
+            omitted = items.length - included.length;
+            marker = omittedMarkerFn(omitted);
+        }
+    }
+    const fits = omitted === 0 || used + marker.length <= itemBudget;
+    if (fits) {
+        const withFooter = header + included.join('') + marker + footer;
+        if (withFooter.length <= remaining) {
+            return { text: withFooter, consumed: withFooter.length, lossFlag: omitted > 0 };
+        }
+        const withoutFooter = header + included.join('') + marker;
+        if (withoutFooter.length <= remaining) {
+            return { text: withoutFooter, consumed: withoutFooter.length, lossFlag: true };
+        }
+    }
+    if (minimalFallback.length <= remaining) {
+        return { text: minimalFallback, consumed: minimalFallback.length, lossFlag: true };
+    }
+    if (BARE_OMIT_MARKER.length <= remaining) {
+        return { text: BARE_OMIT_MARKER, consumed: BARE_OMIT_MARKER.length, lossFlag: true };
+    }
+    return { text: '', consumed: 0, lossFlag: true };
+}
+const P3_TEXT = '\n## More\n' +
+    '  Full checkpoint history: `monolith mission checkpoints <id>`\n' +
+    '  Mission detail: `monolith mission show <id>`\n' +
+    '  Full ADR/protocol listings: see their directories above.\n';
+export function render(model, maxChars = DEFAULT_MAX_CHARS) {
+    const coreText0 = buildCoreP0(model, false);
+    // The Freshness headline sits right under Completeness and is counted in the budget like it.
+    const freshnessLine = model.freshness ? `Freshness: ${model.freshness.status}\n` : '';
+    const requiredMinimum = coreText0.length + RESERVED_COMPLETENESS_LEN + freshnessLine.length;
+    const budgetExceededByRequired = requiredMinimum > maxChars;
+    const coreText = budgetExceededByRequired ? buildCoreP0(model, true) : coreText0;
+    let remaining = budgetExceededByRequired ? 0 : Math.max(0, maxChars - coreText.length - RESERVED_COMPLETENESS_LEN - freshnessLine.length);
+    let budgetLoss = false;
+    let p1 = '';
+    let p2 = '';
+    let p3 = '';
+    if (!budgetExceededByRequired) {
+        // Checkpoints (carries "Next steps") is given first claim on the P1
+        // budget, ahead of Story — a long Story excerpt must not be able to
+        // silently starve Next-steps information out of the brief (review
+        // finding F-5).
+        const ckpt = buildCheckpointsSection(model, remaining);
+        p1 += ckpt.text;
+        remaining -= ckpt.consumed;
+        budgetLoss = budgetLoss || ckpt.lossFlag;
+        const story = buildStorySection(model, remaining);
+        p1 += story.text;
+        remaining -= story.consumed;
+        budgetLoss = budgetLoss || story.lossFlag;
+        const adrSource = san(model.adrs.provenance.source);
+        const missionsSource = san(model.missions.provenance.source);
+        const adrItems = model.adrs.items.map((a) => formatDocRef(a));
+        const adrSection = fitItemList(`\n## Accepted ADR Index (${model.adrs.items.length})\n`, adrItems, `  (source: ${adrSource})\n`, remaining, (n) => `  ...and ${n} more ADR(s) omitted (budget) — see ${adrSource}.\n`, `\n[Accepted ADR Index omitted — budget; see ${adrSource}]\n`);
+        p2 += adrSection.text;
+        remaining -= adrSection.consumed;
+        budgetLoss = budgetLoss || adrSection.lossFlag;
+        const recentFinished = model.missions.recentFinished.slice(0, RECENT_FINISHED_MISSIONS_RENDER_LIMIT);
+        const finishedItems = recentFinished.map(formatMission);
+        const finishedSection = fitItemList(`\n## Recently Finished Missions (${recentFinished.length})\n`, finishedItems, `  (source: ${missionsSource})\n`, remaining, (n) => `  ...and ${n} more omitted (budget) — see ${missionsSource}.\n`, `\n[Recently Finished Missions omitted — budget; see ${missionsSource}]\n`);
+        p2 += finishedSection.text;
+        remaining -= finishedSection.consumed;
+        budgetLoss = budgetLoss || finishedSection.lossFlag;
+        if (P3_TEXT.length <= remaining) {
+            p3 = P3_TEXT;
+            remaining -= p3.length;
+        }
+    }
+    const collectTimeError = model.diagnostics.some((d) => d.severity === 'error');
+    const completeness = !collectTimeError && !budgetExceededByRequired && !budgetLoss ? 'COMPLETE' : 'INCOMPLETE';
+    const completenessLine = completeness === 'COMPLETE' ? COMPLETE_LINE : INCOMPLETE_LINE;
+    const text = `${completenessLine}\n${freshnessLine}${coreText}${p1}${p2}${p3}`;
+    return { text: `${text.replace(/\n+$/, '')}\n`, completeness };
+}

package/dist/brief/sanitize.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Review finding F-7 (data/instruction boundary): `monolith brief` output
+ * is AI-facing. Project data — a Mission title, a checkpoint summary, a
+ * Story excerpt, a document title from frontmatter — is free text that a
+ * contributor (or an attacker with ordinary write access to the project)
+ * fully controls. Without escaping, a crafted value containing real
+ * newlines could fake a brief-native line such as `Completeness: COMPLETE`
+ * or a `## Section` heading, making project data visually indistinguishable
+ * from the brief's own structure to a reader (human or AI) skimming the
+ * raw text.
+ *
+ * This is deterministic, non-LLM hygiene only — it does not attempt to
+ * detect or block prompt injection as a concept, and makes no claim that
+ * it does. It guarantees two narrower, checkable properties:
+ *   - a field rendered as a single line can never introduce a newline
+ *     (so it can never start what looks like a new brief line/section);
+ *   - control characters (escape codes, NUL, etc.) are never written to
+ *     stdout raw, in single-line or multi-line fields alike.
+ * The Story excerpt is the one legitimately multi-line field (it is a
+ * verbatim block from active.md, already bounded by its own header and
+ * `(source: ...)` footer) — its internal newlines are preserved, only
+ * other control characters are escaped.
+ */
+/**
+ * For fields rendered as a single logical line (mission title, checkpoint
+ * summary, a remaining-step entry, a doc title): collapses any real
+ * newline to a visible `\n` escape sequence and escapes other control
+ * characters, so the field can never break out of its line.
+ */
+export declare function sanitizeSingleLine(s: string): string;
+/**
+ * For fields allowed to span multiple lines (the Story excerpt): keeps
+ * real newlines (that is the field's legitimate internal structure) but
+ * still escapes other control characters so nothing unprintable reaches
+ * stdout raw.
+ */
+export declare function sanitizeMultiLine(s: string): string;
+//# sourceMappingURL=sanitize.d.ts.map

package/dist/brief/sanitize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sanitize.d.ts","sourceRoot":"","sources":["../../src/brief/sanitize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAWH;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAEnD"}

package/dist/brief/sanitize.js

@@ -0,0 +1,48 @@
+/**
+ * Review finding F-7 (data/instruction boundary): `monolith brief` output
+ * is AI-facing. Project data — a Mission title, a checkpoint summary, a
+ * Story excerpt, a document title from frontmatter — is free text that a
+ * contributor (or an attacker with ordinary write access to the project)
+ * fully controls. Without escaping, a crafted value containing real
+ * newlines could fake a brief-native line such as `Completeness: COMPLETE`
+ * or a `## Section` heading, making project data visually indistinguishable
+ * from the brief's own structure to a reader (human or AI) skimming the
+ * raw text.
+ *
+ * This is deterministic, non-LLM hygiene only — it does not attempt to
+ * detect or block prompt injection as a concept, and makes no claim that
+ * it does. It guarantees two narrower, checkable properties:
+ *   - a field rendered as a single line can never introduce a newline
+ *     (so it can never start what looks like a new brief line/section);
+ *   - control characters (escape codes, NUL, etc.) are never written to
+ *     stdout raw, in single-line or multi-line fields alike.
+ * The Story excerpt is the one legitimately multi-line field (it is a
+ * verbatim block from active.md, already bounded by its own header and
+ * `(source: ...)` footer) — its internal newlines are preserved, only
+ * other control characters are escaped.
+ */
+// C0 controls other than \t (0x09), \n (0x0A), \r (0x0D), plus DEL (0x7F) and
+// the C1 range (0x80-0x9F — includes 0x9B, a single-byte CSI that some
+// terminals honor as an escape-sequence introducer, and 0x85, NEL).
+const OTHER_CONTROL_CHARS_RE = /[\x00-\x08\x0B\x0C\x0E-\x1F\x7F-\x9F]/g;
+function escapeChar(ch) {
+    return `\\x${ch.charCodeAt(0).toString(16).padStart(2, '0')}`;
+}
+/**
+ * For fields rendered as a single logical line (mission title, checkpoint
+ * summary, a remaining-step entry, a doc title): collapses any real
+ * newline to a visible `\n` escape sequence and escapes other control
+ * characters, so the field can never break out of its line.
+ */
+export function sanitizeSingleLine(s) {
+    return s.replace(/\r\n|\r|\n/g, '\\n').replace(OTHER_CONTROL_CHARS_RE, escapeChar);
+}
+/**
+ * For fields allowed to span multiple lines (the Story excerpt): keeps
+ * real newlines (that is the field's legitimate internal structure) but
+ * still escapes other control characters so nothing unprintable reaches
+ * stdout raw.
+ */
+export function sanitizeMultiLine(s) {
+    return s.replace(/\r\n/g, '\n').replace(OTHER_CONTROL_CHARS_RE, escapeChar);
+}

package/dist/brief/selectors.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Pure, read-only selectors over an already-loaded CoordinatoriumState.
+ *
+ * `listMissions()`/`listCheckpoints()` in mission.ts/checkpoint.ts each call
+ * `readState()` independently, which would mean re-reading state.json once
+ * per section of a brief. Collect-brief reads state.json exactly once (see
+ * collect.ts) and derives everything else from that single snapshot through
+ * these selectors instead.
+ */
+import type { CoordinatoriumState, Mission, Checkpoint } from '../coordinatorium/types.js';
+/** Stable, locale-independent string comparator (never localeCompare — ADR determinism rule). */
+export declare function compareStrings(a: string, b: string): number;
+export declare function selectActiveMissions(state: CoordinatoriumState): Mission[];
+/**
+ * Finished missions (completed/failed/cancelled), most recently updated
+ * first, capped to `limit`. Used for the P2 "last finished missions" slice.
+ */
+export declare function selectRecentFinishedMissions(state: CoordinatoriumState, limit: number): Mission[];
+/**
+ * The checkpoint with the highest numeric ordinal in its id
+ * (`<missionId>-CKPT-NNNN`) — the monotonic per-mission sequence number,
+ * exactly as nextCheckpointId() in checkpoint.ts derives it — NOT the one
+ * with the latest `createdAt` (section 6 of the brief contract: ID order is
+ * authoritative, timestamps are not). Returns null if the mission has no
+ * checkpoints.
+ */
+export declare function selectLatestCheckpoint(state: CoordinatoriumState, missionId: string): Checkpoint | null;
+/**
+ * True if some other checkpoint for this mission has a strictly later
+ * `createdAt` than the one selectLatestCheckpoint() picked by ID ordinal —
+ * i.e. timestamps and ID order disagree about which checkpoint is "latest".
+ * Purely informational (CHECKPOINT_ORDER_MISMATCH), never changes which
+ * checkpoint is reported.
+ */
+export declare function hasCheckpointOrderMismatch(state: CoordinatoriumState, missionId: string, latest: Checkpoint): boolean;
+//# sourceMappingURL=selectors.d.ts.map

package/dist/brief/selectors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"selectors.d.ts","sourceRoot":"","sources":["../../src/brief/selectors.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAE3F,iGAAiG;AACjG,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAI3D;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,EAAE,CAI1E;AAED;;;GAGG;AACH,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,mBAAmB,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,EAAE,CAKjG;AAWD;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,mBAAmB,EAAE,SAAS,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAWvG;AAED;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,mBAAmB,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,GAAG,OAAO,CAMrH"}

package/dist/brief/selectors.js

@@ -0,0 +1,75 @@
+/**
+ * Pure, read-only selectors over an already-loaded CoordinatoriumState.
+ *
+ * `listMissions()`/`listCheckpoints()` in mission.ts/checkpoint.ts each call
+ * `readState()` independently, which would mean re-reading state.json once
+ * per section of a brief. Collect-brief reads state.json exactly once (see
+ * collect.ts) and derives everything else from that single snapshot through
+ * these selectors instead.
+ */
+/** Stable, locale-independent string comparator (never localeCompare — ADR determinism rule). */
+export function compareStrings(a, b) {
+    if (a < b)
+        return -1;
+    if (a > b)
+        return 1;
+    return 0;
+}
+export function selectActiveMissions(state) {
+    return Object.values(state.tactical.missions)
+        .filter((m) => m.status === 'in_progress')
+        .sort((a, b) => compareStrings(a.startedAt, b.startedAt) || compareStrings(a.id, b.id));
+}
+/**
+ * Finished missions (completed/failed/cancelled), most recently updated
+ * first, capped to `limit`. Used for the P2 "last finished missions" slice.
+ */
+export function selectRecentFinishedMissions(state, limit) {
+    return Object.values(state.tactical.missions)
+        .filter((m) => m.status !== 'in_progress')
+        .sort((a, b) => compareStrings(b.updatedAt, a.updatedAt) || compareStrings(b.id, a.id))
+        .slice(0, limit);
+}
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/** All checkpoints belonging to one mission, in no particular order. */
+function checkpointsForMission(state, missionId) {
+    return Object.values(state.tactical.checkpoints).filter((c) => c.missionId === missionId);
+}
+/**
+ * The checkpoint with the highest numeric ordinal in its id
+ * (`<missionId>-CKPT-NNNN`) — the monotonic per-mission sequence number,
+ * exactly as nextCheckpointId() in checkpoint.ts derives it — NOT the one
+ * with the latest `createdAt` (section 6 of the brief contract: ID order is
+ * authoritative, timestamps are not). Returns null if the mission has no
+ * checkpoints.
+ */
+export function selectLatestCheckpoint(state, missionId) {
+    const re = new RegExp(`^${escapeRegExp(missionId)}-CKPT-(\\d+)$`);
+    let best = null;
+    for (const c of checkpointsForMission(state, missionId)) {
+        const match = re.exec(c.id);
+        const ordinal = match ? Number(match[1]) : -1;
+        if (!best || ordinal > best.ordinal || (ordinal === best.ordinal && compareStrings(c.id, best.checkpoint.id) < 0)) {
+            best = { checkpoint: c, ordinal };
+        }
+    }
+    return best?.checkpoint ?? null;
+}
+/**
+ * True if some other checkpoint for this mission has a strictly later
+ * `createdAt` than the one selectLatestCheckpoint() picked by ID ordinal —
+ * i.e. timestamps and ID order disagree about which checkpoint is "latest".
+ * Purely informational (CHECKPOINT_ORDER_MISMATCH), never changes which
+ * checkpoint is reported.
+ */
+export function hasCheckpointOrderMismatch(state, missionId, latest) {
+    for (const c of checkpointsForMission(state, missionId)) {
+        if (c.id === latest.id)
+            continue;
+        if (compareStrings(c.createdAt, latest.createdAt) > 0)
+            return true;
+    }
+    return false;
+}

package/dist/brief/story.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Extracts the "## Current Story" section from
+ * `.monolith/memory/working/active.md` — confirmed structure only, no
+ * heuristic Markdown interpretation (section 5 of the brief contract).
+ *
+ * Only two things are recognized: a line that is exactly a level-1..6
+ * heading, and a line that is exactly `---` (used in active.md as a visual
+ * section separator). The "Current Story" section's content is everything
+ * between its own heading line and the next such boundary.
+ */
+export interface StoryExtraction {
+    hasCurrentStorySection: boolean;
+    excerpt: string | null;
+    /** 1-indexed inclusive line range, e.g. "24-29". */
+    lineRange: string | null;
+}
+export declare function extractCurrentStory(content: string): StoryExtraction;
+//# sourceMappingURL=story.d.ts.map

package/dist/brief/story.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"story.d.ts","sourceRoot":"","sources":["../../src/brief/story.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,MAAM,WAAW,eAAe;IAC9B,sBAAsB,EAAE,OAAO,CAAC;IAChC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,oDAAoD;IACpD,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,eAAe,CAoDpE"}