@vegastack/skills 0.9.1 → 0.11.0

package/skill/dev-chronicle/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: dev-chronicle
+description: The project's narrative record — what got built, why, and how it went, in plain language for the operator's future recall. Use when asked to "catch me up on this project", "what did we build here", "what happened in this repo", "tell me the story so far", "what's the project story", when a chronicle entry needs writing for finished work, or when dev-implement's hand-back cites the chronicle format. Not for the consumer-facing changelog (dev-implement writes those per the changelog knob), release notes (dev-ship), or current board state ("what needs me" is dev-status).
+---
+
+# dev-chronicle
+
+`.vegastack/chronicle.md` is the project's story, newest first — the answer to "what did I build here and what happened?" months later, when the operator remembers nothing. Entries are **story language for a human**, never commit-log prose: the changelog tells consumers what changed; the chronicle tells the operator what happened.
+
+Nearest neighbors: `dev-implement` writes the entries at hand-back (the write rule lives there; the format lives here); `dev-status` answers "what needs me now" — this skill answers "how did we get here". `dev-ship`'s ship-gate checks entry presence when dev.md says `chronicle: on`.
+
+## The entry — one per behavior-changing branch
+
+```markdown
+## DD-MM-YYYY — <title: the change as a human outcome — not a mechanism, not a commit subject> (#<issue>)
+
+**What:** <2–4 plain sentences: what exists now that didn't, from the operator's point of view>
+**Why:** <the need that prompted it>
+**How it went:** <the honest one-liner: smooth / what fought back / what was cut>
+**Changed:** <the user-visible changes, simple words — bullets or one ·-separated line>
+**Decisions:** <register lines it produced, or "none">
+— approved by operator (<username>) · built by <agent> · branch <name>
+```
+
+- Titles name the outcome ("Invoice reminders now chase late payers"), never the mechanism ("add reminderAt column").
+- Prepend — newest first. File missing → create it with a two-line header naming this skill as the format home.
+- **How it went** is where honesty lives: what fought back, what was cut, what surprised. "Smooth" is a fine answer; silence is not.
+- Research issues get an entry only when the findings changed direction; docs/test-only merges get none (ship-gate's excuse flag covers both records at once).
+- A notable ship event — rollback, failed release — becomes its own short entry on the next branch, not a rewrite of an old one. Entries are never edited except for typos; the story is append-only like the register.
+
+## The digest — "catch me up"
+
+On "catch me up on this project" (or any story-so-far ask), read **only** `.vegastack/chronicle.md` and the decision register — never git archaeology — and render three parts, plain language throughout:
+
+1. **The story so far** — 3–5 sentences: what this project is, the arc of what's been built, where it stands.
+2. **Recent chapters** — the last 3–7 entries, one line each: date, the outcome title, and the one thing worth remembering from How-it-went.
+3. **Open threads** — pending decisions the register hasn't recorded, entries whose How-it-went named unfinished business, and (when `dev-status` is installed) a one-line pointer to run it for the live board.
+
+Length scales with the ask: "catch me up quickly" is one paragraph; a returning-after-months operator gets all three parts. Never pad — a young project with three entries gets three honest lines.
+
+## Setup
+
+The `chronicle:` knob in dev.md (`on` default | `off`) governs whether dev-implement writes entries and ship-gate checks them; `dev-setup` writes the knob. A project that turns it on mid-life starts from now — no retroactive backfill unless the operator asks, and then it's marked as reconstructed.
+
+Close every run with the plain-language summary: what was written or rendered, and anything the story surfaced that deserves the operator's attention.

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "dev-chronicle"
+  short_description: "The project's story — entries and the catch-me-up digest"
+  default_prompt: "Use $dev-chronicle to catch me up on this project."

package/skill/dev-chronicle/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-chronicle/refresh/REFRESH.md

@@ -0,0 +1,3 @@
+# Refresh contract — dev-chronicle
+
+Evergreen: this skill asserts no version pins, vendor mechanisms, numeric limits, or dated claims — its content is a narrative format and a reading discipline, all versionless. Revisit if a future edit introduces a volatile fact.

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

@@ -0,0 +1,43 @@
+---
+name: dev-debug
+description: Reproduce-first bug work. Use when given a bug to fix — "debug this", "this is broken and I don't know why", "users report X fails", "login intermittently 500s", implementing a fix-type issue whose brief carries a Reproduction section, or when a fix keeps not fixing the symptom. Not for writing the bug up as an issue (dev-intake), building planned features (dev-implement — this skill governs the diagnosis inside its dark mode), or reviewing a finished fix (dev-review).
+---
+
+# dev-debug
+
+The failure this skill prevents: reading code, forming one theory, and "fixing" something that was never the cause. The discipline is a hard order — **reproduce, shrink, suspect, test, prove, clean** — and each phase has a completion criterion you can check, not vibe. It runs inside dev-implement's dark mode: no operator questions; missing-artifact stops are one `handback` comment; every phase result is a ledger checkpoint.
+
+Nearest neighbors: `dev-intake`'s bug variant writes the brief this skill executes; `dev-implement` owns the surrounding build ceremony; `dev-review` judges the finished fix.
+
+## Phase 1 — the red command. No red command, no theorizing.
+
+Build **one named command** that demonstrates the bug: it fails right now *because of this bug's exact symptom*, and will pass once it's truly fixed. The completion criterion, all four checkable:
+
+- **Red-capable** — it asserts the reported symptom, not "runs without erroring"; you have run it at least once and its invocation + failing output (redacted) go in the ledger.
+- **Deterministic** — same verdict every run; a flaky bug substitutes a pinned, stated reproduction rate ("~1 in 12 across 50 runs").
+- **Fast** — seconds, not minutes; a tight loop is the whole superpower here.
+- **Agent-runnable** — no human in the loop.
+
+Pick the cheapest rung that reaches the bug from the [loop ladder](references/loop-ladder.md). Can't build one after walking the ladder → stop: one `handback` comment listing what was tried and asking for artifacts (logs, HAR, recording, environment access), `needs-operator`. Proceeding to theories without a red command is the exact failure this skill exists to prevent.
+
+## Phase 2 — shrink until everything left is load-bearing
+
+Run the loop, watch it go red on the *reported* symptom (the wrong bug means the wrong fix). Then minimise: cut inputs, callers, config, and steps **one at a time**, re-running after each cut, keeping only what the failure needs. Done when removing any remaining element turns the loop green. The minimal repro shrinks the suspect space and becomes Phase 5's regression test.
+
+## Phase 3 — suspects: 3–5, ranked, falsifiable, posted, then GO
+
+List 3–5 candidate causes ranked most-likely first — a single hypothesis anchors on the first plausible idea. Each must be **falsifiable**: "if X is the cause, then changing Y makes the bug disappear / Z makes it worse." A suspect whose prediction you can't state is a vibe — discard or sharpen it. **Post the ranked list to the ledger and proceed immediately** — never pause for the operator (their async re-rank is welcome whenever it comes; dark mode holds).
+
+## Phase 4 — test suspects one variable at a time
+
+Every probe maps to one suspect's prediction. Prefer a debugger/REPL breakpoint over logs; when logging, target the boundaries that separate suspects — never "log everything and grep". **Every debug log carries a `[DEBUG-<4hex>]` tag** (one random tag per session): cleanup becomes a single grep, and ship-gate blocks any tag that survives into the diff. Performance bugs: logs lie — measure a baseline first (timing harness, profiler, query plan), then bisect.
+
+## Phase 5 — regression test before the fix
+
+Write the failing test **before** touching the fix, at a **correct seam**: one where the test exercises the real bug pattern as it occurs at the call site. If the only reachable seam is too shallow to replicate the trigger, **that is itself a finding** — record it in the ledger and evidence; a false-confidence test is worse than a named gap. With a correct seam: minimal repro → failing test → watch it fail → fix → watch it pass → re-run the **original un-minimised** Phase 1 loop green.
+
+## Phase 6 — clean up and teach
+
+Before hand-back, all checkable: the original repro re-runs green · `git diff <base>... | grep -F '[DEBUG-'` comes back empty (fixed-string grep; ship-gate backstops the added lines) · throwaway harnesses deleted · the **winning suspect and its evidence** named in the evidence comment and the commit message — the next debugger learns what it actually was, not just that it went away.
+
+Close with the plain-language summary: the symptom, the cause, the proof, and anything the investigation surfaced that deserves its own issue.

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "dev-debug"
+  short_description: "Reproduce-first bug diagnosis and fix"
+  default_prompt: "Use $dev-debug to find and fix this bug."

package/skill/dev-debug/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-debug/references/loop-ladder.md

@@ -0,0 +1,20 @@
+# The loop ladder
+
+How to build the red command, cheapest rung that reaches the bug first. The goal is always the same: symptom in, verdict out, seconds per run, no human.
+
+1. **Failing test** at whatever seam reaches the bug — unit, integration, or e2e. First choice when the code path is importable.
+2. **Curl / HTTP script** against a running dev server, asserting on status/body — for bugs that live in the request path.
+3. **CLI invocation with a fixture input**, diffing stdout/exit code against known-good — for tools and scripts.
+4. **Headless browser script** (Playwright or equivalent) driving the UI and asserting on DOM, console, or network — when the bug needs a real browser.
+5. **Captured-trace replay** — save a real request/payload/event log once, replay it through the code path in isolation; turns "only happens with production data" into a loop.
+6. **Throwaway harness** — boot the minimal slice of the system (one service, mocked deps) that exercises the path with a single call. Deleted in Phase 6.
+7. **Property/fuzz loop** — for "sometimes wrong output": run hundreds of random inputs and trap the failure mode; the trapped case seeds the minimised repro.
+8. **Bisection harness** — when the bug appeared between two known states (commit, dataset, version): automate "boot at state X, check, report" so `git bisect run` can drive it.
+
+## Tightening
+
+A loop earns its keep on three axes — make it **faster** (mock the slow dependency, cache the boot), **sharper** (assert the exact symptom, not a proxy), **more deterministic** (pin the clock, the seed, the ordering). A 30-second flaky loop is barely better than none; a 2-second deterministic one changes what's possible.
+
+## When no rung works
+
+That's a stop, not a license to guess: `handback` with the rungs tried, why each failed, and the specific artifact or access that would unlock one (a HAR of the failing request, server logs around the timestamp, a screen recording, an environment credential). The operator trades one artifact for a loop; nobody trades theories for luck.

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

@@ -0,0 +1,3 @@
+# Refresh contract — dev-debug
+
+Evergreen: this skill asserts no version pins, vendor mechanisms, numeric limits, or dated claims — its content is diagnosis discipline (the phase order, the red-command criterion, the ladder), all versionless. Revisit if a future edit introduces a volatile fact.

package/skill/dev-debug/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-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.
+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. 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. 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.