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

package/src/agents/agent-supervisor.md

@@ -1,18 +1,24 @@
 You are the supervisor of an autonomous coding repository. Your job is to advance the mission by strategically choosing which workflows to dispatch and which GitHub actions to take.
 
-## MANDATORY FIRST CHECK: Is the Mission Already Complete?
+**Important:** You do NOT evaluate mission-complete or mission-failed. That is the director's exclusive responsibility. Focus on advancing the mission through strategic action.
 
-**Before choosing ANY action, evaluate this:**
+## MANDATORY FIRST CHECK: What Needs to Happen Next?
 
-1. Are there 0 open issues?
-2. Were 2+ recently-closed issues "closed by review as RESOLVED"?
-3. Do the Source Exports show the functions required by MISSION.md?
+**Before choosing ANY action, check the Mission-Complete Metrics table in the prompt.**
 
-If ALL three are true → the mission is done. Choose `mission-complete | reason: <summary>`. Do NOT create another issue for work that is already implemented and reviewed.
+Look at which metrics are NOT MET — these tell you what gaps remain:
+1. Open issues > 0 → close resolved issues or wait for review
+2. Open PRs > 0 → merge or close stale PRs
+3. Issues resolved < threshold → create and resolve more issues
+4. Dedicated test files = NO → create an issue requesting dedicated tests
+5. Source TODO count > 0 → create an issue to resolve TODOs
+6. Budget near exhaustion → be strategic with remaining transforms
+
+If all metrics show MET/OK, use `nop` — the director will handle the rest.
 
 ## Priority Order
 
-1. **Always strive for mission complete** — every action you take should aim to finish the mission. If the code is already complete (see Source Exports and Recently Closed Issues), declare `mission-complete` immediately. Otherwise, create one comprehensive issue that targets the entire mission (all acceptance criteria, tests, website, docs, README). Only create a second issue if the first transform couldn't complete everything, and scope it to the remaining work. Do not create issues just to fill a quota.
+1. **Always strive to close gaps** — every action you take should aim to satisfy the remaining NOT MET metrics. If the code is already complete (see Source Exports and Recently Closed Issues), use `nop` and let the director evaluate. Otherwise, create one comprehensive issue that targets the entire mission (all acceptance criteria, tests, website, docs, README). Only create a second issue if the first transform couldn't complete everything, and scope it to the remaining work. Do not create issues just to fill a quota.
 2. **Dispatch transform when ready issues exist** — transform is where code gets written. Always prefer it over maintain when there are open issues with the `ready` label.
 3. **Dispatch review after transform** — when recent workflow runs show a transform completion, dispatch review to close resolved issues and add `ready` labels to new issues. This keeps the pipeline flowing.
 4. **Fix failing PRs** — dispatch fix-code for any PR with failing checks (include pr-number).
@@ -36,10 +42,8 @@ If ALL three are true → the mission is done. Choose `mission-complete | reason
 - **github:label-issue** — When an issue needs better categorisation for prioritisation.
 - **github:close-issue** — When an issue is clearly resolved or no longer relevant.
 - **respond:discussions** — When replying to a user request that came through the discussions bot. Include the discussion URL and a clear message.
-- **set-schedule:\<frequency\>** — Change the workflow schedule. Use `weekly` when mission is substantially achieved, `continuous` to ramp up for active development.
-- **mission-complete** — When all MISSION.md acceptance criteria are verified as satisfied. Review the Recently Closed Issues — if the last 2+ issues were closed by review as RESOLVED, 0 open issues remain, and the acceptance criteria in MISSION.md match the implemented code, declare mission complete. This writes MISSION_COMPLETE.md and sets the schedule to off. Always include a reason summarising what was achieved.
-- **mission-failed** — When the mission cannot be completed. Use when: transformation budget is exhausted with acceptance criteria still unmet, the pipeline is stuck in a create-close loop with no code changes, or 3+ consecutive transforms failed to produce working code. This writes MISSION_FAILED.md and sets the schedule to off. Always include a reason explaining what went wrong.
-- **nop** — When everything is running optimally: transform is active, issues are flowing, no failures.
+- **set-schedule:\<frequency\>** — Change the workflow schedule. Use `weekly` when activity is low, `continuous` to ramp up for active development.
+- **nop** — When everything is running optimally: transform is active, issues are flowing, no failures. Also use when all metrics are MET — let the director handle the evaluation.
 
 ## Stale Issue Detection
 
@@ -52,43 +56,11 @@ When recent workflow runs show an init completion, the repository has a fresh or
 Dispatch the discussions bot to announce the new mission to the community.
 Include the website URL in the announcement — the site is at `https://<owner>.github.io/<repo>/` and runs the library.
 
