@vegastack/skills 0.9.1 → 0.11.0

package/skill/dev-implement/references/ledger-and-resume.md

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

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

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

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

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

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

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

package/skill/dev-intake/SKILL.md

@@ -1,62 +1,68 @@
 ---
 name: dev-intake
-description: Turn ideas, brainstorms, feature requests, or SOW documents into GitHub issues an agent can implement without further questions. Use when asked to "turn this into issues", "create tasks from this SOW", "write up an issue for" a feature or bug, "plan this as issues", "slice this epic", or when the user gives approval on a drafted issue and it needs recording. Produces complete inline build briefs with labels, milestones, and blocker links. Not for implementing issues (dev-implement), creating PRs or merging (dev-ship), or project bootstrap (dev-setup).
+description: Turn ideas, brainstorms, feature requests, bug reports, or SOW documents into GitHub issues an agent can act on without further questions. Use when asked to "turn this into issues", "create tasks from this SOW", "write up an issue for" a feature or bug, "users report X — make an issue", "plan this as issues", "slice this epic", or when the user gives approval on a drafted issue and it needs recording. Not for writing the implementation plan of an approved issue (dev-plan), implementing issues (dev-implement), creating PRs or merging (dev-ship), or project bootstrap (dev-setup).
 ---
 
 # dev-intake
 
-Requirements come in as the user's brainstorm, feature thought, or SOW; issues go out complete enough that a fresh agent needs nothing but the URL. Every question gets asked **here** — once implementation starts, dark mode means no questions, so an under-specified issue becomes either an interruption or a guess. This skill exists to make both impossible.
+Requirements come in as the operator's brainstorm, feature thought, bug report, or SOW; issues go out complete enough that a fresh agent needs nothing but the URL. Every question gets asked **here** — once implementation starts, dark mode means no questions, so an under-specified issue becomes either an interruption or a guess. Artifact formats (markers, operator identity, labels, revisions) follow the `dev-setup` skill's `references/conventions.md`.
 
-Nearest neighbor: `dev-implement` consumes what this produces — intake writes and gets approval, implement builds. If `.vegastack/dev.md` is missing, run `dev-setup` first, then continue here.
+Nearest neighbors: `dev-plan` owns the how once a brief is approved — intake owns the what/why and the approval mechanics; `dev-implement` builds. If `.vegastack/dev.md` is missing → run `dev-setup` first, then continue.
 
 ## Ground before you ask
 
-Finding facts is your job, never the user's — and a brief built on unverified facts is a confident mistake waiting for dark mode. The source can be one sentence in chat; thinner material just means the grounding and interview carry more weight. Before the first question:
+Finding facts is your job, never the operator's — a brief built on unverified facts is a confident mistake waiting for dark mode. Before the first question:
 
-- **Read the touched code.** Open the actual paths the feature would change: current behavior, existing patterns to reuse, where the new work plugs in. The brief cites these real paths later — a brief naming no files is a sign this step was skipped.
-- **Verify dependencies.** Any library, service, or API capability the approach leans on gets checked against current official docs (docs tools or web search), noted with the date. Consult `architect`'s pinned facts for stack questions before re-researching; re-verify a pinned fact older than 60 days; skip lookups for long-stable basics — judgment, not ritual.
-- **Cross-check the request** against product docs and current behavior. A contradiction is pushback, never a silent resolution: "you asked for X; the code/docs currently do Y — which wins?" Push back on cost the same way: when a simpler version covers most of the need, name it.
-- **Triage every unknown** into exactly three bins: *findable* → find it now, yourself; *only-the-user-knows* → ask, with a recommendation; *only-running-code-can-tell* → flag it as a spike that becomes the issue's first step. Guessing is not a bin.
+- **Read the touched code.** Open the actual paths the work would change: current behavior, patterns to reuse, where it plugs in. The brief cites these real paths later — a brief naming no files is a sign this step was skipped.
+- **Verify dependencies.** Any library, service, or API capability the approach leans on gets checked against current official docs, noted with the date. Stack, schema, auth, and infra choices route through `dev-architect` — its verify protocol governs the check.
+- **Cross-check the request** against product docs and current behavior. A contradiction is pushback, never a silent resolution: "you asked for X; the code currently does Y — which wins?" Push back on cost the same way: when a simpler version covers most of the need, name it.
+- **Triage every unknown** into exactly three bins: *findable* → find it now, yourself; *only-the-operator-knows* → ask, with a recommendation; *only-running-code-can-tell* → a `research` issue or the issue's first spike step. Guessing is not a bin.
 
