codecartographer-pi 0.17.0 → 0.18.0

package/dist/core/pipeline.js

@@ -2,6 +2,7 @@
 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",
@@ -155,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.");
     }
@@ -169,6 +180,7 @@ export async function validatePhaseOutput(state, phaseId) {
         gaps,
         errors,
         secondaryOutputs,
+        ...(warnings.length > 0 && { warnings }),
     };
 }
 export function buildValidationSummary(validation) {
@@ -184,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.d.ts

@@ -14,7 +14,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;

package/dist/core/status.js

@@ -126,26 +126,40 @@ export function createEmptyStatus(projectName, pipelinePath, pipeline) {
         post_pipeline: [],
     };
 }
+/**
+ * Spell a tool for both executable surfaces — the shape the scaffold
+ * staleness notice adopted (#177). next_actions is canonical state rendered
+ * by codecarto_status on MCP and as the Pi widget's "Next:" line alike, and a
+ * Pi user handed only the MCP tool name has nothing to run. Several tools
+ * join with "then" so a sequence reads as one per surface. No backticks:
+ * these lines render in a plain TUI line and in the HTML dashboard.
+ */
+function onBothSurfaces(...tools) {
+    const mcp = tools.map((tool) => `codecarto_${tool}`).join(" then ");
+    const pi = tools.map((tool) => `/codecarto-${tool.replace(/_/g, "-")}`).join(" then ");
+    return `${mcp} on MCP, ${pi} on Pi`;
+}
 /**
  * Route the terminal boundary to the post-pipeline surfaces (issue #114). The
  * 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 function buildTerminalNextActions(status) {
     const openQuestions = Object.values(status.phases).reduce((sum, phase) => sum + (phase.open_questions?.length ?? 0), 0);
     const postPipeline = status.post_pipeline.length;
     const actions = [
-        "All phases complete. Review findings; post-pipeline skills: codecarto_list_skills / codecarto_skill.",
+        `All phases complete. Review findings; post-pipeline skills: ${onBothSurfaces("list_skills", "skill")}.`,
     ];
     if (openQuestions > 0 || postPipeline > 0) {
-        actions.push(`${openQuestions} open question(s) and ${postPipeline} post-pipeline item(s) remain — apply resolutions with codecarto_amend (write scratch/amendments/<slug>.yaml from templates/amendment.yaml).`);
+        actions.push(`${openQuestions} open question(s) and ${postPipeline} post-pipeline item(s) remain — apply resolutions with ${onBothSurfaces("amend")} (write scratch/amendments/<slug>.yaml from templates/amendment.yaml).`);
     }
     if ("reimplementation-spec" in status.phases) {
-        actions.push("Publish the finished spec to a library: codecarto_publish (create one with codecarto_library_init; see the library guide topic).");
+        actions.push(`Publish the finished spec to a library: ${onBothSurfaces("publish")} (create one with ${onBothSurfaces("library_init")}; see the library guide topic).`);
     }
-    actions.push("Dashboard: .codecarto/dashboard.html (refreshed on completion and amendment; codecarto_dashboard re-renders on demand). Usage totals: codecarto_usage.");
+    actions.push(`Dashboard: .codecarto/dashboard.html (refreshed on completion and amendment; re-render on demand with ${onBothSurfaces("dashboard")}). Usage totals: ${onBothSurfaces("usage")}.`);
     return actions;
 }
 export function normalizeStatus(status, pipeline, pipelinePath, cwd) {
@@ -274,36 +288,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)

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

@@ -72,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
@@ -114,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

@@ -38,6 +38,16 @@ export declare function copyPackagedWorkspace(targetWorkspaceDir: string, source
  * @returns the file names created, for the caller's report.
  */
 export declare function seedOrchestratorFiles(workspaceDir: string): Promise<string[]>;
