@svenroth-ai/shipwright 0.24.1-next.0

package/server/dist/core/mission-context/decisions.js

@@ -0,0 +1,222 @@
+/*
+ * core/mission-context/decisions.ts — the DECISIONS artifact source
+ * (CONTRACT §6 row 5 / §10 Slice-2, campaign 2026-07-18-mission-artifacts).
+ *
+ * `.shipwright/agent_docs/decision_log.md` is a 639 KB append-only log of EVERY
+ * ADR this project ever recorded. The provenance problem external-review GPT #10
+ * closed is what makes it usable: each iterate's ADR carries a
+ * `- **Run-ID:** <run_id>` bullet, so this run's decisions are an EXACT-MATCH
+ * filter — not a date heuristic, not "the last N entries". That exactness is
+ * AC3: a concurrent iterate's ADRs, written into the same file minutes apart,
+ * can never leak into this run.
+ *
+ * Two disciplines this module exists to keep (S1 review lessons):
+ *
+ *   1. SCOPE THE READ TO THE SECTION THE CONTRACT NAMED. The right panel renders
+ *      "the ADR Markdown", not the decision log. So we extract the matched ADR
+ *      BLOCKS and render those — pointing the viewer at the whole 639 KB file
+ *      would bury this run's two decisions under four hundred unrelated ones.
+ *   2. BOUND EVERYTHING. Entry count, per-entry size and total size are all
+ *      capped, and truncation is REPORTED rather than silently applied.
+ */
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { readRunDrops } from "./decision-drops.js";
+import { readBoundedFile } from "./fs-read.js";
+import { pathGuard } from "../path-guard.js";
+export const DECISION_LOG_REL = ".shipwright/agent_docs/decision_log.md";
+/** Real file is ~640 KB and only grows; 16 MB bounds it with room to spare. */
+const MAX_LOG_BYTES = 16 * 1024 * 1024;
+/** One iterate records a handful of ADRs. 20 is a generous, bounded ceiling. */
+export const MAX_DECISION_ENTRIES = 20;
+/** Per-entry and total caps on the Markdown carried into the response. */
+const MAX_ENTRY_CHARS = 64 * 1024;
+const MAX_TOTAL_CHARS = 256 * 1024;
+/** Absolute path to the decision log — used for `sourceRev` probing. */
+export function decisionLogPath(projectRoot) {
+    return path.join(projectRoot, ...DECISION_LOG_REL.split("/"));
+}
+/** An ADR heading at h1–h4: `### ADR-070: title`. */
+const ADR_HEADING = /^#{1,4}[ \t]+(ADR-[0-9A-Za-z._-]+)[ \t]*(?::[ \t]*(.*))?$/;
+/** Any h1–h3 heading closes the previous ADR block. */
+const BLOCK_BOUNDARY = /^#{1,3}[ \t]+\S/;
+/**
+ * The Run-ID bullet. BOTH real spellings occur in this repo's log and both must
+ * match, or a third of the entries would silently never resolve:
+ *   `- **Run-ID:** iterate-…`   (colon inside the bold)
+ *   `- **Run-ID**: iterate-…`   (colon outside)
+ */
+const RUN_ID_BULLET = /^[ \t]*[-*][ \t]*\*\*Run-ID[ \t]*:?[ \t]*\*\*[ \t]*:?[ \t]*(\S.*)$/i;
+/**
+ * The recorded value, normalised for comparison: strip Markdown code ticks,
+ * quotes and trailing punctuation a human may have typed around it.
+ */
+function normaliseRunId(raw) {
+    return raw
+        .trim()
+        .replace(/^[`'"]+/, "")
+        .replace(/[`'".,;]+$/, "")
+        .trim();
+}
+/** The Run-ID this block declares, or null when it declares none. */
+export function blockRunId(block) {
+    for (const line of block.split(/\r?\n/)) {
+        const m = RUN_ID_BULLET.exec(line);
+        if (m) {
+            const v = normaliseRunId(m[1]);
+            return v.length > 0 ? v : null;
+        }
+    }
+    return null;
+}
+/**
+ * Split the log into ADR blocks. Exported for direct unit testing — the
+ * splitting rule is the fragile part and deserves its own cases.
+ */
+export function splitAdrBlocks(text) {
+    const lines = text.split(/\r?\n/);
+    const blocks = [];
+    let current = null;
+    for (const line of lines) {
+        const heading = ADR_HEADING.exec(line);
+        if (heading) {
+            if (current)
+                blocks.push(current);
+            current = { adrId: heading[1], title: (heading[2] ?? "").trim(), lines: [line] };
+            continue;
+        }
+        if (current && BLOCK_BOUNDARY.test(line)) {
+            // A non-ADR h1–h3 heading ends the block — an ADR body never contains one.
+            blocks.push(current);
+            current = null;
+            continue;
+        }
+        if (current)
+            current.lines.push(line);
+    }
+    if (current)
+        blocks.push(current);
+    return blocks;
+}
+/**
+ * The ADRs this run recorded.
+ *
+ * `unavailable` means the log itself could not be read. An `ok` with zero
+ * entries means the log WAS read and this run recorded no ADR — a real, honest
+ * answer, and the caller renders the two cases differently.
+ */
+export function readRunDecisions(projectRoot, runId) {
+    if (typeof runId !== "string" || runId.trim().length === 0) {
+        return { status: "unavailable", reason: "missing" };
+    }
+    const guard = pathGuard(projectRoot, DECISION_LOG_REL);
+    if (!guard.ok)
+        return { status: "unavailable", reason: "denied" };
+    if (!existsSync(guard.absolute))
+        return { status: "unavailable", reason: "missing" };
+    const read = readBoundedFile(guard.absolute, MAX_LOG_BYTES);
+    if (!read)
+        return { status: "unavailable", reason: "too_large" };
+    const wanted = runId.trim();
+    const entries = [];
+    let truncated = false;
+    let totalChars = 0;
+    for (const block of splitAdrBlocks(read.text)) {
+        const text = block.lines.join("\n").trimEnd();
+        // EXACT match — the whole point of the Run-ID tag (AC3). A prefix or
+        // substring test would let `…-mission-s2` match `…-mission-s2-followup`.
+        if (blockRunId(text) !== wanted)
+            continue;
+        if (entries.length >= MAX_DECISION_ENTRIES) {
+            truncated = true;
+            break;
+        }
+        const clipped = text.length > MAX_ENTRY_CHARS ? `${text.slice(0, MAX_ENTRY_CHARS)}\n\n…` : text;
+        if (totalChars + clipped.length > MAX_TOTAL_CHARS) {
+            truncated = true;
+            break;
+        }
+        totalChars += clipped.length;
+        if (clipped.length < text.length)
+            truncated = true;
+        entries.push({ adrId: block.adrId, title: block.title, markdown: clipped });
+    }
+    return { status: "ok", entries, truncated };
+}
+/** Join key between a drop and the log entry it became. */
+function titleKey(title) {
+    return title.trim().replace(/\s+/g, " ").toLowerCase();
+}
+/**
+ * The run's decisions from **drops ∪ decision_log**, merged PER ENTRY.
+ *
+ * The dedupe granularity is the load-bearing detail, and an earlier version got
+ * it wrong: it keyed on the RUN, returning early whenever the log held any entry
+ * for this run and never reading the drops at all. The record's true granularity
+ * is run + `_NNN`, and those coincide only if aggregation were all-or-nothing.
+ * It is not — `aggregate_decisions.py` snapshots the drops it will fold, writes
+ * them, then unlinks them ONE AT A TIME, so a drop written mid-aggregation is
+ * never snapshotted and simply stays on disk. A run could therefore have `_001`
+ * published and `_002` still pending, and the run-level short-circuit rendered
+ * the first while the second vanished with `sawUnreadable: false` — a decision
+ * lost silently, by the function written to stop decisions being lost silently.
+ *
+ * So: read BOTH, always. A drop whose TITLE matches a published entry has been
+ * folded and is suppressed as the duplicate it is (`format_entry` renders the
+ * drop's own `title` as the ADR heading, and a drop with no title never becomes
+ * an entry here, so the join holds for exactly the drops we would render). Every
+ * other drop is still pending and renders unnumbered. The log wins on conflict;
+ * it no longer wins on mere presence.
+ */
+export function readRunDecisionRecord(projectRoot, runId) {
+    const log = readRunDecisions(projectRoot, runId);
+    // Read unconditionally. A readable log must never be allowed to assert that
+    // an unread drops directory held nothing — the second half of the same bug.
+    const drops = readRunDrops(projectRoot, runId);
+    // An ABSENT decision_log.md is not a fault — it is a project that has never
+    // had a release aggregation, which is most of them. Only a log that is there
+    // and unusable (denied, over the cap) is. Treating `missing` as a fault would
+    // pin Decisions at "records could not be read" for every such project even
+    // when the drops answered perfectly well: the very confusion this iterate is
+    // about, rebuilt one level up. (Caught by its own test, not by review.)
+    //
+    // An empty/invalid runId also reports `missing` here, but it independently
+    // fails `isSafeRunId` in the drops reader → `denied` → still surfaced below.
+    const logUnreadable = log.status === "unavailable" && log.reason !== "missing";
+    const logEntries = log.status === "ok" ? log.entries : [];
+    const logTruncated = log.status === "ok" && log.truncated;
+    const dropsUnreadable = drops.status === "unavailable";
+    const dropEntries = drops.status === "ok" ? drops.entries : [];
+    const dropsTruncated = drops.status === "ok" && drops.truncated;
+    const malformedCount = drops.status === "ok" ? drops.malformed : 0;
+    // Published titles suppress their own drop; everything else is still pending.
+    const published = new Set(logEntries.map((e) => titleKey(e.title)).filter((k) => k.length > 0));
+    const pending = dropEntries.filter((d) => !published.has(titleKey(d.title)));
+    return {
+        entries: [
+            ...logEntries.map((e) => ({
+                adrId: e.adrId,
+                title: e.title,
+                markdown: e.markdown,
+                source: "decision_log",
+            })),
+            ...pending.map((d) => ({
+                adrId: null,
+                title: d.title,
+                markdown: d.markdown,
+                source: "drop",
+            })),
+        ],
+        // BOTH sources' truncation, not just the drops'. A bounded scan that was cut
+        // short has not established that this run has no further decision.
+        truncated: logTruncated || dropsTruncated,
+        malformedCount,
+        // Every way either source could have lost something, OR-ed in ONE place so
+        // no branch can hardcode `false` without looking — which is exactly what the
+        // run-level short-circuit used to do.
+        sawUnreadable: logUnreadable || dropsUnreadable || malformedCount > 0 || logTruncated || dropsTruncated,
+        // The uncountable subset, for the sentence that cannot cite a number.
+        logOrScanLoss: logUnreadable || dropsUnreadable || logTruncated || dropsTruncated,
+    };
+}
+//# sourceMappingURL=decisions.js.map

package/server/dist/core/mission-context/decisions.js.map

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

package/server/dist/core/mission-context/doc-ids.d.ts

@@ -0,0 +1,35 @@
+export interface DocIdPayload {
+    /** Binding: the task this descriptor was built for. */
+    t: string;
+    /** Binding: the session uuid. */
+    s: string;
+    /** Binding: the project root the resolve ran against. */
+    p: string;
+    /** The iterate run id. */
+    r: string;
+    /** The root the document was resolved in (project root or a worktree). */
+    root: string;
+    /** Known-layout relative path segments, joined with "/". */
+    rel: string;
+    /** Context-wide source revision at mint time. */
+    rev: string;
+    /**
+     * PER-DOCUMENT fingerprint (`<size>:<mtimeMs>`) at mint time.
+     *
+     * The context-wide `rev` is not sufficient for AC3: it is derived from the
+     * adopted spec + event log, so editing only the iterate document would leave
+     * it unchanged and the detail endpoint would silently serve the NEW body as
+     * `ok` (external code review, openai HIGH). The detail endpoint recomputes
+     * this and reports `stale` on any difference.
+     */
+    f: string;
+}
+/** Mint an opaque id for a resolved document. */
+export declare function mintDocId(payload: DocIdPayload): string;
+/**
+ * Verify + decode. Returns null on ANY defect (shape, signature, JSON, missing
+ * field) — the caller then 404s with a generic message rather than explaining
+ * which part failed, so the endpoint is not an oracle.
+ */
+export declare function parseDocId(id: unknown): DocIdPayload | null;
+//# sourceMappingURL=doc-ids.d.ts.map

package/server/dist/core/mission-context/doc-ids.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doc-ids.d.ts","sourceRoot":"","sources":["../../../src/core/mission-context/doc-ids.ts"],"names":[],"mappings":"AA6BA,MAAM,WAAW,YAAY;IAC3B,uDAAuD;IACvD,CAAC,EAAE,MAAM,CAAC;IACV,iCAAiC;IACjC,CAAC,EAAE,MAAM,CAAC;IACV,yDAAyD;IACzD,CAAC,EAAE,MAAM,CAAC;IACV,0BAA0B;IAC1B,CAAC,EAAE,MAAM,CAAC;IACV,0EAA0E;IAC1E,IAAI,EAAE,MAAM,CAAC;IACb,4DAA4D;IAC5D,GAAG,EAAE,MAAM,CAAC;IACZ,iDAAiD;IACjD,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;;;OAQG;IACH,CAAC,EAAE,MAAM,CAAC;CACX;AAeD,iDAAiD;AACjD,wBAAgB,SAAS,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM,CAGvD;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,EAAE,EAAE,OAAO,GAAG,YAAY,GAAG,IAAI,CA2B3D"}

package/server/dist/core/mission-context/doc-ids.js

@@ -0,0 +1,78 @@
+/*
+ * core/mission-context/doc-ids.ts — OPAQUE artifact-document ids
+ * (CONTRACT §5.2, Review-2 GPT #9).
+ *
+ * The client must NOT construct `/file?path=…` for a Mission artifact. If it
+ * did, the path rules would exist in two places and the descriptor and the file
+ * read would drift — the classic "the UI shows spec A but fetches file B" bug.
+ * Instead the resolver mints an opaque, SIGNED id and the detail endpoint is
+ * the only thing that turns it back into a path.
+ *
+ * The id is a signed capability, not a secret: it carries the binding fields
+ * (task, session, project root, run, the chosen root, the relative path, and
+ * the source revision) under an HMAC over a per-process key. Tampering with any
+ * field invalidates the signature, so a caller cannot rewrite `relPath` to
+ * point at `../../.env`.
+ *
+ * The signature is NOT the security boundary on its own — the detail endpoint
+ * ALSO re-checks that the decoded task/session belong to the requesting
+ * project and re-runs pathGuard + realPathGuard against the decoded root. The
+ * HMAC is what makes those checks cheap and unambiguous; the guards are what
+ * make them safe. A per-process key means ids do not survive a restart, which
+ * is correct: they are request-scoped handles, not durable links.
+ */
+import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+/** Regenerated every boot — ids are ephemeral handles by design. */
+const KEY = randomBytes(32);
+function b64url(buf) {
+    return buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function unb64url(s) {
+    const pad = s.length % 4 === 0 ? "" : "=".repeat(4 - (s.length % 4));
+    return Buffer.from(s.replace(/-/g, "+").replace(/_/g, "/") + pad, "base64");
+}
+function sign(body) {
+    return b64url(createHmac("sha256", KEY).update(body).digest());
+}
+/** Mint an opaque id for a resolved document. */
+export function mintDocId(payload) {
+    const body = b64url(Buffer.from(JSON.stringify(payload), "utf-8"));
+    return `${body}.${sign(body)}`;
+}
+/**
+ * Verify + decode. Returns null on ANY defect (shape, signature, JSON, missing
+ * field) — the caller then 404s with a generic message rather than explaining
+ * which part failed, so the endpoint is not an oracle.
+ */
+export function parseDocId(id) {
+    if (typeof id !== "string" || id.length === 0 || id.length > 4096)
+        return null;
+    const dot = id.lastIndexOf(".");
+    if (dot <= 0 || dot === id.length - 1)
+        return null;
+    const body = id.slice(0, dot);
+    const sig = id.slice(dot + 1);
+    const expected = sign(body);
+    // Constant-time compare — lengths must match first (timingSafeEqual throws
+    // on a length mismatch, which would itself be a side channel).
+    const a = Buffer.from(sig, "utf-8");
+    const b = Buffer.from(expected, "utf-8");
+    if (a.length !== b.length || !timingSafeEqual(a, b))
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(unb64url(body).toString("utf-8"));
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        return null;
+    const o = parsed;
+    for (const k of ["t", "s", "p", "r", "root", "rel", "rev", "f"]) {
+        if (typeof o[k] !== "string" || o[k].length === 0)
+            return null;
+    }
+    return o;
+}
+//# sourceMappingURL=doc-ids.js.map

package/server/dist/core/mission-context/doc-ids.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"doc-ids.js","sourceRoot":"","sources":["../../../src/core/mission-context/doc-ids.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEvE,oEAAoE;AACpE,MAAM,GAAG,GAAG,WAAW,CAAC,EAAE,CAAC,CAAC;AA6B5B,SAAS,MAAM,CAAC,GAAW;IACzB,OAAO,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;AAC3F,CAAC;AAED,SAAS,QAAQ,CAAC,CAAS;IACzB,MAAM,GAAG,GAAG,CAAC,CAAC,MAAM,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC;IACrE,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,GAAG,GAAG,EAAE,QAAQ,CAAC,CAAC;AAC9E,CAAC;AAED,SAAS,IAAI,CAAC,IAAY;IACxB,OAAO,MAAM,CAAC,UAAU,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;AACjE,CAAC;AAED,iDAAiD;AACjD,MAAM,UAAU,SAAS,CAAC,OAAqB;IAC7C,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC;IACnE,OAAO,GAAG,IAAI,IAAI,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;AACjC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,UAAU,CAAC,EAAW;IACpC,IAAI,OAAO,EAAE,KAAK,QAAQ,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,IAAI;QAAE,OAAO,IAAI,CAAC;IAC/E,MAAM,GAAG,GAAG,EAAE,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IAChC,IAAI,GAAG,IAAI,CAAC,IAAI,GAAG,KAAK,EAAE,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAEnD,MAAM,IAAI,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAC9B,MAAM,GAAG,GAAG,EAAE,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC;IAC9B,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC;IAE5B,2EAA2E;IAC3E,+DAA+D;IAC/D,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IACpC,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IACzC,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM,IAAI,CAAC,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IAEjE,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC;IACxD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;QAAE,OAAO,IAAI,CAAC;IAChF,MAAM,CAAC,GAAG,MAAiC,CAAC;IAC5C,KAAK,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,CAAC,EAAE,CAAC;QAChE,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC,KAAK,QAAQ,IAAK,CAAC,CAAC,CAAC,CAAY,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;IAC7E,CAAC;IACD,OAAO,CAA4B,CAAC;AACtC,CAAC"}

package/server/dist/core/mission-context/document-read.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Re-resolve a document for the detail endpoint. `expectFingerprint` implements
+ * AC3's "changed → stale": the descriptor promised a specific revision, so a
+ * rewritten file reports `changed` rather than serving different content under
+ * an id the client believes points at what it was shown.
+ */
+export declare function readDocumentBody(root: string, relParts: string[], expectFingerprint?: string): {
+    ok: true;
+    body: string;
+} | {
+    ok: false;
+    reason: "denied" | "not_found" | "too_large" | "changed";
+};
+//# sourceMappingURL=document-read.d.ts.map

package/server/dist/core/mission-context/document-read.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-read.d.ts","sourceRoot":"","sources":["../../../src/core/mission-context/document-read.ts"],"names":[],"mappings":"AAgBA;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAAE,EAClB,iBAAiB,CAAC,EAAE,MAAM,GAExB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC1B;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,QAAQ,GAAG,WAAW,GAAG,WAAW,GAAG,SAAS,CAAA;CAAE,CAW1E"}

package/server/dist/core/mission-context/document-read.js

@@ -0,0 +1,36 @@
+/*
+ * core/mission-context/document-read.ts — the artifact-detail endpoint's
+ * document read (CONTRACT §5.2).
+ *
+ * Split out of `resolver.ts` in Slice 2: that file is the ORCHESTRATION of a
+ * context response, while this is a single re-read on a later, unrelated
+ * request. Keeping them together pushed resolver.ts past the 300-LOC rule and
+ * the two have no shared state — only the guards, which live in
+ * `worktree-roots.ts` either way.
+ */
+import { existsSync } from "node:fs";
+import { docFingerprint, readBounded } from "./resolver-parts.js";
+import { MAX_DOC_BYTES, resolveFirstDoc } from "./worktree-roots.js";
+/**
+ * Re-resolve a document for the detail endpoint. `expectFingerprint` implements
+ * AC3's "changed → stale": the descriptor promised a specific revision, so a
+ * rewritten file reports `changed` rather than serving different content under
+ * an id the client believes points at what it was shown.
+ */
+export function readDocumentBody(root, relParts, expectFingerprint) {
+    const r = resolveFirstDoc(root, [relParts]);
+    if (!r.ok)
+        return { ok: false, reason: r.reason === "denied" ? "denied" : "not_found" };
+    if (r.sizeBytes > MAX_DOC_BYTES)
+        return { ok: false, reason: "too_large" };
+    if (!existsSync(r.absolute))
+        return { ok: false, reason: "not_found" };
+    if (expectFingerprint && docFingerprint(r.absolute) !== expectFingerprint) {
+        return { ok: false, reason: "changed" };
+    }
+    const body = readBounded(r.absolute);
+    if (body == null)
+        return { ok: false, reason: "not_found" };
+    return { ok: true, body };
+}
+//# sourceMappingURL=document-read.js.map

package/server/dist/core/mission-context/document-read.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-read.js","sourceRoot":"","sources":["../../../src/core/mission-context/document-read.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAErC,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClE,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAErE;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAC9B,IAAY,EACZ,QAAkB,EAClB,iBAA0B;IAI1B,MAAM,CAAC,GAAG,eAAe,CAAC,IAAI,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC;IAC5C,IAAI,CAAC,CAAC,CAAC,EAAE;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;IACxF,IAAI,CAAC,CAAC,SAAS,GAAG,aAAa;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;IAC3E,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,QAAQ,CAAC;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;IACvE,IAAI,iBAAiB,IAAI,cAAc,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,iBAAiB,EAAE,CAAC;QAC1E,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;IAC1C,CAAC;IACD,MAAM,IAAI,GAAG,WAAW,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;IACrC,IAAI,IAAI,IAAI,IAAI;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;IAC5D,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AAC5B,CAAC"}

package/server/dist/core/mission-context/fold-map.d.ts

@@ -0,0 +1,45 @@
+import type { FrRow } from "./types.js";
+/** The adopted spec, relative to the project root. Constant — no user segment. */
+export declare const SPEC_REL_PARTS: string[];
+export declare function isFrId(v: unknown): v is string;
+export interface FrEntry {
+    id: string;
+    area: string | null;
+    name: string | null;
+    description: string | null;
+}
+export interface FoldMap {
+    /** Surviving capability rows, keyed by id. */
+    entries: Map<string, FrEntry>;
+    /** folded id → parent id (one hop; `resolveFr` follows the chain). */
+    folds: Map<string, string>;
+    /** True when spec.md was found and parsed — false means "resolve raw". */
+    loaded: boolean;
+}
+/**
+ * Parse the FR table rows + the `## FR-Fold-Map` alias table out of spec.md.
+ *
+ * Both are pipe tables, distinguished by shape rather than by position: a
+ * capability row's 2nd column is an AREA code, a fold row's 2nd column is
+ * another FR id. That keeps the parser stable if the sections move.
+ */
+export declare function parseFoldMap(specText: string): FoldMap;
+/**
+ * Load (and mtime-cache) the fold map for a project root. A missing or
+ * unreadable spec.md yields an EMPTY map with `loaded: false`, which makes
+ * `resolveFr` echo ids raw — the honest degradation, never a blank.
+ */
+export declare function loadFoldMap(projectRoot: string): FoldMap;
+/** Test-only cache reset. */
+export declare function _clearFoldMapCache(): void;
+/**
+ * Resolve one FR id to its display row. Follows a fold CHAIN (a folded id whose
+ * parent was itself later folded) with a hop bound and cycle detection; on a
+ * cycle it stops at the last id reached rather than throwing.
+ */
+export declare function resolveFr(map: FoldMap, originalFrId: string): FrRow;
+/** Resolve a list, dropping non-FR-shaped junk but keeping unknown-but-valid ids raw. */
+export declare function resolveFrList(map: FoldMap, ids: readonly string[]): FrRow[];
+/** Absolute path to the adopted spec (for sourceRev mtime probing). */
+export declare function specPath(projectRoot: string): string;
+//# sourceMappingURL=fold-map.d.ts.map

package/server/dist/core/mission-context/fold-map.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fold-map.d.ts","sourceRoot":"","sources":["../../../src/core/mission-context/fold-map.ts"],"names":[],"mappings":"AAyBA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAExC,kFAAkF;AAClF,eAAO,MAAM,cAAc,UAAuD,CAAC;AAQnF,wBAAgB,MAAM,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,MAAM,CAE9C;AAED,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED,MAAM,WAAW,OAAO;IACtB,8CAA8C;IAC9C,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,sEAAsE;IACtE,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC3B,0EAA0E;IAC1E,MAAM,EAAE,OAAO,CAAC;CACjB;AAqBD;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CA6BtD;AAQD;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAkBxD;AAED,6BAA6B;AAC7B,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC;AAKD;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,GAAG,KAAK,CAuBnE;AAED,yFAAyF;AACzF,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,SAAS,MAAM,EAAE,GAAG,KAAK,EAAE,CAa3E;AAED,uEAAuE;AACvE,wBAAgB,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAEpD"}

package/server/dist/core/mission-context/fold-map.js

@@ -0,0 +1,168 @@
+/*
+ * core/mission-context/fold-map.ts — resolve an FR id to its SURVIVING parent
+ * (CONTRACT §3.1 / §6; prereq PR #287).
+ *
+ * The 2026-07-17 taxonomy cleanup folded 37 endpoint/delta rows into their
+ * owning capability and recorded the aliases in `## FR-Fold-Map`. Historical
+ * `affected_frs` values and source `@fr` tags still name the FOLDED ids — that
+ * was deliberate (finer provenance), so every consumer must resolve through the
+ * map before display. The canonical example, and AC2 of this slice:
+ *   FR-01.44 (terminal appearance)  →  FR-01.28 (Embedded terminal)
+ *
+ * Honesty rule (§3.1, last clause): an id in NEITHER the table nor the map is
+ * shown RAW — never blanked, never silently dropped. A missing name is a
+ * display gap; a vanished requirement id would be a lie about what the run did.
+ *
+ * BOTH ids survive resolution (`originalFrId` + `displayFrId`) so the UI can
+ * say "FR-01.28 — mapped from FR-01.44" instead of quietly rewriting history.
+ */
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { readBoundedFile } from "./fs-read.js";
+import { pathGuard } from "../path-guard.js";
+/** The adopted spec, relative to the project root. Constant — no user segment. */
+export const SPEC_REL_PARTS = [".shipwright", "planning", "01-adopted", "spec.md"];
+/** Hard cap on spec.md — bounds a corrupt/huge file (CONTRACT §11). */
+const MAX_SPEC_BYTES = 4 * 1024 * 1024;
+/** `FR-01.66` — the immutable id grammar. */
+const FR_ID_RE = /^FR-\d{2}\.\d{2,3}$/;
+export function isFrId(v) {
+    return typeof v === "string" && FR_ID_RE.test(v);
+}
+const EMPTY_MAP = { entries: new Map(), folds: new Map(), loaded: false };
+/** Strip markdown code ticks + whitespace from a table cell. */
+function cell(s) {
+    return s.replace(/`/g, "").trim();
+}
+/** Keep the adopted row's user-facing capability sentence, not its markup or changelog. */
+function readableDescription(value) {
+    if (!value)
+        return null;
+    const leading = value.split(/<br\s*\/?>/i, 1)[0];
+    const text = leading
+        .replace(/\*\*/g, "")
+        .replace(/\[([^\]]+)\]\([^)]*\)/g, "$1")
+        .replace(/\s+/g, " ")
+        .trim();
+    return text || null;
+}
+/**
+ * Parse the FR table rows + the `## FR-Fold-Map` alias table out of spec.md.
+ *
+ * Both are pipe tables, distinguished by shape rather than by position: a
+ * capability row's 2nd column is an AREA code, a fold row's 2nd column is
+ * another FR id. That keeps the parser stable if the sections move.
+ */
+export function parseFoldMap(specText) {
+    const entries = new Map();
+    const folds = new Map();
+    for (const line of specText.split(/\r?\n/)) {
+        if (!line.startsWith("|"))
+            continue;
+        const cols = line.split("|").slice(1, -1).map(cell);
+        if (cols.length < 2)
+            continue;
+        const first = cols[0];
+        if (!isFrId(first))
+            continue;
+        // NB: use the regex, not the `v is string` predicate — the predicate would
+        // narrow this already-string cell to `never` in the else branch.
+        const second = cols[1];
+        if (FR_ID_RE.test(second)) {
+            // Fold row: | `FR-01.44` | `FR-01.28` | delta | description |
+            folds.set(first, second);
+        }
+        else if (cols.length >= 3) {
+            // Capability row: | FR-01.66 | TSK | Mission view (live session) | … |
+            entries.set(first, {
+                id: first,
+                area: second.length > 0 && second.length <= 8 ? second : null,
+                name: cols[2].length > 0 ? cols[2] : null,
+                description: readableDescription(cols[4]),
+            });
+        }
+    }
+    return { entries, folds, loaded: entries.size > 0 || folds.size > 0 };
+}
+const cache = new Map();
+/**
+ * Load (and mtime-cache) the fold map for a project root. A missing or
+ * unreadable spec.md yields an EMPTY map with `loaded: false`, which makes
+ * `resolveFr` echo ids raw — the honest degradation, never a blank.
+ */
+export function loadFoldMap(projectRoot) {
+    const guard = pathGuard(projectRoot, SPEC_REL_PARTS.join("/"));
+    if (!guard.ok || !existsSync(guard.absolute))
+        return EMPTY_MAP;
+    // ONE atomic read: the mtime used as the cache key describes exactly the
+    // bytes parsed below, so the cache can never key a different revision than
+    // the map it holds (CodeQL js/file-system-race).
+    const read = readBoundedFile(guard.absolute, MAX_SPEC_BYTES);
+    if (!read)
+        return EMPTY_MAP;
+    const hit = cache.get(guard.absolute);
+    if (hit && hit.mtimeMs === read.mtimeMs)
+        return hit.map;
+    const map = parseFoldMap(read.text);
+    const mtimeMs = read.mtimeMs;
+    if (cache.size > 32)
+        cache.clear();
+    cache.set(guard.absolute, { map, mtimeMs });
+    return map;
+}
+/** Test-only cache reset. */
+export function _clearFoldMapCache() {
+    cache.clear();
+}
+/** Bound the alias chain — a malformed map must not spin (A→B→A). */
+const MAX_FOLD_HOPS = 8;
+/**
+ * Resolve one FR id to its display row. Follows a fold CHAIN (a folded id whose
+ * parent was itself later folded) with a hop bound and cycle detection; on a
+ * cycle it stops at the last id reached rather than throwing.
+ */
+export function resolveFr(map, originalFrId) {
+    const original = originalFrId.trim();
+    let current = original;
+    const seen = new Set([current]);
+    for (let hop = 0; hop < MAX_FOLD_HOPS; hop++) {
+        const next = map.folds.get(current);
+        if (!next || seen.has(next))
+            break;
+        seen.add(next);
+        current = next;
+    }
+    const entry = map.entries.get(current) ?? null;
+    return {
+        originalFrId: original,
+        displayFrId: current,
+        name: entry?.name ?? null,
+        area: entry?.area ?? null,
+        description: entry?.description ?? null,
+        sourceAnchor: `fr-${current.slice(3).replace(".", "")}`,
+        // Only set when the fold actually MOVED the id — never a self-reference.
+        mappedFrom: current !== original ? original : null,
+    };
+}
+/** Resolve a list, dropping non-FR-shaped junk but keeping unknown-but-valid ids raw. */
+export function resolveFrList(map, ids) {
+    const out = [];
+    const seenDisplay = new Set();
+    for (const id of ids) {
+        if (!isFrId(id))
+            continue;
+        const row = resolveFr(map, id);
+        // Two folded ids can collapse onto the same parent — keep the first, so the
+        // rail does not repeat a capability.
+        if (seenDisplay.has(row.displayFrId))
+            continue;
+        seenDisplay.add(row.displayFrId);
+        out.push(row);
+    }
+    return out;
+}
+/** Absolute path to the adopted spec (for sourceRev mtime probing). */
+export function specPath(projectRoot) {
+    return path.join(projectRoot, ...SPEC_REL_PARTS);
+}
+//# sourceMappingURL=fold-map.js.map

package/server/dist/core/mission-context/fold-map.js.map

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