@vegastack/vegafactory 0.19.0

package/skill/dev-implement/scripts/evidence-check.mjs

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+// dev-implement guard: the evidence comment's required shape. Structure blocks;
+// nothing here warns.
+//
+// Exit codes: 0 pass · 2 blocked (this guard has no warn class).
+// Usage: node evidence-check.mjs --file <evidence.md> --json
+import { compareTaskIds } from './recovery.mjs';
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { GhUnavailable, findMarkerComment, ghJson, parseFlags, parseMarker, renderResult } from './lib/gh.mjs';
+
+const REQUIRED_SECTIONS = [
+  [/\*\*Done:\*\*/, '**Done:** section'],
+  [/\*\*Tests:\*\*/, '**Tests:** section (command → fresh result)'],
+  [/\*\*Review:\*\*/, '**Review:** section (mode + verdict/adjudications)'],
+  [/\*\*Changelog:\*\*/, '**Changelog:** section (entry, or none with a holding reason)'],
+  [/\*\*Docs:\*\*/, '**Docs:** section (brief/plan revisions in sync, or unchanged)'],
+  [/\*\*Not done/, '**Not done / limits:** section (the honest list)'],
+];
+
+export function checkEvidence(text) {
+  const blocks = [];
+
+  const marker = parseMarker(text);
+  if (!marker || marker.keys.type !== 'evidence') {
+    blocks.push('missing evidence marker (<!-- vsk:v1 type=evidence rev=n branch=... sha=... -->)');
+  } else {
+    if (!marker.keys.branch) blocks.push('evidence marker missing branch=');
+    if (!/^[0-9a-f]{7,}$/.test(marker.keys.sha ?? '')) blocks.push('evidence marker missing a real sha=');
+  }
+
+  for (const [pattern, label] of REQUIRED_SECTIONS) {
+    if (!pattern.test(text)) blocks.push(`missing ${label}`);
+  }
+
+  if (!/Branch:\s*\S+\s*@\s*[0-9a-f]{7,}/.test(text)) blocks.push('missing "Branch: <name> @ <sha7>" tail line');
+
+  return { blocks, warns: [] };
+}
+
+// The plan comment's checkboxes and the ledger's completed tasks are two records
+// of the same fact, and the checkbox — a second write, to a different comment
+// than the ledger the session already maintains — is the one that silently rots.
+// At hand-back the ledger's completed tasks must be reflected in the plan's
+// checkboxes, or the operator reads a false x/y. Distinct task numbers with a
+// `complete` line in the ledger, versus `[x]` boxes in the plan.
+export function checkTaskConsistency(comments) {
+  const blocks = [];
+  const warns = [];
+  const plan = findMarkerComment(comments, 'plan')?.comment?.body;
+  const ledger = findMarkerComment(comments, 'ledger')?.comment?.body;
+
+  // No plan comment, or a plan with no checkboxes (e.g. a research issue), is
+  // nothing to reconcile — not a violation. No ledger yet is the same.
+  if (!plan || !ledger) return { blocks, warns };
+  const rows = [...plan.matchAll(/^-\s*\[([ x])\].*$/gim)];
+  if (!rows.length) return { blocks, warns };
+  const ids = rows.map(row => /<!--\s*task-id:([1-9]\d*-T[1-9]\d*)\s*-->/.exec(row[0])?.[1]);
+  if (ids.some(id => !id) || new Set(ids).size !== ids.length) {
+    blocks.push('plan task identities missing or duplicate; regenerate only from newly approved scope');
+    return { blocks, warns };
+  }
+  const planDone = rows.flatMap((row, i) => row[1].toLowerCase() === 'x' ? [ids[i]] : []);
+  const completed = [...ledger.matchAll(/^-\s*(?:Task\s+)?([1-9]\d*-T[1-9]\d*):\s*complete\b/gim)].map(row => row[1]);
+  if (/^-\s*Task\s+\d+:\s*complete\b/im.test(ledger)) blocks.push('legacy numeric ledger completion lacks approved task identity');
+  const difference = compareTaskIds(planDone, completed);
+  if (difference.missing.length || difference.unknown.length) blocks.push('task identity mismatch: plan-only [' + difference.missing.join(', ') + ']; ledger-only [' + difference.unknown.join(', ') + ']');
+  return { blocks, warns };
+}
+
+// Fetch the issue's comments and reconcile plan checkboxes against the ledger.
+// Fails closed: an unreachable gh blocks rather than passing silently.
+function taskConsistencyFromIssue({ issue, repo: repoFlag }) {
+  const repo = repoFlag || ghJson(['repo', 'view', '--json', 'nameWithOwner']).nameWithOwner;
+  const comments = ghJson(['api', 'repos/' + repo + '/issues/' + issue + '/comments', '--paginate']);
+  return checkTaskConsistency(comments);
+}
+
+const invokedDirectly = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (invokedDirectly) {
+  const flags = parseFlags(process.argv.slice(2));
+  let outcome;
+  if (!flags.file) {
+    outcome = { blocks: ['usage: evidence-check.mjs --file <evidence.md> [--issue <n> --repo <o/r>] [--json]'], warns: [] };
+  } else {
+    try {
+      outcome = checkEvidence(readFileSync(flags.file, 'utf8'));
+    } catch (error) {
+      outcome = { blocks: [`cannot read evidence: ${error.message}`], warns: [] };
+    }
+    // Consistency check only when an issue is named — keeps the file-shape check
+    // network-free by default. A gh failure fails closed onto the block list.
+    if (flags.issue) {
+      try {
+        const consistency = taskConsistencyFromIssue(flags);
+        outcome.blocks.push(...consistency.blocks);
+        outcome.warns.push(...consistency.warns);
+      } catch (error) {
+        outcome.blocks.push(error instanceof GhUnavailable ? `cannot verify plan/ledger consistency: ${error.message}` : `consistency check error: ${error.message}`);
+      }
+    }
+  }
+  const { exitCode, text } = renderResult('evidence-check', outcome, { json: Boolean(flags.json) });
+  console.log(text);
+  process.exit(exitCode);
+}

