> ## 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-113: Bootstrap Path Resolution and Scaffold Completeness

> Ring 1 BIOS reads Ring 2 methodology at runtime from immutable $PRISM_ROOT/templates/; scaffold/adopt writes only thin edge artifacts to $PROJECT_ROOT; offline fallback gated on successful template resolution

# SPEC-113 v0.3 — Bootstrap Path Resolution and Scaffold Completeness

**Status:** accepted (Frank ratified 2026-05-13 via Cherry `bf82c5b2` correction → Donna TaskAssigned `b1cf46c8`).
**Owner / Author:** Texi (architecture), Donna (PO / Plan #18 integration).
**Implementation lanes:** Cherry (Windows launcher `coder.ps1`), Lafonda (Mac/POSIX launcher + install/scaffold), mcp-node lifecycle (`resolvePid`, architecture review by Texi), Donna + Texi (legacy DFW/global constitution cleanup).
**Related:** [SPEC-112 v0.3](/specs/spec-112-v0-3-client-and-contributor-scaffold-boundary) (sibling — client/contributor scaffold boundary), SPEC-111 (shares launcher/template touch points), [SPEC-021](/specs/spec-021-v1-0-session-bootstrap-enforcement-ring-0) (Ring 0 bootstrap enforcement), [SPEC-090](/specs/spec-090-v0-1-prism-adopt-existing-repo) (`prism_adopt`).

## Origin

Donna TaskAssigned `b1cf46c8` from Cherry signal `7506efc0`, Frank-directed, 2026-05-13. v0.3 corrects the P0 architectural miss caught by Frank via Cherry signal `bf82c5b2`: `PRISM.md` is not a normal project replica. Prism methodology lives immutably under `$PRISM_ROOT/templates/` and agents read it at runtime. Scaffold/adopt writes only thin edge artifacts into `$PROJECT_ROOT`.

## Canonical Terms

`$PRISM_ROOT` is the Prism install directory. It is a single instance per host, immutable to non-contributors, and owns methodology at `$PRISM_ROOT/templates/`: `prism-base.md`, ptype overlays, and the content that historically composed `PRISM.md`. Agents read methodology from `$PRISM_ROOT/templates/` at runtime; it is never copied.

`$PROJECT_ROOT` is the customer project directory. It is mutable customer space. It gets only the thin edge: `CLAUDE.md` and/or `AGENTS.md` Ring 1 replicas, `.prism/`, and `.agent/` dotfile dirs when contributor mode is explicitly selected. It gets no root `PRISM.md`.

## Corrected RCA

DPA-Crawl had Ring 1 bootstrap artifacts but no valid runtime path to Ring 2 Prism methodology at `$PRISM_ROOT/templates/`. Codex fell back to DFW global constitution, eagerly read `context/_ACTIVE_CONTEXT.md` and `plans/_TODO.md` before `prism_start`, improvised `prism_start(name='Codex')`, and needed trial-and-error before succeeding.

The fix is **not** to copy `PRISM.md` into every project. The fix is:

* Ring 1 BIOS points agents to `$PRISM_ROOT/templates/prism-base.md` plus ptype/profile overlay.
* Scaffold/adopt creates `$PROJECT_ROOT/.prism/` metadata and Ring 1 replicas only, never `$PROJECT_ROOT/PRISM.md` except for the Prism repo special case where `$PROJECT_ROOT == $PRISM_ROOT`.
* Launch/lifecycle code resolves project identity from explicit args and Prism env without silently binding through conflicts.

## Frank's Model

Prism installs once at `$PRISM_ROOT`. Methodology files are immutable and owned by Prism at `$PRISM_ROOT/templates/`. Agents read them at runtime. `$PROJECT_ROOT` contains project-owned dotfile directories such as `.prism/` and, in contributor mode, `.agent/`. Customers must not receive mutable copies of Prism's Ring 2 methodology.

Ring model:

* Prism owns top rings and template methodology under `$PRISM_ROOT`.
* Customer/project directories may add lower overlays/state through `$PROJECT_ROOT` dotfiles and backend records.
* Copying `PRISM.md` into every customer project would let customers delete/modify methodology and would make Prism upgrades touch every customer repo, violating install-root ownership.

## Special Case: Prism Repo Itself

On a contributor machine working on Prism itself, `$PRISM_ROOT` and `$PROJECT_ROOT` resolve to the same path. That is why `PRISM.md` exists at the Prism repo root: the repo is both product/install root and customer project for Prism development.

This is a single-machine special case, not the general rule. Customer/client projects do not get root `PRISM.md`.

## Scope

One cross-surface spec covers:

1. BIOS templates: `$PRISM_ROOT/templates/AGENTS.md` and `$PRISM_ROOT/templates/CLAUDE.md`.
2. Windows launcher: `bin/coder.ps1`.
3. Mac/POSIX launcher: `bin/coder.sh`.
4. Scaffold/adopt dotfile completeness: `prism_scaffold`, `prism_create`, `prism_adopt`, sync/repair helpers.
5. mcp-node lifecycle PID resolution: `mcp-node/src/verbs/lifecycle.ts` `resolvePid`.
6. Legacy DFW/global fallback constitution behavior for `_ACTIVE_CONTEXT.md` / `_TODO.md` reads.
7. Template text cleanup: `$PRISM_ROOT/templates/prism-application.md` and BIOS version/sync wording that still describes project `PRISM.md` replicas.

## Contract

### 1. BIOS reads runtime templates, not project PRISM.md

Ring 1 BIOS boot step 1 changes from `./PRISM.md` to runtime Ring 2 template resolution:

1. Locate and validate `$PRISM_ROOT`.
2. Read `$PRISM_ROOT/templates/prism-base.md`.
3. Resolve selected ptype/profile overlay from `$PROJECT_ROOT/.prism/` and/or backend project metadata.
4. Read `$PRISM_ROOT/templates/<overlay>.md`.
5. If `$PRISM_ROOT` is invalid, fail as `prism_root_misconfigured`.
6. If base or overlay is missing, fail as `template_not_found_at_prism_root`.
7. If metadata cannot choose a valid overlay, fail as `template_resolution_failed`.

BIOS may mention that the Prism repo itself has a root `PRISM.md` special case, but customer project bootstraps must not depend on `$PROJECT_ROOT/PRISM.md`.

### 2. Offline fallback must be gated

BIOS offline fallback must not read `context/_ACTIVE_CONTEXT.md` or `plans/_TODO.md` until runtime Ring 2 template resolution succeeds and the project is identified as Prism-managed.

If template resolution fails:

* Do not read `_ACTIVE_CONTEXT.md` or `_TODO.md`.
* Do not import DFW/global project hygiene as Ring 2 Prism methodology.
* Surface `template_not_found_at_prism_root`, `prism_root_misconfigured`, or `template_resolution_failed` and request/trigger install/scaffold repair.

### 3. Launchers resolve project root from Prism env first

`coder.ps1` and `coder.sh` must prefer explicit Prism env over relative walks:

1. explicit `-project`
2. `PRISM_PROJECT_DIR` containing Prism project metadata sentinel
3. `$PROJECT_ROOT/$PRISM_PROJECT_NAME` containing Prism project metadata sentinel
4. cwd walk for Prism project metadata sentinel
5. fail loud with remediation naming `prism_adopt` / scaffold repair

The sentinel set is no longer `PRISM.md`. It is:

* `$PROJECT_ROOT/.prism/` project metadata directory,
* `$PROJECT_ROOT/AGENTS.md` or `$PROJECT_ROOT/CLAUDE.md` Ring 1 replica when applicable,
* and backend project metadata where available.

Cherry owns Windows implementation. Mac/POSIX must maintain parity with `coder.ps1`.

### 4. Scaffold/adopt creates dotfiles and Ring 1 replicas, not PRISM.md

For any Prism-managed project, scaffold/adopt writes into `$PROJECT_ROOT` only:

* `.prism/` dotfile directory with project binding, ptype/profile, selected overlay reference, and repair/sync metadata.
* `AGENTS.md` and/or `CLAUDE.md` Ring 1 replicas as required by supported editor surfaces.
* `.agent/` only in contributor mode.

Scaffold/adopt must not create `$PROJECT_ROOT/PRISM.md` in customer/client projects. It must not compose and write `PRISM.md` to project root. Runtime composition is read-time, from `$PRISM_ROOT/templates/`.

### 5. Runtime methodology composition

`PRISM.md` has no standalone `$PRISM_ROOT/templates/PRISM.md` source file. Runtime methodology is composed conceptually by reading:

* `$PRISM_ROOT/templates/prism-base.md`, and
* selected ptype/profile overlay under `$PRISM_ROOT/templates/`.

Selection contract:

* `ptype` and `scaffold_profile` live in backend project metadata and/or `$PROJECT_ROOT/.prism/` metadata.
* Client/default projects must resolve a client-safe overlay.
* Contributor/Prism-development projects may resolve developer/application overlays.
* If `$PRISM_ROOT` is invalid, fail as `prism_root_misconfigured`.
* If the base or selected overlay is absent, fail as `template_not_found_at_prism_root`.
* If no valid overlay can be selected, fail as `template_resolution_failed` rather than selecting `prism-application.md` by default.

### 6. Lifecycle PID resolution uses launcher-injected project name as defense in depth

`resolvePid` fallback order:

1. explicit `pid`
2. explicit `name`
3. `PRISM_PROJECT_NAME` exact case-insensitive lookup
4. `PRISM_PROJECT_DIR` exact `project_dir` lookup where available
5. structured failure naming expected inputs

If explicit args conflict with env, return `env_project_mismatch` / `name_arg_mismatch_env_project`; never silently bind to env against an explicit conflicting arg.

### 7. Legacy DFW/global constitution must not contaminate Prism bootstrap

Legacy DFW context reads are allowed only for non-Prism projects after Prism-managed detection fails cleanly. If a project has `$PROJECT_ROOT/.prism/`, `$PROJECT_ROOT/AGENTS.md`, or `$PROJECT_ROOT/CLAUDE.md` but runtime template resolution fails, it is a Prism repair fault, not a DFW project.

### 8. Template cleanup required

Remove or rewrite stale text that encodes the old replica model:

* `$PRISM_ROOT/templates/prism-application.md` A6 paragraph saying PRISM.md is composed and written to project root.
* `$PRISM_ROOT/templates/CLAUDE.md` version-sync language that treats PRISM.md as a normal project replica.
* Any AGENTS/CLAUDE boot wording that directs agents to `./PRISM.md` as the project methodology source.

## Failure Modes

* `template_not_found_at_prism_root`: `$PRISM_ROOT/templates/prism-base.md` or the selected overlay is absent.
* `prism_root_misconfigured`: runtime cannot locate or trust `$PRISM_ROOT` as the Prism install directory.
* `template_resolution_failed`: runtime cannot resolve base + overlay from `$PROJECT_ROOT/.prism/` and/or backend project metadata.
* `misprofiled_template_overlay`: client/customer project resolves contributor/product-specific Ring 2 methodology.
* `out_of_order_offline_context_read`: agent reads `_ACTIVE_CONTEXT.md` / `_TODO.md` before runtime Ring 2 template resolution succeeds.
* `identity_as_project_name`: model supplies agent identity or surface name as project name.
* `env_project_mismatch`: explicit name/pid conflicts with launcher-injected env.
* `partial_scaffold_dotfiles`: scaffold/adopt writes incomplete `$PROJECT_ROOT/.prism`/Ring 1/dotfile metadata.

Removed failure mode:

* `missing_prism_replica` is invalid under the corrected architecture because `PRISM.md` is not a project replica.

## Acceptance Criteria

1. Default/client `prism_create` and `prism_adopt` produce no `$PROJECT_ROOT/PRISM.md`.
2. Default/client scaffold creates `$PROJECT_ROOT/.prism/` metadata and Ring 1 editor bootstrap replicas as needed.
3. Contributor scaffold creates `$PROJECT_ROOT/.agent/` only when explicitly selected.
4. `coder.ps1` and `coder.sh` use `.prism`/Ring 1/project metadata sentinels, not `PRISM.md`, to find project roots.
5. Runtime bootstrap reads `$PRISM_ROOT/templates/prism-base.md` and selected overlay.
6. Missing template/overlay fails as `template_not_found_at_prism_root`, `prism_root_misconfigured`, or `template_resolution_failed`.
7. Client/default project never silently resolves to Prism-product developer overlay.
8. `resolvePid` uses env fallback when args are omitted and returns structured mismatch when explicit args conflict.
9. BIOS template tests assert no `./PRISM.md` boot dependency remains.
10. `$PRISM_ROOT/templates/prism-application.md` no longer says scaffold writes `PRISM.md` to project root.
11. The Prism repo root `PRISM.md` remains allowed as the documented `$PROJECT_ROOT == $PRISM_ROOT` special case.

## Ownership

* Architecture: Texi.
* PO / Plan #18 integration: Donna.
* Windows launcher: Cherry.
* Mac/POSIX launcher and install/scaffold lane: Lafonda.
* MCP-node lifecycle: backend/shim implementation lane, architecture review by Texi.
* Legacy DFW/global constitution cleanup: Donna/Texi with operator confirmation if outside Prism governance.

## Interactions

* SPEC-112: client/contributor profile selection drives runtime template resolution and `$PROJECT_ROOT` artifact boundary.
* SPEC-111: shares launcher/template touch points; coordinate edits.
* SPEC-021: reinforces Ring 0 bootstrap enforcement.
* SPEC-090: `prism_adopt` creates/repairs `.prism` and Ring 1 replicas, not `PRISM.md`.