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

package/dist/brief/collect.js

@@ -0,0 +1,342 @@
+/**
+ * `collect()` — the read-only Collection stage of the brief pipeline.
+ *
+ * readMonolithRoot → collect() → BriefModel → render(model, budget) → stdout
+ *
+ * Strictly read-only: no directories, lock files, or state.json are ever
+ * created; `mutateState()` is never imported here. state.json is read at
+ * most once (one `readFile` call) per invocation — every section that needs
+ * Coordinatorium data derives it from that single snapshot via the pure
+ * selectors in selectors.ts, never by calling `listMissions()`/
+ * `listCheckpoints()` (which each independently re-read the file).
+ */
+import { existsSync } from 'fs';
+import { join, relative, posix } from 'path';
+import { readBriefConfig } from './config.js';
+import { resolveMonolithRootValue, checkContainedFile, readBoundedFileStable, isReadSecurityViolation, findWriteArtifacts, describeWriteArtifacts, } from '../root/index.js';
+import { discoverDocs } from './docs.js';
+import { extractCurrentStory } from './story.js';
+import { selectActiveMissions, selectRecentFinishedMissions, selectLatestCheckpoint, hasCheckpointOrderMismatch, } from './selectors.js';
+import { stateFilePath, validateState, createInitialState, MAX_STATE_BYTES } from '../coordinatorium/index.js';
+import { ACTIVE_MD_REL, PARKED_IDEAS_LIMIT, PROTOCOLS_DIR, ROADMAP_INDEX_REL, STORY_INDEX_REL, HANDOFF_REL } from './constants.js';
+import { evaluateFreshness, parseActiveStoryClaim, parseRoadmapActiveStory, parseRoadmapStatuses, parseStoryIndexStatuses, } from './freshness.js';
+import { readGitSignals } from './git-signals.js';
+import { ideaStore, listIdeas } from '../ideas/index.js';
+import { ideaNumber } from '../ideas/format.js';
+const RECENT_FINISHED_MISSIONS_LIMIT = 5;
+/** SEC-001B.1: `active.md` is a short hand-written context file (~3 KB today). */
+export const MAX_ACTIVE_CONTEXT_BYTES = 256 * 1024;
+function isPlainObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+async function readStateForBrief(targetDir, monolithRoot, root, diagnostics) {
+    const stateDir = join(targetDir, monolithRoot);
+    const filePath = stateFilePath(stateDir);
+    const provenance = { source: relative(targetDir, filePath) };
+    // SEC-001A: never read a state.json that resolves outside the project.
+    const escape = checkContainedFile(root, 'state.json');
+    if (escape) {
+        diagnostics.push({
+            code: 'PATH_OUTSIDE_PROJECT',
+            severity: 'error',
+            message: `${provenance.source} was not read: ${escape.message}`,
+        });
+        return { summary: { status: 'unreadable', provenance }, state: createInitialState() };
+    }
+    // Rule (section 4, #1): existence is established by the same bounded,
+    // non-blocking open that reads the file (SEC-001B.1) — a FIFO or an
+    // over-limit file is rejected before any content is read.
+    const read = readBoundedFileStable(filePath, provenance.source, { boundary: targetDir, maxBytes: MAX_STATE_BYTES, allowEmpty: true }, true);
+    if (!read.ok && read.code === 'FILE_MISSING') {
+        diagnostics.push({
+            code: 'STATE_NOT_INITIALIZED',
+            severity: 'info',
+            message: `${provenance.source} does not exist — no missions have ever been recorded.`,
+            readCode: 'FILE_MISSING',
+        });
+        return { summary: { status: 'absent', provenance }, state: createInitialState() };
+    }
+    if (!read.ok) {
+        diagnostics.push({
+            code: 'STATE_UNREADABLE',
+            severity: 'error',
+            message: `${provenance.source} exists but could not be read: ${read.code}: ${read.detail}`,
+            readCode: read.code,
+        });
+        return { summary: { status: 'unreadable', provenance }, state: createInitialState() };
+    }
+    const raw = 'content' in read ? read.content : '';
+    // A literally empty file is distinguished from corrupted content
+    // (DEC-CONTEXT-002: "corrupted state.json must not be treated as empty
+    // state") precisely so the STATE_UNREADABLE path below is never reached
+    // for this case by accident — it gets its own diagnostic instead.
+    //
+    // Review finding F-1: an empty state.json means no actual state could be
+    // read — that is a loss of information, not a benign "zero missions"
+    // result (which only a successfully parsed, valid file can report).
+    // severity 'error' here is what makes render() treat this as INCOMPLETE
+    // (and --strict exit 2), the same way STATE_UNREADABLE already does.
+    if (raw.trim() === '') {
+        diagnostics.push({
+            code: 'STATE_EMPTY',
+            severity: 'error',
+            message: `${provenance.source} exists but is empty — no state could be read.`,
+        });
+        return { summary: { status: 'empty', provenance }, state: createInitialState() };
+    }
+    let parsedJson;
+    try {
+        parsedJson = JSON.parse(raw);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        diagnostics.push({
+            code: 'STATE_UNREADABLE',
+            severity: 'error',
+            message: `${provenance.source} is not valid JSON: ${msg}`,
+        });
+        return { summary: { status: 'unreadable', provenance }, state: createInitialState() };
+    }
+    const onDiskSchemaVersion = isPlainObject(parsedJson) && typeof parsedJson.schemaVersion === 'number' ? parsedJson.schemaVersion : undefined;
+    let state;
+    try {
+        // Supports schemaVersion 2 and an in-memory v1→v2 migration of legacy
+        // files — nothing is ever written back (section 4, #6/#7).
+        state = validateState(parsedJson);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        diagnostics.push({
+            code: 'STATE_UNREADABLE',
+            severity: 'error',
+            message: `${provenance.source} failed schema validation: ${msg}`,
+        });
+        return { summary: { status: 'unreadable', schemaVersionOnDisk: onDiskSchemaVersion, provenance }, state: createInitialState() };
+    }
+    if (onDiskSchemaVersion === 1) {
+        diagnostics.push({
+            code: 'STATE_LEGACY_SCHEMA_MIGRATED',
+            severity: 'info',
+            message: `${provenance.source} is schemaVersion 1 — read via the existing in-memory v1→v2 migration; nothing was written to disk.`,
+        });
+    }
+    return { summary: { status: 'ok', schemaVersionOnDisk: onDiskSchemaVersion, provenance }, state };
+}
+function collectMissions(targetDir, monolithRoot, state, diagnostics) {
+    const active = selectActiveMissions(state);
+    const recentFinished = selectRecentFinishedMissions(state, RECENT_FINISHED_MISSIONS_LIMIT);
+    if (active.length > 1) {
+        diagnostics.push({
+            code: 'MULTIPLE_ACTIVE_MISSIONS',
+            severity: 'info',
+            message: `${active.length} missions are in_progress simultaneously: ${active.map((m) => m.id).join(', ')}.`,
+        });
+    }
+    const filePath = stateFilePath(join(targetDir, monolithRoot));
+    return { active, recentFinished, provenance: { source: `${relative(targetDir, filePath)}#tactical.missions` } };
+}
+function collectCheckpoints(targetDir, monolithRoot, state, active, diagnostics) {
+    const filePath = stateFilePath(join(targetDir, monolithRoot));
+    const provenance = { source: `${relative(targetDir, filePath)}#tactical.checkpoints` };
+    return active.map((m) => {
+        const latest = selectLatestCheckpoint(state, m.id);
+        if (latest && hasCheckpointOrderMismatch(state, m.id, latest)) {
+            diagnostics.push({
+                code: 'CHECKPOINT_ORDER_MISMATCH',
+                severity: 'info',
+                message: `Mission "${m.id}": another checkpoint has a later createdAt than "${latest.id}" (the highest-ordinal one) — timestamp order and ID order disagree.`,
+            });
+        }
+        return { missionId: m.id, latest, provenance };
+    });
+}
+function collectStory(targetDir, monolithRoot, root, diagnostics) {
+    const activeMdAbs = join(targetDir, monolithRoot, ACTIVE_MD_REL);
+    const relPath = relative(targetDir, activeMdAbs);
+    // SEC-001A: never present a file outside the project as project context.
+    const escape = checkContainedFile(root, ACTIVE_MD_REL);
+    if (escape) {
+        diagnostics.push({
+            code: 'PATH_OUTSIDE_PROJECT',
+            severity: 'error',
+            message: `${relPath} was not read: ${escape.message}`,
+        });
+        return { fileExists: false, hasCurrentStorySection: false, excerpt: null, lineRange: null, provenance: null };
+    }
+    const read = readBoundedFileStable(activeMdAbs, relPath, { boundary: targetDir, maxBytes: MAX_ACTIVE_CONTEXT_BYTES, allowEmpty: true }, true);
+    if (!read.ok) {
+        // SEC-001B.1-R (M-1): three different situations, three different diagnostics.
+        // Only a really absent file is "missing" (a warning: a project may have no story
+        // yet). A file the safe-read policy refuses, or one that cannot be read, is an
+        // error: the story exists but was not shown, so the brief is INCOMPLETE. The
+        // detail never carries file content — only the label and the typed code.
+        if (read.code === 'FILE_MISSING') {
+            diagnostics.push({
+                code: 'ACTIVE_MD_MISSING',
+                severity: 'warn',
+                message: `${relPath} does not exist.`,
+                readCode: read.code,
+            });
+        }
+        else if (isReadSecurityViolation(read.code)) {
+            diagnostics.push({
+                code: 'ACTIVE_MD_REJECTED',
+                severity: 'error',
+                message: `${relPath} exists but was refused by the safe-read policy and not read: ${read.code}: ${read.detail}`,
+                readCode: read.code,
+            });
+        }
+        else {
+            diagnostics.push({
+                code: 'ACTIVE_MD_UNREADABLE',
+                severity: 'error',
+                message: `${relPath} exists but could not be read: ${read.code}: ${read.detail}`,
+                readCode: read.code,
+            });
+        }
+        return { fileExists: false, hasCurrentStorySection: false, excerpt: null, lineRange: null, provenance: null };
+    }
+    const content = 'content' in read ? read.content : '';
+    const extraction = extractCurrentStory(content);
+    if (!extraction.hasCurrentStorySection) {
+        diagnostics.push({
+            code: 'ACTIVE_MD_NO_CURRENT_STORY',
+            severity: 'info',
+            message: `${relPath} exists but has no "## Current Story" section.`,
+        });
+    }
+    return {
+        fileExists: true,
+        hasCurrentStorySection: extraction.hasCurrentStorySection,
+        excerpt: extraction.excerpt,
+        lineRange: extraction.lineRange,
+        provenance: { source: extraction.lineRange ? `${relPath}:${extraction.lineRange}` : relPath },
+    };
+}
+const IDEAS_UNREADABLE_LISTED = 3;
+/**
+ * IDEA-002A: the `inbox` ideas, via the Idea Capture reader (`listIdeas`: bounded,
+ * symlink/hardlink/special-file refusing, never writes). A file that cannot be read
+ * as an idea is not counted and is reported as one warning — it never breaks the
+ * brief. Idea content is untrusted; only ids and titles are kept.
+ */
+function collectParkedIdeas(targetDir, diagnostics) {
+    const empty = { total: 0, items: [] };
+    let entries;
+    try {
+        entries = listIdeas(ideaStore(targetDir));
+    }
+    catch (err) {
+        const code = err instanceof Error && 'code' in err ? String(err.code) : 'ERROR';
+        diagnostics.push({
+            code: 'IDEAS_UNREADABLE',
+            severity: 'warn',
+            message: `The ideas directory was not read (${code}); parked ideas are not shown.`,
+        });
+        return empty;
+    }
+    const inbox = entries.flatMap((e) => (e.ok && e.idea.status === 'inbox' ? [e.idea] : []));
+    inbox.sort((a, b) => ideaNumber(b.id) - ideaNumber(a.id));
+    const bad = entries.flatMap((e) => (e.ok ? [] : [e]));
+    if (bad.length > 0) {
+        const listed = bad.slice(0, IDEAS_UNREADABLE_LISTED).map((e) => `${e.id} (${e.code})`).join(', ');
+        const more = bad.length > IDEAS_UNREADABLE_LISTED ? `, and ${bad.length - IDEAS_UNREADABLE_LISTED} more` : '';
+        diagnostics.push({
+            code: 'IDEAS_UNREADABLE',
+            severity: 'warn',
+            message: `${bad.length} idea file(s) could not be read and are not counted as parked: ${listed}${more}. Run \`monolith idea show <id>\`.`,
+        });
+    }
+    return { total: inbox.length, items: inbox.slice(0, PARKED_IDEAS_LIMIT).map((i) => ({ id: i.id, title: i.title })) };
+}
+/**
+ * Best-effort read of one state document for the freshness check. A missing,
+ * refused or unreadable file simply contributes no evidence — freshness never
+ * adds a diagnostic of its own and never makes the brief INCOMPLETE.
+ */
+function readStateDocument(targetDir, monolithRoot, root, rel) {
+    if (checkContainedFile(root, rel))
+        return null;
+    const abs = join(targetDir, monolithRoot, rel);
+    const read = readBoundedFileStable(abs, relative(targetDir, abs), { boundary: targetDir, maxBytes: MAX_ACTIVE_CONTEXT_BYTES, allowEmpty: true }, true);
+    return read.ok && 'content' in read ? read.content : null;
+}
+function collectFreshness(targetDir, monolithRoot, root, story) {
+    const docs = [ACTIVE_MD_REL, ROADMAP_INDEX_REL, STORY_INDEX_REL, HANDOFF_REL];
+    const stateFiles = docs.map((rel) => posix.normalize(`${monolithRoot}/${rel}`));
+    const content = new Map(docs.map((rel) => [rel, readStateDocument(targetDir, monolithRoot, root, rel)]));
+    const roadmap = content.get(ROADMAP_INDEX_REL) ?? null;
+    const storyIndex = content.get(STORY_INDEX_REL) ?? null;
+    const evidence = {
+        git: readGitSignals(targetDir, stateFiles),
+        activeStory: story.fileExists && story.hasCurrentStorySection ? parseActiveStoryClaim(story.excerpt) : { kind: 'unknown' },
+        roadmapActiveStory: roadmap === null ? null : parseRoadmapActiveStory(roadmap),
+        roadmapStatuses: roadmap === null ? new Map() : parseRoadmapStatuses(roadmap),
+        storyIndexStatuses: storyIndex === null ? new Map() : parseStoryIndexStatuses(storyIndex),
+        recordedText: [...content.values()].filter((c) => c !== null).join('\n'),
+        stateFiles: new Set(stateFiles),
+    };
+    return { result: evaluateFreshness(evidence), evidence };
+}
+export async function collect(targetDir) {
+    const diagnostics = [];
+    const config = readBriefConfig(targetDir, diagnostics);
+    // Re-validates (and realpath-checks) the root readBriefConfig just accepted.
+    const root = resolveMonolithRootValue(targetDir, config.monolithRoot);
+    const monolithRootAbs = root.rootAbs;
+    const monolithInitialized = existsSync(monolithRootAbs);
+    if (!monolithInitialized) {
+        diagnostics.push({
+            code: 'MONOLITH_NOT_INITIALIZED',
+            severity: 'warn',
+            message: `No MONOLITH instance found at "${config.monolithRoot}" — nothing to summarize.`,
+        });
+    }
+    if (monolithInitialized) {
+        // Read-only (SEC-001B.2): names only. A warning, never an error — it does
+        // not make the brief INCOMPLETE — and nothing is deleted or repaired.
+        const artifacts = findWriteArtifacts(monolithRootAbs);
+        if (artifacts.length > 0) {
+            diagnostics.push({
+                code: 'WRITE_ARTIFACTS_PRESENT',
+                severity: 'warn',
+                message: describeWriteArtifacts(artifacts, config.monolithRoot),
+            });
+        }
+    }
+    const identity = {
+        name: config.projectName,
+        monolithRoot: config.monolithRoot,
+        provenance: { source: 'monolith.config.json#project.name' },
+    };
+    const { summary: stateKeeper, state } = await readStateForBrief(targetDir, config.monolithRoot, root, diagnostics);
+    const missions = collectMissions(targetDir, config.monolithRoot, state, diagnostics);
+    const checkpoints = collectCheckpoints(targetDir, config.monolithRoot, state, missions.active, diagnostics);
+    const story = collectStory(targetDir, config.monolithRoot, root, diagnostics);
+    const { result: freshness, evidence: freshnessEvidence } = collectFreshness(targetDir, config.monolithRoot, root, story);
+    const protocolsRelDir = `${config.monolithRoot}/${PROTOCOLS_DIR}`;
+    const mandatoryProtocols = {
+        items: discoverDocs(targetDir, [protocolsRelDir], (fields) => fields.get('enforcement') === 'mandatory', diagnostics),
+        provenance: { source: protocolsRelDir },
+    };
+    const adrDirs = config.adrDirs;
+    const adrs = {
+        items: discoverDocs(targetDir, adrDirs, (fields) => fields.get('status') === 'accepted', diagnostics),
+        provenance: { source: adrDirs.join(', ') },
+    };
+    const parkedIdeas = monolithInitialized ? collectParkedIdeas(targetDir, diagnostics) : { total: 0, items: [] };
+    return {
+        identity,
+        monolithInitialized,
+        stateKeeper,
+        missions,
+        checkpoints,
+        story,
+        mandatoryProtocols,
+        adrs,
+        parkedIdeas,
+        diagnostics,
+        freshness,
+        freshnessEvidence,
+    };
+}

