@vegastack/skills 0.10.0 → 0.11.0

package/skill/dev-setup/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/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: dev-ship
-description: Create the pull request and merge for a finished issue, each only on the user's explicit word, then run the project's Ship runbook — releases, guards, deploys. Use when the user says "make the PR", "open a pull request" for an issue, "ship it", "merge it", "merge issue 12", "release", "release everything since the last tag", or asks to close out a reviewed issue, merge a bot PR, or roll back a bad release (roll-forward). Verifies the issue is at for-operator with evidence and its changelog entry, links the PR to the issue, merges on the separate merge instruction, and records approved decisions. Not for implementing issues (dev-implement) or writing and approving them (dev-intake).
+description: Land finished work, each step only on the operator's explicit word. Use when the user says "make the PR", "open a pull request" for an issue, "ship it", "merge it", "merge issue 12", "release", "release everything since the last tag", or asks to close out a reviewed for-operator issue, merge a bot PR (Renovate, Dependabot), or roll back a bad release. Not for implementing issues (dev-implement), reviewing them (dev-review), or writing and approving them (dev-intake).
 ---
 
 # dev-ship
@@ -13,23 +13,28 @@ Nearest neighbor: `dev-implement` produces the `for-operator` issue with its evi
 
 On the user's PR instruction:
 
-- Verify the issue is at `for-operator` with the evidence comment present, and the branch is pushed. Not there yet → say what's missing instead of creating a premature PR.
+- Run the deterministic guard first: `node <path-to-this-skill>/scripts/ship-gate.mjs --issue <n> --branch <name> --json` (add `--repo <o/r> --dev-md <path>` outside the project root) — it re-runs the project check command fresh from the branch's own checkout, requires the evidence sha to equal the branch head (the corrections loop is the only reconciliation path), the changelog entry, the chronicle entry where the knob says `on`, a clean-or-adjudicated review verdict, and greps added lines for leftover `[DEBUG-` tags; exit 2 stops you with its reasons, warnings are read-twice signals.
+- Verify the issue is at `for-operator` with the evidence comment present — including its `**Docs:**` line (brief/plan revisions in sync) — and the branch is pushed. Not there yet → say what's missing instead of creating a premature PR. Docs out of sync is corrections work: never patch a brief or plan from inside dev-ship.
 - Verify the changelog state matches the evidence comment's `**Changelog:**` line: a behavior-changing branch carries its entry per dev.md's `changelog:` knob (changesets: a `.changeset/*.md` in the diff; keep-a-changelog: the diff adds lines to CHANGELOG.md), while `none` with a reason that holds up (docs-only, test-only) is fine. An unexplained miss → corrections loop, not a PR.
 - `gh pr create` from the task branch: title from the issue, body is `Closes #<n>` plus a link to the evidence comment — the issue holds the report; the PR links it rather than duplicating it.
 - No draft PRs unless the user asks for one.
