​

spec_id: SPEC-016 version: “1.1” title: prism_sync_bios — general replica-sync verb for chain files status: draft authors: Donna (Claude Code) authority: ADR #13, ADR #14, ADR #16 supersedes: SPEC-016 v1.0 (2026-04-17 18:42Z) — Q1–Q9 now resolved paired_todos: #53 (impl), #54 (drift detection in prism_start) date: 2026-04-17

​

SPEC-016 v1.1 — prism_sync_bios

​

Changes from v1.0

• Q9 resolved by ADR #16 — PRISM.md is whole-file overwrite with pre-flight check (not BIOS-style unconditional overwrite, not LOCAL markers).
• Pre-flight check is now normative §6.
• force parameter added to §3 signature.
• Error payload §7 updated to carry structured local_lines on pre-flight block.
• Open questions Q1–Q8 resolved as drafted; dropped from open list.

​

1. Purpose

​

2. Files In Scope

​

3. Signature

prism_sync_bios(
    pid: str,
    files: str | list[str] = "all",      # see §4
    dry_run: bool = False,
    force: bool = False,                 # bypass PRISM.md pre-flight (ADR #16)
    ptype: str | None = None,            # overlay selector for PRISM.md
) -> {
    "synced":  [{"file", "replica_path", "from_version", "to_version", "action"}],
    "skipped": [{"file", "reason"}],
    "errors":  [{"file", "error", ...optional structured fields (e.g. local_lines)}],
    "ptype": str | None,
    "dry_run": bool,
    "force": bool,
    "prism_root": str,
    "project_dir": str,
}

​

4. Behavior

1. Resolve paths from PID metadata. Whole-call failure if PID has no project_dir.
2. BIOS files (claude/agents):
   • Read SOR → compare to replica → write atomic if different; noop otherwise.
   • No pre-flight — ADR #14 allows unconditional overwrite.
3. PRISM.md (prism):
   • Compose SOR from prism-base.md + prism-<ptype>.md.
   • If replica byte-identical to composed SOR → noop.
   • Else run pre-flight check (§6). On block, add structured error and skip.
   • If pre-flight passes OR force=True, write atomically.
4. ORG.md is always in skipped[] with reason: "org-scope, no replica".
5. Per-file errors never abort the whole call. Partial success is normal.

​

5. Whole-File Overwrite + Pre-Flight

• BIOS replicas (CLAUDE.md, AGENTS.md): no markers, no preservation. Operator edits are lost on sync. ADR #14.
• PRISM.md replica: no markers, no preservation — BUT pre-flight check refuses to overwrite if replica contains local content not present in templates or composed output. ADR #16. force=True overrides.

​

6. Pre-Flight Check (PRISM.md only, ADR #16)

• prism-base.md body (post-frontmatter)
• prism-<ptype>.md body (post-frontmatter)
• the composed output

• blank lines
• frontmatter fences (---)
• markdown headings (# …, ## …)
• blockquote lines (> …)

{
  "file": "prism",
  "error": "pre-flight blocked (ADR #16): replica contains N line(s) of local content...",
  "local_lines": ["...", "..."],
  "local_line_count": N,
  "remediation": [
    "Review each local line",
    "Move org-scope content to $PROJECT_ROOT/ORG.md",
    "Move template-worthy content into templates/",
    "Discard accepted-obsolete content",
    "Then re-run prism_sync_bios",
    "OR: pass force=True to accept the loss"
  ]
}

​

7. Version Stamping

​

7.1 CLAUDE.md / AGENTS.md

​

7.2 PRISM.md (composed)

project: <project_name>
pid: <pid>
persona: <persona>
ptype: <ptype>
methodology_version: "base@<base_v>+<ptype>@<overlay_v>"
composed_from:
  - templates/prism-base.md (v<base_v>)
  - templates/prism-<ptype>.md (v<overlay_v>)
composed_at: "<ISO-date>"
override_chain: ORG.md

​

8. Error Semantics

​

9. Concurrency

​

10. Out of Scope

• Diff/merge of user edits (ADR #14 / ADR #16 explicit).
• Initial scaffold (that’s bootstrap_project).
• SOR mutation (this verb only writes replicas).
• ORG.md lifecycle (untouched — separate concern).

​

11. Exit Criteria

1. CLAUDE.md replica matches SOR byte-for-byte.
2. AGENTS.md replica matches SOR byte-for-byte.
3. PRISM.md either matches composed output OR the attempt was pre-flight-blocked with a clean structured error OR force=True was used.
4. ORG.md is in skipped[].
5. Return payload enumerates synced, skipped, errors, plus ptype, dry_run, force, prism_root, project_dir.

• Fresh clone → all three replicas written, headers stamped.
• Modified BIOS replica → reverted on sync.
• PRISM.md with local content → pre-flight blocks with local_lines.
• PRISM.md with force=True → overwritten.
• Missing ptype overlay → PRISM.md errored, BIOS still syncs.
• Unknown alias → whole-call error.

​

12. Resolved Open Questions (from v1.0)

• Q1 ("all" scope) — resolved. "all" = claude+agents+prism; ORG.md always in skipped.
• Q2 (missing ptype overlay) — resolved (a): visible failure on the file, no silent fallback.
• Q3 (composed version tagging) — resolved (b): tuple form base@vX+<ptype>@vY plus composed_from list.
• Q4 (concurrency) — resolved: last-writer-wins, no locking. Revisit when multi-agent concurrent sync becomes a real scenario.
• Q5 (pre-overwrite backup) — resolved (a): no backup, git is the safety net. Pre-flight already protects PRISM.md; BIOS overwrite is explicit per ADR #14.
• Q6 (ORG.md lifecycle) — resolved: sync verb never touches ORG.md. Creation is bootstrap_project’s job.
• Q7 (ORG.md as SOR-override) — resolved: no sync-time ORG.md injection. ORG.md is runtime only. Revisit if TODO #48 philosophy session changes ORG.md’s power.
• Q8 (on-disk spec mirror) — not a blocker. Defer until specs/ directory convention is established for the project.
• Q9 (PRISM.md local content) — resolved by ADR #16: whole-file overwrite with pre-flight check. See §6 above.

​

13. Implementation Status

• mcp/sync_helper.py — host-side implementation (composition, atomic write, pre-flight). Not in backend because Docker container has no access to host $PRISM_ROOT or $PROJECT_DIR.
• mcp/server.py — prism_sync_bios MCP tool wrapping sync_helper.
• mcp/smoke_sync_bios.py — 65-check smoke suite, all green.
• Live dry-run against PID-PGR01 confirms pre-flight blocks correctly (replica has ~100 local lines beyond templates, mostly structural tables + §6 Communication Style; surface area for TODO #59 + broader review).

​

14. Acceptance