project-iris 0.0.6

package/dist/workflows/bolt-plan.js

@@ -0,0 +1,192 @@
+import { randomUUID } from "crypto";
+import inquirer from "inquirer";
+import kleur from "kleur";
+import fs from "fs";
+import path from "path";
+import { WorkflowStage } from "../bridge/types.js";
+import { appendEvent, saveRun } from "../iris/run-state.js";
+/**
+ * Execute Bolt Plan stage
+ * Steps:
+ * 1. Generate bolt plan and individual bolt files
+ * 2. Parse bolt list from plan
+ * 3. Gate: Approve bolt plan? (y/N)
+ */
+export async function executeBoltPlan(runState, connector, options) {
+    console.log(kleur.bold("Bolt Plan Stage"));
+    console.log(kleur.dim("Generating implementation plan and bolts\n"));
+    // Step 1: Generate bolt plan
+    console.log(kleur.cyan("→ Generating bolt plan..."));
+    const planTaskId = randomUUID();
+    const planPacket = {
+        taskId: planTaskId,
+        intent: runState.intent,
+        stage: WorkflowStage.BOLT_PLAN,
+        agent: "iris-master-agent",
+        instructions: `Based on the intent artifacts, create a bolt plan and individual bolt files.
+
+Intent: ${runState.intent}
+
+Review the intent artifacts in memory-bank/intents/ to understand requirements.
+
+Create:
+1. memory-bank/operations/bolts/plan.md - Overall implementation plan listing all bolts
+2. memory-bank/operations/bolts/<bolt-id>.md - One file per bolt
+
+Each bolt should be a focused, testable unit of work (e.g., "setup-database", "create-api-endpoint", "build-ui-component").
+
+Bolt file format:
+# Bolt: <Name>
+
+## Purpose
+Brief description of what this bolt accomplishes
+
+## Dependencies
+List any other bolts this depends on
+
+## Tasks
+- [ ] Task 1
+- [ ] Task 2
+
+## Acceptance Criteria
+- Criterion 1
+- Criterion 2
+
+In plan.md, list all bolts in dependency order.`,
+        inputs: runState.artifacts,
+        expectedOutputs: [
+            "memory-bank/operations/bolts/plan.md"
+        ],
+        metadata: { step: "generate_bolt_plan" }
+    };
+    appendEvent(runState.runId, {
+        stage: WorkflowStage.BOLT_PLAN,
+        action: "Requesting bolt plan generation",
+        taskId: planTaskId
+    });
+    if (options.noBridge) {
+        console.log(kleur.yellow("  Bridge disabled. Task packet written to:"));
+        console.log(kleur.dim(`  .iris/bridge/inbox/${planTaskId}.json`));
+        console.log(kleur.dim("  Manually create result in .iris/bridge/outbox/\n"));
+        return;
+    }
+    try {
+        await connector.sendTask(planPacket);
+        console.log(kleur.dim(`  Task sent: ${planTaskId}`));
+        console.log(kleur.dim("  Waiting for IDE agent to create bolt plan...\n"));
+        const planResult = await connector.waitResult(planTaskId, {
+            timeoutMs: 600000 // 10 minutes
+        });
+        if (planResult.status === "error") {
+            throw new Error(planResult.error || "Failed to generate bolt plan");
+        }
+        console.log(kleur.green("✓ Bolt plan created"));
+        if (planResult.filesChanged) {
+            planResult.filesChanged.forEach(file => {
+                console.log(kleur.dim(`  - ${file}`));
+                runState.artifacts.push(file);
+            });
+        }
+        console.log("");
+        appendEvent(runState.runId, {
+            stage: WorkflowStage.BOLT_PLAN,
+            action: "Bolt plan generated",
+            outputs: planResult.filesChanged,
+            resultStatus: "ok"
+        });
+        // Step 2: Parse bolt list from plan
+        const bolts = await parseBoltsFromPlan();
+        if (bolts.length === 0) {
+            console.log(kleur.yellow("⚠ No bolts found in plan. Creating default bolt.\n"));
+            bolts.push({
+                id: "implementation",
+                status: "pending"
+            });
+        }
+        runState.bolts = bolts;
+        console.log(kleur.cyan(`Found ${bolts.length} bolt(s):`));
+        bolts.forEach((bolt, i) => {
+            console.log(kleur.dim(`  ${i + 1}. ${bolt.id}`));
+        });
+        console.log("");
+        // Step 3: Gate - Approve bolt plan?
+        if (options.gate === "manual") {
+            console.log(kleur.bold(kleur.yellow("Gate: Bolt Plan Approval")));
+            const { approved } = await inquirer.prompt([
+                {
+                    type: "confirm",
+                    name: "approved",
+                    message: "Approve bolt plan and proceed to execution?",
+                    default: true
+                }
+            ]);
+            appendEvent(runState.runId, {
+                stage: WorkflowStage.BOLT_PLAN,
+                action: "Gate decision",
+                userGateDecision: approved ? "approved" : "rejected"
+            });
+            if (!approved) {
+                console.log(kleur.yellow("\n⚠ Bolt plan rejected. Revision loop not yet implemented."));
+                console.log(kleur.dim("For now, manually edit bolt files and re-run.\n"));
+                runState.stage = WorkflowStage.DONE;
+                return;
+            }
+            console.log(kleur.green("✓ Bolt plan approved\n"));
+        }
+        // Move to next stage
+        runState.stage = WorkflowStage.BOLT_EXECUTION;
+        runState.currentBoltIndex = 0;
+        saveRun(runState);
+    }
+    catch (error) {
+        console.error(kleur.red(`\n✗ Error: ${error.message}`));
+        appendEvent(runState.runId, {
+            stage: WorkflowStage.BOLT_PLAN,
+            action: "Stage failed",
+            message: error.message,
+            resultStatus: "error"
+        });
+        throw error;
+    }
+}
+/**
+ * Parse bolts from plan.md
+ * Looks for bolt file references or creates default list
+ */
+async function parseBoltsFromPlan() {
+    const planPath = path.join(process.cwd(), "memory-bank/operations/bolts/plan.md");
+    if (!fs.existsSync(planPath)) {
+        return [];
+    }
+    const content = fs.readFileSync(planPath, "utf8");
+    const bolts = [];
+    // Look for bolt file references (e.g., "- bolt-name.md" or "1. bolt-name")
+    const boltPattern = /(?:^|\n)(?:\d+\.|[-*])\s+([a-z0-9-]+)(?:\.md)?/gi;
+    let match;
+    while ((match = boltPattern.exec(content)) !== null) {
+        const boltId = match[1].replace(/\.md$/, "");
+        if (!bolts.find(b => b.id === boltId)) {
+            bolts.push({
+                id: boltId,
+                status: "pending"
+            });
+        }
+    }
+    // Also check for actual bolt files in the directory
+    const boltsDir = path.join(process.cwd(), "memory-bank/operations/bolts");
+    if (fs.existsSync(boltsDir)) {
+        const files = fs.readdirSync(boltsDir);
+        files.forEach(file => {
+            if (file.endsWith(".md") && file !== "plan.md") {
+                const boltId = file.replace(/\.md$/, "");
+                if (!bolts.find(b => b.id === boltId)) {
+                    bolts.push({
+                        id: boltId,
+                        status: "pending"
+                    });
+                }
+            }
+        });
+    }
+    return bolts;
+}