-- If required checks fail on the PR, that's implement work: hand the failures to the corrections loop, update the evidence comment, and tell the user. Under `gates: 2` the standing ship word holds once checks are green again — unless the fix changed behavior, which goes back to the user (same rule as a merge conflict).
+- If required checks fail on the PR, that's implement work: hand the failures to the corrections loop, update the evidence comment, and tell the user. Under `gates: 2` the standing ship word holds once checks are green again — subject to Gate 2's staleness bound (behavior change or >7 days → one-sentence re-confirm).
 - A direct chat change (dev-implement's no-issue path) ships on the same words: the chat request stands in for the recorded approval, the PR body carries the evidence instead of linking an issue comment, and the changelog rule applies unchanged.
 - User corrections left on the PR itself flow through the same corrections loop on the same branch — the PR updates with the push; nothing gets recreated.
 
 With `gates: 1` there is no PR: the same verifications run, then the ship word triggers the merge below directly ([runbook](references/runbook.md) has the mechanics).
 
+| Excuse (observed) | Reality |
+|---|---|
+| "Opening a PR is preparation, not shipping — it pushes nothing… exactly the state the workflow wants finished work parked in." | Under `gates: 3` the PR is a gate spent only by the operator's word. Finished work parks on the pushed branch; a draft PR is still a PR nobody asked for. |
+
 ## Gate 2 — the merge
 
 On the user's merge instruction:
 
 - Re-check that the PR head is still the revision the evidence comment names and checks are green — a branch that moved since review gets re-verified before it lands.
-- Pending `Decision:` lines exist (issue comments, or the evidence comment's `**Decision:**` line) → name them in the merge confirmation — "merging will record: …" — so the operator's word demonstrably covers them; never append on inferred consent. On the word, append each to the register dev.md names (`decisions:` knob) in its `- DD-MM-YYYY (github-username) — …` format; the register is append-only and this is its moment.
-- A merge conflict with the default branch is corrections work: update the branch, re-verify what the update touched, and the standing merge instruction holds once checks are green again — unless the update changed behavior, which goes back to the user.
+- Pending `Decision:` lines exist (issue comments, or the evidence comment's `**Decision:**` line) → name them in the merge confirmation — "merging will record: …" — so the operator's word demonstrably covers them; never append on inferred consent. On the word, append each to the register dev.md names (`decisions:` knob) in its `- DD-MM-YYYY operator (github-username) — …` format; the register is append-only and this is its moment.
+- A merge conflict with the default branch is corrections work: update the branch, re-verify what the update touched, and the standing merge instruction holds once checks are green again — unless the update changed behavior, or more than 7 days have passed since the word; either way, re-confirm with one sentence rather than acting on a stale instruction.
 - Merge per the dev.md `merge` knob (default `gh pr merge --squash`; `gates: 1` merges locally per the same knob and pushes). `Closes #<n>` closes the issue; confirm both happened.
 - A bot PR (Renovate, Dependabot) has no issue or evidence comment and merging it is still shipping: green checks qualify it, only the operator's explicit word — per PR or per named batch — merges it; majors and security advisories get named before their word is acted on.
 
@@ -37,8 +42,10 @@ On the user's merge instruction:
 
 Merge is not the end when dev.md has a `## Ship` section: follow its steps in order — `auto:` lines you just do, `ask:` lines wait for the operator's word, `guard:` lines are deterministic checks you run locally at their position (their CI copies are the backstop). With `release: per-merge`, the runbook is part of shipping the issue; with `release: on-request`, it runs only when the operator says "release" (covering everything merged since the last one). Report each step's outcome; a failing step — guard included — stops the sequence and goes to the operator, never skipped past. Execution detail, release batching, direct-to-main, bot PRs, and rollback: [runbook](references/runbook.md).
 
-Rollback is never a force-push: follow the Ship section's rollback line — roll forward through the normal flow. A gotcha here (a step that surprised you, an instruction the operator had to repeat) is one proposed line folded into the runbook; a directional gotcha that passes dev.md's Decisions test is a register proposal instead, on the user's yes.
+Rollback is never a force-push: follow the Ship section's rollback line — roll forward through the normal flow. Gotchas surfaced here feed the Report's closing retro below.
 
 ## Report
 
-One short confirmation each gate: what was created or merged, the link, decisions recorded, and anything that still needs the user (failing check, failing guard, moved head, missing evidence or changelog entry). When a gate's condition isn't met, the answer is what's missing — the gate itself never gets skipped to be helpful.
+One short confirmation each gate, in plain language: what was created or merged, the link, decisions recorded, and anything that still needs the operator (failing check, failing guard, moved head, missing evidence or changelog entry). When a gate's condition isn't met, the answer is what's missing — the gate itself never gets skipped to be helpful.
+
+Close every ship with the retro: any bounce, gotcha, or instruction the operator had to repeat during this issue? Propose the ONE dev.md (or runbook) line that would have prevented it — fold into an existing line, never append a log; a directional gotcha becomes a register proposal instead. Each lands only on the operator's yes.

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": []
+}