codecartographer-pi 0.17.1 → 0.18.0

package/.codecarto/GUIDE.md

@@ -92,7 +92,7 @@ If you are uncertain whether a file should be modified, treat it as read-only.
 ### Two things named "backlog", and neither is the other
 
 - **`BACKLOG.md` in this workspace** is *this project's* deferrals: work the project chose not to do yet. `DECISIONS.md` records what the project decided to **do**; `BACKLOG.md` records what it decided to **defer**. Deferrals get no `D` number. When a deferred item is later picked up, remove its entry here and record the decision in `DECISIONS.md`.
-- **`status.yaml`'s `post_pipeline` list** is framework-owned lifecycle state, not this file. Items there are retired by `codecarto_amend`, never by hand.
+- **`status.yaml`'s `post_pipeline` list** is framework-owned lifecycle state, not this file. Items there are retired by an amendment (`codecarto_amend` on MCP, `/codecarto-amend` on Pi), never by hand.
 - **CodeCartographer's own backlog** — deferred improvements to the *framework* — lives in the CodeCartographer repository, not in your workspace. If a phase prompt misled you or a validation criterion did not fit, that is feedback to the framework; it does not belong in this file.
 
 ## Pipeline Selection
@@ -215,7 +215,7 @@ post_pipeline:
 
 `kind` is one of: `needs-runtime-test`, `needs-maintainer-decision`, `needs-spec-ruling`, `defer-to-phase`, `needs-fixture-capture`, or a post-pipeline work kind such as `spike` or `amendment`. Every new `carry_forward.target_phase` must be an ID in the active pipeline. Every `post_pipeline` entry requires a stable ID. Open questions should carry a stable `id` (e.g. `q-loadconfig-ambiguity`); if omitted, the framework auto-assigns one. When a later phase resolves an open question, list its id in `open_question_closures` to remove it from all phases. The downstream phase records resolved carry-forward IDs in `carry_forward_closures`; completion removes those entries atomically.
 
-After the pipeline completes, the handoff channel closes with it. Post-pipeline resolutions — an open question answered on evidence, a finished `post_pipeline` backlog item — are applied with an **amendment**: write `scratch/amendments/<slug>.yaml` (see `templates/amendment.yaml`) and run `codecarto_amend`. It updates `workflow/status.yaml` under the same lock completion uses and writes an amendment closeout plus THREAD_LOG entry. Never hand-edit `status.yaml` for this; amendments are refused while the pipeline is still running, so the two channels cannot race.
+After the pipeline completes, the handoff channel closes with it. Post-pipeline resolutions — an open question answered on evidence, a finished `post_pipeline` backlog item — are applied with an **amendment**: write `scratch/amendments/<slug>.yaml` (see `templates/amendment.yaml`) and run `codecarto_amend` (MCP) or `/codecarto-amend <slug>` (Pi). It updates `workflow/status.yaml` under the same lock completion uses and writes an amendment closeout plus THREAD_LOG entry. Never hand-edit `status.yaml` for this; amendments are refused while the pipeline is still running, so the two channels cannot race.
 
 ## Phase Selection Logic
 

package/.codecarto/skills/spec-delta-application/SKILL.md

@@ -88,7 +88,7 @@ Per the standard closeout ritual:
 
 - Append a one-line entry to `THREAD_LOG.md` pointing at the closeout file.
 - Write `closeouts/<YYYY-MM-DD>-spec-deltas.md` using `templates/closeout-template.md`.
-- If a delta resolved an `open_questions` entry (or finished a `post_pipeline` backlog item), apply it: write `scratch/amendments/<slug>.yaml` (see `templates/amendment.yaml`) listing the closures, then run `codecarto_amend`. It updates `status.yaml` under the completion lock and writes the amendment closeout — never hand-edit `status.yaml`, which is framework-owned. Without the MCP server, record the intended amendment file in the closeout for the next MCP-capable session to apply.
+- If a delta resolved an `open_questions` entry (or finished a `post_pipeline` backlog item), apply it: write `scratch/amendments/<slug>.yaml` (see `templates/amendment.yaml`) listing the closures, then run `codecarto_amend` (MCP) or `/codecarto-amend <slug>` (Pi). It updates `status.yaml` under the completion lock and writes the amendment closeout — never hand-edit `status.yaml`, which is framework-owned. Without Pi or the MCP server (drop-in mode), record the intended amendment file in the closeout for the next Pi or MCP session to apply.
 - Append numbered entries to `DECISIONS.md` for any decisions made during triage that weren't already in the deltas (e.g., "rejected Δ7 because the spec already covered the case at §X").
 
 ## What to avoid

