codecartographer-pi 0.14.1 → 0.16.0

package/dist/core/amendment.js

@@ -0,0 +1,143 @@
+// Post-pipeline amendments (issue #99, formerly template BACKLOG item B2):
+// apply evidence-based resolutions to workflow/status.yaml AFTER the pipeline
+// is complete, under the same lock completion uses. During the pipeline the
+// phase handoff is the only state channel (open_question_closures /
+// carry_forward_closures); an amendment is the post-pipeline counterpart, so
+// spec-delta sessions, spikes, and maintainer rulings no longer end with
+// "record for a later explicit amendment" that nothing can perform.
+import { appendFile, mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { getNextEligiblePhase } from "./pipeline.js";
+import { buildTerminalNextActions, ensureArray, normalizeStatus } from "./status.js";
+import { dateOnly, pathExists } from "./utils.js";
+import { getWorkspaceState, updateStatusAtomically } from "./workspace.js";
+import { loadYamlFile } from "./yaml.js";
+/** Same charset rule as phase ids: the slug becomes file names, so path shapes are refused. */
+export function assertSafeAmendmentSlug(slug) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(slug)) {
+        throw new Error(`Invalid amendment name: ${slug}`);
+    }
+}
+/**
+ * Load and validate one amendment file.
+ * @param name - the amendment slug, with or without a `.yaml` suffix.
+ */
+export async function loadAmendmentFile(name, workspaceDir) {
+    const slug = name.trim().replace(/\.ya?ml$/i, "");
+    assertSafeAmendmentSlug(slug);
+    const amendmentPath = join(workspaceDir, "scratch", "amendments", `${slug}.yaml`);
+    if (!(await pathExists(amendmentPath))) {
+        throw new Error(`No amendment at .codecarto/scratch/amendments/${slug}.yaml. `
+            + `Write it first (see templates/amendment.yaml): schema_version: 1, arrays for open_question_closures, post_pipeline_closures, and notes, plus closeout_summary and optional closeout_content.`);
+    }
+    const raw = (await loadYamlFile(amendmentPath)) ?? {};
+    const schemaVersion = typeof raw.schema_version === "number" ? raw.schema_version : 1;
+    if (schemaVersion > 1) {
+        throw new Error(`Invalid amendment: unsupported schema_version ${schemaVersion}. Supported: 1.`);
+    }
+    for (const field of ["open_question_closures", "post_pipeline_closures", "notes"]) {
+        if (raw[field] !== undefined && !Array.isArray(raw[field])) {
+            throw new Error(`Invalid amendment: ${field} must be an array`);
+        }
+    }
+    const amendment = {
+        slug,
+        open_question_closures: ensureArray(raw.open_question_closures),
+        post_pipeline_closures: ensureArray(raw.post_pipeline_closures),
+        notes: ensureArray(raw.notes),
+        closeout_summary: typeof raw.closeout_summary === "string" ? raw.closeout_summary : "",
+        closeout_content: typeof raw.closeout_content === "string" ? raw.closeout_content : "",
+        schema_version: schemaVersion,
+    };
+    if (amendment.open_question_closures.length === 0 && amendment.post_pipeline_closures.length === 0 && amendment.notes.length === 0) {
+        throw new Error("Invalid amendment: nothing to apply (no closures and no notes)");
+    }
+    return amendment;
+}
+/** Render the generated closeout body when the amendment supplies none. */
+function renderAmendmentCloseout(amendment, applied, timestamp) {
+    const lines = [`# Amendment — ${amendment.slug}`, "", `Applied ${dateOnly(timestamp)}.`, ""];
+    if (applied.openQuestionsClosed.length > 0) {
+        lines.push("## Open questions closed", "", ...applied.openQuestionsClosed.map((id) => `- ${id}`), "");
+    }
+    if (applied.postPipelineClosed.length > 0) {
+        lines.push("## Post-pipeline items closed", "", ...applied.postPipelineClosed.map((id) => `- ${id}`), "");
+    }
+    if (applied.unknownIds.length > 0) {
+        lines.push("## Ids that matched nothing (already closed or unknown)", "", ...applied.unknownIds.map((id) => `- ${id}`), "");
+    }
+    if (amendment.notes.length > 0) {
+        lines.push("## Notes", "", ...amendment.notes.map((note) => `- ${note}`), "");
+    }
+    return lines.join("\n");
+}
+/**
+ * Apply one amendment to canonical state under the completion lock. Refuses
+ * while the pipeline is incomplete — mid-pipeline resolutions belong in the
+ * phase handoff, and allowing both channels at once would race them.
+ * Idempotent: ids that no longer match anything are reported, not fatal.
+ */
+export async function applyAmendment(cwd, name) {
+    const initialState = await getWorkspaceState(cwd);
+    if (!initialState)
+        throw new Error("CodeCartographer workspace not found. Run /codecarto-init first.");
+    const amendment = await loadAmendmentFile(name, initialState.workspaceDir);
+    const nextPhase = getNextEligiblePhase(initialState);
+    if (nextPhase) {
+        throw new Error(`Cannot amend: the pipeline is not complete (next phase: ${nextPhase.id}). `
+            + `Resolve open questions and routed items through that phase's handoff (open_question_closures / carry_forward_closures) instead.`);
+    }
+    const timestamp = new Date().toISOString();
+    const applied = { openQuestionsClosed: [], postPipelineClosed: [], unknownIds: [] };
+    let closeoutNotice = "";
+    const updatedState = await updateStatusAtomically(cwd, async (lockedState) => {
+        const nextStatus = normalizeStatus(lockedState.status, lockedState.pipeline, lockedState.status.pipeline, lockedState.cwd);
+        for (const closureId of amendment.open_question_closures) {
+            if (!closureId)
+                continue;
+            let matched = false;
+            for (const phase of Object.values(nextStatus.phases)) {
+                const before = phase.open_questions.length;
+                phase.open_questions = phase.open_questions.filter((entry) => entry.id !== closureId);
+                if (phase.open_questions.length !== before)
+                    matched = true;
+            }
+            (matched ? applied.openQuestionsClosed : applied.unknownIds).push(closureId);
+        }
+        for (const closureId of amendment.post_pipeline_closures) {
+            if (!closureId)
+                continue;
+            const before = nextStatus.post_pipeline.length;
+            nextStatus.post_pipeline = nextStatus.post_pipeline.filter((entry) => entry.id !== closureId);
+            (nextStatus.post_pipeline.length !== before ? applied.postPipelineClosed : applied.unknownIds).push(closureId);
+        }
+        // The amendment changed exactly the counts the terminal routing lines
+        // carry (issue #114); rebuild them so status never shows stale numbers.
+        nextStatus.next_actions = buildTerminalNextActions(nextStatus);
+        nextStatus.last_updated = timestamp;
+        // Amendment closeout + THREAD_LOG entry, same idempotence rule as
+        // completion: the closeout link appears in THREAD_LOG at most once.
+        const closeoutFile = `${dateOnly(timestamp)}-amendment-${amendment.slug}.md`;
+        const closeoutsDir = join(lockedState.workspaceDir, "closeouts");
+        await mkdir(closeoutsDir, { recursive: true });
+        const body = amendment.closeout_content.trim() || renderAmendmentCloseout(amendment, applied, timestamp);
+        await writeFile(join(closeoutsDir, closeoutFile), `${body}\n`, "utf8");
+        const summary = amendment.closeout_summary.trim()
+            || `Amendment applied: ${applied.openQuestionsClosed.length} open question(s) and ${applied.postPipelineClosed.length} post-pipeline item(s) closed.`;
+        const entry = `- ${dateOnly(timestamp)} — amendment:${amendment.slug} — ${summary} — [closeout](closeouts/${closeoutFile})`;
+        const threadLogPath = join(lockedState.workspaceDir, "THREAD_LOG.md");
+        let current = "";
+        try {
+            current = await readFile(threadLogPath, "utf8");
+        }
+        catch {
+            // Created below when absent.
+        }
+        if (!current.split(/\r?\n/).some((line) => line.includes(`[closeout](closeouts/${closeoutFile})`))) {
+            await appendFile(threadLogPath, `${entry}\n`, "utf8");
+        }
+        closeoutNotice = `Closeout: .codecarto/closeouts/${closeoutFile}`;
+        return { state: { ...lockedState, status: nextStatus } };
+    });
+    return { updatedState, closeoutNotice, applied };
+}

