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

package/dist/finalize/index.d.ts

@@ -0,0 +1,5 @@
+export { parseProposal, validateRelPath, PROPOSAL_SCHEMA_VERSION } from './proposal.js';
+export type { FinalizationProposal, ProposalParse, ExpectedCurrentStory } from './proposal.js';
+export { planFinalization, applyFinalization, readFinalizeConfig, renderCapsule } from './core.js';
+export type { ApplyResult, ApplyStatus, Check, CheckStatus, FinalizationPlan, FinalizeConfig, FinalizeOptions, PlanStatus, PlannedTarget, TargetKind, TargetState, } from './core.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/finalize/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC;AACxF,YAAY,EAAE,oBAAoB,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAC/F,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AACnG,YAAY,EACV,WAAW,EACX,WAAW,EACX,KAAK,EACL,WAAW,EACX,gBAAgB,EAChB,cAAc,EACd,eAAe,EACf,UAAU,EACV,aAAa,EACb,UAAU,EACV,WAAW,GACZ,MAAM,WAAW,CAAC"}

package/dist/finalize/index.js

@@ -0,0 +1,2 @@
+export { parseProposal, validateRelPath, PROPOSAL_SCHEMA_VERSION } from './proposal.js';
+export { planFinalization, applyFinalization, readFinalizeConfig, renderCapsule } from './core.js';

package/dist/finalize/proposal.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Finalization proposal (DOCSYNC-001): the typed, strictly validated input an
+ * AI assistant or developer prepares. It carries the *content* of the
+ * finalization; MONOLITH decides whether and where it may be applied.
+ *
+ * Validation is structural and syntactic only. Whether the content is *true*
+ * (the summary matches the code) is the owner's judgement, taken when they
+ * approve the plan digest — never something this module claims to check.
+ */
+export declare const PROPOSAL_SCHEMA_VERSION = 1;
+/**
+ * What the Current Story section of active.md must hold before the transition.
+ * There is deliberately no "any": a proposal cannot switch the guard off and
+ * silently replace somebody else's active story. `contains` must name the
+ * story being finalized (checked in `parseProposal`).
+ */
+export type ExpectedCurrentStory = 'none' | {
+    contains: string;
+};
+export interface FinalizationProposal {
+    schemaVersion: 1;
+    story: {
+        /** Story identifier, e.g. `DOCSYNC-001` or `1.3`. Used as the idempotency key. */
+        id: string;
+        title: string;
+        /** Phase directory name under `memory/working/phases/`, e.g. `phase-1`. */
+        phase: string;
+        /** Text of the `## ` heading in story-index.md the entry belongs to. */
+        phaseHeading: string;
+        /** Capsule file base name (without `.md`), e.g. `story-docsync-001-finalization`. */
+        slug: string;
+        /** `YYYY-MM-DD`. Supplied by the caller: MONOLITH never invents a finalization date. */
+        date: string;
+    };
+    /** What the Current Story section of active.md must look like before the transition. */
+    expectedCurrentStory: ExpectedCurrentStory;
+    work: {
+        objective: string;
+        implementationSummary: string;
+        filesChanged: string[];
+        tests: string;
+        keyDecisions: string;
+        adrs: string[];
+        lessons: string;
+    };
+    /** One-paragraph summary for story-index.md. */
+    summary: string;
+    keyOutputs: string[];
+    history: {
+        phaseName: string;
+        decision: string;
+        build: string;
+    };
+    /** Complete replacement of HANDOFF.md. Optional: omitted means HANDOFF.md is not touched. */
+    handoff?: {
+        content: string;
+    };
+    /** Extra documentation edits; each path must be allowed by `monolith.config.json` `finalization`. */
+    docUpdates?: Array<{
+        path: string;
+        newContent: string;
+        reason: string;
+    }>;
+}
+export type ProposalParse = {
+    ok: true;
+    proposal: FinalizationProposal;
+} | {
+    ok: false;
+    errors: string[];
+};
+export declare const LIMITS: {
+    readonly idLen: 64;
+    readonly titleLen: 200;
+    readonly lineLen: 1000;
+    readonly blockLen: 20000;
+    readonly listItems: 200;
+    readonly docUpdates: 20;
+    readonly docBytes: number;
+};
+/**
+ * True when `text` holds `id` as a whole Story ID token (case-insensitive).
+ * Tokens are maximal runs of the Story ID alphabet [A-Za-z0-9._-]; trailing
+ * `.`/`_`/`-` (sentence punctuation) are dropped. So `S-1` is a token of
+ * "S-1 in progress" or "(S-1)", but never of "S-10", "XS-1", "1.10" or "11.1".
+ */
+export declare function hasStoryIdToken(text: string, id: string): boolean;
+export declare function validDate(s: string): boolean;
+/**
+ * Lexical validation of a project-relative document path (R4). Rejects
+ * absolute paths, `..`, backslashes, NUL, empty segments and VCS internals.
+ * Symlinks are NOT decided here: they are refused by the safe read/write
+ * primitives, which look at the real file system.
+ */
+export declare function validateRelPath(p: unknown): string | null;
+export declare function parseProposal(raw: unknown): ProposalParse;
+//# sourceMappingURL=proposal.d.ts.map

