@decibelsystems/tools 2.1.4 → 3.0.0

package/dist/tools/sentinel.js

@@ -1,10 +1,42 @@
 import fs from 'fs/promises';
 import path from 'path';
+import { stringify as stringifyYaml } from 'yaml';
 import { log } from '../config.js';
 import { ensureDir } from '../dataRoot.js';
 import { resolveProjectPaths, validateWritePath } from '../projectRegistry.js';
 import { emitCreateProvenance } from './provenance.js';
 import { safeParseYaml } from '../sentinelIssues.js';
+import { readStoreDir, storeMeta } from './shared/storeRead.js';
+import { FsIssueRepository, AmbiguousIssueIdError as RepoAmbiguousIssueIdError, IssueNotFoundError as RepoIssueNotFoundError, } from '../domain/issueRepository.js';
+import { writeFileAtomic } from '../lib/atomicWrite.js';
+import { allocateAndWriteEpic } from '../lib/recordIdAllocator.js';
+/**
+ * Sentinel record files exist in two on-disk formats: markdown-with-frontmatter
+ * (`.md`) and bare YAML (`.yml`/`.yaml`). Historically every directory scan
+ * filtered on `.md` only, so ~530 `.yml` issues across 15 projects were
+ * silently omitted from list_issues while read_issue/update_issue resolved
+ * them fine. Treat both as first-class.
+ */
+const RECORD_EXT_RE = /\.(md|ya?ml)$/i;
+function isRecordFile(filename) {
+    return RECORD_EXT_RE.test(filename);
+}
+function stripRecordExt(filename) {
+    return filename.replace(RECORD_EXT_RE, '');
+}
+/**
+ * Extract the frontmatter region from a record file. `.md` records delimit it
+ * with `---`; bare `.yml` records are frontmatter all the way down, so the
+ * whole file is the region.
+ */
+function frontmatterRegion(content) {
+    const fmMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    if (fmMatch)
+        return fmMatch[1];
+    if (/^---/.test(content.trimStart()))
+        return null; // malformed delimiter block
+    return content;
+}
 /**
  * Quote a scalar for use as a YAML frontmatter value when the string contains
  * characters that would otherwise change parser behaviour. Plain titles like
@@ -55,104 +87,210 @@ function formatTimestampForFilename(date) {
     const iso = date.toISOString();
     return iso.replace(/:/g, '-').replace(/\.\d{3}Z$/, 'Z');
 }
-async function getNextEpicNumber(epicsDir) {
-    try {
-        const files = await fs.readdir(epicsDir);
-        const epicNumbers = files
-            .filter((f) => f.startsWith('EPIC-') && f.endsWith('.md'))
-            .map((f) => {
-            const match = f.match(/^EPIC-(\d+)/);
-            return match ? parseInt(match[1], 10) : 0;
-        });
-        return epicNumbers.length > 0 ? Math.max(...epicNumbers) + 1 : 1;
-    }
-    catch {
-        return 1;
-    }
-}
-function formatEpicId(num) {
-    return `EPIC-${num.toString().padStart(4, '0')}`;
-}
+// getNextEpicNumber/formatEpicId lived here and were the epic half of the
+// duplicate-id race: they read the directory for the current maximum, and the
+// write happened ~20 awaits later with nothing holding the two together.
+// Allocation now runs under the same cross-process lock as issues — see
+// allocateAndWriteEpic in src/lib/recordIdAllocator.ts.
 function formatIssueId(num) {
     return `ISS-${num.toString().padStart(4, '0')}`;
 }
-async function getNextIssueNumber(issuesDir) {
-    let max = 0;
-    try {
-        const files = await fs.readdir(issuesDir);
-        for (const file of files) {
-            const prefixMatch = file.match(/^ISS-(\d+)/i);
-            if (prefixMatch) {
-                max = Math.max(max, parseInt(prefixMatch[1], 10));
-                continue;
-            }
-            if (!file.endsWith('.md'))
-                continue;
-            try {
-                const content = await fs.readFile(path.join(issuesDir, file), 'utf-8');
-                const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
-                if (!fmMatch)
-                    continue;
-                const idLine = fmMatch[1].split('\n').find((l) => l.trim().toLowerCase().startsWith('id:'));
-                if (!idLine)
-                    continue;
-                const idVal = idLine.slice(idLine.indexOf(':') + 1).trim();
-                const idMatch = idVal.match(/^ISS-(\d+)$/i);
-                if (idMatch)
-                    max = Math.max(max, parseInt(idMatch[1], 10));
+/**
+ * The identity a writer would collide on: the padded ISS-NNNN from the
+ * filename, else from frontmatter, else the filename itself (which is unique
+ * by construction). Mirrors the tier-3/tier-4 matching in findIssueCandidates
+ * so the collision report and the write refusal agree on what "same id" means.
+ */
+function canonicalIssueKey(filename, summaryId) {
+    const fromName = filename.match(/^ISS-(\d+)/i);
+    if (fromName)
+        return `ISS-${fromName[1].padStart(4, '0')}`.toUpperCase();
+    const fromFrontmatter = summaryId.match(/^ISS-(\d+)$/i);
+    if (fromFrontmatter)
+        return `ISS-${fromFrontmatter[1].padStart(4, '0')}`.toUpperCase();
+    return filename;
+}
+/**
+ * Coerce a parsed YAML mapping into the flat shape the epic reader expects.
+ * Scalars become strings, sequences become string arrays, absent stays absent.
+ */
+function normalizeFrontmatter(parsed) {
+    const out = {};
+    for (const [key, value] of Object.entries(parsed)) {
+        if (value === null || value === undefined) {
+            out[key] = '';
+        }
+        else if (Array.isArray(value)) {
+            out[key] = value.map((v) => (typeof v === 'string' ? v : String(v)));
+        }
+        else if (typeof value === 'string') {
+            out[key] = value;
+        }
+        else if (value instanceof Date) {
+            out[key] = value.toISOString();
+        }
+        else if (typeof value === 'object') {
+            // A nested mapping has no representation in the flat epic model. Keep it
+            // legible rather than emitting "[object Object]".
+            out[key] = JSON.stringify(value);
+        }
+        else {
+            out[key] = String(value);
+        }
+    }
+    return out;
+}
+/**
+ * The pre-YAML reader: split each line on its first colon. Retained ONLY as a
+ * fallback for records YAML rejects — see parseEpicFrontmatter.
+ */
+function parseLooseFrontmatter(raw) {
+    const frontmatter = {};
+    for (const line of raw.split('\n')) {
+        const colonIndex = line.indexOf(':');
+        if (colonIndex > 0) {
+            const key = line.slice(0, colonIndex).trim();
+            let value = line.slice(colonIndex + 1).trim();
+            // Handle arrays (simple format: [item1, item2])
+            if (value.startsWith('[') && value.endsWith(']')) {
+                frontmatter[key] = value
+                    .slice(1, -1)
+                    .split(',')
+                    .map((s) => s.trim().replace(/^"(.*)"$/s, '$1'))
+                    .filter((s) => s.length > 0);
             }
-            catch {
-                // skip unreadable files
+            else {
+                // Strip YAML-style outer quoting. yamlScalar writes values containing
+                // '#', ':' etc. as JSON-style double-quoted strings; without this,
+                // the naive parser returns the literal "..."-wrapped string.
+                if (value.length >= 2) {
+                    if (value.startsWith('"') && value.endsWith('"')) {
+                        try {
+                            value = JSON.parse(value);
+                        }
+                        catch { /* keep as-is on bad escape */ }
+                    }
+                    else if (value.startsWith("'") && value.endsWith("'")) {
+                        value = value.slice(1, -1).replace(/''/g, "'");
+                    }
+                }
+                frontmatter[key] = value;
             }
         }
     }
+    return frontmatter;
+}
+/**
+ * Parse epic frontmatter, YAML first.
+ *
+ * The fenced (`.md`) branch used to hand-roll `key: value` splitting while the
+ * bare-YAML branch six lines above used a real parser. Splitting on the first
+ * colon reports a block-scalar INDICATOR as the value — `summary: |-` read back
+ * as the literal string "|-", losing the whole summary — and then treats every
+ * indented prose line containing a colon as its own key. On EPIC-0038 that
+ * produced 11 invented keys with names like "STILL LIVE" and "degraded".
+ *
+ * YAML cannot simply replace it. 7 of 38 epic records on disk have frontmatter
+ * a real parser rejects: unquoted values containing ": ", emitted by a write
+ * path that does not quote (`title: Epic: Special Characters!`). Parsing those
+ * strictly would return null and drop them from list_epics entirely — a worse
+ * defect than the one being fixed. So YAML when the record is valid, the loose
+ * reader when it is not.
+ *
+ * The loose path is a compatibility shim for existing damage, not a supported
+ * format. It is removable once the write side stops emitting unquoted scalars
+ * (EPIC-0038 Phase 1e) and the affected records are repaired.
+ */
+function parseEpicFrontmatter(raw) {
+    try {
+        const parsed = safeParseYaml(raw);
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            return normalizeFrontmatter(parsed);
+        }
+    }
     catch {
-        // dir doesn't exist yet
+        // Not valid YAML — fall through rather than dropping the record.
     }
-    return max + 1;
+    return parseLooseFrontmatter(raw);
 }
 async function parseEpicFile(filePath) {
     try {
         const content = await fs.readFile(filePath, 'utf-8');
-        const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
-        if (!frontmatterMatch)
-            return null;
-        const frontmatter = {};
-        for (const line of frontmatterMatch[1].split('\n')) {
-            const colonIndex = line.indexOf(':');
-            if (colonIndex > 0) {
-                const key = line.slice(0, colonIndex).trim();
-                let value = line.slice(colonIndex + 1).trim();
-                // Handle arrays (simple format: [item1, item2])
-                if (value.startsWith('[') && value.endsWith(']')) {
-                    frontmatter[key] = value
-                        .slice(1, -1)
-                        .split(',')
-                        .map((s) => s.trim().replace(/^"(.*)"$/s, '$1'))
-                        .filter((s) => s.length > 0);
-                }
-                else {
-                    // Strip YAML-style outer quoting. yamlScalar writes values containing
-                    // '#', ':' etc. as JSON-style double-quoted strings; without this,
-                    // the naive parser returns the literal "..."-wrapped string.
-                    if (value.length >= 2) {
-                        if (value.startsWith('"') && value.endsWith('"')) {
-                            try {
-                                value = JSON.parse(value);
-                            }
-                            catch { /* keep as-is on bad escape */ }
-                        }
-                        else if (value.startsWith("'") && value.endsWith("'")) {
-                            value = value.slice(1, -1).replace(/''/g, "'");
-                        }
-                    }
-                    frontmatter[key] = value;
-                }
+        const hasDelimiters = /^---\r?\n/.test(content);
+        // Bare-YAML epics (`.yml`/`.yaml`) have no `---` fence and no markdown
+        // body — parse them as YAML outright rather than failing the fence check.
+        if (!hasDelimiters) {
+            let parsed;
+            try {
+                parsed = safeParseYaml(content);
             }
+            catch {
+                return null;
+            }
+            if (typeof parsed !== 'object' || parsed === null)
+                return null;
+            const str = (k) => typeof parsed[k] === 'string' ? parsed[k] : '';
+            const list = (k) => Array.isArray(parsed[k]) ? parsed[k] : [];
+            return {
+                id: str('id'),
+                title: str('title'),
+                summary: str('summary'),
+                status: str('status') || 'planned',
+                priority: str('priority') || 'medium',
+                motivation: list('motivation'),
+                outcomes: list('outcomes'),
+                acceptance_criteria: list('acceptance_criteria'),
+                tags: list('tags'),
+                owner: str('owner'),
+                squad: str('squad'),
+                created_at: str('created_at'),
+                // Bare-YAML epics have no markdown body, so there is nowhere for a
+                // `## Note (…)` section to live. Empty, not absent — callers should
+                // not have to distinguish "no notes" from "this format cannot hold
+                // notes".
+                notes: [],
+            };
         }
+        const frontmatterMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+        if (!frontmatterMatch)
+            return null;
+        const frontmatter = parseEpicFrontmatter(frontmatterMatch[1]);
         // Extract sections from body
         const bodyMatch = content.match(/---\n\n([\s\S]*)/);
         const body = bodyMatch ? bodyMatch[1] : '';
+        /**
+         * Notes are `## Note (<iso>)` sections appended by update_epic, so the
+         * reader is written against that exact shape rather than against any
+         * heading that looks note-ish.
+         *
+         * A note runs to the NEXT `## Note (…)` heading, not to the next `##`.
+         * That distinction is the whole bug: a note whose own text opens with a
+         * markdown heading — `## Resolution`, the commonest thing anyone writes in
+         * one — made the terminator match at offset zero, so the section came back
+         * empty and `if (text)` dropped it. read_epic then returned `notes: []` for
+         * an epic whose file plainly held the note, and update_epic had reported
+         * success, which is why it survived #72.
+         *
+         * Ending at the next NOTE heading is safe because notes are only ever
+         * appended after every other section: log_epic writes Summary, Motivation,
+         * Outcomes and Acceptance Criteria before any note can exist, and the one
+         * writer that could append a section later (the summary fallback below)
+         * now inserts ahead of the notes for this reason.
+         */
+        const extractNotes = () => {
+            const out = [];
+            const re = /^##\s+Note\s*\(([^)]*)\)\s*$/gm;
+            let m;
+            while ((m = re.exec(body)) !== null) {
+                const from = m.index + m[0].length;
+                const rest = body.slice(from);
+                const next = rest.search(/^##\s+Note\s*\([^)]*\)\s*$/m);
+                const text = (next === -1 ? rest : rest.slice(0, next)).trim();
+                if (text)
+                    out.push({ at: m[1].trim(), text });
+            }
+            return out;
+        };
         const extractList = (section) => {
             const regex = new RegExp(`## ${section}\\n([\\s\\S]*?)(?=\\n## |$)`);
             const match = body.match(regex);
@@ -176,6 +314,7 @@ async function parseEpicFile(filePath) {
             owner: frontmatter.owner || '',
             squad: frontmatter.squad || '',
             created_at: frontmatter.created_at || '',
+            notes: extractNotes(),
         };
     }
     catch {
@@ -189,7 +328,7 @@ async function getAllEpics(projectId) {
     try {
         const files = await fs.readdir(epicsDir);
         for (const file of files) {
-            if (!file.endsWith('.md'))
+            if (!isRecordFile(file))
                 continue;
             const filePath = path.join(epicsDir, file);
             const epic = await parseEpicFile(filePath);
@@ -255,108 +394,169 @@ function calculateFuzzyScore(query, text) {
  * `epic_id` injection via crafted column-0 lines. The real parser closes both.
  */
 async function parseIssueFile(filePath) {
+    let content;
     try {
-        const content = await fs.readFile(filePath, 'utf-8');
-        let parsed;
+        content = await fs.readFile(filePath, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+    // 1. Whole-file parse. Covers well-formed bare YAML and, via safeParseYaml's
+    //    multi-doc handling, most markdown-with-frontmatter records.
+    try {
+        const parsed = safeParseYaml(content);
+        if (typeof parsed === 'object' && parsed !== null) {
+            return buildIssueSummary(filePath, content, parsed, false);
+        }
+    }
+    catch {
+        // fall through
+    }
+    // 2. Delimited frontmatter only — the markdown body confused the parser.
+    const region = frontmatterRegion(content);
+    if (region && region !== content) {
         try {
-            parsed = safeParseYaml(content);
+            const parsed = safeParseYaml(region);
+            if (typeof parsed === 'object' && parsed !== null) {
+                return buildIssueSummary(filePath, content, parsed, false);
+            }
         }
         catch {
-            // safeParseYaml threw — likely the markdown body after `---` confused
-            // the multi-doc parser. Last-resort: extract just the frontmatter region
-            // manually and parse that.
-            const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
-            if (!fmMatch)
-                return null;
-            try {
-                parsed = safeParseYaml(fmMatch[1]);
-            }
-            catch {
-                return null;
-            }
+            // fall through
         }
-        // Title: first markdown heading wins (legacy markdown-frontmatter format),
-        // else explicit `title:` key in YAML, else filename as last-resort.
-        const titleMatch = content.match(/^# (.+)$/m);
-        const title = titleMatch?.[1] ??
-            (typeof parsed.title === 'string' ? parsed.title : undefined) ??
-            path.basename(filePath, '.md');
-        // ID: prefer canonical ISS-NNNN form from frontmatter, else filename.
-        const fmId = typeof parsed.id === 'string' ? parsed.id.match(/^ISS-\d+$/i)?.[0] : undefined;
-        const id = fmId ?? path.basename(filePath);
-        return {
-            id,
-            title,
-            severity: parsed.severity || 'low',
-            status: (typeof parsed.status === 'string' ? parsed.status : undefined) || 'open',
-            epic_id: (typeof parsed.epic_id === 'string' ? parsed.epic_id : undefined) ??
-                (typeof parsed.epicId === 'string' ? parsed.epicId : undefined),
-            priority: typeof parsed.priority === 'string' ? parsed.priority : undefined,
-            tags: Array.isArray(parsed.tags) ? parsed.tags : undefined,
-            created_at: typeof parsed.created_at === 'string' ? parsed.created_at : undefined,
-            updated_at: typeof parsed.updated_at === 'string' ? parsed.updated_at : undefined,
-        };
+    }
+    // 3. Salvage. close_issue appends a markdown `## Resolution` section to
+    //    bare-YAML records; the prose beneath it is not valid YAML, so the whole
+    //    record used to vanish. Parse only the region above the first heading.
+    const salvaged = salvageBareYaml(content);
+    if (salvaged)
+        return buildIssueSummary(filePath, content, salvaged, true);
+    return null;
+}
+/**
+ * Parse only the YAML region above the first markdown heading. Returns null if
+ * the record is delimited, has no heading, or the region is still unparseable.
+ */
+function salvageBareYaml(content) {
+    if (/^---/.test(content.trimStart()))
+        return null;
+    const lines = content.split('\n');
+    const headingIdx = lines.findIndex((l) => /^#{1,6}\s/.test(l));
+    if (headingIdx <= 0)
+        return null;
+    try {
+        const parsed = safeParseYaml(lines.slice(0, headingIdx).join('\n'));
+        if (typeof parsed !== 'object' || parsed === null)
+            return null;
+        return parsed;
     }
     catch {
         return null;
     }
 }
-async function findIssueFile(projectId, issueId) {
+function buildIssueSummary(filePath, content, parsed, degraded) {
+    // Title: first markdown heading wins (legacy markdown-frontmatter format),
+    // else explicit `title:` key in YAML, else filename as last-resort.
+    const titleMatch = content.match(/^# (.+)$/m);
+    const title = titleMatch?.[1] ??
+        (typeof parsed.title === 'string' ? parsed.title : undefined) ??
+        stripRecordExt(path.basename(filePath));
+    // ID: prefer canonical ISS-NNNN form from frontmatter, else filename.
+    const fmId = typeof parsed.id === 'string' ? parsed.id.match(/^ISS-\d+$/i)?.[0] : undefined;
+    const id = fmId ?? path.basename(filePath);
+    const summary = {
+        id,
+        title,
+        severity: parsed.severity || 'low',
+        status: (typeof parsed.status === 'string' ? parsed.status : undefined) || 'open',
+        epic_id: (typeof parsed.epic_id === 'string' ? parsed.epic_id : undefined) ??
+            (typeof parsed.epicId === 'string' ? parsed.epicId : undefined),
+        priority: typeof parsed.priority === 'string' ? parsed.priority : undefined,
+        tags: Array.isArray(parsed.tags) ? parsed.tags : undefined,
+        created_at: typeof parsed.created_at === 'string' ? parsed.created_at : undefined,
+        updated_at: typeof parsed.updated_at === 'string' ? parsed.updated_at : undefined,
+    };
+    if (degraded)
+        summary.degraded = true;
+    return summary;
+}
+/**
+ * Resolve an issue id to every file it could plausibly mean.
+ *
+ * Matching runs in tiers of decreasing specificity and returns only the FIRST
+ * NON-EMPTY tier. That ordering is load-bearing: an exact filename outranks an
+ * ISS-NNNN prefix, so passing a filename stays a reliable way to name one
+ * member of a duplicate-id pair. Ambiguity is only ever reported within a
+ * single tier, never across tiers.
+ *
+ * Returning an array rather than the first hit is the point. Duplicate ISS-NNNN
+ * ids exist in the wild (ISS-0131), and `files.find(...)` resolved them in
+ * fs.readdir order — so every writer had an undefined target, silently edited
+ * one record, silently left the other untouched, and returned success.
+ */
+async function findIssueCandidates(projectId, issueId) {
     const resolved = resolveProjectPaths(projectId);
     const issuesDir = resolved.subPath('sentinel', 'issues');
+    const at = (filename) => ({ filePath: path.join(issuesDir, filename), filename });
     try {
         const files = await fs.readdir(issuesDir);
-        // Try exact match first
+        // Tier 1: exact filename. A directory cannot hold two of these.
         if (files.includes(issueId)) {
-            return { filePath: path.join(issuesDir, issueId), filename: issueId };
+            return [at(issueId)];
         }
-        // Try with .md extension
-        const withMd = issueId.endsWith('.md') ? issueId : `${issueId}.md`;
-        if (files.includes(withMd)) {
-            return { filePath: path.join(issuesDir, withMd), filename: withMd };
+        // Tier 2: filename + record extension. At most one per extension, and the
+        // extension order (.md, .yml, .yaml) is the established precedence.
+        if (!isRecordFile(issueId)) {
+            for (const ext of ['.md', '.yml', '.yaml']) {
+                const candidate = `${issueId}${ext}`;
+                if (files.includes(candidate)) {
+                    return [at(candidate)];
+                }
+            }
         }
         // ISS-NNNN: match filename prefix with word boundary, or frontmatter id
         const issMatch = issueId.match(/^ISS-(\d+)$/i);
         if (issMatch) {
             const padded = `ISS-${issMatch[1].padStart(4, '0')}`.toLowerCase();
-            const prefixHit = files.find((f) => {
+            // Tier 3: filename prefix. THIS is where duplicates collide.
+            const prefixHits = files.filter((f) => {
                 const lower = f.toLowerCase();
-                return lower.startsWith(`${padded}-`) || lower === `${padded}.md`;
+                return lower.startsWith(`${padded}-`) || stripRecordExt(lower) === padded;
             });
-            if (prefixHit) {
-                return { filePath: path.join(issuesDir, prefixHit), filename: prefixHit };
+            if (prefixHits.length > 0) {
+                return prefixHits.map(at);
             }
-            // Scan frontmatter for legacy retroactively-stamped issues
+            // Tier 4: frontmatter id, for legacy retroactively-stamped issues.
+            const fmHits = [];
             for (const f of files) {
-                if (!f.endsWith('.md'))
+                if (!isRecordFile(f))
                     continue;
                 try {
                     const content = await fs.readFile(path.join(issuesDir, f), 'utf-8');
-                    const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
-                    if (!fmMatch)
+                    const region = frontmatterRegion(content);
+                    if (!region)
                         continue;
-                    const idLine = fmMatch[1].split('\n').find((l) => l.trim().toLowerCase().startsWith('id:'));
+                    const idLine = region.split('\n').find((l) => l.trim().toLowerCase().startsWith('id:'));
                     if (!idLine)
                         continue;
                     const idVal = idLine.slice(idLine.indexOf(':') + 1).trim().toLowerCase();
-                    if (idVal === padded) {
-                        return { filePath: path.join(issuesDir, f), filename: f };
-                    }
+                    if (idVal === padded)
+                        fmHits.push(f);
                 }
                 catch {
                     // skip unreadable
                 }
             }
+            if (fmHits.length > 0)
+                return fmHits.map(at);
         }
-        // Fuzzy match - find file containing the query
-        const match = files.find(f => f.toLowerCase().includes(issueId.toLowerCase()));
-        if (match) {
-            return { filePath: path.join(issuesDir, match), filename: match };
-        }
-        return null;
+        // Tier 5: fuzzy substring. Genuinely ambiguous when it hits more than once
+        // (`ISS-011` spans ISS-0110, ISS-0112, ISS-0119), so it reports all of them.
+        const fuzzyHits = files.filter((f) => f.toLowerCase().includes(issueId.toLowerCase()));
+        return fuzzyHits.map(at);
     }
     catch {
-        return null;
+        return [];
     }
 }
 async function getProjectIssues(projectId) {
@@ -366,7 +566,7 @@ async function getProjectIssues(projectId) {
     try {
         const files = await fs.readdir(issuesDir);
         for (const file of files) {
-            if (!file.endsWith('.md'))
+            if (!isRecordFile(file))
                 continue;
             const filePath = path.join(issuesDir, file);
             const issue = await parseIssueFile(filePath);
@@ -384,7 +584,6 @@ async function getProjectIssues(projectId) {
 // Issue Functions
 // ============================================================================
 export async function createIssue(input) {
-    // Resolve project paths first - fail fast if no project
     let resolved;
     try {
         resolved = resolveProjectPaths(input.projectId);
@@ -392,74 +591,119 @@ export async function createIssue(input) {
     catch (err) {
         return makeProjectResolutionError('create issue');
     }
-    const issuesDir = resolved.subPath('sentinel', 'issues');
-    // Validate epic_id if provided
+    // Epic validation stays here: it is a policy question about this project's
+    // epics, not a storage concern, so it does not belong behind the repository.
     if (input.epic_id) {
         const allEpics = await getAllEpics(input.projectId);
-        const epicExists = allEpics.some((e) => e.id === input.epic_id);
-        if (!epicExists) {
-            // Return structured error with suggestions
-            const suggested = allEpics
-                .slice(0, 5)
-                .map((e) => ({ id: e.id, title: e.title }));
+        if (!allEpics.some((e) => e.id === input.epic_id)) {
             return {
                 error: 'EPIC_NOT_FOUND',
                 epic_id: input.epic_id,
                 message: `Unknown epic_id ${input.epic_id}.`,
-                suggested_epics: suggested,
+                suggested_epics: allEpics.slice(0, 5).map((e) => ({ id: e.id, title: e.title })),
             };
         }
     }
-    const now = new Date();
-    const timestamp = now.toISOString();
-    const slug = slugify(input.title);
-    ensureDir(issuesDir);
-    const issueNum = await getNextIssueNumber(issuesDir);
-    const issueId = formatIssueId(issueNum);
-    const filename = `${issueId}-${slug}.md`;
-    const filePath = path.join(issuesDir, filename);
-    validateWritePath(filePath, resolved);
-    // Build frontmatter with optional epic_id
-    const frontmatterLines = [
-        '---',
-        `id: ${issueId}`,
-        `projectId: ${resolved.id}`,
-        `severity: ${input.severity}`,
-        `status: open`,
-        `created_at: ${timestamp}`,
-    ];
-    if (input.epic_id) {
-        frontmatterLines.push(`epic_id: ${input.epic_id}`);
-    }
-    frontmatterLines.push('---');
-    const frontmatter = frontmatterLines.join('\n');
-    const bodyLines = [
-        `# ${input.title}`,
-        '',
-        `**Severity:** ${input.severity}`,
-        `**Status:** open`,
-    ];
-    if (input.epic_id) {
-        bodyLines.push(`**Epic:** ${input.epic_id}`);
-    }
-    bodyLines.push('', '## Details', '', input.details);
-    const body = bodyLines.join('\n');
-    const content = `${frontmatter}\n\n${body}\n`;
-    await fs.writeFile(filePath, content, 'utf-8');
-    log(`Sentinel: Created issue at ${filePath} (project: ${resolved.id})`);
-    // Emit provenance event for this creation
-    await emitCreateProvenance(`sentinel:issue:${filename}`, content, `Created issue: ${input.title}`, input.projectId);
+    const repo = new FsIssueRepository(resolved.subPath('sentinel', 'issues'));
+    // The repository allocates and writes under one cross-process lock and stamps
+    // a uid at birth — which the previous writer did not, so every issue filed
+    // since the Phase 3 backfill was landing without a stable identity.
+    //
+    // Path traversal is not reachable here: the filename is built from an
+    // allocated ISS-NNNN plus a slug that strips everything outside [a-z0-9-],
+    // so a hostile title cannot escape the issues directory.
+    const created = await repo.create({
+        title: input.title,
+        details: input.details,
+        severity: input.severity,
+        epicId: input.epic_id,
+        project: resolved.id,
+        // Forwarded rather than dropped. CreateIssueSpec has accepted these all
+        // along; omitting them here meant a caller could pass priority:'high' and
+        // watch it vanish with no error, because create_issue's schema allows
+        // additional properties.
+        priority: input.priority,
+        tags: input.tags,
+    });
+    log(`Sentinel: Created issue at ${created.path} (project: ${resolved.id})`);
+    await emitCreateProvenance(`sentinel:issue:${created.filename}`, await fs.readFile(created.path, 'utf-8'), `Created issue: ${input.title}`, input.projectId);
     return {
-        id: issueId,
-        timestamp,
-        path: filePath,
+        id: created.issue.id,
+        timestamp: created.issue.created_at ?? new Date().toISOString(),
+        path: created.path,
         status: 'open',
         epic_id: input.epic_id,
         location: 'project',
     };
 }
+/**
+ * Split a bare-YAML record into its YAML region and any trailing markdown.
+ * close_issue historically appended a `## Resolution` section to bare-YAML
+ * records; that tail is pre-existing corruption we preserve rather than
+ * discard, while writing new fields into the YAML region where they belong.
+ */
+function splitBareYamlRecord(content) {
+    const lines = content.split('\n');
+    const headingIdx = lines.findIndex((l) => /^#{1,6}\s/.test(l));
+    if (headingIdx < 0)
+        return { yaml: lines, tail: [] };
+    return { yaml: lines.slice(0, headingIdx), tail: lines.slice(headingIdx) };
+}
+/** Replace a column-0 scalar key in a YAML region, appending it if absent. */
+function setYamlScalarField(lines, key, value) {
+    const re = new RegExp(`^${key}:`);
+    const idx = lines.findIndex((l) => re.test(l));
+    if (idx >= 0) {
+        const out = [...lines];
+        out[idx] = `${key}: ${value}`;
+        return out;
+    }
+    // Append after the last non-blank line so we don't strand it past a gap.
+    const out = [...lines];
+    while (out.length > 0 && out[out.length - 1].trim() === '')
+        out.pop();
+    out.push(`${key}: ${value}`);
+    return out;
+}
+/** Replace a column-0 block-scalar key (and its indented continuation). */
+function setYamlBlockField(lines, key, value) {
+    const re = new RegExp(`^${key}:`);
+    const out = [];
+    let i = 0;
+    while (i < lines.length) {
+        if (re.test(lines[i])) {
+            i++;
+            // Consume the indented continuation block, including interior blank
+            // lines, but stop before the next column-0 key.
+            while (i < lines.length) {
+                if (lines[i].trim() === '') {
+                    let j = i;
+                    while (j < lines.length && lines[j].trim() === '')
+                        j++;
+                    if (j >= lines.length || /^\S/.test(lines[j]))
+                        break;
+                    i = j;
+                    continue;
+                }
+                if (/^\s/.test(lines[i])) {
+                    i++;
+                    continue;
+                }
+                break;
+            }
+            continue;
+        }
+        out.push(lines[i]);
+        i++;
+    }
+    while (out.length > 0 && out[out.length - 1].trim() === '')
+        out.pop();
+    out.push(`${key}: |-`);
+    for (const l of value.split('\n'))
+        out.push(`  ${l}`);
+    return out;
+}
 export async function closeIssue(input) {
-    // Resolve project paths first
     let resolved;
     try {
         resolved = resolveProjectPaths(input.projectId);
@@ -467,64 +711,59 @@ export async function closeIssue(input) {
     catch (err) {
         return makeProjectResolutionError('close issue');
     }
-    const found = await findIssueFile(input.projectId, input.issue_id);
-    if (!found) {
-        const available = await getProjectIssues(input.projectId);
+    const repo = new FsIssueRepository(resolved.subPath('sentinel', 'issues'));
+    try {
+        // One call replaces the format fork this function used to carry. The
+        // bare-YAML branch was where close_issue historically failed: its
+        // frontmatter-anchored regexes silently no-opped on a delimiter-less
+        // record, so status stayed `open` while the markdown resolution append
+        // still fired — corrupting the YAML and reporting success. The codec has
+        // one write path for both formats, so that divergence cannot recur.
+        const closed = await repo.close(input.issue_id, input.resolution ?? '', input.status ?? 'closed');
+        log(`Sentinel: Closed issue at ${closed.path}`);
         return {
-            error: 'ISSUE_NOT_FOUND',
-            projectId: resolved.id,
-            issue_id: input.issue_id,
-            message: `Could not find issue matching "${input.issue_id}" in project "${resolved.id}".`,
-            available_issues: available.slice(0, 5),
+            id: closed.issue.id,
+            path: closed.path,
+            status: closed.issue.status,
+            closed_at: closed.issue.closed_at ?? new Date().toISOString(),
+            resolution: input.resolution,
         };
     }
-    const { filePath, filename } = found;
-    const content = await fs.readFile(filePath, 'utf-8');
-    const now = new Date();
-    const closedAt = now.toISOString();
-    const newStatus = input.status || 'closed';
-    // Update frontmatter
-    let updatedContent = content.replace(/^(---\n[\s\S]*?)status: \w+/m, `$1status: ${newStatus}`);
-    // Add closed_at to frontmatter if not present
-    if (!updatedContent.includes('closed_at:')) {
-        updatedContent = updatedContent.replace(/^(---\n[\s\S]*?)(---)$/m, `$1closed_at: ${closedAt}\n$2`);
-    }
-    else {
-        updatedContent = updatedContent.replace(/closed_at: .*/, `closed_at: ${closedAt}`);
-    }
-    // Update status in body
-    updatedContent = updatedContent.replace(/\*\*Status:\*\* \w+/, `**Status:** ${newStatus}`);
-    // Add resolution section if provided
-    if (input.resolution) {
-        if (updatedContent.includes('## Resolution')) {
-            // Replace existing resolution
-            updatedContent = updatedContent.replace(/## Resolution\n\n[\s\S]*?(?=\n## |$)/, `## Resolution\n\n${input.resolution}\n`);
+    catch (err) {
+        if (err instanceof RepoAmbiguousIssueIdError) {
+            return {
+                error: 'AMBIGUOUS_ISSUE_ID',
+                projectId: resolved.id,
+                issue_id: input.issue_id,
+                message: `"${input.issue_id}" matches ${err.candidates.length} records in project "${resolved.id}", ` +
+                    `so the write target is undefined and nothing was changed. ` +
+                    `Re-run with one of these filenames as issue_id: ${err.candidates.join(', ')}`,
+                candidates: err.candidates,
+            };
         }
-        else {
-            // Add resolution section at the end
-            updatedContent = updatedContent.trimEnd() + `\n\n## Resolution\n\n${input.resolution}\n`;
+        if (err instanceof RepoIssueNotFoundError) {
+            const available = await getProjectIssues(input.projectId);
+            return {
+                error: 'ISSUE_NOT_FOUND',
+                projectId: resolved.id,
+                issue_id: input.issue_id,
+                message: `Could not find issue matching "${input.issue_id}" in project "${resolved.id}".`,
+                available_issues: available.slice(0, 5),
+            };
         }
+        throw err;
     }
-    await fs.writeFile(filePath, updatedContent, 'utf-8');
-    log(`Sentinel: Closed issue at ${filePath}`);
-    // Prefer ISS-NNNN id from filename or frontmatter for the return value
-    const filenamePrefix = filename.match(/^(ISS-\d+)/i)?.[1];
-    const fmIdMatch = updatedContent.match(/^---\n([\s\S]*?)\n---/);
-    const fmId = fmIdMatch?.[1]
-        .split('\n')
-        .find((l) => l.trim().toLowerCase().startsWith('id:'))
-        ?.split(':')[1]
-        ?.trim()
-        ?.match(/^ISS-\d+$/i)?.[0];
-    const returnedId = filenamePrefix ?? fmId ?? filename;
-    return {
-        id: returnedId,
-        path: filePath,
-        status: newStatus,
-        closed_at: closedAt,
-        resolution: input.resolution,
-    };
 }
+/**
+ * Delegates to the Phase 3 repository. The output contract is unchanged — the
+ * point of the seam is that callers cannot tell which layer answered.
+ *
+ * `degraded` changes meaning slightly and for the better: it used to mean "only
+ * parsed after salvaging corrupted YAML", and now means "readable, but the
+ * codec had to interpret something" — a superset that also catches a legacy
+ * status value or a title that fell back to the filename. Both are the same
+ * repair queue.
+ */
 export async function listRepoIssues(input) {
     let resolved;
     try {
@@ -533,29 +772,52 @@ export async function listRepoIssues(input) {
     catch (err) {
         return makeProjectResolutionError('list issues');
     }
-    const issuesDir = resolved.subPath('sentinel', 'issues');
-    const issues = [];
-    try {
-        const files = await fs.readdir(issuesDir);
-        for (const file of files) {
-            if (!file.endsWith('.md'))
-                continue;
-            const filePath = path.join(issuesDir, file);
-            const issue = await parseIssueFile(filePath);
-            if (issue) {
-                // Apply status filter
-                if (input.status && issue.status !== input.status)
-                    continue;
-                issues.push(issue);
-            }
-        }
+    const repo = new FsIssueRepository(resolved.subPath('sentinel', 'issues'));
+    const [records, integrity] = await Promise.all([
+        repo.list(input.status ? { status: input.status } : {}),
+        repo.integrity(),
+    ]);
+    const issues = records.map((r) => toIssueSummary(r, integrity));
+    issues.sort((a, b) => b.id.localeCompare(a.id));
+    const out = { issues };
+    if (integrity.malformed.length > 0) {
+        out.malformed = integrity.malformed.length;
+        out.malformed_files = integrity.malformed;
     }
-    catch {
-        // Directory doesn't exist
+    if (integrity.degraded.length > 0) {
+        out.degraded = integrity.degraded.length;
+        out.degraded_files = integrity.degraded.map((d) => d.filename);
     }
-    // Sort by filename (newest first based on timestamp)
-    issues.sort((a, b) => b.id.localeCompare(a.id));
-    return { issues };
+    const dupEntries = Object.entries(integrity.duplicateIds);
+    if (dupEntries.length > 0) {
+        out.duplicate_ids = dupEntries.length;
+        out.duplicate_id_files = Object.fromEntries(dupEntries);
+    }
+    return out;
+}
+/** Canonical record -> the wire shape this module has always returned. */
+function toIssueSummary(r, integrity) {
+    // Records with no ISS-NNNN have always been identified on the wire by their
+    // filename INCLUDING the extension, and close_issue/read_issue accept that
+    // form. The canonical model drops the extension, which is tidier and which
+    // the repository resolves either way — but changing it here would be a wire
+    // contract change smuggled in on a refactor. ISS-0113 tracks the
+    // inconsistency deliberately; this migration stays behaviour-preserving.
+    const wireId = /^ISS-\d+$/i.test(r.issue.id) ? r.issue.id : r.filename;
+    const summary = {
+        id: wireId,
+        title: r.issue.title,
+        severity: r.issue.severity ?? 'low',
+        status: r.issue.status,
+        epic_id: r.issue.epicId,
+        priority: r.issue.priority,
+        tags: r.issue.tags,
+        created_at: r.issue.created_at,
+        updated_at: r.issue.updated_at,
+    };
+    if (integrity.degraded.some((d) => d.filename === r.filename))
+        summary.degraded = true;
+    return summary;
 }
 // ============================================================================
 // Epic Functions
@@ -572,55 +834,57 @@ export async function logEpic(input) {
     const now = new Date();
     const timestamp = now.toISOString();
     ensureDir(epicsDir);
-    const epicNum = await getNextEpicNumber(epicsDir);
-    const epicId = formatEpicId(epicNum);
     const slug = slugify(input.title);
-    const filename = `${epicId}-${slug}.md`;
-    const filePath = path.join(epicsDir, filename);
-    validateWritePath(filePath, resolved);
     const priority = input.priority || 'medium';
     const tags = input.tags || [];
     const owner = input.owner || '';
     const squad = input.squad || '';
-    // Build frontmatter — use yamlScalar on free-text fields so values containing
-    // `#`, `:` etc. don't truncate on read-back (see ISS-0110 bug 3).
-    const frontmatter = [
-        '---',
-        `id: ${epicId}`,
-        `projectId: ${yamlScalar(resolved.id)}`,
-        `title: ${yamlScalar(input.title)}`,
-        `summary: ${yamlScalar(input.summary)}`,
-        `status: planned`,
-        `priority: ${priority}`,
-        `tags: [${tags.map(yamlScalar).join(', ')}]`,
-        `owner: ${yamlScalar(owner)}`,
-        `squad: ${yamlScalar(squad)}`,
-        `created_at: ${timestamp}`,
-        '---',
-    ].join('\n');
-    // Build body sections
-    const sections = [];
-    sections.push(`# ${input.title}`, '', '## Summary', '', input.summary);
-    if (input.motivation && input.motivation.length > 0) {
-        sections.push('', '## Motivation', '');
-        for (const item of input.motivation) {
-            sections.push(`- ${item}`);
+    // Content is built from the id the allocator hands out, so it cannot be
+    // assembled before allocation — the id appears in the frontmatter.
+    const buildContent = (epicId) => {
+        // Build frontmatter — use yamlScalar on free-text fields so values containing
+        // `#`, `:` etc. don't truncate on read-back (see ISS-0110 bug 3).
+        const frontmatter = [
+            '---',
+            `id: ${epicId}`,
+            `projectId: ${yamlScalar(resolved.id)}`,
+            `title: ${yamlScalar(input.title)}`,
+            `summary: ${yamlScalar(input.summary)}`,
+            `status: planned`,
+            `priority: ${priority}`,
+            `tags: [${tags.map(yamlScalar).join(', ')}]`,
+            `owner: ${yamlScalar(owner)}`,
+            `squad: ${yamlScalar(squad)}`,
+            `created_at: ${timestamp}`,
+            '---',
+        ].join('\n');
+        // Build body sections
+        const sections = [];
+        sections.push(`# ${input.title}`, '', '## Summary', '', input.summary);
+        if (input.motivation && input.motivation.length > 0) {
+            sections.push('', '## Motivation', '');
+            for (const item of input.motivation) {
+                sections.push(`- ${item}`);
+            }
         }
-    }
-    if (input.outcomes && input.outcomes.length > 0) {
-        sections.push('', '## Outcomes', '');
-        for (const item of input.outcomes) {
-            sections.push(`- ${item}`);
+        if (input.outcomes && input.outcomes.length > 0) {
+            sections.push('', '## Outcomes', '');
+            for (const item of input.outcomes) {
+                sections.push(`- ${item}`);
+            }
         }
-    }
-    if (input.acceptance_criteria && input.acceptance_criteria.length > 0) {
-        sections.push('', '## Acceptance Criteria', '');
-        for (const item of input.acceptance_criteria) {
-            sections.push(`- [ ] ${item}`);
+        if (input.acceptance_criteria && input.acceptance_criteria.length > 0) {
+            sections.push('', '## Acceptance Criteria', '');
+            for (const item of input.acceptance_criteria) {
+                sections.push(`- [ ] ${item}`);
+            }
         }
-    }
-    const content = `${frontmatter}\n\n${sections.join('\n')}\n`;
-    await fs.writeFile(filePath, content, 'utf-8');
+        return `${frontmatter}\n\n${sections.join('\n')}\n`;
+    };
+    // Capture what actually landed rather than rebuilding it, so the provenance
+    // fingerprint below is of the bytes on disk and not of a second render.
+    let content = '';
+    const { id: epicId, filePath } = await allocateAndWriteEpic(epicsDir, slug, (id) => (content = buildContent(id)), { validate: (p) => validateWritePath(p, resolved) });
     log(`Sentinel: Created epic at ${filePath} (project: ${resolved.id})`);
     // Emit provenance event for this creation
     await emitCreateProvenance(`sentinel:epic:${epicId}`, content, `Created epic: ${input.title}`, input.projectId);
@@ -641,39 +905,31 @@ export async function listEpics(input) {
     }
     const epicsDir = resolved.subPath('sentinel', 'epics');
     const epics = [];
-    try {
-        const files = await fs.readdir(epicsDir);
-        for (const file of files) {
-            if (!file.endsWith('.md'))
-                continue;
-            const filePath = path.join(epicsDir, file);
-            const epic = await parseEpicFile(filePath);
-            if (!epic)
-                continue;
-            // Apply filters
-            if (input.status && epic.status !== input.status)
-                continue;
-            if (input.priority && epic.priority !== input.priority)
+    // ISS-0153. The previous form was `catch { /* directory doesn't exist yet */ }`
+    // wrapped around BOTH the readdir and the parse loop, with `if (!epic)
+    // continue` inside it. So a permissions failure, a corrupt epic, and a project
+    // that has never logged one all returned `{epics: []}` — and the caller could
+    // not tell which. readStoreDir keeps them apart and counts what it skipped.
+    const read = await readStoreDir(epicsDir, parseEpicFile, isRecordFile);
+    for (const epic of read.entries) {
+        if (input.status && epic.status !== input.status)
+            continue;
+        if (input.priority && epic.priority !== input.priority)
+            continue;
+        if (input.tags && input.tags.length > 0) {
+            if (!input.tags.some((t) => epic.tags.includes(t)))
                 continue;
-            if (input.tags && input.tags.length > 0) {
-                const hasTag = input.tags.some((t) => epic.tags.includes(t));
-                if (!hasTag)
-                    continue;
-            }
-            epics.push({
-                id: epic.id,
-                title: epic.title,
-                status: epic.status,
-                priority: epic.priority,
-            });
         }
-    }
-    catch {
-        // Directory doesn't exist yet
+        epics.push({
+            id: epic.id,
+            title: epic.title,
+            status: epic.status,
+            priority: epic.priority,
+        });
     }
     // Sort by ID (newest first based on number)
     epics.sort((a, b) => b.id.localeCompare(a.id));
-    return { epics };
+    return { epics, ...storeMeta(read) };
 }
 export async function getEpic(input) {
     let resolved;
@@ -701,6 +957,172 @@ export async function getEpic(input) {
         return { epic: null, error: `Epic not found: ${input.epic_id}` };
     }
 }
+/**
+ * Locate the file backing an epic id.
+ *
+ * Boundary-matched deliberately. A bare `startsWith` has no boundary, so
+ * `EPIC-003` would match EPIC-0030, EPIC-0031 and EPIC-0038 at once and the
+ * caller would silently write to whichever readdir returned first — the same
+ * defect that made issue resolution unsafe (ISS-0131). Returning every match
+ * lets the caller refuse rather than guess.
+ */
+async function findEpicFiles(epicsDir, epicId) {
+    let files;
+    try {
+        files = await fs.readdir(epicsDir);
+    }
+    catch {
+        return [];
+    }
+    const padded = epicId.match(/^EPIC-(\d+)$/i);
+    const canonical = padded ? `epic-${padded[1].padStart(4, '0')}` : epicId.toLowerCase();
+    return files.filter((f) => {
+        if (!isRecordFile(f))
+            return false;
+        const lower = f.toLowerCase();
+        // Exact filename, or the id followed by a non-digit separator.
+        return lower === epicId.toLowerCase() || new RegExp(`^${canonical}(?![0-9])`).test(lower);
+    });
+}
+/**
+ * Update an epic in place.
+ *
+ * Epics were write-once: log_epic created them and nothing could change status,
+ * priority, summary, or ownership afterwards (ISS-0140). The practical effects
+ * were that `status` stayed `planned` forever — making list_epics(status:...)
+ * useless and feeding wrong epic state into oracle/roadmap reporting
+ * (ISS-0110) — and that correcting an epic meant hand-editing the file, which
+ * is the markdown-into-YAML write hazard that corrupted issue records in the
+ * first place.
+ *
+ * Frontmatter is mutated as a parsed object and re-serialized, never patched by
+ * regex, and the file is replaced atomically. The body's `## Summary` section
+ * mirrors the frontmatter `summary` field, so both are updated together —
+ * leaving them to drift is what makes hand-editing an epic error-prone.
+ */
+export async function updateEpic(input) {
+    let resolved;
+    try {
+        resolved = resolveProjectPaths(input.projectId);
+    }
+    catch {
+        return makeProjectResolutionError('update epic');
+    }
+    const epicsDir = resolved.subPath('sentinel', 'epics');
+    const matches = await findEpicFiles(epicsDir, input.epic_id);
+    if (matches.length === 0) {
+        const all = await getAllEpics(input.projectId);
+        return {
+            error: 'EPIC_NOT_FOUND',
+            epic_id: input.epic_id,
+            message: `Unknown epic_id ${input.epic_id}.`,
+            suggested_epics: all.slice(0, 5).map((e) => ({ id: e.id, title: e.title })),
+        };
+    }
+    if (matches.length > 1) {
+        return {
+            error: 'AMBIGUOUS_EPIC_ID',
+            epic_id: input.epic_id,
+            message: `${matches.length} epic records match "${input.epic_id}". ` +
+                `Pass an exact filename to disambiguate.`,
+            candidates: matches,
+        };
+    }
+    const filePath = path.join(epicsDir, matches[0]);
+    validateWritePath(filePath, resolved);
+    const content = await fs.readFile(filePath, 'utf-8');
+    const fmMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+    if (!fmMatch) {
+        return {
+            error: 'EPIC_NOT_FOUND',
+            epic_id: input.epic_id,
+            message: `Epic record ${matches[0]} has no parseable frontmatter; refusing to write into a malformed file.`,
+            suggested_epics: [],
+        };
+    }
+    let parsed;
+    try {
+        parsed = safeParseYaml(fmMatch[1]);
+    }
+    catch (err) {
+        return {
+            error: 'EPIC_NOT_FOUND',
+            epic_id: input.epic_id,
+            message: `Epic record ${matches[0]} has unparseable frontmatter (${err instanceof Error ? err.message : String(err)}); refusing to write into it.`,
+            suggested_epics: [],
+        };
+    }
+    let body = fmMatch[2];
+    const changes = [];
+    const applyScalar = (key, value, label = key) => {
+        if (value === undefined)
+            return;
+        const before = parsed[key];
+        if (before === value)
+            return;
+        parsed[key] = value;
+        changes.push(`${label}: ${before ?? 'unset'} → ${value}`);
+    };
+    applyScalar('status', input.status);
+    applyScalar('priority', input.priority);
+    applyScalar('title', input.title);
+    applyScalar('owner', input.owner);
+    applyScalar('squad', input.squad);
+    if (input.tags !== undefined) {
+        parsed.tags = input.tags;
+        changes.push(`tags: ${input.tags.length} tag(s)`);
+    }
+    if (input.summary !== undefined) {
+        parsed.summary = input.summary;
+        changes.push('summary rewritten');
+        // Keep the body's Summary section in step with frontmatter. They are two
+        // copies of one value; letting them diverge is what makes an epic
+        // untrustworthy to read.
+        const summarySection = /^## Summary\s*\n[\s\S]*?(?=\n## |\s*$)/m;
+        const replacement = `## Summary\n\n${input.summary}\n`;
+        if (summarySection.test(body)) {
+            body = body.replace(summarySection, replacement);
+        }
+        else {
+            // Ahead of the notes, not after them. A note section ends at the next
+            // note heading (see extractNotes), so a Summary appended past the last
+            // note would be read back as part of that note's text.
+            const firstNote = body.search(/^##\s+Note\s*\([^)]*\)\s*$/m);
+            body = firstNote === -1
+                ? `${body.trimEnd()}\n\n${replacement}`
+                : `${body.slice(0, firstNote).trimEnd()}\n\n${replacement}\n${body.slice(firstNote)}`;
+        }
+    }
+    if (input.note) {
+        const stamp = new Date().toISOString();
+        body = `${body.trimEnd()}\n\n## Note (${stamp})\n\n${input.note}\n`;
+        changes.push('note appended');
+    }
+    if (changes.length === 0) {
+        return {
+            id: String(parsed.id ?? input.epic_id),
+            path: filePath,
+            status: parsed.status ?? 'planned',
+            priority: parsed.priority ?? 'medium',
+            updated_at: String(parsed.updated_at ?? ''),
+            changes: [],
+        };
+    }
+    const updatedAt = new Date().toISOString();
+    parsed.updated_at = updatedAt;
+    const frontmatter = stringifyYaml(parsed, { lineWidth: 0 }).trimEnd();
+    const rebuilt = `---\n${frontmatter}\n---\n\n${body.replace(/^\n+/, '').trimEnd()}\n`;
+    await writeFileAtomic(filePath, rebuilt);
+    log(`Sentinel: Updated epic ${parsed.id} at ${filePath} — ${changes.join(', ')}`);
+    return {
+        id: String(parsed.id ?? input.epic_id),
+        path: filePath,
+        status: parsed.status ?? 'planned',
+        priority: parsed.priority ?? 'medium',
+        updated_at: updatedAt,
+        changes,
+    };
+}
 export async function getEpicIssues(input) {
     let resolved;
     try {
@@ -714,7 +1136,7 @@ export async function getEpicIssues(input) {
     try {
         const issueFiles = await fs.readdir(issuesDir);
         for (const file of issueFiles) {
-            if (!file.endsWith('.md'))
+            if (!isRecordFile(file))
                 continue;
             const filePath = path.join(issuesDir, file);
             // Parse first, then filter on the parsed epic_id field. Previously this