@vegastack/skills 0.9.1 → 0.11.0

package/skill/dev-ship/references/conventions.md

@@ -0,0 +1,93 @@
+# Workflow conventions
+
+The single spec for the artifacts every dev-family skill reads and writes. One home per rule: skills cite this file, never restate it. Everything here is harness-neutral.
+
+## Comment metadata markers
+
+Every workflow-generated issue comment opens with an invisible HTML marker followed by a human heading:
+
+```markdown
+<!-- vsk:v1 type=<type> rev=<n> [key=value ...] -->
+## <Human title> (v<n>)
+```
+
+| type | required keys | instances |
+|---|---|---|
+| `approval` | `scope=<brief\|brief+plan\|plan>` | one per approval event |
+| `plan` | `rev` | one, edited in place |
+| `ledger` | `branch` | one, edited in place |
+| `evidence` | `rev branch sha` | one, edited in place |
+| `review` | `round sha agent=<claude\|codex> verdict=<clean\|needs-fixes>` | one per review cycle, rounds appended inside |
+| `decision` | — | one per decision proposal |
+| `handback` | — | one per stop event |
+
+`rev=<n>` and the matching `(v<n>)` heading suffix appear only on revisable artifacts — the brief (issue description), `plan`, and `evidence` — starting at `rev=1`/`(v1)`. Single-event comments (`approval`, `decision`, `handback`) and the `ledger` carry neither. Scripts and agents locate comments strictly by marker, never by heading text. A comment without its marker does not count as the artifact — there is no legacy fallback.
+
+## Operator identity
+
+Every human reference in every artifact — approvals, revisions, decisions, changelog attributions, review adjudications — is written `operator (<github-username>)`:
+
+- Approval: `Approved by operator (<username>) on DD-MM-YYYY: "<their words>"`
+- Register line: `- DD-MM-YYYY operator (<username>) — <decision>`
+
+## Revision markers
+
+Any artifact edited after its first approval: the heading gains `(v2)`, the marker gains `rev=2`, and a `Revisions:` line is appended at the bottom — `v2 — DD-MM-YYYY: <what changed>, per operator (<username>) correction`. Existing revision lines are never rewritten.
+
+## Scope classes
+
+Set at intake, applied as a label, announced with its reason (operator can override):
+
+- **`research`** — a question to answer; throwaway code allowed, never merged. No branch/PR/changelog; findings + recommendation are the evidence comment.
+- **`quick-build`** — small change and the flow being changed already exists in the repo to read. Brief (description) + plan (comment) are drafted in the same conversation; **one approval covers both**; then straight to `ready`.
+- **`full-plan`** — big or new ground. Brief approval → `needs-plan` → a separate, fresh-grounded planning session posts the plan → `needs-operator` → "plan approved" → `ready`. Multi-deliverable work becomes an epic; each sub-issue is classified independently.
+
+Scope calls are revisited through the one-way ratchet, whose rules and mechanics live in the `dev-plan` skill — the one home for upgrade/downgrade behavior.
+
+## Labels
+
+State — exactly one per issue (creation colors live in dev-setup's labels row, their one home):
+
+| label | meaning |
+|---|---|
+| `needs-operator` | waiting on the operator: a question, a brief or plan to approve, a proposal |
+| `needs-plan` | brief approved; waiting for the planning stage (full-plan only) |
+| `ready` | fully approved — an agent may start |
+| `working` | claimed, in progress; the ledger comment shows live progress |
+| `for-operator` | done — evidence posted, awaiting operator review |
+
+Modifiers (may coexist with the state label): `risky` · scope `research` / `quick-build` / `full-plan` · `epic` (map parents, only where the org has no native Epic issue type).
+
+## Titles, types, hierarchy
+
+- **Title prefixes** on issues, branches, and PRs identically: dev.md's `branch:` knob type list (that knob stays the list's one home) plus `research:` for research issues. PR title = issue title.
+- **Native issue types** where the org defines them: Feature (feat) · Bug (fix) · Task (docs/chore/refactor/research) · Epic for parents (label fallback otherwise).
+- **Hierarchy:** epic parent = map only (Destination · Decisions so far as one-line gists · Not clear yet · Out of scope), children attached as native sub-issues; issues = the unit of work (brief in description, own approvals/branch/PR/evidence); tasks = checkboxes **in the plan comment only**. Blockers use native issue dependencies; phases use milestones. Only issues — never epics — get `ready`. GitHub caps issue bodies and comments at ~65,536 characters; what a plan nearing that cap means is the `dev-plan` ratchet's call.
+
+## The ledger
+
+Maintained by the implement session as one comment, edited in place:
+
+```markdown
+<!-- vsk:v1 type=ledger branch=<branch> -->
+## Ledger — <branch>
+- Task <N>: complete (commits <base7>..<head7>[, review clean | K parked])
+- Task <N>: fix round <R>/3 (<X> addressed, <Y> open — <one-liners>; commits <a>..<b>)
+- Ruling: <what> — <why> — cost if wrong: <cost>
+- Task <N>: parked — <finding> — Ruling: <why the code stands>
+- Deferred minor: <one-liner>
+```
+
+**Resume protocol:** a fresh, compacted, or (operator-handed) takeover session reads, in order: the brief → the plan comment → the ledger → `git log` on the branch — **nothing else**. Tasks with a `complete` line are DONE, never re-executed; a task whose last line is a fix round resumes at the next round. After compaction, trust the ledger and `git log` over recollection. Every `Ruling:` line surfaces in the evidence comment — a ruling that dies with the session was a decision made in secret.
+
+## `.vegastack/.tmp/` workspace
+
+All transitory artifacts — subagent reports, review packages, plan drafts, extracted diffs — live at `.vegastack/.tmp/<issue-number>-<title-slug>/` (pre-issue intake drafts, which have no number yet: `.vegastack/.tmp/intake-<slug>/`), kept out of git by a self-ignoring `.gitignore` (`printf '*\n' > .vegastack/.tmp/.gitignore`, created on first use). Subagents write full reports to files there and return only short status — a dead subagent's findings survive on disk, and the primary session never holds full reports in context. The workspace lives in the working tree (never under `.git/`, which harnesses protect from writes).
+
+## Verification gate
+
+Before claiming any status: **IDENTIFY** the command that proves the claim → **RUN** it fresh and complete → **READ** the full output and exit code → only then claim, with the evidence. "Should pass", a previous run, or a subagent's say-so are never evidence. Guard scripts follow the same doctrine: machine-verifiable facts **block** (exit 2 with the reason); regex or judgment heuristics only **warn** — no AI inference inside guards, and an unverifiable state fails closed.
+
+## Plain-language collaboration
+
+Every skill run ends with a simple-language summary: what happened, which paths were taken — cross-agent invocations announced at trigger time AND summarized at the end — and what is worth the operator double-checking. Use mermaid or ASCII diagrams in issues wherever a picture beats prose. A vague or self-contradicting operator answer gets pushback with concrete options, never silent absorption.