package/dist/workflows/intent-inception.js

@@ -0,0 +1,188 @@
+import { randomUUID } from "crypto";
+import inquirer from "inquirer";
+import kleur from "kleur";
+import { WorkflowStage } from "../bridge/types.js";
+import { appendEvent, saveRun } from "../iris/run-state.js";
+/**
+ * Execute Intent Inception stage
+ * Steps:
+ * 1. Generate clarifying questions (3-8)
+ * 2. Prompt user for answers
+ * 3. Generate requirements/system-context/stories/units
+ * 4. Gate: Approve intent? (y/N)
+ */
+export async function executeIntentInception(runState, connector, options) {
+    console.log(kleur.bold("Intent Inception Stage"));
+    console.log(kleur.dim("Clarifying requirements and creating intent artifacts\n"));
+    // Step 1: Generate clarifying questions
+    console.log(kleur.cyan("→ Generating clarifying questions..."));
+    const questionsTaskId = randomUUID();
+    const questionsPacket = {
+        taskId: questionsTaskId,
+        intent: runState.intent,
+        stage: WorkflowStage.INTENT_INCEPTION,
+        agent: "iris-inception-agent",
+        instructions: `Based on the intent "${runState.intent}", generate 3-8 clarifying questions to better understand:
+- The problem being solved
+- Success criteria
+- Scope and constraints
+- Technical requirements
+- User expectations
+
+Return the questions as a JSON array of strings in the result message.`,
+        inputs: [],
+        expectedOutputs: [],
+        metadata: { step: "clarifying_questions" }
+    };
+    appendEvent(runState.runId, {
+        stage: WorkflowStage.INTENT_INCEPTION,
+        action: "Requesting clarifying questions",
+        taskId: questionsTaskId
+    });
+    if (options.noBridge) {
+        console.log(kleur.yellow("  Bridge disabled. Task packet written to:"));
+        console.log(kleur.dim(`  .iris/bridge/inbox/${questionsTaskId}.json`));
+        console.log(kleur.dim("  Manually create result in .iris/bridge/outbox/\n"));
+        return;
+    }
+    try {
+        await connector.sendTask(questionsPacket);
+        console.log(kleur.dim(`  Task sent: ${questionsTaskId}`));
+        console.log(kleur.dim("  Waiting for IDE agent response...\n"));
+        const questionsResult = await connector.waitResult(questionsTaskId, {
+            timeoutMs: 300000 // 5 minutes
+        });
+        if (questionsResult.status === "error") {
+            throw new Error(questionsResult.error || "Failed to generate questions");
+        }
+        // Parse questions from result
+        let questions;
+        try {
+            questions = JSON.parse(questionsResult.message);
+        }
+        catch {
+            // Fallback: treat message as newline-separated questions
+            questions = questionsResult.message.split("\n").filter(q => q.trim());
+        }
+        console.log(kleur.green("✓ Questions received\n"));
+        // Step 2: Prompt user for answers
+        console.log(kleur.bold("Clarifying Questions:"));
+        const answers = {};
+        for (let i = 0; i < questions.length; i++) {
+            const { answer } = await inquirer.prompt([
+                {
+                    type: "input",
+                    name: "answer",
+                    message: `${i + 1}. ${questions[i]}`
+                }
+            ]);
+            answers[questions[i]] = answer;
+        }
+        console.log("");
+        appendEvent(runState.runId, {
+            stage: WorkflowStage.INTENT_INCEPTION,
+            action: "User answered clarifying questions",
+            message: `${questions.length} questions answered`
+        });
+        // Step 3: Generate intent artifacts
+        console.log(kleur.cyan("→ Generating intent artifacts..."));
+        const intentSlug = runState.intent
+            .toLowerCase()
+            .replace(/[^a-z0-9]+/g, "-")
+            .replace(/^-|-$/g, "")
+            .substring(0, 50);
+        const artifactsTaskId = randomUUID();
+        const artifactsPacket = {
+            taskId: artifactsTaskId,
+            intent: runState.intent,
+            stage: WorkflowStage.INTENT_INCEPTION,
+            agent: "iris-inception-agent",
+            instructions: `Based on the intent and user answers, create the following intent artifacts:
+
+1. requirements.md - Problem statement, scope, success criteria
+2. system-context.md - Architecture decisions, constraints, tooling
+3. stories.md - User stories or feature breakdown (optional)
+4. units/ - If applicable, identify major units/components
+
+Intent: ${runState.intent}
+
+User Answers:
+${Object.entries(answers).map(([q, a]) => `Q: ${q}\nA: ${a}`).join("\n\n")}
+
+Create files in: memory-bank/intents/${intentSlug}/
+
+Use the IRIS templates as guidance. Do not use placeholders - write real, specific content based on the intent and answers.`,
+            inputs: [],
+            expectedOutputs: [
+                `memory-bank/intents/${intentSlug}/requirements.md`,
+                `memory-bank/intents/${intentSlug}/system-context.md`
+            ],
+            metadata: { step: "generate_artifacts", intentSlug }
+        };
+        appendEvent(runState.runId, {
+            stage: WorkflowStage.INTENT_INCEPTION,
+            action: "Requesting artifact generation",
+            taskId: artifactsTaskId
+        });
+        await connector.sendTask(artifactsPacket);
+        console.log(kleur.dim(`  Task sent: ${artifactsTaskId}`));
+        console.log(kleur.dim("  Waiting for IDE agent to create artifacts...\n"));
+        const artifactsResult = await connector.waitResult(artifactsTaskId, {
+            timeoutMs: 600000 // 10 minutes
+        });
+        if (artifactsResult.status === "error") {
+            throw new Error(artifactsResult.error || "Failed to generate artifacts");
+        }
+        console.log(kleur.green("✓ Artifacts created"));
+        if (artifactsResult.filesChanged) {
+            artifactsResult.filesChanged.forEach(file => {
+                console.log(kleur.dim(`  - ${file}`));
+                runState.artifacts.push(file);
+            });
+        }
+        console.log("");
+        appendEvent(runState.runId, {
+            stage: WorkflowStage.INTENT_INCEPTION,
+            action: "Artifacts generated",
+            outputs: artifactsResult.filesChanged,
+            resultStatus: "ok"
+        });
+        // Step 4: Gate - Approve intent?
+        if (options.gate === "manual") {
+            console.log(kleur.bold(kleur.yellow("Gate: Intent Approval")));
+            const { approved } = await inquirer.prompt([
+                {
+                    type: "confirm",
+                    name: "approved",
+                    message: "Approve intent artifacts and proceed to Bolt Plan?",
+                    default: true
+                }
+            ]);
+            appendEvent(runState.runId, {
+                stage: WorkflowStage.INTENT_INCEPTION,
+                action: "Gate decision",
+                userGateDecision: approved ? "approved" : "rejected"
+            });
+            if (!approved) {
+                console.log(kleur.yellow("\n⚠ Intent rejected. Revision loop not yet implemented."));
+                console.log(kleur.dim("For now, manually edit artifacts and re-run.\n"));
+                runState.stage = WorkflowStage.DONE;
+                return;
+            }
+            console.log(kleur.green("✓ Intent approved\n"));
+        }
+        // Move to next stage
+        runState.stage = WorkflowStage.BOLT_PLAN;
+        saveRun(runState);
+    }
+    catch (error) {
+        console.error(kleur.red(`\n✗ Error: ${error.message}`));
+        appendEvent(runState.runId, {
+            stage: WorkflowStage.INTENT_INCEPTION,
+            action: "Stage failed",
+            message: error.message,
+            resultStatus: "error"
+        });
+        throw error;
+    }
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "project-iris",
+  "version": "0.0.06",
+  "type": "module",
+  "bin": {
+    "iris": "dist/cli.js"
+  },
+  "files": [
+    "dist/**",
+    "src/iris_bundle/**"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "start": "node dist/cli.js",
+    "iris": "node dist/cli.js",
+    "dev": "node --loader ts-node/esm src/cli.ts",
+    "verify": "npm run build && npm run iris -- validate --strict",
+    "verify:repo": "if git ls-files | grep -q '^node_modules/'; then echo 'FAIL: node_modules is tracked'; exit 1; else echo 'PASS: node_modules is not tracked'; fi",
+    "lint": "echo \"(add lint if you want)\"",
+    "link:iris": "npm run build && chmod +x dist/cli.js && npm link && echo '\n✓ iris linked globally' && echo 'Run: iris doctor' && echo 'If iris is not found, add global bin to PATH:' && echo '  export PATH=\"$(npm prefix -g)/bin:$PATH\"'",
+    "unlink:iris": "npm unlink -g && echo '✓ iris unlinked'",
+    "doctor": "npm run iris -- doctor",
+    "prepublishOnly": "npm run build && node dist/cli.js --help",
+    "test:smoke": "npm run build && node scripts/smoke-install.js"
+  },
+  "dependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "commander": "^12.1.0",
+    "fast-glob": "^3.3.3",
+    "gray-matter": "^4.0.3",
+    "inquirer": "^9.3.7",
+    "js-yaml": "^4.1.0",
+    "kleur": "^4.1.5"
+  },
+  "devDependencies": {
+    "@types/inquirer": "^9.0.9",
+    "@types/node": "^22.10.2",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.6.3"
+  }
+}

