project-iris 0.0.1

package/dist/workflows/intent-inception.js

@@ -0,0 +1,210 @@
+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"));
+    try {
+        // Step 1: Clarification Loop (Ping-Pong)
+        console.log(kleur.cyan("→ Starting clarification loop..."));
+        const history = [];
+        let isDone = false;
+        let turnCount = 0;
+        const MAX_TURNS = 10;
+        while (!isDone && turnCount < MAX_TURNS) {
+            turnCount++;
+            const turnId = randomUUID();
+            // Prepare context for the agent
+            const contextStr = history.map(h => `Q: ${h.question}\nA: ${h.answer}`).join("\n\n");
+            const instructions = `You are an expert product manager refining a user's intent.
+Intent: "${runState.intent}"
+
+Current Understanding (Q&A History):
+${contextStr || "(None yet)"}
+
+Task:
+Analyze the intent and history.
+You MUST clarify the following aspects before finishing:
+1. Target User & Use Case
+2. Technical Constraints (Language, Frameworks, Database)
+3. Success Criteria (Specific requirements)
+4. Non-Goals (What to avoid)
+
+Instructions:
+1. If you have clear answers for ALL the above aspects, return exactly the string "DONE".
+2. If any aspect is missing or vague, ask the SINGLE most important clarifying question to ask the user next.
+
+Return ONLY the question string or "DONE". Do not include JSON or explanation.`;
+            const packet = {
+                taskId: turnId,
+                intent: runState.intent,
+                stage: WorkflowStage.INTENT_INCEPTION,
+                agent: "iris-inception-agent",
+                instructions,
+                inputs: [],
+                expectedOutputs: [],
+                metadata: { step: "clarify_turn", turn: turnCount }
+            };
+            if (options.noBridge) {
+                console.log(kleur.yellow(`  [Turn ${turnCount}] Bridge disabled. Write result to .iris/bridge/inbox/${turnId}.json`));
+                return; // Cannot proceed in loop without bridge in this mock implementation
+            }
+            // Inner try/catch for turn resilience
+            try {
+                await connector.sendTask(packet);
+                // Show loading spinner or status?
+                const turnResult = await connector.waitResult(turnId, { timeoutMs: 120000 }); // 2 mins per turn
+                if (turnResult.status === "error") {
+                    throw new Error(turnResult.error || "Agent failed to respond");
+                }
+                const agentResponse = turnResult.message.trim();
+                if (agentResponse === "DONE" || agentResponse.includes('"DONE"')) {
+                    isDone = true;
+                    console.log(kleur.green("\n✓ Intent clarified. Proceeding to design...\n"));
+                }
+                else {
+                    // It's a question
+                    const question = agentResponse.replace(/^"|"$/g, ""); // strip quotes if present
+                    console.log(kleur.bold(`\n${question}`));
+                    const { answer } = await inquirer.prompt([
+                        {
+                            type: "input",
+                            name: "answer",
+                            message: "Answer:",
+                            validate: (val) => val.trim().length > 0 || "Please provide an answer"
+                        }
+                    ]);
+                    history.push({ question, answer });
+                    // Append event for tracking
+                    appendEvent(runState.runId, {
+                        stage: WorkflowStage.INTENT_INCEPTION,
+                        action: "Q&A Turn",
+                        message: `Q: ${question}\nA: ${answer}`
+                    });
+                }
+            }
+            catch (e) {
+                console.error(kleur.red(`Error in clarification loop: ${e.message}`));
+                break; // Exit loop on error to save partial progress
+            }
+        }
+        if (history.length > 0) {
+            console.log(kleur.dim(`Captured ${history.length} clarification points.`));
+        }
+        // Prepare answers object for artifact generation (format match)
+        const answers = {};
+        history.forEach((h, i) => {
+            answers[`${i + 1}. ${h.question}`] = h.answer;
+        });
+        // 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/dist/workflows/reporting.js

@@ -0,0 +1,74 @@
+import fs from "fs";
+import path from "path";
+import kleur from "kleur";
+import { ensureDir } from "../lib.js";
+const TIMELINES_DIR = path.join(process.cwd(), "memory-bank/timelines");
+/**
+ * Generate a report for a completed bolt
+ */
+export function generateBoltReport(boltId, runState) {
+    const bolt = runState.bolts.find(b => b.id === boltId);
+    if (!bolt)
+        return;
+    // Find events related to this bolt
+    const events = runState.events.filter(e => e.boltId === boltId);
+    // Calculate duration? (Requires timestamps in BoltState or inferred from events)
+    // For now simplfy.
+    let report = `# Bolt Report: ${boltId}\n\n`;
+    report += `**Status:** ${bolt.status}\n`;
+    report += `**Completed:** ${new Date().toISOString()}\n\n`;
+    report += `## Summary\n`;
+    report += `Successfully executed bolt ${boltId}.\n\n`;
+    report += `## Changes\n`;
+    // We could track files changed in RunEvent if we updated executeBoltExecution to save them properly
+    // For now, list artifacts mentioning this bolt?
+    // Or just say "See git history".
+    report += `See version control for code changes.\n\n`;
+    report += `## Verification\n`;
+    const testEvents = events.filter(e => e.action === "Testing completed");
+    if (testEvents.length > 0) {
+        testEvents.forEach(e => {
+            report += `### Test Results\n`;
+            report += `${e.message}\n\n`;
+        });
+    }
+    else {
+        report += `No specific test results recorded.\n\n`;
+    }
+    report += `## Event Log\n`;
+    events.forEach(e => {
+        report += `- [${e.timestamp}] ${e.action}\n`;
+    });
+    const reportPath = path.join(TIMELINES_DIR, `bolt-${boltId}-report.md`);
+    ensureDir(TIMELINES_DIR);
+    fs.writeFileSync(reportPath, report, "utf8");
+    console.log(kleur.green(`  ✓ Generated report: memory-bank/timelines/bolt-${boltId}-report.md`));
+}
+/**
+ * Generate final project report
+ */
+export function generateFinalReport(runState) {
+    let report = `# Project Completion Report\n\n`;
+    report += `**Intent:** ${runState.intent}\n`;
+    report += `**Completed:** ${new Date().toISOString()}\n\n`;
+    report += `## Executive Summary\n`;
+    report += `The project has been completed successfully. All planned bolts have been executed and verified.\n\n`;
+    report += `## Delivered Bolts\n`;
+    runState.bolts.forEach(bolt => {
+        report += `- **${bolt.id}**: ${bolt.status}\n`;
+    });
+    report += `\n`;
+    report += `## Artifacts\n`;
+    report += `The following key artifacts were generated:\n`;
+    report += `- [Requirements](../intents/default/requirements.md)\n`;
+    report += `- [System Context](../intents/default/system-context.md)\n`;
+    report += `- [Bolt Plan](../operations/bolts/plan.md)\n`;
+    report += `\n`;
+    report += `## Next Steps\n`;
+    report += `1. Review the generated code.\n`;
+    report += `2. Perform manual integration testing.\n`;
+    report += `3. Deploy to target environment.\n`;
+    const reportPath = path.join(process.cwd(), "project-report.md");
+    fs.writeFileSync(reportPath, report, "utf8");
+    console.log(kleur.bold(kleur.green(`\n✓ Project Report Generated: project-report.md`)));
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "project-iris",
+  "version": "0.0.1",
+  "type": "module",
+  "bin": {
+    "iris": "dist/cli.js",
+    "project-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": "vitest run",
+    "test:integration": "vitest run test/integration",
+    "test:smoke": "npm run build && vitest run test/smoke --sequence.concurrent false"
+  },
+  "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",
+    "vitest": "^4.0.16"
+  }
+}

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.

