loopgen 0.4.0 → 0.6.0

package/README.md

@@ -181,6 +181,32 @@ npm run loopgen -- run test-repair . --mode driven --adapter ollama --ollama-mod
 - 需要干净的 git 工作区(`--allow-dirty` 可跳过);`--dry-run` 只预览第一轮提议、不写文件。
 - 诚实说明:**有界 + 强制 + 验证 + 留证 —— 不是沙箱。** 模型仍会提议,loopgen 负责框住、限制、验证、留证。
 
+#### 治理 —— 把审计账本变成团队证据(`loopgen audit`)
+
+每次 `loopgen run` 都会往本仓库的、带哈希链的 `.loopgen/audit.jsonl` 追加一条。`audit` 命令族把这些账本
+变成团队级、可用于合规的证据,以及一个 CI 闸门 —— local-first、无需服务器:
+
+```bash
+npm run loopgen -- audit verify                  # 校验哈希链是否完好(防篡改)
+npm run loopgen -- audit summary                 # 单仓库:通过率、按 loop、违规数
+npm run loopgen -- audit aggregate ../repos --html gov.html --report gov.md   # 聚合多个仓库/开发者
+npm run loopgen -- audit check --require test-repair --require-no-violations --require-chain   # CI 闸门
+```
+
+`aggregate` 会在给定的文件/目录里找 `audit.jsonl`,合并成一份汇总,并可生成一个**自包含的 HTML 治理看板**
+(直接打开即可,无需服务器)和一份 markdown 报告。`check` 是**合并闸门**:当某个必需 loop 没有通过记录、
+有改动碰了禁止路径、或链断了,就以非 0 退出 —— 接进 CI 即可在「证据缺失/不足」时挡住合并。
+
+也有现成的 GitHub Action(会把治理汇总写进 job summary,并在策略违规时让 job 失败):
+
+```yaml
+- uses: Nagiici/Loopgen/.github/actions/audit-check@v0.6.0
+  with:
+    require: test-repair,ci-failure-repair
+    require-no-violations: "true"
+    require-chain: "true"
+```
+
 可用 adapter：
 
 - `agents-md`：通用 `AGENTS.md`，可被 Claude Code、Codex、Cursor、Copilot、Gemini CLI、Aider 等读取
@@ -436,6 +462,34 @@ audit + a proof report with the full iteration history (including every blocked
 - Honest scope: **bounded + enforced + verified + proven — not a sandbox.** The model still proposes; loopgen
   bounds, confines, verifies, and proves.
 
+#### Governance — turn the ledgers into team evidence (`loopgen audit`)
+
+Every `loopgen run` appends to a per-repo, hash-chained `.loopgen/audit.jsonl`. The `audit` commands turn
+those ledgers into team-level, compliance-ready evidence and a CI gate — local-first, no server:
+
+```bash
+npm run loopgen -- audit verify                  # prove the hash chain is intact (tamper check)
+npm run loopgen -- audit summary                 # one repo: pass rate, by loop, violations
+npm run loopgen -- audit aggregate ../repos --html gov.html --report gov.md   # roll up many repos/devs
+npm run loopgen -- audit check --require test-repair --require-no-violations --require-chain   # CI gate
+```
+
+`aggregate` scans the given files/directories for `audit.jsonl`, merges them into one rollup, and can write
+a self-contained **HTML governance dashboard** (just open it — no server) plus a markdown report. `check` is
+the **merge gate**: it exits non-zero if a required loop has no passing run, a run touched forbidden paths, or
+the chain is broken — wire it into CI to block merges on missing or insufficient proof.
+
+There's a ready-made GitHub Action (it renders the governance rollup into the job summary and fails the job
+on policy violations):
+
+```yaml
+- uses: Nagiici/Loopgen/.github/actions/audit-check@v0.6.0
+  with:
+    require: test-repair,ci-failure-repair
+    require-no-violations: "true"
+    require-chain: "true"
+```
+
 Available adapters:
 
 - `agents-md` — one `AGENTS.md` read by Claude Code, Codex, Cursor, Copilot, Gemini CLI, Aider, and more