package/skill/dev-implement/scripts/evidence-upload.mjs

@@ -0,0 +1,181 @@
+#!/usr/bin/env node
+// dev-implement evidence-upload: put one screenshot into the shared evidence
+// repo through the GitHub contents API. Dry-run by default — it prints the PUT
+// it would make (path and size, never the bytes) — and sends only under
+// --write. The request body ({message, content}) travels over gh's stdin
+// (`--input -`), so the base64 payload never touches argv or any output line.
+// A 409 on the first PUT (a concurrent upload chose the same name) is retried
+// once under a fresh name. Symlinks, non-image extensions, and empty files are
+// refused before any network call.
+//
+// Exit codes: 0 planned or sent · 1 sent after a 409 retry (warn) · 2 refused
+// (reasons printed). Usage:
+//   node evidence-upload.mjs --repo <o/r> --issue <n> --file <png>
+//     [--evidence-repo <o/r>] [--dev-md <path>] [--write] [--json]
+// The evidence repo comes from dev.md's `evidence-repo:` knob; --evidence-repo
+// overrides it. The uploaded path is <repo-name>/<issue>/<timestamp>-<name>.
+import { lstatSync, readFileSync } from 'node:fs';
+import { basename, extname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { GhUnavailable, ghJson, parseFlags, renderResult } from './lib/gh.mjs';
+
+export const IMAGE_EXTENSIONS = ['.png', '.jpg', '.jpeg', '.webp', '.gif'];
+const REPO = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
+const ISSUE = /^\d+$/;
+
+// The contents-API path for one file in the evidence repo — the one place it is built.
+// Interpolated paths and messages are concatenated, not template literals: a backtick at a
+// shell-word start whose first inner token carries the interpolation trips SkillSpector's
+// bounded parser for the whole skill (skill-maintainer's standards.md, known behaviours).
+const apiPathFor = (evidenceRepo, path) => 'repos/' + evidenceRepo + '/contents/' + path;
+
+// First `evidence-repo:` knob line in dev.md; a trailing `# comment` is ignored
+// because the value stops at whitespace.
+export function evidenceRepoFrom(devMd) {
+  const match = /^evidence-repo:\s*(\S+)/m.exec(devMd ?? '');
+  return match ? match[1] : null;
+}
+
+// UTC YYYYMMDD-HHMMSS — the collision-avoiding prefix on every evidence file.
+export function timestamp(now) {
+  return now.toISOString().replace(/[-:]/g, '').replace('T', '-').slice(0, 15);
+}
+
+// Pure plan: file checks by metadata only (lstat — the file's contents are
+// never read here), evidence repo resolution, target path and size. `put` is
+// null whenever anything blocks.
+export function plan({ repo, issue, file, evidenceRepo, devMd, now = new Date() }) {
+  const blocks = [];
+  // repo and issue become path segments in the evidence repo, so each is held
+  // to its own shape — a stray `../` would otherwise land the file elsewhere.
+  if (!repo) blocks.push('--repo <o/r> is required (the repo the evidence belongs to)');
+  else if (!REPO.test(repo)) blocks.push(`--repo ${repo} is not <owner>/<name>`);
+  if (!issue) blocks.push('--issue <n> is required');
+  else if (!ISSUE.test(String(issue))) blocks.push(`--issue ${issue} is not an issue number`);
+  if (!file) blocks.push('--file <png> is required');
+
+  let bytes = 0;
+  if (file) {
+    let stat = null;
+    try {
+      stat = lstatSync(file);
+    } catch (error) {
+      blocks.push(`cannot read ${file}: ${error.code || error.message}`);
+    }
+    if (stat) {
+      if (stat.isSymbolicLink()) {
+        blocks.push(file + ' is a symlink — evidence is uploaded from a regular file so the bytes sent are the bytes named');
+      } else if (!stat.isFile()) {
+        blocks.push(file + ' is not a regular file');
+      } else {
+        const ext = extname(file).toLowerCase();
+        if (!IMAGE_EXTENSIONS.includes(ext)) {
+          blocks.push((ext || '(no extension)') + ' is not an image extension (png, jpg, jpeg, webp, gif)');
+        }
+        if (stat.size === 0) blocks.push(file + ' is empty (0 bytes)');
+        bytes = stat.size;
+      }
+    }
+  }
+
+  const target = evidenceRepo || evidenceRepoFrom(devMd);
+  if (!target) blocks.push('no evidence repo: dev.md has no evidence-repo: line and --evidence-repo was not passed');
+  else if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(target)) blocks.push(`evidence repo "${target}" is not owner/name — it becomes an API path segment, so it is checked before use`);
+
+  if (blocks.length > 0) return { blocks, put: null };
+
+  const path = repo.slice(repo.indexOf('/') + 1) + '/' + issue + '/' + timestamp(now) + '-' + basename(file);
+  return {
+    blocks,
+    put: { evidenceRepo: target, path, bytes, apiPath: apiPathFor(target, path), message: `evidence #${issue}` },
+  };
+}
+
+// The retry name after a 409: `-r2` after the timestamp, so a concurrent
+// upload's file and this one both survive under the same issue directory.
+export function retryPath(path) {
+  return path.replace(/(\/\d{8}-\d{6})-/, '$1-r2-');
+}
+
+// One PUT through gh with the JSON body on stdin. A 409 (a concurrent upload
+// chose the same name) is retried once under retryPath; any other failure,
+// or a second one, propagates to the caller.
+export function upload(put, contentBase64, { gh } = {}) {
+  const warns = [];
+  const send = (apiPath) => ghJson(['api', '-X', 'PUT', apiPath, '--input', '-'], {
+    gh,
+    input: JSON.stringify({ message: put.message, content: contentBase64 }),
+  });
+  let path = put.path;
+  let response;
+  let attempts = 1;
+  try {
+    response = send(put.apiPath);
+  } catch (error) {
+    if (!(error instanceof GhUnavailable) || error.httpStatus !== 409) throw error;
+    path = retryPath(put.path);
+    warns.push(`first PUT hit HTTP 409 (a concurrent upload chose the same name) — retried as ${path}`);
+    attempts = 2;
+    response = send(apiPathFor(put.evidenceRepo, path));
+  }
+  return { attempts, path, url: response?.content?.html_url ?? null, warns };
+}
+
+// Plan, then (only under --write) read the bytes and send them. The base64
+// string exists only inside the request body handed to gh's stdin.
+export function run(flags, { gh, now = new Date() } = {}) {
+  const devMdPath = flags['dev-md'] || '.vegastack/dev.md';
+  let devMd = '';
+  if (!flags['evidence-repo']) {
+    try {
+      devMd = readFileSync(devMdPath, 'utf8');
+    } catch {
+      return { blocks: [`cannot read ${devMdPath} (pass --dev-md <path> or --evidence-repo <o/r>)`], warns: [], upload: null };
+    }
+  }
+  const planned = plan({
+    repo: flags.repo,
+    issue: flags.issue,
+    file: flags.file,
+    evidenceRepo: flags['evidence-repo'],
+    devMd,
+    now,
+  });
+  if (planned.blocks.length > 0) return { blocks: planned.blocks, warns: [], upload: null };
+
+  const { put } = planned;
+  const summary = { evidenceRepo: put.evidenceRepo, path: put.path, bytes: put.bytes };
+  if (!flags.write) return { blocks: [], warns: [], upload: { ...summary, mode: 'dry-run', attempts: 0, url: null } };
+
+  const sent = upload(put, readFileSync(flags.file).toString('base64'), { gh });
+  return {
+    blocks: [],
+    warns: sent.warns,
+    upload: { ...summary, path: sent.path, mode: 'sent', attempts: sent.attempts, url: sent.url },
+  };
+}
+
+const invokedDirectly = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (invokedDirectly) {
+  const flags = parseFlags(process.argv.slice(2), ['json', 'write']);
+  let outcome;
+  try {
+    outcome = run(flags);
+  } catch (error) {
+    outcome = {
+      blocks: [error instanceof GhUnavailable ? `cannot upload: ${error.message}` : `evidence-upload error: ${error.message}`],
+      warns: [],
+      upload: null,
+    };
+  }
+  const { exitCode, text } = renderResult('evidence-upload', outcome, { json: false });
+  if (flags.json) {
+    const { blocks, warns, upload: result } = outcome;
+    console.log(JSON.stringify({ guard: 'evidence-upload', ok: blocks.length === 0, blocks, warns, upload: result }, null, 2));
+  } else {
+    const lines = [text];
+    if (outcome.upload) lines.splice(1, 0, '  ' + outcome.upload.mode + ': ' + outcome.upload.path + ' (' + outcome.upload.bytes + ' bytes)');
+    console.log(lines.join('\n'));
+  }
+  process.exit(exitCode);
+}

