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

package/dist/brief/git-signals.js

@@ -0,0 +1,101 @@
+/**
+ * Read-only git signals for the freshness check (SELF-AWARENESS-001).
+ *
+ * Runs only `git log` and `git rev-parse`, never a command that writes, never
+ * through a shell, with config that could launch helper programs switched off.
+ * Any failure degrades to `{ status: 'unavailable' }` — git being absent,
+ * broken or refusing the directory must never fail the brief.
+ */
+import { execFileSync } from 'child_process';
+/** Upper bound on commits read after the last state update. Hitting it marks the result truncated. */
+export const MAX_COMMITS_SINCE = 500;
+const GIT_TIMEOUT_MS = 10_000;
+const GIT_MAX_BUFFER = 8 * 1024 * 1024;
+const SAFE_CONFIG = [
+    '-c', 'core.fsmonitor=false',
+    '-c', 'core.pager=cat',
+    '-c', 'log.showSignature=false',
+    '-c', 'diff.external=',
+];
+class GitMissingError extends Error {
+}
+function git(cwd, args) {
+    try {
+        return execFileSync('git', [...SAFE_CONFIG, ...args], {
+            cwd,
+            encoding: 'utf8',
+            timeout: GIT_TIMEOUT_MS,
+            maxBuffer: GIT_MAX_BUFFER,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            env: { ...process.env, GIT_OPTIONAL_LOCKS: '0', GIT_TERMINAL_PROMPT: '0', GIT_EXTERNAL_DIFF: '' },
+        });
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            throw new GitMissingError('git not installed');
+        throw err;
+    }
+}
+const RS = '\x1e'; // record separator, starts each commit
+const US = '\x1f'; // unit separator, between header fields
+/**
+ * @param targetDir project directory (git is run from here; paths are relative to it)
+ * @param stateFiles state documents, relative to `targetDir`. Only existing ones need be passed.
+ */
+export function readGitSignals(targetDir, stateFiles) {
+    try {
+        const inside = git(targetDir, ['rev-parse', '--is-inside-work-tree']).trim();
+        if (inside !== 'true')
+            return { status: 'unavailable', reason: 'NOT_A_GIT_REPOSITORY' };
+    }
+    catch (err) {
+        if (err instanceof GitMissingError)
+            return { status: 'unavailable', reason: 'GIT_NOT_INSTALLED' };
+        const stderr = String(err.stderr ?? '');
+        return { status: 'unavailable', reason: /not a git repository/i.test(stderr) ? 'NOT_A_GIT_REPOSITORY' : 'GIT_FAILED' };
+    }
+    try {
+        // A repository without commits has no HEAD: nothing to compare with.
+        try {
+            git(targetDir, ['rev-parse', '--verify', '--quiet', 'HEAD']);
+        }
+        catch {
+            return { status: 'ok', lastStateUpdate: null, commitsSince: [], truncated: false };
+        }
+        let lastStateUpdate = null;
+        if (stateFiles.length > 0) {
+            const out = git(targetDir, ['log', '-1', `--format=%H${US}%cI`, '--', ...stateFiles]).trim();
+            if (out) {
+                const [sha, date] = out.split(US);
+                lastStateUpdate = { sha, date };
+            }
+        }
+        if (!lastStateUpdate)
+            return { status: 'ok', lastStateUpdate: null, commitsSince: [], truncated: false };
+        const raw = git(targetDir, [
+            'log',
+            `-n${MAX_COMMITS_SINCE + 1}`,
+            '--no-ext-diff',
+            '--no-textconv',
+            '--relative',
+            '--name-only',
+            `--format=${RS}%H${US}%cI${US}%s`,
+            `${lastStateUpdate.sha}..HEAD`,
+        ]);
+        const commits = [];
+        for (const rec of raw.split(RS)) {
+            if (!rec.trim())
+                continue;
+            const nl = rec.indexOf('\n');
+            const header = nl === -1 ? rec : rec.slice(0, nl);
+            const [sha, date, subject] = header.split(US);
+            const files = (nl === -1 ? '' : rec.slice(nl + 1)).split('\n').filter((l) => l.trim() !== '');
+            commits.push({ sha, date, subject: subject ?? '', files });
+        }
+        const truncated = commits.length > MAX_COMMITS_SINCE;
+        return { status: 'ok', lastStateUpdate, commitsSince: commits.slice(0, MAX_COMMITS_SINCE), truncated };
+    }
+    catch {
+        return { status: 'unavailable', reason: 'GIT_FAILED' };
+    }
+}

