Skip to main content

​
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 (sibling — client/contributor scaffold boundary), SPEC-111 (shares launcher/template touch points), SPEC-021 (Ring 0 bootstrap enforcement), SPEC-090 (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.
Last modified on May 18, 2026