@xn-intenton-z2a/agentic-lib 7.4.13 → 7.4.15

package/src/copilot/state.js

@@ -0,0 +1,211 @@
+// SPDX-License-Identifier: GPL-3.0-only
+// Copyright (C) 2025-2026 Polycode Limited
+// state.js — Persistent state across workflow runs via agentic-lib-state.toml
+//
+// Lives on the agentic-lib-logs branch. Read at the start of each
+// agentic-step invocation, written at the end.
+
+import { existsSync, readFileSync, writeFileSync } from "fs";
+import { join } from "path";
+
+/**
+ * Default state structure — used when no state file exists (first run after init).
+ */
+export function defaultState() {
+  return {
+    counters: {
+      "log-sequence": 0,
+      "cumulative-transforms": 0,
+      "cumulative-maintain-features": 0,
+      "cumulative-maintain-library": 0,
+      "cumulative-nop-cycles": 0,
+      "total-tokens": 0,
+    },
+    budget: {
+      "transformation-budget-used": 0,
+      "transformation-budget-cap": 0,
+    },
+    status: {
+      "mission-complete": false,
+      "mission-failed": false,
+      "mission-failed-reason": "",
+      "last-transform-at": "",
+      "last-non-nop-at": "",
+    },
+    schedule: {
+      current: "",
+      "auto-disabled": false,
+      "auto-disabled-reason": "",
+    },
+  };
+}
+
+/**
+ * Serialize a state object to TOML format.
+ * Uses a simple serializer — no external TOML library needed for writing.
+ */
+export function serializeState(state) {
+  const lines = [
+    "# agentic-lib-state.toml — Persistent state across workflow runs",
+    "# Written to the agentic-lib-logs branch by each agentic-step invocation",
+    "",
+  ];
+
+  for (const [section, values] of Object.entries(state)) {
+    lines.push(`[${section}]`);
+    for (const [key, val] of Object.entries(values)) {
+      if (typeof val === "boolean") {
+        lines.push(`${key} = ${val}`);
+      } else if (typeof val === "number") {
+        lines.push(`${key} = ${val}`);
+      } else {
+        lines.push(`${key} = "${String(val).replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`);
+      }
+    }
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Parse a TOML state file into a state object.
+ * Simple parser that handles the known state structure.
+ */
+export function parseState(content) {
+  const state = defaultState();
+  let currentSection = null;
+
+  for (const line of content.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+
+    const sectionMatch = trimmed.match(/^\[(\w[\w-]*)\]$/);
+    if (sectionMatch) {
+      currentSection = sectionMatch[1];
+      if (!state[currentSection]) state[currentSection] = {};
+      continue;
+    }
+
+    if (!currentSection) continue;
+
+    const kvMatch = trimmed.match(/^([\w-]+)\s*=\s*(.+)$/);
+    if (!kvMatch) continue;
+
+    const [, key, rawVal] = kvMatch;
+    let val;
+    if (rawVal === "true") val = true;
+    else if (rawVal === "false") val = false;
+    else if (/^-?\d+$/.test(rawVal)) val = parseInt(rawVal, 10);
+    else if (/^-?\d+\.\d+$/.test(rawVal)) val = parseFloat(rawVal);
+    else if (rawVal.startsWith('"') && rawVal.endsWith('"')) {
+      val = rawVal.slice(1, -1).replace(/\\"/g, '"').replace(/\\\\/g, "\\");
+    } else {
+      val = rawVal;
+    }
+
+    if (state[currentSection]) {
+      state[currentSection][key] = val;
+    }
+  }
+
+  return state;
+}
+
+/**
+ * Read state from the agentic-lib-state.toml file in the given directory.
+ *
+ * @param {string} logsDir - Directory containing agentic-lib-state.toml (usually workspace root where logs are checked out)
+ * @returns {Object} Parsed state, or defaults if file is missing
+ */
+export function readState(logsDir) {
+  const filePath = join(logsDir || ".", "agentic-lib-state.toml");
+  if (!existsSync(filePath)) return defaultState();
+  try {
+    const content = readFileSync(filePath, "utf8");
+    return parseState(content);
+  } catch {
+    return defaultState();
+  }
+}
+
+/**
+ * Write state to the agentic-lib-state.toml file in the given directory.
+ *
+ * @param {string} logsDir - Directory to write to
+ * @param {Object} state - State object to serialize
+ */
+export function writeState(logsDir, state) {
+  const filePath = join(logsDir || ".", "agentic-lib-state.toml");
+  writeFileSync(filePath, serializeState(state));
+}
+
+/**
+ * Increment a counter in the state object. Returns the updated state.
+ *
+ * @param {Object} state - State object
+ * @param {string} key - Counter key (e.g. "cumulative-transforms")
+ * @returns {Object} The same state object (mutated)
+ */
+export function incrementCounter(state, key) {
+  if (state.counters && key in state.counters) {
+    state.counters[key] = (state.counters[key] || 0) + 1;
+  }
+  return state;
+}
+
+/**
+ * Reset the consecutive nop cycle counter (called on any non-nop outcome).
+ *
+ * @param {Object} state - State object
+ * @returns {Object} The same state object (mutated)
+ */
+export function resetConsecutiveNops(state) {
+  if (state.counters) {
+    state.counters["cumulative-nop-cycles"] = 0;
+  }
+  return state;
+}
+
+/**
+ * Update state after a task completes.
+ *
+ * @param {Object} state - State object
+ * @param {Object} params
+ * @param {string} params.task - Task name
+ * @param {string} params.outcome - Task outcome
+ * @param {number} params.transformationCost - 0 or 1
+ * @param {number} params.tokensUsed - Tokens consumed by this task
+ * @returns {Object} The same state object (mutated)
+ */
+export function updateStateAfterTask(state, { task, outcome, transformationCost, tokensUsed }) {
+  const now = new Date().toISOString();
+
+  // Update counters
+  state.counters["log-sequence"] = (state.counters["log-sequence"] || 0) + 1;
+  state.counters["total-tokens"] = (state.counters["total-tokens"] || 0) + (tokensUsed || 0);
+
+  if (transformationCost > 0) {
+    state.counters["cumulative-transforms"] = (state.counters["cumulative-transforms"] || 0) + transformationCost;
+    state.budget["transformation-budget-used"] = (state.budget["transformation-budget-used"] || 0) + transformationCost;
+    state.status["last-transform-at"] = now;
+  }
+
+  // Track task-specific counters
+  if (task === "maintain-features" && outcome !== "nop" && outcome !== "error") {
+    state.counters["cumulative-maintain-features"] = (state.counters["cumulative-maintain-features"] || 0) + 1;
+  }
+  if (task === "maintain-library" && outcome !== "nop" && outcome !== "error") {
+    state.counters["cumulative-maintain-library"] = (state.counters["cumulative-maintain-library"] || 0) + 1;
+  }
+
+  // Consecutive nop tracking
+  if (outcome === "nop") {
+    state.counters["cumulative-nop-cycles"] = (state.counters["cumulative-nop-cycles"] || 0) + 1;
+  } else {
+    state.counters["cumulative-nop-cycles"] = 0;
+    state.status["last-non-nop-at"] = now;
+  }
+
+  return state;
+}

package/src/copilot/telemetry.js

@@ -37,18 +37,68 @@ export function countSourceTodos(dir, extensions = [".js", ".ts", ".mjs"]) {
   return count;
 }
 
+/**
+ * Count source lines in a directory (recursive, .js/.ts/.mjs files).
+ * @param {string} dir
+ * @returns {number}
+ */
+export function countSourceLines(dir) {
+  if (!dir || !existsSync(dir)) return 0;
+  let count = 0;
+  try {
+    const entries = readdirSync(dir);
+    for (const entry of entries) {
+      if (entry === "node_modules" || entry.startsWith(".")) continue;
+      const fullPath = join(dir, entry);
+      try {
+        const stat = statSync(fullPath);
+        if (stat.isDirectory()) {
+          count += countSourceLines(fullPath);
+        } else if (/\.(js|ts|mjs)$/.test(entry)) {
+          const content = readFileSync(fullPath, "utf8");
+          count += content.split("\n").length;
+        }
+      } catch { /* skip */ }
+    }
+  } catch { /* skip */ }
+  return count;
+}
+
+/**
+ * Count acceptance criteria checkboxes in MISSION.md.
+ * @param {string} missionPath
+ * @returns {{ met: number, total: number }}
+ */
+export function countAcceptanceCriteria(missionPath) {
+  if (!missionPath || !existsSync(missionPath)) return { met: 0, total: 0 };
+  try {
+    const content = readFileSync(missionPath, "utf8");
+    const checked = (content.match(/- \[x\]/gi) || []).length;
+    const unchecked = (content.match(/- \[ \]/g) || []).length;
+    return { met: checked, total: checked + unchecked };
+  } catch { return { met: 0, total: 0 }; }
+}
+
 /**
  * Build mission-complete metrics array for the intentïon.md dashboard.
  *
+ * C2: Uses cumulativeCost from persistent state (not per-run).
+ * C5: Includes both per-task and cumulative values.
+ * C6: Replaces "Dedicated test files" with dynamic metrics.
+ *
  * @param {Object} config - Parsed agentic-lib config
  * @param {Object} result - Task result object
  * @param {Array} _limitsStatus - Limits status array (unused but kept for signature compatibility)
- * @param {number} cumulativeCost - Cumulative transformation cost
+ * @param {number} cumulativeCost - Cumulative transformation cost (from state.toml)
  * @param {number} featureIssueCount - Number of open feature issues
  * @param {number} maintenanceIssueCount - Number of open maintenance issues
+ * @param {Object} [taskCosts] - Per-task costs for split display
+ * @param {number} [taskCosts.transformationCost] - This task's transformation cost (0 or 1)
+ * @param {number} [taskCosts.tokensUsed] - This task's token usage
+ * @param {number} [taskCosts.cumulativeTokens] - Cumulative tokens from state
  * @returns {Array} Mission metrics entries
  */
-export function buildMissionMetrics(config, result, _limitsStatus, cumulativeCost, featureIssueCount, maintenanceIssueCount) {
+export function buildMissionMetrics(config, result, _limitsStatus, cumulativeCost, featureIssueCount, maintenanceIssueCount, taskCosts) {
   const openIssues = featureIssueCount + maintenanceIssueCount;
   const budgetCap = config.transformationBudget || 0;
   const resolvedCount = result.resolvedCount || 0;
@@ -61,26 +111,54 @@ export function buildMissionMetrics(config, result, _limitsStatus, cumulativeCos
   const srcRoot = sourceDir.includes("/") ? sourceDir.split("/").slice(0, -1).join("/") || "src" : "src";
   const todoCount = countSourceTodos(srcRoot);
 
-  const dedicatedTestCount = result.dedicatedTestCount ?? 0;
-
   const thresholds = config.missionCompleteThresholds || {};
   const minResolved = thresholds.minResolvedIssues ?? 3;
-  const minTests = thresholds.minDedicatedTests ?? 1;
   const maxTodos = thresholds.maxSourceTodos ?? 0;
 
+  // C6: Dynamic metrics
+  const sourceLines = countSourceLines(sourceDir);
+  const featuresPath = config.paths?.features?.path || "features/";
+  const featureSpecCount = countMdFilesInDir(featuresPath);
+  const missionPath = config.paths?.mission?.path || "MISSION.md";
+  const acceptance = countAcceptanceCriteria(missionPath);
+
+  // C5: Per-task costs (optional)
+  const tc = taskCosts || {};
+  const thisTaskCost = tc.transformationCost ?? 0;
+  const thisTaskTokens = tc.tokensUsed ?? 0;
+  const cumulativeTokens = tc.cumulativeTokens ?? 0;
+
   return [
     { metric: "Open issues", value: String(openIssues), target: "0", status: openIssues === 0 ? "MET" : "NOT MET" },
     { metric: "Open PRs", value: String(openPrs), target: "0", status: openPrs === 0 ? "MET" : "NOT MET" },
     { metric: "Issues resolved (review or PR merge)", value: String(resolvedCount), target: `>= ${minResolved}`, status: resolvedCount >= minResolved ? "MET" : "NOT MET" },
-    { metric: "Dedicated test files", value: String(dedicatedTestCount), target: `>= ${minTests}`, status: dedicatedTestCount >= minTests ? "MET" : "NOT MET" },
     { metric: "Source TODO count", value: String(todoCount), target: `<= ${maxTodos}`, status: todoCount <= maxTodos ? "MET" : "NOT MET" },
-    { metric: "Transformation budget used", value: `${cumulativeCost}/${budgetCap}`, target: budgetCap > 0 ? `< ${budgetCap}` : "unlimited", status: budgetCap > 0 && cumulativeCost >= budgetCap ? "EXHAUSTED" : "OK" },
-    { metric: "Cumulative transforms", value: String(cumulativeCost), target: ">= 1", status: cumulativeCost >= 1 ? "MET" : "NOT MET" },
+    { metric: "Source lines", value: String(sourceLines), target: "—", status: "—" },
+    { metric: "Feature specs", value: String(featureSpecCount), target: "—", status: "—" },
+    { metric: "Acceptance criteria", value: acceptance.total > 0 ? `${acceptance.met}/${acceptance.total}` : "—", target: "—", status: "—" },
+    { metric: "Transforms (this task)", value: String(thisTaskCost), target: "—", status: "—" },
+    { metric: "Transforms (cumulative)", value: String(cumulativeCost), target: ">= 1", status: cumulativeCost >= 1 ? "MET" : "NOT MET" },
+    { metric: "Budget (this task)", value: String(thisTaskCost), target: "—", status: "—" },
+    { metric: "Budget (cumulative)", value: `${cumulativeCost}/${budgetCap}`, target: budgetCap > 0 ? `< ${budgetCap}` : "unlimited", status: budgetCap > 0 && cumulativeCost >= budgetCap ? "EXHAUSTED" : "OK" },
+    { metric: "Tokens (this task)", value: String(thisTaskTokens), target: "—", status: "—" },
+    { metric: "Tokens (cumulative)", value: String(cumulativeTokens), target: "—", status: "—" },
     { metric: "Mission complete declared", value: missionComplete ? "YES" : "NO", target: "—", status: "—" },
     { metric: "Mission failed declared", value: missionFailed ? "YES" : "NO", target: "—", status: "—" },
   ];
 }
 
+/**
+ * Count .md files in a directory (non-recursive).
+ * @param {string} dir
+ * @returns {number}
+ */
+function countMdFilesInDir(dir) {
+  if (!dir || !existsSync(dir)) return 0;
+  try {
+    return readdirSync(dir).filter(f => f.endsWith(".md")).length;
+  } catch { return 0; }
+}
+
 /**
  * Build mission-complete readiness narrative from metrics.
  *
@@ -91,8 +169,8 @@ export function buildMissionReadiness(metrics) {
   const openIssues = parseInt(metrics.find((m) => m.metric === "Open issues")?.value || "0", 10);
   const openPrs = parseInt(metrics.find((m) => m.metric === "Open PRs")?.value || "0", 10);
   const resolved = parseInt(metrics.find((m) => m.metric === "Issues resolved (review or PR merge)")?.value || "0", 10);
-  const dedicatedTests = parseInt(metrics.find((m) => m.metric === "Dedicated test files")?.value || "0", 10);
   const todoCount = parseInt(metrics.find((m) => m.metric === "Source TODO count")?.value || "0", 10);
+  const sourceLines = parseInt(metrics.find((m) => m.metric === "Source lines")?.value || "0", 10);
   const missionComplete = metrics.find((m) => m.metric === "Mission complete declared")?.value === "YES";
   const missionFailed = metrics.find((m) => m.metric === "Mission failed declared")?.value === "YES";
 
@@ -105,7 +183,7 @@ export function buildMissionReadiness(metrics) {
 
   if (allMet) {
     parts.push("Mission complete conditions ARE met.");
-    parts.push(`0 open issues, 0 open PRs, ${resolved} issue(s) resolved, ${dedicatedTests} dedicated test(s), TODOs: ${todoCount}.`);
+    parts.push(`0 open issues, 0 open PRs, ${resolved} issue(s) resolved, ${sourceLines} source lines, TODOs: ${todoCount}.`);
   } else {
     parts.push("Mission complete conditions are NOT met.");
     if (openIssues > 0) parts.push(`${openIssues} open issue(s) remain.`);

package/src/seeds/missions/1-dan-create-c64-emulator.md

@@ -55,19 +55,19 @@ During web-search and document-gathering workflow phases, the agent should look
 
 The opcode table in particular should be assembled from reference data during the research phase and stored as `src/lib/opcodes.js` — a data-driven 256-entry array — rather than hand-coded instruction by instruction. This avoids the agent losing track of which opcodes are implemented and reduces the chance of transcription errors.
 
-## Core API
-
-Export from `src/lib/main.js` (re-exporting from submodules):
-
-- `createC64(opts?)` — create an emulator instance with 64KB RAM and subsystem objects (`cpu`, `memory`, `vic`, `sid`, `cia1`, `cia2`).
-- `loadROMs(c64, { kernal, basic, chargen })` — load ROM images (Uint8Arrays). Must be called before running.
-- `loadPRG(c64, data)` — load a `.prg` file (Uint8Array) into memory at the address from its two-byte header.
-- `step(c64)` — execute one CPU instruction, advance cycle count, update timers. Returns the updated state.
-- `runFrame(c64)` — execute one PAL video frame (~19656 cycles). Fire raster interrupts. Returns the RGBA framebuffer.
-- `getFramebuffer(c64)` — return the current screen as a Uint8Array RGBA pixel buffer (320x200).
-- `pressKey(c64, key)` / `releaseKey(c64, key)` — simulate keyboard input via CIA1 keyboard matrix.
-- `joystickInput(c64, port, directions)` — set joystick state (up/down/left/right/fire) on port 1 or 2.
-- `reset(c64)` — hardware reset (CPU to reset vector, clear subsystem state).
+## Required Capabilities
+
+The emulator must provide a public API (exported from `src/lib/main.js`, re-exporting from submodules) that supports:
+
+- Creating an emulator instance with 64KB RAM and all subsystem objects (CPU, memory, VIC-II, SID, CIAs).
+- Loading ROM images (KERNAL, BASIC, character generator) as Uint8Arrays. Must be called before running.
+- Loading `.prg` files into memory at the address from their two-byte header.
+- Single-stepping one CPU instruction with cycle-accurate timing and timer updates.
+- Running a full PAL video frame (~19656 cycles) with raster interrupt handling, returning an RGBA framebuffer.
+- Reading the current screen as a Uint8Array RGBA pixel buffer (320x200).
+- Simulating keyboard input via the CIA1 keyboard matrix (press and release).
+- Setting joystick state (up/down/left/right/fire) on port 1 or 2.
+- Hardware reset (CPU to reset vector, clear subsystem state).
 
 ## CPU (src/lib/cpu.js, src/lib/opcodes.js)
 

package/src/seeds/missions/1-dan-create-planning-engine.md

@@ -0,0 +1,82 @@
+# Mission
+
+A JavaScript planning engine that implements partial-order planning with constraint satisfaction and belief revision. The engine reads a committed plan file, finds proceedable actions, assembles agents from capabilities, executes them, witnesses the results, and iterates — all within a budget of compute.
+
+## Background
+
+The engine draws on three interconnected disciplines:
+
+- **Knowledge representation** — event calculus for tracking what conditions are initiated and terminated over time, plus truth maintenance for assumption management
+- **Constraint satisfaction** — matching agents to actions based on capabilities and resource requirements, finding non-conflicting sets of actions to execute in parallel
+- **Planning** — partial-order planning (POP) where actions have preconditions and effects, linked by causal chains that can be threatened by other actions
+
+## Required Capabilities
+
+### The Plan File
+
+A committed markdown file with YAML front matter that persists across engine cycles:
+
+- **Front matter**: cycle count, realization score (0.0–1.0), iteration and token budgets
+- **Actions table**: each action has an ID, description, preconditions, effects, assigned agent, status (`open`/`ready`/`in-progress`/`achieved`/`failed`), and resource paths
+- **Causal links**: action A provides condition C that action B needs — forming a dependency chain
+- **Threats**: action X might undo condition C that a causal link protects, with a resolution strategy
+- **Assumptions**: beliefs held by the system with justification, strength, and what depends on them
+- **Open conditions**: conditions needed but not yet provided by any action (explicit gaps)
+- **Observations**: event calculus entries recording what happened, what conditions were initiated/terminated
+- **Witness log**: per-cycle realization score with evidence
+
+The engine must parse this plan, serialize it back losslessly (round-trip fidelity), and update it after each engine step.
+
+### The Engine Loop (7 steps)
+
+1. **Assess** — Read current state: plan + source files + logs + agent definitions + capabilities
+2. **Plan** — Refine the planning artifact (add actions, resolve threats, close open conditions)
+3. **Solve** — Find proceedable actions via constraint satisfaction (met preconditions, no unresolved threats, no resource conflicts)
+4. **Assemble** — Match or compose agents from capabilities for each proceedable action
+5. **Execute** — Run agents in parallel (within concurrency limit), each producing changes
+6. **Witness** — Assess realization (0.0–1.0), record observations
+7. **Iterate** — If budget remains and realization is below threshold, loop back to Assess
+
+### Constraint Solver
+
+An action is **proceedable** when:
+- All preconditions are satisfied (conditions initiated by achieved actions or initial state)
+- No unresolved threats exist against causal links providing those preconditions
+- Its resource paths don't conflict with other actions in the same batch
+
+### Belief Revision
+
+When an observation contradicts an assumption:
+1. Find the weakest-justified contradicted assumption
+2. Retract it
+3. Cascade: re-evaluate all dependents — any action whose sole support was the retracted assumption reverts to `open`
+4. When an action is achieved, propagate its effects as available preconditions for blocked actions
+
+### Agent Assembly
+
+Given an action's requirements, find an agent definition whose capabilities cover the needs. If no existing agent matches, compose one from the minimum set of capabilities that provides all needed tools (constraint satisfaction over the capability set).
+
+## Requirements
+
+- Export all public API as named exports from `src/lib/main.js`.
+- The plan file format must survive parse → serialize → parse round-trips losslessly.
+- The constraint solver must handle preconditions, threats, and resource conflicts correctly.
+- Belief revision must cascade retractions to dependent actions.
+- No external runtime dependencies.
+- Comprehensive unit tests for plan parsing/serialization, constraint solving, belief revision, and agent assembly.
+- README documenting the planning model, engine loop, and plan file format.
+
+## Acceptance Criteria
+
+- [ ] Plan file parses from markdown with YAML front matter into a structured object
+- [ ] Plan file serializes back to markdown losslessly (round-trip)
+- [ ] Constraint solver identifies proceedable actions (all preconditions met, no threats)
+- [ ] Constraint solver excludes actions with unmet preconditions
+- [ ] Constraint solver excludes actions with resource conflicts against the current batch
+- [ ] Belief revision retracts the weakest-justified contradicted assumption
+- [ ] Belief revision cascades: actions depending solely on a retracted assumption revert to `open`
+- [ ] Agent assembly matches an agent definition to an action based on capabilities
+- [ ] Agent assembly composes a novel agent when no existing definition matches
+- [ ] Engine loop iterates through all 7 steps and terminates on budget exhaustion or realization threshold
+- [ ] All unit tests pass
+- [ ] README documents the planning model and engine loop

package/src/seeds/missions/1-kyu-create-ray-tracer.md

@@ -18,14 +18,37 @@ The library should progressively implement:
 - Output PPM (P3) format — simple text-based image format
 - Vector3 class for all geometric operations
 - Configurable resolution and ray depth
-- Deterministic output (no random sampling unless seeded)
+- Deterministic output: all random sampling must use a seeded PRNG. Given the same scene JSON, output must be byte-identical across runs.
+
+## Scene JSON Structure
+
+The scene description format must support at minimum:
+
+```json
+{
+  "camera": { "position": [0,2,-5], "lookAt": [0,0,0], "fov": 60 },
+  "lights": [{ "position": [5,10,-5], "color": [1,1,1] }],
+  "objects": [
+    { "type": "sphere", "center": [0,1,0], "radius": 1, "material": { "color": [1,0,0], "reflective": 0.3 } },
+    { "type": "plane", "normal": [0,1,0], "d": 0, "material": { "color": [0.5,0.5,0.5] } }
+  ]
+}
+```
+
+## Requirements
+
+- Export all public API as named exports from `src/lib/main.js`.
+- No external runtime dependencies.
+- Comprehensive unit tests verifying ray-sphere intersection, reflection vectors, and Snell's law.
+- A sample scene JSON file included in `docs/examples/`.
+- README with rendering examples and scene format documentation.
 
 ## Acceptance Criteria
 
-- `renderScene(scene)` returns a PPM string for a given scene description
-- `parseScene(json)` loads a scene from a JSON string
-- Renders a scene with 3+ spheres, a plane, and a point light in under 10 seconds (640x480)
-- At least one sphere is reflective and one is refractive
-- Unit tests verify ray-sphere intersection, reflection vectors, and Snell's law
-- A sample scene JSON file is included in `docs/examples/`
-- Output PPM can be viewed in any image viewer (validated by checking header format)
+- [ ] Rendering a scene from JSON returns a PPM string
+- [ ] Parsing a scene JSON string returns a usable scene object
+- [ ] Renders a scene with 3+ spheres, a plane, and a point light in under 30 seconds (640x480)
+- [ ] At least one sphere is reflective and one is refractive
+- [ ] Unit tests verify ray-sphere intersection, reflection vectors, and Snell's law
+- [ ] A sample scene JSON file is included in `docs/examples/`
+- [ ] Output PPM can be viewed in any image viewer (validated by checking header format)

package/src/seeds/missions/2-dan-create-self-hosted.md

@@ -0,0 +1,67 @@
+# Mission
+
+A JavaScript test framework that proves a code transformation system can manage its own source code — the software engineering equivalent of a compiler that compiles itself.
+
+## Background
+
+Self-hosting is the strongest proof of capability: if a system can maintain and recreate itself, it can maintain anything. This mission builds a test harness that validates self-hosting through four scenarios of increasing ambition.
+
+## Required Capabilities
+
+### Scenario 1: Clone Self
+
+Copy the system's own source tree into a temporary workspace, write a narrowly-scoped improvement goal (e.g. "Add JSDoc to exported functions in safety.js"), run a transform cycle, and verify the system made a substantive change to its own code.
+
+- Workspace: copy of source tree (excluding `.git/`, `node_modules/`, `models/`)
+- Assertions: target file modified, still valid JavaScript, diff is substantive (not just whitespace)
+
+### Scenario 2: Empty Bootstrap
+
+Start from an empty repository, run an init/purge to create the seed state, write a goal describing the delta between version N and version N+1 (which already exists as a known target), run a transform, and verify convergence toward the known target.
+
+- Workspace: empty, then init creates seed state
+- Key insight: because the target already exists, convergence is objectively measurable
+- Assertions: seed files created, features generated, source modified, valid JavaScript
+- Soft assertion: convergence score — keywords from the N+1 delta found in generated code
+
+### Scenario 3: Version Increment
+
+Copy the source tree, write a goal to update the package version and synchronise seeds, run a transform, and verify the version was updated correctly.
+
+- Assertions: `package.json` modified, still valid JSON
+- Soft: version field matches target, seeds updated
+
+### Scenario 4: Seed Sync
+
+Copy the source tree, tamper with a seed file to introduce an outdated function, write a goal to review and fix seeds, run a transform, and verify the tampered file was corrected.
+
+- Assertions: tampered file modified, still valid JavaScript
+- Soft: modification moves toward correctness
+
+## Infrastructure Required
+
+- A source tree copy function that excludes `.git/`, `node_modules/`, and `models/` directories
+- A diff quality checker that distinguishes substantive changes from whitespace-only edits
+- A JSON validity checker for `package.json` verification
+- A convergence scoring function (0.0–1.0) that measures how many target keywords appear in generated code
+
+## Requirements
+
+- Export all public API as named exports from `src/lib/main.js`.
+- Each scenario must be independently runnable and independently pass/fail.
+- Scenarios must work with a local LLM (no external API dependency required for mechanical validation).
+- No external runtime dependencies beyond what the host system already provides.
+- Comprehensive unit tests for each helper function and integration tests for each scenario.
+- README documenting what self-hosting means, how to run each scenario, and how to interpret results.
+
+## Acceptance Criteria
+
+- [ ] Clone-self scenario: modifies a file in the source tree, output is valid JavaScript, diff is substantive
+- [ ] Empty-bootstrap scenario: creates seed files, generates features, modifies source, output is valid JavaScript
+- [ ] Version-increment scenario: modifies `package.json`, output is valid JSON
+- [ ] Seed-sync scenario: corrects a tampered seed file, output is valid JavaScript
+- [ ] Convergence score function returns 0.0–1.0 based on target keyword matching
+- [ ] Source tree copy excludes `.git/`, `node_modules/`, and `models/`
+- [ ] Each scenario is independently runnable
+- [ ] All unit tests pass
+- [ ] README documents self-hosting concept and scenario execution

package/src/seeds/missions/2-kyu-create-markdown-compiler.md

@@ -0,0 +1,48 @@
+# Mission
+
+Build a Markdown-to-HTML compiler library that converts GitHub Flavored Markdown (GFM) to semantic HTML.
+
+## Required Capabilities
+
+The library must parse and render these 10 GFM feature areas:
+
+1. Headings (h1-h6 via `#` markers) and paragraphs
+2. Inline formatting: bold (`**`), italic (`*`), code (`` ` ``), strikethrough (`~~`)
+3. Links `[text](url)` and images `![alt](src)`
+4. Ordered and unordered lists (including nested lists)
+5. Code blocks (fenced with ``` and language annotation)
+6. Blockquotes (nested `>`)
+7. Tables (GFM pipe syntax with alignment)
+8. Horizontal rules (`---`, `***`, `___`)
+9. Task lists (`- [ ]`, `- [x]`)
+10. Auto-linked URLs and HTML entity escaping
+
+It must also provide a tokenization/inspection mode for testing intermediate representations.
+
+## Technical Requirements
+
+- Pure JavaScript, no external Markdown parsing libraries
+- XSS-safe: all user content must be HTML-escaped before insertion. Specifically, compiling `<script>alert('xss')</script>` must produce escaped output with `&lt;script&gt;`, never executable script tags.
+- Well-formed HTML output: every opening tag must have a matching closing tag. Self-closing tags (`<br/>`, `<img/>`) use XHTML syntax.
+- Exported as both CommonJS and ESM
+
+## Suggested Approach
+
+A two-pass architecture (tokeniser/lexer pass, then renderer pass) works well for this problem, but any architecture that passes the acceptance criteria is acceptable.
+
+## Requirements
+
+- Export all public API as named exports from `src/lib/main.js`.
+- Comprehensive test suite covering: 1 test per feature area (10 minimum), nesting combinations (bold in links, links in lists, code in blockquotes — 5 minimum), edge cases (empty input, single character, whitespace only, deeply nested lists — 5 minimum).
+- README with usage examples.
+
+## Acceptance Criteria
+
+- [ ] Compiling markdown returns an HTML string
+- [ ] Tokenizing markdown returns an array of token objects for inspection
+- [ ] Handles all 10 feature areas listed above
+- [ ] Nested constructs work: bold inside links, links inside lists, code inside blockquotes
+- [ ] Compiling `<script>alert('xss')</script>` produces `&lt;script&gt;` (XSS-safe)
+- [ ] A sample document is compiled and saved to `docs/examples/sample.html`
+- [ ] Output is well-formed HTML (every opening tag has a matching closing tag)
+- [ ] All unit tests pass