package/dist/brief/index.d.ts

@@ -0,0 +1,11 @@
+export type { BriefModel, BriefDiagnostic, BriefDiagnosticCode, DiagnosticSeverity, Provenance, ProjectIdentity, StateKeeperStatus, StateKeeperSummary, MissionsSummary, CheckpointSummary, StorySummary, DocRef, AdrRef, AdrIndex, ProtocolIndex, } from './types.js';
+export { collect } from './collect.js';
+export { render, DEFAULT_MAX_CHARS } from './render.js';
+export type { RenderResult, Completeness } from './render.js';
+export { runBrief, parseBriefArgs } from './cli.js';
+export type { BriefArgsResult, BriefArgsOk, BriefArgsErr } from './cli.js';
+export { evaluateFreshness } from './freshness.js';
+export type { FreshnessStatus, FreshnessResult, FreshnessEvidence, FreshnessReason, GitSignals } from './freshness.js';
+export { reconcile, renderReconciliation } from './reconcile.js';
+export type { ReconciliationReport, ReconciliationFinding, FindingKind, UntrackedWorkItem, ReviewDocument } from './reconcile.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/brief/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,UAAU,EACV,eAAe,EACf,mBAAmB,EACnB,kBAAkB,EAClB,UAAU,EACV,eAAe,EACf,iBAAiB,EACjB,kBAAkB,EAClB,eAAe,EACf,iBAAiB,EACjB,YAAY,EACZ,MAAM,EACN,MAAM,EACN,QAAQ,EACR,aAAa,GACd,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,MAAM,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACxD,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AACpD,YAAY,EAAE,eAAe,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAC3E,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACnD,YAAY,EAAE,eAAe,EAAE,eAAe,EAAE,iBAAiB,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACvH,OAAO,EAAE,SAAS,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AACjE,YAAY,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,WAAW,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/brief/index.js

@@ -0,0 +1,5 @@
+export { collect } from './collect.js';
+export { render, DEFAULT_MAX_CHARS } from './render.js';
+export { runBrief, parseBriefArgs } from './cli.js';
+export { evaluateFreshness } from './freshness.js';
+export { reconcile, renderReconciliation } from './reconcile.js';

package/dist/brief/reconcile.d.ts

