codecartographer-pi 0.17.1 → 0.19.0

package/dist/core/coverage.js

@@ -0,0 +1,131 @@
+// The coverage-gap ledger every primary output carries (#122, #186).
+//
+// Each phase output ends with a `## Coverage and limits` section whose bullet
+// labels are fixed across every template — `- Inspected scope:`, `- Skipped
+// scope:`, `- Evidence basis:`, `- Known blind spots:`, `- Coverage
+// disposition:` — which is what makes reading it a parse and not a guess.
+//
+// The ledger was carried nowhere: not into the next phase's prompt, not into
+// status.yaml, not into validation. So an upstream phase could declare "the
+// encoded search-proxy command was not fully decoded" and the next phase could
+// assert an `observed fact` about that exact component, with nothing in the
+// framework comparing the two. The contradiction sweep could not have caught
+// it either: that sweep compares against `owner_notes`, and a declared blind
+// spot is not an owner note.
+//
+// Everything here is non-gating and read-only. A missing file, a missing
+// section, or an empty bullet yields nothing; nothing throws.
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { pathExists } from "./utils.js";
+/** The section heading whose bullets this module reads. */
+export const COVERAGE_SECTION_HEADING = "Coverage and limits";
+/** Bullet label (normalized) to ledger field. */
+const LEDGER_LABELS = new Map([
+    ["inspected scope", "inspected_scope"],
+    ["skipped scope", "skipped_scope"],
+    ["evidence basis", "evidence_basis"],
+    ["known blind spots", "known_blind_spots"],
+    ["coverage disposition", "coverage_disposition"],
+]);
+/** The two ledger bullets a downstream phase is bound by, in render order. */
+const GAP_FIELDS = [
+    { field: "skipped_scope", label: "skipped scope" },
+    { field: "known_blind_spots", label: "known blind spots" },
+];
+function emptyLedger() {
+    return {
+        inspected_scope: "",
+        skipped_scope: "",
+        evidence_basis: "",
+        known_blind_spots: "",
+        coverage_disposition: "",
+    };
+}
+function normalizeLabel(label) {
+    return label.replace(/[`*_]/g, "").replace(/\s+/g, " ").trim().toLowerCase();
+}
+/**
+ * Read a phase output's `## Coverage and limits` ledger.
+ *
+ * Returns null when the document has no such section. A bullet the author left
+ * blank comes back as an empty string, as does a label the section omits, so a
+ * caller never has to distinguish "absent" from "empty" — both mean nothing to
+ * carry forward.
+ *
+ * Sub-bullets and wrapped continuation lines under a label belong to that
+ * label: a real report writes its blind spots as a nested list, and dropping
+ * them would silence exactly the case this exists for. They fold onto one line
+ * (sub-bullets joined with "; ") because the consumer is a prompt bullet.
+ */
+export function parseCoverageAndLimits(content) {
+    const lines = content.split(/\r?\n/);
+    const start = lines.findIndex((line) => /^##\s+Coverage and limits\s*$/i.test(line.replace(/[`*_]/g, "")));
+    if (start < 0)
+        return null;
+    const ledger = emptyLedger();
+    let current = null;
+    for (let i = start + 1; i < lines.length; i++) {
+        const line = lines[i];
+        if (/^##\s/.test(line))
+            break;
+        const bullet = /^[-*]\s+(.*)$/.exec(line);
+        if (bullet) {
+            const separator = bullet[1].indexOf(":");
+            const field = separator >= 0 ? LEDGER_LABELS.get(normalizeLabel(bullet[1].slice(0, separator))) : undefined;
+            // An unrecognized top-level bullet ends the previous label's block
+            // rather than absorbing text that belongs to neither.
+            current = field ?? null;
+            if (field)
+                ledger[field] = bullet[1].slice(separator + 1).trim();
+            continue;
+        }
+        if (!line.trim())
+            continue; // a blank line does not end a label's block
+        if (!current || !/^\s/.test(line)) {
+            current = null; // unindented prose is not part of any bullet
+            continue;
+        }
+        const continuation = line.trim();
+        const nested = /^[-*]\s+(.*)$/.exec(continuation);
+        const text = (nested ? nested[1] : continuation).trim();
+        if (!text)
+            continue;
+        ledger[current] = ledger[current] ? `${ledger[current]}${nested ? "; " : " "}${text}` : text;
+    }
+    return ledger;
+}
+/**
+ * Every declared gap from every completed phase whose primary output exists.
+ *
+ * Walks `phase_order` so the list is deterministic and reads upstream-first.
+ * Only `Skipped scope` and `Known blind spots` are collected: those are the
+ * two bullets that bind a later phase's claims. Unreadable or unparsable
+ * outputs contribute nothing.
+ */
+export async function collectCoverageGaps(state) {
+    const configs = new Map(state.pipeline.phases.map((phase) => [phase.id, phase]));
+    const gaps = [];
+    for (const phaseId of state.pipeline.phase_order ?? []) {
+        if (state.status.phases[phaseId]?.status !== "complete")
+            continue;
+        const output = configs.get(phaseId)?.primary_output;
+        if (!output)
+            continue;
+        const outputPath = join(state.workspaceDir, output);
+        if (!(await pathExists(outputPath)))
+            continue;
+        const content = await readFile(outputPath, "utf8").catch(() => null);
+        if (content === null)
+            continue;
+        const ledger = parseCoverageAndLimits(content);
+        if (!ledger)
+            continue;
+        for (const { field, label } of GAP_FIELDS) {
+            const detail = ledger[field];
+            if (detail)
+                gaps.push({ phaseId, label, detail, output });
+        }
+    }
+    return gaps;
+}

package/dist/core/index.d.ts

@@ -5,6 +5,7 @@ export * from "./status.ts";
 export * from "./amendment.ts";
 export * from "./pipeline.ts";
 export * from "./findings.ts";
+export * from "./coverage.ts";
 export * from "./prompts.ts";
 export * from "./workspace.ts";
 export * from "./completion.ts";

package/dist/core/index.js

@@ -8,6 +8,7 @@ export * from "./status.js";
 export * from "./amendment.js";
 export * from "./pipeline.js";
 export * from "./findings.js";
+export * from "./coverage.js";
 export * from "./prompts.js";
 export * from "./workspace.js";
 export * from "./completion.js";

package/dist/core/library.d.ts

@@ -136,6 +136,11 @@ export declare function isValidSlug(slug: string): boolean;
  * Caller is responsible for collision handling — derived slugs may already
  * exist in the library and the calling UX (Pi or MCP) is the right place
  * to ask the user about it.
+ *
+ * A clone's remote URL and its checkout directory derive the same slug
+ * (`…/whisper.git`, `git@host:acme/whisper`, and `/path/whisper` all give
+ * `whisper`), which is what lets the Pi command switch from recording the
+ * directory to recording the remote without renaming anyone's entry.
  */
 export declare function deriveSlug(sourceRepo: string): string;
 /**
@@ -212,6 +217,41 @@ export declare class ConfidentialityMismatchError extends Error {
     readonly libraryVisibility: LibraryVisibility;
     constructor(message: string, entryConfidentiality: LibraryVisibility, libraryVisibility: LibraryVisibility);
 }
+/**
+ * Thrown by `publishEntry` when the target entry's newest version records a
+ * `source_repo` that denotes a different repository than the incoming one.
+ * Nothing has been written when this is raised. It carries both values so a
+ * wrapper with a user to ask (Pi) can pose "did the repository move?" from
+ * the values rather than by matching the message.
+ */
+export declare class SourceRepoMismatchError extends Error {
+    /** The `source_repo` the entry's newest version records. */
+    readonly recorded: string;
+    /** The `source_repo` this publish carries. */
+    readonly incoming: string;
+    constructor(message: string, recorded: string, incoming: string);
+}
+/** What `publishEntry` would do to an entry's version history, without doing it. */
+export interface PublishVersionPreview {
+    /** Highest version directory present, or 0 for a new entry. */
+    latestVersion: number;
+    /** The version the publish would write or update. */
+    version: number;
+    /** True when a new version directory would be created; false for a metadata-only update. */
+    isNewVersion: boolean;
+}
+/**
+ * Read-only preview of the version a publish would land on. This is the same
+ * content-hash decision `publishEntry` makes (it calls this), so a wrapper
+ * that has to describe a publish before performing it — the MCP server's
+ * `publish_confirm` refusal — shows what would actually happen. Neither the
+ * collision nor the confidentiality guard is evaluated here; those still run
+ * on the real publish.
+ */
+export declare function previewPublishVersion(libraryRoot: string, spec: string, ref: {
+    slug: string;
+    namespace?: string;
+}, opts?: Pick<PublishOptions, "forceNewVersion">): Promise<PublishVersionPreview>;
 export declare function publishEntry(libraryRoot: string, spec: string, input: PublishInput, opts?: PublishOptions): Promise<PublishResult>;
 export interface EntryRef {
     slug: string;
@@ -248,6 +288,39 @@ export declare function reindex(libraryRoot: string): Promise<ReindexResult>;
  * reported the same way; the history alone cannot tell the two apart.
  */
 export declare function detectProvenanceConflicts(libraryRoot: string, entries: ReadonlyArray<Pick<LibraryIndexEntry, "slug" | "namespace">>): Promise<ProvenanceConflict[]>;
+/** What a Pi publish records as `source_repo`, and where the value came from. */
+export interface ResolvedSourceRepo {
+    /** The value to record: a remote's fetch URL verbatim, or the directory itself. */
+    source_repo: string;
+    /**
+     * The git remote the URL was read from (`origin`, or the current branch's
+     * upstream remote), or null when the directory was recorded instead — it
+     * is not a git work tree, is a subdirectory of one, or has no usable
+     * remote.
+     */
+    remote: string | null;
+}
+/**
+ * Resolve the repository reference a publish from `cwd` should record. The
+ * remote is preferred over the path because a path means nothing outside the
+ * machine that published it, and because a slug derived from the remote is
+ * stable across clones of one repository, which is what lets the collision
+ * guard compare something meaningful (#147).
+ *
+ * Resolution order: `origin`'s fetch URL, else the fetch URL of the remote
+ * the current branch tracks, else `cwd`. The remote is consulted only when
+ * `cwd` is the root of its work tree. A subdirectory keeps recording its
+ * path: every subdirectory of one repository would otherwise resolve to the
+ * same URL and the same slug, and the second one published would land as a
+ * new version of the first with no guard able to tell — exactly the
+ * cross-project append the guard exists to refuse.
+ *
+ * The URL is stored as git reports it. Spellings of one repository are
+ * reconciled at comparison time by `sameSourceRepo`, not here, so the
+ * recorded value stays human-readable. Never throws: a missing `git` binary
+ * or any git failure falls back to the path.
+ */
+export declare function resolvePublishSourceRepo(cwd: string): Promise<ResolvedSourceRepo>;
 export interface CommitOptions {
     addAll?: boolean;
 }

package/dist/core/library.js

@@ -25,13 +25,14 @@
 //    files, entries whose versions disagree about source_repo — the shape
 //    a slug collision left behind before publish refused cross-project
 //    appends. Repair is manual; see the "Provenance conflicts" section.
-//  - Git operations (`commitPublish`) shell out to the `git` binary.
-//    Failures are non-fatal — the caller decides how to surface them.
+//  - Git operations (`commitPublish`, `resolvePublishSourceRepo`) shell out
+//    to the `git` binary. Failures are non-fatal — the caller decides how to
+//    surface them, and the resolver falls back to the directory itself.
 import { createHash } from "node:crypto";
 import { spawn } from "node:child_process";
 import { mkdir, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
 import { basename, join, resolve } from "node:path";
-import { isPlainObject, pathExists } from "./utils.js";
+import { canonicalPath, isPlainObject, normalizeForComparison, pathExists } from "./utils.js";
 import { parseSimpleYaml, stringifySimpleYaml } from "./yaml.js";
 // ─── Constants ──────────────────────────────────────────────────────────────
 export const LIBRARY_MARKER_FILE = ".codecarto-library";
@@ -137,9 +138,19 @@ export function isValidSlug(slug) {
  * Caller is responsible for collision handling — derived slugs may already
  * exist in the library and the calling UX (Pi or MCP) is the right place
  * to ask the user about it.
+ *
+ * A clone's remote URL and its checkout directory derive the same slug
+ * (`…/whisper.git`, `git@host:acme/whisper`, and `/path/whisper` all give
+ * `whisper`), which is what lets the Pi command switch from recording the
+ * directory to recording the remote without renaming anyone's entry.
  */
 export function deriveSlug(sourceRepo) {
-    const cleaned = sourceRepo.replace(/\.git$/i, "").replace(/\\/g, "/");
+    let cleaned = sourceRepo.replace(/\.git$/i, "").replace(/\\/g, "/");
+    // SCP shorthand for a repository at the root of a host (`git@host:whisper`)
+    // has no slash at all, so the colon is the only separator to split on. Any
+    // form with a slash already yields the right trailing segment below.
+    if (!cleaned.includes("/"))
+        cleaned = cleaned.replace(/^[^:]*:/, "");
     const parts = cleaned.split("/").filter((p) => p.length > 0);
     const last = parts[parts.length - 1] ?? "entry";
     const slug = last
@@ -195,8 +206,10 @@ export function normalizeSourceRepo(sourceRepo) {
     // Windows drive paths. A POSIX absolute path is not: /srv/Repos/tool and
     // /srv/repos/tool are two directories on Linux, and folding them together
     // would hide exactly the cross-project collision this comparison exists to
-    // catch. Pi records the analyzed directory as source_repo, so local paths
-    // are a common case here rather than a curiosity.
+    // catch. Pi records the analyzed directory as source_repo whenever it has
+    // no git remote to record instead, and every entry Pi published before it
+    // resolved remotes holds one, so local paths are a common case here rather
+    // than a curiosity.
     return isCaseSensitivePath(s) ? s : s.toLowerCase();
 }
 /** An absolute POSIX path (or a `~` home reference), where case is significant. */
@@ -305,6 +318,48 @@ export class ConfidentialityMismatchError extends Error {
         this.libraryVisibility = libraryVisibility;
     }
 }
+/**
+ * Thrown by `publishEntry` when the target entry's newest version records a
+ * `source_repo` that denotes a different repository than the incoming one.
+ * Nothing has been written when this is raised. It carries both values so a
+ * wrapper with a user to ask (Pi) can pose "did the repository move?" from
+ * the values rather than by matching the message.
+ */
+export class SourceRepoMismatchError extends Error {
+    /** The `source_repo` the entry's newest version records. */
+    recorded;
+    /** The `source_repo` this publish carries. */
+    incoming;
+    constructor(message, recorded, incoming) {
+        super(message);
+        this.name = "SourceRepoMismatchError";
+        this.recorded = recorded;
+        this.incoming = incoming;
+    }
+}
+/**
+ * Read-only preview of the version a publish would land on. This is the same
+ * content-hash decision `publishEntry` makes (it calls this), so a wrapper
+ * that has to describe a publish before performing it — the MCP server's
+ * `publish_confirm` refusal — shows what would actually happen. Neither the
+ * collision nor the confidentiality guard is evaluated here; those still run
+ * on the real publish.
+ */
+export async function previewPublishVersion(libraryRoot, spec, ref, opts = {}) {
+    const entryDir = entryRoot(libraryRoot, ref.namespace, ref.slug);
+    const existingVersions = await listVersionDirs(entryDir);
+    const latestVersion = existingVersions.length === 0 ? 0 : existingVersions[existingVersions.length - 1];
+    if (latestVersion > 0 && !opts.forceNewVersion) {
+        const latestSpecPath = join(versionDir(libraryRoot, ref.namespace, ref.slug, latestVersion), SPEC_FILE);
+        if (await pathExists(latestSpecPath)) {
+            const existingSpec = await readFile(latestSpecPath, "utf8");
+            if (sha256(existingSpec) === sha256(spec)) {
+                return { latestVersion, version: latestVersion, isNewVersion: false };
+            }
+        }
+    }
+    return { latestVersion, version: latestVersion + 1, isNewVersion: true };
+}
 export async function publishEntry(libraryRoot, spec, input, opts = {}) {
     const marker = await readMarker(libraryRoot);
     if (!marker) {
@@ -324,9 +379,8 @@ export async function publishEntry(libraryRoot, spec, input, opts = {}) {
     }
     const namespace = input.namespace;
     const entryDir = entryRoot(libraryRoot, namespace, input.slug);
-    const existingVersions = await listVersionDirs(entryDir);
-    const latestVersion = existingVersions.length === 0 ? 0 : existingVersions[existingVersions.length - 1];
-    const newSpecHash = sha256(spec);
+    const preview = await previewPublishVersion(libraryRoot, spec, { slug: input.slug, namespace }, opts);
+    const latestVersion = preview.latestVersion;
     // Collision guard. Slugs derive from the trailing path segment of the source
     // repo, so two unrelated projects (acme/whisper and openai/whisper) collapse
     // onto one slug. Without this check the second publish would append its spec
@@ -338,13 +392,13 @@ export async function publishEntry(libraryRoot, spec, input, opts = {}) {
         const recorded = await readRecordedSourceRepo(libraryRoot, namespace, input.slug, latestVersion);
         if (recorded !== null && !sameSourceRepo(recorded, input.source_repo)) {
             const label = namespace ? `${namespace}/${input.slug}` : input.slug;
-            throw new Error(`Refusing to publish: entry "${label}" v${latestVersion} records source_repo ` +
+            throw new SourceRepoMismatchError(`Refusing to publish: entry "${label}" v${latestVersion} records source_repo ` +
                 `"${recorded}", but this publish carries "${input.source_repo}". Publishing would ` +
                 `append this spec to a different project's version history. Publish this project ` +
                 `under a distinct slug to shelve it separately, or — if the repository itself ` +
                 `moved (rename, org transfer, host change) — re-publish with the source-repo ` +
                 `change allowed: allow_source_repo_change on codecarto_publish, ` +
-                `allowSourceRepoChange in PublishOptions.`);
+                `allowSourceRepoChange in PublishOptions.`, recorded, input.source_repo);
         }
     }
     // Confidentiality guard. Levels are ordered internal < shared < public. An
@@ -370,34 +424,29 @@ export async function publishEntry(libraryRoot, spec, input, opts = {}) {
             `this exposure is intended — re-publish with the mismatch allowed: ` +
             `allow_confidentiality_mismatch on codecarto_publish, allowConfidentialityMismatch in PublishOptions.`, entryConfidentiality, libraryVisibility);
     }
-    // Content-hash idempotence: if the latest version's spec matches bytes-for-bytes,
-    // update metadata in place and return without bumping the version.
-    if (latestVersion > 0 && !opts.forceNewVersion) {
+    // Content-hash idempotence: if the latest version's spec matches bytes-for-bytes
+    // (decided by previewPublishVersion above), update metadata in place and
+    // return without bumping the version.
+    if (!preview.isNewVersion) {
         const latestVersionDir = versionDir(libraryRoot, namespace, input.slug, latestVersion);
-        const latestSpecPath = join(latestVersionDir, SPEC_FILE);
-        if (await pathExists(latestSpecPath)) {
-            const existingSpec = await readFile(latestSpecPath, "utf8");
-            if (sha256(existingSpec) === newSpecHash) {
-                // buildMetadata writes provenance only when the input carries it, and
-                // neither surface sends it on publish — so without this the rewrite
-                // would drop the block the version's original publish recorded.
-                const provenance = input.provenance ?? (await readRecordedProvenance(libraryRoot, namespace, input.slug, latestVersion));
-                const metadata = buildMetadata({ ...input, provenance }, latestVersion);
-                await atomicWriteYaml(join(latestVersionDir, METADATA_FILE), metadata);
-                if (!opts.skipReindex)
-                    await reindex(libraryRoot);
-                return {
-                    slug: input.slug,
-                    namespace,
-                    version: latestVersion,
-                    isNewVersion: false,
-                    entryDir,
-                    versionDir: latestVersionDir,
-                };
-            }
-        }
+        // buildMetadata writes provenance only when the input carries it, and
+        // neither surface sends it on publish — so without this the rewrite
+        // would drop the block the version's original publish recorded.
+        const provenance = input.provenance ?? (await readRecordedProvenance(libraryRoot, namespace, input.slug, latestVersion));
+        const metadata = buildMetadata({ ...input, provenance }, latestVersion);
+        await atomicWriteYaml(join(latestVersionDir, METADATA_FILE), metadata);
+        if (!opts.skipReindex)
+            await reindex(libraryRoot);
+        return {
+            slug: input.slug,
+            namespace,
+            version: latestVersion,
+            isNewVersion: false,
+            entryDir,
+            versionDir: latestVersionDir,
+        };
     }
-    const nextVersion = latestVersion + 1;
+    const nextVersion = preview.version;
     const finalVersionDir = versionDir(libraryRoot, namespace, input.slug, nextVersion);
     const stagingDir = `${entryDir}.publish.${process.pid}.${Date.now()}`;
     // Stage all files under a sibling directory, then atomically rename it
@@ -901,6 +950,55 @@ async function atomicWriteYaml(path, value) {
 function sha256(content) {
     return createHash("sha256").update(content, "utf8").digest("hex");
 }
+/**
+ * Resolve the repository reference a publish from `cwd` should record. The
+ * remote is preferred over the path because a path means nothing outside the
+ * machine that published it, and because a slug derived from the remote is
+ * stable across clones of one repository, which is what lets the collision
+ * guard compare something meaningful (#147).
+ *
+ * Resolution order: `origin`'s fetch URL, else the fetch URL of the remote
+ * the current branch tracks, else `cwd`. The remote is consulted only when
+ * `cwd` is the root of its work tree. A subdirectory keeps recording its
+ * path: every subdirectory of one repository would otherwise resolve to the
+ * same URL and the same slug, and the second one published would land as a
+ * new version of the first with no guard able to tell — exactly the
+ * cross-project append the guard exists to refuse.
+ *
+ * The URL is stored as git reports it. Spellings of one repository are
+ * reconciled at comparison time by `sameSourceRepo`, not here, so the
+ * recorded value stays human-readable. Never throws: a missing `git` binary
+ * or any git failure falls back to the path.
+ */
+export async function resolvePublishSourceRepo(cwd) {
+    const asPath = { source_repo: cwd, remote: null };
+    try {
+        const toplevel = await runGit(cwd, ["rev-parse", "--show-toplevel"]);
+        if (!toplevel.ok || toplevel.stdout.trim() === "")
+            return asPath;
+        const [canonicalCwd, canonicalTop] = await Promise.all([canonicalPath(cwd), canonicalPath(toplevel.stdout.trim())]);
+        if (normalizeForComparison(canonicalCwd) !== normalizeForComparison(canonicalTop))
+            return asPath;
+        const origin = await runGit(cwd, ["remote", "get-url", "origin"]);
+        if (origin.ok && origin.stdout.trim() !== "")
+            return { source_repo: origin.stdout.trim(), remote: "origin" };
+        const branch = await runGit(cwd, ["symbolic-ref", "--short", "HEAD"]);
+        if (!branch.ok || branch.stdout.trim() === "")
+            return asPath;
+        const upstream = await runGit(cwd, ["config", "--get", `branch.${branch.stdout.trim()}.remote`]);
+        const remote = upstream.stdout.trim();
+        // `.` marks a branch tracking another local branch; there is no URL behind it.
+        if (!upstream.ok || remote === "" || remote === ".")
+            return asPath;
+        const url = await runGit(cwd, ["remote", "get-url", remote]);
+        if (url.ok && url.stdout.trim() !== "")
+            return { source_repo: url.stdout.trim(), remote };
+        return asPath;
+    }
+    catch {
+        return asPath;
+    }
+}
 /**
  * Optional convenience: stage and commit publish output. Never pushes.
  * On any failure, returns `{ ok: false, skipped: <reason> }` rather than

package/dist/core/orchestrator-config.d.ts

@@ -17,6 +17,12 @@ export interface LibraryConfig {
     /** Whether `codecarto publish` should display a confirmation prompt
      *  with slug + source + library path before writing. Default true. */
     publish_confirm: boolean;
+    /** True when some config layer set `publish_confirm`; false when the
+     *  default above supplied it. Pi confirms either way (a dialog costs
+     *  nothing), but the MCP server's refuse-unless-confirmed gate on
+     *  `codecarto_publish` costs every host a round trip, so it applies only
+     *  to hosts that actually configured the key. */
+    publish_confirm_configured: boolean;
 }
 export interface CodecartoConfig {
     orchestrator: OrchestratorConfig;

package/dist/core/orchestrator-config.js

@@ -38,6 +38,7 @@ const DEFAULT_CONFIG = {
         path: null,
         namespace: null,
         publish_confirm: true,
+        publish_confirm_configured: false,
     },
 };
 export async function loadCodecartoConfig(workspaceDir) {
@@ -101,6 +102,7 @@ function applyRaw(base, raw) {
         }
         if (typeof l.publish_confirm === "boolean") {
             out.library.publish_confirm = l.publish_confirm;
+            out.library.publish_confirm_configured = true;
         }
     }
     return out;

package/dist/core/prompts.js

@@ -4,12 +4,17 @@
 import { readdir } from "node:fs/promises";
 import { join } from "node:path";
 import { pathExists } from "./utils.js";
+import { collectCoverageGaps } from "./coverage.js";
 import { countPendingProposals } from "./completion.js";
 import { describeScaffoldStaleness } from "./workspace.js";
 import { runPhasePreflight } from "./synthesis.js";
 /** Open-question kinds whose label the orchestrator re-tests at each phase boundary. */
 const RETRIAGE_KINDS = new Set(["needs-maintainer-decision", "needs-runtime-test"]);
-/** Cap on individually listed re-triage questions; the rest collapse to a count. */
+/**
+ * Cap on the individually listed entries of a mechanically surfaced duty list
+ * — re-triage questions and upstream coverage gaps alike; the rest collapse to
+ * a count naming where the full list lives.
+ */
 const RETRIAGE_LIST_LIMIT = 10;
 /**
  * Build the "Orchestrator duties" prompt block (issue #98): the cross-phase
@@ -47,6 +52,19 @@ async function buildOrchestratorDuties(state, phase, auto) {
             lines.push(`  - .codecarto/${output.path} (${exists ? "exists" : "missing"})`);
         }
     }
+    // The coverage-gap ledger (#122, #186). The contradiction sweep below
+    // compares against `owner_notes` only, and a declared blind spot is not an
+    // owner note — so a phase could assert an observed fact about a component
+    // the upstream phase had recorded as not decoded, and nothing compared the
+    // two. Non-gating: this is a duty in the prompt, not a validation rule.
+    const coverageGaps = await collectCoverageGaps(state);
+    if (coverageGaps.length > 0) {
+        lines.push("- Upstream phases declared these coverage gaps in their `## Coverage and limits` sections. A finding of yours that lands inside one must either close the gap with cited new evidence of its own or inherit its uncertainty — an upstream `not inspected` or `not decoded` does not license an `observed fact` about that scope:");
+        for (const gap of coverageGaps.slice(0, RETRIAGE_LIST_LIMIT))
+            lines.push(`  - ${gap.phaseId} (${gap.label}): ${gap.detail}`);
+        if (coverageGaps.length > RETRIAGE_LIST_LIMIT)
+            lines.push(`  - (+${coverageGaps.length - RETRIAGE_LIST_LIMIT} more in completed phases' Coverage and limits sections)`);
+    }
     const anyCompleted = Object.values(state.status.phases).some((phaseState) => phaseState.status === "complete");
     if (anyCompleted) {
         lines.push("- Contradiction sweep: compare this phase's required reads against completed phases' owner_notes; a measured fact that contradicts a summarized claim is a gap to route through the handoff, not a nuance to smooth over.");

package/dist/core/status.d.ts

@@ -1,9 +1,16 @@
-import type { NormalizedStatus, OpenQuestionEntry, PostPipelineEntry, PhaseHandoff, PipelineFile, ProposedConventionEntry, StatusFile, StatusPhase } from "./types.ts";
+import type { ClosureEntry, NormalizedStatus, OpenQuestionEntry, PostPipelineEntry, PhaseHandoff, PipelineFile, ProposedConventionEntry, StatusFile, StatusPhase } from "./types.ts";
 export declare const LOCK_RETRY_MS = 125;
 export declare const LOCK_TIMEOUT_MS = 5000;
 export declare const STALE_LOCK_MS = 60000;
 export declare function assertSafePhaseId(phaseId: string): void;
 export declare function ensureArray(value: unknown): string[];
+/**
+ * Normalize a handoff's `open_question_closures` (#122, #186). Accepts both
+ * the original bare-string shape and `{ id, evidence }`; a string becomes
+ * `{ id }`, and an entry with no usable id is dropped rather than resolving
+ * nothing under the lock. Values are trimmed.
+ */
+export declare function ensureClosureArray(value: unknown): ClosureEntry[];
 export declare function ensureEntryArray<T extends OpenQuestionEntry>(value: unknown, allowTargetPhase?: boolean): T[];
 export declare function autoAssignIds(entries: OpenQuestionEntry[], prefix: string, phaseId: string): void;
 export declare function ensurePostPipelineArray(value: unknown): PostPipelineEntry[];
@@ -14,7 +21,8 @@ export declare function createEmptyStatus(projectName: string, pipelinePath: str
  * moment every phase completes is exactly when skills, amendments, publishing,
  * and the dashboard apply; the prior static sentence left them undiscovered —
  * the 0.15.0 field test finished two full runs with every one of them unused.
- * Amendment recomputes this list so closure counts never go stale.
+ * Amendment recomputes this list so closure counts never go stale. Every tool
+ * named here is spelled for both surfaces (see onBothSurfaces).
  */
 export declare function buildTerminalNextActions(status: NormalizedStatus): string[];
 export declare function normalizeStatus(status: StatusFile, pipeline: PipelineFile, pipelinePath: string, cwd: string): NormalizedStatus;