@xn-intenton-z2a/agentic-lib 7.2.5 → 7.2.7

package/src/actions/agentic-step/tasks/supervise.js

@@ -6,7 +6,7 @@
 // asks the Copilot SDK to choose multiple concurrent actions, then dispatches them.
 
 import * as core from "@actions/core";
-import { existsSync, readFileSync, writeFileSync } from "fs";
+import { existsSync, readFileSync, readdirSync, statSync } from "fs";
 import { runCopilotTask, readOptionalFile, scanDirectory, filterIssues } from "../copilot.js";
 
 /**
@@ -218,6 +218,13 @@ async function gatherContext(octokit, repo, config, t) {
             closeReason = "RESOLVED";
           }
         }
+        // Check for automerge closure (issue has "merged" label — set by ci-automerge)
+        if (closeReason !== "RESOLVED") {
+          const issueLabels = ci.labels.map((l) => (typeof l === "string" ? l : l.name));
+          if (issueLabels.includes("merged")) {
+            closeReason = "RESOLVED";
+          }
+        }
       } catch (_) { /* ignore */ }
       recentlyClosedSummary.push(`#${ci.number}: ${ci.title} — ${closeReason}`);
     }
@@ -305,6 +312,61 @@ async function gatherContext(octokit, repo, config, t) {
     }
   } catch { /* ignore */ }
 
