@getarbiter/cli 0.5.0

package/dist/templates/scripts/inject-pact-samples.sh.ejs

@@ -0,0 +1,96 @@
+#!/usr/bin/env bash
+# inject-pact-samples.sh — Seed Pact interaction samples for Postman/Newman runs
+#
+# Generated by arbiter (#894) — F7: Postman/Newman contract test template
+# Emitted when contractType=rest-owned for Java projects.
+#
+# This script seeds the running service with the Pact interaction samples so that
+# the Newman collection can run against a predictable, consistent set of API behaviors.
+#
+# When to use:
+#   Call this before run-postman-tests.sh when INJECT_PACT_SAMPLES=true,
+#   or invoke directly to reset the service state before a contract test session.
+#
+# Prerequisites:
+#   - The service is running and reachable at SERVICE_BASE_URL
+#   - pacts/ directory contains at least one Pact JSON file
+#   - The service exposes an admin/test endpoint for seeding (or uses a test DB)
+#
+# Exit codes:
+#   0 — samples injected successfully (or no pacts to inject)
+#   1 — injection failed
+#   2 — environment error
+
+set -euo pipefail
+
+# ─── Configuration ────────────────────────────────────────────────────────────
+
+BASE_URL="${SERVICE_BASE_URL:-http://localhost:8080}"
+PACTS_DIR="${PACTS_DIR:-pacts}"
+SEED_ENDPOINT="${SEED_ENDPOINT:-${BASE_URL}/api/test/seed}"
+SEED_TIMEOUT="${SEED_TIMEOUT_SECONDS:-10}"
+
+# ─── Validation ───────────────────────────────────────────────────────────────
+
+if [[ ! -d "${PACTS_DIR}" ]]; then
+  echo "[inject-pact-samples] No pacts directory found at ${PACTS_DIR} — nothing to inject." >&2
+  exit 0
+fi
+
+pact_files=("${PACTS_DIR}"/*.json)
+
+if [[ ${#pact_files[@]} -eq 0 || ! -f "${pact_files[0]}" ]]; then
+  echo "[inject-pact-samples] No Pact JSON files found in ${PACTS_DIR} — nothing to inject." >&2
+  exit 0
+fi
+
+if ! command -v curl &>/dev/null; then
+  echo "[inject-pact-samples] ERROR: curl not found." >&2
+  exit 2
+fi
+
+# ─── Inject Pact samples ─────────────────────────────────────────────────────
+
+injected=0
+failed=0
+
+for pact_file in "${pact_files[@]}"; do
+  [[ -f "${pact_file}" ]] || continue
+
+  consumer=$(jq -r '.consumer.name // "unknown"' "${pact_file}" 2>/dev/null || echo "unknown")
+  provider=$(jq -r '.provider.name // "unknown"' "${pact_file}" 2>/dev/null || echo "unknown")
+  interaction_count=$(jq '.interactions | length' "${pact_file}" 2>/dev/null || echo "0")
+
+  echo "[inject-pact-samples] Injecting: ${pact_file} (${consumer} → ${provider}, ${interaction_count} interactions)"
+
+  http_status=$(curl -sf \
+    --max-time "${SEED_TIMEOUT}" \
+    -X POST "${SEED_ENDPOINT}" \
+    -H "Content-Type: application/json" \
+    -H "X-Pact-Consumer: ${consumer}" \
+    -H "X-Pact-Provider: ${provider}" \
+    --data-binary "@${pact_file}" \
+    -o /dev/null \
+    -w "%{http_code}" \
+    2>/dev/null || echo "000")
+
+  if [[ "${http_status}" =~ ^2 ]]; then
+    echo "[inject-pact-samples]   OK (HTTP ${http_status})"
+    injected=$((injected + 1))
+  else
+    echo "[inject-pact-samples]   WARN: seed endpoint returned HTTP ${http_status} for ${pact_file}" >&2
+    # Non-fatal: the pact sample injection endpoint may not be present in all environments.
+    # Newman tests will still run; failures will surface in the test results.
+    failed=$((failed + 1))
+  fi
+done
+
+echo "[inject-pact-samples] Injected ${injected} pact file(s). ${failed} failed."
+
+# Only hard-fail if ALL injections failed and at least one was attempted
+if [[ ${injected} -eq 0 && ${failed} -gt 0 ]]; then
+  echo "[inject-pact-samples] ERROR: all pact injections failed. Check SEED_ENDPOINT=${SEED_ENDPOINT}" >&2
+  exit 1
+fi
+
+exit 0

package/dist/templates/scripts/issue-readiness.mjs.ejs

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// issue-readiness.mjs — entry gate ("grill") upstream of every wave (acceptance-anchor P1).
+//
+// No issue enters a wave (or /ship preflight) until its "done right" target is written
+// down IN THE ISSUE: explicit `AC-N:` acceptance criteria beyond the template stock
+// lines, non-goals, and the files/contracts it touches. Underspecification is paid as a
+// prompt BEFORE dispatch, not as a thrown-away PR after. Orchestration-time tool —
+// intentionally NOT wired into check-all (gh/network is forbidden in the gate path).
+//
+// Usage:
+//   node scripts/issue-readiness.mjs --body-file <path> [--emit-comment]
+//   node scripts/issue-readiness.mjs --issue <n> [--emit-comment]     # via gh CLI
+//
+// Output: one JSON line {ready, missing:[…]} on stdout; with --emit-comment and a
+// not-ready verdict, the needs-clarification comment body follows after a "---" line.
+//
+// Exit codes (INV-53): 0 ready · 1 not ready · 2 error (bad args, gh missing/failed)
+import { readFileSync } from 'node:fs'
+import { spawnSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+import { assessReadiness, renderClarificationComment } from './lib/acceptance-criteria.mjs'
+
+function loadBody(args) {
+  const bodyIdx = args.indexOf('--body-file')
+  if (bodyIdx !== -1) {
+    const path = args[bodyIdx + 1]
+    if (!path) return { error: '--body-file requires a path' }
+    try {
+      return { body: readFileSync(path, 'utf-8') }
+      // FAIL-OPEN-INTENT: the error object is returned; main() surfaces it on stderr and exits 2 — fail-closed at the call site.
+    } catch (err) {
+      return { error: `cannot read body file: ${err instanceof Error ? err.message : String(err)}` }
+    }
+  }
+  const issueIdx = args.indexOf('--issue')
+  if (issueIdx !== -1) return loadFromIssue(args[issueIdx + 1])
+  return { error: 'usage: issue-readiness.mjs (--body-file <path> | --issue <n>) [--emit-comment]' }
+}
+
+function ghFailureDetail(r) {
+  if (r.error) return r.error.message
+  const stderr = (r.stderr ?? '').trim()
+  return stderr !== '' ? stderr : `exit ${r.status}`
+}
+
+function loadFromIssue(n) {
+  if (!n || !/^\d+$/.test(n)) return { error: '--issue requires a number' }
+  const r = spawnSync('gh', ['issue', 'view', n, '--json', 'body'], { encoding: 'utf-8' })
+  if (r.error || r.status !== 0) {
+    return { error: `gh issue view ${n} failed: ${ghFailureDetail(r)}` }
+  }
+  try {
+    return { body: JSON.parse(r.stdout).body ?? '' }
+    // FAIL-OPEN-INTENT: the error object is returned; main() surfaces it on stderr and exits 2 — fail-closed at the call site.
+  } catch {
+    return { error: `gh issue view ${n} returned unparseable JSON` }
+  }
+}
+
+function main() {
+  const args = process.argv.slice(2)
+  const loaded = loadBody(args)
+  if (loaded.error) {
+    process.stderr.write(`ERROR issue-readiness: ${loaded.error}\n`)
+    return 2
+  }
+  const verdict = assessReadiness(loaded.body)
+  console.log(JSON.stringify(verdict))
+  if (!verdict.ready && args.includes('--emit-comment')) {
+    console.log('---')
+    console.log(renderClarificationComment(verdict.missing))
+  }
+  return verdict.ready ? 0 : 1
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  try {
+    process.exit(main())
+  } catch (err) {
+    console.error(`ERROR issue-readiness: ${err instanceof Error ? err.message : String(err)}`)
+    process.exit(2)
+  }
+}

package/dist/templates/scripts/knowledge-map-update.mjs.ejs

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+// <%= projectName %> — knowledge-map updater
+// Utility: regenerate **Lines:** counts in KNOWLEDGE_MAP.md from actual doc sizes.
+// Exits 0 always (utility, not a gate).
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const CWD = process.cwd();
+const KM_FILE = join(CWD, 'docs', 'METHOD', 'KNOWLEDGE_MAP.md');
+
+if (!existsSync(KM_FILE)) {
+  console.log('  knowledge-map-update: no KNOWLEDGE_MAP.md found — skipping');
+  process.exit(0);
+}
+
+let content = readFileSync(KM_FILE, 'utf-8');
+
+const LOCATION_LINES_PATTERN = /(\*\*Location:\*\*\s+`([^`]+)`[^\n]*\n)(\*\*Lines:\*\*\s+\d+)/g;
+
+let updated = 0;
+content = content.replace(LOCATION_LINES_PATTERN, (match, locLine, filePath) => {
+  const abs = join(CWD, filePath);
+  if (!existsSync(abs)) return match;
+  const text = readFileSync(abs, 'utf-8');
+  const actual = text.split('\n').length - (text.endsWith('\n') ? 1 : 0);
+  updated++;
+  return `${locLine}**Lines:** ${actual}`;
+});
+
+writeFileSync(KM_FILE, content, 'utf-8');
+console.log(`  knowledge-map-update: updated ${updated} entry/entries in KNOWLEDGE_MAP.md`);
+process.exit(0);

package/dist/templates/scripts/lib/acceptance-criteria.mjs.ejs

@@ -0,0 +1,213 @@
+// SPDX-License-Identifier: Apache-2.0
+// acceptance-criteria.mjs — pure parsing/validation core for the acceptance-criteria
+// anchor (INV-138). No I/O, no process.exit: shared by scripts/issue-readiness.mjs
+// (orchestration-time entry gate), scripts/check-acceptance.mjs (L1 gate) and tests.
+//
+// Grammar:
+//   - Sections are markdown headings at any level (or bold-label lines) matching
+//     /acceptance criteria/i, /non-goals?/i, /(files|contracts|touch)/i — the shapes
+//     GitHub issue forms emit (`### Acceptance criteria`) included. CRLF normalized.
+//   - Criteria are checkbox bullets `- [ ] AC-N: text`. Explicit stable `AC-N:` ids are
+//     REQUIRED for readiness (bare checkboxes are a renumbering hazard: inserting one
+//     silently shifts every later id after tests/reviews already cite them). Bare
+//     checkboxes still parse (positional id, explicit:false) for display purposes.
+import { createHash } from 'node:crypto'
+
+export const AC_FIT_SCHEMA = 'arbiter-ac-fit-v1'
+const VERDICTS = new Set(['PASS', 'FAIL', 'NOT-TESTED'])
+
+// Template prefill lines that never count as task-specific criteria.
+const STOCK_CRITERIA = new Set([
+  'gate l1 passes',
+  'gate l2 passes',
+  'tests cover new behavior',
+  'criterion 1',
+  'criterion 2',
+])
+
+function sectionKind(headingText) {
+  const t = headingText.trim().toLowerCase()
+  if (/acceptance\s+criteria/.test(t)) return 'criteria'
+  if (/^non[-\s]?goals?\b/.test(t)) return 'nonGoals'
+  if (/\bfiles?\b|\bcontracts?\b|\btouch(?:es|ed)?\b|\bscope\b/.test(t)) return 'touches'
+  return 'other'
+}
+
+/** GitHub issue forms number labels ("6. Non-Goals") and may emphasize them — strip both. */
+function normalizeHeading(headingText) {
+  return headingText
+    .trim()
+    .replace(/^[*_]+|[*_]+$/g, '')
+    .replace(/^\d+[.)]\s*/, '')
+    .trim()
+}
+
+function normalizeText(text) {
+  return text.replace(/\s+/g, ' ').trim()
+}
+
+/** Parse AC checkboxes, non-goals and touches sections out of an issue/plan body. */
+export function parseAcceptanceBlocks(markdown) {
+  const lines = String(markdown ?? '')
+    .split('\r\n')
+    .join('\n')
+    .split('\n')
+  const criteria = []
+  const nonGoals = []
+  const touches = []
+  let current = 'other'
+  let inFence = false
+  for (const line of lines) {
+    // Fenced code blocks quote the grammar (docs, ADRs, skill examples) — never parse them.
+    if (/^\s*(```|~~~)/.test(line)) {
+      inFence = !inFence
+      continue
+    }
+    if (inFence) continue
+    const heading = /^#{1,6}\s+(.+?)\s*$/.exec(line) ?? /^\*\*(.+?)\*\*:?\s*$/.exec(line)
+    if (heading) {
+      current = sectionKind(normalizeHeading(heading[1]))
+      continue
+    }
+    if (current === 'criteria') parseCriterionLine(line, criteria)
+    else if (current === 'nonGoals') parseBulletLine(line, nonGoals)
+    else if (current === 'touches') parseBulletLine(line, touches)
+  }
+  return { criteria, nonGoals, touches }
+}
+
+function parseBulletLine(line, target) {
+  const bullet = /^\s*[-*]\s+(?:\[[ xX]\]\s*)?(.+)$/.exec(line)
+  if (bullet) target.push(normalizeText(bullet[1]))
+}
+
+function parseCriterionLine(line, criteria) {
+  const box = /^\s*[-*]\s*\[[ xX]\]\s*(.+)$/.exec(line)
+  if (!box) return
+  const body = box[1].trim()
+  // Explicit stable ids: AC-3, or wave-namespaced AC-123.1 / AC-123-1 (issue.criterion)
+  const explicit = /^AC-(\d+(?:[.-]\d+)?)\s*[:.–-]\s*(.*)$/.exec(body)
+  if (explicit) {
+    criteria.push({ id: `AC-${explicit[1]}`, text: normalizeText(explicit[2]), explicit: true })
+  } else {
+    criteria.push({ id: `AC-${criteria.length + 1}`, text: normalizeText(body), explicit: false })
+  }
+}
+
+function isStock(criterion) {
+  // Unreplaced template placeholders (`<observable behavior>`) are as generic as stock lines.
+  if (/<[^>]+>/.test(criterion.text)) return true
+  return STOCK_CRITERIA.has(criterion.text.toLowerCase().replace(/[.!]+$/, ''))
+}
+
+/**
+ * Entry-gate readiness: an issue is workable only when its target is written down —
+ * explicit AC-N criteria beyond the template stock lines, non-goals, and the
+ * files/contracts it touches. Anything less is `needs-clarification`, priced as a
+ * prompt BEFORE dispatch instead of a thrown-away PR after.
+ */
+export function assessReadiness(markdown) {
+  const { criteria, nonGoals, touches } = parseAcceptanceBlocks(markdown)
+  const missing = []
+  if (criteria.length === 0) {
+    missing.push('acceptance-criteria: no `- [ ] AC-N: <observable behavior>` checkbox found')
+  } else {
+    if (criteria.some((c) => !c.explicit)) {
+      missing.push('acceptance-criteria: every checkbox needs an explicit stable `AC-N:` id')
+    }
+    if (criteria.every(isStock)) {
+      missing.push('acceptance-criteria: only stock/template lines — add task-specific criteria')
+    }
+  }
+  if (nonGoals.length === 0) missing.push('non-goals: section missing or empty')
+  if (touches.length === 0) missing.push('files/contracts touched: section missing or empty')
+  return { ready: missing.length === 0, missing }
+}
+
+/** Markdown comment body posted on an issue that fails readiness. */
+export function renderClarificationComment(missing) {
+  return [
+    'This issue is not ready for a wave (`needs-clarification`).',
+    '',
+    'The "done right" target must live in the issue, not in anyone\'s head. Please add:',
+    '',
+    ...missing.map((m) => `- [ ] ${m}`),
+    '',
+    'Template: explicit `- [ ] AC-N: <observable behavior>` acceptance criteria,',
+    'a `Non-goals` section, and a `Files / contracts touched` section.',
+    'Once updated, remove the `needs-clarification` label to re-enter the queue.',
+  ].join('\n')
+}
+
+/** Read the frozen AC anchor out of a plan body; null when no anchor sections exist. */
+export function parsePlanAnchor(planBody) {
+  const { criteria, nonGoals } = parseAcceptanceBlocks(planBody)
+  if (criteria.length === 0 && nonGoals.length === 0) return null
+  return { criteria, nonGoals }
+}
+
+/** Stable hash of the frozen criteria (id + normalized text) — detects issue↔anchor drift. */
+export function computeAcHash(criteria) {
+  const canonical = criteria.map((c) => `${c.id}:${normalizeText(c.text)}`).join('\n')
+  return createHash('sha1').update(canonical, 'utf-8').digest('hex')
+}
+
+/**
+ * Validate an ac-fit evidence artifact against the plan's frozen criteria ids.
+ * Returns an error list (empty = valid). With `requireAllPass`, any non-PASS verdict
+ * is an error — the mechanical form of "unproven criterion = REJECT".
+ */
+function validateFitHeader(json, opts, errors) {
+  if (json.schema !== AC_FIT_SCHEMA) errors.push(`ac-fit: schema must be "${AC_FIT_SCHEMA}"`)
+  if (typeof json.taskId !== 'string' || json.taskId.length === 0) {
+    errors.push('ac-fit: missing taskId')
+  } else if (typeof opts.expectedTaskId === 'string' && json.taskId !== opts.expectedTaskId) {
+    errors.push(
+      `ac-fit: taskId "${json.taskId}" does not match the active task "${opts.expectedTaskId}" (stale artifact?)`,
+    )
+  }
+}
+
+function isUsableEvidence(e) {
+  return typeof e?.file === 'string' && e.file.length > 0 && Number.isInteger(e?.line) && e.line > 0
+}
+
+function validateFitVerdict(criterion, id, opts, errors) {
+  const verdict =
+    criterion === null || typeof criterion !== 'object' ? undefined : criterion.verdict
+  if (!VERDICTS.has(verdict)) errors.push(`criterion ${id}: invalid verdict "${verdict}"`)
+  const evidence = Array.isArray(criterion?.evidence) ? criterion.evidence : []
+  if (verdict === 'PASS' && !evidence.some(isUsableEvidence))
+    errors.push(`criterion ${id}: PASS without evidence (cite the diff/test line)`)
+  if (opts.requireAllPass && verdict !== 'PASS')
+    errors.push(`criterion ${id}: verdict ${verdict} is not PASS`)
+}
+
+function validateFitCriterion(c, seen, opts, errors) {
+  const id = typeof c?.id === 'string' ? c.id : '(missing id)'
+  if (seen.has(id)) errors.push(`criterion ${id}: duplicated in the ac-fit artifact`)
+  seen.add(id)
+  validateFitVerdict(c, id, opts, errors)
+}
+
+function validateFitCoverage(seen, planCriteriaIds, errors) {
+  for (const id of planCriteriaIds) {
+    if (!seen.has(id)) errors.push(`criterion ${id}: not covered by ac-fit artifact`)
+  }
+  for (const id of seen) {
+    if (!planCriteriaIds.includes(id))
+      errors.push(`criterion ${id}: unknown (not in the plan anchor)`)
+  }
+}
+
+export function validateAcFit(json, planCriteriaIds, opts = {}) {
+  const errors = []
+  if (typeof json !== 'object' || json === null) return ['ac-fit: not an object']
+  validateFitHeader(json, opts, errors)
+  const list = Array.isArray(json.criteria) ? json.criteria : []
+  if (!Array.isArray(json.criteria)) errors.push('ac-fit: criteria must be an array')
+  const seen = new Set()
+  for (const c of list) validateFitCriterion(c, seen, opts, errors)
+  validateFitCoverage(seen, planCriteriaIds, errors)
+  return errors
+}