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

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

@@ -1 +1 @@
-{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../../src/finalize/core.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../../src/finalize/core.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAKH,OAAO,EAUL,KAAK,UAAU,EACf,KAAK,KAAK,EACV,KAAK,YAAY,EAClB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAe,KAAK,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAG1E,OAAO,EAAqB,KAAK,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AACjF,OAAO,EAA8B,KAAK,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAEtF,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,MAAM,GAAG,cAAc,CAAC;AAC3D,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,mBAAmB,GAAG,aAAa,GAAG,KAAK,GAAG,SAAS,GAAG,QAAQ,CAAC;AACxG,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,MAAM,GAAG,UAAU,GAAG,SAAS,GAAG,YAAY,CAAC;AACrF,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,WAAW,GAAG,mBAAmB,CAAC;AACrE,MAAM,MAAM,WAAW,GAAG,WAAW,GAAG,mBAAmB,GAAG,SAAS,GAAG,YAAY,CAAC;AAEvF,MAAM,WAAW,KAAK;IACpB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,WAAW,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,mFAAmF;IACnF,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,UAAU,CAAC;IACjB,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,WAAW,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,gFAAgF;IAChF,IAAI,EAAE,MAAM,CAAC;IACb,gGAAgG;IAChG,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,UAAU,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,sGAAsG;IACtG,MAAM,EAAE,MAAM,CAAC;IACf,8GAA8G;IAC9G,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,KAAK,EAAE,CAAC;IAChB,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB;;;;OAIG;IACH,WAAW,CAAC,EAAE,qBAAqB,CAAC;CACrC;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,WAAW,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,gBAAgB,CAAC;IACvB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,MAAM,CAAC,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACnE,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,eAAe;IAC9B,+DAA+D;IAC/D,GAAG,CAAC,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;IACrB,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,SAAS,CAAC,EAAE,CAAC,CAAC,EAAE,YAAY,KAAK,IAAI,CAAC;CACvC;AAYD,MAAM,WAAW,cAAc;IAC7B,YAAY,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACrD,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,UAAU,GAAG,cAAc,CAiCrE;AAuBD,wBAAgB,aAAa,CAAC,CAAC,EAAE,oBAAoB,GAAG,MAAM,CA4C7D;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAgFlD;AA2LD,uFAAuF;AACvF,eAAO,MAAM,qBAAqB,IAAI,CAAC;AAQvC,MAAM,MAAM,cAAc,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAItF;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,gBAAgB,EAAE,MAAM,GAAG,cAAc,CAQ5E;AAyWD,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,oBAAoB,GAAG,gBAAgB,CAIpG;AAUD,wBAAsB,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,EAAE,IAAI,GAAE,eAAoB,GAAG,OAAO,CAAC,WAAW,CAAC,CAuFnK"}

package/dist/finalize/core.js

@@ -25,6 +25,8 @@ import { dirname, join } from 'path';
 import { RootContainmentError, SafeWriteError, createFile, openParent, projectBoundary, readConfigFile, readProjectFile, replaceFile, resolveMonolithRoot, } from '../root/index.js';
 import { acquireLock } from '../coordinatorium/lock.js';
 import { extractCurrentStory } from '../brief/story.js';
+import { declaresNoActiveStory, maskNonContent } from '../brief/markdown-context.js';
+import { assessConsistency } from './consistency.js';
 import { validDate, validateRelPath } from './proposal.js';
 const MAX_DOC_BYTES = 4 * 1024 * 1024;
 const LOCK_NAME = 'finalize.lock';
@@ -104,28 +106,143 @@ export function renderCapsule(p) {
         `# STORY ${s.id} — ${s.title}`,
         '',
         '## Objective',
+        '',
         w.objective,
         '',
         '## Implementation Summary',
+        '',
         w.implementationSummary,
         '',
         '## Files Changed',
+        '',
         bullets(w.filesChanged),
         '',
         '## Tests',
+        '',
         w.tests,
         '',
         '## Key Decisions',
+        '',
         w.keyDecisions,
         '',
         '## ADRs Written',
+        '',
         bullets(w.adrs),
         '',
         '## Lessons Learned',
+        '',
         w.lessons,
         '',
     ].join('\n');
 }
