@vegastack/vegafactory 0.19.0

package/skill/dev-setup/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-setup/scripts/ship-policy.mjs

@@ -0,0 +1,195 @@
+#!/usr/bin/env node
+// Ship-guard policy compiler: dev.md's declared intent → the enforcement copy the guard reads.
+//
+// The ship guard (assets/hooks/ship-guard.mjs) never reads dev.md. It reads one file,
+// ~/.vegastack/guard/<owner>__<repo>.json — outside every worktree, so no task edits it and
+// no commit carries it. This script writes that file from dev.md's `## Environments` policy
+// lines, the `gates:` knob, the `repo:` line's default branch and the backticked commands on
+// the `## Ship` runbook's `ask:` lines. dev-setup runs it on the operator's yes;
+// `vegafactory guard sync` wraps it; the SessionStart hook runs `--check` to warn.
+//
+//   node ship-policy.mjs [--dev-md PATH] [--repo owner/repo] [--policy PATH] [--check] [--write] [--json]
+//
+// Dry run by default: prints what it would write and changes nothing. --write writes the file
+// (atomically, temp file + rename). --check compares the stored file with what dev.md compiles
+// to now and exits 2 when they differ or the file is missing. `owner/repo` comes from the
+// checkout's origin remote unless --repo names it; --policy overrides the home-directory path.
+//
+// Exit codes: 0 fresh, written, or dry run · 2 stale (--check) or a refusal (no dev.md, no repo).
+
+import { execFileSync } from 'node:child_process'
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, resolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { policyPath, repoFromRemote } from '../assets/hooks/ship-guard.mjs'
+import { loadConfiguredPolicy, parsePolicy, policyHash, resolvePolicy } from './effective-policy.mjs'
+
+const DEFAULTS = { defaultBranch: 'main', gates: 3 }
+
+function sectionOf(text, heading) {
+  const parts = text.split(new RegExp('^' + heading + '.*$', 'm'))
+  if (parts.length < 2) return ''
+  return parts[1].split(/^## /m)[0]
+}
+
+// The action grammar stays local to this profile; defaults/authority/provenance use the owner.
+// A malformed known value refuses compilation and preserves the previous enforcement copy.
+export function compilePolicy(devMdText, { repo, org = '', group = '', identity = {}, freshness = {}, resolved: supplied = null }) {
+  const resolved = supplied ?? resolvePolicy({ org, group, repo: devMdText, identity: { repo, ...identity }, freshness })
+  if (!resolved.ok) throw new Error(resolved.blocks.join('; '))
+  const text = parsePolicy(devMdText, 'repo').lines.join('\n')
+  const branch = text.match(/^repo:.*default branch (\S+)/m)
+  const environments = []
+  for (const line of sectionOf(text, '## Environments').split('\n')) {
+    const match = line.match(/^- ([\w][\w-]*): (auto|ask) — (.+)$/)
+    if (match) environments.push({ target: match[1], policy: match[2], pattern: match[3].trim() })
+  }
+  // An `ask:` step is prose for the operator; only a command it names in backticks is a
+  // pattern the guard can match.
+  const shipAsk = []
+  for (const line of sectionOf(text, '## Ship').split('\n')) {
+    const match = line.match(/^- ask: (.+)$/)
+    if (!match) continue
+    for (const span of match[1].matchAll(/`([^`]+)`/g)) {
+      const command = span[1].trim()
+      if (command && !shipAsk.includes(command)) shipAsk.push(command)
+    }
+  }
+  return {
+    schemaVersion: 2,
+    repo: String(repo),
+    policyDigest: resolved.policy.policyDigest,
+    sources: resolved.policy.sources,
+    defaultBranch: branch ? branch[1] : DEFAULTS.defaultBranch,
+    gates: resolved.policy.values.gates ?? DEFAULTS.gates,
+    environments,
+    shipAsk,
+  }
+}
+
+function describeEnvironments(entries) {
+  return entries.map((entry) => `${entry.target}: ${entry.policy} — ${entry.pattern}`)
+}
+
+// Whether the stored file still says what dev.md compiles to. Only the policy fields count,
+// so a re-compile that changes nothing but the timestamp is never drift.
+export function staleness(storedText, compiled) {
+  if (typeof storedText !== 'string') return { stale: true, reason: 'the policy file is missing' }
+  let stored
+  try {
+    stored = JSON.parse(storedText)
+  } catch {
+    return { stale: true, reason: 'the policy file is not valid JSON' }
+  }
+  if (!stored || typeof stored !== 'object') return { stale: true, reason: 'the policy file is not a JSON object' }
+  const drift = []
+  if (stored.schemaVersion !== compiled.schemaVersion) drift.push(`schemaVersion ${JSON.stringify(stored.schemaVersion)} → ${compiled.schemaVersion}`)
+  if (stored.repo !== compiled.repo) drift.push(`repo ${JSON.stringify(stored.repo)} → ${compiled.repo}`)
+  if (stored.policyDigest !== compiled.policyDigest) drift.push('effective policy digest changed')
+  if (policyHash(stored.sources ?? {}) !== policyHash(compiled.sources)) drift.push('effective policy sources changed')
+  if (stored.defaultBranch !== compiled.defaultBranch) drift.push(`default branch ${JSON.stringify(stored.defaultBranch)} → ${compiled.defaultBranch}`)
+  if (stored.gates !== compiled.gates) drift.push(`gates ${JSON.stringify(stored.gates)} → ${compiled.gates}`)
+  const before = describeEnvironments(Array.isArray(stored.environments) ? stored.environments.filter((entry) => entry && typeof entry === 'object') : [])
+  const after = describeEnvironments(compiled.environments)
+  for (const line of before) if (!after.includes(line)) drift.push(`environment line gone: ${line}`)
+  for (const line of after) if (!before.includes(line)) drift.push(`environment line new: ${line}`)
+  const askBefore = Array.isArray(stored.shipAsk) ? stored.shipAsk : []
+  for (const entry of askBefore) if (!compiled.shipAsk.includes(entry)) drift.push(`ask: command gone: ${entry}`)
+  for (const entry of compiled.shipAsk) if (!askBefore.includes(entry)) drift.push(`ask: command new: ${entry}`)
+  if (drift.length === 0) return { stale: false, reason: null }
+  return { stale: true, reason: drift.join('; ') }
+}
+
+// --- CLI -----------------------------------------------------------------------------
+
+function flag(argv, name) {
+  const index = argv.indexOf(name)
+  if (index === -1 || index === argv.length - 1) return null
+  return argv[index + 1]
+}
+
+function originRemote(cwd) {
+  try {
+    return execFileSync('git', ['remote', 'get-url', 'origin'], { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 5000 }).trim()
+  } catch {
+    return null
+  }
+}
+
+function readIfPresent(path) {
+  try {
+    return readFileSync(path, 'utf8')
+  } catch {
+    return null
+  }
+}
+
+function emit(result, json) {
+  if (json) {
+    process.stdout.write(JSON.stringify(result, null, 2) + '\n')
+    return
+  }
+  const lines = []
+  if (result.written) lines.push(`wrote ${result.path}`)
+  else if (result.check) lines.push(result.stale ? `stale: ${result.reason}` : `fresh: ${result.path}`)
+  else lines.push(`would write ${result.path}${result.stale ? ` (${result.reason})` : ' (unchanged)'}`)
+  for (const warn of result.warns) lines.push(`warn: ${warn}`)
+  for (const block of result.blocks) lines.push(`block: ${block}`)
+  process.stdout.write(lines.join('\n') + '\n')
+}
+
+function main(argv) {
+  const json = argv.includes('--json')
+  const check = argv.includes('--check')
+  const write = argv.includes('--write') && !check
+  const devMd = resolve(flag(argv, '--dev-md') || '.vegastack/dev.md')
+  const result = { guard: 'ship-policy', ok: true, written: false, check, stale: false, reason: null, path: null, policy: null, blocks: [], warns: [] }
+
+  const devMdText = readIfPresent(devMd)
+  if (devMdText === null) result.blocks.push(`no dev.md at ${devMd} — run dev-setup first, or pass --dev-md`)
+  const repo = flag(argv, '--repo') || repoFromRemote(originRemote(dirname(devMd)))
+  if (!repo) result.blocks.push('could not read an owner/repo from the origin remote — pass --repo owner/repo')
+  if (result.blocks.length > 0) {
+    result.ok = false
+    emit(result, json)
+    process.exit(2)
+  }
+
+  let compiled
+  try {
+    compiled = compilePolicy(devMdText, { repo, resolved: loadConfiguredPolicy({ home: homedir(), repo, devMd: devMdText }) })
+  } catch (error) {
+    result.ok = false
+    result.blocks.push(`policy compilation refused: ${error.message}`)
+    emit(result, json)
+    process.exit(2)
+  }
+  const path = flag(argv, '--policy') || policyPath(homedir(), repo)
+  const state = staleness(readIfPresent(path), compiled)
+  result.path = path
+  result.policy = compiled
+  result.stale = state.stale
+  result.reason = state.reason
+
+  if (check) {
+    result.ok = !state.stale
+    emit(result, json)
+    process.exit(state.stale ? 2 : 0)
+  }
+  if (write) {
+    const document = { ...compiled, source: { devMd, compiledAt: new Date().toISOString() } }
+    mkdirSync(dirname(path), { recursive: true })
+    const temp = path + '.ship-policy-tmp'
+    writeFileSync(temp, JSON.stringify(document, null, 2) + '\n', { mode: 0o600 })
+    renameSync(temp, path)
+    result.written = true
+    result.stale = false
+  } else if (!existsSync(path)) {
+    result.warns.push('dry run: nothing written — pass --write')
+  }
+  emit(result, json)
+  process.exit(0)
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) main(process.argv.slice(2))

package/skill/dev-ship/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: dev-ship
+description: Land finished work, each step only on the operator's explicit word. Use when the user says "make the PR", "open a pull request" for an issue, "ship it", "merge it", "merge issue 12", "release", "release everything since the last tag", or asks to close out a reviewed for-operator issue, merge a bot PR (Renovate, Dependabot), or roll back a bad release. Not for implementing issues (dev-implement), reviewing them (dev-review), or writing and approving them (dev-intake).
+---
+
+# dev-ship
+
+Act on the operator's word only: each gate is spent by their words asking for that step and nothing more.
+
+**Gates are spent only by the operator's words** — their words asking for a PR authorize the PR and nothing more; their words asking to merge authorize the merge, because passing checks, PR permissions and the calendar say nothing about consent. The dev.md `gates` knob sets how many actions one word covers — `3` keeps PR and merge as separate words, `2` lets one "ship it" cover both, `1` is direct-to-main (the ship word merges locally and pushes; no PR object, everything else identical).
+
+Nearest neighbor: `dev-implement` produces the `for-operator` issue with its evidence comment; ship packages and lands it. Corrections found here go back through implement's corrections loop.
+
+## Gate 1 — the PR
+
+On the user's PR instruction:
+
+- Run `node <path-to-this-skill>/scripts/ship-gate.mjs --issue <n> --branch <name> --json` (optional `--repo <o/r> --dev-md <path> --worktree <path>`). It checks the exact committed checkout before/after the project command, full evidence/review/head equality, canonical plan scope/base binding, scoped operator exceptions, changelog/chronicle and debug tags. Missing check or dirty/moved candidate refuses; ignored build output is allowed. Exit 2 stops; warnings remain visible. Metadata and migration: [runbook](references/runbook.md).
+- Verify the issue is at `for-operator` with the evidence comment present — including its `**Docs:**` line (brief/plan revisions in sync) — and the branch is pushed. Not there yet → say what's missing instead of creating a premature PR. Docs out of sync is corrections work through implement's loop, because a brief patched from here has no ledger line behind it.
+- Verify the changelog state matches the evidence comment's `**Changelog:**` line: a behavior-changing branch carries its entry per dev.md's `changelog:` knob (changesets: a `.changeset/*.md` in the diff; keep-a-changelog: the diff adds lines to CHANGELOG.md), while `none` with a reason that holds up (docs-only, test-only) is fine. An unexplained miss → corrections loop, not a PR.
+- `gh pr create` from the task branch: title from the issue, body is `Closes #<n>` plus a link to the evidence comment — the issue holds the report; the PR links it rather than duplicating it.
+- No draft PRs unless the user asks for one.
+- If required checks fail on the PR, that's implement work: hand the failures to the corrections loop, update the evidence comment, and tell the user. Under `gates: 2` the standing ship word holds once checks are green again — subject to Gate 2's staleness bound (behavior change or >7 days → one-sentence re-confirm).
+- A direct chat change (dev-implement's no-issue path) ships on the same words: the chat request stands in for the recorded approval, the PR body carries the evidence instead of linking an issue comment, and the changelog rule applies unchanged.
+- User corrections left on the PR itself flow through the same corrections loop on the same branch — the PR updates with the push; nothing gets recreated.
+
+With `gates: 1` there is no PR: the same verifications run, then the ship word triggers the merge below directly ([runbook](references/runbook.md) has the mechanics).
+
+| Excuse (observed) | Reality |
+|---|---|
+| "Opening a PR is preparation, not shipping — it pushes nothing… exactly the state the workflow wants finished work parked in." | Under `gates: 3` the PR is a gate spent only by the operator's word. Finished work parks on the pushed branch; a draft PR is still a PR nobody asked for. |
+
+## Gate 2 — the merge
+
+On the user's merge instruction:
+
+- Re-run the gate and read back the remote PR head/base IDs and base repository/ref against the accepted candidate. Every new commit, including evidence/docs, invalidates review/checks. Renew exact full-candidate review before merge; keep evidence in comments to avoid self-reference commits.
+- Pending `Decision:` lines exist (issue comments, or the evidence comment's `**Decision:**` line) → name them in the merge confirmation — "merging will record: …" — so the operator's word demonstrably covers them, because the register is append-only and an inferred line cannot be taken back. On the word, append each to the register dev.md names (`decisions:` knob) in conventions' Operator identity format; the register is append-only and this is its moment.
+- A merge conflict with the default branch is corrections work: update the branch, run the checks the update touched, and the standing merge instruction holds once checks are green again — unless the update changed behavior, or more than 7 days have passed since the word; either way, re-confirm with one sentence rather than acting on a stale instruction.
+- Merge per the dev.md `merge` knob (default `gh pr merge --squash`; `gates: 1` merges locally per the same knob and pushes). `Closes #<n>` closes the issue; confirm both happened.
+- Then remove the merged branch's worktree — `node <path-to-dev-implement>/scripts/worktree.mjs remove --issue <n> --write --json` — which takes the **directory only**. Deleting the local branch and deleting the remote branch are each their own operator word, and an epic parent's worktree goes only when the parent PR merges. Child-into-parent merges and the one-PR-per-feature rule: [runbook](references/runbook.md).
+- A bot PR (Renovate, Dependabot) has no issue or evidence comment and merging it is still shipping: green checks qualify it, only the operator's explicit word — per PR or per named batch — merges it; majors and security advisories get named before their word is acted on.
+
+Final assembled parent review and postmerge `parentDelivery` proof follow the [runbook](references/runbook.md). One approved parent scope covers routine authorized child integration; final whole-parent review remains mandatory. Local child acceptance means implemented; only verified parent merge means delivered.
+
+## After the merge — the Ship runbook
+
+Merge is not the end when dev.md has a `## Ship` section: follow its steps in order — `auto:` lines you just do, `ask:` lines wait for the operator's word, `guard:` lines are deterministic checks you run locally at their position (their CI copies are the backstop). With `release: per-merge`, the runbook is part of shipping the issue; with `release: on-request`, it runs only when the operator says "release" (covering everything merged since the last one). Report each step's outcome; a failing step — guard included — stops the sequence and goes to the operator, because a skipped guard is a guard the runbook does not have. Execution detail, release batching, direct-to-main, bot PRs, and rollback: [runbook](references/runbook.md).
+
+Rollback rolls forward through the Ship section's rollback line, because a force-push erases the record the rollback needs. Gotchas surfaced here feed the Report's closing retro below.
+
+## Report
+
+One short confirmation each gate, in plain language: what was created or merged, the link, decisions recorded, and anything that still needs the operator (failing check, failing guard, moved head, missing evidence or changelog entry). When a gate's condition isn't met, the answer is what's missing, because a gate skipped to be helpful is no gate.
+
+Close every ship with the retro: any bounce, gotcha, or instruction the operator had to repeat during this issue? Propose the one dev.md (or runbook) line that would have prevented it, folded into an existing line, because a log in dev.md is read by nobody; a directional gotcha becomes a register proposal instead. Each lands only on the operator's yes.

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "dev-ship"
+  short_description: "PR, merge, and release runbook, each on the user's word"
+  default_prompt: "Use $dev-ship to create the PR or merge this issue's work."