package/dist/finalize/proposal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proposal.d.ts","sourceRoot":"","sources":["../../src/finalize/proposal.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,eAAO,MAAM,uBAAuB,IAAI,CAAC;AAEzC;;;;;GAKG;AACH,MAAM,MAAM,oBAAoB,GAAG,MAAM,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjE,MAAM,WAAW,oBAAoB;IACnC,aAAa,EAAE,CAAC,CAAC;IACjB,KAAK,EAAE;QACL,kFAAkF;QAClF,EAAE,EAAE,MAAM,CAAC;QACX,KAAK,EAAE,MAAM,CAAC;QACd,2EAA2E;QAC3E,KAAK,EAAE,MAAM,CAAC;QACd,wEAAwE;QACxE,YAAY,EAAE,MAAM,CAAC;QACrB,qFAAqF;QACrF,IAAI,EAAE,MAAM,CAAC;QACb,wFAAwF;QACxF,IAAI,EAAE,MAAM,CAAC;KACd,CAAC;IACF,wFAAwF;IACxF,oBAAoB,EAAE,oBAAoB,CAAC;IAC3C,IAAI,EAAE;QACJ,SAAS,EAAE,MAAM,CAAC;QAClB,qBAAqB,EAAE,MAAM,CAAC;QAC9B,YAAY,EAAE,MAAM,EAAE,CAAC;QACvB,KAAK,EAAE,MAAM,CAAC;QACd,YAAY,EAAE,MAAM,CAAC;QACrB,IAAI,EAAE,MAAM,EAAE,CAAC;QACf,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;IACF,gDAAgD;IAChD,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,OAAO,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAChE,6FAA6F;IAC7F,OAAO,CAAC,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9B,qGAAqG;IACrG,UAAU,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC1E;AAED,MAAM,MAAM,aAAa,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,oBAAoB,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAE3G,eAAO,MAAM,MAAM;;;;;;;;CAQT,CAAC;AAIX;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAGjE;AAaD,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAK5C;AAuBD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAUzD;AAED,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,aAAa,CA2GzD"}

package/dist/finalize/proposal.js

