redlinegate 0.0.1 → 0.0.3

package/README.md

@@ -39,7 +39,7 @@ OpenAI Codex / `AGENTS.md`, and Claude. A Cursor adapter exists but ships disabl
 | `scripts/validate.mjs` | Bundle self-check, run by this repo's CI | this repo |
 | `scripts/check-pins.mjs` | Re-resolves SHA-pinned actions against their upstream tag | this repo's CI |
 | `scripts/assign-rule-ids.mjs` | Assigns and verifies the stable `<stack>/<slug>` id on every rule | this repo |
-| `seeded/` | Recall corpus (12 stacks, 82 BLOCKER seeds) + precision corpus, scored by `scripts/score-seeds.mjs` | validation only, never merged |
+| `seeded/` | Recall corpus (16 stacks, 117 BLOCKER seeds) + precision corpus, scored by `scripts/score-seeds.mjs` | validation only, never merged |
 
 ## Language coverage vs org reality
 
@@ -56,10 +56,26 @@ cd your-repo
 npx redlinegate init
 ```
 
-That is the whole procedure. It detects your stack, renders the standards for it, installs
-the merge-readiness template and the gate (advisory — it reports, it does not block),
-turns on the security floor, and opens a pull request. Anything that needed repository
-admin rights you do not have is listed at the end for an administrator to run.
+That is the whole procedure. With no flags, at a terminal, it asks before it writes:
+which standards apply, where the repository lives, what runs your pull request checks,
+which assistants should read the rules, what to install, and how hard the gate should
+bite. Whatever it detected is preselected, so pressing enter through it accepts detection,
+and the last question offers **Dry run** before Apply.
+
+Choose Apply and it renders the standards, installs the merge-readiness template and the
+gate (advisory — it reports, it does not block), turns on the security floor, and opens a
+pull request on `redline/onboard`. It never pushes to your default branch, so `git status`
+stays clean. Anything that needed repository admin rights you do not have is listed at the
+end for an administrator to run.
+
+In CI, in a pipe, or with any flag present it prompts for nothing and takes the scripted
+path — a prompt in a pipeline is a hang with nobody there to answer it:
+
+```sh
+npx redlinegate init --dry-run                 # the plan; writes nothing, contacts no host
+npx redlinegate init --profile web-react,infra # a React app with its own Terraform beside it
+npx redlinegate init --pipeline azure-pipelines  # on GitHub, but built by Azure Pipelines
+```
 
 Install it once and the everyday command is shorter:
 
@@ -123,8 +139,8 @@ Redline carries two versions that move independently. Do not conflate them.
 
 | Axis | Lives in | Bumped by | Example |
 | --- | --- | --- | --- |
-| **CLI version** | `redlinegate` on npm (git `v*` tags) | semantic-release, from conventional commits on `main` | `0.0.1` |
-| **Standards version** | `standards/manifest.json` → `version` | A human, in the same PR as the rule change (see above) | `0.0.1` |
+| **CLI version** | `redlinegate` on npm (git `v*` tags) | semantic-release, from conventional commits on `main` | `0.0.2` |
+| **Standards version** | `standards/manifest.json` → `version` | A human, in the same PR as the rule change (see above) | `0.0.2` |
 
 The CLI version is the tool's release line: [CHANGELOG.md](CHANGELOG.md) tracks it, and
 semantic-release computes the next one from commit messages — never edit

package/dist/bin/redline.js

@@ -9,6 +9,15 @@ import { isSeverity } from "../core/severity.js";
 import { isRung, RUNGS } from "../enforce/ladder.js";
 import { resolvePlatform as defaultResolvePlatform, } from "../platforms/resolve.js";
 import { init, ONBOARD_BRANCH } from "../commands/init.js";
+import { explain, loadRules } from "../rules/catalogue.js";
+import { formatStatus, status } from "../commands/status.js";
+import { createGit } from "../core/git.js";
+import { parseRemote } from "../platforms/detect.js";
+import { Cancelled, createPrompter, isInteractive } from "../ui/prompt.js";
+import { renderReport } from "../ui/report.js";
+import { colorDepth, colorEnabled, glyphs, palette } from "../ui/tty.js";
+import { gatherFacts } from "../ui/facts.js";
+import { runWizard } from "../ui/wizard.js";
 import { capabilitySelection, OPTIONAL_CAPABILITIES, } from "../config/redline-json.js";
 import { remove, REMOVE_BRANCH } from "../commands/remove.js";
 import { createHostWithdrawal } from "../remove/host.js";
@@ -26,19 +35,35 @@ import { createSyncHost } from "../sync/host.js";
 import { verifyRemote } from "../verify/remote.js";
 import { createRemoteVerifyHost } from "../verify/host.js";
 import { standardsVersion } from "../commands/sync.js";
+import { isGatePipeline, isGateSource } from "../platforms/types.js";
 const PACKAGE_ROOT = fileURLToPath(new URL('../../', import.meta.url));
 const USAGE = [
     'redline — engineering control plane',
     '',
-    '  redline init [--profile <name>] [--vendors <list>] [--blocking] [--no-a11y] [--speckit] [--dry-run] [--repair]',
-    '               [--adopt-caller] [--skip <list>] [--with <list>]',
+    '  redline init [--profile <list>] [--vendors <list>] [--blocking] [--no-a11y] [--dry-run] [--repair]',
+    '               [--adopt-caller] [--skip <list>] [--with <list>] [--pipeline <name>]',
+    '               [--gate-source org|local] [--no-commit]',
     '      onboard this repository: standards, security floor, merge gate (advisory), registration',
     '      --dry-run   print the plan; writes nothing, needs no credential, contacts no host',
+    '      --no-commit write the files into the working tree and stop: no repository setting is',
+    '                  changed, no branch is made, nothing is committed and no pull request is',
+    '                  opened. Needs no credential and contacts no host, so it works offline — and',
+    '                  so an org-sourced caller is written without checking the organisation',
+    '                  publishes the gate it references. Run redline verify once you have committed',
+    '      --profile <list>  one profile, or several separated by commas, whose stacks are',
+    '                  rendered together — a React app with its own Terraform beside it is',
+    '                  web,infra. The recorded name is sorted, so the order you type cannot',
+    '                  change the artifacts. Omitted, the stack is detected from the checkout',
     '      --vendors <list>  comma-separated vendor ids (copilot,agents,claude,cursor) to render for —',
     '                  overrides both detection and whatever .redline.json already recorded; a vendor',
     '                  the org has not enabled never renders no matter what this list names',
     '      --blocking  promote the merge gate from advisory to blocking',
-    '      --no-a11y, --speckit  recorded in .redline.json for later phases; changes nothing in Phase 1',
+    '      --no-a11y   recorded in .redline.json for a later phase; changes nothing in Phase 1',
+    '      --speckit / --no-speckit, --tmf / --no-tmf  the optional context sections rendered',
+    '                  into the standards artifacts beside the rules. speckit is on by default',
+    '                  and is dropped automatically where the repository already runs Spec Kit;',
+    '                  tmf is off unless asked for. Passing the negative on a later run removes',
+    '                  a section already rendered — the block is regenerated, not appended to',
     '      --repair    re-apply every capability even if this repository looks already onboarded — for',
     '                  labels, review-ownership, repo-property, gate and merge-policy, whose recorded',
     '                  pendingAdmin entry a plain re-run can never clear on its own; composes with --dry-run',
@@ -49,9 +74,34 @@ const USAGE = [
     '                  organisation-wide minimum and is refused by name rather than deselected',
     '      --with <list>  the same names, selected again — how a deselection recorded in .redline.json is',
     '                  reversed',
+    '      --gate-source org|local  where the gate machinery lives. org (the default) references the',
+    '                  reusable workflow published at <org>/.github; local vendors a copy into this',
+    '                  repository at .github/workflows/redline-gate.yml, for a repository whose',
+    '                  organisation has no shared .github repo yet. local is the WEAKER control: the',
+    '                  workflow runs from the pull request\'s own head commit, so a pull request can',
+    '                  edit the gate that is judging it — protect .github/workflows/ with CODEOWNERS.',
+    '                  Omitting the flag keeps whatever the repository already recorded',
     `      --rung <name>  the enforcement rung: ${RUNGS.join(', ')}. A promotion needs recorded`,
     '                  evidence and is refused without it; a demotion is always allowed. Omitting',
     '                  the flag keeps whatever the repository already recorded',
+    '      --branches <patterns>  which branches the merge policy governs, comma separated, in the',
+    '      host\'s own syntax (~DEFAULT_BRANCH, refs/heads/release/*). Default: the default branch',
+    '      alone. Widening this widens an enforcement boundary, so it is never detected for you.',
+    '      --review-owners <list>  who owns the paths seeded into CODEOWNERS — a team, a user or',
+    '      an email, several separated by commas. Defaults to the platform team, which may not',
+    '      exist in your organisation: GitHub ignores an owner it cannot resolve, so the file',
+    '      would install and enforce nothing.',
+    '      --setup <list>  controls to install alongside Redline: dependabot, renovate, codeql.',
+    '      Only what works with no account and no token is offered — writes .github/dependabot.yml,',
+    '      renovate.json, .github/workflows/codeql.yml. An existing file is never overwritten.',
+    '      --integrations <list>  comma-separated ids of controls this repository already runs',
+    '      (sonarqube,snyk,mend,dependabot,renovate,gitleaks,trufflehog,codeql). Overrides what',
+    '      detection found — it reads a checkout, so it cannot see a scanner wired through a',
+    '      shared pipeline template. Recorded, so the correction is made once.',
+    '      --pipeline <name>  github-actions or azure-pipelines — what actually runs this',
+    '                  repository\'s pull request checks. Asked separately from the host because',
+    '                  the two come apart: a repository on GitHub can be built entirely by Azure',
+    '                  Pipelines, and installing an Actions workflow there gates nothing',
     '      --adopt-caller  let Redline take over the gate machinery file (.github/workflows/redline.yml,',
     '                  .azuredevops/redline-gate.yml) when what is already there carries nothing that',
     '                  attributes it to Redline — a 2.1 caller, in practice. Without it the run refuses',
@@ -67,7 +117,8 @@ const USAGE = [
     '      the security floor (secret scanning, push protection, dependency alerts) is the',
     '      organisation\'s minimum, not Redline\'s state — no flag here turns it off',
     '',
-    '  redline verify [--gate] [--repo <owner/name>]',
+    '  redline verify [--gate] [--repo <owner/name>] [--json]',
+    '      --json      the whole report as JSON, for a wrapper that has to act on it',
     '      check this repository still matches what .redline.json claims',
     '      --repo <owner/name>  check a repository over the API, with no checkout — a check',
     '                  that genuinely needs a working tree reports ?? rather than passing',
@@ -81,6 +132,13 @@ const USAGE = [
     '  redline policy --diff-file <path>',
     '      evaluate the rules a checker can decide, with no model call. Exit 1 on a BLOCKER',
     '',
+    '  redline status [--json]',
+    '      what is installed here, how hard it bites, what an administrator still owes',
+    '      you and whether the standards have moved on. Reads the checkout only.',
+    '  redline explain <rule-id> [--json]',
+    '      what a rule means, who decided it, which files it is scoped to and which',
+    '      profiles receive it. The id is the bracketed part of a finding.',
+    '      --list      every rule id in the standards, with its severity',
     '  redline exempt --body-file <path> [--scope <check>]',
     '      decide whether a pull request carries a valid exemption for a failing process',
     '      check — a reason, an actor and an expiry, not a bare label. Exit 0 if it applies',
@@ -118,6 +176,37 @@ export async function run(argv, deps = {}) {
     const cwd = deps.cwd ?? process.cwd();
     const root = deps.root ?? PACKAGE_ROOT;
     const log = createLog(deps.sink);
+    const interactive = deps.isInteractive ?? (() => isInteractive());
+    // The host is read from the git remote alone, with no credential and no
+    // request — the menu's first question has to render before either exists,
+    // because "Dry run" is one of its answers. A remote this cannot classify is
+    // `null`, which is exactly the case the host question is there to settle.
+    const detectHost = () => {
+        try {
+            return parseRemote(createGit(cwd).remoteUrl()).host;
+        }
+        catch {
+            return null;
+        }
+    };
+    const runInitWizard = async (dir, packageRoot) => {
+        const prompter = deps.prompter?.() ?? createPrompter();
+        const answers = await runWizard(prompter, gatherFacts({ cwd: dir, root: packageRoot, detectedHost: detectHost() }));
+        // The prompter comes back with the answers because the work starts the
+        // moment the last question is answered, and the operator has to be able to
+        // see that it did. Building a second one here would mean a second set of
+        // signal handlers on the same terminal.
+        return { answers, prompter };
+    };
+    // Report colour is decided the same way the prompts decide it, and from the
+    // same env: NO_COLOR, FORCE_COLOR, a dumb terminal and a pipe all have to
+    // mean the same thing in both halves of one run. An injected sink is a test
+    // or a pipe, so it is never painted.
+    const reportTheme = {
+        palette: palette(deps.sink === undefined && colorEnabled(process.env, process.stdout.isTTY === true), colorDepth(process.env)),
+        glyphs: glyphs(process.env),
+        width: process.stdout.columns ?? 80,
+    };
     const resolve = deps.resolvePlatform ??
         ((dir, options) => defaultResolvePlatform(dir, options));
     const [command, ...rest] = argv;
@@ -144,15 +233,31 @@ export async function run(argv, deps = {}) {
                     blocking: { type: 'boolean' },
                     'no-a11y': { type: 'boolean' },
                     speckit: { type: 'boolean' },
+                    'no-speckit': { type: 'boolean' },
+                    tmf: { type: 'boolean' },
+                    'no-tmf': { type: 'boolean' },
                     'dry-run': { type: 'boolean' },
+                    'no-commit': { type: 'boolean' },
                     repair: { type: 'boolean' },
                     'adopt-caller': { type: 'boolean' },
                     skip: { type: 'string' },
                     with: { type: 'string' },
                     rung: { type: 'string' },
+                    pipeline: { type: 'string' },
+                    'gate-source': { type: 'string' },
+                    integrations: { type: 'string' },
+                    'review-owners': { type: 'string' },
+                    setup: { type: 'string' },
+                    branches: { type: 'string' },
                 },
                 allowPositionals: false,
             }));
+            // `redline init` with nothing after it, at a terminal, is a person asking
+            // to be walked through onboarding — so walk them through it. Any flag at
+            // all means the caller has already decided, and the menu would be in the
+            // way; CI and pipes never see it (isInteractive), so the scripted path is
+            // byte-identical to what it was before the menu existed.
+            const wizard = rest.length === 0 && interactive() ? await runInitWizard(cwd, root) : null;
             const names = (list) => list === undefined
                 ? []
                 : list
@@ -161,7 +266,14 @@ export async function run(argv, deps = {}) {
                     .filter((name) => name !== '');
             // Throws a usage RedlineError on an unknown or non-optional name, before
             // a platform is resolved or a byte is written.
-            const selection = capabilitySelection(names(values.skip), names(values.with));
+            //
+            // The menu answers arrive here as the same two lists the flags produce,
+            // rather than as a parallel set of options: a capability the operator
+            // deselected in the wizard is a `--skip`, and there is exactly one place
+            // that decides what a skip means.
+            const selection = wizard
+                ? capabilitySelection(OPTIONAL_CAPABILITIES.filter((name) => !wizard.answers.capabilities.includes(name)), [...wizard.answers.capabilities])
+                : capabilitySelection(names(values.skip), names(values.with));
             const menu = { ...selection.menu };
             if (values.blocking !== undefined)
                 menu.blockingGate = values.blocking;
@@ -169,6 +281,16 @@ export async function run(argv, deps = {}) {
                 menu.accessibility = !values['no-a11y'];
             if (values.speckit !== undefined)
                 menu.speckit = values.speckit;
+            if (values['no-speckit'] === true)
+                menu.speckit = false;
+            if (values.tmf !== undefined)
+                menu.tmf = values.tmf;
+            if (values['no-tmf'] === true)
+                menu.tmf = false;
+            if (wizard) {
+                menu.speckit = wizard.answers.speckit;
+                menu.tmf = wizard.answers.tmf;
+            }
             // Same "no default" reasoning as the menu flags above: undefined is how
             // init() tells "nothing typed, keep detection or the recorded
             // selection" from "the caller typed an empty list".
@@ -181,54 +303,136 @@ export async function run(argv, deps = {}) {
             if (values.rung !== undefined && !isRung(values.rung)) {
                 throw new RedlineError('usage', `--rung must be one of ${RUNGS.join(', ')}, not "${values.rung}"`, 'observe reports and blocks nothing; block-blocker stops a merge on a BLOCKER');
             }
-            const dryRun = values['dry-run'] === true;
+            if (values.pipeline !== undefined && !isGatePipeline(values.pipeline)) {
+                throw new RedlineError('usage', `--pipeline must be github-actions or azure-pipelines, not "${values.pipeline}"`, 'a repository on GitHub whose pull request checks are Azure Pipelines wants azure-pipelines');
+            }
+            if (values['gate-source'] !== undefined && !isGateSource(values['gate-source'])) {
+                throw new RedlineError('usage', `--gate-source must be org or local, not "${values['gate-source']}"`, 'org references the reusable gate in the organisation .github repository; local vendors a ' +
+                    'copy into this repository, which means a pull request can edit the gate judging it');
+            }
+            const pipelineChoice = wizard?.answers.pipeline ?? values.pipeline;
+            const gateSourceChoice = wizard?.answers.gateSource ?? values['gate-source'];
+            const dryRun = values['dry-run'] === true || wizard?.answers.action === 'dry-run';
+            const noCommit = values['no-commit'] === true || wizard?.answers.action === 'no-commit';
             const repair = values.repair === true;
             const adoptCaller = values['adopt-caller'] === true;
             // A dry run sends no request, so it must not require a credential —
-            // see ResolvePlatformOptions.lazyCredentials. Every other path here
-            // resolves one up front, exactly as before.
-            const platform = await resolve(cwd, dryRun ? { lazyCredentials: true } : {});
+            // see ResolvePlatformOptions.lazyCredentials. --no-commit contacts no host
+            // either, so it must not demand a credential up front any more than a dry
+            // run does — working offline is most of the reason it exists. Every other
+            // path here resolves one up front, exactly as before.
+            const platform = await resolve(cwd, dryRun || noCommit ? { lazyCredentials: true } : {});
+            const profileChoice = wizard?.answers.profile ?? values.profile;
+            const vendorChoice = wizard ? [...wizard.answers.vendors] : vendors;
+            const rungChoice = wizard?.answers.rung ?? values.rung;
+            const setupChoice = wizard
+                ? [...wizard.answers.setup]
+                : values.setup?.split(',').map((id) => id.trim()).filter((id) => id !== '');
+            const branchChoice = values.branches?.split(',').map((b) => b.trim()).filter((b) => b !== '');
+            const ownerChoice = wizard
+                ? [...wizard.answers.reviewOwners]
+                : values['review-owners']?.split(',').map((o) => o.trim()).filter((o) => o !== '');
+            const integrationChoice = wizard
+                ? [...wizard.answers.integrations]
+                : values.integrations?.split(',').map((id) => id.trim()).filter((id) => id !== '');
+            // Only the wizard path spins: a scripted `redline init` in CI has nobody
+            // watching, and an animated line in a build log is noise with no reader.
+            // Reassigned, not just stopped: the fallback prompt below has to take the
+            // terminal back from the spinner to be readable at all, and the run
+            // carries on afterwards — so it gets a fresh one rather than finishing in
+            // silence.
+            let task = wizard?.prompter.task('onboarding this repository') ?? null;
             const report = await init(platform, {
                 cwd,
                 root,
-                ...(values.profile ? { profile: values.profile } : {}),
-                ...(vendors ? { vendors } : {}),
+                ...(wizard ? { onStep: (label) => task?.update(label) } : {}),
+                ...(profileChoice ? { profile: profileChoice } : {}),
+                ...(vendorChoice ? { vendors: vendorChoice } : {}),
                 ...(dryRun ? { dryRun: true } : {}),
+                ...(noCommit ? { noCommit: true } : {}),
                 ...(repair ? { repair: true } : {}),
                 ...(adoptCaller ? { adoptCaller: true } : {}),
-                ...(values.rung ? { rung: values.rung } : {}),
+                ...(rungChoice ? { rung: rungChoice } : {}),
+                ...(integrationChoice ? { integrations: integrationChoice } : {}),
+                ...(ownerChoice && ownerChoice.length > 0 ? { reviewOwners: ownerChoice } : {}),
+                ...(branchChoice && branchChoice.length > 0 ? { branches: branchChoice } : {}),
+                ...(setupChoice && setupChoice.length > 0 ? { setup: setupChoice } : {}),
+                ...(pipelineChoice ? { pipeline: pipelineChoice } : {}),
+                ...(gateSourceChoice ? { gateSource: gateSourceChoice } : {}),
+                // Offered only at a terminal, and only when the planning pass finds the
+                // organisation publishes no gate. A scripted run gets the denial it has
+                // always got: vendoring the gate is a weaker control, and nothing
+                // unattended should be able to choose it on an operator's behalf.
+                ...(wizard
+                    ? {
+                        onGateFallback: async (detail) => {
+                            task?.stop();
+                            const vendor = await wizard.prompter.select(`${detail}. Install the gate where?`, [
+                                {
+                                    value: false,
+                                    label: 'skip the gate for now',
+                                    hint: 'everything else installs; re-run once the org publishes one',
+                                },
+                                {
+                                    value: true,
+                                    label: 'vendor it into this repository',
+                                    hint: 'weaker: a pull request can edit the gate that judges it',
+                                },
+                            ], false);
+                            task = wizard.prompter.task('onboarding this repository');
+                            return vendor;
+                        },
+                    }
+                    : {}),
                 menu,
                 capabilities: selection.capabilities,
-            });
-            log.info(`profile ${report.profile}`);
-            if (report.migratedFrom)
-                log.info(`migrated from ${report.migratedFrom}`);
-            // Printed on every path, settled included: a report that falls silent
-            // about what was never attempted cannot be told from one where it broke.
-            if (report.optedOut.length > 0)
-                log.info(`opted out: ${report.optedOut.join(', ')}`);
-            for (const note of report.notes)
-                log.info(note);
+            }).finally(() => task?.stop());
+            const summary = {
+                profile: report.profile,
+                migratedFrom: report.migratedFrom,
+                optedOut: report.optedOut,
+                notes: report.notes,
+                files: report.files,
+                removals: report.removals,
+                outcomes: report.outcomes,
+                pullRequestUrl: report.pullRequest?.url ?? null,
+                pendingAdmin: report.pendingAdmin,
+                dryRun: report.dryRun,
+                hostPlan: report.hostPlan,
+            };
             if (report.dryRun) {
-                log.info('dry run — nothing was written, read or changed on the host');
                 if (report.alreadyOnboarded) {
+                    for (const line of renderReport({ ...summary, files: [], hostPlan: [] }, reportTheme)) {
+                        log.info(line);
+                    }
+                    log.info('');
                     log.info('already onboarded — no file would change (host settings were not read)');
                     return 0;
                 }
-                for (const file of report.files) {
-                    log.info(`  would ${report.removals.includes(file) ? 'remove' : 'write '}  ${file}`);
-                }
-                for (const step of report.hostPlan)
-                    log.info(`  would apply   ${step}`);
-                for (const [key, value] of Object.entries(report.menu))
-                    log.info(`  menu   ${key}: ${value}`);
+                for (const line of renderReport(summary, reportTheme))
+                    log.info(line);
+                log.info('');
+                // The menu is the half of a dry run the file list cannot show: two of
+                // its answers move no file at all, and a preview that hid them would
+                // send an operator to `--blocking` to find out what `--blocking` did.
+                log.info(`  menu: ${Object.entries(report.menu)
+                    .map(([key, value]) => `${key}=${value}`)
+                    .join(' ')}`);
+                log.info('');
+                log.info('dry run — nothing was written, read or changed on the host');
                 return 0;
             }
-            for (const file of report.files) {
-                log.info(`  ${report.removals.includes(file) ? 'remove' : 'write '}  ${file}`);
-            }
-            for (const outcome of report.outcomes) {
-                log.info(`  ${outcome.status.padEnd(11)} ${outcome.capability}  ${outcome.detail}`);
+            for (const line of renderReport(summary, reportTheme))
+                log.info(line);
+            log.info('');
+            // Said plainly, because the one thing an operator must not do after this
+            // is assume the repository is onboarded: the files are on disk, the host
+            // is untouched, and the branch a full run would have opened does not
+            // exist. The run that finishes the job is named rather than described.
+            if (report.noCommit === true) {
+                log.info('  not committed — the files are in your working tree. Review them, commit them, then ' +
+                    'run redline init to apply the repository settings and open the pull request');
+                return 0;
             }
             if (report.pendingAdmin.length > 0) {
                 // On the already-onboarded path this run applied nothing, so the list
@@ -247,10 +451,21 @@ export async function run(argv, deps = {}) {
                 log.error(`could not open the pull request: ${report.pullRequestError}`, `the Redline changes are on branch ${ONBOARD_BRANCH} — push it if it is not already on origin, then open the pull request manually`);
                 return exitCodeFor('failed');
             }
-            if (report.pullRequest)
-                log.info(`pull request: ${report.pullRequest.url}`);
-            else if (report.alreadyOnboarded)
-                log.info('already onboarded — nothing to change');
+            if (report.pullRequest) {
+                // The URL itself is printed by the report's own Pull request section.
+                // What that section cannot say is why the working tree looks untouched:
+                // onboarding commits to its own branch and pushes it, so `git status`
+                // here stays clean. Without this the run looked like it did nothing —
+                // the first real onboarding ended with the operator running `init` a
+                // second time and being told "already onboarded" by a repository they
+                // believed was not.
+                log.info(`  the changes are committed on ${ONBOARD_BRANCH} and pushed, not in your working tree —`);
+                log.info('  `git status` here stays clean. Review and merge the pull request above.');
+            }
+            else if (report.alreadyOnboarded) {
+                log.info(`already onboarded — nothing to change (recorded in .redline.json; ` +
+                    `re-run with --repair to re-apply every capability)`);
+            }
             return 0;
         }
         if (command === 'remove') {
@@ -309,7 +524,11 @@ export async function run(argv, deps = {}) {
         if (command === 'verify') {
             const { values } = parseCliArgs(() => parseArgs({
                 args: rest,
-                options: { gate: { type: 'boolean', default: false }, repo: { type: 'string' } },
+                options: {
+                    gate: { type: 'boolean', default: false },
+                    repo: { type: 'string' },
+                    json: { type: 'boolean', default: false },
+                },
                 allowPositionals: false,
             }));
             if (values.repo !== undefined) {
@@ -321,9 +540,15 @@ export async function run(argv, deps = {}) {
                 const remoteReport = await verifyRemote(remoteHost, remoteRef, {
                     root,
                     standardsVersion: standardsVersion(root),
+                    cliVersion: CLI_VERSION,
                 });
-                log.info(`${values.repo} (${remoteRef.defaultBranch})`);
-                log.report(remoteReport.findings);
+                if (values.json === true) {
+                    log.info(JSON.stringify({ repo: values.repo, ref: remoteRef.defaultBranch, ...remoteReport }, null, 2));
+                }
+                else {
+                    log.info(`${values.repo} (${remoteRef.defaultBranch})`);
+                    log.report(remoteReport.findings);
+                }
                 // Same mapping as the local path: one finding means the repository was
                 // never onboarded, which is a different thing to tell an operator than
                 // onboarded-and-drifted.
@@ -333,7 +558,13 @@ export async function run(argv, deps = {}) {
             // resolve is passed unevaluated: verify() must be able to report "not
             // onboarded" without a host credential — see cli/commands/verify.ts.
             const report = await verify(() => resolve(cwd), { cwd, root, gate: values.gate === true });
-            log.report(report.findings);
+            // The findings are the same object either way. `--json` exists because a
+            // tool whose whole claim is auditability was unreadable by anything but a
+            // human, and a wrapper had to scrape prose to learn what it already knew.
+            if (values.json === true)
+                log.info(JSON.stringify(report, null, 2));
+            else
+                log.report(report.findings);
             // verify() short-circuits to exactly one finding when .redline.json is
             // missing or corrupt (see cli/commands/verify.ts), precisely so this
             // mapping can tell "never onboarded" (usage, 2) apart from "onboarded
@@ -460,6 +691,63 @@ export async function run(argv, deps = {}) {
             }
             return report.ok ? 0 : exitCodeFor('failed');
         }
+        if (command === 'status') {
+            const { values } = parseCliArgs(() => parseArgs({
+                args: rest,
+                options: { json: { type: 'boolean', default: false } },
+                allowPositionals: false,
+            }));
+            const report = status(cwd, root);
+            if (values.json === true) {
+                log.info(JSON.stringify(report, null, 2));
+            }
+            else {
+                for (const line of formatStatus(report))
+                    log.info(line);
+            }
+            // Not onboarded is an answer, not a failure: `status` is what somebody
+            // runs to find that out, and exiting non-zero would break the script that
+            // asked.
+            return 0;
+        }
+        if (command === 'explain') {
+            const { values, positionals } = parseCliArgs(() => parseArgs({
+                args: rest,
+                options: { list: { type: 'boolean', default: false }, json: { type: 'boolean', default: false } },
+                allowPositionals: true,
+            }));
+            const rules = loadRules(root);
+            if (values.list === true) {
+                for (const rule of rules.values()) {
+                    log.info(`${rule.severity.padEnd(10)} ${rule.id}`);
+                }
+                log.info(`${rules.size} rule(s) across the core standard and every stack`);
+                return 0;
+            }
+            const id = positionals[0];
+            if (id === undefined) {
+                throw new RedlineError('usage', 'redline explain needs a rule id', 'the id is the part in brackets on a finding: redline explain core/hardcoded-secrets');
+            }
+            const found = explain(root, id);
+            if (values.json === true) {
+                log.info(JSON.stringify(found, null, 2));
+                return 0;
+            }
+            log.info(`${found.rule.severity} ${found.rule.id}`);
+            log.info('');
+            log.info(`  ${found.rule.text}`);
+            log.info('');
+            log.info(`  decided by   ${found.deterministic ? 'a checker, with no model call' : 'review judgement'}`);
+            log.info(`  defined in   ${found.rule.source}:${found.rule.line}`);
+            if (found.globs.length > 0) {
+                log.info(`  applies to   ${found.globs.join(', ')}`);
+            }
+            else {
+                log.info('  applies to   every file — the core standard is not scoped by stack');
+            }
+            log.info(`  reaches      ${found.profiles.join(', ')}`);
+            return 0;
+        }
         if (command === 'exempt') {
             const { values } = parseCliArgs(() => parseArgs({
                 args: rest,
@@ -563,6 +851,13 @@ export async function run(argv, deps = {}) {
         return exitCodeFor('usage');
     }
     catch (error) {
+        // Cancelling at a prompt is a decision, not a failure. It must not print an
+        // `error` line: an operator who pressed Ctrl-C already knows what happened,
+        // and a wrapping script reading exit 1 would file it as onboarding broken.
+        if (error instanceof Cancelled) {
+            log.info('cancelled — nothing was written');
+            return error.exitCode;
+        }
         if (isRedlineError(error)) {
             log.error(error.message, error.hint);
             return error.exitCode;