@ornexus/neocortex 4.60.71 → 4.60.73

package/packages/client/dist/yoloop/shared-discover-epics.js

@@ -1 +1,1007 @@
-const ge=Object.freeze({epicId:"P{number}",epicFilename:"docs/epics/epic-P{number}.md",storyId:"P{number}.NN",storyFilename:"docs/stories/P{number}.NN.story.md",acceptedOnly:Object.freeze({epicFilenames:Object.freeze(["docs/epics/epic-{number}.md","docs/epics/EPIC-{number}-{slug}.md","docs/epics/EPIC-{number}_{slug}.md","docs/epics/epic-{slug}.md"]),storyFilenames:Object.freeze(["docs/stories/{number}.NN.story.md","docs/stories/story-P{number}.NN.md","docs/stories/story-{number}.NN.md","docs/stories/EPIC-{number}.STORY-{number}.md"])})}),O=Object.freeze([/^epic-(P?\d+(?:\.\d+)?)\.md$/i,/^EPIC-(\d+)(?:[-_].*)?\.md$/,/^epic-([a-z0-9][a-z0-9_-]*)\.md$/i]),D=Object.freeze([/^(P?\d+\.\d+(?:\.\d+)?)\.story\.md$/i,/^story-(P?\d+\.\d+)\.md$/i,/^EPIC-(\d+)\.STORY-(\d+)\.md$/]),k=Object.freeze([".archive","_archive","_archives","_drafts","archive","archives","archived","drafts"]),F=/^---\s*\n([\s\S]*?)\n---/;function z(t,e){const i=new RegExp(`^${e}:\\s*(.+?)\\s*$`,"mi"),n=t.match(i);if(!n)return;let c=n[1].trim();return(c.startsWith('"')&&c.endsWith('"')||c.startsWith("'")&&c.endsWith("'"))&&(c=c.slice(1,-1)),c||void 0}function G(t){if(typeof t!="string"||t.length===0)return{};const e=t.match(F);if(!e)return{};const i=e[1];return{id:z(i,"id"),title:z(i,"title"),status:z(i,"status"),epic_id:z(i,"epic_id"),depends_on:te(i),files_to_modify:P(i,"files_to_modify"),total_stories:x(z(i,"total_stories"))}}const Y=32,B=4096,H=/^\s*\*\*([^*\r\n]+?):\*\*\s*(.*?)\s*$/,U=new Set(["backlog","pending","ready","planning","in-progress","done","completed","merged","cancelled","canceled","abandoned","draft","template","archived","branch-ready","diagnose","research","write-spec","create-tasks","implemented","refactor-suggest-done","property-tests-emitted","tests-validated","qa-gate-passed","memory-updated","committed","synced","pr-created","pr-reviewed","partial"]);function L(t){let e=t.trim();return e.startsWith("`")&&e.endsWith("`")&&e.length>=2&&(e=e.slice(1,-1).trim()),(e.startsWith('"')&&e.endsWith('"')||e.startsWith("'")&&e.endsWith("'"))&&(e=e.slice(1,-1).trim()),e}function x(t){if(t===void 0||!/^\d{1,5}$/.test(t.trim()))return;const e=Number(t);return Number.isSafeInteger(e)?e:void 0}function Z(t){const e=L(t).toLowerCase().replace(/[_\s]+/g,"-"),n={planned:"planning",complete:"completed",closed:"done",finished:"done"}[e]??e;return U.has(n)?n:void 0}function X(t){const e=t.trim().toLowerCase().replace(/[_-]+/g," ").replace(/\s+/g," ");if(e==="id"||e==="epic id")return"id";if(e==="title"||e==="titulo")return"title";if(e==="status")return"status";if(e==="total stories"||e==="total de stories")return"total_stories"}function q(t){const e=t.find(c=>/^#\s+\S/.test(c));if(!e)return;const i=e.replace(/^#\s+/,"").trim();return(i.replace(/^(?:Epic|Story)\s+\S+\s*(?:(?:--?|:)|[\u2013\u2014])\s*/i,"")||i).slice(0,200)}function j(t,e,i,n){const c=[...new Set(t.map(L).filter(Boolean))];if(c.length>1){n.push(`legacy metadata ambiguous for '${e}' in '${i}': conflicting values ignored`);return}return c[0]}function K(t,e){const i=[],n=[],c=t.slice(0,B).split(/\r?\n/,Y);for(const m of c){if(n.length>0&&(/^\s*---\s*$/.test(m)||/^##\s+/.test(m)))break;n.push(m)}const o=new Map;for(const m of n){const r=m.match(H);if(!r)continue;const a=X(r[1]);if(!a)continue;const d=o.get(a)??[];d.push(r[2]),o.set(a,d)}const f=j(o.get("id")??[],"id",e,i),l=j(o.get("title")??[],"title",e,i),_=j(o.get("status")??[],"status",e,i),g=j(o.get("total_stories")??[],"total_stories",e,i),p=_===void 0?void 0:Z(_);_!==void 0&&p===void 0&&i.push(`legacy metadata status unrecognized in '${e}': value ignored`);const b=x(g);g!==void 0&&b===void 0&&i.push(`legacy metadata total_stories invalid in '${e}': value ignored`);const $=f&&/^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/.test(f)?f:void 0;f!==void 0&&$===void 0&&i.push(`legacy metadata id invalid in '${e}': value ignored`);const s=q(n),u=l??s;return{metadata:{...$?{id:$}:{},...u?{title:u.slice(0,200)}:{},...p?{status:p}:{},...b!==void 0?{total_stories:b}:{}},source:"legacy-metadata",warnings:Object.freeze(i)}}function V(t){return/^[A-Za-z0-9._-]{1,160}$/.test(t)?t:"markdown-target.md"}function J(t){return new TextEncoder().encode(t).length}function Q(t){let e=!1;for(const i of t.split(/\r?\n/)){if(!i.trim()||i.trimStart().startsWith("#"))continue;const n=i.match(/^\s+-\s+(.+?)\s*$/);if(n){if(!e)return!0;const f=n[1].trim();if(f.startsWith('"')&&!f.endsWith('"')||f.startsWith("'")&&!f.endsWith("'"))return!0;continue}if(/^\s+/.test(i))return!0;const c=i.match(/^[A-Za-z0-9_-]+:\s*(.*?)\s*$/);if(!c)return!0;const o=c[1].trim();if(e=o.length===0,o.startsWith('"')&&!o.endsWith('"')||o.startsWith("'")&&!o.endsWith("'"))return!0}return!1}function ee(t,e,i){const n=V(e),c=t.match(F);if(!c)return Object.freeze([`metadata-frontmatter reason=frontmatter-malformed file='${n}': repair the bounded leading YAML envelope; source content omitted`]);const o=c[1];return J(o)>8*1024||o.split(/\r?\n/).length>128?Object.freeze([`metadata-frontmatter reason=frontmatter-oversized file='${n}': reduce the leading YAML envelope; source content omitted`]):Q(o)||o.trim().length>0&&Object.keys(i).length===0?Object.freeze([`metadata-frontmatter reason=frontmatter-unsupported-value file='${n}': use bounded scalar fields or string lists; source content omitted`]):Object.freeze([])}function N(t,e){if(/^---(?:\s*\r?\n|\s*$)/.test(t)){const i=G(t);return{metadata:i,source:"frontmatter",warnings:ee(t,e,i)}}return typeof t!="string"||t.length===0?{metadata:{},source:"none",warnings:Object.freeze([])}:K(t,e)}function R(t){let e=t.trim();if((e.startsWith('"')&&e.endsWith('"')||e.startsWith("'")&&e.endsWith("'"))&&(e=e.slice(1,-1).trim()),!!e&&!/^(null|undefined|true|false)$/i.test(e))return e}function te(t){return P(t,"depends_on")}function P(t,e){const i=e.replace(/[.*+?^${}()|[\]\\]/g,"\\$&"),c=t.match(new RegExp(`^${i}:[ \\t]*(.+?)[ \\t]*$`,"mi"))?.[1]?.trim();if(c!==void 0){const g=(c.startsWith("[")&&c.endsWith("]")?c.slice(1,-1).split(","):[c]).map(R).filter(p=>typeof p=="string"&&p.length>0);return g.length>0?Object.freeze(g):void 0}const o=t.split(/\r?\n/),f=[];let l=!1;for(const _ of o){if(!l){new RegExp(`^${i}:\\s*$`,"i").test(_.trim())&&(l=!0);continue}if(/^[A-Za-z0-9_-]+:\s*/.test(_))break;const g=_.match(/^\s*-\s*(.+?)\s*$/);if(!g)continue;const p=R(g[1]);p&&f.push(p)}return f.length>0?Object.freeze(f):void 0}function T(t){return t.startsWith("_")||t.startsWith(".")}function ie(t){return k.includes(t)}async function he(){const t=await import("node:fs"),e=await import("node:path");return{isDirectory(i){try{return t.statSync(i).isDirectory()}catch{return!1}},readdir(i){try{return t.readdirSync(i)}catch{return[]}},readFile(i){try{return t.readFileSync(i,"utf8")}catch{return""}},join(...i){try{return e.join(...i)}catch{return i.join("/")}}}}function ne(t,e){let i=!1,n=null,c=null;for(let o=0;o<O.length;o++){const f=O[o],l=t.match(f);if(l){i=!0,n=l[1],c=o===2?"filename-slug":"filename-canonical";break}}return i?e.id&&e.id.length>0?{id:e.id,source:"frontmatter"}:{id:n,source:c}:null}function se(t){for(const e of O){const i=t.match(e);if(i)return i[1]}return null}function I(t){const e=t.trim();return/^\d+(?:\.\d+)*$/i.test(e)?`P${e}`.toUpperCase():e.toUpperCase()}function re(t){const e=I(t);return/^P\d+(?:\.\d+)?$/i.test(e)?`epic-${e}.md`:`epic-${t}.md`}function oe(t){const e=I(t);return/^P\d+\.\d+(?:\.\d+)?$/i.test(e)?`${e}.story.md`:`${t}.story.md`}function C(t,e){return!t||!e?!1:I(t)!==I(e)}function ce(t,e,i){return`frontmatter/filename mismatch: epic '${t}' has frontmatter id '${e}' but filename implies '${i}'. Repair by using generated canonical '${re(e)}' or changing frontmatter id to '${i}'.`}function ae(t,e,i){return`frontmatter/filename mismatch: story '${t}' has frontmatter id '${e}' but filename implies '${i}'. Repair by using generated canonical '${oe(e)}' or changing frontmatter id to '${i}'.`}function de(t){let e=t.match(D[0]);if(e){const i=e[1],n=i.indexOf(".");return{id:i,epic_id_hint:n>0?i.slice(0,n):null}}if(e=t.match(D[1]),e){const i=e[1],n=i.indexOf(".");return{id:i,epic_id_hint:n>0?i.slice(0,n):null}}if(e=t.match(D[2]),e){const i=e[1],n=e[2];return{id:`${i}.${n}`,epic_id_hint:i}}return null}function ue(t,e){return e.join(t,"..","stories")}function _e(t,e){const i=[],n=[],c=[],o=new Date().toISOString();if(typeof t!="string"||t.length===0)return Object.freeze({epics:Object.freeze([]),warnings:Object.freeze([]),skipped:Object.freeze([])});if(!e.isDirectory(t))return Object.freeze({epics:Object.freeze([]),warnings:Object.freeze([]),skipped:Object.freeze([])});const f=[...e.readdir(t)].sort(),l=[];for(const s of f){const u=e.join(t,s);if(T(s)){n.push(`${s}: ignored (draft or hidden prefix)`);continue}if(e.isDirectory(u)){if(ie(s)){n.push(`${s}: ignored subdirectory`);continue}n.push(`${s}: subdirectory not recursed`);continue}if(!s.endsWith(".md"))continue;if(!O.some(h=>h.test(s))){n.push(`${s}: did not match any EPIC_FILE_PATTERNS`);continue}const m=e.readFile(u),r=N(m,s);i.push(...r.warnings);const a=r.metadata,d=se(s);a.id&&C(a.id,d)&&i.push(r.source==="frontmatter"?ce(s,a.id,d):`legacy metadata/filename mismatch: epic '${s}' id does not match its filename`),l.push({filename:s,fullPath:u,metadata:a,metadataSource:r.source})}const _=new Map,g=[];for(const s of l){const u=ne(s.filename,s.metadata);if(u===null){n.push(`${s.filename}: id resolution returned null`);continue}let y=u.id;const m=y,r=_.get(m)??0;r>0&&(y=`${m}-${r+1}`,i.push(`epic ID collision: '${m}' resolved to '${y}' for ${s.filename}`)),_.set(m,r+1),g.push({candidate:s,finalId:y,idSource:s.metadataSource==="legacy-metadata"&&s.metadata.id?"legacy-metadata":u.source})}const p=new Map,b=ue(t,e);if(e.isDirectory(b)){const s=[...e.readdir(b)].sort();for(const u of s){if(T(u)||!u.endsWith(".md"))continue;const y=e.join(b,u);if(e.isDirectory(y))continue;const m=de(u);if(!m)continue;const r=e.readFile(y),a=N(r,u);i.push(...a.warnings);const d=a.metadata;d.id&&C(d.id,m.id)&&i.push(a.source==="frontmatter"?ae(u,d.id,m.id):`legacy metadata/filename mismatch: story '${u}' id does not match its filename`);const h=d.epic_id??m.epic_id_hint;if(!h){i.push(`story '${u}' has no epic_id (frontmatter or filename pattern)`);continue}const S=Object.freeze({id:m.id,epic_id:h,filename:u,path:y,...d.title?{title:d.title}:{},...d.status?{status:d.status}:{},...d.depends_on?{depends_on:d.depends_on}:{},...d.files_to_modify?{files_to_modify:d.files_to_modify}:{}});p.has(h)||p.set(h,[]),p.get(h).push(S)}}for(const s of g){const u=p.get(s.finalId)??[],y=Object.freeze({id:s.finalId,filename:s.candidate.filename,path:s.candidate.fullPath,...s.candidate.metadata.title?{title:s.candidate.metadata.title}:{},...s.candidate.metadata.status?{status:s.candidate.metadata.status}:{},...s.candidate.metadata.total_stories!==void 0?{total_stories:s.candidate.metadata.total_stories}:{},...s.candidate.metadata.depends_on?{depends_on:s.candidate.metadata.depends_on}:{},source:"discovered",discovered_at:o,stories:Object.freeze([...u]),t:s.idSource,e:s.candidate.metadataSource});c.push(y)}const $=new Set(c.map(s=>s.id));for(const[s,u]of p.entries())if(!$.has(s))for(const y of u)i.push(`orphan story '${y.filename}' references unknown epic '${s}'`);return Object.freeze({epics:Object.freeze(c),warnings:Object.freeze(i),skipped:Object.freeze(n)})}function M(t){const e=fe(t);return e==="done"||e==="completed"||e==="merged"}function A(t){return M(t)}function fe(t){return typeof t=="string"?t.trim().toLowerCase().replace(/[_\s]+/g,"-"):""}function E(t){return!!t&&typeof t=="object"&&!Array.isArray(t)}function w(t){throw new Error(`epic-aggregate-writer:${t}`)}function le(t){const e=[],i=new Set;for(const n of t)(typeof n!="string"||n.length===0)&&w("epic_aggregate_story_ref_invalid"),i.has(n)&&w("epic_aggregate_story_ref_duplicate"),i.add(n),e.push(n);return e}function pe(t,e,i){const n=i[e];return n===void 0&&w("epic_aggregate_story_missing"),E(n)||w("epic_aggregate_story_not_object"),n.id!==e&&w("epic_aggregate_story_id_conflict"),n.epic_id!==t&&w("epic_aggregate_story_epic_conflict"),n}function me(t,e,i,n,c){const o=e[t];E(o)||w("epic_aggregate_epic_not_object"),o.id!==t&&w("epic_aggregate_epic_id_conflict"),Array.isArray(o.stories)||w("epic_aggregate_story_list_not_array");const f=le(o.stories),l=f.length,_=f.filter(u=>M(pe(t,u,i).status)).length,g=c?.total_stories,p=c?.e==="legacy-metadata"&&A(o.status),b=p?g??l:l>0?l:g??0,$=p||l===0&&b>0&&A(o.status)?b:_,s=l>0&&_===l;A(o.status)&&!p&&!s&&l>0&&w("epic_aggregate_terminal_incomplete_conflict"),o.total_stories=b,o.completed_stories=$,!A(o.status)&&s&&(o.status="done",(o.completed_at===void 0||o.completed_at===null)&&(o.completed_at=n))}function ye(t,e,i){const n=t??{},c=E(n.epics)?n.epics:{},o=E(n.stories)?n.stories:{},f=structuredClone(c),l=structuredClone(o),_=[],g=[],p=new Set,b=new Map;let $=0;const s=i?.forceOverwrite===!0,u=i?.nowIso??new Date().toISOString(),y=new Set,m=new Map;for(const r of e.epics){if(!r.id||y.has(r.id))throw new Error("discovery_epic_identity_conflict");y.add(r.id),b.set(r.id,r);const a=f[r.id];if(a!==void 0&&(!E(a)||a.id!==void 0&&a.id!==r.id))throw new Error("discovery_epic_identity_conflict");for(const d of r.stories){if(!d.id||d.epic_id!==r.id||m.has(d.id))throw new Error("discovery_story_identity_conflict");m.set(d.id,r.id);const h=l[d.id];if(h!==void 0&&(!E(h)||h.id!==void 0&&h.id!==d.id||h.epic_id!==void 0&&h.epic_id!==r.id))throw new Error("discovery_story_identity_conflict")}}for(const r of e.epics){const a=f[r.id],d=a;if(d&&(d.branch_mode==="epic"||typeof d.execution_branch=="string")){g.push({id:r.id,reason:"epic Git lifecycle preserved"});continue}if(a&&a.source==="create-epic"&&!s){g.push({id:r.id,reason:"create-epic source preserved (defense)"});continue}if(a){const S=a;S.depends_on=r.depends_on??[];const v=Array.isArray(S.stories)?S.stories.filter(W=>typeof W=="string"):[];S.stories=[...new Set([...v,...r.stories.map(W=>W.id)])],r.title!==void 0&&(S.title=r.title),a.source!=="create-epic"&&p.add(r.id);continue}const h={id:r.id,title:r.title??"",status:r.status??"planning",source:"discovered",discovered_at:u,merged_at:u,stories:r.stories.map(S=>S.id),depends_on:r.depends_on??[]};f[r.id]=h,p.add(r.id),_.push(r.id)}for(const r of e.epics)for(const a of r.stories){const d=l[a.id],h=f[r.id];if(d&&h&&(h.branch_mode==="epic"||typeof h.execution_branch=="string")){g.push({id:a.id,reason:"story Git lifecycle preserved"});continue}if(d&&d.source==="create-epic"&&!s){g.push({id:a.id,reason:"create-epic source preserved (defense, story)"});continue}if(d){const v=d;a.title!==void 0&&(v.title=a.title),v.depends_on=a.depends_on??[],v.files_to_modify=a.files_to_modify??[];continue}const S={id:a.id,epic_id:a.epic_id,title:a.title??"",status:"backlog",source:"discovered",discovered_at:u,depends_on:a.depends_on??[],files_to_modify:a.files_to_modify??[]};l[a.id]=S,$++}for(const r of p)me(r,f,l,u,b.get(r));return n.epics=f,n.stories=l,{state:n,added:Object.freeze([..._]),skipped:Object.freeze([...g]),storiesAdded:$}}export{O as EPIC_FILE_PATTERNS,ge as GENERATED_NAMING_CONTRACT,D as STORY_FILE_PATTERNS,he as buildDefaultDiscoveryFs,_e as discoverEpicsFromDir,ne as getEpicIdFromDescriptor,ye as mergeDiscoveredIntoState};
+/**
+ * @license FSL-1.1
+ * Copyright (c) 2026 OrNexus AI
+ *
+ * This file is part of Neocortex CLI, licensed under the
+ * Functional Source License, Version 1.1 (FSL-1.1).
+ *
+ * Change Date: February 20, 2029
+ * Change License: MIT
+ *
+ * See the LICENSE file in the project root for full license text.
+ */
+// =====================================================================
+// Pattern arrays (2 readonly arrays per AC3)
+// =====================================================================
+/**
+ * Canonical naming contract for files generated by `*create-epic`.
+ *
+ * Discovery keeps accepting older forms for compatibility, but new generated
+ * files must use only the canonical values below.
+ */
+export const GENERATED_NAMING_CONTRACT = Object.freeze({
+    epicId: 'P{number}',
+    epicFilename: 'docs/epics/epic-P{number}.md',
+    storyId: 'P{number}.NN',
+    storyFilename: 'docs/stories/P{number}.NN.story.md',
+    acceptedOnly: Object.freeze({
+        epicFilenames: Object.freeze([
+            'docs/epics/epic-{number}.md',
+            'docs/epics/EPIC-{number}-{slug}.md',
+            'docs/epics/EPIC-{number}_{slug}.md',
+            'docs/epics/epic-{slug}.md',
+        ]),
+        storyFilenames: Object.freeze([
+            'docs/stories/{number}.NN.story.md',
+            'docs/stories/story-P{number}.NN.md',
+            'docs/stories/story-{number}.NN.md',
+            'docs/stories/EPIC-{number}.STORY-{number}.md',
+        ]),
+    }),
+});
+/**
+ * Three accepted epic filename conventions.
+ * Anchored regex (`^...$`) so partial matches are rejected.
+ *
+ *   - `[0]` generated canonical: `epic-P119.md`
+ *         accepted legacy:       `epic-92.5.md`, `epic-277.md`
+ *   - `[1]` accepted legacy:     `EPIC-01-foundation.md`, `EPIC-12_setup.md`
+ *   - `[2]` accepted legacy:     `epic-customer-portal.md`, `epic-feature-x.md`
+ *
+ * Group 1 is the canonical ID (or slug) extracted from the filename.
+ */
+export const EPIC_FILE_PATTERNS = Object.freeze([
+    /^epic-(P?\d+(?:\.\d+)?)\.md$/i,
+    /^EPIC-(\d+)(?:[-_].*)?\.md$/,
+    /^epic-([a-z0-9][a-z0-9_-]*)\.md$/i,
+]);
+/**
+ * Three accepted story filename conventions.
+ *
+ *   - `[0]` generated canonical: `P119.01.story.md`
+ *         accepted legacy:       `01.02.story.md`
+ *   - `[1]` accepted legacy:     `story-P104.04.md`
+ *   - `[2]` accepted legacy:     `EPIC-01.STORY-02.md`
+ *
+ * Group 1 = story ID for `[0]` and `[1]`. For `[2]`, group 1 = epic id,
+ * group 2 = story local id (composite).
+ *
+ * Pattern[0] accepts both `P119.01.story.md` (P-prefix) and `01.02.story.md`
+ * (numeric only) -- the `P?` prefix is optional.
+ */
+export const STORY_FILE_PATTERNS = Object.freeze([
+    /^(P?\d+\.\d+(?:\.\d+)?)\.story\.md$/i,
+    /^story-(P?\d+\.\d+)\.md$/i,
+    /^EPIC-(\d+)\.STORY-(\d+)\.md$/,
+]);
+/**
+ * Subdirectory names that are skipped (not recursed) during scan.
+ * Operators use these conventions for archival/draft separation.
+ */
+const IGNORED_SUBDIRS = Object.freeze([
+    '.archive',
+    '_archive',
+    '_archives',
+    '_drafts',
+    'archive',
+    'archives',
+    'archived',
+    'drafts',
+]);
+// =====================================================================
+// Helpers (internal, not exported)
+// =====================================================================
+/** Pre-compiled YAML frontmatter regex (top-of-file `---\n...\n---`). */
+const FRONTMATTER_RE = /^---\s*\n([\s\S]*?)\n---/;
+/** Field extractors -- trim + strip surrounding quotes if any. */
+function parseField(block, key) {
+    const re = new RegExp(`^${key}:\\s*(.+?)\\s*$`, 'mi');
+    const match = block.match(re);
+    if (!match)
+        return undefined;
+    let value = match[1].trim();
+    // Strip wrapping quotes (single or double)
+    if ((value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'"))) {
+        value = value.slice(1, -1);
+    }
+    return value || undefined;
+}
+/**
+ * Lightweight regex-only frontmatter parser.
+ * No js-yaml dependency: only the bounded discovery fields are extracted.
+ * Malformed frontmatter (no closing `---`, extra `:`) returns empty object.
+ */
+function parseFrontmatter(content) {
+    if (typeof content !== 'string' || content.length === 0)
+        return {};
+    const match = content.match(FRONTMATTER_RE);
+    if (!match)
+        return {};
+    const block = match[1];
+    return {
+        id: parseField(block, 'id'),
+        title: parseField(block, 'title'),
+        status: parseField(block, 'status'),
+        epic_id: parseField(block, 'epic_id'),
+        depends_on: parseDependencyField(block),
+        files_to_modify: parseStringListField(block, 'files_to_modify'),
+        total_stories: parseNonNegativeInteger(parseField(block, 'total_stories')),
+    };
+}
+const LEGACY_HEADER_MAX_LINES = 32;
+const LEGACY_HEADER_MAX_CHARS = 4_096;
+const LEGACY_FIELD_RE = /^\s*\*\*([^*\r\n]+?):\*\*\s*(.*?)\s*$/;
+const LEGACY_KNOWN_STATUSES = new Set([
+    'backlog', 'pending', 'ready', 'planning', 'in-progress',
+    'done', 'completed', 'merged', 'cancelled', 'canceled', 'abandoned',
+    'draft', 'template', 'archived', 'branch-ready', 'diagnose', 'research',
+    'write-spec', 'create-tasks', 'implemented', 'refactor-suggest-done',
+    'property-tests-emitted', 'tests-validated', 'qa-gate-passed',
+    'memory-updated', 'committed', 'synced', 'pr-created', 'pr-reviewed', 'partial',
+]);
+function stripLegacyMarkup(raw) {
+    let value = raw.trim();
+    if (value.startsWith('`') && value.endsWith('`') && value.length >= 2) {
+        value = value.slice(1, -1).trim();
+    }
+    if ((value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'"))) {
+        value = value.slice(1, -1).trim();
+    }
+    return value;
+}
+function parseNonNegativeInteger(raw) {
+    if (raw === undefined || !/^\d{1,5}$/.test(raw.trim()))
+        return undefined;
+    const parsed = Number(raw);
+    return Number.isSafeInteger(parsed) ? parsed : undefined;
+}
+function normalizeLegacyStatus(raw) {
+    const normalized = stripLegacyMarkup(raw).toLowerCase().replace(/[_\s]+/g, '-');
+    const aliases = {
+        planned: 'planning',
+        complete: 'completed',
+        closed: 'done',
+        finished: 'done',
+    };
+    const canonical = aliases[normalized] ?? normalized;
+    return LEGACY_KNOWN_STATUSES.has(canonical) ? canonical : undefined;
+}
+function normalizeLegacyLabel(raw) {
+    const label = raw.trim().toLowerCase().replace(/[_-]+/g, ' ').replace(/\s+/g, ' ');
+    if (label === 'id' || label === 'epic id')
+        return 'id';
+    if (label === 'title' || label === 'titulo')
+        return 'title';
+    if (label === 'status')
+        return 'status';
+    if (label === 'total stories' || label === 'total de stories')
+        return 'total_stories';
+    return undefined;
+}
+function legacyHeadingTitle(lines) {
+    const heading = lines.find((line) => /^#\s+\S/.test(line));
+    if (!heading)
+        return undefined;
+    const value = heading.replace(/^#\s+/, '').trim();
+    const withoutPrefix = value.replace(/^(?:Epic|Story)\s+\S+\s*(?:(?:--?|:)|[\u2013\u2014])\s*/i, '');
+    return (withoutPrefix || value).slice(0, 200);
+}
+function selectLegacyValue(values, field, filename, warnings) {
+    const normalized = [...new Set(values.map(stripLegacyMarkup).filter(Boolean))];
+    if (normalized.length > 1) {
+        warnings.push(`legacy metadata ambiguous for '${field}' in '${filename}': conflicting values ignored`);
+        return undefined;
+    }
+    return normalized[0];
+}
+function parseLegacyMetadata(content, filename) {
+    const warnings = [];
+    const lines = [];
+    const boundedLines = content.slice(0, LEGACY_HEADER_MAX_CHARS).split(/\r?\n/, LEGACY_HEADER_MAX_LINES);
+    for (const line of boundedLines) {
+        if (lines.length > 0 && (/^\s*---\s*$/.test(line) || /^##\s+/.test(line)))
+            break;
+        lines.push(line);
+    }
+    const values = new Map();
+    for (const line of lines) {
+        const match = line.match(LEGACY_FIELD_RE);
+        if (!match)
+            continue;
+        const field = normalizeLegacyLabel(match[1]);
+        if (!field)
+            continue;
+        const current = values.get(field) ?? [];
+        current.push(match[2]);
+        values.set(field, current);
+    }
+    const id = selectLegacyValue(values.get('id') ?? [], 'id', filename, warnings);
+    const explicitTitle = selectLegacyValue(values.get('title') ?? [], 'title', filename, warnings);
+    const rawStatus = selectLegacyValue(values.get('status') ?? [], 'status', filename, warnings);
+    const rawTotalStories = selectLegacyValue(values.get('total_stories') ?? [], 'total_stories', filename, warnings);
+    const status = rawStatus === undefined ? undefined : normalizeLegacyStatus(rawStatus);
+    if (rawStatus !== undefined && status === undefined) {
+        warnings.push(`legacy metadata status unrecognized in '${filename}': value ignored`);
+    }
+    const totalStories = parseNonNegativeInteger(rawTotalStories);
+    if (rawTotalStories !== undefined && totalStories === undefined) {
+        warnings.push(`legacy metadata total_stories invalid in '${filename}': value ignored`);
+    }
+    const safeId = id && /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/.test(id) ? id : undefined;
+    if (id !== undefined && safeId === undefined) {
+        warnings.push(`legacy metadata id invalid in '${filename}': value ignored`);
+    }
+    const headingTitle = legacyHeadingTitle(lines);
+    const title = explicitTitle ?? headingTitle;
+    const metadata = {
+        ...(safeId ? { id: safeId } : {}),
+        ...(title ? { title: title.slice(0, 200) } : {}),
+        ...(status ? { status } : {}),
+        ...(totalStories !== undefined ? { total_stories: totalStories } : {}),
+    };
+    return { metadata, source: 'legacy-metadata', warnings: Object.freeze(warnings) };
+}
+function safeDiagnosticFilename(filename) {
+    return /^[A-Za-z0-9._-]{1,160}$/.test(filename) ? filename : 'markdown-target.md';
+}
+function utf8ByteLength(value) {
+    return new TextEncoder().encode(value).length;
+}
+function hasUnsupportedFrontmatterShape(block) {
+    let listAllowed = false;
+    for (const rawLine of block.split(/\r?\n/)) {
+        if (!rawLine.trim() || rawLine.trimStart().startsWith('#'))
+            continue;
+        const listItem = rawLine.match(/^\s+-\s+(.+?)\s*$/);
+        if (listItem) {
+            if (!listAllowed)
+                return true;
+            const value = listItem[1].trim();
+            if ((value.startsWith('"') && !value.endsWith('"')) ||
+                (value.startsWith("'") && !value.endsWith("'")))
+                return true;
+            continue;
+        }
+        if (/^\s+/.test(rawLine))
+            return true;
+        const field = rawLine.match(/^[A-Za-z0-9_-]+:\s*(.*?)\s*$/);
+        if (!field)
+            return true;
+        const value = field[1].trim();
+        listAllowed = value.length === 0;
+        if ((value.startsWith('"') && !value.endsWith('"')) ||
+            (value.startsWith("'") && !value.endsWith("'")))
+            return true;
+    }
+    return false;
+}
+function frontmatterDiagnosticWarnings(content, filename, metadata) {
+    const safeFilename = safeDiagnosticFilename(filename);
+    const match = content.match(FRONTMATTER_RE);
+    if (!match) {
+        return Object.freeze([
+            `metadata-frontmatter reason=frontmatter-malformed file='${safeFilename}': repair the bounded leading YAML envelope; source content omitted`,
+        ]);
+    }
+    const block = match[1];
+    if (utf8ByteLength(block) > 8 * 1024 || block.split(/\r?\n/).length > 128) {
+        return Object.freeze([
+            `metadata-frontmatter reason=frontmatter-oversized file='${safeFilename}': reduce the leading YAML envelope; source content omitted`,
+        ]);
+    }
+    if (hasUnsupportedFrontmatterShape(block) ||
+        (block.trim().length > 0 && Object.keys(metadata).length === 0)) {
+        return Object.freeze([
+            `metadata-frontmatter reason=frontmatter-unsupported-value file='${safeFilename}': use bounded scalar fields or string lists; source content omitted`,
+        ]);
+    }
+    return Object.freeze([]);
+}
+function parseDescriptorMetadata(content, filename) {
+    if (/^---(?:\s*\r?\n|\s*$)/.test(content)) {
+        const metadata = parseFrontmatter(content);
+        return {
+            metadata,
+            source: 'frontmatter',
+            warnings: frontmatterDiagnosticWarnings(content, filename, metadata),
+        };
+    }
+    if (typeof content !== 'string' || content.length === 0) {
+        return { metadata: {}, source: 'none', warnings: Object.freeze([]) };
+    }
+    return parseLegacyMetadata(content, filename);
+}
+function normalizeDependencyToken(raw) {
+    let value = raw.trim();
+    if ((value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'"))) {
+        value = value.slice(1, -1).trim();
+    }
+    if (!value)
+        return undefined;
+    if (/^(null|undefined|true|false)$/i.test(value))
+        return undefined;
+    return value;
+}
+function parseDependencyField(block) {
+    return parseStringListField(block, 'depends_on');
+}
+function parseStringListField(block, fieldName) {
+    const escapedField = fieldName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const inlineMatch = block.match(new RegExp(`^${escapedField}:[ \\t]*(.+?)[ \\t]*$`, 'mi'));
+    const inline = inlineMatch?.[1]?.trim();
+    if (inline !== undefined) {
+        const rawItems = inline.startsWith('[') && inline.endsWith(']')
+            ? inline.slice(1, -1).split(',')
+            : [inline];
+        const items = rawItems
+            .map(normalizeDependencyToken)
+            .filter((d) => typeof d === 'string' && d.length > 0);
+        return items.length > 0 ? Object.freeze(items) : undefined;
+    }
+    const lines = block.split(/\r?\n/);
+    const items = [];
+    let inListBlock = false;
+    for (const line of lines) {
+        if (!inListBlock) {
+            if (new RegExp(`^${escapedField}:\\s*$`, 'i').test(line.trim())) {
+                inListBlock = true;
+            }
+            continue;
+        }
+        if (/^[A-Za-z0-9_-]+:\s*/.test(line))
+            break;
+        const match = line.match(/^\s*-\s*(.+?)\s*$/);
+        if (!match)
+            continue;
+        const value = normalizeDependencyToken(match[1]);
+        if (value)
+            items.push(value);
+    }
+    return items.length > 0 ? Object.freeze(items) : undefined;
+}
+/**
+ * Test if a basename should be ignored (drafts/hidden).
+ * Anchored on prefix only (`_*`, `.*`).
+ */
+function isIgnoredFile(basename) {
+    return basename.startsWith('_') || basename.startsWith('.');
+}
+/**
+ * Test if a subdirectory name should be skipped.
+ */
+function isIgnoredSubdir(name) {
+    return IGNORED_SUBDIRS.includes(name);
+}
+/**
+ * Default filesystem adapter wrapping `node:fs` synchronous APIs.
+ * Lazy-loaded via dynamic require so this module is safe to import in
+ * non-Node environments (browser bundles tree-shake unused calls).
+ *
+ * @example
+ * ```ts
+ * const fs = await buildDefaultDiscoveryFs();
+ * const result = discoverEpicsFromDir(dir, fs);
+ * ```
+ */
+export async function buildDefaultDiscoveryFs() {
+    const fsModule = await import('node:fs');
+    const pathModule = await import('node:path');
+    return {
+        isDirectory(p) {
+            try {
+                return fsModule.statSync(p).isDirectory();
+            }
+            catch {
+                return false;
+            }
+        },
+        readdir(p) {
+            try {
+                return fsModule.readdirSync(p);
+            }
+            catch {
+                return [];
+            }
+        },
+        readFile(p) {
+            try {
+                return fsModule.readFileSync(p, 'utf8');
+            }
+            catch {
+                return '';
+            }
+        },
+        join(...parts) {
+            try {
+                return pathModule.join(...parts);
+            }
+            catch {
+                return parts.join('/');
+            }
+        },
+    };
+}
+// =====================================================================
+// Public API
+// =====================================================================
+/**
+ * Resolve canonical epic ID from filename + frontmatter.
+ *
+ * Priority (highest to lowest):
+ *   1. Frontmatter `id:` field (operator-authoritative)
+ *   2. `EPIC_FILE_PATTERNS[0]` canonical (numeric or P-prefix)
+ *   3. `EPIC_FILE_PATTERNS[1]` uppercase numeric
+ *   4. `EPIC_FILE_PATTERNS[2]` alpha-slug fallback
+ *
+ * Returns `null` if no pattern matches AND no frontmatter id.
+ *
+ * @param filename basename only (e.g., `epic-P119.md`)
+ * @param frontmatter parsed frontmatter (may have `id?: string`)
+ */
+export function getEpicIdFromDescriptor(filename, frontmatter) {
+    // Priority 1: frontmatter id (only if pattern at least matches the
+    // filename shape -- prevents arbitrary files claiming to be epics)
+    let patternMatched = false;
+    let patternId = null;
+    let patternSource = null;
+    for (let i = 0; i < EPIC_FILE_PATTERNS.length; i++) {
+        const re = EPIC_FILE_PATTERNS[i];
+        const match = filename.match(re);
+        if (match) {
+            patternMatched = true;
+            patternId = match[1];
+            patternSource = i === 2 ? 'filename-slug' : 'filename-canonical';
+            break;
+        }
+    }
+    if (!patternMatched) {
+        // Filename did NOT match any epic pattern -- not an epic at all.
+        return null;
+    }
+    // Frontmatter id wins if present
+    if (frontmatter.id && frontmatter.id.length > 0) {
+        return { id: frontmatter.id, source: 'frontmatter' };
+    }
+    return { id: patternId, source: patternSource };
+}
+function getEpicIdFromFilename(filename) {
+    for (const re of EPIC_FILE_PATTERNS) {
+        const match = filename.match(re);
+        if (match)
+            return match[1];
+    }
+    return null;
+}
+function normalizeGeneratedComparableId(id) {
+    const trimmed = id.trim();
+    if (/^\d+(?:\.\d+)*$/i.test(trimmed))
+        return `P${trimmed}`.toUpperCase();
+    return trimmed.toUpperCase();
+}
+function canonicalEpicFilenameFor(id) {
+    const normalized = normalizeGeneratedComparableId(id);
+    return /^P\d+(?:\.\d+)?$/i.test(normalized)
+        ? `epic-${normalized}.md`
+        : `epic-${id}.md`;
+}
+function canonicalStoryFilenameFor(id) {
+    const normalized = normalizeGeneratedComparableId(id);
+    return /^P\d+\.\d+(?:\.\d+)?$/i.test(normalized)
+        ? `${normalized}.story.md`
+        : `${id}.story.md`;
+}
+function idsDiffer(frontmatterId, filenameId) {
+    if (!frontmatterId || !filenameId)
+        return false;
+    return normalizeGeneratedComparableId(frontmatterId) !== normalizeGeneratedComparableId(filenameId);
+}
+function epicMismatchWarning(filename, frontmatterId, filenameId) {
+    return `frontmatter/filename mismatch: epic '${filename}' has frontmatter id '${frontmatterId}' but filename implies '${filenameId}'. Repair by using generated canonical '${canonicalEpicFilenameFor(frontmatterId)}' or changing frontmatter id to '${filenameId}'.`;
+}
+function storyMismatchWarning(filename, frontmatterId, filenameId) {
+    return `frontmatter/filename mismatch: story '${filename}' has frontmatter id '${frontmatterId}' but filename implies '${filenameId}'. Repair by using generated canonical '${canonicalStoryFilenameFor(frontmatterId)}' or changing frontmatter id to '${filenameId}'.`;
+}
+/**
+ * Match a story filename and extract its canonical ID.
+ * Returns null if no story pattern matches.
+ */
+function matchStoryFilename(filename) {
+    // Pattern [0] canonical: P119.01.story.md
+    let m = filename.match(STORY_FILE_PATTERNS[0]);
+    if (m) {
+        const id = m[1];
+        // Hint: epic_id is the prefix before the dot (P119.01 -> P119)
+        const dotIdx = id.indexOf('.');
+        return {
+            id,
+            epic_id_hint: dotIdx > 0 ? id.slice(0, dotIdx) : null,
+        };
+    }
+    // Pattern [1] legacy: story-P104.04.md
+    m = filename.match(STORY_FILE_PATTERNS[1]);
+    if (m) {
+        const id = m[1];
+        const dotIdx = id.indexOf('.');
+        return {
+            id,
+            epic_id_hint: dotIdx > 0 ? id.slice(0, dotIdx) : null,
+        };
+    }
+    // Pattern [2] uppercase: EPIC-01.STORY-02.md
+    m = filename.match(STORY_FILE_PATTERNS[2]);
+    if (m) {
+        const epicNum = m[1];
+        const storyNum = m[2];
+        return {
+            id: `${epicNum}.${storyNum}`,
+            epic_id_hint: epicNum,
+        };
+    }
+    return null;
+}
+/**
+ * Locate the stories directory adjacent to the epics directory.
+ * Convention: `<dir>/../stories/`. Returns the path string regardless of
+ * existence (caller checks via fs adapter).
+ */
+function inferStoriesDir(epicsDir, fs) {
+    return fs.join(epicsDir, '..', 'stories');
+}
+/**
+ * Scan `dir` for epic markdown files and return discovered descriptors.
+ *
+ * Behavior:
+ *   - Non-recursive scan of `dir/*.md`
+ *   - Sibling stories directory at `<dir>/../stories/*.story.md` (if exists)
+ *   - Files with prefix `_` or `.` are skipped (drafts, hidden)
+ *   - Subdirectories listed in `IGNORED_SUBDIRS` are not recursed
+ *   - Frontmatter parser extracts `id`, `title`, `status`, `epic_id`
+ *   - ID derivation: frontmatter > canonical regex > slug fallback
+ *   - Slug collision: 2nd file with same canonical ID gets `-2`, `-3` suffix + warning
+ *   - Story-to-epic linking: prefer frontmatter `epic_id` field, fallback filename pattern
+ *   - Default fs adapter wraps `node:fs` synchronous methods (lazy-loaded)
+ *
+ * @param dir absolute or relative path to the epics directory
+ * @param fs optional fs adapter; defaults to `node:fs` wrapper (lazy)
+ * @returns DiscoveryResult with epics, warnings, skipped arrays
+ */
+export function discoverEpicsFromDir(dir, fs) {
+    const warnings = [];
+    const skipped = [];
+    const epics = [];
+    const discoveredAt = new Date().toISOString();
+    // Defensive guard: dir must be a non-empty string
+    if (typeof dir !== 'string' || dir.length === 0) {
+        return Object.freeze({
+            epics: Object.freeze([]),
+            warnings: Object.freeze([]),
+            skipped: Object.freeze([]),
+        });
+    }
+    // Skip discovery if dir doesn't exist (fail-open)
+    if (!fs.isDirectory(dir)) {
+        return Object.freeze({
+            epics: Object.freeze([]),
+            warnings: Object.freeze([]),
+            skipped: Object.freeze([]),
+        });
+    }
+    const entries = [...fs.readdir(dir)].sort();
+    const candidates = [];
+    for (const entry of entries) {
+        const fullPath = fs.join(dir, entry);
+        if (isIgnoredFile(entry)) {
+            skipped.push(`${entry}: ignored (draft or hidden prefix)`);
+            continue;
+        }
+        if (fs.isDirectory(fullPath)) {
+            if (isIgnoredSubdir(entry)) {
+                skipped.push(`${entry}: ignored subdirectory`);
+                continue;
+            }
+            // Other subdirs: not recursed (P120 is non-recursive)
+            skipped.push(`${entry}: subdirectory not recursed`);
+            continue;
+        }
+        if (!entry.endsWith('.md')) {
+            // Not markdown -- silently skip
+            continue;
+        }
+        // Quick filename match check before parsing frontmatter
+        const matchesEpic = EPIC_FILE_PATTERNS.some((re) => re.test(entry));
+        if (!matchesEpic) {
+            skipped.push(`${entry}: did not match any EPIC_FILE_PATTERNS`);
+            continue;
+        }
+        const content = fs.readFile(fullPath);
+        const parsed = parseDescriptorMetadata(content, entry);
+        warnings.push(...parsed.warnings);
+        const metadata = parsed.metadata;
+        const filenameId = getEpicIdFromFilename(entry);
+        if (metadata.id && idsDiffer(metadata.id, filenameId)) {
+            warnings.push(parsed.source === 'frontmatter'
+                ? epicMismatchWarning(entry, metadata.id, filenameId)
+                : `legacy metadata/filename mismatch: epic '${entry}' id does not match its filename`);
+        }
+        candidates.push({ filename: entry, fullPath, metadata, metadataSource: parsed.source });
+    }
+    // ID resolution + collision tracking
+    const idCount = new Map();
+    const resolved = [];
+    for (const candidate of candidates) {
+        const idResult = getEpicIdFromDescriptor(candidate.filename, candidate.metadata);
+        if (idResult === null) {
+            // Should not happen since we pre-filtered, but defensive
+            skipped.push(`${candidate.filename}: id resolution returned null`);
+            continue;
+        }
+        let finalId = idResult.id;
+        // Collision suffix only for filename-slug source (frontmatter / canonical
+        // are already operator-deterministic; collisions there are user error)
+        const baseId = finalId;
+        const prevCount = idCount.get(baseId) ?? 0;
+        if (prevCount > 0) {
+            finalId = `${baseId}-${prevCount + 1}`;
+            warnings.push(`epic ID collision: '${baseId}' resolved to '${finalId}' for ${candidate.filename}`);
+        }
+        idCount.set(baseId, prevCount + 1);
+        resolved.push({
+            candidate,
+            finalId,
+            idSource: candidate.metadataSource === 'legacy-metadata' && candidate.metadata.id
+                ? 'legacy-metadata'
+                : idResult.source,
+        });
+    }
+    // Discover stories from sibling stories/ dir
+    const storiesByEpic = new Map();
+    const storiesDir = inferStoriesDir(dir, fs);
+    if (fs.isDirectory(storiesDir)) {
+        const storyEntries = [...fs.readdir(storiesDir)].sort();
+        for (const entry of storyEntries) {
+            if (isIgnoredFile(entry))
+                continue;
+            if (!entry.endsWith('.md'))
+                continue;
+            const fullPath = fs.join(storiesDir, entry);
+            if (fs.isDirectory(fullPath))
+                continue;
+            const storyMatch = matchStoryFilename(entry);
+            if (!storyMatch)
+                continue;
+            const content = fs.readFile(fullPath);
+            const parsed = parseDescriptorMetadata(content, entry);
+            warnings.push(...parsed.warnings);
+            const fm = parsed.metadata;
+            if (fm.id && idsDiffer(fm.id, storyMatch.id)) {
+                warnings.push(parsed.source === 'frontmatter'
+                    ? storyMismatchWarning(entry, fm.id, storyMatch.id)
+                    : `legacy metadata/filename mismatch: story '${entry}' id does not match its filename`);
+            }
+            // Link priority: frontmatter epic_id > filename pattern hint
+            const epicId = fm.epic_id ?? storyMatch.epic_id_hint;
+            if (!epicId) {
+                warnings.push(`story '${entry}' has no epic_id (frontmatter or filename pattern)`);
+                continue;
+            }
+            const story = Object.freeze({
+                id: storyMatch.id,
+                epic_id: epicId,
+                filename: entry,
+                path: fullPath,
+                ...(fm.title ? { title: fm.title } : {}),
+                ...(fm.status ? { status: fm.status } : {}),
+                ...(fm.depends_on ? { depends_on: fm.depends_on } : {}),
+                ...(fm.files_to_modify ? { files_to_modify: fm.files_to_modify } : {}),
+            });
+            if (!storiesByEpic.has(epicId)) {
+                storiesByEpic.set(epicId, []);
+            }
+            storiesByEpic.get(epicId).push(story);
+        }
+    }
+    // Build final EpicDescriptor list
+    for (const r of resolved) {
+        const stories = storiesByEpic.get(r.finalId) ?? [];
+        const desc = Object.freeze({
+            id: r.finalId,
+            filename: r.candidate.filename,
+            path: r.candidate.fullPath,
+            ...(r.candidate.metadata.title ? { title: r.candidate.metadata.title } : {}),
+            ...(r.candidate.metadata.status ? { status: r.candidate.metadata.status } : {}),
+            ...(r.candidate.metadata.total_stories !== undefined ? { total_stories: r.candidate.metadata.total_stories } : {}),
+            ...(r.candidate.metadata.depends_on ? { depends_on: r.candidate.metadata.depends_on } : {}),
+            source: 'discovered',
+            discovered_at: discoveredAt,
+            stories: Object.freeze([...stories]),
+            _idSource: r.idSource,
+            _metadataSource: r.candidate.metadataSource,
+        });
+        epics.push(desc);
+    }
+    // Identify orphan stories (epic_id points to non-existent epic)
+    const knownEpicIds = new Set(epics.map((e) => e.id));
+    for (const [epicId, stories] of storiesByEpic.entries()) {
+        if (!knownEpicIds.has(epicId)) {
+            for (const s of stories) {
+                warnings.push(`orphan story '${s.filename}' references unknown epic '${epicId}'`);
+            }
+        }
+    }
+    return Object.freeze({
+        epics: Object.freeze(epics),
+        warnings: Object.freeze(warnings),
+        skipped: Object.freeze(skipped),
+    });
+}
+function isDoneLikeStoryStatus(status) {
+    const normalized = normalizePublicStatus(status);
+    return normalized === 'done' || normalized === 'completed' || normalized === 'merged';
+}
+function isTerminalEpicStatus(status) {
+    return isDoneLikeStoryStatus(status);
+}
+function normalizePublicStatus(status) {
+    return typeof status === 'string' ? status.trim().toLowerCase().replace(/[_\s]+/g, '-') : '';
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function aggregateHardStop(reasonCode) {
+    throw new Error(`epic-aggregate-writer:${reasonCode}`);
+}
+function validateAggregateStoryRefs(storyRefs) {
+    const storyIds = [];
+    const seen = new Set();
+    for (const storyRef of storyRefs) {
+        if (typeof storyRef !== 'string' || storyRef.length === 0) {
+            aggregateHardStop('epic_aggregate_story_ref_invalid');
+        }
+        if (seen.has(storyRef))
+            aggregateHardStop('epic_aggregate_story_ref_duplicate');
+        seen.add(storyRef);
+        storyIds.push(storyRef);
+    }
+    return storyIds;
+}
+function validateAggregateListedStory(epicId, storyId, storiesMap) {
+    const story = storiesMap[storyId];
+    if (story === undefined)
+        aggregateHardStop('epic_aggregate_story_missing');
+    if (!isRecord(story))
+        aggregateHardStop('epic_aggregate_story_not_object');
+    if (story.id !== storyId)
+        aggregateHardStop('epic_aggregate_story_id_conflict');
+    if (story.epic_id !== epicId)
+        aggregateHardStop('epic_aggregate_story_epic_conflict');
+    return story;
+}
+function recomputeDiscoveredEpicAggregate(epicId, epicsMap, storiesMap, nowIso, descriptor) {
+    const epic = epicsMap[epicId];
+    if (!isRecord(epic))
+        aggregateHardStop('epic_aggregate_epic_not_object');
+    if (epic.id !== epicId)
+        aggregateHardStop('epic_aggregate_epic_id_conflict');
+    if (!Array.isArray(epic.stories))
+        aggregateHardStop('epic_aggregate_story_list_not_array');
+    const storyIds = validateAggregateStoryRefs(epic.stories);
+    const linkedStories = storyIds.length;
+    const linkedCompletedStories = storyIds.filter((storyId) => isDoneLikeStoryStatus(validateAggregateListedStory(epicId, storyId, storiesMap).status)).length;
+    const declaredTotalStories = descriptor?.total_stories;
+    const legacyTerminalMetadata = descriptor?._metadataSource === 'legacy-metadata' &&
+        isTerminalEpicStatus(epic.status);
+    const totalStories = legacyTerminalMetadata
+        ? declaredTotalStories ?? linkedStories
+        : linkedStories > 0
+            ? linkedStories
+            : declaredTotalStories ?? 0;
+    const completedStories = legacyTerminalMetadata ||
+        (linkedStories === 0 && totalStories > 0 && isTerminalEpicStatus(epic.status))
+        ? totalStories
+        : linkedCompletedStories;
+    const allListedStoriesDoneLike = linkedStories > 0 && linkedCompletedStories === linkedStories;
+    if (isTerminalEpicStatus(epic.status) && !legacyTerminalMetadata &&
+        !allListedStoriesDoneLike && linkedStories > 0) {
+        aggregateHardStop('epic_aggregate_terminal_incomplete_conflict');
+    }
+    epic.total_stories = totalStories;
+    epic.completed_stories = completedStories;
+    if (!isTerminalEpicStatus(epic.status) && allListedStoriesDoneLike) {
+        epic.status = 'done';
+        if (epic.completed_at === undefined || epic.completed_at === null) {
+            epic.completed_at = nowIso;
+        }
+    }
+}
+/**
+ * Merge `DiscoveryResult` (from `discoverEpicsFromDir`) into a `state` object,
+ * preserving canonical `*create-epic`-registered entries unless `forceOverwrite`.
+ *
+ * **Critical defense**: the non-overwrite guard prevents discovered entries
+ * from clobbering valuable canonical registrations. Even with `forceOverwrite:
+ * true`, the function preserves the existing `source` field for audit trail.
+ *
+ * **Idempotency**: re-running merge with the same `discovered` + same `state`
+ * produces identical output (no duplicate stories, timestamps from first run
+ * preserved). Critical for `/loop` iteration which may re-invoke discovery
+ * between stories.
+ *
+ * **Mutation semantics**: merge work is staged on cloned maps and committed to
+ * the caller-owned container only after every identity and aggregate invariant
+ * passes. Validation failures therefore provide strong exception safety.
+ *
+ * @param state target state object (`null`/`undefined` ok -- treated as empty)
+ * @param discovered discovery result (epics + warnings + skipped)
+ * @param options optional behavior modifiers
+ * @returns `MergeResult` with mutated state + telemetry counters
+ *
+ * @example
+ * ```ts
+ * const result = mergeDiscoveredIntoState(state, discovered);
+ * if (result.skipped.length > 0) {
+ *   console.warn('skipped:', result.skipped);
+ * }
+ * console.info(`merged ${result.added.length} epics, ${result.storiesAdded} stories`);
+ * ```
+ */
+export function mergeDiscoveredIntoState(state, discovered, options) {
+    // AC4: defensive null guard -- treat null/undefined state as empty containers.
+    // Existing maps remain untouched until the final two-field commit.
+    const safeState = state ?? {};
+    const currentEpics = isRecord(safeState.epics) ? safeState.epics : {};
+    const currentStories = isRecord(safeState.stories) ? safeState.stories : {};
+    const epicsMap = structuredClone(currentEpics);
+    const storiesMap = structuredClone(currentStories);
+    const added = [];
+    const skipped = [];
+    const aggregateEpicIds = new Set();
+    const aggregateDescriptors = new Map();
+    let storiesAdded = 0;
+    const forceOverwrite = options?.forceOverwrite === true;
+    const nowIso = options?.nowIso ?? new Date().toISOString();
+    // Track which epic IDs are part of THIS discovery batch (for orphan story detection)
+    const discoveredEpicIds = new Set();
+    const discoveredStoryOwners = new Map();
+    for (const epic of discovered.epics) {
+        if (!epic.id || discoveredEpicIds.has(epic.id)) {
+            throw new Error('discovery_epic_identity_conflict');
+        }
+        discoveredEpicIds.add(epic.id);
+        aggregateDescriptors.set(epic.id, epic);
+        const existingEpic = epicsMap[epic.id];
+        if (existingEpic !== undefined && (!isRecord(existingEpic) ||
+            existingEpic.id !== undefined && existingEpic.id !== epic.id)) {
+            throw new Error('discovery_epic_identity_conflict');
+        }
+        for (const story of epic.stories) {
+            if (!story.id || story.epic_id !== epic.id || discoveredStoryOwners.has(story.id)) {
+                throw new Error('discovery_story_identity_conflict');
+            }
+            discoveredStoryOwners.set(story.id, epic.id);
+            const existingStory = storiesMap[story.id];
+            if (existingStory !== undefined && (!isRecord(existingStory) ||
+                existingStory.id !== undefined && existingStory.id !== story.id ||
+                existingStory.epic_id !== undefined && existingStory.epic_id !== epic.id)) {
+                throw new Error('discovery_story_identity_conflict');
+            }
+        }
+    }
+    // -------------------------------------------------------------------
+    // Pass 1: merge epics
+    // -------------------------------------------------------------------
+    for (const epic of discovered.epics) {
+        const existing = epicsMap[epic.id];
+        // Filesystem discovery supplies descriptors, never physical Git authority.
+        // Preserve lifecycle state even when legacy records have no source marker.
+        const lifecycle = existing;
+        if (lifecycle && (lifecycle.branch_mode === 'epic' || typeof lifecycle.execution_branch === 'string')) {
+            skipped.push({ id: epic.id, reason: 'epic Git lifecycle preserved' });
+            continue;
+        }
+        // AC2: non-overwrite guard (default behavior)
+        if (existing && existing.source === 'create-epic' && !forceOverwrite) {
+            skipped.push({
+                id: epic.id,
+                reason: 'create-epic source preserved (defense)',
+            });
+            continue;
+        }
+        // Existing state owns lifecycle and unknown fields regardless of provenance.
+        // Discovery may only enrich bounded specification metadata.
+        if (existing) {
+            const existingRecord = existing;
+            existingRecord.depends_on = epic.depends_on ?? [];
+            const existingStoryIds = Array.isArray(existingRecord.stories)
+                ? existingRecord.stories.filter((id) => typeof id === 'string')
+                : [];
+            existingRecord.stories = [...new Set([
+                    ...existingStoryIds,
+                    ...epic.stories.map((story) => story.id),
+                ])];
+            if (epic.title !== undefined)
+                existingRecord.title = epic.title;
+            if (existing.source !== 'create-epic')
+                aggregateEpicIds.add(epic.id);
+            // Already merged previously -- skip without churning timestamps
+            // (NOT in skipped[] because this is normal idempotent flow, not a
+            // defense rejection)
+            continue;
+        }
+        // Build new entry (or overwrite when forceOverwrite is set)
+        const newEntry = {
+            id: epic.id,
+            title: epic.title ?? '',
+            status: epic.status ?? 'planning',
+            source: 'discovered',
+            discovered_at: nowIso,
+            merged_at: nowIso,
+            stories: epic.stories.map((s) => s.id),
+            depends_on: epic.depends_on ?? [],
+        };
+        epicsMap[epic.id] = newEntry;
+        aggregateEpicIds.add(epic.id);
+        added.push(epic.id);
+    }
+    // -------------------------------------------------------------------
+    // Pass 2: merge stories
+    // -------------------------------------------------------------------
+    for (const epic of discovered.epics) {
+        for (const story of epic.stories) {
+            const existing = storiesMap[story.id];
+            const owner = epicsMap[epic.id];
+            if (existing && owner && (owner.branch_mode === 'epic' || typeof owner.execution_branch === 'string')) {
+                skipped.push({ id: story.id, reason: 'story Git lifecycle preserved' });
+                continue;
+            }
+            // AC6: story-level non-overwrite guard
+            if (existing && existing.source === 'create-epic' && !forceOverwrite) {
+                skipped.push({
+                    id: story.id,
+                    reason: 'create-epic source preserved (defense, story)',
+                });
+                continue;
+            }
+            // Existing state owns workflow lifecycle even when provenance is absent
+            // or forceOverwrite is requested. Overlay specification metadata only.
+            if (existing) {
+                const existingRecord = existing;
+                if (story.title !== undefined)
+                    existingRecord.title = story.title;
+                existingRecord.depends_on = story.depends_on ?? [];
+                existingRecord.files_to_modify = story.files_to_modify ?? [];
+                continue;
+            }
+            const newStory = {
+                id: story.id,
+                epic_id: story.epic_id,
+                title: story.title ?? '',
+                // Filesystem frontmatter is specification, never workflow authority.
+                status: 'backlog',
+                source: 'discovered',
+                discovered_at: nowIso,
+                depends_on: story.depends_on ?? [],
+                files_to_modify: story.files_to_modify ?? [],
+            };
+            storiesMap[story.id] = newStory;
+            storiesAdded++;
+        }
+    }
+    // -------------------------------------------------------------------
+    // Pass 3: P189.04 aggregate writer invariants
+    // -------------------------------------------------------------------
+    for (const epicId of aggregateEpicIds) {
+        recomputeDiscoveredEpicAggregate(epicId, epicsMap, storiesMap, nowIso, aggregateDescriptors.get(epicId));
+    }
+    // Publish only after the full batch and all aggregate invariants pass.
+    safeState.epics = epicsMap;
+    safeState.stories = storiesMap;
+    return {
+        state: safeState,
+        added: Object.freeze([...added]),
+        skipped: Object.freeze([...skipped]),
+        storiesAdded,
+    };
+}