package/skill/dev-implement/scripts/learning.mjs

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+// Bounded lessons reuse ordinary-work evidence. No model, network or vendor memory.
+const sha=/^[a-f0-9]{40}$/;
+const digest=/^[a-f0-9]{64}$/;
+const closed=(row,keys)=>row&&typeof row==='object'&&!Array.isArray(row)&&Object.keys(row).length===keys.length&&keys.every(key=>Object.hasOwn(row,key));
+const safePath=value=>typeof value==='string'&&value.length>0&&!value.startsWith('/')&&!value.includes('\\')&&!/[\0\r\n]/.test(value)&&!value.split('/').some(part=>['.','..',''].includes(part));
+const nativePath=path=>/(?:^|\/)\.(?:claude|codex)\/.*memory|(?:^|\/)MEMORY\.md$/i.test(path);
+const protectedPath=path=>/(?:^|\/)(?:AGENTS\.md|CLAUDE\.md|org\.md|dev\.md|decisions\.md|settings\.json|factory\.json)$/.test(path);
+export function validateLesson(row) {
+  if (!closed(row,['id','repo','taskId','scopeDigest','sourceSha','statement','evidenceRefs','targetPaths','undoRef','state','supersedes'])||!/^lesson-[a-f0-9]{32}$/.test(row.id)||!/^\S+\/\S+$/.test(row.repo)||!/^\d+-T\d+$/.test(row.taskId)||!digest.test(row.scopeDigest)||!sha.test(row.sourceSha)||typeof row.statement!=='string'||!row.statement.trim()||Buffer.byteLength(row.statement)>768||/[\0\r]/.test(row.statement)) throw Error('invalid lesson identity');
+  if (!['observed','validated','adopted','rejected','reverted'].includes(row.state)||!Array.isArray(row.targetPaths)||!row.targetPaths.length||row.targetPaths.length>32||row.targetPaths.some(path=>!safePath(path)||nativePath(path))||new Set(row.targetPaths).size!==row.targetPaths.length||typeof row.undoRef!=='string'||!/^git:[a-f0-9]{40}$/.test(row.undoRef)||!Array.isArray(row.supersedes)||row.supersedes.length>32||row.supersedes.some(id=>!/^lesson-[a-f0-9]{32}$/.test(id)||id===row.id)) throw Error('invalid reversible lesson');
+  if (!Array.isArray(row.evidenceRefs)||!row.evidenceRefs.length||row.evidenceRefs.length>8||row.evidenceRefs.some(ref=>!closed(ref,['kind','ref','sha','passed'])||!['check','review','measurement'].includes(ref.kind)||typeof ref.ref!=='string'||ref.ref.length>256||!sha.test(ref.sha)||typeof ref.passed!=='boolean')) throw Error('invalid lesson evidence');
+  return row;
+}
+export function evaluateLesson(candidate,context) {
+  const answer=(action,reason)=>({action,reason});
+  if (context?.protectedChange || candidate?.targetPaths?.some(protectedPath)) return answer('propose','protected rules require explicit approval');
+  try { validateLesson(candidate); } catch(error) { return answer('reject',error.message); }
+  if (context.learningEnabled!==true) return answer('reject','learning disabled or policy unavailable');
+  if (candidate.repo!==context.repo||candidate.scopeDigest!==context.scopeDigest||candidate.sourceSha!==context.sourceSha||!context.taskIds?.includes(candidate.taskId)) return answer('reject','lesson scope or source differs');
+  if (candidate.targetPaths.some(path=>!context.allowedFiles?.includes(path))||context.paidProviderChange) return answer('propose','outside reversible local authorization');
+  if (!['validated','adopted'].includes(candidate.state)||context.reversible!==true||context.improved!==true) return answer('reject','ordinary work improvement and exact undo unverified');
+  if (!candidate.evidenceRefs.every(ref=>context.verifiedEvidence?.some(verified=>JSON.stringify(verified)===JSON.stringify(ref)))||!candidate.evidenceRefs.some(ref=>ref.passed&&ref.sha===candidate.sourceSha)) return answer('reject','source-bound evidence unavailable');
+  if (context.reviewRequired&&!candidate.evidenceRefs.some(ref=>ref.kind==='review'&&ref.passed&&ref.sha===candidate.sourceSha)) return answer('reject','independent review required');
+  if (context.adoption==='propose-only') return answer('propose','policy requires proposal');
+  return answer('adopt','verified reversible improvement');
+}
+export function selectLessons(packet,{repo,scopeDigest,sourceSha,maxItems=3,maxBytes=2048}) {
+  if (!Array.isArray(packet?.learning)||packet.learning.length>32||Buffer.byteLength(JSON.stringify(packet.learning))>16384) return [];
+  const count=Math.min(3,Math.max(0,maxItems)),limit=Math.min(2048,Math.max(0,maxBytes)),selected=[],seen=new Set();
+  const superseded=new Set(packet.learning.filter(row=>['adopted','reverted'].includes(row.state)).flatMap(row=>row.supersedes??[]));
+  for (const row of packet.learning) {
+    try {validateLesson(row);}catch{continue;}
+    if(row.state!=='adopted'||row.repo!==repo||row.scopeDigest!==scopeDigest||row.sourceSha!==sourceSha||superseded.has(row.id))continue;
+    const key=JSON.stringify([repo,[...row.targetPaths].sort(),row.evidenceRefs]);
+    if(seen.has(key)||selected.some(other=>other.targetPaths.some(path=>row.targetPaths.includes(path))))continue;
+    if(selected.length>=count||Buffer.byteLength(JSON.stringify([...selected,row]))>limit)continue;
+    seen.add(key);selected.push(row);
+  }
+  return selected;
+}