@t275005746/gse 0.1.0

package/scripts/record-host-invocation.mjs

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+import fs from 'node:fs'
+import path from 'node:path'
+
+const args = process.argv.slice(2)
+
+function readArg(name, fallback = '') {
+  const index = args.indexOf(name)
+  if (index === -1) return fallback
+  return args[index + 1] ?? fallback
+}
+
+function hasArg(name) {
+  return args.includes(name)
+}
+
+const root = path.resolve(readArg('--root', path.join(import.meta.dirname, '..')))
+const host = readArg('--host')
+const hostVersion = readArg('--host-version', 'unknown')
+const project = readArg('--project', 'unknown')
+const adapterPath = readArg('--adapter-path', 'unknown')
+const invocationMethod = readArg('--invocation-method')
+const command = readArg('--command', '/gse help')
+const status = readArg('--status', 'verified')
+const startedAt = readArg('--started-at', new Date().toISOString())
+const finishedAt = readArg('--finished-at', startedAt)
+const evidenceOwner = readArg('--evidence-owner')
+const evidence = readArg('--evidence')
+const filesRead = readArg('--files-read', '')
+const filesWritten = readArg('--files-written', '')
+const verificationCommand = readArg('--verification-command', '')
+const nativeSlashCommand = readArg('--native-slash-command', 'unknown')
+const portableTextCommand = readArg('--portable-text-command', 'unknown')
+const generatedPointer = readArg('--generated-pointer', 'unknown')
+const ownerAcceptanceRequired = readArg('--owner-acceptance-required', 'unknown')
+const residualRisk = readArg('--residual-risk', '')
+const out = path.resolve(readArg('--out', path.join(root, '.gse', 'evidence', 'host-invocations', `${new Date().toISOString().slice(0, 10)}-${host || 'unknown'}-gse.md`)))
+const dryRun = hasArg('--dry-run')
+const force = hasArg('--force')
+const jsonOnly = hasArg('--json')
+
+const validStatuses = new Set(['result', 'verified', 'accepted', 'failed'])
+const validBooleans = new Set(['true', 'false', 'unknown'])
+const errors = []
+
+function requireField(value, message) {
+  if (!String(value).trim()) errors.push(message)
+}
+
+requireField(host, '--host is required')
+requireField(invocationMethod, '--invocation-method is required')
+requireField(evidenceOwner, '--evidence-owner is required')
+requireField(evidence, '--evidence is required')
+if (!validStatuses.has(status)) errors.push('--status must be result, verified, accepted, or failed')
+if (!validBooleans.has(nativeSlashCommand)) errors.push('--native-slash-command must be true, false, or unknown')
+if (!validBooleans.has(portableTextCommand)) errors.push('--portable-text-command must be true, false, or unknown')
+if (!validBooleans.has(generatedPointer)) errors.push('--generated-pointer must be true, false, or unknown')
+if (!validBooleans.has(ownerAcceptanceRequired)) errors.push('--owner-acceptance-required must be true, false, or unknown')
+if (nativeSlashCommand === 'true' && portableTextCommand === 'true') {
+  errors.push('native slash-command records cannot also claim portable text-command routing')
+}
+if (nativeSlashCommand === 'true' && generatedPointer === 'true') {
+  errors.push('native slash-command records cannot rely on a generated pointer file')
+}
+if (status === 'accepted' && ownerAcceptanceRequired !== 'false') {
+  errors.push('accepted host invocation records must set --owner-acceptance-required false')
+}
+if (status === 'accepted' && !verificationCommand.trim()) {
+  errors.push('accepted host invocation records must include --verification-command')
+}
+if (status === 'accepted' && generatedPointer === 'true') {
+  errors.push('accepted host invocation records must not rely on a generated pointer file')
+}
+
+const lines = [
+  '# Host UI Invocation Record',
+  '',
+  '## Host',
+  '',
+  '- Host name: ' + host,
+  '- Host version: ' + hostVersion,
+  '- Project: ' + project,
+  '- Adapter path: ' + adapterPath,
+  '- Invocation method: ' + invocationMethod,
+  '',
+  '## Command',
+  '',
+  '```text',
+  command,
+  '```',
+  '',
+  '## Result',
+  '',
+  '- Status: ' + status,
+  '- Started at: ' + startedAt,
+  '- Finished at: ' + finishedAt,
+  '- Evidence owner: ' + evidenceOwner,
+  '',
+  '## Evidence',
+  '',
+  '- Screenshot, transcript, thread id, terminal output, or host log: ' + evidence,
+  '- Files read by the host: ' + filesRead,
+  '- Files written by the host: ' + filesWritten,
+  '- Verification command: ' + verificationCommand,
+  '',
+  '## Boundaries',
+  '',
+  '- Does this prove native slash-command support? ' + nativeSlashCommand,
+  '- Does this prove portable text-command routing only? ' + portableTextCommand,
+  '- Does this rely on a generated pointer file? ' + generatedPointer,
+  '- Does this require owner acceptance before being called trusted? ' + ownerAcceptanceRequired,
+  '',
+  '## Residual Risk',
+  '',
+  '- ' + residualRisk,
+  '',
+]
+
+const report = {
+  root,
+  out,
+  dryRun,
+  status: errors.length ? 'failed' : dryRun ? 'ready' : 'written',
+  host,
+  invocationStatus: status,
+  nativeSlashCommand,
+  portableTextCommand,
+  errors,
+}
+
+if (!errors.length && !dryRun) {
+  if (fs.existsSync(out) && !force) {
+    report.status = 'exists'
+    report.errors.push('output exists; use --force or choose another --out path')
+  } else {
+    fs.mkdirSync(path.dirname(out), { recursive: true })
+    fs.writeFileSync(out, lines.join('\n'), 'utf8')
+  }
+}
+
+if (jsonOnly) console.log(JSON.stringify(report, null, 2))
+else {
+  console.log('Host invocation record status: ' + report.status)
+  console.log('Output: ' + report.out)
+  if (report.errors.length) {
+    console.log('Errors:')
+    for (const error of report.errors) console.log('- ' + error)
+  }
+}
+
+if (report.status === 'failed' || report.status === 'exists') process.exit(1)