package/.codecarto/templates/amendment.yaml

@@ -1,7 +1,7 @@
 # Post-pipeline amendment schema v1. Copy to scratch/amendments/<slug>.yaml,
-# then run codecarto_amend (MCP) with the slug. Refused while the pipeline is
-# incomplete — mid-pipeline resolutions belong in the phase handoff
-# (open_question_closures / carry_forward_closures).
+# then run codecarto_amend (MCP) or /codecarto-amend <slug> (Pi). Refused while
+# the pipeline is incomplete — mid-pipeline resolutions belong in the phase
+# handoff (open_question_closures / carry_forward_closures).
 schema_version: 1
 # Open-question ids resolved on evidence after the pipeline completed;
 # removed from every phase in workflow/status.yaml.

package/.codecarto/templates/spike-report.md

@@ -12,8 +12,8 @@
   phase handoff. When a spike's findings change the reimplementation spec, write
   the deltas as Recommended Deltas below and apply them with the
   spec-delta-application skill; when a spike resolves an open question after the
-  pipeline completed, close it with an amendment (templates/amendment.yaml +
-  codecarto_amend), citing this report.
+  pipeline completed, close it with an amendment (templates/amendment.yaml, then
+  codecarto_amend on MCP or /codecarto-amend on Pi), citing this report.
 
   Keep it honest: a spike that failed to answer its question is a valid result —
   record what was tried and what blocked it.

package/.codecarto/workflow/scaffold-version.yaml

@@ -3,4 +3,4 @@
 # workspace's framework-owned files (GUIDE.md, templates/, workflow/ pipelines
 # and VALIDATE.md) predate the running release. Written at release time and
 # copied verbatim by init — never edit by hand.
-scaffold_version: 0.17.1
+scaffold_version: 0.18.0

package/README.md

@@ -92,7 +92,7 @@ Use this when your coding agent isn't Pi — Claude Code, Codex, opencode, Curso
 
 > **30-second setup for Claude Code, Cursor, Codex, and Claude Desktop: see the [MCP quickstart](docs/mcp-quickstart.md).**
 
-> **Teaching an agent to drive it:** call the `codecarto_guide` tool — the server returns the full drive loop, the phase-handoff contract, executor selection, and recovery patterns, with nothing to install. The same content ships as an installable skill at `agent-skill/codecartographer/` for agents that load skills from disk.
+> **Teaching an agent to drive it:** call the `codecarto_guide` tool — the server returns the full drive loop, the phase-handoff contract, executor selection, and recovery patterns, with nothing to install. The same content ships as an installable skill at `agent-skill/codecartographer/` for agents that load skills from disk, and `/codecarto-guide [topic]` reads it into a Pi session.
 
 ```bash
 npm install --global codecartographer-pi
@@ -137,7 +137,7 @@ Analysis turns repositories into reusable specifications. Synthesis runs the oth
    library:
      path: /absolute/path/to/codecarto-library
      namespace: your-namespace # omit for a single-tenant library
-     publish_confirm: true
+     publish_confirm: true # Pi asks before writing; MCP refuses a publish that lacks confirm: true
    ```
 
 2. Initialize a clean planning workspace and fill in its brief:
@@ -321,12 +321,16 @@ Beyond the slash commands, the Pi extension layers on:
 | `/codecarto-validate [phase]` | Validate a phase output against completion criteria |
 | `/codecarto-complete [phase]` | Validate and atomically apply the phase handoff, canonical status, closeout, and log entry |
 | `/codecarto-skill <name>` | Run a post-pipeline skill once all phases are complete (or `broadside` any time, for the scout reading guide) |
