@vegastack/skills 0.9.1 → 0.11.0

package/skill/dev-intake/scripts/brief-lint.mjs

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+// dev-intake guard: deterministic checks on a drafted brief before posting.
+// Missing structure blocks; quality smells only warn (heuristics never block).
+// Inline quick-build plans are linted separately by dev-plan's plan-lint — the
+// banned-placeholder list lives there, its single home.
+//
+// Exit codes: 0 pass · 1 pass-with-warnings · 2 blocked (reasons printed).
+// Usage: node brief-lint.mjs --file <brief.md> --scope <research|quick-build|full-plan> --json
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const REQUIRED_HEADINGS = {
+  research: [/^##\s+.*question/im, /^##\s+.*answered/im],
+  'quick-build': [/^##\s+Outcome\b/m, /^##\s+Tests and acceptance\b/m, /^##\s+Approach/m],
+  'full-plan': [/^##\s+Outcome\b/m, /^##\s+Out of scope\b/m, /^##\s+Tests and acceptance\b/m, /^##\s+Approach/m],
+};
+
+const VAGUE_SMELLS = [
+  /\bworks (properly|correctly|as expected)\b/i,
+  /\buser[- ]friendly\b/i,
+  /\brobust(ly)?\b/i,
+  /\betc\.?\b/i,
+];
+
+export function lintBrief(text, scope, { fix = false } = {}) {
+  const blocks = [];
+  const warns = [];
+
+  if (!REQUIRED_HEADINGS[scope]) {
+    return { blocks: [`unknown scope class "${scope}" (research | quick-build | full-plan)`], warns };
+  }
+  if (!/<!--\s*vsk:v1\s+type=brief\b/.test(text)) blocks.push('missing brief marker (<!-- vsk:v1 type=brief rev=n scope=... -->)');
+  if (scope !== 'research' && !/^\*\*Scope:\*\*/m.test(text)) {
+    blocks.push('missing the **Scope:** line — the announced reason must survive the conversation');
+  }
+  if (fix && !/^##\s+Reproduction\b/m.test(text)) {
+    blocks.push('fix-type brief without a ## Reproduction section — an unreproducible bug is research first');
+  }
+
+  for (const heading of REQUIRED_HEADINGS[scope]) {
+    if (!heading.test(text)) blocks.push(`missing required section for ${scope}: ${heading.source}`);
+  }
+
+  if (scope !== 'research') {
+    const approach = text.split(/^(?=##\s)/m).find((chunk) => /^##\s+Approach/.test(chunk));
+    if (approach && !/`[^`]*[/.][^`]*`/.test(approach)) {
+      blocks.push('Approach and touch points names no real backticked paths — grounding was skipped or unrecorded');
+    }
+  }
+
+  for (const smell of VAGUE_SMELLS) {
+    const hit = smell.exec(text);
+    if (hit) warns.push(`vague wording: "${hit[0]}" — name the observable behavior instead`);
+  }
+
+  return { blocks, warns };
+}
+
+const invokedDirectly = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (invokedDirectly) {
+  const argv = process.argv.slice(2);
+  const json = argv.includes('--json');
+  const get = (flag) => { const i = argv.indexOf(flag); return i === -1 ? undefined : argv[i + 1]; };
+  let outcome;
+  const file = get('--file');
+  const scope = get('--scope');
+  if (!file || !scope) {
+    outcome = { blocks: ['usage: brief-lint.mjs --file <brief.md> --scope <class> [--fix] [--json]'], warns: [] };
+  } else {
+    try {
+      outcome = lintBrief(readFileSync(file, 'utf8'), scope, { fix: argv.includes('--fix') });
+    } catch (error) {
+      outcome = { blocks: [`cannot read brief: ${error.message}`], warns: [] };
+    }
+  }
+  const ok = outcome.blocks.length === 0;
+  const exitCode = ok ? (outcome.warns.length ? 1 : 0) : 2;
+  if (json) {
+    console.log(JSON.stringify({ guard: 'brief-lint', ok, ...outcome }, null, 2));
+  } else {
+    console.log(`brief-lint: ${ok ? (outcome.warns.length ? 'pass with warnings' : 'pass') : 'BLOCKED'}`);
+    for (const b of outcome.blocks) console.log(`  block: ${b}`);
+    for (const w of outcome.warns) console.log(`  warn: ${w}`);
+  }
+  process.exit(exitCode);
+}

package/skill/dev-plan/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: dev-plan
+description: Write the implementation plan for an approved issue before any code exists. Use when asked to "plan issue 12", "write the plan for" a feature or issue, "plan this before building", when picking up an issue labeled needs-plan, when an approved brief needs its technical approach worked out, or when dev-intake requests the inline plan for a quick-build issue. Not for writing or approving the brief itself (dev-intake), not for executing an approved plan (dev-implement), not for architecture stack advice (dev-architect — this skill consults it while planning).
+---
+
+# dev-plan
+
+The planning stage: an approved brief goes in, an operator-approved plan comes out, and only then does code exist. Plans are written against the repo **as it is now** — a separate session from intake for `full-plan` issues, because code drifts between brief approval and build. Formats follow the `dev-setup` skill's `references/conventions.md` (cited by name — read it wherever dev-setup is installed).
+
+Nearest neighbors: `dev-intake` owns the brief and its approval mechanics — this skill owns the how; `dev-implement` executes what this produces, task by task. If `.vegastack/dev.md` is missing → run `dev-setup` first.
+
+## Every run
+
+1. Read `.vegastack/dev.md` and the issue: brief (description), recorded brief approval (`type=approval` marker), scope label. Full-plan issues arrive labeled `needs-plan`; anything else at this door is either intake's inline request (below) or a misroute — say so.
+2. **Re-ground.** Open the brief's touch points in the current code; verify the flow, names, and shapes the plan will build on. A brief claim that no longer matches reality goes back to the operator (`handback` comment, `needs-operator`) — never plan on top of drift.
+3. Stack-bearing choices (schema, hosting, services, jobs, auth) check `dev-architect` — its verify protocol governs platform claims, and no plan re-proposes a recorded rejection.
+
+## The questionnaire
+
+Numbered rounds over the full frontier (every open question whose prerequisites are settled), each question carrying a recommended answer so the operator can reply "all recommended":
+
+1. **Approaches** — 2–3 candidates with the trade-off that matters and one recommendation. Never a single option.
+2. **System design** — schema, interfaces, migration shape, failure modes; what breaks at the edges.
+3. **Risk** — blast radius, what a rollback looks like, what should stop a dark run beyond the standing stop-list.
+4. **Brief challenge** — anything planning revealed the brief missed or got wrong goes back to the operator as a question, never silently absorbed into the plan.
+
+A vague or self-contradicting answer gets pushback with concrete options — simple words, a mermaid or ASCII sketch in the issue when a picture beats prose (conventions' collaboration rule).
+
+## The plan
+
+Post one comment per [plan-format](references/plan-format.md): Goal · Approach (alternatives named) · Constraints · ordered `- [ ]` tasks, each with exact Files, an Interfaces block (consumes/produces with exact signatures), and Steps that put the failing test before the code. Before posting:
+
+- Self-review: every brief requirement maps to a task; names and types are consistent across tasks; no banned placeholders (the list lives in plan-format).
+- Run this skill's plan-lint: `node <path-to-this-skill>/scripts/plan-lint.mjs --file <draft> --json`; exit 2 = fix before posting (placeholders and structural gaps block).
+
+Checkboxes belong to the implement session — never pre-tick them.
+
+## Labels and approval
+
+Post the plan → flip to `needs-operator`. On the operator's "plan approved": record `<!-- vsk:v1 type=approval scope=plan -->` with their quoted words (`operator (<username>)` format), flip to `ready`, stop — building is dev-implement's.
+
+## The ratchet — one home, this file
+
+- **Upgrade (any time, no permission needed to propose):** planning reveals the work is bigger than its scope label — a quick-build that needs real design, an issue that is actually several deliverables. Stop, post one `handback` comment proposing the reclassification or the epic split (parent map + sub-issues, each classified fresh), `needs-operator`. Never silently plan a monster: a plan approaching GitHub's ~65,536-character comment cap is the slicing telling you it wants to be an epic.
+- **Downgrade (operator's yes only):** planning reveals the work is trivial — propose skipping to `ready` with the brief's inline approach, and wait for the yes.
+
+## Quick-build inline mode
+
+Invoked from inside dev-intake's conversation, after the brief has consensus: same format, proportionally small (a four-item task list is a fine plan), posted as the plan comment alongside the brief. The operator's single approval covers both (`scope=brief+plan`) — no `needs-plan` stop, no second exchange. The re-grounding step collapses to what intake already read; the ratchet still applies.
+
+## Closing
+
+End every run with the plain-language summary: what was planned, which approach won and why, what the operator should double-check, and what happens next.

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "dev-plan"
+  short_description: "Plan an approved issue before any code exists"
+  default_prompt: "Use $dev-plan to write the implementation plan for this approved issue."

package/skill/dev-plan/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-plan/references/plan-format.md

@@ -0,0 +1,54 @@
+# The plan format
+
+The comment a plan lives in, verbatim. dev-implement executes it task by task and ticks the checkboxes; plan-lint enforces the deterministic parts.
+
+````markdown
+<!-- vsk:v1 type=plan rev=1 -->
+## Plan (v1)
+
+**Goal:** <one sentence: what exists when this plan is done>
+**Approach:** <2–3 sentences — and the alternatives considered with why they lost, one line each>
+**Constraints:** <binding requirements from the brief and Architecture facts, exact values, one per line>
+
+### Tasks
+
+- [ ] **Task 1: <name>**
+  - Files — Create: `exact/path.ts` · Modify: `exact/path.ts` (<which area>) · Test: `exact/path.test.ts`
+  - Interfaces — Consumes: <exact signatures/names from earlier tasks> · Produces: <exact names, parameter and return types later tasks rely on — an implementer may see only this task; this block is how they learn what neighbors use>
+  - Steps: write the failing test (the actual test code, fenced) → run it, expect FAIL with <reason> → implement the minimal code → run, expect PASS → commit `<type>: <message>`
+- [ ] **Task 2: …**
+
+**Revisions:** (absent until a post-approval edit; then one line per edit)
+````
+
+## Rules
+
+- **Task size:** the smallest unit that carries its own test cycle and is worth a fresh reviewer's look. Fold setup/scaffolding/docs into the task whose deliverable needs them; split only where a reviewer could reject one task while approving its neighbor. Each task ends independently verifiable.
+- **Prose tasks** (docs, skill text, config) swap the test-first Steps for edit → verify (the concrete command: `bun run check`, a link-resolution run, a rendered read-through) → commit. The verify step is never omitted.
+- **Revisions:** post-approval edits follow the revision-marker rule in dev-setup's `references/conventions.md` — bump the heading/marker version and append the `Revisions:` line.
+
+## Banned placeholders
+
+These are plan failures — plan-lint rejects them, and a human reviewer should too:
+
+- "TBD", "TODO", "implement later", "fill in details"
+- "Add appropriate error handling" / "add validation" / "handle edge cases"
+- "Write tests for the above" without the actual test code
+- "Similar to Task N" — repeat the content; tasks are read out of order
+- Steps that describe what to do without showing how (code steps require code blocks)
+- References to types, functions, or files no task defines
+
+## Self-review before posting
+
+1. **Coverage:** walk the brief section by section — every requirement points at a task; list any gap (a gap is a question for the operator, not a silent omission).
+2. **Placeholder scan:** search the draft for the banned list above; fix inline.
+3. **Consistency:** names, signatures, and paths used in later tasks match what earlier tasks define — `clearLayers()` in Task 3 but `clearFullLayers()` in Task 7 is a bug now, not at build time.
+
+## Worked micro-example
+
+```markdown
+- [ ] **Task 1: reminder schedule column**
+  - Files — Modify: `server/db/schema/invoices.ts` (invoices table) · Test: `server/db/schema/invoices.test.ts`
+  - Interfaces — Produces: `invoices.reminderAt: timestamp | null` (Drizzle column), read by Task 2's query
+  - Steps: failing test asserting the column exists in the generated schema → run, expect FAIL "no such column" → add the column + regenerate → run, expect PASS → commit `feat: reminder schedule column`
+```

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

@@ -0,0 +1,3 @@
+# Refresh contract — dev-plan
+
+Evergreen: this skill asserts no version pins, vendor mechanisms beyond long-stable GitHub comment behavior (the ~65,536-character comment cap is stated as approximate and directional), numeric vendor limits, or dated claims — its content is planning discipline (questionnaire, plan format, ratchet), all versionless. Revisit if a future edit introduces a volatile fact.

package/skill/dev-plan/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-plan/scripts/plan-lint.mjs

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+// dev-plan guard: deterministic checks on a drafted plan comment. Placeholders
+// and structural gaps block; nothing here warns. The banned-placeholder list's
+// single home is this file — brief-lint defers inline-plan checks to it.
+//
+// Exit codes: 0 pass · 2 blocked (this guard has no warn class).
+// Usage: node plan-lint.mjs --file <plan.md> --json
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+// Self-contained on purpose: plan-lint ships with dev-plan and must run on a
+// standalone install, so it carries its own tiny flag/result helpers instead of
+// importing dev-implement's lib.
+
+export const bannedPlaceholders = [
+  /\bTBD\b/,
+  /\bTODO\b/,
+  /implement later/i,
+  /fill in details/i,
+  /add appropriate error handling/i,
+  /\badd validation\b/i,
+  /handle edge cases/i,
+  /write tests for the above/i,
+  /similar to task \d+/i,
+];
+
+export function lintPlan(text) {
+  const blocks = [];
+
+  if (!/<!--\s*vsk:v1\s+type=plan\b/.test(text)) blocks.push('missing plan marker (<!-- vsk:v1 type=plan rev=n -->)');
+
+  for (const pattern of bannedPlaceholders) {
+    const hit = pattern.exec(text);
+    if (hit) blocks.push(`banned placeholder: "${hit[0]}" — plans carry the actual content`);
+  }
+
+  // A Task-header line not carried by a checkbox would otherwise be absorbed
+  // into the previous task's chunk and inherit its sections — detect it.
+  // Anchored to the line START so mid-line references ("consumes Task 2's
+  // output") never false-block.
+  for (const line of text.split('\n')) {
+    const t = line.trim();
+    if (/^(\*\*|[-*]\s+\*\*)?Task \d+:/.test(t) && !/^- \[[ x]\]/.test(t)) {
+      blocks.push(`task line without a checkbox: "${t.slice(0, 60)}"`);
+    }
+  }
+
+  const tasks = text.split(/^- \[[ x]\] \*\*Task /m).slice(1);
+  if (tasks.length === 0) blocks.push('no checkbox tasks found (- [ ] **Task N: ...**)');
+  tasks.forEach((task, index) => {
+    const n = index + 1;
+    if (!/Files\s*—/.test(task)) blocks.push(`task ${n}: missing "Files —" line with exact paths`);
+    if (!/Interfaces\s*—/.test(task)) blocks.push(`task ${n}: missing "Interfaces —" block (consumes/produces)`);
+    if (!/Steps[:\s]/.test(task)) blocks.push(`task ${n}: missing "Steps" line`);
+    if (/failing test/i.test(task) && !task.includes('```')) {
+      blocks.push(`task ${n}: a failing-test step must carry the actual test code in a fenced block`);
+    }
+  });
+
+  return { blocks, warns: [] };
+}
+
+const invokedDirectly = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (invokedDirectly) {
+  const argv = process.argv.slice(2);
+  const json = argv.includes('--json');
+  const fileIndex = argv.indexOf('--file');
+  let outcome;
+  if (fileIndex === -1 || !argv[fileIndex + 1]) {
+    outcome = { blocks: ['usage: plan-lint.mjs --file <plan.md> [--json]'], warns: [] };
+  } else {
+    try {
+      outcome = lintPlan(readFileSync(argv[fileIndex + 1], 'utf8'));
+    } catch (error) {
+      outcome = { blocks: [`cannot read plan: ${error.message}`], warns: [] };
+    }
+  }
+  const ok = outcome.blocks.length === 0;
+  if (json) {
+    console.log(JSON.stringify({ guard: 'plan-lint', ok, ...outcome }, null, 2));
+  } else {
+    console.log(`plan-lint: ${ok ? 'pass' : 'BLOCKED'}`);
+    for (const b of outcome.blocks) console.log(`  block: ${b}`);
+  }
+  process.exit(ok ? 0 : 2);
+}

package/skill/dev-review/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: dev-review
+description: Independent review of finished implementation work — a diff against its brief and plan. Use when dev-implement's review step runs, when asked to "review this branch/diff/issue", "give this a second pair of eyes", "check the finished work on issue N", when a cross-agent session (Claude or Codex) is handed a REVIEW REQUEST, or when review findings need a fix loop, re-review, or adjudication. Not for reviewing an unbuilt plan (dev-plan's approval gate), architecture review (dev-architect), shipping gates (dev-ship), or generic PR review in repos outside this workflow.
+---
+
+# dev-review
+
+Review is a specified system, not a vibe: fresh eyes per axis, severities with teeth, a bounded fix loop, and every dismissal on the record. The reviewer's job is findings or verified absence of findings — never praise. Formats follow the `dev-setup` skill's `references/conventions.md`; the reviewer briefs live in [dispatch-prompts](references/dispatch-prompts.md).
+
+Nearest neighbors: `dev-implement` invokes this per dev.md's `review:` knob and applies the findings; `dev-ship` consumes the verdict marker; `dev-plan`'s approval gate reviews plans before build — this skill reviews built work after.
+
+## Inputs — files, never pasted context
+
+Build the review package first: `git log --oneline <base>..<head>` + `git diff --stat` + `git diff -U10`, written to `.vegastack/.tmp/<issue>-<slug>/review-<base7>..<head7>.diff`. Reviewers get paths — the brief (issue body), the plan comment, the package file, the project's `.vegastack/review-known-patterns.md` — plus the binding constraints copied verbatim. Reviewers write their full reports to `.tmp` files and return short status; a dead reviewer's findings survive on disk.
+
+## The axes — parallel, fresh, never merged
+
+| Axis | Runs | Judges |
+|---|---|---|
+| **Spec** | always | the diff vs the CURRENT brief + plan: missing, scope creep, implemented-but-wrong — quoting the brief line per finding; includes the tests-are-real rubric |
+| **Standards** | always | project rules (known-patterns file + repo docs, which override) + the fixed smell baseline pasted in full into its prompt |
+| **Security** | on `risky`, or when touch points hit auth, money, user data, or external input | data-flow traces, exploitability before severity — method in [security-axis](references/security-axis.md) |
+
+Each axis is a fresh subagent with no memory of writing the code (its prompt: [dispatch-prompts](references/dispatch-prompts.md)). Axes report separately and are never re-ranked into one list — a change can pass one axis and fail another, and merging lets one mask the other.
+
+**Never pre-judge.** A dispatch containing "do not flag…", "don't treat X as a defect", or "at most minor" is forbidden — if you believe something is a false positive, let the reviewer raise it and adjudicate it openly in the loop.
+
+## The review comment — one per cycle, rounds appended, marker always current
+
+One comment per review cycle. **The single marker at the top is edited every round** to the newest `round`/`sha`/`verdict` — consumers (ship-gate) read the first marker, so a stale round-1 `needs-fixes` must never sit above a clean round 3. Prior rounds stay as plain `## Review — round <n>` sections appended below, carrying no markers of their own.
+
+```markdown
+<!-- vsk:v1 type=review round=<n> sha=<head7> agent=<claude|codex> verdict=<clean|needs-fixes> -->
+## Review — round <n> @ <sha7>
+
+**Verdict: <clean|needs-fixes>** — spec: <counts> · standards: <counts> · security: <counts | n/a (no surface)>
+
+### <Axis> axis
+**Finding [N]: <title>** — **[SEVERITY]** (confidence: high|medium|low) `path/file.ts:42`
+<issue> / <why it matters> / <fix, fenced snippet> / <quoted brief line, spec axis>
+
+<details><summary>Nitpicks and low-confidence (N) — non-blocking</summary>…</details>
+
+Reviewed: <sha7> · axes: <list> · reviewer: <mode>
+```
+
+Severities: `[CRITICAL]` (security axis: exploitable now — blocks) > `[MUST-FIX]` (wrong, broken, or contradicts the brief — blocks) > `[SHOULD-FIX]` (convention or quality, does not block) > `[NIT]`. Finding IDs are `Finding [N]` — never `#N`, which GitHub auto-links. Low-confidence findings and nitpicks go in the collapsed block, never the main list. Group one recurring defect across files into one finding with a location list.
+
+## The loop — 3 rounds max, then open adjudication
+
+`[CRITICAL]` and `[MUST-FIX]` findings enter the loop; `[SHOULD-FIX]`/`[NIT]` are fixed opportunistically or recorded as deferred minors — they never extend it.
+
+- **Rounds 1–2:** resume (or redispatch) the implementer with the open findings verbatim and the report-file path. It fixes, re-runs the covering tests, appends its fix report to the same file.
+- **Round 3:** a fresh implementer — "a prior implementer attempted this; read the report file for what was tried." A loop surviving two resumes usually means the implementer can't see its own problem.
+- **Every round:** the re-review is scoped to the fix diff (`FIX_BASE..HEAD`, a new package file); the re-reviewer verdicts each finding **ADDRESSED / NOT ADDRESSED** ("attempted" is not addressed), and new breakage in the fix diff joins the open list. Out-of-scope observations become deferred minors.
+- **At the cap:** adjudicate each open finding yourself, openly — parked with a ruling ("why the code stands"), or fixed forward — every adjudication lands in the evidence comment's Review line and the ledger. Adjudicating early to end a loop is pre-judging with a different name.
+
+## Noise controls — hard filters, not politeness
+
+- Default quiet profile: spec, bugs, and security always; style only where a documented rule exists. The comment count is the noise metric.
+- `.vegastack/review-known-patterns.md` (seed: [template](assets/review-known-patterns.md.template)) holds the project's never-flag patterns — each entry REQUIRES a **"Still flag if:"** exception clause; a suppression without one is a blind spot. Operator dismissals of findings get appended there by dev-implement's corrections loop, so a dismissed pattern stays dismissed.
+
+## Cross-agent — the independence upgrade
+
+The dev.md `review:` knob maps to exactly three states — `subagent` (fresh-subagent axes always, cross-agent never), `cross-agent-risky` (subagent axes normally; the other agent on `risky` — the recommended default where the CLI exists), `cross-agent` (the other agent always). When it runs on the other agent, follow [cross-agent](references/cross-agent.md): announce the invocation to the operator at trigger time, send the `REVIEW REQUEST (vsk cross-agent v1)` handoff (`codex exec` from Claude; `claude -p` from Codex), and summarize the outcome at the end. The reviewing agent posts its own review comment (`agent=codex`), so independence is verifiable. CLI absent → fall back to the manual relay and note that dev-setup recommends installing it.
+
+## Closing
+
+End with the plain-language summary: verdict, what was found and fixed, what was adjudicated and why, and what's worth the operator double-checking.

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "dev-review"
+  short_description: "Independent multi-axis review of finished work"
+  default_prompt: "Use $dev-review to review this branch against its brief and plan."

package/skill/dev-review/assets/review-known-patterns.md.template

@@ -0,0 +1,30 @@
+# Review known patterns — {{owner/repo}}
+
+The project's never-flag list. Every entry REQUIRES a "Still flag if:" exception clause — a suppression without one is a blind spot, not a calibration. dev-implement's corrections loop appends an entry whenever the operator dismisses a review finding, so dismissed patterns stay dismissed. Repo-documented standards override the reviewer's baseline; this file overrides neither — it only suppresses specific recurring false positives.
+
+Format, one entry per pattern:
+
+```markdown
+## <short pattern name>
+
+**Pattern:** <what the reviewer keeps flagging, concretely — code shape, file area>
+**Why it's safe here:** <the project fact that makes it a false positive>
+**Still flag if:** <the exception that makes it a real finding after all>
+**Origin:** <date + issue where the dismissal happened — operator (<username>)>
+```
+
+## Worked examples (replace with real entries)
+
+### Sequential awaits in setup scripts
+
+**Pattern:** consecutive `await` calls in bootstrap/setup code flagged as a parallelization miss.
+**Why it's safe here:** setup steps have ordering dependencies the reviewer can't see locally (labels before issues, scaffold before wiring).
+**Still flag if:** the awaits are inside a hot request path or a loop over user data.
+**Origin:** seeded example — delete when the first real entry lands.
+
+### Direct `gh` CLI calls without a wrapper
+
+**Pattern:** scripts shelling to `gh` flagged as needing an API client abstraction.
+**Why it's safe here:** the workflow standardizes on `gh` for auth and pagination; a wrapper would duplicate it.
+**Still flag if:** arguments are interpolated into a shell string instead of an execFile arg array.
+**Origin:** seeded example — delete when the first real entry lands.

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