@@ -0,0 +1,75 @@
+/**
+ * State Reconciliation Report (SELF-AWARENESS-002).
+ *
+ * SELF-AWARENESS-001 says *whether* the recorded state looks outdated. This
+ * module says *what* the evidence is and *what a human should check*. It is
+ * pure: it takes the same `FreshnessEvidence` / `FreshnessResult` that
+ * `brief` already computed, reads nothing and writes nothing.
+ *
+ * Two rules shape every line of the report:
+ *   - A git commit is not evidence that a work item is complete, and a work-item
+ *     id in a commit subject is not evidence that its recorded status is right.
+ *     The report therefore only ever says "referenced" and "not mentioned",
+ *     never "done" or "missing from the roadmap because it was finished".
+ *   - Recommendations are things for a person to verify or decide. Nothing here
+ *     edits a document or concludes anything on the person's behalf.
+ *
+ * Findings are graded:
+ *   confirmed  a concrete, checkable discrepancy (documents contradict each other,
+ *              or git names a work item that no state document mentions)
+ *   suspected  something that may be a discrepancy but cannot be shown from the data
+ *   unknown    the evidence needed to decide is missing (no git, truncated history, ...)
+ */
+import { type FreshnessEvidence, type FreshnessResult, type FreshnessStatus } from './freshness.js';
+export type FindingKind = 'confirmed' | 'suspected' | 'unknown';
+export type FindingCode = 'STATE_CONTRADICTION' | 'UNRECORDED_WORK' | 'UNATTRIBUTED_ACTIVITY' | 'ACTIVITY_WITHOUT_ACTIVE_STORY' | 'GIT_UNAVAILABLE' | 'STATE_NOT_IN_GIT' | 'GIT_HISTORY_TRUNCATED' | 'ACTIVE_STORY_UNKNOWN';
+export interface ReconciliationFinding {
+    kind: FindingKind;
+    code: FindingCode;
+    summary: string;
+    /** Short, checkable pointers: document names or `<sha7> <subject>`. */
+    evidence: string[];
+}
+export interface UntrackedWorkItem {
+    id: string;
+    /** Newest first, at most `MAX_COMMITS_PER_ITEM`. */
+    commits: {
+        sha: string;
+        subject: string;
+    }[];
+    totalCommits: number;
+}
+export interface ReviewDocument {
+    path: string;
+    reasons: string[];
+}
+export interface ReconciliationReport {
+    freshness: FreshnessStatus;
+    lastStateUpdate: {
+        sha: string;
+        date: string;
+    } | null;
+    findings: ReconciliationFinding[];
+    /** Work-item ids git references after the last state update that no state document mentions. Sorted. */
+    untrackedWork: UntrackedWorkItem[];
+    /** Ids git references that some state document mentions. Mentioned is not correct. Sorted. */
+    mentionedWork: string[];
+    documents: ReviewDocument[];
+    limitations: string[];
+    actions: string[];
+}
+export declare const MAX_COMMITS_PER_ITEM = 3;
+export declare function reconcile(ev: FreshnessEvidence, result: FreshnessResult): ReconciliationReport;
+export interface RenderedReconciliation {
+    text: string;
+    /** True when a section was dropped to fit the budget. */
+    truncated: boolean;
+}
+/**
+ * Deterministic, bounded text. The header (freshness) and the closing
+ * "No files were modified." are mandatory and never dropped; the sections in
+ * between are added in priority order while they fit, and an omission is
+ * always announced.
+ */
+export declare function renderReconciliation(report: ReconciliationReport, maxChars: number): RenderedReconciliation;
+//# sourceMappingURL=reconcile.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"reconcile.d.ts","sourceRoot":"","sources":["../../src/brief/reconcile.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAGL,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACpB,KAAK,eAAe,EAErB,MAAM,gBAAgB,CAAC;AAGxB,MAAM,MAAM,WAAW,GAAG,WAAW,GAAG,WAAW,GAAG,SAAS,CAAC;AAEhE,MAAM,MAAM,WAAW,GACnB,qBAAqB,GACrB,iBAAiB,GACjB,uBAAuB,GACvB,+BAA+B,GAC/B,iBAAiB,GACjB,kBAAkB,GAClB,uBAAuB,GACvB,sBAAsB,CAAC;AAE3B,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,WAAW,CAAC;IAClB,IAAI,EAAE,WAAW,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,uEAAuE;IACvE,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,oDAAoD;IACpD,OAAO,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC5C,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,eAAe,CAAC;IAC3B,eAAe,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IACtD,QAAQ,EAAE,qBAAqB,EAAE,CAAC;IAClC,wGAAwG;IACxG,aAAa,EAAE,iBAAiB,EAAE,CAAC;IACnC,8FAA8F;IAC9F,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,SAAS,EAAE,cAAc,EAAE,CAAC;IAC5B,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,eAAO,MAAM,oBAAoB,IAAI,CAAC;AAiBtC,wBAAgB,SAAS,CAAC,EAAE,EAAE,iBAAiB,EAAE,MAAM,EAAE,eAAe,GAAG,oBAAoB,CAmI9F;AAiBD,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,yDAAyD;IACzD,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,oBAAoB,EAAE,QAAQ,EAAE,MAAM,GAAG,sBAAsB,CAoF3G"}

package/dist/brief/reconcile.js

