@nanobpm/nano-workforce 0.50.0 → 0.52.0

package/docs/adr/0002-escalations-are-user-tasks-and-forms.md

@@ -0,0 +1,167 @@
+# ADR 0002 — Escalations are user tasks + forms
+
+Status: **Proposed.**
+Date: 2026-08-13.
+
+> **Scope note.** This is a **nano-workforce-local** ADR — it governs how *this app's* agent workforce
+> models human (and agent) decision points. Platform-wide ADRs live in `Magikcraft/nano-bpm/docs/adr`
+> (referenced by number + repo, e.g. "nano-bpm ADR 0026"). nano-workforce's own series continues here
+> after ADR 0001.
+
+Relates to:
+nano-bpm **ADR 0026** (Urban human surfaces + run model — the `taskInbox` surface this ADR builds on:
+a hosted task list backed by the engine's user-task search that renders a linked `.form` and posts
+completion),
+nano-bpm **ADR 0037** (execution + task listeners — the user-task lifecycle hooks this ADR leans on),
+nano-bpm **ADR 0046** (agent-as-worker vs agent-in-the-node — the duality that lets an **agent** be a
+task assignee, answering the same form a human would),
+nano-bpm **ADR 0051** (nano-workforce — the crew orchestrator whose escalations this reshapes),
+nano-bpm **ADR 0056** (the Nano agentic protocol — this ADR is the **durable** human-in-the-loop lane,
+complementary to that ADR's **ephemeral** live-steering cockpit),
+nano-workforce **ADR 0001** (this repo's ADR series),
+and the current bespoke escalation subsystem in this repo: `app/plan.ts` (`plan_escalations`,
+`plan_review_escalations`, `answerTaskEscalation`, `answerPlanEscalation`, `refreshOpenTaskEscalation`),
+`app/service.ts` (the `open_escalation_*` pointer on `pull_requests`), the `pr.persist-*-escalation`
+service workers, and the `feature-escalation-answered` / `plan-escalation-answered` resume messages in
+`resources/processes/plan-fanout.bpmn`.
+
+## Context
+
+When a fanned-out agent task cannot proceed on its own — an open question, a trial-merge conflict, a
+plan-review budget cap, a stuck PR-review loop — nano-workforce **escalates**: it parks the process and
+waits for a human decision. Today that is a hand-rolled subsystem, and the same shape recurs three times:
+
+1. **Task escalation** (`plan_escalations`, issue #25) — a fanned-out task's open question. In
+   `plan-fanout.bpmn`: an `exclusiveGateway` (`escalated?`) routes to a **service task**
+   `persist-task-escalation` (`pr.persist-task-escalation`) which writes the row + a denormalised
+   `open_task_escalation_id` pointer on the plan, then an **intermediate message-catch**
+   `wait-feature-answer` parks on `feature-escalation-answered` (correlationKey `=escalationCorrKey`).
+2. **Plan-review escalation** (`plan_review_escalations`) — a plan-review cap; a human returns a
+   `proceed | revise` directive. Same persist-service-task → message-catch shape
+   (`plan-escalation-answered`); the table is **append-only** and the review **epoch** is derived from
+   the count of answered rows.
+3. **PR review-loop escalation** (`open_escalation_*` columns on `pull_requests`, #597/#599) — a review
+   convergence that will not settle; surfaced via denormalised columns on the PR row.
+
+Answering, in every case, means: an app worker records the answer, **mirrors** it onto the task/PR row,
+**publishes the resume message**, and **re-surfaces** the next open escalation by rewriting a denormalised
+"oldest open" pointer. The "form" is a bespoke Urban page that fires when a pointer is set and prints the
+free-text `question`; the answer is a free-text string.
+
+This is a **user task + form, re-implemented by hand** — and the bug tail proves it. Every incident is a
+denormalised-pointer or free-text-contract failure: stale rows resurfacing a *dead* form after a re-plan
+(`refreshOpenTaskEscalation`), the "addressed-escalation paradox," `blank question fabricates an
+answerable escalation` (a hack to avoid an incident on an empty question), and per-run one-by-one row
+cleanup. None of these can occur under a single-source-of-truth user-task lifecycle.
+
+Crucially, **the primitives already exist**:
+
+- The engine has **native user tasks** — `UserTaskProps`, `Command::CompleteUserTask` / `UpdateUserTask`,
+  task listeners (ADR 0037), and `zeebe:assignmentDefinition` / priority / schedule parsed off the
+  `userTask` element (`engine-core/src/bpmn.rs`, `model.rs`).
+- Urban ships the **`taskInbox` surface** (ADR 0026): `GET /tasks` (list), `GET /tasks/api/tasks`
+  (`engine.searchUserTasks`), `POST /tasks/api/complete` (`engine.completeUserTask(key, variables)`),
+  rendering the linked **`.form`**. It is manifest-enabled (`surfaces.taskInbox`) and unused by nwf today.
+- Forms are `.form` assets; the Urban **form editor** (the "Delphi" authoring surface) is the tool that
+  authors them. This ADR is that editor's **first real internal customer**.
+
+## Decision
+
+**Model every decision-required escalation in nano-workforce as a native BPMN `userTask` with a linked
+`.form`, surfaced through Urban's `taskInbox`, completed with typed variables that resume the process.**
+Retire the bespoke `persist-escalation` service task → message-catch → resume-publish → denormalised-pointer
+machinery.
+
+### 1. A tiered taxonomy — not everything is a task
+
+The current code conflates three tiers; draw the line explicitly at each raise site:
+
+| Tier | Example | Mechanism |
+| --- | --- | --- |
+| **Transient** | empty-status backstop, re-request a review, a retriable step | stays **in-process** (retry / default arm) — **no task** |
+| **Advisory** | a hint, a note for the next agent | the **blackboard** (`app/blackboard.ts`) — never gates a flow |
+| **Decision-required** | proceed/revise, answer an open question, resolve a conflict, abandon | **user task + form** |
+
+Only the third tier becomes a user task. This retires the "fabricate a blank answerable escalation" hack:
+an empty question is a *non-escalation*, not a task.
+
+### 2. `serviceTask(persist) + message-catch(wait)` → one `userTask`
+
+Each `persist-*-escalation` service task and its paired intermediate message-catch collapse into a single
+`userTask` bearing a `zeebe:formDefinition` (linked `.form`) and a `zeebe:assignmentDefinition`. The engine
+owns the wait, the correlation, and the work-item state — so `escalationCorrKey`, the
+`feature-escalation-answered` / `plan-escalation-answered` messages, and the `pr.persist-*-escalation`
+workers are deleted. Completing the task carries typed variables straight back into the process.
+
+### 3. Forms are the typed escalation contract
+
+Each escalation kind gets a `.form` whose schema *is* its interface — replacing free-text question/answer:
+
+- **Task escalation** → `{ resolution: "answer" | "abandon", answer?: string }`.
+- **Plan-review escalation** → `{ directive: "proceed" | "revise", notes?: string }` — deleting the
+  hand-rolled `parsePlanEscalationDirective`; the enum + required-field validation live in the form/FEEL.
+- **Trial-merge escalation** → `{ action: "proceed" | "rebase" | "abandon", notes?: string }`.
+- **PR review-loop escalation** → `{ answer: string }` (or a kind-specific action enum).
+
+### 4. One queryable task list replaces three denormalised pointers
+
+`open_task_escalation_id`, `open_plan_escalation_id`, and the `open_escalation_*` columns on
+`pull_requests` all collapse into `engine.searchUserTasks(...)` — filterable by assignee, candidate group,
+process instance, element, age. There is **no "surfaced" field to go stale**, so the resurface / dead-form
+bug class is eliminated at the root. The plans page and any inbox read the live task search; the
+`inbox_entries` seed is the natural home for the cross-plan view.
+
+### 5. The assignee may be a human **or** an agent
+
+`zeebe:assignmentDefinition` routes a task to a specific human, a **candidate group** (e.g. the operator /
+crew leads), or — per ADR 0046 — an **agent**. An LLM worker can complete the *same* form a human would,
+via the `chat`/agent surface or a job-worker-style completer. This makes "auto-resolve with a
+slower/smarter model, else route to a human" a single lifecycle with one contract — something the bespoke
+subsystem cannot express. Agent-answered completion is still a first-class, audited task completion.
+
+### 6. SLA via a timer boundary
+
+A user task carries a due date; a **timer boundary event** provides escalation-of-the-escalation —
+reassign, notify, or auto-proceed on a default — the durable replacement for the review poller's ad-hoc
+nudge. A decision no longer hangs forever with no deadline.
+
+### 7. Audit trail from user-task history
+
+`plan_review_escalations` is append-only because the **review epoch** = count of answered plan-review
+escalations. Under this ADR the epoch is derived from **completed plan-review user tasks** (native user-task
+history / completion events), so the dedicated audit table is retired without losing the audit.
+
+## Consequences
+
+- **A whole bug class disappears.** No denormalised "surfaced" pointer ⇒ no stale/dead-form resurfacing, no
+  addressed-escalation paradox, no blank-question fabrication. The engine's single-source-of-truth
+  user-task lifecycle replaces three hand-maintained mirrors.
+- **Less code.** Delete `pr.persist-*-escalation` workers, the two resume messages + their catch events,
+  `escalationCorrKey`, `answerTaskEscalation`/`answerPlanEscalation`/`refreshOpenTaskEscalation`, the
+  denormalised columns, and the bespoke answer page — replaced by `userTask` nodes + `.form`s + the
+  existing `taskInbox` surface.
+- **Dogfoods the Delphi vision.** nwf becomes the first real consumer of the Urban form editor + user-task
+  inbox, exercising forms end to end on a live app.
+- **The third human-in-the-loop lane.** Enrolment (#152) = what work exists; visibility (#142) =
+  watch/nudge a *live* agent (ephemeral); **escalation-as-user-task** = decide *durably* when blocked. The
+  cockpit can list a worker's open escalation tasks; the two planes reinforce each other.
+- **Migration is a real refactor, not a rename.** The bespoke tables encode edge cases (epoch-from-count,
+  re-plan cleanup, trial-merge "proceed" override). The migration must preserve those semantics on the new
+  substrate and run behind tests, phased kind-by-kind.
+- **New dependency on engine user-task depth.** Assignment, candidate groups, task listeners, and timer
+  boundaries on user tasks must be exercised (some may surface gaps to file against the engine). Form
+  rendering richness is bounded by the `taskInbox`/form-editor state of the art.
+
+## Open questions
+
+- **Form-rendering fidelity.** The current `taskInbox` page is minimal (lists key/element). How rich a
+  `.form` render is needed before the answer page can be deleted — and is that the form editor's job or a
+  `taskInbox` upgrade (an nano-ide concern)?
+- **Agent-answer policy (§5).** When may an agent auto-complete vs must-route-to-human — a per-kind policy,
+  a confidence gate, or an operator toggle? How is an agent completion attributed and reversible?
+- **Assignment model.** Candidate group vs named assignee for each kind; where the operator's routing
+  preference is persisted (manifest vs app state).
+- **Cross-plan inbox surface.** Does nwf embed `taskInbox` directly, or render its own plan-aware inbox
+  page over `searchUserTasks` (matching the existing plans page), keyed through `inbox_entries`?
+- **Back-compat window.** Do in-flight escalations at migration time drain on the old path, or are they
+  re-issued as user tasks? (Prefer drain-old, issue-new, per kind.)

package/docs/adr/0003-epic-base-branch-admission.md

@@ -0,0 +1,123 @@
+# ADR 0003 — Epic base-branch admission: explicit, auto-created, and guarded
+
+Status: **Proposed.**
+Date: 2026-08-13.
+
+> **Scope note.** A **nano-workforce-local** ADR — it governs how *this app* admits an epic for
+> execution. Platform-wide ADRs live in `Magikcraft/nano-bpm/docs/adr` (referenced by number + repo).
+> Continues nano-workforce's series after ADR 0001 (ADR 0002 is planned but not yet written; see below).
+
+Relates to:
+nano-workforce **ADR 0001** (cross-repo epics + integration branches — this ADR hardens *how* an epic's
+integration branch is chosen, created, and protected),
+nano-workforce **ADR 0002** *(planned — not yet written in this repo; escalations as user tasks)*: the
+confirm / shared-base gates are human decisions that *could* later surface as user tasks; see Open questions,
+nano-bpm **ADR 0058** (the OpenAPI endpoint surface — `startPlanFanout` is a spec operation whose request
+schema this ADR changes),
+migration `019_plan_base_branch.sql` (the `plans.base_branch` column, whose example is `epic/agent-protocol`),
+and in this repo: `operations/startPlanFanout.ts` (the launch operation), `app/plan.ts`
+(`startPlan`, `normalizeBaseBranch`, `renderBaseBranchBrief`, `PLAN_TERMINAL_STATUSES`), `app/baseGuard.ts`
++ `app/github.ts` (`baseBranchLanded`, `fetchDefaultBranch`), and `resources/processes/plan-fanout.bpmn`.
+
+## Context
+
+An epic is launched through the `startPlanFanout` operation, which calls `startPlan(data, engine, parsed,
+baseBranch)`. The `base_branch` (migration 019) tells every fanned-out task agent to branch off it and open
+its PR against it (`renderBaseBranchBrief`), landing the whole epic on a long-lived integration branch that
+reaches the default branch — and any merge-to-default side effect such as auto-publishing — only when the
+integration branch is deliberately merged.
+
+Four gaps make this a footgun surface:
+
+1. **Implicit default.** `normalizeBaseBranch` maps a blank/absent value to `null`, silently meaning "target
+   the repository default branch." An operator who *meant* to name an integration branch but omitted it
+   lands every task straight onto the default branch (e.g. `main`) with **no integration buffer** — and
+   any merge-to-default side effect fires per task.
+2. **No branch creation.** Nothing creates the integration branch. `baseGuard`/`baseBranchLanded` only
+   *read* (`gh pr list`, `fetchPrBase`, `fetchDefaultBranch`). So if the named branch doesn't exist, the
+   **first task's** `git fetch origin <branch>` / `gh pr create --base <branch>` fails — a late, per-task
+   failure instead of a clean admission error.
+3. **No typo guard.** A mistyped branch name is indistinguishable from an intended new one; without
+   creation it fails late, and *with* naive creation it would silently spawn a wrong-rooted branch.
+4. **No collision guard.** Two in-flight epics can target the **same** integration branch, interleaving
+   commits and poisoning each other's base — with no warning.
+
+The pieces to fix this already exist: `fetchDefaultBranch` (default-branch identity), `PLAN_TERMINAL_STATUSES`
+(`done|failed|abandoned` → the complement is "active"), a strict `isPlausibleBranchName` allowlist, and the
+`019` example convention `epic/*`.
+
+## Decision
+
+**Every epic launch must state its base branch explicitly, and `startPlanFanout` admits it through one
+fail-fast gate** — `admitPlan(...)` — run before any task fans out, backed by a durable `ensure-base-branch`
+head step in `plan-fanout.bpmn`. The gate has four ordered rules:
+
+### 1. Required + explicit — no implicit default
+
+`baseBranch` becomes a **required** field of `StartPlanFanoutRequest`. `normalizeBaseBranch` **rejects** a
+blank/absent value (`MissingBaseBranchError` → HTTP 400) instead of returning `null`. "Land on the default
+branch" is now a **conscious, named, confirmed** choice (rule 3), never a silent fallback. The
+`base_branch == null ? default : brief` fork in the launch/prompt path is removed; `renderBaseBranchBrief`
+is always rendered. (`plans.base_branch` stays nullable in the DB **only** to grandfather pre-migration
+rows; new launches always set it.)
+
+### 2. Create-if-missing, idempotently — with an `epic/*` guard
+
+`ensureBaseBranch(repo, branch, token)`:
+- **Exists** → no-op (never reset — a reset would nuke in-flight task PRs stacked on it; a stacked epic's
+  base already exists and is left alone).
+- **Missing and matches `epic/*`** → create `refs/heads/<branch>` off the **default branch HEAD**.
+- **Missing and *not* `epic/*`** → **reject** (`BaseBranchMustExistError`): a non-`epic/*` branch must
+  already exist, so a typo can't silently spawn a wrong-rooted branch. (`epic/*` is the `019` convention.)
+
+Runs at admission (fail fast) **and** as a head `ensure-base-branch` service task in `plan-fanout.bpmn` so
+it is durable + retriable even on a re-plan.
+
+### 3. Confirm-default — naming the default branch is deliberate
+
+If the explicit target **equals the repository default** (via `fetchDefaultBranch`), admission requires an
+explicit `confirmDefaultBase: true`, else **reject** (`DefaultBaseNotConfirmedError` → 400) with a message
+spelling out the consequence ("every task lands directly on `<default>` with no integration branch; any
+merge-to-default side effect fires per task"). This is the single guardrail on the one dangerous explicit
+value.
+
+### 4. Shared-base guard — one integration branch, one epic
+
+If another plan whose `status ∉ PLAN_TERMINAL_STATUSES` (i.e. **active**) targets the **same repo + same
+base branch**, admission **rejects** (`SharedBaseError` → 409) unless `allowSharedBase: true`. **Exempt: the
+default branch** — many epics target the default concurrently and don't collide (each task PR is
+independent). The guard fires only for a **shared custom integration branch**, the genuinely dangerous case.
+
+### Recommended defaults (confirm before build)
+
+- **Hard-require flags**, not soft warnings, for rules 3 and 4: a warning in a headless submit flow is
+  ignorable; a required `confirmDefaultBase` / `allowSharedBase` is a "warn you can't skip."
+- **`epic/*` auto-create guard** (rule 2): auto-create only `epic/*`; any other non-existent name is a
+  400. Matches the `019` convention.
+
+## Consequences
+
+- **A footgun class disappears:** no silent land-on-main, no first-task-fails-on-missing-branch, no typo'd
+  wrong-rooted branch, no two-epics-one-branch interleave — all become clean admission errors.
+- **Breaking API + launch-path change.** `StartPlanFanoutRequest.baseBranch` is now required; any
+  fire-and-forget caller/CLI/epic template that omitted it will (intentionally) 400. The OpenAPI spec +
+  generated types (`nano-generated/api-io.d.ts`, controller) regenerate; the submit surface + docs update.
+- **Back-compat:** pre-migration / in-flight `base_branch = null` plans are **grandfathered** (the column
+  stays nullable; the required-ness is enforced at *admission* of new launches, not by a DB `NOT NULL`).
+- **New write permission exercised:** ref creation (already held by the token that pushes task branches).
+- **Ties into ADR 0001/0002:** this is the admission half of the integration-branch story (0001), and its
+  human gates could later be modeled as user tasks (planned ADR 0002) rather than flags — see Open questions.
+
+## Open questions
+
+- **Gates as user tasks (planned ADR 0002)?** Should `confirmDefaultBase` / shared-base become an inbox **user
+  task** ("Epic X wants to target `main` / share `epic/y` — approve?") instead of a submit-time flag? For
+  *pre-fan-out* admission a synchronous flag is simpler and fail-fast; a user task fits only if we want a
+  human in the launch loop. Deferred.
+- **Auto-create root.** Always off default HEAD — correct for a fresh integration branch. Should a stacked
+  epic be able to declare `stackOn: <branch>` so its base is auto-created off *another* epic's branch
+  rather than default? (Today: that base must pre-exist.)
+- **Convention scope.** Is `epic/*` the only auto-createable prefix, or should the app config own the
+  allowlist?
+- **Grandfathered nulls.** Leave historical `null` rows as-is, or backfill them to the (then-current)
+  default branch for a uniform read model?

package/main.ts

@@ -16,8 +16,11 @@
 // The reviewer agent (job type `senior:pr-review`) is deliberately NOT hosted here — it is an
 // EXTERNAL worker. Point a coding-agent harness at that job type (the same one that services
 // the code-first twin) so the automated review stays decoupled from the orchestration.
+import { Server } from "node:http";
 import { createNanoSdkEngineClient, runFromEnv, selectHost } from "@nanobpm/urban";
+import { type AgenticChannelHandle, mountAgenticChannel } from "./app/agentic/channel.ts";
 import { MAX_ROUNDS, pollOnce } from "./app/service.ts";
+import { envVar } from "./app/version.ts";
 
 const PORT = Number(process.env.PR_REVIEW_PORT ?? 3000);
 const POLL_MS = Number(process.env.NANO_PR_POLL_MS ?? 60_000);
@@ -40,6 +43,30 @@ const engine = await createNanoSdkEngineClient({
 // signal handler would only stop the HTTP server, leaving the poller keeping us alive).
 const app = await runFromEnv({ engine, host, port: PORT, handleSignals: false });
 
+// Agentic visibility channel (ADR 0056, epic #142). Ride the app's OWN HTTP server so the channel
+// shares the app port (no sidecar). This is the ONLY main.ts wiring for the whole epic — sibling
+// slices (H1/H3/H4) extend it by dropping a family module under `app/agentic/families/`, never here.
+// Mount only when a shared identity secret is configured, so the app never exposes an
+// unauthenticated upgrade; `app.httpServer` is a `node:http` Server once started (undefined on hosts
+// that don't surface one, e.g. Deno).
+let agentic: AgenticChannelHandle | undefined;
+const agenticSecret = envVar("NANO_AGENTIC_SECRET") ?? envVar("NANO_PR_WEBHOOK_SECRET");
+const httpServer = app.httpServer;
+if (httpServer instanceof Server) {
+  if (agenticSecret) {
+    agentic = await mountAgenticChannel({
+      server: httpServer,
+      secret: agenticSecret,
+      data: app.data,
+      log: app.log,
+    });
+  } else {
+    app.log.warn("agentic channel not mounted: set NANO_AGENTIC_SECRET (or NANO_PR_WEBHOOK_SECRET)");
+  }
+} else if (agenticSecret) {
+  app.log.warn("agentic channel not mounted: app.httpServer is not a node:http Server on this host");
+}
+
 // Review-ready poller. Self-scheduling (not setInterval) so a slow GitHub call can never
 // overlap two passes (which could double-signal `review-ready`); the next pass is scheduled
 // only after the previous one settles.
@@ -59,6 +86,13 @@ async function drainAndExit(): Promise<void> {
   if (shuttingDown) return;
   shuttingDown = true;
   if (pollTimer) clearTimeout(pollTimer);
+  // Tear the agentic families + hub down (releases the WS clients) before the app stops its HTTP
+  // server, which the channel shares.
+  if (agentic) {
+    try {
+      await agentic.teardown();
+    } catch { /* best-effort channel shutdown */ }
+  }
   try {
     await app.stop();
   } catch { /* already stopped */ }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.50.0",
+  "version": "0.52.0",
   "description": "Nano Workforce — an Agent Graph Orchestration application for Agentic SDLC: durable BPMN processes that coordinate a graph of AI agents across the software delivery lifecycle.",
   "type": "module",
   "main": "main.ts",
@@ -46,7 +46,8 @@
     "lint:fix": "biome check --write app operations workers pages components scripts e2e main.ts"
   },
   "dependencies": {
-    "@nanobpm/urban": "^0.45.0"
+    "@nanobpm/agentic": "^0.1.0",
+    "@nanobpm/urban": "^0.46.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.11",

package/prompts/plan-review.md

@@ -40,6 +40,19 @@ decomposition **from the issues**, then test the plan against it.
   `dependsOn` it. Reject a `dependsOn` edge added purely to **serialise the landing** of otherwise
   parallel work — that is not a fix, it just needlessly serialises implementation; name the pair,
   the shared surface, and which of (a)/(b) the planner should apply.
+- **Package fragmentation (Conway artifact).** The plan gives a cohesive body of work its own
+  published unit **per task** — N tasks ⇒ N npm packages / crates / services — where one library
+  with the slices as **subpath exports / subdirectories** would serve the same consumers. This is
+  the task decomposition leaking into the artifact's module boundaries: separate packages are the
+  frictionless maximum of independence, so they get chosen by default, then have to be
+  unfragmented by hand (and each extra published unit is a publish/credentials bootstrap +
+  changelog + version cadence forever). Try to disprove that each **new** published-package
+  boundary is **consumer-driven**: is there a distinct external consumer of *it* alone, an
+  intentional independent release cadence, or a different runtime tier? If not for a given
+  package, flag it and demand the remedy: **coarsen the siblings into one package** exposing
+  subpaths, landing a **wave-0 scaffold task** (manifest with the full exports map
+  pre-declared + one empty subdirectory per slice) first if the shared manifest would otherwise be
+  a merge collision. Name the packages that lack a consumer-facing justification.
 - **Non-self-contained prompt.** A task's `prompt` can't be executed without reasoning the planner
   kept to itself.
 - **Sequencing intent violated.** If the issues state an ordering (e.g. "audit the foundation

package/prompts/plan.md

@@ -157,6 +157,41 @@ Choose (1) when the surface *is* the task; choose (2) when the surface is shared
 infrastructure several distinct tasks sit on top of. Reserve plain parallel tasks
 (no shared surface) for genuinely disjoint work.
 
+### Packaging cohesion → one library, subpaths, not a package per task
+
+The shared-surface rule above pushes toward independence, and independence has a
+seductive failure mode: giving each task its **own published unit** (npm package,
+crate, service) is the *frictionless maximum* of independence — a separate
+manifest, separate exports, separate directory mean zero shared surface and zero
+merge collision. So a plan that slices a single cohesive library into N tasks will,
+left alone, tend to emit **N packages** — one per task. That is not a design; it is
+your task decomposition leaking into the artifact's module boundaries (Conway's
+Law). It has to be unfragmented by hand later, and each extra published unit is a
+one-time publish/credentials bootstrap plus a changelog and version cadence forever.
+
+So, before you slice: **a new published unit requires a consumer-facing
+justification, not merely "this is an independent task."** A new package/crate/
+service is warranted only when at least one is true:
+
+- a **distinct external consumer** imports it on its own (something outside the
+  family depends on *it*, not on its siblings);
+- it needs an **independent release cadence** (versioned and shipped separately on
+  purpose); or
+- it is a **different runtime tier** (e.g. a browser bundle vs. a server library vs.
+  a worker client) that consumers install separately.
+
+Absent one of those, the default is **one library, with the slices as subpath
+exports / subdirectories inside it** (the shape of a package that exposes several
+surfaces — e.g. `./runtime`, `./toolkit`, `./worker` — from a single manifest). The
+slices stay independent to *write*: use the
+**wave-0 scaffold task** (option 2 above) to land the library skeleton first — its
+manifest with the **full exports map pre-declared** and an empty subdirectory per
+slice — so every sibling only **adds files inside its own subdirectory** and never
+touches the shared manifest or barrel. That buys parallel-merge independence **and**
+a cohesive published artifact at the same time. Reserve genuinely separate packages
+for the consumer-facing cases above, and say in the task prompt which consumer
+justifies the split.
+
 ## Output contract
 
 Write a JSON object of **result variables** to the file named by the