package/src/iris_bundle/.iris/aidlc/README.md

@@ -0,0 +1,16 @@
+# IRIS AI-DLC Doctrine (Full SDLC) — Core Pack (#1–#4)
+
+This folder is the **authoritative doctrine** for IRIS: a strict, file-based SDLC operating system for AI-assisted development.
+
+## What is implemented in this pack
+1. **Frozen doctrine layout**
+2. **Strict doc schema applied to core docs**
+3. **Canonical SDLC artifacts + templates**
+4. **Phase transitions (preconditions + exit criteria)**
+
+## Non‑negotiables
+- Doctrine governs; tools execute.
+- If it isn't in files, it is unknown.
+- Missing prerequisites are a hard stop.
+
+Start with: `quick-start.md` then `standards/phases-and-gates.md`.

package/src/iris_bundle/.iris/aidlc/agents/iris-construction-agent.md

@@ -0,0 +1,35 @@
+# IRIS Construction Agent
+
+## Purpose
+Implement approved units/bolts with verifiable evidence.
+
+## Inputs
+- Approved unit(s)
+- Ready bolts (optional but recommended)
+
+## Outputs
+- Code changes
+- Verification evidence (review/log)
+- Construction completion log
+
+
+## Hard Rules (Global)
+- MUST follow `standards/phases-and-gates.md`.
+- MUST treat missing prerequisites as a hard stop (`validation/phase-preconditions.md`).
+- MUST log non-trivial decisions (`standards/decision-logging.md`).
+- MUST produce file-addressable outputs (exact paths).
+- MUST NOT invent project state.
+
+## Default Output Format
+- Plan (short)
+- File path list (create/modify)
+- Gate mapping (which checklist items are satisfied)
+- Stop conditions (if blocked)
+
+
+## Procedure
+1. Load unit + bolt(s).
+2. Implement smallest change set.
+3. Verify (`skills/reasoning/verification.md`).
+4. Record evidence.
+5. If scope expands, STOP and request Inception update.

