@vegastack/vegafactory 0.19.0

package/skill/dev-setup/assets/factory-board.yml.template

@@ -0,0 +1,162 @@
+# factory-board.yml.template — dev-setup writes this to .github/workflows/factory-board.yml
+# on the operator's yes, with three placeholders bound and every line above the strip
+# marker below dropped:
+#   {{runs-on}}       the job's runner label or label array, e.g. ubuntu-latest
+#   {{profile}}       path to the project's dev.md, e.g. .vegastack/dev.md
+#   {{product-revision}} immutable product commit supplying the packaged policy compiler
+# Requirements the offer must state: the VegaFactory App installed for the org with
+# VEGAFACTORY_APP_ID and VEGAFACTORY_APP_PRIVATE_KEY set (references/github-app.md), and
+# gh 2.97.0 or newer on the runner for name-based project field edits.
+# ---
+# Board mirror — the five state labels drive the project board's Status field.
+#
+# One way only: this workflow reads labels and writes Status. Nothing reads the board.
+# A card dragged on the board is cosmetic until the next label change overwrites it.
+#
+# Needs the VegaFactory App (org variable VEGAFACTORY_APP_ID, org secret
+# VEGAFACTORY_APP_PRIVATE_KEY) because GITHUB_TOKEN cannot write Projects, and gh 2.97.0
+# or newer on the runner for `--field Status --value <name>`.
+name: Board mirror
+
+on:
+  issues:
+    types: [labeled, unlabeled, opened, reopened]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: board-mirror-${{ github.event.issue.number }}
+  cancel-in-progress: false
+
+jobs:
+  mirror:
+    runs-on: {{runs-on}}
+    steps:
+      - name: Read the profile
+        uses: actions/checkout@v7
+        with:
+          # Its own directory, never the runner's shared checkout: a sparse checkout
+          # leaves git in sparse mode, and on a self-hosted runner the next job that
+          # reuses the same path would start from an almost-empty tree.
+          path: profile
+          sparse-checkout: "{{profile}}"
+          sparse-checkout-cone-mode: false
+
+      - name: Read the pinned policy compiler
+        uses: actions/checkout@v7
+        with:
+          repository: vegastack/vegafactory
+          ref: "{{product-revision}}"
+          path: .vegafactory-policy
+          sparse-checkout: "skills/dev/dev-setup/scripts/effective-policy.mjs"
+          sparse-checkout-cone-mode: false
+          persist-credentials: false
+
+      - name: Resolve the board and the state label
+        id: resolve
+        env:
+          PROFILE: "profile/{{profile}}"
+          POLICY_MODULE: ".vegafactory-policy/skills/dev/dev-setup/scripts/effective-policy.mjs"
+          LABELS: '${{ toJSON(github.event.issue.labels.*.name) }}'
+          APP_ID: "${{ vars.VEGAFACTORY_APP_ID }}"
+        run: |
+          set -eu
+
+          if [ ! -f "$PROFILE" ]; then
+            echo "board mirror: skipped - no such file $PROFILE in this repo"
+            echo 'decision=skip' >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          board=$(sed -n 's/^board:[[:space:]]*\([^[:space:]#]*\).*/\1/p' "$PROFILE" | head -1)
+          if [ -z "$board" ] || [ "$board" = "none" ]; then
+            echo "board mirror: skipped - $PROFILE carries no board number"
+            echo 'decision=skip' >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          if [ -z "${APP_ID:-}" ]; then
+            echo "board mirror: skipped - no VEGAFACTORY_APP_ID variable; the factory App is not installed for this org"
+            echo 'decision=skip' >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          have=$(gh --version | sed -n '1s/^gh version \([0-9][0-9.]*\).*/\1/p')
+          have_n=$(awk -F. '{ printf "%d", $1 * 1000000 + $2 * 1000 + $3 }' <<<"$have")
+          if [ "${have_n:-0}" -lt 2097000 ]; then
+            echo "::error::board mirror needs gh 2.97.0 or newer for name-based project fields; this runner has ${have:-unknown}"
+            exit 1
+          fi
+
+          node --input-type=module <<'JS'
+          import { readFileSync, appendFileSync } from 'node:fs';
+          import { resolve } from 'node:path';
+          import { pathToFileURL } from 'node:url';
+          const { parsePolicy, readWorkflowLabels, resolveState } = await import(pathToFileURL(resolve(process.env.POLICY_MODULE)).href);
+          try {
+            const policy = parsePolicy(readFileSync(process.env.PROFILE, 'utf8'));
+            if (policy.blocks.length) throw new Error(policy.blocks.join('; '));
+            const map = readWorkflowLabels(readFileSync(process.env.PROFILE, 'utf8'));
+            const state = resolveState(JSON.parse(process.env.LABELS), map);
+            if (state.blocks.length) throw new Error(state.blocks.join('; '));
+            const board = policy.extensions.board?.split(/\s/)[0];
+            if (!/^[1-9][0-9]*$/.test(board ?? '')) throw new Error('invalid board number');
+            appendFileSync(process.env.GITHUB_OUTPUT, 'decision=sync\nboard=' + board + '\nstatus=' + map[state.state] + '\n');
+          } catch (error) {
+            console.log('board mirror: skipped - ' + error.message);
+            appendFileSync(process.env.GITHUB_OUTPUT, 'decision=skip\n');
+          }
+          JS
+
+      - name: Mint the App token
+        id: token
+        if: steps.resolve.outputs.decision == 'sync'
+        uses: actions/create-github-app-token@v3
+        with:
+          app-id: "${{ vars.VEGAFACTORY_APP_ID }}"
+          private-key: "${{ secrets.VEGAFACTORY_APP_PRIVATE_KEY }}"
+          # owner resolves the org installation; repositories narrows the token to this one
+          # repository — without it the token reaches every repository the installation covers.
+          owner: "${{ github.repository_owner }}"
+          repositories: "${{ github.event.repository.name }}"
+
+      - name: Write Status on the board
+        id: mirror
+        if: steps.resolve.outputs.decision == 'sync'
+        env:
+          GH_TOKEN: "${{ steps.token.outputs.token }}"
+          OWNER: "${{ github.repository_owner }}"
+          BOARD: "${{ steps.resolve.outputs.board }}"
+          STATUS: "${{ steps.resolve.outputs.status }}"
+          ISSUE_URL: "${{ github.event.issue.html_url }}"
+        run: |
+          set -eu
+          options=$(mktemp)
+          gh project field-list "$BOARD" --owner "$OWNER" --format json > "$options"
+          OPTIONS_FILE="$options" node --input-type=module <<'JS'
+          import { readFileSync } from 'node:fs';
+          const fields = JSON.parse(readFileSync(process.env.OPTIONS_FILE, 'utf8')).fields;
+          const status = Array.isArray(fields) ? fields.filter(field => field.name === 'Status') : [];
+          if (status.length !== 1 || !Array.isArray(status[0].options) || !status[0].options.some(option => option.name === process.env.STATUS)) {
+            console.error('board mirror: configured Status option unavailable; no board mutation');
+            process.exit(1);
+          }
+          JS
+          err=$(mktemp)
+          if gh project item-edit "$BOARD" --owner "$OWNER" --url "$ISSUE_URL" --field Status --value "$STATUS" 2>"$err"; then
+            echo "board mirror: Status=$STATUS on project $BOARD"
+            exit 0
+          fi
+          cat "$err" >&2
+          # Only the one failure that means "not on the board yet" earns an item-add; gh names
+          # it ("<url> is not an item in project <n>; add it first with `gh project item-add`").
+          # A permission, option or transport error is reported as itself and stops here.
+          if ! grep -q 'is not an item in project' "$err"; then
+            echo "::error::board mirror: item-edit failed for a reason other than a missing item (the message above) - not adding, not retrying"
+            exit 1
+          fi
+          echo "board mirror: item not on project $BOARD yet - adding it, then retrying once"
+          gh project item-add "$BOARD" --owner "$OWNER" --url "$ISSUE_URL"
+          gh project item-edit "$BOARD" --owner "$OWNER" --url "$ISSUE_URL" --field Status --value "$STATUS"
+          echo "board mirror: Status=$STATUS on project $BOARD"