@@ -0,0 +1,213 @@
+/**
+ * Finalization proposal (DOCSYNC-001): the typed, strictly validated input an
+ * AI assistant or developer prepares. It carries the *content* of the
+ * finalization; MONOLITH decides whether and where it may be applied.
+ *
+ * Validation is structural and syntactic only. Whether the content is *true*
+ * (the summary matches the code) is the owner's judgement, taken when they
+ * approve the plan digest — never something this module claims to check.
+ */
+export const PROPOSAL_SCHEMA_VERSION = 1;
+export const LIMITS = {
+    idLen: 64,
+    titleLen: 200,
+    lineLen: 1000,
+    blockLen: 20000,
+    listItems: 200,
+    docUpdates: 20,
+    docBytes: 1024 * 1024,
+};
+const ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+/**
+ * True when `text` holds `id` as a whole Story ID token (case-insensitive).
+ * Tokens are maximal runs of the Story ID alphabet [A-Za-z0-9._-]; trailing
+ * `.`/`_`/`-` (sentence punctuation) are dropped. So `S-1` is a token of
+ * "S-1 in progress" or "(S-1)", but never of "S-10", "XS-1", "1.10" or "11.1".
+ */
+export function hasStoryIdToken(text, id) {
+    const want = id.toLowerCase();
+    return (text.match(/[A-Za-z0-9._-]+/g) ?? []).some((t) => t.replace(/[._-]+$/, '').toLowerCase() === want);
+}
+const SLUG_RE = /^[a-z0-9][a-z0-9._-]{0,99}$/;
+const PHASE_RE = /^[a-z0-9][a-z0-9-]{0,31}$/;
+const DATE_RE = /^(\d{4})-(\d{2})-(\d{2})$/;
+function isObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+function noUnknown(obj, allowed, where, errors) {
+    for (const k of Object.keys(obj))
+        if (!allowed.includes(k))
+            errors.push(`${where}: unknown field "${k}".`);
+}
+export function validDate(s) {
+    const m = DATE_RE.exec(s);
+    if (m === null)
+        return false;
+    const d = new Date(Date.UTC(Number(m[1]), Number(m[2]) - 1, Number(m[3])));
+    return d.getUTCFullYear() === Number(m[1]) && d.getUTCMonth() === Number(m[2]) - 1 && d.getUTCDate() === Number(m[3]);
+}
+function text(v, where, errors, opts) {
+    if (typeof v !== 'string') {
+        errors.push(`${where}: must be a string.`);
+        return '';
+    }
+    if (v.includes('\0'))
+        errors.push(`${where}: must not contain NUL.`);
+    if (!opts.allowEmpty && v.trim().length === 0)
+        errors.push(`${where}: must not be empty.`);
+    if (v.length > opts.max)
+        errors.push(`${where}: longer than ${opts.max} characters.`);
+    if (!opts.multiline && /[\r\n\u2028\u2029]/.test(v))
+        errors.push(`${where}: must be a single line.`);
+    return v;
+}
+function lines(v, where, errors) {
+    if (!Array.isArray(v)) {
+        errors.push(`${where}: must be an array of strings.`);
+        return [];
+    }
+    if (v.length > LIMITS.listItems)
+        errors.push(`${where}: more than ${LIMITS.listItems} items.`);
+    return v.map((x, i) => text(x, `${where}[${i}]`, errors, { multiline: false, max: LIMITS.lineLen }));
+}
+/**
+ * Lexical validation of a project-relative document path (R4). Rejects
+ * absolute paths, `..`, backslashes, NUL, empty segments and VCS internals.
+ * Symlinks are NOT decided here: they are refused by the safe read/write
+ * primitives, which look at the real file system.
+ */
+export function validateRelPath(p) {
+    if (typeof p !== 'string' || p.length === 0 || p.length > 260)
+        return 'path must be a non-empty string of at most 260 characters';
+    if (p.includes('\0') || p.includes('\\'))
+        return 'path must not contain NUL or backslashes';
+    if (p.startsWith('/') || /^[A-Za-z]:/.test(p))
+        return 'path must be relative to the project root';
+    const segs = p.split('/');
+    if (segs.some((s) => s === '' || s === '.' || s === '..'))
+        return 'path must not contain empty, "." or ".." segments';
+    // `.git` at ANY depth (nested repositories, submodule checkouts), any case
+    // (case-insensitive file systems), and trailing dot/space (Windows aliases).
+    if (segs.some((s) => /^\.git[. ]*$/i.test(s)) || segs.includes('node_modules'))
+        return 'path must not contain a .git (any case, any depth) or node_modules component';
+    return null;
+}
+export function parseProposal(raw) {
+    const errors = [];
+    if (!isObject(raw))
+        return { ok: false, errors: ['proposal must be a JSON object.'] };
+    noUnknown(raw, ['schemaVersion', 'story', 'expectedCurrentStory', 'work', 'summary', 'keyOutputs', 'history', 'handoff', 'docUpdates'], 'proposal', errors);
+    if (raw.schemaVersion !== PROPOSAL_SCHEMA_VERSION)
+        errors.push(`schemaVersion: must be ${PROPOSAL_SCHEMA_VERSION}.`);
+    const story = isObject(raw.story) ? raw.story : (errors.push('story: must be an object.'), {});
+    noUnknown(story, ['id', 'title', 'phase', 'phaseHeading', 'slug', 'date'], 'story', errors);
+    const id = text(story.id, 'story.id', errors, { multiline: false, max: LIMITS.idLen });
+    if (id && !ID_RE.test(id))
+        errors.push('story.id: must match [A-Za-z0-9][A-Za-z0-9._-]{0,63}.');
+    const title = text(story.title, 'story.title', errors, { multiline: false, max: LIMITS.titleLen });
+    const phase = text(story.phase, 'story.phase', errors, { multiline: false, max: 32 });
+    if (phase && !PHASE_RE.test(phase))
+        errors.push('story.phase: must match [a-z0-9][a-z0-9-]{0,31}.');
+    const phaseHeading = text(story.phaseHeading, 'story.phaseHeading', errors, { multiline: false, max: LIMITS.titleLen });
+    if (phaseHeading.startsWith('#'))
+        errors.push('story.phaseHeading: give the heading text without leading "#".');
+    const slug = text(story.slug, 'story.slug', errors, { multiline: false, max: 100 });
+    if (slug && !SLUG_RE.test(slug))
+        errors.push('story.slug: must match [a-z0-9][a-z0-9._-]{0,99}.');
+    const date = text(story.date, 'story.date', errors, { multiline: false, max: 10 });
+    if (date && !validDate(date))
+        errors.push('story.date: must be a real date YYYY-MM-DD.');
+    let expected = 'none';
+    const e = raw.expectedCurrentStory;
+    if (e === 'none')
+        expected = e;
+    else if (isObject(e) && typeof e.contains === 'string' && e.contains.trim() !== '' && Object.keys(e).length === 1 && e.contains.length <= LIMITS.lineLen) {
+        expected = { contains: e.contains };
+        if (id && !hasStoryIdToken(e.contains, id)) {
+            errors.push(`expectedCurrentStory.contains: must contain the story id "${id}" as a whole token (not as part of a longer id), so the guard cannot match another story.`);
+        }
+    }
+    else if (e === 'any') {
+        errors.push('expectedCurrentStory: "any" is not accepted (it would allow replacing an unrelated active story). Use "none" or {"contains": "<text containing the story id>"}.');
+    }
+    else
+        errors.push('expectedCurrentStory: must be "none" or {"contains": "<text containing the story id>"}.');
+    const w = isObject(raw.work) ? raw.work : (errors.push('work: must be an object.'), {});
+    noUnknown(w, ['objective', 'implementationSummary', 'filesChanged', 'tests', 'keyDecisions', 'adrs', 'lessons'], 'work', errors);
+    const block = (v, name) => text(v, `work.${name}`, errors, { multiline: true, max: LIMITS.blockLen });
+    const work = {
+        objective: block(w.objective, 'objective'),
+        implementationSummary: block(w.implementationSummary, 'implementationSummary'),
+        filesChanged: lines(w.filesChanged, 'work.filesChanged', errors),
+        tests: block(w.tests, 'tests'),
+        keyDecisions: block(w.keyDecisions, 'keyDecisions'),
+        adrs: lines(w.adrs, 'work.adrs', errors),
+        lessons: block(w.lessons, 'lessons'),
+    };
+    const summary = text(raw.summary, 'summary', errors, { multiline: false, max: LIMITS.blockLen });
+    const keyOutputs = lines(raw.keyOutputs, 'keyOutputs', errors);
+    const h = isObject(raw.history) ? raw.history : (errors.push('history: must be an object.'), {});
+    noUnknown(h, ['phaseName', 'decision', 'build'], 'history', errors);
+    const history = {
+        phaseName: text(h.phaseName, 'history.phaseName', errors, { multiline: false, max: LIMITS.titleLen }),
+        decision: text(h.decision, 'history.decision', errors, { multiline: false, max: LIMITS.blockLen }),
+        build: text(h.build, 'history.build', errors, { multiline: false, max: LIMITS.lineLen }),
+    };
+    let handoff;
+    if (raw.handoff !== undefined) {
+        if (!isObject(raw.handoff))
+            errors.push('handoff: must be an object {"content": "..."}.');
+        else {
+            noUnknown(raw.handoff, ['content'], 'handoff', errors);
+            const content = text(raw.handoff.content, 'handoff.content', errors, { multiline: true, max: LIMITS.docBytes });
+            handoff = { content };
+        }
+    }
+    let docUpdates;
+    if (raw.docUpdates !== undefined) {
+        if (!Array.isArray(raw.docUpdates))
+            errors.push('docUpdates: must be an array.');
+        else {
+            if (raw.docUpdates.length > LIMITS.docUpdates)
+                errors.push(`docUpdates: more than ${LIMITS.docUpdates} entries.`);
+            docUpdates = [];
+            const seen = new Set();
+            raw.docUpdates.forEach((d, i) => {
+                const where = `docUpdates[${i}]`;
+                if (!isObject(d)) {
+                    errors.push(`${where}: must be an object.`);
+                    return;
+                }
+                noUnknown(d, ['path', 'newContent', 'reason'], where, errors);
+                const bad = validateRelPath(d.path);
+                if (bad !== null)
+                    errors.push(`${where}.path: ${bad}.`);
+                const path = typeof d.path === 'string' ? d.path : '';
+                if (seen.has(path))
+                    errors.push(`${where}.path: "${path}" is listed twice.`);
+                seen.add(path);
+                docUpdates.push({
+                    path,
+                    newContent: text(d.newContent, `${where}.newContent`, errors, { multiline: true, max: LIMITS.docBytes }),
+                    reason: text(d.reason, `${where}.reason`, errors, { multiline: false, max: LIMITS.lineLen }),
+                });
+            });
+        }
+    }
+    if (errors.length > 0)
+        return { ok: false, errors };
+    const proposal = {
+        schemaVersion: 1,
+        story: { id, title, phase, phaseHeading, slug, date },
+        expectedCurrentStory: expected,
+        work,
+        summary,
+        keyOutputs,
+        history,
+    };
+    if (handoff)
+        proposal.handoff = handoff;
+    if (docUpdates && docUpdates.length > 0)
+        proposal.docUpdates = docUpdates;
+    return { ok: true, proposal };
+}

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.2";
 //# 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.2';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@latysh-development/monolith",
-  "version": "0.1.0-alpha.1",
+  "version": "0.1.0-alpha.2",
   "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/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,12 +22,62 @@ 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`)
+
+Where the CLI provides `monolith finalize`, use it instead of editing the memory
+files by hand (Steps 2-6 below describe what it writes; Step 1 and 5.5 stay 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