done-done-axi 0.4.1 → 0.4.2

package/README.md

@@ -162,6 +162,7 @@ Run `done-done` with no arguments to see the current config and the next step.
 - 👀 **Shows the outcome** (always): `check`, `receipt` and `verify` start done-done's own judge, a fresh, tools-off agent on your own plan or key (Claude Code, opencode, pi or Gemini CLI, or your own OpenAI API key), to say whether each capture is the right screen for the claim (and each text capture, such as a log, JSON or CLI output, the right output), and a wrong one fails. There is no way to turn it off: done-done gives no result without it. The checks above never pass on their own, and a check that cites only files the judge cannot read (a video) stops before the judge, with exit 2. You choose the judge route (`done-done init --judge <agent> --judge-model <model>`, or pick it from the list done-done shows in a terminal; `done-done check --judge <route>` overrides it for one call); for a Pi judge with no explicit model, done-done defaults to `openai-codex/gpt-6-luna` unless `agent_config.pi.model` is set. Any agent and model you choose runs, your coding agent's own too. A judge that fails or times out stops the command with its cause (exit 2; a `verify` run stops with exit 2 and its cause in the run record), and no receipt is written.
 - 🎨 **Looks right**: `done-done design <screens...> [--mock <screen>=<mock>]` has the same judge look at each captured screen, alone or next to its approved mock, and fails it on stretched or squashed images, clipped or squashed text, overlap, elements off-screen, blank or black strips and broken layout, naming each defect and where it is ([how](docs/reference.md#design-check)).
 - 📐 **Fits the screen**: `done-done look <url>` opens a web page in headless Chrome at a 390x844 phone viewport, captures it, and fails the journey that calls it on squashed text, clipped text, elements cut off by an edge or a page wider than the screen, naming each element, with no model ([how](docs/reference.md#look-check)).
+- 🧮 **Honest, cheap claim gate**: `done-done lint <PR URL | report file> <evidence folder>` is a no-model gate on a worker's `## Checks` block, on whenever you call it. It prints `PASS` or `FAIL: <reason>` and exits 1 on a fail: the four lines present, proof naming a command or path, a real repro on a fix PR, evidence files that exist, are non-empty, are newer than the evidence folder and differ from each other, at least one never used by another PR (hashes kept in `~/.done-done/lint.hashes`, every run logged to `lint.log` there), and under 1,000 added non-generated lines ([how](docs/reference.md#lint-check)). `evidence: not proven: <cause>` passes.
 - 🧩 **Page is clean** (with a `dom` block): each captured screen also needs its page-check record. A page that overflows the viewport, logs a console error, has a failed request or shows squashed, clipped or cut-off UI fails, unless an allow list names it ([how](docs/reference.md#dom-assertions)).
 - 🔒 **Safe in CI**: `--trusted-ref origin/main` reads the rules from your main branch, so a pull request can't loosen them.
 

package/dist/cli.js

@@ -18,6 +18,7 @@ import { cellEnv, cellName, cellSuffix, hasMatrix, matrixManifest, splitMatrix }
 import { design, KINDS } from './design.js';
 import { checkMedia } from './media.js';
 import { domIssues, domRecord, isDomRecord, lookIssues, SQUASHED_TEXT } from './dom.js';
+import { lint } from './lint.js';
 import { look } from './look.js';
 import { scanSecrets } from './secrets.js';
 const PASS = 0, FAIL = 1, USAGE = 2, INCONCLUSIVE = 3, WAITING = 4;
@@ -197,6 +198,17 @@ const COMMANDS = {
   overflow, squashed text, text clipped by its container and elements cut off by the left, right or top edge, writes the
   screenshot and its .dom.json record, and exits 1 naming each element, kind and text, 0 when there is none. A hit always
   fails: never wrap it in || true. Needs Chrome or Chromium (DONE_DONE_CHROME names the binary)`],
+    },
+    lint: {
+        usage: [['done-done lint <PR URL | report file> <evidence folder>', 'merge gate on a worker\'s claim: prints PASS or FAIL: <reason>; the rules need no judge, model or config']],
+        flags: [],
+        more: [`lint: a deterministic gate that is on whenever you call it. The newest "## Checks" block of the PR body (gh pr view) or report file needs
+  outcome:, repro:, proof: and evidence: lines. proof names a command or path, and the repo's verify-<app> skill, or says "no verify skill"
+  when the repo (the current folder) has none; repro is not n/a on a fix PR. evidence names files in the evidence folder (or absolute):
+  each exists, is non-empty and is newer than the folder itself; no two are byte-identical; at least one has a hash no other PR used
+  (hash store lint.hashes in ~/.done-done, or $DONE_DONE_HOME). "evidence: not proven: <cause>" passes. A PR with 1,000 or more added
+  non-generated lines fails (lockfiles, vendor/, dist/, LICENSE-type files, deletions and moved lines do not count); a bot PR passes.
+  Every run is appended to lint.log next to the store. Exit 0 PASS, 1 FAIL, 2 usage error. Needs gh for a PR URL`],
     },
     status: {
         usage: [['done-done status [--run <run-id>]', "show a run's steps, result, findings and next step"]],
@@ -1886,9 +1898,23 @@ function showRun(dir, cfg, command, gone = false) {
     emit(result);
     return code;
 }
+// A progress line on stderr every 60s (DONE_DONE_HEARTBEAT_MS overrides) naming the running step, so a caller that kills silent commands does not.
+function heartbeat(dir) {
+    const t = setInterval(() => {
+        const run = loadRun(dir);
+        process.stderr.write(`done-done: run ${run.run_id} still ${run.status}, step ${run.steps.find((s) => s.status === 'running')?.name ?? 'between steps'}\n`);
+    }, Number(process.env.DONE_DONE_HEARTBEAT_MS) || 60_000);
+    return () => clearInterval(t);
+}
 async function waitRun(dir, pid) {
-    while (['pending', 'running'].includes(loadRun(dir).status) && alive(pid))
-        await new Promise((r) => setTimeout(r, 200));
+    const stop = heartbeat(dir);
+    try {
+        while (['pending', 'running'].includes(loadRun(dir).status) && alive(pid))
+            await new Promise((r) => setTimeout(r, 200));
+    }
+    finally {
+        stop();
+    }
 }
 // The judge a command will start: the user's agent and judge, asked for when unset.
 async function preflightJudge(cfg, needsAgent = true) {
@@ -1972,7 +1998,13 @@ async function cmdVerify(argv) {
 // runner goes on when this command or its shell ends; --wait (the default) holds this command until the run ends.
 async function launch(dir, cfg, command, how) {
     if (how.foreground) {
-        await runSteps(dir);
+        const stop = heartbeat(dir);
+        try {
+            await runSteps(dir);
+        }
+        finally {
+            stop();
+        }
         return showRun(dir, cfg, command);
     }
     const fd = openSync(join(dir, 'logs', 'runner.log'), 'a');
@@ -3446,6 +3478,14 @@ async function cmdLook(argv) {
     });
     return hits.length ? FAIL : PASS;
 }
+function cmdLint(argv) {
+    const { positionals } = parseArgs({ args: argv, allowPositionals: true });
+    if (positionals.length !== 2)
+        throw new UsageError('lint needs a PR URL or report file, then the evidence folder', 'Re-run as: done-done lint <PR URL | report file> <evidence folder>');
+    const v = lint(positionals[0], positionals[1], home());
+    console.log(v.ok ? 'PASS' : `FAIL: ${v.why}`);
+    return v.ok ? PASS : FAIL;
+}
 async function cmdDesign(argv) {
     const { values, positionals } = parseArgs({ args: argv, options: { mock: { type: 'string', multiple: true } }, allowPositionals: true });
     const mocks = new Map();
@@ -3569,6 +3609,8 @@ async function main(argv) {
             return await cmdDesign(rest);
         if (cmd === 'look')
             return await cmdLook(rest);
+        if (cmd === 'lint')
+            return cmdLint(rest);
         if (cmd === 'status')
             return cmdStatus(rest);
         if (cmd === 'attach')

package/dist/lint.js

@@ -0,0 +1,125 @@
+// `done-done lint`: the deterministic merge gate on a worker's claim. It reads the newest "## Checks" block of a PR body
+// or report file and fails an unproven, reused or oversized claim. No judge, no model, no repo config.
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { basename, dirname, isAbsolute, join, resolve } from 'node:path';
+// Third-party, legal text and committed build output are not reviewable code.
+const GENERATED = /(^|\/)(package-lock\.json|pnpm-lock\.yaml|yarn\.lock|Cargo\.lock|go\.sum|[^/]*\.lock)$|(^|\/)vendor\/|(^|\/)dist\/|(^|\/)(LICENSE|LICENSES|NOTICE|COPYING)[^/]*$/;
+export const SIZE_LIMIT = 1000;
+const FIX_TITLE = /^(fix|bugfix|hotfix)\b/i;
+const NOT_APPLICABLE = /^n\/?a\b/i;
+const gh = (...args) => {
+    const r = spawnSync('gh', args, { encoding: 'utf8', timeout: 60_000, maxBuffer: 1 << 28 });
+    return { status: r.error ? 1 : r.status, stdout: r.stdout ?? '', stderr: r.error?.message ?? r.stderr ?? '' };
+};
+// Added minus deleted non-generated lines of a unified diff: a line moved between files cancels out.
+function netLines(diff) {
+    const net = new Map();
+    let generated = false;
+    for (const l of diff.split('\n')) {
+        if (l.startsWith('+++ ')) {
+            generated = GENERATED.test(l.startsWith('+++ b/') ? l.slice(6) : l.slice(4));
+            continue;
+        }
+        if (l.startsWith('--- ') || generated || !l.slice(1).trim())
+            continue;
+        if (l[0] === '+' || l[0] === '-')
+            net.set(l.slice(1).trim(), (net.get(l.slice(1).trim()) ?? 0) + (l[0] === '+' ? 1 : -1));
+    }
+    let total = 0;
+    for (const n of net.values())
+        if (n > 0)
+            total += n;
+    return total;
+}
+const sha256 = (p) => createHash('sha256').update(readFileSync(p)).digest('hex');
+// src: a PR URL or a report file; ev: the folder the evidence names are relative to; dir: where the hash store and log live.
+export function lint(src, ev, dir, run = gh) {
+    const log = (v) => {
+        mkdirSync(dir, { recursive: true });
+        appendFileSync(join(dir, 'lint.log'), `${new Date().toISOString()}\t${src}\t${v.head}\t${v.ok ? 'pass' : 'fail'}\t${v.why}\n`);
+        return v;
+    };
+    let body = '', title = '', head = '-', task = '';
+    if (existsSync(src) && statSync(src).isFile()) {
+        body = readFileSync(src, 'utf8');
+        task = basename(dirname(resolve(src)));
+    }
+    else {
+        const r = run('pr', 'view', src, '--json', 'author,body,title,files,headRefOid,headRefName');
+        if (r.status)
+            return log({ ok: false, why: `gh pr view failed: ${r.stderr.trim().split('\n').pop()?.slice(0, 160) || '?'}`, head });
+        const pr = JSON.parse(r.stdout);
+        ({ body, title } = { body: pr.body ?? '', title: pr.title ?? '' });
+        head = pr.headRefOid ?? '-';
+        task = String(pr.headRefName ?? '').split('/').pop();
+        const author = pr.author?.login ?? '';
+        if (/^(app\/)?(dependabot|renovate)(\[bot\])?$/.test(author))
+            return log({ ok: true, why: 'bot', head });
+        let size = (pr.files ?? []).reduce((n, f) => n + (GENERATED.test(f.path ?? '') ? 0 : f.additions ?? 0), 0);
+        if (size >= SIZE_LIMIT) {
+            const d = run('pr', 'diff', src);
+            if (!d.status)
+                size = netLines(d.stdout);
+        }
+        if (size >= SIZE_LIMIT)
+            return log({ ok: false, why: `${size} added non-generated lines (moved lines excluded): split it (limit ${SIZE_LIMIT})`, head });
+    }
+    const fail = (why) => log({ ok: false, why, head });
+    const block = [...body.matchAll(/^##\s*Checks\s*$([\s\S]*?)(?=^##\s|(?![\s\S]))/gm)].pop(); // newest: workers append, never replace
+    if (!block)
+        return fail('no "## Checks" block');
+    const f = {};
+    for (const m of block[1].replace(/```\w*/g, '').matchAll(/^\s*(outcome|repro|proof|evidence)\s*:\s*(.*)$/gm))
+        f[m[1]] = m[2].trim();
+    const missing = ['outcome', 'repro', 'proof', 'evidence'].filter((k) => !f[k]);
+    if (missing.length)
+        return fail(`missing or empty Checks line: ${missing.join(', ')}`);
+    if (!/[/`]|\.\w{2,4}\b|\b(npm|pnpm|yarn|npx|bash|sh|python3?|node|cargo|go|gradle|make|adb|xcrun|done-done)\b/.test(f.proof))
+        return fail('proof: names no command or path');
+    const skills = join(process.cwd(), '.agents', 'skills');
+    const hasVerify = existsSync(skills) && readdirSync(skills).some((d) => d.startsWith('verify-'));
+    if (!f.proof.includes('verify-') && (hasVerify || !/no verify skill/i.test(f.proof)))
+        return fail(`proof: does not name the verify-<app> skill run${hasVerify ? '' : ' (or "no verify skill")'}`);
+    if (NOT_APPLICABLE.test(f.repro) && FIX_TITLE.test(title))
+        return fail('repro: is n/a on a fix PR');
+    if (/^not proven\s*:\s*\S/i.test(f.evidence))
+        return log({ ok: true, why: `not-proven: ${f.evidence.slice(0, 120)}`, head });
+    const names = f.evidence.split(/[,\s]+/).map((n) => n.replace(/^[`"']+|[`"']+$/g, '')).filter((n) => /\.\w{1,10}$/.test(n));
+    if (!names.length)
+        return fail('evidence: names no files (or write "not proven: <cause>")');
+    const store = join(dir, 'lint.hashes');
+    const seen = new Map();
+    if (existsSync(store))
+        for (const l of readFileSync(store, 'utf8').split('\n')) {
+            const p = l.split(' ');
+            if (p.length === 2)
+                seen.set(p[0], p[1]);
+        }
+    // The evidence folder is born when the task starts, so a file older than it was captured for something else.
+    const born = existsSync(ev) ? statSync(ev).birthtimeMs : 0;
+    const mine = [];
+    let fresh = false;
+    for (const n of names) {
+        const p = isAbsolute(n) ? n : join(ev, n);
+        if (!existsSync(p) || !statSync(p).isFile() || statSync(p).size === 0)
+            return fail(`evidence file missing or empty: ${p}`);
+        if (born && statSync(p).mtimeMs < born)
+            return fail(`evidence file older than the task start: ${p}`);
+        const h = sha256(p);
+        mine.push(h);
+        const owner = seen.get(h); // the same task's earlier lint is not reuse
+        if (owner === undefined || owner === src || owner === task)
+            fresh = true;
+    }
+    if (!fresh)
+        return fail('every evidence file was already used by another PR');
+    if (new Set(mine).size < mine.length)
+        return fail('two evidence files are byte-identical: capture each claimed state separately, or write "not proven: <cause>"');
+    mkdirSync(dir, { recursive: true });
+    for (const h of mine)
+        if (!seen.has(h))
+            appendFileSync(store, `${h} ${task || src}\n`);
+    return log({ ok: true, why: `${names.length} evidence files`, head });
+}

package/docs/reference.md

@@ -221,6 +221,17 @@ journeys:
 | a hit of any kind | 1 |
 | bad flags, no Chrome, or the page did not load | 2 |
 
+### Lint check
+
+`done-done lint <PR URL | report file> <evidence folder>` is a deterministic gate on a worker's claim: no judge, no model, no config. It prints `PASS` or `FAIL: <reason>` and exits 0, 1, or 2 on a usage error. A PR URL is read with `gh pr view`; a file is read as the report.
+
+- The newest `## Checks` block needs `outcome:`, `repro:`, `proof:` and `evidence:`.
+- `proof:` names a command or path, and the repo's `verify-<app>` skill; it may say `no verify skill` only when `.agents/skills/` in the current folder holds none.
+- `repro:` is not `n/a` when the PR title starts with `fix`, `bugfix` or `hotfix`.
+- `evidence: not proven: <cause>` passes.
+- Otherwise each named file (relative to the evidence folder, or absolute) exists, is non-empty and is newer than the evidence folder itself; no two are byte-identical; and at least one has a hash no other PR used. Hashes are kept in `lint.hashes` and each run is appended to `lint.log`, both in `~/.done-done` (`$DONE_DONE_HOME`). A later lint of the same PR is not reuse.
+- A PR with 1,000 or more added non-generated lines fails. Lockfiles, `vendor/`, `dist/` and `LICENSE`-type files do not count, and neither do deletions or lines moved between files. A dependabot or renovate PR passes.
+
 ### Base-ref before
 
 A before/after change is judged as a pair. With `base_ref` set to a branch, tag or commit (for example `base_ref: origin/main`), `verify` drives the base ref too, after the head's drive and only when it passed:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "done-done-axi",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "license": "Apache-2.0",
   "description": "Proof that the real product works before a task is called done: commit-bound evidence runs and evidence checks.",
   "type": "module",

package/skills/done-done/SKILL.md

@@ -46,6 +46,11 @@ journeys:
     command: done-done look http://127.0.0.1:3000/inbox --out "$DONE_DONE_EVIDENCE_ROOT/inbox.png"
 ```
 
+To gate a worker's claim cheaply, `done-done lint <PR URL | report file> <evidence folder>` reads the newest `## Checks` block
+with no judge or model and prints `PASS` or `FAIL: <reason>` (exit 1 on a fail): missing lines, evidence that is absent,
+empty, stale, duplicated or already used by another PR, a n/a repro on a fix, or a PR of 1,000+ added lines all fail.
+`evidence: not proven: <cause>` passes. Fix the cause it names and re-run; never edit the evidence to get past it.
+
 done-done starts a coding agent the user chose. When it says no agent is set, ask the user which agent
 (and model) to use and save their answer with the command it prints; never choose one for them.