@@ -0,0 +1,259 @@
+/**
+ * State Reconciliation Report (SELF-AWARENESS-002).
+ *
+ * SELF-AWARENESS-001 says *whether* the recorded state looks outdated. This
+ * module says *what* the evidence is and *what a human should check*. It is
+ * pure: it takes the same `FreshnessEvidence` / `FreshnessResult` that
+ * `brief` already computed, reads nothing and writes nothing.
+ *
+ * Two rules shape every line of the report:
+ *   - A git commit is not evidence that a work item is complete, and a work-item
+ *     id in a commit subject is not evidence that its recorded status is right.
+ *     The report therefore only ever says "referenced" and "not mentioned",
+ *     never "done" or "missing from the roadmap because it was finished".
+ *   - Recommendations are things for a person to verify or decide. Nothing here
+ *     edits a document or concludes anything on the person's behalf.
+ *
+ * Findings are graded:
+ *   confirmed  a concrete, checkable discrepancy (documents contradict each other,
+ *              or git names a work item that no state document mentions)
+ *   suspected  something that may be a discrepancy but cannot be shown from the data
+ *   unknown    the evidence needed to decide is missing (no git, truncated history, ...)
+ */
+import { extractWorkItemIds, mentionsId, } from './freshness.js';
+import { sanitizeSingleLine as san } from './sanitize.js';
+export const MAX_COMMITS_PER_ITEM = 3;
+const MAX_LISTED_ITEMS = 10;
+const MAX_SUBJECT_CHARS = 72;
+const DOC_ORDER = ['active.md', 'roadmap-index.md', 'story-index.md', 'HANDOFF.md'];
+function short(sha) {
+    return sha.slice(0, 7);
+}
+function clip(s) {
+    return s.length <= MAX_SUBJECT_CHARS ? s : `${s.slice(0, MAX_SUBJECT_CHARS - 1)}…`;
+}
+function commitLine(c) {
+    return `${short(c.sha)} ${clip(c.subject)}`;
+}
+export function reconcile(ev, result) {
+    const findings = [];
+    const reviewReasons = new Map();
+    const actions = [];
+    const limitations = [
+        'A commit is not evidence that a work item is complete; an id in a commit subject does not show its recorded status is correct.',
+    ];
+    const pathOf = (name) => [...ev.stateFiles].find((f) => f === name || f.endsWith(`/${name}`)) ?? name;
+    const review = (name, reason) => {
+        const path = pathOf(name);
+        const list = reviewReasons.get(path) ?? [];
+        if (!list.includes(reason))
+            list.push(reason);
+        reviewReasons.set(path, list);
+    };
+    // 1. Contradictions between the state documents — need no git.
+    for (const r of result.reasons) {
+        if (r.code !== 'STATE_CONTRADICTION')
+            continue;
+        const docs = r.documents ?? [];
+        findings.push({ kind: 'confirmed', code: 'STATE_CONTRADICTION', summary: r.message, evidence: docs });
+        for (const d of docs)
+            review(d, 'contradicts another state document');
+        actions.push(`Decide which state document is correct: ${r.message}`);
+    }
+    // 2. Git-derived evidence.
+    const untrackedWork = [];
+    let mentionedWork = [];
+    if (ev.git.status === 'unavailable') {
+        findings.push({ kind: 'unknown', code: 'GIT_UNAVAILABLE', summary: reasonMessage(result, 'GIT_UNAVAILABLE'), evidence: [] });
+        actions.push('Run this command from a git checkout (git must be installed) to compare the state documents with history.');
+        limitations.push('Git is unavailable: only contradictions between the state documents can be detected.');
+    }
+    else if (ev.git.lastStateUpdate === null) {
+        findings.push({ kind: 'unknown', code: 'STATE_NOT_IN_GIT', summary: reasonMessage(result, 'STATE_NOT_IN_GIT'), evidence: [] });
+        actions.push('Commit the state documents to establish a baseline, then re-run.');
+        limitations.push('No commit touches the state documents, so there is no baseline to compare history with.');
+    }
+    else {
+        const activity = ev.git.commitsSince.filter((c) => c.files.some((f) => !ev.stateFiles.has(f)));
+        const byId = new Map();
+        const unattributed = [];
+        for (const c of activity) {
+            const ids = extractWorkItemIds(c.subject);
+            if (ids.length === 0)
+                unattributed.push(c);
+            for (const id of ids)
+                byId.set(id, [...(byId.get(id) ?? []), c]);
+        }
+        const ids = [...byId.keys()].sort();
+        mentionedWork = ids.filter((id) => mentionsId(ev.recordedText, id));
+        for (const id of ids.filter((i) => !mentionsId(ev.recordedText, i))) {
+            const commits = byId.get(id) ?? [];
+            untrackedWork.push({
+                id,
+                commits: commits.slice(0, MAX_COMMITS_PER_ITEM).map((c) => ({ sha: c.sha, subject: c.subject })),
+                totalCommits: commits.length,
+            });
+            findings.push({
+                kind: 'confirmed',
+                code: 'UNRECORDED_WORK',
+                summary: `${id} is referenced by ${commits.length} commit(s) after the last state update; no state document mentions it.`,
+                evidence: commits.slice(0, MAX_COMMITS_PER_ITEM).map(commitLine),
+            });
+        }
+        if (untrackedWork.length > 0) {
+            review('roadmap-index.md', 'no entry for work items that git references');
+            review('HANDOFF.md', 'may not describe work items that git references');
+            if (ev.activeStory.kind !== 'ids')
+                review('active.md', 'confirm whether any of this work is current');
+            for (const u of untrackedWork.slice(0, MAX_LISTED_ITEMS)) {
+                actions.push(`Verify the status of ${u.id} and record it if appropriate (git references it; that does not show it is complete).`);
+            }
+            if (untrackedWork.length > MAX_LISTED_ITEMS) {
+                actions.push(`Verify the remaining ${untrackedWork.length - MAX_LISTED_ITEMS} untracked work item(s) listed above.`);
+            }
+        }
+        if (unattributed.length > 0) {
+            findings.push({
+                kind: 'suspected',
+                code: 'UNATTRIBUTED_ACTIVITY',
+                summary: `${unattributed.length} commit(s) after the last state update change project files without naming a work item; whether the state documents cover them cannot be determined.`,
+                evidence: unattributed.slice(0, MAX_COMMITS_PER_ITEM).map(commitLine),
+            });
+            actions.push(`Review the ${unattributed.length} commit(s) that name no work item and decide whether the recorded state covers them.`);
+        }
+        if (activity.length > 0 && ev.activeStory.kind === 'none') {
+            findings.push({
+                kind: 'suspected',
+                code: 'ACTIVITY_WITHOUT_ACTIVE_STORY',
+                summary: 'Git shows project activity after the last state update, but no active story is recorded.',
+                evidence: [],
+            });
+            review('active.md', 'no active story recorded while git shows later activity');
+            actions.push('Review the active story: confirm whether any work is current. No active story does not mean the project is complete.');
+        }
+        if (ev.git.truncated) {
+            findings.push({ kind: 'unknown', code: 'GIT_HISTORY_TRUNCATED', summary: reasonMessage(result, 'GIT_HISTORY_TRUNCATED'), evidence: [] });
+            limitations.push('Git history after the last state update was cut at the read limit; older commits are not examined.');
+            actions.push('Review the history since the last state update manually; this report covers only the newest commits.');
+        }
+        limitations.push('The last state update is the last commit touching a state document; uncommitted edits count for "mentioned" but not for that baseline.');
+    }
+    if (ev.activeStory.kind === 'unknown') {
+        findings.push({
+            kind: 'unknown',
+            code: 'ACTIVE_STORY_UNKNOWN',
+            summary: 'The active story could not be determined from active.md.',
+            evidence: [],
+        });
+        review('active.md', 'its current story could not be parsed');
+    }
+    const documents = [...reviewReasons.entries()]
+        .map(([path, reasons]) => ({ path, reasons }))
+        .sort((a, b) => docRank(a.path) - docRank(b.path));
+    return {
+        freshness: result.status,
+        lastStateUpdate: result.lastStateUpdate,
+        findings,
+        untrackedWork,
+        mentionedWork,
+        documents,
+        limitations,
+        actions,
+    };
+}
+function docRank(path) {
+    const i = DOC_ORDER.findIndex((n) => path === n || path.endsWith(`/${n}`));
+    return i === -1 ? DOC_ORDER.length : i;
+}
+function reasonMessage(result, code) {
+    return result.reasons.find((r) => r.code === code)?.message ?? code;
+}
+// ---------------------------------------------------------------------------
+// Rendering
+// ---------------------------------------------------------------------------
+const TRUNCATION_MARKER_RESERVE = 100;
+/**
+ * Deterministic, bounded text. The header (freshness) and the closing
+ * "No files were modified." are mandatory and never dropped; the sections in
+ * between are added in priority order while they fit, and an omission is
+ * always announced.
+ */
+export function renderReconciliation(report, maxChars) {
+    const head = ['MONOLITH STATE RECONCILIATION', '', `Freshness: ${report.freshness}`];
+    if (report.lastStateUpdate) {
+        head.push(`Last state update: ${san(short(report.lastStateUpdate.sha))} (${san(report.lastStateUpdate.date.slice(0, 10))}, git)`);
+    }
+    const foot = '\nNo files were modified.\n';
+    const sections = [];
+    const bullets = (title, lines) => `\n${title}\n${lines.join('\n')}\n`;
+    const contradictions = report.findings.filter((f) => f.code === 'STATE_CONTRADICTION');
+    if (contradictions.length > 0) {
+        sections.push(bullets('Confirmed mismatches between state documents:', contradictions.map((f) => `- ${san(f.summary)}`)));
+    }
+    if (report.untrackedWork.length > 0) {
+        const lines = [];
+        for (const u of report.untrackedWork.slice(0, MAX_LISTED_ITEMS)) {
+            lines.push(`- ${u.id} (${u.totalCommits} commit(s) in git)`);
+            for (const c of u.commits)
+                lines.push(`    ${san(commitLine(c))}`);
+            if (u.totalCommits > u.commits.length)
+                lines.push(`    … and ${u.totalCommits - u.commits.length} more`);
+        }
+        if (report.untrackedWork.length > MAX_LISTED_ITEMS) {
+            lines.push(`- … and ${report.untrackedWork.length - MAX_LISTED_ITEMS} more work item(s)`);
+        }
+        sections.push(bullets('Untracked work items (referenced in git, mentioned in no state document):', lines));
+    }
+    for (const [kind, title] of [
+        ['suspected', 'Suspected mismatches (not confirmable from the data):'],
+        ['unknown', 'Unknown (evidence missing):'],
+    ]) {
+        const list = report.findings.filter((f) => f.kind === kind);
+        if (list.length === 0)
+            continue;
+        const lines = [];
+        for (const f of list) {
+            lines.push(`- ${san(f.summary)}`);
+            for (const e of f.evidence)
+                lines.push(`    ${san(e)}`);
+        }
+        sections.push(bullets(title, lines));
+    }
+    if (report.documents.length > 0) {
+        const lines = [];
+        for (const d of report.documents)
+            lines.push(`- ${san(d.path)} — ${d.reasons.map(san).join('; ')}`);
+        sections.push(bullets('Documents requiring review:', lines));
+    }
+    if (report.findings.length === 0) {
+        sections.push('\nNo discrepancy was found in the available evidence. This is not a guarantee the state is correct.\n');
+    }
+    if (report.mentionedWork.length > 0) {
+        const shown = report.mentionedWork.slice(0, MAX_LISTED_ITEMS).join(', ');
+        const more = report.mentionedWork.length > MAX_LISTED_ITEMS ? ` and ${report.mentionedWork.length - MAX_LISTED_ITEMS} more` : '';
+        sections.push(`\nWork items in git that state documents mention: ${shown}${more}. Mentioned does not mean the recorded status is correct.\n`);
+    }
+    sections.push(bullets('Limitations:', report.limitations.map((l) => `- ${san(l)}`)));
+    if (report.actions.length > 0) {
+        sections.push(bullets('Suggested actions (for a person to decide; none is applied automatically):', report.actions.map((a, i) => `${i + 1}. ${san(a)}`)));
+    }
+    const mandatory = head.join('\n') + '\n' + foot;
+    let used = mandatory.length;
+    const kept = [];
+    let omitted = 0;
+    for (const s of sections) {
+        // Priority order: once a section is dropped, every later one is too. Room for the marker is always reserved.
+        if (omitted === 0 && used + s.length <= maxChars - TRUNCATION_MARKER_RESERVE) {
+            kept.push(s);
+            used += s.length;
+        }
+        else {
+            omitted++;
+        }
+    }
+    let body = kept.join('');
+    if (omitted > 0) {
+        body += `\n[truncated: ${omitted} section(s) omitted to fit --max-chars ${maxChars}]\n`;
+    }
+    return { text: head.join('\n') + '\n' + body + foot, truncated: omitted > 0 };
+}

