SPEC-017 v1.0: prism_clone — cross-machine clone + register + sync (host-side MCP verb)

​

SPEC-017 — prism_clone

dir_exists($PROJECT_ROOT/<name>)            AND
(optional) git_repo($PROJECT_ROOT/<name>)    AND
prism_pid_exists(<name>, project_dir)        AND
mcp_allowlist_contains($PROJECT_ROOT/<name>) AND
bios_synced(<pid>)

​

Runs host-side (not in the backend)

• git clone executes on the host (same process as the MCP server).
• Legacy-project detection probes the host filesystem.
• Prism-side registration (bootstrap_project, register_project_paths, prism_sync_bios) is delegated to existing verbs.

​

Signature

prism_clone(
    name: str,
    github_repo: str | None = None,
    project_dir: str | None = None,   # defaults to $PROJECT_ROOT/<name>
    ptype: str = "application",
    branch: str | None = None,         # optional checkout after clone
    persona: str = "Lola",
) -> dict

​

Mode detection

​

Terminal steps (all modes, unconditional on success)

1. register_project_paths(project_dir) — idempotent allowlist injection.
2. prism_sync_bios(pid, files="all", dry_run=False, force=False) — best-effort; if PRISM.md pre-flight blocks, surface in response but don’t fail the whole call.
3. Legacy-project detection — returns migration_candidate: bool + legacy_signatures: list[str].

​

Return payload

{
  "pid": "PID-XYZ01",
  "project_dir": "/abs/path",
  "mode": "clone" | "register" | "bind",
  "git_result": { ... },
  "bootstrap_result": { ... },
  "paths_result": { ... },
  "sync_result": { "synced": [...], "skipped": [...], "errors": [...] },
  "migration_candidate": false,
  "legacy_signatures": []
}

​

Legacy-project signature probes (Wave A stub — Wave B does full mapper)

• context/_ACTIVE_CONTEXT.md
• plans/_TODO.md
• plans/_DELTAS.md
• AGENTS.md containing the regex r"^# AGENTS\.md\s*$" as a legacy AGENTS.md header signature
• A sibling Obsidian vault at <project_dir>/../<name>Vault/ or <project_dir>/.obsidian/

​

Error shaping

• DirExistsNotGit: dir present, no .git. Agent should escalate to the user.
• NothingToClone: dir absent and github_repo absent.
• GitCloneFailed: propagate git’s stderr in the error message.
• BackendError: wrap any HTTPError from the backend with the call that failed.

​

Smoke battery (Wave A exit gate)

1. fresh_clone — target dir absent, github_repo given, small repo. Expect mode=clone, PID created, paths registered, bios synced, migration_candidate=False.
2. register_existing — target dir is a Prism project already on disk. Expect mode=register, PID resolved (or created via bootstrap register), allowlist updated, bios re-synced.
3. bind_non_prism — target dir is a git repo with no Prism structure. Expect mode=bind, PID minted, scaffold manifest written, bios synced.
4. error_exists_non_git — target dir exists, no .git. Expect DirExistsNotGit. No side effects.

​

Exit gate for Wave A

​

Frank-decisions NOT silently resolved

• FD-1 (Wave B): write path stays behind explicit user prompt, not auto-executed. (Affects Wave B migration integration — not Wave A.)
• FD-2/FD-3: n/a for Wave A.

​

Dependencies

• Existing: bootstrap_project, register_project_paths, prism_sync_bios (all shipped).
• New: host-side git subprocess, legacy-project detector stub, mode-detection branching.
• Not new: no backend schema change, no new route, no alembic migration for Wave A.