@vegastack/skills 0.10.0 → 0.11.0

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.

package/skill/dev-review/references/cross-agent.md

@@ -0,0 +1,39 @@
+# Cross-agent review
+
+The independence upgrade: the review runs on the *other* agent — Codex when Claude built the code, Claude when Codex did — so the reviewer shares no model, no session, and no authorship with the implementer. Used on `risky` issues by default and whenever dev.md's `review:` knob says `cross-agent`.
+
+## Announce, invoke, summarize — the operator is never blind
+
+1. **At trigger time**, tell the operator in plain language: "invoking Codex for the cross-agent review of issue #N" — before the call, not after.
+2. **Invoke** non-interactively with the handoff below passed as ONE argument through an exec arg array — `execFile('codex', ['exec', handoff])` from Claude, `execFile('claude', ['-p', handoff])` from Codex — never interpolated into a shell string (the exact pattern this skill's own known-patterns template says to still-flag).
+3. **At the end**, summarize: which agent reviewed, the verdict, where its comment is, and what's worth the operator double-checking.
+
+## The handoff — exact format
+
+```
+REVIEW REQUEST (vsk cross-agent v1)
+repo: <absolute path> · issue: <url> · branch: <name> · range: <base7>..<head7>
+brief: the issue description (marker type=brief) · plan: the issue comment
+marked type=plan · package: <path to the review package file> · known-patterns:
+.vegastack/review-known-patterns.md · conventions: references/conventions.md inside ANY installed dev-family skill
+(e.g. .claude/skills/dev-review/references/conventions.md — every dev skill ships a copy)
+axes: spec, standards[, security]
+output contract: post exactly ONE issue comment in the review-comment format
+(marker: <!-- vsk:v1 type=review round=<n> sha=<head7> agent=codex verdict=... -->;
+the reverse direction writes agent=claude);
+on a re-review round, EDIT that same comment — update its single top marker to the
+new round/sha/verdict and append the round section below (never a second marker,
+never a second comment),
+findings as Finding [N] with severities [CRITICAL|MUST-FIX|SHOULD-FIX|NIT] and
+path:line evidence; nitpicks and low-confidence collapsed in <details>.
+constraints: READ-ONLY — never commit, push, edit files, or change labels; your
+only write is the review comment, via gh.
+```
+
+The reviewing agent posts its own comment with its own `agent=` key — independence stays verifiable in the record, never paraphrased by the author.
+
+## Fallbacks and failure honesty
+
+- The other agent's CLI is not installed → fall back to the manual relay (tell the operator which agent to point at the issue), and note that `dev-setup` records the gap and recommends installing it.
+- The invocation fails or times out → say so plainly, fall back to a fresh-subagent review, and label the evidence comment's Review line accordingly — never silently substitute and call it cross-agent.
+- The other agent's review misses the output contract (no marker, no severities) → treat its content as raw findings: post them yourself in the correct format with `agent=` credited, and note the reformatting.

package/skill/dev-review/references/dispatch-prompts.md

@@ -0,0 +1,104 @@
+# Reviewer dispatch prompts
+
+The verbatim briefs each axis subagent receives. Compose with paths and constraints — never pasted history. Every dispatch carries the shared preamble, then its axis brief.
+
+## Shared preamble (every axis)
+
+```
+You are a fresh-context reviewer with no memory of writing this change and no
+stake in it passing. Inputs (read them all): the brief at <issue url or path>,
+the plan comment (marker type=plan), the review package at <package path>, and
+the constraints below, copied verbatim from the brief/plan:
+
+<constraints block>
+
+Write your FULL report to <report path> — complete findings there, each as:
+Finding [N]: <title> — [SEVERITY] (confidence: high|medium|low) path:line,
+issue, why it matters, fix (fenced snippet when code).
+Return only short status: verdict, per-severity counts, and one line per
+finding (title + severity + path:line) — the detail lives in the report file.
+
+You do not dispatch subagents. Do all reading and judging yourself — a reviewer
+you spawn duplicates this review at full cost and its opinion counts for
+nothing in the process. Read full files where the diff needs context (30+
+lines around a hunk) — diff-only review misses invariants.
+
+Report findings or verified absence of findings, never praise. Do not soften a
+finding because the change is large, late, or almost done.
+```
+
+## Spec axis brief
+
+```
+Judge the diff against the CURRENT brief and plan only:
+(a) MISSING — requirements asked for that are absent or partial;
+(b) SCOPE CREEP — behavior in the diff nobody asked for;
+(c) WRONG — requirements that look implemented but don't do what the brief
+    says.
+Quote the exact brief/plan line for every finding. If code and brief diverge
+because the operator changed direction, that is still a finding — the brief
+must be revision-updated before review can pass; say so.
+
+Tests-are-real rubric — flag as [MUST-FIX] any acceptance-relevant test that is:
+- implementation-coupled: mocks internal collaborators, asserts call
+  counts/order, or breaks on refactor without behavior change;
+- tautological: the assertion recomputes the expected value the way the code
+  does, so it can never disagree;
+- horizontal-sliced: bulk tests asserting imagined shapes rather than the
+  behavior the brief names.
+A changed behavior with no covering test at the brief's named seams is MISSING.
+```
+
+## Standards axis brief
+
+```
+Judge the diff against, in priority order:
+1. .vegastack/review-known-patterns.md — its never-flag entries suppress
+   findings UNLESS their "Still flag if:" clause applies;
+2. the project's documented standards (dev.md Project rules, CONTRIBUTING);
+   a documented repo standard always overrides the baseline below;
+3. the smell baseline — each a labeled judgment call ("possible feature
+   envy"), never a hard violation; skip anything tooling already enforces:
+
+- Mysterious name: a name that doesn't reveal what it does or holds → rename.
+- Duplicated code: the same logic shape in more than one hunk/file → extract.
+- Feature envy: a method reaching into another object's data more than its
+  own → move it to the data it envies.
+- Data clumps: the same fields/params traveling together → bundle into a type.
+- Primitive obsession: a primitive standing in for a domain concept → type it.
+- Repeated switches: the same case-cascade on the same type recurring → one
+  shared map or polymorphism.
+- Shotgun surgery: one logical change forcing scattered edits everywhere →
+  gather it into one module.
+- Divergent change: one module edited for several unrelated reasons → split.
+- Speculative generality: abstraction or hooks for needs the brief doesn't
+  have → delete, inline until a real need shows.
+- Message chains: long a.b().c().d() walks the caller depends on → hide the
+  walk behind one method.
+- Middle man: a unit that mostly delegates onward → cut it, call direct.
+- Refused bequest: an implementer ignoring most of what it inherits → compose
+  instead.
+
+Quiet profile: report style only where a documented rule exists. Hard
+violations of documented standards may be [MUST-FIX]; baseline smells are
+[SHOULD-FIX] or [NIT].
+```
+
+## Security axis brief
+
+Compose the security dispatch from [security-axis](security-axis.md): the shared preamble above, then that file's Method steps, finding format (the three extra lines), severity definitions, and standing red lines, quoted into the prompt — the reviewer must receive them in full, not a pointer it cannot follow.
+
+## Re-review brief (scoped, every fix round)
+
+```
+Findings under verification: <the open findings, verbatim>.
+Inputs: the same brief and plan, the implementer's report file (its fix
+reports are the test evidence — do not re-run suites), and the SCOPED package
+at <fix package path> covering only <FIX_BASE>..<HEAD>.
+
+For each finding, in order: ADDRESSED or NOT ADDRESSED, with path:line
+evidence. "Attempted" is not addressed — the specific defect must no longer
+exist. Then: new breakage the fix diff itself introduced (severity + line),
+and out-of-scope observations (non-blocking, one line each). Final line:
+"Fix round: all addressed | findings remain open".
+```

package/skill/dev-review/references/security-axis.md

@@ -0,0 +1,33 @@
+# The security axis
+
+Runs on `risky` issues, and whenever the diff's touch points hit an auth surface, money, user data, or externally-controlled input — the trigger is the surface, not the label alone.
+
+## Method — evidence before severity
+
+1. **Trace the data flow** for every candidate finding: origin → transformations → sink. Is the value attacker-controlled at the point of use? A finding without a traced flow is a hunch, not a finding.
+2. **Check defense in depth before flagging a gap.** A missing check at one layer is not a vulnerability if another layer enforces it on every path — name the enforcing layer instead. Flag it only when no layer holds, or the only holding layer is UX (client-side, middleware-as-convenience).
+3. **Verify library defaults** before "missing configuration" findings — frameworks ship safe defaults more often than training-data memory suggests; check the current docs per `dev-architect`'s verify protocol.
+4. **Assess exploitability**: what does the attacker need (auth level, network position, timing, knowledge)? What mitigating controls exist? Severity follows exploitability, never vibes.
+
+## Finding format — three extra lines
+
+On top of the standard finding shape, every security finding carries:
+
+```
+Data flow: <origin> → <transformations> → <sink>
+Attack prerequisites: <what the attacker needs>
+Mitigating controls: <existing defenses that reduce but don't eliminate>
+```
+
+A finding that can't fill the Data flow line goes to the collapsed low-confidence block, not the main list.
+
+## Severity
+
+- **[CRITICAL]** — exploitable now: auth bypass at the enforcement layer, injection with a traced user-input path, secret/credential exposure, unprotected sensitive mutation. Blocks, above MUST-FIX.
+- **[MUST-FIX]** — a real weakness needing prerequisites an attacker can plausibly meet.
+- **[SHOULD-FIX]** — hardening: rate limits, PII in logs, missing timeouts, defense-in-depth gaps with a holding layer.
+- Never round up to look thorough; judge against the project's Architecture facts — platform-scale concerns are not defects on a small internal tool.
+
+## Standing red lines (summary — `dev-architect` remains their home)
+
+Middleware/proxy is never the authorization boundary; authorization lives server-side per resource. No secret in plaintext anywhere — code, config, logs, events, agent state. Permission checks fail closed, and the deny is still audited.

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

@@ -0,0 +1,3 @@
+# Refresh contract — dev-review
+
+Evergreen: this skill asserts no version pins, numeric vendor limits, or dated claims — its content is review discipline (axes, severities, the bounded loop, dispatch briefs, the smell baseline, cross-agent handoff shape), all versionless. The `codex exec` / `claude -p` invocation forms are deliberately treated as durable CLI surfaces; dev-setup's detection covers their presence per machine. Revisit if a future edit introduces a volatile fact.

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

@@ -1,11 +1,11 @@
 ---
 name: dev-setup
-description: Bootstrap a project for issue-driven agent development — existing repo or brand-new empty directory. Use when asked to "set up the dev workflow", "bootstrap this project for agents", "install the dev workflow here", "set up this new project", or invoked as dev-setup; also run automatically when dev-intake, dev-implement, or dev-ship find no .vegastack/dev.md in the project. Detects the stack and drafts its native release, changelog, and guard conventions; creates the project profile, the AGENTS.md dev section plus CLAUDE.md import, the workflow labels, and the decision register; offers release-guard workflows and the decision-capture hook on the user's yes. Not for architecture advice (that is dev-architect reading the dev.md Architecture section this skill writes), not for authoring skills, not for general CI or app scaffolding.
+description: Bootstrap a project for issue-driven agent development — existing repo or brand-new empty directory. Use when asked to "set up the dev workflow", "bootstrap this project for agents", "install the dev workflow here", "set up this new project", "wire the release guards", "create the workflow labels", "set up the changelog convention", "fill the architecture profile section", to re-run setup after machinery appeared or knobs changed, or invoked as dev-setup; also run automatically when any dev-family skill finds no .vegastack/dev.md in the project. Not for architecture advice (dev-architect reads the section this skill writes), authoring skills (skillify), or general CI and app scaffolding.
 ---
 
 # dev-setup
 
-Re-runnable bootstrap that gives a project everything the dev workflow needs: a profile file holding the knobs and runbooks, a thin AGENTS.md section that both Claude Code and Codex read, the GitHub labels, and the decision register. The other dev skills call this automatically when `.vegastack/dev.md` is missing, then continue with their original request.
+Re-runnable bootstrap that gives a project everything the dev workflow needs: a profile file holding the knobs and runbooks, a thin AGENTS.md section that both Claude Code and Codex read, the GitHub labels, and the decision register. The other dev skills call this automatically when `.vegastack/dev.md` is missing, then continue with their original request. The workflow-wide artifact spec — comment markers, operator identity, revision markers, scope classes, ledger format, `.vegastack/.tmp/` workspace — lives in [conventions](references/conventions.md); dev skills cite it rather than restating it (the v3 rewrites adopt it skill by skill).
 
 Nearest neighbor: `dev-architect` consumes dev.md's `## Architecture` section and gives architecture advice; dev-setup detects the facts and writes the section. There is no separate architecture profile — dev.md is the one file.
 
@@ -24,6 +24,8 @@ Facts are your job; decisions are the user's. Gather these silently and present
 | architecture (app repos) | wrangler files (a `d1_databases` binding with no Postgres driver = the D1-only class), drizzle config, better-auth usage, `@aws-sdk/client-s3`/R2 bindings, pg-boss dependency, `eve`/`ai` packages, Dockerfiles/compose, pubspec.yaml — these draft `## Architecture` |
 | existing files | AGENTS.md, CLAUDE.md, `.vegastack/dev.md`, a legacy `.vegastack/arch.md`, the decision register |
 | existing labels | `gh label list` |
+| native issue types | `gh api orgs/<org>/issue-types` — an `Epic` type routes parents to it; absent endpoint or type → the `epic` label fallback ([conventions](references/conventions.md)) |
+| Codex CLI (cross-agent review) | `command -v codex` — absent → record the gap in dev.md `## Environments` and recommend installing it |
 
 Not a git repo, or no origin remote → this is a **greenfield run, not an error**: follow the greenfield playbook in [stack-playbooks](references/stack-playbooks.md) — interview for the intended stack, offer `git init` and `gh repo create` each on its own yes, and render dev.md from the chosen playbook's conventions with TODO lines where machinery doesn't exist yet. A declined remote skips labels and records the TODO plainly.
 
@@ -35,7 +37,7 @@ Ask with your harness's question tool — AskUserQuestion in Claude Code, `reque
 
 **Round B — the workflow knobs**, recommended default first:
 
-1. Review of finished work: **subagent** · cross-agent (Codex↔Claude) · cross-agent only on `risky` issues
+1. Review of finished work (`review:` knob, mapped by dev-review): **cross-agent-risky** (subagent axes, the other agent on `risky` — recommended where the Codex CLI was detected; otherwise recommend `subagent`) · `subagent` (never cross-agent) · `cross-agent` (always)
 2. Proof for UI work: **playwright screenshots** · none
 3. Gates: **3** (approve → PR → merge as separate user words) · 2 (approve → one "ship it" covers PR and merge) · 1 (direct-to-main for single-operator projects: the ship word merges locally and pushes, no PR — everything else unchanged)
 4. Tests: **required for every change** · required for logic changes only
@@ -62,8 +64,8 @@ Everything else — merge style, branch naming, the stop-and-ask list — takes
 | `.vegastack/dev.md` | render [dev-profile template](assets/dev-profile.md.template) with the answers — the project's single canonical process doc (short directional bullets; Ship/Verify/Environments/Design drafted from the playbook, Architecture drafted from detection, Decisions test included, placeholders deleted, TODO lines where machinery is absent) |
 | `AGENTS.md` | create it, or insert/replace only the block between `<!-- vsk-dev:start -->` and `<!-- vsk-dev:end -->` using the [agents-section template](assets/agents-section.md.template); content outside the markers is the user's and stays untouched |
 | `CLAUDE.md` | ensure its first line is `@AGENTS.md` — Claude Code does not read AGENTS.md natively and needs this import ([harness-facts](references/harness-facts.md)); create the file when absent |
-| labels | `gh label create <name> --color <hex> --description "<text>"` for the names the `labels:` knob records, skipping ones that exist; default names and creation colors: `needs-operator` FBCA04 (waiting on the user) · `ready` 0E8A16 (approved, agent may start) · `working` 1D76DB (claimed by an agent) · `for-operator` 5319E7 (result awaiting user review) · `risky` B60205 (security, money, data, or production) |
-| decision register | create the file the `decisions:` knob names (default `.vegastack/decisions.md`) when missing, with a two-line header stating the format: `- DD-MM-YYYY (github-username) — the decision` (username via `gh api user -q .login`, fallback `git config user.name`); a project with an existing register keeps it and the knob points there |
+| labels | `gh label create <name> --color <hex> --description "<text>"` for the names the `labels:` knob records, skipping ones that exist; default names and creation colors ([conventions](references/conventions.md) holds meanings): state `needs-operator` FBCA04 · `needs-plan` E36209 · `ready` 0E8A16 · `working` 1D76DB · `for-operator` 5319E7; modifiers `risky` B60205 · scope `research` C5DEF5 · `quick-build` 76C7C0 · `full-plan` 2A9D8F · `epic` 24292E (only when the org has no native Epic issue type) |
+| decision register | create the file the `decisions:` knob names (default `.vegastack/decisions.md`) when missing, with a two-line header stating the format: `- DD-MM-YYYY operator (github-username) — the decision` (username via `gh api user -q .login`, fallback `git config user.name`); a project with an existing register keeps it and the knob points there |
 | guard workflows / hook files | only the ones the user said yes to in Round C |
 
 ## Step 4 — Report

package/skill/dev-setup/assets/agents-section.md.template

@@ -1,9 +1,9 @@
 <!-- vsk-dev:start -->
 ## Dev workflow
 
-Read `.vegastack/dev.md` for this project's stack, commands, and workflow knobs.
+Read `.vegastack/dev.md` for this project's stack, commands, and workflow knobs. The workflow's stages are the dev-family skills: dev-setup (bootstrap) · dev-intake (ideas to briefs) · dev-plan (approved briefs to plans) · dev-architect (stack judgment) · dev-implement (dark builds) · dev-debug (reproduce-first fixes) · dev-review (independent review) · dev-ship (gated landing) · dev-status (the operator's board) · dev-chronicle (the project's story).
 
-Work flows through GitHub issues. An issue labeled `ready` carries the user's recorded approval and a complete brief — implement it end to end per the `dev-implement` skill, post the evidence in the issue, and hand it back with `for-operator`. Start only on `ready` issues. The workflow vocabulary is the labels dev.md's `labels:` knob names (defaults: `needs-operator` waiting on the user → `ready` approved → `working` claimed by an agent → `for-operator` result awaiting review; `risky` flags security, money, data, or production) — use them and no others.
+Work flows through GitHub issues. An issue labeled `ready` carries the user's recorded approval and a complete brief — implement it end to end per the `dev-implement` skill, post the evidence in the issue, and hand it back with `for-operator`. Start only on `ready` issues. The workflow vocabulary is the labels dev.md's `labels:` knob names (defaults — state: `needs-operator` waiting on the user → `needs-plan` awaiting the planning stage → `ready` approved → `working` claimed → `for-operator` result awaiting review; modifiers: `risky` for security/money/data/production, scope `research`/`quick-build`/`full-plan`, `epic` on map parents) — use them and no others. Artifact formats (comment markers, ledger, revisions, operator identity) follow the dev-setup skill's `references/conventions.md`.
 
 **Nothing ships without the operator's explicit instruction** — no push to the default branch, merge, tag, publish, or deploy on green checks, schedules, or standing approvals alone. The `gates` knob in dev.md changes how many of those actions one instruction covers, never whether an instruction is needed. Behavior changes carry their changelog entry per dev.md's `changelog:` knob before hand-back; after merge, the `## Ship` runbook in dev.md says what happens next and which steps need the operator's word.
 

package/skill/dev-setup/assets/dev-profile.md.template

@@ -9,17 +9,18 @@ authority: {{ordered — e.g. "CONTRIBUTING.md → this file → skill defaults"
 
 ## Knobs
 
-review: subagent            # subagent | cross-agent | cross-agent-risky
+review: cross-agent-risky   # subagent (never cross-agent) | cross-agent-risky (other agent on risky) | cross-agent (always) — dev-review maps these
 ui-evidence: playwright     # playwright | none
 evidence-repo: {{owner}}/dev-review-evidence   # shared across projects; this project's folder = repo name; delete the line when ui-evidence is none
 gates: 3                    # 3 = approve/PR/merge · 2 = approve + one "ship it" · 1 = direct-to-main, ship word merges locally and pushes, no PR
 tests: required             # required | logic-only
 merge: squash
 branch: <type>/<issue>-<slug>   # type: feat | fix | docs | chore | refactor — the only place this list lives
-labels: needs-operator ready working for-operator risky
+labels: needs-operator needs-plan ready working for-operator risky research quick-build full-plan epic   # epic label marks map parents only where the org has no native Epic issue type
 changelog: {{changesets | keep-a-changelog | pubspec+changelog | none (reason)}}
 decisions: .vegastack/decisions.md
 release: on-request         # per-merge = Ship runbook runs as part of shipping · on-request = only when the operator says "release"
+chronicle: on               # on = dev-implement writes a .vegastack/chronicle.md story entry per behavior-changing branch · off
 
 ## Ship — what happens after merge, in order
 
@@ -66,7 +67,7 @@ mobile: {{no | flutter (separate repo)}}
 
 Record a decision only when it is directional — it steers work beyond this issue: a real alternative was rejected; it constrains work not yet written; and no dev.md line, lint rule, or guard can enforce it instead (if one can, write the rule). Feature requests, one-off fixes, and routine implementation choices never qualify. Every entry needs the user's explicit yes. One line in the register (`decisions:` knob), append-only, no other metadata:
 
-- DD-MM-YYYY (github-username) — the decision
+- DD-MM-YYYY operator (github-username) — the decision
 
 ## Stop and ask