@vegastack/vegafactory 0.19.0

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

@@ -0,0 +1,54 @@
+---
+name: dev-plan
+description: Write the implementation plan for an approved issue before any code exists. Use when asked to "plan issue 12", "write the plan for" a feature or issue, "plan this before building", when picking up an issue labeled needs-plan, when an approved brief needs its technical approach worked out, or when dev-intake requests the inline plan for a quick-build issue. Not for writing or approving the brief itself (dev-intake), not for executing an approved plan (dev-implement), not for architecture stack advice (dev-architect — this skill consults it while planning).
+---
+
+# dev-plan
+
+Advise: turn the approved brief into the plan the operator approves and dev-implement executes, against the repo as it is now.
+
+The planning stage: an approved brief goes in, an operator-approved plan comes out, and only then does code exist. A `full-plan` issue is planned in a separate session from intake, because code drifts between brief approval and build.
+
+Nearest neighbors: `dev-intake` owns the brief and its approval mechanics — this skill owns the how; `dev-implement` executes what this produces, task by task.
+
+## Every run
+
+1. Read `.vegastack/dev.md` and the issue: brief (description), current schema-v2 brief approval (bundled `scripts/lib/approval.mjs`’s `evaluateApprovals`, complete history and current operator policy), scope label. Full-plan issues arrive labeled `needs-plan`; anything else at this door is either intake's inline request (below) or a misroute — say so.
+2. **Re-ground before planning** — open the brief's touch points in the current code and verify the flow, names and shapes the plan builds on, because code drifts between approval and build. A claim that no longer matches reality goes back to the operator (`handback` comment, `needs-operator`).
+3. Stack-bearing choices (schema, hosting, services, jobs, auth) check `dev-architect` — its verify protocol governs platform claims, and no plan re-proposes a recorded rejection.
+
+## The questionnaire
+
+Numbered rounds over the full frontier (every open question whose prerequisites are settled), each question carrying a recommended answer so the operator can reply "all recommended":
+
+1. **Approaches** — two or three candidates with the trade-off that matters and one recommendation, because a single option is a decision dressed as a question.
+2. **System design** — schema, interfaces, migration shape, failure modes; what breaks at the edges.
+3. **Risk** — blast radius, what a rollback looks like, what should stop a dark run beyond the standing stop-list.
+4. **Brief challenge** — anything planning revealed the brief missed or got wrong goes back to the operator as a question, because a brief gap absorbed into the plan is a decision the operator did not make.
+
+Rounds go out by the ask route (`references/ask-route.md`); an issue-routed round stops the session at `needs-operator` and the next run parses the reply before re-asking anything. A vague or self-contradicting answer gets pushback with concrete options — simple words, a mermaid or ASCII sketch in the issue when a picture beats prose (conventions' collaboration rule).
+
+## The plan
+
+Give every task its stable `<issue>-T<n>` identity before approval. Post one comment per [plan-format](references/plan-format.md): Goal · Approach (alternatives named) · Constraints · ordered `- [ ]` tasks, each with exact Files, an Interfaces block (consumes/produces with exact signatures), and Steps that put the failing test before the code. Before posting:
+
+- Walk the brief section by section per plan-format's self-review — every requirement points at a task, names match across tasks, no banned placeholder.
+- Work that can run at the same time gets plan-format's independent-group block, because a declared file set is what lets dev-implement run children in parallel and prove afterwards that none of them wandered.
+- Run this skill's plan-lint: `node <path-to-this-skill>/scripts/plan-lint.mjs --file <draft> --json`; exit 2 = fix before posting (placeholders and structural gaps block).
+
+Checkboxes belong to the implement session and post empty, because dev-status reads a ticked box as progress.
+
+## Labels and approval
+
+Post a new plan → `needs-operator`, assigned to the issue's operator (conventions' Labels table). Resolve fresh complete approval history against current canonical artifacts first: reuse valid intent covering the requested scope, including a combined brief+plan grant, preserving canonical `approvalBindings`. When new approval is needed, record the operator's actual scope per conventions: `scope=plan` for standalone full-plan approval, `scope=brief+plan` for quick-build inline approval, with exact source quotation and current canonical `ArtifactRef`s. A policy-operator publisher attests session words; another recorder may only relay a verified identical scoped grant.
+
+A requested approval draft must match that disposition: the exact existing event body for reuse, or the applicable new event/verified relay, never a hypothetical substitute. Validate the complete body per conventions. Only after fresh evaluation confirms both current brief and plan approval, flip to `ready` and unassign; stop — building is dev-implement's.
+
+## The ratchet — one home, this file
+
+- **Upgrade (any time, no permission needed to propose):** planning reveals the work is bigger than its scope label — a quick-build that needs real design, an issue that is actually several deliverables. Stop, post one `handback` comment proposing the reclassification or the epic split (parent map + sub-issues, each classified fresh), `needs-operator`, assigned to the operator. A plan runs about one screen per task — Files, Interfaces, Steps — and a plan approaching GitHub's ~65,536-character comment cap is the slicing telling you it wants to be an epic.
+- **Downgrade (operator's yes only):** planning reveals the work is trivial — propose skipping to `ready` with the brief's inline approach, and wait for the yes.
+
+## Quick-build inline mode
+
+Invoked from inside dev-intake's conversation, after the brief has consensus: same format, proportionally small (a four-item task list is a fine plan), posted as the plan comment alongside the brief. The operator's single approval covers both (`scope=brief+plan`) — no `needs-plan` stop, no second exchange. The re-grounding step collapses to what intake already read; the ratchet still applies.

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

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

package/skill/dev-plan/references/ask-route.md

@@ -0,0 +1,80 @@
+# The ask route
+
+Where a round of questions goes when a skill needs the user. Two surfaces: the harness's question tool, or the issue itself. This file is the one home for the route, the comment shape and the reply grammar; `scripts/questions.mjs` is the deterministic method behind them, and the marker row lives in [conventions](conventions.md).
+
+## The route
+
+Three steps, in this order, first match wins:
+
+1. `VSK_ASK_ROUTE` is set to `issue` or `tool` — the dispatcher and CI set it; any other non-empty value is refused rather than guessed.
+2. This harness and this run have no question tool → `issue`.
+3. The asker is not the issue's operator → `issue`. An unresolved asker or operator is also `issue`.
+
+Otherwise the tool. The issue route needs an issue: where none exists yet — dev-intake's interview runs before its issue is created — the skill creates the issue first, at `needs-operator` with the operator assigned and the request as its body, and posts the round to it; the brief is written into that issue once the round is answered. On the tool route the issue is created after approval, as before. Settle it deterministically rather than by judgement:
+
+```sh
+node <path-to-this-skill>/scripts/questions.mjs route --tool <name|none> --asker <login> --operator <login> --json
+```
+
+Which tool each harness has — and the Codex Plan-mode gating on `request_user_input` — is recorded in dev-setup's `references/harness-facts.md` (a backticked path, not a link: this file ships into dev-intake, dev-plan and dev-implement, which do not carry that reference) and not restated here. The operator identity comes from the caller under dev.md's `operators:` knob; the script takes both logins as inputs and never resolves them itself.
+
+The bias is deliberate: a round in a comment is always readable by whoever owns the issue, and a round put to the wrong person is not.
+
+## The comment
+
+One comment per round, marker first, the whole round wrapped in `<questions>` tags so the parser and the model both find it inside a comment that may carry prose around it:
+
+```markdown
+<!-- vsk:v1 type=questions rev=1 -->
+## Questions (v1)
+
+<questions>
+**Q1.** Where does the reminder queue live?
+- a) A Postgres table
+- b) A Redis list (recommended — Redis is already a dependency)
+
+**Q2.** How late may a reminder fire?
+- a) Within the hour (recommended — matches the existing cron cadence)
+- b) Same day
+
+Reply with `1: a` per question, or `all recommended`.
+</questions>
+```
+
+No question, option or reason may carry an HTML comment delimiter or a `questions` block tag: a round can be read back out of a comment anyone may have written, so text that could close the block or forge a marker is refused in both directions. Every question carries at least two options and exactly one recommendation, and every recommendation carries its one-line reason — a round that cannot say which way it leans is a round that has not been thought through, and the renderer refuses it. Options run `a` through `h`. After posting, the label moves to `needs-operator` and the session ends.
+
+## Replying
+
+Anyone on the issue may answer, in an ordinary comment, one line per question:
+
+- `1: b`
+- `2: a — the cron already runs` (trailing prose after the dash is kept)
+- `3: other — a third way` (`other` is accepted for any question)
+- `all recommended` on its own line fills every question not answered explicitly
+
+An explicit line always beats `all recommended`. Bulleted lines, a `.` instead of `:`, and upper-case letters all parse. Surrounding prose is ignored; the first answer to a question stands and a repeat is reported. A numbered line whose letter runs straight into prose with no dash (`1: a is wrong, go with b`) is malformed, not an answer of `a` — the parser reports it and the question is re-asked.
+
+## Re-asks
+
+Parse before asking anything. A later session has no `round.json` on disk, so it reads the round back out of the posted comment — that is what the `<questions>` wrapper is for, and `--round <comment.md>` takes it in place of `--spec`. What comes back is answered questions, still-open questions, and malformed lines. If nothing is open, continue — never re-ask an answered question. If something is open, post a second comment at `rev=<n+1>` carrying only the open questions **at their original numbers**, so `**Q3.**` stays Q3. Earlier `questions` comments are left in place as record. A reply with no answer line at all is malformed, not empty: it gets one re-ask naming the expected shape.
+
+## What it is not
+
+An answer is not an approval. Any teammate may answer a round; only the operator approves, and approval is still its own `approval` marker comment recording the operator's own words in the `(<username>)` format ([conventions](conventions.md)). A round that is fully answered unblocks the work; it does not move the issue to `ready`.
+
+Assignment is not this route's job either — the label moving to `needs-operator` is what puts the issue on the operator.
+
+## Commands
+
+Save the reply comment to `.vegastack/.tmp/<issue>-<slug>/reply.md` first; the parser reads a file, never a network.
+
+```sh
+node <path-to-this-skill>/scripts/questions.mjs render --spec round.json --rev 1 --json
+node <path-to-this-skill>/scripts/questions.mjs parse  --comment reply.md --round asked.md --json
+node <path-to-this-skill>/scripts/questions.mjs re-ask --round asked.md --comment reply.md --rev 2 --json
+node <path-to-this-skill>/scripts/questions.mjs route  --tool none --asker <login> --operator <login> --json
+```
+
+`asked.md` is the posted `questions` comment; `--spec round.json` takes the same round as JSON instead, where the rendering session still has it. A spec is `{ "questions": [ { "text": "…", "options": [ { "letter": "a", "text": "…" }, { "letter": "b", "text": "…", "recommended": true, "reason": "…" } ] } ] }`.
+
+Exit codes: 0 pass · 1 answers still open or malformed, and for `re-ask` nothing left to ask · 2 refusal or usage error.

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