autonomous-sdlc-harness 0.1.0 → 0.4.0

package/dist/doctor/checks.js

@@ -21,7 +21,11 @@
  *    that module's {@link GITIGNORE_BLOCK_HEADER}, the line the write engine itself matches on, the
  *    push-settings precedence is `generators/notifications.ts`'s {@link pushEnvCandidates}, the
  *    repository registry's location, reader and staleness grading are `machine/registry.ts`'s {@link registryPath},
- *    {@link readRegistry} and {@link inspect} — the same three `daemon list` enumerates through — and
+ *    {@link readRegistry} and {@link inspect} — the same three `daemon list` enumerates through — the
+ *    remote-execution switch is `config/model.ts`'s {@link remoteExecutionApplies}, the workflow
+ *    paths and the binary run as `gh` are `remote/githubActions.ts`'s ({@link WORKFLOW_RUN_PATH},
+ *    {@link WORKFLOW_RESUME_PATH}, {@link GH_CLI_VARIABLE}, {@link ghCli}), whether a ref carries a
+ *    file is `core/git.ts`'s {@link pathAtRef}, and
  *    the writability probe is the write engine's {@link probeWritable}. A
  *    check that wanted a slightly different answer would be a second definition of the thing being
  *    checked, which is how a green `doctor` starts disagreeing with the run it is supposed to
@@ -54,6 +58,19 @@
  *    did not ask says so, rather than leaving an adopter to read a pass as a promise the packages can
  *    be fetched.
  *
+ *    **Remote setup keeps the same line: it is graded from local evidence by default and asks GitHub
+ *    only under `--check-github`.** {@link REMOTE_EXECUTION_CHECK} reads files, refs and `PATH`, and
+ *    spawns no `gh` subcommand; {@link REMOTE_GITHUB_CHECK} spawns them only under
+ *    {@link CheckContext.probeGithub}, and each is a read.
+ *
+ *    **The three docs-retrieval checks keep that line.** `retrieval-dependencies` and
+ *    `retrieval-model-cache` are file tests answered by `retrieval/runtime.ts`'s
+ *    {@link retrievalRuntimeState} and `retrieval/models.ts`'s {@link modelFilesPresent}, and load
+ *    nothing. `retrieval-index` spawns a child of this CLI running `docs index --in-memory`: a child
+ *    because {@link Check.run} is synchronous and the store is not, and because the child is the
+ *    installation whose optional peers resolve beside it. It builds in memory and exits, so it starts
+ *    no server and writes nothing.
+ *
  * ## What this module deliberately does not do
  *
  * - **It writes nothing** beyond {@link probeWritable}'s temp file, which that function removes with
@@ -62,18 +79,19 @@
  * - **It repairs nothing.** Every failure names what to run — `init`, `init --force`, an edit to one
  *   config key — and `doctor` stays a command that is safe to run against a repository at any time.
  */
-import { execFileSync } from 'node:child_process';
+import { execFileSync, spawnSync } from 'node:child_process';
 import { accessSync, constants as fsConstants, existsSync, readFileSync, statSync } from 'node:fs';
 import { delimiter, join, posix, resolve as resolvePath } from 'node:path';
 import { formatProblem } from '../config/check.js';
 import { loadConfig } from '../config/io.js';
-import { answersNone, browserWiringApplies, COMMAND_NONE_SENTINEL, CONFIG_FILENAME, DEFAULTS, FALLBACK_PRESET, isPlaceholder, LAYER_CATCH_ALL_PATH, STATE_DIR_DOT_PATTERN, STATE_DIR_PATTERN, } from '../config/model.js';
-import { branchResolves, checkedOutBranch, commitsAhead, configuredRemotes, hasCommits, pathIsIgnored, remoteTrackingBranchResolves, resolveRepoRoot, worktreeList, } from '../core/git.js';
+import { answersNone, browserWiringApplies, COMMAND_NONE_SENTINEL, CONFIG_FILENAME, DEFAULTS, FALLBACK_PRESET, isPlaceholder, LAYER_CATCH_ALL_PATH, remoteExecutionApplies, retrievalApplies, STATE_DIR_DOT_PATTERN, STATE_DIR_PATTERN, } from '../config/model.js';
+import { branchResolves, checkedOutBranch, commitsAhead, configuredRemotes, hasCommits, pathAtRef, pathIsIgnored, remoteTrackingBranchResolves, resolveRepoRoot, worktreeList, } from '../core/git.js';
 import { isJsonObject, readJsonFile } from '../core/json.js';
 import { layerCoverage } from '../core/layerCoverage.js';
 import { layerGapRemedy, recordedVerdictClause } from '../core/layerGapRemedy.js';
 import { nameList } from '../core/nameList.js';
 import { readTemplate, workRoot } from '../core/paths.js';
+import { ANALYZE_COMMAND } from '../core/pluginIdentity.js';
 import { normalizeRepoPathStrict } from '../core/repoPaths.js';
 import { probeWritable } from '../core/writer.js';
 import { detectBackend, resolveWatcherPath, watcherMissingMessage } from '../daemon/backend.js';