package/skill/dev-setup/assets/hooks/decision-nudge.mjs

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+// Decision reminders remain session prose. This compatibility Stop hook only
+// requests the same bounded, deduplicated local flush as stop-heartbeat.
+//
+// Installed to .vegastack/hooks/decision-nudge.mjs and wired on the Stop event. It replaces
+// the inline shell recipe this skill used to carry: Node is guaranteed by the installer while
+// `jq` is not, and a hook that silently exits because `jq` is missing is a guard that is not
+// there. The prose instruction in the AGENTS.md dev section remains the portable base; this
+// is a deterministic nudge on top of it, not a replacement.
+
+import { pathToFileURL } from 'node:url'
+
+export const NUDGE_REASON =
+  'Before finishing: if this session settled a directional choice (the Decisions test in .vegastack/dev.md), propose one dated register line and ask the user to confirm; otherwise finish.'
+
+const DIRECTIONAL = /decided|chose|instead of|convention|from now on|standardi[sz]|switch(ed|ing)? to/i
+
+export function isDirectional(message) {
+  return typeof message === 'string' && DIRECTIONAL.test(message)
+}
+
+// Directional changes remain proposals in the session, never a Stop continuation
+// or an unchecked session ID used as a temporary-file destination.
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  try {
+    const { runAdvisoryHook } = await import('./session-start.mjs')
+    await runAdvisoryHook('Stop', process.argv.slice(2))
+  } catch { /* advisory only */ }
+  process.exit(0)
+}

