autonomous-sdlc-harness 0.1.0 → 0.4.0

package/dist/commands/init.js

@@ -7,7 +7,7 @@
  * reproducible: a second `init` over the same repository produces the same result, and an adopter can
  * re-derive the recorded preset from the detection table by hand. It is also why judgement-dependent
  * work — reading real code to refine a layer profile, filling a conventions stub — belongs to
- * `/harness-analyze` and is deliberately absent from this file. The offer to run it
+ * `/autonomous-sdlc-harness:harness-analyze` and is deliberately absent from this file. The offer to run it
  * ({@link resolveAnalyzeOffer}) adds no model call and no external process here: the answer's whole
  * material effect is which banner wording the generated always-loaded file carries and which closing
  * pointer this run prints.
@@ -91,7 +91,7 @@ import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs';
 import { join, relative, resolve } from 'node:path';
 import { formatProblem } from '../config/check.js';
 import { configExists, loadConfig } from '../config/io.js';
-import { answersNone, asQaDriver, browserWiringApplies, CONFIG_FILENAME, DEFAULTS, isPlaceholder, qaDriverChoices, STATE_DIR_DOT_PATTERN, } from '../config/model.js';
+import { answersNone, asQaDriver, browserWiringApplies, CONFIG_FILENAME, DEFAULTS, isPlaceholder, qaDriverChoices, retrievalApplies, STATE_DIR_DOT_PATTERN, } from '../config/model.js';
 import { EXIT, HarnessError } from '../core/errors.js';
 import { commitAll, hasCommits, initRepository, probeRepoRoot } from '../core/git.js';
 import { readJsonFile } from '../core/json.js';
@@ -99,7 +99,8 @@ import { layerCoverage } from '../core/layerCoverage.js';
 import { layerGapRemedy, recordedVerdictClause } from '../core/layerGapRemedy.js';
 import { nameList } from '../core/nameList.js';
 import { insideRepo, packageRoot } from '../core/paths.js';
-import { askLine, askYesNo, canPrompt } from '../core/prompt.js';
+import { ANALYZE_COMMAND } from '../core/pluginIdentity.js';
+import { askLine, askYesNo, canPrompt, REPROMPT_LIMIT } from '../core/prompt.js';
 import { normalizeRepoDir, normalizeRepoPathStrict } from '../core/repoPaths.js';
 import { WritePlan } from '../core/writer.js';
 import { findNestedApplicationDir } from '../detect/nestedApplication.js';
