@vegastack/skills 0.10.0 → 0.11.0

package/skill/dev-status/scripts/status.mjs

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+// dev-status data gatherer: everything the board report needs, deterministically,
+// read-only, markers-only. The skill renders; this script never invents state.
+//
+// Usage: node status.mjs [--repo o/r] [--stale-days 3] [--dev-md <path>] --json
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const DEFAULT_LABELS = ['needs-operator', 'needs-plan', 'ready', 'working', 'for-operator', 'risky', 'research', 'quick-build', 'full-plan', 'epic'];
+
+// The labels: knob lists names positionally (5 states, risky, 3 scopes, epic —
+// the dev-profile template order); a project that renamed labels still parses.
+export function readKnobs(devMdText) {
+  const labelsLine = /^labels:\s*([^\n#]+)/m.exec(devMdText ?? '')?.[1]?.trim();
+  const names = labelsLine ? labelsLine.split(/\s+/) : DEFAULT_LABELS;
+  const labels = names.length >= 10 ? names : DEFAULT_LABELS;
+  return {
+    states: labels.slice(0, 5),
+    risky: labels[5],
+    scopes: labels.slice(6, 9),
+    register: /^decisions:\s*(\S+)/m.exec(devMdText ?? '')?.[1] ?? '.vegastack/decisions.md',
+  };
+}
+
+function gh(args) {
+  // env spread at call time: some runtimes pass a startup env snapshot to
+  // children, which would hide the VSK_GH/GH_STUB_DIR test seam.
+  const out = execFileSync(process.env.VSK_GH || 'gh', args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], env: { ...process.env } });
+  return JSON.parse(out);
+}
+
+export function ageDays(iso, now = Date.now()) {
+  return Math.floor((now - Date.parse(iso)) / 86_400_000);
+}
+
+export function parseMarker(body) {
+  const match = /<!--\s*vsk:v1\s+([^>]*?)\s*-->/.exec(body ?? '');
+  if (!match) return null;
+  const keys = {};
+  for (const pair of match[1].split(/\s+/)) {
+    const eq = pair.indexOf('=');
+    if (eq > 0) keys[pair.slice(0, eq)] = pair.slice(eq + 1);
+  }
+  return { keys };
+}
+
+// Count plan-comment checkboxes: [done, total]. No plan comment → null.
+export function taskProgress(comments) {
+  for (const c of comments ?? []) {
+    if (parseMarker(c.body)?.keys?.type === 'plan') {
+      const done = (c.body.match(/^- \[x\]/gim) ?? []).length;
+      const total = done + (c.body.match(/^- \[ \]/gm) ?? []).length;
+      return total > 0 ? [done, total] : null;
+    }
+  }
+  return null;
+}
+
+// Latest ledger comment's updated_at → staleness signal for working issues.
+export function ledgerMovedAt(comments) {
+  let at = null;
+  for (const c of comments ?? []) {
+    if (parseMarker(c.body)?.keys?.type === 'ledger') at = c.updated_at;
+  }
+  return at;
+}
+
+// Decision proposals not yet in the register: marker type=decision comments
+// (and evidence **Decision:** lines) whose text isn't in the register file.
+export function pendingDecisions(comments, registerText) {
+  const pending = [];
+  for (const c of comments ?? []) {
+    const type = parseMarker(c.body)?.keys?.type;
+    if (type === 'decision') {
+      const gist = (c.body.split('\n').find((l) => l.trim() && !l.startsWith('<!--') && !l.startsWith('#')) ?? '').trim();
+      if (gist && !(registerText ?? '').includes(gist.slice(0, 60))) pending.push(gist);
+    }
+    if (type === 'evidence') {
+      const m = /\*\*Decision:\*\*\s*([^\n]+)/.exec(c.body);
+      if (m && !/^none\b/i.test(m[1].trim()) && !(registerText ?? '').includes(m[1].trim().slice(0, 60))) pending.push(m[1].trim());
+    }
+  }
+  return pending;
+}
+
+// CheckRuns carry `conclusion`; StatusContexts carry `state`. An empty rollup
+// is "no-checks", never green.
+export function checksState(rollup) {
+  if (!rollup || rollup.length === 0) return 'no-checks';
+  const ok = (c) => ['SUCCESS', 'NEUTRAL', 'SKIPPED'].includes(c.conclusion ?? c.state ?? '');
+  return rollup.every(ok) ? 'green' : 'pending-or-red';
+}
+
+export function gatherStatus({ repo, staleDays = 3, devMdPath = '.vegastack/dev.md', chroniclePath = '.vegastack/chronicle.md', now = Date.now() } = {}) {
+  const resolvedRepo = repo || gh(['repo', 'view', '--json', 'nameWithOwner']).nameWithOwner;
+  const devMdText = existsSync(devMdPath) ? readFileSync(devMdPath, 'utf8') : '';
+  const knobs = readKnobs(devMdText);
+  const board = {};
+  for (const label of knobs.states) {
+    board[label] = gh(['issue', 'list', '-R', resolvedRepo, '--label', label, '--state', 'open',
+      '--json', 'number,title,url,updatedAt,labels,assignees']).map((i) => ({
+      number: i.number, title: i.title, url: i.url,
+      ageDays: ageDays(i.updatedAt, now),
+      scope: (i.labels ?? []).map((l) => l.name).find((n) => knobs.scopes.includes(n)) ?? null,
+      risky: (i.labels ?? []).some((l) => l.name === knobs.risky),
+    }));
+  }
+
+  // Enrich working + for-operator issues with comment-derived signals.
+  const registerText = existsSync(knobs.register) ? readFileSync(knobs.register, 'utf8') : '';
+  const decisions = [];
+  for (const bucket of [knobs.states[3], knobs.states[4]]) {
+    for (const issue of board[bucket]) {
+      const comments = gh(['api', `repos/${resolvedRepo}/issues/${issue.number}/comments`, '--paginate']);
+      issue.tasks = taskProgress(comments);
+      const moved = ledgerMovedAt(comments);
+      issue.ledgerAgeDays = moved ? ageDays(moved, now) : null;
+      issue.stale = bucket === knobs.states[3] && (issue.ledgerAgeDays === null || issue.ledgerAgeDays >= staleDays);
+      decisions.push(...pendingDecisions(comments, registerText).map((d) => ({ issue: issue.number, gist: d })));
+    }
+  }
+
+  const prs = gh(['pr', 'list', '-R', resolvedRepo, '--json', 'number,title,url,statusCheckRollup'])
+    .map((p) => ({
+      number: p.number, title: p.title, url: p.url,
+      checks: checksState(p.statusCheckRollup),
+    }));
+
+  let lastChronicle = null;
+  if (existsSync(chroniclePath)) {
+    const m = /^## (\d{2}-\d{2}-\d{4}) — (.+)$/m.exec(readFileSync(chroniclePath, 'utf8'));
+    if (m) lastChronicle = { date: m[1], title: m[2] };
+  }
+
+  return { repo: resolvedRepo, staleDays, board, prs, pendingDecisions: decisions, lastChronicle };
+}
+
+const invokedDirectly = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (invokedDirectly) {
+  const argv = process.argv.slice(2);
+  const get = (f) => { const i = argv.indexOf(f); return i === -1 ? undefined : argv[i + 1]; };
+  try {
+    const staleDaysRaw = Number(get('--stale-days'));
+    const data = gatherStatus({ repo: get('--repo'), staleDays: Number.isFinite(staleDaysRaw) && staleDaysRaw >= 1 ? staleDaysRaw : 3, devMdPath: get('--dev-md') });
+    console.log(JSON.stringify(data, null, argv.includes('--json') ? 2 : 0));
+  } catch (error) {
+    console.error(`status: cannot verify — ${error.message}`);
+    process.exit(2);
+  }
+}