+/**
+ * Format-equivalence of a capsule (FIN-001, made context-aware by A4-FIN-01).
+ * The capsule is created once and never overwritten, so "already present" used
+ * to mean byte-identical; a formatter pass (Prettier adds a blank line after
+ * every heading) then turned an unchanged capsule into a CONFLICT. Equivalence
+ * is deliberately narrow and NOT a general whitespace-insensitive comparison.
+ * Ignored: line endings (CRLF/LF), trailing whitespace on a line that is plain
+ * prose, a single blank line directly after an ATX heading, and trailing blank
+ * lines at end of file. NOT ignored, because whitespace carries meaning there:
+ *  - anything inside a fenced code block (``` or ~~~), an indented code block /
+ *    4-space-or-tab-indented line, an HTML comment, or YAML frontmatter
+ *    (`---` ... `---` at the very top; an unterminated one protects the whole
+ *    file) — those lines are compared verbatim;
+ *  - a Markdown hard line break (two or more trailing spaces before a line that
+ *    continues the paragraph): kept as a break (any run of 2+ spaces is the
+ *    same break); a backslash break is not whitespace and is always compared;
+ *  - blank lines anywhere else (paragraph breaks).
+ */
+export function capsuleCanonical(s) {
+    const lines = norm(s).split('\n');
+    const verbatim = lines.map(() => false);
+    const fenceOpen = (l) => {
+        const m = /^ {0,3}(`{3,}|~{3,})(.*)$/.exec(l);
+        return m !== null && !(m[1][0] === '`' && m[2].includes('`')) ? m : null;
+    };
+    let i = 0;
+    if (lines[0] === '---') {
+        const close = lines.findIndex((l, k) => k > 0 && (l === '---' || l === '...'));
+        const end = close === -1 ? lines.length - 1 : close; // unterminated: cannot tell where it ends
+        for (let k = 0; k <= end; k++)
+            verbatim[k] = true;
+        i = end + 1;
+    }
+    let fence = null;
+    let comment = false;
+    let htmlBlock = false; // an HTML block runs to the next blank line; its content is not Markdown
+    for (; i < lines.length; i++) {
+        const l = lines[i];
+        if (htmlBlock) {
+            if (l.trim() === '')
+                htmlBlock = false;
+            else {
+                verbatim[i] = true;
+                continue;
+            }
+        }
+        if (fence !== null) {
+            verbatim[i] = true;
+            const close = /^ {0,3}(`{3,}|~{3,})[ \t]*$/.exec(l);
+            if (close !== null && close[1][0] === fence.ch && close[1].length >= fence.len)
+                fence = null;
+        }
+        else if (comment) {
+            verbatim[i] = true;
+            if (l.includes('-->'))
+                comment = false;
+        }
+        else {
+            const open = fenceOpen(l);
+            if (open !== null) {
+                verbatim[i] = true;
+                fence = { ch: open[1][0], len: open[1].length };
+            }
+            else if (/^ {0,3}<!--/.test(l)) {
+                verbatim[i] = true;
+                if (!l.includes('-->', l.indexOf('<!--') + 4))
+                    comment = true;
+            }
+            else if (/^ {0,3}<[A-Za-z\/!?]/.test(l)) {
+                verbatim[i] = true;
+                htmlBlock = true;
+            }
+            else if (/^ {0,3}>/.test(l)) {
+                verbatim[i] = true; // blockquote: may hold fences/code whose whitespace we cannot track
+            }
+            else if (/^(?: {4}|\t)/.test(l)) {
+                verbatim[i] = true; // indented code block (or an indented continuation): compared as written
+            }
+        }
+    }
+    const out = [];
+    const outVerbatim = [];
+    let skippable = false; // a blank line right after an ATX heading, at most one
+    for (let k = 0; k < lines.length; k++) {
+        let l = lines[k];
+        if (verbatim[k]) {
+            out.push(l);
+            outVerbatim.push(true);
+            skippable = false;
+            continue;
+        }
+        const next = k + 1 < lines.length ? lines[k + 1] : undefined;
+        const hardBreak = / {2}$/.test(l) && l.trim() !== '' && !/^#{1,6}[ \t]/.test(l) && next !== undefined && next.trim() !== '' && !/^#{1,6}([ \t]|$)/.test(next) && fenceOpen(next) === null;
+        l = l.replace(/[ \t]+$/, '') + (hardBreak ? '  ' : '');
+        if (l === '' && skippable) {
+            skippable = false;
+            continue;
+        }
+        skippable = /^#{1,6}[ \t]/.test(l);
+        out.push(l);
+        outVerbatim.push(false);
+    }
+    while (out.length > 0 && out[out.length - 1] === '' && !outVerbatim[outVerbatim.length - 1]) {
+        out.pop();
+        outVerbatim.pop();
+    }
+    return out.join('\n');
+}
 const capsulePathOf = (root, p) => `${root}/memory/working/phases/${p.story.phase}/stories/${p.story.slug}.md`;
 function historyHeading(p) {
     return `## ${p.story.id} — ${p.story.title} (${p.story.date})`;
@@ -169,11 +286,16 @@ function activeBodies(root, p) {
 // Text transforms (pure)
 // ---------------------------------------------------------------------------
 const eolOf = (s) => (s.includes('\r\n') ? '\r\n' : '\n');
-/** Boundaries as in brief/story.ts: the next heading or a `---` rule ends a section. */
-function findSection(lines, re) {
+/**
+ * Boundaries as in brief/story.ts: the next heading or a `---` rule ends a
+ * section, and headings inside code fences or HTML comments do not count.
+ * `structural` is the same text with fenced / commented lines blanked (same
+ * line count), so reading and writing agree on which section is "Current Story".
+ */
+function findSection(lines, structural, re) {
     const hits = [];
-    lines.forEach((l, i) => {
-        if (re.test(l.trim()))
+    structural.forEach((l, i) => {
+        if (re.test(l.trim()) && l.trim() === lines[i].trim())
             hits.push(i);
     });
     if (hits.length === 0)
@@ -182,7 +304,7 @@ function findSection(lines, re) {
         return 'ambiguous';
     let end = lines.length;
     for (let i = hits[0] + 1; i < lines.length; i++) {
-        const t = lines[i].trim();
+        const t = structural[i].trim();
         if (/^#{1,6}\s+/.test(t) || /^-{3,}\s*$/.test(t)) {
             end = i;
             break;
@@ -199,8 +321,9 @@ const CURRENT_RE = /^##\s+Current Story\s*$/i;
 const LAST_RE = /^##\s+Last Finalization\s*$/i;
 function editActive(content, bodies) {
     const lines = content.split('\n');
-    const cur = findSection(lines, CURRENT_RE);
-    const last = findSection(lines, LAST_RE);
+    const structural = maskNonContent(content).split('\n');
+    const cur = findSection(lines, structural, CURRENT_RE);
+    const last = findSection(lines, structural, LAST_RE);
     for (const [name, s] of [['## Current Story', cur], ['## Last Finalization', last]]) {
         if (s === 'absent')
             return { state: 'conflict', reason: `active.md has no "${name}" section; it is never created automatically.` };
@@ -295,37 +418,13 @@ const FIX_HINT = 'To finalize, put exactly one line "**Story:** <id> — <title>
  * evidence files and `## Last Finalization`); its FIRST token is the id. Ids
  * mentioned in titles, descriptions, comments, code fences or other fields carry
  * no authority. Zero, several, or malformed field lines → no identity (fail closed).
+ * A section whose first visible line says "no active story" AND that has a
+ * structural field is contradictory → no identity (PSC-004A).
  */
 export function activeStoryIdentity(currentStoryBody) {
-    const found = [];
-    let fence = null;
-    let comment = false;
-    for (const raw of norm(currentStoryBody).split('\n')) {
-        const line = raw.trim();
-        if (comment) {
-            if (line.includes('-->'))
-                comment = false;
-            continue;
-        }
-        const f = /^(`{3,}|~{3,})/.exec(line);
-        if (fence !== null) {
-            if (f !== null && f[1][0] === fence[0] && f[1].length >= fence.length && line === f[1])
-                fence = null;
-            continue;
-        }
-        if (f !== null) {
-            fence = f[1];
-            continue;
-        }
-        if (line.startsWith('<!--')) {
-            if (!line.includes('-->'))
-                comment = true;
-            continue;
-        }
-        const m = /^\*\*Story:\*\*[ \t]*(.*)$/.exec(raw.replace(/\r$/, ''));
-        if (m !== null)
-            found.push(m[1].trim());
-    }
+    const found = structuralStoryFields(currentStoryBody);
+    if (found.length > 0 && declaresNoActiveStory(currentStoryBody))
+        return { ok: false, reason: `the Current Story section says there is no active story but also has ${found.length === 1 ? 'a "**Story:**" line' : `${found.length} "**Story:**" lines`} (${found.map((x) => `"${x.slice(0, 40)}"`).join(', ')}): contradictory identity. ${FIX_HINT}` };
     if (found.length === 0)
         return { ok: false, reason: `the Current Story section has no "**Story:** <id>" line, so the active story cannot be identified (ids in free text, headings, comments or code blocks are not identity). ${FIX_HINT}` };
     if (found.length > 1)
@@ -335,6 +434,19 @@ export function activeStoryIdentity(currentStoryBody) {
         return { ok: false, reason: `the "**Story:**" line ("${found[0].slice(0, 60)}") does not start with a valid story id. ${FIX_HINT}` };
     return { ok: true, id };
 }
+/** Values of the structural `**Story:**` field lines (outside code fences and HTML comments). */
+function structuralStoryFields(currentStoryBody) {
+    const found = [];
+    // Same fence / HTML-comment grammar as the brief's story extraction and
+    // freshness readers (one shared helper): text inside a code fence or an HTML
+    // comment, including a comment opened mid-line, is never identity.
+    for (const raw of maskNonContent(norm(currentStoryBody)).split('\n')) {
+        const m = /^\*\*Story:\*\*[ \t]*(.*)$/.exec(raw.replace(/\r$/, ''));
+        if (m !== null)
+            found.push(m[1].trim());
+    }
+    return found;
+}
 /**
  * Attested evidence. Contract: exactly one `**Status:**` (PASS or FAIL, nothing
  * else on the line), exactly one `**Story:**` whose FIRST token is the story id,
@@ -500,6 +612,8 @@ function buildInternals(ctx, p) {
         }
         else if (d.content === content)
             out.push({ target: { ...t, state: 'done', reason: 'capsule already present with identical content', base: 'DONE' } });
+        else if (capsuleCanonical(d.content) === capsuleCanonical(content))
+            out.push({ target: { ...t, state: 'done', reason: 'capsule already present; differs from the rendered form only in formatting (line endings, trailing whitespace, blank lines after headings) — left untouched', base: 'DONE' } });
         else
             out.push({ target: { ...t, state: 'conflict', reason: 'a different file already exists at the capsule path; it is never overwritten', base: d.sha } });
     }
@@ -612,13 +726,23 @@ function plan(ctx, p) {
             let ok;
             let want;
             let why = '';
-            if (exp === 'none')
-                (ok = ex.hasCurrentStorySection && /no active story/i.test(excerpt)), (want = 'no active story');
+            const visible = maskNonContent(excerpt);
+            if (exp === 'none') {
+                // Same rule as the brief: the first visible line says "no active story"
+                // and no structural **Story:** field (valid, duplicate or malformed)
+                // contradicts it (PSC-004A). Text inside code fences or comments is
+                // not a statement.
+                (ok = ex.hasCurrentStorySection && declaresNoActiveStory(excerpt) && structuralStoryFields(excerpt).length === 0), (want = 'no active story');
+                if (!ok && ex.hasCurrentStorySection && declaresNoActiveStory(excerpt))
+                    why = ' The section also has a "**Story:**" field: contradictory identity. ' + FIX_HINT;
+            }
             else {
                 const ident = activeStoryIdentity(excerpt);
                 want = `Current Story containing "${exp.contains}" whose "**Story:**" field is exactly ${p.story.id}`;
-                if (!excerpt.includes(exp.contains))
-                    (ok = false), (why = ' The expected text is not in the Current Story section.');
+                if (ex.ambiguous)
+                    (ok = false), (why = ' active.md has more than one "## Current Story" section outside code blocks and comments; the active story is ambiguous. ' + FIX_HINT);
+                else if (!visible.includes(exp.contains))
+                    (ok = false), (why = ` The expected text is not in the Current Story section${ident.ok ? '.' : `, and ${ident.reason}`}`);
                 else if (!ident.ok)
                     (ok = false), (why = ` ${ident.reason}`);
                 else if (ident.id !== p.story.id)
@@ -661,7 +785,28 @@ function plan(ctx, p) {
         evidence: [integrity.sha, governance.sha],
         config: [ctx.config.requiredDocs, ctx.config.allowedDocs],
     }));
-    return { plan: { status, storyId: p.story.id, digest, partial: someDone && !allDone, checks, targets, diagnostics }, internals };
+    const finalText = (rel) => {
+        const it = internals.find((i) => i.target.path === rel);
+        if (it?.write)
+            return it.write.content;
+        const d = readDoc(ctx.projectRoot, rel);
+        return d.kind === 'present' ? d.content : null;
+    };
+    let consistency;
+    try {
+        consistency = assessConsistency({
+            active: finalText(`${ctx.root}/memory/working/active.md`),
+            roadmap: finalText(`${ctx.root}/context/maps/roadmap-index.md`),
+            storyIndex: finalText(`${ctx.root}/memory/working/story-index.md`),
+            writtenPaths: targets.filter((t) => t.kind !== 'capsule' && t.kind !== 'execution-history' && (t.state === 'pending' || t.state === 'done')).map((t) => t.path),
+            projected: !allDone,
+            managedRoot: ctx.root,
+        });
+    }
+    catch (err) {
+        consistency = { status: 'NOT_VERIFIED', projected: !allDone, findings: [], notVerified: [`the assessment failed: ${err.message}`], scope: 'not assessed' };
+    }
+    return { plan: { status, storyId: p.story.id, digest, partial: someDone && !allDone, checks, targets, diagnostics, consistency }, internals };
 }
 export function planFinalization(targetDir, proposal) {
     const c = makeContext(targetDir);

package/dist/ideas/cli.d.ts

@@ -11,6 +11,7 @@ interface AddFlags {
     description?: string;
     context?: string;
     descriptionStdin?: boolean;
+    paths?: string[];
 }
 /** Strict: every flag needs a value, none may repeat, unknown flags and stray arguments are errors. */
 export declare function parseAddArgs(args: string[]): AddFlags;

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

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/ideas/cli.ts"],"names":[],"mappings":"AACA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAiBvC,UAAU,QAAQ;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAMD,uGAAuG;AACvG,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,QAAQ,CA4BrD;AAED;;;;GAIG;AACH,wBAAsB,aAAa,CAAC,KAAK,GAAE,QAAQ,GAAG;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAkB,GAAG,OAAO,CAAC,MAAM,CAAC,CAyB1G;AAED,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,SAAS,SAAgB,EAAE,KAAK,GAAE,QAAQ,GAAG;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAYhJ;AAED,wBAAsB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,SAAS,SAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAqB1F;AAiBD,wBAAsB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,SAAS,SAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAG1F;AAED,6CAA6C;AAC7C,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,SAAS,SAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAe7F"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/ideas/cli.ts"],"names":[],"mappings":"AACA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAiBvC,UAAU,QAAQ;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB;AAOD,uGAAuG;AACvG,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,QAAQ,CAmCrD;AAED;;;;GAIG;AACH,wBAAsB,aAAa,CAAC,KAAK,GAAE,QAAQ,GAAG;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAkB,GAAG,OAAO,CAAC,MAAM,CAAC,CAyB1G;AAED,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,SAAS,SAAgB,EAAE,KAAK,GAAE,QAAQ,GAAG;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAYhJ;AAED,wBAAsB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,SAAS,SAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAqB1F;AAkBD,wBAAsB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,SAAS,SAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAG1F;AAED,6CAA6C;AAC7C,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,SAAS,SAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAe7F"}

package/dist/ideas/cli.js

@@ -9,7 +9,7 @@
 import { reportWriteWarning } from '../root/index.js';
 import { addIdea, getIdea, ideaStore, listIdeas } from './store.js';
 import { IDEA_LIMITS, IdeaError } from './types.js';
-const ADD_USAGE = 'Usage: monolith idea add --title "..." (--description "..." | --description-stdin) [--context "..."]';
+const ADD_USAGE = 'Usage: monolith idea add --title "..." (--description "..." | --description-stdin) [--context "..."] [--path <project-relative document file> ...]';
 /** UTF-8 needs at most 4 bytes per UTF-16 code unit's worth of text; anything larger cannot fit the description limit. */
 const STDIN_MAX_BYTES = IDEA_LIMITS.description * 4;
 const LIST_USAGE = 'Usage: monolith idea list';
@@ -21,7 +21,8 @@ function printable(s) {
 }
 const ADD_FLAGS = ['--title', '--description', '--context'];
 const STDIN_FLAG = '--description-stdin';
-const KNOWN_FLAGS = [...ADD_FLAGS, STDIN_FLAG];
+const PATH_FLAG = '--path';
+const KNOWN_FLAGS = [...ADD_FLAGS, STDIN_FLAG, PATH_FLAG];
 /** Strict: every flag needs a value, none may repeat, unknown flags and stray arguments are errors. */
 export function parseAddArgs(args) {
     const out = {};
@@ -36,6 +37,14 @@ export function parseAddArgs(args) {
             out.descriptionStdin = true;
             continue;
         }
+        if (flag === PATH_FLAG) {
+            const v = args[i + 1];
+            if (v === undefined || KNOWN_FLAGS.includes(v))
+                throw new IdeaError('IDEA_INVALID_INPUT', `${flag} needs a value.\n${ADD_USAGE}`);
+            (out.paths ??= []).push(v);
+            i++;
+            continue;
+        }
         const key = flag.slice(2);
         if (key in out)
             throw new IdeaError('IDEA_INVALID_INPUT', `${flag} was given more than once.\n${ADD_USAGE}`);
@@ -92,7 +101,7 @@ export async function runIdeaAdd(args, targetDir = process.cwd(), stdin = proces
     const flags = parseAddArgs(args);
     const description = flags.descriptionStdin ? await readStdinText(stdin) : flags.description;
     const store = ideaStore(targetDir);
-    const { idea, path } = addIdea(store, { title: flags.title, description, context: flags.context }, { onWarning: (w) => reportWriteWarning(w) });
+    const { idea, path } = addIdea(store, { title: flags.title, description, context: flags.context, ...(flags.paths !== undefined ? { paths: flags.paths } : {}) }, { onWarning: (w) => reportWriteWarning(w) });
     console.log(`Saved ${idea.id} [${idea.status}]: ${printable(idea.title)}`);
     console.log(`  file: ${path}`);
     console.log('Current task and focus are unchanged. Recall with `monolith idea list` / `monolith idea show ' + idea.id + '`.');
@@ -130,6 +139,8 @@ function formatIdea(i) {
     ];
     if (i.tags !== undefined && i.tags.length > 0)
         lines.push(`  tags:       ${i.tags.map(printable).join(', ')}`);
+    if (i.paths !== undefined && i.paths.length > 0)
+        lines.push(`  paths:      ${i.paths.map(printable).join(', ')}`);
     lines.push('  context:    ' + (i.context === undefined ? '(none)' : ''));
     if (i.context !== undefined)
         lines.push(...i.context.split('\n').map((l) => `    ${l}`));

package/dist/ideas/format.d.ts

@@ -9,6 +9,7 @@
  *   createdAt: "2026-..."
  *   context: "..."          (optional)
  *   tags: ["a", "b"]        (optional)
+ *   paths: ["docs/x.md"]  (optional, KA-001: exact document files of the registered artifact; see attributionPathProblem)
  *   ---
  *
  *   ## Description
@@ -21,6 +22,35 @@
  * The description is the body: no escaping, no trimming.
  */
 import { type Idea, type NewIdea } from './types.js';
+/**
+ * KA-001: a registered artifact path. Project-relative, `/`-separated, no
+ * traversal, no globs; a trailing `/` makes it a directory prefix. Returns the
+ * reason it is invalid, or null.
+ */
+export declare function invalidArtifactPath(p: unknown): string | null;
+/** True when `file` is covered by one of the registered `paths` (exact file, or `dir/` prefix). */
+export declare function artifactPathsCover(paths: readonly string[], file: string): boolean;
+/**
+ * Extensions of documents that can be registered as independent knowledge.
+ * Deliberately an allow-list of *document* formats, not of directories: a
+ * strategy paper may live anywhere, but source code, configuration and
+ * scripts never qualify, whatever directory they are in.
+ */
+export declare const KNOWLEDGE_DOCUMENT_EXTENSIONS: readonly string[];
+/**
+ * A4-SEC-03: the policy for a path that is to ATTRIBUTE commits to independent
+ * knowledge (stricter than `invalidArtifactPath`, which only says the path is
+ * well-formed). A registered path must be
+ *  - one exact file: a `dir/` prefix would turn every later change under it into
+ *    "knowledge" (`src/`, the project root, ...);
+ *  - a document (`KNOWLEDGE_DOCUMENT_EXTENSIONS`): registering `src/pay.ts` would
+ *    let an idea id launder ordinary code;
+ *  - outside the MONOLITH root (case-insensitive; `.monolith` is always refused
+ *    too): governance state is never independent knowledge.
+ * Returns the reason a path is refused, or null. Registration says WHICH file a
+ * commit may be explained by; it does not say the change was reviewed or allowed.
+ */
+export declare function attributionPathProblem(p: string, monolithRoot?: string): string | null;
 export declare function isIdeaId(value: string): boolean;
 export declare function ideaNumber(id: string): number;
 export declare function formatIdeaId(n: number): string;
@@ -28,7 +58,7 @@ export declare function formatIdeaId(n: number): string;
 export declare function ideaIdFromFileName(name: string): string | null;
 export declare function ideaFileName(id: string): string;
 /** Validates user input; returns it unchanged (content is never trimmed or rewritten). */
-export declare function validateNewIdea(input: NewIdea): NewIdea;
+export declare function validateNewIdea(input: NewIdea, monolithRoot?: string): NewIdea;
 export declare function serializeIdea(idea: Idea): string;
 /**
  * Parse an idea file. `expectedId` is the id implied by the file name; a

package/dist/ideas/format.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../src/ideas/format.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAyC,KAAK,IAAI,EAAmB,KAAK,OAAO,EAAE,MAAM,YAAY,CAAC;AAS7G,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAE/C;AAED,wBAAgB,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAI7C;AAED,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAE9C;AAED,wFAAwF;AACxF,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAG9D;AAED,wBAAgB,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAG/C;AAaD,0FAA0F;AAC1F,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAmBvD;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAahD;AAqBD;;;GAGG;AACH,wBAAgB,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CA0DhE"}
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../src/ideas/format.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAyC,KAAK,IAAI,EAAmB,KAAK,OAAO,EAAE,MAAM,YAAY,CAAC;AAS7G;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAY7D;AAED,mGAAmG;AACnG,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAElF;AAED;;;;;GAKG;AACH,eAAO,MAAM,6BAA6B,EAAE,SAAS,MAAM,EAA0C,CAAC;AAOtG;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAiBtF;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAE/C;AAED,wBAAgB,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAI7C;AAED,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAE9C;AAED,wFAAwF;AACxF,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAG9D;AAED,wBAAgB,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAG/C;AAaD,0FAA0F;AAC1F,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,CA4B9E;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAchD;AAqBD;;;GAGG;AACH,wBAAgB,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAsEhE"}

package/dist/ideas/format.js

@@ -9,6 +9,7 @@
  *   createdAt: "2026-..."
  *   context: "..."          (optional)
  *   tags: ["a", "b"]        (optional)
+ *   paths: ["docs/x.md"]  (optional, KA-001: exact document files of the registered artifact; see attributionPathProblem)
  *   ---
  *
  *   ## Description
@@ -27,6 +28,85 @@ const FILE_RE = /^(IDEA-\d{3,9})\.md$/;
 // C0 controls, DEL and C1 controls (a title is shown in a terminal).
 // eslint-disable-next-line no-control-regex
 const CONTROL_RE = /[\u0000-\u001f\u007f-\u009f\u2028\u2029]/;
+/**
+ * KA-001: a registered artifact path. Project-relative, `/`-separated, no
+ * traversal, no globs; a trailing `/` makes it a directory prefix. Returns the
+ * reason it is invalid, or null.
+ */
+export function invalidArtifactPath(p) {
+    if (typeof p !== 'string' || p === '')
+        return 'path must be a non-empty string';
+    if (p.length > IDEA_LIMITS.pathLength)
+        return `path is too long (> ${IDEA_LIMITS.pathLength} characters)`;
+    if (CONTROL_RE.test(p))
+        return 'path must not contain control characters';
+    if (p.includes('"'))
+        return 'path must not contain a double quote';
+    if (p.includes('\\'))
+        return 'path must use "/" separators';
+    if (p.startsWith('/') || /^[A-Za-z]:/.test(p))
+        return 'path must be project-relative';
+    if (/[*?[\]{}]/.test(p))
+        return 'path must not contain glob characters';
+    if (p !== p.trim())
+        return 'path must not start or end with whitespace';
+    const segments = p.endsWith('/') ? p.slice(0, -1).split('/') : p.split('/');
+    if (segments.some((x) => x === '' || x === '.' || x === '..'))
+        return 'path must not contain empty, "." or ".." segments';
+    return null;
+}
+/** True when `file` is covered by one of the registered `paths` (exact file, or `dir/` prefix). */
+export function artifactPathsCover(paths, file) {
+    return paths.some((p) => (p.endsWith('/') ? file.startsWith(p) : file === p));
+}
+/**
+ * Extensions of documents that can be registered as independent knowledge.
+ * Deliberately an allow-list of *document* formats, not of directories: a
+ * strategy paper may live anywhere, but source code, configuration and
+ * scripts never qualify, whatever directory they are in.
+ */
+export const KNOWLEDGE_DOCUMENT_EXTENSIONS = ['.md', '.mdx', '.markdown', '.adoc'];
+/** Directories whose documents steer tools, agents or dependencies; never knowledge (compared lower-case). */
+const KNOWLEDGE_DENIED_DIRS = ['.git', '.claude', '.cursor', '.github', '.vscode', '.husky', 'node_modules'];
+/** Agent-instruction file names (compared lower-case): changing them changes agent behaviour. */
+const KNOWLEDGE_DENIED_NAMES = ['agents.md', 'agent.md', 'claude.md', 'gemini.md', 'skill.md', 'conventions.md', 'codeowners.md', 'copilot-instructions.md', '.cursorrules', '.windsurfrules.md'];
+/**
+ * A4-SEC-03: the policy for a path that is to ATTRIBUTE commits to independent
+ * knowledge (stricter than `invalidArtifactPath`, which only says the path is
+ * well-formed). A registered path must be
+ *  - one exact file: a `dir/` prefix would turn every later change under it into
+ *    "knowledge" (`src/`, the project root, ...);
+ *  - a document (`KNOWLEDGE_DOCUMENT_EXTENSIONS`): registering `src/pay.ts` would
+ *    let an idea id launder ordinary code;
+ *  - outside the MONOLITH root (case-insensitive; `.monolith` is always refused
+ *    too): governance state is never independent knowledge.
+ * Returns the reason a path is refused, or null. Registration says WHICH file a
+ * commit may be explained by; it does not say the change was reviewed or allowed.
+ */
+export function attributionPathProblem(p, monolithRoot) {
+    const syntax = invalidArtifactPath(p);
+    if (syntax !== null)
+        return syntax;
+    if (p.endsWith('/'))
+        return 'a directory prefix is not allowed; register the exact document file';
+    const lower = p.toLowerCase();
+    for (const root of new Set(['.monolith', (monolithRoot ?? '.monolith').replace(/^(\.\/)+/, '').replace(/\/+$/, '').toLowerCase()])) {
+        if (root !== '' && root !== '.' && (lower === root || lower.startsWith(`${root}/`)))
+            return `a path inside the MONOLITH root (${root}) is never independent knowledge`;
+    }
+    if (/[\u200b-\u200f\u2028-\u202e\u2060-\u2064\ufeff\u00a0]/.test(p))
+        return 'path must not contain invisible or look-alike whitespace characters';
+    const segs = lower.split('/');
+    const hiddenDir = segs.slice(0, -1).find((x) => x.startsWith('.') || KNOWLEDGE_DENIED_DIRS.includes(x));
+    if (hiddenDir !== undefined)
+        return `a path under ${hiddenDir}/ (hidden or tool/dependency directory) configures tools or dependencies and is never independent knowledge`;
+    if (KNOWLEDGE_DENIED_NAMES.includes(segs[segs.length - 1]))
+        return 'agent-instruction files cannot be registered as independent knowledge';
+    if (!KNOWLEDGE_DOCUMENT_EXTENSIONS.some((e) => lower.endsWith(e))) {
+        return `only document files (${KNOWLEDGE_DOCUMENT_EXTENSIONS.join(', ')}) can be registered, not source code or configuration`;
+    }
+    return null;
+}
 export function isIdeaId(value) {
     return ID_RE.test(value);
 }
@@ -57,7 +137,7 @@ function wellFormed(s) {
     return !LONE_SURROGATE_RE.test(s);
 }
 /** Validates user input; returns it unchanged (content is never trimmed or rewritten). */
-export function validateNewIdea(input) {
+export function validateNewIdea(input, monolithRoot) {
     const { title, description, context } = input;
     if (typeof title !== 'string' || title.trim() === '')
         throw invalid('title must not be empty.');
@@ -77,6 +157,19 @@ export function validateNewIdea(input) {
             throw invalid(`context is too long (${context.length} > ${IDEA_LIMITS.context} characters).`);
         }
     }
+    if (input.paths !== undefined) {
+        if (!Array.isArray(input.paths) || input.paths.length === 0)
+            throw invalid('paths, when given, must be a non-empty list.');
+        if (input.paths.length > IDEA_LIMITS.paths)
+            throw invalid(`too many paths (${input.paths.length} > ${IDEA_LIMITS.paths}).`);
+        for (const p of input.paths) {
+            const bad = attributionPathProblem(p, monolithRoot);
+            if (bad !== null)
+                throw invalid(`paths: ${bad} (${JSON.stringify(String(p).slice(0, 80))}).`);
+        }
+        if (new Set(input.paths).size !== input.paths.length)
+            throw invalid('paths must not repeat.');
+    }
     for (const [name, v] of [['title', title], ['description', description], ['context', context]]) {
         if (v !== undefined && !wellFormed(v))
             throw invalid(`${name} contains an unpaired surrogate and cannot be stored losslessly.`);
@@ -96,6 +189,8 @@ export function serializeIdea(idea) {
         lines.push(`context: ${JSON.stringify(idea.context)}`);
     if (idea.tags !== undefined && idea.tags.length > 0)
         lines.push(`tags: ${JSON.stringify(idea.tags)}`);
+    if (idea.paths !== undefined && idea.paths.length > 0)
+        lines.push(`paths: ${JSON.stringify(idea.paths)}`);
     lines.push('---');
     return `${lines.join('\n')}\n${BODY_HEADING}${idea.description}\n`;
 }
@@ -190,5 +285,18 @@ export function parseIdea(expectedId, text) {
         }
         idea.tags = tags;
     }
+    if ('paths' in fm) {
+        let paths;
+        try {
+            paths = JSON.parse(fm.paths);
+        }
+        catch {
+            throw corrupt(expectedId, '"paths" is not a JSON array of strings.');
+        }
+        if (!Array.isArray(paths) || paths.length > IDEA_LIMITS.paths || !paths.every((x) => invalidArtifactPath(x) === null)) {
+            throw corrupt(expectedId, '"paths" is not a JSON array of valid project-relative paths.');
+        }
+        idea.paths = paths;
+    }
     return idea;
 }

package/dist/ideas/store.d.ts

@@ -26,6 +26,8 @@ import { type Idea, type IdeaEntry, type NewIdea } from './types.js';
 export interface IdeaStore {
     projectRoot: string;
     rootAbs: string;
+    /** Validated relative MONOLITH root (`.monolith` by default). */
+    monolithRoot: string;
     dirAbs: string;
     boundary: WriteBoundary;
 }

package/dist/ideas/store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/ideas/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAIH,OAAO,EAWL,KAAK,aAAa,EAClB,KAAK,YAAY,EAClB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAE9C,OAAO,EAA0B,KAAK,IAAI,EAAE,KAAK,SAAS,EAAE,KAAK,OAAO,EAAE,MAAM,YAAY,CAAC;AAQ7F,MAAM,WAAW,SAAS;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,aAAa,CAAC;CACzB;AAED,uFAAuF;AACvF,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAetD;AAED,MAAM,WAAW,cAAc;IAC7B,4BAA4B;IAC5B,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;IACjB,8EAA8E;IAC9E,GAAG,CAAC,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;IACrB,8EAA8E;IAC9E,SAAS,CAAC,EAAE,CAAC,CAAC,EAAE,YAAY,KAAK,IAAI,CAAC;CACvC;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,IAAI,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;CACd;AA+DD,wBAAgB,OAAO,CAAC,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,GAAE,cAAmB,GAAG,aAAa,CA4ElG;AAsBD,8GAA8G;AAC9G,wBAAgB,OAAO,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI,CAM1D;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,SAAS,GAAG,SAAS,EAAE,CAiBvD"}
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/ideas/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAIH,OAAO,EAWL,KAAK,aAAa,EAClB,KAAK,YAAY,EAClB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAE9C,OAAO,EAA0B,KAAK,IAAI,EAAE,KAAK,SAAS,EAAE,KAAK,OAAO,EAAE,MAAM,YAAY,CAAC;AAQ7F,MAAM,WAAW,SAAS;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,iEAAiE;IACjE,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,aAAa,CAAC;CACzB;AAED,uFAAuF;AACvF,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAgBtD;AAED,MAAM,WAAW,cAAc;IAC7B,4BAA4B;IAC5B,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;IACjB,8EAA8E;IAC9E,GAAG,CAAC,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;IACrB,8EAA8E;IAC9E,SAAS,CAAC,EAAE,CAAC,CAAC,EAAE,YAAY,KAAK,IAAI,CAAC;CACvC;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,IAAI,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;CACd;AA+DD,wBAAgB,OAAO,CAAC,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,GAAE,cAAmB,GAAG,aAAa,CA6ElG;AAsBD,8GAA8G;AAC9G,wBAAgB,OAAO,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI,CAM1D;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,SAAS,GAAG,SAAS,EAAE,CAiBvD"}