+  // Check for dedicated test files (not just seed tests)
+  // A dedicated test imports from the source directory (src/lib/) rather than being a seed test
+  let hasDedicatedTests = false;
+  let dedicatedTestFiles = [];
+  try {
+    const testDirs = ["tests", "__tests__"];
+    for (const dir of testDirs) {
+      if (existsSync(dir)) {
+        const testFiles = scanDirectory(dir, [".js", ".ts", ".mjs"], { limit: 20 });
+        for (const tf of testFiles) {
+          // Skip seed test files (main.test.js, web.test.js, behaviour.test.js)
+          if (/^(main|web|behaviour)\.test\.[jt]s$/.test(tf.name)) continue;
+          const content = readFileSync(tf.path, "utf8");
+          // Check if it imports from src/lib/ (mission-specific code)
+          if (/from\s+['"].*src\/lib\//.test(content) || /require\s*\(\s*['"].*src\/lib\//.test(content)) {
+            hasDedicatedTests = true;
+            dedicatedTestFiles.push(tf.name);
+          }
+        }
+      }
+    }
+  } catch { /* ignore */ }
+
+  // W9: Count TODO comments in source directory
+  let sourceTodoCount = 0;
+  try {
+    const sourcePath = config.paths.source?.path || "src/lib/";
+    const sourceDir = sourcePath.endsWith("/") ? sourcePath.slice(0, -1) : sourcePath;
+    const srcRoot = sourceDir.includes("/") ? sourceDir.split("/").slice(0, -1).join("/") || "src" : "src";
+    // Inline recursive TODO counter (avoids circular import with index.js)
+    const countTodos = (dir) => {
+      let n = 0;
+      if (!existsSync(dir)) return 0;
+      try {
+        const entries = readdirSync(dir);
+        for (const entry of entries) {
+          if (entry === "node_modules" || entry.startsWith(".")) continue;
+          const fp = `${dir}/${entry}`;
+          try {
+            const stat = statSync(fp);
+            if (stat.isDirectory()) {
+              n += countTodos(fp);
+            } else if (/\.(js|ts|mjs)$/.test(entry)) {
+              const content = readFileSync(fp, "utf8");
+              const m = content.match(/\bTODO\b/gi);
+              if (m) n += m.length;
+            }
+          } catch { /* skip */ }
+        }
+      } catch { /* skip */ }
+      return n;
+    };
+    sourceTodoCount = countTodos(srcRoot);
+  } catch { /* ignore */ }
+
   return {
     mission,
     recentActivity,
@@ -333,10 +395,13 @@ async function gatherContext(octokit, repo, config, t) {
     cumulativeTransformationCost,
     recentlyClosedSummary,
     sourceExports,
+    hasDedicatedTests,
+    dedicatedTestFiles,
+    sourceTodoCount,
   };
 }
 
-function buildPrompt(ctx, agentInstructions) {
+function buildPrompt(ctx, agentInstructions, config) {
   return [
     "## Instructions",
     agentInstructions,
@@ -368,6 +433,39 @@ function buildPrompt(ctx, agentInstructions) {
           "",
         ]
       : []),
+    `### Test Coverage`,
+    ctx.hasDedicatedTests
+      ? `Dedicated test files: ${ctx.dedicatedTestFiles.join(", ")}`
+      : "**No dedicated test files found.** Only seed tests (main.test.js, web.test.js) exist. Mission-complete requires dedicated tests that import from src/lib/.",
+    "",
+    `### Source TODO Count: ${ctx.sourceTodoCount}`,
+    ctx.sourceTodoCount > 0
+      ? `**${ctx.sourceTodoCount} TODO(s) found in source.** All TODOs must be resolved before mission-complete can be declared.`
+      : "No TODOs found in source — this criterion is met.",
+    "",
+    ...(() => {
+      // W10: Build mission-complete metrics inline for the LLM
+      const thresholds = config?.missionCompleteThresholds || {};
+      const minResolved = thresholds.minResolvedIssues ?? 3;
+      const requireTests = thresholds.requireDedicatedTests ?? true;
+      const maxTodos = thresholds.maxSourceTodos ?? 0;
+      const resolvedCount = ctx.recentlyClosedSummary.filter((s) => s.includes("RESOLVED")).length;
+      const rows = [
+        `### Mission-Complete Metrics`,
+        "| Metric | Value | Target | Status |",
+        "|--------|-------|--------|--------|",
+        `| Open issues | ${ctx.issuesSummary.length} | 0 | ${ctx.issuesSummary.length === 0 ? "MET" : "NOT MET"} |`,
+        `| Open PRs | ${ctx.prsSummary.length} | 0 | ${ctx.prsSummary.length === 0 ? "MET" : "NOT MET"} |`,
+        `| Issues resolved (RESOLVED) | ${resolvedCount} | >= ${minResolved} | ${resolvedCount >= minResolved ? "MET" : "NOT MET"} |`,
+        `| Dedicated test files | ${ctx.hasDedicatedTests ? "YES" : "NO"} | ${requireTests ? "YES" : "—"} | ${!requireTests || ctx.hasDedicatedTests ? "MET" : "NOT MET"} |`,
+        `| Source TODO count | ${ctx.sourceTodoCount} | <= ${maxTodos} | ${ctx.sourceTodoCount <= maxTodos ? "MET" : "NOT MET"} |`,
+        `| Budget used | ${ctx.cumulativeTransformationCost}/${ctx.transformationBudget} | < ${ctx.transformationBudget || "unlimited"} | ${ctx.transformationBudget > 0 && ctx.cumulativeTransformationCost >= ctx.transformationBudget ? "EXHAUSTED" : "OK"} |`,
+        "",
+        "**All metrics must show MET/OK for mission-complete to be declared.**",
+        "",
+      ];
+      return rows;
+    })(),
     `### Recent Workflow Runs`,
     ctx.workflowsSummary.join("\n") || "none",
     "",
@@ -419,7 +517,7 @@ function buildPrompt(ctx, agentInstructions) {
         ]
       : []),
     ...(ctx.transformationBudget > 0
-      ? [`### Transformation Budget: ${ctx.cumulativeTransformationCost}/${ctx.transformationBudget} used (${Math.max(0, ctx.transformationBudget - ctx.cumulativeTransformationCost)} remaining)`, ""]
+      ? [`### Transformation Budget: ${ctx.cumulativeTransformationCost}/${ctx.transformationBudget} used (${Math.max(0, ctx.transformationBudget - ctx.cumulativeTransformationCost)} remaining)`, "Note: instability transforms (infrastructure fixes) do not count against this budget.", ""]
       : []),
     `### Issue Limits`,
     `Feature development WIP limit: ${ctx.featureIssuesWipLimit}`,
@@ -444,10 +542,6 @@ function buildPrompt(ctx, agentInstructions) {
     "### Communication",
     "- `respond:discussions | message: <text> | discussion-url: <url>` — Reply via discussions bot",
     "",
-    "### Mission Lifecycle",
-    "- `mission-complete | reason: <text>` — Declare mission accomplished. Writes MISSION_COMPLETE.md and sets schedule to off. Use when: all acceptance criteria in MISSION.md are satisfied, tests pass, and recently-closed issues confirm resolution.",
-    "- `mission-failed | reason: <text>` — Declare mission failed. Writes MISSION_FAILED.md and sets schedule to off. Use when: transformation budget is exhausted with no progress, pipeline is stuck in a loop, or the mission is unachievable.",
-    "",
     "### Schedule Control",
     "- `set-schedule:<frequency>` — Change supervisor schedule (off, weekly, daily, hourly, continuous). Use `set-schedule:weekly` when mission is substantially complete, `set-schedule:continuous` to ramp up.",
     "",
@@ -605,152 +699,11 @@ async function executeRespondDiscussions(octokit, repo, params, ctx) {
   return "skipped:respond-no-message";
 }
 
-async function executeMissionComplete(octokit, repo, params, ctx) {
-  const reason = params.reason || "All acceptance criteria satisfied";
-  const signal = [
-    "# Mission Complete",
-    "",
-    `- **Timestamp:** ${new Date().toISOString()}`,
-    `- **Detected by:** supervisor`,
-    `- **Reason:** ${reason}`,
-    "",
-    "This file was created automatically. To restart transformations, delete this file or run `npx @xn-intenton-z2a/agentic-lib init --reseed`.",
-  ].join("\n");
-  writeFileSync("MISSION_COMPLETE.md", signal);
-  core.info(`Mission complete signal written: ${reason}`);
-
-  // Persist MISSION_COMPLETE.md to the repository via Contents API so it survives across runs
-  try {
-    const contentBase64 = Buffer.from(signal).toString("base64");
-    // Check if file already exists (to get its SHA for updates)
-    let existingSha;
-    try {
-      const { data } = await octokit.rest.repos.getContent({ ...repo, path: "MISSION_COMPLETE.md", ref: "main" });
-      existingSha = data.sha;
-    } catch {
-      // File doesn't exist yet — that's fine
-    }
-    await octokit.rest.repos.createOrUpdateFileContents({
-      ...repo,
-      path: "MISSION_COMPLETE.md",
-      message: "mission-complete: " + reason.substring(0, 72),
-      content: contentBase64,
-      branch: "main",
-      ...(existingSha ? { sha: existingSha } : {}),
-    });
-    core.info("MISSION_COMPLETE.md committed to main via Contents API");
-  } catch (err) {
-    core.warning(`Could not commit MISSION_COMPLETE.md to repo: ${err.message}`);
-  }
-
-  if (process.env.GITHUB_REPOSITORY !== "xn-intenton-z2a/agentic-lib") {
-    // Only turn off schedule if it's not already off or in maintenance mode
-    let currentSupervisor = "";
-    try {
-      const tomlContent = readFileSync("agentic-lib.toml", "utf8");
-      const match = tomlContent.match(/^\s*supervisor\s*=\s*"([^"]*)"/m);
-      if (match) currentSupervisor = match[1];
-    } catch { /* ignore */ }
-
-    if (currentSupervisor === "off" || currentSupervisor === "maintenance") {
-      core.info(`Schedule already "${currentSupervisor}" — not changing on mission-complete`);
-    } else {
-      try {
-        await octokit.rest.actions.createWorkflowDispatch({
-          ...repo,
-          workflow_id: "agentic-lib-schedule.yml",
-          ref: "main",
-          inputs: { frequency: "off" },
-        });
-      } catch (err) {
-        core.warning(`Could not set schedule to off: ${err.message}`);
-      }
-    }
-
-    // Announce mission complete via bot
-    const websiteUrl = getWebsiteUrl(repo);
-    const discussionUrl = ctx?.activeDiscussionUrl || "";
-    await dispatchBot(octokit, repo, `Mission complete! ${reason}\n\nWebsite: ${websiteUrl}`, discussionUrl);
-  }
-  return `mission-complete:${reason.substring(0, 100)}`;
-}
-
-async function executeMissionFailed(octokit, repo, params, ctx) {
-  const reason = params.reason || "Mission could not be completed";
-  const signal = [
-    "# Mission Failed",
-    "",
-    `- **Timestamp:** ${new Date().toISOString()}`,
-    `- **Detected by:** supervisor`,
-    `- **Reason:** ${reason}`,
-    "",
-    "This file was created automatically. To restart, delete this file and run `npx @xn-intenton-z2a/agentic-lib init --reseed`.",
-  ].join("\n");
-  writeFileSync("MISSION_FAILED.md", signal);
-  core.info(`Mission failed signal written: ${reason}`);
-
-  // Persist MISSION_FAILED.md to the repository via Contents API so it survives across runs
-  try {
-    const contentBase64 = Buffer.from(signal).toString("base64");
-    let existingSha;
-    try {
-      const { data } = await octokit.rest.repos.getContent({ ...repo, path: "MISSION_FAILED.md", ref: "main" });
-      existingSha = data.sha;
-    } catch {
-      // File doesn't exist yet — that's fine
-    }
-    await octokit.rest.repos.createOrUpdateFileContents({
-      ...repo,
-      path: "MISSION_FAILED.md",
-      message: "mission-failed: " + reason.substring(0, 72),
-      content: contentBase64,
-      branch: "main",
-      ...(existingSha ? { sha: existingSha } : {}),
-    });
-    core.info("MISSION_FAILED.md committed to main via Contents API");
-  } catch (err) {
-    core.warning(`Could not commit MISSION_FAILED.md to repo: ${err.message}`);
-  }
-
-  if (process.env.GITHUB_REPOSITORY !== "xn-intenton-z2a/agentic-lib") {
-    // Only turn off schedule if it's not already off or in maintenance mode
-    let currentSupervisor = "";
-    try {
-      const tomlContent = readFileSync("agentic-lib.toml", "utf8");
-      const match = tomlContent.match(/^\s*supervisor\s*=\s*"([^"]*)"/m);
-      if (match) currentSupervisor = match[1];
-    } catch { /* ignore */ }
-
-    if (currentSupervisor === "off" || currentSupervisor === "maintenance") {
-      core.info(`Schedule already "${currentSupervisor}" — not changing on mission-failed`);
-    } else {
-      try {
-        await octokit.rest.actions.createWorkflowDispatch({
-          ...repo,
-          workflow_id: "agentic-lib-schedule.yml",
-          ref: "main",
-          inputs: { frequency: "off" },
-        });
-      } catch (err) {
-        core.warning(`Could not set schedule to off: ${err.message}`);
-      }
-    }
-
-    // Announce mission failed via bot
-    const websiteUrl = getWebsiteUrl(repo);
-    const discussionUrl = ctx?.activeDiscussionUrl || "";
-    await dispatchBot(octokit, repo, `Mission failed. ${reason}\n\nWebsite: ${websiteUrl}`, discussionUrl);
-  }
-  return `mission-failed:${reason.substring(0, 100)}`;
-}
-
 const ACTION_HANDLERS = {
   "github:create-issue": executeCreateIssue,
   "github:label-issue": executeLabelIssue,
   "github:close-issue": executeCloseIssue,
   "respond:discussions": executeRespondDiscussions,
-  "mission-complete": executeMissionComplete,
-  "mission-failed": executeMissionFailed,
 };
 
 async function executeSetSchedule(octokit, repo, frequency) {
@@ -778,7 +731,7 @@ async function executeAction(octokit, repo, action, params, ctx) {
   if (action === "nop") return "nop";
   const handler = ACTION_HANDLERS[action];
   if (handler) return handler(octokit, repo, params, ctx);
-  core.warning(`Unknown action: ${action}`);
+  core.debug(`Ignoring unrecognised action: ${action}`);
   return `unknown:${action}`;
 }
 
@@ -814,7 +767,7 @@ export async function supervise(context) {
 
   // --- LLM decision ---
   const agentInstructions = instructions || "You are the supervisor. Decide what actions to take.";
-  const prompt = buildPrompt(ctx, agentInstructions);
+  const prompt = buildPrompt(ctx, agentInstructions, config);
 
   const { content, tokensUsed, inputTokens, outputTokens, cost } = await runCopilotTask({
     model,
@@ -845,28 +798,8 @@ export async function supervise(context) {
 
   // --- Deterministic lifecycle posts (after LLM) ---
 
-  // Strategy A: Deterministic mission-complete fallback
-  // If the LLM didn't choose mission-complete but conditions are clearly met, auto-execute it.
-  // Skip in maintenance mode — maintenance keeps running regardless of mission status.
-  if (!ctx.missionComplete && !ctx.missionFailed && config.supervisor !== "maintenance") {
-    const llmChoseMissionComplete = results.some((r) => r.startsWith("mission-complete:"));
-    if (!llmChoseMissionComplete) {
-      const resolvedCount = ctx.recentlyClosedSummary.filter((s) => s.includes("RESOLVED")).length;
-      const hasNoOpenIssues = ctx.issuesSummary.length === 0;
-      const hasNoOpenPRs = ctx.prsSummary.length === 0;
-      if (hasNoOpenIssues && hasNoOpenPRs && resolvedCount >= 1) {
-        core.info(`Deterministic mission-complete: 0 open issues, 0 open PRs, ${resolvedCount} recently resolved — LLM did not detect completion`);
-        try {
-          const autoResult = await executeMissionComplete(octokit, repo,
-            { reason: `All acceptance criteria satisfied (${resolvedCount} issues resolved, 0 open issues, 0 open PRs)` },
-            ctx);
-          results.push(autoResult);
-        } catch (err) {
-          core.warning(`Deterministic mission-complete failed: ${err.message}`);
-        }
-      }
-    }
-  }
+  // W12: Mission-complete/failed evaluation moved to the director task.
+  // The supervisor no longer declares mission-complete or mission-failed.
 
   // Step 3: Auto-respond when a message referral is present
   // If the workflow was triggered with a message (from bot's request-supervisor),
@@ -888,14 +821,8 @@ export async function supervise(context) {
 
   // Build changes list from executed actions
   const changes = results
-    .filter((r) => r.startsWith("created-issue:") || r.startsWith("mission-complete:") || r.startsWith("mission-failed:"))
-    .map((r) => {
-      if (r.startsWith("created-issue:")) return { action: "created-issue", file: r.replace("created-issue:", ""), sizeInfo: "" };
-      if (r.startsWith("mission-complete:")) return { action: "mission-complete", file: "MISSION_COMPLETE.md", sizeInfo: r.replace("mission-complete:", "") };
-      if (r.startsWith("mission-failed:")) return { action: "mission-failed", file: "MISSION_FAILED.md", sizeInfo: r.replace("mission-failed:", "") };
-      return null;
-    })
-    .filter(Boolean);
+    .filter((r) => r.startsWith("created-issue:"))
+    .map((r) => ({ action: "created-issue", file: r.replace("created-issue:", ""), sizeInfo: "" }));
 
   return {
     outcome: actions.length === 0 ? "nop" : `supervised:${actions.length}-actions`,

package/src/agents/agent-apply-fix.md

@@ -18,10 +18,13 @@ A fix is never just one file. These layers form a single unit — if you change
 
 - **Library source** (`src/lib/main.js`) — the core implementation
 - **Unit tests** (`tests/unit/`) — test every function at the API level with exact values and edge cases
-- **Website** (`src/web/index.html` and related files) — imports and calls the library to demonstrate features
+- **Website** (`src/web/index.html` and related files) — imports and calls the library to demonstrate features.
+  **NEVER duplicate library functions inline in the web page** — use the build pipeline (`lib-meta.js`, or
+  a generated browser module) to share code. Inline copies cause behaviour tests to test a simulation, not the real library.
 - **Website unit tests** (`tests/unit/web.test.js`) — verify HTML structure and library wiring
 - **Behaviour tests** (`tests/behaviour/`) — Playwright tests that load the website in a real browser
-  and verify features work at a high navigational level (demo output visible, interactive elements work)
+  and verify features work at a high navigational level (demo output visible, interactive elements work).
+  Includes a coupling test that imports `getIdentity()` from `src/lib/main.js` and asserts the page version matches.
 
 If the failure is in one layer, the fix often requires coordinating changes across multiple layers.
 For example, if a unit test fails because a function signature changed, the website and behaviour tests

package/src/agents/agent-director.md

@@ -0,0 +1,58 @@
+You are the director of an autonomous coding repository. Your sole responsibility is evaluating whether the mission is complete, failed, or in progress.
+
+## Your Role
+
+You do NOT dispatch workflows, create issues, or manage the schedule. That is the supervisor's job. You ONLY assess mission status and produce a structured evaluation.
+
+## Input
+
+You receive:
+1. **MISSION.md** — the acceptance criteria
+2. **Mission-Complete Metrics** — a table of mechanical checks (open issues, PRs, resolved count, test coverage, TODO count, budget)
+3. **Metric based mission complete assessment** — a pre-computed advisory from the mechanical check
+4. **Source Exports** — functions exported from source files
+5. **Recently Closed Issues** — issues resolved since init
+6. **Recent Activity** — the latest entries from the activity log
+
+## Decision Framework
+
+### Mission Complete
+Declare `mission-complete` when ALL of the following are true:
+1. Every row in the Mission-Complete Metrics table shows **MET** or **OK**
+2. The Source Exports demonstrate that all functions required by MISSION.md are implemented
+3. The Recently Closed Issues confirm that acceptance criteria have been addressed
+4. No TODOs remain in source code
+5. Dedicated test files exist (not just seed tests)
+
+### Mission Failed
+Declare `mission-failed` when ANY of the following are true:
+1. Transformation budget is EXHAUSTED and acceptance criteria are still unmet
+2. The last 3+ transforms produced no meaningful code changes
+3. The pipeline is stuck in a loop (same issues created and closed repeatedly)
+
+### Gap Analysis (most common output)
+When the mission is neither complete nor failed, produce a detailed gap analysis:
+- What has been achieved so far
+- What specific gaps remain between the current state and mission-complete
+- Which metrics are NOT MET and what needs to happen to satisfy them
+- Prioritised list of what should be done next
+
+## Output Format
+
+Respond with EXACTLY this structure:
+
+```
+[DECISION]
+mission-complete | mission-failed | in-progress
+[/DECISION]
+[REASON]
+One-line summary of the decision.
+[/REASON]
+[ANALYSIS]
+Detailed gap analysis or completion summary. Include:
+- Metrics status (which are MET, which are NOT MET)
+- What has been achieved
+- What remains (if in-progress)
+- Recommended next actions (if in-progress)
+[/ANALYSIS]
+```

package/src/agents/agent-discovery.md

@@ -0,0 +1,52 @@
+You are a project discovery agent running locally via the intentïon CLI.
+
+Your job is to explore the current working directory and generate a MISSION.md file that describes what this project is and what improvements could be made.
+
+## Your Goal
+
+Analyse the project in the current directory and produce a MISSION.md that a code transformation agent can act on. The mission should be achievable, specific, and grounded in what you actually find.
+
+## Discovery Strategy
+
+1. **Read the project structure** — list files, examine package.json (or equivalent), read README.md if present
+2. **Understand the tech stack** — identify the language, framework, build system, test framework
+3. **Read existing source code** — understand what the project does, its architecture, and its current state
+4. **Read existing tests** — understand test coverage and what's already verified
+5. **Run tests** — use `run_tests` to see the current pass/fail state
+6. **Identify opportunities** — look for:
+   - Missing or incomplete functionality based on README/docs promises
+   - Missing test coverage for existing functions
+   - Code quality improvements (error handling, input validation, edge cases)
+   - Documentation gaps
+   - Obvious bugs or issues
+
+## Output Format
+
+Write a MISSION.md file with the following structure:
+
+```markdown
+# Mission: [Descriptive Title]
+
+[1-2 sentence summary of what this project is and what the mission aims to achieve]
+
+## Current State
+
+[Brief description of what exists — key files, main functionality, test coverage]
+
+## Objectives
+
+[Numbered list of specific, achievable improvements]
+
+## Acceptance Criteria
+
+[Specific, testable criteria that define "done" — these become the test assertions]
+```
+
+## Important Rules
+
+- **Be specific** — don't write vague goals like "improve code quality". Write "add input validation to the `parse()` function for empty strings and null values"
+- **Be achievable** — scope the mission to what can be done in a single transformation session (30-60 minutes of agent work)
+- **Be grounded** — every objective must reference actual code you found in the project
+- **Prioritise test coverage** — if the project has functions without tests, that's always a good mission
+- **Don't hallucinate** — only reference files, functions, and patterns you actually observed
+- **Write the MISSION.md file** — use the file writing tool to create or overwrite MISSION.md in the workspace root

package/src/agents/agent-issue-resolution.md

@@ -92,6 +92,24 @@ automatically (from `docs/` via `npm run build:web`).
 - **Demonstrate features**: Each significant library feature should be visible and usable on the website.
   Behaviour tests will verify these demonstrations work, so make them testable (use IDs, structured output).
 
+### CRITICAL: Never duplicate library code in the web page
+
+**Do NOT copy or recreate library functions inline in `src/web/index.html`.** The web page must consume
+the library through the build pipeline — not by reimplementing functions in a `<script>` block.
+
+Why this matters:
+- Unit tests test `src/lib/main.js` directly
+- Behaviour tests test the web page via Playwright
+- If the web page has its own copy of the functions, behaviour tests test a **simulation** — not the real library
+- The two copies can diverge silently, and tests pass even when the real library is broken
+
+How to share code between library and web:
+- Identity (name, version, description) flows via `lib-meta.js` (generated by `build:web` from `package.json`)
+- If the web page needs to call mission-specific functions, make them available through the build pipeline
+  (e.g. generate a browser-compatible module in `docs/` or add a build step that packages the pure functions)
+- The behaviour test imports `getIdentity()` from `src/lib/main.js` and asserts the page displays the same
+  version — this coupling test proves the pipeline is wired up correctly
+
 ### Guidelines
 
 - `src/web/index.html` is the main page — update it as the library grows

package/src/agents/agent-iterate.md

@@ -0,0 +1,45 @@
+You are an autonomous code transformation agent running locally via the intentïon CLI.
+
+Your workspace is the current working directory. You have been given a MISSION to implement.
+
+## Your Goal
+
+Implement the MISSION described in the user prompt. This means:
+
+1. Read and understand the mission requirements
+2. Read the existing source code and tests to understand the current state
+3. Write the implementation code — keep existing exports, add new ones
+4. Write comprehensive tests covering all acceptance criteria
+5. Run `run_tests` to verify everything passes
+6. If tests fail, read the error output carefully, fix the code, and iterate
+
+## Strategy
+
+1. Read MISSION.md to understand what needs to be built
+2. Examine the project structure — look at package.json, existing source, and test files
+3. Implement the required functionality in the source files
+4. Write dedicated test files covering ALL acceptance criteria from the mission
+5. Run `run_tests` to verify everything passes
+6. If tests fail, read the error output carefully, fix the code, and repeat
+
+## Important Rules
+
+- Keep existing exports and functionality — add to them, don't replace
+- Write tests that import from the library's main entry point
+- Do NOT modify existing test files unless the mission specifically requires it — create new test files for mission-specific tests
+- Keep going until all tests pass or you've exhausted your options
+- Prefer simple, clean implementations over clever ones
+- Follow the project's existing code style and conventions
+
+## All Code Must Change Together
+
+When you change a function signature, return value, or error type, update ALL consumers:
+- Source code
+- Unit tests
+- Any documentation or examples
+
+A partial change that updates the source but not the tests will fail.
+
+## Tests Must Pass
+
+Your changes MUST leave all existing tests passing. The mission's acceptance criteria are the source of truth — if tests and acceptance criteria disagree, fix the tests to match the acceptance criteria and fix the code to pass those tests.