package/src/iris_bundle/.iris/aidlc/context/exclusion-rules.md

@@ -0,0 +1,13 @@
+# Exclusion Rules
+
+## Purpose
+Prevent context bloat and leakage.
+
+## Hard Rules
+- MUST NOT load:
+  - `node_modules/`, build artifacts, binaries
+  - secrets (`.env`, keys, credentials)
+  - large generated files unless required for verification
+
+## Recovery
+If context is too large, reduce to: intent + unit + relevant code + checklist.

package/src/iris_bundle/.iris/aidlc/context/load-order.md

@@ -0,0 +1,25 @@
+# Context Load Order (Canonical)
+
+Tools and runners MUST load context in this order:
+
+1. IRIS phase doctrine
+   - `.iris/aidlc/standards/phases-and-gates.md`
+   - `.iris/aidlc/validation/phase-preconditions.md`
+
+2. IRIS artifact doctrine
+   - `.iris/aidlc/standards/artifacts-registry.md`
+   - `.iris/aidlc/memory/memory-bank.yaml`
+   - `.iris/aidlc/memory/*-rules.md`
+
+3. The requested entrypoint
+   - `.iris/aidlc/commands/<command>.md`
+
+4. Repo-local project signals (if present)
+   - `specs.md`, `README.md`, `package.json`, `tsconfig.json`, relevant `src/**`
+
+5. Phase-specific memory-bank artifacts (if present)
+   - Inception: `memory-bank/intents/**`
+   - Construction: `memory-bank/units/**`, `memory-bank/bolts/**`
+   - Operations: `memory-bank/logs/**`, `memory-bank/standards/**`
+
+If required artifacts are missing, IRIS MUST stop and request creation using templates.

package/src/iris_bundle/.iris/aidlc/memory/intent-rules.md

@@ -0,0 +1,9 @@
+# Intent Rules
+
+## Hard Rules
+- Every repo MUST have at least one active intent.
+- Intent MUST include: Problem, Goals, Non-goals, Constraints, Definition of Done.
+- Any intent change MUST be logged.
+
+## Quality Gate
+If goals are not measurable, the intent is not ready.

package/src/iris_bundle/.iris/aidlc/memory/log-rules.md

@@ -0,0 +1,5 @@
+# Log Rules
+
+## Hard Rules
+- Logs are append-only via new files.
+- Any architecture/behavior decision MUST be logged using `templates/log.md`.