codecartographer-pi 0.16.0 → 0.17.1

package/dist/core/library.js

@@ -15,11 +15,16 @@
 //  - publishEntry is content-hash idempotent: re-publishing the same
 //    spec bytes does not create a new version. Metadata-only changes
 //    (headline, tags, capabilities) update the existing latest
-//    metadata.yaml in place.
+//    metadata.yaml in place; the version's recorded provenance is
+//    carried forward unless the publish supplies its own.
 //  - reindex regenerates index.yaml and INDEX.md from filesystem state.
 //    Treat both as derived artifacts; never hand-edit. Resolution
 //    recipe for git merge conflicts is documented in
 //    docs/library-format.md.
+//  - reindex also reports, on its return value and never in the index
+//    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.
 import { createHash } from "node:crypto";
@@ -86,6 +91,16 @@ function normalizeMarker(raw) {
 function isVisibility(v) {
     return v === "internal" || v === "shared" || v === "public";
 }
+/**
+ * The level a marker's `visibility` or an entry's `confidentiality` is taken
+ * to have when it declares none. It is the default `initLibrary` writes and
+ * the default docs/library-format.md gives the entry field.
+ */
+export const DEFAULT_VISIBILITY = "internal";
+// Ordered from most to least restricted. An entry may sit in a library at or
+// below its own level; one above it would expose the entry to everyone the
+// library reaches.
+const VISIBILITY_RANK = { internal: 0, shared: 1, public: 2 };
 /**
  * Initialize a CodeCartographer library at the given path: create the
  * directory if needed, write the `.codecarto-library` marker if missing,
@@ -102,7 +117,7 @@ export async function initLibrary(libraryPath, options = {}) {
         schema_version: MARKER_SCHEMA_VERSION,
         name,
         namespaced: options.namespaced ?? false,
-        visibility: options.visibility ?? "internal",
+        visibility: options.visibility ?? DEFAULT_VISIBILITY,
         created_at: new Date().toISOString(),
     };
     await writeMarker(libraryPath, marker);
@@ -136,6 +151,104 @@ export function deriveSlug(sourceRepo) {
     const safe = slug.length === 0 || !/^[a-z]/.test(slug) ? `entry-${slug}`.slice(0, 64) : slug;
     return RESERVED_SLUGS.has(safe) ? `${safe}-entry` : safe;
 }
+/**
+ * Reduce a repo reference to a comparable form so that spellings of the same
+ * repository do not read as different projects. Handles scheme, `git@host:path`
+ * SCP syntax, a `www.` host prefix, a trailing `.git`, repeated and trailing
+ * slashes, backslash separators, and case.
+ *
+ * This is deliberately conservative: it only collapses spellings that are
+ * unambiguously the same target. Anything it cannot prove equivalent stays
+ * distinct, because the caller treats "different" as a hard error. Case is the
+ * one place that cuts the other way — see the note above the return.
+ */
+export function normalizeSourceRepo(sourceRepo) {
+    let s = sourceRepo.trim().replace(/\\/g, "/");
+    // Order matters here. The scheme comes off first so that the SCP branch
+    // below sees only genuine `host:path` syntax, and the userinfo strip runs
+    // before either interpretation of a colon. Getting this order wrong makes
+    // `ssh://git@host/acme/tool` and `https://host/acme/tool` read as two
+    // different repositories, which would refuse a legitimate re-publish.
+    const hadScheme = /^[A-Za-z][A-Za-z0-9+.-]*:\/\//.test(s);
+    s = s.replace(/^[A-Za-z][A-Za-z0-9+.-]*:\/\//, "");
+    // git@, user:token@, oauth2:x-oauth-basic@ ...
+    s = s.replace(/^[^/@]+@/, "");
+    // SCP syntax (git@github.com:acme/tool) only ever appears without a scheme,
+    // where the colon separates host from path rather than naming a port. The
+    // dot requirement keeps a Windows drive letter (C:/repos/tool) out of this
+    // branch.
+    if (!hadScheme)
+        s = s.replace(/^([^:/]+\.[^:/]+):(.+)$/, "$1/$2");
+    // A default port for the transports in play is not a distinguishing part of
+    // the address. Any other port is left alone, since two services on one host
+    // may genuinely differ by port.
+    s = s.replace(/^([^/]+):(?:22|80|443)(?=\/|$)/, "$1");
+    s = s.replace(/^www\./i, "");
+    s = s.replace(/\.git$/i, "");
+    // Repeated separators name the same location. A leading `//` is the one
+    // exception: on Windows that is a UNC share (\\server\share), which is not
+    // the same place as /server/share.
+    s = s.startsWith("//") ? `/${s.replace(/\/{2,}/g, "/")}` : s.replace(/\/{2,}/g, "/");
+    s = s.replace(/\/+$/, "");
+    // Case folding is only safe where the target is case-insensitive. Hosts are,
+    // as are the repository paths the major forges serve over them, and so are
+    // 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.
+    return isCaseSensitivePath(s) ? s : s.toLowerCase();
+}
+/** An absolute POSIX path (or a `~` home reference), where case is significant. */
+function isCaseSensitivePath(s) {
+    return s.startsWith("/") || s === "~" || s.startsWith("~/");
+}
+/** True when two repo references denote the same repository. */
+export function sameSourceRepo(a, b) {
+    return normalizeSourceRepo(a) === normalizeSourceRepo(b);
+}
+/**
+ * The `source_repo` recorded on one version of an entry, or null when it
+ * cannot be determined (no metadata, unreadable, or malformed). Null means
+ * "unknown", and callers treat unknown as permission to proceed rather than
+ * as a mismatch — the publish guard lets the publish through, and conflict
+ * detection skips the version.
+ */
+async function readRecordedSourceRepo(libraryRoot, namespace, slug, version) {
+    const metaPath = join(versionDir(libraryRoot, namespace, slug, version), METADATA_FILE);
+    if (!(await pathExists(metaPath)))
+        return null;
+    try {
+        const raw = parseSimpleYaml(await readFile(metaPath, "utf8"));
+        if (!isPlainObject(raw))
+            return null;
+        const recorded = raw.source_repo;
+        return typeof recorded === "string" && recorded.trim() !== "" ? recorded : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The `provenance` block recorded on one version of an entry, or undefined
+ * when there is none to carry forward (no metadata, unreadable, malformed,
+ * or a version that never had the block — a hand-built entry, say). The
+ * metadata-only publish branch uses this so an identical re-publish, which
+ * neither surface sends `provenance` with, rewrites `metadata.yaml` without
+ * dropping what the version's original publish recorded.
+ */
+async function readRecordedProvenance(libraryRoot, namespace, slug, version) {
+    const metaPath = join(versionDir(libraryRoot, namespace, slug, version), METADATA_FILE);
+    if (!(await pathExists(metaPath)))
+        return undefined;
+    try {
+        const raw = parseSimpleYaml(await readFile(metaPath, "utf8"));
+        return normalizeMetadata(raw, { slug, namespace, version }).provenance;
+    }
+    catch {
+        return undefined;
+    }
+}
 // ─── Path helpers ───────────────────────────────────────────────────────────
 function entryRoot(libraryRoot, namespace, slug) {
     return namespace ? join(libraryRoot, ENTRIES_DIR, namespace, slug) : join(libraryRoot, ENTRIES_DIR, slug);
@@ -176,6 +289,22 @@ async function readLatestPointer(entryDir) {
         return null;
     }
 }
+/**
+ * Thrown by `publishEntry` when the entry is more restricted than the library
+ * it is headed for. Nothing has been written when this is raised. It carries
+ * the two compared levels so a wrapper with a user to ask (Pi) can pose the
+ * question from the values rather than by matching the message.
+ */
+export class ConfidentialityMismatchError extends Error {
+    entryConfidentiality;
+    libraryVisibility;
+    constructor(message, entryConfidentiality, libraryVisibility) {
+        super(message);
+        this.name = "ConfidentialityMismatchError";
+        this.entryConfidentiality = entryConfidentiality;
+        this.libraryVisibility = libraryVisibility;
+    }
+}
 export async function publishEntry(libraryRoot, spec, input, opts = {}) {
     const marker = await readMarker(libraryRoot);
     if (!marker) {
@@ -198,6 +327,49 @@ export async function publishEntry(libraryRoot, spec, input, opts = {}) {
     const existingVersions = await listVersionDirs(entryDir);
     const latestVersion = existingVersions.length === 0 ? 0 : existingVersions[existingVersions.length - 1];
     const newSpecHash = sha256(spec);
+    // 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
+    // to the first project's version history, and the index would then report the
+    // newcomer's source_repo as though it owned every prior version. Checked
+    // before the idempotence branch below, because a metadata-only update would
+    // overwrite the wrong entry just as silently.
+    if (latestVersion > 0 && !opts.allowSourceRepoChange) {
+        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 ` +
+                `"${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.`);
+        }
+    }
+    // Confidentiality guard. Levels are ordered internal < shared < public. An
+    // entry may sit in a library at or below its own level, but one more
+    // restricted than its library would be exposed to everyone the library
+    // reaches: an internal spec in a public library is a leak. Either side that
+    // declares nothing counts as internal — the marker default initLibrary
+    // writes, and the entry default docs/library-format.md documents — so a
+    // library with no visibility field accepts everything it did before. Like
+    // the collision guard this runs ahead of the idempotence branch, so a
+    // metadata-only update cannot reclassify an entry past it, and it fails
+    // before anything is written.
+    const entryConfidentiality = input.confidentiality ?? DEFAULT_VISIBILITY;
+    const libraryVisibility = marker.visibility ?? DEFAULT_VISIBILITY;
+    if (!opts.allowConfidentialityMismatch && VISIBILITY_RANK[entryConfidentiality] < VISIBILITY_RANK[libraryVisibility]) {
+        const label = namespace ? `${namespace}/${input.slug}` : input.slug;
+        const declared = input.confidentiality ? "" : " (the default when none is declared)";
+        throw new ConfidentialityMismatchError(`Refusing to publish: entry "${label}" has confidentiality "${entryConfidentiality}"${declared}, ` +
+            `but library "${marker.name}" has visibility "${libraryVisibility}". Publishing would expose a ` +
+            `spec classified "${entryConfidentiality}" to everyone the "${libraryVisibility}" library reaches. ` +
+            `Publish it to a library whose visibility is "${entryConfidentiality}" or narrower, declare a ` +
+            `confidentiality of "${libraryVisibility}" or wider if the spec may travel that far, or — if ` +
+            `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) {
@@ -206,7 +378,11 @@ export async function publishEntry(libraryRoot, spec, input, opts = {}) {
         if (await pathExists(latestSpecPath)) {
             const existingSpec = await readFile(latestSpecPath, "utf8");
             if (sha256(existingSpec) === newSpecHash) {
-                const metadata = buildMetadata(input, latestVersion);
+                // 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);
@@ -508,7 +684,10 @@ export async function reindex(libraryRoot) {
     };
     await atomicWriteYaml(join(libraryRoot, LIBRARY_INDEX_FILE), index);
     await writeIndexMarkdown(libraryRoot, index, marker);
-    return index;
+    // Reported, not written. The index files above are ABI, so the conflict
+    // list travels on the return value only (see ReindexResult).
+    const provenance_conflicts = await detectProvenanceConflicts(libraryRoot, entries);
+    return { ...index, provenance_conflicts };
 }
 async function buildIndexEntry(libraryRoot, namespace, slug) {
     const entryDir = entryRoot(libraryRoot, namespace, slug);
@@ -590,7 +769,10 @@ async function writeIndexMarkdown(libraryRoot, index, marker) {
     lines.push("");
     lines.push(`_Generated ${index.generated_at}. Do not edit by hand — regenerate with \`codecarto library-reindex\`._`);
     lines.push("");
-    lines.push(`**${index.entry_count} ${index.entry_count === 1 ? "entry" : "entries"}** across ${index.namespaces.length || 1} ${index.namespaces.length === 1 ? "namespace" : "namespaces"}.`);
+    // A single-tenant library has no namespaces but is still one namespace's
+    // worth of entries; count once so the noun agrees with the number shown.
+    const namespaceCount = index.namespaces.length || 1;
+    lines.push(`**${index.entry_count} ${index.entry_count === 1 ? "entry" : "entries"}** across ${namespaceCount} ${namespaceCount === 1 ? "namespace" : "namespaces"}.`);
     lines.push("");
     if (marker.namespaced) {
         const grouped = new Map();
@@ -628,14 +810,85 @@ async function writeIndexMarkdown(libraryRoot, index, marker) {
     await rename(tempPath, path);
 }
 function formatIndexRow(e, namespaced) {
-    const pathPart = namespaced && e.namespace ? `${ENTRIES_DIR}/${e.namespace}/${e.slug}/latest/` : `${ENTRIES_DIR}/${e.slug}/latest/`;
+    // Link to the newest version directory, not `latest/`: the pointer is a
+    // one-line regular file (see the module header), so a `latest/` link has
+    // nothing to land on when the library is browsed on a forge.
+    const entryPath = namespaced && e.namespace ? `${ENTRIES_DIR}/${e.namespace}/${e.slug}` : `${ENTRIES_DIR}/${e.slug}`;
+    const pathPart = `${entryPath}/v${e.latest_version}/`;
     const slugLink = `[${escapeMd(e.slug)}](${pathPart})`;
     const headline = escapeMd(e.headline).replace(/\n+/g, " ");
     const tags = e.tags.length === 0 ? "" : e.tags.map(escapeMd).join(", ");
     return `| ${slugLink} | v${e.latest_version} | ${headline} | ${tags} |`;
 }
 function escapeMd(value) {
-    return value.replace(/\|/g, "\\|").replace(/\r?\n/g, " ");
+    // Backslashes first: escaping only the pipe lets an input ending in `\`
+    // turn the emitted `\|` into a literal-backslash-plus-cell-delimiter and
+    // break out of the table cell (code scanning alert #3).
+    return value.replace(/\\/g, "\\\\").replace(/\|/g, "\\|").replace(/\r?\n/g, " ");
+}
+// ─── Provenance conflicts ───────────────────────────────────────────────────
+//
+// Before publish refused cross-project appends (#123), two projects whose
+// source_repo shared a trailing path segment derived the same slug, and the
+// second publish landed as the next version of the first project's entry.
+// Nothing rewrites those entries after the fact: the index reads only the
+// newest version's metadata, so it advertises every version under whichever
+// project published last, and a synthesis run reading the entry gets one
+// project's spec history presented as another's (#148). Detection reads every
+// version and reports the disagreement. Repair is deliberately manual —
+// splitting an entry means inventing a slug, renumbering versions and
+// repointing `latest`, all of which are paths docs/library-format.md calls
+// ABI — so nothing here renames, renumbers, or moves anything.
+/**
+ * Read-only check over the given entries: does every version of each entry
+ * record the same repository as its newest version? Comparison goes through
+ * `sameSourceRepo`, so spellings of one repository (scheme, `.git`, SCP
+ * syntax, casing where safe) do not count as disagreement. A version whose
+ * metadata is missing, unreadable, or lacks `source_repo` is skipped rather
+ * than reported — the stance the publish guard takes — and an entry whose
+ * newest version is unreadable is skipped entirely, since there is nothing to
+ * compare against. Never writes.
+ *
+ * A repository that genuinely moved and was re-published with
+ * `allowSourceRepoChange` leaves the same on-disk shape as a collision and is
+ * reported the same way; the history alone cannot tell the two apart.
+ */
+export async function detectProvenanceConflicts(libraryRoot, entries) {
+    const conflicts = [];
+    for (const entry of entries) {
+        const conflict = await findProvenanceConflict(libraryRoot, entry.namespace, entry.slug);
+        if (conflict)
+            conflicts.push(conflict);
+    }
+    return conflicts;
+}
+async function findProvenanceConflict(libraryRoot, namespace, slug) {
+    const versions = await listVersionDirs(entryRoot(libraryRoot, namespace, slug));
+    if (versions.length < 2)
+        return null;
+    const latest = versions[versions.length - 1];
+    const latestRepo = await readRecordedSourceRepo(libraryRoot, namespace, slug, latest);
+    if (latestRepo === null)
+        return null;
+    const disagreeing = [];
+    for (const version of versions.slice(0, -1)) {
+        const recorded = await readRecordedSourceRepo(libraryRoot, namespace, slug, version);
+        if (recorded === null)
+            continue;
+        if (!sameSourceRepo(recorded, latestRepo))
+            disagreeing.push({ version, source_repo: recorded });
+    }
+    if (disagreeing.length === 0)
+        return null;
+    const conflict = {
+        slug,
+        latest_version: latest,
+        source_repo: latestRepo,
+        disagreeing_versions: disagreeing,
+    };
+    if (namespace)
+        conflict.namespace = namespace;
+    return conflict;
 }
 // ─── Atomic YAML write ──────────────────────────────────────────────────────
 async function atomicWriteYaml(path, value) {

package/dist/core/orchestrator-config.js

@@ -14,7 +14,7 @@
 // `library.path` is returned tilde-expanded and absolute so consumers
 // don't have to expand themselves.
 import { homedir } from "node:os";
-import { join, resolve } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { expandTilde, pathExists } from "./utils.js";
 import { loadYamlFile, parseSimpleYaml, stringifySimpleYaml } from "./yaml.js";
@@ -131,7 +131,10 @@ export async function writeLibraryConfig(configPath, libraryPath, namespace = nu
     if (namespace)
         library.namespace = namespace;
     const updated = { ...existing, library };
-    const dir = configPath.includes("/") ? configPath.slice(0, configPath.lastIndexOf("/")) : ".";
+    // dirname() honors the platform separator; the previous hand-rolled
+    // `includes("/")` check treated every Windows path as a bare filename
+    // and left mkdir a no-op before the writeFile ENOENT'd (#128).
+    const dir = dirname(configPath);
     await mkdir(dir, { recursive: true });
     await writeFile(configPath, `${stringifySimpleYaml(updated)}\n`, "utf8");
 }

package/dist/core/pipeline.js

@@ -2,9 +2,11 @@
 import { readFile } from "node:fs/promises";
 import { basename, join } from "node:path";
 import { pathExists } from "./utils.js";
+import { crossCheckFindings, findingsPairingGateActive } from "./findings.js";
 export const PIPELINE_ALIASES = {
     "full-with-audit": "workflow/pipeline-full-with-audit.yaml",
     "full-with-deep-audit": "workflow/pipeline-full-with-deep-audit.yaml",
+    "scout-first": "workflow/pipeline-scout-first.yaml",
     full: "workflow/pipeline.yaml",
     "defect-scan": "workflow/pipeline-defect-scan.yaml",
     lite: "workflow/pipeline-lite.yaml",
@@ -154,6 +156,16 @@ export async function validatePhaseOutput(state, phaseId) {
         errors.push("One or more validation criteria are marked FAIL.");
         overall = "FAIL";
     }
+    // Findings cross-checks (#122): the validation table says whether criteria
+    // were met; these read what the findings' own evidence and action cells
+    // say. Deterministic on two cells the model wrote, so the pairing rule can
+    // gate — on a scaffold that offers `verify at runtime`. Older scaffolds warn.
+    const crossCheck = crossCheckFindings(content, { gate: findingsPairingGateActive(state.scaffoldVersion) });
+    if (crossCheck.errors.length > 0) {
+        errors.push(...crossCheck.errors);
+        overall = "FAIL";
+    }
+    const warnings = crossCheck.warnings;
     if (overall === "FAIL" && errors.length === 0) {
         errors.push("Validation overall result is FAIL.");
     }
@@ -168,6 +180,7 @@ export async function validatePhaseOutput(state, phaseId) {
         gaps,
         errors,
         secondaryOutputs,
+        ...(warnings.length > 0 && { warnings }),
     };
 }
 export function buildValidationSummary(validation) {
@@ -183,6 +196,9 @@ export function buildValidationSummary(validation) {
     if (validation.errors.length > 0) {
         lines.push(...validation.errors.slice(0, 3));
     }
+    for (const warning of validation.warnings ?? []) {
+        lines.push(`NOTE: ${warning} Non-gating.`);
+    }
     const missingSecondary = (validation.secondaryOutputs ?? []).filter((output) => !output.exists);
     if (missingSecondary.length > 0) {
         lines.push(`NOTE: ${missingSecondary.length} declared secondary output(s) not written: ${missingSecondary.map((output) => `.codecarto/${output.path}`).join(", ")} — write each, or account for it in Coverage and limits / a routed handoff entry. Non-gating.`);

package/dist/core/prompts.js

@@ -33,7 +33,7 @@ async function buildOrchestratorDuties(state, phase, auto) {
         }
     }
     if (retriage.length > 0) {
-        lines.push("- Re-triage these open questions' kind labels — a label is a claim needing its own evidence; re-test whether each is now answerable by reading before accepting it:");
+        lines.push("- Re-triage these open questions' kind labels — a label is a claim needing its own evidence; re-test whether each is now answerable by reading before accepting it. If one still needs a runtime test, no finding in this phase may assert one of its candidate answers with a settled action (fix before porting / fix now): the finding inherits the question's uncertainty as `verify at runtime` until runtime evidence closes the question:");
         for (const label of retriage.slice(0, RETRIAGE_LIST_LIMIT))
             lines.push(`  - ${label}`);
         if (retriage.length > RETRIAGE_LIST_LIMIT)

package/dist/core/status.js

@@ -274,36 +274,44 @@ export function applyHandoff(status, handoff) {
             }
         }
     }
-    // Now merge into the current phase: overwrite by id or append new
+    // Now merge into the current phase: overwrite by id or append new. An entry
+    // with neither id nor description has no key to merge on; it is kept as-is
+    // rather than lost when the array is rebuilt from the map (#134).
     const localOqMap = new Map();
+    const unkeyedOpenQuestions = [];
     for (const entry of phase.open_questions) {
         const key = entry.id || entry.description || "";
         if (key)
             localOqMap.set(key, entry);
+        else
+            unkeyedOpenQuestions.push(entry);
     }
     for (const entry of handoff.open_questions) {
         const key = entry.id || entry.description || "";
         if (key)
             localOqMap.set(key, entry);
         else
-            phase.open_questions.push(entry);
+            unkeyedOpenQuestions.push(entry);
     }
-    phase.open_questions = [...localOqMap.values()];
-    // Merge carry_forward: overwrite by id or append new
+    phase.open_questions = [...localOqMap.values(), ...unkeyedOpenQuestions];
+    // Merge carry_forward: overwrite by id or append new, same unkeyed rule
     const cfMap = new Map();
+    const unkeyedCarryForward = [];
     for (const entry of phase.carry_forward) {
         const key = entry.id || entry.description || "";
         if (key)
             cfMap.set(key, entry);
+        else
+            unkeyedCarryForward.push(entry);
     }
     for (const entry of handoff.carry_forward) {
         const key = entry.id || entry.description || "";
         if (key)
             cfMap.set(key, entry);
         else
-            phase.carry_forward.push(entry);
+            unkeyedCarryForward.push(entry);
     }
-    phase.carry_forward = [...cfMap.values()];
+    phase.carry_forward = [...cfMap.values(), ...unkeyedCarryForward];
     // Apply closures: remove carry_forward entries from ALL phases by id
     for (const closureId of handoff.carry_forward_closures) {
         if (!closureId)
@@ -345,7 +353,15 @@ export async function acquireLock(lockPath) {
     while (true) {
         try {
             const handle = await open(lockPath, "wx");
-            await handle.writeFile(`${process.pid}\n${new Date().toISOString()}\n`, "utf8");
+            try {
+                await handle.writeFile(`${process.pid}\n${new Date().toISOString()}\n`, "utf8");
+            }
+            catch (error) {
+                // A non-EEXIST write failure must not leak the descriptor the
+                // open just created (#131); close best-effort, then rethrow.
+                await handle.close().catch(() => undefined);
+                throw error;
+            }
             await handle.close();
             return {
                 release: async () => {

package/dist/core/types.d.ts

@@ -94,6 +94,12 @@ export type ValidationResult = {
         path: string;
         exists: boolean;
     }>;
+    /**
+     * Non-gating observations from the findings cross-checks (issue #122):
+     * contradictions worth the reader's attention that must not stop an
+     * --auto run. Rendered as NOTE lines by buildValidationSummary.
+     */
+    warnings?: string[];
 };
 /**
  * One convention a phase proposes for promotion. Completion stages these in

package/dist/core/utils.d.ts

@@ -15,6 +15,14 @@ export declare function isWithinPathResolved(path: string, root: string): Promis
 export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
 export declare function uniqueStrings(items: string[]): string[];
 export declare function dateOnly(timestamp: string): string;
+/**
+ * The separator to put before a line appended to file content `current` so
+ * the line starts at column 0. A file whose last line lacks a trailing newline
+ * (a hand-edited THREAD_LOG.md, an editor that strips final newlines) would
+ * otherwise have the appended entry glued onto that line (#134). Empty or
+ * absent content needs no separator.
+ */
+export declare function newlineIfUnterminated(current: string): string;
 /**
  * Expand a leading `~` or `~/` to the user's home directory. Node's `path`
  * module deliberately doesn't do this (it's a shell convention, not a path
@@ -36,3 +44,9 @@ export declare function formatTokenCount(count: number): string;
  * dashboard renderer can reuse without crossing the core/extensions boundary.
  */
 export declare function formatMillis(ms: number): string;
+/**
+ * Compare two dotted `major.minor.patch` versions. Returns -1, 0, or 1, or
+ * null when either side is not a plain three-part version (pre-release tags,
+ * hand-edited markers) so callers can fall back to string equality.
+ */
+export declare function compareDottedVersions(a: string, b: string): number | null;

package/dist/core/utils.js

@@ -34,7 +34,13 @@ export function isWithinPath(path, root) {
     const normalizedRoot = normalizeForComparison(resolve(root));
     if (normalizedPath === normalizedRoot)
         return true;
-    return normalizedPath.startsWith(`${normalizedRoot}${process.platform === "win32" ? "\\" : "/"}`);
+    // A filesystem root (e.g. "/" or "C:\") already ends in a separator;
+    // appending another one produced a prefix ("//" / "C:\\") that no real
+    // path starts with, falsely rejecting every legitimate subpath (#130).
+    const prefix = normalizedRoot.endsWith("/") || normalizedRoot.endsWith("\\")
+        ? normalizedRoot
+        : `${normalizedRoot}${process.platform === "win32" ? "\\" : "/"}`;
+    return normalizedPath.startsWith(prefix);
 }
 /**
  * Symlink-aware version of isWithinPath. Resolves symlinks on both the path
@@ -66,6 +72,16 @@ export function uniqueStrings(items) {
 export function dateOnly(timestamp) {
     return timestamp.slice(0, 10);
 }
+/**
+ * The separator to put before a line appended to file content `current` so
+ * the line starts at column 0. A file whose last line lacks a trailing newline
+ * (a hand-edited THREAD_LOG.md, an editor that strips final newlines) would
+ * otherwise have the appended entry glued onto that line (#134). Empty or
+ * absent content needs no separator.
+ */
+export function newlineIfUnterminated(current) {
+    return current === "" || current.endsWith("\n") ? "" : "\n";
+}
 /**
  * Expand a leading `~` or `~/` to the user's home directory. Node's `path`
  * module deliberately doesn't do this (it's a shell convention, not a path
@@ -108,3 +124,23 @@ export function formatMillis(ms) {
     const seconds = Math.floor((ms % 60_000) / 1000);
     return `${minutes}m${seconds.toString().padStart(2, "0")}s`;
 }
+/**
+ * Compare two dotted `major.minor.patch` versions. Returns -1, 0, or 1, or
+ * null when either side is not a plain three-part version (pre-release tags,
+ * hand-edited markers) so callers can fall back to string equality.
+ */
+export function compareDottedVersions(a, b) {
+    const parse = (version) => {
+        const match = /^(\d+)\.(\d+)\.(\d+)$/.exec(version.trim());
+        return match ? [Number(match[1]), Number(match[2]), Number(match[3])] : null;
+    };
+    const left = parse(a);
+    const right = parse(b);
+    if (!left || !right)
+        return null;
+    for (let i = 0; i < 3; i++) {
+        if (left[i] !== right[i])
+            return left[i] < right[i] ? -1 : 1;
+    }
+    return 0;
+}

package/dist/core/workspace.d.ts

@@ -11,7 +11,24 @@ export declare const ORCHESTRATOR_FILES: readonly [{
 }, {
     readonly file: "DECISIONS.md";
     readonly template: "decisions-template.md";
+}, {
+    readonly file: "BACKLOG.md";
+    readonly template: "backlog-project.md";
+}, {
+    readonly file: "THREAD_LOG.md";
+    readonly template: "thread-log.md";
 }];
+/**
+ * Copy the packaged template into a target workspace, skipping this
+ * repository's own project state. Directories are still created, so a fresh
+ * workspace has an empty `closeouts/` rather than no `closeouts/`.
+ *
+ * @param targetWorkspaceDir - Absolute path to the `.codecarto/` to create or merge into.
+ * @param sourceWorkspaceDir - The template to copy from. Defaults to the packaged
+ *   template; tests pass a synthetic directory so they can prove the state filter
+ *   without mutating the repository's own live workspace mid-suite.
+ */
+export declare function copyPackagedWorkspace(targetWorkspaceDir: string, sourceWorkspaceDir?: string): Promise<void>;
 /**
  * Seed the orchestrator-maintained files from the workspace's templates
  * (issue #98): orchestration is on by default, so a fresh workspace starts