redlinegate 0.0.1 → 0.0.3

package/dist/commands/init.js

@@ -1,24 +1,28 @@
 import { existsSync, readdirSync, readFileSync, rmSync } from 'node:fs';
 import { join } from 'node:path';
 import { isRedlineError, RedlineError } from "../core/errors.js";
-import { CLI_VERSION } from "../core/version.js";
+import { CLI_VERSION, UNPUBLISHED_VERSION } from "../core/version.js";
+import { VENDORED_GATE_PATH } from "../platforms/github/vendor.js";
 import { canPromote } from "../enforce/ladder.js";
-import { CAPABILITY_KEYS, CONFIG_FILE, MENU_KEYS, deselectedCapabilities, labelsCarriedByGate, readConfig, writeConfig, } from "../config/redline-json.js";
+import { CAPABILITY_KEYS, MENU_DEFAULTS, CONFIG_FILE, MENU_KEYS, deselectedCapabilities, labelsCarriedByGate, readConfig, writeConfig, } from "../config/redline-json.js";
 import { proposeProfile } from "../detect/stack.js";
 import { scanRepo } from "../detect/scan.js";
 import { loadManifest } from "../render/manifest.js";
 import { resolveProfile } from "../render/profile.js";
 import { render } from "../render/standards.js";
 import { renderCommands, COMMAND_HOSTS } from "../render/commands.js";
+import { CONTEXTS, detectSpecKit } from "../render/contexts.js";
+import { surveyRepo, TOOL_PROBES } from "../detect/existing.js";
+import { applySetup, offerable } from "../detect/setup.js";
 import { LOCAL_RULES_FILE } from "../render/vendors.js";
 import { isPending } from "../platforms/types.js";
-export const DEFAULT_MENU = {
-    blockingGate: false,
-    adrForLargeDiffs: true,
-    accessibility: true,
-    speckit: false,
-    sensitivePathReviewers: true,
-};
+// What a repository gets when it says nothing. Every default here has to be
+// safe on a repository nobody has looked at, because that is the one the
+// command is usually run on.
+// Re-exported from the config module, which owns them so the parser can fill a
+// key a repository was onboarded before. See MENU_DEFAULTS there for what each
+// default is and why.
+export const DEFAULT_MENU = MENU_DEFAULTS;
 // Named once so the label FLOOR_GATE soft-fails on and the label
 // openPullRequest applies below share one literal instead of two that could
 // drift apart, and so web/components/journey.tsx's hardcoded SYNC_LABEL can
@@ -63,11 +67,29 @@ export const SENSITIVE_PATHS = [
     '/terraform/',
     'Dockerfile',
 ];
+// The team that owns the paths Redline seeds into CODEOWNERS.
+//
+// A default, never a fact. GitHub silently ignores an owner it cannot resolve —
+// no error on push, no warning in the UI — so a CODEOWNERS naming a team that
+// does not exist reports as installed and enforces nothing, which is the worst
+// of the three possible outcomes. This was hardcoded, which meant every
+// organisation but the one it was written for got exactly that. `--review-owners`
+// states the real owners; absent, the capability still defaults to this name and
+// the report says plainly that it is a guess.
 export const OWNING_TEAM = 'platform-engineering';
 // Accessibility rules only exist for the stacks that render a user interface,
 // so recording `accessibility: true` on a Terraform or Go repository files a
 // commitment against rules that will never be rendered there.
-const ACCESSIBILITY_STACKS = ['react', 'react-native', 'kotlin', 'swift'];
+const ACCESSIBILITY_STACKS = [
+    'react',
+    'react-native',
+    'angular',
+    'vue',
+    'svelte',
+    'dom',
+    'kotlin',
+    'swift',
+];
 // The 2.1 artifact that identifies a repository onboarded by the previous
 // generation. It is NOT in the removal list below: v3's GitHub adapter writes
 // the same path, so removing it would delete the gate this run just installed
@@ -88,8 +110,33 @@ const LEGACY_SCRIPT = /^redline-.*\.sh$/;
 // The brownfield rule applies to files as much as to host objects: what carries
 // no Redline marker belongs to a human and is never deleted.
 const REDLINE_OWNED = /(?:managed|generated|installed) by redline|REDLINE:BEGIN/i;
