@decibelsystems/tools 2.2.0-beta.0 → 3.0.0

package/dist/tools/sentinel.js

@@ -1,10 +1,15 @@
 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
@@ -82,61 +87,131 @@ 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-') && isRecordFile(f))
-            .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 (!isRecordFile(file))
-                continue;
-            try {
-                const content = await fs.readFile(path.join(issuesDir, file), 'utf-8');
-                const region = frontmatterRegion(content);
-                if (!region)
-                    continue;
-                const idLine = region.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 {
@@ -169,47 +244,53 @@ async function parseEpicFile(filePath) {
                 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(/^---\n([\s\S]*?)\n---/);
+        const frontmatterMatch = content.match(/^---\r?\n([\s\S]*?)\r?\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 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);
@@ -233,6 +314,7 @@ async function parseEpicFile(filePath) {
             owner: frontmatter.owner || '',
             squad: frontmatter.squad || '',
             created_at: frontmatter.created_at || '',
+            notes: extractNotes(),
         };
     }
     catch {
@@ -398,21 +480,37 @@ function buildIssueSummary(filePath, content, parsed, degraded) {
         summary.degraded = true;
     return summary;
 }
-async function findIssueFile(projectId, issueId) {
+/**
+ * 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 each record extension (.md, .yml, .yaml)
+        // 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 { filePath: path.join(issuesDir, candidate), filename: candidate };
+                    return [at(candidate)];
                 }
             }
         }
@@ -420,14 +518,16 @@ async function findIssueFile(projectId, issueId) {
         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}-`) || 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 (!isRecordFile(f))
                     continue;
@@ -440,24 +540,23 @@ async function findIssueFile(projectId, issueId) {
                     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) {
@@ -485,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);
@@ -493,67 +591,46 @@ 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',
@@ -627,7 +704,6 @@ function setYamlBlockField(lines, key, value) {
     return out;
 }
 export async function closeIssue(input) {
-    // Resolve project paths first
     let resolved;
     try {
         resolved = resolveProjectPaths(input.projectId);
@@ -635,85 +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';
-    let updatedContent;
-    if (/^---\r?\n/.test(content)) {
-        // ---- Markdown-with-frontmatter record ------------------------------------
-        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}`);
+    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,
+            };
         }
-        // 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`);
-            }
-            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;
     }
-    else {
-        // ---- Bare-YAML record ----------------------------------------------------
-        // The frontmatter regexes above are all anchored on a leading `---`, so on
-        // a bare-YAML record they silently no-op: status stayed `open` while the
-        // markdown resolution append (which had no such guard) still fired. That
-        // both corrupted the YAML and left the issue looking open, while
-        // close_issue returned success. Write real YAML fields instead.
-        const { yaml, tail } = splitBareYamlRecord(content);
-        let region = setYamlScalarField(yaml, 'status', newStatus);
-        region = setYamlScalarField(region, 'closed_at', closedAt);
-        if (input.resolution) {
-            region = setYamlBlockField(region, 'resolution', input.resolution);
-        }
-        // Preserve any pre-existing markdown tail verbatim — repairing already
-        // corrupted files is a separate, reviewed migration (see ISS-0129).
-        const parts = tail.length > 0 ? [...region, '', ...tail] : region;
-        updatedContent = parts.join('\n').replace(/\n*$/, '\n');
-    }
-    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 {
@@ -722,47 +772,53 @@ export async function listRepoIssues(input) {
     catch (err) {
         return makeProjectResolutionError('list issues');
     }
-    const issuesDir = resolved.subPath('sentinel', 'issues');
-    const issues = [];
-    const malformedFiles = [];
-    const degradedFiles = [];
-    try {
-        const files = await fs.readdir(issuesDir);
-        for (const file of files) {
-            if (!isRecordFile(file))
-                continue;
-            const filePath = path.join(issuesDir, file);
-            const issue = await parseIssueFile(filePath);
-            if (issue) {
-                if (issue.degraded)
-                    degradedFiles.push(file);
-                // Apply status filter
-                if (input.status && issue.status !== input.status)
-                    continue;
-                issues.push(issue);
-            }
-            else {
-                // Unparseable file: report it instead of silently shrinking the list
-                malformedFiles.push(file);
-            }
-        }
-    }
-    catch {
-        // Directory doesn't exist
-    }
-    // Sort by filename (newest first based on timestamp)
+    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 (malformedFiles.length > 0) {
-        out.malformed = malformedFiles.length;
-        out.malformed_files = malformedFiles;
+    if (integrity.malformed.length > 0) {
+        out.malformed = integrity.malformed.length;
+        out.malformed_files = integrity.malformed;
+    }
+    if (integrity.degraded.length > 0) {
+        out.degraded = integrity.degraded.length;
+        out.degraded_files = integrity.degraded.map((d) => d.filename);
     }
-    if (degradedFiles.length > 0) {
-        out.degraded = degradedFiles.length;
-        out.degraded_files = degradedFiles;
+    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
 // ============================================================================
@@ -778,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);
@@ -847,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 (!isRecordFile(file))
-                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;
@@ -907,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 {