+| `/codecarto-list-skills` | List the installed post-pipeline skills and the ungated `broadside` reading guide, and say when the gated ones unlock |
+| `/codecarto-guide [topic]` | Read the packaged agent guide — drive loop, handoff contract, executors, recovery, Broad-Side — into the session; tab-completes topics; needs no workspace |
 | `/codecarto-broadside [action] [lenses…]` | Batch reconnaissance (Broad-Side). Actions: `submit`, `collect`, `status`, `models`. Prices the run and asks before spending; works with or without a workspace |
 | `/codecarto-publish` | Publish the reimplementation spec to the configured library after reviewing an explicit confirmation preview |
 | `/codecarto-library-init <path> [--namespace <name>]` | Create a library directory with marker and write the config — fixes the first-publish dead end |
 | `/codecarto-config` | Show the effective merged configuration (global + workspace) and library marker status |
 | `/codecarto-usage` | Cumulative + per-phase token usage |
 | `/codecarto-dashboard [--narrate]` | Regenerate `.codecarto/dashboard.html`; `--narrate` for the LLM executive summary |
+| `/codecarto-refresh-scaffold` | Refresh the framework-owned `.codecarto/` files (GUIDE.md, templates/, workflow/ pipelines and VALIDATE.md) from the packaged template after a confirmation that lists the exact file set; project state, config, findings outputs, scratch, closeouts, and `broadside/` are never touched |
+| `/codecarto-amend <name>` | Apply a post-pipeline amendment from `scratch/amendments/<name>.yaml` after a confirmation that previews which open questions and post-pipeline items it closes; refused while the pipeline is incomplete |
 
 ### End-to-end auto mode (0.8.0+)
 