package/src/iris_bundle/.iris/aidlc/agents/iris-inception-agent.md

@@ -0,0 +1,30 @@
+# IRIS Inception Agent
+
+## Purpose
+Create and approve intent + units with testable acceptance criteria.
+
+## Outputs
+- Approved intent + approved units
+- Inception kickoff log
+
+
+## Hard Rules (Global)
+- MUST follow `standards/phases-and-gates.md`.
+- MUST treat missing prerequisites as a hard stop (`validation/phase-preconditions.md`).
+- MUST log non-trivial decisions (`standards/decision-logging.md`).
+- MUST produce file-addressable outputs (exact paths).
+- MUST NOT invent project state.
+
+## Default Output Format
+- Plan (short)
+- File path list (create/modify)
+- Gate mapping (which checklist items are satisfied)
+- Stop conditions (if blocked)
+
+
+## Procedure
+1. Draft intent (`templates/intent.md`) and refine until measurable.
+2. Decompose into units (`skills/reasoning/decomposition.md`).
+3. Add risks/rollback (`skills/reasoning/risk-analysis.md`).
+4. Approve only when gates pass; otherwise keep Draft.
+5. Log key decisions.

package/src/iris_bundle/.iris/aidlc/agents/iris-master-agent.md

@@ -0,0 +1,35 @@
+# IRIS Master Agent
+
+## Purpose
+Route work, enforce gates, and resolve conflicts across phases.
+
+## Inputs
+- Doctrine: `.iris/aidlc/**`
+- Project memory: `memory-bank/**`
+
+## Outputs
+- Routing decisions
+- Gate decisions + reviews
+- Decision logs for architecture-level choices
+
+
+## Hard Rules (Global)
+- MUST follow `standards/phases-and-gates.md`.
+- MUST treat missing prerequisites as a hard stop (`validation/phase-preconditions.md`).
+- MUST log non-trivial decisions (`standards/decision-logging.md`).
+- MUST produce file-addressable outputs (exact paths).
+- MUST NOT invent project state.
+
+## Default Output Format
+- Plan (short)
+- File path list (create/modify)
+- Gate mapping (which checklist items are satisfied)
+- Stop conditions (if blocked)
+
+
+## Procedure
+1. Identify current phase + requested action.
+2. Load required artifacts for that phase.
+3. If prerequisites missing, STOP and request exact file(s).
+4. Route to the correct phase agent.
+5. Enforce gate completion before any transition.

