@decibelsystems/tools 2.2.0-beta.0 → 3.0.0

package/dist/domain/issueCodec.js

@@ -0,0 +1,298 @@
+// ============================================================================
+// Issue codec — EPIC-0038 Phase 3
+// ============================================================================
+// Translates between on-disk records and the canonical Issue model. This is the
+// only place that knows there are two formats.
+//
+// Two rules shape the whole file:
+//
+// 1. DECODE IS LOSSLESS. Every frontmatter key survives a decode/encode round
+//    trip, whether or not the model has a field for it. Records in this store
+//    carry keys no interface declares — `repo`, `closed_reason`, `degraded`,
+//    `source`, `projectId` alongside `project` — and a codec that emitted only
+//    the fields it recognized would silently delete them on the first write.
+//    The precedent is real: update_issue once rewrote markdown records as bare
+//    YAML and dropped the delimiters, the heading and the body.
+//
+// 2. THE BODY MIRROR IS OUTPUT, NEVER INPUT. Markdown records repeat status and
+//    severity in the body as `**Status:** x` for human readers. Decode ignores
+//    those lines entirely and reads frontmatter; encode regenerates them from
+//    the model. That asymmetry is the point — it makes the drift that hit
+//    sixteen records structurally impossible rather than merely fixed. There is
+//    no code path that can write a mirror disagreeing with its frontmatter.
+// ============================================================================
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
+import { isUid, normalizeStatus, } from './issue.js';
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
+/** Keys the model owns. Everything else is preserved verbatim in raw.data. */
+const MODEL_KEYS = new Set([
+    'uid',
+    'id',
+    'title',
+    'status',
+    'severity',
+    'priority',
+    'tags',
+    'epic_id',
+    'epicId',
+    'project',
+    'description',
+    'details',
+    'resolution',
+    'created_at',
+    'updated_at',
+    'closed_at',
+]);
+function normalizeTags(v) {
+    if (!Array.isArray(v))
+        return undefined;
+    const tags = v.filter((t) => typeof t === 'string' && t.trim() !== '');
+    return tags.length > 0 ? tags : undefined;
+}
+function str(v) {
+    return typeof v === 'string' && v.trim() !== '' ? v : undefined;
+}
+/**
+ * Split a bare-YAML record into its YAML head and any markdown tail at column 0.
+ *
+ * The column-0 anchor is load-bearing and must not gain `\s*`: headings indented
+ * inside a `description:` block scalar are body text, not a tail, and matching
+ * them would truncate the record at parse time. Phase 2 verified no record in
+ * the store relies on the difference, but nothing else pins it, so it is pinned
+ * by test here.
+ */
+export function splitBareYaml(content) {
+    const lines = content.split('\n');
+    const idx = lines.findIndex((l) => /^#{1,6}\s/.test(l));
+    if (idx < 0)
+        return { head: content, tail: '' };
+    return { head: lines.slice(0, idx).join('\n'), tail: lines.slice(idx).join('\n') };
+}
+/**
+ * Prose under `## Details`, which is where the markdown format keeps the body.
+ *
+ * This used to stop at the next `##` heading of any kind, which quietly made
+ * the format unable to hold a structured issue. Authors write `## Problem`,
+ * `## Root Cause`, `## Fix` — 44 records in this store did, and every one read
+ * back truncated at the first of them, in two cases from 107 characters to 30.
+ *
+ * Only ONE trailing section is not the author's: `## Resolution`, which
+ * encodeIssue regenerates from `issue.resolution` and which decode reads from
+ * frontmatter. Including it here would duplicate it into details and then
+ * re-append it on every write. Everything else belongs to the body.
+ *
+ * The trailing occurrence is the one stripped, not the first — an issue whose
+ * prose discusses a resolution mid-body keeps it.
+ */
+function extractDetails(body) {
+    const m = body.match(/^##\s+Details\s*\n([\s\S]*)$/m);
+    if (!m)
+        return undefined;
+    let rest = m[1];
+    const headings = [...rest.matchAll(/\n##\s+Resolution\s*(?:\n|$)/g)];
+    const last = headings[headings.length - 1];
+    if (last?.index !== undefined)
+        rest = rest.slice(0, last.index);
+    return rest.trim() || undefined;
+}
+export function decodeIssue(filename, content) {
+    const warnings = [];
+    const fm = FRONTMATTER_RE.exec(content);
+    let data;
+    let body;
+    let format;
+    if (fm) {
+        format = 'md';
+        body = fm[2];
+        try {
+            data = parseYaml(fm[1]) ?? {};
+        }
+        catch (err) {
+            data = {};
+            warnings.push(`frontmatter did not parse: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    else {
+        format = 'yaml';
+        const split = splitBareYaml(content);
+        body = split.tail;
+        if (split.tail.trim()) {
+            // Phase 2 repaired every instance of this. A new one means a writer is
+            // appending markdown to bare YAML again.
+            warnings.push('bare-YAML record has a markdown tail — a writer is appending prose outside the YAML');
+        }
+        try {
+            data = parseYaml(split.head) ?? {};
+        }
+        catch (err) {
+            data = {};
+            warnings.push(`YAML did not parse: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    if (typeof data !== 'object' || data === null) {
+        data = {};
+        warnings.push('record did not parse to an object');
+    }
+    // ---- id: frontmatter ISS-NNNN, else the filename ------------------------
+    const fmId = str(data.id);
+    const id = (fmId && /^ISS-\d+$/i.test(fmId) ? fmId.toUpperCase() : undefined) ??
+        filename.match(/^(ISS-\d+)/i)?.[1]?.toUpperCase() ??
+        fmId ??
+        filename.replace(/\.(md|ya?ml)$/i, '');
+    // ---- title: frontmatter wins, then the heading, then the filename -------
+    //
+    // Frontmatter first, because the writer puts a title there ONLY when the
+    // body cannot hold it — no heading at all, or a title containing a newline,
+    // which a `# heading` truncates at the line break. Reading the heading first
+    // meant a multi-line title came back as its first line, from a record whose
+    // frontmatter held the whole thing: "first line\nsecond line" read back as
+    // "first line", with create_issue reporting success.
+    //
+    // Preferring frontmatter cannot regress a record that predates this, because
+    // the writer never emitted both: `title` went to frontmatter exactly when
+    // there was no heading to compete with it.
+    const heading = body.match(/^#\s+(.+)$/m)?.[1]?.trim();
+    const fmTitle = str(data.title);
+    const title = fmTitle ?? heading ?? filename.replace(/\.(md|ya?ml)$/i, '');
+    if (!heading && !fmTitle) {
+        warnings.push('no title in heading or frontmatter — fell back to the filename');
+    }
+    // ---- status: the whole reason this codec exists -------------------------
+    const norm = normalizeStatus(data.status);
+    if (norm.unrecognized) {
+        warnings.push(`unrecognized status ${JSON.stringify(data.status)} — read as ${norm.status}`);
+    }
+    else if (norm.normalizedFrom) {
+        warnings.push(`status ${JSON.stringify(norm.normalizedFrom)} normalized to ${norm.status}`);
+    }
+    const uid = isUid(data.uid) ? data.uid : undefined;
+    if (data.uid !== undefined && !uid) {
+        warnings.push(`uid ${JSON.stringify(data.uid)} is not a valid UUIDv7 — ignored`);
+    }
+    const issue = {
+        uid,
+        id,
+        title,
+        status: norm.status,
+        severity: str(data.severity),
+        priority: str(data.priority),
+        // An empty tag list and no tag list mean the same thing, and encode omits
+        // empty arrays — so decoding [] to [] would make the codec non-idempotent.
+        // Twelve records in the store carry `tags: []`; the corpus test caught it.
+        tags: normalizeTags(data.tags),
+        epicId: str(data.epic_id) ?? str(data.epicId),
+        // Both spellings exist; `projectId` is the markdown writer's, `project` the
+        // YAML writer's. The model has one, and encode puts it back where it came from.
+        project: str(data.project) ?? str(data.projectId),
+        details: str(data.description) ?? extractDetails(body),
+        resolution: str(data.resolution),
+        created_at: str(data.created_at),
+        updated_at: str(data.updated_at),
+        closed_at: str(data.closed_at),
+    };
+    // Strip model-owned keys; whatever remains is carried through untouched.
+    const preserved = {};
+    for (const [k, v] of Object.entries(data)) {
+        if (!MODEL_KEYS.has(k) && k !== 'projectId')
+            preserved[k] = v;
+    }
+    return { issue, format, raw: { data: preserved, body }, warnings };
+}
+/**
+ * Rewrite the derived header lines in a markdown body from the model.
+ *
+ * Only lines that already exist are updated — this does not inject a mirror
+ * into a record that never had one, because the mirror is a convention of the
+ * markdown writer's layout, not a requirement of the format.
+ */
+function syncBodyMirror(body, issue) {
+    let out = body;
+    out = out.replace(/^\*\*Status:\*\* .*$/m, `**Status:** ${issue.status}`);
+    if (issue.severity) {
+        out = out.replace(/^\*\*Severity:\*\* .*$/m, `**Severity:** ${issue.severity}`);
+    }
+    if (issue.epicId) {
+        out = out.replace(/^\*\*Epic:\*\* .*$/m, `**Epic:** ${issue.epicId}`);
+    }
+    // The heading is the title's home in this format; keep them in step.
+    //
+    // Only ever the FIRST LINE. Splicing a multi-line title into the heading
+    // line pushed its remaining lines into the body as loose prose — and since
+    // the writer had already put them there once, they appeared twice. The
+    // authoritative copy of such a title is in frontmatter (see encodeIssue);
+    // this is the human-readable rendering of it.
+    out = out.replace(/^#\s+.+$/m, `# ${issue.title.split(/\r?\n/)[0]}`);
+    // Resolution is rendered into the body for the same reason status is: a
+    // markdown record is read by people, and `## Resolution` is where they look.
+    // It is regenerated from the model rather than stored there, so it cannot
+    // drift from frontmatter the way the status mirror did. Writing it ONLY to
+    // frontmatter would have been the tidier data model and the worse record —
+    // the prose would have silently vanished from every closed issue.
+    if (issue.resolution) {
+        const section = `## Resolution\n\n${issue.resolution}\n`;
+        out = /^##\s+Resolution\s*$/m.test(out)
+            ? out.replace(/^##\s+Resolution\s*\n[\s\S]*?(?=\n##\s|$)/m, section)
+            : `${out.replace(/\s+$/, '')}\n\n${section}`;
+    }
+    return out;
+}
+export function encodeIssue(decoded) {
+    const { issue, format, raw } = decoded;
+    const data = {};
+    const put = (k, v) => {
+        if (v !== undefined && v !== null && !(Array.isArray(v) && v.length === 0))
+            data[k] = v;
+    };
+    // Field order is stable so diffs stay readable across writes.
+    put('uid', issue.uid);
+    put('id', issue.id);
+    // Markdown records normally carry the title in the `# heading`, and writing
+    // it to frontmatter as well would create a second copy to drift — the same
+    // mistake as the status mirror. But a record with no heading has nowhere else
+    // to keep it, and omitting it there means the title is silently replaced by
+    // the filename on the next read. So: frontmatter holds the title exactly when
+    // the body cannot.
+    //
+    // A MULTI-LINE TITLE IS A TITLE THE BODY CANNOT HOLD. A markdown heading ends
+    // at the newline, so `# first\nsecond` is a heading reading "first" followed
+    // by a stray paragraph, and the record came back a line long with no error
+    // anywhere in the chain (ISS-0155). YAML quotes and escapes it exactly, so
+    // frontmatter is the only container that round-trips one.
+    const bodyHasHeading = /^#\s+.+$/m.test(raw.body);
+    const titleFitsAHeading = !/[\r\n]/.test(issue.title);
+    if (format === 'yaml' || !bodyHasHeading || !titleFitsAHeading)
+        put('title', issue.title);
+    // The markdown writer spells it projectId; keep each format's own spelling so
+    // a rewrite is not a gratuitous diff on every record.
+    put(format === 'md' ? 'projectId' : 'project', issue.project);
+    put('severity', issue.severity);
+    put('status', issue.status);
+    put('priority', issue.priority);
+    put('epic_id', issue.epicId);
+    put('tags', issue.tags);
+    put('created_at', issue.created_at);
+    put('updated_at', issue.updated_at);
+    put('closed_at', issue.closed_at);
+    // Bare YAML keeps prose in `description`; markdown keeps it in the body.
+    if (format === 'yaml')
+        put('description', issue.details);
+    put('resolution', issue.resolution);
+    // Preserved unknown keys land after the model's, so they never displace a
+    // known field's position but are never lost either.
+    for (const [k, v] of Object.entries(raw.data))
+        if (!(k in data))
+            data[k] = v;
+    const yaml = stringifyYaml(data, { lineWidth: 0 });
+    if (format === 'md') {
+        const body = syncBodyMirror(raw.body, issue);
+        return `---\n${yaml}---\n${body}`;
+    }
+    // A bare-YAML tail should not exist post-Phase-2, but if one is present it is
+    // pre-existing prose and gets preserved rather than dropped.
+    return raw.body.trim() ? `${yaml}\n${raw.body}` : yaml;
+}
+/** Apply changes to a decoded record, keeping derived state consistent. */
+export function applyIssueChanges(decoded, changes) {
+    return { ...decoded, issue: { ...decoded.issue, ...changes } };
+}
+//# sourceMappingURL=issueCodec.js.map

package/dist/domain/issueCodec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"issueCodec.js","sourceRoot":"","sources":["../../src/domain/issueCodec.ts"],"names":[],"mappings":"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"}

package/dist/domain/issueRepository.d.ts

@@ -0,0 +1,91 @@
+import { Issue, IssuePriority, IssueSeverity, IssueStatus } from './issue.js';
+import { IssueFormat } from './issueCodec.js';
+/** An issue plus where it lives. The path is for diagnostics, not for callers to write through. */
+export interface StoredIssue {
+    issue: Issue;
+    filename: string;
+    path: string;
+    format: IssueFormat;
+    /** Integrity observations from decoding. Empty for a healthy record. */
+    warnings: string[];
+}
+export interface IssueListFilter {
+    status?: IssueStatus;
+    /** All non-terminal statuses. Distinct from status:'open', which is one value. */
+    liveOnly?: boolean;
+    epicId?: string;
+}
+export interface CreateIssueSpec {
+    title: string;
+    details: string;
+    severity: IssueSeverity;
+    priority?: IssuePriority;
+    epicId?: string;
+    tags?: string[];
+    project?: string;
+}
+/**
+ * Integrity state of the whole store, reported alongside a listing rather than
+ * discovered mid-incident.
+ *
+ * The distinction that matters: `malformed` records are invisible to callers,
+ * so a silent skip would make a broken store look like a shorter clean one.
+ * `degraded` records are readable but carry something the codec had to
+ * interpret. Both are repair queues, not cosmetics — a duplicate id makes an
+ * issue unwritable, because the repository refuses an ambiguous target.
+ */
+export interface StoreIntegrity {
+    malformed: string[];
+    degraded: Array<{
+        filename: string;
+        warnings: string[];
+    }>;
+    duplicateIds: Record<string, string[]>;
+}
+export interface IssueRepository {
+    integrity(): Promise<StoreIntegrity>;
+    list(filter?: IssueListFilter): Promise<StoredIssue[]>;
+    get(idOrFilename: string): Promise<StoredIssue | null>;
+    create(spec: CreateIssueSpec): Promise<StoredIssue>;
+    update(idOrFilename: string, changes: Partial<Issue>): Promise<StoredIssue>;
+    close(idOrFilename: string, resolution: string, status?: 'closed' | 'wontfix'): Promise<StoredIssue>;
+}
+export declare class AmbiguousIssueIdError extends Error {
+    readonly issueId: string;
+    readonly candidates: string[];
+    readonly code = "AMBIGUOUS_ISSUE_ID";
+    constructor(issueId: string, candidates: string[]);
+}
+export declare class IssueNotFoundError extends Error {
+    readonly issueId: string;
+    readonly code = "ISSUE_NOT_FOUND";
+    constructor(issueId: string);
+}
+export declare class FsIssueRepository implements IssueRepository {
+    private readonly issuesDir;
+    constructor(issuesDir: string);
+    private readAll;
+    /**
+     * Duplicate detection deliberately runs over EVERY record, never a filtered
+     * subset: a closed twin still makes an id ambiguous for writers, so filtering
+     * it out of a listing must not filter it out of the collision report.
+     */
+    integrity(): Promise<StoreIntegrity>;
+    list(filter?: IssueListFilter): Promise<StoredIssue[]>;
+    /**
+     * Resolve an id to exactly one record, in tiers of decreasing specificity.
+     *
+     * Only the first non-empty tier is considered, and ambiguity is reported
+     * within a tier rather than across tiers — so naming a record by its filename
+     * stays a reliable way to pick one member of a duplicate pair even while the
+     * shared ISS-NNNN remains ambiguous. uid is checked first because it is the
+     * only identifier guaranteed unique by construction.
+     */
+    private resolve;
+    get(idOrFilename: string): Promise<StoredIssue | null>;
+    private requireOne;
+    create(spec: CreateIssueSpec): Promise<StoredIssue>;
+    update(idOrFilename: string, changes: Partial<Issue>): Promise<StoredIssue>;
+    close(idOrFilename: string, resolution: string, status?: 'closed' | 'wontfix'): Promise<StoredIssue>;
+}
+//# sourceMappingURL=issueRepository.d.ts.map

package/dist/domain/issueRepository.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"issueRepository.d.ts","sourceRoot":"","sources":["../../src/domain/issueRepository.ts"],"names":[],"mappings":"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"}

package/dist/domain/issueRepository.js

@@ -0,0 +1,257 @@
+// ============================================================================
+// Issue repository — EPIC-0038 Phase 3
+// ============================================================================
+// The seam between "what an issue is" and "where issues live".
+//
+// Callers ask for issues by id and get back canonical Issue objects. They do
+// not learn whether a record was markdown-with-frontmatter or bare YAML, which
+// directory it came from, or how its id was resolved. That is the whole point:
+// Phase 5 converges the on-disk format and should be a change to the codec and
+// this file only, and a future SupabaseIssueRepository should be a sibling
+// rather than a rewrite of every caller.
+//
+// Resolution is the subtle part. An id can name more than one record — four
+// duplicate groups existed before Phase 2 repaired them — and the historical
+// failure mode was `files.find(...)` picking whichever the directory listing
+// happened to yield first, so writers had an undefined target and reported
+// success either way. Ambiguity is therefore an error here, never a guess.
+// ============================================================================
+import { promises as fs } from 'fs';
+import path from 'path';
+import { writeFileAtomic } from '../lib/atomicWrite.js';
+import { allocateAndWriteIssue } from '../lib/recordIdAllocator.js';
+import { listDirOrThrow } from '../tools/shared/storeRead.js';
+import { isLive, newUid, } from './issue.js';
+import { decodeIssue, encodeIssue, } from './issueCodec.js';
+export class AmbiguousIssueIdError extends Error {
+    issueId;
+    candidates;
+    code = 'AMBIGUOUS_ISSUE_ID';
+    constructor(issueId, candidates) {
+        super(`Issue id ${issueId} matches ${candidates.length} records: ${candidates.join(', ')}. ` +
+            `Name one by filename, or by its uid, to disambiguate.`);
+        this.issueId = issueId;
+        this.candidates = candidates;
+        this.name = 'AmbiguousIssueIdError';
+    }
+}
+export class IssueNotFoundError extends Error {
+    issueId;
+    code = 'ISSUE_NOT_FOUND';
+    constructor(issueId) {
+        super(`Issue ${issueId} not found.`);
+        this.issueId = issueId;
+        this.name = 'IssueNotFoundError';
+    }
+}
+const RECORD_RE = /\.(md|ya?ml)$/i;
+function slugify(text) {
+    return text
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 50);
+}
+export class FsIssueRepository {
+    issuesDir;
+    constructor(issuesDir) {
+        this.issuesDir = issuesDir;
+    }
+    async readAll() {
+        // ISS-0153. ENOENT is the only error that means "empty": a directory that
+        // was never created is what an untouched project looks like. EACCES,
+        // EPERM, EIO and the rest mean the issues may well be there and this
+        // process cannot see them — returning [] there reported "no issues" for a
+        // store it could not open, and list_issues is the read most likely to be
+        // believed.
+        const names = await listDirOrThrow(this.issuesDir, (f) => RECORD_RE.test(f));
+        const out = [];
+        for (const filename of names) {
+            const full = path.join(this.issuesDir, filename);
+            let content;
+            try {
+                content = await fs.readFile(full, 'utf-8');
+            }
+            catch {
+                continue; // Unreadable record: skip rather than fail the whole listing.
+            }
+            const decoded = decodeIssue(filename, content);
+            out.push({
+                issue: decoded.issue,
+                filename,
+                path: full,
+                format: decoded.format,
+                warnings: decoded.warnings,
+            });
+        }
+        return out;
+    }
+    /**
+     * Duplicate detection deliberately runs over EVERY record, never a filtered
+     * subset: a closed twin still makes an id ambiguous for writers, so filtering
+     * it out of a listing must not filter it out of the collision report.
+     */
+    async integrity() {
+        const all = await this.readAll();
+        const malformed = [];
+        const degraded = [];
+        const claims = new Map();
+        for (const r of all) {
+            const unparseable = r.warnings.some((w) => w.includes('did not parse'));
+            if (unparseable)
+                malformed.push(r.filename);
+            else if (r.warnings.length > 0)
+                degraded.push({ filename: r.filename, warnings: r.warnings });
+            const key = r.issue.id.toUpperCase();
+            claims.set(key, [...(claims.get(key) ?? []), r.filename]);
+        }
+        const duplicateIds = {};
+        for (const [id, files] of claims)
+            if (files.length > 1)
+                duplicateIds[id] = files;
+        return { malformed, degraded, duplicateIds };
+    }
+    async list(filter = {}) {
+        // A record that did not parse is not an issue — returning it would hand
+        // callers a husk built from filename fallbacks. It is still counted by
+        // integrity(), so the file is reported rather than silently dropped.
+        let all = (await this.readAll()).filter((r) => !r.warnings.some((w) => w.includes('did not parse')));
+        if (filter.status)
+            all = all.filter((r) => r.issue.status === filter.status);
+        if (filter.liveOnly)
+            all = all.filter((r) => isLive(r.issue.status));
+        if (filter.epicId)
+            all = all.filter((r) => r.issue.epicId === filter.epicId);
+        return all;
+    }
+    /**
+     * Resolve an id to exactly one record, in tiers of decreasing specificity.
+     *
+     * Only the first non-empty tier is considered, and ambiguity is reported
+     * within a tier rather than across tiers — so naming a record by its filename
+     * stays a reliable way to pick one member of a duplicate pair even while the
+     * shared ISS-NNNN remains ambiguous. uid is checked first because it is the
+     * only identifier guaranteed unique by construction.
+     */
+    async resolve(idOrFilename) {
+        const all = await this.readAll();
+        const needle = idOrFilename.trim();
+        const upper = needle.toUpperCase();
+        const byUid = all.filter((r) => r.issue.uid && r.issue.uid === needle);
+        if (byUid.length > 0)
+            return byUid;
+        const byFilename = all.filter((r) => r.filename.toUpperCase() === upper);
+        if (byFilename.length > 0)
+            return byFilename;
+        // Filename without the extension, which is how list output used to name records.
+        const byStem = all.filter((r) => r.filename.replace(RECORD_RE, '').toUpperCase() === upper.replace(RECORD_RE, ''));
+        if (byStem.length > 0)
+            return byStem;
+        // ISS-NNNN, requiring the id to end at a separator or the extension. A bare
+        // startsWith made "ISS-011" swallow ISS-0110, ISS-0112 and ISS-0119.
+        const byId = all.filter((r) => {
+            if (r.issue.id.toUpperCase() === upper)
+                return true;
+            const base = r.filename.toUpperCase();
+            if (!base.startsWith(upper))
+                return false;
+            const rest = base.slice(upper.length);
+            return rest === '' || rest.startsWith('-') || /^\.(MD|YA?ML)$/.test(rest);
+        });
+        if (byId.length > 0)
+            return byId;
+        // Last tier: a partial id like "ISS-011", which is a prefix of ISS-0110,
+        // ISS-0112 and ISS-0119. The boundary rule above deliberately refuses to
+        // resolve it, but refusing is not the same as saying nothing is there —
+        // "not found" would be a misleading answer when three records obviously
+        // start with it. So a loose prefix is reported as a collision when it spans
+        // several records, and is NEVER resolved to a single one: silently picking
+        // one is the swallow bug this whole tier system exists to prevent.
+        const loose = all.filter((r) => r.filename.toUpperCase().startsWith(upper));
+        return loose.length > 1 ? loose : [];
+    }
+    async get(idOrFilename) {
+        const matches = await this.resolve(idOrFilename);
+        if (matches.length === 0)
+            return null;
+        if (matches.length > 1) {
+            throw new AmbiguousIssueIdError(idOrFilename, matches.map((m) => m.filename));
+        }
+        return matches[0];
+    }
+    async requireOne(idOrFilename) {
+        const found = await this.get(idOrFilename);
+        if (!found)
+            throw new IssueNotFoundError(idOrFilename);
+        return found;
+    }
+    async create(spec) {
+        const now = new Date().toISOString();
+        const slug = slugify(spec.title);
+        // Allocation and write happen under one cross-process lock (Phase 1). Every
+        // new record gets a uid at birth, so the backfill only ever has to deal
+        // with records that predate this path.
+        const issue = {
+            uid: newUid(),
+            id: 'ISS-PENDING',
+            title: spec.title,
+            status: 'open',
+            severity: spec.severity,
+            priority: spec.priority,
+            tags: spec.tags,
+            epicId: spec.epicId,
+            project: spec.project,
+            details: spec.details,
+            created_at: now,
+        };
+        const build = (issueId) => {
+            const body = [
+                // First line only — a heading ends at the newline, so the rest would
+                // land in the body as stray prose. encodeIssue writes the whole title
+                // to frontmatter when it does not fit here.
+                `# ${spec.title.split(/\r?\n/)[0]}`,
+                '',
+                `**Severity:** ${spec.severity}`,
+                `**Status:** open`,
+                ...(spec.epicId ? [`**Epic:** ${spec.epicId}`] : []),
+                '',
+                '## Details',
+                '',
+                spec.details,
+                '',
+            ].join('\n');
+            const decoded = {
+                issue: { ...issue, id: issueId },
+                format: 'md',
+                raw: { data: {}, body },
+                warnings: [],
+            };
+            return encodeIssue(decoded);
+        };
+        const allocated = await allocateAndWriteIssue(this.issuesDir, 'md', slug, build);
+        return this.requireOne(allocated.filename);
+    }
+    async update(idOrFilename, changes) {
+        const current = await this.requireOne(idOrFilename);
+        const content = await fs.readFile(current.path, 'utf-8');
+        const decoded = decodeIssue(current.filename, content);
+        const updated = {
+            ...decoded,
+            issue: {
+                ...decoded.issue,
+                ...changes,
+                // Identity is not editable through update. Renumbering is a migration.
+                uid: decoded.issue.uid ?? changes.uid,
+                id: decoded.issue.id,
+                updated_at: new Date().toISOString(),
+            },
+        };
+        await writeFileAtomic(current.path, encodeIssue(updated));
+        return this.requireOne(current.filename);
+    }
+    async close(idOrFilename, resolution, status = 'closed') {
+        const now = new Date().toISOString();
+        return this.update(idOrFilename, { status, resolution, closed_at: now });
+    }
+}
+//# sourceMappingURL=issueRepository.js.map