arkgate 4.8.9 → 4.8.10

package/bin/lib/doctor-next-actions.mjs

@@ -116,7 +116,9 @@ export function collectDoctorNextActions(ctx) {
     actions.push('review dirty baseline freezes — fix the contract before trusting green-via-freeze');
   }
   if (ctx.analysisComplete && ctx.staleBaseline > 0) {
-    actions.push('tighten the baseline (--update-baseline)');
+    actions.push(
+      'tighten the baseline (--update-baseline --force --contract-session --author <steward>)'
+    );
   }
   if (ctx.staleRunners.length > 0) {
     actions.push(

package/bin/lib/field-install.mjs

@@ -83,6 +83,27 @@ function addDevDependencyPreservingFormat(source, version) {
   return `${source.slice(0, contentEnd)}${addition}${eol}${rootClosingIndent}${source.slice(rootClose)}`;
 }
 
+const ARK_CHECK_BIN_RE = /\b(?:ark-check|arkgate-check)(?:\.mjs|\.js)?\b/;
+const ARK_CHECK_RUNNER_RE =
+  /(?:^|[\s"'`;|&])(?:npx|pnpm|yarn|npm|bunx?|node)(?:\s|$)/;
+const GITHUB_RUN_KEY_RE = /^\s*(?:-\s+)?run:\s+/;
+const YAML_CHECK_JOB_ID_RE =
+  /^\s*(?:-\s+)?['"]?(?:ark-check|arkgate-check)['"]?\s*:/;
+const YAML_CONCURRENCY_GROUP_RE = /^\s*group:\s+/;
+
+/**
+ * True when the line invokes ark-check / arkgate-check (npx/pnpm/yarn/npm/node/run).
+ * YAML concurrency.group and job-id keys that only contain the name are not invocations.
+ */
+export function isArkCheckInvocationLine(command) {
+  if (typeof command !== 'string' || !command.trim()) return false;
+  if (/^\s*#/.test(command)) return false;
+  if (YAML_CHECK_JOB_ID_RE.test(command)) return false;
+  if (YAML_CONCURRENCY_GROUP_RE.test(command)) return false;
+  if (!ARK_CHECK_BIN_RE.test(command)) return false;
+  return ARK_CHECK_RUNNER_RE.test(command) || GITHUB_RUN_KEY_RE.test(command);
+}
+
 /**
  * Ensure a check command string includes `--baseline <file>`.
  * Only touches strings that already invoke ark-check / arkgate-check.
@@ -97,7 +118,7 @@ export function ensureBaselineFlagInCheckCommand(
   if (/^\s*#/.test(command)) {
     return { command, changed: false };
   }
-  if (!/\b(ark-check|arkgate-check)\b/.test(command)) {
+  if (!isArkCheckInvocationLine(command)) {
     return { command, changed: false };
   }
   if (/(?:^|\s)--baseline(?:\s|=|$)/.test(command)) {
@@ -180,7 +201,7 @@ export function syncBaselineIntoCheckSurfaces(root, opts = {}) {
       let fileChanged = false;
       const nextLines = lines.map((line) => {
         if (/^\s*#/.test(line)) return line;
-        if (!/\b(ark-check|arkgate-check)\b/.test(line)) return line;
+        if (!isArkCheckInvocationLine(line)) return line;
         if (/(?:^|\s)--baseline(?:\s|=|$)/.test(line)) return line;
         const { command, changed: c } = ensureBaselineFlagInCheckCommand(line, flagRel);
         if (c) {

package/bin/lib/first-run-help.mjs

@@ -95,12 +95,74 @@ Non-interactive (no TTY): uses the same defaults as --yes — never calls readli
 `;
 }
 
+/** `--sensors` is contract + coverage-evidence only — never a full-check pass. */
+export const SENSORS_PARTIAL_MODE_LINE =
+  'Contract + coverage-evidence only: no TypeScript, no analysis. Not a validity verdict.';
+
+export const SENSORS_DID_NOT_RUN = Object.freeze(['TypeScript', 'analysis']);
+
+/**
+ * Stamp a successful `--sensors --json` payload so agents cannot read exit 0 as
+ * a full-check pass. Failure payloads (`sensors.ok === false`) stay untouched.
+ */
+export function stampSensorsPartialModePayload(payload) {
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) return payload;
+  const sensors = payload.sensors;
+  if (!sensors || typeof sensors !== 'object' || Array.isArray(sensors)) return payload;
+  if (sensors.ok === false) return payload;
+  return {
+    ...payload,
+    sensors: {
+      ...sensors,
+      notAVerdict: true,
+      didNotRun: [...SENSORS_DID_NOT_RUN],
+      partialMode: 'contract-only',
+    },
+  };
+}
+
+/**
+ * After `runSensors`, name what this mode skipped. Human success prints the
+ * line on stdout; JSON success restamps the captured object. Failures reprint
+ * as-is so exit 2 does not look like a map.
+ */
+export async function withSensorsPartialModeHonesty(args, run) {
+  if (args?.json) {
+    const chunks = [];
+    const original = console.log;
+    console.log = (...parts) => {
+      chunks.push(parts.map(String).join(' '));
+    };
+    try {
+      await run();
+    } finally {
+      console.log = original;
+    }
+    const text = chunks.join('\n');
+    if ((process.exitCode ?? 0) !== 0) {
+      if (text) original(text);
+      return;
+    }
+    try {
+      original(JSON.stringify(stampSensorsPartialModePayload(JSON.parse(text)), null, 2));
+    } catch {
+      original(text);
+    }
+    return;
+  }
+  await run();
+  if ((process.exitCode ?? 0) === 0) {
+    console.log(SENSORS_PARTIAL_MODE_LINE);
+  }
+}
+
 export function checkUsage() {
   return [
     'arkgate-check (alias ark-check) — the architecture check.',
     '',
     '  arkgate-check --doctor         where you are: one status light, one next action',
     '  arkgate-check --strict-merge   CI / merge gate (required GitHub status)',
+    '  arkgate-check --sensors        which sensors can ever be enforced (does not run analysis)',
     '',
     'Every flag and command: arkgate-check --help --all',
   ].join('\n');
@@ -124,7 +186,7 @@ export function checkUsageAll() {
     '           Exit 0 ran and clean, 1 drift remains, 2 could not run (no usable base ref).',
     '       ark-check --sensors [--json]           every sensor with its tier and whether it can EVER be enforced, plus every declared rule',
     '           with its local id, the sensor it delegates to, its source file, its mode and why it can or cannot be promoted.',
-    '           Contract + coverage-evidence only: no TypeScript, no analysis. Exit 0 on a report, 2 if the contract will not load.',
+    `           ${SENSORS_PARTIAL_MODE_LINE} Exit 0 on a report, 2 if the contract will not load.`,
     '       ark-check --promote [<ruleId>] [--json] [--apply]',
     '           what enforcing would cost: the findings each advisory rule already produces, from ONE run rather than one run per attempt.',
     '           Plan by default; --promote <ruleId> --apply (or --promote=<ruleId>) writes mode "enforced" into the ArkRules file that declares it.',
@@ -143,12 +205,14 @@ export function checkUsageAll() {
     '       ark-check --init [--preset hexagonal|layered|feature-sliced|monorepo|ui-surface|vertical-slice|ddd-bounded-contexts|vite-vercel-spa|clean-architecture|onion-architecture] [--force] [--follow-config-root]',
     '       --follow-config-root  On writes (init/install-agent-gates/migrate --write/…), adopt walked-up monorepo config root (default: keep explicit --root)',
     '       ark-check --install-agent-gates [--tools claude,cursor,codex,grok,antigravity] [--require-write-hook <host>] [--skills-only] [--codex-home] [--claude-home] [--grok-home] [--antigravity-home] [--agent-homes] [--force]',
-    '       ark-check --update-baseline [file]     freeze current violations (default .ark-baseline.json)',
+    '       ark-check --update-baseline [file] --force --contract-session --author <steward>',
+    '           freeze current violations (default .ark-baseline.json). --contract-session is required;',
+    '           --force when freeze-refuse fires; --author when stewards[] is set.',
     '       ark-check --print-config eleven-layer',
     '',
-    'Adopting Ark in an existing codebase? Run --update-baseline once to freeze existing',
-    'violations, commit the baseline file, and gate CI with --baseline: only NEW violations',
-    'fail the check, so the ratchet only moves toward zero.',
+    'Adopting Ark in an existing codebase? Run --update-baseline --force --contract-session --author <steward>',
+    'once to freeze existing violations, commit the baseline file, and gate CI with --baseline: only NEW',
+    'violations fail the check, so the ratchet only moves toward zero.',
     '',
     'Team parliament: law files (ark.config / arkrules / .ark-baseline.json) cannot ship in',
     'the same diff as product source. --changed --base <ref> checks touched files only.',

package/bin/lib/resolved-candidate-facts.mjs

@@ -750,6 +750,83 @@ function declaredIntent(value, config) {
   );
 }
 
+/** Call names whose string arguments are declared intent-reference sites. */
+const INTENT_CALL_NAMES = new Set(['publish', 'subscribe', 'defineIntent', 'registerHandler']);
+
+function isSyntaxWrapper(ts, node) {
+  return Boolean(
+    node &&
+      (ts.isParenthesizedExpression(node) ||
+        ts.isAsExpression(node) ||
+        (typeof ts.isTypeAssertionExpression === 'function' &&
+          ts.isTypeAssertionExpression(node)) ||
+        (typeof ts.isSatisfiesExpression === 'function' && ts.isSatisfiesExpression(node)))
+  );
+}
+
+function unwrapWrappers(ts, node) {
+  let current = node;
+  while (current?.parent && isSyntaxWrapper(ts, current.parent)) {
+    current = current.parent;
+  }
+  return current;
+}
+
+function callCalleeName(ts, node) {
+  if (!node || !ts.isCallExpression(node)) return undefined;
+  const expression = node.expression;
+  if (ts.isIdentifier(expression)) return expression.text;
+  if (ts.isPropertyAccessExpression(expression)) return expression.name.text;
+  return undefined;
+}
+
+function isPublishMetadataSource(ts, sourceProp) {
+  const object = sourceProp.parent;
+  if (!object || !ts.isObjectLiteralExpression(object)) return false;
+  const objectSite = unwrapWrappers(ts, object);
+  const objectParent = objectSite.parent;
+  if (!objectParent) return false;
+  if (ts.isCallExpression(objectParent) && callCalleeName(ts, objectParent) === 'publish') {
+    const args = objectParent.arguments;
+    return args[1] === objectSite || args[2] === objectSite;
+  }
+  if (
+    ts.isPropertyAssignment(objectParent) &&
+    syntaxPropertyName(ts, objectParent.name) === 'metadata'
+  ) {
+    const eventObject = objectParent.parent;
+    if (!eventObject) return false;
+    const eventSite = unwrapWrappers(ts, eventObject);
+    const call = eventSite.parent;
+    return Boolean(
+      call && ts.isCallExpression(call) && callCalleeName(ts, call) === 'publish'
+    );
+  }
+  return false;
+}
+
+/** Events, sagas, and publish metadata — not every string that matches a prefix. */
+function isDeclaredIntentSite(ts, node) {
+  const siteNode = unwrapWrappers(ts, node);
+  const parent = siteNode.parent;
+  if (!parent) return false;
+  if (ts.isCallExpression(parent)) {
+    const name = callCalleeName(ts, parent);
+    if (INTENT_CALL_NAMES.has(name) && parent.arguments.some((arg) => arg === siteNode)) {
+      return true;
+    }
+  }
+  if (ts.isArrayLiteralExpression(parent)) {
+    return isDeclaredIntentSite(ts, parent);
+  }
+  if (ts.isPropertyAssignment(parent)) {
+    const name = syntaxPropertyName(ts, parent.name);
+    if (name === 'intent' || name === 'onEvent' || name === 'reactsTo') return true;
+    if (name === 'source' && isPublishMetadataSource(ts, parent)) return true;
+  }
+  return false;
+}
+
 function mayContainForbiddenCapability(ts, sourceFile, forbiddenGlobals) {
   // Every symbol-aware match originates in an identifier or static string path segment.
   // Inspect decoded AST text so escaped identifiers still take the full checker path.
@@ -788,7 +865,11 @@ function collectPolicyFacts(ts, sourceFile, relativePath, config) {
           : {}),
       });
     }
-    if (ts.isStringLiteralLike(node) && declaredIntent(node.text, config)) {
+    if (
+      ts.isStringLiteralLike(node) &&
+      declaredIntent(node.text, config) &&
+      isDeclaredIntentSite(ts, node)
+    ) {
       intentReferences.push({
         file: relativePath,
         line: lineOf(sourceFile, node.getStart(sourceFile)),

package/bin/lib/rules-inventory.mjs

@@ -8,6 +8,7 @@
  * Pure CLI helper (bin/lib/rules-inventory.mjs). Zero Node I/O.
  */
 
+import { DOMAIN_EVENTS_PUSH_RE, DOMAIN_INVARIANT_WORD_RE, expectedDomainInvariantWordsPhrase, isIdiomaticEventsReset, } from './arkrules-sensors.mjs';
 function lineOf(content, index) {
     return content.slice(0, index).split('\n').length;
 }
@@ -226,7 +227,7 @@ export function buildRulesInventory(input) {
                 /(?:^|\/)[^/]*(?:-access)?\.error\./i.test(posix) ||
                 /(?:^|\/)errors?(?:\/|$)/i.test(posix);
             if (!isErrorBag) {
-                const mutRe = /this\.\w+\s*=/g;
+                const mutRe = /\bthis\.[A-Za-z_][A-Za-z0-9_]*\s*=(?!=)/g;
                 let mut;
                 while ((mut = mutRe.exec(content)) !== null) {
                     const classStart = content.lastIndexOf('class ', mut.index);
@@ -239,15 +240,18 @@ export function buildRulesInventory(input) {
                     if (/\bextends\s+(?:Error|[A-Za-z_$][A-Za-z0-9_$]*Error)\b/.test(classHeader)) {
                         continue;
                     }
+                    if (isIdiomaticEventsReset(content, mut.index))
+                        continue;
                     const window = content.slice(Math.max(0, mut.index - 200), mut.index + 200);
-                    if (!/\b(ensureInvariants|assertInvariants|validate|publish|emit)\b/.test(window)) {
+                    if (!DOMAIN_INVARIANT_WORD_RE.test(window) &&
+                        !DOMAIN_EVENTS_PUSH_RE.test(window)) {
                         seq += 1;
                         candidates.push({
                             id: `inv-mut-${seq}`,
                             kind: 'mutation-without-guard',
                             file,
                             line: lineOf(content, mut.index),
-                            message: 'Domain field mutation without nearby guard/publish call.',
+                            message: `Domain field mutation without nearby ${expectedDomainInvariantWordsPhrase()}.`,
                             confidence: 'heuristic',
                             governedLayer,
                             suggestedArkRule: {

package/bin/lib/upstream-report.mjs

@@ -0,0 +1,330 @@
+/**
+ * Upstream GitHub issue draft for ArkGate itself (`arkgate report` / `ark report`).
+ * Target is this package's package.json bugs.url (pedroknigge/arkgate), never the consumer repo.
+ */
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import readline from 'node:readline/promises';
+
+import { __packageRoot } from './gate-files.mjs';
+
+export const UPSTREAM_OWNER_REPO = 'pedroknigge/arkgate';
+export const SUBMIT_PROMPT = 'Type submit to send';
+
+export function ownerRepoFromGithubUrl(url) {
+  if (typeof url !== 'string' || url.trim() === '') return null;
+  const match = url.trim().match(/github\.com[:/]+([^/]+)\/([^/#?\s]+)/i);
+  if (!match) return null;
+  const owner = match[1];
+  const repo = match[2].replace(/\.git$/i, '');
+  if (!owner || !repo) return null;
+  return `${owner}/${repo}`;
+}
+
+export function resolveUpstreamRepo(pkg) {
+  const fromBugs = ownerRepoFromGithubUrl(pkg?.bugs?.url);
+  if (fromBugs) return fromBugs;
+  const repository = pkg?.repository;
+  const repoUrl = typeof repository === 'string' ? repository : repository?.url;
+  const fromRepo = ownerRepoFromGithubUrl(repoUrl);
+  if (fromRepo) return fromRepo;
+  return UPSTREAM_OWNER_REPO;
+}
+
+export function posixSingleQuote(value) {
+  return `'${String(value).replace(/'/g, `'\\''`)}'`;
+}
+
+export function formatGhIssueCreateCommand({ repo, title, body }) {
+  return `gh issue create --repo ${posixSingleQuote(repo)} --title ${posixSingleQuote(title)} --body ${posixSingleQuote(body)}`;
+}
+
+export function reportUsage() {
+  return `arkgate report (alias ark report) — draft an upstream GitHub issue for ArkGate.
+
+Target: pedroknigge/arkgate (this package's package.json bugs.url). Never the consumer repo.
+
+Usage:
+  arkgate report [--root <project>] [--json] [--title <text>] [--finding <ref>]
+  arkgate report --submit --i-confirm-submit
+  arkgate report --submit          # TTY: type submit to send
+
+Default prints a draft (arkgate version + last-check snippet). Nothing is created.
+Create only with --submit AND (--i-confirm-submit after the human said yes, or TTY
+"${SUBMIT_PROMPT}"). --yes does not submit.
+
+If gh is missing or not logged in: prints the draft and the exact
+gh issue create --repo pedroknigge/arkgate command, then exits 2.
+`;
+}
+
+export function lastCheckSnippet(latest) {
+  if (!latest || typeof latest !== 'object') return null;
+  const at =
+    typeof latest.generatedAt === 'string'
+      ? latest.generatedAt
+      : typeof latest.at === 'string'
+        ? latest.at
+        : null;
+  const active =
+    typeof latest.activeViolations === 'number'
+      ? latest.activeViolations
+      : typeof latest.violations?.active === 'number'
+        ? latest.violations.active
+        : null;
+  let verdict = null;
+  if (latest.ok === true && (active == null || active === 0)) verdict = 'pass';
+  else if (latest.ok === false || (typeof active === 'number' && active > 0)) verdict = 'fail';
+  else if (latest.completeness === 'partial' || latest.completeness === 'unavailable') {
+    verdict = 'incomplete';
+  } else if (latest.ok === true) verdict = 'pass';
+  if (at == null && verdict == null && active == null) return null;
+  return { at, verdict, activeViolations: active };
+}
+
+export function readLastCheckSnapshot(root) {
+  const latestPath = path.join(root, '.ark', 'reports', 'latest.json');
+  try {
+    return JSON.parse(fs.readFileSync(latestPath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+export function buildIssueDraft({ repo, arkgateVersion, lastCheck, finding, title }) {
+  const resolvedTitle =
+    typeof title === 'string' && title.trim()
+      ? title.trim()
+      : finding
+        ? `ArkGate finding ${finding}`
+        : 'ArkGate field report';
+  const lines = [`## ArkGate version`, String(arkgateVersion ?? 'unknown'), ''];
+  if (finding) {
+    lines.push('## Finding', String(finding), '');
+  }
+  if (lastCheck) {
+    lines.push('## Last check');
+    lines.push(`- at: ${lastCheck.at ?? 'none'}`);
+    lines.push(`- verdict: ${lastCheck.verdict ?? 'none'}`);
+    lines.push(`- activeViolations: ${lastCheck.activeViolations ?? 'unknown'}`);
+    lines.push('');
+  } else {
+    lines.push('## Last check', 'No last-check snapshot under .ark/reports/latest.json.', '');
+  }
+  lines.push(
+    '## Repro',
+    '```bash',
+    'npx arkgate-check --doctor',
+    'npx arkgate status --json',
+    '```',
+    '',
+    '## What happened',
+    '(ArkGate bug, false green, false red, missing doc, or improvable behavior in ArkGate itself — not leftover design in the consumer app.)',
+    '',
+    `Prepared with \`arkgate report\` against upstream ${repo}. Not the consumer repo.`
+  );
+  return { repo, title: resolvedTitle, body: lines.join('\n') };
+}
+
+export function defaultRunGh(argv, options = {}) {
+  const env = { ...(options.env ?? process.env) };
+  delete env.GH_REPO;
+  const result = spawnSync('gh', argv, {
+    encoding: 'utf8',
+    env,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  if (result.error && (result.error.code === 'ENOENT' || result.error.code === 'EACCES')) {
+    return { missing: true, status: 127, stdout: '', stderr: result.error.message };
+  }
+  return {
+    missing: false,
+    status: result.status ?? 1,
+    stdout: result.stdout ?? '',
+    stderr: result.stderr ?? '',
+  };
+}
+
+function loadArkgatePackageJson(explicit) {
+  if (explicit && typeof explicit === 'object') return explicit;
+  try {
+    return JSON.parse(fs.readFileSync(path.join(__packageRoot, 'package.json'), 'utf8'));
+  } catch {
+    return { bugs: { url: `https://github.com/${UPSTREAM_OWNER_REPO}/issues` } };
+  }
+}
+
+function packageVersion(pkg, fallback) {
+  if (typeof fallback === 'string' && fallback.trim()) return fallback;
+  return typeof pkg?.version === 'string' ? pkg.version : 'unknown';
+}
+
+function renderHumanDraft(draft, arkgateVersion) {
+  return [
+    `Upstream: ${draft.repo}`,
+    '(never the consumer repo)',
+    '',
+    `ArkGate version: ${arkgateVersion}`,
+    '',
+    `Title: ${draft.title}`,
+    '',
+    draft.body,
+  ].join('\n');
+}
+
+async function defaultPromptSubmit(stdin, stdout) {
+  const rl = readline.createInterface({ input: stdin, output: stdout });
+  try {
+    return await rl.question(`${SUBMIT_PROMPT}\n`);
+  } finally {
+    rl.close();
+  }
+}
+
+export function parseReportArgv(argv = []) {
+  const out = {
+    submit: false,
+    iConfirmSubmit: false,
+    json: false,
+    yes: false,
+    help: false,
+    finding: undefined,
+    title: undefined,
+    root: undefined,
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    const next = () => {
+      const value = argv[i + 1];
+      if (value === undefined || String(value).startsWith('-')) {
+        throw new Error(`Missing value for ${arg}. Run arkgate report --help for usage.`);
+      }
+      i += 1;
+      return value;
+    };
+    if (arg === '--submit') out.submit = true;
+    else if (arg === '--i-confirm-submit') out.iConfirmSubmit = true;
+    else if (arg === '--json') out.json = true;
+    else if (arg === '--yes' || arg === '-y') out.yes = true;
+    else if (arg === '--help' || arg === '-h' || arg === 'help') out.help = true;
+    else if (arg === '--finding') out.finding = next();
+    else if (arg === '--title') out.title = next();
+    else if (arg === '--root') out.root = path.resolve(next());
+    else throw new Error(`Unknown argument: ${arg}. Run arkgate report --help for usage.`);
+  }
+  return out;
+}
+
+/**
+ * @param {object} options
+ * @returns {Promise<number>} process exit code
+ */
+export async function runUpstreamReportCommand(options = {}) {
+  const fromArgv = Array.isArray(options.argv) ? parseReportArgv(options.argv) : {};
+  if (fromArgv.help) {
+    const writeOut = options.writeOut ?? ((text) => console.log(text));
+    writeOut(reportUsage());
+    return 0;
+  }
+  const root = path.resolve(fromArgv.root ?? options.root ?? process.cwd());
+  const json = Boolean(fromArgv.json || options.json);
+  const submit = Boolean(fromArgv.submit || options.submit);
+  const iConfirmSubmit = Boolean(fromArgv.iConfirmSubmit || options.iConfirmSubmit);
+  const yes = Boolean(fromArgv.yes || options.yes);
+  const finding = fromArgv.finding ?? options.finding;
+  const title = fromArgv.title ?? options.title;
+  const stdin = options.stdin ?? process.stdin;
+  const stdout = options.stdout ?? process.stdout;
+  const stdinIsTTY = options.stdinIsTTY ?? Boolean(stdin.isTTY);
+  const env = options.env ?? process.env;
+  const runGh = options.runGh ?? ((argv) => defaultRunGh(argv, { env }));
+  const writeOut = options.writeOut ?? ((text) => console.log(text));
+  const writeErr = options.writeErr ?? ((text) => console.error(text));
+
+  const pkg = loadArkgatePackageJson(options.arkgatePackageJson);
+  const repo = resolveUpstreamRepo(pkg);
+  const arkgateVersion = packageVersion(pkg, options.arkgateVersion);
+  const lastCheck = lastCheckSnippet(options.latestSnapshot ?? readLastCheckSnapshot(root));
+  const draft = buildIssueDraft({
+    repo,
+    arkgateVersion,
+    lastCheck,
+    finding,
+    title,
+  });
+  const ghCommand = formatGhIssueCreateCommand(draft);
+  const human = renderHumanDraft(draft, arkgateVersion);
+
+  const payload = {
+    schemaVersion: '1.0',
+    command: 'report',
+    created: false,
+    submitted: false,
+    repo: draft.repo,
+    title: draft.title,
+    body: draft.body,
+    arkgateVersion,
+    lastCheck,
+    ghCommand,
+    yesDoesNotSubmit: true,
+  };
+
+  const emit = (extraHuman, extraPayload) => {
+    if (json) writeOut(JSON.stringify({ ...payload, ...extraPayload }, null, 2));
+    else writeOut(extraHuman ? `${human}\n\n${extraHuman}` : human);
+  };
+
+  if (!submit) {
+    emit('Draft only. Nothing was created.\nAfter a human confirms: arkgate report --submit --i-confirm-submit\n--yes does not submit.');
+    return 0;
+  }
+
+  // --yes never confirms. Confirm is --i-confirm-submit or TTY "submit".
+  let confirmed = iConfirmSubmit;
+  if (!confirmed && stdinIsTTY) {
+    const typed = options.promptSubmit
+      ? await options.promptSubmit()
+      : await defaultPromptSubmit(stdin, stdout);
+    confirmed = /^\s*submit\s*$/i.test(String(typed ?? ''));
+  }
+
+  if (!confirmed) {
+    const refused =
+      'Refused: --submit requires --i-confirm-submit or typing submit on a TTY. --yes does not submit.';
+    if (json) {
+      writeOut(JSON.stringify({ ...payload, error: 'submit-confirm-required', yesDoesNotSubmit: true }, null, 2));
+    } else {
+      writeOut(`${human}\n\nDraft only. ${refused}`);
+    }
+    writeErr(refused);
+    return 2;
+  }
+
+  const auth = runGh(['auth', 'status']);
+  const ghUnavailable = Boolean(auth?.missing) || auth?.status !== 0;
+  if (ghUnavailable) {
+    const missing =
+      'Not filed: gh is missing or not logged in.\nExact command:\n' + ghCommand;
+    emit(missing, { created: false, submitted: false, error: 'gh-unavailable', ghCommand });
+    if (!json) writeErr('Not filed: gh is missing or not logged in.');
+    return 2;
+  }
+
+  const created = runGh(['issue', 'create', '--repo', repo, '--title', draft.title, '--body', draft.body]);
+  if (created?.missing || created?.status !== 0) {
+    const missing =
+      'Not filed: gh is missing or not logged in.\nExact command:\n' + ghCommand;
+    emit(missing, { created: false, submitted: false, error: 'gh-unavailable', ghCommand });
+    if (!json) writeErr('Not filed: gh is missing or not logged in.');
+    return 2;
+  }
+
+  const url = String(created.stdout ?? '').trim();
+  emit(url ? `Created: ${url}` : 'Created.', {
+    created: true,
+    submitted: true,
+    url: url || null,
+  });
+  return 0;
+}