-export function sensitivePathRules(org) {
-    return SENSITIVE_PATHS.map((pattern) => ({ pattern, owners: [`@${org}/${OWNING_TEAM}`] }));
+/**
+ * Who owns the sensitive paths.
+ *
+ * `owners` are taken as written when given: a team (`@org/team`), a user
+ * (`@person`) and an email are all valid CODEOWNERS entries, and Redline is not
+ * the right place to decide which an organisation uses. A bare name is qualified
+ * with the org, because `@team` alone means a *user* to GitHub and would silently
+ * own nothing.
+ */
+export function sensitivePathRules(org, owners) {
+    const resolved = owners !== undefined && owners.length > 0
+        ? owners.map((owner) => qualifyOwner(org, owner))
+        : [`@${org}/${OWNING_TEAM}`];
+    return SENSITIVE_PATHS.map((pattern) => ({ pattern, owners: resolved }));
+}
+// CODEOWNERS distinguishes the three by shape, so this only ever adds what is
+// missing: `@name` is a USER and is left alone — qualifying it to `@org/name`
+// would turn a person into a team that does not exist — `@org/team` and an email
+// address are already complete, and only a bare word is ambiguous enough to need
+// the organisation putting in front of it.
+function qualifyOwner(org, owner) {
+    const trimmed = owner.trim();
+    if (trimmed.startsWith('@'))
+        return trimmed;
+    if (trimmed.includes('@'))
+        return trimmed;
+    return trimmed.includes('/') ? `@${trimmed}` : `@${org}/${trimmed}`;
 }
 export const ONBOARD_BRANCH = 'redline/onboard';
 // Local and free — both adapters read the checkout and nothing else — but the
@@ -172,7 +219,7 @@ const VENDOR_MARKERS = [
 // org-enabled vendor) rather than an empty selection — that is the greenfield
 // case the standard is written for, not a repository that opted out of all of
 // them.
-function detectVendors(cwd, orgDefault) {
+export function detectVendors(cwd, orgDefault) {
     const found = VENDOR_MARKERS.filter((marker) => marker.paths.some((relPath) => existsSync(join(cwd, relPath)))).map((marker) => marker.vendor);
     return found.length > 0 ? found : orgDefault;
 }
@@ -209,6 +256,7 @@ export async function init(platform, opts) {
     const repair = opts.repair === true;
     const manifest = loadManifest(root);
     const now = opts.now ?? (() => new Date());
+    const step = opts.onStep ?? (() => { });
     // Profile resolution happens before any host call or write: a bad --profile
     // flag must fail clean, with nothing on disk and nothing sent to the host.
     const detected = opts.profile ?? proposeProfile(scanRepo(cwd)).profile;
@@ -237,6 +285,12 @@ export async function init(platform, opts) {
     // enforcement keeps what the repository already had: a re-run for an unrelated
     // reason silently promoting a repository is how a ladder loses the trust it
     // exists to build.
+    // Absent keeps what the repository recorded, for the same reason the rung
+    // does: `local` is the weaker control, and a re-run that said nothing about
+    // the gate must not be able to move a repository onto it — or, just as bad,
+    // silently move a deliberately-local repository back to an organisation gate
+    // that does not exist and lose it the gate entirely.
+    let gateSource = opts.gateSource ?? existing?.gateSource ?? 'org';
     const currentRung = existing?.rung ?? 'observe';
     const rungNotes = [];
     let rung = currentRung;
@@ -268,7 +322,12 @@ export async function init(platform, opts) {
     }
     // A dry run must work offline and with an unscoped token: repoRef() is a
     // live GET, so the plan is built from what the local clone already knows.
-    const ref = dryRun ? platform.localRef(cwd) : await platform.repoRef(cwd);
+    // `--no-commit` is under the same rule and for the same reason — it is
+    // documented as contacting no host, and this read is a host contact whatever
+    // else the run goes on to skip.
+    const offline = dryRun || opts.noCommit === true;
+    step(offline ? 'reading the repository' : `reading ${platform.host}`);
+    const ref = offline ? platform.localRef(cwd) : await platform.repoRef(cwd);
     // detected <- what this repository already recorded <- what the caller
     // typed, the same precedence the menu resolves under. The org ceiling is
     // deliberately not applied to the RECORD: render() enforces it on every call
@@ -278,16 +337,55 @@ export async function init(platform, opts) {
         .filter(([, v]) => v.enabled)
         .map(([k]) => k);
     const vendors = opts.vendors ?? existing?.vendors ?? detectVendors(cwd, orgVendors);
-    const gateOptions = {
+    // The same courtesy Spec Kit gets, generalised to the rest of the toolchain.
+    // A repository with a mature pipeline already runs a scanner for most of what
+    // the gate would add; installing a second one beside it is not defence in
+    // depth, it is two sets of findings and two exemption paths for one problem.
+    // What Redline still brings such a repository is the part nothing else does —
+    // the standards the AI reviews against, and a check that they were applied —
+    // so detection narrows the gate rather than cancelling the onboarding.
+    const survey = surveyRepo(cwd);
+    // Precedence, strongest first: what the caller stated this run, then what the
+    // repository recorded, then what detection found. Someone who corrected the
+    // survey once must not have to correct it again on every re-run.
+    const stated = opts.integrations ?? (existing !== null && existing.integrations.length > 0 ? existing.integrations : null);
+    const integrations = stated ?? survey.tools.map((tool) => tool.id);
+    const evidenceOf = new Map(survey.tools.map((tool) => [tool.id, tool.evidence]));
+    // Which of the gate's own jobs those tools make redundant. It is computed
+    // here, above the gate options, because the planning pass and the real
+    // install must build the SAME caller workflow: a stand-down list that
+    // appeared between them would make the two disagree about whether the file
+    // changed, which is the class of bug that plans a path nothing writes.
+    //
+    // Every tool on the list narrows the gate, whatever put it there. Detection
+    // deselects rather than duplicates — that is what cli/detect/existing.ts is
+    // for — and the wizard hands its own findings back through --integrations, so
+    // treating a detected tool as weaker than a typed one would make the same
+    // repository behave differently depending on which entry point ran it.
+    //
+    // `dependencies` and `secrets` are the two jobs no label can waive, so this
+    // is a security decision and never a silent one: every stand-down names the
+    // tool, the marker that proved it, and the flag that puts the job back.
+    const standDown = [
+        ...new Set(integrations.flatMap((id) => {
+            const covers = TOOL_PROBES.find((probe) => probe.id === id)?.standsDown;
+            return covers === undefined || covers === null ? [] : [covers];
+        })),
+    ];
+    let gateOptions = {
         ...FLOOR_GATE,
+        ...(opts.pipeline ? { pipeline: opts.pipeline } : {}),
         ...(menu.adrForLargeDiffs ? {} : { adrDiffThreshold: Number.MAX_SAFE_INTEGER }),
         ...(opts.adoptCaller === true ? { adoptCaller: true } : {}),
         ...(capabilities.labels ? {} : { manageLabels: false }),
+        ...(standDown.length > 0 ? { standDown } : {}),
+        ...(gateSource === 'local' ? { gateSource } : {}),
+        ...(opts.noCommit === true ? { offline: true } : {}),
         // Written into the caller workflow, so the gate blocks or reports according
         // to the rung recorded here rather than needing a second source of truth.
         rung,
     };
-    const ownershipRules = sensitivePathRules(ref.org);
+    const ownershipRules = sensitivePathRules(ref.org, opts.reviewOwners);
     // The gate and ownership file diffs are computed in check mode FIRST, before
     // a single host setting is touched. Without it there was no way to know a
     // re-run had nothing to do until four host objects had already been
@@ -299,8 +397,13 @@ export async function init(platform, opts) {
     // Redline, and its message says nothing was written; planning after the
     // render made that untrue, leaving every vendor artifact and command file on
     // disk with no .redline.json, no branch and no pull request to carry them.
-    const gatePlan = capabilities.gate
-        ? await platform.installGate(ref, cwd, gateOptions, true)
+    // `preflight: !dryRun` is what makes this pass a real plan rather than an
+    // optimistic one: a live run may ask the host whether the reusable workflow
+    // exists, and must, because the answer decides which paths it will stage. A
+    // dry run may not — it contacts no host and needs no credential.
+    step('planning the change');
+    let gatePlan = capabilities.gate
+        ? await platform.installGate(ref, cwd, { ...gateOptions, preflight: !dryRun }, true)
         : { files: [], outcomes: [] };
     const ownershipPlan = menu.sensitivePathReviewers
         ? await platform.ensureReviewOwnership(ref, cwd, ownershipRules, true)
@@ -309,6 +412,39 @@ export async function init(platform, opts) {
     // acting on any of it. Detection informs; it does not decide.
     const machinery = observeGateMachinery(platform, cwd);
     const notes = [...rungNotes];
+    // The organisation publishes no gate, and this run has written nothing yet.
+    // Offer the repository the one that fits in it, and re-plan so both passes
+    // agree on the paths — planning one gate source and installing another is
+    // exactly how a run stages a file nothing wrote.
+    if (gatePlan.vendorableGate === true && opts.onGateFallback !== undefined) {
+        const detail = `${ref.org}/.github publishes no Redline gate`;
+        if (await opts.onGateFallback(detail)) {
+            gateSource = 'local';
+            gateOptions = { ...gateOptions, gateSource };
+            gatePlan = await platform.installGate(ref, cwd, { ...gateOptions, preflight: !dryRun }, true);
+            notes.push(`${detail}, so the gate is vendored into this repository instead`);
+        }
+    }
+    // Said on every local run, not only the one that chose it here: a repository
+    // that recorded `local` three runs ago carries the same property and the same
+    // exposure, and a note that appears once at onboarding and never again is a
+    // note nobody reads at the moment it matters.
+    if (capabilities.gate && gateSource === 'local') {
+        notes.push(`the gate is vendored at ${VENDORED_GATE_PATH} rather than referenced from ` +
+            `${ref.org}/.github. It runs from the pull request's own head commit, so a pull ` +
+            'request that edits it changes the gate judging it — including standing down the ' +
+            'dependency and secret jobs, which no label can waive. Move to --gate-source org ' +
+            'once the organisation publishes a gate');
+        // The protection already exists and is simply off: `/.github/workflows/` is
+        // the first entry in SENSITIVE_PATHS. Naming the command rather than
+        // turning it on, because the owner it would write is a guess — a CODEOWNERS
+        // line naming a team that does not exist blocks every pull request in the
+        // repository, which is worse than the exposure it was meant to close.
+        if (!menu.sensitivePathReviewers) {
+            notes.push('nothing requires review on .github/workflows/ here, so that edit needs no owner\'s ' +
+                'approval. Re-run with --with review-ownership --review-owners <team> to require one');
+        }
+    }
     // Detection, not a decision. `readGateMachinery` is local and free, and what
     // it gives that nothing else here has is the path this host runs its gate
     // from — so the only claim made is what else is already sitting in that
@@ -351,9 +487,64 @@ export async function init(platform, opts) {
             'it — the selection recorded in .redline.json is unchanged, and re-selecting the gate ' +
             'brings them back');
     }
+    // Spec Kit is a separate tool that scaffolds its own files and carries its own
+    // account of how the repository works. Where it is already installed, Redline
+    // drops its section rather than adding a second one beside it — and says so,
+    // because a context silently missing from the artifacts is indistinguishable
+    // from one that was never asked for.
+    const specKitAt = detectSpecKit(cwd);
+    if (specKitAt !== null && menu.speckit) {
+        menu.speckit = false;
+        notes.push(`this repository already runs Spec Kit (${specKitAt}), so Redline left the spec-driven ` +
+            'development context out rather than writing a second account of it beside the one Spec ' +
+            'Kit maintains — pass --speckit to include it anyway');
+    }
+    for (const id of integrations) {
+        const probe = TOOL_PROBES.find((p) => p.id === id);
+        if (probe === undefined)
+            continue;
+        const how = evidenceOf.get(id) ?? 'you said so — detection could not see it from the checkout';
+        const covers = probe.standsDown;
+        notes.push(covers === null
+            ? `this repository already runs ${probe.label} (${how}) — noted; Redline installs nothing that overlaps it`
+            : `this repository already runs ${probe.label} (${how}), which covers what Redline's own ` +
+                `${covers} check would report, so the gate's ${covers} job is stood down here rather ` +
+                `than run a second time. To run it anyway, re-run with an --integrations list that ` +
+                `leaves ${id} out`);
+    }
+    // Detected, and then unticked. Worth saying: the next run will not re-detect
+    // it into the plan, and a reader of the report should know why it is absent.
+    for (const tool of survey.tools) {
+        if (!integrations.includes(tool.id)) {
+            notes.push(`${tool.label} was detected (${tool.evidence}) but recorded as not in use here`);
+        }
+    }
+    // Controls the operator asked for. Written here rather than by an adapter
+    // because they are plain repository files on any host that supports them, and
+    // they ride in the same pull request as everything else this run writes.
+    const wanted = new Set(opts.setup ?? []);
+    const chosen = offerable(cwd, platform.host, stacks).filter(({ integration }) => wanted.has(integration.id));
+    const setupResult = applySetup(cwd, chosen, dryRun);
+    for (const path of setupResult.skipped) {
+        // Never overwritten: a repository with its own renovate.json has a
+        // considered one, and replacing it with a generated default is the kind of
+        // help that costs a team a week of tuning.
+        notes.push(`${path} already exists and was left exactly as it is`);
+    }
+    for (const { integration } of chosen) {
+        if (integration.id === 'renovate' && setupResult.written.includes('renovate.json')) {
+            notes.push('renovate.json is written, but Renovate only runs once the Renovate app is installed on ' +
+                'the organisation — the file alone does nothing');
+        }
+        if (integration.id === 'codeql' && setupResult.written.includes('.github/workflows/codeql.yml')) {
+            notes.push('CodeQL is written; on a private repository it needs GitHub Advanced Security to run');
+        }
+    }
+    const contexts = CONTEXTS.filter((context) => menu[context.key]).map((context) => context.key);
     // Files next, host settings after: a denied host call must never cost the
     // file-level work that already succeeded.
-    const rendered = render({ root, profile, out: cwd, vendors, check: dryRun });
+    step(dryRun ? 'rendering the standards (plan only)' : 'rendering the standards');
+    const rendered = render({ root, profile, out: cwd, vendors, contexts, check: dryRun });
     // The ceiling render() applies internally, applied here too. renderCommands
     // cannot enforce it for itself: COMMAND_HOSTS carries hosts the vendor
     // manifest has no entry for at all (opencode), which is not the same thing
@@ -381,6 +572,7 @@ export async function init(platform, opts) {
         ...commands.written,
         ...gatePlan.files,
         ...ownershipPlan.files,
+        ...setupResult.written,
     ];
     // A menu change moves no file of its own (the gate template already diffs
     // adrForLargeDiffs), but it is exactly what `redline init --blocking` on a
@@ -393,7 +585,11 @@ export async function init(platform, opts) {
     // a selection this run was explicitly told to drop.
     const vendorsChanged = existing !== null &&
         (existing.vendors.length !== vendors.length ||
-            [...existing.vendors].sort().join('') !== [...vendors].sort().join(''));
+            // `\0` as the escape, never a literal NUL byte. The byte itself made this
+            // file read as binary to grep and ripgrep, which then skipped it silently:
+            // a repository-wide search for any symbol in the largest command module
+            // returned nothing and reported no error.
+            [...existing.vendors].sort().join('\0') !== [...vendors].sort().join('\0'));
     // Same shape again: deselecting a capability moves no file of its own, and
     // swallowing it as "nothing to change" would leave .redline.json recording a
     // capability the operator just switched off — with Redline still maintaining it.
@@ -481,11 +677,11 @@ export async function init(platform, opts) {
             hostPlan,
         };
     }
-    const files = [...changedFiles, CONFIG_FILE];
+    const plannedFiles = [...changedFiles, CONFIG_FILE];
     if (dryRun) {
         return {
             profile,
-            files,
+            files: plannedFiles,
             removals,
             // installGate's plan reports no outcome (it made no host call);
             // ensureReviewOwnership's are decided locally and worth printing.
@@ -503,13 +699,78 @@ export async function init(platform, opts) {
             hostPlan,
         };
     }
+    step('installing the merge gate');
     const gate = capabilities.gate
         ? await platform.installGate(ref, cwd, gateOptions)
         : { files: [], outcomes: [] };
+    // Files written, nothing else attempted. Everything below this point either
+    // changes a setting on the host or puts a commit in the repository's history,
+    // and `--no-commit` exists precisely to reach neither.
+    //
+    // The config is written here rather than at the shared site below so this
+    // path records what it actually did: a repository whose settings were never
+    // applied must not carry a pendingAdmin list computed from outcomes that
+    // never happened, and must not read back as fully onboarded on the next run.
+    if (opts.noCommit === true) {
+        if (capabilities.gate && gateSource === 'org') {
+            notes.push(`the caller workflow references ${ref.org}/.github and nothing checked that it publishes ` +
+                'the gate, because --no-commit contacts no host. Run redline verify after you commit, ' +
+                'or re-run without --no-commit, before relying on the check');
+        }
+        const written = [
+            ...rendered.written,
+            ...removals,
+            ...commands.written,
+            ...gate.files,
+            ...setupResult.written,
+            CONFIG_FILE,
+        ];
+        step('recording .redline.json');
+        writeConfig(cwd, {
+            standardsVersion: manifest.version,
+            cliVersion: CLI_VERSION,
+            host: platform.host,
+            profile,
+            vendors,
+            menu,
+            capabilities,
+            integrations,
+            // Nothing was applied, so nothing is owed to an administrator yet. The
+            // run that does apply them computes this from real outcomes.
+            pendingAdmin: existing?.pendingAdmin ?? [],
+            onboardedAt: existing?.onboardedAt ?? now().toISOString(),
+            lastRunAt: now().toISOString(),
+            localRules: existsSync(join(cwd, LOCAL_RULES_FILE)),
+            commandFiles: commands.contentIds,
+            rung,
+            gateSource,
+            gateVersion: gateSource === 'local' && CLI_VERSION !== UNPUBLISHED_VERSION ? CLI_VERSION : '',
+        });
+        return {
+            profile,
+            files: written,
+            removals,
+            outcomes: [],
+            pendingAdmin: existing?.pendingAdmin ?? [],
+            pullRequest: null,
+            pullRequestError: null,
+            migratedFrom,
+            alreadyOnboarded: false,
+            dryRun: false,
+            noCommit: true,
+            menu,
+            capabilities,
+            optedOut,
+            notes,
+            hostPlan,
+        };
+    }
     const ownership = menu.sensitivePathReviewers
         ? await platform.ensureReviewOwnership(ref, cwd, ownershipRules)
         : { files: [], outcomes: [] };
+    step('applying the security floor');
     const security = await platform.enableSecurityFloor(ref);
+    step('applying the branch policy');
     const policy = capabilities.mergePolicy
         ? await platform.applyPolicy(ref, {
             requiredApprovals: 1,
@@ -522,13 +783,28 @@ export async function init(platform, opts) {
             // MergePolicy — what verify reports back off the host.
             requiredChecks: [],
             blocking: menu.blockingGate,
+            ...(opts.branches && opts.branches.length > 0 ? { branches: opts.branches } : {}),
         })
         : { outcomes: [], policy: null };
+    // The check pass cannot perform host preflight reads, so an adapter may
+    // suppress a planned file during the real install. Stage only what the
+    // installers actually wrote; otherwise git add receives a path that does
+    // not exist.
+    const files = [
+        ...rendered.written,
+        ...removals,
+        ...commands.written,
+        ...gate.files,
+        ...ownership.files,
+        ...setupResult.written,
+        CONFIG_FILE,
+    ];
     // denied -> pendingAdmin work for an administrator; unsupported -> the
     // capability doesn't exist on this repository (e.g. Advanced Security is
     // unlicensed) and must never be reported as permanently half-onboarded.
     const outcomes = [...gate.outcomes, ...ownership.outcomes, ...security.outcomes, ...policy.outcomes];
     const pendingAdmin = outcomes.filter(isPending).map((o) => o.capability);
+    step('recording .redline.json');
     writeConfig(cwd, {
         standardsVersion: manifest.version,
         cliVersion: CLI_VERSION,
@@ -537,6 +813,7 @@ export async function init(platform, opts) {
         vendors,
         menu,
         capabilities,
+        integrations,
         pendingAdmin,
         // When the repository joined, not when it was last touched: overwriting
         // this on every run erased the only record of when the standard landed.
@@ -549,14 +826,21 @@ export async function init(platform, opts) {
         // a re-run for an unrelated reason silently promoting a repository is how a
         // ladder loses the trust it exists to build.
         rung,
+        gateSource,
+        // Only a vendored gate has a version to record, and only a published CLI
+        // stamps one: a development build leaves the reusable copy's own pin alone
+        // rather than writing a version npm has never heard of, so there is nothing
+        // for verify to compare and the field stays empty.
+        gateVersion: gateSource === 'local' && CLI_VERSION !== UNPUBLISHED_VERSION ? CLI_VERSION : '',
     });
+    step('committing and opening the pull request');
     let pullRequest = null;
     let pullRequestError = null;
     try {
         pullRequest = await platform.openPullRequest(ref, cwd, {
             branch: ONBOARD_BRANCH,
             title: `chore(redline): onboard to standards v${manifest.version}`,
-            body: onboardBody(profile, manifest.version, pendingAdmin),
+            body: onboardBody(profile, manifest.version, pendingAdmin, files, hostPlan, menu, notes),
             labels: capabilities.labels ? [SYNC_LABEL] : [],
             files,
         });
@@ -594,22 +878,57 @@ export async function init(platform, opts) {
         hostPlan,
     };
 }
-function onboardBody(profile, version, pendingAdmin) {
+// The pull request a team sees first, and usually the only thing they read
+// before deciding whether this tool is worth having. It used to open with
+// "Onboards this repository to Redline standards v0.0.3" — a sentence that
+// means nothing to a reviewer who has not heard of Redline, followed by three
+// paragraphs of Redline's own vocabulary and no statement of what changed in
+// THEIR repository or what happens next. So: what it does, what it changed
+// here, what the reviewer will notice, and how to switch any of it off.
+function onboardBody(profile, version, pendingAdmin, files, hostPlan, menu, notes) {
+    const bullets = (items) => items.map((item) => `- \`${item}\``);
+    const gate = menu.blockingGate
+        ? 'The gate **blocks** a merge that fails it.'
+        : 'The gate is **advisory**: it reports and does not block. Making it blocking is a separate, ' +
+            'deliberate step once you have watched it for a while.';
     const pending = pendingAdmin.length === 0
-        ? 'Everything that needed repository settings was applied.'
-        : `A repository administrator still needs to enable: ${pendingAdmin.join(', ')}. ` +
-            `Until then this repository shows as partially onboarded.`;
+        ? []
+        : [
+            '',
+            '## Needs an administrator',
+            '',
+            `These could not be applied with the permissions this run had: ${pendingAdmin.join(', ')}.`,
+            'Everything else is in place; re-run `redline init --repair` once they are granted.',
+        ];
     return [
-        `Onboards this repository to Redline standards \`v${version}\` (profile: \`${profile}\`).`,
+        'This adds an automated review standard to the repository: one versioned set of rules, rendered',
+        'into the files your coding assistants already read, plus a pull request check that applies them',
+        'to the diff.',
+        '',
+        `Detected stack: \`${profile}\`. Rules version: \`v${version}\`.`,
+        '',
+        '## What changed here',
+        '',
+        ...(files.length === 0 ? ['No files changed.'] : bullets(files)),
+        ...(hostPlan.length === 0 ? [] : ['', 'Repository settings:', '', ...hostPlan.map((h) => `- ${h}`)]),
+        '',
+        '## What you will notice',
+        '',
+        `- ${gate}`,
+        '- Your next pull request runs the Redline check and comments findings on the diff.',
+        '- Nothing outside the `<!-- REDLINE:BEGIN -->` markers was touched. Files you already had —',
+        '  a pull request template, a CODEOWNERS — were left exactly as they are.',
         '',
-        'The merge gate runs **advisory** — it reports, it does not block. Promotion to blocking is a',
-        'deliberate second step after a soak period.',
+        '## Turning it down',
         '',
-        'Generated content sits inside `<!-- REDLINE:BEGIN -->` markers; anything outside them is yours',
-        'and was preserved. If a rule is wrong for this repository, raise it in the Redline source repo',
-        'rather than editing it here, so every repository benefits.',
+        '- A capability you already have your own version of: `redline init --skip <name>`.',
+        '- A rule that is wrong for this repository: raise it in the Redline repository rather than',
+        '  editing the generated block here, so every repository gets the fix.',
+        '- All of it: `redline remove` takes back only what Redline can prove it wrote, as a pull request.',
         '',
-        pending,
+        '`.redline.json` records every choice above and explains each one in its own `//` key.',
+        ...(notes.length === 0 ? [] : ['', '## Worth knowing', '', ...notes.map((n) => `- ${n}`)]),
+        ...pending,
     ].join('\n');
 }
 //# sourceMappingURL=init.js.map