@@ -360,7 +364,7 @@ Implements MCP spec revision [`2025-11-25`](https://modelcontextprotocol.io/spec
 | `codecarto_validate` | `/codecarto-validate` |
 | `codecarto_complete` | `/codecarto-complete` |
 | `codecarto_skill` | `/codecarto-skill` |
-| `codecarto_list_skills` | MCP-only ([#161](https://github.com/HuginnIndustries/CodeCartographer/issues/161)); Pi lists skills when `/codecarto-skill` runs with no argument |
+| `codecarto_list_skills` | `/codecarto-list-skills` |
 | `codecarto_publish` | `/codecarto-publish` |
 | `codecarto_library_init` | `/codecarto-library-init` |
 | `codecarto_library_list` | MCP-only library listing |
@@ -368,9 +372,9 @@ Implements MCP spec revision [`2025-11-25`](https://modelcontextprotocol.io/spec
 | `codecarto_config` | `/codecarto-config` |
 | `codecarto_usage` | `/codecarto-usage` |
 | `codecarto_dashboard` | `/codecarto-dashboard` |
-| `codecarto_guide` | MCP-only ([#160](https://github.com/HuginnIndustries/CodeCartographer/issues/160)) |
-| `codecarto_amend` | MCP-only ([#157](https://github.com/HuginnIndustries/CodeCartographer/issues/157)) |
-| `codecarto_refresh_scaffold` | MCP-only ([#159](https://github.com/HuginnIndustries/CodeCartographer/issues/159)) |
+| `codecarto_guide` | `/codecarto-guide` |
+| `codecarto_amend` | `/codecarto-amend` (Pi previews the closures and asks first) |
+| `codecarto_refresh_scaffold` | `/codecarto-refresh-scaffold` (Pi lists the file set and asks first) |
 | `codecarto_broadside` | `/codecarto-broadside` |
 
 Each workflow tool accepts an absolute `cwd` for the target repository. `codecarto_init` requires `force: true` to overwrite an existing `.codecarto/` (instead of Pi's interactive confirmation). The library tools accept an explicit absolute `library_path` or resolve `library.path` from `.codecarto/workflow/config.yaml` / `~/.codecarto/config.yaml`. `codecarto_library_reindex` and `codecarto_library_list` also report entries whose versions disagree about `source_repo` — the shape a slug collision left behind before v0.17.0's publish guard — and leave the repair manual, since splitting an entry changes paths the library format treats as ABI. The library schema is experimental and may break before v2.

package/agent-skill/codecartographer/SKILL.md

@@ -117,7 +117,7 @@ A PARTIAL row's evidence must name what is missing and which `open_questions` or
 - `codecarto_next` returns a prompt. Something still has to *do* the phase.
 - Never hand-edit `workflow/status.yaml`, append `THREAD_LOG.md`, or write a second closeout. Propose through the handoff.
 - Do not force phases out of DAG order unless the user asked.
-- If `codecarto_status` reports a scaffold-staleness warning, refresh the workspace's framework-owned files before trusting anything written inside `.codecarto/`; a stale scaffold's `GUIDE.md` can contradict this contract.
+- If `codecarto_status` reports a scaffold-staleness warning, refresh the workspace's framework-owned files (`codecarto_refresh_scaffold`; `/codecarto-refresh-scaffold` on the Pi extension) before trusting anything written inside `.codecarto/`; a stale scaffold's `GUIDE.md` can contradict this contract. The refresh never touches project state, findings outputs, or session directories.
 - A delegated run that times out may still have written its artifact. Check for the file and validate before retrying.
 - The drop-in `.codecarto/` template works without MCP, but the server is preferred: it owns atomic state updates, validation parsing, and the completion gate.
 

package/agent-skill/codecartographer/references/library.md

@@ -13,7 +13,7 @@ A CodeCartographer **library** is a directory of published reimplementation-spec
 | Tool | Does | Notes |
 |---|---|---|
 | `codecarto_library_init` | Create the directory, write the marker, record `library.path` in user-global config | Idempotent; pass `namespace` to create a namespaced library |
-| `codecarto_publish` | Publish a spec as a library entry | Required: `source_repo`, `headline`, and `spec` (inline) or `spec_path` (absolute). Content-hash idempotent: identical bytes update metadata in place, no version bump. `slug` derives from `source_repo` if omitted; namespaced libraries require `namespace` (or inherit via `cwd`). Provenance (`source_commit`, `source_branch`, `source_dirty`, `analyzed_at`, `pipeline`, `model_metadata`) is recorded; omitted generation fields default to `unknown` |
+| `codecarto_publish` | Publish a spec as a library entry | Required: `source_repo`, `headline`, and `spec` (inline) or `spec_path` (absolute). Content-hash idempotent: identical bytes update metadata in place, no version bump. `slug` derives from `source_repo` if omitted; namespaced libraries require `namespace` (or inherit via `cwd`). Provenance (`source_commit`, `source_branch`, `source_dirty`, `analyzed_at`, `pipeline`, `model_metadata`) is recorded; omitted generation fields default to `unknown`. `confirm: true` acknowledges the `publish_confirm` gate (below) |
 | `codecarto_library_list` | List entries | Filter by `namespace`, `tag`, `slug`, or `source_repo` |
 | `codecarto_library_reindex` | Regenerate `index.yaml` + `INDEX.md` from filesystem state | For manual edits and index merge conflicts. Also reports entries whose versions disagree about `source_repo` (merged by a slug collision before publish refused cross-project appends; `codecarto_library_list` flags them too) — repair is manual, split the entry by hand |
 
@@ -25,7 +25,7 @@ The moment `reimplementation-spec` completes and validates is the publish moment
 codecarto_publish cwd:<workspace repo> source_repo:<repo URL or path> headline:"<one line>" spec_path:<abs path to reimplementation-spec.md>
 ```
 
-Set `publish_confirm` in config if you want an explicit confirmation gate before writes. **Pi-only today:** the Pi extension asks for interactive confirmation before `/codecarto-publish` writes; the MCP `codecarto_publish` tool does not act on the key (an MCP host has no one to ask — [#162](https://github.com/HuginnIndustries/CodeCartographer/issues/162) tracks whether it should refuse-unless-forced instead), so on MCP treat it as advisory.
+Set `publish_confirm` in config if you want an explicit confirmation gate before writes. It means something on both executable surfaces, in the only way each can ask. The Pi extension shows a preview and asks interactively before `/codecarto-publish` writes. The MCP `codecarto_publish` tool has no one to ask, so when the key is set — in `~/.codecarto/config.yaml`, or in the workspace's `.codecarto/workflow/config.yaml` when `cwd` is passed — it refuses a call that lacks `confirm: true` and returns the preview instead: library, entry, whether this would be a new version or a metadata-only update, `source_repo`, headline, confidentiality. Nothing is written by the refusal. Show the preview, then re-invoke with the same arguments plus `confirm: true` to publish. The gate applies only when the key is actually set in a config file (`codecarto_library_init` writes `publish_confirm: true`, so a library initialized through the tool has it on); a host that never configured the key is not gated, and `publish_confirm: false` drops the gate.
 
 ## What this is not
 

package/agent-skill/codecartographer/references/phase-recovery.md

@@ -39,7 +39,7 @@ If two reduced-scope attempts fail, the problem is usually scope, not the execut
 
 - Split the reading. Use scoped pre-passes over individual subsystems, save the notes under `.codecarto/scratch/`, and give the retry those notes as evidence.
 - Consider whether the pipeline variant is right. A repository too large for one `architecture` pass may want `architecture-only` first, reviewed, then a switch.
-- Check for a scaffold-staleness warning in `codecarto_status`. A workspace whose framework-owned files predate the running version can carry instructions that contradict the current contract, which produces artifacts that fail validation for reasons the executor cannot see.
+- Check for a scaffold-staleness warning in `codecarto_status`. A workspace whose framework-owned files predate the running version can carry instructions that contradict the current contract, which produces artifacts that fail validation for reasons the executor cannot see. `codecarto_refresh_scaffold` (`/codecarto-refresh-scaffold` on the Pi extension) refreshes those files without touching project state.
 
 ## What not to do
 

package/dist/core/amendment.d.ts

@@ -27,6 +27,11 @@ export type AmendmentResult = {
 };
 /** Same charset rule as phase ids: the slug becomes file names, so path shapes are refused. */
 export declare function assertSafeAmendmentSlug(slug: string): void;
+/**
+ * Slugs of the amendment files staged under scratch/amendments/, sorted.
+ * Discovery only — nothing here is validated; {@link loadAmendmentFile} does that.
+ */
+export declare function listAmendmentNames(workspaceDir: string): Promise<string[]>;
 /**
  * Load and validate one amendment file.
  * @param name - the amendment slug, with or without a `.yaml` suffix.

package/dist/core/amendment.js

@@ -5,8 +5,8 @@
 // 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 { appendFile, mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { basename, join } from "node:path";
 import { getNextEligiblePhase } from "./pipeline.js";
 import { buildTerminalNextActions, ensureArray, normalizeStatus } from "./status.js";
 import { dateOnly, newlineIfUnterminated, pathExists } from "./utils.js";
@@ -18,6 +18,25 @@ export function assertSafeAmendmentSlug(slug) {
         throw new Error(`Invalid amendment name: ${slug}`);
     }
 }
+/**
+ * Slugs of the amendment files staged under scratch/amendments/, sorted.
+ * Discovery only — nothing here is validated; {@link loadAmendmentFile} does that.
+ */
+export async function listAmendmentNames(workspaceDir) {
+    const amendmentsDir = join(workspaceDir, "scratch", "amendments");
+    if (!(await pathExists(amendmentsDir)))
+        return [];
+    try {
+        const entries = await readdir(amendmentsDir, { withFileTypes: true });
+        return entries
+            .filter((entry) => entry.isFile() && /\.ya?ml$/i.test(entry.name))
+            .map((entry) => basename(entry.name).replace(/\.ya?ml$/i, ""))
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
 /**
  * Load and validate one amendment file.
  * @param name - the amendment slug, with or without a `.yaml` suffix.

package/dist/core/library.d.ts

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

package/dist/core/library.js

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

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

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

package/dist/core/orchestrator-config.js

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

package/dist/core/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;