Project-qualified paths: projects as mount points in the tool namespace

[phernandez]

Problem (measured, #1398 live A/B runs 3-4)

Tool outputs return project-prefixed identifiers (verified stored that way in live DBs: at-<run>-<task>/notes/redis-cache-tuning), but tool inputs demand a separate project argument plus a relative path. Agents do the natural thing — faithfully quote identifiers from prior results — and the quoted form is not accepted back. With the MCP server now fully stateless, an omitted project falls back to the default project, which in multi-project use is silently wrong: in run 4, five of seven POSIX-surface failures found the correct notes in the wrong project, and in run 3 an agent wrote a note into the wrong project and then 'verified' it there. POSIX-shaped verbs amplify the omission — shell affordances prime cwd-style thinking (nobody passes a project to ls).

Design

Make the project the first segment of the path namespace — projects as mount points — and close the round-trip:

1. Accept slug-qualified paths/identifiers on every input (<project>/<path>), resolved through the existing qualified-permalink machinery (cloud already accepts workspace-qualified permalinks; local resolves the same way — the prefix is a virtual namespace, not a filesystem path).
2. Advertise the namespace: the MCP server instructions enumerate active projects and state the path rule once; ls / (posix surface) lists projects as the root directory.
3. Refuse, don't mislead: unknown first segment errors with 'no project X — active projects: a, b, c' (one-turn recovery); ambiguous unqualified paths in multi-project use refuse rather than silently defaulting. Same principle as project add should index by default and expose a trustworthy readiness signal #1414's never-indexed refusal.
4. Collision rule needs an explicit decision: a project named notes vs a folder named notes in another project — first-segment-matches-a-project wins, documented, or a separator convention.

Why now / how we validate

The A/B harness (#1401) makes this measurable: run 4's five wrong-scope failures are the baseline; a v2 posix surface with qualified paths re-runs the identical tasks and the wrong-scope class should vanish. The eval built to compare surfaces also evaluates surface revisions.

Part of #1398 findings. Related: #1414 (readiness refusal), SPEC-47 (this is the addressing model its 'agent filesystem' framing implies).

🤖 Generated with Claude Code

https://claude.ai/code/session_014pmKq6bqCi6Zp6BTHuZjrp

[claude]

Claude finished @phernandez's task in 35s —— View job

---

Triage

Type: Enhancement — a design proposal for a new addressing model (project-qualified paths as a namespace prefix across MCP tool inputs), not a defect in existing behavior.

Priority: High — the issue cites measured harm from #1398's A/B runs: 5 of 7 POSIX-surface failures in run 4 were the "correct note, wrong project" class, and run 3 had an agent write and then falsely "verify" a note in the wrong project because an omitted project silently falls back to the default. That's silent data misplacement, not just a UX rough edge.

Component: MCP tools (input/path resolution across write_note, read_note, edit_note, move_note, delete_note, etc.), plus the POSIX-surface CLI tooling (ls /) and server instructions. Applies to both local and cloud routing — cloud already accepts workspace-qualified permalinks, so this generalizes that to the full tool surface rather than being cloud-specific.

Complexity: Complex — this is an architectural change with several open sub-decisions the issue itself flags as unresolved: the collision rule for a project named notes vs. a folder named notes (first-segment-matches-a-project vs. a separator convention), how "refuse rather than silently default" interacts with existing single-project workflows, and how deep the qualified-path resolution needs to reach through mcp/clients/, the CLI posix surface, and list_memory_projects/project routing. Validating the fix also depends on #1401's A/B harness re-run to confirm the wrong-scope failure class actually vanishes.

Duplicates: None found. Related, already-resolved issues (#810, #836, #847, #802, #799, #782) covered workspace-qualified permalinks for individual tools/routes on the cloud side. This issue proposes generalizing that pattern into a first-class addressing convention across the whole tool namespace (local + cloud), building on that prior work rather than duplicating it. Also cross-references #1414 (readiness refusal) and SPEC-47 (agent filesystem addressing model), both open.

Labeled enhancement (component: none — not cloud-exclusive). No implementation performed per triage scope.

[phernandez]

Implemented and validated by the eval that motivated it (A/B run at-b0442a6f5cd7, Sonnet 5, identical tasks/budgets to the baseline run):

	before (run 5)	after (run 6)
posix pass rate	5/12	10/12 — equal to rich
wrong-project failures	2 rich + 6 posix	zero on both surfaces

The entire wrong-scope failure class vanished; curate-connect passed on both surfaces for the first time. Posix metadata-search went 0/3 → 3/3 (brute-forced at ~2× rich's tokens — the remaining efficiency gap is structured frontmatter predicates on the posix verbs). Where surfaces overlap cleanly, posix stays 17–24% cheaper.

Remaining from this issue after the PR: server-instructions namespace advertisement, and the hosted/factory-mode refusal scope gap noted in review.

[phernandez]

The project-qualified routing and hosted/factory refusal behavior are implemented and covered on main. The remaining first-connect namespace guidance is now tracked with the v0.24 default-enable work in #1476.