Redesign an existing website to make it better. Built on top of impeccable.
88%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
Low
Low-risk findings worth noting
#!/usr/bin/env node
/**
* skills/replica/scripts/gate-evidence.mjs
*
* Phase 5 handoff collector: fill every migrated page's `_meta.json` sidecar
* (`gatesPassed[]` + `gateEvidence{}`) from the evidence the earlier phases already
* left on disk, and roll the same facts into `stardust/replica/progress.json`.
* Nothing is measured here. The collector reads run-bg's job state
* (`<bg>/<job>.json`, through run-bg's own reader) and each job's log
* (`<bg>/<job>.log`), attributes a job to a page by the job's ARGUMENTS — never by
* grepping log prose — takes the LATEST ended job per page × instrument × width by
* its `endedAt` (never by file mtime; jobs still running are skipped), and runs
* delivery-lint in-process per page because it is static and fast. A gate is
* added only when its instrument printed a pass; a fail or open verdict is still
* written into `gateEvidence`, prefixed `FAIL: ` / `OPEN: `, so the reader sees why
* the gate is missing. Existing entries are never removed.
*
* Gates derived (each evidence one-liner carries its `(<job>.log)` pointer):
* pixel-gate-<width> latest gate.sh round at that width (gate.sh <slug> <live> <build> <width>
* [label]) whose pixel-compare line reads `→ PASS` with |height delta| ≤
* --height-tolerance AND whose overflow assert did not fire: a round whose log
* carries gate.sh's `OVERFLOW at <w> — build scrollWidth <n> > viewport <n>
* (+<n>px)` line is `FAIL: horizontal overflow +<n>px …` whatever the pixel
* line says (a recorded run passed two pages 373 and 400 px wide at 360 as
* residuals; the assert is the one no iteration cap waives). The line ends
* with the round's REGIME, read from the
* build URL argument: localhost / 127.0.0.1 / file: → `[prototype regime]`,
* anything else → `[published regime]`. The prototype-regime bar is the
* archetype's; siblings are gated in the published regime only (#126); it never replaces the published-origin gate
* (gate.sh header: "the published-origin gate is the same command with the
* preview URL") — a reader who needs the published verdict looks for that word.
* A --full round's element lines outrank its pixel PASS the way the overflow
* assert does (#125): `clip-probe: Clipped: <n>` with n > 0 or `content-
* presence: Content: MISSING <n> … HIDDEN <n>` with a count > 0 → FAIL. THE
* PIXEL TABLE IS THE SOURCE OF RECORD (#125 rule: every crafted prototype and
* every deployed page is a row in `<tables>/prototypes-<w>/summary.json` or
* `<tables>/all-<w>/summary.json`, written by gate-all.mjs): when a table
* exists for the width, the page's row decides the gate (published row first)
* and a page WITHOUT a row is OPEN: no table row — whatever a gate.sh log
* says. Without any table the log rule above stands and one note names the
* missing table.
* content-count latest content-diff.mjs job for the page (`Findings: none …` or
* `Findings: N (0 structural 🔴)` and nothing-lost 🟡 0); when no such job exists, the
* newest gate.sh --full round's `content-diff:` line; structural 🔴 or nothing-lost > 0 → OPEN:
* media-reconcile latest media-reconcile.mjs job whose counts line has no `omit` and no
* `unresolved` (the instrument's own exit-1 rule); either → OPEN: — but only once
* the page's DELIVERED content file exists (`<--content>/<da-path>.html`, or
* `<da-path>/index.html`; the root page is `index.html`). Before that the gate is
* not required: the evidence reads `n/a: no delivered content file yet (<file>) —
* media-reconcile runs in the delivery chain (row C)`, the sibling acceptance set
* skips it, and a passing job still passes. A recorded run demanded it on
* prototype files and every sibling sidecar carried `media-reconcile: OPEN` until
* delivery. Once the file exists the gate is required again.
* delivery-lint --lint run per page (`--file <html> --path </da/path>`), pass on
* `0 P0 · 0 P1`; when --lint does not resolve, the latest delivery-lint.mjs
* job for the page; P0/P1 → FAIL:
* variance-probe siblings only: latest sibling-variance.mjs job that named this page's URL
* or its archetype's. ONLY the page's own `■ <url>` line is evidence: 0 deltas
* pass, deltas pass only with a declared `variants[]`, deltas with an empty
* `variants[]` → OPEN:. A probe whose output has no `■` line for the page
* never passes — `OPEN: not in the probe — <✓|✗ summary>` — whatever the
* summary says.
* content-fidelity NEVER added here — it is the agent's declaration
* (`migrate.mjs gate <slug> content-fidelity --evidence …`)
*
* The NEWEST ended job per page × instrument (× width) decides, and only a verdict can pass:
* • run-bg state `timedOut: true` or `exit 124` (the instrument's deadline) →
* `OPEN: deadline (<job>.log) — re-run` for that gate; an older pass is not resurrected.
* • a pixel round whose exit is not 0 or 2 (gate.sh: 1 = capture/compare error, 3 = bot
* challenge, 4 = build-side identity failed) → `OPEN: no verdict (exit N) (<job>.log)`.
* • a sibling-variance probe with an exit other than 0 or 2 → the same `OPEN: no verdict`.
*
* Attribution: gate.sh by its slug argument; other instruments by an argument that names the page
* (URL path, `<slug>-proposed.html`, a file resolved from the job's cwd). The job-name fallback
* (`<slug>-…`) applies only when NO argument names ANY known page — a job whose arguments name
* another page is that page's, whatever it was called.
*
* Usage:
* node stardust/scripts/replica/gate-evidence.mjs [--migrated stardust/migrated]
* [--bg stardust/.work/replica/bg] [--progress stardust/replica/progress.json]
* [--lint stardust/scripts/rollout/delivery-lint.mjs] [--content content] [--widths 1440,360]
* [--height-tolerance 8] [--tables stardust/replica/gates] [--slug <s>]… [--check] [--dry-run] [--json]
*
* --tables <dir> where gate-all.mjs writes the pixel tables (`prototypes-<w>/`, `all-<w>/`); when
* one exists for a width its rows decide pixel-gate-<w> and a page without a row is
* OPEN
* --slug <s> only these pages (repeatable): rows and sidecar writes; the progress
* ledger's `migrate` totals are rewritten only by an unfiltered run
* --content <dir> the delivered content tree (default `content`, the deploy driver's) — the
* media-reconcile gate is required only for a page whose file exists there
* --check exit 2 when a sibling lacks a gate of the acceptance set: variance-probe,
* pixel-gate-<w> for EVERY --widths entry, delivery-lint, media-reconcile (only once
* the page's delivered content file exists — above), content-fidelity,
* content-count. The pixel gates belong to the set: a recorded
* run published eleven siblings that had never been compared at 360, and they
* read 17–27 % against the ≤ 10 % bar on the published origin. Archetypes and
* thin pages are not held to this set here (their `missing` is always empty).
* Also exit 2, for ANY tier, on a STALE gate: one that sits in gatesPassed[] while
* its latest evidence reads FAIL:/OPEN: — printed as `<slug>: stale <gates> — …`
* (the gate is never removed; the line names what must be re-earned)
* --dry-run compute and print, write nothing
* --json the rows as a JSON array instead of the table
*
* Prints one row per page — `<slug> <tier> 1440=<pct>%/Δ<px>[/ovf+<px>] 360=… cd=<…> lint=<…>
* media=<…> gates=<n>` (`/ovf+<px>` only when the round's overflow assert fired) — then
* `gate-evidence: <n> pages, <n> sidecars updated`.
* Exit 0; 1 usage error (a malformed sidecar or progress.json included, and a progress.json whose
* top level is one archetype's record naming no archetype — below); 2 --check found a sibling short
* of the acceptance set or a stale gate.
*
* Writes: each page's sidecar (`_meta.json` / `<name>._meta.json`): `gatesPassed[]` =
* existing ∪ derived (existing first) and `gateEvidence{}` merged (derived lines overwrite
* the same key; `n/a: ` lines are neither passes nor stale) — nothing else, indent preserved.
* `--progress`: `migrate` {at, pages, archetypes, siblings, thin, gates{<gate>: <pass count>},
* missing{<slug>: [<gates>]}} and `siblings{<slug>: {archetype, variants, pixel{<width>:
* {pct, px, heightDelta, overflowX, verdict, label, regime}}, contentDiff, deliveryLint, media,
* gatesPassed, migrated}}` (`overflowX`: px over the viewport, 0 when the assert ran clean,
* null when the round predates it), other keys
* preserved. progress.json is read and parsed BEFORE the first sidecar is touched (a malformed
* ledger aborts the run with nothing written). A ledger with no `types` map whose top level is one
* archetype's record (`breakpoints`, or `pageType` + `archetype` — the old documented example) is
* wrapped under `types.<archetype>` losslessly and noted on stderr, and only a record naming no
* `archetype` is refused (source-fidelity-gate.md § Residual logging format); every sidecar and the
* ledger are written through a temp file + rename. Nothing with --dry-run or --help.
*/
/* eslint-disable no-restricted-syntax, brace-style, object-curly-newline, max-len, no-continue */
import { execFileSync } from 'node:child_process';
import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, statSync, writeFileSync } from 'node:fs';
import { basename, dirname, join, relative, resolve, sep } from 'node:path';
import { fileURLToPath } from 'node:url';
import { listJobs, logPath } from './run-bg.mjs';
// The shared rules (contracts.mjs) live beside browser.mjs in the master skill's scripts dir: the plugin tree or the Setup step 7 copy.
const CONTRACTS = ['../../stardust/scripts/contracts.mjs', '../stardust/contracts.mjs']
.map((p) => new URL(p, import.meta.url)).find((u) => existsSync(u));
if (!CONTRACTS) { console.error('gate-evidence: contracts.mjs not found (looked in ../../stardust/scripts/ and ../stardust/). Copy the master skill\'s scripts dir to stardust/scripts/stardust/ (skills/stardust/SKILL.md § Setup).'); process.exit(1); }
const { treePath, siblingPath } = await import(CONTRACTS.href);
export const DEFAULTS = { tables: 'stardust/replica/gates', migrated: 'stardust/migrated', bg: 'stardust/.work/replica/bg', progress: 'stardust/replica/progress.json', lint: 'stardust/scripts/rollout/delivery-lint.mjs', content: 'content', widths: [1440, 360], heightTolerance: 8 };
// The sibling acceptance set for one --widths list: a pixel gate per width, in the order given. Every reader of the set
// (--check, the row's `missing`, progress.json migrate.missing) goes through this; archetypes and thin pages are not held to it.
export const acceptanceFor = (widths) => ['variance-probe', ...widths.map((w) => `pixel-gate-${w}`), 'delivery-lint', 'media-reconcile', 'content-fidelity', 'content-count'];
// The set for the default widths (1440, 360) — kept for importers.
export const ACCEPTANCE = acceptanceFor(DEFAULTS.widths);
// Instrument script → job kind. The instrument is the first cmd/arg token with one of these basenames
// (a wrapper such as bash or run-capped may precede it); its own arguments follow.
export const INSTRUMENTS = { 'gate.sh': 'pixel', 'content-diff.mjs': 'content-diff', 'media-reconcile.mjs': 'media-reconcile', 'delivery-lint.mjs': 'delivery-lint', 'sibling-variance.mjs': 'variance' };
const SELF = fileURLToPath(import.meta.url);
class UsageError extends Error {}
function help() {
const header = readFileSync(SELF, 'utf8').match(/\/\*\*[\s\S]*?\*\//);
return header ? header[0].replace(/^\/\*\*\s*|\s*\*\/$/g, '').replace(/^\s*\* ?/gm, '').trim() : 'no usage header';
}
export function parseArgs(argv) {
const o = { ...DEFAULTS, widths: [...DEFAULTS.widths], lintGiven: false, slugs: [], check: false, dryRun: false, json: false };
const val = (flag, v) => { if (v === undefined || v.startsWith('--')) throw new UsageError(`gate-evidence: ${flag} needs a value (see --help)`); return v; };
for (let i = 0; i < argv.length; i += 1) {
const a = argv[i];
if (a === '--migrated') o.migrated = val(a, argv[++i]);
else if (a === '--bg') o.bg = val(a, argv[++i]);
else if (a === '--progress') o.progress = val(a, argv[++i]);
else if (a === '--lint') { o.lint = val(a, argv[++i]); o.lintGiven = true; }
else if (a === '--content') o.content = val(a, argv[++i]);
else if (a === '--tables') o.tables = val(a, argv[++i]);
else if (a === '--widths') { o.widths = val(a, argv[++i]).split(',').map((w) => Number(w.trim())); if (!o.widths.length || o.widths.some((w) => !Number.isInteger(w) || w <= 0)) throw new UsageError(`gate-evidence: --widths needs a comma list of pixel widths (got "${argv[i]}")`); }
else if (a === '--height-tolerance') { o.heightTolerance = Number(val(a, argv[++i])); if (!Number.isFinite(o.heightTolerance) || o.heightTolerance < 0) throw new UsageError('gate-evidence: --height-tolerance needs a number of pixels'); }
else if (a === '--slug') o.slugs.push(val(a, argv[++i]));
else if (a === '--check') o.check = true;
else if (a === '--dry-run') o.dryRun = true;
else if (a === '--json') o.json = true;
else throw new UsageError(`gate-evidence: unknown argument ${a} (see --help)`);
}
return o;
}
// ---- sidecars ----------------------------------------------------------------------------------
// `_meta.json` sits beside `index.html`; `<name>._meta.json` beside `<name>.html` (migration-procedure.md § `_meta.json` sidecar).
export function sidecarHtml(file) {
const b = basename(file);
if (b === '_meta.json') return 'index.html';
if (b.endsWith('._meta.json')) return `${b.slice(0, -'._meta.json'.length)}.html`;
return null;
}
// The indent the file was written with (run-bg and the recorded migrations use 1 space, others 2) — or 2 for a one-line file.
export function detectIndent(text) { const m = text.match(/^[{[]\r?\n([ \t]+)/); return m ? m[1] : 2; }
function readJson(file) {
const text = readFileSync(file, 'utf8');
let data; try { data = JSON.parse(text); } catch (e) { throw new UsageError(`gate-evidence: ${file}: ${e.message}`); }
return { data, text, indent: detectIndent(text), eol: text.endsWith('\n') };
}
const serialize = (data, indent, eol) => JSON.stringify(data, null, indent) + (eol ? '\n' : '');
// Temp file + rename: a crash mid-write never leaves a half-written sidecar or ledger behind.
function writeAtomic(file, text) { const tmp = `${file}.${process.pid}.tmp`; writeFileSync(tmp, text); renameSync(tmp, file); }
export function findSidecars(migrated) {
const out = [];
const walk = (dir) => {
for (const f of readdirSync(dir).sort()) {
const p = join(dir, f);
if (statSync(p).isDirectory()) { walk(p); continue; }
const html = sidecarHtml(p);
if (!html) continue;
const j = readJson(p);
out.push({ file: p, meta: j.data, text: j.text, indent: j.indent, eol: j.eol, slug: j.data.slug, htmlFile: join(dir, html), outputPath: relative(migrated, join(dir, html)).split(sep).join('/') });
}
};
if (existsSync(migrated)) walk(migrated);
return out;
}
// ---- run-bg jobs -------------------------------------------------------------------------------
export function classify(job) {
const tokens = [job.cmd, ...(Array.isArray(job.args) ? job.args : [])].filter((t) => typeof t === 'string');
for (let i = 0; i < tokens.length; i += 1) {
const kind = INSTRUMENTS[basename(tokens[i])];
if (kind) return { kind, instArgs: tokens.slice(i + 1) };
}
return null;
}
export const jobAt = (job) => Date.parse(job.endedAt || job.launchedAt || job.queuedAt || '') || 0;
// Every ENDED job that ran a known instrument, with its log text. A job without `endedAt` (queued, running, or lost
// with its wrapper) has no verdict and is skipped — run-bg's state, never the log's mtime, decides.
export function loadJobs(bg) {
const out = [];
for (const st of listJobs(bg)) {
if (!st.endedAt) continue;
const c = classify(st);
if (!c) continue;
let log = ''; try { log = readFileSync(logPath(bg, st.name), 'utf8'); } catch { /* no log — nothing to parse */ }
out.push({ ...st, ...c, log, logName: `${st.name}.log` });
}
return out.sort((a, b) => jobAt(a) - jobAt(b));
}
// The URL paths a page answers to: `tours/north/index.html` → /tours/north/index.html, /tours/north/, /tours/north;
// `about/history.html` → /about/history.html, /about/history; `index.html` → /index.html, /.
export function pagePaths(outputPath) {
const full = `/${outputPath}`;
const set = new Set([full]);
if (full.endsWith('/index.html')) { const d = full.slice(0, -'index.html'.length); set.add(d); if (d !== '/') set.add(d.slice(0, -1)); }
else if (full.endsWith('.html')) set.add(full.slice(0, -5));
return [...set];
}
const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
const isUrl = (s) => /^https?:\/\//i.test(s);
const urlPath = (s) => { try { return decodeURIComponent(new URL(s).pathname) || '/'; } catch { return null; } };
// Does one argument name the page? A URL by its path, the prototype file `<slug>-proposed.html` (slug at a word
// boundary, so `north` does not claim `tours-north-proposed.html`), or a file by where it resolves from the job's cwd.
export function argNamesPage(arg, page, job, migrated) {
if (typeof arg !== 'string') return false;
if (isUrl(arg)) { const p = urlPath(arg); return p !== null && pagePaths(page.outputPath).includes(p); }
if (new RegExp(`(^|[^A-Za-z0-9_-])${escapeRe(page.slug)}-proposed\\.html`).test(arg)) return true;
if (!migrated) return false;
return resolve(job.cwd || process.cwd(), arg) === resolve(migrated, page.outputPath);
}
// The slug a job name `<slug>-…` belongs to: the LONGEST known slug that prefixes it (`tours-north-1440` is tours-north's, not tours').
export function nameOwner(name, slugs) { return slugs.filter((s) => name.startsWith(`${s}-`)).sort((a, b) => b.length - a.length)[0] || null; }
// gate.sh: its first argument IS the slug. Other instruments: an argument names the page. The job-name fallback is
// the last resort and only when no argument names ANY known page (ctx.pages) — a job called `tours-north-lint` whose
// --file is about/history.html is about-history's, not tours-north's.
export function attribute(job, page, ctx = {}) {
if (job.kind === 'pixel') return job.instArgs[0] === page.slug;
if (job.instArgs.some((a) => argNamesPage(a, page, job, ctx.migrated))) return true;
if ((ctx.pages || []).some((p) => p !== page && job.instArgs.some((a) => argNamesPage(a, p, job, ctx.migrated)))) return false;
return ctx.slugs ? nameOwner(job.name, ctx.slugs) === page.slug : job.name.startsWith(`${page.slug}-`);
}
// The regime a gate.sh round ran in, from its build URL argument (gate.sh <slug> <live> <build> <width>): a served
// prototype (localhost / 127.0.0.1 / file:) is `prototype`, anything else — the preview or live origin — `published`.
export function regimeOf(job) {
const u = String(job.instArgs[2] || '');
return /^file:/i.test(u) || /^https?:\/\/(localhost|127\.0\.0\.1)(?=[:/?#]|$)/i.test(u) ? 'prototype' : 'published';
}
// A job that ended on the instrument's deadline: run-bg's `timedOut` flag or exit 124. Not a verdict.
export const deadline = (job) => job.timedOut === true || job.exit === 124;
// ---- verdict parsers (pure) --------------------------------------------------------------------
// pixel-compare: `A WxH B WxH → compare WxH, height delta Npx` then `differing pixels: n / m = p% (threshold t%) → PASS|FAIL…`.
export function parseVerdict(text) {
const v = [...text.matchAll(/differing pixels: (\d+) \/ (\d+) = ([\d.]+)%\s+\(threshold ([\d.]+)%\) → (PASS|FAIL)/g)].pop();
if (!v) return null;
const h = [...text.matchAll(/→ compare \d+x\d+, height delta (-?\d+)px/g)].pop();
return { px: Number(v[1]), total: Number(v[2]), pct: Number(v[3]), threshold: Number(v[4]), verdict: v[5], heightDelta: h ? Number(h[1]) : null };
}
// content-diff: `Findings: none — content + roles match` | `Findings: N (S structural 🔴)`, then `Tiers: looks-same 🔴 S ·
// nothing-lost 🟡 L · …`; gate.sh --full echoes both on one `content-diff: ` line. lost = the nothing-lost count of the
// SAME round as the last Findings line — on that line or the Tiers line right after it (0 when an older probe printed
// no tiers), never a count from another round of a multi-round log.
export function parseFindings(text) {
const m = [...text.matchAll(/^(?:Findings|content-diff): (none[^\n]*|(\d+) \((\d+) structural[^\n]*)$(?:\r?\nTiers: [^\n]*)?/gm)].pop();
if (!m) return null;
const tiers = /nothing-lost 🟡 (\d+)/.exec(m[0]);
return { total: m[2] === undefined ? 0 : Number(m[2]), structural: m[3] === undefined ? 0 : Number(m[3]), lost: tiers ? Number(tiers[1]) : 0, text: m[1].trim() };
}
// media-reconcile: last line `<n> keep · <n> optimize · <n> omit …` — one `<n> <decision>` per decision that occurred.
export function parseCounts(text) {
const m = [...text.matchAll(/^((?:\d+ [a-z]+)(?: · \d+ [a-z]+)*)[ \t]*$/gm)].pop();
if (!m) return null;
const counts = {}; for (const part of m[1].split(' · ')) { const [n, k] = part.split(' '); counts[k] = Number(n); }
return { counts, line: m[1] };
}
// gate.sh --full element lines (#125): `clip-probe: Clipped: <n> …`, `content-presence: Content: MISSING <n> … / HIDDEN <n> …`.
export function parseElements(text) {
const clip = text.match(/^clip-probe: Clipped: (\d+)/m); const cp = text.match(/^content-presence: Content: MISSING (\d+).*?HIDDEN (\d+)/m);
return { clipped: clip ? Number(clip[1]) : null, missing: cp ? Number(cp[1]) : null, hidden: cp ? Number(cp[2]) : null };
}
// The pixel tables gate-all.mjs writes: { published: { <slug>: row }, prototype: { <slug>: row }, any: boolean } per width.
export function loadTables(dir, widths) {
const out = {};
for (const w of widths) {
const read = (name) => { const f = join(dir, `${name}-${w}`, 'summary.json'); if (!existsSync(f)) return null; try { return Object.fromEntries((JSON.parse(readFileSync(f, 'utf8')).rows || []).map((r) => [r.slug, { ...r, file: f }])); } catch { return null; } };
const published = read('all'); const prototype = read('prototypes');
out[w] = { published, prototype, any: !!(published || prototype) };
}
return out;
}
// gate.sh's overflow assert: `gate.sh: OVERFLOW at <w> — build scrollWidth <n> > viewport <n> (+<n>px) → FAIL …` fired;
// `gate.sh: overflow assert at <w> — … → ok` ran clean. The LAST of either decides; null when the round predates the assert.
export function parseOverflow(text) {
const m = [...text.matchAll(/^gate\.sh: (?:OVERFLOW at (\d+) — build scrollWidth (\d+) > viewport (\d+) \(\+(\d+)px\)|overflow assert at (\d+) — [^\n]*→ ok)[^\n]*$/gm)].pop();
if (!m) return null;
if (m[5] !== undefined) return { width: Number(m[5]), px: 0, scrollWidth: null, viewport: null };
return { width: Number(m[1]), px: Number(m[4]), scrollWidth: Number(m[2]), viewport: Number(m[3]) };
}
// delivery-lint: `<n> P0 · <n> P1 · <n> P2`.
export function parseLint(text) {
const m = [...text.matchAll(/^(\d+) P0 · (\d+) P1 · (\d+) P2[ \t]*$/gm)].pop();
return m ? { p0: Number(m[1]), p1: Number(m[2]), p2: Number(m[3]), line: `${m[1]} P0 · ${m[2]} P1 · ${m[3]} P2` } : null;
}
// sibling-variance: per sibling `■ <url>: ✓ matches the archetype | N delta(s)`, then a `✓|✗ … sibling(s) …` summary.
// `paths` = the page's own URL paths; its `■` line is the evidence when present (`own: true`), else the summary is
// returned with `own: false` and `deltas: null` — the caller must not pass on a summary alone.
export function parseVariance(text, paths = []) {
const summary = [...text.matchAll(/^[✓✗] \d+ (?:of \d+ )?sibling\(s\) [^\n]*$/gm)].pop();
const own = [...text.matchAll(/^■ (\S+): ([^\n]*)$/gm)].find((m) => { const p = urlPath(m[1]); return p !== null && paths.includes(p); });
if (!summary && !own) return null;
const d = own && own[2].match(/^(\d+) delta/);
return { summary: summary ? summary[0] : null, line: own ? own[0] : summary[0], deltas: own ? (d ? Number(d[1]) : 0) : null, own: Boolean(own) };
}
// ---- derivation --------------------------------------------------------------------------------
const latest = (items, at = (x) => jobAt(x.j)) => items.reduce((best, x) => (!best || at(x) > at(best) ? x : best), null);
const fmtPct = (n) => `${n.toFixed(2)}%`;
// The `--path` delivery-lint expects: the output path without `.html` and without a trailing `/index`; the root page is `/` (lib/paths.mjs treePath).
export const daPath = treePath;
// The page's DELIVERED content file (the deploy driver's tree: a file's path minus `.html` is its DA path): `<content>/<da-path>.html`,
// or `<content>/<da-path>/index.html`; the root page is `<content>/index.html`. `file` names the first candidate (relative, for
// evidence lines) even when none exists.
export function contentFileFor(contentDir, outputPath) {
const p = daPath(outputPath);
const rel = p === '/' ? ['index.html'] : [`${p.slice(1)}.html`, `${p.slice(1)}/index.html`];
const hit = rel.find((r) => existsSync(join(contentDir, r)));
return { file: join(contentDir, hit || rel[0]), exists: Boolean(hit) };
}
export function runLint(lint, page) {
const args = [lint, '--file', page.htmlFile, '--path', daPath(page.outputPath)];
let out = ''; let code = 0;
try { out = execFileSync(process.execPath, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 60000 }); }
catch (e) { out = String(e.stdout || ''); code = typeof e.status === 'number' ? e.status : 1; if (!out.trim()) return { ok: false, line: `delivery-lint gave no output (exit ${code}): ${String(e.stderr || e.message).trim().split('\n')[0].slice(0, 160)}` }; }
const l = parseLint(out);
return l ? { ok: l.p0 === 0 && l.p1 === 0, line: l.line } : { ok: false, line: `delivery-lint printed no summary line (exit ${code})` };
}
// Every gate one page earns from the jobs attributed to it. Returns { gates, evidence, facts, notes }; the caller merges.
export function derive(page, jobs, o, ctx) {
const mine = jobs.filter((j) => attribute(j, page, ctx));
const gates = []; const evidence = {}; const notes = [];
const facts = { pixel: {}, contentDiff: null, deliveryLint: null, media: null, variance: null, delivered: null };
const pass = (g, line) => { gates.push(g); evidence[g] = line; };
const open = (g, line, prefix = 'OPEN') => { evidence[g] = `${prefix}: ${line}`; };
const cite = (j) => `(${j.logName})`;
// The newest job of a set decides the gate: on a deadline, or (when `verdictExits` is given) an exit that is not a
// verdict, the gate is recorded OPEN and null is returned — an older pass never stands in. Otherwise the latest job
// with a parsable verdict line among the jobs that could carry one.
const pick = (list, parse, gate, verdictExits = null) => {
const newest = latest(list.map((j) => ({ j })));
if (!newest) return null;
if (deadline(newest.j)) { open(gate, `deadline ${cite(newest.j)} — re-run`); return null; }
if (verdictExits && !verdictExits.includes(newest.j.exit)) { open(gate, `no verdict (exit ${newest.j.exit}) ${cite(newest.j)}`); return null; }
const usable = list.filter((j) => !deadline(j) && (!verdictExits || verdictExits.includes(j.exit)));
return latest(usable.map((j) => ({ j, v: parse(j.log) })).filter((x) => x.v));
};
const ofKind = (...kinds) => mine.filter((j) => kinds.includes(j.kind));
for (const w of o.widths) {
const t = ctx.tables && ctx.tables[w];
if (t && t.any) {
// the table rule: the row decides; no row = ungated, whatever a log says
const row = (t.published && t.published[page.slug]) || (t.prototype && t.prototype[page.slug]) || null;
if (!row) { open(`pixel-gate-${w}`, `no row in the pixel table (${[t.published && 'all', t.prototype && 'prototypes'].filter(Boolean).map((n) => `${n}-${w}`).join(', ')}) — run gate-all.mjs${t.published ? '' : ' --stage prototype'} so the page is measured`); continue; }
const regime = t.published && t.published[page.slug] ? 'published' : 'prototype';
facts.pixel[w] = { pct: row.pct, px: null, heightDelta: row.heightDelta, overflowX: null, clipped: row.clipped ?? null, content: row.content || null, verdict: row.pass ? 'PASS' : 'FAIL', label: 'table', regime };
const line = `${fmtPct(row.pct)}, height delta ${row.heightDelta ?? '?'}px, clipped ${row.clipped ?? 'n/a'}, content ${row.contentNA ? 'n/a' : row.content ? `MISSING ${row.content.missing} / HIDDEN ${row.content.hidden}` : 'n/a'} (${relative(process.cwd(), row.file).replace(/\.json$/, '.md')}) [${regime} regime]`;
if (row.pass) pass(`pixel-gate-${w}`, line); else open(`pixel-gate-${w}`, `${(row.reasons || []).join('; ') || 'FAIL'} — ${line}`, 'FAIL');
continue;
}
const best = pick(ofKind('pixel').filter((j) => Number(j.instArgs[3]) === w), parseVerdict, `pixel-gate-${w}`, [0, 2]);
if (!best) continue;
const { j, v } = best;
const label = j.instArgs[4] && !j.instArgs[4].startsWith('--') ? j.instArgs[4] : 'iter';
const regime = regimeOf(j);
const ov = parseOverflow(j.log);
facts.pixel[w] = { pct: v.pct, px: v.px, heightDelta: v.heightDelta, overflowX: ov ? ov.px : null, verdict: v.verdict, label, regime };
const line = `${fmtPct(v.pct)} (${v.px} px, threshold ${v.threshold}%), height delta ${v.heightDelta === null ? '?' : v.heightDelta}px, round ${label} @${w} ${cite(j)} [${regime} regime]`;
const withinHeight = v.heightDelta !== null && Math.abs(v.heightDelta) <= o.heightTolerance;
// The overflow assert and the --full element lines outrank the pixel line: a build wider than its viewport, a
// clipped text / control or a MISSING / HIDDEN link never earns the gate (#125).
const el = parseElements(j.log);
if (ov && ov.px > 0) open(`pixel-gate-${w}`, `horizontal overflow +${ov.px}px at ${w} (scrollWidth ${ov.scrollWidth} > viewport ${ov.viewport}) — ${line}`, 'FAIL');
else if (el.clipped > 0) open(`pixel-gate-${w}`, `clipped ${el.clipped} on the build (clip-probe) — ${line}`, 'FAIL');
else if (el.missing + el.hidden > 0) open(`pixel-gate-${w}`, `content MISSING ${el.missing} / HIDDEN ${el.hidden} (content-presence) — ${line}`, 'FAIL');
else if (v.verdict === 'PASS' && withinHeight) pass(`pixel-gate-${w}`, line);
else open(`pixel-gate-${w}`, v.verdict === 'PASS' ? `|height delta| > ${o.heightTolerance}px tolerance — ${line}` : line, 'FAIL');
}
// The dedicated content-diff run is the acceptance check; a gate.sh --full round's line stands in only when there is none.
const dedicated = ofKind('content-diff');
const cd = dedicated.length ? pick(dedicated, parseFindings, 'content-count') : pick(ofKind('pixel').filter((j) => j.instArgs.includes('--full')), parseFindings, 'content-count');
if (cd) {
facts.contentDiff = cd.v.text;
const line = `content-diff: ${cd.v.text} ${cite(cd.j)}`;
if (cd.v.structural === 0 && cd.v.lost === 0) pass('content-count', line); else open('content-count', line);
}
const md = pick(ofKind('media-reconcile'), parseCounts, 'media-reconcile');
if (md) {
facts.media = md.v.line;
const held = ['omit', 'unresolved'].filter((k) => md.v.counts[k] > 0).map((k) => `${md.v.counts[k]} ${k}`);
const line = `${md.v.line} ${cite(md.j)}`;
if (!held.length) pass('media-reconcile', line); else open('media-reconcile', `${held.join(', ')} hold the gate — ${line}`);
}
// media-reconcile belongs to the delivery chain: without the page's delivered content file it is not required — an
// OPEN (or a deadline / a missing job) reads `n/a:` instead, a pass still stands. The caller drops it from the set.
const delivered = ctx.contentFile ? ctx.contentFile(page) : { file: null, exists: true };
facts.delivered = delivered.exists;
if (!delivered.exists && !gates.includes('media-reconcile')) {
const latest_ = md ? ` — latest run ${md.v.line} ${cite(md.j)} is advisory until then` : '';
evidence['media-reconcile'] = `n/a: no delivered content file yet (${delivered.file}) — media-reconcile runs in the delivery chain (row C)${latest_}`;
}
if (ctx.lint) {
if (!existsSync(page.htmlFile)) notes.push(`${page.slug}: ${page.htmlFile} missing — delivery-lint skipped`);
else {
const r = runLint(ctx.lint, page); facts.deliveryLint = r.line;
const line = `${r.line} (delivery-lint --path ${daPath(page.outputPath)})`;
if (r.ok) pass('delivery-lint', line); else open('delivery-lint', line, 'FAIL');
}
} else {
const lj = pick(ofKind('delivery-lint'), parseLint, 'delivery-lint');
if (lj) { facts.deliveryLint = lj.v.line; const line = `${lj.v.line} ${cite(lj.j)}`; if (lj.v.p0 === 0 && lj.v.p1 === 0) pass('delivery-lint', line); else open('delivery-lint', line, 'FAIL'); }
}
if (page.meta.fidelityTier === 'sibling') {
const archSlug = page.meta.archetypeSource || page.meta.template || null;
const arch = archSlug ? (ctx.pages || []).find((p) => p.slug === archSlug) || null : null;
const paths = pagePaths(page.outputPath);
const probes = jobs.filter((j) => j.kind === 'variance' && (mine.includes(j) || (arch && attribute(j, arch, ctx))));
const vj = pick(probes, (log) => parseVariance(log, paths), 'variance-probe', [0, 2]);
if (vj) {
facts.variance = vj.v.line;
const variants = Array.isArray(page.meta.variants) ? page.meta.variants : [];
const line = `${vj.v.line}${variants.length ? ` — variants [${variants.join(', ')}]` : ''} ${cite(vj.j)}`;
// Only the page's own `■` line is evidence: a summary alone — ✓ or ✗ — says nothing about this page.
if (!vj.v.own) open('variance-probe', `not in the probe — ${vj.v.summary} ${cite(vj.j)}`);
else if (vj.v.deltas && !variants.length) open('variance-probe', `${vj.v.deltas} delta(s) and no variants[] declared — ${line}`);
else pass('variance-probe', line);
}
}
return { gates, evidence, facts, notes };
}
// ---- sidecar merge -----------------------------------------------------------------------------
// gatesPassed = existing ∪ derived (existing first, deduped); gateEvidence merged, derived lines overwrite the same key.
// `stale` names gates the sidecar already lists whose LATEST evidence now reads FAIL/OPEN — kept (never removed), but reported.
export function mergeMeta(meta, derived) {
const existing = Array.isArray(meta.gatesPassed) ? meta.gatesPassed : [];
const gatesPassed = [...existing];
for (const g of derived.gates) if (!gatesPassed.includes(g)) gatesPassed.push(g);
const stale = existing.filter((g) => /^(FAIL|OPEN): /.test(derived.evidence[g] || ''));
const prior = meta.gateEvidence && typeof meta.gateEvidence === 'object' && !Array.isArray(meta.gateEvidence) ? meta.gateEvidence : {};
return { meta: { ...meta, gatesPassed, gateEvidence: { ...prior, ...derived.evidence } }, stale };
}
// ---- progress ledger ---------------------------------------------------------------------------
// `siblings` is merged per slug; `migrate` (totals, per-gate pass counts, the siblings' missing gates) is rebuilt only by
// an unfiltered run — a --slug run must not shrink the ledger's totals. Every other key in the file is preserved.
export function buildProgress(existing, rows, { partial = false } = {}) {
const out = { ...existing };
const sib = rows.filter((r) => r.tier === 'sibling');
out.siblings = { ...(existing.siblings || {}) };
for (const r of sib) out.siblings[r.slug] = { archetype: r.archetype, variants: r.variants, pixel: r.pixel, contentDiff: r.contentDiff, deliveryLint: r.deliveryLint, media: r.media, gatesPassed: r.gatesPassed, migrated: r.migrated };
if (partial) return out;
const gates = {}; for (const r of rows) for (const g of r.gatesPassed) gates[g] = (gates[g] || 0) + 1;
const missing = {}; for (const r of sib) if (r.missing.length) missing[r.slug] = r.missing;
const count = (tier) => rows.filter((r) => r.tier === tier).length;
out.migrate = { ...(existing.migrate || {}), at: new Date().toISOString(), pages: rows.length, archetypes: count('archetype'), siblings: sib.length, thin: count('thin'), gates, missing };
return out;
}
// ---- rows --------------------------------------------------------------------------------------
const compact = (s) => (s === null || s === undefined ? '—' : String(s).replace(/ /g, ''));
export function formatRow(r, widths) {
const px = widths.map((w) => `${w}=${r.pixel[w] ? `${fmtPct(r.pixel[w].pct)}/Δ${r.pixel[w].heightDelta}${r.pixel[w].overflowX > 0 ? `/ovf+${r.pixel[w].overflowX}` : ''}` : '—'}`).join(' ');
const cd = r.contentDiff === null ? '—' : (/^none/.test(r.contentDiff) ? 'none' : compact(r.contentDiff.replace(/ structural 🔴\)/, '🔴)')));
return `${r.slug} ${r.tier || '—'} ${px} cd=${cd} lint=${compact(r.deliveryLint)} media=${compact(r.media)} gates=${r.gatesPassed.length}`;
}
function resolveLint(o) {
// --lint (or its default path) first; otherwise the rollout skill's own copy, in whichever layout holds it (lib/resolve.mjs).
if (existsSync(o.lint) && statSync(o.lint).isFile()) return o.lint;
return o.lintGiven ? null : siblingPath('rollout', 'delivery-lint.mjs');
}
export function collect(o) {
const migrated = resolve(o.migrated);
const notes = [];
const pages = findSidecars(migrated).filter((s) => { if (s.slug) return true; notes.push(`${relative(process.cwd(), s.file)}: no slug — skipped`); return false; });
const unknown = o.slugs.filter((s) => !pages.some((p) => p.slug === s));
if (unknown.length) throw new UsageError(`gate-evidence: no sidecar with slug ${unknown.join(', ')} under ${o.migrated}`);
const selected = o.slugs.length ? pages.filter((p) => o.slugs.includes(p.slug)) : pages;
const jobs = loadJobs(resolve(o.bg));
const lint = resolveLint(o);
if (!lint) notes.push(`delivery-lint: ${o.lint} not found — pass --lint (using run-bg delivery-lint jobs, if any)`);
const contentDir = resolve(o.content);
const tables = loadTables(o.tables, o.widths);
if (o.check) for (const w of o.widths) if (!tables[w].any) notes.push(`no pixel table for ${w} under ${o.tables}/ (prototypes-${w} or all-${w}/summary.json) — the #125 rule wants every prototype and deployed page as a row: run gate-all.mjs [--stage prototype]; the gate.sh logs stand in until then`);
const ctx = { tables, migrated, pages, slugs: pages.map((p) => p.slug), lint, contentFile: (page) => { const c = contentFileFor(contentDir, page.outputPath); return { ...c, file: relative(process.cwd(), c.file).split(sep).join('/') }; } };
const acceptance = acceptanceFor(o.widths);
// The ledger is parsed before any sidecar is touched: a malformed progress.json aborts with nothing written.
const prior = existsSync(o.progress) ? readJson(o.progress) : { data: {}, indent: 2, eol: true };
if (!prior.data || typeof prior.data !== 'object' || Array.isArray(prior.data)) throw new UsageError(`gate-evidence: ${o.progress} is not a JSON object`);
// The ledger is the map of every archetype: the agent's records under `types.<slug>`, this script's `siblings` /
// `migrate`, `_provenance`. A file whose top level is one archetype's record (the old documented example) is wrapped
// under its own slug, losslessly; only a record without a slug is refused.
if (!('types' in prior.data)) {
const single = ['breakpoints', 'pageType', 'archetype'].filter((k) => k in prior.data);
const looksLikeRecord = single.includes('breakpoints') || (single.includes('pageType') && single.includes('archetype'));
if (looksLikeRecord) {
const slug = typeof prior.data.archetype === 'string' ? prior.data.archetype.trim() : '';
if (!slug) throw new UsageError(`gate-evidence: ${o.progress} is one archetype's residual record at the top level (${single.join(', ')}) and names no archetype — move it under types.<archetype> (source-fidelity-gate.md § Residual logging format)`);
prior.data = { types: { [slug]: prior.data } };
notes.push(`${o.progress}: one archetype's record at the top level was wrapped under types.${slug} (source-fidelity-gate.md § Residual logging format)`);
}
}
const rows = []; let updated = 0;
for (const page of selected) {
const d = derive(page, jobs, o, ctx);
notes.push(...d.notes);
const { meta, stale } = mergeMeta(page.meta, d);
for (const g of stale) notes.push(`${page.slug}: ${g} stays in gatesPassed, but the latest evidence reads "${meta.gateEvidence[g].slice(0, 100)}"`);
const text = serialize(meta, page.indent, page.eol);
if (text !== page.text) { updated += 1; if (!o.dryRun) writeAtomic(page.file, text); }
const tier = meta.fidelityTier || null;
// A sibling is not held to media-reconcile before its delivered content file exists (derive() recorded `n/a:` for it).
const required = acceptance.filter((g) => g !== 'media-reconcile' || d.facts.delivered !== false);
rows.push({ slug: page.slug, tier, archetype: meta.archetypeSource || meta.template || null, variants: Array.isArray(meta.variants) ? meta.variants : [], outputPath: page.outputPath, migrated: join(o.migrated, page.outputPath), ...d.facts, gatesPassed: meta.gatesPassed, gateEvidence: meta.gateEvidence, missing: tier === 'sibling' ? required.filter((g) => !meta.gatesPassed.includes(g)) : [], stale });
}
if (rows.length && !o.dryRun) {
mkdirSync(dirname(resolve(o.progress)), { recursive: true });
writeAtomic(o.progress, serialize(buildProgress(prior.data, rows, { partial: o.slugs.length > 0 }), prior.indent, prior.eol));
}
return { rows, updated, notes };
}
// ---- cli ---------------------------------------------------------------------------------------
function cli(argv) {
if (argv.includes('--help') || argv.includes('-h')) { console.log(help()); return 0; }
const o = parseArgs(argv);
const r = collect(o);
for (const n of r.notes) console.error(`gate-evidence: ${n}`);
if (!r.rows.length) { console.log(`gate-evidence: no _meta.json sidecars${o.slugs.length ? ` for --slug ${o.slugs.join(', ')}` : ''} under ${o.migrated} — nothing to collect`); return 0; }
const short = r.rows.filter((row) => row.missing.length);
const stale = r.rows.filter((row) => row.stale.length);
if (o.json) console.log(JSON.stringify(r.rows, null, 2));
else {
for (const row of r.rows) console.log(formatRow(row, o.widths));
for (const row of short) console.log(`${row.slug}: missing ${row.missing.join(', ')}`);
for (const row of stale) console.log(`${row.slug}: stale ${row.stale.join(', ')} — in gatesPassed, but the latest evidence reads FAIL/OPEN (re-earn it, or drop the gate)`);
const n = (k, w) => `${k} ${w}${k === 1 ? '' : 's'}`;
console.log(`gate-evidence: ${n(r.rows.length, 'page')}, ${n(r.updated, 'sidecar')} ${o.dryRun ? 'would be updated (dry-run: nothing written)' : 'updated'}`);
}
return o.check && (short.length || stale.length) ? 2 : 0;
}
// Compare by real path: a symlinked checkout or temp dir must not turn the CLI into a silent no-op.
function safeRealpath(p) { try { return realpathSync(p); } catch { return p; } }
if (process.argv[1] && SELF === safeRealpath(process.argv[1])) {
try { process.exitCode = cli(process.argv.slice(2)); }
catch (e) { console.error(e instanceof UsageError ? e.message : `gate-evidence: ${e.stack || e.message}`); process.exitCode = 1; }
}.tessl-plugin
skills
audit
reference
deploy
reference
scripts
test
diff
direct
dynamics
extract
migrate
prepare-migration
prototype
assets
motion
fixtures
reference
qa
replica
reference
scripts
test
reskin
rollout
spec
stardust
uplift
reference