package/dist/core/completion.d.ts

@@ -2,5 +2,21 @@ import type { ValidationResult, WorkspaceState } from "./types.ts";
 export type CompletionResult = {
     updatedState: WorkspaceState;
     closeoutNotice?: string;
+    /**
+     * One-line phase-boundary reminder covering what completion just mechanized
+     * (decisions appended, proposals staged) and what still needs orchestrator
+     * judgment (pending proposals, open-question label re-triage). Undefined
+     * when there is nothing to surface.
+     */
+    orchestratorCheckpoint?: string;
 };
+/** Section heading completion appends mechanized decision rows under. */
+export declare const DECISIONS_COMPLETION_LOG_HEADING = "## Completion log";
+/** Section heading completion stages proposed conventions under. */
+export declare const CONVENTIONS_PENDING_HEADING = "## Pending proposals";
+/**
+ * Count staged proposals in CONVENTIONS.md's pending section.
+ * @param content - the file content, or null to read from disk (null when the file is absent).
+ */
+export declare function countPendingProposals(workspaceDir: string, content?: string): Promise<number>;
 export declare function completeValidatedPhase(cwd: string, validation: ValidationResult, sourceLabel: string): Promise<CompletionResult>;

package/dist/core/completion.js

@@ -1,9 +1,190 @@
 import { appendFile, copyFile, mkdir, readFile, readdir, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { getNextEligiblePhase, resolvePhase } from "./pipeline.js";
-import { applyHandoff, autoAssignIds, loadHandoffFile, normalizeStatus } from "./status.js";
+import { applyHandoff, autoAssignIds, buildTerminalNextActions, loadHandoffFile, normalizeStatus } from "./status.js";
 import { dateOnly, pathExists, uniqueStrings } from "./utils.js";
 import { getWorkspaceState, updateStatusAtomically } from "./workspace.js";
+/**
+ * The Markdown a reader sees: content inside `<!-- -->` blocks removed by a
+ * line scanner. This is read-only scan input for numbering and dedupe — never
+ * written back or rendered — so it is deliberately not an HTML sanitizer; an
+ * unterminated comment drops the remainder of the file from the scan.
+ */
+function visibleMarkdown(content) {
+    const out = [];
+    let inComment = false;
+    for (const line of content.split(/\r?\n/)) {
+        let rest = line;
+        let visible = "";
+        while (rest.length > 0) {
+            if (inComment) {
+                const end = rest.indexOf("-->");
+                if (end === -1) {
+                    rest = "";
+                    break;
+                }
+                rest = rest.slice(end + 3);
+                inComment = false;
+            }
+            else {
+                const start = rest.indexOf("<!--");
+                if (start === -1) {
+                    visible += rest;
+                    rest = "";
+                    break;
+                }
+                visible += rest.slice(0, start);
+                rest = rest.slice(start + 4);
+                inComment = true;
+            }
+        }
+        out.push(visible);
+    }
+    return out.join("\n");
+}
+/** Section heading completion appends mechanized decision rows under. */
+export const DECISIONS_COMPLETION_LOG_HEADING = "## Completion log";
+/** Section heading completion stages proposed conventions under. */
+export const CONVENTIONS_PENDING_HEADING = "## Pending proposals";
+/**
+ * True when `heading` exists as its own visible line. Both orchestrator-file
+ * templates mention their headings in running prose (issue #111: a raw
+ * substring check saw the decisions-template's "…rows under `## Completion
+ * log`…" sentence and never inserted the real heading), so presence checks
+ * must match a whole trimmed line of comment-stripped content.
+ */
+function hasVisibleHeadingLine(content, heading) {
+    return visibleMarkdown(content)
+        .split(/\r?\n/)
+        .some((line) => line.trim() === heading);
+}
+/**
+ * Ensure an orchestrator file exists: prefer the workspace's template, fall
+ * back to a minimal header for scaffolds that predate the template.
+ * @returns the file's current content.
+ */
+async function ensureOrchestratorFile(workspaceDir, fileName, templateName, fallbackHeader) {
+    const filePath = join(workspaceDir, fileName);
+    if (!(await pathExists(filePath))) {
+        const templatePath = join(workspaceDir, "templates", templateName);
+        if (await pathExists(templatePath)) {
+            await copyFile(templatePath, filePath);
+        }
+        else {
+            await writeFile(filePath, fallbackHeader, "utf8");
+        }
+    }
+    return readFile(filePath, "utf8");
+}
+/**
+ * Append handoff `decisions` to DECISIONS.md as `D<NNN> | ...` rows under
+ * {@link DECISIONS_COMPLETION_LOG_HEADING}. Numbering continues from the
+ * highest `D<NNN>` anywhere in the file, so orchestrator-curated category
+ * entries and the completion log share one namespace. A decision whose text
+ * already appears in the file is skipped, so re-running completion cannot
+ * duplicate rows.
+ * @returns how many rows were appended.
+ */
+async function appendDecisionLog(workspaceDir, phaseId, closeoutFile, decisions) {
+    if (decisions.length === 0)
+        return 0;
+    let content = await ensureOrchestratorFile(workspaceDir, "DECISIONS.md", "decisions-template.md", "# Decisions\n\nAppend-only log of cross-cutting decisions. This scaffold predates templates/decisions-template.md; refresh the framework-owned files for the full format.\n");
+    // The template ships worked examples inside HTML comments (a commented
+    // `D001 | ...` row); numbering and dedupe must read only visible content or
+    // a fresh file starts at D002 and a decision matching example text is lost.
+    const visible = visibleMarkdown(content);
+    const fresh = decisions.filter((decision) => decision.trim() && !visible.includes(decision.trim()));
+    if (fresh.length === 0)
+        return 0;
+    let nextNumber = 1;
+    for (const match of visible.matchAll(/^D(\d+)\s*\|/gm)) {
+        const parsed = Number.parseInt(match[1], 10);
+        if (Number.isFinite(parsed) && parsed >= nextNumber)
+            nextNumber = parsed + 1;
+    }
+    if (!hasVisibleHeadingLine(content, DECISIONS_COMPLETION_LOG_HEADING)) {
+        content += `${content.endsWith("\n") ? "" : "\n"}\n${DECISIONS_COMPLETION_LOG_HEADING}\n\nAppended by completion from each phase handoff's \`decisions\` array. The orchestrator may re-file entries into the category sections above; numbering is shared with them.\n`;
+    }
+    const source = closeoutFile.replace(/\.md$/, "");
+    const rows = fresh.map((decision, index) => {
+        const number = String(nextNumber + index).padStart(3, "0");
+        return `D${number} | ${decision.trim()} | ${source} | closeouts/${closeoutFile} §Decisions Beyond Prompt (${phaseId})`;
+    });
+    content += `${content.endsWith("\n") ? "" : "\n"}${rows.join("\n")}\n`;
+    await writeFile(join(workspaceDir, "DECISIONS.md"), content, "utf8");
+    return fresh.length;
+}
+/**
+ * Count staged proposals in CONVENTIONS.md's pending section.
+ * @param content - the file content, or null to read from disk (null when the file is absent).
+ */
+export async function countPendingProposals(workspaceDir, content) {
+    let text = content;
+    if (text === undefined) {
+        const filePath = join(workspaceDir, "CONVENTIONS.md");
+        if (!(await pathExists(filePath)))
+            return 0;
+        text = await readFile(filePath, "utf8");
+    }
+    // Same line-anchored rule as the heading-insertion checks: a prose mention
+    // of the heading must not open the section early and miscount.
+    const lines = visibleMarkdown(text).split(/\r?\n/);
+    const headingIndex = lines.findIndex((line) => line.trim() === CONVENTIONS_PENDING_HEADING);
+    if (headingIndex === -1)
+        return 0;
+    let count = 0;
+    for (const line of lines.slice(headingIndex + 1)) {
+        if (line.startsWith("## "))
+            break;
+        if (line.startsWith("- **"))
+            count += 1;
+    }
+    return count;
+}
+/**
+ * Stage handoff `proposed_conventions` in CONVENTIONS.md under
+ * {@link CONVENTIONS_PENDING_HEADING}. Staging is mechanical; promotion into
+ * the numbered convention sections stays an orchestrator judgment at the
+ * phase boundary. A proposal whose name and rule both already appear in the
+ * file is skipped, so re-running completion cannot duplicate entries.
+ * @returns staged count and the section's total pending count afterward.
+ */
+async function stageProposedConventions(workspaceDir, phaseId, timestamp, proposals) {
+    if (proposals.length === 0) {
+        return { staged: 0, totalPending: await countPendingProposals(workspaceDir) };
+    }
+    let content = await ensureOrchestratorFile(workspaceDir, "CONVENTIONS.md", "conventions-template.md", "# Conventions\n\nCross-cutting patterns promoted to project-wide invariants. This scaffold predates templates/conventions-template.md; refresh the framework-owned files for the full format.\n");
+    if (!hasVisibleHeadingLine(content, CONVENTIONS_PENDING_HEADING)) {
+        content += `${content.endsWith("\n") ? "" : "\n"}\n${CONVENTIONS_PENDING_HEADING}\n\nStaged by completion from each phase handoff's \`proposed_conventions\`. The orchestrator promotes an entry into a numbered convention above (or removes it with a note) at the phase boundary — see GUIDE.md §Roles.\n`;
+    }
+    // Same visible-content rule as the decision log: template comments must not
+    // swallow a genuine proposal through the dedupe check.
+    const visible = visibleMarkdown(content);
+    const fresh = proposals.filter((proposal) => !(visible.includes(`**${proposal.name}**`) && visible.includes(proposal.rule)));
+    if (fresh.length > 0) {
+        const bullets = fresh.map((proposal) => {
+            const evidence = proposal.evidence ? `\n  - Evidence: ${proposal.evidence}` : "";
+            return `- **${proposal.name}** (${phaseId}, ${dateOnly(timestamp)}) — ${proposal.rule}${evidence}`;
+        });
+        content += `${content.endsWith("\n") ? "" : "\n"}${bullets.join("\n")}\n`;
+        await writeFile(join(workspaceDir, "CONVENTIONS.md"), content, "utf8");
+    }
+    return { staged: fresh.length, totalPending: await countPendingProposals(workspaceDir, content) };
+}
+/** Build the phase-boundary checkpoint line, or undefined when nothing needs surfacing. */
+function buildOrchestratorCheckpoint(decisionsAppended, totalPendingProposals, status) {
+    const openQuestions = Object.values(status.phases).reduce((sum, phase) => sum + (phase.open_questions?.length ?? 0), 0);
+    const parts = [];
+    if (decisionsAppended > 0)
+        parts.push(`${decisionsAppended} decision(s) appended to DECISIONS.md`);
+    if (totalPendingProposals > 0)
+        parts.push(`${totalPendingProposals} proposal(s) pending in CONVENTIONS.md — promote or remove them before the next phase`);
+    if (openQuestions > 0)
+        parts.push(`${openQuestions} open question(s) outstanding — re-triage their kind labels before the next phase (GUIDE.md §Roles)`);
+    if (parts.length === 0)
+        return undefined;
+    return `Orchestrator checkpoint: ${parts.join("; ")}.`;
+}
 function escapeRegExp(value) {
     return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
@@ -44,7 +225,13 @@ async function writeCompletionArtifacts(workspaceDir, phaseId, validation, times
     if (!current.split(/\r?\n/).some((line) => line.includes(link))) {
         await appendFile(threadLogPath, `${entry}\n`, "utf8");
     }
-    return `.codecarto/closeouts/${closeoutFile}`;
+    // Mechanize the orchestrator loop's bookkeeping half (issue #98): decisions
+    // reach DECISIONS.md and proposals reach CONVENTIONS.md at completion, so a
+    // run without a promotion ritual cannot strand them in closeout prose.
+    // Promotion of pending proposals into numbered conventions stays judged.
+    const decisionsAppended = await appendDecisionLog(workspaceDir, phaseId, closeoutFile, handoff?.decisions ?? []);
+    const { totalPending: totalPendingProposals } = await stageProposedConventions(workspaceDir, phaseId, timestamp, handoff?.proposed_conventions ?? []);
+    return { closeoutPath: `.codecarto/closeouts/${closeoutFile}`, decisionsAppended, totalPendingProposals };
 }
 export async function completeValidatedPhase(cwd, validation, sourceLabel) {
     const initialState = await getWorkspaceState(cwd);
@@ -63,7 +250,7 @@ export async function completeValidatedPhase(cwd, validation, sourceLabel) {
         if (declaringPhase?.handoff_requirements?.length) {
             throw new Error(`Phase ${validation.phaseId} declares handoff_requirements, but no phase handoff exists at .codecarto/scratch/handoffs/${validation.phaseId}.yaml. `
                 + `Write the handoff first (see GUIDE.md and templates/phase-handoff.yaml): schema_version: 1, the exact phase_id, `
-                + `arrays for owner_notes, open_questions, carry_forward, carry_forward_closures, open_question_closures, post_pipeline, and decisions (omitted arrays default to empty), `
+                + `arrays for owner_notes, open_questions, carry_forward, carry_forward_closures, open_question_closures, post_pipeline, decisions, and proposed_conventions (omitted arrays default to empty), `
                 + `plus closeout_summary and optional closeout_content. Then re-run completion.`);
         }
     }
@@ -83,6 +270,7 @@ export async function completeValidatedPhase(cwd, validation, sourceLabel) {
     }
     const completionTimestamp = new Date().toISOString();
     let closeoutPath;
+    let orchestratorCheckpoint;
     const updatedState = await updateStatusAtomically(cwd, async (lockedState) => {
         const phase = resolvePhase(lockedState, validation.phaseId);
         if (!phase?.primary_output)
@@ -129,12 +317,15 @@ export async function completeValidatedPhase(cwd, validation, sourceLabel) {
         nextStatus.current_phase = nextEligible?.id ?? "complete";
         nextStatus.next_actions = nextEligible
             ? [`Begin ${nextEligible.id} phase by producing ${nextEligible.primary_output ?? `findings/${nextEligible.id}/`}`]
-            : ["All phases complete. Review findings, open questions, and downstream implementation notes."];
-        closeoutPath = await writeCompletionArtifacts(lockedState.workspaceDir, validation.phaseId, validation, completionTimestamp, handoff);
+            : buildTerminalNextActions(nextStatus);
+        const artifacts = await writeCompletionArtifacts(lockedState.workspaceDir, validation.phaseId, validation, completionTimestamp, handoff);
+        closeoutPath = artifacts.closeoutPath;
+        orchestratorCheckpoint = buildOrchestratorCheckpoint(artifacts.decisionsAppended, artifacts.totalPendingProposals, nextStatus);
         return { state: { ...nextWorkspace, status: nextStatus } };
     });
     return {
         updatedState,
         closeoutNotice: closeoutPath ? `Closeout: ${closeoutPath}` : undefined,
+        orchestratorCheckpoint,
     };
 }

package/dist/core/index.d.ts

@@ -2,6 +2,7 @@ export * from "./types.ts";
 export * from "./utils.ts";
 export * from "./yaml.ts";
 export * from "./status.ts";
+export * from "./amendment.ts";
 export * from "./pipeline.ts";
 export * from "./prompts.ts";
 export * from "./workspace.ts";

package/dist/core/index.js

@@ -5,6 +5,7 @@ export * from "./types.js";
 export * from "./utils.js";
 export * from "./yaml.js";
 export * from "./status.js";
+export * from "./amendment.js";
 export * from "./pipeline.js";
 export * from "./prompts.js";
 export * from "./workspace.js";

package/dist/core/pipeline.js

@@ -72,6 +72,17 @@ export async function validatePhaseOutput(state, phaseId) {
     if (!phase.primary_output) {
         throw new Error(`Phase ${phase.id} has no primary_output in the active pipeline.`);
     }
+    // Declared secondary outputs with existence (issue #101): non-gating
+    // visibility, because secondary outputs are created only when needed — but
+    // a declared output that ends the phase absent AND unaccounted-for is how
+    // a real run silently dropped one. The summary surfaces it; the session
+    // either writes it or routes the gap.
+    const secondaryOutputs = [];
+    for (const output of phase.secondary_outputs ?? []) {
+        if (!output.path)
+            continue;
+        secondaryOutputs.push({ path: output.path, exists: await pathExists(join(state.workspaceDir, output.path)) });
+    }
     const outputPath = join(state.workspaceDir, phase.primary_output);
     if (!(await pathExists(outputPath))) {
         return {
@@ -84,6 +95,7 @@ export async function validatePhaseOutput(state, phaseId) {
             rows: [],
             gaps: [],
             errors: [`Missing primary output: .codecarto/${phase.primary_output}`],
+            secondaryOutputs,
         };
     }
     const content = await readFile(outputPath, "utf8");
@@ -99,6 +111,7 @@ export async function validatePhaseOutput(state, phaseId) {
             rows: [],
             gaps: [],
             errors: ["Primary output exists but is missing a ## Validation block."],
+            secondaryOutputs,
         };
     }
     const validationContent = content.slice(validationHeadingIndex);
@@ -154,6 +167,7 @@ export async function validatePhaseOutput(state, phaseId) {
         rows,
         gaps,
         errors,
+        secondaryOutputs,
     };
 }
 export function buildValidationSummary(validation) {
@@ -169,5 +183,9 @@ export function buildValidationSummary(validation) {
     if (validation.errors.length > 0) {
         lines.push(...validation.errors.slice(0, 3));
     }
+    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.`);
+    }
     return lines;
 }

package/dist/core/prompts.js

@@ -4,8 +4,60 @@
 import { readdir } from "node:fs/promises";
 import { join } from "node:path";
 import { pathExists } from "./utils.js";
+import { countPendingProposals } from "./completion.js";
 import { describeScaffoldStaleness } from "./workspace.js";
 import { runPhasePreflight } from "./synthesis.js";
+/** Open-question kinds whose label the orchestrator re-tests at each phase boundary. */
+const RETRIAGE_KINDS = new Set(["needs-maintainer-decision", "needs-runtime-test"]);
+/** Cap on individually listed re-triage questions; the rest collapse to a count. */
+const RETRIAGE_LIST_LIMIT = 10;
+/**
+ * Build the "Orchestrator duties" prompt block (issue #98): the cross-phase
+ * intelligence surfaced mechanically, so an inline run cannot skip it
+ * silently. Returns an empty array when there is nothing to surface (fresh
+ * workspace, no proposals, no questions, no declared secondary outputs).
+ */
+async function buildOrchestratorDuties(state, phase, auto) {
+    const lines = [];
+    const pendingProposals = await countPendingProposals(state.workspaceDir);
+    if (pendingProposals > 0) {
+        lines.push(`- CONVENTIONS.md has ${pendingProposals} pending proposal(s) under "## Pending proposals" — promote each into a numbered convention or remove it with a note.`);
+    }
+    const retriage = [];
+    for (const [phaseId, phaseState] of Object.entries(state.status.phases)) {
+        for (const entry of phaseState.open_questions ?? []) {
+            if (!entry.kind || !RETRIAGE_KINDS.has(entry.kind))
+                continue;
+            const label = [entry.id, `(${entry.kind}, from ${phaseId})`, entry.description ?? ""].filter(Boolean).join(" ").trim();
+            retriage.push(label);
+        }
+    }
+    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:");
+        for (const label of retriage.slice(0, RETRIAGE_LIST_LIMIT))
+            lines.push(`  - ${label}`);
+        if (retriage.length > RETRIAGE_LIST_LIMIT)
+            lines.push(`  - (+${retriage.length - RETRIAGE_LIST_LIMIT} more in workflow/status.yaml)`);
+    }
+    const secondaryOutputs = phase.secondary_outputs ?? [];
+    if (secondaryOutputs.length > 0) {
+        lines.push("- This phase declares secondary outputs. Each should end the phase either written or explicitly accounted for (in Coverage and limits, or a routed handoff entry) — never dropped silently:");
+        for (const output of secondaryOutputs) {
+            const exists = await pathExists(join(state.workspaceDir, output.path));
+            lines.push(`  - .codecarto/${output.path} (${exists ? "exists" : "missing"})`);
+        }
+    }
+    const anyCompleted = Object.values(state.status.phases).some((phaseState) => phaseState.status === "complete");
+    if (anyCompleted) {
+        lines.push("- Contradiction sweep: compare this phase's required reads against completed phases' owner_notes; a measured fact that contradicts a summarized claim is a gap to route through the handoff, not a nuance to smooth over.");
+    }
+    if (lines.length === 0)
+        return [];
+    const header = auto
+        ? "Orchestrator duties (auto run — perform them without asking the user; defer judgment calls into the handoff's owner_notes or open_questions):"
+        : "Orchestrator duties (perform BEFORE executing this phase; see GUIDE.md §Roles):";
+    return ["", header, ...lines];
+}
 export function describeEntry(entry) {
     const parts = [];
     if (entry.id)
@@ -96,6 +148,7 @@ export async function buildPhasePrompt(state, phase, forced, options = {}) {
         }
         lines.push("Close each item by editing your phase output to address it, then record the closure in your phase handoff so the framework can remove the carry_forward entry atomically.");
     }
+    lines.push(...await buildOrchestratorDuties(state, phase, options.auto === true));
     if (preflight.libraryPath) {
         lines.push("", "Synthesis library context:");
         lines.push(`- Library: ${preflight.libraryName ?? "CodeCartographer library"} (${preflight.libraryPath})`);

package/dist/core/status.d.ts

@@ -1,4 +1,4 @@
-import type { NormalizedStatus, OpenQuestionEntry, PostPipelineEntry, PhaseHandoff, PipelineFile, StatusFile, StatusPhase } from "./types.ts";
+import type { NormalizedStatus, OpenQuestionEntry, PostPipelineEntry, PhaseHandoff, PipelineFile, ProposedConventionEntry, StatusFile, StatusPhase } from "./types.ts";
 export declare const LOCK_RETRY_MS = 125;
 export declare const LOCK_TIMEOUT_MS = 5000;
 export declare const STALE_LOCK_MS = 60000;
@@ -9,8 +9,23 @@ export declare function autoAssignIds(entries: OpenQuestionEntry[], prefix: stri
 export declare function ensurePostPipelineArray(value: unknown): PostPipelineEntry[];
 export declare function ensurePhaseRecord(value: unknown): Record<string, StatusPhase>;
 export declare function createEmptyStatus(projectName: string, pipelinePath: string, pipeline: PipelineFile): NormalizedStatus;
+/**
+ * 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.
+ */
+export declare function buildTerminalNextActions(status: NormalizedStatus): string[];
 export declare function normalizeStatus(status: StatusFile, pipeline: PipelineFile, pipelinePath: string, cwd: string): NormalizedStatus;
 export declare function parseHandoff(value: unknown): PhaseHandoff;
+/**
+ * Parse the handoff's `proposed_conventions` collection. A present entry must
+ * carry non-empty `name` and `rule` strings — a proposal the framework cannot
+ * stage legibly fails completion loudly instead of being staged as a stub
+ * (same posture as post_pipeline's required id). Omitted defaults to empty.
+ */
+export declare function ensureProposedConventionArray(value: unknown): ProposedConventionEntry[];
 export declare function loadHandoffFile(phaseId: string, workspaceDir: string): Promise<PhaseHandoff | null>;
 export declare function applyHandoff(status: NormalizedStatus, handoff: PhaseHandoff): NormalizedStatus;
 export declare function acquireLock(lockPath: string): Promise<{

package/dist/core/status.js

@@ -126,6 +126,28 @@ export function createEmptyStatus(projectName, pipelinePath, pipeline) {
         post_pipeline: [],
     };
 }
+/**
+ * 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.
+ */
+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.",
+    ];
+    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).`);
+    }
+    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("Dashboard: .codecarto/dashboard.html (refreshed on completion and amendment; codecarto_dashboard re-renders on demand). Usage totals: codecarto_usage.");
+    return actions;
+}
 export function normalizeStatus(status, pipeline, pipelinePath, cwd) {
     if (typeof status.schema_version === "number" && status.schema_version > 1) {
         throw new Error(`Unsupported status schema_version ${status.schema_version}. Supported: 1.`);
@@ -166,7 +188,7 @@ export function parseHandoff(value) {
     if (schemaVersion > 1) {
         throw new Error(`Invalid handoff: unsupported schema_version ${schemaVersion}. Supported: 1.`);
     }
-    for (const field of ["owner_notes", "open_questions", "carry_forward", "carry_forward_closures", "open_question_closures", "post_pipeline", "decisions"]) {
+    for (const field of ["owner_notes", "open_questions", "carry_forward", "carry_forward_closures", "open_question_closures", "post_pipeline", "decisions", "proposed_conventions"]) {
         if (raw[field] !== undefined && !Array.isArray(raw[field])) {
             throw new Error(`Invalid handoff: ${field} must be an array`);
         }
@@ -185,11 +207,37 @@ export function parseHandoff(value) {
         open_question_closures: ensureArray(raw.open_question_closures),
         post_pipeline: ensurePostPipelineArray(raw.post_pipeline),
         decisions: ensureArray(raw.decisions),
+        proposed_conventions: ensureProposedConventionArray(raw.proposed_conventions),
         closeout_content: typeof raw.closeout_content === "string" ? raw.closeout_content : "",
         closeout_summary: typeof raw.closeout_summary === "string" ? raw.closeout_summary : "",
         schema_version: schemaVersion,
     };
 }
+/**
+ * Parse the handoff's `proposed_conventions` collection. A present entry must
+ * carry non-empty `name` and `rule` strings — a proposal the framework cannot
+ * stage legibly fails completion loudly instead of being staged as a stub
+ * (same posture as post_pipeline's required id). Omitted defaults to empty.
+ */
+export function ensureProposedConventionArray(value) {
+    if (!Array.isArray(value))
+        return [];
+    const result = [];
+    for (const item of value) {
+        if (!item || typeof item !== "object" || Array.isArray(item)) {
+            throw new Error("Invalid handoff: proposed_conventions entries must be objects with name and rule");
+        }
+        const raw = item;
+        const name = typeof raw.name === "string" ? raw.name.trim() : "";
+        const rule = typeof raw.rule === "string" ? raw.rule.trim() : "";
+        if (!name || !rule) {
+            throw new Error("Invalid handoff: proposed_conventions entries require non-empty name and rule");
+        }
+        const evidence = typeof raw.evidence === "string" && raw.evidence.trim() ? raw.evidence.trim() : undefined;
+        result.push({ name, rule, ...(evidence !== undefined && { evidence }) });
+    }
+    return result;
+}
 export async function loadHandoffFile(phaseId, workspaceDir) {
     assertSafePhaseId(phaseId);
     const handoffPath = join(workspaceDir, "scratch", "handoffs", `${phaseId}.yaml`);