package/dist/brief/config.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Minimal `monolith.config.json` reader for the brief subsystem.
+ *
+ * Mirrors the existing `readMonolithRoot()` duplicated in
+ * `src/coordinatorium/cli.ts` and `src/validate/index.ts` — same
+ * "duplicate rather than couple CLI layers together" precedent. Adds one
+ * new, explicit, optional field: `contextGateway.adrDirs` (DEC-CONTEXT-003 /
+ * section 8 — the existing config contract had no way to name additional
+ * ADR directories, so this is the minimal extension to it, not a new
+ * configuration subsystem).
+ *
+ * Review finding F-6: a missing config file is a legitimate, silent
+ * default (no project has been configured yet). A *present but corrupted*
+ * config file is not the same thing and must not be masked as "healthy
+ * project, defaults apply" — it is reported via CONFIG_UNREADABLE and
+ * forces Completeness: INCOMPLETE, same severity model as STATE_UNREADABLE.
+ * Likewise, a present-but-wrong-shape `contextGateway.adrDirs` (not an
+ * array) is reported via CONFIG_ADR_DIRS_INVALID rather than silently
+ * collapsing to `[]`. Non-string entries *within* an otherwise-valid array
+ * are dropped with a lower-severity (warn) note — a partially-junk list is
+ * a lesser problem than the field having the wrong shape entirely.
+ */
+import type { BriefDiagnostic } from './types.js';
+export interface BriefConfig {
+    monolithRoot: string;
+    projectName: string;
+    /**
+     * ADR directories to scan, relative to targetDir. Defaults to the canonical
+     * `docs/adr`; `monolith.config.json`'s `contextGateway.adrDirs` replaces
+     * (does not extend) that default. No legacy directory is scanned implicitly.
+     */
+    adrDirs: string[];
+}
+/**
+ * Throws RootContainmentError when `monolithRoot` violates the SEC-001A
+ * containment policy (see src/root) — the brief never degrades to a default
+ * root in that case.
+ */
+export declare function readBriefConfig(targetDir: string, diagnostics?: BriefDiagnostic[]): BriefConfig;
+//# sourceMappingURL=config.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/brief/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAIH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAIlD,MAAM,WAAW,WAAW;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAMD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,WAAW,GAAE,eAAe,EAAO,GAAG,WAAW,CAuDnG"}