package/skill/skillify/SKILL.md

@@ -139,6 +139,6 @@ Phase 6: bun run check green; 8/8 → properly skilled
 | Need | Read |
 |---|---|
 | description engineering, writing style, numeric limits, token budgets, script-vs-instructions, volatile facts | [authoring](references/authoring.md) |
-| eval method, pass criteria, trigger-query doctrine, cycle protocol, KNOWN_GAPS, model guidance | [eval playbook](references/eval-playbook.md) |
+| eval method, pass criteria, trigger-query doctrine (incl. family-level re-runs), workflow-skill drills, cycle protocol, KNOWN_GAPS, model guidance | [eval playbook](references/eval-playbook.md) |
 | the scaffolded starting points | `assets/templates/` |
 | skillify's own freshness stance | [refresh/REFRESH.md](refresh/REFRESH.md) |

package/skill/skillify/references/eval-playbook.md

@@ -28,6 +28,12 @@ The with-skill run must be *materially* better on the dimensions the skill exist
 
 The body eval above assumes the skill got loaded. Separately check the description triggers correctly: walk `tests/fixtures/trigger-queries.json` and judge, for each query, whether an agent seeing only the skill list (name + description) would load this skill. Near-miss negatives are the valuable half — a description that survives them draws a real boundary. Fix failures by editing the *description* (triggers, boundary clause), never by stuffing workflow summary into it.
 
