@skyf0xx/hedgehog 0.1.0

package/src/skills/hedgehog-bootstrap/SKILL.md

@@ -0,0 +1,403 @@
+---
+name: hedgehog-bootstrap
+description: Use once, at the start of a new Hedgehog project, to scaffold Project Bootstrap and wire in the enforcement config that makes the stack and build order mechanically true (Nx boundaries, lefthook, commitlint, env validation, phase gate). Triggers on "bootstrap this project", "set up the hedgehog stack", "scaffold the workspace". Not for per-module work — that's the `hedgehog-loop` skill, one step at a time.
+---
+
+# Hedgehog Bootstrap
+
+Scaffolds Project Bootstrap once per project, plus the enforcement config
+that makes the stack and build order mechanically true rather than merely
+documented. After this runs, `hedgehog-loop` takes over per module, one
+step at a time. This skill touches no domain modules — no schema, no
+contract, nothing under `libs/<module>/`. That's Phase A, started fresh
+after Bootstrap closes.
+
+Run the `nx g` commands below via nrwl's [nx-generate](https://github.com/nrwl/nx-ai-agents-config/tree/main/skills/nx-generate) skill — it dry-runs
+and verifies generator flags against the installed Nx version. Run the
+`nx run` / `nx affected` commands in Enforcement wiring via
+[nx-run-tasks](https://github.com/nrwl/nx-ai-agents-config/tree/main/skills/nx-run-tasks) the same way. The commands below are the spec; those
+skills execute it correctly.
+
+## The Stack (locked)
+
+One opinionated stack, applied the same way on every project:
+
+| Layer | Choice |
+|---|---|
+| Monorepo | Nx |
+| Package manager | pnpm |
+| Backend framework | NestJS |
+| ORM | Drizzle (+ `drizzle-zod`) |
+| Database | PostgreSQL |
+| Platform | Railway |
+| API contract | ts-rest |
+| Validation | Zod |
+| Auth | Better Auth (+ `@thallesp/nestjs-better-auth`, Drizzle adapter) |
+| Data fetching / hooks | TanStack Query |
+| Web UI | Next.js (frontend only) + ShadCN + Tailwind |
+| Mobile UI (optional) | Expo + React Native Reusables + NativeWind |
+| Queues / jobs | BullMQ + Redis |
+| Logging | Pino (`nestjs-pino`) |
+| Lint / format | ESLint (flat config) + Prettier (+ `prettier-plugin-tailwindcss`) |
+| Testing | Vitest (unit/integration) + Playwright (web e2e) |
+| Commits | Conventional Commits + commitlint + lefthook |
+| Observability | Sentry |
+
+Constraint-contingent substitutions: Prisma for Drizzle when the team
+isn't SQL-comfortable; cloud + Pulumi/SST for Railway when full
+declarative IaC is a hard requirement; tRPC for ts-rest when the client is
+committed TypeScript-only.
+
+### Monorepo layout
+
+```
+apps/
+  web        (Next.js — UI only)
+  mobile     (Expo — optional)
+  api        (NestJS — owns all domain logic + DB access)
+  worker     (BullMQ consumers)
+
+packages/
+  db         (Drizzle schema + client)
+  contracts  (ts-rest + Zod contracts)
+  hooks      (TanStack Query — shared web + mobile)
+  jobs       (typed job registry / queue definitions)
+  auth       (Better Auth config)
+  config     (locked ESLint/Prettier/tsconfig/env schema)
+  shared     (cross-cutting types + utils)
+
+docs/
+  design     (<module>.md per module — `ux-planner` agent output)
+```
+
+`packages/auth` and `packages/jobs` are infra, built once, here — not
+touched again per module. `docs/design` fills in per module during
+Phase B; nothing to scaffold here beyond the empty directory.
+
+### Queues: seam in, usage deferred
+
+The queue seam is a day-one standing default: Redis provisioned on
+Railway, a `worker` app in the monorepo, a `Queue` port with a BullMQ
+adapter (same pattern as repositories). Usage stays last-responsible-
+moment: an operation goes async only when it genuinely needs to
+(long-running work, retries, fan-out). Services don't know how their
+results are returned — the enqueue-vs-await decision lives at the
+application/controller layer. Workers are idempotent (at-least-once
+delivery).
+
+## Before running
+
+Confirm Intake already happened — a scope boundary and domain vocabulary
+should exist (`planner` produces these). Bootstrap doesn't need the
+vocabulary to scaffold infra, but starting before Intake signals work
+getting ahead of itself. No scope boundary yet: stop and point to
+`planner`.
+
+Confirm this hasn't already run: check for an existing Nx workspace
+(`nx.json` at repo root) or a prior Bootstrap commit
+(`git log --grep="^feat(config)"`). Re-running Bootstrap against an
+existing workspace is a Correction Protocol case (patch the specific
+config step at its source, per `hedgehog-loop`), not a re-scaffold.
+
+## Steps (run in sequence, one commit per step)
+
+### 1. Nx workspace + `packages/config`
+
+```bash
+npx create-nx-workspace@latest . --preset=ts --pm=pnpm --nxCloud=skip
+```
+
+Scaffold `packages/config` as a plain `@nx/js` lib holding the locked,
+shared files:
+
+- `packages/config/eslint-base.js` — flat config, extended by every
+  app/lib. Include `@nx/enforce-module-boundaries` and `depConstraints`
+  from Enforcement wiring below, verbatim.
+- `packages/config/prettier.js` — includes `prettier-plugin-tailwindcss`.
+- `packages/config/env.schema.ts` — the Zod env schema from Enforcement
+  wiring below (`DATABASE_URL`, `BETTER_AUTH_SECRET`, `REDIS_URL`,
+  `NODE_ENV`; extend per project as new infra is added later).
+- Root `eslint.config.js` extends `packages/config/eslint-base.js` and
+  declares the project tags table below (`scope:*`, `type:*`) as comments
+  or a lookup, so every later generator step tags its project correctly.
+
+Commit: `feat(config): workspace + shared config`
+
+### 2. `packages/db` — Drizzle client + connection
+
+```bash
+npx nx g @nx/js:lib packages/db --bundler=none --unitTestRunner=vitest
+pnpm add drizzle-orm pg && pnpm add -D drizzle-kit drizzle-zod
+```
+
+Wire a Postgres connection reading `DATABASE_URL` via `loadEnv()`
+(step 1's env schema). No domain schema files yet — that's Phase A, per
+module. Tag: `scope:db`, `type:adapter`.
+
+Commit: `feat(db): drizzle client + connection`
+
+### 3. `packages/auth` — Better Auth config
+
+```bash
+npx nx g @nx/js:lib packages/auth --bundler=none --unitTestRunner=vitest
+pnpm add better-auth @thallesp/nestjs-better-auth
+```
+
+Configure the Drizzle adapter against `packages/db`. Tag: `scope:auth`,
+`type:adapter`.
+
+Commit: `feat(auth): better auth config`
+
+### 4. `apps/api` — Nest app shell, global guard, Pino
+
+```bash
+npx nx g @nx/nest:app apps/api
+pnpm add nestjs-pino pino-http && pnpm add @thallesp/nestjs-better-auth
+```
+
+Wire the global auth guard (secure-by-default) and `nestjs-pino` for
+structured logging. Call `loadEnv()` at the top of `apps/api/src/main.ts`.
+Tag: `scope:api`. No controllers beyond a health check — domain
+controllers arrive per module in Phase A.
+
+Commit: `feat(api): nest shell + global guard + pino`
+
+### 5. `apps/worker` — BullMQ seam (Redis, no consumers yet)
+
+```bash
+npx nx g @nx/node:app apps/worker
+pnpm add bullmq ioredis
+```
+
+Provision the Redis connection and a `Queue` port shape (port + BullMQ
+adapter, same pattern repositories use later) with no consumers — usage
+is deferred (see Queues, above). Call `loadEnv()` at the top of
+`apps/worker/src/main.ts`. Tag: `scope:worker`.
+
+Commit: `feat(worker): bullmq seam, no consumers`
+
+### 6. `apps/web` — Next shell, TanStack Query provider, base theme
+
+```bash
+npx nx g @nx/next:app apps/web
+pnpm add @tanstack/react-query
+pnpm dlx shadcn@latest init
+```
+
+Wire the TanStack Query provider at the root layout. `shadcn init` writes
+`apps/web`'s base theme (CSS variables for color, radius, light/dark
+mode) — set the actual palette here, once, rather than leaving ShadCN's
+placeholder values for `ui-builder` to inherit unnoticed on the first
+screen. Light/dark mode toggle wiring belongs here too, not as a
+per-screen decision later. No screens or hooks yet — Phase B doesn't
+start until Phase A closes for at least one module. Tag: `scope:web`.
+
+Commit: `feat(web): next shell + query provider + base theme`
+
+### 7. `apps/mobile` — Expo shell (only if mobile is in scope)
+
+Skip entirely if mobile isn't in the scope boundary from Intake — don't
+scaffold speculative infra.
+
+```bash
+npx nx g @nx/expo:app apps/mobile
+pnpm add react-native-reusables nativewind
+```
+
+Configure NativeWind's theme (`tailwind.config.js` colors, light/dark) to
+match `apps/web`'s base theme from step 6 — one visual identity across
+platforms, set once here rather than drifting per-screen. Tag:
+`scope:mobile`.
+
+Commit: `feat(mobile): expo shell + base theme`
+
+## Enforcement wiring (within step 1, not a separate pass)
+
+These are config *files*, not extra steps — write them as part of step 1
+so the commit gate is live before step 2 starts. Every rule below is a
+compiler error, lint failure, or blocked commit — this is what makes the
+stack and build order mechanically true.
+
+### Nx module boundaries
+
+Encodes "service imports only ports" as a build-time failure.
+`@nx/enforce-module-boundaries` reasons at Nx-project granularity, so each
+domain module's repository and service are their own Nx lib; `apps/api`
+itself is wiring (controllers + module registration) importing those
+libs. This makes cross-module isolation (FK-by-ID only, per
+`hedgehog-loop`) mechanically true.
+
+**Tags:**
+
+```
+apps/api          → scope:api
+apps/worker        → scope:worker
+apps/web            → scope:web
+apps/mobile         → scope:mobile
+packages/db          → scope:db,        type:adapter
+packages/contracts   → scope:contracts, type:contract
+packages/hooks       → scope:hooks,     type:hook
+packages/auth        → scope:auth,      type:adapter
+packages/shared      → scope:shared,    type:util
+libs/<module>/port      → scope:<module>, type:port
+libs/<module>/repository → scope:<module>, type:adapter
+libs/<module>/service    → scope:<module>, type:service
+```
+
+One `libs/<module>/` triplet per domain module (one table = one module) —
+e.g. `libs/orders/port`, `libs/orders/repository`, `libs/orders/service`.
+
+**Root `eslint.config.js` rule:**
+
+```js
+'@nx/enforce-module-boundaries': ['error', {
+  depConstraints: [
+    // domain services never import adapters directly — only ports
+    { sourceTag: 'type:service', onlyDependOnLibsWithTags: ['type:port', 'type:util'] },
+    // web/mobile never import db or api internals — only contracts + hooks
+    { sourceTag: 'scope:web',    onlyDependOnLibsWithTags: ['scope:contracts', 'scope:hooks', 'scope:shared'] },
+    { sourceTag: 'scope:mobile', onlyDependOnLibsWithTags: ['scope:contracts', 'scope:hooks', 'scope:shared'] },
+    // worker only reaches domain logic through ports, same as api
+    { sourceTag: 'scope:worker', onlyDependOnLibsWithTags: ['type:port', 'type:util', 'scope:shared'] },
+  ],
+}],
+```
+
+Building out of order (a controller before a service exists, a hook
+reaching into `apps/api` directly) fails `nx lint`.
+
+### Commit gate (lefthook + commitlint)
+
+Enforces one coherent change, tested, conventionally committed. Runs on
+staged files only — fast regardless of repo size.
+
+**`lefthook.yml`:**
+
+```yaml
+pre-commit:
+  parallel: true
+  commands:
+    typecheck:
+      glob: "*.{ts,tsx}"
+      run: npx nx affected -t typecheck --files={staged_files}
+    lint:
+      glob: "*.{ts,tsx}"
+      run: npx nx affected -t lint --files={staged_files}
+    test:
+      glob: "*.{ts,tsx}"
+      run: npx nx affected -t test --files={staged_files}
+
+commit-msg:
+  commands:
+    commitlint:
+      run: npx commitlint --edit {1}
+```
+
+**`commitlint.config.js`:**
+
+```js
+module.exports = {
+  extends: ['@commitlint/config-conventional'],
+};
+```
+
+Scope is open — a domain module (`orders`, `users`, ...) or an infra area
+(`db`, `contracts`, `auth`, `hooks`, `api`, `worker`, `web`, `mobile`,
+`config`). `@commitlint/config-conventional` validates type and subject
+case; scope isn't restricted to a fixed list since new modules enter play
+throughout a project's life.
+
+A commit that fails typecheck, lint, or test does not happen. A commit
+exists once it compiles and passes.
+
+Run `pnpm dlx lefthook install` once `lefthook.yml` exists so the gate is
+active from step 2 onward.
+
+### Env validation (fail fast)
+
+Types-first extended to config. Boot fails immediately on a missing or
+malformed env var.
+
+**`packages/config/env.schema.ts`:**
+
+```ts
+import { z } from 'zod';
+
+export const envSchema = z.object({
+  DATABASE_URL: z.string().url(),
+  BETTER_AUTH_SECRET: z.string().min(32),
+  REDIS_URL: z.string().url(),
+  NODE_ENV: z.enum(['development', 'test', 'production']),
+});
+
+export type Env = z.infer<typeof envSchema>;
+
+export function loadEnv(): Env {
+  const parsed = envSchema.safeParse(process.env);
+  if (!parsed.success) {
+    console.error(parsed.error.format());
+    process.exit(1);
+  }
+  return parsed.data;
+}
+```
+
+Called once, at the top of `apps/api/src/main.ts` and
+`apps/worker/src/main.ts`.
+
+### Phase gate (CI)
+
+Encodes "Phase A closes before Phase B opens" as a CI check. Blocks a PR
+introducing a `feat(<module>): hooks` or `feat(<module>): screen-*` commit
+for a module with no prior `feat(<module>): api` commit on the branch. Can
+land in step 1's commit or as its own `feat(config): phase gate` commit.
+
+**`.github/workflows/phase-gate.yml` (logic sketch):**
+
+```yaml
+- name: Enforce Phase A before Phase B
+  run: |
+    node tools/phase-gate.js
+```
+
+**`tools/phase-gate.js` (logic):**
+
+```
+for each commit in PR:
+  if commit matches /^feat\(([a-z-]+)\): (hooks|screen-\w+)/:
+    module = capture group 1
+    fail unless a commit matching /^feat\(<module>\): api/ (module
+      substituted in) already exists on main or earlier in this branch
+```
+
+### Locked format/lint config
+
+One shared config, extended everywhere:
+
+- `packages/config/eslint-base.js` — flat config, extended by every
+  app/lib.
+- `packages/config/prettier.js` — includes `prettier-plugin-tailwindcss`.
+
+A per-app override request signals to fix the base config at the source.
+
+## After Bootstrap
+
+Update `TODO.md`: check off every Bootstrap line now built, leave Phase
+A/B sections as-is (per-module, filled in by `planner` during Intake or
+when new scope enters play). Hand off to `hedgehog-loop` — from here,
+every domain module goes through Phase A steps 1–5(a) one at a time,
+gated by lefthook, each its own commit.
+
+## Constraints
+
+- Run once per project. Not a per-module or per-feature tool.
+- Don't scaffold `apps/mobile` unless mobile is explicitly in scope.
+- Don't add domain schema, contracts, or any `libs/<module>/*` content —
+  that's Phase A, started after Bootstrap, one module at a time.
+- Don't deviate from the package/library choices above. If a generator or
+  package name changed upstream since this was written, verify against
+  current docs before running the command — don't substitute a different
+  library.
+- Each of the 7 steps is its own commit, in order — same unit-of-work
+  discipline as every other step in the discipline, even though this is
+  infra rather than a domain module.

package/src/skills/hedgehog-loop/SKILL.md

@@ -0,0 +1,197 @@
+---
+name: hedgehog-loop
+description: Use for every unit of work once a Hedgehog project is bootstrapped — building one Order step (schema, contract, repository, service, controller, hook, screen), gating it, committing it, and checking it off TODO.md. Triggers on "next step", "build this module", "what's next", or the start of any work session on a bootstrapped project. Also covers the Correction Protocol for fixing a wrong upstream step.
+---
+
+# Hedgehog Loop
+
+The operating loop for a bootstrapped Hedgehog project: pick the next step,
+build it, gate it, commit it, check it off. `TODO.md` at repo root is the
+live list — read it before starting. It's thin: a context blurb plus a
+checklist mirroring the phase/step structure below. Checked/unchecked is
+its only state.
+
+## Determine phase
+
+Before touching code, know which phase applies to the module in scope:
+
+- **Phase A** — building/extending the backend. Every module in scope
+  needs schema → contract → repository → service → controller (→ queue)
+  before Phase B starts for any of them.
+- **Phase B** — Phase A is closed for the module. Build hooks and screens.
+
+Check `TODO.md`, or the commit log for `feat(<module>): api` commits. No
+such commit means the module is in Phase A.
+
+## The Domain Module Pattern
+
+A **domain module = one table.** `users`, `orders`, `order_items` are each
+their own module, carrying the full step sequence below. The schema is the
+source of truth for module boundaries.
+
+**Cross-module references are FK-by-ID only.** If `orders.user_id`
+references `users`, the `orders` schema holds a plain FK column. The
+`orders` repository and service depend only on their own ports — a service
+knows related entities only as an ID.
+
+- Need the related row? Resolve it at the contract/controller layer
+  (parallel calls to each module's own endpoint), or join against the
+  other module's *schema* directly inside the repository (Drizzle query).
+- This keeps every service importing only its own ports, so the Nx rule
+  `type:service → onlyDependOnLibsWithTags: ['type:port', 'type:util']`
+  holds uniformly (wired at bootstrap).
+
+A junction table (e.g. `order_items`) is one table, one module, with two
+FK-by-ID columns instead of one, each resolved the same way.
+
+Every module goes through the same shape, in order:
+
+```
+schema      (Drizzle)              — types before data
+contract    (Zod / ts-rest)        — the boundary
+repository  (port + Drizzle adapter)
+service     (domain logic)         — imports only ports
+controller  (thin HTTP)
+hook        (TanStack Query)       — Phase B only
+```
+
+Plus, when an operation needs async: **queue = port + BullMQ adapter**,
+same port/adapter shape as the repository. The service imports only ports.
+
+Standard Nx generators (`@nx/nest`, `@nx/next`, `@nx/expo`, `@nx/js`)
+scaffold the app/lib shell. Each step's actual content (schema, contract,
+repository, service, controller, hook) is hand-built, following this
+sequence.
+
+## Domain Module — Backend Steps (Phase A, every module in scope)
+
+A horizontal pass across the whole backend — every module goes through
+these before any module gets a hook or screen.
+
+| # | Step | Lives in | Commit |
+|---|---|---|---|
+| 1 | Schema | `packages/db` (Drizzle) | `feat(<module>): schema` |
+| 2 | Contract | `packages/contracts` (Zod via `drizzle-zod` + ts-rest) | `feat(<module>): contract` |
+| 3 | Repository | `libs/<module>/repository` (port + Drizzle adapter) | `feat(<module>): repository` |
+| 4 | Service | `libs/<module>/service` (domain logic — imports only ports) | `feat(<module>): service` |
+| 5 | Controller | `apps/api` (thin HTTP, wires contract → service) | `feat(<module>): api` |
+| 5a | Queue *(if needed)* | `apps/worker` (port + BullMQ adapter) | `feat(<module>): queue` |
+
+Repeat 1–5(a) per module in scope. The API is complete, typed, and
+callable (Postman/curl/contract tests) before frontend work starts.
+
+## Domain Module — Frontend Steps (Phase B, after Phase A closes for the module)
+
+| # | Step | Lives in | Commit |
+|---|---|---|---|
+| 6 | Hook | `packages/hooks` (TanStack Query) | `feat(<module>): hooks` |
+| 6a | UX rationale | `docs/design/<module>.md`, `ux-planner` agent | bundled into step 7's commit |
+| 7 | Screen | `apps/web` and/or `apps/mobile` | `feat(<module>): screen-web` / `feat(<module>): screen-mobile` |
+
+Phase B starts once Phase A is done for the scope. The frontend is a pure
+consumer of an already-finished API. Step 6a is where "how it should feel"
+gets decided — once per module, after the hook exists and before
+`ui-builder` starts the screen — via `ux-planner`, starting from whatever
+`planner` filed in `docs/design/<module>-notes.md` at Intake. Its first run
+for a module also signals to the user that Phase B has started, and is the
+point a mockup, screenshot, or export (Google Stitch, Figma) can be handed
+over. It writes `docs/design/<module>.md`, not its own step commit;
+`TODO.md` tracks only hooks/screen-web/screen-mobile per module.
+
+## The Loop (every unit of work)
+
+1. **Pick the next step** per the tables above, from `TODO.md`. One step
+   at a time, in order.
+2. **Check the gate.** The prior step compiles and passes tests first.
+3. **Build exactly one step.** One schema, one contract, one repository.
+4. **Run the gate on your own work**: typecheck, lint, test (mirrors
+   lefthook, wired at bootstrap).
+5. **Commit** using the exact Conventional Commit format above.
+6. **Check off the line in `TODO.md`.**
+7. **Repeat.**
+
+Each commit batches exactly one step, built right for what's known now; a
+wrong step is fixed forward later via the Correction Protocol.
+
+## Intra-step conventions
+
+The Nx boundaries, phase gate, and lint own the *structural* rules
+(what imports what, what gets built when). These are the conventions
+*inside* a step that those gates can't see — apply them uniformly so a
+fresh-context session builds module N the same way it built module 1. The
+`reviewer` agent checks these at a phase boundary.
+
+- **Errors are thrown, typed, and domain-named.** A service throws a
+  domain error (`OrderNotFoundError`, not a bare `Error` or an HTTP
+  exception) — services don't know they're behind HTTP. The controller is
+  the only layer that maps domain errors to status codes. Never return
+  `null`/`undefined` to signal a failure a caller must branch on.
+- **Repository not-found returns `undefined`; the service decides.** A
+  `findById` that misses returns `undefined` (a plain absence, not an
+  error); the service turns that into a thrown domain error when the
+  operation requires the row. Adapters don't throw domain errors — they
+  report absence, the service interprets it.
+- **Validation lives at the contract boundary, once.** Input is
+  Zod-validated at the controller via the ts-rest contract. Past that
+  boundary, types are trusted — services and repositories don't re-parse.
+  A service-level invariant that isn't expressible in the Zod schema
+  (e.g. "can't cancel after payment") is enforced in the service as a
+  thrown domain error, not a second validation pass.
+- **Multi-write operations are transactional.** A service method that
+  writes more than once wraps the writes in one Drizzle transaction,
+  passed through the port — partial writes never escape a failed
+  operation.
+- **Services are pure domain logic.** No logging, no HTTP, no queue
+  mechanics inside a service method — those live at the controller /
+  adapter edge. A service reads as the business rule and nothing else.
+
+## Correction Protocol
+
+When a downstream step reveals an upstream step was wrong:
+
+1. Stop.
+2. Patch the upstream step directly, in place.
+3. Fast-forward every dependent step that breaks, each its own small
+   commit.
+4. The commit messages are the explanation.
+5. Resume the loop.
+
+Use `conventional-commits` when a correction touches several steps in one
+working-tree pass and needs splitting back into per-step commits.
+
+## Phase Transition Checks
+
+Before starting Phase B for a module, confirm:
+
+- A `feat(<module>): api` commit exists for that module.
+- The contract is callable and typed (contract tests pass).
+
+Use the `reviewer` agent for this — it checks what the mechanical gate
+can't (port discipline, FK-by-ID discipline, contract shape).
+
+Before starting Phase A for a module, confirm it's inside the stated scope
+boundary from Intake (`planner`). If not, stop and ask.
+
+## Rules
+
+- **Phase A closes before Phase B opens.** Every module in scope has a
+  working, tested API before any hook or screen starts.
+- **Sequential within a phase.** A step starts once the one before it
+  compiles and passes tests.
+- **Step 5a is conditional** — only when an operation genuinely needs
+  async (long-running, retries, fan-out); the normal case has no queue.
+- **A wrong step gets fixed at its source** — the Correction Protocol, not
+  a downstream workaround.
+- **Tests gate every commit** in the sequence.
+- A module's frontend code (hook, screen) is built after its API is
+  committed.
+- The screen step doesn't start blank — `ux-planner` runs once per module,
+  after the hook is committed, before `ui-builder` starts the screen.
+- `packages/config` is the single source for shared config; a per-app
+  override request signals to fix the base config at the source.
+
+## Stop Condition
+
+A build session ends when every module in scope has completed both Phase
+A and Phase B, or when scope is ambiguous enough that continuing means
+guessing — ask one question and wait.