package/src/iris_bundle/.iris/aidlc/agents/iris-operations-agent.md

@@ -0,0 +1,29 @@
+# IRIS Operations Agent
+
+## Purpose
+Operate and stabilize: handover, monitoring, incidents, maintenance.
+
+## Outputs
+- Ops handover log
+- Incident logs and postmortems (when needed)
+
+
+## Hard Rules (Global)
+- MUST follow `standards/phases-and-gates.md`.
+- MUST treat missing prerequisites as a hard stop (`validation/phase-preconditions.md`).
+- MUST log non-trivial decisions (`standards/decision-logging.md`).
+- MUST produce file-addressable outputs (exact paths).
+- MUST NOT invent project state.
+
+## Default Output Format
+- Plan (short)
+- File path list (create/modify)
+- Gate mapping (which checklist items are satisfied)
+- Stop conditions (if blocked)
+
+
+## Procedure
+1. Confirm Ops entry prerequisites.
+2. Maintain runbooks/logs.
+3. For incidents: log → triage → resolve → postmortem (if major).
+4. Feed learnings into standards or new intents.

package/src/iris_bundle/.iris/aidlc/commands/iris-construction-agent.md

@@ -0,0 +1,18 @@
+# /iris-construction-agent
+
+## Purpose
+Run the Construction Agent: implement approved work with evidence.
+
+## Loads
+- `.iris/aidlc/standards/**`
+- `.iris/aidlc/validation/**`
+- `.iris/aidlc/memory/**`
+- `.iris/aidlc/agents/iris-construction-agent.md`
+- `memory-bank/**`
+
+## Required inputs
+See: `.iris/aidlc/validation/phase-preconditions.md`
+
+## Output expectations
+- File-addressable deliverables
+- Evidence and logs where required