-## The interview
+## Scope the work — say it out loud
+
+Every issue gets exactly one scope call, announced with its reason, applied as a label, and recorded in the brief's `**Scope:**` line so the reasoning survives the conversation. The operator can override it:
 
-Ask in rounds using your harness's question tool (AskUserQuestion in Claude Code, `request_user_input` in Codex where the mode allows; no tool available → draft with recommended answers marked `TODO confirm` and say so). Each round covers the current frontier: every open decision that does not depend on another answer.
+- **`research`** — a question to answer, not code to keep. The brief is the question plus what "answered" looks like.
+- **`quick-build`** — the objective test (conventions' wording): *a small change AND the flow being changed already exists in the repo to read*. Missing either half — no existing flow, or not actually small — means it is not quick-build; familiarity with the kind of app doesn't count.
+- **`full-plan`** — big or new ground: a new subsystem, a restructuring, a brand-new flow.
 
-- Number the questions. Give each a **recommended answer with a one-line reason**, so the user can reply "all recommended" or override by number.
-- Stop asking when the bar is met: *a fresh agent could implement each issue without asking anything.* Test every brief against that sentence before calling it done.
-- Do not re-ask what the material or an earlier round already settled.
+In doubt between two classes, take the heavier one. Re-classification after this point belongs to `dev-plan`'s one-way ratchet — never silently downgrade.
 
-## The angles, in order
+## The interview
 
-Work the design the way a joint product-and-tech review would; each round's answers feed the next:
+Ask in rounds with your harness's question tool (no tool available → documented defaults marked `TODO confirm`, and say so). Each round covers the current frontier: every open decision that doesn't depend on another answer. Number the questions; give each a **recommended answer with a one-line reason** so the operator can reply "all recommended"; never re-ask what the material or an earlier round already settled. A vague or self-contradicting answer gets pushback with concrete options — simple words, a mermaid or ASCII sketch when a picture beats prose — never silent absorption. Stop when the bar is met: *a fresh agent could act on each issue without asking anything.*
 
-1. **Product** — who this is for, the observable outcome, what's in and out of scope now, how it splits into slices or phases, priority.
-2. **Behavior** — primary and alternate flows, rules, permissions, validations, edge and failure cases; for UI, the states, components, and copy.
-3. **Technical** — only the choices that are genuinely the user's: approach trade-offs, data and interface implications, integrations, migration; recommend one and say why. When the project versions releases (dev.md `changelog:` knob), settle the intended version impact (patch/minor/major) here — the brief records it and dev-implement's changelog entry starts from it. Routine implementation stays the implementer's.
-4. **Quality and risk** — what proves it works (test cases, acceptance), what earns the `risky` label, what should stop a dark run beyond the standing stop-list.
+The angles, in order — product (who, observable outcome, in/out of scope, slices, priority) → behavior (flows, rules, permissions, edge and failure cases; UI states and copy) → technical (only choices genuinely the operator's, each with a recommendation, checked against `dev-architect`; settle the version impact where the project versions releases) → quality and risk (what proves it works, what earns `risky`, what stops a dark run). Deep approach trade-offs beyond the operator's choices belong to `dev-plan`, not this interview.
 
-These are the brief template's sections in interview form — a question exists only where reading the material, the codebase, and sensible defaults cannot fill a section.
+**Bug variant** (`fix:` issues): reproduction steps — or the artifacts needed to obtain them (logs, HAR, recording) — are a required brief section, and the brief names `dev-debug` as the implement path. A bug that can't be reproduced yet becomes a `research` issue first.
 
-## Slicing
+## Slicing and hierarchy
 
-- One issue = one outcome that fits one agent session, sliced vertically (a thin working path through the stack beats a layer at a time).
-- Blockers use native issue dependencies (blocked-by); phases use milestones; hierarchy uses parent/sub-issues. Labels never duplicate these.
-- A large feature gets a parent issue holding the map and child issues holding the work. **Only child issues ever get `ready`** — a parent brief is context, not an executable task, and an agent must never pick it up whole.
-- Deliberately deferred work ("someday, not now") lives in the parent's out-of-scope section, not as its own issue — icebox issues clutter the tracker. Create a tracking issue for it only when the user asks.
+- One issue = one outcome that fits one agent session, sliced vertically. Blockers use native dependencies; phases use milestones; parents use native sub-issues.
+- Deliberately deferred work ("someday, not now") lives in the parent's out-of-scope section, never as its own issue — icebox issues clutter the tracker; a tracking issue exists only on the operator's ask.
+- **Epics:** a multi-deliverable feature gets a parent whose body is a map, never a task — `Destination` (one or two lines every session orients to) · `Decisions so far` (one-line gists linking closed children) · `Not clear yet` (in-scope questions you cannot yet state precisely — the test is whether the question can be phrased sharply now, not answered now; don't pre-slice fog) · `Out of scope` (the tempting adjacent work, named). A mermaid overview when it helps. Each child is classified independently. **Only children ever get `ready`.**
+- Titles carry the type prefix (dev.md `branch:` type list + `research:`) and the native issue type where the org has them — issue, branch, and PR always agree.
 
 ## The brief
 
-Every issue body follows [brief-template](references/brief-template.md): Outcome · Out of scope · Rules and edge cases · UI states (when there is UI) · Approach and touch points · Tests and acceptance · Risks and stop conditions · Assumptions. Write the sections that apply and delete the ones that don't — an empty "N/A" section is noise, not diligence. Details live inline in the issue; links to docs are supporting material, never a substitute for the brief. Evidence over confidence: touch points name real paths, dependency claims carry their check date, and anything material the grounding could not verify goes in **Assumptions — confirm or correct**, never asserted as fact.
+The issue body follows [brief-template](references/brief-template.md), marker line included. Inline over linked; concrete over abstract; evidence over confidence — touch points name real paths, dependency claims carry their check date, and anything unverifiable goes to **Assumptions — confirm or correct**, never asserted. Tests-and-acceptance names the **seams** — the public boundaries tests will live at — because dark mode can't ask later.
+
+**Quick-build issues get their plan now:** after the brief has consensus, invoke `dev-plan`'s inline mode in this same conversation and post brief (description) + plan (comment) together — the operator's single approval covers both.
+
+Before posting any brief, run `node <path-to-this-skill>/scripts/brief-lint.mjs --file <draft> --scope <class> --json` (add `--fix` for fix:-type briefs — it requires the Reproduction section) — structure gaps block (exit 2), quality smells only warn; fix blocks before the operator ever sees the draft. Inline plans additionally pass `dev-plan`'s plan-lint.
 
 ## Labels and approval
 
-- A new issue starts at `needs-operator`. Add `risky` when it touches security, money, user data, or production. (Label names come from dev.md's `labels:` knob; the defaults are used throughout this skill family's prose.)
-- Approval is only the user's explicit words — "approved", "go ahead", clearly tied to this issue, in chat or on the issue. Labels, silence, or the passage of time never create approval.
-- Record it once: comment `Approved by <user> on <date>: "<their words>"`, then swap `needs-operator` → `ready`. That comment is what dev-implement's preflight looks for.
-- An issue with an unconfirmed entry in its Assumptions section cannot go `ready` — the recorded approval covers the ledger the user saw, so resolve every entry (confirmed, corrected, or moved to a spike) first.
-- An issue that settles a directional decision — one that passes the Decisions test in `.vegastack/dev.md` — records it as one comment starting `Decision:`, in the register's line format; dev-ship appends it at merge after naming it in the merge confirmation. A decision that stands regardless of the issue's fate may go into the register immediately on the user's explicit yes in the same conversation — note "recorded" on the comment so dev-ship doesn't append it twice. Choices that fail the test are brief content, never register lines.
-- The user edits or corrects a draft → apply, and summarize what changed since they last read it.
+- A new issue starts at `needs-operator`, plus its scope label; add `risky` when it touches security, money, user data, or production. (Names come from dev.md's `labels:` knob.)
+- Approval is only the operator's explicit words, clearly tied to the issue. Labels, silence, or time never create approval.
+- Record it as one approval marker comment per conventions — `scope=brief`, or `scope=brief+plan` when the inline plan was posted with it — quoting the operator's words in the operator (username) format. That comment is what preflight verifies.
+- Then flip the state: `research` and `quick-build` → `ready`; `full-plan` → `needs-plan` (dev-plan takes it from there).
+- An issue with an unresolved Assumptions entry cannot leave `needs-operator` — resolve every entry (confirmed, corrected, or moved to a spike) first; the section is deleted once resolved.
+- A directional decision this work settles — one passing the Decisions test in dev.md — is proposed as one register line on the operator's yes; `dev-ship` records at merge.
+- The operator edits a draft → apply, and summarize what changed since they last read it.
 
 ## After approval
 
-An approved issue that later needs a material change flips back to `needs-operator` with one comment naming what changed; the new approval is recorded the same way. Small wording fixes that change no behavior don't reopen anything.
+An approved issue that later needs a material change flips back to `needs-operator` with one comment naming what changed; the new approval is recorded the same way, and the brief's revision marker bumps. Small wording fixes that change no behavior don't reopen anything.
+
+End every run with the plain-language summary: what was created or changed, the scope calls made and why, and exactly what awaits the operator's word.

package/skill/dev-intake/references/brief-template.md

@@ -1,13 +1,21 @@
 # Issue brief template
 
-The issue body a `ready` issue must have. Write the sections that apply, delete the rest. The test for every section: would a fresh agent have to guess or ask without it?
+The issue body a workable issue must have. Write the sections that apply, delete the rest. The test for every section: would a fresh agent have to guess or ask without it?
 
 ```markdown
+<!-- vsk:v1 type=brief rev=1 scope=research|quick-build|full-plan -->
+**Scope:** research | quick-build | full-plan — the announced reason for the call, one line.
+
 ## Outcome
 
 What exists when this is done, in observable terms — what the user can do, what the
 system produces. One paragraph.
 
+Research issues replace Outcome and the build sections with two headings brief-lint
+expects verbatim in spirit: `## The question` (what this issue resolves) and
+`## What answered looks like` (the evidence that closes it). Risks/stop conditions
+and Assumptions still apply.
+
 ## Out of scope
 
 The nearby things this issue deliberately does NOT do. This is what stops scope creep
@@ -18,6 +26,12 @@ in dark mode — name the tempting adjacent work.
 The behavior that isn't obvious: validations, permissions, limits, empty/error/concurrent
 cases, what happens on failure. Bullet list, one behavior per line.
 
+## Reproduction            <!-- fix: issues only -->
+
+The exact steps (or attached artifacts — logs, HAR, recording) that demonstrate the
+bug today, and the observed vs expected behavior. A bug without this is a `research`
+issue, not a fix. The implement path is dev-debug.
+
 ## UI states            <!-- only when there is UI -->
 
 Loading, empty, error, success, disabled. Which design-system components. Copy for
@@ -26,19 +40,18 @@ user-facing text. Responsive and keyboard behavior when it matters.
 ## Approach and touch points
 
 The chosen technical approach in a few lines: which parts of the codebase change,
-new/changed interfaces or schemas, data migrations. Routine choices (file names,
-helpers, fixtures) stay the implementer's — don't specify them.
-Name the docs and changelog surfaces this change must update (README section, user
-docs, the changelog entry's gist).
+new/changed interfaces or schemas, data migrations. Routine choices stay the
+implementer's — don't specify them. Name the docs and changelog surfaces this change
+must update. Task-level detail belongs to the plan (dev-plan), not here.
 **Version impact:** patch | minor | major, one-line reason — only when the project
-versions releases (dev.md `changelog:` knob); dev-implement's changelog entry or
-changeset starts from this line.
+versions releases (dev.md `changelog:` knob).
 
 ## Tests and acceptance
 
 What proves it works: the cases tests must cover (success, boundary, failure,
-authorization where relevant) and the commands to run. Acceptance = the Outcome plus
-these passing.
+authorization where relevant), the commands to run, and the **seams** — the public
+boundaries tests live at (dark mode can't negotiate seams later; they're settled
+here). Acceptance = the Outcome plus these passing.
 
 ## Risks and stop conditions
 
@@ -48,9 +61,10 @@ through — beyond the standing stop-list in .vegastack/dev.md.
 ## Assumptions — confirm or correct
 
 Anything material the grounding investigation could not verify, one per line, each
-awaiting the user's confirm/correct. The issue cannot go `ready` while one is
-unconfirmed. Verified facts never appear here — they live in their section with
-their evidence. Delete the section once every entry is resolved.
+awaiting the operator's confirm/correct. The issue cannot leave needs-operator while
+one is unconfirmed. Verified facts never appear here — they live in their section
+with their evidence. Delete the whole section once every entry is resolved (its
+presence alone blocks preflight).
 ```
 
 ## Writing rules
@@ -59,4 +73,5 @@ their evidence. Delete the section once every entry is resolved.
 - Concrete over abstract: "rejects amounts over 10,000 with error E402" beats "validates input".
 - Evidence over confidence: touch points name real file paths; a dependency capability claim carries the doc check and its date; what couldn't be verified goes to Assumptions, never stated as fact.
 - The brief binds the agent, so ambiguity is a bug in the brief — if two readings exist, the interview wasn't done.
+- Post-approval edits follow the revision-marker rule in dev-setup's `references/conventions.md` (heading `(v2)`, marker `rev=2`, a `Revisions:` line).
 - A `Decision:` comment exists only for a choice that passes the Decisions test in `.vegastack/dev.md` — feature requests and implementation details never qualify; they are brief content, not register lines.

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