bootstrap

## IMO — Ingress / Middle / Egress **Ingress (Trigger):** Developer runs /bootstrap in a repo root. Optionally passes `--tier=garage|car|sub-hub` to declare tier explicitly. **Middle (Processing):** - Detect or accept tier declaration - Read existing repo file inventory - Compare against required skeleton for detected tier - Stamp missing files only from imo-creator templates - Confirm sovereign ID present or prompt for declaration - Produce bootstrap report **Egress (Output):** Missing doctrine files stamped at repo root and /ADRs/. Bootstrap report listing what was created, what already existed, and sovereign ID status. **Go/No-Go Gate:** Do not close until bootstrap report confirms zero missing required files for the declared tier and sovereign ID is declared. --- ## Constants — What Is Fixed About Every Bootstrap Run 1. Bootstrap is always non-destructive. Existing files are never overwritten. 2. Tier determines the required file skeleton. Tier is always declared — never inferred silently. 3. Sovereign ID must be declared before bootstrap closes. No exceptions. 4. All stamped files come from imo-creator templates. No hand-written files during bootstrap. 5. Bootstrap produces a report. A run with no report is not complete. 6. ADR-000-template.md is always stamped regardless of tier. 7. Doctrine flows DOWN. Bootstrap reads from imo-creator. It never modifies imo-creator. 8. If imo-creator path cannot be resolved, bootstrap halts immediately — it does not guess. --- ## Variables — What Changes Per Invocation | Variable | What It Is | Who Sets It | |----------|-----------|-------------| | `target_repo_path` | Absolute path to repo being bootstrapped | Detected from working directory | | `tier` | Garage / Car / Sub-Hub | Developer declaration or Phase 1 detection | | `sovereign_id` | Unique ID connecting this repo to its parent hub | Developer declaration | | `imo_creator_path` | Path to imo-creator templates | Resolved from FLEET_REGISTRY or declared | | `missing_files` | List of required files not yet present | Computed in Phase 2 | --- ## Hub-and-Spoke Configuration The bootstrap process is a wheel. Hub is the stamped repo. Each spoke is a phase. | Spoke | Input | Output | Interface to Hub | |-------|-------|--------|-----------------| | Detect | Repo path + optional --tier flag | Confirmed tier | Go/No-Go: tier is unambiguous | | Inventory | Repo file list | Missing file list per tier | Go/No-Go: delta computed, no unknowns | | Resolve | imo-creator path | Template file paths confirmed | Go/No-Go: all templates found | | Stamp | Missing file list + templates | Files written to repo | Go/No-Go: all missing files now present | | Sovereign | Repo state | Sovereign ID declared in CLAUDE.md | Go/No-Go: sovereign ID present | | Report | Completed repo state | Bootstrap report | Final output — task complete | **Hub rule:** Each spoke completes and returns to hub. Spokes do not call other spokes. --- ## Rules — What This Skill Never Does - Never overwrite an existing file. If it exists, skip it and note it in the report. - Never stamp files without a confirmed tier. Tier ambiguity halts bootstrap. - Never generate sovereign ID automatically. Developer declares it — bootstrap confirms it. - Never modify imo-creator templates. Read only. Doctrine flows down, never up. - Never close without a bootstrap report. Silent completion is not completion. - Never stamp a sub-hub without confirming its parent Car repo is already bootstrapped. - Never put tool names or repo-specific values in the stamped CLAUDE.md Constants block. --- ## Tier Skeletons — Required Files Per Tier ### GARAGE (imo-creator itself) ``` CLAUDE.md CONSTITUTION.md README.md FLEET_REGISTRY.yaml ADR_INDEX.md REPO_HOUSEKEEPING.md /templates/ (already exists) /ADRs/ADR-000-template.md ``` ### CAR REPO (e.g. UT, barton-outreach-core) ``` CLAUDE.md (9-section skeleton — defer to Garage) README.md (repo-specific orientation) SYSTEM_MAP.md (hub/spoke/data flow map) /ADRs/ADR-000-template.md /docs/OSAM.md (routing contract) /docs/PRD.md (what this repo does + why) ``` ### SUB-HUB (e.g. Fetcher, Parser Registry) ``` CLAUDE.md (thin — identity + pointer to Car CLAUDE.md) README.md (sub-hub purpose, spokes, triggers) /docs/PRD.md (required — if you can't write it, don't build it) /docs/OSAM.md (routing contract) /ADRs/ADR-000-template.md ``` --- ## Workflow ### Phase 1 — Detect Tier (Spoke 1) **Constants for this phase:** - Tier must be one of exactly three values: Garage / Car / Sub-Hub. - If --tier flag is passed, accept it. If not, ask — never infer silently. - A repo that looks like a Car but has no FLEET_REGISTRY.yaml is a Car, not a Garage. **Variables for this phase:** - Whether --tier flag was passed. - Repo contents used for detection hints. **Execute:** 1. Check for --tier flag. If present, accept and proceed. 2. If no flag: scan repo root for FLEET_REGISTRY.yaml (Garage signal), CONSTITUTION.md (Garage signal), or neither (Car/Sub-Hub). 3. If ambiguous between Car and Sub-Hub, ask: "Does this repo have its own hub processing logic, or is it a domain within a Car repo?" 4. Confirm tier with developer before proceeding. **Go/No-Go:** Tier is declared and confirmed. If not confirmed, halt and ask. --- ### Phase 2 — Inventory (Spoke 2) **Constants for this phase:** - Required file list is determined by tier skeleton above. It is a Constant per tier. - A file that exists but is empty counts as present — bootstrap does not validate content. - Only root-level and /docs/ and /ADRs/ files are in scope. Bootstrap does not recurse deeper. **Variables for this phase:** - Which specific files are missing in this repo. **Execute:** 1. Load required file list for confirmed tier. 2. Check repo root, /docs/, and /ADRs/ for each required file. 3. Build two lists: PRESENT (skip) and MISSING (stamp). 4. Display both lists to developer before proceeding. **Go/No-Go:** Missing file list is complete and confirmed. Developer has seen it. --- ### Phase 3 — Resolve Templates (Spoke 3) **Constants for this phase:** - All templates come from imo-creator. No other source. - If imo-creator path cannot be resolved, halt immediately. - Template paths are fixed per the CLAUDE.md locked file registry. **Variables for this phase:** - Actual resolved path to imo-creator on this machine. **Execute:** 1. Check for imo-creator path in FLEET_REGISTRY.yaml or ask developer. 2. Verify each required template exists at resolved path. 3. Map: missing file → source template path. **Go/No-Go:** Every missing file has a confirmed source template. If any template is missing from imo-creator, halt and report — do not improvise. --- ### Phase 4 — Stamp (Spoke 4) **Constants for this phase:** - Stamp = copy template to target path. No modification of template content except replacing [REPO_NAME], [TIER], [DATE], [SOVEREIGN_ID] placeholders. - Never overwrite. If file appeared between Phase 2 and Phase 4, skip it. - Placeholder replacement is the only permitted modification during stamp. **Variables for this phase:** - The specific placeholder values for this repo. **Execute:** 1. For each file in MISSING list: - Copy from source template to target path. - Replace placeholders: [REPO_NAME], [TIER], [DATE], [SOVEREIGN_ID]. - Confirm file written. 2. Log each stamped file: path + source template. **Go/No-Go:** Every file in MISSING list now exists in repo. Zero failures. --- ### Phase 5 — Sovereign ID (Spoke 5) **Constants for this phase:** - Sovereign ID is always declared by the developer. Never generated. - Sovereign ID must appear in CLAUDE.md Section 01 (Repo Identity). - Format follows HEIR naming convention: H.E.I.R notation per imo-creator doctrine. **Variables for this phase:** - The actual sovereign ID value for this repo. **Execute:** 1. Check CLAUDE.md Section 01 for sovereign ID field. 2. If present: confirm with developer and proceed. 3. If absent: ask developer to declare it now. Insert into CLAUDE.md Section 01. **Go/No-Go:** Sovereign ID is declared and present in CLAUDE.md. If not, do not close. --- ### Phase 6 — Report (Spoke 6) **Constants for this phase:** - Report always has four sections: Tier, Files Stamped, Files Skipped, Sovereign ID. - A bootstrap with zero files stamped is still a valid run — it means the repo was already compliant. Report it as such. **Execute:** Produce bootstrap report in this format: ``` BOOTSTRAP REPORT ──────────────── Repo: [repo name] Tier: [Garage / Car / Sub-Hub] Date: [date] Sovereign ID: [value] FILES STAMPED (created) → [file path] (from [template source]) → ... FILES SKIPPED (already present) → [file path] → ... STATUS: COMPLETE — repo is doctrine-compliant for [tier] tier. ``` **Go/No-Go:** Report produced and shown to developer. Task complete. --- ## Phase Failure Handling **IMO of a Phase Failure:** - **Ingress:** Phase produces unexpected result not matching defined output. - **Middle:** Log three fields — (1) which phase failed, (2) what was attempted, (3) what was returned. Do not guess. Do not retry silently. - **Egress:** Escalate to developer with three-field log. Ask for direction. **OTHER path:** If failure cannot be classified, log to error with `phase_failed`, `attempted_action`, `raw_output`. Do not resolve without developer input. --- ## CTB Backbone Mapping Bootstrap output maps to repo structure: - CLAUDE.md → constitutional layer (CANONICAL — do not modify after stamp without ADR) - SYSTEM_MAP.md → architectural declaration - /docs/PRD.md → transformation proof (CONST → VAR) - /docs/OSAM.md → routing contract - /ADRs/ → decision log Bootstrap IS the Day 0 structural proof. A repo that has passed bootstrap has satisfied the structural instantiation requirement per CONSTITUTION.md. --- ## Reference Files | File | Contains | Load When | |------|----------|-----------| | `references/tier-skeletons.md` | Full required file list per tier with template mappings | Phase 2 — building missing file list | | `references/placeholder-map.md` | All valid placeholders and replacement rules | Phase 4 — stamping files | --- ## Observability - Bootstrap report IS the telemetry. Every run produces one. - Failed phases log three-field entries before escalating. - A bootstrap run with no report = audit violation. Treat as Phase 6 failure.