@vegastack/vegafactory 0.19.0

package/skill/dev-plan/scripts/questions.mjs

@@ -0,0 +1,381 @@
+#!/usr/bin/env node
+// The ask round: render questions into a `questions` comment, parse whatever a
+// teammate replies, re-ask only what is still open, and decide which route the
+// round takes at all. Text in, text out — this script makes no `gh` call, no
+// network call, and writes no file, so it needs no credentials and no dry run.
+//
+// The route, the comment shape and the reply grammar are documented once in
+// dev-setup's references/ask-route.md; this file is the method behind them.
+//
+//   node questions.mjs render  --spec <file.json> [--rev <n>] [--json]
+//   node questions.mjs parse   --comment <file> (--spec <file.json> | --round <file.md>) [--json]
+//   node questions.mjs re-ask  (--spec <file.json> | --round <file.md>) --comment <file> --rev <n> [--json]
+//   node questions.mjs route   --tool <name|none> --asker <login> --operator <login> [--json]
+//
+// Exit codes: 0 pass · 1 answers still open or malformed (nothing to re-ask, for
+// `re-ask`) · 2 refusal or usage error.
+import { lstatSync, readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+// The comment marker, written once: the renderer emits it and the round reader
+// finds it by the same string, so the two can never drift apart.
+const MARKER_OPEN = '<!-- vsk:v1 type=questions rev='
+const MARKER_CLOSE = ' -->'
+
+// Options run a through h: eight is already more than a person will weigh, and a
+// bounded set is what makes the reply grammar a single character.
+const LETTERS = ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h']
+
+// Every path this script reads goes through here. A symlink is refused rather
+// than followed: the caller hands it a path from an issue comment's neighbourhood,
+// and a guard that resolves links reads whatever the link points at.
+export function readTextFile(path) {
+  const stats = lstatSync(path)
+  if (stats.isSymbolicLink()) throw new Error('refusing to read a symlink: ' + path)
+  if (!stats.isFile()) throw new Error('not a regular file: ' + path)
+  return readFileSync(path, 'utf8')
+}
+
+// The display number of a question: its `n` when the round is a re-ask carrying
+// the original numbering, otherwise its position.
+function numberOf(question, index) {
+  return typeof question.n === 'number' ? question.n : index + 1
+}
+
+// Text that would break out of the round it is rendered into. A round can be read
+// back out of a comment anyone may have written, so this is checked on the way in
+// as well as on the way out — rendered text is never allowed to carry a marker or
+// close the block it sits in.
+const UNSAFE_TEXT = ['<!--', '-->', '<questions>', '</questions>']
+
+function checkText(label, value) {
+  if (typeof value !== 'string' || value.trim() === '') throw new Error(label + ' is empty')
+  for (const fragment of UNSAFE_TEXT) {
+    if (value.includes(fragment)) throw new Error(label + ' carries markup that would break the round: ' + fragment)
+  }
+}
+
+// A spec that cannot render is a bug in the caller, not a question for the user,
+// so every check throws with the question's own number in the message.
+export function checkSpec(spec) {
+  const questions = spec && Array.isArray(spec.questions) ? spec.questions : null
+  if (!questions) throw new Error('spec has no questions array')
+  if (questions.length === 0) throw new Error('a round needs at least one question')
+  questions.forEach((question, index) => {
+    const n = numberOf(question, index)
+    const label = 'question ' + n
+    checkText(label, question.text)
+    const options = Array.isArray(question.options) ? question.options : []
+    if (options.length < 2) throw new Error(label + ' has fewer than two options')
+    const seen = new Set()
+    for (const option of options) {
+      checkText(label, option.text)
+      if (!LETTERS.includes(option.letter)) {
+        throw new Error(label + ' uses the letter "' + option.letter + '" — options run a through h')
+      }
+      if (seen.has(option.letter)) throw new Error(label + ' repeats the letter "' + option.letter + '"')
+      seen.add(option.letter)
+      if (option.recommended) {
+        if (typeof option.reason !== 'string' || option.reason.trim() === '') {
+          throw new Error(label + ' recommends "' + option.letter + '" without a reason')
+        }
+        checkText(label, option.reason)
+      }
+    }
+    const recommended = options.filter((option) => option.recommended)
+    if (recommended.length === 0) throw new Error(label + ' has no recommended option')
+    if (recommended.length > 1) throw new Error(label + ' has ' + recommended.length + ' recommended options')
+  })
+  return questions
+}
+
+// The rendered comment. The `<questions>` wrapper is what lets the parser and the
+// model both find the round inside a comment that may carry prose around it.
+export function renderQuestions(spec, options) {
+  const rev = options && options.rev ? Number(options.rev) : 1
+  if (!Number.isInteger(rev) || rev < 1) throw new Error('rev must be a positive integer')
+  const questions = checkSpec(spec)
+  const lines = []
+  lines.push(MARKER_OPEN + rev + MARKER_CLOSE)
+  lines.push('## Questions (v' + rev + ')')
+  lines.push('')
+  lines.push('<questions>')
+  questions.forEach((question, index) => {
+    if (index > 0) lines.push('')
+    lines.push('**Q' + numberOf(question, index) + '.** ' + question.text)
+    for (const option of question.options) {
+      let line = '- ' + option.letter + ') ' + option.text
+      if (option.recommended) line += ' (recommended — ' + option.reason + ')'
+      lines.push(line)
+    }
+  })
+  // The example in the reply line is the round's own first question and its first
+  // letter, so a re-ask that starts at Q3 tells the reader to write `3: a`.
+  const first = questions[0]
+  const example = numberOf(first, 0) + ': ' + first.options[0].letter
+  lines.push('')
+  lines.push('Reply with `' + example + '` per question, or `all recommended`.')
+  lines.push('</questions>')
+  lines.push('')
+  return lines.join('\n')
+}
+
+// An answer line: an optional bullet, the question number, `:` or `.`, the option
+// word, and optional trailing prose — only after a dash. The dash is what makes
+// `1: a — too slow` a note and `1: a is too slow, go with b` a sentence: without
+// it the letter is not an answer, and a numbered line that is not an answer is
+// reported rather than read as the letter it happens to open with. Lines with no
+// number are prose — a reply is a comment written by a person, not a form.
+const ANSWER_LINE = /^\s*(?:[-*]\s+)?(\d+)\s*[:.]\s*([A-Za-z]+)[.!]?\s*(?:(?:—|–|--|-)\s*(.*))?$/
+const NUMBERED_LINE = /^\s*(?:[-*]\s+)?(\d+)\s*[:.]\s*(\S.*)$/
+const ALL_RECOMMENDED = /^\s*(?:[-*]\s+)?all\s+recommended\s*[.!]?\s*$/i
+
+// Reads a reply comment against the round it answers. Never throws on the reply
+// itself: an unusable reply comes back as `malformed`, which is what a re-ask is
+// built from. It throws only on a spec that could not have been rendered.
+export function parseAnswers(replyText, spec) {
+  const questions = checkSpec(spec)
+  const numbers = questions.map((question, index) => numberOf(question, index))
+  const answers = {}
+  const malformed = []
+  let sawAnswerLine = false
+  let allRecommended = false
+
+  for (const line of String(replyText).split('\n')) {
+    if (ALL_RECOMMENDED.test(line)) {
+      allRecommended = true
+      sawAnswerLine = true
+      continue
+    }
+    const match = ANSWER_LINE.exec(line)
+    if (!match) {
+      const numbered = NUMBERED_LINE.exec(line)
+      if (numbered) {
+        sawAnswerLine = true
+        malformed.push('question ' + Number(numbered[1]) + ': "' + numbered[2].trim() + '" is not a bare answer — write "' + Number(numbered[1]) + ': a" or "' + Number(numbered[1]) + ': a — <note>"')
+      }
+      continue
+    }
+    sawAnswerLine = true
+    const n = Number(match[1])
+    const token = match[2].toLowerCase()
+    const trailing = (match[3] || '').trim()
+    const position = numbers.indexOf(n)
+    if (position === -1) {
+      malformed.push('question ' + n + ' is not in this round')
+      continue
+    }
+    if (Object.prototype.hasOwnProperty.call(answers, n)) {
+      malformed.push('question ' + n + ' answered twice — the first answer stands')
+      continue
+    }
+    const known = questions[position].options.some((option) => option.letter === token)
+    if (token !== 'other' && !known) {
+      malformed.push('question ' + n + ': "' + token + '" is not an option')
+      continue
+    }
+    answers[n] = { option: token, text: trailing === '' ? null : trailing }
+  }
+
+  if (allRecommended) {
+    questions.forEach((question, index) => {
+      const n = numbers[index]
+      if (Object.prototype.hasOwnProperty.call(answers, n)) return
+      const recommended = question.options.find((option) => option.recommended)
+      answers[n] = { option: recommended.letter, text: null }
+    })
+  }
+
+  const missing = numbers.filter((n) => !Object.prototype.hasOwnProperty.call(answers, n))
+  if (!sawAnswerLine) {
+    malformed.push('no answer line found — expected "<number>: <letter>" per question, or "all recommended"')
+  }
+  return { answers, missing, malformed }
+}
+
+// The next round: the questions a reply left open, each carrying the number it
+// had in the original round, so a re-ask re-uses `**Q3.**` rather than renumbering
+// and inviting an answer to a question nobody asked twice.
+export function openQuestions(spec, parsed) {
+  const questions = checkSpec(spec)
+  const numbers = questions.map((question, index) => numberOf(question, index))
+  const open = new Set(parsed.missing)
+  // A malformed entry names its question; reopen it unless an earlier line in the
+  // same reply already answered it (a repeat is malformed, but the first stands).
+  for (const problem of parsed.malformed) {
+    const named = /^question (\d+)\b/.exec(problem)
+    if (!named) continue
+    const n = Number(named[1])
+    if (!numbers.includes(n)) continue
+    if (Object.prototype.hasOwnProperty.call(parsed.answers, n)) continue
+    open.add(n)
+  }
+  const kept = questions
+    .map((question, index) => ({ ...question, n: numbers[index] }))
+    .filter((question) => open.has(question.n))
+  return { ...spec, questions: kept }
+}
+
+// The inverse of `renderQuestions`: a posted `questions` comment read back into
+// the spec it was rendered from. This is what makes the wrapper earn its place —
+// the run that reads the reply is a different, later session with no round.json
+// on disk, so the comment itself has to be the record of what was asked.
+const ROUND_QUESTION = /^\*\*Q(\d+)\.\*\*\s+(.+)$/
+const ROUND_OPTION = /^-\s+([a-z])\)\s+(.+)$/
+const ROUND_RECOMMENDED = /^(.*?)\s+\(recommended — (.+)\)$/
+
+export function parseRound(commentText) {
+  const text = String(commentText)
+  const opened = text.indexOf('<questions>')
+  const closed = text.indexOf('</questions>', opened + 1)
+  if (opened === -1 || closed === -1) throw new Error('no <questions> block in this comment')
+  const markerAt = text.indexOf(MARKER_OPEN)
+  const revDigits = markerAt === -1 ? null : /^(\d+)/.exec(text.slice(markerAt + MARKER_OPEN.length))
+  const rev = revDigits ? Number(revDigits[1]) : 1
+  const questions = []
+  for (const line of text.slice(opened + '<questions>'.length, closed).split('\n')) {
+    const asked = ROUND_QUESTION.exec(line)
+    if (asked) {
+      questions.push({ n: Number(asked[1]), text: asked[2].trim(), options: [] })
+      continue
+    }
+    const offered = ROUND_OPTION.exec(line)
+    if (!offered) continue
+    if (questions.length === 0) throw new Error('an option appears before any question')
+    const recommended = ROUND_RECOMMENDED.exec(offered[2].trim())
+    if (recommended) {
+      questions[questions.length - 1].options.push({
+        letter: offered[1],
+        text: recommended[1].trim(),
+        recommended: true,
+        reason: recommended[2].trim(),
+      })
+    } else {
+      questions[questions.length - 1].options.push({ letter: offered[1], text: offered[2].trim() })
+    }
+  }
+  const round = { rev, questions }
+  checkSpec(round)
+  return round
+}
+
+// Which surface the round goes to, in one precedence a caller cannot reorder:
+// the environment the dispatcher sets, then whether this harness and run have a
+// question tool at all, then whether the person being asked is the person who
+// owns the issue. Anything unresolved routes to the issue, because a round in a
+// comment is always readable and a round put to the wrong person is not.
+export function decideRoute(input) {
+  const env = (input && input.env) || {}
+  const forced = typeof env.VSK_ASK_ROUTE === 'string' ? env.VSK_ASK_ROUTE.trim() : ''
+  if (forced !== '') {
+    if (forced !== 'issue' && forced !== 'tool') throw new Error('VSK_ASK_ROUTE must be issue or tool, not "' + forced + '"')
+    return { route: forced, reason: 'VSK_ASK_ROUTE=' + forced }
+  }
+  const tool = input && typeof input.tool === 'string' ? input.tool.trim() : ''
+  if (tool === '' || tool === 'none') return { route: 'issue', reason: 'no question tool in this harness or run' }
+  const asker = input && typeof input.asker === 'string' ? input.asker.trim() : ''
+  const operator = input && typeof input.operator === 'string' ? input.operator.trim() : ''
+  if (asker === '' || operator === '') return { route: 'issue', reason: 'the asker or the issue operator is unknown' }
+  if (asker !== operator) return { route: 'issue', reason: 'asker ' + asker + ' is not the issue operator ' + operator }
+  return { route: 'tool', reason: 'tool ' + tool + ' is available and the asker is the issue operator' }
+}
+
+// ---------------------------------------------------------------------------
+// CLI
+// ---------------------------------------------------------------------------
+
+const USAGE = [
+  'usage:',
+  '  questions.mjs render --spec <file.json> [--rev <n>] [--json]',
+  '  questions.mjs parse  --comment <file> (--spec <file.json> | --round <file.md>) [--json]',
+  '  questions.mjs re-ask (--spec <file.json> | --round <file.md>) --comment <file> --rev <n> [--json]',
+  '  questions.mjs route  --tool <name|none> --asker <login> --operator <login> [--json]',
+].join('\n')
+
+// A caller supplies the round it is answering either as the JSON it rendered from
+// (--spec) or as the posted comment itself (--round), which is what a later,
+// fresh session actually has.
+function readSpec(path) {
+  return JSON.parse(readTextFile(path))
+}
+
+function loadRound(specPath, roundPath) {
+  if (specPath && roundPath) throw new Error('pass --spec or --round, not both')
+  if (specPath) return readSpec(specPath)
+  return parseRound(readTextFile(roundPath))
+}
+
+function report(json, payload, exitCode, humanLines) {
+  if (json) console.log(JSON.stringify(payload, null, 2))
+  else for (const line of humanLines) console.log(line)
+  process.exit(exitCode)
+}
+
+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] }
+  const command = argv[0]
+  const refuse = (reason) => report(json, { command: command || null, ok: false, error: reason }, 2, ['questions: ' + reason])
+
+  if (command === 'render') {
+    const specPath = get('--spec')
+    if (!specPath) refuse(USAGE)
+    try {
+      const rev = get('--rev') ? Number(get('--rev')) : 1
+      const markdown = renderQuestions(readSpec(specPath), { rev })
+      report(json, { command: 'render', ok: true, rev, markdown }, 0, [markdown])
+    } catch (error) {
+      refuse(error.message)
+    }
+  } else if (command === 'parse') {
+    const specPath = get('--spec')
+    const roundPath = get('--round')
+    const commentPath = get('--comment')
+    if ((!specPath && !roundPath) || !commentPath) refuse(USAGE)
+    try {
+      const parsed = parseAnswers(readTextFile(commentPath), loadRound(specPath, roundPath))
+      const open = parsed.missing.length > 0 || parsed.malformed.length > 0
+      const human = ['questions: ' + Object.keys(parsed.answers).length + ' answered']
+      if (parsed.missing.length) human.push('  open: ' + parsed.missing.join(', '))
+      for (const problem of parsed.malformed) human.push('  malformed: ' + problem)
+      report(json, { command: 'parse', ok: !open, ...parsed }, open ? 1 : 0, human)
+    } catch (error) {
+      refuse(error.message)
+    }
+  } else if (command === 're-ask') {
+    const specPath = get('--spec')
+    const roundPath = get('--round')
+    const commentPath = get('--comment')
+    const revRaw = get('--rev')
+    if ((!specPath && !roundPath) || !commentPath || !revRaw) refuse(USAGE)
+    try {
+      const spec = loadRound(specPath, roundPath)
+      const parsed = parseAnswers(readTextFile(commentPath), spec)
+      const open = openQuestions(spec, parsed)
+      if (open.questions.length === 0) {
+        report(json, { command: 're-ask', ok: false, open: [], reason: 'nothing is open — every question is answered' }, 1, ['questions: nothing is open'])
+      }
+      const rev = Number(revRaw)
+      const markdown = renderQuestions(open, { rev })
+      report(json, { command: 're-ask', ok: true, rev, open: open.questions.map((q) => q.n), markdown }, 0, [markdown])
+    } catch (error) {
+      refuse(error.message)
+    }
+  } else if (command === 'route') {
+    const tool = get('--tool')
+    const asker = get('--asker')
+    const operator = get('--operator')
+    if (!tool || !asker || !operator) refuse(USAGE)
+    try {
+      const decision = decideRoute({ env: process.env, tool, asker, operator })
+      report(json, { command: 'route', ok: true, ...decision }, 0, ['questions: route ' + decision.route + ' — ' + decision.reason])
+    } catch (error) {
+      refuse(error.message)
+    }
+  } else {
+    refuse(USAGE)
+  }
+}

