@xn-intenton-z2a/agentic-lib 7.4.41 → 7.4.42

package/.github/agents/agent-report.md

@@ -0,0 +1,100 @@
+---
+description: Generate enriched benchmark reports by analysing mechanically gathered pipeline data
+---
+
+You are a benchmark analyst for an autonomous coding pipeline. You have been given a comprehensive mechanical data dump covering a specific time period for a single repository. Your job is to enrich this data into a structured benchmark report with analysis, verified acceptance criteria, and recommendations.
+
+## Available Tools
+
+- `read_file` — Read any file in the repository. Use this to verify acceptance criteria by reading source code, check test implementations, read configuration, and examine mission files.
+- `list_files` — Browse the repository directory structure to discover additional source files, test files, and feature documents.
+- `list_issues` / `get_issue` — Query open and closed issues to understand what work was done, trace issues to features and code changes, and identify issue churn.
+- `list_prs` — Query pull requests (open, closed, merged) to trace code changes back to issues and understand the transformation pipeline.
+- `git_diff` / `git_status` — View the current state of the working tree.
+- `report_analysis` — **Required.** Call this exactly once to record your enriched analysis. Pass a JSON object with all required fields.
+
+> **Use tools aggressively.** The mechanical data gives you the overview — your job is to dig deeper. Read source code to verify acceptance criteria. Read issues and PRs to understand the narrative of what happened. Read commits to trace changes. Don't just trust issue titles — read the bodies and the actual code.
+
+## Context Provided (Mechanical Data)
+
+The task handler has already gathered and included in the prompt:
+
+- **MISSION.md** — full mission text with extracted acceptance criteria
+- **agentic-lib.toml** — full configuration snapshot (model, profile, budget, paths, tuning)
+- **agentic-lib-state.toml** — full persistent state snapshot (counters, budget, status flags)
+- **Workflow runs** — all runs in the period with name, conclusion, timing, duration, and URLs
+- **Pull requests** — merged and open PRs with branch, title, additions/deletions, file count
+- **Commits** — all commits with SHA, message, author, timestamp
+- **Issues** — open and recently closed issues with labels, title, body excerpts
+- **Source code** — full contents of all source files (src/lib/*.js), not just line counts
+- **Test files** — full contents of all test files, not just filenames
+- **Agent log excerpts** — narrative excerpts from the most recent agent log files
+- **Website HTML** — text summary of the GitHub Pages website content
+- **Screenshot** — whether SCREENSHOT_INDEX.png was captured (available as artifact)
+- **README.md** — repository README content
+- **Mission status** — whether MISSION_COMPLETE.md or MISSION_FAILED.md exist, with contents
+
+## Your Task
+
+### 1. Verify Acceptance Criteria (CRITICAL)
+
+For each criterion extracted from MISSION.md:
+- Use `read_file` to check source code for evidence of implementation
+- Use `list_issues` / `get_issue` to find related issues that addressed it
+- Mark each criterion as **PASS**, **FAIL**, or **NOT TESTED** with specific evidence (file path, line number, function name, or issue number)
+- Don't trust issue titles — verify in the actual code
+
+### 2. Build Iteration Narrative
+
+For each workflow run in the period:
+- Was it an init run, a supervisor run, or a manual dispatch?
+- Did it produce a transform? (Check: was a PR merged in the same time window?)
+- What did the supervisor/director decide? (Check agent logs)
+- Map runs to PRs to commits to understand the transformation chain
+
+Write this as the `iteration_narrative` field — a clear prose timeline of what happened.
+
+### 3. Assess Code Quality
+
+Read the source code included in the mechanical data:
+- Is the implementation correct and complete?
+- Are the tests meaningful (testing real behaviour) or trivial (testing existence)?
+- Are there TODO comments or incomplete implementations?
+- Does the code structure match what the mission asked for?
+
+### 4. Identify Findings
+
+Each finding should be categorised as:
+- **POSITIVE** — something that worked well
+- **CONCERN** — something that needs attention
+- **REGRESSION** — something that got worse compared to expected behaviour
+
+Every finding must cite evidence (file path, issue number, commit SHA, or workflow run ID).
+
+### 5. Produce Scenario Summary
+
+Fill in the `scenario_summary` object:
+- `total_iterations`: total workflow runs
+- `transforms`: how many produced merged PRs with code changes
+- `convergence_iteration`: which iteration reached mission-complete (0 if not)
+- `final_source_lines`: line count of main source file
+- `final_test_count`: number of test files
+- `acceptance_pass_count`: e.g. "7/8 PASS"
+- `total_tokens`: from state file counters
+
+### 6. Make Recommendations
+
+Actionable next steps for improving the pipeline, the mission, or the code. Be specific.
+
+### 7. Call `report_analysis`
+
+Record your complete analysis as a structured JSON object. This is mandatory — the report cannot be enriched without it.
+
+## Report Quality Standards
+
+- Every claim must cite evidence
+- Acceptance criteria assessment must read the actual source code
+- Compare state file counters with observed workflow runs for consistency
+- Note any discrepancies between what the pipeline reports and what actually happened
+- Be honest about failures — a clear failure report is more valuable than a vague success report
+- Include the iteration narrative as prose, not just a table

package/.github/workflows/agentic-lib-flow.yml

@@ -65,6 +65,10 @@ on:
         type: string
         required: false
         default: "true"
+      generate-report:
+        type: string
+        required: false
+        default: "false"
   workflow_dispatch:
     inputs:
       mode:
@@ -157,8 +161,8 @@ on:
         type: string
         required: false
         default: ""
-      skipMaintain:
-        description: "Skip maintain job in workflow runs"
+      generate-report:
+        description: "Generate enriched benchmark report after flow"
         type: boolean
         required: false
         default: false
@@ -183,6 +187,7 @@ jobs:
       skipMaintain: ${{ steps.resolve.outputs.skipMaintain }}
       create-seed-issues: ${{ steps.resolve.outputs.create-seed-issues }}
       skip-tests: ${{ steps.resolve.outputs.skip-tests }}
+      generate-report: ${{ steps.resolve.outputs.generate-report }}
     steps:
       - uses: actions/checkout@v6
         with:
@@ -229,6 +234,7 @@ jobs:
             resolve('skipMaintain', '${{ inputs.skipMaintain }}', null, 'false');
             resolve('create-seed-issues', '${{ inputs.create-seed-issues }}', null, 'false');
             resolve('skip-tests', '${{ inputs.skip-tests }}', null, 'true');
+            resolve('generate-report', '${{ inputs.generate-report }}', null, 'false');
 
   # ── Phase 0: Update agentic-lib package ────────────────────────────
   update:
@@ -1007,3 +1013,14 @@ jobs:
         with:
           name: benchmark-report
           path: BENCHMARK_REPORT_FLOW_*.md
+
+  # ── Enriched benchmark report (opt-in) ──────────────────────────
+  enriched-report:
+    needs: [params, generate-report]
+    if: always() && needs.params.outputs.generate-report == 'true'
+    uses: ./.github/workflows/agentic-lib-report.yml
+    with:
+      model: ${{ inputs.model }}
+      config-path: ${{ inputs.config-path }}
+      dry-run: ${{ inputs.dry-run || 'false' }}
+    secrets: inherit

package/.github/workflows/agentic-lib-report.yml

@@ -0,0 +1,248 @@
+# SPDX-License-Identifier: MIT
+# Copyright (C) 2025-2026 Polycode Limited
+# .github/workflows/agentic-lib-report.yml
+#
+# Benchmark report generator: mechanically gathers pipeline data for a time period,
+# optionally enriches via LLM, and commits the report to repo root on main.
+
+name: agentic-lib-report
+run-name: "agentic-lib-report [${{ github.ref_name }}]"
+
+on:
+  workflow_call:
+    inputs:
+      ref:
+        type: string
+        required: false
+        default: ""
+      period-start:
+        type: string
+        required: false
+        default: ""
+      period-end:
+        type: string
+        required: false
+        default: ""
+      model:
+        type: string
+        required: false
+        default: ""
+      config-path:
+        type: string
+        required: false
+        default: ""
+      dry-run:
+        type: string
+        required: false
+        default: "false"
+  workflow_dispatch:
+    inputs:
+      period-start:
+        description: "Report period start (ISO 8601, default: most recent init run)"
+        type: string
+        required: false
+        default: ""
+      period-end:
+        description: "Report period end (ISO 8601, default: now)"
+        type: string
+        required: false
+        default: ""
+      model:
+        description: "Copilot SDK model for LLM enrichment"
+        type: choice
+        required: false
+        default: ""
+        options:
+          - ""
+          - gpt-5-mini
+          - claude-sonnet-4
+          - gpt-4.1
+      dry-run:
+        description: "Skip commit and push"
+        type: boolean
+        required: false
+        default: false
+
+permissions:
+  contents: write
+  issues: read
+  pull-requests: read
+  actions: read
+
+env:
+  configPath: "agentic-lib.toml"
+
+jobs:
+  params:
+    runs-on: ubuntu-latest
+    outputs:
+      period-start: ${{ steps.resolve.outputs.period-start }}
+      period-end: ${{ steps.resolve.outputs.period-end }}
+      model: ${{ steps.resolve.outputs.model }}
+      config-path: ${{ steps.resolve.outputs.config-path }}
+      dry-run: ${{ steps.resolve.outputs.dry-run }}
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          sparse-checkout: ${{ env.configPath }}
+          sparse-checkout-cone-mode: false
+      - id: resolve
+        uses: actions/github-script@v8
+        with:
+          script: |
+            const fs = require('fs');
+            const configPath = '${{ env.configPath }}';
+            let toml = '';
+            if (fs.existsSync(configPath)) toml = fs.readFileSync(configPath, 'utf8');
+            const readToml = (key) => {
+              const m = toml.match(new RegExp(`^\\s*${key}\\s*=\\s*"([^"]*)"`, 'm'));
+              return m ? m[1] : '';
+            };
+            const resolve = (name, input, configKey, defaultValue) => {
+              let value = input || '';
+              let source = 'input';
+              if (!value && configKey) {
+                value = readToml(configKey);
+                source = value ? 'config' : '';
+              }
+              if (!value) {
+                value = defaultValue;
+                source = 'default';
+              }
+              const configVal = configKey ? readToml(configKey) : 'N/A';
+              core.info(`param ${name}: input='${input}' config='${configVal}' default='${defaultValue}' → '${value}' (source: ${source})`);
+              core.setOutput(name, value);
+              return value;
+            };
+            resolve('period-start', '${{ inputs.period-start }}', null, '');
+            resolve('period-end', '${{ inputs.period-end }}', null, '');
+            resolve('model', '${{ inputs.model }}', 'model', 'gpt-5-mini');
+            resolve('config-path', '${{ inputs.config-path }}', null, '${{ env.configPath }}');
+            resolve('dry-run', '${{ inputs.dry-run }}', null, 'false');
+
+  generate-report:
+    needs: [params]
+    runs-on: ubuntu-latest
+    outputs:
+      report-file: ${{ steps.write.outputs.report-file }}
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          ref: ${{ inputs.ref || 'main' }}
+          fetch-depth: 0
+          token: ${{ secrets.WORKFLOW_TOKEN || github.token }}
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: "24"
+
+      - name: Self-init (agentic-lib dev only)
+        if: hashFiles('scripts/self-init.sh') != '' && hashFiles('.github/agentic-lib/actions/agentic-step/package.json') == ''
+        run: bash scripts/self-init.sh
+
+      - name: Install agentic-step dependencies
+        working-directory: .github/agentic-lib/actions/agentic-step
+        run: |
+          npm ci
+          if [ -d "../../copilot" ]; then
+            ln -sf "$(pwd)/node_modules" ../../copilot/node_modules
+          fi
+
+      - name: Fetch state and logs from logs branch
+        run: |
+          git fetch origin agentic-lib-logs --depth=1 2>/dev/null || true
+          git show origin/agentic-lib-logs:agentic-lib-state.toml > agentic-lib-state.toml 2>/dev/null || echo "# no state" > agentic-lib-state.toml
+          # Fetch agent log files for context
+          git ls-tree origin/agentic-lib-logs --name-only 2>/dev/null | grep '^agent-log-' | sort > /tmp/log-files.txt || true
+          while read -r logfile; do
+            git show "origin/agentic-lib-logs:${logfile}" > "${logfile}" 2>/dev/null || true
+          done < /tmp/log-files.txt
+          # Fetch screenshot from logs branch
+          git show origin/agentic-lib-logs:SCREENSHOT_INDEX.png > SCREENSHOT_INDEX.png 2>/dev/null || true
+
+      - name: Fetch website from GitHub Pages
+        run: |
+          REPO_NAME="${{ github.event.repository.name }}"
+          OWNER="${{ github.repository_owner }}"
+          curl -sL --max-time 15 "https://${OWNER}.github.io/${REPO_NAME}/" > /tmp/website.html 2>/dev/null || echo "<html><body>No website available</body></html>" > /tmp/website.html
+          echo "Website fetched: $(wc -c < /tmp/website.html) bytes"
+
+      - name: Run report task
+        id: report
+        uses: ./.github/agentic-lib/actions/agentic-step
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          COPILOT_GITHUB_TOKEN: ${{ secrets.COPILOT_GITHUB_TOKEN }}
+        with:
+          task: "report"
+          config: ${{ needs.params.outputs.config-path }}
+          instructions: ".github/agents/agent-report.md"
+          model: ${{ needs.params.outputs.model }}
+          period-start: ${{ needs.params.outputs.period-start }}
+          period-end: ${{ needs.params.outputs.period-end }}
+
+      - name: Write report file
+        id: write
+        shell: bash
+        run: |
+          REPORT_NUM=$(printf "%03d" $(( $(ls BENCHMARK_REPORT_*.md 2>/dev/null | wc -l) + 1 )))
+          REPORT_FILE="BENCHMARK_REPORT_${REPORT_NUM}.md"
+          # The report content is in the action output; write it via env var to handle multiline
+          cat > "${REPORT_FILE}" << 'REPORT_EOF'
+          ${{ steps.report.outputs.report-content }}
+          REPORT_EOF
+          echo "report-file=${REPORT_FILE}" >> $GITHUB_OUTPUT
+          echo "Generated ${REPORT_FILE}"
+
+      - name: Commit and push report
+        if: needs.params.outputs.dry-run != 'true' && github.repository != 'xn-intenton-z2a/agentic-lib'
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add BENCHMARK_REPORT_*.md
+          git diff --staged --quiet && echo "No report to commit" && exit 0
+          git commit -m "report: benchmark report [skip ci]"
+          MAX_RETRIES=3
+          PUSH_SUCCESS=""
+          for attempt in $(seq 1 $MAX_RETRIES); do
+            case $attempt in
+              1)
+                echo "=== Attempt 1: rebase ==="
+                git pull --rebase origin main || {
+                  git rebase --abort 2>/dev/null || true
+                  sleep $((10 + RANDOM % 10))
+                  continue
+                }
+                ;;
+              2)
+                echo "=== Attempt 2: merge ==="
+                git pull --no-rebase origin main || {
+                  git merge --abort 2>/dev/null || true
+                  sleep $((20 + RANDOM % 10))
+                  continue
+                }
+                ;;
+              3)
+                echo "=== Attempt 3: merge -X theirs ==="
+                git pull -X theirs --no-rebase origin main || {
+                  git merge --abort 2>/dev/null || true
+                  sleep $((30 + RANDOM % 10))
+                  continue
+                }
+                ;;
+            esac
+            git push origin main && { PUSH_SUCCESS="true"; break; }
+            echo "Push failed on attempt $attempt"
+            sleep $((attempt * 10 + RANDOM % 10))
+          done
+          if [ "$PUSH_SUCCESS" != "true" ]; then
+            echo "::warning::Failed to push report after $MAX_RETRIES attempts — saved as artifact"
+          fi
+
+      - name: Upload report artifact
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: benchmark-report
+          path: BENCHMARK_REPORT_*.md
+          if-no-files-found: ignore

package/bin/agentic-lib.js

@@ -29,12 +29,13 @@ const command = args[0];
 const flags = args.slice(1);
 
 let initChanges = 0;
-const TASK_COMMANDS = ["transform", "maintain-features", "maintain-library", "fix-code"];
+const TASK_COMMANDS = ["transform", "maintain-features", "maintain-library", "fix-code", "report"];
 const TASK_AGENT_MAP = {
   "transform": "agent-issue-resolution",
   "fix-code": "agent-apply-fix",
   "maintain-features": "agent-maintain-features",
   "maintain-library": "agent-maintain-library",
+  "report": "agent-report",
 };
 const INIT_COMMANDS = ["init", "update", "reset"];
 const ALL_COMMANDS = [...INIT_COMMANDS, ...TASK_COMMANDS, "version", "iterate"];
@@ -55,6 +56,7 @@ Tasks (run Copilot SDK transformations):
   maintain-features    Generate feature files from mission
   maintain-library     Update library docs from SOURCES.md
   fix-code             Fix failing tests
+  report               Generate benchmark report for a time period
 
 Iterator:
   iterate              Single Copilot SDK session — reads, writes, tests, iterates autonomously
@@ -129,6 +131,10 @@ const prIdx = flags.indexOf("--pr");
 const prNumber = prIdx >= 0 ? parseInt(flags[prIdx + 1], 10) : 0;
 const discussionIdx = flags.indexOf("--discussion");
 const discussionUrl = discussionIdx >= 0 ? flags[discussionIdx + 1] : "";
+const periodStartIdx = flags.indexOf("--period-start");
+const periodStart = periodStartIdx >= 0 ? flags[periodStartIdx + 1] : "";
+const periodEndIdx = flags.indexOf("--period-end");
+const periodEnd = periodEndIdx >= 0 ? flags[periodEndIdx + 1] : "";
 
 // ─── Task Commands ───────────────────────────────────────────────────
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xn-intenton-z2a/agentic-lib",
-  "version": "7.4.41",
+  "version": "7.4.42",
   "description": "Agentic-lib Agentic Coding Systems SDK powering automated GitHub workflows.",
   "type": "module",
   "scripts": {

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

@@ -13,7 +13,7 @@ inputs:
   task:
     description: >
       The task to perform. One of: resolve-issue, fix-code, transform, maintain-features,
-      maintain-library, enhance-issue, review-issue, discussions, supervise
+      maintain-library, enhance-issue, review-issue, discussions, supervise, report
     required: true
   config:
     description: "Path to agentic-lib.toml configuration file"
@@ -50,6 +50,14 @@ inputs:
     description: "Copilot SDK model to use"
     required: false
     default: "gpt-5-mini"
+  period-start:
+    description: "Report period start (ISO 8601, default: most recent init run)"
+    required: false
+    default: ""
+  period-end:
+    description: "Report period end (ISO 8601, default: now)"
+    required: false
+    default: ""
 
 outputs:
   result:
@@ -66,6 +74,8 @@ outputs:
     description: "Argument for the chosen action (free text)"
   narrative:
     description: "One-sentence English narrative of what the task did and why"
+  report-content:
+    description: "Generated report content (report task only)"
 
 runs:
   using: "node24"

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

@@ -32,13 +32,14 @@ import { discussions } from "./tasks/discussions.js";
 import { supervise } from "./tasks/supervise.js";
 import { direct } from "./tasks/direct.js";
 import { implementationReview } from "./tasks/implementation-review.js";
+import { report } from "./tasks/report.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, "supervise": supervise, "direct": direct,
-  "implementation-review": implementationReview,
+  "implementation-review": implementationReview, "report": report,
 };
 
 async function run() {
@@ -88,6 +89,8 @@ async function run() {
       discussionUrl: core.getInput("discussion-url"),
       commentNodeId: core.getInput("comment-node-id"),
       commentCreatedAt: core.getInput("comment-created-at"),
+      periodStart: core.getInput("period-start"),
+      periodEnd: core.getInput("period-end"),
       octokit: github.getOctokit(process.env.GITHUB_TOKEN),
       repo: github.context.repo, github: github.context,
       logFilePath, screenshotFilePath,
@@ -102,7 +105,7 @@ async function run() {
 
     // Set outputs
     core.setOutput("result", result.outcome || "completed");
-    for (const [key, field] of [["pr-number", "prNumber"], ["tokens-used", "tokensUsed"], ["model", "model"], ["action", "action"], ["action-arg", "actionArg"], ["narrative", "narrative"]]) {
+    for (const [key, field] of [["pr-number", "prNumber"], ["tokens-used", "tokensUsed"], ["model", "model"], ["action", "action"], ["action-arg", "actionArg"], ["narrative", "narrative"], ["report-content", "reportContent"]]) {
       if (result[field]) core.setOutput(key, String(result[field]));
     }
 

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

@@ -0,0 +1,690 @@
+// SPDX-License-Identifier: GPL-3.0-only
+// Copyright (C) 2025-2026 Polycode Limited
+// tasks/report.js — Benchmark report: mechanical data gathering + optional LLM enrichment
+//
+// Gathers configuration, state, workflow runs, commits, issues, PRs, source code,
+// test files, agent logs, screenshots, and website HTML for a given time period.
+// Produces a structured markdown report comparable to what a Claude Code session
+// would write following ITERATION_BENCHMARKS_SIMPLE.md.
+
+import * as core from "@actions/core";
+import { existsSync, readFileSync, readdirSync } from "fs";
+import { readOptionalFile, scanDirectory, NARRATIVE_INSTRUCTION } from "../copilot.js";
+import { runCopilotSession } from "../../../copilot/copilot-session.js";
+import { createGitHubTools, createGitTools } from "../../../copilot/github-tools.js";
+
+/**
+ * Discover the most recent init workflow run timestamp via GitHub API.
+ */
+async function findLatestInitRun(octokit, owner, repo) {
+  try {
+    const { data } = await octokit.rest.actions.listWorkflowRunsForRepo({
+      owner, repo, per_page: 20,
+    });
+    const initRuns = data.workflow_runs
+      .filter(r => r.name && r.name.includes("agentic-lib-init"))
+      .sort((a, b) => new Date(b.created_at) - new Date(a.created_at));
+    if (initRuns.length > 0) return initRuns[0].created_at;
+  } catch (err) {
+    core.warning(`Could not find init runs: ${err.message}`);
+  }
+  return new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString();
+}
+
+/**
+ * List workflow runs in the period.
+ */
+async function listWorkflowRuns(octokit, owner, repo, since, until) {
+  const runs = [];
+  try {
+    const { data } = await octokit.rest.actions.listWorkflowRunsForRepo({
+      owner, repo, per_page: 50, created: `${since}..${until}`,
+    });
+    for (const r of data.workflow_runs) {
+      runs.push({
+        id: r.id, name: r.name, status: r.status, conclusion: r.conclusion,
+        created_at: r.created_at, updated_at: r.updated_at,
+        html_url: r.html_url,
+      });
+    }
+  } catch (err) {
+    core.warning(`Could not list workflow runs: ${err.message}`);
+  }
+  return runs;
+}
+
+/**
+ * List commits in the period.
+ */
+async function listCommits(octokit, owner, repo, since, until) {
+  const commits = [];
+  try {
+    const { data } = await octokit.rest.repos.listCommits({
+      owner, repo, since, until, per_page: 100,
+    });
+    for (const c of data) {
+      commits.push({
+        sha: c.sha.substring(0, 8),
+        message: c.commit.message.split("\n")[0],
+        author: c.commit.author?.name || "unknown",
+        date: c.commit.author?.date || "",
+      });
+    }
+  } catch (err) {
+    core.warning(`Could not list commits: ${err.message}`);
+  }
+  return commits;
+}
+
+/**
+ * List issues (open + recently closed) with bodies for context.
+ */
+async function listIssues(octokit, owner, repo, since) {
+  const issues = [];
+  for (const state of ["open", "closed"]) {
+    try {
+      const { data } = await octokit.rest.issues.listForRepo({
+        owner, repo, state, since, per_page: 50, sort: "created", direction: "desc",
+      });
+      for (const i of data) {
+        if (i.pull_request) continue;
+        issues.push({
+          number: i.number, state: i.state, title: i.title,
+          labels: i.labels.map(l => l.name).join(", "),
+          created_at: i.created_at, closed_at: i.closed_at,
+          body: i.body ? i.body.substring(0, 500) : "",
+        });
+      }
+    } catch { /* ignore */ }
+  }
+  return issues;
+}
+
+/**
+ * List PRs (merged + open) with diff stats.
+ */
+async function listPullRequests(octokit, owner, repo, since) {
+  const prs = [];
+  for (const state of ["closed", "open"]) {
+    try {
+      const { data } = await octokit.rest.pulls.list({
+        owner, repo, state, per_page: 30, sort: "created", direction: "desc",
+      });
+      for (const p of data) {
+        if (state === "closed" && !p.merged_at) continue;
+        if (new Date(p.created_at) < new Date(since)) continue;
+        prs.push({
+          number: p.number, title: p.title, state: p.state,
+          branch: p.head?.ref || "", merged_at: p.merged_at,
+          created_at: p.created_at,
+          additions: p.additions || 0, deletions: p.deletions || 0,
+          changed_files: p.changed_files || 0,
+        });
+      }
+    } catch { /* ignore */ }
+  }
+  return prs;
+}
+
+/**
+ * Read source file contents (with size limit per file).
+ */
+function readSourceFiles(config) {
+  const files = [];
+  const MAX_CHARS = 5000;
+  const srcPath = config.paths?.source?.path || "src/lib/main.js";
+  const srcDir = "src/lib";
+
+  // Collect all source files
+  const filePaths = [];
+  if (existsSync(srcPath)) filePaths.push(srcPath);
+  if (existsSync(srcDir)) {
+    try {
+      for (const f of readdirSync(srcDir)) {
+        const fp = `${srcDir}/${f}`;
+        if (fp === srcPath) continue;
+        if (f.endsWith(".js") || f.endsWith(".ts")) filePaths.push(fp);
+      }
+    } catch { /* ignore */ }
+  }
+
+  for (const fp of filePaths) {
+    try {
+      const content = readFileSync(fp, "utf8");
+      files.push({
+        file: fp,
+        lines: content.split("\n").length,
+        content: content.length > MAX_CHARS
+          ? content.substring(0, MAX_CHARS) + `\n... (truncated at ${MAX_CHARS} chars, total ${content.length})`
+          : content,
+      });
+    } catch { /* ignore */ }
+  }
+  return files;
+}
+
+/**
+ * Read test file contents (with size limit).
+ */
+function readTestFiles() {
+  const files = [];
+  const MAX_CHARS = 3000;
+  for (const dir of ["tests", "tests/unit", "__tests__"]) {
+    if (!existsSync(dir)) continue;
+    try {
+      for (const f of readdirSync(dir)) {
+        if (!f.endsWith(".test.js") && !f.endsWith(".test.ts") && !f.endsWith(".spec.js")) continue;
+        const fp = `${dir}/${f}`;
+        try {
+          const content = readFileSync(fp, "utf8");
+          files.push({
+            file: fp,
+            lines: content.split("\n").length,
+            content: content.length > MAX_CHARS
+              ? content.substring(0, MAX_CHARS) + `\n... (truncated)`
+              : content,
+          });
+        } catch { /* ignore */ }
+      }
+    } catch { /* ignore */ }
+  }
+  return files;
+}
+
+/**
+ * Read agent log file contents (last N logs).
+ */
+function readAgentLogs(logPrefix, maxLogs = 10) {
+  const logDir = logPrefix.includes("/") ? logPrefix.substring(0, logPrefix.lastIndexOf("/")) : ".";
+  const logBase = logPrefix.includes("/") ? logPrefix.substring(logPrefix.lastIndexOf("/") + 1) : logPrefix;
+  const logs = [];
+  try {
+    const allLogs = readdirSync(logDir)
+      .filter(f => f.startsWith(logBase) && f.endsWith(".md"))
+      .sort();
+    // Take the most recent N logs
+    const recent = allLogs.slice(-maxLogs);
+    for (const f of recent) {
+      const fp = logDir === "." ? f : `${logDir}/${f}`;
+      try {
+        const content = readFileSync(fp, "utf8");
+        // Extract key info: first 80 lines
+        const lines = content.split("\n");
+        logs.push({
+          file: f,
+          excerpt: lines.slice(0, 80).join("\n"),
+          totalLines: lines.length,
+        });
+      } catch { /* ignore */ }
+    }
+  } catch { /* ignore */ }
+  return logs;
+}
+
+/**
+ * Extract acceptance criteria from MISSION.md.
+ * Looks for bullet points, numbered lists, or "Acceptance Criteria" sections.
+ */
+function extractAcceptanceCriteria(missionContent) {
+  if (!missionContent) return [];
+  const criteria = [];
+  const lines = missionContent.split("\n");
+  let inCriteria = false;
+  for (const line of lines) {
+    const lower = line.toLowerCase();
+    if (lower.includes("acceptance") || lower.includes("criteria") || lower.includes("requirements")) {
+      inCriteria = true;
+      continue;
+    }
+    if (inCriteria && /^#+\s/.test(line) && !lower.includes("criteria")) {
+      inCriteria = false;
+    }
+    if (inCriteria) {
+      const match = line.match(/^[\s]*[-*]\s+(.+)/) || line.match(/^[\s]*\d+\.\s+(.+)/);
+      if (match) criteria.push(match[1].trim());
+    }
+  }
+  // If no explicit criteria section found, extract all bullet points as potential criteria
+  if (criteria.length === 0) {
+    for (const line of lines) {
+      const match = line.match(/^[\s]*[-*]\s+(.+)/);
+      if (match && match[1].length > 10) criteria.push(match[1].trim());
+    }
+  }
+  return criteria;
+}
+
+/**
+ * Read website HTML if available (placed by workflow).
+ */
+function readWebsiteHtml() {
+  const path = "/tmp/website.html";
+  if (existsSync(path)) {
+    const content = readFileSync(path, "utf8");
+    // Extract meaningful text content (strip tags, keep first 2000 chars)
+    const textContent = content
+      .replace(/<script[^>]*>[\s\S]*?<\/script>/gi, "")
+      .replace(/<style[^>]*>[\s\S]*?<\/style>/gi, "")
+      .replace(/<[^>]+>/g, " ")
+      .replace(/\s+/g, " ")
+      .trim();
+    return {
+      rawLength: content.length,
+      textSummary: textContent.substring(0, 2000),
+      hasContent: textContent.length > 100,
+    };
+  }
+  return null;
+}
+
+/**
+ * Build the mechanical report content.
+ */
+function buildMechanicalReport({
+  periodStart, periodEnd, config, stateContent, configContent,
+  workflowRuns, commits, issues, prs, sourceFiles, testFiles, agentLogs,
+  missionContent, acceptanceCriteria, websiteInfo, hasScreenshot, repo,
+}) {
+  const sections = [];
+  const now = new Date().toISOString().split("T")[0];
+
+  sections.push(`# Benchmark Report`);
+  sections.push(``);
+  sections.push(`**Date**: ${now}`);
+  sections.push(`**Repository**: ${repo.owner}/${repo.repo}`);
+  sections.push(`**Period**: ${periodStart} → ${periodEnd}`);
+  sections.push(`**Generated by**: agentic-lib-report (mechanical + LLM enrichment)`);
+  sections.push(``);
+  sections.push(`---`);
+
+  // ── Mission ──
+  sections.push(``);
+  sections.push(`## Mission`);
+  sections.push(``);
+  sections.push("```");
+  sections.push(missionContent || "(no MISSION.md found)");
+  sections.push("```");
+
+  if (acceptanceCriteria.length > 0) {
+    sections.push(``);
+    sections.push(`### Extracted Acceptance Criteria`);
+    sections.push(``);
+    for (let i = 0; i < acceptanceCriteria.length; i++) {
+      sections.push(`${i + 1}. ${acceptanceCriteria[i]}`);
+    }
+  }
+
+  // ── Configuration snapshot ──
+  sections.push(``);
+  sections.push(`## Configuration (agentic-lib.toml)`);
+  sections.push(``);
+  sections.push("```toml");
+  sections.push(configContent || "(not found)");
+  sections.push("```");
+
+  // ── State snapshot ──
+  sections.push(``);
+  sections.push(`## State (agentic-lib-state.toml)`);
+  sections.push(``);
+  sections.push("```toml");
+  sections.push(stateContent || "(not found)");
+  sections.push("```");
+
+  // ── Mission status ──
+  sections.push(``);
+  sections.push(`## Mission Status`);
+  sections.push(``);
+  const complete = existsSync("MISSION_COMPLETE.md");
+  const failed = existsSync("MISSION_FAILED.md");
+  sections.push(`| Signal | Present |`);
+  sections.push(`|--------|---------|`);
+  sections.push(`| MISSION_COMPLETE.md | ${complete ? "YES" : "NO"} |`);
+  sections.push(`| MISSION_FAILED.md | ${failed ? "YES" : "NO"} |`);
+
+  if (complete) {
+    sections.push(``);
+    sections.push("```");
+    sections.push(readFileSync("MISSION_COMPLETE.md", "utf8").trim());
+    sections.push("```");
+  }
+  if (failed) {
+    sections.push(``);
+    sections.push("```");
+    sections.push(readFileSync("MISSION_FAILED.md", "utf8").trim());
+    sections.push("```");
+  }
+
+  // ── Workflow runs (iteration timeline) ──
+  sections.push(``);
+  sections.push(`## Workflow Runs (${workflowRuns.length})`);
+  sections.push(``);
+  sections.push(`| # | Name | Conclusion | Started | Duration | URL |`);
+  sections.push(`|---|------|------------|---------|----------|-----|`);
+  for (let i = 0; i < workflowRuns.length; i++) {
+    const r = workflowRuns[i];
+    const startMs = new Date(r.created_at).getTime();
+    const endMs = new Date(r.updated_at).getTime();
+    const durationMin = Math.round((endMs - startMs) / 60000);
+    sections.push(`| ${i + 1} | ${r.name} | ${r.conclusion || r.status} | ${r.created_at} | ~${durationMin}min | [${r.id}](${r.html_url}) |`);
+  }
+
+  // ── Pull Requests (transformation evidence) ──
+  sections.push(``);
+  sections.push(`## Pull Requests (${prs.length})`);
+  sections.push(``);
+  sections.push(`| # | Branch | Title | Merged | +/- | Files |`);
+  sections.push(`|---|--------|-------|--------|-----|-------|`);
+  for (const p of prs) {
+    sections.push(`| #${p.number} | ${p.branch} | ${p.title} | ${p.merged_at || "open"} | +${p.additions}/-${p.deletions} | ${p.changed_files} |`);
+  }
+
+  // ── Commits timeline ──
+  sections.push(``);
+  sections.push(`## Commits Timeline (${commits.length})`);
+  sections.push(``);
+  sections.push(`| SHA | Date | Author | Message |`);
+  sections.push(`|-----|------|--------|---------|`);
+  for (const c of commits) {
+    sections.push(`| ${c.sha} | ${c.date} | ${c.author} | ${c.message} |`);
+  }
+
+  // ── Issues ──
+  sections.push(``);
+  sections.push(`## Issues (${issues.length})`);
+  sections.push(``);
+  sections.push(`| # | State | Labels | Title |`);
+  sections.push(`|---|-------|--------|-------|`);
+  for (const i of issues) {
+    sections.push(`| #${i.number} | ${i.state} | ${i.labels || "-"} | ${i.title} |`);
+  }
+
+  // ── Source Code (full contents) ──
+  sections.push(``);
+  sections.push(`## Source Code (${sourceFiles.length} files)`);
+  for (const s of sourceFiles) {
+    sections.push(``);
+    sections.push(`### ${s.file} (${s.lines} lines)`);
+    sections.push(``);
+    sections.push("```javascript");
+    sections.push(s.content);
+    sections.push("```");
+  }
+
+  // ── Test Files (full contents) ──
+  sections.push(``);
+  sections.push(`## Test Files (${testFiles.length} files)`);
+  for (const t of testFiles) {
+    sections.push(``);
+    sections.push(`### ${t.file} (${t.lines} lines)`);
+    sections.push(``);
+    sections.push("```javascript");
+    sections.push(t.content);
+    sections.push("```");
+  }
+
+  // ── Website & Screenshot ──
+  sections.push(``);
+  sections.push(`## Website & Screenshot`);
+  sections.push(``);
+  sections.push(`**Screenshot**: ${hasScreenshot ? "SCREENSHOT_INDEX.png captured (see artifacts)" : "not available"}`);
+  sections.push(``);
+  if (websiteInfo) {
+    sections.push(`**Website** (${websiteInfo.rawLength} bytes, ${websiteInfo.hasContent ? "has content" : "minimal content"}):`);
+    sections.push(``);
+    sections.push("```");
+    sections.push(websiteInfo.textSummary);
+    sections.push("```");
+  } else {
+    sections.push(`**Website**: not fetched`);
+  }
+
+  // ── Agent Log Narratives ──
+  sections.push(``);
+  sections.push(`## Agent Logs (${agentLogs.length} files)`);
+  for (const log of agentLogs) {
+    sections.push(``);
+    sections.push(`### ${log.file} (${log.totalLines} lines)`);
+    sections.push(``);
+    sections.push("```");
+    sections.push(log.excerpt);
+    if (log.totalLines > 80) sections.push(`... (${log.totalLines - 80} more lines)`);
+    sections.push("```");
+  }
+
+  // ── README ──
+  const readmeContent = readOptionalFile("README.md");
+  if (readmeContent) {
+    sections.push(``);
+    sections.push(`## README.md`);
+    sections.push(``);
+    const readmeLines = readmeContent.split("\n");
+    sections.push(readmeLines.slice(0, 60).join("\n"));
+    if (readmeLines.length > 60) sections.push(`\n... (${readmeLines.length - 60} more lines)`);
+  }
+
+  sections.push(``);
+  return sections.join("\n");
+}
+
+/**
+ * Report task handler.
+ */
+export async function report(context) {
+  const { config, octokit, repo, model } = context;
+  const owner = repo.owner;
+  const repoName = repo.repo;
+
+  // Resolve period
+  let periodStart = context.periodStart || "";
+  let periodEnd = context.periodEnd || new Date().toISOString();
+  if (!periodStart) {
+    periodStart = await findLatestInitRun(octokit, owner, repoName);
+    core.info(`period-start defaulted to latest init run: ${periodStart}`);
+  }
+  core.info(`Report period: ${periodStart} → ${periodEnd}`);
+
+  // Read config and state files
+  const configPath = config._configPath || "agentic-lib.toml";
+  const configContent = readOptionalFile(configPath);
+  const stateContent = readOptionalFile("agentic-lib-state.toml");
+  const missionContent = readOptionalFile("MISSION.md");
+  const acceptanceCriteria = extractAcceptanceCriteria(missionContent || "");
+
+  // Gather data from GitHub API
+  const workflowRuns = await listWorkflowRuns(octokit, owner, repoName, periodStart, periodEnd);
+  const commits = await listCommits(octokit, owner, repoName, periodStart, periodEnd);
+  const issues = await listIssues(octokit, owner, repoName, periodStart);
+  const prs = await listPullRequests(octokit, owner, repoName, periodStart);
+
+  // Gather local data: full file contents, not just stats
+  const sourceFiles = readSourceFiles(config);
+  const testFiles = readTestFiles();
+  const logPrefix = config.intentionBot?.logPrefix || "agent-log-";
+  const agentLogs = readAgentLogs(logPrefix);
+  const websiteInfo = readWebsiteHtml();
+  const hasScreenshot = existsSync("SCREENSHOT_INDEX.png");
+
+  core.info(`Gathered: ${workflowRuns.length} runs, ${commits.length} commits, ${issues.length} issues, ${prs.length} PRs, ${sourceFiles.length} source files, ${testFiles.length} test files, ${agentLogs.length} logs`);
+
+  // Build mechanical report
+  const mechanicalReport = buildMechanicalReport({
+    periodStart, periodEnd, config, stateContent, configContent,
+    workflowRuns, commits, issues, prs, sourceFiles, testFiles, agentLogs,
+    missionContent, acceptanceCriteria, websiteInfo, hasScreenshot, repo,
+  });
+
+  // Optional LLM enrichment (if Copilot token available)
+  let enrichedAnalysis = null;
+  let tokensUsed = 0;
+  let resultModel = model;
+  if (process.env.COPILOT_GITHUB_TOKEN) {
+    try {
+      const agentPrompt = context.instructions || "";
+      const tools = [
+        ...createGitHubTools(octokit, owner, repoName),
+        ...createGitTools(),
+        {
+          name: "report_analysis",
+          description: "Record your enriched analysis of the benchmark data. Call exactly once.",
+          parameters: {
+            type: "object",
+            properties: {
+              summary: { type: "string", description: "Executive summary of the benchmark period" },
+              findings: {
+                type: "array",
+                items: {
+                  type: "object",
+                  properties: {
+                    id: { type: "string" },
+                    title: { type: "string" },
+                    severity: { type: "string", enum: ["POSITIVE", "CONCERN", "REGRESSION"] },
+                    description: { type: "string" },
+                  },
+                  required: ["id", "title", "severity", "description"],
+                },
+              },
+              recommendations: { type: "array", items: { type: "string" } },
+              acceptance_criteria: {
+                type: "array",
+                items: {
+                  type: "object",
+                  properties: {
+                    criterion: { type: "string" },
+                    status: { type: "string", enum: ["PASS", "FAIL", "NOT TESTED"] },
+                    evidence: { type: "string" },
+                  },
+                  required: ["criterion", "status", "evidence"],
+                },
+              },
+              iteration_narrative: { type: "string", description: "Narrative describing each iteration: what happened, what changed, what the agent decided" },
+              scenario_summary: {
+                type: "object",
+                properties: {
+                  total_iterations: { type: "number" },
+                  transforms: { type: "number" },
+                  convergence_iteration: { type: "number", description: "Which iteration reached mission-complete (0 if not reached)" },
+                  final_source_lines: { type: "number" },
+                  final_test_count: { type: "number" },
+                  acceptance_pass_count: { type: "string", description: "e.g. '7/8 PASS'" },
+                  total_tokens: { type: "number" },
+                },
+              },
+            },
+            required: ["summary", "findings", "recommendations"],
+          },
+          handler: async (args) => {
+            enrichedAnalysis = args;
+            return "Analysis recorded.";
+          },
+        },
+      ];
+
+      const userPrompt = [
+        "Analyse the following mechanical benchmark data and produce an enriched report.",
+        "",
+        "You MUST:",
+        "1. Verify each acceptance criterion by reading the actual source code (use read_file).",
+        "2. For each workflow run, determine if it produced a transform (check merged PRs in the same time window).",
+        "3. Read issue bodies (use get_issue) to understand what work was requested and completed.",
+        "4. Produce a narrative timeline: for each iteration, what happened, what changed, what the agent decided.",
+        "5. Assess code quality by reading the source — is it clean, correct, well-tested?",
+        "",
+        "=== MECHANICAL DATA ===",
+        mechanicalReport,
+      ].join("\n");
+
+      const result = await runCopilotSession({
+        workspacePath: ".",
+        model: model || config.model || "gpt-5-mini",
+        tuning: config.tuning || {},
+        timeoutMs: 180000,
+        agentPrompt,
+        userPrompt,
+        tools,
+      });
+      tokensUsed = result.tokensUsed || 0;
+      resultModel = result.model || model;
+    } catch (err) {
+      core.warning(`LLM enrichment failed (report will be mechanical only): ${err.message}`);
+    }
+  }
+
+  // Compose final report
+  let finalReport = mechanicalReport;
+  if (enrichedAnalysis) {
+    const enrichedSections = [];
+    enrichedSections.push(``);
+    enrichedSections.push(`---`);
+    enrichedSections.push(``);
+    enrichedSections.push(`## Analysis (LLM-enriched)`);
+    enrichedSections.push(``);
+    enrichedSections.push(enrichedAnalysis.summary || "");
+    enrichedSections.push(``);
+
+    if (enrichedAnalysis.iteration_narrative) {
+      enrichedSections.push(`### Iteration Narrative`);
+      enrichedSections.push(``);
+      enrichedSections.push(enrichedAnalysis.iteration_narrative);
+      enrichedSections.push(``);
+    }
+
+    if (enrichedAnalysis.acceptance_criteria?.length) {
+      enrichedSections.push(`### Acceptance Criteria`);
+      enrichedSections.push(``);
+      enrichedSections.push(`| Criterion | Status | Evidence |`);
+      enrichedSections.push(`|-----------|--------|----------|`);
+      for (const ac of enrichedAnalysis.acceptance_criteria) {
+        enrichedSections.push(`| ${ac.criterion} | ${ac.status} | ${ac.evidence} |`);
+      }
+      enrichedSections.push(``);
+    }
+
+    if (enrichedAnalysis.scenario_summary) {
+      const s = enrichedAnalysis.scenario_summary;
+      enrichedSections.push(`### Scenario Summary`);
+      enrichedSections.push(``);
+      enrichedSections.push(`| Metric | Value |`);
+      enrichedSections.push(`|--------|-------|`);
+      if (s.total_iterations != null) enrichedSections.push(`| Total iterations | ${s.total_iterations} |`);
+      if (s.transforms != null) enrichedSections.push(`| Transforms | ${s.transforms} |`);
+      if (s.convergence_iteration) enrichedSections.push(`| Convergence | Iteration ${s.convergence_iteration} |`);
+      if (s.final_source_lines) enrichedSections.push(`| Final source lines | ${s.final_source_lines} |`);
+      if (s.final_test_count) enrichedSections.push(`| Final test count | ${s.final_test_count} |`);
+      if (s.acceptance_pass_count) enrichedSections.push(`| Acceptance criteria | ${s.acceptance_pass_count} |`);
+      if (s.total_tokens) enrichedSections.push(`| Total tokens | ${s.total_tokens} |`);
+      enrichedSections.push(``);
+    }
+
+    if (enrichedAnalysis.findings?.length) {
+      enrichedSections.push(`### Findings`);
+      enrichedSections.push(``);
+      for (const f of enrichedAnalysis.findings) {
+        enrichedSections.push(`#### ${f.id}: ${f.title} (${f.severity})`);
+        enrichedSections.push(``);
+        enrichedSections.push(f.description);
+        enrichedSections.push(``);
+      }
+    }
+
+    if (enrichedAnalysis.recommendations?.length) {
+      enrichedSections.push(`### Recommendations`);
+      enrichedSections.push(``);
+      for (let i = 0; i < enrichedAnalysis.recommendations.length; i++) {
+        enrichedSections.push(`${i + 1}. ${enrichedAnalysis.recommendations[i]}`);
+      }
+      enrichedSections.push(``);
+    }
+
+    finalReport += enrichedSections.join("\n");
+  }
+
+  const narrative = `Generated benchmark report for ${repo.owner}/${repo.repo} covering ${periodStart} to ${periodEnd} (${workflowRuns.length} runs, ${commits.length} commits, ${issues.length} issues)`;
+
+  return {
+    outcome: "report-generated",
+    narrative,
+    reportContent: finalReport,
+    tokensUsed,
+    model: resultModel,
+  };
+}

package/src/seeds/zero-package.json

@@ -17,7 +17,7 @@
   "author": "",
   "license": "MIT",
   "dependencies": {
-    "@xn-intenton-z2a/agentic-lib": "^7.4.41"
+    "@xn-intenton-z2a/agentic-lib": "^7.4.42"
   },
   "devDependencies": {
     "@playwright/test": "^1.58.0",