package/src/iris_bundle/.iris/aidlc/commands/iris-inception-agent.md

@@ -0,0 +1,18 @@
+# /iris-inception-agent
+
+## Purpose
+Run the Inception Agent: produce approved intent and units.
+
+## Loads
+- `.iris/aidlc/standards/**`
+- `.iris/aidlc/validation/**`
+- `.iris/aidlc/memory/**`
+- `.iris/aidlc/agents/iris-inception-agent.md`
+- `memory-bank/**`
+
+## Required inputs
+See: `.iris/aidlc/validation/phase-preconditions.md`
+
+## Output expectations
+- File-addressable deliverables
+- Evidence and logs where required

package/src/iris_bundle/.iris/aidlc/commands/iris-master-agent.md

@@ -0,0 +1,18 @@
+# /iris-master-agent
+
+## Purpose
+Run the Master Agent: route work and enforce SDLC gates.
+
+## Loads
+- `.iris/aidlc/standards/**`
+- `.iris/aidlc/validation/**`
+- `.iris/aidlc/memory/**`
+- `.iris/aidlc/agents/iris-master-agent.md`
+- `memory-bank/**`
+
+## Required inputs
+See: `.iris/aidlc/validation/phase-preconditions.md`
+
+## Output expectations
+- File-addressable deliverables
+- Evidence and logs where required

package/src/iris_bundle/.iris/aidlc/commands/iris-operations-agent.md

@@ -0,0 +1,18 @@
+# /iris-operations-agent
+
+## Purpose
+Run the Operations Agent: stabilize and maintain.
+
+## Loads
+- `.iris/aidlc/standards/**`
+- `.iris/aidlc/validation/**`
+- `.iris/aidlc/memory/**`
+- `.iris/aidlc/agents/iris-operations-agent.md`
+- `memory-bank/**`
+
+## Required inputs
+See: `.iris/aidlc/validation/phase-preconditions.md`
+
+## Output expectations
+- File-addressable deliverables
+- Evidence and logs where required

package/src/iris_bundle/.iris/aidlc/context/context-map.md

@@ -0,0 +1,25 @@
+# Context Map
+
+## Purpose
+Define what IRIS loads as context per phase.
+
+## Always load
+- `.iris/aidlc/standards/**`
+- `.iris/aidlc/memory/**`
+- `.iris/aidlc/validation/**`
+
+## Phase-specific
+### Inception
+- templates: `intent.md`, `unit.md`
+- standards: `phases-and-gates.md`
+
+### Construction
+- approved unit(s) + related bolts
+- templates: `bolt.md`, `review.md`
+
+### Operations
+- handover + incident/process logs
+- template: `log.md`
+
+## Hard Rules
+- Context MUST be minimal but sufficient.