codecartographer-pi 0.19.5 → 0.20.0

package/dist/core/workspace.d.ts

@@ -19,9 +19,24 @@ export declare const ORCHESTRATOR_FILES: readonly [{
     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/`.
+ * Every workspace-relative path a packaged pipeline declares as a phase output,
+ * primary or secondary. Findings directories ship README and SKILL stubs
+ * beside the reports sessions write, so the reports have to be excluded by
+ * name rather than by directory, and the pipelines are the source of truth
+ * for those names. A pipeline file that fails to load contributes nothing.
+ */
+export declare function listDeclaredOutputs(sourceWorkspaceDir?: string): Promise<Set<string>>;
+/**
+ * Copy the packaged template into a target workspace, skipping everything a
+ * session wrote into it. Directories are still created, so a fresh workspace
+ * has an empty `closeouts/` rather than no `closeouts/`.
+ *
+ * This repository's `.codecarto/` is the template *and* CodeCartographer's own
+ * live workspace, so a checkout install's template can hold finished phase
+ * reports, handoffs, and a dashboard. Copying those seeded every new workspace
+ * with another project's findings, and validation then passed on them (#224).
+ * The exclusion is by declared output path ({@link listDeclaredOutputs}), so a
+ * new phase's report is covered the moment its pipeline names it.
  *
  * @param targetWorkspaceDir - Absolute path to the `.codecarto/` to create or merge into.
  * @param sourceWorkspaceDir - The template to copy from. Defaults to the packaged
@@ -29,6 +44,34 @@ export declare const ORCHESTRATOR_FILES: readonly [{
  *   without mutating the repository's own live workspace mid-suite.
  */
 export declare function copyPackagedWorkspace(targetWorkspaceDir: string, sourceWorkspaceDir?: string): Promise<void>;
+/**
+ * Move a workspace's session state out into `backupDir`, keeping relative
+ * paths: status, the usage log, every declared phase output, handoffs and
+ * checkpoints, closeouts, the dashboard, the orchestrator files, Broad-Side
+ * runs, and any lock or temp file — everything {@link isTemplatePath} says a
+ * session wrote rather than the framework shipped. Framework-owned files stay
+ * where they are, as do the directories, so the workspace keeps its shape.
+ *
+ * This is what a forced re-init does when `.codecarto/` is the packaged
+ * template itself (#245). A checkout's `.codecarto/` is the template and a
+ * live workspace at once, so the ordinary force — rename the directory away,
+ * copy the template in — would move the very files it copies from. Before
+ * this, that case skipped the backup entirely and reset status in place.
+ *
+ * @returns the workspace-relative paths moved, sorted.
+ */
+export declare function backupWorkspaceState(workspaceDir: string, backupDir: string): Promise<string[]>;
+/**
+ * Give the workspace its ignore rules when it has none. npm never packs a file
+ * named `.gitignore`, so an npm-installed template carried no rules and the
+ * workspaces initialised from it committed the dashboard, the usage log with
+ * its absolute session paths, and the Broad-Side config with any API key in
+ * it (#229). The rules ship as `templates/gitignore` instead and are copied
+ * to `.gitignore` here; an existing `.gitignore` is the user's and is left
+ * alone.
+ * @returns whether a file was written.
+ */
+export declare function ensureWorkspaceGitignore(workspaceDir: string): Promise<boolean>;
 /**
  * Seed the orchestrator-maintained files from the workspace's templates
  * (issue #98): orchestration is on by default, so a fresh workspace starts
@@ -62,7 +105,7 @@ export type RefreshScaffoldResult = {
  * exact set {@link refreshScaffold} copies, computed without writing anything.
  * A wrapper that asks before refreshing shows this.
  */
-export declare function listScaffoldRefreshFiles(): Promise<string[]>;
+export declare function listScaffoldRefreshFiles(sourceWorkspaceDir?: string): Promise<string[]>;
 /**
  * Refresh a workspace's framework-owned files from the packaged template
  * (issue #102): both staleness notices instruct exactly this, and the only
@@ -85,26 +128,64 @@ export declare function refreshScaffold(cwd: string): Promise<RefreshScaffoldRes
  * fail: unversioned workspaces must keep working.
  */
 export declare function describeScaffoldStaleness(state: WorkspaceState): string | null;
-export declare function updateStatusAtomically(cwd: string, updater: (state: WorkspaceState) => Promise<{
-    state: WorkspaceState;
-    handoff?: PhaseHandoff;
-    threadLogEntry?: string;
-}> | {
+/** What an {@link updateStatusAtomically} updater returns. */
+export interface StatusUpdate {
     state: WorkspaceState;
     handoff?: PhaseHandoff;
     threadLogEntry?: string;
-}): Promise<WorkspaceState>;
+    /**
+     * Runs under the lock only after status.yaml has been renamed into place —
+     * the commit point. Closeouts, index lines, decision rows, and anything
+     * else that asserts "this phase is complete" belong here rather than in
+     * the updater, so a failed commit leaves none of them behind (#234). A
+     * step that fails here surfaces as an error, but the status change stands;
+     * steps must therefore be idempotent so re-running the operation
+     * regenerates what they write.
+     */
+    afterCommit?: (committed: WorkspaceState) => Promise<void> | void;
+}
+export declare function updateStatusAtomically(cwd: string, updater: (state: WorkspaceState) => Promise<StatusUpdate> | StatusUpdate): Promise<WorkspaceState>;
 /**
- * Switch the active pipeline in-place without deleting findings, handoffs,
- * usage data, closeouts, or checkpoints. Phases that exist in both the old
- * and new pipelines preserve their completion status, owner notes, open
- * questions, and carry-forward entries. Phases unique to the new pipeline
- * start as pending. Phases unique to the old pipeline are dropped from
- * status.yaml (but their findings remain on disk under findings/).
+ * A carry-forward whose `target_phase` the new pipeline does not run. The
+ * switch moves it to `post_pipeline` (the framework's own rule for work no
+ * active downstream phase will pick up; completion refuses such a target in a
+ * handoff) so an amendment can still close it, and reports it here so both
+ * surfaces can say what moved and where it was going.
  */
-export declare function switchPipeline(cwd: string, newPipelinePath: string): Promise<{
+export interface DanglingCarryForward {
+    /** The entry's id, unchanged, now keyed in `post_pipeline`. */
+    id: string;
+    /** The phase whose handoff routed it. */
+    source_phase: string;
+    /** The phase it targeted, which the new pipeline lacks. */
+    target_phase: string;
+    description?: string;
+}
+export interface SwitchPipelineResult {
     state: WorkspaceState;
+    /** Phases in both pipelines whose `complete` status carried over. */
     carried: string[];
+    /** Phases of the old pipeline the new one does not run. */
     dropped: string[];
+    /** Phases of the new pipeline the old one did not have. */
     newPhases: string[];
-}>;
+    /** Carry-forwards re-routed to `post_pipeline` because their target was dropped (#237). */
+    dangling: DanglingCarryForward[];
+}
+/**
+ * The lines both surfaces print for the carry-forwards a switch moved to
+ * post_pipeline: one summary, then one line per entry naming where it was
+ * going and how to close it now. Empty when nothing moved.
+ */
+export declare function describeDanglingCarryForward(dangling: DanglingCarryForward[]): string[];
+/**
+ * Switch the active pipeline in-place without deleting findings, handoffs,
+ * usage data, closeouts, or checkpoints. Phases that exist in both the old
+ * and new pipelines preserve their completion status, owner notes, open
+ * questions, and carry-forward entries; the cursor is then recomputed from
+ * those carried completions (#236). Phases unique to the new pipeline start
+ * as pending. Phases unique to the old pipeline are dropped from status.yaml
+ * (but their findings remain on disk under findings/), and any carry-forward
+ * that targeted one of them moves to post_pipeline (#237).
+ */
+export declare function switchPipeline(cwd: string, newPipelinePath: string): Promise<SwitchPipelineResult>;

package/dist/core/workspace.js

@@ -3,11 +3,12 @@
 // + normalizes the per-project workspace state from disk, and provides the
 // atomic status-update primitive used by /codecarto-complete.
 import { existsSync, readFileSync } from "node:fs";
-import { appendFile, copyFile, cp, mkdir, readFile, readdir, rename, writeFile } from "node:fs/promises";
+import { appendFile, copyFile, cp, mkdir, readFile, readdir, rename } from "node:fs/promises";
 import { basename, dirname, join, relative } from "node:path";
 import { fileURLToPath } from "node:url";
-import { acquireLock, applyHandoff, createEmptyStatus, normalizeStatus, parseHandoff } from "./status.js";
-import { compareDottedVersions, newlineIfUnterminated, pathExists } from "./utils.js";
+import { getPipelineLabel, recomputeCursor } from "./pipeline.js";
+import { acquireLock, applyHandoff, autoAssignIds, createEmptyStatus, normalizeStatus, parseHandoff } from "./status.js";
+import { atomicWriteFile, 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)
@@ -123,8 +124,25 @@ export const ORCHESTRATOR_FILES = [
  * The four top-level files are seeded fresh from templates instead
  * ({@link ORCHESTRATOR_FILES}); `closeouts/` is created empty.
  */
-const INIT_EXCLUDED_TOP_LEVEL = new Set(["BACKLOG.md", "THREAD_LOG.md", "CONVENTIONS.md", "DECISIONS.md"]);
-const INIT_EXCLUDED_DIR_CONTENTS = new Set(["closeouts"]);
+const INIT_EXCLUDED_TOP_LEVEL = new Set([
+    "BACKLOG.md",
+    "THREAD_LOG.md",
+    "CONVENTIONS.md",
+    "DECISIONS.md",
+    // Rendered from a workspace's own state; the narration cache holds an
+    // LLM summary of it.
+    "dashboard.html",
+    ".dashboard-narration.local.md",
+]);
+// Directories that exist in every workspace but whose contents are one
+// project's sessions: closeouts, and scratch (handoffs, checkpoints,
+// amendments) apart from its .gitkeep.
+const INIT_EXCLUDED_DIR_CONTENTS = new Set(["closeouts", "scratch"]);
+// Project state under workflow/: init writes a fresh status.yaml itself, and
+// the two dot-files hold one machine's usage log and session pointer.
+const INIT_EXCLUDED_WORKFLOW_FILES = new Set(["status.yaml", ".usage.local.yaml", ".orchestrator.local.yaml"]);
+// Where the workspace's ignore rules ship (see ensureWorkspaceGitignore).
+const GITIGNORE_TEMPLATE_RELATIVE_PATH = "templates/gitignore";
 // broadside/ is machine-local scan state (state.json, timestamped run dirs)
 // except for its two template files — the same carve-out .codecarto/.gitignore
 // makes for this repository itself. Without this, init from a local checkout
@@ -133,9 +151,83 @@ const INIT_EXCLUDED_DIR_CONTENTS = new Set(["closeouts"]);
 const BROADSIDE_DIR_NAME = "broadside";
 const INIT_BROADSIDE_TEMPLATE_FILES = new Set(["SKILL.md", "config.yaml"]);
 /**
- * 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/`.
+ * Every workspace-relative path a packaged pipeline declares as a phase output,
+ * primary or secondary. Findings directories ship README and SKILL stubs
+ * beside the reports sessions write, so the reports have to be excluded by
+ * name rather than by directory, and the pipelines are the source of truth
+ * for those names. A pipeline file that fails to load contributes nothing.
+ */
+export async function listDeclaredOutputs(sourceWorkspaceDir = packagedWorkspaceDir) {
+    const outputs = new Set();
+    const workflowDir = join(sourceWorkspaceDir, "workflow");
+    let names;
+    try {
+        names = await readdir(workflowDir);
+    }
+    catch {
+        return outputs;
+    }
+    for (const name of names) {
+        if (!/^pipeline.*\.ya?ml$/.test(name))
+            continue;
+        let pipeline;
+        try {
+            pipeline = await loadYamlFile(join(workflowDir, name));
+        }
+        catch {
+            continue;
+        }
+        for (const phase of pipeline?.phases ?? []) {
+            if (typeof phase.primary_output === "string")
+                outputs.add(toPosixRelative(phase.primary_output));
+            for (const secondary of phase.secondary_outputs ?? []) {
+                const path = secondary.path;
+                if (typeof path === "string")
+                    outputs.add(toPosixRelative(path));
+            }
+        }
+    }
+    return outputs;
+}
+function toPosixRelative(path) {
+    return path.replace(/\\/g, "/").replace(/^\.\//, "");
+}
+/**
+ * Whether a template path (as segments) is framework-owned and travels into a
+ * new workspace. Everything a session produces stays behind: the declared
+ * phase outputs, handoffs and checkpoints, closeouts, the dashboard, usage,
+ * status, Broad-Side runs, and any lock or temp file a crashed process left.
+ * Directories pass so the workspace keeps its shape (an empty `closeouts/`,
+ * a `findings/<phase>/` for every phase).
+ */
+function isTemplatePath(segments, declaredOutputs) {
+    const posixPath = segments.join("/");
+    if (declaredOutputs.has(posixPath))
+        return false;
+    if (/\.(lock|tmp)$/.test(posixPath))
+        return false;
+    if (segments.length === 1)
+        return !INIT_EXCLUDED_TOP_LEVEL.has(segments[0]);
+    const [top, second] = segments;
+    if (top === BROADSIDE_DIR_NAME)
+        return segments.length === 2 && INIT_BROADSIDE_TEMPLATE_FILES.has(second);
+    if (top === "scratch")
+        return segments.length === 2 && second === ".gitkeep";
+    if (top === "workflow")
+        return !(segments.length === 2 && INIT_EXCLUDED_WORKFLOW_FILES.has(second));
+    return !INIT_EXCLUDED_DIR_CONTENTS.has(top);
+}
+/**
+ * Copy the packaged template into a target workspace, skipping everything a
+ * session wrote into it. Directories are still created, so a fresh workspace
+ * has an empty `closeouts/` rather than no `closeouts/`.
+ *
+ * This repository's `.codecarto/` is the template *and* CodeCartographer's own
+ * live workspace, so a checkout install's template can hold finished phase
+ * reports, handoffs, and a dashboard. Copying those seeded every new workspace
+ * with another project's findings, and validation then passed on them (#224).
+ * The exclusion is by declared output path ({@link listDeclaredOutputs}), so a
+ * new phase's report is covered the moment its pipeline names it.
  *
  * @param targetWorkspaceDir - Absolute path to the `.codecarto/` to create or merge into.
  * @param sourceWorkspaceDir - The template to copy from. Defaults to the packaged
@@ -143,20 +235,14 @@ const INIT_BROADSIDE_TEMPLATE_FILES = new Set(["SKILL.md", "config.yaml"]);
  *   without mutating the repository's own live workspace mid-suite.
  */
 export async function copyPackagedWorkspace(targetWorkspaceDir, sourceWorkspaceDir = packagedWorkspaceDir) {
+    const declaredOutputs = await listDeclaredOutputs(sourceWorkspaceDir);
     await cp(sourceWorkspaceDir, targetWorkspaceDir, {
         recursive: true,
         filter: (source) => {
             const relativePath = relative(sourceWorkspaceDir, source);
             if (!relativePath)
                 return true; // the workspace root itself
-            const segments = relativePath.split(/[\\/]/);
-            if (segments.length === 1)
-                return !INIT_EXCLUDED_TOP_LEVEL.has(segments[0]);
-            if (segments[0] === BROADSIDE_DIR_NAME) {
-                return segments.length === 2 && INIT_BROADSIDE_TEMPLATE_FILES.has(segments[1]);
-            }
-            // Keep the directory, drop what this repository wrote inside it.
-            return !INIT_EXCLUDED_DIR_CONTENTS.has(segments[0]);
+            return isTemplatePath(relativePath.split(/[\\/]/), declaredOutputs);
         },
     });
     // The published tarball carries no empty directories, so an excluded-contents
@@ -166,6 +252,65 @@ export async function copyPackagedWorkspace(targetWorkspaceDir, sourceWorkspaceD
     for (const name of INIT_EXCLUDED_DIR_CONTENTS) {
         await mkdir(join(targetWorkspaceDir, name), { recursive: true });
     }
+    await ensureWorkspaceGitignore(targetWorkspaceDir);
+}
+/**
+ * Move a workspace's session state out into `backupDir`, keeping relative
+ * paths: status, the usage log, every declared phase output, handoffs and
+ * checkpoints, closeouts, the dashboard, the orchestrator files, Broad-Side
+ * runs, and any lock or temp file — everything {@link isTemplatePath} says a
+ * session wrote rather than the framework shipped. Framework-owned files stay
+ * where they are, as do the directories, so the workspace keeps its shape.
+ *
+ * This is what a forced re-init does when `.codecarto/` is the packaged
+ * template itself (#245). A checkout's `.codecarto/` is the template and a
+ * live workspace at once, so the ordinary force — rename the directory away,
+ * copy the template in — would move the very files it copies from. Before
+ * this, that case skipped the backup entirely and reset status in place.
+ *
+ * @returns the workspace-relative paths moved, sorted.
+ */
+export async function backupWorkspaceState(workspaceDir, backupDir) {
+    const declaredOutputs = await listDeclaredOutputs(workspaceDir);
+    const moved = [];
+    const walk = async (dir, segments) => {
+        for (const entry of await readdir(dir, { withFileTypes: true })) {
+            const entrySegments = [...segments, entry.name];
+            const source = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                await walk(source, entrySegments);
+                continue;
+            }
+            if (isTemplatePath(entrySegments, declaredOutputs))
+                continue;
+            const destination = join(backupDir, ...entrySegments);
+            await mkdir(dirname(destination), { recursive: true });
+            await rename(source, destination);
+            moved.push(entrySegments.join("/"));
+        }
+    };
+    await walk(workspaceDir, []);
+    return moved.sort();
+}
+/**
+ * Give the workspace its ignore rules when it has none. npm never packs a file
+ * named `.gitignore`, so an npm-installed template carried no rules and the
+ * workspaces initialised from it committed the dashboard, the usage log with
+ * its absolute session paths, and the Broad-Side config with any API key in
+ * it (#229). The rules ship as `templates/gitignore` instead and are copied
+ * to `.gitignore` here; an existing `.gitignore` is the user's and is left
+ * alone.
+ * @returns whether a file was written.
+ */
+export async function ensureWorkspaceGitignore(workspaceDir) {
+    const target = join(workspaceDir, ".gitignore");
+    if (await pathExists(target))
+        return false;
+    const template = join(workspaceDir, GITIGNORE_TEMPLATE_RELATIVE_PATH);
+    if (!(await pathExists(template)))
+        return false;
+    await copyFile(template, target);
+    return true;
 }
 /**
  * Seed the orchestrator-maintained files from the workspace's templates
@@ -194,11 +339,20 @@ export async function seedOrchestratorFiles(workspaceDir) {
  * user-owned top-level files, and the directories sessions write into.
  * Everything else present in the packaged template is framework-owned.
  */
-const REFRESH_EXCLUDED_TOP_LEVEL = new Set(["BACKLOG.md", "THREAD_LOG.md", "CONVENTIONS.md", "DECISIONS.md"]);
+const REFRESH_EXCLUDED_TOP_LEVEL = new Set([
+    "BACKLOG.md",
+    "THREAD_LOG.md",
+    "CONVENTIONS.md",
+    "DECISIONS.md",
+    "dashboard.html",
+    ".dashboard-narration.local.md",
+    // The user's ignore rules; created from templates/gitignore when absent.
+    ".gitignore",
+]);
 // broadside/ holds machine-local scout state (batch ids, API key config,
 // 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"]);
+const REFRESH_EXCLUDED_WORKFLOW_FILES = new Set(["status.yaml", "config.yaml", ".usage.local.yaml", ".orchestrator.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
@@ -209,7 +363,7 @@ export const SCAFFOLD_REFRESH_PROTECTED = Object.freeze({
     dirs: Object.freeze([...REFRESH_EXCLUDED_DIRS]),
     workflowFiles: Object.freeze([...REFRESH_EXCLUDED_WORKFLOW_FILES]),
 });
-async function listTemplateFiles(dir, relativeDir = "") {
+async function listTemplateFiles(dir, declaredOutputs, relativeDir = "") {
     const entries = await readdir(dir, { withFileTypes: true });
     const files = [];
     for (const entry of entries) {
@@ -217,13 +371,20 @@ async function listTemplateFiles(dir, relativeDir = "") {
         if (entry.isDirectory()) {
             if (!relativeDir && REFRESH_EXCLUDED_DIRS.has(entry.name))
                 continue;
-            files.push(...await listTemplateFiles(join(dir, entry.name), relativePath));
+            files.push(...await listTemplateFiles(join(dir, entry.name), declaredOutputs, relativePath));
             continue;
         }
         if (!relativeDir && REFRESH_EXCLUDED_TOP_LEVEL.has(entry.name))
             continue;
         if (relativeDir === "workflow" && REFRESH_EXCLUDED_WORKFLOW_FILES.has(entry.name))
             continue;
+        // A checkout install's template can hold finished reports (the repository
+        // analyses itself); refreshing those over a user's own would be worse
+        // than init copying them (#224).
+        if (declaredOutputs.has(relativePath))
+            continue;
+        if (/\.(lock|tmp)$/.test(entry.name))
+            continue;
         files.push(relativePath);
     }
     return files;
@@ -233,11 +394,12 @@ async function listTemplateFiles(dir, relativeDir = "") {
  * exact set {@link refreshScaffold} copies, computed without writing anything.
  * A wrapper that asks before refreshing shows this.
  */
-export async function listScaffoldRefreshFiles() {
-    if (!existsSync(packagedWorkspaceDir)) {
+export async function listScaffoldRefreshFiles(sourceWorkspaceDir = packagedWorkspaceDir) {
+    if (!existsSync(sourceWorkspaceDir)) {
         throw new Error("Packaged .codecarto template is missing. Reinstall codecartographer-pi.");
     }
-    return (await listTemplateFiles(packagedWorkspaceDir)).sort();
+    const declaredOutputs = await listDeclaredOutputs(sourceWorkspaceDir);
+    return (await listTemplateFiles(sourceWorkspaceDir, declaredOutputs)).sort();
 }
 /**
  * Refresh a workspace's framework-owned files from the packaged template
@@ -265,6 +427,10 @@ export async function refreshScaffold(cwd) {
         await mkdir(dirname(target), { recursive: true });
         await copyFile(join(packagedWorkspaceDir, relativePath), target);
     }
+    // Workspaces initialised from an npm install before the rules shipped as a
+    // template have no .gitignore at all; give them one without touching an
+    // existing (user-owned) file.
+    await ensureWorkspaceGitignore(state.workspaceDir);
     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.`;
     const threadLogPath = join(state.workspaceDir, "THREAD_LOG.md");
     let currentLog = "";
@@ -332,10 +498,17 @@ export async function updateStatusAtomically(cwd, updater) {
             applyHandoff(nextState.status, handoff);
         }
         assertCanonicalStatus(nextState.status);
-        const serialized = `${stringifySimpleYaml(nextState.status)}\n`;
-        const tempPath = `${statusPath}.${process.pid}.${Date.now()}.tmp`;
-        await writeFile(tempPath, serialized, "utf8");
-        await rename(tempPath, statusPath);
+        await atomicWriteFile(statusPath, `${stringifySimpleYaml(nextState.status)}\n`);
+        if (result.afterCommit) {
+            try {
+                await result.afterCommit(nextState);
+            }
+            catch (error) {
+                const reason = error instanceof Error ? error.message : String(error);
+                throw new Error(`status.yaml was updated, but a step that runs after the update failed: ${reason} ` +
+                    "The status change stands; re-run the same operation to regenerate what that step writes.", { cause: error });
+            }
+        }
         if (result.threadLogEntry) {
             const threadLogPath = join(workspaceDir, "THREAD_LOG.md");
             let currentLog = "";
@@ -358,13 +531,31 @@ export async function updateStatusAtomically(cwd, updater) {
         await lock.release();
     }
 }
+/**
+ * The lines both surfaces print for the carry-forwards a switch moved to
+ * post_pipeline: one summary, then one line per entry naming where it was
+ * going and how to close it now. Empty when nothing moved.
+ */
+export function describeDanglingCarryForward(dangling) {
+    if (dangling.length === 0)
+        return [];
+    const noun = dangling.length === 1 ? "carry-forward item" : "carry-forward items";
+    const lines = [`${dangling.length} ${noun} targeted a dropped phase and moved to post_pipeline (close with an amendment's post_pipeline_closures):`];
+    for (const entry of dangling) {
+        const label = entry.description ? `: ${entry.description}` : "";
+        lines.push(`  - ${entry.id} (${entry.source_phase} → ${entry.target_phase})${label}`);
+    }
+    return lines;
+}
 /**
  * Switch the active pipeline in-place without deleting findings, handoffs,
  * usage data, closeouts, or checkpoints. Phases that exist in both the old
  * and new pipelines preserve their completion status, owner notes, open
- * questions, and carry-forward entries. Phases unique to the new pipeline
- * start as pending. Phases unique to the old pipeline are dropped from
- * status.yaml (but their findings remain on disk under findings/).
+ * questions, and carry-forward entries; the cursor is then recomputed from
+ * those carried completions (#236). Phases unique to the new pipeline start
+ * as pending. Phases unique to the old pipeline are dropped from status.yaml
+ * (but their findings remain on disk under findings/), and any carry-forward
+ * that targeted one of them moves to post_pipeline (#237).
  */
 export async function switchPipeline(cwd, newPipelinePath) {
     const workspaceDir = join(cwd, ".codecarto");
@@ -397,17 +588,65 @@ export async function switchPipeline(cwd, newPipelinePath) {
         const dropped = currentState.pipeline.phase_order.filter((phaseId) => !newPipeline.phase_order.includes(phaseId));
         const newPhases = newPipeline.phase_order.filter((phaseId) => !currentState.pipeline.phase_order.includes(phaseId));
         // Preserve post_pipeline entries from the old status.
-        freshStatus.post_pipeline = currentState.status.post_pipeline;
+        freshStatus.post_pipeline = [...currentState.status.post_pipeline];
+        // A carried phase may have routed work to a phase the new pipeline does
+        // not run. Left in place, that entry would never appear in a phase
+        // prompt and nothing but a later handoff could close it (#237). It is
+        // post-pipeline work now, by the same rule completion applies to a
+        // handoff whose target is not a downstream active phase.
+        const dangling = [];
+        const activePhases = new Set(newPipeline.phase_order);
+        const newLabel = getPipelineLabel(newPipelinePath);
+        const postPipelineById = new Map(freshStatus.post_pipeline.filter((entry) => entry.id).map((entry) => [entry.id, entry]));
+        for (const [phaseId, phase] of Object.entries(freshStatus.phases)) {
+            if (!phase.carry_forward.some((entry) => entry.target_phase && !activePhases.has(entry.target_phase)))
+                continue;
+            // Handoff-routed entries always carry a `cf-<phase>-N` id; only a
+            // hand-edited status can lack one, and post_pipeline keys by id.
+            autoAssignIds(phase.carry_forward, "cf", phaseId);
+            const kept = [];
+            for (const entry of phase.carry_forward) {
+                if (!entry.target_phase || activePhases.has(entry.target_phase)) {
+                    kept.push(entry);
+                    continue;
+                }
+                const note = `Routed to ${entry.target_phase}, which the ${newLabel} pipeline does not run.`;
+                const moved = {
+                    id: entry.id,
+                    ...(entry.kind !== undefined && { kind: entry.kind }),
+                    ...(entry.description !== undefined && { description: entry.description }),
+                    deferred_reason: entry.deferred_reason ? `${entry.deferred_reason} ${note}` : note,
+                    source_phase: phaseId,
+                    status: "pending",
+                };
+                if (postPipelineById.has(entry.id)) {
+                    const index = freshStatus.post_pipeline.findIndex((existing) => existing.id === entry.id);
+                    freshStatus.post_pipeline[index] = moved;
+                }
+                else {
+                    freshStatus.post_pipeline.push(moved);
+                    postPipelineById.set(entry.id, moved);
+                }
+                dangling.push({
+                    id: entry.id,
+                    source_phase: phaseId,
+                    target_phase: entry.target_phase,
+                    ...(entry.description !== undefined && { description: entry.description }),
+                });
+            }
+            phase.carry_forward = kept;
+        }
         freshStatus.last_updated = new Date().toISOString();
+        // createEmptyStatus pointed the cursor at phase one; the carried
+        // completions may have moved it (#236). Ask the engine, exactly as
+        // completion does, so status and next agree from the moment of the switch.
+        recomputeCursor({ ...currentState, pipeline: newPipeline, status: freshStatus });
         assertCanonicalStatus(freshStatus);
-        const serialized = `${stringifySimpleYaml(freshStatus)}\n`;
-        const tempPath = `${statusPath}.${process.pid}.${Date.now()}.tmp`;
-        await writeFile(tempPath, serialized, "utf8");
-        await rename(tempPath, statusPath);
+        await atomicWriteFile(statusPath, `${stringifySimpleYaml(freshStatus)}\n`);
         const state = await getWorkspaceState(cwd);
         if (!state)
             throw new Error("Failed to reload workspace state after pipeline switch.");
-        return { state, carried, dropped, newPhases };
+        return { state, carried, dropped, newPhases, dangling };
     }
     finally {
         await lock.release();