@bongos/core 1.17.0

package/scripts/gds/CLAUDE.md

@@ -0,0 +1,144 @@
+# scripts/gds/ — builder CLI (agent notes)
+
+> Nested CLAUDE.md — loads on demand when you work here. Root [CLAUDE.md](../../CLAUDE.md) is the index. See [ADR 0061](../../docs/adr/<redacted>.md) for why these exist.
+
+**Purpose.** Cross-platform Node CLI behind the `/builder-*` slash commands (`.claude/skills/builder-*`). Every script talks to `/api/gds/*` on `example.com` (override `GDS_API_BASE` for local dev). `node` is the one guaranteed runtime — no bash/python/jq in the JS path ([#686](https://example.com/builders#/task/686)), so the skills shell out to `node scripts/gds/*.js`. Session token lives in the instance config dir — `~/.config/<configDir>/gds-session.json`, resolved via `src/instance-config.js` (R61/[#1200](https://example.com/builders#/task/1200)); OTB pins `configDir=otb` so it stays `~/.config/otb`, with read-fallback to the legacy dir + `pms-session.json`. Env vars resolve `<envPrefix>_<SUFFIX>` (OTB → `OTB_`) then legacy `OTB_`/`GDS_`/`PMS_`.
+
+**Shared kit.** `cli-lib.js` — `apiCall(method, path, body)` (adds auth header, resolves token+base), `requireSession`, `arg`/`hasFlag` (argv parsing), `readSessionToken`, plus terminal format helpers + onboarding/cost nudges. `api.js` — generic `node api.js METHOD /path [--body | --body-file -]` caller; status→STDERR, JSON→STDOUT.
+
+**Entry points (→ slash command).**
+- `start.js` → `/builder-start` — list claimable tasks (parallel-safe vs active claims); `--fit`, `--discipline`, `--version`, `--track`, `--json`.
+- `claim.js` → `/builder-claim N` — atomically claim a task; prints claim id + touches[] + relevant learnings/context-pack.
+- `ship.js` → `/builder-ship` — **the big one (~151KB)**; 3-step lifecycle completed→confirmed (credits, smoke)→shipped (merge+deploy). Flags: `--no-merge`, `--skip-grade`, `--regrade`, `--force`, `--allow-empty`. The empty-diff/phantom-ship guard runs **regardless of `--skip-grade`** (task 1365 closed the task-1363 hole where `--skip-grade` bypassed it and a never-committed deliverable confirmed + reconciler-shipped with no artifact on main); a no-artifact/DB-only ship now needs explicit `--allow-empty`, which is still **refused if the working tree is dirty/untracked** (that means you forgot to commit).
+- `release.js` → `/builder-release N` — cancel a claim (no credits); task returns to `ready`.
+- `capture.js` → idea_inbox — file an idea (`--kind`, `--body-file`, `--version`); `recall.js` → `/recall` — lexical (FTS+trigram/RRF) rank-scoped knowledge search; `learning-capture.js` — durable short-form learning into the DB.
+- `gen-diagrams.js` — regenerate the 5 onboarding `.mmd`/`.svg`/`.png` + `assertions.json` from live facts; `gen-repo-map.js` — regenerate the code symbol skeleton (`docs/repo-map.md` + the generated factual block in each nested CLAUDE.md; ADR 0063); `gen-session-index.js` — regenerate the session-log index (`docs/session-log-index.md` + the bounded CLAUDE.md §13 snippet) from `docs/session-logs/*.md` (ADR 0062 §8, task 1226); `gen-file-map.js` — regenerate the `.claude/skills/` + `.claude/scheduled-tasks/` sections of `docs/file-map.md` from disk, notes sourced from `docs/file-map.notes.json` (ADR 0066, task 1276; `--check` fails on drift or an undescribed skill/routine); `fitness.js` — architecture fitness gate (core↔host boundary, CLAUDE.md budget, nested-doc presence, rank-guard, generated-artifact freshness; ADR 0062 §9, enforced via `tests/fitness.mjs`); `architect-audit.js` — MAS Phase 5 bounded first-principles `--scope` audit → `docs/audits/`; `linkify-refs.js` — rewrite bare `#NNN` refs into hall links so GitHub doesn't mis-autolink.
+- `box.js` — operator/control-plane dev-box lifecycle (`provision`/`park`/`wake`/`deprovision`/`sweep-*`/`status`); rank-gated against live DB rank. **Runs on the control plane, never inside a box.**
+- `provision.js` — the **instance-provisioning** control-plane runner (ADR 0111 §2/§3, [#1944](https://example.com/builders#/task/1944)); a sibling of `box.js`. Sole holder of the DO/Cloudflare tokens; drains `provisioning_intents` (the web tier only enqueues) and composes the [`cloudbongos-standup`](../../docs/recipes/cloudbongos-standup.md) runbook — server (co-tenant port OR dedicated droplet) → `createdb` + GDS-only migrate → per-instance `/etc/<slug>/web.env` → systemd unit → per-instance Caddy snippet + reload → `/healthz` — **idempotent, dry-run-default** (nothing mutates without `--apply`), drift-reconciling. Driven by `infra/provision-intent-runner.timer`. Commands: `run-intents`/`provision <slug>`/`teardown <slug>`/`reconcile`/`status`/`dns-check <domain>` (the task-[#1980](https://example.com/builders#/task/1980) DNS token-scope PREFLIGHT — read-only, verifies the CF token reaches the domain's zone before the address step; provisioning also fail-fasts on it up front). Reuses `do-api.js` + `modules/provisioning/provisioning.js`. **Runs on the control plane, never inside the web tier.** The runner is `User=lars` (non-root), so the privileged steps (write `/etc`, `systemctl`, `createdb`/`migrate`) escalate via `sudo` (temp-file + `sudo install`, `sudo systemctl`, `sudo -u postgres`) **only under `PROVISION_SUDO=1`** — the runner unit sets it ([ADR 0128](../../docs/adr/<redacted>.md)); default OFF keeps CLI/test runs bare. The unit must NOT set `NoNewPrivileges=true` (it blocks `sudo`). With `PROVISION_REMOTE_HOST` set it also runs the box-mutating steps on a remote co-hosting box over `ssh` (control plane orchestrates co-tenants that live elsewhere → zero cloud tokens on that box), while the Cloudflare DNS hook stays local via `controlExec` ([ADR 0130](../../docs/adr/<redacted>.md), task 2065); default OFF = all-local, unchanged. The `cohost-*` control-plane runner units + the SSH DB tunnel that read the co-hosting box's queues over `127.0.0.1:5433` to activate this end-to-end are [ADR 0132](../../docs/adr/<redacted>.md) / task 2071.
+- `oauth-secret.js` — **verified, shell-independent OAuth-secret placement** for a provisioned instance (ADR 0111, [#1979](https://example.com/builders#/task/1979)); the onboarding step every form (skill/CLI/hall) drives. `place <slug> --client-id --client-secret [--apply]`: VALIDATES the creds (length/charset — catches the silent 26-char truncation `authConfigured()` misses, since it only checks presence), rewrites `/etc/<slug>/web.env` via Node (never a fragile `read -s`/`sed -i`), restarts the unit, then PROBES `/healthz` for `auth_configured:true`. Dry-run-default; control-plane only.
+- `do-api.js` · `cf-tunnel.js` · `http-api-client.js` — the **shared control-plane network clients** (DigitalOcean v2 · Cloudflare named-tunnel · their JSON-HTTP skeleton). Operator-CLI-only (never the web tier), injectable-transport + **dry-run-by-default**. Moved here from `modules/dev-box/` in BV1 task [#1943](https://example.com/builders#/task/1943) ([ADR 0111](../../docs/adr/<redacted>.md) §2) so both `box.js` AND the instance-provisioning runner `provision.js` (task #1944) reuse the DO client without a module→module import. (The Cloudflare **DNS-record** hook stays at `infra/box-dns-cloudflare.sh`, invoked by path via `BOX_DNS_HOOK`.)
+- `seed-v3-tasks.js` / `seed-gds-v4-tasks.js` — idempotent planning-session task seeders (skip on existing `source_ref`); `newcomer-floor.*` — deterministic copy-stamp replenisher for newcomer chores (`.js` + `.config.json` + `.templates.json` + `.test.js`).
+
+**Gotchas / invariants.**
+- `ship.js` is huge — search by phase keyword, don't read end-to-end. Every change here still needs a claimed GDS task (no admin loophole).
+- Cross-platform = no bash-isms in the `.js` path; keep `process.execPath`/`os.homedir()` patterns.
+- Never hand-edit generated `.mmd`/`assertions.json` — run `gen-diagrams.js`. Never hand-edit `linkify-refs.js`'s output by adding bare `#NNN`.
+- **The guardrails are two-root aware ([ADR 0108](../../docs/adr/<redacted>.md) §Consequences #4).** `fitness.js`, `gen-repo-map.js`, `gen-file-map.js` resolve `resolveCoreRoot()` (core code + the src/bongos·scripts/gds nested docs) vs `resolveInstanceRoot()` (the root CLAUDE.md, `.claude/`, instance modules + migrations); modules are scanned across both. Today both roots are the one checkout (byte-identical); post-split each inspects the right tree. **Do not reintroduce a hardcoded `path.resolve(__dirname,'..','..')`** in these files — it re-fuses the boundary and would point into `node_modules` post-split. `tests/fitness_two_root.mjs` diverges the roots to prove it.
+- **Migration filenames are namespaced by source ([ADR 0108](../../docs/adr/<redacted>.md) §5, `migration-namespace.js`).** A NEW core migration is `migrations/core_NNN_slug.sql`; a NEW module migration is `modules/<key>/migrations/<key>_NNN_slug.sql`; instance seeds stay bare `migrations/instance/NNN_slug.sql`. This is what lets the core repo and the instance repo version independently without their migrations colliding on the stem-keyed `schema_migrations`. Existing bare files are grandfathered (never rename one — it re-runs on prod). `fitness.js` Check 11b + `tests/migration_namespace.mjs` enforce it; `claim.js`/`next-number.js` suggest the namespaced form. `migrate.sh` merges three roots (core-package / instance / module) resolved via `resolveCoreRoot()`/`resolveInstanceRoot()`.
+- Many other files here are not slash-command entry points: smoke tests (`smoke-*.sh`/`smoke-gds.js`), audits (`audit-*`, `main-audit.js`, `gate-review.js`), session tooling (`session*.js`, `pulse.js`), and systemd units (`gds-db-*.{service,timer}`).
+
+<!-- BEGIN GENERATED REPO-MAP (scripts/gds/gen-repo-map.js — do not hand-edit) -->
+**Symbol skeleton (generated from the code — do not hand-edit; refresh: `node scripts/gds/gen-repo-map.js`).** Exported signatures, most-referenced first. The interpretive notes above are hand-written; this factual list is regenerated on deploy so it can't drift ([ADR 0063](../../docs/adr/<redacted>.md)).
+
+- `adopt-detect.js` — `detectStack({ dir, fs = nodeFs, path = nodePath } = {})`, `formatStackSummary(s)`, `detectPackageManager(exists, hasPkg)`
+- `adopt-import.js` — `DEFAULT_MAX`, `parseBacklogFile(text)`, `resolveBacklogTasks({ dir, repo = {}, githubToken, backlogFile, fetchImpl, fs = nodeFs, path = nodePath, max =…)`, `BACKLOG_FILENAMES`, `fetchGitHubIssues({ owner, repo, token, fetchImpl = globalThis.fetch, max = DEFAULT_MAX, onWarn = ()`, `findBacklogFile(dir, fs = nodeFs, path = nodePath)`, `parseGitHubIssues(issues)`
+- `adopt-preflight.js` — `SEV`, `formatPreflight(report)`, `INCOMING_PATHS`, `preflightAdopt({ dir, stack = {}, fs = nodeFs, path = nodePath } = {})`, `checkCiCollisions(workflows = [])`, `checkFitnessBoundary({ topLevelDirs = [], hasSrcBongos = false } = {})`, `checkMigrationNamespace(basenames = [])`, `checkProtectedPaths(incoming = INCOMING_PATHS)`, `CORE_EXPECTED_CHECKS`
+- `architect-audit.js` — `slug(scope)`, `buildPrompt({ scope, fileList, fileBlocks, version })`, `PROMPT_HEADER`, `pickValidKind(kind)`, `validateSeedIdeas(raw)`
+- `art-stage.js` — `waitHealthy(healthUrl, deps = {})`, `affectedTiles(explicit, deps = {})`, `copyAtlasToServed(deps = {})`, `rebuildAtlas(deps = {})` _(+1 more)_
+- `audit-deps.js` — `classify(tTouches, oTouches)`, `OPEN`, `findMissingDeps(tasks, { open = OPEN, isBlocker = isUnshippedBlocker } = {})`, `HOTSPOTS`, `isUnshippedBlocker(s)`
+- `audit-exports.js` — `TARGETS`, `buildCorpus()`, `classifyExports(targetAbsPath, exportNames, corpus)` _(+1 more)_
+- `audit-ships.js` — `findCommitForTask(taskId)`, `gitDiffStatsForCommit(sha)`, `filesTouchedByCommit(sha)`, `downstreamImpact(sha, files)`, `fetchShipped(days)`, `fetchFullTask(id)`, `fetchLearning(taskId)`
+- `autonomy-gate.js` — `decide({ enabled, routine = '', claimableCount = 0, openIdeasCount = 0, mtdSpendUsd = 0, ceiling …)`, `precheck(routine, deps = {})`, `isEnabled(env = process.env)`, `gatherSignals(routine, deps = {})`, `AUTONOMY_FLAG`, `DEFAULT_CEILING_USD`, `ceilingUsd(env = process.env)`, `autofixAllowed({ enabled = false, graderBypassOn = true, isProtected = true, confidence = 'low', fileCoun…)`
+- `backfill-cost.js` — `findLedger(argPath)`, `parseLedger(filePath)`, `postCost(row, sourceRef)`
+- `backfill-sessions.js` — `entryText(entry)`, `extractTaskIds(entries)`, `inScope(dirName)`, `PROJECT_TOKENS`, `TASK_MARKERS`
+- `backfill-task-rewards.js` — `BACKFILL_REASON`, `backfillKey(taskId)`, `computeTaskReward(taskId, rawCredits, kind)`, `netForBuilder(wouldBeTotal, costPlusAlreadyPaid)`, `planForBuilder(builderId, taskRewards, costPlusAlreadyPaid, alreadyBackfilled = new Set()`, `TOKEN_REWARD_REASON`
+- `backup.js` — `fmtBytes(n)`, `fetchStatus()`, `printStatus(data)`, `trigger()`
+- `box-auth-check.js` — `onBox()`, `decideBoxAuth({ onBox, hasToken, isBoxScoped, meStatus })`, `printReauth({ boxScoped })`, `printSetup()`
+- `box-connect-lib.js` — `RANK_ORDER`, `WORKSPACE`, `binPresent(bin, versionArgs = ['--version'])`, `buildKnownHostsUpsert(existing, hostname, hostKeysRaw)`, `buildRemoteShellCommand({ firstRun = false, workdir = WORKSPACE } = {})`, `buildSshAliasBlock({ hostname, identityFile })`, `CLAUDE_VSCODE_EXTENSION`, `fetchRank()`, `isFirstLogin(hostname)`, `parseEnsure(data)` _(+8 more)_
+- `box.js` — `deprovisionOne(pool, boxes, doApi, box, { actor, login, sleepFn } = {})`, `cmdProvision(pool, boxes, boxOnboard, ref, { apply })`, `markErrorUnlessDestroyed(pool, boxes, builderId, errNote)`, `runDnsHook(hostname, ip, hook = CONFIG.dnsHook)`, `deleteWithRetry(fn, { tries = 3, sleepMs = 2000, sleepFn } = {})`, `runDnsHookBlackhole(hostname, hook = CONFIG.dnsHook)`, `cmdReconcileDrift(pool, boxes, { apply })`
+- `build-bongos.js` — `VERSION`, `TARGETS`
+- `capture.js` — `resolveDefaultVersion()`
+- `cf-tunnel.js` — `class CfTunnelApi`, `terminalHostname(login, zone)`, `CfApiError`, `previewHostname(login, zone)`, `CF_API_BASE`, `CACHE_BYPASS_RULE_DESC`, `tunnelName(login)`, `CACHE_BYPASS_EXPRESSION`, `CFARGO_SUFFIX`, `GAME_SERVICE` _(+1 more)_
+- `ci-grade.js` — `git(args)`
+- `claim-recall.js` — `printClaimRecall(task, { excludeKeys = [] } = {})`, `RECALL_LIMIT`, `claimRecallQuery(task)`, `formatRecallSources(results, { limit = RECALL_LIMIT, excludeKeys = [], currentTaskId = null } = {})`, `rowKeys(row)`
+- `claim.js` — `printRelevantLearnings(task)`, `printDisciplineMode(task)`, `captureHeadSha()`, `warnIfToolingStale()`, `printClaimCard(task, widgetsEnabled = true)`
+- `classify-discipline.js` — `pad(s, n)`, `emoji(d)`
+- `claude-materialize.js` — `bongosify(text, verbs = VERBS)`, `materializeClaude({ coreRoot, instanceDir, dryRun = false, overwrite = true, log = ()`, `copyTreeTransformed(srcDir, destDir, { dryRun, onFile, overwrite = true } = {})`, `GDS_INVOCATION_RE`, `scriptToVerb(verbs = VERBS)`, `transformSettings(srcPath)`
+- `cli-lib.js` — `cliClient(opts = {})`, `arg(name, args = process.argv.slice(2)`, `requireSession()`, `API_BASE`, `hasFlag(name, args = process.argv.slice(2)`, `SESSION_PATH`, `apiCall(method, urlPath, body = null, opts = {})`, `loadSession()`, `fmtUsd(n)`, `fmtMinutes(m)` _(+13 more)_
+- `code.js` — `repoRoot()`, `runCode(args, { inherit = true } = {})`, `runLocal({ log })`
+- `codemod-rename-src-gds.js` — `segReplace(s)`, `isSrcTopLevel(rel)`, `gitMv()`, `isBinary(buf)`
+- `conductor-dispatch.js` — `autoDispatch(deps = {})`, `bestMatchingClaim(claims, changedFiles)`, `pickSpecialists(changedFiles)`, `selectAutonomousDispatch(gate, claimable)`
+- `context-pack.js` — `contextPack({ activeClaims = [], currentTaskId = null } = {})`, `formatContextPack(pack)`, `buildContextPack({)`, `formatContextPackCompact(pack)`, `apiContract()`, `formatClaims(claims)`, `formatOs(os)`, `normalizeClaims(activeClaims, currentTaskId)`, `osFacts({ platform, runWhich })`, `resolveWorktreeRoot({ runGit, cwd })`
+- `design-sync.js` — `arg(flag, args)`, `collectFiles(dir, root)`
+- `diagnose-achievements.js` — `backfill()`
+- `diagram-facts.js` — `repoSlug(repo)`, `gatherFacts({ repo })`, `defaultRank(migs)`, `readMigrations(repo)`, `CONCEPTUAL_TASK_IDS`, `conceptualFacts({ repo, migs })`, `DEV_BOX_TASK_IDS`, `liveVersions()`, `rankEnum(migs)`, `readGdsSource(repo)` _(+5 more)_
+- `do-api.js` — `class DoApi`, `DoApiError`, `DO_API_BASE`
+- `docs-entropy.js` — `parseFile(absPath)`, `collectMarkdownFiles()`, `scanStaleLinks(relFiles)`, `scanDuplicateProse(relFiles)`, `toSlug(heading)`
+- `doctor.js` — `section(title)`, `gitOut(cmd, opts = {})`, `checkSession()`, `checkToolchain()`, `checkGitPlumbing()`, `checkRepoState()`, `checkEnvironment()`, `checkDeployTooling()`
+- `feedback-latest.js` — `parseArgs(argv)`
+- `fetch-sound-prefs.js` — `writeAtomic(targetPath, contents)`
+- `figma-design-sync.js` — `arg(flag, args)`, `collectFiles(dir, root)`
+- `fitness.js` — `KERNEL_FILES`, `discoveredModuleKeys(modulesDir)`, `scanScopeMapSource(src)`, `checkCoreHostBoundary()`, `checkScopeMapImportsProtected()`, `moduleImportViolation(fromAbsFile, spec)`, `moduleNamespace(key)`, `moduleOwnerOf(absFile)`, `checkClaudeMdBudget(opts = {})`, `checkCoreCarriesNoModuleCode()` _(+20 more)_
+- `gate-review.js` — `classifyChanges({ files, blobAt, diffBytes = 0 } = {})`, `matchesHardFloor(f)`, `HARD_FLOOR_GLOBS`, `isCanonicalPath(p)`, `resolveAction({ verdict, trusted, ownerApproved })`, `certifyAllowlistNarrowing(base, head)`, `certifyRunUnitTestsNarrowing(base, head)`
+- `gating.js` — `repoSlug()`, `getProtection(repo)`, `toPutBody(p)`, `putProtection(repo, putBody)`, `deleteProtection(repo)`, `workflowState(repo, wf)`, `setWorkflow(repo, wf, enable)`, `readSnapshot()`, `writeSnapshot(obj)`, `summarize(putBody)` _(+3 more)_
+- `gen-api-client.js` — `build()`, `buildModel(spec)`, `camel(s)`, `groupByTag(ops)`, `renderClientJs(spec, ops)`, `renderTypes(spec, ops)`, `pascal(s)`
+- `gen-api-docs.js` — `build()`, `pathParams(route)`, `resolveScalar(expr, constants = {})`, `captureBalanced(str, from)`, `splitTopLevel(inner)`, `extractModel()`, `extractResponse(lines, i)`, `pascalCase(s)`, `requestSchemaFor(r)`, `resolveArray(expr, constants = {})` _(+18 more)_
+- `gen-atlas.js` — `buildContextView()`, `buildModuleView()`
+- `gen-diagrams.js` — `brand()`, `cap(s)`, `lifecycleMmd(f)`, `rankLadderMmd(f)`, `versioningMmd(f)`, `drachmaeKarmaMmd(f)`, `architectureMmd(f)`, `rebuildAssertions(prev, f)`
+- `gen-file-map.js` — `end(id)`, `buildModel()`, `begin(id)`, `SECTIONS`, `renderSection(model)`, `computeWrites()`, `injectSection(existing, model)`, `buildSection(section, notes)`
+- `gen-repo-map.js` — `BEGIN`, `END`, `buildModel()`, `NESTED_DIRS`, `injectBlock(existing, block)`, `renderNestedBlock(model, dir)`, `renderRepoMap(model)`
+- `gen-session-index.js` — `BEGIN`, `END`, `computeWrites()`, `collectEntries(dir = LOGS_DIR)`, `injectSnippet(existing, snippet)`, `renderIndex(entries)`, `SESSION_FILE_RE`, `cleanTitle(rawHeading)`, `parseEntry(filename, content)`, `renderSnippet(entries, count = SNIPPET_COUNT)` _(+1 more)_
+- `git-merge-regen.js` — `REGENERABLE`, `regenerateResolved(relpath, { base = '', ours = '', theirs = '' } = {})`, `resolveInWorktree(relpath)`, `hasMarkers(s)`, `threeWayMerge(base, ours, theirs)`, `MARKER_RE`
+- `grade-smoke.js` — `summarize(result, label)`
+- `http-api-client.js` — `class JsonHttpApi`, `makeApiError(name, code)`
+- `init.js` — `CORE_PKG`, `slugify(s, fallback = 'goal')`, `interview({ adopt = false } = {})`, `HOSTING_SHAPES`, `KNOWN_MODULES`, `coreVersionSafe()`, `coreDepRange()`, `provisioningRequest(spec)`, `seedViaApi(spec, { dryRun, log = console.log, api = apiCall } = {})`, `writeConfigs(spec, { dir, force, dryRun, coreDep, log = console.log })` _(+15 more)_
+- `install-git-hooks.js` — `activate()`, `registerMergeDriver(root)`, `MERGE_DRIVER_NAME`, `configuredHooksDir()`
+- `key-card.js` — `wrap(text, width)`, `esc(s)`, `safeBrand()`, `emitKeyCard(model, { log = console.log, widgetsEnabled = true } = {})`, `buildKeyCardModel(input = {})`, `renderKeyCardHtml(model)`, `renderMonospaceKeyCard(model)`
+- `key-status.js` — `KEYS`, `KEY_LIKE_RE`, `refuseIfKeyPasted(argv)`
+- `land-watch.js` — `watch({ nowMs = Date.now()`, `PENDING_DIR`, `readBreadcrumbs()`, `classifyLand(task, ageMs, { staleMs = DEFAULT_STALE_MS } = {})`, `DEFAULT_STALE_MS`, `writeBreadcrumb(taskId, data = {})`, `buildShippedEnvelope(crumb, task)`, `removeBreadcrumb(fileOrId)`
+- `learning-capture.js` — `csv(v)`, `readStdin()`, `autoDetectFiles()`
+- `linkify-refs.js` — `RESOLVER_BASE`, `linkifyText(text, ids, stats)`, `discoverDocs()`, `classifyKind(left, carried, prevKind)`, `linkifySegment(segment, ids, leftContext, stats)`, `RESOLVER_BASE_BLOCKER`, `RESOLVER_BASE_IDEA`, `upgradeLineCodeSpans(line, ids, stats)`, `normalizeIdSets(ids)`, `unlinkEntitySegment(segment, leftContext, stats)`
+- `local-preview-lib.js` — `start(deps = {})`, `REPO_ROOT`, `stop(deps = {})`, `restart(deps = {})`, `health(deps = {})`, `healthUrl(deps = {})`, `HOST`, `onBox(deps = {})`, `BOX_ENV_PATH`, `localUrl(deps = {})` _(+11 more)_
+- `local-preview.js` — `pollHealthy(ms = 20_000)`, `warnIfOnBox()`
+- `login.js` — `runDeviceFlow(base, { log })`, `normalizeInstanceBase(raw)`, `pollDecision(body)`
+- `main-audit.js` — `analyzeCommits(commits, rankByIdentity, { strict = false } = {})`, `parseCommits(range)`, `resolveRank(c, rankByIdentity)`
+- `memory-map.js` — `entries(text)`, `estTokens(bytes)`, `measure(text)`, `applyCompaction(mapPath, expectedText, newText, deps = {})`, `keepAlways(meta)`, `metaOf(file, memoryDir, deps = {})`, `parseLines(text)`, `planCompaction(text, opts = {})`, `WARN_BYTES`, `isRule(type)` _(+4 more)_
+- `merge-lock.js` — `mainWorktreeRoot()`
+- `migration-namespace.js` — `CORE_NS`, `INSTANCE_NS`, `filenameViolation(source, basename, { moduleKey } = {})`, `migrationNumberOf(basename)`, `stemCollisions(files)`, `nextInNamespace(basenames)`, `parseMigrationName(basename)`, `LEGACY_BARE_CORE_MAX`, `LEGACY_BARE_MODULES`, `sqlNamespace(moduleKey)` _(+2 more)_
+- `mirror-lineage-check.js` — `MIGRATION_BASENAME_RE`, `migrationNumbersFromPaths(paths)`, `parseEnumChecks(sql)`, `proveLineage({ publishableFiles, privateMigrationNumbers, ctx })`, `buildRedactionContext()`, `enumDrift(files)`, `numberingDivergence(privateSet, mirrorSet)`, `runSimulation()`
+- `mirror-redact.js` — `findLeaks(text, sensitiveLiterals)`, `buildRedactionRules(branding = {}, extra = {})`, `collectSensitiveLiterals(branding = {}, extra = {})`, `findSecretLeak(text, extraSecrets = [])`, `REDACTED_IP`, `escapeRegExp(s)`, `redactText(text, rules)`, `NEUTRAL_TOKEN`, `deriveInstanceLiterals(branding = {}, extra = {})`, `firstPublicIP(text)` _(+7 more)_
+- `module.js` — `coreVersion()`, `MODULES_DIR`, `camel(key)`, `printHelp(out = console.log)`, `cmdUpgrade(_args, { log = console.log, errlog = console.error, gather = gatherUpgrade } = {})`, `evaluateUpgrade({ rows = [], errors = [], core } = {})`, `gatherUpgrade({ modulesDir = MODULES_DIR, core = coreVersion()`, `buildManifest(key, { core = coreVersion()`, `checkModulePublishability(key, { modulesDir = MODULES_DIR } = {})`, `claudeMdTemplate(key, manifest)` _(+8 more)_
+- `newcomer-floor.js` — `VALID_DISCIPLINES`, `computeTemplateDeficits(supply, templatesByDisc, floorDefaults, { only = null } = {})`, `templateFloor(template, discipline, floorDefaults)`, `buildProposalFromTemplate(template, seq, { discipline } = {})`, `HARD_MAX_MINUTES`, `parseSeq(ref, discipline, templateId)`, `SOURCE_TAG`, `loadTemplates(templatesPath)`, `nextSeq(existingRefs, discipline, templateId)`, `parseRef(ref)` _(+3 more)_
+- `newcomer-floor.test.js` — `test(name, fn)`, `deficitFor(rows, templateId)`
+- `next-number.js` — `padMig(n)`, `nextFree(numberSet, start = 1)`, `padAdr(n)`, `nextNumbers({ runGit = defaultRunGit, readDir = defaultReadDir } = {})`, `computeNextNumbers({ committedPaths = [], localPaths = [], startAdr = 1, startMigration = 1 } = {})`, `gitTreePaths(ref, dirs, runGit)`, `parseNumbers(basenames, re)`
+- `oauth-secret.js` — `webEnvPath(slug, { etcBase = ETC_BASE } = {})`, `provisionedEnvPrefix()`, `validateClientId(id)`, `validateClientSecret(secret)`, `CLIENT_ID_MIN_LEN`, `parseHealthzAuth(stdout)`, `SECRET_MIN_LEN`, `fillOAuthEnv(body, { prefix, clientId, clientSecret })`, `portFromEnv(body)`
+- `onboard.js` — `oauthAppInstructions(domain)`, `buildInitSpec(a = {})`, `healthzUrl(domain)`, `onboardPlan(mode = 'greenfield')`
+- `onboarding-analyze.js` — `acquireLock()`, `releaseLock()`, `analyzeOne(name, entry)`
+- `onboarding-config.js` — `encodeProjectPath(absPath)`, `ensureDir(dir)`, `SPOOL_DIR`, `windowDays()`, `CONFIG_DIR`, `CONSENT_PATH`, `listTranscripts(dir)`, `readConsent()`, `MANIFEST_PATH`, `needsSpool(manifest, file)` _(+7 more)_
+- `package-core.js` — `coreVersion()`, `octal(n, width)`, `TAR_ROOT`, `normalizeMode(mode)`, `ARTIFACT_NAME`, `MANIFEST_SCHEMA`, `processCoreFile({ pathRel, raw, rules, sensitiveLiterals, envSecrets })`, `sha256hex(buf)`, `buildPackageJson({ version, sourceDeps, sourceOverrides })`, `ustarHeader({ name, prefix = '', mode, size, typeflag })` _(+14 more)_
+- `provision.js` — `CONFIG`, `standaloneRoot(inst, { base = CONFIG.standaloneBase } = {})`, `MAX_INTENT_ATTEMPTS`, `checkDnsTokenScope(domain, { token = <redacted>, zoneOverride = process.env.CLOUDFLARE_…)`, `webEnvPath(inst, { etcBase = CONFIG.etcBase } = {})`, `cmdRunIntents(deps)`, `cmdStatus(deps)`, `coreVersionSafe()`, `dnsUpsertEnv(inst, { publicIp, zone, proxied = false } = {})`, `provisionInstance(inst, deps)` _(+26 more)_
+- `publish-manifest.js` — `isPublishable(relPath)`, `normalize(p)`, `matchesDeny(relPath)`, `PUBLISH_ALLOWLIST`, `PUBLISH_DENYLIST`, `PROTECTED_TOPOLOGY_EXCLUDE`, `INSTANCE_EXCLUDE`, `matchesAllow(relPath)`, `CONTENT_EXCLUDE`, `SENSITIVE_DOC_EXCLUDE` _(+1 more)_
+- `pulse.js` — `loadDeps()`, `parseThresholdHours(args)`, `postDiscordPing(text)`, `releaseStale({ thresholdHours, dryRun })`
+- `push-main.js` — `pushMain(extra = [])`
+- `read-session-export.js` — `render(data, opts)`, `reduce(records)`, `loadExport(zipPath)`, `openZip(filePath)`, `readEntry(fd, entry)`
+- `reauth.js` — `openInBrowser(url)`, `printGuidance({ opened })`
+- `recall.js` — `parseArgs(argv)`, `truncate(s, n)`
+- `render-ideas.js` — `fmtTimestamp(iso)`, `daysAgo(iso)`, `renderIdea(idea)`, `renderSection(heading, ideas, emptyMsg)`, `fetchAllIdeas()`, `partition(ideas)`, `render(ideas)`
+- `repo-metrics.js` — `gatherFileSizes()`, `summarizeSizes(sizes)`, `scanDeadCode()`, `scanBranchHygiene()`, `countConfirmedUnshipped(pool)`, `upsertSnapshot(pool, snap)`
+- `run-routine.js` — `VALID_MODES`, `parseRoutineFrontmatter(skillMd)`, `VALID_SINKS`, `tokenize(cmd)`
+- `run-unit-tests.js` — `discoverModuleTests({ modulesDir = MODULES_DIR, isEnabled = isModuleEnabled } = {})`
+- `sandbox-stage.js` — `stage({ taskId } = {}, deps = {})`, `BOX_ENV_PATH`, `BOX_SERVED_ROOT`, `resolvePreviewContext(deps = {})`, `computeTreeStamp(deps = {})`, `PREVIEWABLE_PATHSPECS`, `markerPath(deps = {})`, `previewUrl(deps = {})`, `runShipGate({ taskId, files, skipStage, tty, approved }, deps = {})`, `verifyServedFresh(deps = {})` _(+11 more)_
+- `search-ingest-db.js` — `buildRows({ sourceRef, title, body, minRank = 'xenos', ownerBuilderId = null, scrub = false })`, `requirePool()`, `SOURCES`, `recentCommitRows(limit = 80)`
+- `search-ingest-md.js` — `SENSITIVE_DOC_GLOBS`, `requirePool()`, `collectMarkdown(dir, root, out = [])`, `minRankForDoc(rel)`, `chunkFile(abs)`, `ingestFile(client, rows, sourceRef)`
+- `<redacted>.js` — `post(path, body)`
+- `<redacted>.js` — `post(path, body)`
+- `seed-module-upstreaming.js` — `findOrCreateGoal()`
+- `seed-provisioning-tasks.js` — `post(path, body)`
+- `seed-v2-world-tasks.js` — `withRetry(fn)`
+- `session-cost.js` — `addTiers(acc, t)`, `emptyTiers()`, `newestTranscriptFor(cwd)`, `priceTranscript(transcriptPath)`, `roundTiers(t)`, `listJsonlRecursive(dir)`, `looksLikeGraderTranscript(file)`, `priceSubagents(sessionDir)`, `addComponents(acc, components)`
+- `session-digest.js` — `parseHookInput(stdinRaw, opts = {})`
+- `session-eval.js` — `computeOverhead(detail)`, `evaluateSession(record)`, `detectFootguns(detail, overhead = {}, opts = {})`, `FINDING_TEMPLATES`, `findingsByBuilder(evaluated)`, `verdictFor(overheadRatio)`, `classifyTurn(turn, opts = {})`, `interpretCorpusSearch(count, opts = {})`, `summarizeSystemicFindings(evaluated, opts = {})`
+- `session.js` — `readArgv(argv)`, `builderLocalHour(timezone)`, `isOvernightHour(hour)`, `recentShipsAllOvernightSafe(me)`, `suggestDefaults(me)`, `ask(rl, q, fallback)`, `interactive(defaults)`, `callOptimizer({ timeBudgetMin, mode, parallel })`, `fitsMode(task, mode)`, `disjointTouches(a, b)` _(+5 more)_
+- `setup.js` — `dryRunStep(msg)`, `promptGeminiKey()`, `readLocalAnthropicAccount()`, `promptAnthropicLink()`, `promptDisciplines()`, `promptOnboardingConsent()`
+- `shell.js` — `repoRoot()`, `runLocal({ remoteCmd, log })`
+- `ship.js` — `buildSessionDigest(entries, opts = {})`, `computeChangedFiles(baseline)`, `sanitizeGitHubRefs(text)`, `computeGraderBaseline(claim)`, `recordUploadSkip(taskId, { code, reason }, opts = {})`, `runSubagentGrader({ task, valueSummary, baseline, changedFiles: precomputedChanged })`, `buildMergeArgv(branch, valueSummary)`, `gradeAndRecord({ taskId, task, summary, baseline, committedFiles })`, `snippetOf(text, extraSecrets, max = 160)`, `buildGradePayload(gradeResult, committedFiles = null)` _(+9 more)_
+- `smoke-gds.js` — `isLocalTarget(hostname)`, `probeListener(host, port, timeoutMs = 1500)`
+- `start.js` — `progressBar(percent, width = 10)`, `formatVersionsRow(progress)`, `formatCostRow(cost)`, `formatRecentRow({ recentShipped, inboxCount, blockerCount })`, `statusParts({ progress, recentShipped, inboxCount, blockerCount })`, `quietStatusLine(header)`, `estimateShort(t)`, `clip(s, n)`, `cell(s)`, `disciplineLabel(t)` _(+10 more)_
+- `status.js` — `parseArgs(argv)`, `renderStatusWidget(data, criterion)`, `renderStatusMarkdown(data, criterion)`
+- `triage.js` — `formatDevelopment(block)`, `loadDevelopment(path)`, `parseDevelopment(text)`, `resolveDevelopmentPath(argv = process.argv, env = process.env)`
+- `upgrade.js` — `parseArgs(argv)`, `CORE_PKG`, `ARTIFACT`, `npmInstall(instanceDir, run = spawnSync)`, `readInstalledCoreVersion(instanceDir, fsImpl = fs)`, `regenerateApiArtifacts({ instanceDir, coreRoot }, run = spawnSync, fsImpl = fs)`, `vendorTarball({ instanceDir, fromTgz, targetVersion }, fsImpl = fs)`, `versionFromTgzPath(p)`, `gitTreeClean(instanceDir, run = spawnSync)`, `pollHealth(healthUrl, deps = {})` _(+8 more)_
+- `validate-design.js` — `readJson(filePath, label)`, `deepMerge(base, override)`, `isUri(s)`, `dirExists(p)`, `fileExists(p)`, `listDirs(p)`
+- `version-close.js` — `parseArgs(argv)`, `buildCommitMessage({ versionId, nextVersionId, shippedCount, carryCount })`, `buildManualSql({ versionId, versionName, nextVersionId, nextScopeDocPath, carryOverTasks, nextVersionExis…)`, `buildNextVersionStub({ nextVersionId, prevVersionId, carryOverTasks })`, `buildShippedArchive({ versionId, versionName, scopeDocPath, shippedTasks, originalScopeBody, shippedAt })`, `deriveNextScopePath(currentPath, nextVersionId)`, `deriveNextVersionId(currentId)`, `deriveShippedPath(currentPath, versionId)`
+<!-- END GENERATED REPO-MAP -->
+
+**See also.** `.claude/skills/builder-*` skill docs · [ADR 0061](../../docs/adr/<redacted>.md) · [docs/recipes/ops-gotchas.md](../../docs/recipes/ops-gotchas.md) · [src/bongos/](../../src/bongos/) (the server side these call).

package/scripts/gds/abandon.js

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+// Abandon a task — the terminal "retire this task" transition (task 987).
+//
+// Usage:
+//   node scripts/gds/abandon.js <task-id> [--reason "..."]
+//
+// Sets the task's status to 'abandoned' (the missing first-class lifecycle
+// transition — the GDS already had promote/ship/confirm/resolve). Use this to
+// retire a task that is no longer relevant — a stale chore, or a duplicate of
+// work another session already shipped — instead of leaving it in 'ready' as
+// claimable noise.
+//
+// Archon-only (the route is requireRank('archon')). Refuses on a shipped task
+// (immutable history) and on a task with an active claim (release it first);
+// idempotent on an already-abandoned task. The abandon + reason are recorded in
+// audit_log by the server's writing middleware, so the ledger stays complete.
+
+const { cliClient, requireSession, arg } = require('./cli-lib');
+
+
+(async () => {
+  await requireSession();
+  const args = process.argv.slice(2);
+  const taskId = Number(args[0]);
+  if (!Number.isFinite(taskId)) {
+    console.error('usage: node scripts/gds/abandon.js <task-id> [--reason "..."]');
+    process.exit(2);
+  }
+  const reason = arg('--reason', args) || '';
+
+  const api = await cliClient();
+  const r = await api.tasks.postTasksIdAbandon({ id: taskId, body: { reason } });
+  if (!r.ok) {
+    if (r.data?.error === 'cannot_abandon_shipped') {
+      console.error(`Task #${taskId} is shipped — shipped work is immutable history and cannot be abandoned.`);
+    } else if (r.data?.error === 'task_has_active_claim') {
+      console.error(`Task #${taskId} has an active claim. Release it first:`);
+      console.error(`  node scripts/gds/release.js ${taskId}`);
+    } else if (r.data?.error === 'task_not_found') {
+      console.error(`Task #${taskId} not found.`);
+    } else if (r.status === 403) {
+      console.error('Abandoning a task is Archon-only.');
+    } else {
+      console.error(`abandon failed (${r.status}):`, r.data);
+    }
+    process.exit(1);
+  }
+
+  if (r.data.alreadyAbandoned) {
+    console.log(`Task #${r.data.taskId} (${r.data.taskTitle}) was already abandoned — no change.`);
+  } else {
+    console.log(`Abandoned task #${r.data.taskId}: ${r.data.taskTitle}`);
+    console.log(`Status: ${r.data.previousStatus} -> abandoned.`);
+  }
+})().catch((err) => {
+  console.error('fatal:', err);
+  process.exit(1);
+});

package/scripts/gds/adopt-detect.js

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+'use strict';
+// scripts/gds/adopt-detect.js — inspect an EXISTING repo tree so `bongos init --adopt`
+// fits what is already there instead of assuming the reference layout (ADR 0121
+// §Decision 4 / task 2043).
+//
+// WHY. Greenfield init writes into a blank slate. `--adopt` LAYERS onto a real repo,
+// so before it writes anything it must know the shape of that repo: language/runtime,
+// package manager, test + CI setup, source layout, and whether it already carries a
+// migrations dir / .claude/ / config/. This detection is the INPUT the later adopt
+// legs consume: real-state capture (task 2044) uses it to seed the right modules + the
+// interview, and the conflict pre-flight (task 2045) reads hasMigrations / ci / layout
+// to compute the blast radius (migration-namespace + CI-workflow collisions).
+//
+// It only READS (existsSync/readFileSync/readdirSync) — no writes, no network — so it
+// is safe to run first, and returns a plain data object (no I/O side effects) for the
+// caller to print and for 2044/2045 to consume. Every probe degrades to a negative
+// signal on a missing/unreadable file; detectStack never throws on repo contents.
+
+const nodeFs = require('node:fs');
+const nodePath = require('node:path');
+
+// A repo's package manager, inferred from its lockfile (the authoritative signal),
+// falling back to npm when a package.json exists with no lockfile at all.
+function detectPackageManager(exists, hasPkg) {
+  if (exists('pnpm-lock.yaml')) return 'pnpm';
+  if (exists('yarn.lock')) return 'yarn';
+  if (exists('bun.lockb')) return 'bun';
+  if (exists('package-lock.json')) return 'npm';
+  return hasPkg ? 'npm' : null;
+}
+
+// Detect the stack + layout of the repo rooted at `dir`. Pure but for the injected
+// (or default node) fs reads. Returns a structured summary.
+function detectStack({ dir, fs = nodeFs, path = nodePath } = {}) {
+  if (!dir) throw new Error('detectStack: dir is required');
+  const at = (rel) => path.join(dir, rel);
+  const exists = (rel) => { try { return fs.existsSync(at(rel)); } catch { return false; } };
+  const readJson = (rel) => { try { return JSON.parse(fs.readFileSync(at(rel), 'utf8')); } catch { return null; } };
+  const listDir = (rel = '.') => { try { return fs.readdirSync(at(rel)); } catch { return []; } };
+  const isDir = (rel) => { try { return fs.statSync(at(rel)).isDirectory(); } catch { return false; } };
+
+  const pkg = readJson('package.json');
+  const deps = { ...((pkg && pkg.dependencies) || {}), ...((pkg && pkg.devDependencies) || {}) };
+
+  // languages / runtime — the marker files each ecosystem leaves at the root.
+  const languages = [];
+  if (pkg || exists('tsconfig.json') || exists('jsconfig.json')) languages.push(exists('tsconfig.json') ? 'typescript' : 'javascript');
+  if (exists('requirements.txt') || exists('pyproject.toml') || exists('setup.py') || exists('Pipfile')) languages.push('python');
+  if (exists('go.mod')) languages.push('go');
+  if (exists('Cargo.toml')) languages.push('rust');
+  if (exists('Gemfile')) languages.push('ruby');
+  if (exists('pom.xml') || exists('build.gradle') || exists('build.gradle.kts')) languages.push('java');
+  if (exists('composer.json')) languages.push('php');
+  const runtime = pkg ? 'node' : exists('go.mod') ? 'go' : languages[0] || 'unknown';
+
+  // test frameworks — from deps, then config-file / marker probes for non-node stacks.
+  const testFrameworks = [];
+  for (const fw of ['jest', 'vitest', 'mocha', 'ava', 'jasmine', 'tap']) {
+    if (deps[fw]) testFrameworks.push(fw);
+  }
+  if (exists('pytest.ini') || exists('tox.ini') || deps.pytest) testFrameworks.push('pytest');
+  const hasTestScript = !!(pkg && pkg.scripts && pkg.scripts.test);
+
+  // CI systems — the workflow file(s) each CI reads.
+  const ci = [];
+  if (isDir('.github/workflows')) {
+    const workflows = listDir('.github/workflows').filter((f) => /\.ya?ml$/.test(f)).sort();
+    ci.push({ system: 'github-actions', workflows });
+  }
+  if (exists('.gitlab-ci.yml')) ci.push({ system: 'gitlab-ci' });
+  if (exists('.circleci/config.yml')) ci.push({ system: 'circleci' });
+  if (exists('Jenkinsfile')) ci.push({ system: 'jenkins' });
+  if (exists('azure-pipelines.yml')) ci.push({ system: 'azure-pipelines' });
+
+  // directory layout — top-level dirs minus dotdirs + node_modules; then the common
+  // source roots among them (so a later leg can fit the fitness boundary to reality).
+  const topLevelDirs = listDir('.')
+    .filter((n) => n !== 'node_modules' && !n.startsWith('.') && isDir(n))
+    .sort();
+  const sourceDirs = ['src', 'lib', 'app', 'source', 'packages', 'pkg', 'internal'].filter((d) => topLevelDirs.includes(d));
+
+  // pre-existing surfaces the pre-flight (2045) + layering (2042) care about.
+  const migrationsDirs = ['migrations', 'db/migrations', 'prisma/migrations', 'sql/migrations'].filter((d) => isDir(d));
+  const rootEntries = listDir('.').filter((n) => !n.startsWith('.'));
+
+  return {
+    runtime,
+    languages,
+    packageManager: detectPackageManager(exists, !!pkg),
+    hasPackageJson: !!pkg,
+    packageName: (pkg && pkg.name) || null,
+    testFrameworks,
+    hasTestScript,
+    ci,
+    topLevelDirs,
+    sourceDirs,
+    migrationsDirs,
+    hasMigrations: migrationsDirs.length > 0,
+    hasClaudeDir: exists('.claude'),
+    hasConfigDir: exists('config'),
+    isEmptyRepo: rootEntries.length === 0,
+  };
+}
+
+// Human-readable lines for the adopt report — one bullet each. Kept separate from
+// detectStack so the data + its display are independently testable.
+function formatStackSummary(s) {
+  const lines = [];
+  lines.push(`runtime: ${s.runtime}${s.languages.length ? ` (${s.languages.join(', ')})` : ''}`);
+  lines.push(`package manager: ${s.packageManager || 'none detected'}`);
+  lines.push(`tests: ${s.testFrameworks.length ? s.testFrameworks.join(', ') : s.hasTestScript ? 'test script present' : 'none detected'}`);
+  lines.push(`CI: ${s.ci.length ? s.ci.map((c) => c.system).join(', ') : 'none detected'}`);
+  lines.push(`source dirs: ${s.sourceDirs.length ? s.sourceDirs.join(', ') : s.topLevelDirs.length ? s.topLevelDirs.slice(0, 6).join(', ') : 'none'}`);
+  if (s.hasMigrations) lines.push(`migrations: ${s.migrationsDirs.join(', ')} (the pre-flight step will check for namespace collisions)`);
+  const carries = [];
+  if (s.hasClaudeDir) carries.push('.claude/');
+  if (s.hasConfigDir) carries.push('config/');
+  if (carries.length) lines.push(`already carries: ${carries.join(', ')} (layering leaves pre-existing files untouched)`);
+  return lines;
+}
+
+module.exports = { detectStack, detectPackageManager, formatStackSummary };

package/scripts/gds/adopt-import.js

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+'use strict';
+// scripts/gds/adopt-import.js — import an existing repo's backlog into GDS tasks so
+// `bongos init --adopt` starts the ledger TRUTHFUL rather than empty (ADR 0121
+// §Decision 3 / task 2044). Sources, in precedence order:
+//   1. GitHub issues — the repo's OPEN issues (via a GitHub token the env supplies)
+//   2. a local backlog file — TODO / ROADMAP / BACKLOG (.md) at the repo root
+//   3. none — the owner captures tasks later (the real version + goal + kickoff still seed)
+//
+// Pure parsers + an injectable fetch keep it testable with no live network. Import is
+// best-effort: a failed/absent GitHub fetch falls through to the local file, and no
+// backlog at all is fine (the ledger still starts with the repo's REAL version/goal).
+
+const nodeFs = require('node:fs');
+const nodePath = require('node:path');
+
+const BACKLOG_FILENAMES = ['TODO.md', 'ROADMAP.md', 'BACKLOG.md', 'TODO', 'ROADMAP', 'BACKLOG'];
+const DEFAULT_MAX = 50; // don't flood a fresh ledger; cap the import + report the cap
+
+// PURE — parse a markdown backlog file into task candidates. Recognizes GitHub-style
+// checklist items (- [ ] / - [x]), plain bullet/numbered list items, and uses the
+// nearest preceding heading as light body context. Checked-off items ([x]) are DONE
+// and skipped (a backlog import wants open work). Returns [{ title, body }].
+function parseBacklogFile(text) {
+  const out = [];
+  let heading = '';
+  for (const raw of String(text == null ? '' : text).split(/\r?\n/)) {
+    const line = raw.trimEnd();
+    const h = line.match(/^#{1,6}\s+(.*)$/);
+    if (h) { heading = h[1].trim(); continue; }
+    // - [ ] item | - [x] done | - item | * item | 1. item
+    const m = line.match(/^\s*(?:[-*]|\d+\.)\s+(?:\[([ xX])\]\s+)?(.*\S)\s*$/);
+    if (!m) continue;
+    if (m[1] && m[1].toLowerCase() === 'x') continue; // checked off → done → skip
+    const title = m[2].trim();
+    if (!title) continue;
+    out.push({ title: title.slice(0, 200), body: heading ? `Imported from the repo backlog (under "${heading}").` : 'Imported from the repo backlog.' });
+  }
+  return out;
+}
+
+// Find the first recognized backlog file at the repo root. Returns its basename or null.
+function findBacklogFile(dir, fs = nodeFs, path = nodePath) {
+  for (const name of BACKLOG_FILENAMES) {
+    try {
+      const abs = path.join(dir, name);
+      if (fs.existsSync(abs) && fs.statSync(abs).isFile()) return name;
+    } catch { /* unreadable → skip */ }
+  }
+  return null;
+}
+
+// PURE — GitHub issues API array → task candidates. Filters out pull requests (the
+// issues endpoint returns PRs too, marked by a pull_request key) and non-open issues.
+function parseGitHubIssues(issues) {
+  if (!Array.isArray(issues)) return [];
+  return issues
+    .filter((i) => i && !i.pull_request && (i.state === undefined || i.state === 'open') && i.title)
+    .map((i) => ({ title: String(i.title).slice(0, 200), body: `Imported from ${i.html_url || `issue #${i.number}`}.`, number: i.number }));
+}
+
+// Fetch a repo's OPEN issues via the GitHub REST API. Injectable fetchImpl for tests.
+// Best-effort: any network/auth failure → [] + an onWarn note (never blocks the adopt).
+async function fetchGitHubIssues({ owner, repo, token, fetchImpl = globalThis.fetch, max = DEFAULT_MAX, onWarn = () => {} }) {
+  if (!owner || !repo || !token || typeof fetchImpl !== 'function') return [];
+  try {
+    const url = `https://api.github.com/repos/${owner}/${repo}/issues?state=open&per_page=${Math.min(max, 100)}`;
+    const res = await fetchImpl(url, { headers: { Authorization: `Bearer ${token}`, Accept: 'application/vnd.github+json', 'User-Agent': 'bongos-init-adopt' } });
+    if (!res || !res.ok) { onWarn(`GitHub issues fetch failed (${res ? res.status : 'no response'}) — falling back to a local backlog file`); return []; }
+    return parseGitHubIssues(await res.json()).slice(0, max);
+  } catch (e) {
+    onWarn(`GitHub issues fetch error (${e.message}) — falling back to a local backlog file`);
+    return [];
+  }
+}
+
+// Resolve the backlog from the best available source. Precedence: an EXPLICIT file the
+// owner named → GitHub issues → an auto-detected local file → none. Returns
+// { source, tasks:[{ title, kind, description }], truncated }.
+async function resolveBacklogTasks({ dir, repo = {}, githubToken, backlogFile, fetchImpl, fs = nodeFs, path = nodePath, max = DEFAULT_MAX, onWarn = () => {} } = {}) {
+  const toTasks = (cands) => cands.slice(0, max).map((t) => ({ title: t.title, kind: 'unclassified', description: t.body || '' }));
+  const readParse = (abs) => { try { return parseBacklogFile(fs.readFileSync(abs, 'utf8')); } catch { return []; } };
+
+  // 0. an explicit backlog file the owner named (path relative to dir, or absolute).
+  if (backlogFile) {
+    const abs = path.isAbsolute(backlogFile) ? backlogFile : path.join(dir, backlogFile);
+    const parsed = readParse(abs);
+    if (parsed.length) return { source: backlogFile, tasks: toTasks(parsed), truncated: parsed.length > max };
+    onWarn(`backlog file "${backlogFile}" was empty or unreadable — trying other sources`);
+  }
+
+  // 1. GitHub issues (only when we have both a token and the repo coordinates)
+  if (githubToken && repo.owner && repo.name) {
+    const gh = await fetchGitHubIssues({ owner: repo.owner, repo: repo.name, token: githubToken, fetchImpl, max, onWarn });
+    if (gh.length) return { source: 'github-issues', tasks: toTasks(gh), truncated: gh.length >= max };
+  }
+
+  // 2. local backlog file
+  const file = findBacklogFile(dir, fs, path);
+  if (file) {
+    let text = '';
+    try { text = fs.readFileSync(path.join(dir, file), 'utf8'); } catch { /* unreadable → empty */ }
+    const parsed = parseBacklogFile(text);
+    if (parsed.length) return { source: file, tasks: toTasks(parsed), truncated: parsed.length > max };
+  }
+
+  // 3. none — the version + goal + kickoff still seed; the owner captures tasks later
+  return { source: 'none', tasks: [], truncated: false };
+}
+
+module.exports = { parseBacklogFile, findBacklogFile, parseGitHubIssues, fetchGitHubIssues, resolveBacklogTasks, BACKLOG_FILENAMES, DEFAULT_MAX };

package/scripts/gds/adopt-preflight.js

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+'use strict';
+// scripts/gds/adopt-preflight.js — the conflict PRE-FLIGHT for `bongos init --adopt`
+// (ADR 0121 §Decision 5 / task 2045). Before adopt writes anything, it reports the
+// blast radius the owner must ACCEPT:
+//   • migration-namespace collisions — a repo migration using core's reserved prefix
+//     (ADR 0108 §5, via migration-namespace.js's canonical filenameViolation).
+//   • core<->host fitness-boundary overlaps — repo dirs that shadow core's reserved
+//     src/bongos or modules/ namespaces the fitness gate scans (ADR 0062 §1).
+//   • protected-path landings — incoming files that fall on the trust-boundary hard
+//     floor (ADR 0043, via gate-review.js's canonical matchesHardFloor).
+//   • CI collisions — the repo's workflows vs core's expected unit/secret-scan/
+//     gate-review checks.
+// READ-ONLY: it computes findings; the accept-gate that decides whether to proceed
+// lives in init.js runAdopt. Pure check functions + a thin fs-reading orchestrator.
+
+const nodeFs = require('node:fs');
+const nodePath = require('node:path');
+const { filenameViolation, INSTANCE_NS } = require('./migration-namespace');
+const { matchesHardFloor } = require('./gate-review');
+
+const SEV = { BLOCK: 'blocking', WARN: 'warning', INFO: 'info' };
+const CORE_EXPECTED_CHECKS = ['unit', 'secret-scan', 'gate-review']; // the merge-gate checks core adds
+
+// The files `bongos init --adopt` writes/materializes — the "incoming" set the
+// protected-path check runs against (representative globs; the .claude/ trees expand).
+const INCOMING_PATHS = [
+  'config/branding.json', 'config/modules.json', 'config/hierarchy.json',
+  'package.json', '.claude/settings.json', '.claude/hooks/', '.claude/skills/',
+];
+
+// PURE — repo migration basenames → findings. A basename destined for the INSTANCE
+// namespace that violates the namespace rule (e.g. it uses core's reserved `core_`
+// prefix) would collide with core's migrations on the stem-keyed ledger. Bare-numbered
+// files are valid instance migrations and safe.
+function checkMigrationNamespace(basenames = []) {
+  const findings = [];
+  if (!basenames.length) return findings;
+  const reserved = basenames.filter((b) => filenameViolation(INSTANCE_NS, b));
+  for (const b of reserved) {
+    findings.push({ category: 'migration-namespace', severity: SEV.BLOCK, message: `migration "${b}" uses a reserved (core_/module) prefix — it would collide with core's migration namespace (ADR 0108 §5). Renumber it as a bare instance migration.` });
+  }
+  const bare = basenames.length - reserved.length;
+  if (bare > 0) findings.push({ category: 'migration-namespace', severity: SEV.INFO, message: `${bare} existing migration(s) adopt as the INSTANCE namespace (bare-numbered); core uses the core_ prefix, so there is no stem collision (ADR 0108 §5).` });
+  return findings;
+}
+
+// PURE — repo layout → fitness-boundary findings (ADR 0062 §1). A repo that already
+// has a top-level modules/ or a src/bongos/ shadows the namespaces core's fitness gate
+// scans, so its own files there may be flagged after adoption.
+function checkFitnessBoundary({ topLevelDirs = [], hasSrcBongos = false } = {}) {
+  const findings = [];
+  if (topLevelDirs.includes('modules')) findings.push({ category: 'fitness-boundary', severity: SEV.WARN, message: 'the repo has a top-level `modules/` dir — core\'s fitness gate scans modules/** for the module-import boundary (ADR 0062 §1); your files there may be flagged.' });
+  if (hasSrcBongos) findings.push({ category: 'fitness-boundary', severity: SEV.WARN, message: 'the repo has `src/bongos/` — it shadows core\'s reserved kernel namespace scanned by the fitness gate (ADR 0062 §1).' });
+  if (!findings.length) findings.push({ category: 'fitness-boundary', severity: SEV.INFO, message: 'no overlap with core\'s reserved src/bongos or modules/ namespaces.' });
+  return findings;
+}
+
+// PURE — incoming paths → protected-path findings (ADR 0043). Which files adopt writes
+// land on the trust-boundary hard floor (via gate-review's canonical matcher)?
+function checkProtectedPaths(incoming = INCOMING_PATHS) {
+  const hits = incoming.filter((p) => matchesHardFloor(p));
+  if (!hits.length) return [{ category: 'protected-paths', severity: SEV.INFO, message: 'no incoming files land on protected paths.' }];
+  return [{ category: 'protected-paths', severity: SEV.WARN, message: `adopt materializes ${hits.length} core-governed file(s) on protected paths (ADR 0043): ${hits.join(', ')}. Additive only — but these are under the trust boundary, so treat them as core-managed.` }];
+}
+
+// PURE — the repo's CI workflows ([{ name, content }]) → CI-collision findings. Flags a
+// workflow that already references a core-reserved check name (unit / secret-scan /
+// gate-review); otherwise notes that core will add those checks alongside existing ones.
+function checkCiCollisions(workflows = []) {
+  if (!workflows.length) return [{ category: 'ci', severity: SEV.INFO, message: 'no existing CI workflows — core\'s unit/secret-scan/gate-review checks will be the only ones.' }];
+  const collisions = new Set();
+  for (const wf of workflows) {
+    for (const check of CORE_EXPECTED_CHECKS) {
+      if (new RegExp(`\\b${check.replace(/[-]/g, '\\-')}\\b`, 'i').test(wf.content || '')) collisions.add(`${wf.name} → ${check}`);
+    }
+  }
+  if (collisions.size) return [{ category: 'ci', severity: SEV.WARN, message: `existing CI workflow(s) reference core-reserved check name(s): ${[...collisions].join(', ')}. Core adds unit/secret-scan/gate-review — reconcile names so the merge gate keys on the right job.` }];
+  return [{ category: 'ci', severity: SEV.INFO, message: `${workflows.length} existing CI workflow(s); core will ADD its own unit/secret-scan/gate-review checks alongside them — confirm no required-check conflict.` }];
+}
+
+// Read the repo (migrations, src/bongos, workflows) and run every check. `stack` is the
+// adopt-detect summary (task 2043); we re-read only what the checks need. Returns
+// { findings, counts:{blocking,warning,info}, hasBlocking }.
+function preflightAdopt({ dir, stack = {}, fs = nodeFs, path = nodePath } = {}) {
+  const listFiles = (rel) => { try { return fs.readdirSync(path.join(dir, rel)).filter((f) => { try { return fs.statSync(path.join(dir, rel, f)).isFile(); } catch { return false; } }); } catch { return []; } };
+  const exists = (rel) => { try { return fs.existsSync(path.join(dir, rel)); } catch { return false; } };
+
+  // migrations across every detected migrations dir
+  const migrationBasenames = (stack.migrationsDirs || []).flatMap((d) => listFiles(d).filter((f) => /\.sql$/i.test(f)));
+
+  // github workflow contents (only when github-actions was detected)
+  const workflows = [];
+  const gh = (stack.ci || []).find((c) => c.system === 'github-actions');
+  if (gh) {
+    for (const wf of gh.workflows || []) {
+      let content = '';
+      try { content = fs.readFileSync(path.join(dir, '.github/workflows', wf), 'utf8'); } catch { content = ''; }
+      workflows.push({ name: wf, content });
+    }
+  }
+
+  const findings = [
+    ...checkMigrationNamespace(migrationBasenames),
+    ...checkFitnessBoundary({ topLevelDirs: stack.topLevelDirs || [], hasSrcBongos: exists('src/bongos') }),
+    ...checkProtectedPaths(INCOMING_PATHS),
+    ...checkCiCollisions(workflows),
+  ];
+  const counts = { blocking: 0, warning: 0, info: 0 };
+  for (const f of findings) counts[f.severity === SEV.BLOCK ? 'blocking' : f.severity === SEV.WARN ? 'warning' : 'info']++;
+  return { findings, counts, hasBlocking: counts.blocking > 0 };
+}
+
+// Human-readable report lines (one per finding, severity-marked), for the owner to
+// read before accepting. Returns an array of strings.
+function formatPreflight(report) {
+  const mark = { [SEV.BLOCK]: '✗ BLOCK', [SEV.WARN]: '⚠ warn', [SEV.INFO]: '· ok' };
+  return report.findings.map((f) => `  ${mark[f.severity] || '·'}  [${f.category}] ${f.message}`);
+}
+
+module.exports = { preflightAdopt, formatPreflight, checkMigrationNamespace, checkFitnessBoundary, checkProtectedPaths, checkCiCollisions, INCOMING_PATHS, CORE_EXPECTED_CHECKS, SEV };