@latysh-development/monolith 0.1.0-alpha.1 → 0.1.0-alpha.3

package/dist/update/cli.js

@@ -10,7 +10,7 @@ export const UPDATE_USAGE = `Usage: monolith update [--apply]
 
 Brings an existing MONOLITH instance up to the current agent integration: a
 stable entry point (<root>/AGENT.md), the idea-capture skill, its routing and the
-pointer in your AI instruction files.
+pointer in your AI instruction files, and an up-to-date finalize-story skill.
   (no flag)  Preview: shows the plan, writes nothing.
   --apply    Performs the plan: ADD creates a missing MONOLITH file, UPDATE adds
              or refreshes a managed block inside a file of yours.
@@ -24,6 +24,13 @@ What is written, and what is not:
     valid UTF-8 (no encoding is converted) or an unreadable file is CONFLICT: nothing is written there and the plan says how
     to resolve it. SKIP means left alone on purpose (e.g. your own skill).
   - Your existing skills, memory, state.json, ideas and text are never overwritten.
+    The one exception: a finalize-story skill byte-identical to a known older
+    MONOLITH template (nothing of yours in it) is replaced by the current one. Any
+    other finalize-story skill (edited, or the current text in different bytes such
+    as CRLF/BOM) is a CONFLICT: it is kept, and its compatibility with the
+    Finalization Contract is not verified, even if it mentions \`monolith finalize
+    plan\` / \`apply\` (it may still allow finalizing by hand). The integration is
+    then INCOMPLETE and --apply exits 2 until the file equals the current template.
     Nothing is executed.
 Instances carry no template version, so state is read from the files. Safe to
 re-run. Not transactional and not coordinated between simultaneous runs: apply
@@ -64,7 +71,7 @@ function verdict(plan, stale = []) {
     const manual = plan.items.filter((i) => i.action === 'CONFLICT').length;
     const broken = plan.chain.filter((c) => !c.ok).length;
     if (pending === 0 && manual === 0 && broken === 0 && stale.length === 0)
-        return 'Idea Capture integration: COMPLETE (the managed components are installed and pass the structural check; how an AI assistant behaves is not verified).';
+        return 'Agent integration: COMPLETE (the managed components are installed and pass the structural check; how an AI assistant behaves is not verified).';
     const parts = [];
     if (pending > 0)
         parts.push(`${pending} change(s) to apply`);
@@ -74,7 +81,7 @@ function verdict(plan, stale = []) {
         parts.push(`${stale.length} change(s) skipped because the file changed meanwhile`);
     if (broken > 0 && parts.length === 0)
         parts.push(`${broken} consistency check(s) failing`);
-    return `Idea Capture integration: INCOMPLETE (${parts.join(', ')}). A partly installed integration is not active.`;
+    return `Agent integration: INCOMPLETE (${parts.join(', ')}). A partly installed integration is not active.`;
 }
 export async function runUpdate(args, targetDir = process.cwd()) {
     let apply = false;

package/dist/update/index.d.ts

@@ -7,6 +7,15 @@
  * read from the files themselves):
  *  - MONOLITH-owned, created when absent: `<root>/AGENT.md`, the `idea-capture`
  *    skill. An existing skill is never overwritten, whatever it contains.
+ *  - `finalize-story` skill (DOGFOOD-002): created when absent; replaced ONLY when
+ *    it is byte-identical to a known older MONOLITH template (sha256 list in
+ *    legacy-skills.ts), so nothing of the user's is lost. Any other content is
+ *    never replaced and is a CONFLICT (DOGFOOD-005): compatibility with the
+ *    Finalization Contract is unverified, so the integration cannot be COMPLETE.
+ *    Mentioning `finalize plan` / `finalize apply` is not evidence of compliance
+ *    and does not change that; only a byte-identical current template is
+ *    UNCHANGED. Its content is only classified, never trusted as authority and
+ *    never executed.
  *  - Mixed (user-owned file + MONOLITH text): CLAUDE.md / AGENTS.md /
  *    .cursorrules / .windsurfrules, routing-map, skills index. MONOLITH text
  *    lives only in checksummed managed blocks (src/managed). A missing block is

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/update/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAKH,OAAO,EAEL,oBAAoB,EAQpB,KAAK,YAAY,EAClB,MAAM,kBAAkB,CAAC;AAK1B,MAAM,MAAM,YAAY,GAAG,KAAK,GAAG,QAAQ,GAAG,WAAW,GAAG,UAAU,GAAG,MAAM,CAAC;AAEhF,MAAM,WAAW,UAAU;IACzB,wDAAwD;IACxD,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,YAAY,CAAC;IACrB,wBAAwB;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,+CAA+C;IAC/C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4DAA4D;IAC5D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oFAAoF;IACpF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iDAAiD;IACjD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,wEAAwE;AACxE,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,UAAU;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,KAAK,EAAE,UAAU,EAAE,CAAC;CACrB;AA+ED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,CAgGrD;AAiCD;;;iKAGiK;AACjK,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAE7D;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,qGAAqG;IACrG,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,QAAQ,EAAE,YAAY,EAAE,CAAC;CAC1B;AAUD;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,WAAW,CAsCvE;AAED,OAAO,EAAE,oBAAoB,EAAE,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/update/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAKH,OAAO,EAEL,oBAAoB,EAQpB,KAAK,YAAY,EAClB,MAAM,kBAAkB,CAAC;AAM1B,MAAM,MAAM,YAAY,GAAG,KAAK,GAAG,QAAQ,GAAG,WAAW,GAAG,UAAU,GAAG,MAAM,CAAC;AAEhF,MAAM,WAAW,UAAU;IACzB,wDAAwD;IACxD,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,YAAY,CAAC;IACrB,wBAAwB;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,+CAA+C;IAC/C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4DAA4D;IAC5D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oFAAoF;IACpF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iDAAiD;IACjD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,wEAAwE;AACxE,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,UAAU;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,KAAK,EAAE,UAAU,EAAE,CAAC;CACrB;AAkHD;;;GAGG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,CAkGrD;AAwCD;;;iKAGiK;AACjK,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAE7D;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,qGAAqG;IACrG,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,QAAQ,EAAE,YAAY,EAAE,CAAC;CAC1B;AAUD;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,WAAW,CAsCvE;AAED,OAAO,EAAE,oBAAoB,EAAE,CAAC"}

package/dist/update/index.js

@@ -7,6 +7,15 @@
  * read from the files themselves):
  *  - MONOLITH-owned, created when absent: `<root>/AGENT.md`, the `idea-capture`
  *    skill. An existing skill is never overwritten, whatever it contains.
+ *  - `finalize-story` skill (DOGFOOD-002): created when absent; replaced ONLY when
+ *    it is byte-identical to a known older MONOLITH template (sha256 list in
+ *    legacy-skills.ts), so nothing of the user's is lost. Any other content is
+ *    never replaced and is a CONFLICT (DOGFOOD-005): compatibility with the
+ *    Finalization Contract is unverified, so the integration cannot be COMPLETE.
+ *    Mentioning `finalize plan` / `finalize apply` is not evidence of compliance
+ *    and does not change that; only a byte-identical current template is
+ *    UNCHANGED. Its content is only classified, never trusted as authority and
+ *    never executed.
  *  - Mixed (user-owned file + MONOLITH text): CLAUDE.md / AGENTS.md /
  *    .cursorrules / .windsurfrules, routing-map, skills index. MONOLITH text
  *    lives only in checksummed managed blocks (src/managed). A missing block is
@@ -28,6 +37,7 @@ import { dirname, join, basename, resolve } from 'path';
 import { SafeWriteError, RootContainmentError, createFile, openParent, projectBoundary, readConfigFile, readProjectFile, replaceFile, resolveMonolithRoot, } from '../root/index.js';
 import { TEMPLATES_ROOT, substitute } from '../init/scaffold.js';
 import { listIdeas, ideaStore } from '../ideas/store.js';
+import { FINALIZE_STORY_LEGACY } from './legacy-skills.js';
 import { blockBody, inspectBlock, planAppend, planRefresh, prose, renderBlock } from '../managed/index.js';
 const INSTRUCTION_FILES = ['CLAUDE.md', '.cursorrules', '.windsurfrules'];
 const AI_TOOL_FILE = { claude: 'CLAUDE.md', cursor: '.cursorrules', windsurf: '.windsurfrules' };
@@ -93,6 +103,42 @@ function blockItem(projectRoot, root, spec) {
         }
     }
 }
+const FINALIZE_SKILL_TEMPLATE = 'monolith/skills/finalize-story/SKILL.md';
+/**
+ * The `finalize-story` skill against the current template (DOGFOOD-002). A known older template
+ * is recognised by exact hash, not by searching text, so a user's file is never "recognised" by
+ * a phrase it happens to contain.
+ */
+function finalizeSkillItem(projectRoot, r, vars) {
+    const rel = `${r}/skills/finalize-story/SKILL.md`;
+    const template = readTemplate(FINALIZE_SKILL_TEMPLATE, vars);
+    const effect = 'the finalize-story skill requires the deterministic plan → approval → apply flow and forbids manual finalization';
+    const read = readInstanceFile(projectRoot, rel, true);
+    if (read.kind === 'unsafe')
+        return { path: rel, action: 'CONFLICT', reason: `cannot be read safely (${read.detail}); not inspected or changed` };
+    if (read.kind === 'missing')
+        return { path: rel, action: 'ADD', reason: 'new file from the current template', content: template, effect };
+    const text = read.content;
+    if (text === template)
+        return { path: rel, action: 'UNCHANGED', reason: 'identical to the current template' };
+    const known = FINALIZE_STORY_LEGACY[sha(text)];
+    if (known !== undefined) {
+        return { path: rel, action: 'UPDATE', reason: `unedited older MONOLITH template (${known}); replace with the current one`, content: template, before: sha(text), effect };
+    }
+    // Anything else is unverified. Mentioning `finalize plan` / `apply` proves nothing about the rest of the file
+    // (it may still allow manual finalization), so there is no heuristic that upgrades trust (DOGFOOD-005).
+    // The byte-variant hint below only improves the message; it never changes the verdict or writes.
+    const bytesOnly = text.replace(/^/, '').replace(/\r\n/g, '\n').replace(/\n+$/, '') === template.replace(/\n+$/, '');
+    const why = bytesOnly
+        ? 'has the current template text but different bytes (line endings, BOM or trailing newline)'
+        : 'differs from the current template and from every known MONOLITH template';
+    return {
+        path: rel,
+        action: 'CONFLICT',
+        reason: `${why}: compatibility with the Finalization Contract is not verified (it may still tell an assistant to finalize by hand). Your file is not changed`,
+        proposal: `Compare your file with the current template (templates/default-instance/${FINALIZE_SKILL_TEMPLATE} in the monolith package) and merge its "Deterministic Execution" section, or rename ${rel} and re-run \`monolith update --apply\` to get the current skill. Until the file equals the current template, the integration is reported INCOMPLETE.\n`,
+    };
+}
 /**
  * Read-only. Throws RootContainmentError when the root/config is unusable and
  * `Error` when the directory is not a MONOLITH instance.
@@ -135,6 +181,7 @@ export function planUpdate(target) {
         skillText = skill.content;
         items.push({ path: skillRel, action: 'SKIP', reason: 'exists and differs from the current template (customized or older); not overwritten' });
     }
+    items.push(finalizeSkillItem(pr, r, vars));
     items.push(blockItem(pr, r, {
         id: 'agent',
         rel: `${r}/AGENT.md`,
@@ -206,6 +253,8 @@ function chainChecks(projectRoot, r, items, skillText) {
     const skillPresent = skillItem?.action === 'UNCHANGED' || skillItem?.action === 'SKIP';
     add('skill', skillPresent, 'the idea-capture skill exists', 'the idea-capture skill is missing or unreadable');
     add('skill → CLI', skillPresent && skillText !== null && /monolith idea add/.test(prose(skillText)), 'the skill calls `monolith idea add`', 'the skill does not call `monolith idea add` (a customized skill may have dropped it)');
+    const finItem = state(`${r}/skills/finalize-story/SKILL.md`);
+    add('finalize skill → CLI', finItem?.action === 'UNCHANGED', 'the finalize-story skill is identical to the current template', 'the finalize-story skill is missing, outdated, unreadable, or not verified to match the current template (a customized one is never assumed compatible)');
     let storage = '';
     try {
         listIdeas(ideaStore(projectRoot));
@@ -225,7 +274,7 @@ export function integrationComplete(plan) {
 }
 /** Apply order: MONOLITH-owned files first, the pointer in the root instruction files last. */
 function rank(item, r) {
-    if (item.path.startsWith(`${r}/skills/idea-capture/`))
+    if (item.path.startsWith(`${r}/skills/idea-capture/`) || item.path.startsWith(`${r}/skills/finalize-story/`))
         return 0;
     if (item.path === `${r}/AGENT.md`)
         return 1;

package/dist/update/legacy-skills.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Known historic bytes of MONOLITH-owned skills (DOGFOOD-002). An installed skill
+ * whose sha256 is listed here is an unedited copy of an older template, so
+ * replacing it loses nothing. Anything else is the user's text and is never
+ * replaced. Hashes are over the file as `init` wrote it (the skill has no
+ * `{{VARS}}`, so nothing was substituted).
+ */
+export declare const FINALIZE_STORY_LEGACY: Readonly<Record<string, string>>;
+/**
+ * sha256 of the CURRENT `finalize-story` template. A test pins it: editing the template fails
+ * that test until the previous hash is moved into FINALIZE_STORY_LEGACY (so instances that
+ * carry the unedited previous text keep updating) and this value is replaced.
+ */
+export declare const FINALIZE_STORY_CURRENT = "9a779ee52327b5dfe64917228eb4dda60bf4901e2ac0cd116339eb70d51d2723";
+//# sourceMappingURL=legacy-skills.d.ts.map

package/dist/update/legacy-skills.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"legacy-skills.d.ts","sourceRoot":"","sources":["../../src/update/legacy-skills.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAMlE,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,qEAAqE,CAAC"}

package/dist/update/legacy-skills.js

@@ -0,0 +1,20 @@
+/**
+ * Known historic bytes of MONOLITH-owned skills (DOGFOOD-002). An installed skill
+ * whose sha256 is listed here is an unedited copy of an older template, so
+ * replacing it loses nothing. Anything else is the user's text and is never
+ * replaced. Hashes are over the file as `init` wrote it (the skill has no
+ * `{{VARS}}`, so nothing was substituted).
+ */
+export const FINALIZE_STORY_LEGACY = {
+    '7a42dbaad1b0908bad820903e2e22b6e06e06f0ddc44d61d003e3cd5ad36f2c6': 'initial template (manual steps only)',
+    '8d7011640de68df5e4aad3f1ff5ecf421d1f7a3b454f3c51f12079cfea743b8a': '0.1.0-alpha.0 / alpha.1; manual steps only, no `monolith finalize`',
+    '6c41ea1411d1ff75f0db92a80289662e0725a248f243d3065cda0d0452bae194': 'pre-release development template (DOCSYNC-001)',
+    '1b8ee0c357de7edb858e211d8a6ae8af1ae0a77a9289259deac25bbcfb138121': 'pre-release development template (DOCSYNC-003)',
+    '31cc69d09ba4996f71b497f1f4454912ab497c1bcd766f4b7b337c34384efd2d': '0.1.0-alpha.2; does not forbid manual finalization',
+};
+/**
+ * sha256 of the CURRENT `finalize-story` template. A test pins it: editing the template fails
+ * that test until the previous hash is moved into FINALIZE_STORY_LEGACY (so instances that
+ * carry the unedited previous text keep updating) and this value is replaced.
+ */
+export const FINALIZE_STORY_CURRENT = '9a779ee52327b5dfe64917228eb4dda60bf4901e2ac0cd116339eb70d51d2723';

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-export declare const MONOLITH_VERSION = "0.1.0-alpha.1";
+export declare const MONOLITH_VERSION = "0.1.0-alpha.3";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -1 +1 @@
-export const MONOLITH_VERSION = '0.1.0-alpha.1';
+export const MONOLITH_VERSION = '0.1.0-alpha.3';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@latysh-development/monolith",
-  "version": "0.1.0-alpha.1",
+  "version": "0.1.0-alpha.3",
   "description": "MONOLITH: Cognitive Infrastructure for AI. An open-source toolkit for observable project state, structured knowledge, and explicit execution governance.",
   "author": "Dmytro Latysh",
   "license": "MIT",

package/templates/default-instance/monolith/context/MONOLITH-CHAT-CONTEXT.md

@@ -0,0 +1,183 @@
+# MONOLITH — Context for Your AI Working Chat
+
+> Paste this document into the AI assistant you use to plan, review and coordinate
+> development (a ChatGPT Project, a Claude Project or conversation, or a similar
+> workspace). It describes the MONOLITH infrastructure installed in this project.
+> It does not describe the project itself: for that, ask the developer for the
+> output of `monolith brief`.
+
+---
+
+## 1. What Is MONOLITH?
+
+MONOLITH is **Cognitive Infrastructure for AI**: a local, file-based toolkit that
+gives AI-assisted development an observable project state, structured knowledge
+and explicit execution rules. Everything lives in the repository as Markdown and
+JSON (by default under `{{MONOLITH_ROOT}}/`) and is read and written by the
+`monolith` CLI. It uses no LLM and makes no external network calls.
+
+Division of responsibility:
+
+| Party | Responsibility |
+|---|---|
+| **MONOLITH** | Stores project memory, protocols and skills; reports project state deterministically; applies controlled changes (finalization, idea capture) only after checks. |
+| **AI agent / assistant** | Reads the context, proposes and performs work, follows the protocols, reports what it did and what it verified. |
+| **Developer (owner)** | Decides scope, approves changes, runs or reviews verification, and is the only authority on what is "done". |
+
+---
+
+## 2. Core Capabilities
+
+All commands run in the project root (the directory where `monolith init` was run;
+it contains `monolith.config.json`). `monolith --help` is the authoritative usage text.
+
+| Command | What it does |
+|---|---|
+| `monolith init` | Scaffolds a MONOLITH instance in the current directory. Refuses to run if any file it would write already exists; never overwrites. |
+| `monolith validate` | Static, read-only integrity check of the instance (config, required directories, unreplaced template placeholders). Exit `0` = PASS, `1` = FAIL. Never executes project code. |
+| `monolith brief` | Deterministic, bounded, read-only summary of project state: current story, active missions and checkpoints, mandatory protocols, accepted ADRs, parked ideas. Prints `Completeness` and `Freshness`. Options: `--max-chars N`, `--strict`. |
+| `monolith brief --reconcile` | Read-only report of the evidence behind the `Freshness` verdict: contradictions between state documents, work items referenced in git but not recorded, and what a person should check. Modifies nothing. |
+| `monolith finalize plan --proposal <file>` | Read-only. Checks a JSON finalization proposal against preconditions (`PASS` / `FAIL` / `NOT_VERIFIED`), lists every write target and prints a digest of the exact plan. |
+| `monolith finalize apply --proposal <file> --approve <digest>` | Applies a finalization only if the plan still matches the digest the owner approved. Writes story records in a fixed order; nothing is written if the plan changed. |
+| `monolith mission start\|list\|show\|finish\|checkpoint\|checkpoints` | Records missions and checkpoints in `{{MONOLITH_ROOT}}/state.json`. Experimental; a recommended discipline, not an enforced gate. |
+| `monolith idea add\|list\|show` | Captures a deferred idea without changing the current task, and recalls it later. One Markdown file per idea; ids are not reused (reservations are kept in `ideas/.ids/`). |
+| `monolith update` | For instances created by an older release: previews (and with `--apply` installs) the current agent entry point, the Idea Capture integration and the current `finalize-story` skill. Never overwrites user edits; conflicts are reported, not resolved. Does not add other new template files. |
+| `monolith ui` | Mission Control: a read-only web dashboard on `127.0.0.1` (default port 4173). Does not open a browser. |
+
+`monolith status` and `monolith dry-run` exist as names but are **not implemented**.
+
+---
+
+## 3. Project Memory
+
+Key files (paths relative to the project root):
+
+| File | Role |
+|---|---|
+| `{{MONOLITH_ROOT}}/memory/working/active.md` | The current phase and story. "No active story recorded" means nothing is registered, **not** that the project is complete. |
+| `{{MONOLITH_ROOT}}/memory/working/story-index.md` | Index of finalized stories. |
+| `{{MONOLITH_ROOT}}/context/maps/project-map.md` | Where each kind of knowledge lives in this instance. |
+| `{{MONOLITH_ROOT}}/context/maps/roadmap-index.md` | Phases, stories and their status. |
+| `{{MONOLITH_ROOT}}/context/maps/routing-map.md` | Classifies a request into a task type, and (Table 8) maps each kind of long-term knowledge to its one canonical destination. |
+| `{{MONOLITH_ROOT}}/memory/long-term/` | Decisions, tech debt, architecture principles, execution history. |
+| `{{MONOLITH_ROOT}}/memory/long-term/ideas/` | The Idea Store. Managed only through `monolith idea`; assistants never edit these files. |
+| `{{MONOLITH_ROOT}}/skills/` | Step-by-step procedures (finalize story, current status, idea capture, …) indexed in `skills/INDEX.md`. |
+| `{{MONOLITH_ROOT}}/protocols/` | Rules for boot, cognition modes, governance and execution. |
+| `AGENTS.md` and the AI-tool instruction file (e.g. `CLAUDE.md`) | Instructions for coding agents working inside the repository. |
+
+Rule of thumb: knowledge has **one canonical place**. Do not suggest creating new
+directories, registries or templates for something that already has a destination.
+
+---
+
+## 4. Recommended Development Workflow
+
+1. **Restore context.** The developer runs `monolith brief` (and, if `Freshness`
+   is not `FRESH`, `monolith brief --reconcile`) and shares the output. Treat it
+   as the starting point, not as a complete picture.
+2. **Plan the task.** Agree on the goal, scope, out-of-scope items and acceptance
+   criteria before implementation starts.
+3. **Implement.** The coding agent works in the repository, following `AGENTS.md`,
+   the routing map and the relevant skill. Prefer an isolated branch.
+4. **Test.** Run the project's own typecheck, build and tests. MONOLITH does not
+   run them for you.
+5. **Review.** Review the diff and the test output, not the agent's summary of them.
+6. **Update project state.** Keep `active.md`, `roadmap-index.md` and related
+   documents in line with what actually happened; use `monolith brief` to spot drift.
+7. **Controlled finalization.** Close a story only with
+   `monolith finalize plan` → owner reviews the plan and digest →
+   `monolith finalize apply --proposal <file> --approve <digest>`. Never finalize by editing the
+   Markdown by hand.
+
+Ideas that come up along the way are saved with `monolith idea add` and the
+current task continues unchanged.
+
+---
+
+## 5. Working With AI Assistants
+
+**In ChatGPT:** put this document into the Project instructions (or the first
+message of a conversation). Share `monolith brief` output, diffs and test
+results as the work progresses. The chat cannot see the repository; it only
+knows what you paste.
+
+**In Claude:** add this document to a Claude Project's knowledge or paste it at
+the start of a conversation. The same rule applies: it sees only what you share.
+
+**Working chat vs. coding agent:**
+
+| | Working chat (this context) | Coding agent (Claude Code, Codex, Cursor, …) |
+|---|---|---|
+| Sees | Only what you paste | The repository itself |
+| Instructions | This document | `AGENTS.md`, `CLAUDE.md`, `{{MONOLITH_ROOT}}/AGENT.md`, skills, protocols |
+| Role | Architect, consultant, reviewer: plans, questions, reviews, drafts task specifications | Executes: edits files, runs commands and tests |
+| Can change the project | No | Yes, within the scope it is given |
+
+A good pattern: the working chat writes a precise task for the coding agent; the
+agent executes it; the developer brings the agent's report and real command output
+back to the chat for review.
+
+---
+
+## 6. Important Guarantees and Limitations
+
+**What the runtime guarantees**
+
+- `brief`, `brief --reconcile`, `validate`, `finalize plan`, `idea list|show`,
+  `ui` and `update` (without `--apply`) are read-only.
+- Diagnostics are deterministic: the same files and git history produce the same
+  output. No LLM and no external network calls (`monolith ui` listens only on
+  `127.0.0.1`).
+- User data is protected: `init` never overwrites an existing file;
+  `idea add` never overwrites an idea; `update --apply` never changes text you
+  edited: it creates missing MONOLITH-owned files, refreshes unedited
+  MONOLITH-managed sections and replaces only an unmodified older
+  `finalize-story` skill; `finalize apply` writes only
+  the exact plan the owner approved by digest. It is not atomic: an interrupted
+  run (exit `3`, `INCOMPLETE`) leaves the story not finalized and is completed by
+  running `plan` and `apply` again; there is no rollback. Symlinked paths are refused.
+
+**What remains a recommendation**
+
+- Protocols, skills, cognitive modes and missions are instructions for the AI and
+  the developer. Nothing technically stops an assistant from ignoring them or from
+  editing Markdown directly.
+- Integrity and governance results used by `finalize` are reports written by the
+  assistant. MONOLITH does not run the build or tests; a digest proves the plan did
+  not change, not who approved it.
+
+**`validate PASS` does not mean the application is correct.** It checks only the
+structure of the MONOLITH instance (configuration, directories, placeholders). It
+does not compile, test, run or analyze your code, and it does not check skill
+content or project state.
+
+**`Freshness: UNKNOWN` is not `STALE`.**
+
+- `STALE` requires a concrete, named discrepancy: state documents contradict each
+  other, or git history references work items no state document mentions.
+- `FRESH` requires positive evidence that nothing changed after the last state update.
+- `UNKNOWN` means there is not enough evidence either way (no git, state never
+  committed, commits that name no work item). It is "unverified", not "outdated".
+
+`Completeness` is separate: it says whether the brief itself lost information
+while being rendered.
+
+---
+
+## 7. Working Agreement
+
+When assisting with a project that uses MONOLITH:
+
+1. **Do not invent project state.** If you have not been shown `brief` output,
+   a file or a command result, say that you do not know.
+2. **An AI's claim is not evidence.** "Tests pass" or "done" from any assistant
+   (including you) counts only with the actual command output or diff.
+3. **No dangerous Git operations without explicit permission:** no force push,
+   reset, rebase of shared branches, branch or worktree deletion, tag, publish or
+   merge into the main branch unless the developer asks for it.
+4. **Do not declare work complete without verification:** typecheck, build, tests
+   and review, then controlled finalization.
+5. **Do not expand scope on your own.** Propose additional work separately (or as
+   an idea via `monolith idea add`); do not fold it into the current task.
+6. **Respect the project's existing instructions.** `AGENTS.md`, the AI-tool
+   instruction file, protocols and skills take precedence over general advice.

package/templates/default-instance/monolith/memory/working/active.md

@@ -15,6 +15,17 @@ referenced_by:
 
 # Active Working Memory
 
+<!--
+Starting a story: replace "No active story." in the "Current Story" section below with
+a field line at the very start of a line (no indent, list marker or quote), e.g.
+    **Story:** <story-id> — <title>
+The first word after "**Story:**" is the story id: letters, digits, "." "_" "-",
+starting with a letter or digit, matched exactly (case-sensitive). `monolith finalize`
+identifies the active story ONLY by this one line. Ids in descriptions, headings,
+code fences or comments do not count; zero or several "**Story:**" lines mean it
+refuses to finalize. Keep the field above any "---" line or heading in that section.
+-->
+
 ## Active Phase
 
 No active phase.

package/templates/default-instance/monolith/skills/finalize-story/SKILL.md

@@ -22,15 +22,81 @@ Triggered by: "finalize story", "complete story", "mark story done"
 
 ## Pre-conditions
 
-- [ ] Active story exists in `memory/working/active.md`
+- [ ] Active story exists in `memory/working/active.md`, identified by exactly one `**Story:** <id>` line in `## Current Story`
 - [ ] All story tasks are complete
 - [ ] No blocking issues open
 
 ---
 
+## Deterministic Execution (`monolith finalize`)
+
+Finalization is deterministic and goes through the CLI, in this order:
+
+```text
+Proposal -> monolith finalize plan -> READY + digest -> Owner Approval
+         -> monolith finalize apply -> Verification
+```
+
+**Do not finalize by hand.** Never edit `active.md`, `story-index.md`,
+`execution-history.md`, a story capsule or any other finalization target yourself
+in order to "finalize" a story, and never skip `plan`, the owner's approval or
+`apply`. If `monolith finalize` is unavailable, fails or reports `NOT_READY` /
+`REFUSED` / `INCOMPLETE`, stop, report the output and ask the owner; do not fall
+back to the manual Steps below. This is an instruction to you, not a technical
+barrier: the CLI cannot stop an assistant from editing Markdown directly, so
+following it is your responsibility.
+
+Steps 2-6 below only describe what `monolith finalize apply` writes; they are not a
+manual procedure. Step 1 (the integrity and governance results, item 1 below) stays yours.
+
+0. **Structural story identity (required before `plan`).** `monolith finalize` knows
+   which story is active only from one field line in the `## Current Story` section of
+   `memory/working/active.md`, at the very start of the line (no indent, list marker or quote):
+
+   ```markdown
+   ## Current Story
+
+   **Story:** S-1 — Example story
+   ```
+
+   The first word after `**Story:**` is the story id and must equal `proposal.story.id`
+   exactly (case-sensitive; letters, digits, `.` `_` `-`, starting with a letter or digit).
+   Text after the id is free. Never infer the id from a heading, a description, "Working on X",
+   a `Previous:` line, a code fence or a comment: those carry no identity, and zero, duplicate
+   or conflicting `**Story:**` lines make `plan` report `NOT_READY` (`expected-state` FAIL) and
+   `apply` `REFUSED`. Keep the field above any `---` line or heading in that section.
+   If `active.md` predates this field (e.g. `Working on STORY-123`), do not guess and do not
+   rewrite it silently: tell the owner the one line that is missing, add it only with their
+   consent, then run `plan` again. `expectedCurrentStory` is `{"contains": "<text naming the
+   story id>"}` for an active story and `"none"` only when `## Current Story` says "No active
+   story."; neither replaces the `**Story:**` field. Do not bypass this by hand-editing the memory
+   files or the integrity/governance results to make a check pass.
+1. Complete Step 1 and write `memory/working/integrity-result.md` and
+   `memory/working/governance-result.md` for THIS story. Each file needs exactly one
+   `**Status:** PASS` (or `FAIL`), exactly one `**Story:** <id> ...` whose first word is
+   the story id, and exactly one `**Date:** YYYY-MM-DD` (not after the finalization date,
+   at most 7 days before it). Repeated, contradictory or malformed fields, another story,
+   or a stale date are never PASS. It is your own report, not an independent check.
+2. Write a finalization proposal (JSON, schema version 1: story, expectedCurrentStory,
+   work, summary, keyOutputs, history, optional handoff / docUpdates). Content is
+   yours; targets and paths are MONOLITH's. `expectedCurrentStory` is `"none"` or
+   `{"contains": "<text naming the story id>"}`; `"any"` does not exist. A story id is
+   finalized once: a second proposal for the same id with other wording is a conflict.
+3. `monolith finalize plan --proposal <file>` — read-only. Shows every precondition as
+   PASS / FAIL / NOT_VERIFIED, every target, and a digest. Show it to the owner.
+4. Only after the owner approves: `monolith finalize apply --proposal <file> --approve <digest>`.
+   Never run `apply` on your own authority and never declare the story finalized
+   unless it printed `FINALIZED` or `ALREADY_FINALIZED`. `INCOMPLETE` or `REFUSED`
+   means it is NOT finalized: report the output, then re-plan.
+
+Documents to keep in sync beyond the memory files go in `docUpdates`; they are written only
+if `monolith.config.json` lists them in `finalization.requiredDocs` / `allowedDocs`.
+
+---
+
 ## Steps
 
-### Step 1 — Verify integrity
+### Step 1 — Verify integrity (yours)
 
 Run integrity verification. All checks must pass before proceeding.
 

package/dist/ui/assets/index-DMZ7ZvZY.css

@@ -1 +0,0 @@
-.skin-switcher[data-v-76c1c45c]{color:var(--muted);font-size:13px;display:flex;gap:6px;align-items:center}.skin-switcher select[data-v-76c1c45c]{background:var(--surface-2);color:var(--text);border:1px solid var(--control-border);border-radius:4px;padding:2px 6px}:root{--bg: #0e1116;--surface: #161b22;--surface-2: #1d242d;--border: #2b3440;--control-border: #627185;--text: #e6edf3;--muted: #8b98a8;--accent: #58a6ff;--ok: #3fb950;--warn: #d29922;--err: #f85149;--demo: #f0b429;color-scheme:dark}*{box-sizing:border-box}body{margin:0;background:var(--bg);color:var(--text);font:15px/1.5 system-ui,-apple-system,Segoe UI,Roboto,sans-serif}code,pre{font-family:ui-monospace,SF Mono,Menlo,Consolas,monospace;font-size:.9em}.shell{display:flex;align-items:flex-start;min-height:100vh}.shell-main{flex:1 1 auto;min-width:0}.sidebar{position:sticky;top:0;align-self:flex-start;flex:0 0 240px;width:240px;height:100vh;display:flex;flex-direction:column;background:var(--surface);border-right:1px solid var(--border)}.sidebar-head{padding:14px 16px}.sidebar-panel{flex:1 1 auto;min-height:0;display:flex;flex-direction:column;justify-content:space-between;gap:16px;padding:4px 12px 16px;overflow-y:auto}.sidebar-panel .skin-switcher{margin-top:auto;padding:12px 4px 0;border-top:1px solid var(--border)}.nav-toggle{display:none}.topbar{display:flex;flex-wrap:wrap;align-items:center;gap:12px 24px;padding:10px 20px;min-height:52px;background:var(--surface);border-bottom:1px solid var(--border)}.brand{display:flex;flex-wrap:wrap;gap:0 10px;align-items:baseline}.brand .muted{white-space:nowrap}.brand strong{letter-spacing:.12em}.project{font-weight:600}.topbar-right{margin-left:auto;display:flex;align-items:center;gap:14px}.scenario{color:var(--muted);font-size:13px;display:flex;gap:6px;align-items:center}.scenario select{background:var(--surface-2);color:var(--text);border:1px solid var(--control-border);border-radius:4px;padding:2px 6px}.demo-badge{background:var(--demo);color:#1a1300;font-weight:800;letter-spacing:.1em;padding:4px 12px;border-radius:4px}.nav{display:flex;flex-direction:column;gap:2px}.nav a{color:var(--muted);text-decoration:none;overflow-wrap:anywhere;padding:6px 10px;border-radius:4px}.nav a:hover{color:var(--text);background:var(--surface-2)}.nav a[aria-current=location]{color:var(--text);background:var(--surface-2);font-weight:600;box-shadow:inset 3px 0 0 var(--accent)}.nav a:focus-visible,button:focus-visible,select:focus-visible{outline:2px solid var(--accent);outline-offset:2px}.content{max-width:1100px;margin:0 auto;padding:20px;display:grid;grid-template-columns:minmax(0,1fr);gap:16px}.panel{min-width:0;overflow-wrap:anywhere;background:var(--surface);border:1px solid var(--border);border-radius:6px;padding:16px 20px;scroll-margin-top:16px}.panel h2{margin:0 0 12px;font-size:16px;text-transform:uppercase;letter-spacing:.06em;color:var(--accent)}.panel h3{margin:16px 0 6px;font-size:14px}.panel h4{margin:10px 0 4px;font-size:13px;color:var(--muted)}.facts{display:grid;grid-template-columns:max-content minmax(0,1fr);gap:4px 16px;margin:0}.facts dt{color:var(--muted)}.facts dt,.facts dd{min-width:0}.facts dd{margin:0;overflow-wrap:anywhere}.facts.compact{font-size:13px;margin-top:8px}.cards{list-style:none;margin:0;padding:0;display:grid;grid-template-columns:minmax(0,1fr);gap:10px}.card{min-width:0;overflow-wrap:anywhere;background:var(--surface-2);border:1px solid var(--border);border-radius:4px;padding:10px 14px}.card h3{margin:6px 0 2px;font-size:15px}.card p{margin:4px 0}.card-head{display:flex;justify-content:space-between;gap:12px;flex-wrap:wrap}.status{font-size:12px;padding:1px 8px;border-radius:10px;border:1px solid var(--ok);color:var(--ok)}.steps ul{margin:0;padding-left:20px}.tag{font-weight:400;font-size:11px;color:var(--warn);border:1px solid var(--warn);border-radius:3px;padding:0 6px;margin-left:6px}.roadmap{margin:0;padding:12px;background:var(--surface-2);border-radius:4px;white-space:pre-wrap;overflow-wrap:anywhere}.diag li{min-width:0}.diag{list-style:none;margin:0;padding:0;display:grid;gap:4px}.sev{font-size:11px;text-transform:uppercase;font-weight:700;margin-right:6px}.sev-info .sev{color:var(--accent)}.sev-warning .sev{color:var(--warn)}.sev-error .sev{color:var(--err)}.muted{color:var(--muted)}.empty{color:var(--muted);font-style:italic;margin:0}.unknown{color:var(--warn);font-weight:600;font-style:normal;letter-spacing:.04em}@media(max-width:899px){.shell{display:block}.sidebar{position:sticky;top:0;z-index:2;width:auto;height:auto;max-height:100vh;border-right:0;border-bottom:1px solid var(--border)}.sidebar-head{display:flex;align-items:center;justify-content:space-between;gap:12px;padding:8px 12px}.sidebar-panel{display:none;padding-top:4px;max-height:calc(100vh - 56px)}.sidebar.open .sidebar-panel{display:flex}.nav-toggle{display:inline-block}.panel{scroll-margin-top:64px}}@media(max-width:600px){.topbar{padding-left:12px;padding-right:12px}.topbar-right{margin-left:0;width:100%;flex-wrap:wrap;justify-content:space-between}.content{padding:12px}.facts{grid-template-columns:1fr}.facts dd{margin-bottom:6px}}.live-badge{background:#1f6f43;color:#eafff3;font-weight:800;letter-spacing:.1em;padding:4px 12px;border-radius:4px}.live-badge-off{background:var(--surface-2);color:var(--muted, #9aa4b2);border:1px solid var(--border)}.story{white-space:pre-wrap;margin:0;font:inherit}button{background:var(--surface-2);color:var(--text);border:1px solid var(--control-border);border-radius:4px;padding:4px 12px;font:inherit;cursor:pointer}button:disabled{opacity:.5;cursor:default}.section-fade-enter-active{transition:opacity .22s ease-out,transform .22s ease-out}.section-fade-leave-active{transition:opacity .15s ease-in,transform .15s ease-in}.section-fade-enter-from{opacity:0;transform:translateY(8px)}.section-fade-leave-to{opacity:0;transform:translateY(-8px)}@media(prefers-reduced-motion:reduce){.section-fade-enter-active,.section-fade-leave-active{transition:none}.section-fade-enter-from,.section-fade-leave-to{opacity:1;transform:none}}:root[data-skin=cosmic-glass]{--bg: #080a1e;--surface: rgba(12, 16, 40, .74);--surface-2: rgba(30, 34, 76, .62);--border: rgba(190, 200, 255, .2);--control-border: rgba(204, 212, 255, .52);--text: #f1f4ff;--muted: #b8c3df;--accent: #b4a9ff;--ok: #5fd68a;--warn: #f0c040;--err: #ff8a85;--demo: #f0b429;--glass-dense: rgba(9, 12, 32, .86);--glass-edge: inset 0 1px 0 rgba(255, 255, 255, .07);--glass-shadow: 0 8px 32px rgba(2, 3, 14, .45);--glass-blur: blur(14px) saturate(1.15);background:var(--bg)}:root[data-skin=cosmic-glass] body{background:transparent;isolation:isolate}:root[data-skin=cosmic-glass] body:before{content:"";position:fixed;top:0;bottom:0;right:0;left:-14vw;z-index:-1;pointer-events:none;background:linear-gradient(180deg,#080a1e00,#080a1e33 60%,#080a1e99),url(./cosmic-glass-bg-Dwx47zPu.webp) 24% 0 / cover no-repeat,var(--bg)}:root[data-skin=cosmic-glass] .sidebar{background:#080b2080;-webkit-backdrop-filter:blur(4px) saturate(1.1);backdrop-filter:blur(4px) saturate(1.1);border-right-color:var(--border);box-shadow:1px 0 #968cff14,6px 0 28px #02030e59}:root[data-skin=cosmic-glass] .brand strong{color:var(--text);letter-spacing:.16em}:root[data-skin=cosmic-glass] .brand .muted{font-size:13px}:root[data-skin=cosmic-glass] .nav a{color:var(--muted);border-left:2px solid transparent;border-radius:0 6px 6px 0}:root[data-skin=cosmic-glass] .nav a:hover{color:var(--text);background:#968cff29;border-left-color:var(--accent)}:root[data-skin=cosmic-glass] .nav a[aria-current=location]{color:var(--text);background:linear-gradient(90deg,#968cff42,#968cff14);border-left-color:#d3ccff;box-shadow:none}:root[data-skin=cosmic-glass] .sidebar-panel .skin-switcher{border-top-color:var(--border)}:root[data-skin=cosmic-glass] .topbar{background:#080b20a8;-webkit-backdrop-filter:blur(12px) saturate(1.1);backdrop-filter:blur(12px) saturate(1.1);border-bottom-color:var(--border);box-shadow:0 6px 24px #02030e4d}:root[data-skin=cosmic-glass] .project{font-size:16px;letter-spacing:.01em}:root[data-skin=cosmic-glass] .live-badge{background:#14532f;color:#eafff3;border:1px solid #5fd68a}:root[data-skin=cosmic-glass] .live-badge-off{background:var(--glass-dense);color:var(--muted);border-color:var(--border)}:root[data-skin=cosmic-glass] .demo-badge{border:1px solid #ffd978}:root[data-skin=cosmic-glass] .panel{background:var(--surface);-webkit-backdrop-filter:var(--glass-blur);backdrop-filter:var(--glass-blur);border-radius:10px;box-shadow:var(--glass-edge),var(--glass-shadow);padding:18px 22px}:root[data-skin=cosmic-glass] .panel h2{font-size:14px;letter-spacing:.08em;font-weight:700;padding-bottom:8px;margin-bottom:14px;border-bottom:1px solid var(--border)}:root[data-skin=cosmic-glass] .panel h3{font-size:15px;font-weight:650}:root[data-skin=cosmic-glass] .card{background:var(--surface-2);border-radius:8px;box-shadow:var(--glass-edge);line-height:1.55}:root[data-skin=cosmic-glass] .facts dt{font-size:13px}:root[data-skin=cosmic-glass] .roadmap,:root[data-skin=cosmic-glass] .story{background:var(--glass-dense);border-radius:8px;line-height:1.6}:root[data-skin=cosmic-glass] .roadmap{border:1px solid var(--border)}:root[data-skin=cosmic-glass] .status{background:#5fd68a1f}:root[data-skin=cosmic-glass] .tag{background:#f0c0401a}:root[data-skin=cosmic-glass] button,:root[data-skin=cosmic-glass] select{background:var(--glass-dense);border-color:var(--control-border)}:root[data-skin=cosmic-glass] button:hover:not(:disabled){border-color:var(--accent);background:#3c3882b3}:root[data-skin=cosmic-glass] button:disabled{opacity:1;color:#8f9abb;border-style:dashed;cursor:not-allowed}:root[data-skin=cosmic-glass] a:focus-visible,:root[data-skin=cosmic-glass] button:focus-visible,:root[data-skin=cosmic-glass] select:focus-visible{outline:2px solid #d3ccff;outline-offset:2px;box-shadow:0 0 0 4px #9a8cff59}@supports not ((backdrop-filter: blur(1px)) or (-webkit-backdrop-filter: blur(1px))){:root[data-skin=cosmic-glass]{--surface: rgba(12, 16, 40, .92);--surface-2: rgba(26, 30, 70, .92)}:root[data-skin=cosmic-glass] .sidebar,:root[data-skin=cosmic-glass] .topbar{background:#080b20f2}}@media(prefers-reduced-motion:no-preference){:root[data-skin=cosmic-glass] .nav a,:root[data-skin=cosmic-glass] button{transition:background-color .15s,border-color .15s,color .15s}}@media(max-width:899px){:root[data-skin=cosmic-glass] body:before{left:0;background:linear-gradient(180deg,#080a1e00,#080a1e33 55%,#080a1e8c),url(./cosmic-glass-bg-Dwx47zPu.webp) 16% 0 / cover no-repeat,var(--bg)}:root[data-skin=cosmic-glass] .sidebar{background:#080b20d1;border-bottom-color:var(--border)}:root[data-skin=cosmic-glass] .panel{padding:14px 16px;background:#0c102899}}