package/dist/brief/render.d.ts

@@ -0,0 +1,67 @@
+/**
+ * `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).
+ *
+ * Advisory section (IDEA-002B): Parked Ideas is the one data-holding section whose
+ * budget degradation does NOT force INCOMPLETE. It is user-saved side context, not
+ * project state; its degradation stays visible (fewer items, count, or a marker
+ * whenever they fit) but `Completeness` and `--strict` keep describing only the
+ * project context that existed before ideas did. Unreadable idea files are
+ * reported by the `IDEAS_UNREADABLE` warning, which is not an error.
+ */
+import type { BriefModel } from './types.js';
+export declare const DEFAULT_MAX_CHARS = 6000;
+export type Completeness = 'COMPLETE' | 'INCOMPLETE';
+export interface RenderResult {
+    text: string;
+    completeness: Completeness;
+}
+export declare function render(model: BriefModel, maxChars?: number): RenderResult;
+//# sourceMappingURL=render.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../../src/brief/render.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AAEH,OAAO,KAAK,EAAE,UAAU,EAA0F,MAAM,YAAY,CAAC;AAYrI,eAAO,MAAM,iBAAiB,OAAO,CAAC;AAGtC,MAAM,MAAM,YAAY,GAAG,UAAU,GAAG,YAAY,CAAC;AAErD,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,YAAY,CAAC;CAC5B;AAwXD,wBAAgB,MAAM,CAAC,KAAK,EAAE,UAAU,EAAE,QAAQ,GAAE,MAA0B,GAAG,YAAY,CAgF5F"}