@bongos/core 1.17.0

package/modules/ideas/routes/blockers.js

@@ -0,0 +1,120 @@
+const express = require('express');
+// Carved into modules/ideas/ (BV1.R78 / ADR 0093 §1): auth gates + request
+// validators reach through the published doorway; `blockers` is an intra-module
+// sibling — a module never requires a core internal.
+const api = require('../../../src/module-api');
+const blockers = require('../blockers');
+const { validateOrRespond, LIMITS, parseId } = api;
+
+module.exports = function buildBlockersRouter() {
+  const router = express.Router();
+
+  // List currently-open blockers + the tasks each is blocking.
+  // Public: anyone landing on /builders or status.amazonprimea.com can see
+  // what's stuck on Lars.
+  // rank: public — open blocker list; documented "Public: anyone landing on /builders
+  // or status.amazonprimea.com can see what's stuck on Lars" in the handler comment above.
+  router.get('/blockers', async (req, res) => {
+    try {
+      // R14 (#2001 / ADR 0119): the open-blocker list is public + grows with the
+      // project — cap it via the shared helper (was unbounded). `page` is additive
+      // (readers of .blockers are unchanged); total lets a caller know to page.
+      const { limit, offset } = api.parsePagination(req);
+      const all = await blockers.listOpenBlockers();
+      res.set('Cache-Control', 'public, max-age=60');
+      res.json({ blockers: all.slice(offset, offset + limit), page: api.pageMeta(limit, offset, all.length) });
+    } catch (err) {
+      console.error('[gds] GET /blockers', err);
+      res.fail('list_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // rank: any-builder — single blocker detail read.
+  router.get('/blockers/:id', api.requireBuilder, async (req, res) => {
+    const id = parseId(req, res, { code: 'bad_id' });
+    if (id === null) return;
+    const blocker = await blockers.getBlocker(id);
+    if (!blocker) return res.fail('blocker_not_found', 404);
+    res.json({ blocker });
+  });
+
+  // rank: any-builder — FILE a blocker (contribution, not resolution).
+  router.post('/blockers', api.requireBuilder, async (req, res) => {
+    if (validateOrRespond(req, res, {
+      title: { required: true, type: 'string', maxLength: LIMITS.TITLE, minLength: 1 },
+      body_md: { type: 'string', maxLength: LIMITS.DESCRIPTION },
+      source: { type: 'string', maxLength: LIMITS.SOURCE },
+      source_ref: { type: 'string', maxLength: LIMITS.SOURCE_REF },
+    })) return;
+    const body = req.body || {};
+    try {
+      const blocker = await blockers.createBlocker({
+        title: body.title,
+        bodyMd: body.body_md ?? '',
+        source: body.source ?? 'manual',
+        sourceRef: body.source_ref ?? null,
+      });
+      if (!blocker) {
+        // ON CONFLICT — same (source, source_ref) already captured.
+        return res.status(200).json({ skipped: true, reason: 'duplicate_source_ref' });
+      }
+      res.status(201).json({ blocker });
+    } catch (err) {
+      if (err.code === 'TITLE_REQUIRED') return res.fail('title_required', 400);
+      console.error('[gds] POST /blockers', err);
+      res.fail('create_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // Resolve. Auto-promotes any blocked tasks linked via task_blockers.
+  // Metic+ (#360 / ADR 0018): blocker review is one of the operations C2
+  // assigns to Metic, so this widened from archon-only to metic+archon when the
+  // three-rank model went live. Any builder can still FILE a blocker (POST
+  // /blockers above); a Xenos cannot resolve or link them.
+  // rank: metic+archon — blocker review (auto-promotes linked blocked tasks);
+  // criterion C2 / #360 / ADR 0018.
+  router.post('/blockers/:id/resolve', api.requireBuilder, api.requireRank('metic', 'archon'), async (req, res) => {
+    if (validateOrRespond(req, res, {
+      resolution_note: { type: 'string', maxLength: LIMITS.NOTES },
+    })) return;
+    const id = parseId(req, res, { code: 'bad_id' });
+    if (id === null) return;
+    try {
+      const result = await blockers.resolveBlocker({
+        id,
+        builderId: req.builder.id,
+        resolutionNote: req.body?.resolution_note ?? null,
+      });
+      res.json(result);
+    } catch (err) {
+      if (err.code === 'BLOCKER_NOT_OPEN') {
+        return res.fail('blocker_not_open', 409);
+      }
+      console.error('[gds] POST /blockers/:id/resolve', err);
+      res.fail('resolve_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // Link an existing blocker to a task (puts the task in 'blocked' status if
+  // it's currently 'backlog' or 'ready'). Metic+ (#360 / ADR 0018) — same
+  // blocker-review grant as resolve above.
+  // rank: metic+archon — link a blocker to a task; same blocker-review grant as resolve.
+  router.post('/blockers/:id/link', api.requireBuilder, api.requireRank('metic', 'archon'), async (req, res) => {
+    if (validateOrRespond(req, res, {
+      task_id: { required: true },  // accept number or stringified number; coerced below
+    })) return;
+    const id = parseId(req, res, { code: 'bad_id' });
+    if (id === null) return;
+    const taskId = Number(req.body?.task_id);
+    if (!Number.isFinite(taskId)) return res.fail('task_id_required', 400);
+    try {
+      await blockers.linkBlockerToTask({ blockerId: id, taskId });
+      res.json({ ok: true });
+    } catch (err) {
+      console.error('[gds] POST /blockers/:id/link', err);
+      res.fail('link_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  return router;
+};

package/modules/ideas/routes/inbox.js

@@ -0,0 +1,230 @@
+const express = require('express');
+// Carved into modules/ideas/ (BV1.R78 / ADR 0093 §1+§5): auth gates + request
+// validators reach through the published doorway; `inbox` is an intra-module
+// sibling — a module never requires a core internal.
+const api = require('../../../src/module-api');
+const inbox = require('../inbox');
+const { validateOrRespond, LIMITS, parseId } = api;
+
+const INBOX_STATUS_VALUES = ['open', 'promoted', 'discarded', 'merged'];
+
+// The `ideas.capture` kernel PORT (ADR 0093 §5) — captureIdea's permanent home,
+// which retired the temporary `module-api.captureIdea` doorway leak (ADR 0091
+// §3). The discord module's #ideas inbound (`discord-inbound.js`) resolves it
+// instead of importing core. Registered here (the route factory is the one boot
+// hook that runs both in the live server AND when a test rebuilds the GDS
+// router) and hasProvider-guarded so re-instantiation never trips the seam's
+// single-provider guard. Mirrors modules/economy/routes/reward.js.
+function registerSeams() {
+  if (!api.hasProvider('ideas.capture')) {
+    api.registerProvider('ideas.capture', inbox.captureIdea);
+  }
+}
+
+module.exports = function buildInboxRouter() {
+  registerSeams();
+  const router = express.Router();
+
+  // rank: any-builder for ordinary ideas; metic+ for kind='criterion-proposal'.
+  // Anyone can file a general contribution (the open-to-all path that
+  // idea-triage's "Xenos can still file" line guarantees). But kind=
+  // 'criterion-proposal' is the marker the /planning-session skill writes from
+  // Metic-mode, and a planning-session proposal reshapes the next version's
+  // scope-truth — that's a trusted-builder operation (V3.R87 / #306). Gate it
+  // here so a Xenos can't slip a criterion proposal in via raw curl after the
+  // skill itself refuses to run for them.
+  router.post('/inbox', api.requireBuilder, async (req, res) => {
+    if (validateOrRespond(req, res, {
+      title: { required: true, type: 'string', maxLength: LIMITS.TITLE, minLength: 1 },
+      body_md: { type: 'string', maxLength: LIMITS.DESCRIPTION },
+      kind: { type: 'string', maxLength: 64 },
+      suggested_version: { type: 'string', maxLength: 64 },
+      suggested_priority: { type: 'integer', min: 0, max: 100 },
+    })) return;
+    const body = req.body || {};
+    if (body.kind === 'criterion-proposal') {
+      const rank = (req.builder?.rank || '').toLowerCase();
+      if (rank && rank !== 'metic' && rank !== 'archon') {
+        return res.fail('rank_forbidden', 403, { required: ['metic', 'archon'], actual: rank, reason: "kind='criterion-proposal' is a planning-session write; Metic+ only." });
+      }
+    }
+    try {
+      const idea = await inbox.captureIdea({
+        title: body.title,
+        bodyMd: body.body_md ?? '',
+        kind: body.kind ?? null,
+        suggestedVersion: body.suggested_version ?? null,
+        suggestedPriority: body.suggested_priority ?? null,
+        capturedBy: req.builder.id,
+      });
+      const open_count = await inbox.countOpenIdeas({ viewerRank: req.builder?.rank ?? null });
+      res.status(201).json({ idea, open_count, kind_auto: !body.kind });
+    } catch (err) {
+      if (err && err.code) {
+        const status =
+          err.code === 'TITLE_REQUIRED' ? 400 :
+          err.code === 'BAD_KIND' ? 400 :
+          err.code === 'BAD_PRIORITY' ? 400 :
+          500;
+        return res.fail(err.code, status, { ...err });
+      }
+      console.error('[gds] POST /inbox', err);
+      res.fail('capture_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // rank: any-builder — read open ideas; skill-friction rows filtered by viewer rank.
+  router.get('/inbox', api.requireBuilder, async (req, res) => {
+    const { kind, limit } = req.query;
+    const limitNum = Number(limit);
+    // Number.isFinite guard: a non-numeric ?limit (e.g. "abc") → NaN, which the
+    // listOpenIdeas({limit=50}) default does NOT catch (defaults fire only on
+    // undefined), so NaN would reach the SQL LIMIT and 500. Fall back to 50.
+    const parsedLimit = limit && Number.isFinite(limitNum) ? Math.max(1, Math.min(500, limitNum)) : 50;
+    try {
+      // Pass the viewer's rank so the skill-friction visibility gate (V3.R70)
+      // is live: Xenos-rank builders don't see [skill-friction] rows. The
+      // builders.rank column is populated (V3.R04), so req.builder.rank gates
+      // for real here; a null rank (unknown/pre-R04 row) still sees everything.
+      const viewerRank = req.builder?.rank ?? null;
+      const ideas = await inbox.listOpenIdeas({
+        kind: kind || null,
+        limit: parsedLimit,
+        viewerRank,
+      });
+      // Count under the same gate so open_count matches the rows the viewer can
+      // actually see — a Xenos must not be told there are more open ideas than
+      // their filtered list shows.
+      const open_count = await inbox.countOpenIdeas({ viewerRank });
+      res.json({ ideas, open_count });
+    } catch (err) {
+      console.error('[gds] GET /inbox', err);
+      res.fail('list_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // rank: any-builder — single idea read for the "#NNN" deep-link resolver
+  // (#1047). Mirrors GET /blockers/:id. The hall resolves /#/idea/N by id, but
+  // the /inbox LIST returns only the open-first-50, so a closed/older idea ref
+  // would dead-end at a "no such idea" card. getIdea() reads any idea by id.
+  // Authed: a logged-out resolve hits the hall's softAuth "sign in" card, so no
+  // idea text is exposed publicly (the linked refs are public, the bodies aren't).
+  router.get('/inbox/:id', api.requireBuilder, async (req, res) => {
+    const id = parseId(req, res, { code: 'bad_id', positiveInt: true });
+    if (id === null) return;
+    try {
+      const idea = await inbox.getIdea(id);
+      if (!idea) return res.fail('idea_not_found', 404);
+      res.json({ idea });
+    } catch (err) {
+      console.error('[gds] GET /inbox/:id', err);
+      res.fail('idea_read_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // Metic+ (#360 / ADR 0018): idea triage (promote/discard/merge) shapes the
+  // backlog. Criterion C2 assigns triage to Metic, so this widened from
+  // archon-only to metic+archon when the three-rank model went live. Any
+  // builder can still FILE an idea (POST /inbox above); a Xenos cannot triage.
+  // rank: metic+archon — idea triage shapes the backlog; criterion C2 / #360 / ADR 0018.
+  router.patch('/inbox/:id', api.requireBuilder, api.requireRank('metic', 'archon'), async (req, res) => {
+    if (validateOrRespond(req, res, {
+      // Enum kept light — inbox.updateIdea returns a structured BAD_STATUS
+      // error if the value falls outside the accepted set, and the supervisor
+      // doesn't hit this endpoint, so we're free to be strict.
+      status: { type: 'string', enum: INBOX_STATUS_VALUES },
+      kind: { type: 'string', maxLength: 64 },
+      promoted_to_task_id: { type: 'integer', min: 1 },
+      // reviewed_at accepts ISO string OR null OR numeric timestamp — type
+      // check stays open (declared untyped so strict-mode accepts it); the
+      // inline `new Date()` parse handles the rest.
+      reviewed_at: {},
+    })) return;
+    const id = parseId(req, res, { code: 'bad_id' });
+    if (id === null) return;
+    const body = req.body || {};
+    const patch = {};
+    if (body.status !== undefined) patch.status = body.status;
+    if (body.kind !== undefined) patch.kind = body.kind;
+    if (body.promoted_to_task_id !== undefined) patch.promoted_to_task_id = body.promoted_to_task_id;
+    if (body.reviewed_at !== undefined) {
+      const d = body.reviewed_at ? new Date(body.reviewed_at) : null;
+      if (d && Number.isNaN(d.getTime())) {
+        return res.fail('bad_reviewed_at', 400);
+      }
+      patch.reviewed_at = d;
+    } else if (body.status !== undefined && body.status !== 'open') {
+      // Auto-stamp on transition to a terminal status (promoted, discarded,
+      // merged). Lets callers PATCH without bookkeeping the timestamp.
+      patch.reviewed_at = new Date();
+    }
+    try {
+      const idea = await inbox.updateIdea(id, patch);
+      res.json({ idea });
+    } catch (err) {
+      if (err && err.code) {
+        const status =
+          err.code === 'IDEA_NOT_FOUND' ? 404 :
+          err.code === 'BAD_STATUS' ? 400 :
+          err.code === 'BAD_KIND' ? 400 :
+          500;
+        return res.fail(err.code, status, { ...err });
+      }
+      console.error('[gds] PATCH /inbox/:id', err);
+      res.fail('update_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // V3.R31 (#252) — Archon ratifies a criterion-proposal idea, atomically:
+  //   - INSERT done_when_criteria row on the target version
+  //   - UPDATE idea_inbox SET status='promoted', reviewed_at=now()
+  //   - INSERT karma_log (delta=+3, reason='proposal_ratified') for proposer
+  //     (V3.R28 / #248 tuned the delta from +5 → +3; tunable.)
+  //   - INSERT criterion_proposal_audit row capturing who/when/what
+  //
+  // Archon-only — done_when_criteria writes are scope-shaping (criterion C2
+  // in canonical-permissions.md). The kind='criterion-proposal' POST is
+  // Metic+ (gated above), but the ratification is the Archon decision.
+  //
+  // Returns 400 if the source idea isn't kind='criterion-proposal' or its
+  // body_md isn't a parseable {target_version, criterion_md, sort_order_hint}
+  // JSON object. Returns 404 if the idea doesn't exist. Returns 409 if the
+  // idea is already promoted/discarded/merged (status != 'open'). All four
+  // writes happen in one transaction — partial failures roll back cleanly.
+  router.post(
+    '/inbox/:id/ratify',
+    api.requireBuilder,
+    api.requireRank('archon'),
+    async (req, res) => {
+      const id = parseId(req, res, { code: 'bad_id' });
+      if (id === null) return;
+      const notes = (req.body && typeof req.body.notes_md === 'string') ? req.body.notes_md : '';
+      try {
+        const result = await inbox.ratifyCriterionProposal(id, req.builder.id, {
+          notesMd: notes,
+        });
+        res.status(201).json({ ok: true, ...result });
+      } catch (err) {
+        if (err && err.code) {
+          const status =
+            err.code === 'IDEA_NOT_FOUND' ? 404 :
+            err.code === 'WRONG_KIND' ? 400 :
+            err.code === 'IDEA_NOT_OPEN' ? 409 :
+            err.code === 'BAD_BODY' ? 400 :
+            err.code === 'BAD_ID' ? 400 :
+            err.code === 'VERSION_NOT_FOUND' ? 400 :
+            500;
+          return res.fail(err.code, status, { ...err });
+        }
+        // Surface unique-constraint trip on (version_id, criterion_id) as a 409.
+        if (err && err.code === '23505') {
+          return res.fail('CRITERION_ALREADY_RATIFIED', 409, { detail: 'A criterion with this proposal ref already exists on the target version.' });
+        }
+        console.error('[gds] POST /inbox/:id/ratify', err);
+        res.fail('ratify_failed', { status: 500, message: 'internal error' });
+      }
+    }
+  );
+
+  return router;
+};

package/modules/lifecycle/CLAUDE.md

@@ -0,0 +1,63 @@
+# `lifecycle` module — the build state machine + the `lifecycle` kernel port
+
+> The **LAST and most-coupled CORE-domain** carved into a module (BV1.R86, [ADR 0093](../../docs/adr/<redacted>.md) §1,§3) — after memory (R72), grading (R73), economy (R77), ideas (R78), security (R79), builder-settings (R80), onboarding (R81), sessions (R82), autonomy (R83), status-UI (R84), hall-UI (R85). Carved last on purpose: by now every capability it INVOKES (`grade`, `reward`, `onboarding`) is a kernel port it resolves, so the lifecycle imports only the kernel + resolves those ports ([02-module-map §4](../../docs/design/modular-architecture/02-module-map.md): keep the state machine WHOLE, never split). `default: true` — every instance runs the lifecycle. This carve makes the `db.js` residue exactly what ADR 0093 §3 predicted: the kernel identity/auth/twin slice + `db-kernel.js`.
+
+Owns the **build state machine**: tasks · claims · versions · done-when criteria · goals · dependencies · the claim→ship→grade→credit lifecycle · override requests · the ship/confirm/promote orchestration · `github-push` (server-mediated branch publish) · `merge-lock` · `conflict-resolve` · the `publish-reconciler` (confirmed→shipped auto-heal) · `ship-card`/`ship-preflight` · `version-close` · the peer-vote→karma fold-in · the work-tracking analytics (est-drift, grade trend, AI-dev curve).
+
+## The boundary (the one rule)
+
+This module reaches core **only** through the published doorway [`../../src/module-api.js`](../../src/module-api.js) (`coreVersion ^1.12.0` — it needs the R86 doorway additions: `repoInfo`, `moduleScopeMap`, `pathMatch`, `userAgent`, `asyncHandler`, `corsPublicGet`). It must **never** `require()` a core internal directly, and never another module. Core, in turn, must never `require()` a file in here — it reaches the lifecycle only through the `lifecycle` port (below). Both directions are enforced by the BV1.R44/R45 fitness checks.
+
+## The `lifecycle` kernel PORT (ADR 0093 §3 — the headline of this carve)
+
+The inverse of every prior carve: the lifecycle is carved last, so every capability it *invokes* (`grade`/`reward`/`onboarding`) is already a port it RESOLVES; the `lifecycle` port is the surface **core and the other modules resolve to reach the build state machine** without importing this module.
+
+- **Provides — port `lifecycle`** → the surface in [`lifecycle.js`](lifecycle.js) (DELEGATES, does not spread, to `./db` + `./task-classifier` so test stubs bite at call time — the economy `reward` precedent). Registered in [`routes/lifecycle.js`](routes/lifecycle.js)'s factory (the loader runs it at boot + on every test router rebuild; `hasProvider`-guarded). It **retires the three ADR-0091 §3 doorway leaks** — `createTask`, `VOTABLE_TASK_STATUSES`, `tallyPeerVotes` — plus exposes `classifyTaskKind` and the work-tracking READS the staying-core read routes need.
+- **Core + the other modules consume it WITHOUT importing this module** (all via `seams.resolveOptional('lifecycle')`):
+  - `src/bongos/routes/public.js` (the status surface) — `getTask`/`listVersions`/`versionProgress`/`recentShippedTasks`/`estimationDriftSummary`/`rollingAvgGrade`/`gradeTrendByDay`.
+  - `src/bongos/routes/me.js` (the profile reader) — `<redacted>`/`getEstVsActualRatio`/`recentGradesForBuilder`/`<redacted>`/`<redacted>`.
+  - `src/bongos/routes/builders.js` (the Archon roster) — `getBuildersRoster`/`<redacted>`/`gradeByBuilder`/`<redacted>`.
+  - `src/bongos/cascade-dispatch.js` (dormant System 3) — `classifyTaskKind`.
+  - `modules/onboarding/db.js` (newcomer-restock) + `modules/discord/db.js` (#bugs→task) — `createTask`.
+  - `modules/discord/discord-reaction.js` — `VOTABLE_TASK_STATUSES`.
+  - `modules/autonomy/pollers/routine-timers.js` — `tallyPeerVotes`.
+- **It RESOLVES (as a transaction-participant consumer)** the `reward` + `onboarding` ports inside its own `withTx` — `claimTask`/`confirmTask`/`decideOverrideRequest`/`applyGrade` open the tx, run the state-machine SQL, and call `seams.resolveOptional('reward')|('onboarding').*(client, …)` so the credit/achievement/stage writes commit atomically with the status flip (ADR 0093 §2). It resolves via `resolveOptional` (graceful), so `consumes: []` — a vanilla instance without economy/onboarding degrades those writes to best-effort no-ops, it does not fail.
+
+## Files
+
+| File | What |
+|---|---|
+| `db.js` | the lifecycle data layer — ~97 functions: tasks/claims/versions/goals/dependencies/criteria, the claim→ship→grade→credit lifecycle (`claimTask`/`resolveClaim`/`confirmTask`/`shipTask`/`applyGrade`/`abandonTask`), overrides, estimation + work analytics, the merge lease, `tallyPeerVotes`, `createTask`. Reaches the pool/withTx/seams via the doorway; resolves `reward`/`onboarding` as a consumer. |
+| `task-classifier.js` | the `tasks.kind`/discipline heuristic + `VOTABLE_TASK_STATUSES`/`VALID_KINDS`/`VALID_DISCIPLINES`/`TASK_FIELD_BOUNDS`. `branding()` (instance blocker-vendors) via the doorway. |
+| `done-when.js` · `hierarchy.js` · `version-close.js` | the done-when criterion read/write surface, the shallow one-level task hierarchy, and the version-close gate evaluator. Pool via the doorway. |
+| `github-push.js` · `conflict-resolve.js` · `publish-reconciler.js` | server-mediated branch publish ([ADR 0055](../../docs/adr/<redacted>.md)) + the [ADR 0082](../../docs/adr/<redacted>.md) generated-file conflict resolver + the confirmed→shipped reconciler. `repoInfo`/`branding`/`userAgent` via the doorway; siblings require each other. |
+| `ship-card.js` · `ship-preflight.js` · `merge-lock.js` | the CLI lifecycle card, the ship preflight guards, and the cross-machine merge lease serializer (pure; `branding` via the doorway). |
+| `lifecycle.js` | the `lifecycle` port provider surface (delegates to `./db` + `./task-classifier`). |
+| `routes/{tasks,claims,versions,done-when,goals,dependencies,gate-approvals,analytics}.js` | the lifecycle HTTP surface — moved out of `src/bongos/routes/`; the loader mounts them via `contributes.routes`. Auth/validators/seams via the doorway; `./db` + libs are siblings. |
+| `routes/lifecycle.js` | the route factory that registers the `lifecycle` port (no HTTP endpoint). |
+| `pollers/publish-reconciler.js` | the loader poller entry (`start`/`stop`) for the publish reconciler — inverts the old `server.js` hardcoded start (the autonomy routine-timers precedent). |
+
+## Boundary-forced duplication (keep in sync)
+
+Two helpers are **deliberately duplicated** with core `src/bongos/db.js` (ADR 0091 §2 — "boundary-forced duplication is allowed + documented"): the same SQL runs on both sides of the kernel↔module line, and a module can't import core:
+
+- **`sealSessionLog`** — core `deactivateBuilder` (rank/identity management, stays core) writes the same `session_logs` close row; here `resolveClaim`/`shipTask` write it.
+- **`_applyRankChangeTx` (+ its `RANKS` / `singleRungPromotionError` deps)** — core `setBuilderRank` (Archon-driven, stays core) runs the same in-tx rank change; here it backs the automatic xenos→thetes graduation on ship (`maybeAutoGraduateToThetes`).
+- **the `gradePassCount` SQL fragment** — core `builderRollingAvgGrade` (the grade-trend read the sessions BFG also consumes, kept on the doorway) + the module's grade reads share it.
+
+## NOT in this module (the db.js residue — stays core)
+
+- **Builder IDENTITY + admission** (`upsertBuilder`/`getBuilderByGithubId`/`hasInvitedAccessRequest`/`linkAnthropicAccount`/`updateBuilderDisciplines`) — `auth.js` imports these; they CANNOT live in a module.
+- **Rank + status MANAGEMENT** (`setBuilderRank`/`_applyRankChangeTx`/`<redacted>`/`deactivate`/`reactivateBuilder`) — Archon identity ops consumed by `routes/builders.js`, NOT the task lifecycle.
+- **AUTH sessions** (`createSession`/`lookupSession`/`revoke*`/`hasCliSession`/`SESSION_TTL_MS`) — the `builder_sessions` token store `auth.js` drives.
+- **TWIN / social** (Discord link flow, karma feed, `listAuditLog`, the grade-trend `builderRollingAvgGrade`) + the **security_docs** store (the kernel security-PROPERTY plane).
+- **The Gemini-key leak** (`getBuilderGeminiKeyRow`/…) — art-pipeline credential infra.
+- **The lifecycle CLIs** — a command travels with its domain but stays a CLI under `scripts/gds/` (`ship.js`/`claim.js`/`release.js`/`merge-mode.js`/`confirm.js`/`merge-lock.js`/`version-close.js`/`main-audit.js`/`gate-review.js`/`push-main.js`/`ci-grade.js`), outside the kernel boundary — they may require this module directly (the grading/economy precedent).
+
+## Tables
+
+None owned. `tasks`/`claims`/`versions`/`goals`/`done_when_criteria`/`dependencies`/`task_grades`/`task_override_requests`/`merge_leases` (+ their migrations) were created before the module system and stay in core `migrations/` (the shared-schema additive rule). The module owns the *queries*; any **new** lifecycle migration belongs in `modules/lifecycle/migrations/` namespaced `lifecycle_*`.
+
+## Tests
+
+The DB-free carved-surface tests in `scripts/gds/coreB-carve-proof.sh` (`task_classifier_vocab`, `criterion_progress`, `github_push_*`, `ship_card`, `ship_preflight`, `merge_lock`, `conflict_resolve`, `publish_reconciler`, `goal_achievement`, `context_pack`) import from `modules/lifecycle/…` and pass byte-identical. The DB-integration tests (`grade_attempts`, `rank_gate`, `abandon_task`, `confirm_attribution`/`override_attribution`/`grade_attribution`, `goal_routes`/`goal_tier`/`goal_achievement`, `dependencies_*`, `task_create_idempotency`, `worktree_disambiguation`, `cap_newcomer_tasks`, `migration_allocation`, `task_ownership_gate`, `verify_task_guard`, `versions_route`, `gate_approvals`, `merge_lease`, `autonomous_fit_protected_paths`, …) require/read `modules/lifecycle/{db,routes/*,libs}.js`; the route-consumer tests (`onboarding_route_signals`, `onboarding_observability`, `discord_reaction`) register the `lifecycle` port. See [ADR 0093](../../docs/adr/<redacted>.md).