package/scripts/record-learning.mjs

@@ -0,0 +1,137 @@
+#!/usr/bin/env node
+import fs from 'node:fs'
+import path from 'node:path'
+
+const args = process.argv.slice(2)
+
+function readArg(name, fallback = null) {
+  const index = args.indexOf(name)
+  if (index === -1) return fallback
+  return args[index + 1] ?? fallback
+}
+
+function clean(value) {
+  return String(value ?? '').replace(/\s+/g, ' ').trim()
+}
+
+function normalize(value) {
+  return clean(value).toLowerCase()
+}
+
+function slugify(value) {
+  return clean(value)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 48) || 'learning'
+}
+
+function today() {
+  return new Date().toISOString().slice(0, 10)
+}
+
+const target = path.resolve(readArg('--target', process.cwd()))
+const summary = clean(readArg('--summary', ''))
+const trigger = clean(readArg('--trigger', 'reusable lesson'))
+const source = clean(readArg('--source', 'manual'))
+const impact = clean(readArg('--impact', ''))
+const promotion = clean(readArg('--promotion', 'first occurrence: learning note'))
+const date = clean(readArg('--date', today()))
+const execute = args.includes('--execute')
+const jsonOnly = args.includes('--json')
+const gseDir = path.join(target, '.gse')
+const learningsPath = path.join(gseDir, 'learnings.md')
+
+function report(data) {
+  if (jsonOnly) console.log(JSON.stringify(data, null, 2))
+  else {
+    console.log('Status: ' + data.status)
+    console.log('Target: ' + data.target)
+    if (data.path) console.log('Path: ' + data.path)
+    if (data.reason) console.log('Reason: ' + data.reason)
+  }
+}
+
+if (!summary) {
+  report({
+    status: 'waiting-for-input',
+    target,
+    required: ['--summary <reusable lesson>'],
+    optional: ['--trigger <why captured>', '--source <where learned>', '--impact <what it prevents>', '--promotion <upgrade rule>'],
+    effect: 'dry-run by default; add --execute to write .gse/learnings.md',
+  })
+  process.exit(0)
+}
+
+if (!fs.existsSync(gseDir) || !fs.statSync(gseDir).isDirectory()) {
+  report({
+    status: 'failed',
+    target,
+    reason: 'target does not contain a .gse directory; initialize or adopt GSE before recording learnings',
+  })
+  process.exit(1)
+}
+
+const existing = fs.existsSync(learningsPath) ? fs.readFileSync(learningsPath, 'utf8').replace(/^\uFEFF/, '') : '# Learnings\n\n'
+const duplicate = existing
+  .split(/\r?\n/)
+  .some((line) => line.trim().startsWith('- Summary:') && normalize(line.replace(/^- Summary:\s*/, '')) === normalize(summary))
+
+const relativePath = path.relative(target, learningsPath).replace(/\\/g, '/')
+const entry = [
+  '## ' + date + ' - ' + slugify(summary),
+  '',
+  '- Trigger: ' + trigger,
+  '- Summary: ' + summary,
+  '- Source: ' + source,
+  '- Impact: ' + (impact || 'helps future agents avoid repeating the same failure or decision drift'),
+  '- Promotion: ' + promotion,
+  '- Status: learning-note',
+  '',
+].join('\n')
+
+if (duplicate) {
+  report({
+    status: 'skipped',
+    target,
+    path: relativePath,
+    summary,
+    reason: 'duplicate summary already exists',
+    evidenceStatus: 'verified',
+  })
+  process.exit(0)
+}
+
+if (!execute) {
+  report({
+    status: 'ready',
+    target,
+    path: relativePath,
+    summary,
+    trigger,
+    source,
+    impact: impact || null,
+    promotion,
+    dryRun: true,
+    effect: 'add --execute to append the learning entry',
+    preview: entry,
+  })
+  process.exit(0)
+}
+
+fs.mkdirSync(gseDir, { recursive: true })
+const prefix = existing.endsWith('\n') ? existing : existing + '\n'
+fs.writeFileSync(learningsPath, prefix + (prefix.endsWith('\n\n') ? '' : '\n') + entry, 'utf8')
+
+report({
+  status: 'written',
+  target,
+  path: relativePath,
+  summary,
+  trigger,
+  source,
+  impact: impact || null,
+  promotion,
+  dryRun: false,
+  evidenceStatus: 'verified',
+})