package/dist/brief/config.js

@@ -0,0 +1,85 @@
+/**
+ * Minimal `monolith.config.json` reader for the brief subsystem.
+ *
+ * Mirrors the existing `readMonolithRoot()` duplicated in
+ * `src/coordinatorium/cli.ts` and `src/validate/index.ts` — same
+ * "duplicate rather than couple CLI layers together" precedent. Adds one
+ * new, explicit, optional field: `contextGateway.adrDirs` (DEC-CONTEXT-003 /
+ * section 8 — the existing config contract had no way to name additional
+ * ADR directories, so this is the minimal extension to it, not a new
+ * configuration subsystem).
+ *
+ * Review finding F-6: a missing config file is a legitimate, silent
+ * default (no project has been configured yet). A *present but corrupted*
+ * config file is not the same thing and must not be masked as "healthy
+ * project, defaults apply" — it is reported via CONFIG_UNREADABLE and
+ * forces Completeness: INCOMPLETE, same severity model as STATE_UNREADABLE.
+ * Likewise, a present-but-wrong-shape `contextGateway.adrDirs` (not an
+ * array) is reported via CONFIG_ADR_DIRS_INVALID rather than silently
+ * collapsing to `[]`. Non-string entries *within* an otherwise-valid array
+ * are dropped with a lower-severity (warn) note — a partially-junk list is
+ * a lesser problem than the field having the wrong shape entirely.
+ */
+import { readConfigFile, resolveMonolithRoot, DEFAULT_MONOLITH_ROOT } from '../root/index.js';
+import { DEFAULT_ADR_DIR } from './constants.js';
+const DEFAULT_PROJECT_NAME = 'project';
+function errMsg(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/**
+ * Throws RootContainmentError when `monolithRoot` violates the SEC-001A
+ * containment policy (see src/root) — the brief never degrades to a default
+ * root in that case.
+ */
+export function readBriefConfig(targetDir, diagnostics = []) {
+    const defaults = { monolithRoot: DEFAULT_MONOLITH_ROOT, projectName: DEFAULT_PROJECT_NAME, adrDirs: [DEFAULT_ADR_DIR] };
+    const read = readConfigFile(targetDir);
+    if (read.status === 'absent') {
+        // Absent config is a legitimate, unconfigured project — not an error.
+        return defaults;
+    }
+    if (read.status !== 'ok') {
+        const message = read.status === 'unreadable'
+            ? `monolith.config.json exists but could not be read: ${read.detail}. Proceeding with defaults.`
+            : read.status === 'invalid-json'
+                ? `monolith.config.json is not valid JSON: ${read.detail}. Proceeding with defaults.`
+                : 'monolith.config.json does not contain a JSON object. Proceeding with defaults.';
+        diagnostics.push({ code: 'CONFIG_UNREADABLE', severity: 'error', message });
+        return defaults;
+    }
+    const cfg = read.cfg;
+    const monolithRoot = resolveMonolithRoot(targetDir, read).monolithRoot;
+    let projectName = DEFAULT_PROJECT_NAME;
+    const project = cfg.project;
+    if (typeof project === 'object' && project !== null && !Array.isArray(project)) {
+        const name = project.name;
+        if (typeof name === 'string' && name.length > 0)
+            projectName = name;
+    }
+    let adrDirs = [DEFAULT_ADR_DIR];
+    const contextGateway = cfg.contextGateway;
+    if (typeof contextGateway === 'object' && contextGateway !== null && !Array.isArray(contextGateway)) {
+        const configured = contextGateway.adrDirs;
+        if (configured !== undefined) {
+            if (!Array.isArray(configured)) {
+                diagnostics.push({
+                    code: 'CONFIG_ADR_DIRS_INVALID',
+                    severity: 'error',
+                    message: 'monolith.config.json#contextGateway.adrDirs is present but is not an array; using the default ADR directory.',
+                });
+            }
+            else {
+                const stringEntries = configured.filter((d) => typeof d === 'string' && d.length > 0);
+                if (stringEntries.length !== configured.length) {
+                    diagnostics.push({
+                        code: 'CONFIG_ADR_DIRS_INVALID',
+                        severity: 'warn',
+                        message: 'monolith.config.json#contextGateway.adrDirs contains non-string entries; they were dropped.',
+                    });
+                }
+                adrDirs = stringEntries;
+            }
+        }
+    }
+    return { monolithRoot, projectName, adrDirs };
+}

package/dist/brief/constants.d.ts

@@ -0,0 +1,12 @@
+/** Shared path constants for the brief subsystem (relative to monolithRoot). */
+export declare const ACTIVE_MD_REL = "memory/working/active.md";
+/** Canonical ADR directory, relative to the project root (not monolithRoot). Used when `contextGateway.adrDirs` is not configured. */
+export declare const DEFAULT_ADR_DIR = "docs/adr";
+export declare const PROTOCOLS_DIR = "protocols";
+/** State documents whose last commit marks the "last recorded state update" (SELF-AWARENESS-001). */
+export declare const ROADMAP_INDEX_REL = "context/maps/roadmap-index.md";
+export declare const STORY_INDEX_REL = "memory/working/story-index.md";
+export declare const HANDOFF_REL = "context/boot/HANDOFF.md";
+/** IDEA-002A: most parked ideas the brief ever lists; the rest is a "+N more" count. */
+export declare const PARKED_IDEAS_LIMIT = 3;
+//# sourceMappingURL=constants.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/brief/constants.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,eAAO,MAAM,aAAa,6BAA6B,CAAC;AACxD,sIAAsI;AACtI,eAAO,MAAM,eAAe,aAAa,CAAC;AAC1C,eAAO,MAAM,aAAa,cAAc,CAAC;AACzC,qGAAqG;AACrG,eAAO,MAAM,iBAAiB,kCAAkC,CAAC;AACjE,eAAO,MAAM,eAAe,kCAAkC,CAAC;AAC/D,eAAO,MAAM,WAAW,4BAA4B,CAAC;AACrD,wFAAwF;AACxF,eAAO,MAAM,kBAAkB,IAAI,CAAC"}

package/dist/brief/constants.js

@@ -0,0 +1,11 @@
+/** Shared path constants for the brief subsystem (relative to monolithRoot). */
+export const ACTIVE_MD_REL = 'memory/working/active.md';
+/** Canonical ADR directory, relative to the project root (not monolithRoot). Used when `contextGateway.adrDirs` is not configured. */
+export const DEFAULT_ADR_DIR = 'docs/adr';
+export const PROTOCOLS_DIR = 'protocols';
+/** State documents whose last commit marks the "last recorded state update" (SELF-AWARENESS-001). */
+export const ROADMAP_INDEX_REL = 'context/maps/roadmap-index.md';
+export const STORY_INDEX_REL = 'memory/working/story-index.md';
+export const HANDOFF_REL = 'context/boot/HANDOFF.md';
+/** IDEA-002A: most parked ideas the brief ever lists; the rest is a "+N more" count. */
+export const PARKED_IDEAS_LIMIT = 3;

package/dist/brief/docs.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Generic, deterministic markdown-frontmatter discovery used for both
+ * Mandatory Protocols (section 7) and ADR Discovery (section 8). Reuses
+ * Scriptorium's existing frontmatter parser (per the brief contract) — does
+ * NOT use `compileMarkdownArtifact()` or the ERG graph builder, both of
+ * which are explicitly out of scope here.
+ *
+ * Resilience (review findings F-2/F-3): a single unreadable directory,
+ * unreadable file, dangling symlink, symlink cycle, or a configured
+ * directory that escapes the project root must never crash the whole brief
+ * or silently disappear. Each failure is caught, reported as a diagnostic
+ * (forcing Completeness: INCOMPLETE), and discovery continues with
+ * whatever else is readable.
+ *
+ * Symlinks (file or directory entries) are never followed while walking —
+ * this is what makes a symlink cycle (ELOOP) impossible by construction,
+ * and is also the first line of defense against using a nested symlink to
+ * tunnel outside a configured directory. The *top-level* directories named
+ * in `dirs` (i.e. `contextGateway.adrDirs` and the standard protocols
+ * dir) get an explicit containment check in addition: both a string-level
+ * check (rejects `..` segments in the configured path itself) and a
+ * real-path check after resolving symlinks (rejects a configured directory
+ * that is itself a symlink escaping the project root). Neither check alone
+ * is treated as sufficient — path.join()/path.relative() string comparison
+ * alone does not account for symlinks on disk.
+ *
+ * `monolithRoot` itself, and the fixed files below it (state.json,
+ * active.md), are vetted separately by the shared resolver in src/root
+ * (SEC-001A); this check covers document directories only.
+ */
+import type { BriefDiagnostic, DocRef } from './types.js';
+/** SEC-001B.1: protocol / ADR documents (largest in this repo is ~80 KB). */
+export declare const MAX_MARKDOWN_DOC_BYTES: number;
+export interface ParsedDoc {
+    /** Relative to targetDir. */
+    relPath: string;
+    id: string | undefined;
+    /** frontmatter `title:`, or (only when no frontmatter title exists) the first H1 — resolved once, at parse time. */
+    resolvedTitle: string | undefined;
+    /** All frontmatter fields (first value per key), for filter predicates. */
+    fields: Map<string, string>;
+}
+/**
+ * Discover documents under `dirs` (relative to targetDir, deduplicated,
+ * each walked recursively) whose frontmatter matches `predicate`. Only
+ * documents with a usable frontmatter `id:` are included — a markdown file
+ * without one isn't a candidate ADR/protocol record, it's silently excluded
+ * from this listing (not an error). `diagnostics` collects every resilience
+ * finding described in the module doc comment; callers that don't care can
+ * omit it.
+ */
+export declare function discoverDocs(targetDir: string, dirs: string[], predicate: (fields: Map<string, string>) => boolean, diagnostics?: BriefDiagnostic[]): DocRef[];
+//# sourceMappingURL=docs.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"docs.d.ts","sourceRoot":"","sources":["../../src/brief/docs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAOH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAE1D,6EAA6E;AAC7E,eAAO,MAAM,sBAAsB,QAAc,CAAC;AAIlD,MAAM,WAAW,SAAS;IACxB,6BAA6B;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,EAAE,EAAE,MAAM,GAAG,SAAS,CAAC;IACvB,oHAAoH;IACpH,aAAa,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,2EAA2E;IAC3E,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC7B;AA+KD;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAC1B,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EAAE,EACd,SAAS,EAAE,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,OAAO,EACnD,WAAW,GAAE,eAAe,EAAO,GAClC,MAAM,EAAE,CAmBV"}