+/**
+ * What a scaffold refresh never touches, for a wrapper that asks before
+ * refreshing to show. The same sets drive {@link refreshScaffold}, so the
+ * preview and the write cannot disagree.
+ */
+export declare const SCAFFOLD_REFRESH_PROTECTED: Readonly<{
+    topLevel: readonly string[];
+    dirs: readonly string[];
+    workflowFiles: readonly string[];
+}>;
 /** One scaffold refresh's outcome. */
 export type RefreshScaffoldResult = {
     /** Workspace-relative paths written, sorted. */
@@ -47,6 +57,12 @@ export type RefreshScaffoldResult = {
     /** The running framework version the scaffold now matches. */
     scaffoldVersionAfter: string;
 };
+/**
+ * The workspace-relative paths a scaffold refresh would write, sorted — the
+ * exact set {@link refreshScaffold} copies, computed without writing anything.
+ * A wrapper that asks before refreshing shows this.
+ */
+export declare function listScaffoldRefreshFiles(): Promise<string[]>;
 /**
  * Refresh a workspace's framework-owned files from the packaged template
  * (issue #102): both staleness notices instruct exactly this, and the only

package/dist/core/workspace.js

@@ -7,7 +7,7 @@ import { appendFile, copyFile, cp, mkdir, readFile, readdir, rename, writeFile }
 import { basename, dirname, join, relative } from "node:path";
 import { fileURLToPath } from "node:url";
 import { acquireLock, applyHandoff, createEmptyStatus, normalizeStatus, parseHandoff } from "./status.js";
-import { pathExists } from "./utils.js";
+import { compareDottedVersions, newlineIfUnterminated, pathExists } from "./utils.js";
 import { loadYamlFile, stringifySimpleYaml } from "./yaml.js";
 // Walk up from the current file to find the package root. Needed because the
 // source lives at <root>/core/workspace.ts (one level below the package root)
@@ -199,6 +199,16 @@ const REFRESH_EXCLUDED_TOP_LEVEL = new Set(["BACKLOG.md", "THREAD_LOG.md", "CONV
 // generated results) — refresh must never overwrite it.
 const REFRESH_EXCLUDED_DIRS = new Set(["scratch", "inputs", "closeouts", "broadside"]);
 const REFRESH_EXCLUDED_WORKFLOW_FILES = new Set(["status.yaml", "config.yaml", ".usage.local.yaml"]);
+/**
+ * What a scaffold refresh never touches, for a wrapper that asks before
+ * refreshing to show. The same sets drive {@link refreshScaffold}, so the
+ * preview and the write cannot disagree.
+ */
+export const SCAFFOLD_REFRESH_PROTECTED = Object.freeze({
+    topLevel: Object.freeze([...REFRESH_EXCLUDED_TOP_LEVEL]),
+    dirs: Object.freeze([...REFRESH_EXCLUDED_DIRS]),
+    workflowFiles: Object.freeze([...REFRESH_EXCLUDED_WORKFLOW_FILES]),
+});
 async function listTemplateFiles(dir, relativeDir = "") {
     const entries = await readdir(dir, { withFileTypes: true });
     const files = [];
@@ -218,6 +228,17 @@ async function listTemplateFiles(dir, relativeDir = "") {
     }
     return files;
 }
+/**
+ * The workspace-relative paths a scaffold refresh would write, sorted — the
+ * exact set {@link refreshScaffold} copies, computed without writing anything.
+ * A wrapper that asks before refreshing shows this.
+ */
+export async function listScaffoldRefreshFiles() {
+    if (!existsSync(packagedWorkspaceDir)) {
+        throw new Error("Packaged .codecarto template is missing. Reinstall codecartographer-pi.");
+    }
+    return (await listTemplateFiles(packagedWorkspaceDir)).sort();
+}
 /**
  * Refresh a workspace's framework-owned files from the packaged template
  * (issue #102): both staleness notices instruct exactly this, and the only
@@ -238,14 +259,22 @@ export async function refreshScaffold(cwd) {
         throw new Error("Packaged .codecarto template is missing. Reinstall codecartographer-pi.");
     }
     const scaffoldVersionBefore = state.scaffoldVersion;
-    const files = (await listTemplateFiles(packagedWorkspaceDir)).sort();
+    const files = await listScaffoldRefreshFiles();
     for (const relativePath of files) {
         const target = join(state.workspaceDir, relativePath);
         await mkdir(dirname(target), { recursive: true });
         await copyFile(join(packagedWorkspaceDir, relativePath), target);
     }
     const entry = `- ${new Date().toISOString().slice(0, 10)} — scaffold-refresh — Refreshed ${files.length} framework-owned file(s) from the packaged template (${scaffoldVersionBefore ?? "unversioned"} → ${PACKAGE_VERSION}); project state, user config, and session outputs untouched.`;
-    await appendFile(join(state.workspaceDir, "THREAD_LOG.md"), `${entry}\n`, "utf8");
+    const threadLogPath = join(state.workspaceDir, "THREAD_LOG.md");
+    let currentLog = "";
+    try {
+        currentLog = await readFile(threadLogPath, "utf8");
+    }
+    catch {
+        // Created by the append when absent (pre-template scaffolds).
+    }
+    await appendFile(threadLogPath, `${newlineIfUnterminated(currentLog)}${entry}\n`, "utf8");
     return {
         written: files,
         ...(scaffoldVersionBefore !== undefined && { scaffoldVersionBefore }),
@@ -253,21 +282,12 @@ export async function refreshScaffold(cwd) {
     };
 }
 // Numeric x.y.z comparison; null when either side is not a plain dotted triple.
-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;
-}
+/**
+ * The remedy every staleness notice points at, spelled for both executable
+ * surfaces: this text renders inside Pi's widget and inside MCP's status
+ * result alike, and a Pi user handed only the MCP tool name has nothing to run.
+ */
+const SCAFFOLD_REFRESH_REMEDY = "`codecarto_refresh_scaffold` on MCP, `/codecarto-refresh-scaffold` on Pi";
 /**
  * Human-readable staleness notice for the workspace's .codecarto/ scaffold,
  * or null when the scaffold matches the running framework. A missing marker
@@ -279,7 +299,7 @@ function compareDottedVersions(a, b) {
 export function describeScaffoldStaleness(state) {
     const scaffold = state.scaffoldVersion;
     if (!scaffold) {
-        return "This workspace's .codecarto/ scaffold has no workflow/scaffold-version.yaml marker (introduced after v0.12.11), so its framework-owned files (GUIDE.md, templates/, workflow/ pipelines and VALIDATE.md) may predate the v0.12.0 handoff contract. Refresh them from the packaged CodeCartographer template (codecarto_refresh_scaffold does exactly this without touching project state).";
+        return `This workspace's .codecarto/ scaffold has no workflow/scaffold-version.yaml marker (introduced after v0.12.11), so its framework-owned files (GUIDE.md, templates/, workflow/ pipelines and VALIDATE.md) may predate the v0.12.0 handoff contract. Refresh them from the packaged CodeCartographer template (${SCAFFOLD_REFRESH_REMEDY}) — that refresh does not touch project state.`;
     }
     const comparison = compareDottedVersions(scaffold, PACKAGE_VERSION);
     if (comparison === 0)
@@ -287,10 +307,10 @@ export function describeScaffoldStaleness(state) {
     if (comparison === null) {
         return scaffold === PACKAGE_VERSION
             ? null
-            : `This workspace's scaffold version (${scaffold}) does not match the running framework (${PACKAGE_VERSION}). Refresh the framework-owned files (GUIDE.md, templates/, workflow/) from the packaged template — codecarto_refresh_scaffold does exactly this without touching project state.`;
+            : `This workspace's scaffold version (${scaffold}) does not match the running framework (${PACKAGE_VERSION}). Refresh the framework-owned files (GUIDE.md, templates/, workflow/) from the packaged template (${SCAFFOLD_REFRESH_REMEDY}) — that refresh does not touch project state.`;
     }
     if (comparison < 0) {
-        return `This workspace's scaffold (v${scaffold}) is older than the running framework (v${PACKAGE_VERSION}). Refresh the framework-owned files (GUIDE.md, templates/, workflow/) from the packaged template to pick up pipeline and template fixes — codecarto_refresh_scaffold does exactly this without touching project state.`;
+        return `This workspace's scaffold (v${scaffold}) is older than the running framework (v${PACKAGE_VERSION}). Refresh the framework-owned files (GUIDE.md, templates/, workflow/) from the packaged template to pick up pipeline and template fixes (${SCAFFOLD_REFRESH_REMEDY}) — that refresh does not touch project state.`;
     }
     return `This workspace's scaffold (v${scaffold}) is newer than the running framework (v${PACKAGE_VERSION}). Upgrade CodeCartographer to at least v${scaffold}.`;
 }
@@ -329,7 +349,7 @@ export async function updateStatusAtomically(cwd, updater) {
             const normalizedEntry = result.threadLogEntry.trim();
             const isDuplicate = logEntries.some((line) => line.trim() === normalizedEntry);
             if (!isDuplicate) {
-                await appendFile(threadLogPath, result.threadLogEntry, "utf8");
+                await appendFile(threadLogPath, `${newlineIfUnterminated(currentLog)}${normalizedEntry}\n`, "utf8");
             }
         }
         return nextState;

package/dist/core/yaml.js

@@ -3,6 +3,18 @@
 // Round-trips structured carry_forward/open_questions entries.
 import { readFile } from "node:fs/promises";
 import { isPlainObject } from "./utils.js";
+/**
+ * True when the double quote at `index` is escaped, i.e. preceded by an odd
+ * run of backslashes. Checking only the single previous character read `\\"`
+ * (an escaped backslash, then the closing quote) as an escaped quote, so the
+ * scalar never closed and a trailing ` # comment` leaked into the value (#134).
+ */
+function isEscapedQuote(text, index) {
+    let backslashes = 0;
+    for (let i = index - 1; i >= 0 && text[i] === "\\"; i--)
+        backslashes++;
+    return backslashes % 2 === 1;
+}
 export function stripYamlComment(value) {
     let inSingle = false;
     let inDouble = false;
@@ -12,7 +24,7 @@ export function stripYamlComment(value) {
             inSingle = !inSingle;
             continue;
         }
-        if (char === '"' && !inSingle && value[i - 1] !== "\\") {
+        if (char === '"' && !inSingle && !isEscapedQuote(value, i)) {
             inDouble = !inDouble;
             continue;
         }
@@ -49,7 +61,7 @@ function findKeySeparator(text) {
             inSingle = !inSingle;
             continue;
         }
-        if (char === '"' && !inSingle && text[i - 1] !== "\\") {
+        if (char === '"' && !inSingle && !isEscapedQuote(text, i)) {
             inDouble = !inDouble;
             continue;
         }
@@ -77,7 +89,10 @@ export function parseYamlScalar(rawValue) {
         return Number.parseInt(trimmed, 10);
     if (/^-?\d+\.\d+$/.test(trimmed))
         return Number.parseFloat(trimmed);
-    if (trimmed.startsWith('"') && trimmed.endsWith('"')) {
+    // A quoted scalar needs at least its two quotes: a lone quote character
+    // satisfied startsWith and endsWith at once and was sliced to "" (#134).
+    const canBeQuoted = trimmed.length >= 2;
+    if (canBeQuoted && trimmed.startsWith('"') && trimmed.endsWith('"')) {
         try {
             return JSON.parse(trimmed);
         }
@@ -85,7 +100,7 @@ export function parseYamlScalar(rawValue) {
             return trimmed.slice(1, -1);
         }
     }
-    if (trimmed.startsWith("'") && trimmed.endsWith("'")) {
+    if (canBeQuoted && trimmed.startsWith("'") && trimmed.endsWith("'")) {
         return trimmed.slice(1, -1).replace(/''/g, "'");
     }
     return trimmed;

package/dist/extensions/codecarto/auto-runner.d.ts

@@ -41,6 +41,8 @@ export declare function isPhaseRunning(phaseId: string): boolean;
 export interface AutoCompleteResult {
     updatedState: WorkspaceState;
     closeoutNotice?: string;
+    /** Non-gating closure-integrity notes from completion (#122). */
+    warnings: string[];
 }
 export declare function autoCompletePhase(ctx: ExtensionContext, validation: ValidationResult): Promise<AutoCompleteResult>;
 export type AutoOutcome = "complete" | "stopped" | "aborted";

package/dist/extensions/codecarto/broadside-flags.d.ts

@@ -4,7 +4,12 @@ export interface BroadsideFlags {
     action: BroadsideAction;
     /** Empty means "the repository's default lens set". */
     lenses: BroadsideLensId[];
-    incremental: boolean;
+    /**
+     * Undefined means "use the repository's config default". --incremental sets
+     * true and --no-incremental sets false, so a config-set `incremental: true`
+     * can be overridden back to a full scan for one run (#163).
+     */
+    incremental?: boolean;
     includeSynthesis?: boolean;
     includeTriage?: boolean;
     retryTruncated?: boolean;
@@ -17,5 +22,5 @@ export interface BroadsideFlags {
     error?: string;
 }
 /** Every token the completer offers, in the order it offers them. */
-export declare const KNOWN_BROADSIDE_TOKENS: readonly ["submit", "collect", "status", "models", "architecture", "api", "security", "defect", "conventions", "porting", "--incremental", "--max-cost=", "--wait=", "--no-synthesis", "--no-triage", "--no-retry-truncated", "--benchmarks"];
+export declare const KNOWN_BROADSIDE_TOKENS: readonly ["submit", "collect", "status", "models", "architecture", "api", "security", "defect", "conventions", "porting", "--incremental", "--no-incremental", "--max-cost=", "--wait=", "--no-synthesis", "--no-triage", "--no-retry-truncated", "--benchmarks"];
 export declare function parseBroadsideFlags(args: string): BroadsideFlags;

package/dist/extensions/codecarto/broadside-flags.js

@@ -10,9 +10,14 @@
 // Flags mirror the codecarto_broadside tool parameters, with the negative
 // forms spelled out because a slash command has no place to pass `false`:
 //   --incremental          --no-synthesis
-//   --max-cost=N           --no-triage
-//   --wait=SECONDS         --no-retry-truncated
-//   --benchmarks (models only)
+//   --no-incremental       --no-triage
+//   --max-cost=N           --no-retry-truncated
+//   --wait=SECONDS         --benchmarks (models only)
+//
+// --incremental has a spelled-out negative because the value is tri-state:
+// absent defers to config.yaml, so a repository that set `incremental: true`
+// can still ask for a one-off full scan (#163), exactly as an MCP caller can
+// with `incremental: false`.
 //
 // The parser never throws. index.ts decides how to surface unknown tokens and
 // invalid combinations, matching parseNextFlags.
@@ -26,6 +31,7 @@ export const KNOWN_BROADSIDE_TOKENS = [
     "models",
     ...BROADSIDE_LENS_IDS,
     "--incremental",
+    "--no-incremental",
     "--max-cost=",
     "--wait=",
     "--no-synthesis",
@@ -50,7 +56,6 @@ export function parseBroadsideFlags(args) {
     const result = {
         action: "submit",
         lenses: [],
-        incremental: false,
         benchmarks: false,
         unknown: [],
     };
@@ -67,8 +72,14 @@ export function parseBroadsideFlags(args) {
                 result.lenses.push(token);
             continue;
         }
-        if (token === "--incremental") {
-            result.incremental = true;
+        if (token === "--incremental" || token === "--no-incremental") {
+            const value = token === "--incremental";
+            // Last-one-wins would be a silent tiebreak on a command that spends
+            // money; a contradiction is an error.
+            if (result.incremental !== undefined && result.incremental !== value) {
+                result.error ??= "--incremental and --no-incremental contradict each other; pass one or neither.";
+            }
+            result.incremental = value;
             continue;
         }
         if (token === "--no-synthesis") {
@@ -99,12 +110,14 @@ export function parseBroadsideFlags(args) {
     }
     // Flags that only mean something for one action are refused rather than
     // ignored: silently dropping --incremental on a collect would read as
-    // "collected incrementally", which is not a thing.
+    // "collected incrementally", which is not a thing (and --no-incremental
+    // would read as a full re-collect, which is not one either).
     if (result.lenses.length > 0 && result.action !== "submit") {
         result.error ??= `Lens names are only meaningful for submit (got action "${result.action}").`;
     }
-    if (result.incremental && result.action !== "submit") {
-        result.error ??= `--incremental is only meaningful for submit (got action "${result.action}").`;
+    if (result.incremental !== undefined && result.action !== "submit") {
+        const flag = result.incremental ? "--incremental" : "--no-incremental";
+        result.error ??= `${flag} is only meaningful for submit (got action "${result.action}").`;
     }
     if (result.benchmarks && result.action !== "models") {
         result.error ??= `--benchmarks is only meaningful for models (got action "${result.action}").`;

package/dist/extensions/codecarto/dashboard-narrator.js

@@ -66,7 +66,7 @@ async function readRecentCloseouts(workspaceDir) {
         return m ? { date: m[1], phaseOrModule: m[2], fileName: name } : null;
     })
         .filter((x) => x !== null)
-        .sort((a, b) => (a.date < b.date ? 1 : -1))
+        .sort((a, b) => (a.date < b.date ? 1 : a.date > b.date ? -1 : 0))
         .slice(0, MAX_CLOSEOUTS);
     const out = [];
     for (const entry of matched) {