@xn-intenton-z2a/agentic-lib 7.4.14 → 7.4.16

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,58 @@ 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;
+  const thisTaskDurationMs = tc.durationMs ?? 0;
+  const cumulativeDurationMs = tc.cumulativeDurationMs ?? 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: "Duration (this task)", value: thisTaskDurationMs > 0 ? `${Math.round(thisTaskDurationMs / 1000)}s` : "—", target: "—", status: "—" },
+    { metric: "Duration (cumulative)", value: cumulativeDurationMs > 0 ? `${Math.round(cumulativeDurationMs / 1000)}s` : "—", 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 +173,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 +187,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

package/src/seeds/missions/2-kyu-create-plot-code-lib.md

@@ -1,24 +1,43 @@
 # Mission
 
-_"Be a go-to plot library with a CLI, be the jq of formulae visualisations."_
+A JavaScript library and CLI tool for generating plots from mathematical expressions and time series data. Produces SVG and PNG output files.
 
-**plot-code-lib** is a JavaScript library and CLI tool designed to:
-- Transform and given range and a simple expression syntax for (pick an existing open standard) to time series data.
-- Read and write the time series data in a standard format (pick an existing open standard).
-- Make use of libraries for formula parsing, time series generation, plotting, and persistence in image formats.
-- Generate SVG and PNG plots from the time series data and save these as files.
-- Variations on this example: `node run start -- --expression "y=sin(x)" --range "x=-1:-1,y=-1:-1" --file output.svg` .
-- Showcase all the features of the library via a CLI by dry running tp generate example commands and output in the README.md file.
+## Required Capabilities
 
-`plot-code-lib` facilitate the creation of plots from mathematical expressions and time series data. It will take a
-mathematical expression and a range of values and generate a plot in SVG or PNG format.
+- Parse a mathematical expression string using JavaScript `Math` functions (e.g. `"y=Math.sin(x)"`, `"y=x*x+2*x-1"`) into an evaluatable function.
+- Evaluate an expression over a numeric range (`start:step:end`) and return an array of data points.
+- Load time series data from a CSV file with columns `time,value`.
+- Render a data series to SVG 1.1 using `<polyline>` elements with a `viewBox` attribute.
+- Render a data series to PNG (canvas-based or via SVG conversion — document the approach in the README).
+- Save a plot to a file, inferring format from extension (`.svg` or `.png`).
+
+## CLI
+
+```
+node src/lib/main.js --expression "y=Math.sin(x)" --range "-3.14:0.01:3.14" --file output.svg
+node src/lib/main.js --csv data.csv --file output.png
+node src/lib/main.js --help
+```
+
+Range format: `start:step:end` (e.g. `-3.14:0.01:3.14`).
+
+The `--help` flag prints usage examples and exits.
+
+## Requirements
+
+- Export all public API as named exports from `src/lib/main.js`.
+- SVG output must be valid SVG 1.1 with a `viewBox` attribute.
+- External dependencies allowed only for PNG rendering (e.g. `canvas`, `sharp`). Expression parsing must use built-in JavaScript `Math` — no external math libraries.
+- Comprehensive unit tests covering expression parsing, series generation, SVG structure, and CLI flags.
+- README with example commands and sample output descriptions.
 
 ## Acceptance Criteria
 
-- [ ] Library parses mathematical expressions (e.g. `y=sin(x)`)
-- [ ] Generates time series data from expression and range
-- [ ] Produces SVG output files
-- [ ] Produces PNG output files
-- [ ] CLI interface works with `--expression`, `--range`, `--file` flags
-- [ ] README showcases example commands and output
+- [ ] Parsing `"y=Math.sin(x)"` returns a callable function
+- [ ] Evaluating over range `-3.14:0.01:3.14` returns ~628 data points
+- [ ] SVG output contains `<polyline>` and `viewBox` attributes
+- [ ] PNG output starts with the PNG magic bytes
+- [ ] CLI `--expression "y=Math.sin(x)" --range "-3.14:0.01:3.14" --file output.svg` produces a file
+- [ ] CLI `--help` prints usage information
 - [ ] All unit tests pass
+- [ ] README documents CLI usage with examples

package/src/seeds/missions/3-kyu-analyze-lunar-lander.md

@@ -9,28 +9,27 @@ A JavaScript library that simulates a lunar lander descent and provides an autop
 - Thrust: each fuel unit burned reduces velocity by 4 m/s
 - Landing: altitude reaches 0. Safe if velocity ≤ 4 m/s, crash if > 4 m/s
 
-## Core Functions
+## Required Capabilities
 
-- `createLander(opts?)` — create a lander state object with configurable initial conditions (altitude, velocity, fuel). Defaults to the values above.
-- `step(lander, thrust)` — advance one tick, burn `thrust` fuel units (clamped to available fuel), return a new state object. The state is immutable.
-- `simulate(lander, controller)` — run to completion using a controller function `(state) => thrustUnits`. Returns an array of states (the trace).
-- `autopilot(state)` — a built-in controller that lands safely. This is the algorithmically interesting part.
-- `score(trace)` — score a landing: 0 for crash, higher for less fuel used + lower landing velocity.
+- Create a lander state with configurable initial conditions (altitude, velocity, fuel). Defaults to the values above.
+- Advance one tick: burn thrust fuel (clamped to available fuel), apply gravity and thrust, return a new immutable state. State objects are plain objects: `{ altitude, velocity, fuel, tick, landed, crashed }`.
+- Simulate to completion using a controller function `(state) => thrustUnits` and return the full trace (array of states).
+- Provide a built-in autopilot controller that lands safely. This is the algorithmically interesting part.
+- Score a landing: `0` for crash, otherwise `(initialFuel - fuelUsed) * 10 + Math.max(0, (4 - landingVelocity) * 25)`. Higher is better.
 
 ## Requirements
 
-- The autopilot must land safely across a range of initial conditions: altitude 500–2000m, velocity 20–80 m/s, fuel 10–50 units.
-- State objects are plain objects: `{ altitude, velocity, fuel, tick, landed, crashed }`.
-- Export all functions as named exports from `src/lib/main.js`.
+- The autopilot must land safely across a range of initial conditions: altitude 500–2000m, velocity 20–80 m/s, fuel 10–50 units. Some combinations are physically impossible to survive (e.g. velocity 80 m/s with fuel 10) — the autopilot should return a crash trace, not throw.
+- Export all public API as named exports from `src/lib/main.js`.
 - Comprehensive unit tests including physics correctness, autopilot safety across parameter ranges, and edge cases (zero fuel, already landed).
 - README with example simulation output showing a successful landing trace.
 
 ## Acceptance Criteria
 
-- [ ] `step()` correctly applies gravity and thrust physics
-- [ ] `autopilot` lands safely with default initial conditions
-- [ ] `autopilot` lands safely across at least 10 different (altitude, velocity, fuel) combinations
-- [ ] `score()` returns 0 for crashes, positive for safe landings
-- [ ] `simulate()` returns a complete trace from start to landing
+- [ ] Stepping correctly applies gravity and thrust physics
+- [ ] Autopilot lands safely with default initial conditions
+- [ ] Autopilot lands safely across at least 10 different (altitude, velocity, fuel) combinations
+- [ ] Scoring returns 0 for crashes, positive for safe landings using the formula `(initialFuel - fuelUsed) * 10 + Math.max(0, (4 - landingVelocity) * 25)`
+- [ ] Simulation returns a complete trace from start to landing
 - [ ] All unit tests pass
 - [ ] README shows example simulation output

package/src/seeds/missions/3-kyu-evaluate-time-series-lab.md

@@ -1,41 +1,35 @@
 # Mission
 
-A JavaScript library that finds, normalises, refreshes, and analyses temporal data. The repo's `data/` directory accumulates CSV/JSON datasets over successive transform cycles.
+A JavaScript library for generating, normalising, forecasting, and correlating time series data. Uses deterministic data generators rather than external APIs, making results reproducible.
 
-This is an ongoing mission. Do not set schedule to off.
+## Required Capabilities
 
-## Core Capabilities
-
-- **Discover** — find publicly available time series data (APIs, open data portals) and fetch snapshots into `data/`.
-- **Normalise** — parse heterogeneous date/time formats, resample to uniform intervals, handle missing values.
-- **Refresh** — on each transform cycle, update existing datasets with newer observations (append, not replace).
-- **Forecast** — implement basic forecasting: moving average, exponential smoothing, linear regression.
-- **Correlate** — find relationships between datasets: cross-correlation, lag analysis.
-- **Report** — generate a `REPORT.md` summarising datasets, trends, and discovered correlations.
-
-## Core Functions
-
-- `discover(sources?)` — search for and download time series data into `data/`.
-- `load(file)` — load a CSV or JSON dataset, auto-detect date format.
-- `normalise(dataset, interval)` — resample to uniform intervals, interpolate missing values.
-- `refresh(file)` — update an existing dataset with newer data from its source.
-- `forecast(dataset, method, horizon)` — predict future values using the specified method.
-- `correlate(datasetA, datasetB)` — compute cross-correlation between two time series.
-- `report(datasets)` — generate a markdown summary report.
+- Generate a sine wave dataset with configurable periods, noise level, and sample rate. Returns an array of `{ time, value }` objects.
+- Generate a seeded random walk for a given number of steps. Returns an array of `{ time, value }` objects.
+- Load time series from a CSV file with columns `time,value`. Auto-detect ISO 8601 and Unix timestamp date formats.
+- Normalise a dataset to uniform intervals using linear interpolation for missing values.
+- Forecast future values using:
+  - Simple moving average (window size N, horizon M).
+  - Exponential smoothing (alpha 0.0–1.0, horizon M).
+- Compute Pearson cross-correlation between two datasets for lags from -maxLag to +maxLag (default 20). Return an array of `{ lag, r }` objects.
+- Generate a markdown report summarising datasets (row count, min, max, mean, trend direction).
 
 ## Requirements
 
-- Export all functions as named exports from `src/lib/main.js`.
-- Store datasets in `data/` as CSV or JSON with consistent schema.
-- Each dataset file should include metadata (source URL, last updated, interval).
-- Unit tests covering normalisation, forecasting accuracy, and correlation.
+- Export all public API as named exports from `src/lib/main.js`.
+- No external runtime dependencies.
+- All random generators must accept a seed for deterministic output.
+- Comprehensive unit tests covering generation, normalisation, forecasting accuracy, and correlation.
 - README with usage examples.
 
 ## Acceptance Criteria
 
-- [ ] Can load and normalise at least one real-world dataset
-- [ ] Forecast produces reasonable predictions (tested against known data)
-- [ ] `data/` directory contains at least one dataset
-- [ ] `REPORT.md` is generated with dataset summaries
+- [ ] Generating a sine wave with 2 periods, 0 noise, 100 samples produces 200 data points tracing a clean sine wave
+- [ ] Generating a random walk with seed 42 produces identical output on repeated calls (deterministic)
+- [ ] Normalising fills gaps with linearly interpolated values
+- [ ] Moving average forecast with window 10, horizon 20 returns 20 predicted values
+- [ ] Forecast of a known sine wave has RMSE < 0.5 for a 10-point horizon
+- [ ] Cross-correlation of two offset sine waves shows peak correlation at the correct lag
+- [ ] Report produces a markdown string with dataset summaries
 - [ ] All unit tests pass
 - [ ] README documents the API with examples