package/skill/dev-setup/assets/hooks/prompt-skill-mention.mjs

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+// Codex prompt → skill mentions, recorded as a proxy.
+//
+// Installed to .vegastack/hooks/prompt-skill-mention.mjs and wired on Codex's UserPromptSubmit
+// event. Codex exposes no skill-activation event, so a skill's name mentioned in the prompt is the best available
+// signal — and the record says so: these land with `trigger: "mention"`, never with the confidence
+// of Claude's real activation events. Proactive skill capture on Codex stays a documented gap
+// rather than a number that looks precise and is not.
+
+import { spawnSync } from 'node:child_process'
+import { readFileSync } from 'node:fs'
+import { pathToFileURL } from 'node:url'
+
+function main() {
+  const raw = readFileSync(0, 'utf8')
+  spawnSync(process.env.VSK_VEGAFACTORY || 'vegafactory', ['stats', 'record', '--source', 'codex-prompt'], {
+    input: raw,
+    stdio: ['pipe', 'ignore', 'ignore'],
+  })
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  try {
+    main()
+  } catch {
+    // a prompt must never fail to submit because nobody could count it
+  }
+  process.exit(0)
+}

package/skill/dev-setup/assets/hooks/session-end.mjs

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+// SessionEnd requests only a bounded local flush. Never block exit, continue a turn,
+// forward transcript/tool payloads, or start detached delivery/model work.
+import { pathToFileURL } from 'node:url'
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  try {
+    // The installer copies the shared SessionStart adapter with either consumer.
+    // A missing sibling is an advisory failure, not an exit-blocking module error.
+    const { runAdvisoryHook } = await import('./session-start.mjs')
+    await runAdvisoryHook('SessionEnd', process.argv.slice(2))
+  } catch { /* missing CLI/adapter, invalid input and timeout remain non-blocking */ }
+  process.exit(0)
+}

package/skill/dev-setup/assets/hooks/session-start.mjs