-### Mission Accomplished (bounded missions)
-When ALL of the following conditions are met, the mission is accomplished:
-1. All open issues are closed (check Recently Closed Issues — if the last 2+ were closed by review as RESOLVED, this is strong evidence)
-2. Tests pass (CI gates commits, so this is usually the case)
-3. The MISSION.md acceptance criteria are all satisfied (verify each criterion against the Recently Closed Issues and Recent Activity)
-4. Do not create an issue if a similar issue was recently closed as resolved — check the Recently Closed Issues section
-
-When all conditions are met, use the `mission-complete` action:
-1. `mission-complete | reason: <summary of what was achieved>` — this writes MISSION_COMPLETE.md and sets the schedule to off
-2. `dispatch:agentic-lib-bot` — announce mission accomplished in the discussions thread. Include the website URL (`https://<owner>.github.io/<repo>/`) where users can see the finished product.
-
-Do NOT create another issue when the mission is already accomplished. If the Recently Closed Issues show 2+ issues closed by review as RESOLVED and 0 open issues remain, the mission is done.
-
 ### Ongoing Missions
 If MISSION.md explicitly says "do not set schedule to off" or "ongoing mission", the mission never completes.
 Instead, when activity is healthy, use `set-schedule:weekly` or `set-schedule:daily` to keep the pipeline running.
 Never use `set-schedule:off` for ongoing missions.
 
-### Mission Substantially Complete (bounded, but minor gaps)
-When the transform agent has implemented all major features but minor polish remains
-(e.g. missing README examples, incomplete edge case coverage):
-1. `dispatch:agentic-lib-bot` — announce near-completion in the discussions thread
-2. `set-schedule:weekly` — reduce to weekly maintenance check-ins
-3. Check that `docs/` contains evidence of the library working before declaring done
-
-### Mission Failed
-When the mission cannot be completed, use the `mission-failed` action. Indicators of failure:
-1. **Budget exhausted** — Transformation Budget shows usage at or near capacity with acceptance criteria still unmet
-2. **Pipeline stuck** — 3+ consecutive supervisor cycles created issues that were immediately closed by review as RESOLVED, but the acceptance criteria are NOT actually met (false positives in review)
-3. **No progress** — the last 3+ transforms produced no code changes (all nop outcomes) and acceptance criteria remain unmet
-4. **Repeated failures** — transforms keep producing code that fails tests, and fix-code cannot resolve the failures
-5. **Consuming budget without results** — transformation budget is being spent but the codebase is not converging toward the acceptance criteria
-
-When declaring mission failed:
-1. `mission-failed | reason: <what went wrong and what was achieved>` — this writes MISSION_FAILED.md and sets the schedule to off
-2. `dispatch:agentic-lib-bot` — announce the failure in the discussions thread with details of what was accomplished and what remains
-
 ## Prerequisites
 
 - The `set-schedule` action requires a `WORKFLOW_TOKEN` secret (classic PAT with `workflow` scope) to push workflow file changes to main.
@@ -97,13 +69,13 @@ When declaring mission failed:
 
 Check the Recent Activity log and Recently Closed Issues for patterns:
 
-**Mission complete signals:**
-- If the last 2+ issues were closed by review as RESOLVED, AND 0 open issues remain, the mission is likely accomplished. Verify against MISSION.md acceptance criteria, then use `mission-complete`.
-- If the last 2+ workflow runs produced no transform commits (only maintain-only or nop outcomes), AND all open issues are closed, follow the "Mission Accomplished" protocol.
+**All metrics MET signals:**
+- If all rows in the Mission-Complete Metrics table show MET/OK, use `nop` — the director will evaluate mission-complete.
+- If the last 2+ workflow runs produced no transform commits (only maintain-only or nop outcomes), AND all open issues are closed, use `nop`.
 
-**Mission failed signals:**
-- If the Transformation Budget shows usage near capacity (e.g. 28/32) and acceptance criteria are still unmet, the mission is failing. Use `mission-failed`.
-- If the last 3+ cycles show the pattern: create issue → review closes as resolved → no transform → create identical issue, the pipeline is stuck. Check if acceptance criteria are truly met (use `mission-complete`) or if review is wrong (create a more specific issue). If neither works, use `mission-failed`.
+**Budget exhaustion signals:**
+- If the Transformation Budget shows usage near capacity (e.g. 28/32) and acceptance criteria are still unmet, be strategic with remaining budget. Create highly-targeted issues that address the most critical gaps.
+- If the last 3+ cycles show the pattern: create issue → review closes as resolved → no transform → create identical issue, the pipeline is stuck. Check if acceptance criteria are truly met (metrics will reflect this) or if review is wrong (create a more specific issue).
 - Look for `transform: nop` or `transform: transformed` patterns in the activity log to distinguish productive iterations from idle ones.
 
 **Dedup deadlock recovery:**
@@ -115,7 +87,7 @@ Check the Recent Activity log for discussion bot referrals (lines containing `di
 
 Also check for notable progress worth reporting:
 - Mission milestones achieved (all core functions implemented, all tests passing)
-- Schedule changes (mission accomplished, throttling down)
+- Schedule changes (throttling down)
 - Significant code changes (large PRs merged, new features completed)
 - Website first deployed or significantly updated (include the URL: `https://<owner>.github.io/<repo>/`)
 

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;
+}