package/dist/cli.js

@@ -13,6 +13,10 @@ import { TEMPLATE_DEFINITIONS } from "./core/templates.js";
 import { startLoopgenServer } from "./server.js";
 import { DEFAULT_ADAPTER_IDS, parseAdapterIds } from "./core/adapters.js";
 import { runLoop } from "./core/runner.js";
+import { readAuditLog, verifyAuditChain } from "./core/audit.js";
+import { buildSummary, collectAuditFiles, evaluatePolicy } from "./core/governance.js";
+import { renderGovernanceHtml, renderGovernanceMarkdown } from "./core/governance-report.js";
+import { promises as fsp } from "node:fs";
 const PROJECT_MANIFESTS = [
     "package.json",
     "pyproject.toml",
@@ -191,6 +195,90 @@ program
     }
     process.exitCode = result.passed ? 0 : 1;
 });
+const audit = program.command("audit").description("Inspect, aggregate, and gate on loopgen audit logs (governance).");
+audit
+    .command("verify")
+    .argument("[project]", "project directory", ".")
+    .description("Verify the audit hash chain is intact (tamper check).")
+    .action(async (project) => {
+    const entries = await readAuditLog(path.resolve(project));
+    const chain = verifyAuditChain(entries);
+    if (chain.valid) {
+        console.log(`Audit chain valid (${entries.length} entries).`);
+    }
+    else {
+        console.log(`Audit chain BROKEN at entry ${chain.brokenAt}.`);
+        process.exitCode = 1;
+    }
+});
+audit
+    .command("summary")
+    .argument("[project]", "project directory", ".")
+    .option("--json", "print the summary as JSON")
+    .description("Summarize one repo's audit log (pass rate, by loop, violations).")
+    .action(async (project, options) => {
+    const root = path.resolve(project);
+    const { summary } = await buildSummary([{ label: ".", filePath: path.join(root, ".loopgen", "audit.jsonl") }]);
+    if (options.json)
+        console.log(JSON.stringify(summary, null, 2));
+    else
+        printSummary(summary);
+});
+audit
+    .command("aggregate")
+    .argument("<paths...>", "audit.jsonl files or directories to scan")
+    .option("--json", "print the rollup as JSON")
+    .option("--report <file>", "write a markdown governance report")
+    .option("--html <file>", "write a self-contained HTML governance dashboard")
+    .description("Aggregate many devs'/repos' audit logs into one team governance rollup.")
+    .action(async (paths, options) => {
+    const files = await collectAuditFiles(paths);
+    if (!files.length) {
+        console.error("No audit.jsonl files found in the given paths.");
+        process.exitCode = 1;
+        return;
+    }
+    const { summary } = await buildSummary(files.map((file) => ({ label: relLabel(file), filePath: file })));
+    if (options.report) {
+        await fsp.writeFile(options.report, renderGovernanceMarkdown(summary), "utf8");
+        console.log(`Wrote ${options.report}`);
+    }
+    if (options.html) {
+        await fsp.writeFile(options.html, renderGovernanceHtml(summary), "utf8");
+        console.log(`Wrote ${options.html}`);
+    }
+    if (options.json)
+        console.log(JSON.stringify(summary, null, 2));
+    else
+        printSummary(summary);
+});
+audit
+    .command("check")
+    .argument("[project]", "project directory", ".")
+    .option("--require <loops>", "comma-separated loop ids that must have a passing run")
+    .option("--since <iso>", "only consider runs at/after this ISO timestamp")
+    .option("--require-no-violations", "fail if any run modified forbidden paths")
+    .option("--require-chain", "fail if the audit chain is broken")
+    .description("Gate CI/merge on the audit log; exits 1 if the policy is not satisfied.")
+    .action(async (project, options) => {
+    const entries = await readAuditLog(path.resolve(project));
+    const policy = {
+        requireLoops: options.require ? options.require.split(",").map((item) => item.trim()).filter(Boolean) : undefined,
+        since: options.since,
+        requireNoViolations: options.requireNoViolations,
+        requireChainValid: options.requireChain
+    };
+    const result = evaluatePolicy(entries, policy);
+    if (result.ok) {
+        console.log(`Policy satisfied (${result.checked} run(s) checked).`);
+    }
+    else {
+        console.log("Policy FAILED:");
+        for (const failure of result.failures)
+            console.log(`  - ${failure}`);
+        process.exitCode = 1;
+    }
+});
 program.parseAsync(process.argv).catch((error) => {
     console.error(error instanceof Error ? error.message : String(error));
     process.exitCode = 1;
@@ -265,6 +353,21 @@ function printRunResult(result) {
     if (!result.dryRun)
         console.log(`  audit: .loopgen/audit.jsonl (${result.entry.hash.slice(0, 12)}…)`);
 }
+function printSummary(summary) {
+    console.log(`Runs: ${summary.total} (${summary.passed} pass / ${summary.failed} fail) — ${Math.round(summary.passRate * 100)}%`);
+    console.log(`Modes: referee ${summary.byMode.referee}, driven ${summary.byMode.driven}`);
+    console.log(`Chain: ${summary.chain.valid ? "valid" : `BROKEN at ${summary.chain.brokenAt}`}`);
+    console.log(`Forbidden violations: ${summary.forbiddenViolationRuns} run(s); blocked attempts (prevented): ${summary.blockedAttempts}`);
+    for (const [loop, stat] of Object.entries(summary.byLoop).sort((a, b) => b[1].total - a[1].total)) {
+        console.log(`  ${loop}: ${stat.passed}/${stat.total} passed`);
+    }
+    if (summary.sources.length > 1) {
+        console.log(`Sources: ${summary.sources.length} (${summary.sources.filter((source) => source.chainValid).length} with a valid chain)`);
+    }
+}
+function relLabel(file) {
+    return path.relative(process.cwd(), file) || file;
+}
 function formatCommands(commands) {
     const entries = Object.entries(commands).filter(([, command]) => command);
     return entries.length ? entries.map(([name, command]) => `${name}=${command}`).join(", ") : "none inferred";

package/dist/core/audit.js

@@ -20,11 +20,8 @@ function canonicalize(value) {
 export function hashEntry(input, prevHash) {
     return createHash("sha256").update(canonicalize({ ...input, prevHash })).digest("hex");
 }
-async function readRaw(projectRoot) {
-    return fs.readFile(path.join(projectRoot, AUDIT_FILE), "utf8").catch(() => undefined);
-}
-export async function readAuditLog(projectRoot) {
-    const raw = await readRaw(projectRoot);
+export async function readAuditFile(filePath) {
+    const raw = await fs.readFile(filePath, "utf8").catch(() => undefined);
     if (!raw)
         return [];
     return raw
@@ -33,6 +30,9 @@ export async function readAuditLog(projectRoot) {
         .filter(Boolean)
         .map((line) => JSON.parse(line));
 }
+export async function readAuditLog(projectRoot) {
+    return readAuditFile(path.join(projectRoot, AUDIT_FILE));
+}
 export async function appendAuditEntry(projectRoot, input) {
     const existing = await readAuditLog(projectRoot);
     const prevHash = existing.length ? existing[existing.length - 1].hash : null;

package/dist/core/governance-report.js

@@ -0,0 +1,111 @@
+const pct = (value) => `${Math.round(value * 100)}%`;
+export function renderGovernanceMarkdown(summary) {
+    const loopRows = Object.entries(summary.byLoop)
+        .sort((a, b) => b[1].total - a[1].total)
+        .map(([loop, stat]) => `| \`${loop}\` | ${stat.total} | ${stat.passed} | ${pct(rate(stat))} |`)
+        .join("\n");
+    const actorRows = Object.entries(summary.byActor)
+        .sort((a, b) => b[1].total - a[1].total)
+        .map(([actor, stat]) => `| ${actor} | ${stat.total} | ${stat.passed} | ${pct(rate(stat))} |`)
+        .join("\n");
+    const sourceRows = summary.sources
+        .map((source) => `| ${source.label} | ${source.entries} | ${source.chainValid ? "valid" : "BROKEN"} |`)
+        .join("\n");
+    return `# loopgen governance report
+
+- Runs: **${summary.total}** (${summary.passed} passed / ${summary.failed} failed) — pass rate **${pct(summary.passRate)}**
+- Window: ${summary.firstAt ?? "—"} → ${summary.lastAt ?? "—"}
+- Modes: referee ${summary.byMode.referee} · driven ${summary.byMode.driven}
+- Chain integrity: ${summary.chain.valid ? "**valid**" : `**BROKEN** (entry ${summary.chain.brokenAt})`}
+- Forbidden-path violations: **${summary.forbiddenViolationRuns}** run(s)
+- Blocked attempts (driven, prevented at apply time): **${summary.blockedAttempts}**
+
+## By loop
+
+| loop | runs | passed | pass rate |
+|---|---|---|---|
+${loopRows || "| — | 0 | 0 | 0% |"}
+
+## By actor
+
+| actor | runs | passed | pass rate |
+|---|---|---|---|
+${actorRows || "| — | 0 | 0 | 0% |"}
+
+## Sources
+
+| source | entries | chain |
+|---|---|---|
+${sourceRows || "| — | 0 | — |"}
+`;
+}
+export function renderGovernanceHtml(summary) {
+    const loopRows = Object.entries(summary.byLoop)
+        .sort((a, b) => b[1].total - a[1].total)
+        .map(([loop, stat]) => row(loop, stat.total, stat.passed))
+        .join("");
+    const actorRows = Object.entries(summary.byActor)
+        .sort((a, b) => b[1].total - a[1].total)
+        .map(([actor, stat]) => row(actor, stat.total, stat.passed))
+        .join("");
+    const sourceRows = summary.sources
+        .map((source) => `<tr><td>${esc(source.label)}</td><td>${source.entries}</td><td>${source.chainValid ? "valid" : '<b class="bad">BROKEN</b>'}</td></tr>`)
+        .join("");
+    return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
+<title>loopgen governance</title>
+<style>
+:root{--paper:#f4efe4;--ink:#1a1714;--muted:#7a7064;--line:#d8cfbd;--rule:#b9ad96;--ok:#4a6b3f;--bad:#c2362b;--surface:#fbf7ee}
+@media(prefers-color-scheme:dark){:root{--paper:#17150f;--ink:#ece4d4;--muted:#948b78;--line:#322d22;--rule:#4a4334;--ok:#8fb079;--bad:#e0524a;--surface:#221e16}}
+*{box-sizing:border-box}
+body{margin:0;background:var(--paper);color:var(--ink);font:15px/1.5 ui-sans-serif,system-ui,sans-serif}
+.wrap{max-width:920px;margin:0 auto;padding:40px 24px}
+h1{font:500 30px/1.1 Georgia,"Times New Roman",serif;margin:0}
+.sub{color:var(--muted);font-size:12px;letter-spacing:.16em;text-transform:uppercase;margin-top:6px}
+hr{border:0;border-top:2px solid var(--ink);margin:16px 0 28px}
+.cards{display:grid;grid-template-columns:repeat(auto-fit,minmax(150px,1fr));gap:0;border:1px solid var(--line);margin-bottom:28px}
+.card{padding:16px 18px;border-right:1px solid var(--line)}
+.card:last-child{border-right:0}
+.card .k{color:var(--muted);font-size:11px;letter-spacing:.1em;text-transform:uppercase}
+.card .v{font:500 26px/1.1 Georgia,serif;margin-top:6px}
+.bar{height:6px;background:var(--line);margin-top:10px}
+.bar>span{display:block;height:6px;background:var(--ok)}
+h2{font:500 18px/1.1 Georgia,serif;margin:28px 0 10px;padding-bottom:8px;border-bottom:1px solid var(--line)}
+table{width:100%;border-collapse:collapse;font-size:14px}
+th{text-align:left;color:var(--muted);font-size:11px;letter-spacing:.08em;text-transform:uppercase;font-weight:500;padding:8px 6px;border-bottom:1px solid var(--rule)}
+td{padding:9px 6px;border-bottom:1px solid var(--line)}
+code{font-family:"IBM Plex Mono",monospace;font-size:13px}
+.good{color:var(--ok)}.bad{color:var(--bad)}
+.note{color:var(--muted);font-size:12px;margin-top:28px;border-top:1px solid var(--line);padding-top:14px}
+</style></head>
+<body><div class="wrap">
+<h1>loopgen governance</h1>
+<div class="sub">audit rollup · ${esc(summary.firstAt ?? "—")} → ${esc(summary.lastAt ?? "—")}</div>
+<hr>
+<div class="cards">
+  <div class="card"><div class="k">Runs</div><div class="v">${summary.total}</div></div>
+  <div class="card"><div class="k">Pass rate</div><div class="v">${pct(summary.passRate)}</div><div class="bar"><span style="width:${pct(summary.passRate)}"></span></div></div>
+  <div class="card"><div class="k">Forbidden violations</div><div class="v ${summary.forbiddenViolationRuns ? "bad" : "good"}">${summary.forbiddenViolationRuns}</div></div>
+  <div class="card"><div class="k">Blocked (prevented)</div><div class="v">${summary.blockedAttempts}</div></div>
+  <div class="card"><div class="k">Chain</div><div class="v ${summary.chain.valid ? "good" : "bad"}">${summary.chain.valid ? "valid" : "BROKEN"}</div></div>
+</div>
+<h2>By loop</h2>
+<table><thead><tr><th>Loop</th><th>Runs</th><th>Passed</th><th>Pass rate</th></tr></thead><tbody>${loopRows || '<tr><td colspan="4">No runs.</td></tr>'}</tbody></table>
+<h2>By actor</h2>
+<table><thead><tr><th>Actor</th><th>Runs</th><th>Passed</th><th>Pass rate</th></tr></thead><tbody>${actorRows || '<tr><td colspan="4">No runs.</td></tr>'}</tbody></table>
+<h2>Sources</h2>
+<table><thead><tr><th>Source</th><th>Entries</th><th>Chain</th></tr></thead><tbody>${sourceRows || '<tr><td colspan="3">No sources.</td></tr>'}</tbody></table>
+<div class="note">Generated by loopgen from hash-chained <code>.loopgen/audit.jsonl</code> ledgers. Local-first — open this file directly; no server. A broken chain means a ledger was edited in place.</div>
+</div></body></html>
+`;
+}
+function row(label, total, passed) {
+    const r = rate({ total, passed });
+    return `<tr><td><code>${esc(label)}</code></td><td>${total}</td><td>${passed}</td><td><span class="${r === 1 ? "good" : r < 0.5 ? "bad" : ""}">${pct(r)}</span></td></tr>`;
+}
+function rate(stat) {
+    return stat.total ? stat.passed / stat.total : 0;
+}
+function esc(value) {
+    return value.replace(/[&<>"]/g, (char) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" })[char] ?? char);
+}

package/dist/core/governance.js

@@ -0,0 +1,127 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { readAuditFile, verifyAuditChain } from "./audit.js";
+// Resolve CLI inputs (files or directories) into a deduped list of audit.jsonl paths.
+export async function collectAuditFiles(inputs) {
+    const found = [];
+    for (const input of inputs) {
+        const stat = await fs.stat(input).catch(() => undefined);
+        if (!stat)
+            continue;
+        if (stat.isFile()) {
+            found.push(path.resolve(input));
+        }
+        else if (stat.isDirectory()) {
+            await walk(path.resolve(input), found, 0);
+        }
+    }
+    return [...new Set(found)];
+}
+async function walk(dir, found, depth) {
+    if (depth > 6)
+        return;
+    const entries = await fs.readdir(dir, { withFileTypes: true }).catch(() => []);
+    for (const entry of entries) {
+        if (entry.name === "node_modules" || entry.name === ".git")
+            continue;
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            await walk(full, found, depth + 1);
+        }
+        else if (entry.name === "audit.jsonl") {
+            found.push(full);
+        }
+    }
+}
+export async function buildSummary(sources) {
+    const all = [];
+    const sourceMeta = [];
+    let allChainsValid = true;
+    let brokenAt;
+    for (const source of sources) {
+        const entries = await readAuditFile(source.filePath);
+        const chain = verifyAuditChain(entries);
+        if (!chain.valid) {
+            allChainsValid = false;
+            if (brokenAt === undefined)
+                brokenAt = chain.brokenAt;
+        }
+        sourceMeta.push({ label: source.label, entries: entries.length, chainValid: chain.valid });
+        all.push(...entries);
+    }
+    return { summary: summarizeEntries(all, sourceMeta, { valid: allChainsValid, brokenAt }), entries: all };
+}
+function summarizeEntries(entries, sources, chain) {
+    const byLoop = {};
+    const byActor = {};
+    const byMode = { referee: 0, driven: 0 };
+    let passed = 0;
+    let blockedAttempts = 0;
+    let forbiddenViolationRuns = 0;
+    let firstAt;
+    let lastAt;
+    for (const entry of entries) {
+        if (entry.passed)
+            passed += 1;
+        if (entry.mode === "driven")
+            byMode.driven += 1;
+        else
+            byMode.referee += 1;
+        byLoop[entry.loopId] ??= { total: 0, passed: 0 };
+        byLoop[entry.loopId].total += 1;
+        if (entry.passed)
+            byLoop[entry.loopId].passed += 1;
+        const actor = entry.actor.user ?? "unknown";
+        byActor[actor] ??= { total: 0, passed: 0 };
+        byActor[actor].total += 1;
+        if (entry.passed)
+            byActor[actor].passed += 1;
+        if (!entry.forbidden.ok)
+            forbiddenViolationRuns += 1;
+        if (entry.driven) {
+            for (const attempt of entry.driven.attempts)
+                blockedAttempts += attempt.blocked.length;
+        }
+        if (!firstAt || entry.timestamp < firstAt)
+            firstAt = entry.timestamp;
+        if (!lastAt || entry.timestamp > lastAt)
+            lastAt = entry.timestamp;
+    }
+    const total = entries.length;
+    return {
+        total,
+        passed,
+        failed: total - passed,
+        passRate: total ? passed / total : 0,
+        byLoop,
+        byMode,
+        byActor,
+        blockedAttempts,
+        forbiddenViolationRuns,
+        firstAt,
+        lastAt,
+        chain,
+        sources
+    };
+}
+// Evaluate a team policy against a repo's audit entries — the CI / merge gate.
+export function evaluatePolicy(entries, policy) {
+    const failures = [];
+    const scoped = policy.since ? entries.filter((entry) => entry.timestamp >= policy.since) : entries;
+    if (policy.requireChainValid) {
+        const chain = verifyAuditChain(entries);
+        if (!chain.valid)
+            failures.push(`audit chain is broken at entry ${chain.brokenAt}`);
+    }
+    if (policy.requireNoViolations) {
+        const violations = scoped.filter((entry) => !entry.forbidden.ok);
+        if (violations.length)
+            failures.push(`${violations.length} run(s) modified forbidden paths`);
+    }
+    for (const loopId of policy.requireLoops ?? []) {
+        const ok = scoped.some((entry) => entry.loopId === loopId && entry.passed);
+        if (!ok)
+            failures.push(`no passing run found for required loop "${loopId}"`);
+    }
+    return { ok: failures.length === 0, failures, checked: scoped.length };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loopgen",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Generate bounded, verifiable AI agent configs for Codex, Claude, Cursor, and local models — with safety rails baked in.",
   "type": "module",
   "engines": {