@@ -0,0 +1,178 @@
+#!/usr/bin/env node
+// Bounded local advisory adapter shared by SessionStart, Stop and SessionEnd.
+// Guard enforcement is separate. This adapter never reads transcripts or native memory,
+// invents a write destination, contacts a network or asks a model to continue.
+
+import { spawn } from 'node:child_process'
+import { accessSync, constants, lstatSync, readFileSync, realpathSync } from 'node:fs'
+import { delimiter, dirname, isAbsolute, join } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import { createHash, randomUUID } from 'node:crypto'
+
+export const MAX_HOOK_INPUT_BYTES = 64 * 1024
+export const LOCAL_FLUSH_MS = 500
+const INPUT_WAIT_MS = 350
+const EVENTS = new Set(['SessionStart', 'Stop', 'SessionEnd'])
+const identity = value => typeof value === 'string' && /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/.test(value)
+
+export function sanitizeHookInput(payload, harness, event) {
+  if (!['claude', 'codex'].includes(harness) || !EVENTS.has(event)) return null
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) return null
+  if (payload.hook_event_name !== undefined && payload.hook_event_name !== event) return null
+  if (!identity(payload.session_id) || (payload.turn_id !== undefined && !identity(payload.turn_id))) return null
+  if (typeof payload.cwd !== 'string' || payload.cwd.length > 4096 || !isAbsolute(payload.cwd) || /[\0\r\n]/.test(payload.cwd)) return null
+  if (payload.stop_hook_active !== undefined && typeof payload.stop_hook_active !== 'boolean') return null
+  // These values are identifiers for the private CLI resolver, never filesystem destinations.
+  return {
+    harness, event, sessionId: payload.session_id,
+    ...(payload.turn_id === undefined ? {} : { turnId: payload.turn_id }),
+    cwd: payload.cwd, stopHookActive: payload.stop_hook_active ?? false,
+  }
+}
+
+export function readBoundedHookInput(stream = process.stdin) {
+  return new Promise(resolve => {
+    const chunks = []
+    let size = 0, finished = false
+    const done = value => {
+      if (finished) return
+      finished = true
+      clearTimeout(timer)
+      stream.removeListener('data', data)
+      stream.removeListener('end', end)
+      stream.removeListener('error', error)
+      stream.pause()
+      resolve(value)
+    }
+    const data = chunk => {
+      const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)
+      size += bytes.length
+      if (size > MAX_HOOK_INPUT_BYTES) return done(null)
+      chunks.push(bytes)
+    }
+    const end = () => {
+      try { done(JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(Buffer.concat(chunks)))) }
+      catch { done(null) }
+    }
+    const error = () => done(null)
+    const timer = setTimeout(() => done(null), INPUT_WAIT_MS)
+    stream.on('data', data).once('end', end).once('error', error)
+  })
+}
+
+function localCli() {
+  const explicit = process.env.VSK_VEGAFACTORY
+  const candidates = explicit ? [explicit] : (process.env.PATH ?? '').split(delimiter).filter(isAbsolute).map(path => join(path, 'vegafactory'))
+  for (const candidate of candidates) {
+    try {
+      if (!isAbsolute(candidate)) continue
+      const path = realpathSync(candidate)
+      if (!lstatSync(path).isFile()) continue
+      accessSync(path, constants.R_OK)
+      const root = dirname(dirname(path))
+      const read = file => {
+        const stat = lstatSync(file)
+        if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 1024 * 1024) throw new Error('unsupported package metadata')
+        return readFileSync(file)
+      }
+      const pkg = JSON.parse(read(join(root, 'package.json')))
+      if (pkg.name !== '@vegastack/vegafactory' || pkg.bin?.vegafactory !== 'dist/index.js'
+        || path !== realpathSync(join(root, 'dist/index.js'))) continue
+      const manifest = JSON.parse(read(join(root, 'skill-integrity.json')))
+      const expected = manifest.schemaVersion === 2 && manifest.skills?.['dev-setup']?.files?.['assets/hooks/session-start.mjs']
+      if (typeof expected !== 'string' || !/^[a-f0-9]{64}$/.test(expected)) continue
+      const hash = bytes => createHash('sha256').update(bytes).digest('hex')
+      if (hash(read(fileURLToPath(import.meta.url))) !== expected
+        || hash(read(join(root, 'skill/dev-setup/assets/hooks/session-start.mjs'))) !== expected) continue
+      return path
+    } catch { /* missing installed CLI is an advisory no-op */ }
+  }
+  return null
+}
+
+export function runLocalHookPhase(cli, command, input, entryAt = performance.now()) {
+  return new Promise(resolvePhase => {
+    const remaining = 1000 - (performance.now() - entryAt)
+    if (remaining <= 0) return resolvePhase({ completed: false, output: '', phaseMs: null, totalMs: performance.now() - entryAt })
+    const nonce = randomUUID()
+    let phase = 'waiting-ready', output = '', phaseAt = null, phaseTimer = null, settled = false
+    // Detached creates one owned POSIX process group; this child remains fully
+    // supervised and is never unref'd or left doing background delivery.
+    const child = spawn(process.execPath, [cli, ...command], {
+      detached: process.platform !== 'win32', stdio: ['pipe', 'pipe', 'ignore', 'ipc'],
+      env: { ...process.env, GIT_OPTIONAL_LOCKS: '0' },
+    })
+    const kill = () => {
+      phase = 'failed'
+      try { if (child.pid && process.platform !== 'win32') process.kill(-child.pid, 'SIGKILL'); else child.kill('SIGKILL') } catch { /* already absent */ }
+    }
+    const deadline = setTimeout(kill, remaining)
+    const cancelled = () => kill()
+    process.once('SIGTERM', cancelled); process.once('SIGINT', cancelled)
+    const done = completed => {
+      const now = performance.now()
+      completed = completed && (phaseAt === null ? output === '' : now - phaseAt <= LOCAL_FLUSH_MS) && now - entryAt <= 1000
+      if (settled) return
+      settled = true
+      clearTimeout(deadline); clearTimeout(phaseTimer)
+      process.removeListener('SIGTERM', cancelled); process.removeListener('SIGINT', cancelled)
+      resolvePhase({ completed, output: completed ? output : '', phaseMs: phaseAt === null ? null : performance.now() - phaseAt, totalMs: performance.now() - entryAt })
+    }
+    child.on('error', () => { kill(); done(false) })
+    child.stdin.on('error', kill)
+    child.stdout.setEncoding('utf8')
+    child.stdout.on('data', chunk => { output += chunk; if (phaseAt === null || Buffer.byteLength(output) > 4096) kill() })
+    child.on('message', message => {
+      const now = performance.now()
+      if (now - entryAt > 1000 || phaseAt !== null && now - phaseAt > LOCAL_FLUSH_MS) return kill()
+      if (!message || typeof message !== 'object' || Array.isArray(message) || message.vskManagedHook !== 1) return kill()
+      if (message.phase === 'ready' && Object.keys(message).sort().join(',') === 'phase,vskManagedHook' && phase === 'waiting-ready') {
+        phase = 'validating'
+        // Read-only registry, session and current-policy validation remains
+        // under the entry-relative deadline. It grants no local write.
+        child.send({ vskManagedHook: 1, phase: 'start', nonce }, error => { if (error) kill() })
+        child.stdin.end(JSON.stringify(input))
+      } else if (message.phase === 'validated' && Object.keys(message).sort().join(',') === 'nonce,phase,vskManagedHook' && message.nonce === nonce && phase === 'validating') {
+        phase = 'flushing'; phaseAt = performance.now()
+        // Exactly one grant covers every claim, write, release, ACK and lesson
+        // mutation. No message can renew either deadline.
+        phaseTimer = setTimeout(kill, Math.min(LOCAL_FLUSH_MS, 1000 - (phaseAt - entryAt)))
+        child.send({ vskManagedHook: 1, phase: 'flush', nonce }, error => { if (error) kill() })
+      } else if (message.phase === 'finish' && Object.keys(message).sort().join(',') === 'nonce,phase,vskManagedHook' && message.nonce === nonce && ['validating', 'flushing'].includes(phase)) {
+        phase = 'finished'
+      } else kill()
+    })
+    child.on('close', (code, signal) => done(code === 0 && signal === null && phase === 'finished'))
+  })
+}
+
+export async function runAdvisoryHook(event, argv) {
+  const entryAt = performance.now()
+  if (argv.length !== 2 || argv[0] !== '--harness') return
+  const input = sanitizeHookInput(await readBoundedHookInput(), argv[1], event)
+  if (!input || (event === 'Stop' && input.stopHookActive)) return
+  const cli = localCli()
+  if (!cli) return
+  const command = event === 'SessionStart' ? ['learning', 'inspect', '--source', 'managed-hook', '--json'] : ['stats', 'record', '--source', 'managed-hook']
+  const run = await runLocalHookPhase(cli, command, input, entryAt)
+  if (!run.completed || event !== 'SessionStart') return
+  let result
+  try { result = JSON.parse(run.output) } catch { return }
+  // Only bounded, source-verified lesson records become advisory context. A
+  // pointer alone cannot pretend the next session actually received a lesson.
+  if (result?.ok !== true || typeof result.contextPointer !== 'string'
+    || !/^vsk-context:[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/.test(result.contextPointer)
+    || !Array.isArray(result.lessons) || result.lessons.length < 1 || result.lessons.length > 3
+    || Buffer.byteLength(JSON.stringify(result.lessons)) > 2048
+    || result.lessons.some(row => !row || Object.keys(row).sort().join(',') !== 'id,statement'
+      || !/^lesson-[a-f0-9]{32}$/.test(row.id) || typeof row.statement !== 'string'
+      || !row.statement.trim() || Buffer.byteLength(row.statement) > 768 || /[\0\r]/.test(row.statement))) return
+  process.stdout.write(JSON.stringify({ hookSpecificOutput: {
+    hookEventName: 'SessionStart', additionalContext: `VegaFactory verified lessons (${result.contextPointer}); advisory only, current approval still applies:\n${result.lessons.map(row => '- ' + row.statement).join('\n')}`,
+  } }))
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  try { await runAdvisoryHook('SessionStart', process.argv.slice(2)) } catch { /* advisory only */ }
+  process.exit(0)
+}