@xn-intenton-z2a/agentic-lib 7.1.6

package/package.json

@@ -0,0 +1,102 @@
+{
+  "name": "@xn-intenton-z2a/agentic-lib",
+  "version": "7.1.6",
+  "description": "Agentic-lib Agentic Coding Systems SDK powering automated GitHub workflows.",
+  "type": "module",
+  "scripts": {
+    "build": "echo \"Nothing to build\"",
+    "formatting": "prettier --check '**/*.{js,json,yml,md}'",
+    "formatting-fix": "prettier --write '**/*.{js,json,yml,md}'",
+    "linting": "eslint",
+    "linting-json": "eslint --format=@microsoft/eslint-formatter-sarif",
+    "linting-fix": "eslint --fix",
+    "update-to-minor": "npx npm-check-updates --upgrade --enginesNode --target minor --verbose --install always",
+    "update-to-greatest": "npx npm-check-updates --upgrade --enginesNode --target greatest --verbose --install always --reject \"alpha\"",
+    "lint:workflows": "node scripts/validate-workflows.js",
+    "security": "npm audit --audit-level=high",
+    "test": "vitest --run",
+    "test:smoke": "node scripts/smoke-test-connectivity.js",
+    "test:copilot": "node scripts/test-copilot-local.js",
+    "test:discussions": "node scripts/test-discussions-local.js",
+    "test:transform": "node scripts/test-transform-local.js ../repository0",
+    "test:system": "bash scripts/system-test.sh --init-only",
+    "test:system:dry-run": "bash scripts/system-test.sh --dry-run",
+    "test:system:live": "bash scripts/system-test.sh",
+    "start": "echo \"agentic-lib is a workflow SDK — see README.md\""
+  },
+  "keywords": [],
+  "author": "https://github.com/xn-intenton-z2a",
+  "license": "GPL-3.0, MIT",
+  "devDependencies": {
+    "@microsoft/eslint-formatter-sarif": "^3.1.0",
+    "eslint": "^9.25.0",
+    "eslint-config-google": "^0.14.0",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-import": "^2.31.0",
+    "eslint-plugin-prettier": "^5.4.0",
+    "eslint-plugin-promise": "^7.2.1",
+    "eslint-plugin-react": "^7.37.5",
+    "eslint-plugin-security": "^4.0.0",
+    "eslint-plugin-sonarjs": "^4.0.0",
+    "js-yaml": "^4.1.0",
+    "markdown-it": "^14.1.0",
+    "markdown-it-github": "^0.5.0",
+    "npm-check-updates": "^19.6.3",
+    "prettier": "^3.8.1",
+    "vitest": "^4.0.18"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "bin": {
+    "agentic-lib": "bin/agentic-lib.js"
+  },
+  "exports": {
+    ".": "./bin/agentic-lib.js",
+    "./config": "./src/actions/agentic-step/config-loader.js",
+    "./copilot": "./src/actions/agentic-step/copilot.js",
+    "./safety": "./src/actions/agentic-step/safety.js",
+    "./logging": "./src/actions/agentic-step/logging.js",
+    "./tools": "./src/actions/agentic-step/tools.js",
+    "./tasks/transform": "./src/actions/agentic-step/tasks/transform.js",
+    "./tasks/maintain-features": "./src/actions/agentic-step/tasks/maintain-features.js",
+    "./tasks/maintain-library": "./src/actions/agentic-step/tasks/maintain-library.js",
+    "./tasks/fix-code": "./src/actions/agentic-step/tasks/fix-code.js",
+    "./tasks/resolve-issue": "./src/actions/agentic-step/tasks/resolve-issue.js",
+    "./tasks/discussions": "./src/actions/agentic-step/tasks/discussions.js",
+    "./tasks/enhance-issue": "./src/actions/agentic-step/tasks/enhance-issue.js",
+    "./tasks/review-issue": "./src/actions/agentic-step/tasks/review-issue.js"
+  },
+  "files": [
+    "package.json",
+    "bin/",
+    "src/workflows/",
+    "src/actions/agentic-step/*.js",
+    "src/actions/agentic-step/*.yml",
+    "src/actions/agentic-step/*.json",
+    "src/actions/agentic-step/tasks/",
+    "src/actions/commit-if-changed/",
+    "src/actions/setup-npmrc/",
+    "src/agents/",
+    "src/seeds/",
+    "src/scripts/"
+  ],
+  "overrides": {
+    "minimatch": ">=10.2.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xn-intenton-z2a/agentic-lib.git"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "@actions/core": "^3.0.0",
+    "@actions/github": "^9.0.0",
+    "@github/copilot-sdk": "^0.1.29",
+    "smol-toml": "^1.6.0"
+  }
+}

package/src/actions/agentic-step/action.yml

@@ -0,0 +1,58 @@
+# SPDX-License-Identifier: MIT
+# Copyright (C) 2025-2026 Polycode Limited
+# .github/agentic-lib/actions/agentic-step/action.yml
+#
+# agentic-step — A GitHub Action wrapping the GitHub Copilot SDK for autonomous code transformation.
+# Part of the intentïon project: https://github.com/xn-intenton-z2a/agentic-lib
+
+name: "agentic-step"
+description: "Run an autonomous agentic task using the GitHub Copilot SDK"
+author: "xn-intenton-z2a"
+
+inputs:
+  task:
+    description: >
+      The task to perform. One of: resolve-issue, fix-code, transform, maintain-features,
+      maintain-library, enhance-issue, review-issue, discussions
+    required: true
+  config:
+    description: "Path to agentic-lib.yml configuration file"
+    required: false
+    default: ".github/agentic-lib/agents/agentic-lib.yml"
+  instructions:
+    description: "Path to agent prompt/instructions file (.md)"
+    required: false
+  issue-number:
+    description: "GitHub issue number (when task involves an issue)"
+    required: false
+  pr-number:
+    description: "GitHub PR number (when task involves a pull request)"
+    required: false
+  writable-paths:
+    description: "Semicolon-separated paths the agent may write to (overrides config)"
+    required: false
+  test-command:
+    description: "Command to validate changes"
+    required: false
+    default: "npm test"
+  discussion-url:
+    description: "GitHub Discussion URL (for discussions task)"
+    required: false
+  model:
+    description: "Copilot SDK model to use"
+    required: false
+    default: "claude-sonnet-4"
+
+outputs:
+  result:
+    description: 'The result of the agentic task (e.g. "pr-created", "code-fixed", "nop")'
+  pr-number:
+    description: "PR number created or modified (if applicable)"
+  tokens-used:
+    description: "Total tokens consumed by the Copilot SDK"
+  model:
+    description: "Model used for the completion"
+
+runs:
+  using: "node24"
+  main: "index.js"

package/src/actions/agentic-step/config-loader.js

@@ -0,0 +1,153 @@
+// 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 {Object<string, PathConfig>} paths - Mapped paths with permissions
+ * @property {string} buildScript - Build command
+ * @property {string} testScript - Test command
+ * @property {string} mainScript - Main entry command
+ * @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", "features", "dependencies", "docs", "readme"];
+
+// Default paths — every key that task handlers might access
+const PATH_DEFAULTS = {
+  mission: "MISSION.md",
+  source: "src/lib/",
+  tests: "tests/unit/",
+  features: ".github/agentic-lib/features/",
+  docs: "docs/",
+  readme: "README.md",
+  dependencies: "package.json",
+  library: "library/",
+  librarySources: "SOURCES.md",
+  contributing: "CONTRIBUTING.md",
+};
+
+// Default limits for path-specific constraints
+const LIMIT_DEFAULTS = {
+  features: 4,
+  library: 32,
+};
+
+/**
+ * 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 toml = parseToml(readFileSync(tomlPath, "utf8"));
+
+  // 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);
+    }
+  }
+
+  // Apply limits from [limits] section or use defaults
+  const limits = toml.limits || {};
+  paths.features.limit = limits["features-limit"] || LIMIT_DEFAULTS.features;
+  paths.library.limit = limits["library-limit"] || LIMIT_DEFAULTS.library;
+
+  const execution = toml.execution || {};
+  const bot = toml.bot || {};
+
+  return {
+    schedule: toml.schedule?.tier || "schedule-1",
+    paths,
+    buildScript: execution.build || "npm run build",
+    testScript: execution.test || "npm test",
+    mainScript: execution.start || "npm run start",
+    featureDevelopmentIssuesWipLimit: limits["feature-issues"] || 2,
+    maintenanceIssuesWipLimit: limits["maintenance-issues"] || 1,
+    attemptsPerBranch: limits["attempts-per-branch"] || 3,
+    attemptsPerIssue: limits["attempts-per-issue"] || 2,
+    seeding: toml.seeding || {},
+    intentionBot: {
+      intentionFilepath: bot["log-file"] || "intentïon.md",
+    },
+    tdd: toml.tdd === true,
+    writablePaths,
+    readOnlyPaths,
+  };
+}
+
+/**
+ * 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;
+}

package/src/actions/agentic-step/copilot.js

@@ -0,0 +1,170 @@
+// SPDX-License-Identifier: GPL-3.0-only
+// Copyright (C) 2025-2026 Polycode Limited
+// copilot.js — Shared utilities for Copilot SDK task handlers
+//
+// Extracts repeated patterns from the 8 task handlers into reusable functions.
+
+import { CopilotClient, approveAll } from "@github/copilot-sdk";
+import { readFileSync, readdirSync, existsSync } from "fs";
+import { createAgentTools } from "./tools.js";
+import * as core from "@actions/core";
+
+/**
+ * Build the CopilotClient options for authentication.
+ *
+ * Auth strategy (in order of preference):
+ * 1. COPILOT_GITHUB_TOKEN env var → override GITHUB_TOKEN/GH_TOKEN in subprocess env
+ *    so the Copilot CLI's auto-login finds the PAT instead of the Actions token.
+ * 2. Fall back to whatever auth is available (GITHUB_TOKEN, gh CLI login, etc.)
+ *
+ * Note: Passing githubToken directly to CopilotClient causes 400 on models.list.
+ * Instead we override the env vars so the CLI subprocess picks up the right token
+ * via its auto-login flow (useLoggedInUser: true).
+ *
+ * @param {string} [githubToken] - Optional token; falls back to COPILOT_GITHUB_TOKEN env var.
+ */
+export function buildClientOptions(githubToken) {
+  const copilotToken = githubToken || process.env.COPILOT_GITHUB_TOKEN;
+  if (!copilotToken) {
+    throw new Error("COPILOT_GITHUB_TOKEN is required. Set it as a repository secret.");
+  }
+  core.info("[copilot] COPILOT_GITHUB_TOKEN found — overriding subprocess env");
+  const env = { ...process.env };
+  // Override both GITHUB_TOKEN and GH_TOKEN so the Copilot CLI
+  // subprocess uses the Copilot PAT for its auto-login flow
+  env.GITHUB_TOKEN = copilotToken;
+  env.GH_TOKEN = copilotToken;
+  return { env };
+}
+
+/**
+ * Run a Copilot SDK session and return the response.
+ * Handles the full lifecycle: create client → create session → send → stop.
+ *
+ * @param {Object} options
+ * @param {string} options.model - Copilot SDK model name
+ * @param {string} options.systemMessage - System message content
+ * @param {string} options.prompt - The prompt to send
+ * @param {string[]} options.writablePaths - Paths the agent may modify
+ * @param {string} [options.githubToken] - Optional token; falls back to COPILOT_GITHUB_TOKEN env var.
+ * @returns {Promise<{content: string, tokensUsed: number}>}
+ */
+export async function runCopilotTask({ model, systemMessage, prompt, writablePaths, githubToken }) {
+  core.info(
+    `[copilot] Creating client (model=${model}, promptLen=${prompt.length}, writablePaths=${writablePaths.length})`,
+  );
+
+  const clientOptions = buildClientOptions(githubToken);
+  const client = new CopilotClient(clientOptions);
+
+  try {
+    core.info("[copilot] Creating session...");
+    const session = await client.createSession({
+      model,
+      systemMessage: { content: systemMessage },
+      tools: createAgentTools(writablePaths),
+      onPermissionRequest: approveAll,
+      workingDirectory: process.cwd(),
+    });
+    core.info(`[copilot] Session created: ${session.sessionId}`);
+
+    // Check auth status now that client is connected
+    try {
+      const authStatus = await client.getAuthStatus();
+      core.info(`[copilot] Auth status: ${JSON.stringify(authStatus)}`);
+    } catch (authErr) {
+      core.warning(`[copilot] Auth check failed: ${authErr.message}`);
+    }
+
+    // Register wildcard event handler for ALL events
+    session.on((event) => {
+      const eventType = event?.type || "unknown";
+      if (eventType === "assistant.message") {
+        const preview = event?.data?.content?.substring(0, 100) || "(no content)";
+        core.info(`[copilot] event=${eventType}: ${preview}...`);
+      } else if (eventType === "session.idle") {
+        core.info(`[copilot] event=${eventType}`);
+      } else if (eventType === "session.error") {
+        core.error(`[copilot] event=${eventType}: ${JSON.stringify(event?.data || event)}`);
+      } else {
+        core.info(`[copilot] event=${eventType}: ${JSON.stringify(event?.data || event).substring(0, 200)}`);
+      }
+    });
+
+    core.info("[copilot] Sending prompt and waiting for idle...");
+    const response = await session.sendAndWait({ prompt }, 300000);
+    core.info(`[copilot] sendAndWait resolved`);
+    const tokensUsed = response?.data?.usage?.totalTokens || 0;
+    const content = response?.data?.content || "";
+
+    return { content, tokensUsed };
+  } finally {
+    await client.stop();
+  }
+}
+
+/**
+ * Read a file, returning empty string on failure. For optional context files.
+ *
+ * @param {string} filePath - Path to read
+ * @param {number} [limit] - Maximum characters to return
+ * @returns {string}
+ */
+export function readOptionalFile(filePath, limit) {
+  try {
+    const content = readFileSync(filePath, "utf8");
+    return limit ? content.substring(0, limit) : content;
+  } catch (err) {
+    core.debug(`[readOptionalFile] ${filePath}: ${err.message}`);
+    return "";
+  }
+}
+
+/**
+ * Scan a directory for files matching an extension, returning name+content pairs.
+ *
+ * @param {string} dirPath - Directory to scan
+ * @param {string|string[]} extensions - File extension(s) to match (e.g. '.md', ['.js', '.ts'])
+ * @param {Object} [options]
+ * @param {number} [options.fileLimit=10] - Max files to return
+ * @param {number} [options.contentLimit] - Max chars per file content
+ * @param {boolean} [options.recursive=false] - Scan recursively
+ * @returns {Array<{name: string, content: string}>}
+ */
+export function scanDirectory(dirPath, extensions, options = {}) {
+  const { fileLimit = 10, contentLimit, recursive = false } = options;
+  const exts = Array.isArray(extensions) ? extensions : [extensions];
+
+  if (!existsSync(dirPath)) return [];
+
+  return readdirSync(dirPath, recursive ? { recursive: true } : undefined)
+    .filter((f) => exts.some((ext) => f.endsWith(ext)))
+    .slice(0, fileLimit)
+    .map((f) => {
+      try {
+        const content = readFileSync(`${dirPath}${f}`, "utf8");
+        return { name: f, content: contentLimit ? content.substring(0, contentLimit) : content };
+      } catch (err) {
+        core.debug(`[scanDirectory] ${dirPath}${f}: ${err.message}`);
+        return { name: f, content: "" };
+      }
+    });
+}
+
+/**
+ * Format the writable/read-only paths section for a prompt.
+ *
+ * @param {string[]} writablePaths
+ * @param {string[]} [readOnlyPaths=[]]
+ * @returns {string}
+ */
+export function formatPathsSection(writablePaths, readOnlyPaths = []) {
+  return [
+    "## File Paths",
+    "### Writable (you may modify these)",
+    writablePaths.length > 0 ? writablePaths.map((p) => `- ${p}`).join("\n") : "- (none)",
+    "",
+    "### Read-Only (for context only, do NOT modify)",
+    readOnlyPaths.length > 0 ? readOnlyPaths.map((p) => `- ${p}`).join("\n") : "- (none)",
+  ].join("\n");
+}

package/src/actions/agentic-step/index.js

@@ -0,0 +1,118 @@
+// SPDX-License-Identifier: GPL-3.0-only
+// Copyright (C) 2025-2026 Polycode Limited
+// index.js — agentic-step GitHub Action entry point
+//
+// Parses inputs, loads config, runs the appropriate task via the Copilot SDK,
+// and sets outputs for downstream workflow steps.
+
+import * as core from "@actions/core";
+import * as github from "@actions/github";
+import { loadConfig, getWritablePaths } from "./config-loader.js";
+import { logActivity } from "./logging.js";
+import { readFileSync } from "fs";
+
+// Task implementations
+import { resolveIssue } from "./tasks/resolve-issue.js";
+import { fixCode } from "./tasks/fix-code.js";
+import { transform } from "./tasks/transform.js";
+import { maintainFeatures } from "./tasks/maintain-features.js";
+import { maintainLibrary } from "./tasks/maintain-library.js";
+import { enhanceIssue } from "./tasks/enhance-issue.js";
+import { reviewIssue } from "./tasks/review-issue.js";
+import { discussions } from "./tasks/discussions.js";
+
+const TASKS = {
+  "resolve-issue": resolveIssue,
+  "fix-code": fixCode,
+  "transform": transform,
+  "maintain-features": maintainFeatures,
+  "maintain-library": maintainLibrary,
+  "enhance-issue": enhanceIssue,
+  "review-issue": reviewIssue,
+  "discussions": discussions,
+};
+
+async function run() {
+  try {
+    // Parse inputs
+    const task = core.getInput("task", { required: true });
+    const configPath = core.getInput("config");
+    const instructionsPath = core.getInput("instructions");
+    const issueNumber = core.getInput("issue-number");
+    const prNumber = core.getInput("pr-number");
+    const writablePathsOverride = core.getInput("writable-paths");
+    const testCommand = core.getInput("test-command");
+    const discussionUrl = core.getInput("discussion-url");
+    const model = core.getInput("model");
+
+    core.info(`agentic-step: task=${task}, model=${model}`);
+
+    // Load config
+    const config = loadConfig(configPath);
+    const writablePaths = getWritablePaths(config, writablePathsOverride);
+
+    // Load instructions if provided
+    let instructions = "";
+    if (instructionsPath) {
+      try {
+        instructions = readFileSync(instructionsPath, "utf8");
+      } catch (err) {
+        core.warning(`Could not read instructions file: ${instructionsPath}: ${err.message}`);
+      }
+    }
+
+    // Look up the task handler
+    const handler = TASKS[task];
+    if (!handler) {
+      throw new Error(`Unknown task: ${task}. Available tasks: ${Object.keys(TASKS).join(", ")}`);
+    }
+
+    // Build context for the task
+    const context = {
+      task,
+      config,
+      instructions,
+      issueNumber,
+      prNumber,
+      writablePaths,
+      testCommand,
+      discussionUrl,
+      model,
+      octokit: github.getOctokit(process.env.GITHUB_TOKEN),
+      repo: github.context.repo,
+      github: github.context,
+    };
+
+    // Run the task
+    const result = await handler(context);
+
+    // Set outputs
+    core.setOutput("result", result.outcome || "completed");
+    if (result.prNumber) core.setOutput("pr-number", String(result.prNumber));
+    if (result.tokensUsed) core.setOutput("tokens-used", String(result.tokensUsed));
+    if (result.model) core.setOutput("model", result.model);
+
+    // Log to intentïon.md
+    const intentionFilepath = config.intentionBot?.intentionFilepath;
+    if (intentionFilepath) {
+      logActivity({
+        filepath: intentionFilepath,
+        task,
+        outcome: result.outcome || "completed",
+        issueNumber,
+        prNumber: result.prNumber,
+        commitUrl: result.commitUrl,
+        tokensUsed: result.tokensUsed,
+        model: result.model || model,
+        details: result.details,
+        workflowUrl: `${process.env.GITHUB_SERVER_URL}/${github.context.repo.owner}/${github.context.repo.repo}/actions/runs/${github.context.runId}`,
+      });
+    }
+
+    core.info(`agentic-step completed: outcome=${result.outcome}`);
+  } catch (error) {
+    core.setFailed(`agentic-step failed: ${error.message}`);
+  }
+}
+
+run();

package/src/actions/agentic-step/logging.js

@@ -0,0 +1,88 @@
+// SPDX-License-Identifier: GPL-3.0-only
+// Copyright (C) 2025-2026 Polycode Limited
+// logging.js — intentïon.md activity log writer
+//
+// Appends structured entries to the intentïon.md activity log,
+// including commit URLs and safety-check outcomes.
+
+import { writeFileSync, appendFileSync, existsSync, mkdirSync } from "fs";
+import { dirname } from "path";
+import * as core from "@actions/core";
+
+/**
+ * Log an activity to the intentïon.md file.
+ *
+ * @param {Object} options
+ * @param {string} options.filepath - Path to the intentïon.md file
+ * @param {string} options.task - The task that was performed
+ * @param {string} options.outcome - The outcome (e.g. 'pr-created', 'nop', 'error')
+ * @param {string} [options.issueNumber] - Related issue number
+ * @param {string} [options.prNumber] - Related PR number
+ * @param {string} [options.commitUrl] - URL to the commit
+ * @param {number} [options.tokensUsed] - Tokens consumed
+ * @param {string} [options.model] - Model used
+ * @param {string} [options.details] - Additional details
+ * @param {string} [options.workflowUrl] - URL to the workflow run
+ */
+export function logActivity({
+  filepath,
+  task,
+  outcome,
+  issueNumber,
+  prNumber,
+  commitUrl,
+  tokensUsed,
+  model,
+  details,
+  workflowUrl,
+}) {
+  const dir = dirname(filepath);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+
+  const isoDate = new Date().toISOString();
+  const parts = [`\n## ${task} at ${isoDate}`, "", `**Outcome:** ${outcome}`];
+
+  if (issueNumber) parts.push(`**Issue:** #${issueNumber}`);
+  if (prNumber) parts.push(`**PR:** #${prNumber}`);
+  if (commitUrl) parts.push(`**Commit:** [${commitUrl}](${commitUrl})`);
+  if (model) parts.push(`**Model:** ${model}`);
+  if (tokensUsed !== undefined) parts.push(`**Tokens:** ${tokensUsed}`);
+  if (workflowUrl) parts.push(`**Workflow:** [${workflowUrl}](${workflowUrl})`);
+  if (details) {
+    parts.push("");
+    parts.push(details);
+  }
+  parts.push("");
+  parts.push("---");
+
+  const entry = parts.join("\n");
+
+  if (existsSync(filepath)) {
+    appendFileSync(filepath, entry);
+  } else {
+    writeFileSync(filepath, `# intentïon Activity Log\n${entry}`);
+  }
+}
+
+/**
+ * Log a safety check outcome to the GitHub Actions log.
+ *
+ * @param {string} checkName - The name of the safety check (e.g. 'attempt-limit', 'wip-limit', 'issue-resolved')
+ * @param {boolean} passed - Whether the check passed (true = allowed to proceed)
+ * @param {Object} [details] - Additional details about the check
+ */
+export function logSafetyCheck(checkName, passed, details = {}) {
+  const detailStr = Object.entries(details)
+    .map(([k, v]) => `${k}=${v}`)
+    .join(", ");
+  const status = passed ? "PASSED" : "BLOCKED";
+  const suffix = detailStr ? ` (${detailStr})` : "";
+  const message = `Safety check [${checkName}]: ${status}${suffix}`;
+  if (passed) {
+    core.info(message);
+  } else {
+    core.warning(message);
+  }
+}