@vegastack/skills 0.10.0 → 0.11.0

package/skill/dev-implement/SKILL.md

@@ -1,70 +1,75 @@
 ---
 name: dev-implement
-description: Implement an approved GitHub issue end to end without further user input. Use when given an issue to build - "do issue 12", "implement" plus an issue URL or number, "pick up the next ready issue", "go dark on" an issue - when returning to apply corrections the user left on a for-operator issue, or when the user directly asks in chat for a quick fix or small change. Runs preflight, claims the issue, builds on a task branch, tests, gets independent review, and posts one evidence comment in the issue. Not for writing or approving issues (dev-intake), not for creating PRs or merging (dev-ship).
+description: Implement an approved GitHub issue end to end without further user input. Use when given an issue to build — "do issue 12", "implement" plus an issue URL or number, "pick up the next ready issue", "go dark on" an issue — when resuming a dead or compacted session's working issue the operator hands over, when returning to apply corrections the user left on a for-operator issue, or when the user directly asks in chat for a small fix. Not for writing or approving issues (dev-intake), planning them (dev-plan), reviewing finished work (dev-review), or creating PRs and merging (dev-ship).
 ---
 
 # dev-implement
 
-One issue, one session, end to end: preflight → claim → build dark → verify → review → evidence in the issue → stop. The user reads the result in the issue on their own time; nothing here creates a PR or merges — those are `dev-ship`, on the user's word.
+One issue, one session, end to end: preflight → claim → build dark → verify → review → evidence → stop. The operator reads the result in the issue on their own time; nothing here creates a PR or merges — those are `dev-ship`, on the operator's word. Artifact formats follow the `dev-setup` skill's `references/conventions.md`; the ledger discipline lives in [ledger-and-resume](references/ledger-and-resume.md).
 
-Nearest neighbor: `dev-intake` writes the brief this skill executes; if the issue turns out to need decisions, that's intake work — hand it back via `needs-operator`, don't guess. `.vegastack/dev.md` missing → run `dev-setup` first. Read dev.md before anything; its knobs (review, ui-evidence, tests, branch, stop-list) govern this whole skill, and when the issue touches stack surfaces (schema, auth, hosting, services, jobs) its `## Architecture` section governs those choices the way the knobs govern process.
+Nearest neighbors: `dev-plan` writes the plan this skill executes task by task; `dev-review` judges the result; issues that turn out to need decisions go back through `needs-operator`, never guessed. `.vegastack/dev.md` missing → run `dev-setup` first. Read dev.md before anything; its knobs govern this skill, and the `## Architecture` section governs stack-touching choices.
 
-## Direct requests
+## Direct requests — trivial only, tightly bounded
 
-The gates exist to stop agent-invented authority, never to slow the user down. When the user directly asks in chat for a change ("fix this typo", "bump that timeout"), their words are the approval — do it, verify it, and report; no issue required. Branch as `<type>/<slug>` (no issue segment); the changelog rule below applies unchanged when the change is behavior-changing; shipping still goes through dev-ship's words, with the chat request standing in for the approval and the report for the evidence comment. Offer to record an issue when the change is material enough that its brief or evidence will matter later. Everything below is the path for issue-driven work.
+When the operator directly asks in chat for a change, their words are the approval — build, verify, report; no issue needed. The bound is **trivial**: the moment the work exceeds it — a behavior change beyond the asked words, a new dependency, more than 1–2 files — stop and route to `dev-intake` instead of continuing. Branch `<type>/<slug>`; the changelog and chronicle rules apply unchanged when behavior changes; shipping still goes through dev-ship's words.
 
 ## Preflight — all must hold, or stop and say which failed
 