package/scripts/record-public-channel-publication.mjs

@@ -0,0 +1,178 @@
+#!/usr/bin/env node
+import fs from 'node:fs'
+import path from 'node:path'
+import { rejectPlaceholderEvidence } from './lib/evidence-placeholders.mjs'
+
+const args = process.argv.slice(2)
+
+function readArg(name, fallback = '') {
+  const index = args.indexOf(name)
+  if (index === -1) return fallback
+  return args[index + 1] ?? fallback
+}
+
+function hasArg(name) {
+  return args.includes(name)
+}
+
+const root = path.resolve(readArg('--root', path.join(import.meta.dirname, '..')))
+const publicationStatus = readArg('--publication-status', 'pending')
+const channelType = readArg('--channel-type', 'unknown')
+const channelName = readArg('--channel-name', '')
+const channelUrl = readArg('--channel-url', '')
+const version = readArg('--version', '')
+const artifactDigest = readArg('--artifact-digest', '')
+const reviewStatus = readArg('--review-status', 'pending')
+const evidenceOwner = readArg('--evidence-owner', '')
+const evidenceDate = readArg('--evidence-date', '')
+const evidenceUrl = readArg('--evidence-url', '')
+const verificationCommand = readArg('--verification-command', 'node scripts/validate-gse.mjs --root . --json')
+const verificationResult = readArg('--verification-result', 'pending')
+const evidenceStatus = readArg('--evidence-status', publicationStatus === 'accepted' ? 'accepted' : 'pending')
+const acceptedBy = readArg('--accepted-by', '')
+const acceptedAt = readArg('--accepted-at', '')
+const provesRegistryPublication = readArg('--proves-registry-publication', 'unknown')
+const provesMarketplaceApproval = readArg('--proves-marketplace-approval', 'unknown')
+const provesChannelInstallability = readArg('--proves-channel-installability', 'unknown')
+const residualRisk = readArg('--residual-risk', 'Public channel publication is not accepted until real external evidence is attached.')
+const nextAction = readArg('--next-action', 'Attach public channel publication evidence and re-run final readiness.')
+const out = path.resolve(readArg('--out', path.join(root, '.gse', 'releases', 'public-channel-publication-pending.md')))
+const dryRun = hasArg('--dry-run')
+const force = hasArg('--force')
+const jsonOnly = hasArg('--json')
+
+const validStatuses = new Set(['pending', 'accepted'])
+const validChannelTypes = new Set(['github-release', 'package-registry', 'marketplace', 'catalog', 'other', 'unknown'])
+const validTriState = new Set(['true', 'false', 'unknown'])
+const errors = []
+
+function requireField(value, message) {
+  if (!String(value).trim()) errors.push(message)
+}
+
+if (!validStatuses.has(publicationStatus)) errors.push('--publication-status must be pending or accepted')
+if (!validStatuses.has(evidenceStatus)) errors.push('--evidence-status must be pending or accepted')
+if (!validChannelTypes.has(channelType)) errors.push('--channel-type must be github-release, package-registry, marketplace, catalog, other, or unknown')
+for (const [value, name] of [
+  [provesRegistryPublication, '--proves-registry-publication'],
+  [provesMarketplaceApproval, '--proves-marketplace-approval'],
+  [provesChannelInstallability, '--proves-channel-installability'],
+]) {
+  if (!validTriState.has(value)) errors.push(`${name} must be true, false, or unknown`)
+}
+
+if (publicationStatus === 'accepted') {
+  if (channelType === 'unknown') errors.push('accepted publication requires --channel-type')
+  requireField(channelName, 'accepted publication requires --channel-name')
+  requireField(channelUrl, 'accepted publication requires --channel-url')
+  requireField(version, 'accepted publication requires --version')
+  requireField(evidenceOwner, 'accepted publication requires --evidence-owner')
+  requireField(evidenceDate, 'accepted publication requires --evidence-date')
+  requireField(evidenceUrl, 'accepted publication requires --evidence-url')
+  requireField(acceptedBy, 'accepted publication requires --accepted-by')
+  requireField(acceptedAt, 'accepted publication requires --accepted-at')
+  if (evidenceStatus !== 'accepted') errors.push('accepted publication requires --evidence-status accepted')
+  if (reviewStatus !== 'approved' && reviewStatus !== 'published') errors.push('accepted publication requires --review-status approved or published')
+  if (!dryRun) {
+    rejectPlaceholderEvidence(errors, channelName, '--channel-name')
+    rejectPlaceholderEvidence(errors, channelUrl, '--channel-url')
+    rejectPlaceholderEvidence(errors, evidenceOwner, '--evidence-owner')
+    rejectPlaceholderEvidence(errors, evidenceUrl, '--evidence-url')
+    rejectPlaceholderEvidence(errors, acceptedBy, '--accepted-by')
+  }
+  if (channelType === 'package-registry') {
+    requireField(artifactDigest, 'accepted package-registry publication requires --artifact-digest')
+    if (provesRegistryPublication !== 'true') errors.push('accepted package-registry publication requires --proves-registry-publication true')
+    if (provesChannelInstallability !== 'true') errors.push('accepted package-registry publication requires --proves-channel-installability true')
+  }
+  if (channelType === 'marketplace' || channelType === 'catalog') {
+    if (provesMarketplaceApproval !== 'true') errors.push('accepted marketplace/catalog publication requires --proves-marketplace-approval true')
+    if (provesChannelInstallability !== 'true') errors.push('accepted marketplace/catalog publication requires --proves-channel-installability true')
+  }
+}
+
+const lines = [
+  '# Public Channel Publication Record',
+  '',
+  'Publication status: ' + publicationStatus,
+  '',
+  'Channel type: ' + channelType,
+  '',
+  'Channel name: ' + channelName,
+  '',
+  'Channel URL: ' + channelUrl,
+  '',
+  'Package or listing version: ' + version,
+  '',
+  'Artifact digest: ' + artifactDigest,
+  '',
+  'Review or approval status: ' + reviewStatus,
+  '',
+  'Evidence owner: ' + evidenceOwner,
+  '',
+  'Evidence date: ' + evidenceDate,
+  '',
+  'Evidence URL or run id: ' + evidenceUrl,
+  '',
+  '## Verification',
+  '',
+  'Verification command: ' + verificationCommand,
+  '',
+  'Verification result: ' + verificationResult,
+  '',
+  '## Acceptance',
+  '',
+  'Evidence status: ' + evidenceStatus,
+  '',
+  'Accepted by: ' + acceptedBy,
+  '',
+  'Accepted at: ' + acceptedAt,
+  '',
+  '## Boundaries',
+  '',
+  '- Does this prove public registry publication? ' + provesRegistryPublication,
+  '- Does this prove marketplace approval? ' + provesMarketplaceApproval,
+  '- Does this prove installability from the channel? ' + provesChannelInstallability,
+  '',
+  '## Residual Risk',
+  '',
+  '- ' + residualRisk,
+  '',
+  '## Next Action',
+  '',
+  '- ' + nextAction,
+  '',
+]
+
+const report = {
+  root,
+  out,
+  dryRun,
+  publicationStatus,
+  channelType,
+  evidenceStatus,
+  status: errors.length ? 'failed' : dryRun ? 'ready' : 'written',
+  errors,
+}
+
+if (!errors.length && !dryRun) {
+  if (fs.existsSync(out) && !force) {
+    report.status = 'exists'
+    report.errors.push('output exists; use --force or choose another --out path')
+  } else {
+    fs.mkdirSync(path.dirname(out), { recursive: true })
+    fs.writeFileSync(out, lines.join('\n'), 'utf8')
+  }
+}
+
+if (jsonOnly) console.log(JSON.stringify(report, null, 2))
+else {
+  console.log('Public channel publication record status: ' + report.status)
+  console.log('Output: ' + report.out)
+  if (report.errors.length) {
+    console.log('Errors:')
+    for (const error of report.errors) console.log('- ' + error)
+  }
+}
+
+if (report.status === 'failed' || report.status === 'exists') process.exit(1)