+**Family-level re-run:** whenever the skill family changes — a skill added, renamed, or removed — re-run the trigger eval across the FULL installed set, not just the changed skill: cross-skill collisions (two descriptions both claiming a query) only appear at family level, and the `ambiguous_with` entries in every skill's fixtures are the cases to walk first.
+
+## Workflow skills — multi-turn, state-bearing
+
+A skill whose value lives in a multi-turn, external-state workflow (gh labels, comments, branches) gets only partial proof from single-prompt subagent runs: those cover prose quality and format compliance. Its end-to-end proof is a **sandbox drill** — a throwaway repo walked through the real flow with the real tools — run before release-level claims, not per edit. Single-prompt evals remain the per-change gate; the drill is the workflow-level one.
+
 ## Cycle protocol (at most 3)
 
 ```

package/skill-integrity.json

@@ -3,9 +3,10 @@
   "skills": {
     "dev-architect": {
       "files": {
-        "SKILL.md": "b6f1fdba7dbae4eadf1c403f7fda7207cc3bea74feb973c2b78ba9de017b9c58",
+        "SKILL.md": "3b0b6f2d18f63f644bb396be9fdd7fbc8c8473c0b29190741c9623407bf82cc3",
         "agents/openai.yaml": "99023b056d5c568ff3acc059e5bb7a4e6cfa5261cd0d35a525407f9e159de562",
         "references/ai-agents.md": "565e5d480f7e342adf43f9b864ab4cb66b7e513f0ea676de66909fe0ccd95988",
+        "references/conventions.md": "815f5189daff1b71b3251b7a57de183a4a387fcdedbd5875e673d5bd3de398fc",
         "references/data.md": "781d3ae7d3bca0b269c123a10013226f3878503dd1224ee526edd102bfc270f0",
         "references/infra.md": "a6d07c5e9ea67788edac7b80742a5588a1f019e387163bfdab531314fb54d009",
         "references/mobile.md": "b6ee481df810f3fd5466487848287ceeb33ac98bf6db0bc2d65c4d6fa397284f",
@@ -18,29 +19,80 @@
         "refresh/sources.json": "2cfd851090f5a0b661bd88c9bbe62ca3f99b744066817cc1067378520616f68e"
       }
     },
+    "dev-chronicle": {
+      "files": {
+        "SKILL.md": "115dc19b93fd266d001592a50acfd21ebd7ec38dec774466b7b18226a20abcc4",
+        "agents/openai.yaml": "765b12e17b7fce88c53ca0fae735bf0efceb843cc3703b91bc1801ab5cac06b4",
+        "references/conventions.md": "815f5189daff1b71b3251b7a57de183a4a387fcdedbd5875e673d5bd3de398fc",
+        "refresh/REFRESH.md": "760e66642eec426cd5ab2319613e817adf5bbd7b64c8eaa22dd13497351bf9c1",
+        "refresh/sources.json": "a7ba2340964dc70410626087686145b5790a0e763a18ef2c4d9aa37e950f2e04"
+      }
+    },
+    "dev-debug": {
+      "files": {
+        "SKILL.md": "62f86b8b88a66c6e8f44eba434fdc8b8dc044deda814cb9a2d1e8ec0dee79538",
+        "agents/openai.yaml": "4aa52b5c620b0bf4de7f1609867956ce762d83dc4297ab5670a68c206ae63075",
+        "references/conventions.md": "815f5189daff1b71b3251b7a57de183a4a387fcdedbd5875e673d5bd3de398fc",
+        "references/loop-ladder.md": "ddcb45ec2241bc5dc25936348074cdcc8f9af848e90b363351a7faf97007c256",
+        "refresh/REFRESH.md": "70816e44c8d6a5d11b73eb40762e6d8931724517e0b4c138eb07bc8e91b45008",
+        "refresh/sources.json": "a7ba2340964dc70410626087686145b5790a0e763a18ef2c4d9aa37e950f2e04"
+      }
+    },
     "dev-implement": {
       "files": {
-        "SKILL.md": "e48d3dd03b9baa0c7e0492b2362160f0b4e1eb63e4c6a11bad5e05a334c229a1",
+        "SKILL.md": "781d8686a763489983d7e9a37ee6817c5e6f41bb794b53d4d72d20abfdc580af",
         "agents/openai.yaml": "1abab383deca54d32749fd9156f9a6211fe96e02e0166dc8a16ff8459ac31b74",
+        "references/conventions.md": "815f5189daff1b71b3251b7a57de183a4a387fcdedbd5875e673d5bd3de398fc",
+        "references/ledger-and-resume.md": "46bd4ad38eb70376d9ad36ac80269abc337c12e692e2b7de6483584f1003346a",
         "refresh/REFRESH.md": "7b854109d897b78b3055bf1ab89517afdca65c12eb65a4d009141e3ee11cf58f",
-        "refresh/sources.json": "7bd883e5b3512e236a909ad6ff20c97f3555785867c31fd728256c7c2c514c74"
+        "refresh/sources.json": "7bd883e5b3512e236a909ad6ff20c97f3555785867c31fd728256c7c2c514c74",
+        "scripts/evidence-check.mjs": "9a360e6c5460d46b271b28457ee6be92f165c54c771c2dc6860c4a52e6890a9a",
+        "scripts/lib/gh.mjs": "d2261e4b3e2d7b3cdc58123b1503c0264664d7e5a258e90d0caa79333466975a",
+        "scripts/preflight.mjs": "1bf47b6d147c8603e28d96f7c81f2b4db61b60a3811190ca96b36d83129820d5"
       }
     },
     "dev-intake": {
       "files": {
-        "SKILL.md": "dcf23ce238b7d0b2c14d0f9edbfed2ac5800b1054e48138946c504710dc6ff49",
+        "SKILL.md": "b5d89453176ad23c047fd38e38199c682c358df0468c9082edd8a6e34e6f229f",
         "agents/openai.yaml": "5473d2d3efffc518c07dfa8e6788c6535a5054ceca696119c5856ad265ef5581",
-        "references/brief-template.md": "98662ec19bca5785a2a9b49aa070ca1d05f1317ea7cc610f913886a11efabcc8",
+        "references/brief-template.md": "906c6b805f9737755f4d4b34fd16d4296924b95039379ea86bc59973949d9823",
+        "references/conventions.md": "815f5189daff1b71b3251b7a57de183a4a387fcdedbd5875e673d5bd3de398fc",
         "refresh/REFRESH.md": "bb5265cee98c243c775c3e5fbc59de4b84ab54e828f3290d7c19e47291d66f71",
-        "refresh/sources.json": "7bd883e5b3512e236a909ad6ff20c97f3555785867c31fd728256c7c2c514c74"
+        "refresh/sources.json": "7bd883e5b3512e236a909ad6ff20c97f3555785867c31fd728256c7c2c514c74",
+        "scripts/brief-lint.mjs": "7202def7c3a8b0049e67d60602a4c652d3c99f5fa1711080fd46b94ff4dc3684"
+      }
+    },
+    "dev-plan": {
+      "files": {
+        "SKILL.md": "3c38b3f78f0f03d04370ea91aad99966fca5313fbe2919f44187d7c585c87866",
+        "agents/openai.yaml": "4b9ccc9870b4eafb73c1bc4492a0b5a530097bbcbae11dbf3235160f4f05587b",
+        "references/conventions.md": "815f5189daff1b71b3251b7a57de183a4a387fcdedbd5875e673d5bd3de398fc",
+        "references/plan-format.md": "a915acce2fc447e685077756aeb94fdc3f84139800703034987b8409971493db",
+        "refresh/REFRESH.md": "e22830102db9cf7c6db1e8fea9e73b7845b77e59da0d44e186a6b26d6dc9ebe1",
+        "refresh/sources.json": "a7ba2340964dc70410626087686145b5790a0e763a18ef2c4d9aa37e950f2e04",
+        "scripts/plan-lint.mjs": "c35e445bdc51e704de807d10a528ba2499c9d28b3840124d84f1c3a6350d8ae7"
+      }
+    },
+    "dev-review": {
+      "files": {
+        "SKILL.md": "00c1b86038ef8497480b440ee490019702013692c8ac5266a8340464745e0cf5",
+        "agents/openai.yaml": "3f35d3dc60f179d4ac2526997c4d10173ba3018d06f0dbe77e209ce2978fa702",
+        "assets/review-known-patterns.md.template": "a521aba1e59c44645bbb9f9b6b0fbba3423f694b2e7bbcb1dbabe7d2c8e5756a",
+        "references/conventions.md": "815f5189daff1b71b3251b7a57de183a4a387fcdedbd5875e673d5bd3de398fc",
+        "references/cross-agent.md": "3541715d0563703373ea3d93582119b80356d1cbdee19ce17f958c0f7c914884",
+        "references/dispatch-prompts.md": "259e8f468cedb961359bad6d080515d4682a9e5aafd268a192d51454d2842c50",
+        "references/security-axis.md": "a152d4500ec8ba21b07be130a529156485737921625c91ab50d90a187b5f8b1f",
+        "refresh/REFRESH.md": "242c1efe630327abe12bf9db4c4085aaf05b262a4dbd885b12b0f29cdd4a285d",
+        "refresh/sources.json": "a7ba2340964dc70410626087686145b5790a0e763a18ef2c4d9aa37e950f2e04"
       }
     },
     "dev-setup": {
       "files": {
-        "SKILL.md": "9a05330771c56bb1816fafc36f8e33d9e2b7f0d73f7a443bac6cb715e4ebfe17",
+        "SKILL.md": "bb82e375b580954a5dae1044c2372e574a954bc8c14f79e4854aa8e39de98dc4",
         "agents/openai.yaml": "be790c04fdf910e71642cfadf1a7c07c217bf7fad18581610feb4c31a79651f2",
-        "assets/agents-section.md.template": "591479cd2beacd5bc80457625fb1e67bf41947f6c2df326a52f0789fa455e8ec",
-        "assets/dev-profile.md.template": "75c6a832a35260cd362cd201fa57a5bc40e0a0419c6f18c547c76e9d48d59812",
+        "assets/agents-section.md.template": "6c9591d50f73e1e05e78c8969c7836767432cf32487af7205b2cb9f4a410440e",
+        "assets/dev-profile.md.template": "45b2a90fc7aee39e7b975151f1281787d6dd4d3b7d5f9df5b8f282d020a1d7a9",
+        "references/conventions.md": "815f5189daff1b71b3251b7a57de183a4a387fcdedbd5875e673d5bd3de398fc",
         "references/harness-facts.md": "2be1d81f6a616d40dc865aaeefaf53c61bc13ade4ba1de8fb406c520bf15be40",
         "references/stack-playbooks.md": "3586a0f03830a9bfaba2d9373a2e745d2207213923af601bf472849f07a7d9e9",
         "refresh/REFRESH.md": "debda6ab96e899dd7e38309f714e9d65a3fbc53fd8ca68b8156f1348226c87b9",
@@ -49,11 +101,23 @@
     },
     "dev-ship": {
       "files": {
-        "SKILL.md": "2938dadc743e03a3113ae15a971e376cd72ccfc6ffca4646d80e6fc701e6c621",
+        "SKILL.md": "25cfb1eb2937cd33824f77cf008113406a54787b03edadc45762e688b1d3b5e0",
         "agents/openai.yaml": "8f18cfd505131557eb4c9f7b7f54e9069f787be4c162403fc30253eed49a06ea",
-        "references/runbook.md": "d8ca232f2abd2bd69c2dbdde0eabf22ff47841fa44036b2553a132367d04441b",
+        "references/conventions.md": "815f5189daff1b71b3251b7a57de183a4a387fcdedbd5875e673d5bd3de398fc",
+        "references/runbook.md": "5cbf3f89b2fcad1a2873f729b6c1a027566344d5dffcb799ed1d039e76b3e679",
         "refresh/REFRESH.md": "06894b54fcbde12d3b5804523f20d5544ba1a18bb5e36960caa4f98454c6203e",
-        "refresh/sources.json": "7bd883e5b3512e236a909ad6ff20c97f3555785867c31fd728256c7c2c514c74"
+        "refresh/sources.json": "7bd883e5b3512e236a909ad6ff20c97f3555785867c31fd728256c7c2c514c74",
+        "scripts/ship-gate.mjs": "8cc32d8e250b0698bbc24097c602b5bce6d3e22b33ce2b4b05e2faa2d1c7ae41"
+      }
+    },
+    "dev-status": {
+      "files": {
+        "SKILL.md": "3d512a6fa30591fc762b11ef4861006defb3ba9ceac03eb77488a15d2489b49c",
+        "agents/openai.yaml": "72435947f5afef0c8a2c170e987b14fe6057b174318c16b6b538ae8d129791fb",
+        "references/conventions.md": "815f5189daff1b71b3251b7a57de183a4a387fcdedbd5875e673d5bd3de398fc",
+        "refresh/REFRESH.md": "52aee9bae64d8342e127704d1db282e43ed57c101148727bf10172d6cb975bfa",
+        "refresh/sources.json": "a7ba2340964dc70410626087686145b5790a0e763a18ef2c4d9aa37e950f2e04",
+        "scripts/status.mjs": "70c959f46764613d4645b1dce54b05a3800c0b689ee5bd14f807b6150dce3cb7"
       }
     },
     "skill-maintainer": {
@@ -68,7 +132,7 @@
     },
     "skillify": {
       "files": {
-        "SKILL.md": "cd66142c4597070a6291024230cad05c517a145adfe7b54ef655c704b9029830",
+        "SKILL.md": "378b66998575b8e316190fa2bbe435852fb191448806e2ec8943037e716a9f9d",
         "agents/openai.yaml": "df320cf32a8db06c213f7892844dab810b7e96cfbf32502d25185d4a4167ef87",
         "assets/templates/README.md.template": "68230ada702ad39f5de1f35e838ba590d89ca19b23868d4499353db6034fcc2c",
         "assets/templates/REFRESH.md.template": "ff86afade565d668333e7f6d0432213760fd68a62b8ba22897a8601b74c94ac0",
@@ -78,7 +142,7 @@
         "assets/templates/sources.json.template": "39449adcef33e6ffbc369a342bbfd1f299e9327157fe873991e1ed8d243288d1",
         "assets/templates/trigger-queries.json.template": "37517e5f3dc66819f61f5a7bb8ace1921282415f10551d2defa5c3eb0985b570",
         "references/authoring.md": "de61bc54140e07bb1910d5adac4e988e10fea9bd11b3e27234c0c699aa7bbf0d",
-        "references/eval-playbook.md": "e810158fbb56c4422b5ee4b5f2f57329e0b7544aa9d22b0fcb3c9cd6d225befe",
+        "references/eval-playbook.md": "1f463dfea8d69b7022712776794369892643aa020186fe3a3707c493a6c2d4e9",
         "refresh/REFRESH.md": "fb74342bec10fbb8d28590dfde9147564346f2eba8976777073901a56e2742a8",
         "refresh/sources.json": "e554e80c72c16dc70587361804db9e0cf2716c128820b2612d5983a009b2b242",
         "scripts/scaffold-skill.mjs": "108ffae496120777ee40414e058aa7e0cdfbfee81766f7124083bd36eaf1b727"