-- `gh auth status` works and the issue's repo matches dev.md.
-- The issue is open, labeled `ready`, and carries the recorded approval comment (`Approved by … : "…"`). A label without the comment is not approval.
-- No open blockers (issue dependencies) and no other assignee — an assigned or `working` issue belongs to someone else. A claim from a dead session is released only by the user: take over a `working` issue only when they explicitly hand it to you.
-- Read the complete brief, plus parent issue and milestone for context. If the brief leaves a material decision open — including an unresolved Assumptions entry — do not start: label `needs-operator`, comment the smallest question that unblocks it, stop.
-- Re-verify the brief against reality before coding: its cited touch points against the current code (things drift between approval and execution), and volatile dependency claims when stale or version-sensitive (per `dev-architect`'s verify protocol). Reality contradicting the brief is a stop — label `needs-operator` with the discrepancy; an approved brief is never a license to improvise past what's actually there.
+- Run the deterministic guard first: `node <path-to-this-skill>/scripts/preflight.mjs --issue <n> --me $(gh api user -q .login) --json` (add `--repo <o/r> --dev-md <path>` when running outside the project root) — exit 2 stops you with its reasons (open + `ready` state, approval marker, scope label, plan approval on full-plan, Assumptions section, blockers, assignee, repo match); exit 1 passes with warnings — read them into the ledger. Resume and corrections runs pass `--expect working` / `--expect for-operator`.
+- Then the judgment checks: read the complete brief plus parent issue and milestone for context; re-verify the brief's touch points against the current code (things drift between approval and execution) — including the version-impact line; volatile dependency claims per `dev-architect`'s verify protocol; a full-plan issue's plan still matches reality. A material decision left open — even outside a formal Assumptions section — or reality contradicting brief or plan is a stop: one `handback` comment with the smallest question, `needs-operator`.
+- Resuming a dead session's issue: the operator's explicit handover is required; then follow the resume protocol in [ledger-and-resume](references/ledger-and-resume.md) — brief → plan → ledger → `git log`, nothing else.
 
-## Claim and branch
+## Claim
 
-Assign yourself, swap `ready` → `working`. Branch from the default branch per dev.md's `branch:` knob — the knob is the only source of the pattern and its type list.
+Assign yourself, swap `ready` → `working`, branch from the default branch per dev.md's `branch:` knob, and **create the ledger comment as your first write**. Record each task's base sha before starting it.
 
-## Build — dark
+## Build — dark, test-first, checkpointed
 
-No progress updates, no questions. A spike the brief flagged runs first — its result opens the evidence comment and shapes the rest of the build. Decide routine things yourself: file layout, helpers, fixtures, and root-cause fixes inside the issue's change areas. A structural choice mid-build — a new dependency, table, or service — checks `dev-architect`'s trigger discipline first; a moving part with no named trigger is a stop condition, not a judgment call. The brief's out-of-scope section and the dev.md stop-list bound you; hitting a stop condition (scope change, new dependency, spending, destructive/production action, unresolvable blocker) ends dark mode — post one `needs-operator` comment stating the smallest decision needed with your recommendation, and stop.
+No progress updates, no questions. A `fix:` issue's diagnosis runs under the `dev-debug` skill — its phases govern the investigation inside this dark mode, and its winning suspect feeds the evidence comment. A spike the brief flagged runs first — its result opens the evidence comment and shapes the rest of the build. Then work the plan task by task:
+
+- **Red before green.** Write the failing test first — at the seams the brief names, never elsewhere — watch it fail for the stated reason, implement the minimal code, watch it pass. One slice at a time. The tests-are-real rubric (implementation-coupled, tautological, horizontal-sliced — defined in `dev-review`'s dispatch prompts) applies to your own tests before a reviewer ever sees them.
+- **Checkpoint the ledger** after every task (tick the plan checkbox in the same pass) and at every ruling, per the reference.
+- **Transitory artifacts** — subagent reports, scratch diffs, drafts — live in `.vegastack/.tmp/<issue>-<slug>/`; subagents write full output to files there and return short status.
+- Decide routine things yourself and ledger the rulings. A structural choice mid-build — a new dependency, table, or service — checks `dev-architect`'s trigger discipline first; a moving part with no named trigger is a stop condition.
+- **The scope ratchet is a stop condition:** work revealed bigger than the issue's scope class (or plainly exceeding one session) → one `handback` comment proposing the upgrade or split (dev-plan's ratchet rules), `needs-operator`, stop.
+- The brief's out-of-scope section and the dev.md stop-list bound you; hitting any stop condition ends dark mode with one `handback` comment stating the smallest decision needed, your recommendation attached.
 
 Honesty over green: a failing test gets fixed at the root or reported as failing. Weakening a test, an assertion, or acceptance to pass is a cover-up, and cover-ups surface at review with interest.
 
-## Changelog — before hand-back
+## Changelog and chronicle — before hand-back
+
+Every behavior-changing branch carries its changelog entry per dev.md's `changelog:` knob (`changesets` → write `.changeset/<slug>.md` directly, never the interactive CLI; `keep-a-changelog` / `pubspec+changelog` → one bullet under `## [Unreleased]`, creating CHANGELOG.md with the `# Changelog` + `## [Unreleased]` skeleton in the same branch when absent; `none` → skip) **and**, when dev.md says `chronicle: on`, its story entry prepended to `.vegastack/chronicle.md` (format: the `dev-chronicle` skill) — both on the branch, landing atomically with the merge. Docs the brief names as affected get updated in the same branch.
 
-Every behavior-changing branch carries its changelog entry per dev.md's `changelog:` knob; a ship-time guard catches misses, but don't rely on it. `changesets` → write `.changeset/<slug>.md` directly (frontmatter `"<package-name>": <bump>` from the brief's version-impact line, plus a one-paragraph summary — the changeset CLI prompt is interactive, never invoke it here). `keep-a-changelog` / `pubspec+changelog` → one bullet under `## [Unreleased]` (Added/Changed/Fixed/Removed subsection as fits); no CHANGELOG.md yet → create it in the same branch with the skeleton (`# Changelog` + `## [Unreleased]`). `none` → skip. Docs the brief names as affected get updated in the same branch.
+## Verify — the gate function
 
-## Verify
+Before claiming ANY status: **identify** the command that proves it → **run** it fresh and complete → **read** the full output and exit code → only then claim, with the evidence. Tests pass ⇒ a fresh run with 0 failures — never "should pass", never a previous run. Build succeeds ⇒ exit 0. Bug fixed ⇒ the original symptom re-tested. A subagent finished ⇒ you inspected its diff or report file — never its say-so.
 
-- Run the tests dev.md requires (`tests: required` → every changed behavior has a test that runs and passes; `logic-only` → content/config tweaks may skip). Record commands and results for the evidence comment.
-- A `risky` issue gets focused security, failure, and recovery checks on top of the required tests.
-- When dev.md has a `## Verify` runbook, follow it — run the app and smoke-check the flows it names; that live result belongs in the evidence comment alongside the test output. Verify is pre-merge only; post-release checks live in `## Ship` and belong to dev-ship.
-- UI changed and `ui-evidence: playwright` → capture screenshots of the key states and flows and upload them to the shared evidence repo (dev.md `evidence-repo`) under `<this-repo-name>/<issue-number>/<timestamp>-<name>.png` — via the contents API so the repo is never cloned: `base64 < <file> | tr -d '\n' | gh api -X PUT repos/<evidence-repo>/contents/<path> -f message="evidence #<issue>" -F content=@-` (piped stdin, so large screenshots never hit argv limits; timestamped names keep re-captures from colliding; a 409 from a concurrent upload just means retry). Link them in the evidence comment — links, not embeds; private-repo images don't render inline in issues. Evidence repo missing or unreachable → name the local file paths and say so; the hand-back never blocks on it.
-- dev.md's Ship or Verify section is an empty TODO while release/deploy machinery visibly exists → finish this issue normally, then suggest re-running dev-setup so detection can fill it.
+- Run what dev.md's `tests:` knob requires; a `risky` issue gets focused security, failure, and recovery checks on top. When dev.md has a `## Verify` runbook, run the app and smoke-check the flows it names. Verify is pre-merge only; post-release checks live in `## Ship` and belong to dev-ship.
+- UI changed and `ui-evidence: playwright` → capture screenshots of the key states and upload to the shared evidence repo (dev.md `evidence-repo`) under `<this-repo-name>/<issue-number>/<timestamp>-<name>.png` via the contents API, never a clone: `base64 < <file> | tr -d '\n' | gh api -X PUT repos/<evidence-repo>/contents/<path> -f message="evidence #<issue>" -F content=@-` (piped stdin so large screenshots never hit argv limits; timestamped names avoid collisions; a 409 from a concurrent upload just means retry). Link them in the evidence comment — links, never embeds (private-repo images don't render inline). Evidence repo unreachable → name local paths and say so; the hand-back never blocks on it.
+- dev.md's Ship or Verify section is an empty TODO next to visible machinery → finish normally, then suggest re-running dev-setup.
 
-## Independent review — per the dev.md knob
+## Independent review — invoke dev-review
 
-- `subagent` (default): spawn a fresh reviewer subagent that gets the diff, the brief, and dev.md — and no memory of writing the code. It checks: does the change do what the brief says, does anything break, are the tests real? In a harness without subagents, do a separate fresh-eyes review pass against the brief and label it a self-review in the evidence comment; prefer cross-agent there for `risky` work.
-- `cross-agent` (or `cross-agent-risky` on a `risky` issue): push the branch, add to the evidence comment "awaiting cross-agent review", keep `working`, and tell the user which agent to point at the issue. The reviewing session posts findings on the issue; you apply them.
-- Fix real findings and rerun affected checks. Disagree with a finding → say why in the evidence comment rather than silently skipping it.
+Run the `dev-review` skill per dev.md's `review:` knob — fresh subagent axes by default, cross-agent (Codex↔Claude, announced to the operator) per the knob's mapping; it owns the axes, severities, review comment, bounded fix loop, and adjudication rules. Apply its findings through its loop and re-run the affected checks. Disagree with a finding → adjudicate openly per its rules, never silently skip. In a harness without subagents, run dev-review's axis briefs yourself as a labeled self-review.
 
 ## The evidence comment — exactly one, edited in place
 
-```
-## Result
+```markdown
+<!-- vsk:v1 type=evidence rev=1 branch=<name> sha=<sha7> -->
+## Result (v1)
 **Done:** what changed, in behavior terms
-**Tests:** <command> → <result summary>
-**Review:** <mode> — <findings fixed / none / disputed with reason>
-**Changelog:** <entry added / none, with reason>     (when the knob is not `none`)
+**Tests:** <command> → <fresh result>
+**Review:** <mode> — <verdict; adjudications and rulings surfaced, in order made>
+**Changelog:** <entry added / none, with reason>
+**Docs:** brief v<n>, plan v<n> — in sync | unchanged since approval
 **UI evidence:** <links>            (when applicable)
-**Decision:** <one line in the register format>     (only a dark-mode choice that passes dev.md's Decisions test — a proposal; dev-ship records it after naming it in the merge confirmation)
+**Decision:** <register-format proposals>   (only choices passing dev.md's Decisions test)
 **Not done / limits:** the honest list
-Branch: <name> @ <short-sha>
+Branch: <name> @ <sha7>
 ```
 
-Post it, swap `working` → `for-operator`, unassign nothing, stop. Later corrections update this same comment — a stack of stale result comments hides the current truth.
+The `**Review:**` line is the one home of surfaced rulings: every ledger `Ruling:` appears there, in the order made. Run `node <path-to-this-skill>/scripts/evidence-check.mjs --file <draft> --json` before posting — exit 2 means the shape is incomplete; fix, don't post. Post it, swap `working` → `for-operator`, stop, and close with the plain-language summary (which repeats, never replaces, the evidence content): what was built, which paths were taken, the rulings, what's worth the operator double-checking.
 
-## Corrections loop
+## Corrections loop — code and docs move together
 
-The user's comments on a `for-operator` issue are the new frontier: apply them, re-verify what they touch, update the evidence comment, back to `for-operator`. Their corrections never need re-approval ceremony unless they change scope — then it's `needs-operator` and dev-intake's recording rule.
+The operator's comments on a `for-operator` issue are the new frontier. Applying a correction is **one pass**: the code change + the affected brief/plan sections edited to match (revision markers bumped, `Revisions:` line appended) + a ledger line + the evidence comment updated in place — its `sha` to the new head and its `Docs:` line to the new revisions. Re-verify what the correction touched. An operator dismissal of a review finding gets appended to `.vegastack/review-known-patterns.md` with its mandatory "Still flag if:" clause. Then back to `for-operator`. Corrections never need re-approval ceremony unless they change scope — that's `needs-operator` and intake's recording rule.

package/skill/dev-implement/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-implement/references/ledger-and-resume.md

@@ -0,0 +1,27 @@
+# Using the ledger
+
+The ledger comment's format, line vocabulary, and the resume read-order (brief → plan → ledger → `git log`, nothing else) live in the `dev-setup` skill's `references/conventions.md` — this file owns only how dev-implement **uses** them. The ledger is the build's recovery map and the operator's live progress view.
+
+## When to checkpoint
+
+Create the ledger comment as the session's **first write after claiming** — before any code — with just the marker and heading. Then checkpoint, editing in place:
+
+- **After each plan task completes** — and tick the matching checkbox in the plan comment in the same pass. Record the task's base sha *before* starting it, so the `complete` line's commit range is exact.
+- **After each review fix round**, with the addressed/open counts.
+- **At every dark-mode judgment call.** A ruling is any decision the brief/plan didn't make for you that a reviewer or the operator could reasonably question. Rulings are cheap; unrecorded decisions are debt.
+- **On findings deferred or parked at review**, per dev-review's adjudication lines.
+
+Never batch checkpoints "for later" — the ledger's value is exactly that a crash between checkpoints loses one task, not the map. Under concurrent edits, last-writer-wins on one comment is accepted (single-operator workflow); note a clobber if you ever see one.
+
+## Resuming — dev-implement's additions to the protocol
+
+- The takeover of a `working` issue requires the operator's explicit handover word; the protocol never makes claiming automatic.
+- Corroborate, don't re-verify: the commits the ledger names should exist in `git log` — reconcile the ranges; a mismatch is a `handback`, not a guess.
+- A task whose last line is a fix round is mid-loop — resume at the next round with the open findings; a later `complete` line supersedes earlier rounds.
+- Recorded rulings bind the resumed session: build on them, and surface disagreement in the evidence comment instead of re-litigating.
+- The "nothing else" is literal: not the full issue thread, not review round history, not any transcript of the dead session — that is context spent re-reading what the ledger already distills.
+- Re-executing work the ledger marks complete is the single most expensive failure this protocol exists to prevent — after compaction, trust the ledger and `git log` over recollection.
+
+## Surfacing — rulings never die in the dark
+
+Every `Ruling:` line lands on the evidence comment's `**Review:**` line at hand-back, in the order made. The operator reads that list and reverses anything wrong — a ruling that only ever lived in the ledger was a decision made in secret.

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

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+// dev-implement guard: the evidence comment's required shape. Structure blocks;
+// nothing here warns.
+//
+// Exit codes: 0 pass · 2 blocked (this guard has no warn class).
+// Usage: node evidence-check.mjs --file <evidence.md> --json
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseFlags, parseMarker, renderResult } from './lib/gh.mjs';
+
+const REQUIRED_SECTIONS = [
+  [/\*\*Done:\*\*/, '**Done:** section'],
+  [/\*\*Tests:\*\*/, '**Tests:** section (command → fresh result)'],
+  [/\*\*Review:\*\*/, '**Review:** section (mode + verdict/adjudications)'],
+  [/\*\*Changelog:\*\*/, '**Changelog:** section (entry, or none with a holding reason)'],
+  [/\*\*Docs:\*\*/, '**Docs:** section (brief/plan revisions in sync, or unchanged)'],
+  [/\*\*Not done/, '**Not done / limits:** section (the honest list)'],
+];
+
+export function checkEvidence(text) {
+  const blocks = [];
+
+  const marker = parseMarker(text);
+  if (!marker || marker.keys.type !== 'evidence') {
+    blocks.push('missing evidence marker (<!-- vsk:v1 type=evidence rev=n branch=... sha=... -->)');
+  } else {
+    if (!marker.keys.branch) blocks.push('evidence marker missing branch=');
+    if (!/^[0-9a-f]{7,}$/.test(marker.keys.sha ?? '')) blocks.push('evidence marker missing a real sha=');
+  }
+
+  for (const [pattern, label] of REQUIRED_SECTIONS) {
+    if (!pattern.test(text)) blocks.push(`missing ${label}`);
+  }
+
+  if (!/Branch:\s*\S+\s*@\s*[0-9a-f]{7,}/.test(text)) blocks.push('missing "Branch: <name> @ <sha7>" tail line');
+
+  return { blocks, warns: [] };
+}
+
+const invokedDirectly = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (invokedDirectly) {
+  const flags = parseFlags(process.argv.slice(2));
+  let outcome;
+  if (!flags.file) {
+    outcome = { blocks: ['usage: evidence-check.mjs --file <evidence.md> [--json]'], warns: [] };
+  } else {
+    try {
+      outcome = checkEvidence(readFileSync(flags.file, 'utf8'));
+    } catch (error) {
+      outcome = { blocks: [`cannot read evidence: ${error.message}`], warns: [] };
+    }
+  }
+  const { exitCode, text } = renderResult('evidence-check', outcome, { json: Boolean(flags.json) });
+  console.log(text);
+  process.exit(exitCode);
+}

package/skill/dev-implement/scripts/lib/gh.mjs

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+// Shared plumbing for the workflow guard scripts: gh invocation, vsk:v1 comment
+// marker parsing, and the block/warn result contract (facts block, heuristics
+// warn — exit 0 pass · 1 warn-only · 2 block; unverifiable state fails closed).
+import { execFileSync } from 'node:child_process';
+
+export class GhUnavailable extends Error {
+  constructor(message, httpStatus = null) {
+    super(message);
+    this.httpStatus = httpStatus; // parsed from gh's "HTTP <code>" stderr, when present
+  }
+}
+
+// Run gh with explicit args (never a shell) and parse JSON output. Any failure
+// to reach GitHub is a GhUnavailable — callers treat it as "cannot verify",
+// which blocks (fail closed), never as a pass. VSK_GH is a TEST SEAM only
+// (points unit tests at a stub binary); guards are enforcement infrastructure,
+// so never set it in real runs.
+export function ghJson(args, { gh = process.env.VSK_GH || 'gh' } = {}) {
+  let out;
+  try {
+    out = execFileSync(gh, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+  } catch (error) {
+    const stderr = error.stderr?.toString().trim() || '';
+    const status = /HTTP (\d{3})/.exec(stderr)?.[1];
+    throw new GhUnavailable(`gh ${args.join(' ')} failed: ${stderr || error.message}`, status ? Number(status) : null);
+  }
+  try {
+    return JSON.parse(out);
+  } catch {
+    throw new GhUnavailable(`gh ${args.join(' ')} returned unparseable JSON`);
+  }
+}
+
+// Parse a `<!-- vsk:v1 key=value ... -->` marker from a comment/body's first
+// marker line. Returns { keys } or null when no marker exists — and per
+// conventions, no marker means the artifact does not exist (no fallback).
+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 };
+}
+
+// Find the last comment carrying a marker of the given type (last wins: for
+// edited-in-place singletons there is one; for repeated types the newest is
+// the operative one).
+export function findMarkerComment(comments, type) {
+  let found = null;
+  for (const comment of comments ?? []) {
+    const marker = parseMarker(comment.body);
+    if (marker && marker.keys.type === type) found = { comment, keys: marker.keys };
+  }
+  return found;
+}
+
+// Render the guard result and compute the exit code. blocks/warns are arrays of
+// human sentences; the caller passes process.argv-derived json flag.
+export function renderResult(name, { blocks = [], warns = [] }, { json = false } = {}) {
+  const ok = blocks.length === 0;
+  const exitCode = blocks.length > 0 ? 2 : warns.length > 0 ? 1 : 0;
+  let text;
+  if (json) {
+    text = JSON.stringify({ guard: name, ok, blocks, warns }, null, 2);
+  } else {
+    const lines = [`${name}: ${ok ? (warns.length ? 'pass with warnings' : 'pass') : 'BLOCKED'}`];
+    for (const b of blocks) lines.push(`  block: ${b}`);
+    for (const w of warns) lines.push(`  warn: ${w}`);
+    text = lines.join('\n');
+  }
+  return { exitCode, text };
+}
+
+// Minimal flag parser shared by the guards: --key value and boolean --flags.
+export function parseFlags(argv, booleans = ['json']) {
+  const flags = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (!arg.startsWith('--')) continue;
+    const key = arg.slice(2);
+    if (booleans.includes(key)) {
+      flags[key] = true;
+    } else {
+      flags[key] = argv[i + 1];
+      i += 1;
+    }
+  }
+  return flags;
+}

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

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+// dev-implement preflight guard: the deterministic facts that must hold before
+// an agent may claim an issue. Facts block (exit 2 with reasons); nothing here
+// warns — judgment checks stay in the skill prose.
+//
+// Exit codes: 0 pass · 1 pass-with-warnings · 2 blocked (reasons printed).
+// Usage: node preflight.mjs --issue <n> [--repo owner/name] [--me <login>] [--dev-md <path>] --json
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { GhUnavailable, findMarkerComment, ghJson, parseFlags, renderResult } from './lib/gh.mjs';
+
+export function evaluatePreflight({ issue, comments, devMd, me, expect = 'ready' }) {
+  const blocks = [];
+  const warns = [];
+  const labels = (issue.labels ?? []).map((l) => l.name);
+
+  if (issue.state && issue.state !== 'open') blocks.push(`issue is ${issue.state} — only open issues are workable`);
+  const STATE_LABELS = ['needs-operator', 'needs-plan', 'ready', 'working', 'for-operator'];
+  const state = STATE_LABELS.filter((s) => labels.includes(s));
+  if (!state.includes(expect)) {
+    blocks.push(`issue state label is [${state.join(', ') || 'none'}], expected ${expect} (fresh start: ready · resume: working with the operator's handover · corrections: for-operator)`);
+  }
+
+  const approval = findMarkerComment(comments, 'approval');
+  if (!approval) blocks.push('no recorded approval comment (marker type=approval) on the issue');
+
+  const scope = ['research', 'quick-build', 'full-plan'].filter((s) => labels.includes(s));
+  if (scope.length !== 1) blocks.push(`issue needs exactly one scope label (research | quick-build | full-plan), found: ${scope.join(', ') || 'none'}`);
+
+  if (scope[0] === 'full-plan') {
+    const planApproved = (comments ?? []).some((c) => {
+      const m = findMarkerComment([c], 'approval');
+      return m && ['plan', 'brief+plan'].includes(m.keys.scope);
+    });
+    if (!planApproved) blocks.push('full-plan issue without a recorded plan approval (marker type=approval scope=plan or brief+plan)');
+  }
+
+  // The brief-template rule: a resolved Assumptions section is deleted, so the
+  // heading's presence at all means unresolved entries remain.
+  if (/^##\s+Assumptions\b/m.test(issue.body ?? '')) {
+    blocks.push('the brief still carries a "## Assumptions" section — resolve every entry (the section is deleted once resolved) before starting');
+  }
+
+  const openBlockers = issue.blockedBy ?? [];
+  if (openBlockers.length > 0) blocks.push(`open blockers: ${openBlockers.map((b) => `#${b.number}`).join(', ')}`);
+
+  const others = (issue.assignees ?? []).map((a) => a.login).filter((l) => l !== me);
+  if (others.length > 0) blocks.push(`already assigned to ${others.join(', ')} — a working issue belongs to its claimant`);
+
+  const repoLine = /^repo:\s*(\S+)/m.exec(devMd ?? '');
+  if (!repoLine) {
+    warns.push('dev.md has no repo: line — the issue-repo match could not be verified');
+  } else if (issue.repo && repoLine[1] !== issue.repo) {
+    blocks.push(`issue repo ${issue.repo} does not match dev.md repo ${repoLine[1]}`);
+  }
+
+  return { blocks, warns };
+}
+
+export function gatherAndEvaluate(flags) {
+  const repo = flags.repo || ghJson(['repo', 'view', '--json', 'nameWithOwner']).nameWithOwner;
+  const issueNumber = flags.issue;
+  const raw = ghJson(['api', `repos/${repo}/issues/${issueNumber}`]);
+  const comments = ghJson(['api', `repos/${repo}/issues/${issueNumber}/comments`, '--paginate']);
+  let blockedBy = [];
+  try {
+    blockedBy = ghJson(['api', `repos/${repo}/issues/${issueNumber}/dependencies/blocked_by`])
+      .filter((b) => b.state === 'open');
+  } catch (error) {
+    // Only an HTTP 404 (host without the dependencies API) means "none
+    // recorded" — matched on the parsed status, never the message text, so a
+    // path containing "404" can't masquerade. Every other failure — auth,
+    // network, rate limit — is unverifiable state and fails closed.
+    if (error.httpStatus !== 404) throw error;
+    blockedBy = [];
+  }
+  const devMd = readFileSync(flags['dev-md'] || '.vegastack/dev.md', 'utf8');
+  const me = flags.me || ghJson(['api', 'user']).login;
+  return evaluatePreflight({
+    issue: { body: raw.body, state: raw.state, labels: raw.labels, assignees: raw.assignees, repo, blockedBy },
+    comments,
+    devMd,
+    me,
+    expect: flags.expect || 'ready',
+  });
+}
+
+const invokedDirectly = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (invokedDirectly) {
+  const flags = parseFlags(process.argv.slice(2));
+  let outcome;
+  try {
+    outcome = gatherAndEvaluate(flags);
+  } catch (error) {
+    outcome = { blocks: [error instanceof GhUnavailable ? `cannot verify: ${error.message}` : `preflight error: ${error.message}`], warns: [] };
+  }
+  const { exitCode, text } = renderResult('preflight', outcome, { json: Boolean(flags.json) });
+  console.log(text);
+  process.exit(exitCode);
+}