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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dmytro Latysh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,133 @@
-# Temporary Holding Version
+<p align="center">
+  <img src="./assets/branding/monolith-banner.png" alt="MONOLITH — Cognitive Infrastructure for AI" width="100%">
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<h1 align="center">MONOLITH</h1>
+
+<p align="center">
+  <strong>Cognitive Infrastructure for AI</strong><br>
+  Observable · Structured · Governed
+</p>
+
+<p align="center">
+  <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License: MIT"></a>
+  <a href="./package.json"><img src="https://img.shields.io/badge/node-%3E%3D20-339933.svg" alt="Node.js >= 20"></a>
+  <img src="https://img.shields.io/badge/status-alpha-orange.svg" alt="Status: alpha">
+  <a href="https://hub.xerj.org/contributors/Demion-L"><img src="https://hub.xerj.org/contributors/Demion-L/badge.svg" alt="XERJ Corpus Hub contributor"></a>
+</p>
+
+---
+
+MONOLITH is an open-source toolkit for observable project state, structured
+knowledge, and explicit execution governance. It gives a
+human and an AI assistant a shared, inspectable record of a project —
+structured knowledge, explicit read and write boundaries, and traceable
+decisions — instead of relying on an assistant's unaided memory.
+
+> **[MANIFESTO.md](./MANIFESTO.md)** — why this project exists and the engineering principles that govern it.
+> **[AGENTS.md](./AGENTS.md)** — current scope, source structure, and the authoritative entry point for AI assistants working in this repository.
+
+## Why MONOLITH?
+
+AI assistants lose context between sessions, and what a project "knows" ends up
+scattered across chats, notes and habits. MONOLITH keeps that knowledge in the
+project itself, in a form both a person and an assistant can read, check and
+trust — using mechanisms that are deterministic and testable.
+
+## What MONOLITH Does
+
+- **Observable** — `monolith brief` summarizes project state in the terminal, including whether it looks stale; Mission Control shows it in a local, read-only web interface.
+- **Structured** — structure is extracted from a project's own markdown (frontmatter, headings, explicit links) into an explicit relationship graph. No embeddings, no LLM, no fuzzy matching.
+- **Governed** — protocols, skills and cognitive modes describe how an assistant reads and updates project memory; missions and checkpoints record progress. This is a recorded discipline, not a runtime gate.
+- **Reproducible** — same input, same output. State lives in a schema-versioned file written with a lock and atomic replace; Durable State adds a hash-chained event log.
+- **Bounded** — managed files are read and written through strict primitives that refuse symlinks; `monolith validate` never executes project code; Mission Control has no write endpoint.
+
+## Quick Start
+
+Requires Node.js >= 20. MONOLITH is an alpha package that is **not published
+to npm**. Build it from a clone:
+
+```bash
+git clone https://github.com/Demion-L/the_monolith.git
+cd the_monolith
+pnpm install
+pnpm build
+npm link             # exposes the `monolith` command (or run: node dist/cli/index.js)
+```
+
+Once the first alpha is published, `npm install -g @latysh-development/monolith@alpha`
+becomes the primary install path ([release notes](./docs/release/alpha-installation.md)).
+
+Then, in a project directory:
+
+```bash
+monolith init        # scaffold a MONOLITH instance (refuses to overwrite existing files)
+monolith validate    # static integrity check of the instance
+monolith brief       # bounded, read-only summary of project state
+monolith ui          # Mission Control at http://127.0.0.1:4173 ; Ctrl+C to stop
+```
+
+`monolith ui` must be run inside a directory that contains a MONOLITH
+instance, and it does not open a browser — open the printed address yourself.
+All commands: [CLI reference](./docs/reference/cli.md).
+
+## Architecture
+
+```text
+Markdown artifact → Scriptorium (extraction) → ERG (relationship graph) → governed project memory
+
+MONOLITH Kernel (src/)  ──►  Project Instance (.monolith/, monolith.config.json)
+                                   │  safe, bounded reads
+                                   ▼
+                    Read model ──► loopback HTTP API ──► Mission Control UI
+```
+
+> **Kernel knows HOW. Instance knows WHAT.** The Kernel holds generic
+> mechanics and has no hardcoded knowledge of any project; an Instance — the
+> `.monolith/` directory of a project using MONOLITH, this repository
+> included — supplies the project's own knowledge. Details:
+> [`docs/architecture/`](./docs/architecture/README.md).
+
+## Ecosystem
+
+- **[Latysh Development](https://github.com/Demion-L)** — developer of MONOLITH.
+- **[Webway](https://github.com/Demion-L/webway)** — a separate, independently developed project on semantic and associative knowledge linking. It was extracted from MONOLITH and has no runtime coupling to it.
+- **SphynX** — a related application. MONOLITH does not depend on it, and this repository does not document it as a current consumer of MONOLITH.
+
+## Community & Recognition
+
+MONOLITH is listed as a contributor project on
+[XERJ Corpus Hub](https://hub.xerj.org/contributors/Demion-L). At the time of
+writing, the contributor page exists, a MONOLITH commit is selected, the corpus
+status is `candidate` and the manifest is `draft`. This is a contribution
+listing — not an official partnership, endorsement or certification.
+
+## Documentation
+
+- [CLI reference](./docs/reference/cli.md) — every command, `init`, `validate`, `brief`, `mission`, `durable`, `ui`
+- [Mission Control](./docs/reference/mission-control.md) — sections, LIVE/DEMO, skins, limitations
+- [Security & Limitations](./docs/reference/security-and-limitations.md) — threat model, platform and filesystem caveats
+- [Programmatic API](./docs/reference/write-scope-api.md) · [Development](./docs/reference/development.md)
+- [Architecture](./docs/architecture/README.md) · [ADRs](./docs/adr/README.md) · [Knowledge-base index](./docs/README.md)
+- [`AGENTS.md`](./AGENTS.md) — scope and entry point for AI assistants · [`MANIFESTO.md`](./MANIFESTO.md) — principles
+
+## Project Status
+
+**Alpha** (`0.1.0-alpha.0`). The API and CLI are experimental and may change
+without notice. Not published to npm. Durable State and the Coordinatorium
+(`monolith durable`, `monolith mission`) are experimental and are not part of
+the Quick Start.
+
+**Security:** Mission Control is read-only, listens on `127.0.0.1` only and has
+no authentication. Concurrent adversarial mutation of a project is unsupported;
+Windows is unverified. Durable State is merged but its security acceptance is
+still open. See [Security & Limitations](./docs/reference/security-and-limitations.md).
+
+**Not yet implemented:** a write-enabled UI, authentication for Mission
+Control, `monolith context <topic>`, `monolith status`, `monolith dry-run`, the
+enforcement gate engine and integrity validators (type declarations only), and
+protocol drift detection. `AGENTS.md` is the authoritative status record.
+
+## License
+
+[MIT](./LICENSE) © 2026 Dmytro Latysh

package/dist/brief/cli.d.ts

@@ -0,0 +1,30 @@
+/**
+ * `monolith brief` CLI command handler.
+ *
+ * stdout carries only the brief's own content; CLI diagnostics and the
+ * INCOMPLETE warning go to stderr (section 12). Exit codes (DEC-CONTEXT-002):
+ *   0 — brief formed (COMPLETE or INCOMPLETE)
+ *   1 — CLI usage error (thrown as a plain Error, caught by src/cli/index.ts's main())
+ *   2 — --strict and the result is INCOMPLETE
+ *
+ * `--reconcile` (SELF-AWARENESS-002) prints the State Reconciliation Report
+ * instead of the brief: what a Freshness verdict rests on and what a person
+ * should check. Same read-only contract, same exit codes (a report is formed
+ * -> 0, whatever the Freshness; usage error -> 1). It does not combine with
+ * `--strict`, whose meaning (Completeness) belongs to the brief.
+ */
+export interface BriefArgsOk {
+    ok: true;
+    maxChars: number;
+    strict: boolean;
+    /** Present (true) only when `--reconcile` was given, so existing result shapes are unchanged. */
+    reconcile?: true;
+}
+export interface BriefArgsErr {
+    ok: false;
+    message: string;
+}
+export type BriefArgsResult = BriefArgsOk | BriefArgsErr;
+export declare function parseBriefArgs(args: string[]): BriefArgsResult;
+export declare function runBrief(args: string[], targetDir?: string): Promise<void>;
+//# sourceMappingURL=cli.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/brief/cli.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;GAcG;AAMH,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,IAAI,CAAC;IACT,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;IAChB,iGAAiG;IACjG,SAAS,CAAC,EAAE,IAAI,CAAC;CAClB;AAED,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,KAAK,CAAC;IACV,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,eAAe,GAAG,WAAW,GAAG,YAAY,CAAC;AAIzD,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,eAAe,CA6C9D;AAED,wBAAsB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,SAAS,SAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CA4BvF"}

package/dist/brief/cli.js

@@ -0,0 +1,85 @@
+/* eslint-disable no-console */
+/**
+ * `monolith brief` CLI command handler.
+ *
+ * stdout carries only the brief's own content; CLI diagnostics and the
+ * INCOMPLETE warning go to stderr (section 12). Exit codes (DEC-CONTEXT-002):
+ *   0 — brief formed (COMPLETE or INCOMPLETE)
+ *   1 — CLI usage error (thrown as a plain Error, caught by src/cli/index.ts's main())
+ *   2 — --strict and the result is INCOMPLETE
+ *
+ * `--reconcile` (SELF-AWARENESS-002) prints the State Reconciliation Report
+ * instead of the brief: what a Freshness verdict rests on and what a person
+ * should check. Same read-only contract, same exit codes (a report is formed
+ * -> 0, whatever the Freshness; usage error -> 1). It does not combine with
+ * `--strict`, whose meaning (Completeness) belongs to the brief.
+ */
+import { collect } from './collect.js';
+import { render, DEFAULT_MAX_CHARS } from './render.js';
+import { reconcile, renderReconciliation } from './reconcile.js';
+const USAGE = 'Usage: monolith brief [--max-chars N] [--strict]\n       monolith brief --reconcile [--max-chars N]';
+export function parseBriefArgs(args) {
+    let maxChars = DEFAULT_MAX_CHARS;
+    let strict = false;
+    let reconcileMode = false;
+    const unknown = [];
+    let i = 0;
+    while (i < args.length) {
+        const arg = args[i];
+        if (arg === '--strict') {
+            strict = true;
+            i++;
+            continue;
+        }
+        if (arg === '--reconcile') {
+            reconcileMode = true;
+            i++;
+            continue;
+        }
+        if (arg === '--max-chars') {
+            const value = args[i + 1];
+            if (value === undefined) {
+                return { ok: false, message: `--max-chars requires a value.\n\n${USAGE}` };
+            }
+            const n = Number(value);
+            if (!Number.isInteger(n) || n <= 0) {
+                return { ok: false, message: `--max-chars must be a positive integer, got "${value}".\n\n${USAGE}` };
+            }
+            maxChars = n;
+            i += 2;
+            continue;
+        }
+        unknown.push(arg);
+        i++;
+    }
+    if (unknown.length > 0) {
+        return { ok: false, message: `Unknown argument(s) for 'monolith brief': ${unknown.join(' ')}\n\n${USAGE}` };
+    }
+    if (reconcileMode && strict) {
+        return { ok: false, message: `--strict cannot be combined with --reconcile.\n\n${USAGE}` };
+    }
+    return reconcileMode ? { ok: true, maxChars, strict, reconcile: true } : { ok: true, maxChars, strict };
+}
+export async function runBrief(args, targetDir = process.cwd()) {
+    const parsed = parseBriefArgs(args);
+    if (!parsed.ok) {
+        throw new Error(parsed.message);
+    }
+    const model = await collect(targetDir);
+    if (parsed.reconcile) {
+        if (!model.freshness || !model.freshnessEvidence) {
+            throw new Error('monolith brief --reconcile: no freshness evidence could be collected.');
+        }
+        process.stdout.write(renderReconciliation(reconcile(model.freshnessEvidence, model.freshness), parsed.maxChars).text);
+        process.exit(0);
+    }
+    const { text, completeness } = render(model, parsed.maxChars);
+    process.stdout.write(text);
+    if (completeness === 'INCOMPLETE') {
+        console.error('monolith brief: result is INCOMPLETE — see the Diagnostics section above.');
+    }
+    if (parsed.strict && completeness === 'INCOMPLETE') {
+        process.exit(2);
+    }
+    process.exit(0);
+}

package/dist/brief/collect.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `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 type { BriefModel } from './types.js';
+/** SEC-001B.1: `active.md` is a short hand-written context file (~3 KB today). */
+export declare const MAX_ACTIVE_CONTEXT_BYTES: number;
+export declare function collect(targetDir: string): Promise<BriefModel>;
+//# sourceMappingURL=collect.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"collect.d.ts","sourceRoot":"","sources":["../../src/brief/collect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAwBH,OAAO,KAAK,EACV,UAAU,EAMX,MAAM,YAAY,CAAC;AAepB,kFAAkF;AAClF,eAAO,MAAM,wBAAwB,QAAa,CAAC;AAsRnD,wBAAsB,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAkEpE"}

package/dist/brief/collect.js

@@ -0,0 +1,302 @@
+/**
+ * `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, 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';
+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 },
+    };
+}
+/**
+ * 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(', ') },
+    };
+    return {
+        identity,
+        monolithInitialized,
+        stateKeeper,
+        missions,
+        checkpoints,
+        story,
+        mandatoryProtocols,
+        adrs,
+        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"}