> ## Documentation Index
> Fetch the complete documentation index at: https://prism.ntecdev.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# SPEC-016 v1.0: prism_sync_bios — general replica-sync verb (v1.1, ADR #16 baked in)

> prism_sync_bios — general replica-sync verb (v1.1, ADR #16 baked in)

<Info>**Status:** `accepted` · **Version** `1.0` · Filed 2026-04-17</Info>

***

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

A single MCP verb that overwrites a project's replica-bearing chain files
with current SOR content. BIOS files (CLAUDE.md, AGENTS.md) overwrite
unconditionally per ADR #14. PRISM.md overwrites with a pre-flight check
per ADR #16 to prevent silent data loss.

## 2. Files In Scope

| File      | Ring | SOR                                  | Replica                      | Version header        | Composed? | Overwrite rule                |
| --------- | ---- | ------------------------------------ | ---------------------------- | --------------------- | --------- | ----------------------------- |
| CLAUDE.md | 1    | `$PRISM_ROOT/templates/CLAUDE.md`    | `<project_dir>/CLAUDE.md`    | `bios_version`        | no        | unconditional (ADR #14)       |
| AGENTS.md | 1    | `$PRISM_ROOT/templates/AGENTS.md`    | `<project_dir>/AGENTS.md`    | `bios_version`        | no        | unconditional (ADR #14)       |
| PRISM.md  | 2    | `prism-base.md` + `prism-<ptype>.md` | `<project_dir>/PRISM.md`     | `methodology_version` | yes       | pre-flight gated (ADR #16)    |
| ORG.md    | 2.5  | `$PROJECT_ROOT/ORG.md`               | (none — SOR-only, org-scope) | n/a                   | n/a       | never synced (always skipped) |

## 3. Signature

```python theme={null}
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,
}
```

`files` aliases: `"all"`, `"claude"`, `"agents"`, `"prism"`, `"org"`.
`"all"` expands to `["claude", "agents", "prism"]`. ORG.md is always in
`skipped[]`. Unknown aliases → whole-call error, no partial sync.

## 4. Behavior

For each requested file:

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)

The check compares the replica's content against the union of:

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

Any non-trivial line in the replica that is NOT present in that union is
flagged as "local content." Trivial lines skipped from the check:

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

If any local lines remain, sync refuses and returns an error payload:

```json theme={null}
{
  "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"
  ]
}
```

`force=True` bypasses the check and overwrites. The operator accepts the
loss of flagged content.

## 7. Version Stamping

### 7.1 CLAUDE.md / AGENTS.md

Inherit `bios_version` from SOR verbatim via HTML-comment frontmatter.

### 7.2 PRISM.md (composed)

```yaml theme={null}
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

| Scenario                               | Outcome                                                                     |
| -------------------------------------- | --------------------------------------------------------------------------- |
| PID missing `project_dir`              | Whole-call failure                                                          |
| SOR template missing                   | That file → `errors[]`, others still sync                                   |
| Ptype overlay missing                  | That file → `errors[]`, reason "ptype overlay not found"                    |
| Replica unwritable                     | That file → `errors[]`                                                      |
| Unknown `files` alias                  | Whole-call failure, structured error                                        |
| Replica missing pre-sync               | Not an error — fresh install, write with from\_version=null                 |
| Replica byte-identical to SOR/composed | `synced[]` with `action: "noop"`, no disk write                             |
| PRISM.md pre-flight block              | `errors[]` with `local_lines`/`remediation`; no write; force=True overrides |

## 9. Concurrency

Not addressed. Last-writer-wins. Simultaneous sync on the same project is not
supported. Document and move on.

## 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

Sync succeeds when:

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`.

Smoke tests (live under `mcp/smoke_sync_bios.py`, 65 checks as of v1.1 impl):

* 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

Ready for Lola review. No open questions blocking impl. Implementation
already landed per TODO #53. Pre-flight tested on synthetic fixtures
(65 checks) and live project (pre-flight correctly blocks).