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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xn-intenton-z2a/agentic-lib",
-  "version": "7.2.6",
+  "version": "7.2.7",
   "description": "Agentic-lib Agentic Coding Systems SDK powering automated GitHub workflows.",
   "type": "module",
   "scripts": {
@@ -72,6 +72,7 @@
     "bin/",
     "src/dist-transform.js",
     "src/iterate.js",
+    "src/copilot/",
     ".github/workflows/agentic-lib-*.yml",
     "agentic-lib.toml",
     "src/actions/agentic-step/*.js",

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

@@ -309,6 +309,13 @@ export async function direct(context) {
             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 */ }
       if (closeReason === "RESOLVED") resolvedCount++;
       recentlyClosedSummary.push(`#${ci.number}: ${ci.title} — ${closeReason}`);

package/src/actions/agentic-step/tasks/supervise.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}`);
     }

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-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.

package/src/copilot/agents.js

@@ -0,0 +1,39 @@
+// SPDX-License-Identifier: GPL-3.0-only
+// Copyright (C) 2025-2026 Polycode Limited
+// src/copilot/agents.js — Load agent prompt files from src/agents/
+
+import { readFileSync, readdirSync } from "fs";
+import { resolve, dirname } from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const agentsDir = resolve(__dirname, "..", "agents");
+
+/**
+ * Load an agent prompt file by name.
+ *
+ * @param {string} agentName - Agent name without extension (e.g. "agent-iterate")
+ * @returns {string} The agent prompt text
+ * @throws {Error} If the agent file is not found
+ */
+export function loadAgentPrompt(agentName) {
+  const filename = agentName.endsWith(".md") ? agentName : `${agentName}.md`;
+  const filePath = resolve(agentsDir, filename);
+  try {
+    return readFileSync(filePath, "utf8");
+  } catch {
+    throw new Error(`Agent prompt not found: ${filePath}`);
+  }
+}
+
+/**
+ * List all available agent prompt files.
+ *
+ * @returns {string[]} Array of agent names (without .md extension)
+ */
+export function listAgents() {
+  return readdirSync(agentsDir)
+    .filter((f) => f.endsWith(".md"))
+    .map((f) => f.replace(".md", ""))
+    .sort();
+}

package/src/copilot/config.js

@@ -0,0 +1,308 @@
+// SPDX-License-Identifier: GPL-3.0-only
+// Copyright (C) 2025-2026 Polycode Limited
+// config-loader.js — Parse agentic-lib.toml and resolve paths
+//
+// TOML-only configuration. The config file is required.
+// All defaults are defined here in one place.
+
+import { readFileSync, existsSync } from "fs";
+import { dirname, join } from "path";
+import { parse as parseToml } from "smol-toml";
+
+/**
+ * @typedef {Object} PathConfig
+ * @property {string} path - The filesystem path
+ * @property {string[]} permissions - Access permissions (e.g. ['write'])
+ * @property {number} [limit] - Maximum number of files allowed
+ */
+
+/**
+ * @typedef {Object} AgenticConfig
+ * @property {string} schedule - Schedule identifier
+ * @property {string} supervisor - Supervisor frequency (off | weekly | daily | hourly | continuous)
+ * @property {string} model - Copilot SDK model for LLM requests
+ * @property {Object<string, PathConfig>} paths - Mapped paths with permissions
+ * @property {string} testScript - Self-contained test command (e.g. "npm ci && npm test")
+ * @property {number} featureDevelopmentIssuesWipLimit - Max concurrent feature issues
+ * @property {number} maintenanceIssuesWipLimit - Max concurrent maintenance issues
+ * @property {number} attemptsPerBranch - Max attempts per branch
+ * @property {number} attemptsPerIssue - Max attempts per issue
+ * @property {Object} seeding - Seed file configuration
+ * @property {Object} intentionBot - Bot configuration
+ * @property {boolean} tdd - Whether TDD mode is enabled
+ * @property {string[]} writablePaths - All paths with write permission
+ * @property {string[]} readOnlyPaths - All paths without write permission
+ */
+
+// Keys whose paths are writable by agents
+const WRITABLE_KEYS = ["source", "tests", "behaviour", "features", "dependencies", "docs", "readme", "examples", "web"];
+
+// Default paths — every key that task handlers might access
+const PATH_DEFAULTS = {
+  mission: "MISSION.md",
+  source: "src/lib/",
+  tests: "tests/unit/",
+  behaviour: "tests/behaviour/",
+  features: "features/",
+  docs: "docs/",
+  examples: "examples/",
+  readme: "README.md",
+  dependencies: "package.json",
+  library: "library/",
+  librarySources: "SOURCES.md",
+  contributing: "CONTRIBUTING.md",
+  web: "src/web/",
+};
+
+// Default limits for path-specific constraints
+const LIMIT_DEFAULTS = {
+  features: 4,
+  library: 32,
+};
+
+// Fallback profile defaults — used only when [profiles.*] is missing from TOML.
+// The canonical source of truth is the [profiles.*] sections in agentic-lib.toml.
+const FALLBACK_TUNING = {
+  reasoningEffort: "medium",
+  infiniteSessions: true,
+  transformationBudget: 32,
+  featuresScan: 10,
+  sourceScan: 10,
+  sourceContent: 5000,
+  testContent: 3000,
+  issuesScan: 20,
+  issueBodyLimit: 500,
+  staleDays: 30,
+  documentSummary: 2000,
+  discussionComments: 10,
+};
+
+const FALLBACK_LIMITS = {
+  featureIssues: 2,
+  maintenanceIssues: 1,
+  attemptsPerBranch: 3,
+  attemptsPerIssue: 2,
+  featuresLimit: 4,
+  libraryLimit: 32,
+};
+
+/**
+ * Parse a TOML profile section into tuning defaults (camelCase keys).
+ */
+function parseTuningProfile(profileSection) {
+  if (!profileSection) return null;
+  return {
+    reasoningEffort: profileSection["reasoning-effort"] || "medium",
+    infiniteSessions: profileSection["infinite-sessions"] ?? true,
+    transformationBudget: profileSection["transformation-budget"] || 32,
+    featuresScan: profileSection["max-feature-files"] || 10,
+    sourceScan: profileSection["max-source-files"] || 10,
+    sourceContent: profileSection["max-source-chars"] || 5000,
+    testContent: profileSection["max-test-chars"] || 3000,
+    issuesScan: profileSection["max-issues"] || 20,
+    issueBodyLimit: profileSection["issue-body-limit"] || 500,
+    staleDays: profileSection["stale-days"] || 30,
+    documentSummary: profileSection["max-summary-chars"] || 2000,
+    discussionComments: profileSection["max-discussion-comments"] || 10,
+  };
+}
+
+/**
+ * Parse a TOML profile section into limits defaults (camelCase keys).
+ */
+function parseLimitsProfile(profileSection) {
+  if (!profileSection) return null;
+  return {
+    featureIssues: profileSection["max-feature-issues"] || 2,
+    maintenanceIssues: profileSection["max-maintenance-issues"] || 1,
+    attemptsPerBranch: profileSection["max-attempts-per-branch"] || 3,
+    attemptsPerIssue: profileSection["max-attempts-per-issue"] || 2,
+    featuresLimit: profileSection["features-limit"] || 4,
+    libraryLimit: profileSection["library-limit"] || 32,
+  };
+}
+
+/**
+ * Read package.json from the project root, returning empty string if not found.
+ * @param {string} tomlPath - Path to the TOML config (used to derive project root)
+ * @param {string} depsRelPath - Relative path to package.json (from config)
+ * @returns {string} Raw package.json content or empty string
+ */
+function readPackageJson(tomlPath, depsRelPath) {
+  try {
+    const projectRoot = dirname(tomlPath);
+    const pkgPath = join(projectRoot, depsRelPath);
+    return existsSync(pkgPath) ? readFileSync(pkgPath, "utf8") : "";
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * Resolve tuning configuration: start from profile defaults, apply explicit overrides.
+ * @param {Object} tuningSection - The [tuning] section from TOML
+ * @param {Object} [profilesSection] - The [profiles] section from TOML (source of truth)
+ */
+function resolveTuning(tuningSection, profilesSection) {
+  const profileName = tuningSection.profile || "recommended";
+  const tomlProfile = profilesSection?.[profileName];
+  const profile = parseTuningProfile(tomlProfile) || FALLBACK_TUNING;
+  const tuning = { ...profile, profileName };
+
+  // "none" explicitly disables reasoning-effort regardless of profile
+  if (tuningSection["reasoning-effort"]) {
+    tuning.reasoningEffort = tuningSection["reasoning-effort"] === "none" ? "" : tuningSection["reasoning-effort"];
+  }
+  if (tuningSection["infinite-sessions"] === true || tuningSection["infinite-sessions"] === false) {
+    tuning.infiniteSessions = tuningSection["infinite-sessions"];
+  }
+  const numericOverrides = {
+    "transformation-budget": "transformationBudget",
+    "max-feature-files": "featuresScan",
+    "max-source-files": "sourceScan",
+    "max-source-chars": "sourceContent",
+    "max-test-chars": "testContent",
+    "max-issues": "issuesScan",
+    "issue-body-limit": "issueBodyLimit",
+    "stale-days": "staleDays",
+    "max-summary-chars": "documentSummary",
+    "max-discussion-comments": "discussionComments",
+  };
+  for (const [tomlKey, jsKey] of Object.entries(numericOverrides)) {
+    if (tuningSection[tomlKey] > 0) tuning[jsKey] = tuningSection[tomlKey];
+  }
+
+  return tuning;
+}
+
+/**
+ * Resolve limits configuration: start from profile defaults, apply explicit overrides.
+ * @param {Object} limitsSection - The [limits] section from TOML
+ * @param {string} profileName - Active profile name
+ * @param {Object} [profilesSection] - The [profiles] section from TOML (source of truth)
+ */
+function resolveLimits(limitsSection, profileName, profilesSection) {
+  const tomlProfile = profilesSection?.[profileName];
+  const profile = parseLimitsProfile(tomlProfile) || FALLBACK_LIMITS;
+  return {
+    featureIssues: limitsSection["max-feature-issues"] || profile.featureIssues,
+    maintenanceIssues: limitsSection["max-maintenance-issues"] || profile.maintenanceIssues,
+    attemptsPerBranch: limitsSection["max-attempts-per-branch"] || profile.attemptsPerBranch,
+    attemptsPerIssue: limitsSection["max-attempts-per-issue"] || profile.attemptsPerIssue,
+    featuresLimit: limitsSection["features-limit"] || profile.featuresLimit,
+    libraryLimit: limitsSection["library-limit"] || profile.libraryLimit,
+  };
+}
+
+/**
+ * Load configuration from agentic-lib.toml.
+ *
+ * If configPath ends in .toml, it is used directly.
+ * Otherwise, the project root is derived (3 levels up from configPath)
+ * and agentic-lib.toml is loaded from there.
+ *
+ * @param {string} configPath - Path to config file or YAML path (for project root derivation)
+ * @returns {AgenticConfig} Parsed configuration object
+ * @throws {Error} If no TOML config file is found
+ */
+export function loadConfig(configPath) {
+  let tomlPath;
+  if (configPath.endsWith(".toml")) {
+    tomlPath = configPath;
+  } else {
+    const configDir = dirname(configPath);
+    const projectRoot = join(configDir, "..", "..", "..");
+    tomlPath = join(projectRoot, "agentic-lib.toml");
+  }
+
+  if (!existsSync(tomlPath)) {
+    throw new Error(`Config file not found: ${tomlPath}. Create agentic-lib.toml in the project root.`);
+  }
+
+  const rawToml = readFileSync(tomlPath, "utf8");
+  const toml = parseToml(rawToml);
+
+  // Merge TOML paths with defaults, normalising library-sources → librarySources
+  const rawPaths = { ...toml.paths };
+  if (rawPaths["library-sources"]) {
+    rawPaths.librarySources = rawPaths["library-sources"];
+    delete rawPaths["library-sources"];
+  }
+  const mergedPaths = { ...PATH_DEFAULTS, ...rawPaths };
+
+  // Build path objects with permissions
+  const paths = {};
+  const writablePaths = [];
+  const readOnlyPaths = [];
+
+  for (const [key, value] of Object.entries(mergedPaths)) {
+    const isWritable = WRITABLE_KEYS.includes(key);
+    paths[key] = { path: value, permissions: isWritable ? ["write"] : [] };
+    if (isWritable) {
+      writablePaths.push(value);
+    } else {
+      readOnlyPaths.push(value);
+    }
+  }
+
+  const profilesSection = toml.profiles || {};
+  const tuning = resolveTuning(toml.tuning || {}, profilesSection);
+  const limitsSection = toml.limits || {};
+  const resolvedLimits = resolveLimits(limitsSection, tuning.profileName, profilesSection);
+
+  // Apply resolved limits to path objects
+  paths.features.limit = resolvedLimits.featuresLimit;
+  paths.library.limit = resolvedLimits.libraryLimit;
+
+  const execution = toml.execution || {};
+  const bot = toml.bot || {};
+
+  // Mission-complete thresholds (with safe defaults)
+  const mc = toml["mission-complete"] || {};
+  const missionCompleteThresholds = {
+    minResolvedIssues: mc["min-resolved-issues"] ?? 3,
+    requireDedicatedTests: mc["require-dedicated-tests"] ?? true,
+    maxSourceTodos: mc["max-source-todos"] ?? 0,
+  };
+
+  return {
+    supervisor: toml.schedule?.supervisor || "daily",
+    model: toml.tuning?.model || toml.schedule?.model || "gpt-5-mini",
+    tuning,
+    paths,
+    testScript: execution.test || "npm ci && npm test",
+    featureDevelopmentIssuesWipLimit: resolvedLimits.featureIssues,
+    maintenanceIssuesWipLimit: resolvedLimits.maintenanceIssues,
+    attemptsPerBranch: resolvedLimits.attemptsPerBranch,
+    attemptsPerIssue: resolvedLimits.attemptsPerIssue,
+    transformationBudget: tuning.transformationBudget,
+    seeding: toml.seeding || {},
+    intentionBot: {
+      intentionFilepath: bot["log-file"] || "intentïon.md",
+    },
+    init: toml.init || null,
+    tdd: toml.tdd === true,
+    missionCompleteThresholds,
+    writablePaths,
+    readOnlyPaths,
+    configToml: rawToml,
+    packageJson: readPackageJson(tomlPath, mergedPaths.dependencies),
+  };
+}
+
+/**
+ * Get the writable paths from config, optionally overridden by an input string.
+ *
+ * @param {AgenticConfig} config - Parsed config
+ * @param {string} [override] - Semicolon-separated override paths
+ * @returns {string[]} Array of writable paths
+ */
+export function getWritablePaths(config, override) {
+  if (override) {
+    return override
+      .split(";")
+      .map((p) => p.trim())
+      .filter(Boolean);
+  }
+  return config.writablePaths;
+}