package/scripts/record-public-ci-run.mjs

@@ -0,0 +1,180 @@
+#!/usr/bin/env node
+import fs from 'node:fs'
+import path from 'node:path'
+import { rejectPlaceholderEvidence } from './lib/evidence-placeholders.mjs'
+
+const args = process.argv.slice(2)
+
+function readArg(name, fallback = '') {
+  const index = args.indexOf(name)
+  if (index === -1) return fallback
+  return args[index + 1] ?? fallback
+}
+
+function hasArg(name) {
+  return args.includes(name)
+}
+
+const root = path.resolve(readArg('--root', path.join(import.meta.dirname, '..')))
+const runStatus = readArg('--run-status', 'pending')
+const runConclusion = readArg('--run-conclusion', 'pending')
+const repositoryUrl = readArg('--repository-url', '')
+const workflowName = readArg('--workflow-name', 'Validate GSE')
+const workflowFile = readArg('--workflow-file', '.github/workflows/validate-gse.yml')
+const runUrl = readArg('--run-url', '')
+const commitSha = readArg('--commit-sha', '')
+const branch = readArg('--branch', '')
+const requiredChecks = readArg('--required-checks', '')
+const evidenceOwner = readArg('--evidence-owner', '')
+const evidenceDate = readArg('--evidence-date', '')
+const evidenceUrl = readArg('--evidence-url', '')
+const verificationCommand = readArg('--verification-command', 'node scripts/validate-gse.mjs --root . --json')
+const verificationResult = readArg('--verification-result', 'pending')
+const evidenceStatus = readArg('--evidence-status', runStatus === 'accepted' ? 'accepted' : 'pending')
+const acceptedBy = readArg('--accepted-by', '')
+const acceptedAt = readArg('--accepted-at', '')
+const provesPublicCiRun = readArg('--proves-public-ci-run', 'unknown')
+const provesRequiredChecks = readArg('--proves-required-checks', 'unknown')
+const provesReleaseCommit = readArg('--proves-release-commit', 'unknown')
+const residualRisk = readArg('--residual-risk', 'Public CI run is not accepted until real external run evidence is attached.')
+const nextAction = readArg('--next-action', 'Attach public CI run evidence and re-run final readiness.')
+const out = path.resolve(readArg('--out', path.join(root, '.gse', 'releases', 'public-ci-run-pending.md')))
+const dryRun = hasArg('--dry-run')
+const force = hasArg('--force')
+const jsonOnly = hasArg('--json')
+
+const validStatuses = new Set(['pending', 'accepted'])
+const validConclusions = new Set(['pending', 'success', 'failure', 'cancelled', 'skipped', 'timed_out', 'unknown'])
+const validTriState = new Set(['true', 'false', 'unknown'])
+const errors = []
+
+function requireField(value, message) {
+  if (!String(value).trim()) errors.push(message)
+}
+
+if (!validStatuses.has(runStatus)) errors.push('--run-status must be pending or accepted')
+if (!validStatuses.has(evidenceStatus)) errors.push('--evidence-status must be pending or accepted')
+if (!validConclusions.has(runConclusion)) errors.push('--run-conclusion must be pending, success, failure, cancelled, skipped, timed_out, or unknown')
+for (const [value, name] of [
+  [provesPublicCiRun, '--proves-public-ci-run'],
+  [provesRequiredChecks, '--proves-required-checks'],
+  [provesReleaseCommit, '--proves-release-commit'],
+]) {
+  if (!validTriState.has(value)) errors.push(`${name} must be true, false, or unknown`)
+}
+
+if (runStatus === 'accepted') {
+  requireField(repositoryUrl, 'accepted CI run requires --repository-url')
+  requireField(workflowName, 'accepted CI run requires --workflow-name')
+  requireField(workflowFile, 'accepted CI run requires --workflow-file')
+  requireField(runUrl, 'accepted CI run requires --run-url')
+  requireField(commitSha, 'accepted CI run requires --commit-sha')
+  requireField(branch, 'accepted CI run requires --branch')
+  requireField(requiredChecks, 'accepted CI run requires --required-checks')
+  requireField(evidenceOwner, 'accepted CI run requires --evidence-owner')
+  requireField(evidenceDate, 'accepted CI run requires --evidence-date')
+  requireField(evidenceUrl, 'accepted CI run requires --evidence-url')
+  requireField(acceptedBy, 'accepted CI run requires --accepted-by')
+  requireField(acceptedAt, 'accepted CI run requires --accepted-at')
+  if (runConclusion !== 'success') errors.push('accepted CI run requires --run-conclusion success')
+  if (evidenceStatus !== 'accepted') errors.push('accepted CI run requires --evidence-status accepted')
+  if (provesPublicCiRun !== 'true') errors.push('accepted CI run requires --proves-public-ci-run true')
+  if (provesRequiredChecks !== 'true') errors.push('accepted CI run requires --proves-required-checks true')
+  if (!dryRun) {
+    rejectPlaceholderEvidence(errors, repositoryUrl, '--repository-url')
+    rejectPlaceholderEvidence(errors, runUrl, '--run-url')
+    rejectPlaceholderEvidence(errors, evidenceOwner, '--evidence-owner')
+    rejectPlaceholderEvidence(errors, evidenceUrl, '--evidence-url')
+    rejectPlaceholderEvidence(errors, acceptedBy, '--accepted-by')
+  }
+}
+
+const lines = [
+  '# Public CI Run Record',
+  '',
+  'Repository URL: ' + repositoryUrl,
+  '',
+  'Workflow name: ' + workflowName,
+  '',
+  'Workflow file: ' + workflowFile,
+  '',
+  'Run URL: ' + runUrl,
+  '',
+  'Run status: ' + runStatus,
+  '',
+  'Run conclusion: ' + runConclusion,
+  '',
+  'Commit SHA: ' + commitSha,
+  '',
+  'Branch: ' + branch,
+  '',
+  'Required checks: ' + requiredChecks,
+  '',
+  'Evidence owner: ' + evidenceOwner,
+  '',
+  'Evidence date: ' + evidenceDate,
+  '',
+  'Evidence URL or run id: ' + evidenceUrl,
+  '',
+  '## Verification',
+  '',
+  'Verification command: ' + verificationCommand,
+  '',
+  'Verification result: ' + verificationResult,
+  '',
+  '## Acceptance',
+  '',
+  'Evidence status: ' + evidenceStatus,
+  '',
+  'Accepted by: ' + acceptedBy,
+  '',
+  'Accepted at: ' + acceptedAt,
+  '',
+  '## Boundaries',
+  '',
+  '- Does this prove a public CI run? ' + provesPublicCiRun,
+  '- Does this prove required checks passed? ' + provesRequiredChecks,
+  '- Does this prove the current release commit? ' + provesReleaseCommit,
+  '',
+  '## Residual Risk',
+  '',
+  '- ' + residualRisk,
+  '',
+  '## Next Action',
+  '',
+  '- ' + nextAction,
+  '',
+]
+
+const report = {
+  root,
+  out,
+  dryRun,
+  runStatus,
+  runConclusion,
+  evidenceStatus,
+  status: errors.length ? 'failed' : dryRun ? 'ready' : 'written',
+  errors,
+}
+
+if (!errors.length && !dryRun) {
+  if (fs.existsSync(out) && !force) {
+    report.status = 'exists'
+    report.errors.push('output exists; use --force or choose another --out path')
+  } else {
+    fs.mkdirSync(path.dirname(out), { recursive: true })
+    fs.writeFileSync(out, lines.join('\n'), 'utf8')
+  }
+}
+
+if (jsonOnly) console.log(JSON.stringify(report, null, 2))
+else {
+  console.log('Public CI run record status: ' + report.status)
+  console.log('Output: ' + report.out)
+  if (report.errors.length) {
+    console.log('Errors:')
+    for (const error of report.errors) console.log('- ' + error)
+  }
+}
+
+if (report.status === 'failed' || report.status === 'exists') process.exit(1)