# Reported issues for CodeCartographer

Pod holds 16 of 19 problems reported by people outside the maintainer team. Issues filed by the project's own owners, members and collaborators are excluded entirely — a maintainer's release checklist is not a warning to a prospective user.

Back to [CodeCartographer](/mcp/codecartographer).

## Most discussed

### needs-runtime-test open questions don't gate findings: the same run said "source alone cannot determine which" and then shipped one candidate as strong inference / fix before porting

## Summary

A phase can ship a finding as `strong inference` with action `fix before porting` while an open
question registered in the same run states that source alone cannot settle that exact point.
Nothing cross-checks the two, so the run contradicts itself and the confident version is the one
that reaches the reader.

## Reproduction

Ran `pipeline-full-with-deep-audit.yaml` over a Windows-only local LLM frontend
(ElodineOfficial/GobboNet at 5524fd4), then verified the findings by executing 

[Read the thread](https://github.com/HuginnIndustries/CodeCartographer/issues/122) · 2026-08-20 · open · 1 comment

### MCP codecarto_init force:true silently destroys all workspace data

## Problem

The MCP `codecarto_init` tool with `force: true` performs the same data-loss deletion as #62 on the Pi side, but without any interactive confirmation dialog. A host or user simply passes `force: true` and the entire `.codecarto/` directory is recursively deleted, losing all phase findings, handoffs, usage data, closeouts, checkpoints, and status.

The tool description says it "overwrites" but does not enumerate what is destroyed. An MCP host (e.g. an automated agent) could call this 

[Read the thread](https://github.com/HuginnIndustries/CodeCartographer/issues/69) · 2026-07-23 · closed · 1 comment

### MCP server handshake hardcodes stale version string (0.2.0)

## Problem

The MCP server handshake hardcodes `version: "0.2.0"` instead of using `PACKAGE_VERSION` from the package. The package is currently at 0.12.3. This means every MCP client that connects sees a wildly stale version string, undermining trust and breaking any version-gated client logic.

## Location

`mcp-server/server.ts` line 779:
```typescript
{ name: "codecartographer", version: "0.2.0" },
```

Should be:
```typescript
{ name: "codecartographer", version: PACKAGE_VERSION },
```

`PAC

[Read the thread](https://github.com/HuginnIndustries/CodeCartographer/issues/66) · 2026-07-23 · closed · 1 comment

### Pi: the source_repo collision guard has no escape hatch on the primary surface

## Problem

#127 makes `publishEntry` refuse a publish whose `source_repo` differs from the one recorded on the entry's newest version, with `allowSourceRepoChange` (`allow_source_repo_change` on `codecarto_publish`) as the opt-out for a repository that genuinely moved.

That opt-out is MCP-only. `/codecarto-publish` is registered with `handler: async (_args, ctx)` (`extensions/codecarto/index.ts:718`) and takes no arguments, so a Pi user who trips the guard after a rename, org transfer, or host

[Read the thread](https://github.com/HuginnIndustries/CodeCartographer/issues/146) · 2026-08-23 · open · 0 comments

### Broad-Side: Pi extension command /codecarto-broadside

**Roadmap item (see ROADMAP.md).** MCP parity for the Pi surface, agreed as the second-surface priority:

- `/codecarto-broadside` slash command: lens picker, key configuration prompt, submits via the core runner.
- Live progress widget while batches are in flight (reuse agent-widget patterns).
- `/codecarto-broadside collect` and `/codecarto-broadside status` mirrors.

Surface priority per CLAUDE.md says new features land on Pi first — this one landed MCP-first intentionally (batch jobs run una

[Read the thread](https://github.com/HuginnIndustries/CodeCartographer/issues/138) · 2026-08-23 · open · 0 comments

### docs: library-format.md describes three shapes the code does not produce

## Summary

Three places where `docs/library-format.md` describes a shape the code does not produce. Grouped because they are one file, one class of problem, and one fix.

The doc's stated purpose is that "external tools can read library entries without going through CodeCartographer itself", which is what makes these worth correcting rather than leaving.

## 1. `latest` is documented as a symlink and is never one

Both directory layout diagrams show `latest -> v2`, and the version resolution se

[Read the thread](https://github.com/HuginnIndustries/CodeCartographer/issues/126) · 2026-08-21 · open · 0 comments

### library format: publish is documented as committing by default, but nothing calls commitPublish

## Summary

`docs/library-format.md` says publish runs `git add` and `git commit` by default. Neither shipped surface ever commits.

## Reproduction

1. Make the library a git repository.
2. Publish an entry through either the MCP server or `/codecarto-publish`.
3. Run `git status` in the library.

## Expected behavior

Per the doc's git interaction table: "`git add` + `git commit` | Optional, on by default. Commit message: `publish: <ns>/<slug> v<N>` or `update: <ns>/<slug> metadata`. Configura

[Read the thread](https://github.com/HuginnIndustries/CodeCartographer/issues/125) · 2026-08-21 · open · 0 comments

### codecarto_usage records nothing for MCP-driven runs — 0 runs after a completed 7-phase pipeline

## What happened

After a fully completed 7-phase pipeline driven through the MCP tools, `codecarto_usage` reported:

```
No phase runs recorded yet.
```

`core/usage.ts` documents why: "each finished phase **sub-agent** contributes one entry" — the usage log is written only by the Pi extension's agent-runner. The MCP path (`codecarto_complete`) records nothing, so any run driven from Claude Code or another MCP host is invisible to usage reporting.

## Proposed fix

- Append a `UsageRun` from th

[Read the thread](https://github.com/HuginnIndustries/CodeCartographer/issues/100) · 2026-08-17 · closed · 0 comments

## Most recent

### Orchestrator duties are prose-only: handoff decisions and proposed conventions never reach DECISIONS.md/CONVENTIONS.md

## What happened

In the deepseek-harness run (7 phases, single-chat MCP), every closeout ended with a "Proposed Conventions" section and every handoff carried `decisions` entries — ~12 proposals and 23 decisions in total. None of them reached `CONVENTIONS.md` or `DECISIONS.md`, because those files are "orchestrator-maintained" and the promotion step exists only as prose in GUIDE.md. One handoff *decision* deferred a declared secondary output to a later phase; since decisions aren't routed anywh

[Read the thread](https://github.com/HuginnIndustries/CodeCartographer/issues/98) · 2026-08-17 · closed · 0 comments

### Tools whose payload is prose return nothing usable to clients that prefer structuredContent — codecarto_next returns no phase prompt

## Summary

Every tool puts its human-readable payload in `content[0].text` and a small set of machine fields in `structuredContent`. MCP clients are free to prefer `structuredContent` when it is present — and in a client that does, the five tools whose payload *is* prose return nothing usable. `codecarto_next` returns no phase prompt, which makes the pipeline undriveable.

## Reproduction

From an MCP client that surfaces `structuredContent` in preference to `content` (observed in Claude Code's

[Read the thread](https://github.com/HuginnIndustries/CodeCartographer/issues/94) · 2026-08-16 · closed · 0 comments

### No stale-scaffold detection: pre-v0.12.0 workspaces run the handoff-era framework with zero warnings

## Summary

A workspace scaffolded before v0.12.0 runs against the current framework with no warning of any kind. The framework cannot tell how old a `.codecarto/` scaffold is: no version marker is stamped at init or shipped in the template, and the phase prompt lists `.codecarto/templates/phase-handoff.yaml` as a required read without checking it exists. A pre-v0.12.0 workspace therefore has a GUIDE.md that instructs the exact opposite of the current contract ("Update `workflow/status.yaml` (th

[Read the thread](https://github.com/HuginnIndustries/CodeCartographer/issues/85) · 2026-08-16 · closed · 0 comments

### codecarto_complete silently succeeds with empty carry_forward when no phase handoff exists, even when the pipeline declares handoff_requirements

## Summary

`completeValidatedPhase` treats a missing phase handoff as normal: `loadHandoffFile` returns `null`, completion proceeds, and the phase is marked complete with `carry_forward: []` and no agent-supplied `open_questions` — even when the active pipeline declares `handoff_requirements` for that phase. The declared requirements are rendered into the phase prompt but never consulted at completion, so the entire cross-phase routing channel can silently no-op for a full pipeline run.

## Rep

[Read the thread](https://github.com/HuginnIndustries/CodeCartographer/issues/84) · 2026-08-16 · closed · 0 comments

### Shipped pipelines' handoff_requirements instruct direct status.yaml/THREAD_LOG.md edits, contradicting the handoff contract in the same prompt

## Summary

Every shipped pipeline's `handoff_requirements` still instruct the agent to `Update workflow/status.yaml.` and `Append a summary entry to THREAD_LOG.md.` — the two actions the v0.12.0 handoff contract explicitly forbids. `buildPhasePrompt` renders both instructions into the same prompt that forbids them, so every phase prompt since v0.12.0 contains a direct self-contradiction.

## Reproduction

1. `codecarto_init` any repo (default pipeline), then `codecarto_next`.
2. Read the return

[Read the thread](https://github.com/HuginnIndustries/CodeCartographer/issues/83) · 2026-08-16 · closed · 0 comments

### MCP readSpecArg skips containment check when allowedRoots is empty (defense-in-depth)

## Description

During a security audit of the v0.12.11 publish-path-containment fix, I found a defense-in-depth gap in `mcp-server/server.ts:readSpecArg`.

The function enforces path containment on `spec_path` **only when `allowedRoots.length > 0`**:

```ts
// mcp-server/server.ts:445-456
if (allowedRoots.length > 0) {
  const resolvedSpecPath = await canonicalPath(args.spec_path);
  const withinAllowed = await Promise.all(
    allowedRoots.map((root) => isWithinPathResolved(resolvedSpecPath, r

[Read the thread](https://github.com/HuginnIndustries/CodeCartographer/issues/76) · 2026-08-02 · closed · 0 comments

### No command to inspect merged orchestrator config

## Problem

There is no command to view the effective merged CodeCartographer configuration. Config lives in two layers that merge with workspace-overrides-global semantics:

1. `~/.codecarto/config.yaml` (user-global)
2. `.codecarto/workflow/config.yaml` (workspace-local)

The merge logic in `core/orchestrator-config.ts` (lines 79-93) gives workspace config precedence over global config. But there is no way for the user to see the merged result. When something goes wrong (wrong `library.path`, 

[Read the thread](https://github.com/HuginnIndustries/CodeCartographer/issues/68) · 2026-07-23 · closed · 0 comments

### MCP feature parity gaps: missing auto-runner, usage, dashboard, open, skill discovery, convenient publish

## Problem

The Pi extension and MCP server have significant feature parity gaps. Features that are central to the product's value proposition only exist on the Pi surface.

### Missing on MCP

| Feature | Pi command | MCP tool | Impact |
|---|---|---|---|
| End-to-end auto runner | `/codecarto-next --auto` | absent | MCP users must manually call next, validate, complete in a loop |
| Usage telemetry | `/codecarto-usage` | absent | No way to inspect token costs, tool counts, or compaction stats 

[Read the thread](https://github.com/HuginnIndustries/CodeCartographer/issues/65) · 2026-07-23 · closed · 0 comments

The remaining reports are on [the project's issue tracker](https://github.com/HuginnIndustries/CodeCartographer/issues).