@@ -107,38 +108,21 @@ import { buildPreset, commandSourceClaim, searchedRoots, SHARED_CONVENTIONS_PATH
 import { detectPreset, parsePresetName, FLAT_FALLBACK_SIGNAL_ID, FORCED_SIGNAL_ID, } from '../detect/signals.js';
 import { writeClaudeContext, CLAUDE_MD_PATH, RESERVED_ANALYZE_TARGETS, SETUP_PENDING_OPEN, isUntouchedSkeletonText, } from '../generators/claudeContext.js';
 import { pointHooksPath, writeGitHooks } from '../generators/githooks.js';
+import { writeGithubWorkflows } from '../generators/githubWorkflows.js';
 import { writeHarnessConfig } from '../generators/harnessConfig.js';
-import { writeNotifications, GUIDED_ENDPOINT_EXAMPLE } from '../generators/notifications.js';
+import { writeNotifications, PUSH_DESTINATION_FORMS, PUSH_DESTINATION_PLACEHOLDER, resolvePushDestination, UNRECOGNISED_DESTINATION_NOTE, } from '../generators/notifications.js';
 import { writeOuterLoopScripts } from '../generators/outerLoopScripts.js';
-import { writePermissionProfile } from '../generators/permissionProfile.js';
-import { writeProjectSettings, MARKETPLACE_FLAG, MARKETPLACE_NAME, MARKETPLACES_KEY, PLUGIN_NAME, SETTINGS_PATH, SLUG_SHAPE, } from '../generators/projectSettings.js';
+import { PLUGIN_ROOT_ENTRIES_FLAG, pluginRootEntriesNote, writePermissionProfile, } from '../generators/permissionProfile.js';
+import { writeProjectSettings, MARKETPLACE_FLAG, MARKETPLACE_NAME, MARKETPLACES_KEY, SETTINGS_PATH, SLUG_SHAPE, } from '../generators/projectSettings.js';
 import { writeRepoRootFiles, MCP_PATH } from '../generators/repoRoot.js';
 import { configKeyPath, configuredCommand, wrapperCommandLine, wrapperPath, writeWrapperScripts, WRAPPER_SCRIPTS, } from '../generators/scripts.js';
 import { writeStateDir } from '../generators/stateDir.js';
+import { API_KEY_SECRET, GIT_TOKEN_SECRET, OAUTH_TOKEN_SECRET, PUSH_URL_SECRET, RUNNER_VARIABLE, } from '../remote/githubActions.js';
+import { setUpRetrieval } from '../retrieval/setup.js';
 /** The command's one-line summary, in the usage block and at the head of its own `--help`. */
 const SUMMARY = 'Wire a repository: config, scripts, state tree, permission profile, project settings, conventions stubs';
 /** The roadmap item this command belongs to, as the registry reports it. */
 const ROADMAP_ITEM = 13;
-/** The analyze command's own name, without the leading `/` and without the plugin prefix. */
-const ANALYZE_COMMAND_NAME = 'harness-analyze';
-/** The analyze command as a line addressing the adopter names it — step C of the install story. */
-const ANALYZE_COMMAND = `/${ANALYZE_COMMAND_NAME}`;
-/**
- * The same command, spelled as something **executed** rather than read.
- *
- * A session's `/` picker lists every command of this plugin under the plugin's own prefix and
- * fuzzy-matches a bare name onto it, so {@link ANALYZE_COMMAND} reaches the command wherever a
- * person types it into a session. A command passed as a session's **first message** — which is
- * what {@link ANALYZE_INVOCATION} does — meets no picker and is matched exactly, so the bare
- * form fails there with `Unknown command`. That the **prefixed** form succeeds where the bare
- * one fails is not established: the only measurement in this tree is headless and negative on
- * both spellings (root `README.md`, `### Measured while building that evidence, and not fixed
- * here`), and the interactive first-message form waits on the hand-run gate — if that comes back
- * negative the printed line is dropped rather than respelled (`docs/analyze.md` §9). The prefix
- * is taken from {@link PLUGIN_NAME}, which mirrors the plugin manifest, rather than written out
- * here.
- */
-const ANALYZE_COMMAND_QUALIFIED = `/${PLUGIN_NAME}:${ANALYZE_COMMAND_NAME}`;
 /**
  * How this CLI is typed, for every line that tells an adopter to run something — stated here once
  * for the whole command surface.
@@ -181,6 +165,8 @@ const DAEMON_INSTALL_COMMAND = `${CLI} daemon install`;
  * `browserWiringApplies` holds (`doctor/checks.ts`'s browser-wiring check, `commands/doctor.ts`).
  */
 const DOCTOR_CHECK_REGISTRY_COMMAND = `${DOCTOR_COMMAND} --check-registry`;
+/** The online check of GitHub-side setup, named last in the remote-execution block ({@link reportGithubSteps}). */
+const DOCTOR_CHECK_GITHUB_COMMAND = `${DOCTOR_COMMAND} --check-github`;
 /**
  * How `.mcp.json` launches those servers, as the sentence names it.
  *
@@ -199,7 +185,27 @@ const MCP_LAUNCHER = 'npx -y';
  */
 const AGENT_CLI = 'claude';
 const MARKETPLACE_ADD_COMMAND = `${AGENT_CLI} plugin marketplace add ${SLUG_SHAPE}`;
-const ANALYZE_INVOCATION = `${AGENT_CLI} "${ANALYZE_COMMAND_QUALIFIED}"`;
+/**
+ * Step C of the install story as a first message: {@link ANALYZE_COMMAND} is the one spelling both
+ * for the name a person types into an open session and for this. The interactive first-message form
+ * waits on the hand-run gate — if that comes back negative the printed line is dropped rather than
+ * respelled (`docs/analyze.md` §9).
+ *
+ * Headless first-message leg, re-measured: Claude Code 2.1.274, from this checkout with the plugin
+ * enabled; the `system`/`init` event of both runs listed `autonomous-sdlc-harness:harness-analyze`
+ * among its slash commands and did not list `harness-analyze`.
+ * - `claude -p "/autonomous-sdlc-harness:harness-analyze" --permission-mode plan --max-turns 2 --output-format stream-json --verbose`:
+ *   exit 1; no `Skill` call, the first tool call was the command's own `Bash` read of the
+ *   unfilled-stub markers; final `result` event `is_error: true`, `result: null`, verbatim message
+ *   `Reached maximum number of turns (2)`.
+ * - `claude -p "/harness-analyze" --permission-mode plan --max-turns 2 --output-format stream-json --verbose`:
+ *   exit 1; the first tool call was `Skill` naming `autonomous-sdlc-harness:harness-analyze`, which
+ *   loaded the command; final `result` event `is_error: true`, `result: null`, verbatim message
+ *   `Reached maximum number of turns (2)`.
+ * Both exits are the two-turn cap, not a resolution failure: the prefixed spelling ran the command
+ * directly, and the bare one reached it only through the model choosing the `Skill` tool.
+ */
+const ANALYZE_INVOCATION = `${AGENT_CLI} "${ANALYZE_COMMAND}"`;
 /** The verb that applies a layer-profile revision — the one writer of `layers[]` (`docs/analyze.md` §3). */
 const CONFIG_SET_LAYERS_COMMAND = `${CLI} config set layers`;
 /** The one-key form of the same verb, named in step 3 for the two run settings (`commands/config.ts`). */
@@ -214,6 +220,22 @@ const CONFIG_SET_COMMAND = `${CLI} config set <key> <value>`;
  */
 const MARKETPLACE_MANIFEST = join('.claude-plugin', 'marketplace.json');
 const CLI_MANIFEST = join('cli', 'package.json');
+/**
+ * The environment variable that lets a run wire the harness's own repository on purpose.
+ *
+ * **Self-adoption** — running the harness's own flows against the harness while developing it — is a
+ * contributor workflow, so the escape is an environment variable rather than a flag. A flag would
+ * appear in `--help` and owe a row in `docs/cli.md`'s table, where the only reader it could reach is
+ * an adopter, for whom it can never mean anything but a mistake. It is documented in
+ * `docs/development.md` instead, beside the gates that are the rest of that audience's contract.
+ *
+ * **A variable rather than a one-off source edit**, which is the other way to get one run through,
+ * because `init` is not one-shot: `--force` regenerates a generated file when `cli/templates/`
+ * changes and `--reset-config` rebuilds the configuration, so the run this exists for recurs every
+ * time a template moves. An edit-build-revert-build cycle per template change is a standing invitation
+ * to ship the CLI with its guard removed, and the test that would catch it only runs if it is run.
+ */
+const SELF_ADOPT_ENV = 'HARNESS_SELF_ADOPT';
 /** The flag whose value the dot-directory refusal is raised against. */
 const STATE_DIR_FLAG = '--state-dir';
 /** The flag that answers the git gate — named in the prompt, in the refusal, and in the note. */
@@ -225,6 +247,18 @@ const GIT_INIT_FLAG = '--git-init';
 const APP_DIR_FLAG = '--app-dir';
 /** The flag that answers the QA-driver question — named in the prompt, the refusal and the note. */
 const QA_DRIVER_FLAG = '--qa-driver';
+/** The flag that answers the docs-retrieval question, read by its option row, its refusal and its prompt. */
+const DOCS_RETRIEVAL_FLAG = '--docs-retrieval';
+/**
+ * The second accepted spelling of that flag, in the word an adopter arrives with. It sets the same
+ * key; {@link DOCS_RETRIEVAL_FLAG} stays the canonical one the prompt and the documentation name.
+ *
+ * A constant rather than a literal for the reason every flag above is one: the `--help` row, the
+ * parser's lookup and the messages that name it to a reader are one spelling read from one owner,
+ * and it reaches all three through {@link InitOption.aliases} rather than through a second accepted-
+ * token list beside {@link INIT_OPTIONS}.
+ */
+const DOCS_RETRIEVAL_ALIAS_FLAG = '--rag';
 /**
  * The two spellings that answer the analyze offer — one accept, one decline, and neither given is
  * the state {@link resolveAnalyzeOffer} answers with the documented default.
@@ -266,8 +300,9 @@ function initOptions(rows, ..._rowsMissingFor) {
  * then the two that decide what is detected, then the values written into the config, then the three
  * phase toggles with their own inputs beside them, then the onboarding slug, then the pair that
  * answers the offer to analyze this repository — which decides the wording the generated
- * always-loaded file carries — and last the pair that decides whether this account gets told when an
- * unattended run finishes, which is the one pair that writes nothing into the repository at all.
+ * always-loaded file carries — then the pair that decides whether this account gets told when an
+ * unattended run finishes, which is the one pair that writes nothing into the repository at all, and
+ * last the switch that adds this machine's plugin-root entries to a freshly generated profile.
  *
  * The first two sit together, and ahead of everything else, because they are the rows whose subject
  * is the **shape of the run** rather than a value in the generated file: one settles what `init` is
@@ -361,6 +396,14 @@ const INIT_OPTIONS = initOptions([
         summary: 'Documentation root the docs phase keeps current (with --docs)',
         configValue: 'docs.root',
     },
+    {
+        key: 'docsRetrieval',
+        flag: DOCS_RETRIEVAL_FLAG,
+        aliases: [DOCS_RETRIEVAL_ALIAS_FLAG],
+        kind: 'switch',
+        summary: 'Turn RAG (docs retrieval) on: a local search tool over the docs and conventions (with --docs)',
+        configValue: 'docs.retrieval',
+    },
     {
         key: 'parity',
         flag: '--parity',
@@ -414,10 +457,24 @@ const INIT_OPTIONS = initOptions([
         key: 'pushUrl',
         flag: PUSH_URL_FLAG,
         kind: 'value',
-        placeholder: '<url>',
-        summary: 'Endpoint unattended-run notifications are posted to (with --notifications)',
+        placeholder: PUSH_DESTINATION_PLACEHOLDER,
+        summary: 'Where notifications are posted: an ntfy topic name, or the full http:// or https:// URL of any endpoint that accepts a POST (with --notifications)',
+    },
+    {
+        key: 'pluginRootEntries',
+        flag: PLUGIN_ROOT_ENTRIES_FLAG,
+        kind: 'switch',
+        summary: "Include this machine's plugin-root permission entries when the profile is generated (for a remote job)",
     },
 ]);
+/**
+ * Every token a row accepts, canonical first: its flag and any {@link InitOption.aliases}. The one
+ * reader of that field, so the parser, the `--help` block and the discarded-flag warning cannot
+ * disagree about which spellings exist.
+ */
+function optionSpellings(option) {
+    return [option.flag, ...(option.aliases ?? [])];
+}
 /**
  * A flag value as a reader can retype it: quoted only where a shell would otherwise split or expand
  * it, so the remedy below stays copy-pasteable for an ordinary branch name and stays correct for a
@@ -457,16 +514,19 @@ function discardedConfigFlagsWarning(flags) {
         if (configKey === undefined)
             continue;
         const steersDetection = option.steersDetection === true;
+        // The naming carries every accepted spelling, so a reader who typed an alias recognises the line
+        // as theirs; the re-invocation stays on the canonical one, because that half is pasted back.
+        const named = option.aliases === undefined ? option.flag : `${option.flag} (or ${option.aliases.join(', ')})`;
         if (option.kind === 'switch') {
             if (flags[option.key] === true) {
-                dropped.push({ flag: option.flag, configKey, invocation: option.flag, steersDetection });
+                dropped.push({ flag: named, configKey, invocation: option.flag, steersDetection });
             }
             continue;
         }
         const value = flags[option.key];
         if (value === undefined)
             continue;
-        dropped.push({ flag: option.flag, configKey, invocation: `${option.flag} ${retypable(value)}`, steersDetection });
+        dropped.push({ flag: named, configKey, invocation: `${option.flag} ${retypable(value)}`, steersDetection });
     }
     if (dropped.length === 0)
         return undefined;
@@ -478,9 +538,12 @@ function discardedConfigFlagsWarning(flags) {
         : ` ${steering.join(', ')} also steer${steering.length === 1 ? 's' : ''} stack detection, and still did on this run: what \`--force\` then re-renders from that detection is the wrapper scripts, not this file.`;
     return `${dropped.map((entry) => entry.flag).join(', ')} ${one ? 'was' : 'were'} given, and ${CONFIG_FILENAME} was read rather than written on this run: ${one ? 'that flag supplies a value' : 'each of those flags supplies a value'} for a key of that file, so no such value was written and the keys in the file are the ones every generator after it read.${steeringClause} Apply ${one ? 'it' : 'them'} by rebuilding the file from detection and this command line with \`${INIT_VERB} --reset-config ${dropped.map((entry) => entry.invocation).join(' ')}\`, which copies the file that is there to a .bak first and is the only route that also re-derives what a value implies — or change ${one ? 'the key' : 'the keys'} alone with ${keyRemedies}`;
 }
-/** The command's own `Options:` rows, invocation-aligned, derived from {@link INIT_OPTIONS}. */
+/**
+ * The command's own `Options:` rows, invocation-aligned, derived from {@link INIT_OPTIONS}. A row
+ * with aliases prints every spelling it accepts, so no accepted token is absent from `--help`.
+ */
 function initOptionLines() {
-    const invocations = INIT_OPTIONS.map((option) => `${option.flag}${option.kind === 'switch' ? '' : ` ${option.placeholder}`}`);
+    const invocations = INIT_OPTIONS.map((option) => `${optionSpellings(option).join(', ')}${option.kind === 'switch' ? '' : ` ${option.placeholder}`}`);
     const width = Math.max(...invocations.map((invocation) => invocation.length));
     return INIT_OPTIONS.map((option, index) => `  ${invocations[index].padEnd(width)}  ${option.summary}`);
 }
@@ -523,13 +586,15 @@ function parseQaDriver(value) {
 }
 function parseInitFlags(argv) {
     const values = new Map();
-    const switches = new Set();
+    // The spelling each switch was typed as, not merely that it was given: a row accepting an alias
+    // ({@link InitOption.aliases}) must be named back to the reader in the words they used.
+    const switches = new Map();
     for (let index = 0; index < argv.length; index += 1) {
         const token = argv[index];
         const separator = token.startsWith('--') ? token.indexOf('=') : -1;
         const name = separator > 0 ? token.slice(0, separator) : token;
         const inlineValue = separator > 0 ? token.slice(separator + 1) : undefined;
-        const option = INIT_OPTIONS.find((candidate) => candidate.flag === name);
+        const option = INIT_OPTIONS.find((candidate) => optionSpellings(candidate).includes(name));
         if (option === undefined) {
             throw new HarnessError(token.startsWith('-')
                 ? `init: unknown option ${JSON.stringify(name)} — run \`${INIT_VERB} --help\` for the options it takes`
@@ -538,7 +603,7 @@ function parseInitFlags(argv) {
         if (option.kind === 'switch') {
             if (inlineValue !== undefined)
                 throw new HarnessError(`init: ${name} does not take a value`);
-            switches.add(option.key);
+            switches.set(option.key, name);
             continue;
         }
         let value = inlineValue;
@@ -568,6 +633,22 @@ function parseInitFlags(argv) {
     if (switches.has('analyze') && switches.has('noAnalyze')) {
         throw new HarnessError(`init: ${ANALYZE_FLAG} and ${NO_ANALYZE_FLAG} answer the same question opposite ways and both were given: pass one, or neither — with neither, the documented default accepts the offer`);
     }
+    // Refused rather than warned, unlike `--qa-driver` without `--qa`: `docs.retrieval: true` without
+    // `phases.docs` is a config-check error, so the generated config would fail the write guard.
+    if (switches.has('docsRetrieval') && !switches.has('docs')) {
+        // Named as it was typed: a run refused for passing the alias is not told about a flag it never
+        // used. The fallback is unreachable while the key is set only from a token, and is here so the
+        // message has a spelling rather than `undefined` if that ever stops holding.
+        const typed = switches.get('docsRetrieval') ?? DOCS_RETRIEVAL_FLAG;
+        throw new HarnessError(`init: ${typed} needs --docs: retrieval searches the documentation corpus the docs phase maintains, so it is legal only with that phase on`);
+    }
+    // Checked here for the reason `qaDriver` is, whether or not --notifications was given: a bad value
+    // must not cost an adopter a repository this run created. The value is withheld from the message,
+    // unlike {@link parseQaDriver}'s, because a push destination is a credential and stderr is logged.
+    const pushUrl = values.get('pushUrl');
+    if (pushUrl !== undefined && resolvePushDestination(pushUrl).kind === 'unrecognised') {
+        throw new HarnessError(`init: ${PUSH_URL_FLAG} takes ${PUSH_DESTINATION_FORMS}; the value given is neither, so nothing was written. It is not repeated here, because a push destination is a credential — check it and pass it again`);
+    }
     return {
         ...Object.fromEntries([...values]),
         ...(qaDriver === undefined ? {} : { qaDriver: parseQaDriver(qaDriver) }),
@@ -578,7 +659,9 @@ function parseInitFlags(argv) {
         notifications: switches.has('notifications'),
         qa: switches.has('qa'),
         docs: switches.has('docs'),
+        docsRetrieval: switches.has('docsRetrieval'),
         parity: switches.has('parity'),
+        pluginRootEntries: switches.has('pluginRootEntries'),
     };
 }
 /** The `name` of a JSON manifest, or `undefined` when there is no readable one with a name. */
@@ -614,13 +697,22 @@ function ownPackageName() {
  * `docs/development.md` §5's gate 2 documents running the built CLI from this root, which was a
  * refusal check for as long as `init` refused everything. Once it works, that invocation would
  * generate a config, a state tree and a permission profile into the harness's own tree.
+ *
+ * It is a refusal and not a prohibition: {@link SELF_ADOPT_ENV} set to `1` is how a contributor asks
+ * for that wiring deliberately, and nothing else reaches it.
  */
 function assertNotHarnessOwnRepository(repoRoot) {
     if (!existsSync(join(repoRoot, MARKETPLACE_MANIFEST)))
         return;
     if (packageNameAt(join(repoRoot, CLI_MANIFEST)) !== ownPackageName())
         return;
-    throw new HarnessError(`refusing to wire the harness's own repository; run \`${INIT_VERB}\` in the repository you want to adopt it. ${repoRoot} carries ${MARKETPLACE_MANIFEST} and a ${CLI_MANIFEST} naming this package, so it is the harness itself rather than an adopting project: wiring it would generate a ${CONFIG_FILENAME}, a run-artifact tree and a permission profile into the tree that ships them. Run ${INIT_VERB} from the adopting repository, or point it at one with --cwd <path>`);
+    // Checked **after** both identity tests rather than before them, which is what keeps the variable
+    // inert everywhere it is not wanted: every root that is not this one has already returned above,
+    // so a value left in a shell's environment changes the behaviour of no adopter's run. Only the
+    // exact `1` opens it — a variable that is merely *set* is too easy to inherit by accident.
+    if (process.env[SELF_ADOPT_ENV] === '1')
+        return;
+    throw new HarnessError(`refusing to wire the harness's own repository; run \`${INIT_VERB}\` in the repository you want to adopt it. ${repoRoot} carries ${MARKETPLACE_MANIFEST} and a ${CLI_MANIFEST} naming this package, so it is the harness itself rather than an adopting project: wiring it would generate a ${CONFIG_FILENAME}, a run-artifact tree and a permission profile into the tree that ships them. Run ${INIT_VERB} from the adopting repository, or point it at one with --cwd <path>. To wire this repository on purpose — the harness's own self-adoption, a contributor workflow \`docs/development.md\` documents — set ${SELF_ADOPT_ENV}=1`);
 }
 /**
  * Refuse a `--state-dir` that names, or reaches through, a dot-directory — **before** anything is
@@ -874,6 +966,21 @@ function askQaDriver(ctx) {
         defaultValue: DEFAULTS.qa.driver,
     }, promptCtx);
 }
+/**
+ * Ask whether to turn docs retrieval on — or answer `undefined` on every run that cannot be asked, for
+ * {@link askQaDriver}'s reason: the generator notes an unasked run, and must not note a declined one.
+ */
+function askRetrieval(ctx) {
+    const promptCtx = { flags: ctx.flags, report: ctx.report };
+    if (!canPrompt(promptCtx))
+        return undefined;
+    return askYesNo({
+        question: 'Turn on RAG (docs retrieval)? It adds a local search tool over the docs and conventions for the plan writer and reviewers. Setup installs about 300 MB of local runtime and downloads two small models into a cache shared by every checkout on this machine. Off by default.',
+        defaultAnswer: false,
+        flag: DOCS_RETRIEVAL_FLAG,
+        flagHint: 'to turn it on without being asked',
+    }, promptCtx);
+}
 /**
  * The conventions documents this repository has: every distinct `layers[].conventions` value, plus
  * the shared cross-layer document whether or not a layer points at it.
@@ -1026,14 +1133,15 @@ function resolveAnalyzeOffer(ctx, flags, repoRoot, config) {
  *
  * The two questions are asked in order and the second only inside the first's yes, because an
  * endpoint is meaningless without the opt-in and the opt-in writes nothing without an endpoint. The
- * endpoint question carries no default: `askLine` answers `undefined` with none, and `undefined` is
- * what routes the run to the generator's guided-setup note rather than to a file — writing an empty
- * machine-local file would shadow a repository-side one that already has values
- * (`generators/notifications.ts`, choice 1).
+ * endpoint question carries no default, and {@link askPushDestination} ends in one of three outcomes:
+ * `undefined`, which routes the run to the generator's guided-setup note rather than to a file —
+ * writing an empty machine-local file would shadow a repository-side one that already has values
+ * (`generators/notifications.ts`, choice 1); a recognised destination, passed on as typed; or, after
+ * the re-asks run out, the last unrecognised answer, on which the generator writes nothing and warns.
  *
  * A `--push-url` passed **without** the opt-in is left in place rather than dropped here: the
  * generator owns what that means and warns about it, as it owns every other line about the artifact
- * it writes.
+ * it writes. The flag always wins over asking.
  */
 function resolveNotifications(ctx, flags) {
     const promptCtx = { flags: ctx.flags, report: ctx.report };
@@ -1044,15 +1152,27 @@ function resolveNotifications(ctx, flags) {
             flag: NOTIFICATIONS_FLAG,
             flagHint: 'to set them up without being asked',
         }, promptCtx);
-    const pushUrl = flags.pushUrl ??
-        (enabled
-            ? askLine({
-                question: `Where should notifications be posted? (any endpoint that accepts a POST, e.g. ${GUIDED_ENDPOINT_EXAMPLE})`,
-                flag: PUSH_URL_FLAG,
-            }, promptCtx)
-            : undefined);
+    const pushUrl = flags.pushUrl ?? (enabled ? askPushDestination(promptCtx) : undefined);
     return pushUrl === undefined ? { enabled } : { enabled, pushUrl };
 }
+/**
+ * Ask for the push destination, re-asking an unrecognised answer up to `REPROMPT_LIMIT` times. Loops
+ * over `askLine` rather than reading the terminal, so `core/prompt.ts` stays the one way to ask.
+ * Returns `undefined` for no answer, a recognised answer as typed, or the last unrecognised one.
+ */
+function askPushDestination(promptCtx) {
+    let answer;
+    for (let attempt = 0; attempt <= REPROMPT_LIMIT; attempt += 1) {
+        answer = askLine({
+            question: `Where should notifications be posted? Type ${PUSH_DESTINATION_FORMS}.`,
+            flag: PUSH_URL_FLAG,
+        }, promptCtx);
+        if (answer === undefined || resolvePushDestination(answer).kind !== 'unrecognised')
+            return answer;
+        promptCtx.report.info(UNRECOGNISED_DESTINATION_NOTE);
+    }
+    return answer;
+}
 /** What detection concluded, as one line the summary can carry. */
 function detectionLine(detection) {
     if (detection.matchedSignal === FORCED_SIGNAL_ID) {
@@ -1568,6 +1688,8 @@ async function run(ctx) {
         // back-references it ({@link askQaDriver}) — "the detected preset" names nothing an adopter who
         // has not read that line can resolve.
         askDriver: () => askQaDriver(ctx),
+        // Lazy for the same reason: asked only while the docs phase is on and `--docs-retrieval` was absent.
+        askRetrieval: () => askRetrieval(ctx),
     });
     // `kept` is known only now, so this is where the four held-back lists are published or dropped —
     // ahead of `config.warnings`, which is the order they printed in before they were gated. A kept
@@ -1632,6 +1754,9 @@ async function run(ctx) {
     // exist (`generators/outerLoopScripts.ts`).
     const outerLoop = writeOuterLoopScripts({ repoRoot, config: effective, plan });
     notes.push(...outerLoop.notes);
+    // After the scripts, which the workflows run, and before the permission profile. Enqueues nothing
+    // unless `execution.target` is `github-actions` (`generators/githubWorkflows.ts`).
+    const workflows = writeGithubWorkflows({ repoRoot, config: effective, plan });
     const state = writeStateDir({ repoRoot, config: effective, plan });
     notes.push(...state.notes);
     // The third of the four questions this run puts, and settled here because its answer is an
@@ -1676,6 +1801,7 @@ async function run(ctx) {
         // The run's `--dry-run`, which changes that report's tense and nothing else — the same contract
         // the project-file generator above keeps.
         dryRun: ctx.flags.dryRun,
+        pluginRootEntries: flags.pluginRootEntries === true,
     });
     warnings.push(...permissions.warnings);
     notes.push(...permissions.notes);
@@ -1711,12 +1837,24 @@ async function run(ctx) {
     warnings.push(...hooks.warnings);
     notes.push(...hooks.notes);
     ctx.report.step(ctx.flags.dryRun ? 'files (dry run — nothing is written)' : 'files');
-    plan.apply({ repoRoot, report: ctx.report, dryRun: ctx.flags.dryRun, force: ctx.flags.force });
+    const applied = plan.apply({ repoRoot, report: ctx.report, dryRun: ctx.flags.dryRun, force: ctx.flags.force });
+    const profileWrite = applied.find((result) => result.path === permissions.path);
+    const pluginRootNote = profileWrite === undefined ? undefined : pluginRootEntriesNote(permissions.pluginRootEntries, profileWrite.effect);
+    if (pluginRootNote !== undefined)
+        notes.push(pluginRootNote);
     // After the plan, deliberately: this is the one git-configuration write, and pointing
     // `core.hooksPath` at a directory whose hook has not landed yet would enable nothing.
     const hooksPath = pointHooksPath({ repoRoot, githooksDir: hooks.githooksDir, dryRun: ctx.flags.dryRun });
     warnings.push(...hooksPath.warnings);
     notes.push(...hooksPath.notes);
+    // After the plan: this step writes nothing into the repository, and a real install takes minutes, so
+    // it must not delay the plan's own report. Before the commit, which a failure here must not stop.
+    if (retrievalApplies(effective)) {
+        ctx.report.step('docs retrieval setup');
+        const retrieval = setUpRetrieval({ dryRun: ctx.flags.dryRun });
+        warnings.push(...retrieval.warnings);
+        notes.push(...retrieval.notes);
+    }
     // The second post-plan step, and after the plan for a reason of its own: the managed `.gitignore`
     // block that decides what `git add -A` may stage arrived with the plan. Before the summary, so the
     // commit is reported inside the run's action log rather than after its closing pointer.
@@ -1737,8 +1875,50 @@ async function run(ctx) {
     // browser wiring at all. Taken from the one predicate the two generators that write that wiring
     // read, never re-spelled here (`config/model.ts`).
     browserWiringApplies(effective));
+    // Only the workflows this run created or replaced: a kept one is the adopter's already, and telling
+    // them to commit it again is false on every unforced re-run and in every remote job's `init`.
+    const freshWorkflows = workflows.workflows
+        .filter(({ absolute }) => {
+        const result = applied.find((r) => r.path === absolute);
+        return result !== undefined && result.effect !== 'kept';
+    })
+        .map(({ repoPath }) => repoPath);
+    if (freshWorkflows.length > 0)
+        reportGithubSteps(ctx, effective.defaultBranch, ctx.flags.dryRun, freshWorkflows);
     return EXIT.OK;
 }
+/**
+ * The GitHub-side steps only the adopter can take, printed when this run created or replaced at least
+ * one of the two workflows; `workflowPaths` names those, repo-relative.
+ *
+ * Commands stand on their own lines so each can be pasted. The push comes first because GitHub
+ * dispatches a `workflow_dispatch` workflow only once it exists on the default branch.
+ */
+function reportGithubSteps(ctx, defaultBranch, dryRun, workflowPaths) {
+    const wrote = dryRun ? 'would write' : 'wrote';
+    const command = (line) => ctx.report.info(`   ${line}`);
+    ctx.report.step('remote execution');
+    ctx.report.info(`1. This run ${wrote} ${workflowPaths.join(' and ')}. Commit and push ${workflowPaths.length === 1 ? 'it' : 'both'} to GitHub's default branch (assumed \`${defaultBranch}\` below) — a workflow_dispatch workflow can be dispatched only once it exists there:`);
+    command(`git add ${workflowPaths.join(' ')}`);
+    command('git commit -m "Add the harness workflows"');
+    command(`git push origin ${defaultBranch}`);
+    ctx.report.info('');
+    ctx.report.info(`2. Set one credential secret: ${OAUTH_TOKEN_SECRET} for subscription billing, or ${API_KEY_SECRET} for API billing. When both are set, billing follows ${API_KEY_SECRET}:`);
+    command(`gh secret set ${OAUTH_TOKEN_SECRET}`);
+    command(`gh secret set ${API_KEY_SECRET}`);
+    ctx.report.info('');
+    ctx.report.info(`3. Optionally set ${PUSH_URL_SECRET} to receive push notifications from the job, and ${GIT_TOKEN_SECRET} — a personal or App token — so the job's pushes trigger your own CI, which pushes made with the job's built-in token never do:`);
+    command(`gh secret set ${PUSH_URL_SECRET}`);
+    command(`gh secret set ${GIT_TOKEN_SECRET}`);
+    ctx.report.info('');
+    ctx.report.info(`4. Optionally set the repository variable ${RUNNER_VARIABLE} to run on a self-hosted runner label instead of ubuntu-latest:`);
+    command(`gh variable set ${RUNNER_VARIABLE} --body <runner-label>`);
+    ctx.report.info('');
+    ctx.report.info('5. Then verify the GitHub side:');
+    command(DOCTOR_CHECK_GITHUB_COMMAND);
+    ctx.report.info('');
+    ctx.report.info('Runner choices, costs, billing and security: the harness documentation, docs/remote-execution.md — Remote execution on GitHub Actions.');
+}
 /**
  * The caveats, after the action log: the informational lines first, then the ones needing attention.
  *
@@ -1898,12 +2078,9 @@ function analyzeRecordSentence(analyze, force, dryRun, backupWouldCarryContent,
  * rather than a fifth thing to do. It names {@link AGENT_CLI} directly where the generated watcher
  * reaches the same binary through `${HARNESS_AGENT_CLI:-claude}`
  * (`templates/scripts/autonomous-watcher.sh`) — an override that belongs to a script's own
- * environment and would mean nothing on a line printed for a person to paste. It names
- * {@link ANALYZE_COMMAND_QUALIFIED} where step 2 above it names {@link ANALYZE_COMMAND}, and the
- * difference is the two paths rather than an inconsistency: step 2 is a name to type into a session,
- * whose picker resolves the bare form, while this line is a first message, which is matched exactly —
- * the introducing sentence says so, because a report that showed both spellings and explained neither
- * would read as a typo. It is withheld wherever
+ * environment and would mean nothing on a line printed for a person to paste. It names the same
+ * {@link ANALYZE_COMMAND} spelling step 2 above it names, so the introducing sentence gives no
+ * spelling reason. It is withheld wherever
  * it would contradict the report around it: on the declined arm, whose answer the same step just
  * quoted; on the skip branch, where there is nothing to fill; and under `--dry-run`, which wired
  * nothing to run it against. On the unresolved-slug arm it is **printed but qualified** rather than
@@ -1911,7 +2088,7 @@ function analyzeRecordSentence(analyze, force, dryRun, backupWouldCarryContent,
  * published — because step 1 has just said the session resolves the plugin only once one of the two
  * routes it names is taken, and handing the line over without that precondition would contradict it.
  * **The outcome is stated as intended on both arms**: whether the prefixed first-message form
- * succeeds is not established ({@link ANALYZE_COMMAND_QUALIFIED}), so the line an adopter acts on
+ * succeeds is not established ({@link ANALYZE_INVOCATION}), so the line an adopter acts on
  * immediately names the typed route as the measured one instead of asserting its own.
  *
  * **One blank line between the numbered steps, and none before that paste line.** Each step is a
@@ -1974,13 +2151,12 @@ function reportNextSteps(ctx, layerNames, analyze, force, dryRun, backupWouldCar
     // The sentence introducing the line carries the precondition step 1 just stated. On the unresolved
     // arm, handing the line over without that precondition would contradict the step above it, which
     // has said the session resolves the plugin only once one of the two routes it names is taken.
-    const pasteReason = " It is spelled with the plugin prefix because a first message is matched exactly, where a session's command picker matches the name above.";
-    // Whether the prefixed first message succeeds is unmeasured, so the outcome is named as intended
-    // and the measured route is pointed at ({@link ANALYZE_COMMAND_QUALIFIED}, `docs/analyze.md` §9).
+    // The name typed into an open session is the measured route; the interactive first message is not,
+    // so the outcome is named as intended ({@link ANALYZE_INVOCATION}, `docs/analyze.md` §9).
     const pasteUnconfirmed = ' That first-message form is not confirmed on the version measured here; the name above, typed into an open session, is the route that is.';
     const pasteIntro = wiring.marketplaceSlug === undefined
-        ? ` Once the plugin resolves — step 1 names both routes — paste the line below at this repository's root: it is meant to start a session with that command already running.${pasteReason}${pasteUnconfirmed}`
-        : ` Paste the line below at this repository's root: it is meant to start a session with that command already running.${pasteReason}${pasteUnconfirmed}`;
+        ? ` Once the plugin resolves — step 1 names both routes — paste the line below at this repository's root: it is meant to start a session with that command already running.${pasteUnconfirmed}`
+        : ` Paste the line below at this repository's root: it is meant to start a session with that command already running.${pasteUnconfirmed}`;
     ctx.report.step('next');
     ctx.report.info(`1. ${wired}`);
     ctx.report.info('');