opstruth 0.1.2 → 0.2.0

package/README.md

@@ -6,13 +6,16 @@ Read-only operational truth checks for AI-assisted engineering workflows.
 
 ## Install
 
-After npm publication:
+Current published package:
 
 ```bash
 npm install -g opstruth
 opstruth
 ```
 
+The latest published npm package is `opstruth@0.1.3`. This source package is prepared for
+`opstruth@0.2.0`, pending an authenticated npm publish.
+
 One-off usage:
 
 ```bash
@@ -24,17 +27,28 @@ npx opstruth
 ```bash
 opstruth
 opstruth welcome
+opstruth init --yes
+opstruth repo
+opstruth quality
+opstruth github-ci --workflow CI
 opstruth probes
 opstruth secrets
 opstruth routes --base-url https://example.com
 opstruth local --port 3000 --health /health
+opstruth supabase
+opstruth supabase-live --evidence-file <redacted.json>
+opstruth supabase-live --telemetry-file /tmp/opstruth-supabase-telemetry.json
+opstruth cloudflare
+opstruth evidence
+opstruth --json
+opstruth --no-color
 ```
 
 ## Terminal Output
 
 Human output uses a restrained colour theme for status, warnings, proof gaps, evidence, and next safe steps when the terminal supports ANSI colour.
 
-Use `--no-color` or `NO_COLOR=1` to disable colour. Use `--color` to force colour for demos. JSON output remains machine-readable and does not include ANSI codes.
+Use `--no-color` or `NO_COLOR=1` to disable colour. Use `--color` to force colour for demos. JSON output remains machine-readable and does not include ANSI codes. Evidence markdown output remains ANSI-free.
 
 ## Safety Model
 
@@ -42,6 +56,16 @@ opstruth is read-only by default. CLI checks do not deploy, mutate databases, tr
 
 Skipped checks and not-verified areas are reported as proof gaps instead of being treated as safe.
 
+## Configuration
+
+`opstruth.config.json` can provide route paths, local ports/health paths, and secret allowlists. Generate a starter config:
+
+```bash
+opstruth init --yes
+```
+
+CLI flags remain the clearest way to provide runtime inputs.
+
 ## Repository
 
 Source, docs, and release evidence live at:

package/examples/supabase-live-redacted-evidence.json

@@ -0,0 +1,78 @@
+{
+  "schemaVersion": "opstruth.supabase-live.v1",
+  "collectedAt": "2026-06-28T10:00:00.000Z",
+  "repositoryCommit": "example-short-sha",
+  "functionName": "import-reddit-tips",
+  "schedulerJob": "import-reddit-tips-daily",
+  "evidenceSource": "redacted local operator evidence",
+  "manualOrAutonomous": "autonomous",
+  "signals": {
+    "function_deployed": {
+      "state": "verified",
+      "summary": "Function deployment metadata was observed."
+    },
+    "secret_name_configured": {
+      "state": "verified",
+      "summary": "Secret name presence was observed; secret value was not inspected."
+    },
+    "missing_credential_denial": {
+      "state": "verified",
+      "summary": "Missing credential denial was observed."
+    },
+    "incorrect_credential_denial": {
+      "state": "verified",
+      "summary": "Incorrect credential denial was observed."
+    },
+    "authorised_noop": {
+      "state": "verified",
+      "summary": "Authorised no-op response was observed with zero inserts."
+    },
+    "scheduler_configured": {
+      "state": "verified",
+      "summary": "One intended scheduler job was observed."
+    },
+    "scheduler_autonomous_execution": {
+      "state": "verified",
+      "summary": "Autonomous scheduler run history was observed."
+    },
+    "telemetry_count_only": {
+      "state": "not_verified",
+      "summary": "Filtered production function logs were not available."
+    },
+    "non_admin_authorization": {
+      "state": "authentication_unavailable",
+      "summary": "No safe existing non-admin identity was available."
+    },
+    "admin_authorization": {
+      "state": "authentication_unavailable",
+      "summary": "No safe existing admin identity was available."
+    },
+    "rate_limit": {
+      "state": "unsafe_to_test",
+      "summary": "Testing would update production rate-limit state."
+    },
+    "database_effects": {
+      "state": "verified",
+      "summary": "Scoped count-only database effects were observed."
+    }
+  },
+  "databaseScope": {
+    "tables": [
+      "pet_tips"
+    ],
+    "rowCountsOnly": true,
+    "rowsDumped": false
+  },
+  "redactionsApplied": [
+    "project reference omitted",
+    "credential headers omitted",
+    "raw logs omitted",
+    "scheduler payload omitted"
+  ],
+  "notVerified": [
+    "function log telemetry",
+    "non-admin credential branch",
+    "admin credential branch",
+    "rate-limit recovery"
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opstruth",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Read-only operational truth checks for AI-assisted engineering workflows.",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -11,13 +11,15 @@ import { runCloudflare } from './commands/cloudflare.js';
 import { runLocal } from './commands/local.js';
 import { runEvidence } from './commands/evidence.js';
 import { runProbes } from './commands/probes.js';
+import { runGitHubCi } from './commands/github-ci.js';
+import { runSupabaseLive } from './commands/supabase-live.js';
 import { resultToMarkdown } from './lib/markdown.js';
 import { formatTerminalOutput } from './lib/terminal.js';
 import { writeFileSafe } from './lib/fs.js';
 import { redactObject } from './lib/redact.js';
 import { exitCodeFor } from './lib/result.js';
 
-const COMMANDS = new Set(['repo', 'quality', 'routes', 'secrets', 'supabase', 'cloudflare', 'local', 'evidence', 'probes', 'welcome', 'init']);
+const COMMANDS = new Set(['repo', 'quality', 'routes', 'secrets', 'supabase', 'supabase-live', 'cloudflare', 'local', 'github-ci', 'evidence', 'probes', 'welcome', 'init']);
 function take(args, index) { return args[index + 1]; }
 export function parseArgs(argv) {
   const options = { skip: [], only: [], port: [], protectedTable: [], include: [] };
@@ -49,6 +51,10 @@ export function parseArgs(argv) {
     else if (arg === '--process') options.process = take(argv, i++);
     else if (arg === '--service') options.service = take(argv, i++);
     else if (arg === '--script') { options.scripts ||= []; options.scripts.push(take(argv, i++)); }
+    else if (arg === '--github-ci') options.githubCi = true;
+    else if (arg === '--workflow') options.workflow = take(argv, i++);
+    else if (arg === '--evidence-file') options.evidenceFile = take(argv, i++);
+    else if (arg === '--telemetry-file') options.telemetryFile = take(argv, i++);
   }
   if (!options.protectedTable.length) delete options.protectedTable;
   return { command, options };
@@ -62,8 +68,10 @@ async function dispatch(command, options) {
   if (command === 'routes') return runRoutes(options);
   if (command === 'secrets') return runSecrets(options);
   if (command === 'supabase') return runSupabase(options);
+  if (command === 'supabase-live') return runSupabaseLive(options);
   if (command === 'cloudflare') return runCloudflare(options);
   if (command === 'local') return runLocal(options);
+  if (command === 'github-ci') return runGitHubCi(options);
   if (command === 'evidence') return runEvidence(options);
   if (command === 'probes') return runProbes(options);
   throw new Error('Unknown command: ' + command);
@@ -100,8 +108,10 @@ function helpText(command) {
     '  routes       Probe configured HTTP routes with HEAD/GET',
     '  secrets      Scan source for risky references with redaction',
     '  supabase     Static Supabase safety checks',
+    '  supabase-live Validate redacted Supabase production evidence',
     '  cloudflare   Static Cloudflare/Wrangler checks',
     '  local        Check explicit local ports/processes/services',
+    '  github-ci    Read GitHub Actions metadata for the exact local commit',
     '  evidence     Write a markdown evidence pack',
     '  probes       Inspect the stack-aware probe catalogue',
     '',
@@ -115,34 +125,45 @@ function helpText(command) {
     '  --no-color          Disable colour for human terminal output',
     '  -h, --help          Print help and exit 0'
   ];
-  const route = [
-    ASCII_HEADER,
-    'Usage: opstruth routes --base-url <url> [--routes file] [--strict]',
-    '',
-    'Read-only route probes collect URL, method, status, latency, redirects, and security-header evidence.',
-    '',
-    'Options:',
-    '  --base-url <url>    Base URL to probe',
-    '  --routes <file>     JSON route config',
-    '  --json              Print JSON output',
-    '  --color             Force colour for human terminal output',
-    '  --no-color          Disable colour for human terminal output',
-    '  -h, --help          Print help and exit 0'
-  ];
-  const repo = [
-    ASCII_HEADER,
-    'Usage: opstruth repo [--json] [--strict]',
-    '',
-    'Read-only repository inspection reports cwd, git root, branch, latest commit, dirty files, and detected stack.',
-    '',
-    'Options:',
-    '  --json              Print JSON output',
-    '  --color             Force colour for human terminal output',
-    '  --no-color          Disable colour for human terminal output',
-    '  -h, --help          Print help and exit 0'
-  ];
-  if (command === 'routes') return route.join('\n') + '\n';
-  if (command === 'repo') return repo.join('\n') + '\n';
+  const commandHelp = {
+    repo: ['Usage: opstruth repo [--json] [--strict]', 'Inspect cwd, git root, branch, latest commit, dirty files, and detected stack.'],
+    quality: ['Usage: opstruth quality [--script name] [--continue] [--json]', 'Run only existing safe package scripts; missing scripts and npm placeholder tests are skipped.'],
+    routes: ['Usage: opstruth routes --base-url <url> [--routes file] [--json]', 'Collect read-only URL, method, status, latency, redirect, and header evidence.'],
+    secrets: ['Usage: opstruth secrets [--json]', 'Scan source text for risky secret/auth references with redacted previews; .env contents are skipped.'],
+    supabase: ['Usage: opstruth supabase [--protected-table name] [--frontend-dir dir] [--migrations-dir dir]', 'Run a static Supabase migration/frontend exposure audit without credentials or database calls.'],
+    'supabase-live': ['Usage: opstruth supabase-live --evidence-file <redacted.json> [--telemetry-file /tmp/redacted-provider-output.json] [--json]', 'Validate explicit redacted Supabase production evidence without credentials, mutation, or network calls.'],
+    cloudflare: ['Usage: opstruth cloudflare [--url https://example.com] [--json]', 'Inspect Wrangler config, deploy scripts, and optional read-only route status; no deploy is run.'],
+    local: ['Usage: opstruth local --port 3000 [--health /health] [--process name] [--service name]', 'Check explicit local runtime inputs without starting, stopping, or killing services.'],
+    'github-ci': ['Usage: opstruth github-ci [--workflow CI] [--json]', 'Read GitHub Actions run metadata for the exact local commit. No logs, deploys, or production calls are made.'],
+    probes: ['Usage: opstruth probes [--json] [--only area|id] [--skip area|id]', 'Inspect probe catalogue metadata, eligible probes, skipped probes, required inputs, and proof gaps.'],
+    evidence: ['Usage: opstruth evidence [--title text] [--out evidence/opstruth.md] [--include file]', 'Write a markdown evidence pack with verified facts, proof gaps, boundaries, and next safe step.'],
+    init: ['Usage: opstruth init [--yes]', 'Create a safe starter opstruth.config.json after confirmation.']
+  };
+  if (commandHelp[command]) {
+    const [usage, description] = commandHelp[command];
+    return [
+      ASCII_HEADER,
+      usage,
+      '',
+      description,
+      '',
+      'Examples:',
+      '  opstruth',
+      '  opstruth --base-url https://example.com',
+      '  opstruth routes --base-url https://example.com',
+      '  opstruth local --port 3000 --health /health',
+      '  opstruth --json',
+      '  opstruth --no-color',
+      '  opstruth --color',
+      '',
+      'Options:',
+      '  --json              Print JSON output',
+      '  --strict            Treat warnings/skips as failing confidence',
+      '  --color             Force colour for human terminal output',
+      '  --no-color          Disable colour for human terminal output',
+      '  -h, --help          Print help and exit 0'
+    ].join('\n') + '\n';
+  }
   return common.join('\n') + '\n';
 }
 
@@ -165,8 +186,17 @@ function welcomeText() {
     '- opstruth --strict',
     '- opstruth routes --base-url https://example.com',
     '- opstruth local --port 3000 --health /health',
+    '- opstruth --json',
+    '- opstruth --no-color',
+    '- opstruth --color',
     '- opstruth evidence --title "Release proof"',
     '',
+    'Improving confidence:',
+    '- provide --base-url or route config when route proof matters',
+    '- provide --port and --health when local runtime proof matters',
+    '- run inside a git repo for stronger change evidence',
+    '- attach evidence/opstruth-report.md to reviews or CI artifacts',
+    '',
     'Safety philosophy:',
     'opstruth prefers skipped or not verified over pretending something is safe. Dangerous actions require explicit approval and are not part of the default run.',
     ''
@@ -174,27 +204,34 @@ function welcomeText() {
 }
 
 const INIT_CONFIG = {
-  routes: {
-    baseUrl: '',
-    paths: ['/', '/login', '/healthz'],
-    requiredHeaders: [
-      'content-security-policy',
-      'strict-transport-security',
-      'x-frame-options',
-      'referrer-policy'
-    ]
-  },
+  projectName: 'example',
+  routes: [
+    { path: '/', expectedStatus: 200 },
+    { path: '/health', expectedStatus: 200 }
+  ],
   local: {
     ports: [],
-    healthPath: '/health'
+    healthPaths: ['/health']
+  },
+  quality: {
+    skipScripts: [],
+    requiredScripts: []
+  },
+  secrets: {
+    allowlistPaths: [],
+    allowlistPatterns: []
   },
   supabase: {
+    enabled: true,
     protectedTables: [
       'agent_jobs',
       'platform_credentials',
       'worker_logs'
     ]
   },
+  cloudflare: {
+    enabled: true
+  },
   ignore: [
     '.cache',
     '.agents',

package/src/commands/github-ci.js

@@ -0,0 +1,338 @@
+import { runCommand } from '../lib/exec.js';
+import { gitText } from '../lib/git.js';
+import { createFinding, createResult } from '../lib/result.js';
+import { loadOpstruthConfig } from '../lib/config.js';
+import { resolveProjectBoundary } from '../lib/boundary.js';
+
+const TERMINAL_STATES = new Set(['completed', 'success', 'failure', 'cancelled', 'skipped', 'timed_out']);
+
+export const GITHUB_CI_STATES = [
+  'verified_success',
+  'verified_failure',
+  'in_progress',
+  'no_run_for_commit',
+  'authentication_unavailable',
+  'repository_unresolved',
+  'workflow_not_found',
+  'commit_mismatch',
+  'not_configured',
+  'not_verified'
+];
+
+export function parseGitHubRemote(remote = '') {
+  const value = remote.trim();
+  if (!value) return null;
+
+  const ssh = value.match(/^git@github\.com:([^/]+)\/(.+?)(?:\.git)?$/i);
+  if (ssh) return `${ssh[1]}/${ssh[2].replace(/\.git$/i, '')}`;
+
+  const sshUrl = value.match(/^ssh:\/\/git@github\.com\/([^/]+)\/(.+?)(?:\.git)?$/i);
+  if (sshUrl) return `${sshUrl[1]}/${sshUrl[2].replace(/\.git$/i, '')}`;
+
+  try {
+    const url = new URL(value);
+    if (url.hostname.toLowerCase() !== 'github.com') return null;
+    const parts = url.pathname.replace(/^\/|\.git$/g, '').split('/');
+    if (parts.length >= 2 && parts[0] && parts[1]) return `${parts[0]}/${parts[1]}`;
+  } catch {
+    // Not a URL shape.
+  }
+
+  return null;
+}
+
+function normalizeConclusion(conclusion) {
+  return String(conclusion || '').toLowerCase();
+}
+
+function normalizeStatus(status) {
+  return String(status || '').toLowerCase();
+}
+
+function parseJsonArray(text) {
+  const parsed = JSON.parse(text || '[]');
+  return Array.isArray(parsed) ? parsed : [];
+}
+
+function parseJsonObject(text) {
+  const parsed = JSON.parse(text || '{}');
+  return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
+}
+
+function isAuthOrCliFailure(result) {
+  const text = `${result.stderr || ''}\n${result.stdout || ''}`;
+  return result.exitCode === 127
+    || /not found|could not resolve to a repository|authentication|not logged in|requires authentication|HTTP 401|HTTP 403/i.test(text);
+}
+
+function runState(run) {
+  const status = normalizeStatus(run.status);
+  const conclusion = normalizeConclusion(run.conclusion);
+  if (status && !TERMINAL_STATES.has(status)) return 'in_progress';
+  if (['queued', 'in_progress', 'requested', 'waiting', 'pending'].includes(status)) return 'in_progress';
+  if (conclusion === 'success') return 'verified_success';
+  if (conclusion) return 'verified_failure';
+  return status === 'completed' ? 'not_verified' : 'in_progress';
+}
+
+export function selectGitHubRun(runs = [], { commitSha, workflow } = {}) {
+  const exact = runs.filter((run) => run.headSha === commitSha);
+  if (!exact.length) {
+    return {
+      state: runs.length ? 'commit_mismatch' : 'no_run_for_commit',
+      run: runs[0] || null
+    };
+  }
+
+  const workflowMatches = workflow
+    ? exact.filter((run) => String(run.workflowName || '') === workflow || String(run.name || '') === workflow)
+    : exact;
+
+  if (!workflowMatches.length) {
+    return { state: 'workflow_not_found', run: exact[0] || null };
+  }
+
+  const completed = workflowMatches
+    .filter((run) => normalizeStatus(run.status) === 'completed' || normalizeConclusion(run.conclusion))
+    .sort((a, b) => Date.parse(b.updatedAt || b.createdAt || 0) - Date.parse(a.updatedAt || a.createdAt || 0));
+
+  const active = workflowMatches
+    .filter((run) => !completed.includes(run))
+    .sort((a, b) => Date.parse(b.updatedAt || b.createdAt || 0) - Date.parse(a.updatedAt || a.createdAt || 0));
+
+  const selected = completed[0] || active[0] || workflowMatches[0];
+  return { state: runState(selected), run: selected };
+}
+
+function githubStatusForState(state) {
+  if (state === 'verified_success') return 'pass';
+  if (state === 'verified_failure') return 'fail';
+  if (state === 'in_progress') return 'warn';
+  if (state === 'not_configured' || state === 'no_run_for_commit' || state === 'workflow_not_found') return 'skipped';
+  return 'not_verified';
+}
+
+function stateLabel(state) {
+  return state.replace(/_/g, ' ');
+}
+
+function jobSummary(jobs = []) {
+  return jobs.map((job) => ({
+    name: job.name,
+    status: job.status,
+    conclusion: job.conclusion,
+    startedAt: job.startedAt,
+    completedAt: job.completedAt
+  }));
+}
+
+async function defaultGhRunner(args, cwd) {
+  return runCommand('gh', args, { cwd, timeoutMs: 30000, redactStdout: false, redactStderr: true });
+}
+
+export async function resolveGitHubContext({ cwd, commitSha, remoteUrl } = {}) {
+  const boundary = await resolveProjectBoundary(cwd || process.cwd());
+  const root = boundary.root;
+  const sha = commitSha || await gitText(['rev-parse', 'HEAD'], root, { redactStdout: false });
+  const remote = remoteUrl || await gitText(['remote', 'get-url', 'origin'], root, { redactStdout: false });
+  const repository = parseGitHubRemote(remote || '');
+  return { boundary, root, commitSha: sha || null, remoteUrl: remote || null, repository };
+}
+
+function baseData({ state, context, workflow, run, jobs, exactCommitMatch }) {
+  return {
+    githubCi: {
+      state,
+      repository: context.repository,
+      localCommitSha: context.commitSha,
+      workflow: workflow || null,
+      runId: run?.databaseId || run?.id || null,
+      runUrl: run?.url || null,
+      event: run?.event || null,
+      status: run?.status || null,
+      conclusion: run?.conclusion || null,
+      workflowName: run?.workflowName || null,
+      headSha: run?.headSha || null,
+      exactCommitMatch,
+      createdAt: run?.createdAt || null,
+      updatedAt: run?.updatedAt || null,
+      jobs: jobSummary(jobs)
+    }
+  };
+}
+
+function resultForState({ state, context, workflow, run = null, jobs = [], details = [] }) {
+  const exactCommitMatch = Boolean(run?.headSha && context.commitSha && run.headSha === context.commitSha);
+  const checks = [];
+  const verified = [];
+  const warnings = [];
+  const failures = [];
+  const skipped = [];
+  const notVerified = [];
+  const findings = [];
+
+  checks.push({
+    name: 'github repository resolution',
+    status: context.repository ? 'pass' : 'not_verified',
+    message: context.repository || 'origin remote did not resolve to GitHub'
+  });
+  checks.push({
+    name: 'github ci exact commit',
+    status: state === 'verified_success' ? 'pass' : state === 'verified_failure' ? 'fail' : githubStatusForState(state),
+    message: `${stateLabel(state)}${workflow ? `; workflow=${workflow}` : ''}`
+  });
+
+  if (state === 'verified_success') {
+    verified.push(`GitHub repository resolved: ${context.repository}`);
+    verified.push(`Exact local commit matched GitHub Actions run: ${context.commitSha}`);
+    verified.push(`Workflow run succeeded: ${run.workflowName || workflow || 'not specified'}`);
+    if (jobs.length) verified.push(`Workflow jobs inspected: ${jobs.map((job) => `${job.name}:${job.conclusion || job.status}`).join(', ')}`);
+  } else if (state === 'verified_failure') {
+    failures.push(`GitHub Actions run for exact commit did not succeed: ${run?.conclusion || run?.status || 'unknown'}`);
+    findings.push(createFinding({
+      status: 'fail',
+      area: 'github',
+      title: 'GitHub Actions exact-commit run failed',
+      finding: `GitHub Actions run for ${context.commitSha || 'current commit'} did not succeed.`,
+      evidence: [
+        `repository: ${context.repository || 'unresolved'}`,
+        `workflow: ${run?.workflowName || workflow || 'not specified'}`,
+        `run id: ${run?.databaseId || run?.id || 'not available'}`,
+        `status: ${run?.status || 'unknown'}`,
+        `conclusion: ${run?.conclusion || 'unknown'}`
+      ],
+      whyItMatters: 'CI failure is local/hosted quality evidence for the exact commit, not a deploy or production proof.',
+      nextSafeStep: 'Inspect the failing check in GitHub and fix it before relying on this commit.'
+    }));
+  } else if (state === 'in_progress') {
+    warnings.push('GitHub Actions run for the exact commit is still in progress');
+  } else if (state === 'repository_unresolved') {
+    notVerified.push('GitHub repository could not be resolved from origin remote');
+  } else if (state === 'authentication_unavailable') {
+    notVerified.push('GitHub authentication or gh CLI was unavailable');
+  } else if (state === 'workflow_not_found') {
+    skipped.push(`No GitHub Actions run matched workflow ${workflow}`);
+    notVerified.push('Configured GitHub Actions workflow was not verified for this commit');
+  } else if (state === 'no_run_for_commit') {
+    skipped.push('No GitHub Actions run was found for the current local commit');
+    notVerified.push('GitHub CI did not provide proof for this checkout');
+  } else if (state === 'commit_mismatch') {
+    notVerified.push('GitHub Actions metadata did not match the current local commit');
+  } else {
+    notVerified.push('GitHub Actions proof was not verified');
+  }
+
+  for (const detail of details) notVerified.push(detail);
+
+  return createResult('github-ci', githubStatusForState(state), {
+    summary: 'Read-only GitHub Actions exact-commit proof check completed.',
+    verified,
+    warnings,
+    failures,
+    skipped,
+    notVerified: [
+      ...notVerified,
+      'GitHub CI does not prove production deployment, Supabase state, scheduler state, production headers, or function behavior'
+    ],
+    findings,
+    checks,
+    data: baseData({ state, context, workflow, run, jobs, exactCommitMatch }),
+    nextSafeStep: state === 'verified_success'
+      ? 'Treat CI as hosted quality proof only; verify production separately when needed.'
+      : 'Resolve the GitHub CI proof gap or inspect the matching workflow in GitHub.'
+  });
+}
+
+export async function runGitHubCi({
+  cwd = process.cwd(),
+  workflow,
+  ghRunner = defaultGhRunner,
+  commitSha,
+  remoteUrl
+} = {}) {
+  const loaded = await loadOpstruthConfig(cwd);
+  const configuredWorkflow = workflow || loaded.config?.github?.ci?.workflow;
+  let context;
+  try {
+    context = await resolveGitHubContext({ cwd, commitSha, remoteUrl });
+  } catch (error) {
+    context = { root: cwd, commitSha: commitSha || null, remoteUrl: remoteUrl || null, repository: null };
+  }
+
+  if (!context.repository || !context.commitSha) {
+    return resultForState({
+      state: 'repository_unresolved',
+      context,
+      workflow: configuredWorkflow,
+      details: loaded.warning ? [loaded.warning] : []
+    });
+  }
+
+  const listArgs = [
+    'run',
+    'list',
+    '--repo',
+    context.repository,
+    '--commit',
+    context.commitSha,
+    '--limit',
+    '20',
+    '--json',
+    'databaseId,headSha,conclusion,status,event,createdAt,updatedAt,workflowName,url'
+  ];
+
+  const list = await ghRunner(listArgs, context.root);
+  if (list.exitCode !== 0) {
+    const state = isAuthOrCliFailure(list) ? 'authentication_unavailable' : 'not_verified';
+    return resultForState({ state, context, workflow: configuredWorkflow, details: [list.stderr || list.stdout || 'GitHub CLI query failed'] });
+  }
+
+  let runs;
+  try {
+    runs = parseJsonArray(list.stdout);
+  } catch (error) {
+    return resultForState({ state: 'not_verified', context, workflow: configuredWorkflow, details: ['GitHub CLI returned malformed workflow JSON'] });
+  }
+
+  const selection = selectGitHubRun(runs, { commitSha: context.commitSha, workflow: configuredWorkflow });
+  if (!selection.run || !['verified_success', 'verified_failure', 'in_progress'].includes(selection.state)) {
+    return resultForState({ state: selection.state, context, workflow: configuredWorkflow, run: selection.run });
+  }
+
+  const runId = selection.run.databaseId || selection.run.id;
+  if (!runId) return resultForState({ state: selection.state, context, workflow: configuredWorkflow, run: selection.run });
+
+  const view = await ghRunner([
+    'run',
+    'view',
+    String(runId),
+    '--repo',
+    context.repository,
+    '--json',
+    'databaseId,conclusion,status,event,headSha,workflowName,jobs,url,createdAt,updatedAt'
+  ], context.root);
+
+  if (view.exitCode !== 0) {
+    const state = isAuthOrCliFailure(view) ? 'authentication_unavailable' : selection.state;
+    return resultForState({ state, context, workflow: configuredWorkflow, run: selection.run, details: [view.stderr || view.stdout || 'GitHub CLI run detail query failed'] });
+  }
+
+  let run;
+  try {
+    run = parseJsonObject(view.stdout);
+  } catch {
+    return resultForState({ state: 'not_verified', context, workflow: configuredWorkflow, run: selection.run, details: ['GitHub CLI returned malformed run detail JSON'] });
+  }
+
+  if (run.headSha !== context.commitSha) {
+    return resultForState({ state: 'commit_mismatch', context, workflow: configuredWorkflow, run });
+  }
+
+  return resultForState({
+    state: runState(run),
+    context,
+    workflow: configuredWorkflow,
+    run,
+    jobs: Array.isArray(run.jobs) ? run.jobs : []
+  });
+}