package/skill/dev-ship/references/runbook.md

@@ -33,4 +33,4 @@ A bot PR has no issue, no brief, no evidence comment — and merging it is still
 
 ## Guard failure at ship time
 
-A local `guard:` failure (missing changelog entry, tag/version mismatch) means the branch or release prep is incomplete: route it to dev-implement's corrections loop, get the evidence comment updated, then resume at the failed step. Never edit release artifacts inline just to get past a guard.
+A local `guard:` failure (missing changelog entry, tag/version mismatch) means the branch or release prep is incomplete: route it to dev-implement's corrections loop, get the evidence comment updated, then resume at the failed step. Never edit release artifacts inline just to get past a guard. `ship-gate.mjs` speaks the same language: exit 0 pass · 1 pass-with-warnings (read them twice, they never block) · 2 blocked with its reasons printed — a 2 routes to corrections exactly like a failing `guard:` line.

package/skill/dev-ship/scripts/ship-gate.mjs

@@ -0,0 +1,213 @@
+#!/usr/bin/env node
+// dev-ship guard, run at Gate 1 before a PR (and re-run before merge): the
+// deterministic facts that make a hand-back shippable. Facts block; the
+// rationalization scan over the evidence text only warns — regex heuristics
+// never block. Self-contained (ships with dev-ship; no cross-skill imports).
+//
+// Exit codes: 0 pass · 1 pass-with-warnings · 2 blocked (reasons printed).
+// Usage: node ship-gate.mjs --issue <n> --branch <name> [--repo o/r] [--dev-md <path>]
+//        [--base main] [--allow-no-changelog "<reason>"] --json
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const RATIONALIZATIONS = [
+  /skip(ping)? tests? for now/i,
+  /pre-existing (issue|bug)/i,
+  /fix (this|it) later/i,
+  /(tests?|coverage) (is|are) (failing|broken) but/i,
+];
+
+function sh(cmd, args) {
+  // VSK_GH is a TEST SEAM (stubs gh in unit tests); git always runs real.
+  const bin = cmd === 'gh' ? (process.env.VSK_GH || 'gh') : cmd;
+  return execFileSync(bin, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], env: { ...process.env } }).trim();
+}
+
+// Adjudication means OPEN FINDINGS were ruled on at the loop cap. Routine
+// ledger vocabulary ("Ruling:", a mid-build "parked", "nothing parked") must
+// not lift a needs-fixes block — only "adjudicat*" or a finding-tied park
+// ("Finding [N] ... parked") counts.
+export function reviewAdjudicated(evidenceBody) {
+  const section = /\*\*Review:\*\*[\s\S]*?(?=\n\*\*[A-Z]|\nBranch:|$)/.exec(evidenceBody ?? '')?.[0] ?? '';
+  return /adjudicat/i.test(section) || /finding \[\d+\][^\n]*parked/i.test(section);
+}
+
+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 };
+}
+
+// An entry means an ADDED "## " heading in the file-scoped diff — a deleted
+// file or a typo edit to an old entry is not a new entry.
+export function chronicleEntryAdded(fileDiff) {
+  return /^\+## /m.test(fileDiff ?? '');
+}
+
+// Pure evaluation over gathered facts — unit tests drive this directly.
+export function evaluateShipGate(facts) {
+  const blocks = [];
+  const warns = [];
+  const {
+    evidence,            // { body } | null
+    reviewVerdict,       // 'clean' | 'needs-fixes' | null
+    adjudicated,         // boolean: evidence Review section carries adjudication rulings
+    headSha,             // short sha of the branch head
+    diffText,            // full diff vs base
+    changelogTouched,    // boolean: diff adds a changelog/changeset entry
+    // chronicleOn/chronicleTouched (via facts.*): dev.md chronicle knob and
+    // whether the diff adds a "## " chronicle entry heading
+    allowNoChangelog,    // reason string | undefined
+    checkExit,           // number | null (null = no check command configured)
+  } = facts;
+
+  if (!evidence) {
+    blocks.push('no evidence comment (marker type=evidence) on the issue');
+    return { blocks, warns };
+  }
+  const marker = parseMarker(evidence.body);
+  const evidenceSha = marker?.keys?.sha ?? '';
+
+  if (!/^[0-9a-f]{7,40}$/.test(evidenceSha)) {
+    blocks.push(`evidence marker carries no valid sha= (found "${evidenceSha || 'nothing'}") — the shipped revision must be named`);
+  } else if (!headSha.startsWith(evidenceSha) && !evidenceSha.startsWith(headSha)) {
+    // Strict equality, no reconciliation window: the corrections loop updates
+    // the evidence comment (Docs line AND sha) after every change, so a
+    // mismatched sha means unrecorded work. An "edited since the commit"
+    // window was spoofable by any comment edit and was removed.
+    blocks.push(`branch head ${headSha} moved past evidence sha ${evidenceSha} — the corrections loop must re-verify and update the evidence comment (Docs line + new sha) before shipping`);
+  }
+
+  if (!changelogTouched && !allowNoChangelog) {
+    blocks.push('no changelog/changeset entry in the diff and no --allow-no-changelog reason given');
+  }
+
+  if (facts.chronicleOn && !facts.chronicleTouched && !allowNoChangelog) {
+    blocks.push('dev.md says chronicle: on but the diff adds no .vegastack/chronicle.md entry (the same --allow-no-changelog reason covers docs/test-only branches)');
+  }
+  if (allowNoChangelog && (!changelogTouched || (facts.chronicleOn && !facts.chronicleTouched))) {
+    warns.push(`--allow-no-changelog exercised ("${allowNoChangelog}") — it excused: ${[!changelogTouched ? 'changelog' : null, facts.chronicleOn && !facts.chronicleTouched ? 'chronicle' : null].filter(Boolean).join(' + ')}`);
+  }
+
+  if (reviewVerdict !== 'clean' && !adjudicated) {
+    blocks.push(`latest review verdict is ${reviewVerdict ?? 'absent'} and the evidence Review section carries no adjudication`);
+  }
+
+  if (facts.checkoutMismatch) {
+    blocks.push(facts.checkoutMismatch);
+  }
+  if (facts.checkMissing) {
+    warns.push('dev.md has no check command on its commands: line — the fresh-run gate could not run; verify by hand');
+  }
+  if (checkExit !== null && checkExit !== 0) {
+    blocks.push(`the project check command exited ${checkExit} on a fresh run — a claim is never trusted, always re-proven`);
+  }
+
+  // Added lines only, and only the REAL tag shape ([DEBUG- + hex): docs that
+  // document the tag write placeholders like [DEBUG-<4hex>] and must not block.
+  if (/^\+(?!\+\+).*\[DEBUG-[0-9a-f]{4}\]/m.test(diffText)) {
+    blocks.push('the diff adds [DEBUG- tagged instrumentation — dev-debug cleanup was skipped');
+  }
+
+  for (const pattern of RATIONALIZATIONS) {
+    const hit = pattern.exec(evidence.body);
+    if (hit) warns.push(`rationalization wording in evidence: "${hit[0]}" — heuristics never block, but read it twice`);
+  }
+
+  return { blocks, warns };
+}
+
+export function gatherFacts(flags) {
+  const repo = flags.repo || sh('gh', ['repo', 'view', '--json', 'nameWithOwner', '-q', '.nameWithOwner']);
+  const base = flags.base || 'main';
+  const branch = flags.branch;
+  const comments = JSON.parse(sh('gh', ['api', `repos/${repo}/issues/${flags.issue}/comments`, '--paginate']));
+
+  let evidence = null;
+  let reviewVerdict = null;
+  for (const comment of comments) {
+    const marker = parseMarker(comment.body);
+    if (marker?.keys?.type === 'evidence') evidence = { body: comment.body, updatedAt: comment.updated_at };
+    if (marker?.keys?.type === 'review') reviewVerdict = marker.keys.verdict ?? null;
+  }
+  const adjudicated = reviewAdjudicated(evidence?.body);
+
+  const headSha = sh('git', ['rev-parse', '--short=7', branch]);
+  const diffText = sh('git', ['diff', `${base}...${branch}`]);
+  // The fresh check run and dev.md read use the WORKING TREE — they prove
+  // nothing unless the checkout is the branch under review.
+  const checkoutSha = sh('git', ['rev-parse', 'HEAD']);
+  const branchSha = sh('git', ['rev-parse', branch]);
+  const checkoutMismatch = checkoutSha === branchSha
+    ? null
+    : `the current checkout (${checkoutSha.slice(0, 7)}) is not the branch under review (${branch} @ ${branchSha.slice(0, 7)}) — run ship-gate from that branch so the fresh check proves the right code`;
+
+  const devMd = readFileSync(flags['dev-md'] || '.vegastack/dev.md', 'utf8');
+  const changelogKnob = (/^changelog:\s*(\S+)/m.exec(devMd) || [])[1] ?? 'none';
+  // Added files/lines only — a deleted changeset or the +++ diff header must
+  // not count as an entry.
+  const changelogTouched = changelogKnob === 'none'
+    ? true
+    : changelogKnob === 'changesets'
+      ? /^\+\+\+ b\/\.changeset\/(?!config)/m.test(diffText)
+      : /^\+(?!\+\+)[^\n]*\S/m.test(sh('git', ['diff', `${base}...${branch}`, '--', 'CHANGELOG.md']) || '');
+
+  const chronicleOn = /^chronicle:\s*on\s*(#|$)/m.test(devMd);
+  const chronicleTouched = chronicleEntryAdded(sh('git', ['diff', `${base}...${branch}`, '--', '.vegastack/chronicle.md']) || '');
+
+  let checkExit = null;
+  const checkCmd = (/^commands:.*?check\s+`([^`]+)`/m.exec(devMd) || [])[1];
+  const checkMissing = !checkCmd;
+  if (checkCmd) {
+    try {
+      execFileSync('sh', ['-c', checkCmd], { stdio: ['ignore', 'pipe', 'pipe'] });
+      checkExit = 0;
+    } catch (error) {
+      checkExit = error.status ?? 1;
+    }
+  }
+
+  return {
+    evidence, reviewVerdict, adjudicated, headSha, diffText,
+    changelogTouched, chronicleOn, chronicleTouched,
+    allowNoChangelog: flags['allow-no-changelog'], checkExit, checkMissing, checkoutMismatch,
+  };
+}
+
+const invokedDirectly = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (invokedDirectly) {
+  const argv = process.argv.slice(2);
+  const json = argv.includes('--json');
+  const get = (flag) => { const i = argv.indexOf(flag); return i === -1 ? undefined : argv[i + 1]; };
+  const flags = {
+    issue: get('--issue'), branch: get('--branch'), repo: get('--repo'), base: get('--base'),
+    'dev-md': get('--dev-md'), 'allow-no-changelog': get('--allow-no-changelog'), json,
+  };
+  let outcome;
+  if (!flags.issue || !flags.branch) {
+    outcome = { blocks: ['usage: ship-gate.mjs --issue <n> --branch <name> [--json]'], warns: [] };
+  } else {
+    try {
+      outcome = evaluateShipGate(gatherFacts(flags));
+    } catch (error) {
+      outcome = { blocks: [`cannot verify: ${error.message}`], warns: [] };
+    }
+  }
+  const ok = outcome.blocks.length === 0;
+  const exitCode = ok ? (outcome.warns.length ? 1 : 0) : 2;
+  if (json) {
+    console.log(JSON.stringify({ guard: 'ship-gate', ok, ...outcome }, null, 2));
+  } else {
+    console.log(`ship-gate: ${ok ? (outcome.warns.length ? 'pass with warnings' : 'pass') : 'BLOCKED'}`);
+    for (const b of outcome.blocks) console.log(`  block: ${b}`);
+    for (const w of outcome.warns) console.log(`  warn: ${w}`);
+  }
+  process.exit(exitCode);
+}

package/skill/dev-status/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: dev-status
+description: The operator's board — whose move is it, across every issue in the dev workflow. Use when asked "status", "what needs me", "where are we", "what's in flight", "anything stale?", "what should I look at next", or for a board overview of needs-operator / needs-plan / ready / working / for-operator issues. Not for the project's history ("catch me up" is dev-chronicle), implementing or reviewing anything, or repo bootstrap (dev-setup).
+---
+
+# dev-status
+
+One question, answered from deterministic data: **whose move is it?** The bundled script gathers; this skill orders and narrates — it never invents state, and an unverifiable board is reported as exactly that.
+
+Nearest neighbors: `dev-chronicle` answers "how did we get here"; this skill answers "what needs whom right now". Formats read via the `dev-setup` skill's `references/conventions.md` markers.
+
+## Gather
+
+```
+node <path-to-this-skill>/scripts/status.mjs --stale-days 3 --json
+```
+
+Read-only; it returns the board (open issues per state label with age, scope, risky), task progress `x/y` from plan-comment checkboxes, ledger movement for `working` issues (stale = no ledger edit within `--stale-days`, default 3), open PRs with check state, pending unrecorded `Decision:` proposals, and the last chronicle entry. Exit 2 = cannot verify (offline, unauthenticated) — report the gap plainly and stop; never render a guessed board.
+
+## Render — names, never bare numbers
+
+```markdown
+## Status — <repo> · DD-MM
+
+Needs you (N):
+- <linked title> — <state> <age>d: <one line: what it waits for and the word needed>
+Waiting on plan (N): - <linked title> — needs-plan <age>d
+Ready to build (N): - <linked title> — <scope>
+In flight (N): - <linked title> — working, task <x>/<y>, ledger moved <n>d ago
+Stale (N): - <linked title> — working <age>d, ledger silent <n>d → check or reclaim
+Open PRs (N): - <linked title> — checks <green|pending-or-red|no-checks>
+Pending decisions (N): "<gist>" (<linked issue>) — records at that issue's merge
+Last chronicle chapter: <date> — <title>
+Next: <the single most valuable operator action, and why>
+```
+
+- **Needs you** first (for-operator + needs-operator merged, oldest first) — it's the operator's queue; everything else is context.
+- Sections with zero entries are omitted, not rendered empty. A completely quiet board is one line: "Nothing needs you — <n> issues ready for agents, nothing in flight."
+- `risky` issues get their flag shown inline wherever they appear.
+- **Next** is one line, chosen not computed-looking: the action that unblocks the most (a plan approval blocking several ready issues beats a lone review).
+- <linked title> means a markdown link wrapping the issue/PR title around its URL; numbers ride inside the link, never stand alone.
+
+## Honesty rules
+
+Data comes only from the script; ordering, the wait-reason one-liners, and Next are the skill's judgment — clearly judgment, never dressed as data. A stale `working` issue is a fact to surface, not an accusation: "check or reclaim" is the operator's call (a takeover still needs their explicit handover, per dev-implement). Close with the plain-language summary only when invoked as part of a larger run; standalone, the report IS the summary.

package/skill/dev-status/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "dev-status"
+  short_description: "The operator's board — whose move is it"
+  default_prompt: "Use $dev-status to show what needs me."

package/skill/dev-status/references/conventions.md

@@ -0,0 +1,93 @@
+# Workflow conventions
+
+The single spec for the artifacts every dev-family skill reads and writes. One home per rule: skills cite this file, never restate it. Everything here is harness-neutral.
+
+## Comment metadata markers
+
+Every workflow-generated issue comment opens with an invisible HTML marker followed by a human heading:
+
+```markdown
+<!-- vsk:v1 type=<type> rev=<n> [key=value ...] -->
+## <Human title> (v<n>)
+```
+
+| type | required keys | instances |
+|---|---|---|
+| `approval` | `scope=<brief\|brief+plan\|plan>` | one per approval event |
+| `plan` | `rev` | one, edited in place |
+| `ledger` | `branch` | one, edited in place |
+| `evidence` | `rev branch sha` | one, edited in place |
+| `review` | `round sha agent=<claude\|codex> verdict=<clean\|needs-fixes>` | one per review cycle, rounds appended inside |
+| `decision` | — | one per decision proposal |
+| `handback` | — | one per stop event |
+
+`rev=<n>` and the matching `(v<n>)` heading suffix appear only on revisable artifacts — the brief (issue description), `plan`, and `evidence` — starting at `rev=1`/`(v1)`. Single-event comments (`approval`, `decision`, `handback`) and the `ledger` carry neither. Scripts and agents locate comments strictly by marker, never by heading text. A comment without its marker does not count as the artifact — there is no legacy fallback.
+
+## Operator identity
+
+Every human reference in every artifact — approvals, revisions, decisions, changelog attributions, review adjudications — is written `operator (<github-username>)`:
+
+- Approval: `Approved by operator (<username>) on DD-MM-YYYY: "<their words>"`
+- Register line: `- DD-MM-YYYY operator (<username>) — <decision>`
+
+## Revision markers
+
+Any artifact edited after its first approval: the heading gains `(v2)`, the marker gains `rev=2`, and a `Revisions:` line is appended at the bottom — `v2 — DD-MM-YYYY: <what changed>, per operator (<username>) correction`. Existing revision lines are never rewritten.
+
+## Scope classes
+
+Set at intake, applied as a label, announced with its reason (operator can override):
+
+- **`research`** — a question to answer; throwaway code allowed, never merged. No branch/PR/changelog; findings + recommendation are the evidence comment.
+- **`quick-build`** — small change and the flow being changed already exists in the repo to read. Brief (description) + plan (comment) are drafted in the same conversation; **one approval covers both**; then straight to `ready`.
+- **`full-plan`** — big or new ground. Brief approval → `needs-plan` → a separate, fresh-grounded planning session posts the plan → `needs-operator` → "plan approved" → `ready`. Multi-deliverable work becomes an epic; each sub-issue is classified independently.
+
+Scope calls are revisited through the one-way ratchet, whose rules and mechanics live in the `dev-plan` skill — the one home for upgrade/downgrade behavior.
+
+## Labels
+
+State — exactly one per issue (creation colors live in dev-setup's labels row, their one home):
+
+| label | meaning |
+|---|---|
+| `needs-operator` | waiting on the operator: a question, a brief or plan to approve, a proposal |
+| `needs-plan` | brief approved; waiting for the planning stage (full-plan only) |
+| `ready` | fully approved — an agent may start |
+| `working` | claimed, in progress; the ledger comment shows live progress |
+| `for-operator` | done — evidence posted, awaiting operator review |
+
+Modifiers (may coexist with the state label): `risky` · scope `research` / `quick-build` / `full-plan` · `epic` (map parents, only where the org has no native Epic issue type).
+
+## Titles, types, hierarchy
+
+- **Title prefixes** on issues, branches, and PRs identically: dev.md's `branch:` knob type list (that knob stays the list's one home) plus `research:` for research issues. PR title = issue title.
+- **Native issue types** where the org defines them: Feature (feat) · Bug (fix) · Task (docs/chore/refactor/research) · Epic for parents (label fallback otherwise).
+- **Hierarchy:** epic parent = map only (Destination · Decisions so far as one-line gists · Not clear yet · Out of scope), children attached as native sub-issues; issues = the unit of work (brief in description, own approvals/branch/PR/evidence); tasks = checkboxes **in the plan comment only**. Blockers use native issue dependencies; phases use milestones. Only issues — never epics — get `ready`. GitHub caps issue bodies and comments at ~65,536 characters; what a plan nearing that cap means is the `dev-plan` ratchet's call.
+
+## The ledger
+
+Maintained by the implement session as one comment, edited in place:
+
+```markdown
+<!-- vsk:v1 type=ledger branch=<branch> -->
+## Ledger — <branch>
+- Task <N>: complete (commits <base7>..<head7>[, review clean | K parked])
+- Task <N>: fix round <R>/3 (<X> addressed, <Y> open — <one-liners>; commits <a>..<b>)
+- Ruling: <what> — <why> — cost if wrong: <cost>
+- Task <N>: parked — <finding> — Ruling: <why the code stands>
+- Deferred minor: <one-liner>
+```
+
+**Resume protocol:** a fresh, compacted, or (operator-handed) takeover session reads, in order: the brief → the plan comment → the ledger → `git log` on the branch — **nothing else**. Tasks with a `complete` line are DONE, never re-executed; a task whose last line is a fix round resumes at the next round. After compaction, trust the ledger and `git log` over recollection. Every `Ruling:` line surfaces in the evidence comment — a ruling that dies with the session was a decision made in secret.
+
+## `.vegastack/.tmp/` workspace
+
+All transitory artifacts — subagent reports, review packages, plan drafts, extracted diffs — live at `.vegastack/.tmp/<issue-number>-<title-slug>/` (pre-issue intake drafts, which have no number yet: `.vegastack/.tmp/intake-<slug>/`), kept out of git by a self-ignoring `.gitignore` (`printf '*\n' > .vegastack/.tmp/.gitignore`, created on first use). Subagents write full reports to files there and return only short status — a dead subagent's findings survive on disk, and the primary session never holds full reports in context. The workspace lives in the working tree (never under `.git/`, which harnesses protect from writes).
+
+## Verification gate
+
+Before claiming any status: **IDENTIFY** the command that proves the claim → **RUN** it fresh and complete → **READ** the full output and exit code → only then claim, with the evidence. "Should pass", a previous run, or a subagent's say-so are never evidence. Guard scripts follow the same doctrine: machine-verifiable facts **block** (exit 2 with the reason); regex or judgment heuristics only **warn** — no AI inference inside guards, and an unverifiable state fails closed.
+
+## Plain-language collaboration
+
+Every skill run ends with a simple-language summary: what happened, which paths were taken — cross-agent invocations announced at trigger time AND summarized at the end — and what is worth the operator double-checking. Use mermaid or ASCII diagrams in issues wherever a picture beats prose. A vague or self-contradicting operator answer gets pushback with concrete options, never silent absorption.

package/skill/dev-status/refresh/REFRESH.md

@@ -0,0 +1,3 @@
+# Refresh contract — dev-status
+
+Evergreen: this skill asserts no version pins, numeric vendor limits, or dated claims — the gh CLI surfaces it shells to are the long-stable subcommands the family already treats as durable. Revisit if a future edit introduces a volatile fact.

package/skill/dev-status/refresh/sources.json

@@ -0,0 +1,6 @@
+{
+  "schemaVersion": 1,
+  "retrievalBaseline": "2026-08-28",
+  "note": "Evergreen waiver recorded in REFRESH.md; sources deliberately empty.",
+  "sources": []
+}

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/skill-maintainer/references/release-ops.md

@@ -8,8 +8,8 @@ Content is advisory prose and decision tables — no rule IDs, no machine-extrac
 
 | Bump | Content change |
 |---|---|
-| MAJOR | Removing or renaming a skill. A breaking change to a per-project profile format (e.g. `.vegastack/arch.md`) that invalidates existing committed profiles. |
-| MINOR | New reference file or reference section. New or changed recorded decision (e.g. a new "use/not/why" row, a new red line). New skill. |
+| MAJOR | Removing a skill. A breaking change to the per-project profile format (`.vegastack/dev.md`) that invalidates existing committed profiles — the operator may also declare any other change major. |
+| MINOR | Renaming a skill (default — the operator declares major when the break warrants it). New reference file or reference section. New or changed recorded decision (e.g. a new "use/not/why" row, a new red line). New skill. |
 | PATCH | Factual refreshes: pinned-fact updates, version pins, vendor mechanism names, URLs, registry checksums. Wording clarifications that don't change the recorded decision. Test/fixture-only changes. |
 
 Installer/CLI changes follow ordinary semver on the same package version; a release takes the highest bump either side requires.
@@ -44,7 +44,7 @@ Skill names are consumer-facing identifiers — treat a rename as a stable-ID br
 
 1. Rename the directory and the frontmatter `name` in the same commit — they must always stay equal.
 2. Update every wiring point in the same PR: the skill's entry in `packages/cli/packaging.json`, the root README skills table row, and any cross-skill or docs links.
-3. Changeset: MAJOR. Note the migration in `CHANGELOG.md`: copies installed under the old name are orphaned, and installer operations addressed to the old name stop resolving once the shipped manifest no longer knows it.
+3. Changeset: MINOR by default — major only when the operator declares it. Either way, note the migration in `CHANGELOG.md`: copies installed under the old name are orphaned, and installer operations addressed to the old name stop resolving once the shipped manifest no longer knows it.
 4. Registry source IDs inside `refresh/sources.json` are skill-internal and unaffected, but every `affected` ref must still resolve to a real reference in the renamed tree.
 5. Re-run `node packages/cli/scripts/validate-skill.mjs skills/<new-name>` and the skill's tests — name/directory equality is validated.