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

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,180 @@
-# 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?
+
+You are deep in a task when a good idea arrives — one that has nothing to do
+with what you are doing right now. Switching to it would break your focus, so
+you postpone it. A few hours later it is buried in a long chat, or simply gone.
+
+A conversation history is a poor place to keep it. It is tied to one session,
+it is hard to search, and an AI assistant that starts a new session does not
+carry it over. A thought that only lives in a chat lasts as long as the chat.
+
+MONOLITH keeps that knowledge in the project itself: ideas, structured project
+context and recorded decisions, as plain Markdown that both a person and an
+assistant can read, check and commit. You save the idea, and keep working.
+
+> **Your AI assistant may forget the conversation. Your project shouldn't forget the ideas.**
+
+Ideas are where MONOLITH started, not where it ends: the same approach — durable,
+inspectable, deterministic — also covers project state and execution governance.
+
+## What MONOLITH Does
+
+- **Idea Capture** — save a thought that is unrelated to the current task, without losing focus. You decide what to save; ideas are stored as one Markdown file each in `.monolith/memory/long-term/ideas/`, independent of the active story, and are managed with `monolith idea add|list|show` or by an assistant that follows your project's instructions.
+- **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.
+
+## Idea Capture Example
+
+```bash
+monolith idea add \
+  --title 'Automatic Tool Tests' \
+  --description 'Generate tests from business tool contracts'
+
+monolith idea list
+monolith idea show IDEA-001
+```
+
+`IDEA-001` is a demonstration ID; the real ID is printed by `idea add`, and
+`idea list` shows every saved idea.
+
+With an AI assistant, you can simply say: *"Save this idea for later."* The
+assistant then saves it by running `monolith idea add` — it does not edit idea
+files itself. This works because `monolith init` installs instructions and an
+`idea-capture` skill for the assistant; it is not guaranteed for an arbitrary
+model without that setup. Details and limits: [`monolith idea` in the CLI reference](./docs/reference/cli.md#monolith-idea).
+
+Ideas are saved and recalled **manually**. There is no automatic idea detection,
+no automatic recall or reminders, no idea status management and no idea UI yet.
+
+## Quick Start
+
+Requires Node.js >= 20. Install the published alpha package from npm:
+
+```bash
+npm install -g @latysh-development/monolith@alpha
+```
+
+To build from source instead, see the [installation and release guide](./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).
+
+## Updating an Existing Project
+
+If a project was initialised with an earlier MONOLITH version, bring it up to the current agent integration (agent entry point and Idea Capture) with:
+
+```bash
+monolith update            # preview: shows the plan, writes nothing
+monolith update --apply    # applies the safe changes
+```
+
+- The first command only prints a plan and does not modify the project.
+- The second applies the safe changes (missing MONOLITH-owned files and managed blocks).
+- Your project memory (`active.md`, `decisions.md`, roadmap, stories, ideas) and your own files are preserved.
+- A managed block you have edited is never overwritten automatically.
+- On a conflict the command writes nothing to that file and reports that manual resolution is required.
+
+Details and the full list of verdicts: [`monolith update` in the CLI reference](./docs/reference/cli.md#monolith-update).
+
+## 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`, `idea`, `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.1`). The API and CLI are experimental and may change
+without notice. Published to npm under the alpha dist-tag. 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,EAOX,MAAM,YAAY,CAAC;AAiBpB,kFAAkF;AAClF,eAAO,MAAM,wBAAwB,QAAa,CAAC;AA8TnD,wBAAsB,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAqEpE"}