package/skill/dev-review/SKILL.md

@@ -0,0 +1,76 @@
+---
+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), scanning skills for vulnerabilities or vetting a skill you did not write (skill-scan), or generic PR review in repos outside this workflow.
+---
+
+# dev-review
+
+Advise: report every finding with its confidence and severity, or the verified absence of findings — the loop downstream is the filter.
+
+Fresh reviewers report findings or their verified absence, with bounded fix loops and recorded dismissals. Briefs: [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, this skill reviews built work.
+
+## Inputs — files, not pasted context
+
+Build the review package first — `git log --oneline <base>..<head>` + `git diff --stat` + `git diff -U10` — at `.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, ordered data first and ask last, as the dispatch prompts show. **Read the file before judging it** — the full files where the diff needs context, because a diff-only read misses invariants. Reviewers write full reports to `.tmp` files and return short status, so a dead reviewer's findings survive on disk.
+
+When dev.md names a `skill-scan:` root, the security dispatch also gets the scan report, at `.vegastack/.tmp/<issue>-<slug>/skill-scan.json`, produced by `node <path-to-skill-scan>/scripts/skill-scan.mjs --json` — the `skill-scan` skill owns running it, its knobs, and its baseline. The same guard already ran at `dev-implement`'s Verify gate; this axis triages what sits below the blocking bar and judges whether anything above it was suppressed rather than fixed.
+
+## The axes — parallel, fresh, reported separately
+
+| 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`, when touch points hit auth, money, user data, or external input, or when the diff touches a skill under dev.md's `skill-scan:` root | data-flow traces, exploitability before severity, and triage of the skill scan's findings — method in [security-axis](references/security-axis.md) |
+
+Each axis uses a fresh subagent without implementation memory and reports separately. Report every finding with confidence/severity; the loop filters findings.
+
+**Dispatch without pre-judgement** — a brief saying what not to flag ("do not flag…", "don't treat X as a defect", "at most minor") hides a false positive that belongs in the open adjudication below.
+
+## The review comment — one per cycle, rounds appended, marker always current
+
+Use one cycle comment. Update its top marker each round; ship-gate reads it. Keep prior rounds as plain text without markers/bindings. Publish one fenced `reviewBinding` JSON per `references/conventions.md`: full commit/base IDs, plan digest, verdict, stable finding IDs/statuses. Marker/binding stay identical; renew legacy reviews. Consumers accept one SHA/base/scope match from a publisher in the accepted base commit's `operators:` roster; candidate edits cannot appoint a reviewer. The gate reports that roster's SHA/path/body digest as `operatorPolicy`; a roster change becomes eligible when its commit later serves as the accepted base. Zero or multiple matches refuse. `agent=` records the harness, not cryptographic model/publisher identity.
+
+```markdown
+<!-- vsk:v1 type=review round=<n> sha=<full-head-sha> 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]`, because `#N` auto-links to an issue. Low-confidence findings and nitpicks go in the collapsed block, because low-confidence items in the main list dilute it. Group one recurring defect across files into one finding with a location list. Each finding appears once with issue, impact and fix; collapse nitpicks.
+
+## 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, keeping the loop bounded.
+
+- **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" — because a loop surviving two resumes 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), new breakage in the fix diff joins the open list, and out-of-scope observations become deferred minors.
+- **At the cap:** fix forward or bring unresolved findings to the operator. Only their explicit same-review decision can accept risk; record the typed `adjudication` in evidence and surface its rulings in the Review line and ledger. Negative prose or an agent’s parked ruling grants no exception. Early adjudication never shortens the loop.
+
+Risky work requires tests and independent review. Every commit renews full-candidate review. After qualification, review all assembled child/preparation scopes; child reviews bind only their parent base. Transformations/delivery: dev-ship’s runbook.
+
+## Noise controls — hard filters, not politeness
+
+- Default quiet profile: spec, bugs, and security always; style only where a documented rule exists.
+- `.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. dev-implement's corrections loop appends operator dismissals there, so a dismissed pattern stays dismissed.
+- The skill scan's suppressions follow the same discipline in the baseline the `skill-scan` skill owns, and its guard enforces the clause — a rule scoped `id:` with no `path:` is a repo-wide blind spot. A finding suppressed rather than fixed is a review finding, not a settled matter.
+
+## A scan with no issue attached
+
+A `skill-scan` run outside an issue — a standalone check, or the pre-publish guard in dev.md's `## Ship` — has no review comment to land in, so its findings go to intake as a `risky` issue, because a comment posted somewhere convenient is a finding nobody owns. Offer the operator one `risky` issue whose brief body carries the findings, their locations, and what is known about each cause; intake's questions, scope call and approval follow.
+
+## Cross-agent — the independence upgrade
+
+The dev.md `review:` knob maps to exactly three states — `subagent` (fresh-subagent axes always, no cross-agent), `cross-agent-risky` (subagent axes normally; the other agent on `risky` — the recommended default where the CLI exists), `cross-agent` (the other agent always). 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 → the manual relay, noting that dev-setup recommends installing it. Which model and effort the other agent runs at is dev.md's `harness-policy:` `review` entry (`<stage> <agent> <model> <effort>`); with no such line, the reviewing harness's own default stands — never a guessed model id.

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,32 @@
+# 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 — (<username>)>
+```
+
+The four fields are list items — this file is read in a repo's file view, where single newlines soft-wrap into one paragraph; bullets are what guarantee a line per field. Appended entries (dev-implement's corrections loop) keep the same shape.
+
+## 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,113 @@
+# Workflow conventions
+
+Artifact authority.
+
+Defaults resolve repo, group, then org; locks require explicit org delegation. Repository dispatch/commands never inherit; registers concatenate. Policy/migration uses dev-setup's `scripts/effective-policy.mjs` and vegafactory-setup's control-room reference.
+
+## Comment metadata markers
+
+Comments open:
+
+```markdown
+<!-- vsk:v1 type=<type> rev=<n> [key=value ...] -->
+## <Human title> (v<n>)
+```
+
+| type | required keys | instances |
+|---|---|---|
+| `approval` | `scope=<brief\|brief+plan\|plan\|consolidated\|none>` and schema-v2 JSON | one per approval event |
+| `questions` | `rev` | one per ask round; earlier rounds stay as record (dev-setup's `references/ask-route.md`) |
+| `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 `(v<n>)` start at 1 only on brief, plan, questions and evidence; other types have neither. Locate by marker, never heading/legacy fallback.
+
+## Operator identity
+
+Use parenthesized GitHub usernames:
+
+- Approval: `Approved by (<username>) on DD-MM-YYYY: "<their words>"`
+- Register line: `- DD-MM-YYYY (<username>) — <decision>`
+
+Approval.mjs’s publisher/relay contract lets current-policy provider-envelope publishers attest listed operators’ session words. Other recorders may only relay independently read identical operator-published scoped grants within complete authority history, without lifecycle mutations. Relays inherit source authority/lifecycle; account attestation cannot authenticate off-platform speech.
+
+## Scoped approval records
+
+Use only dev-implement’s `scripts/lib/approval.mjs` and follow its contract. Refresh current policy and complete GitHub histories. `ArtifactRef={repo,issue,kind,artifactId,rev,digest}` binds brief issue-node or unique plan/protocol comment-node identity, revision and canonical SHA-256.
+
+Post exactly one approval comment: matching scope marker, then one fenced JSON `ApprovalRecord={schemaVersion:2,id,operator,scope,source:{kind,ref,quote},artifacts,supersedes,revokes}`. Exclude outer Markdown fences, future alternatives and unresolved source locators; validate the whole body with approval.mjs's `parseApproval`. Source kind is `session` or `github-comment`, with inspectable words. Reuse valid current grants/relays; avoid counterfactual plan-only or redundant approvals. Scope is `brief`, `plan` or `brief+plan`; planning requires brief, implementation both, research execution also its protocol. Empty-artifact revocations remove exact earlier IDs. Conflicts explicitly supersede; newest never wins.
+
+Preserve legacy comments. Without writes, inventory refusals/current digests and request reconfirmation. For duplicate canonical plans preserve both identities/bodies and request record-preserving reconciliation; never delete to clear ambiguity. Follow approval.mjs’s exact correction schema, operator-publisher and target checks. Only malformed or demonstrably invalid-source targets qualify, never valid authority or unavailable/inconsistent facts. Resolve source facts first; corrections grant no scope. Exact child checkpoint actions bind one selected code child's branch/ref/base/tasks/files; other actions never substitute.
+
+Consolidated parent events bind frozen manifests, canonical artifacts and exact task/action subsets. Use inline UTF-8 or immutable repository/commit/path plus blob hash, never local paths. Canonical `approvalBindings` authorize; requested `recordBinding` only audits. Follow approval.mjs’s preparation/research/recovery provenance, receipts, adapters, counted attempts and fresh admission; retain immutable history and unverified legacy records. Keep checkpoint/private/live/shipping gates separate.
+
+Canonicalization normalizes CRLF; its only exceptions are structural plan checkboxes and one validated JSON `{tasks:[{id,evidenceUrls}]}` block between `<!-- vsk:progress:start -->` / `<!-- vsk:progress:end -->`. IDs must exist; URLs are HTTP(S); unknown fields/duplicates refuse. Stable task IDs/order, interfaces, actions, revisions and all other bytes remain scope. Brief/protocol bodies have no mutable fields; fenced examples stay immutable and grant no authority.
+
+## Revision markers
+
+Scope edits increment marker/heading revisions and append `Revisions: v2 — DD-MM-YYYY: <change>, per (<username>) correction`; preserve earlier lines and obtain fresh approval. Validated progress changes need neither.
+
+## Scope classes
+
+Intake explains scope; operator overrides:
+
+- **`research`** — inquiry; throwaway code allowed, never merged. No branch/PR/changelog; evidence comment contains findings and recommendation.
+- **`quick-build`** — existing flow: draft brief+plan together, approve both, then `ready`.
+- **`full-plan`** — new ground: approve brief, `needs-plan`, separate grounded planning session, `needs-operator`, approve plan, `ready`. Split multiple deliverables into independently classified epic children.
+
+Scope ratchet: `dev-plan`.
+
+## Labels
+
+One state; flips set assignees (colors: dev-setup):
+
+| label | meaning | assignee |
+|---|---|---|
+| `needs-operator` | question, brief or plan approval, proposal | the operator |
+| `needs-plan` | brief approved; awaiting planning (full-plan only) | the operator |
+| `ready` | approved — an agent may start | nobody |
+| `working` | claimed; ledger shows live progress | the runner |
+| `for-operator` | done — evidence posted, awaiting operator review | the operator |
+
+Modifiers coexist with state: `risky` · scope `research` / `quick-build` / `full-plan` · `epic` (map parents without a native Epic type). Boards mirror states one-way.
+
+## Titles, types, hierarchy
+
+- **Title prefixes:** issues, branches and PRs use dev.md's `branch:` types plus `research:`; PR title = issue title.
+- **Native issue types/fields:** Feature (feat) · Bug (fix) · Task (docs/chore/refactor/research) · Epic for parents (else label); intake sets Priority/Effort. Scope classes stay labels.
+- **Hierarchy:** epic parent = map only (Destination · Decisions so far · Not clear yet · Out of scope), with native child sub-issues. Issues are work units (brief, approvals, branch, PR, evidence); tasks are checkboxes **only in the plan comment**. Blockers use dependencies; phases use milestones. Only non-epic issues get `ready`.
+
+## The ledger
+
+One implementation ledger:
+
+```markdown
+<!-- vsk:v1 type=ledger branch=<branch> -->
+## Ledger — <branch>
+- <issue>-T<N>: complete (commits <base7>..<head7>[, review clean | K parked])
+- <issue>-T<N>: fix round <R>/3 (<X> addressed, <Y> open — <one-liners>; commits <a>..<b>)
+- Ruling: <what> — <why> — cost if wrong: <cost>
+- <issue>-T<N>: parked — <finding> — Ruling: <why the code stands>
+- Deferred minor: <one-liner>
+```
+
+
+**Resume protocol:** brief → plan comment → ledger → `git log`; then reconcile task IDs, canonical approval history, edited authority, source/evidence, ownership and delivery effects. Preserve completed work/provenance; stale heartbeat is not stop proof. Preparation never implies issue completion. Dev-implement's ledger reference owns recovery detail.
+
+## `.vegastack/` workspaces
+
+Drafts/reports: `.vegastack/.tmp/<issue-number>-<title-slug>/` (pre-issue: `intake-<slug>`), self-ignored by a `.gitignore` containing `*`. Branch checkouts: root-ignored `.vegastack/.worktrees/<issue-number>-<title-slug>/`; main stays on its default branch. Keep both outside `.git/`. Subagents save full reports and return short status. `<path-to-this-skill>` means SKILL.md’s directory.
+
+## Verification gate
+
+Prove claims with fresh command output and exit codes; report failures and skips. Delegate only substantial independent parallel work, never your own verification; keep spawn counts low. Guards block machine-verifiable failures (exit 2); heuristics warn. Guards contain no AI inference; unverifiable state fails closed.
+
+## Review bindings
+
+One fenced JSON each: `{"reviewBinding":{sha,baseSha,scopeDigest,verdict,findings:[{id,status}]}}` in review; `{"adjudication":{sha,reviewCommentId,operator,source:{kind,ref,quote},findings:[{id,disposition,reason}]}}` in evidence. Use full commit IDs and canonical-plan scopeDigest; status=open/resolved; disposition=accept-risk. Every open finding requires same-review operator acceptance. dev-ship’s README defines source checks. No prose exceptions.
+
+Communicate starts/findings/direction plainly; self-contained outcomes include paths and remaining checks. Avoid invented labels/arrows; visualize usefully. Challenge ambiguity with options; never guess silently.