@@ -82,16 +100,19 @@ import { LAYERLESS_BY_DESIGN_PRESETS, SHARED_CONVENTIONS_PATH, TESTS_LAYER_NAME
 import { FORCED_SIGNAL_ID } from '../detect/signals.js';
 import { CLAUDE_MD_PATH, SETUP_PENDING_CLOSE, SETUP_PENDING_OPEN, SKELETON_GUIDANCE_MARKER, TASK_OFFER_PATH, UNFILLED_STUB_MARKER, } from '../generators/claudeContext.js';
 import { caseLabelMatches, isGlobPattern, PRE_PUSH_HOOK, readProtectedCaseLabel, resolveGithooksDir, resolveProtectedBranches, } from '../generators/githooks.js';
-import { PUSH_CMD_KEY, PUSH_URL_KEY, pushEnvCandidates, } from '../generators/notifications.js';
-import { outerLoopScriptsDir } from '../generators/outerLoopScripts.js';
-import { bashScriptRule, entryWord, isUnderDirectory, namesBrowserTool, normalizedRoot, pluginRootEntryTarget, PROFILE_PATH, readRule, renderProfile, TEMPLATE_PATH as PROFILE_TEMPLATE_PATH, } from '../generators/permissionProfile.js';
+import { PUSH_CMD_KEY, PUSH_DESTINATION_PLACEHOLDER, PUSH_URL_KEY, pushEnvCandidates, } from '../generators/notifications.js';
+import { DOCS_SEARCH_SERVER_SCRIPT_NAME, outerLoopScriptsDir } from '../generators/outerLoopScripts.js';
+import { bashScriptRule, entryWord, isUnderDirectory, namesBrowserTool, normalizedRoot, pluginRootEntries, pluginRootEntryTarget, pluginRootHelpers, PROFILE_PATH, readRule, renderProfile, TEMPLATE_PATH as PROFILE_TEMPLATE_PATH, } from '../generators/permissionProfile.js';
 import { ENABLED_PLUGINS_KEY, MARKETPLACE_ENTRY_SHAPE, MARKETPLACE_FLAG, MARKETPLACES_KEY, MARKETPLACE_NAME, marketplaceEntryDefect, PLUGIN_KEY, SETTINGS_PATH, SLUG_SHAPE, } from '../generators/projectSettings.js';
 import { clarificationsIgnoreRules, contentsIgnoredDirectories, GITIGNORE_BLOCK_HEADER, GITIGNORE_PATH, MCP_PATH, } from '../generators/repoRoot.js';
 import { configKeyPath, configuredWrapperFile, scriptInvocation, selectWrapper, wrappedKeyMismatch, wrappedKeyMismatchMessage, WRAPPER_SCRIPTS, wrapperCommandLine, } from '../generators/scripts.js';
 import { selectedStateDirs } from '../generators/stateDir.js';
 import { machineConfigDir } from '../machine/paths.js';
-import { installedPluginsPath, knownMarketplacesPath, pluginHelperPath, pluginHelperScripts, pluginInstallRoot, pluginRuntimeRoot, pluginScriptsDir, } from '../machine/plugins.js';
+import { installedPluginsPath, knownMarketplacesPath, pluginInstallRoot, pluginRuntimeRoot, pluginScriptsDir, } from '../machine/plugins.js';
 import { inspect, readRegistry, registryPath } from '../machine/registry.js';
+import { API_KEY_SECRET, DEFAULT_GH_CLI, GH_CLI_VARIABLE, ghCli, GIT_TOKEN_SECRET, OAUTH_TOKEN_SECRET, PUSH_URL_SECRET, REMOTE_STOP_VARIABLE, runGh, RUNNER_VARIABLE, WORKFLOW_RESUME_FILE, WORKFLOW_RESUME_PATH, WORKFLOW_RUN_FILE, WORKFLOW_RUN_PATH, } from '../remote/githubActions.js';
+import { modelFilesPresent } from '../retrieval/models.js';
+import { retrievalCliEntry, retrievalModelCacheDir, retrievalRuntimeDir, retrievalRuntimeState, } from '../retrieval/runtime.js';
 /**
  * How the CLI is typed, for every remedy that tells an operator what to run next. The `npx` prefix
  * is not decoration: the rule for which occurrences carry it is stated once in `commands/init.ts`,
@@ -112,6 +133,21 @@ const WORKTREE_SCRIPT = 'create-worktree.sh';
  * `bash <scriptsDir>/<file>` — so nothing here formats that shape a second time.
  */
 const REFRESH_SCRIPT = 'refresh-branch.sh';
+/**
+ * The outer-loop script the watcher dispatches a remote run through, named in {@link requiredBinaries}'
+ * and {@link REMOTE_EXECUTION_CHECK}'s sentences on {@link WORKTREE_SCRIPT}'s terms: a file in a
+ * sentence, never resolved or read here.
+ */
+const REMOTE_RUN_SCRIPT = 'remote-run.sh';
+/**
+ * The `gh api` path {@link REMOTE_GITHUB_CHECK} reads the repository's artifact retention from; `gh`
+ * fills `{owner}` and `{repo}` from the checkout's remote. Local, not a `remote/githubActions.ts`
+ * export: that module owns the names `cli/src` shares with the shell and YAML mirrors, and no shell or
+ * YAML file spells this endpoint.
+ */
+const ARTIFACT_RETENTION_ENDPOINT = 'repos/{owner}/{repo}/actions/permissions/artifact-and-log-retention';
+/** Below this many days of artifact retention {@link REMOTE_GITHUB_CHECK} warns; argued there. */
+const ARTIFACT_RETENTION_WARN_DAYS = 30;
 /** The permission lists a generated profile carries, in the order the template writes them. */
 const PERMISSION_LISTS = Object.freeze(['allow', 'deny', 'ask']);
 /** An unsubstituted token, which a raw template's entry may carry and a rendered profile may not. */
@@ -356,11 +392,11 @@ function serversStartedByProfile(profile) {
  * has to report on rather than crash against, and the same holds for a config or a profile that does
  * not parse. Each failure becomes a field the check that owns that subject renders.
  *
- * `probeRegistry` is the caller's answer rather than this function's, and it defaults to `false`: a
- * context built without it is the context every default run gets, and no check here reaches a network
- * unless the command was asked to.
+ * `probeRegistry` and `probeGithub` are the caller's answers rather than this function's, and both
+ * default to `false`: a context built without them is the context every default run gets, and no
+ * check here reaches a network unless the command was asked to.
  */
-export function buildCheckContext(cwd, probeRegistry = false) {
+export function buildCheckContext(cwd, probeRegistry = false, probeGithub = false) {
     let repoRoot;
     let repoProblem;
     try {
@@ -370,7 +406,7 @@ export function buildCheckContext(cwd, probeRegistry = false) {
         repoProblem = messageOf(error);
     }
     if (repoRoot === undefined)
-        return { cwd, repoProblem, configProblems: [], probeRegistry };
+        return { cwd, repoProblem, configProblems: [], probeRegistry, probeGithub };
     const loaded = loadConfig(repoRoot);
     const profilePath = join(repoRoot, PROFILE_PATH);
     let profile;
@@ -400,6 +436,7 @@ export function buildCheckContext(cwd, probeRegistry = false) {
         profileProblem,
         profilePath,
         probeRegistry,
+        probeGithub,
     };
 }
 /** Is this repository inside a work tree at all — the precondition every repo-wiring check has. */
@@ -416,11 +453,11 @@ const GIT_CHECK = {
  * No `jj` binary is looked for and none is invoked.
  *
  * **What the directory establishes is that `jj` manages this working copy, and not that the
- * repository is colocated.** Measured on jj 0.44.0 and recorded in `README.md`'s `## Scope and
- * limits`, in the bullet opening *Both `jj` shapes adopt*: a **non**-colocated repository's
- * `.jj/repo/store/git_target` holds `../../../.git`, so it too keeps a real non-bare `.git` at the
- * working-copy root with `.jj/` beside it, and this probe answers the same on both shapes. The one
- * clause of the warning below that is colocated-only says so in its own words.
+ * repository is colocated.** Measured on jj 0.44.0 and recorded in `docs/cli.md` §7, the
+ * `jj-repository` bullet: a **non**-colocated repository's `.jj/repo/store/git_target` holds
+ * `../../../.git`, so it too keeps a real non-bare `.git` at the working-copy root with `.jj/`
+ * beside it, and this probe answers the same on both shapes. The one clause of the warning below
+ * that is colocated-only says so in its own words.
  */
 const JJ_DIR = '.jj';
 /**
@@ -1044,7 +1081,7 @@ function deliveryOptInAdvice(candidates) {
     const repositoryRemedy = candidates.some((candidate) => candidate.origin === 'repository')
         ? ', and the repository-side one is filled in by hand'
         : `; this repository configures no repository-side file, so filling one means setting \`pushEnvPath\` in ${CONFIG_FILENAME} first`;
-    return `delivery is opt-in and defaults to nothing pushed, so with neither ${PUSH_URL_KEY} nor ${PUSH_CMD_KEY} set an unattended run's completed, parked and failed events reach a macOS desktop banner where one is available and nothing at all on a Linux host. \`${CLI} init --notifications --push-url <url>\` writes the machine-local file for you${repositoryRemedy}`;
+    return `delivery is opt-in and defaults to nothing pushed, so with neither ${PUSH_URL_KEY} nor ${PUSH_CMD_KEY} set an unattended run's completed, parked and failed events reach a macOS desktop banner where one is available and nothing at all on a Linux host. \`${CLI} init --notifications --push-url ${PUSH_DESTINATION_PLACEHOLDER}\` writes the machine-local file for you${repositoryRemedy}`;
 }
 /**
  * Which settings file an unattended run's notifier will actually read, and whether either delivery
@@ -1586,7 +1623,10 @@ function commandHeads(config, repoRoot) {
  * configuration through and which {@link JQ_CHECK} already treats as a hard floor; and the agent CLI
  * above, whose name arrives as the installed unit's value — `undefined` or empty when the unit does
  * not set it, which is the default case because `${HARNESS_AGENT_CLI:-claude}` reads an empty value
- * as unset too.
+ * as unset too. **A conditional fourth joins them only when {@link remoteExecutionApplies}:** the
+ * binary run as `gh`, which `remote-run.sh` dispatches every remote run through. Its name is the
+ * unit's own {@link GH_CLI_VARIABLE} value when set and non-empty, else {@link DEFAULT_GH_CLI}, on
+ * the agent CLI's terms. With remote execution off the list is exactly the three and the derived.
  *
  * **The unit of comparison is the head of a command line**, over the two places such a line lives, and
  * deriving it is {@link commandHeads}' — this check classifies nothing itself, so it and its sibling
@@ -1612,7 +1652,7 @@ function commandHeads(config, repoRoot) {
  * `ENOENT` in with them printed an unfollowable instruction over the one state `init` clears by
  * itself (Finding 1).
  */
-function requiredBinaries(config, repoRoot, unitAgentCli) {
+function requiredBinaries(config, repoRoot, unitAgentCli, unitGhCli) {
     const found = new Map();
     const ungraded = [];
     // Named `absent` rather than `missing`: in this module a *missing* binary is one the unit's PATH
@@ -1633,6 +1673,10 @@ function requiredBinaries(config, repoRoot, unitAgentCli) {
     add(agent === '' ? DEFAULT_AGENT_CLI : agent, agent === ''
         ? `the watcher's agent binary (${AGENT_CLI_VARIABLE} unset in the unit, so the watcher's default)`
         : `the watcher's agent binary (${AGENT_CLI_VARIABLE}, as the unit sets it)`);
+    if (remoteExecutionApplies(config)) {
+        const gh = unitGhCli?.trim() ?? '';
+        add(gh === '' ? DEFAULT_GH_CLI : gh, `${REMOTE_RUN_SCRIPT}, which the watcher dispatches every run through while execution.target is github-actions (${GH_CLI_VARIABLE} ${gh === '' ? 'unset in the unit, so the default' : 'as the unit sets it'})`);
+    }
     // `deploy` is this check's to skip, on both arms: its command line lives on `deploy.command`
     // rather than in `commands`, and no daemon-launched run deploys. {@link commandHeads} derives it
     // for its other consumer, which does grade it.
@@ -1770,7 +1814,7 @@ const DAEMON_PATH_CHECK = {
             }
             return warn(`the ${backend.kind} unit for ${unit.label} is at ${unit.targetPath} and could not be read (${messageOf(error)}), so the PATH it gives the daemon is unknown: read it yourself, or ${reinstallAdvice(backend.kind)}`);
         }
-        const { binaries: required, ungraded, absent } = requiredBinaries(ctx.config, ctx.repoRoot, unitEnvValue(backend.kind, text, AGENT_CLI_VARIABLE));
+        const { binaries: required, ungraded, absent } = requiredBinaries(ctx.config, ctx.repoRoot, unitEnvValue(backend.kind, text, AGENT_CLI_VARIABLE), unitEnvValue(backend.kind, text, GH_CLI_VARIABLE));
         const envPath = unitEnvValue(backend.kind, text, 'PATH');
         if (envPath === undefined) {
             return warn(`the ${backend.kind} unit for ${unit.label} at ${unit.targetPath} carries no PATH, so the daemon runs on the service manager's own default directories — the state every unit installed before this key shipped is in, and on macOS that is /usr/bin:/bin:/usr/sbin:/sbin, where a Homebrew package manager and an agent CLI under ~/.local/bin both fail to resolve. An unattended run then dies at its first configured command with \`command not found\` while a foreground run is fine, because your shell's PATH is not this. To fix it, ${reinstallAdvice(backend.kind)}`);
@@ -1782,6 +1826,285 @@ const DAEMON_PATH_CHECK = {
         return pass(`the ${backend.kind} unit for ${unit.label} at ${unit.targetPath} carries a PATH reaching every binary an unattended run invokes by name${ungraded.length + absent.length > 0 ? ' that could be derived here' : ''}, each with what requires it: ${nameList(required.map((binary) => `${binary.name} (${binary.sources.join(', ')})`))}. This grades that file rather than this machine — the shell doctor runs in resolves what a service manager's environment does not${describeUngraded(ungraded, absent)}`);
     },
 };
+/**
+ * The configured execution target, and whether this repository has what a remote run needs locally.
+ *
+ * **Remote setup is graded from local evidence by default and asks GitHub only under
+ * `--check-github`** (the module header's choice 3). This reads the two workflow files, one git ref
+ * and `PATH`, and spawns no `gh` subcommand: resolving the binary {@link ghCli} names is the whole of
+ * its `gh` question. What only GitHub can answer — the secrets, the variables, whether GitHub knows
+ * the workflow — the pass text names and leaves to that flag.
+ *
+ * **Every finding is reported, and the grade is the worst of them.** Two `fail`s: no
+ * `harness-run.yml`, because no remote run can be dispatched; and no `gh`, because the watcher
+ * dispatches through it. Three `warn`s: no `harness-resume.yml`, because a usage-paused hosted run then
+ * waits for `/autonomous-sdlc-harness:branch-resume`; a `harness-run.yml` that
+ * `origin/<defaultBranch>` does not carry, because GitHub dispatches only a workflow its default
+ * branch has — the run starts once it is pushed, so nothing is broken here; and `phases.qa` true,
+ * because a remote run skips the interactive-test phase and the branch still reaches review — the
+ * phase is then owed a local run. It needs no GitHub answer, so it is asked here rather than in
+ * {@link REMOTE_GITHUB_CHECK}.
+ *
+ * `gh` is resolved on **this shell's** `PATH`. Whether the installed daemon's `PATH` reaches it is
+ * {@link DAEMON_PATH_CHECK}'s question, answered there through {@link requiredBinaries}' conditional
+ * member, so it is not asked twice.
+ *
+ * **A missing `origin/<defaultBranch>`, or an unusable `defaultBranch`, leaves the origin row
+ * ungraded** and the detail says so: that ref's absence is {@link REMOTE_CHECK}'s `fail`, and
+ * reporting it again would make one finding two. It is asked only when `harness-run.yml` exists here,
+ * for the same reason. The ref is read as this checkout last fetched it.
+ *
+ * With remote execution off, a workflow file left in place is a `pass` that says it does nothing:
+ * the watcher dispatches nothing while the key is `local`.
+ */
+const REMOTE_EXECUTION_CHECK = {
+    id: 'remote-execution',
+    title: 'the configured execution target, and whether this repository has what a remote run needs locally',
+    run: (ctx) => {
+        if (ctx.repoRoot === undefined)
+            return unevaluated('the repository root did not resolve (see the git check)');
+        if (ctx.config === undefined)
+            return unevaluated(`${CONFIG_FILENAME} could not be read (see the config check)`);
+        const root = ctx.repoRoot;
+        const present = (path) => existsSync(join(root, ...path.split('/')));
+        const runPresent = present(WORKFLOW_RUN_PATH);
+        const resumePresent = present(WORKFLOW_RESUME_PATH);
+        if (!remoteExecutionApplies(ctx.config)) {
+            const left = [WORKFLOW_RUN_PATH, WORKFLOW_RESUME_PATH].filter(present);
+            if (left.length === 0)
+                return pass('local execution; remote execution is off (`execution.target`)');
+            return pass(`local execution; remote execution is off (\`execution.target\`), so ${nameList(left)} ${left.length === 1 ? 'is' : 'are'} present and unused: the watcher dispatches nothing while the key is local. \`${CLI} config set execution.target github-actions\` turns remote execution on`);
+        }
+        const failures = [];
+        const warnings = [];
+        const notes = [];
+        if (!runPresent) {
+            failures.push(`${WORKFLOW_RUN_PATH} is absent, so no remote run can be dispatched: re-run \`${CLI} init\`, which writes it create-if-absent while execution.target is github-actions`);
+        }
+        if (!resumePresent) {
+            warnings.push(`${WORKFLOW_RESUME_PATH} is absent, so a hosted run paused on usage waits for /autonomous-sdlc-harness:branch-resume instead of resuming on its own: re-run \`${CLI} init\` to write it`);
+        }
+        const gh = ghCli();
+        if (!resolvesOnPath(gh)) {
+            failures.push(`${gh} does not resolve on this shell's PATH, and the watcher dispatches every remote run through it (${REMOTE_RUN_SCRIPT}): install the GitHub CLI (https://cli.github.com) and run \`gh auth login\`, or point ${GH_CLI_VARIABLE} at it`);
+        }
+        if (ctx.config.phases?.qa === true) {
+            warnings.push("phases.qa is true, but a remote run skips the interactive-test phase — GitHub Actions jobs have no browser wiring, application dependencies or QA credentials for it (docs/remote-execution.md → §3, The interactive-test phase): run /autonomous-sdlc-harness:branch-qa-test <branch> locally before merging a remote run's branch");
+        }
+        if (runPresent) {
+            const branch = ctx.config.defaultBranch;
+            if (typeof branch !== 'string' || branch.trim() === '') {
+                notes.push(`whether GitHub's default branch carries ${WORKFLOW_RUN_PATH} is not graded, because defaultBranch is not a branch name (see the config check)`);
+            }
+            else if (!remoteTrackingBranchResolves(root, branch)) {
+                notes.push(`whether origin/${branch} carries ${WORKFLOW_RUN_PATH} is not graded, because there is no origin/${branch} (see the remote check)`);
+            }
+            else if (!pathAtRef(root, `origin/${branch}`, WORKFLOW_RUN_PATH)) {
+                warnings.push(`origin/${branch} does not carry ${WORKFLOW_RUN_PATH}, as this checkout last fetched it, and GitHub dispatches only a workflow its default branch carries: commit it and push it with \`git push origin ${branch}\``);
+            }
+        }
+        const noted = notes.length > 0 ? `; ${notes.join('; ')}` : '';
+        const on = 'remote execution is on (execution.target github-actions)';
+        if (failures.length > 0)
+            return fail(`${on}: ${[...failures, ...warnings].join('; ')}${noted}`);
+        if (warnings.length > 0)
+            return warn(`${on}: ${warnings.join('; ')}${noted}`);
+        return pass(`${on}: ${WORKFLOW_RUN_PATH} and ${WORKFLOW_RESUME_PATH} are present and ${gh} resolves on PATH${noted}. What this cannot see lives on GitHub — a credential secret (${OAUTH_TOKEN_SECRET} or ${API_KEY_SECRET}), the ${PUSH_URL_SECRET} and ${GIT_TOKEN_SECRET} secrets, and the ${RUNNER_VARIABLE} and ${REMOTE_STOP_VARIABLE} variables; \`${CLI} doctor --check-github\` asks GitHub`);
+    },
+};
+/**
+ * What `gh` prints when it cannot reach GitHub at all — `error connecting to api.github.com`, then a
+ * pointer to check the connection. Matched so a network failure grades as *cannot tell* rather than
+ * as the thing asked about being missing.
+ */
+const GH_UNREACHABLE_PATTERN = /error connecting to|check your internet connection/i;
+/**
+ * A stopped call — the bound in `runGh`, or any other signal — and one that could not reach GitHub
+ * are `unknown`; any other non-zero exit is `refused`, quoting `gh`'s own first line.
+ */
+function classifyGh(result) {
+    if (result.status === 0)
+        return { kind: 'answered', stdout: result.stdout };
+    const said = firstLine(result.stderr) || firstLine(result.stdout);
+    if (result.status === null)
+        return { kind: 'unknown', why: 'it was stopped before it answered (timed out)' };
+    if (GH_UNREACHABLE_PATTERN.test(result.stderr))
+        return { kind: 'unknown', why: `it could not reach GitHub (${said})` };
+    return { kind: 'refused', why: said === '' ? `it exited ${result.status}` : `it exited ${result.status}: ${said}` };
+}
+/** The `name` field of each element of a `gh … list --json` array, or `undefined` when it is not that shape. */
+function ghJsonEntries(stdout) {
+    let parsed;
+    try {
+        parsed = JSON.parse(stdout);
+    }
+    catch {
+        return undefined;
+    }
+    if (!Array.isArray(parsed))
+        return undefined;
+    const entries = new Map();
+    for (const item of parsed) {
+        if (!isJsonObject(item) || typeof item.name !== 'string')
+            return undefined;
+        entries.set(item.name, typeof item.value === 'string' ? item.value : '');
+    }
+    return entries;
+}
+/** The positive-integer `days` of an artifact-retention answer, or `undefined` for any other shape. */
+function retentionDaysOf(stdout) {
+    let parsed;
+    try {
+        parsed = JSON.parse(stdout);
+    }
+    catch {
+        return undefined;
+    }
+    if (!isJsonObject(parsed))
+        return undefined;
+    const days = parsed.days;
+    return typeof days === 'number' && Number.isInteger(days) && days > 0 ? days : undefined;
+}
+/**
+ * What GitHub says about the remote setup — asked only under {@link CheckContext.probeGithub}.
+ *
+ * **Off by default** (the module header's choice 3): a default run passes saying it did not ask, and
+ * spawns nothing. Every call goes through `remote/githubActions.ts` → `runGh` with a fixed argument
+ * vector and is a read. Secret **values** are never read: `gh secret list` returns names only.
+ *
+ * Grades, worst wins and every finding is reported:
+ * - `fail` — `gh` does not spawn or `gh auth status` refuses (nothing further is asked); GitHub does
+ *   not know `harness-run.yml`; neither credential secret is set.
+ * - `warn` — `HARNESS_PUSH_URL` absent; `harness-resume.yml` unknown to GitHub; `HARNESS_REMOTE_STOP`
+ *   set; artifact retention below {@link ARTIFACT_RETENTION_WARN_DAYS} days; and any call that timed
+ *   out, could not reach GitHub, or answered in a shape not understood — *cannot tell* is not
+ *   *missing*, so it never fails.
+ * - both credential secrets present is a note, not a finding: billing follows `ANTHROPIC_API_KEY`.
+ * - the retention read refused (typically HTTP 403: the endpoint needs admin access) is a note too —
+ *   the read is best-effort, and a collaborator without admin can still run remotely.
+ *
+ * **Why 30 days.** A parked run waits on a human answer and a usage-paused one on a reset, and the
+ * `harness-state` bundle is the only remote copy of either; once the repository's retention expires
+ * it, the run can no longer be answered and loses its carried counts. Thirty days covers an ordinary
+ * absence — a holiday — while GitHub's own default of 90 passes; below it, an ordinary absence can
+ * cost a parked run its question.
+ */
+const REMOTE_GITHUB_CHECK = {
+    id: 'remote-github',
+    title: 'what GitHub says about the remote setup',
+    run: (ctx) => {
+        if (ctx.repoRoot === undefined)
+            return unevaluated('the repository root did not resolve (see the git check)');
+        if (ctx.config === undefined)
+            return unevaluated(`${CONFIG_FILENAME} could not be read (see the config check)`);
+        if (!remoteExecutionApplies(ctx.config))
+            return pass('remote execution is off (`execution.target`), so nothing was asked of GitHub');
+        if (!ctx.probeGithub)
+            return pass(`not asked — run \`${CLI} doctor --check-github\` to ask GitHub about the secrets, variables and workflows a remote run needs`);
+        const root = ctx.repoRoot;
+        const gh = ghCli();
+        const ask = (args) => {
+            const result = runGh(args, root);
+            return { call: `\`gh ${args.join(' ')}\``, answer: result === undefined ? undefined : classifyGh(result) };
+        };
+        const ghRemedy = `install the GitHub CLI (https://cli.github.com) and run \`gh auth login\`, or point ${GH_CLI_VARIABLE} at it`;
+        const noSpawn = `${gh} could not be run, so GitHub was not asked: ${ghRemedy}`;
+        const cannotTell = (call, why, what) => `cannot tell ${what}: ${call} gave no answer, because ${why}`;
+        const auth = ask(['auth', 'status']);
+        if (auth.answer === undefined)
+            return fail(noSpawn);
+        if (auth.answer.kind === 'unknown')
+            return warn(cannotTell(auth.call, auth.answer.why, 'whether gh is authenticated, so nothing further was asked'));
+        if (auth.answer.kind === 'refused')
+            return fail(`${auth.call} reports no usable login, because ${auth.answer.why}: run \`gh auth login\``);
+        const failures = [];
+        const warnings = [];
+        const notes = [];
+        const run = ask(['workflow', 'view', WORKFLOW_RUN_FILE]);
+        if (run.answer === undefined)
+            return fail(noSpawn);
+        if (run.answer.kind === 'unknown')
+            warnings.push(cannotTell(run.call, run.answer.why, `whether GitHub knows ${WORKFLOW_RUN_FILE}`));
+        if (run.answer.kind === 'refused') {
+            failures.push(`GitHub does not know ${WORKFLOW_RUN_FILE} (${run.call}: ${run.answer.why}), so no remote run can be dispatched: push ${WORKFLOW_RUN_PATH} to the repository's default branch`);
+        }
+        const secrets = ask(['secret', 'list', '--json', 'name']);
+        if (secrets.answer === undefined)
+            return fail(noSpawn);
+        const secretNames = secrets.answer.kind === 'answered' ? ghJsonEntries(secrets.answer.stdout) : undefined;
+        if (secrets.answer.kind !== 'answered') {
+            warnings.push(cannotTell(secrets.call, secrets.answer.why, 'which repository secrets are set'));
+        }
+        else if (secretNames === undefined) {
+            warnings.push(`cannot tell which repository secrets are set: ${secrets.call} answered in a shape this check does not read`);
+        }
+        else {
+            const oauth = secretNames.has(OAUTH_TOKEN_SECRET);
+            const apiKey = secretNames.has(API_KEY_SECRET);
+            if (!oauth && !apiKey) {
+                failures.push(`neither ${OAUTH_TOKEN_SECRET} nor ${API_KEY_SECRET} is a repository secret, so a remote run cannot authenticate its agent: set one with \`gh secret set <name>\` — billing follows ${API_KEY_SECRET} when both are set`);
+            }
+            else if (oauth && apiKey) {
+                notes.push(`both ${OAUTH_TOKEN_SECRET} and ${API_KEY_SECRET} are set, so billing follows ${API_KEY_SECRET}`);
+            }
+            if (!secretNames.has(PUSH_URL_SECRET)) {
+                warnings.push(`${PUSH_URL_SECRET} is not a repository secret, so notifications from a remote run reach no one: set it with \`gh secret set ${PUSH_URL_SECRET}\``);
+            }
+        }
+        const resume = ask(['workflow', 'view', WORKFLOW_RESUME_FILE]);
+        if (resume.answer === undefined)
+            return fail(noSpawn);
+        if (resume.answer.kind === 'unknown')
+            warnings.push(cannotTell(resume.call, resume.answer.why, `whether GitHub knows ${WORKFLOW_RESUME_FILE}`));
+        if (resume.answer.kind === 'refused') {
+            warnings.push(`GitHub does not know ${WORKFLOW_RESUME_FILE} (${resume.call}: ${resume.answer.why}), so usage auto-resume is unavailable: push ${WORKFLOW_RESUME_PATH} to the repository's default branch`);
+        }
+        const variables = ask(['variable', 'list', '--json', 'name,value']);
+        if (variables.answer === undefined)
+            return fail(noSpawn);
+        const variableValues = variables.answer.kind === 'answered' ? ghJsonEntries(variables.answer.stdout) : undefined;
+        let runner;
+        if (variables.answer.kind !== 'answered') {
+            warnings.push(cannotTell(variables.call, variables.answer.why, `the ${RUNNER_VARIABLE} and ${REMOTE_STOP_VARIABLE} variables`));
+        }
+        else if (variableValues === undefined) {
+            warnings.push(`cannot tell the ${RUNNER_VARIABLE} and ${REMOTE_STOP_VARIABLE} variables: ${variables.call} answered in a shape this check does not read`);
+        }
+        else {
+            const label = variableValues.get(RUNNER_VARIABLE)?.trim() ?? '';
+            runner = label === '' ? 'GitHub-hosted (`ubuntu-latest`)' : `runner label \`${label}\``;
+            if ((variableValues.get(REMOTE_STOP_VARIABLE) ?? '') !== '') {
+                warnings.push(`${REMOTE_STOP_VARIABLE} is set, so every remote start and continuation is stopped: \`gh variable delete ${REMOTE_STOP_VARIABLE}\` lifts it`);
+            }
+        }
+        const retention = ask(['api', ARTIFACT_RETENTION_ENDPOINT]);
+        if (retention.answer === undefined)
+            return fail(noSpawn);
+        let retentionDays;
+        if (retention.answer.kind === 'unknown') {
+            warnings.push(cannotTell(retention.call, retention.answer.why, 'how long the repository keeps artifacts'));
+        }
+        else if (retention.answer.kind === 'refused') {
+            notes.push(`artifact retention not checked: ${retention.call} needs admin access (${retention.answer.why})`);
+        }
+        else {
+            retentionDays = retentionDaysOf(retention.answer.stdout);
+            if (retentionDays === undefined) {
+                warnings.push(`cannot tell how long the repository keeps artifacts: ${retention.call} answered in a shape this check does not read`);
+            }
+            else if (retentionDays < ARTIFACT_RETENTION_WARN_DAYS) {
+                warnings.push(`the repository keeps artifacts for ${retentionDays} days, so a remote run parked or paused longer than that loses its state bundle: raise it under Settings → Actions → General → Artifact and log retention`);
+            }
+        }
+        const noted = notes.length > 0 ? `; ${notes.join('; ')}` : '';
+        if (failures.length > 0)
+            return fail(`${[...failures, ...warnings].join('; ')}${noted}`);
+        if (warnings.length > 0)
+            return warn(`${warnings.join('; ')}${noted}`);
+        const kept = retentionDays === undefined ? '' : `, and the repository keeps artifacts for ${retentionDays} days`;
+        return pass(`gh is authenticated, GitHub knows ${WORKFLOW_RUN_FILE} and ${WORKFLOW_RESUME_FILE}, a credential secret and ${PUSH_URL_SECRET} are set, and remote runs use ${runner}${kept}${noted}`);
+    },
+};
 /**
  * The config's shape, re-checked at runtime.
  *
@@ -2202,8 +2525,6 @@ const STATE_DIR_TREE_CHECK = {
         return pass(`all ${expected.length} artifact directories the configured phases call for are present under ${root}`);
     },
 };
-/** The command both remedies below name, spelled as `init` and every stub footer spell it. */
-const ANALYZE_COMMAND = '/harness-analyze';
 /**
  * Setup's judgement half, reported as the four facts that decide it: a configured conventions
  * document with nothing behind it, one that is still an untouched skeleton, a configured
@@ -2459,7 +2780,7 @@ function detectionProvenance(detection) {
  *
  * **It is deliberately blind to the conventions documents.** {@link SETUP_ANALYSIS_CHECK} above
  * grades those, and its skeleton warning was the last indirect trace that a fallback profile had
- * never been examined — a trace `/harness-analyze conventions` clears by filling the documents,
+ * never been examined — a trace `/autonomous-sdlc-harness:harness-analyze conventions` clears by filling the documents,
  * leaving `doctor` green about a profile nobody looked at. This check reads no document, so that
  * command does not move it.
  *
@@ -3035,7 +3356,7 @@ function namesHelperScript(entry) {
  * With nothing left to grade — the phase off at a single root — it reports **not graded** and names
  * which, rather than a pass an adopter would read as coverage.
  *
- * The helper names come from **reading `<root>/scripts/`** ({@link pluginHelperScripts}) at each
+ * The helper names come from **reading `<root>/scripts/`** ({@link pluginRootHelpers}) at each
  * graded root and taking the union, never from a list kept here: they are declared once, in the
  * plugin's own `scripts/README.md`, and a copy in this file would be a second declaration that
  * drifts the first time one is added. Nothing here classifies a helper by its call site either —
@@ -3120,7 +3441,7 @@ const PLUGIN_PERMISSIONS_CHECK = {
         // complete that is one unreadable file away from a stall.
         const phaseKnown = ctx.config !== undefined;
         const qaOn = ctx.config?.phases?.qa === true;
-        const helpers = qaOn ? [...new Set(roots.flatMap((root) => pluginHelperScripts(root)))].sort() : [];
+        const helpers = pluginRootHelpers(roots, qaOn);
         const groups = roots.map((root) => ({
             root,
             label: split
@@ -3130,17 +3451,15 @@ const PLUGIN_PERMISSIONS_CHECK = {
                 : installRoot === undefined
                     ? `the directory this marketplace is sourced from (the only root that resolved: ${installedPluginsPath()} records no install root)`
                     : `the one plugin root this machine resolves, recorded in ${installedPluginsPath()}`,
-            required: [
-                // Outside the phase gate, and only where the runtime root is its own directory: reads at the
-                // install root were measured to succeed ungranted, ten at the runtime root to be refused.
-                ...(root === installRoot
-                    ? []
-                    : [{ rule: readRule(root), symptom: 'improvises in place of a contract file it is refused' }]),
-                ...helpers.map((name) => ({
-                    rule: bashScriptRule(pluginHelperPath(root, name)),
-                    symptom: 'parks with no error at the first helper script it reaches',
-                })),
-            ],
+            // The builder `init --plugin-root-entries` writes through too, so the two cannot differ. The
+            // read rule is outside the phase gate and absent at the install root: reads there were measured
+            // to succeed ungranted, ten at the runtime root to be refused.
+            required: pluginRootEntries(root, { isInstallRoot: root === installRoot, helpers }).map(({ kind, rule }) => ({
+                rule,
+                symptom: kind === 'read'
+                    ? 'improvises in place of a contract file it is refused'
+                    : 'parks with no error at the first helper script it reaches',
+            })),
         }));
         const required = groups.flatMap((group) => group.required);
         if (required.length === 0) {
@@ -3383,6 +3702,121 @@ const BROWSER_WIRING_CHECK = {
         return pass(`${MCP_PATH} declares ${nameList(declared)} and every launch command resolves on PATH; no server was started and no browser was launched${resolution}.${registryNote}${noClient}`);
     },
 };
+/** The pass every retrieval check gives when {@link retrievalApplies} is false. */
+const RETRIEVAL_OFF = 'docs.retrieval is off (it needs phases.docs and docs.retrieval both true), so no RAG library is expected and none was resolved';
+/** How many missing model files {@link RETRIEVAL_MODEL_CACHE_CHECK} names before it counts the rest. */
+const MISSING_MODEL_FILES_NAMED = 5;
+/**
+ * How long the `retrieval-index` probe may run. Wide because a real corpus embeds every chunk on this
+ * probe, and a bound that cut that off would fail an index that builds.
+ */
+const RETRIEVAL_INDEX_TIMEOUT_MS = 600_000;
+/**
+ * Is the runtime `.mcp.json`'s launcher `exec`s installed, at this CLI's version, with its peers?
+ *
+ * Answered by {@link retrievalRuntimeState} alone — the predicate `init`'s setup skips the install on —
+ * so the two cannot disagree (choice 1). Whether **this** installation resolves its own peers is not
+ * consulted: the launcher never runs this installation, so a pass on it would be a pass on a server
+ * that never starts.
+ */
+const RETRIEVAL_DEPENDENCIES_CHECK = {
+    id: 'retrieval-dependencies',
+    // The first of the three retrieval checks in registration order, and so the one that expands the
+    // term for the whole report: the other two say "RAG" alone.
+    title: 'RAG (docs retrieval) libraries resolve',
+    run: (ctx) => {
+        if (ctx.repoRoot === undefined)
+            return unevaluated('the repository root did not resolve (see the git check)');
+        if (ctx.config === undefined)
+            return unevaluated(`${CONFIG_FILENAME} could not be read (see the config check)`);
+        if (!retrievalApplies(ctx.config))
+            return pass(RETRIEVAL_OFF);
+        const runtime = retrievalRuntimeDir();
+        const state = retrievalRuntimeState();
+        if (state.installed) {
+            return pass(`the RAG runtime is installed at ${runtime} (version ${state.version ?? 'unknown'}) with every optional peer, and ${MCP_PATH}'s launcher ${DOCS_SEARCH_SERVER_SCRIPT_NAME} execs that installation's entry`);
+        }
+        return fail(`the RAG runtime at ${runtime} is missing ${nameList(state.missing)}, so ${MCP_PATH}'s launcher ${DOCS_SEARCH_SERVER_SCRIPT_NAME} has nothing to exec until it is installed and the search server never starts — run \`${CLI} init\`, which installs it`);
+    },
+};
+/** Are both models' files in the shared model cache — the offline load's precondition? */
+const RETRIEVAL_MODEL_CACHE_CHECK = {
+    id: 'retrieval-model-cache',
+    title: "RAG's models are cached",
+    run: (ctx) => {
+        if (ctx.repoRoot === undefined)
+            return unevaluated('the repository root did not resolve (see the git check)');
+        if (ctx.config === undefined)
+            return unevaluated(`${CONFIG_FILENAME} could not be read (see the config check)`);
+        if (!retrievalApplies(ctx.config))
+            return pass(RETRIEVAL_OFF);
+        const dir = retrievalModelCacheDir();
+        const { present, missing } = modelFilesPresent(dir);
+        if (present)
+            return pass(`every model file RAG loads offline is cached in ${dir}`);
+        const named = missing.slice(0, MISSING_MODEL_FILES_NAMED).join(', ');
+        const rest = missing.length - MISSING_MODEL_FILES_NAMED;
+        return fail(`the model cache at ${dir} is missing ${named}${rest > 0 ? ` and ${rest} more` : ''} — run \`${CLI} init\`, which downloads them at setup time. An unattended run has no web access, so a model missing now is never fetched later`);
+    },
+};
+/** The last non-empty line of a child's output, or `undefined` when it printed nothing. */
+function lastNonEmptyLine(output) {
+    return output
+        .split('\n')
+        .map((line) => line.trim())
+        .filter((line) => line !== '')
+        .at(-1);
+}
+/**
+ * Does the docs-retrieval index build?
+ *
+ * A child process of this CLI runs `docs index --in-memory` rather than the server being launched —
+ * choice 3's *"never a launch"*: the child builds the whole index in memory, prints one line and exits,
+ * so no server starts and nothing is written. It is a child at all because {@link Check.run} is
+ * synchronous and the store is not. Its entry is {@link retrievalCliEntry}'s: the probe asks whether an
+ * index builds, not what the launcher runs, which `retrieval-dependencies` grades.
+ *
+ * **`spawnSync` rather than `execFileSync`**, for the reason `cli/src/commands/doctor.ts` →
+ * `runNotifier` states: `execFileSync` returns stdout and surfaces a child's stderr on the error path
+ * only, and the child's corpus-coverage warnings — an unset or mis-spelled `docs.root`, a missing
+ * conventions document — are printed on stderr by a run that **succeeds**. This is the one check an
+ * adopter runs to answer "is retrieval set up correctly?", so a build over a corpus missing the whole
+ * documentation catalog must not read as an unqualified pass.
+ */
+const RETRIEVAL_INDEX_CHECK = {
+    id: 'retrieval-index',
+    title: 'the RAG index builds',
+    run: (ctx) => {
+        if (ctx.repoRoot === undefined)
+            return unevaluated('the repository root did not resolve (see the git check)');
+        if (ctx.config === undefined)
+            return unevaluated(`${CONFIG_FILENAME} could not be read (see the config check)`);
+        if (!retrievalApplies(ctx.config))
+            return pass(RETRIEVAL_OFF);
+        const resolved = retrievalCliEntry();
+        if (resolved === undefined)
+            return fail('cannot build without the RAG libraries (see retrieval-dependencies)');
+        // `spawnSync` does not throw on a non-zero exit, so this `try` now covers a spawn failure alone;
+        // the child's own failure is graded on `status` and `error` below.
+        try {
+            const child = spawnSync(process.execPath, [resolved.entry, 'docs', 'index', '--in-memory', '--cwd', ctx.repoRoot], {
+                encoding: 'utf8',
+                stdio: ['ignore', 'pipe', 'pipe'],
+                timeout: RETRIEVAL_INDEX_TIMEOUT_MS,
+                env: process.env,
+            });
+            const line = lastNonEmptyLine(child.stderr ?? '');
+            if (child.error !== undefined || child.status !== 0) {
+                const how = child.status === null ? `it was stopped by ${child.signal}` : `it exited with status ${child.status}`;
+                return fail(`the RAG index did not build in memory: ${line ?? (child.error === undefined ? how : messageOf(child.error))} — run \`${CLI} init\` to set retrieval up`);
+            }
+            return pass(line === undefined ? child.stdout.trim() : `${child.stdout.trim()} — ${line}`);
+        }
+        catch (error) {
+            return fail(`the RAG index did not build in memory: ${messageOf(error)} — run \`${CLI} init\` to set retrieval up`);
+        }
+    },
+};
 /**
  * The checks, in the order they are evaluated and reported: the host and the tools first, then the
  * repository's own wiring, then the permission profile and the browser half that depends on it.
@@ -3459,11 +3893,17 @@ const BROWSER_WIRING_CHECK = {
  * for the machine around it — and they are meant to be read together. `daemon-path` comes last of
  * the six because it is the only one that grades an *installed* unit: it has nothing to say until the
  * five above it are answered, and it says so rather than guessing.
+ * `remote-execution` follows it because it asks the same "can this run unattended" question of a run
+ * the watcher dispatches to GitHub rather than spawns here, and `remote-github` follows that because it
+ * asks GitHub the half of the same question local evidence cannot answer.
  *
  * `plugin-permissions` closes the profile block for the same shape of reason: it is the only profile
  * question whose other half is not in the repository at all — the plugin's machine-local install
  * root — so it is answerable only once the profile itself has been read, and a reader whose
  * profile lines all passed reads it as the last thing that can still be missing from that file.
+ *
+ * The three `retrieval-*` checks come last, under `browser-wiring`: the runtime, the models, then
+ * whether an index builds, which needs libraries and models both and so reads after them.
  */
 export const CHECKS = Object.freeze([
     GIT_CHECK,
@@ -3481,6 +3921,8 @@ export const CHECKS = Object.freeze([
     REPO_REGISTRY_CHECK,
     MACHINE_FOOTPRINT_CHECK,
     DAEMON_PATH_CHECK,
+    REMOTE_EXECUTION_CHECK,
+    REMOTE_GITHUB_CHECK,
     CONFIG_CHECK,
     COMMAND_WRAPPERS_CHECK,
     COMMAND_PERMISSIONS_CHECK,
@@ -3499,6 +3941,9 @@ export const CHECKS = Object.freeze([
     PROFILE_DENY_FLOOR_CHECK,
     PLUGIN_PERMISSIONS_CHECK,
     BROWSER_WIRING_CHECK,
+    RETRIEVAL_DEPENDENCIES_CHECK,
+    RETRIEVAL_MODEL_CACHE_CHECK,
+    RETRIEVAL_INDEX_CHECK,
 ]);
 /**
  * Evaluate every check in order and return one result each.