@nanobpm/nano-workforce 0.49.0 → 0.51.0

package/app/agentic/registry.test.ts

@@ -0,0 +1,160 @@
+// Unit tests for the agentic family-registration seam (ADR 0056, H0 / #143).
+import { test } from "node:test";
+import { assert, assertEquals, assertRejects, assertThrows } from "#test-assert";
+import { noopLog } from "../../test/log.ts";
+import { type AgenticContext, AgenticFamilyRegistry, type AgenticFamily } from "./registry.ts";
+
+// A minimal context — the seam only threads it through to `mount`, so the tests don't need a real
+// hub. `undefined`/no-op handles are fine here; the channel test exercises the real handles.
+function fakeCtx(): AgenticContext {
+  // biome-ignore lint/suspicious/noExplicitAny: seam only forwards ctx opaquely in these tests
+  const stub: any = {};
+  return { hub: stub, registry: stub, transport: stub, data: undefined, log: noopLog() };
+}
+
+/** A family that records the order of mount/teardown calls into a shared trace. */
+function tracer(name: string, trace: string[]): AgenticFamily {
+  return {
+    name,
+    mount() {
+      trace.push(`mount:${name}`);
+    },
+    teardown() {
+      trace.push(`teardown:${name}`);
+    },
+  };
+}
+
+test("mounts families in registration order, tears them down in reverse", async () => {
+  const trace: string[] = [];
+  const reg = new AgenticFamilyRegistry();
+  reg.registerAll([tracer("a", trace), tracer("b", trace), tracer("c", trace)]);
+  assertEquals(reg.names(), ["a", "b", "c"]);
+
+  await reg.mountAll(fakeCtx());
+  assertEquals(trace, ["mount:a", "mount:b", "mount:c"]);
+
+  await reg.teardownAll(noopLog());
+  assertEquals(trace, ["mount:a", "mount:b", "mount:c", "teardown:c", "teardown:b", "teardown:a"]);
+});
+
+test("mountAll is idempotent — a second call never re-mounts", async () => {
+  const trace: string[] = [];
+  const reg = new AgenticFamilyRegistry();
+  reg.register(tracer("a", trace));
+  const ctx = fakeCtx();
+  await reg.mountAll(ctx);
+  await reg.mountAll(ctx);
+  assertEquals(trace, ["mount:a"]);
+});
+
+test("teardownAll only reverses families that actually mounted, and is idempotent", async () => {
+  const trace: string[] = [];
+  const reg = new AgenticFamilyRegistry();
+  reg.register(tracer("a", trace));
+  await reg.mountAll(fakeCtx());
+  await reg.teardownAll();
+  await reg.teardownAll();
+  assertEquals(trace, ["mount:a", "teardown:a"]);
+});
+
+test("a rejected duplicate family name protects one-family-one-slot", () => {
+  const reg = new AgenticFamilyRegistry();
+  reg.register({ name: "dup", mount() {} });
+  assertThrows(() => reg.register({ name: "dup", mount() {} }), Error, "duplicate agentic family");
+});
+
+test("registering after mount is refused", async () => {
+  const reg = new AgenticFamilyRegistry();
+  reg.register({ name: "a", mount() {} });
+  await reg.mountAll(fakeCtx());
+  assertThrows(() => reg.register({ name: "b", mount() {} }), Error, "after mount");
+});
+
+test("a family with no teardown is skipped cleanly on shutdown", async () => {
+  const trace: string[] = [];
+  const reg = new AgenticFamilyRegistry();
+  reg.register({ name: "no-teardown", mount() {
+    trace.push("mount");
+  } });
+  await reg.mountAll(fakeCtx());
+  await reg.teardownAll();
+  assertEquals(trace, ["mount"]);
+});
+
+test("one family's teardown throw is isolated and does not strand siblings", async () => {
+  const trace: string[] = [];
+  const reg = new AgenticFamilyRegistry();
+  reg.register(tracer("a", trace));
+  reg.register({
+    name: "boom",
+    mount() {
+      trace.push("mount:boom");
+    },
+    teardown() {
+      throw new Error("teardown boom");
+    },
+  });
+  await reg.mountAll(fakeCtx());
+  // Should not throw despite "boom" failing; "a" must still tear down.
+  await reg.teardownAll(noopLog());
+  assertEquals(trace, ["mount:a", "mount:boom", "teardown:a"]);
+});
+
+test("a mount failure only tears down what actually mounted", async () => {
+  const trace: string[] = [];
+  const reg = new AgenticFamilyRegistry();
+  reg.register(tracer("a", trace));
+  reg.register({
+    name: "fails",
+    mount() {
+      throw new Error("mount fails");
+    },
+    teardown() {
+      trace.push("teardown:fails");
+    },
+  });
+  await assertRejects(() => reg.mountAll(fakeCtx()), Error, "mount fails");
+  await reg.teardownAll();
+  // "fails" never completed mount, so its teardown must not run; "a" did mount, so it tears down.
+  assertEquals(trace, ["mount:a", "teardown:a"]);
+});
+
+test("mountAll self-heals after a mid-mount failure — a retry re-mounts, never a stuck no-op", async () => {
+  const trace: string[] = [];
+  const reg = new AgenticFamilyRegistry();
+  reg.register(tracer("a", trace));
+  let shouldFail = true;
+  reg.register({
+    name: "flaky",
+    mount() {
+      if (shouldFail) {
+        shouldFail = false;
+        throw new Error("mount fails once");
+      }
+      trace.push("mount:flaky");
+    },
+    teardown() {
+      trace.push("teardown:flaky");
+    },
+  });
+
+  // First attempt fails mid-mount; mountAll must reverse the partial mount and reset its own state
+  // (without the caller having to call teardownAll)...
+  await assertRejects(() => reg.mountAll(fakeCtx()), Error, "mount fails once");
+  assertEquals(trace, ["mount:a", "teardown:a"]);
+
+  // ...so a retry actually re-mounts instead of being a silent no-op (the wedged-state regression).
+  await reg.mountAll(fakeCtx());
+  assertEquals(trace, ["mount:a", "teardown:a", "mount:a", "mount:flaky"]);
+
+  await reg.teardownAll();
+  assertEquals(trace, [
+    "mount:a",
+    "teardown:a",
+    "mount:a",
+    "mount:flaky",
+    "teardown:flaky",
+    "teardown:a",
+  ]);
+});

package/app/agentic/registry.ts

@@ -0,0 +1,130 @@
+// nano-workforce — the agentic-channel family-registration SEAM (ADR 0056, H0 / #143).
+//
+// This module is OWNED by H0 (the keystone slice). It is the single extension point every sibling
+// slice of the agentic-visibility epic (#142) plugs into:
+//
+//   - H1 presence  (#144) → adds `app/agentic/families/presence.family.ts`
+//   - H3 relay     (#146) → adds `app/agentic/families/relay.family.ts`
+//   - H4 blackboard(#147) → adds `app/agentic/families/blackboard.family.ts`
+//
+// A sibling adds ONE NEW FILE under `app/agentic/families/` exporting an {@link AgenticFamily} and
+// NOTHING ELSE — it never edits `main.ts`, `drainAndExit`, or any shared boot line. The loader
+// ({@link ./loader.ts}) discovers those files by convention (`*.family.ts`) and hands them to this
+// registry, so there is no central registration list for siblings to collide on either — the
+// shared-file collision the plan review flagged is designed out, not merely relocated.
+//
+// The registry mounts families on boot (in discovery order) and tears them down in REVERSE order on
+// shutdown — the mirror-image lifecycle a stack of resources needs so a later family that depends on
+// an earlier one is torn down first.
+//
+// RESERVED forward-only migration prefixes (H0 pre-allocates these so no two siblings independently
+// grab "the next" number — current highest committed prefix is 022):
+//   - `db/migrations/023_agentic_presence.sql`   → H1 (#144)
+//   - `db/migrations/024_agentic_transcript.sql` → H3 (#146)
+//   - `db/migrations/025_agentic_blackboard.sql` → H4 (#147), only if it needs a schema change
+//
+// Invariants (ADR 0056): app-tier only, never the engine; the Camunda-8 job protocol (worker⇄engine)
+// is untouched — the agentic channel is the only new conversation; advisory semantics are preserved
+// (a family NEVER hard-locks or gates a BPMN sequence flow).
+import type { AgenticHub, ConnectionRegistry, WebSocketChannelTransport } from "@nanobpm/agentic/channel";
+import type { DataLayer, Logger } from "@nanobpm/urban";
+
+/**
+ * The reusable handle the seam threads to every family module at mount time. A sibling family uses
+ * these — and only these — so it never re-mounts the transport, re-authenticates, or reaches into
+ * the boot script.
+ */
+export interface AgenticContext {
+  /** The app-tier hub: attach a family message handler via `hub.registerFamilyHandler(...)`. */
+  readonly hub: AgenticHub;
+  /** The shared connection registry with liveness (presence detail is attached here by H1). */
+  readonly registry: ConnectionRegistry;
+  /** The listening WebSocket transport bound to the app's OWN port. */
+  readonly transport: WebSocketChannelTransport;
+  /** The app's SQLite data layer — the same store the advisory blackboard uses (may be absent). */
+  readonly data: DataLayer | undefined;
+  /** A structured logger for boot/shutdown lifecycle lines. */
+  readonly log: Logger;
+}
+
+/**
+ * One pluggable family module. A sibling slice implements this and exports it (default export, or a
+ * named `family` export) from a `*.family.ts` file under `app/agentic/families/`.
+ */
+export interface AgenticFamily {
+  /** A stable, unique name (used for ordering diagnostics, `inspect()`, and teardown logging). */
+  readonly name: string;
+  /** Attach the family's behaviour to the hub/channel. May be async. */
+  mount(ctx: AgenticContext): void | Promise<void>;
+  /** Release anything `mount` acquired. Called in REVERSE registration order on shutdown. */
+  teardown?(): void | Promise<void>;
+}
+
+/**
+ * The seam itself: collects registered families, mounts them all on boot (in registration order),
+ * and tears them down in reverse on shutdown. Mounting is idempotent-guarded (each family mounts at
+ * most once) so a double `mountAll` can never double-attach a handler.
+ */
+export class AgenticFamilyRegistry {
+  readonly #families: AgenticFamily[] = [];
+  readonly #mounted: AgenticFamily[] = [];
+  #isMounted = false;
+
+  /** Register a family. Rejects a duplicate name so two slices cannot silently claim one slot. */
+  register(family: AgenticFamily): void {
+    if (this.#isMounted) {
+      throw new Error(`cannot register agentic family "${family.name}" after mount`);
+    }
+    if (this.#families.some((f) => f.name === family.name)) {
+      throw new Error(`duplicate agentic family name "${family.name}"`);
+    }
+    this.#families.push(family);
+  }
+
+  /** Register several families at once (the loader hands the discovered set here). */
+  registerAll(families: Iterable<AgenticFamily>): void {
+    for (const family of families) this.register(family);
+  }
+
+  /** The registered family names, in registration order. Surfaced in `inspect()`/logs. */
+  names(): string[] {
+    return this.#families.map((f) => f.name);
+  }
+
+  /** Mount every registered family, in registration order. A no-op if already mounted. */
+  async mountAll(ctx: AgenticContext): Promise<void> {
+    if (this.#isMounted) return;
+    this.#isMounted = true;
+    try {
+      for (const family of this.#families) {
+        await family.mount(ctx);
+        // Track post-mount so a failure mid-mount only tears down what actually mounted.
+        this.#mounted.push(family);
+      }
+    } catch (err) {
+      // A mid-mount failure must not wedge the registry at #isMounted=true (which would make every
+      // later mountAll a silent no-op). Reuse the canonical teardown to reverse the partial mount and
+      // reset the flag, leaving the registry clean and re-mountable, then rethrow to the caller.
+      await this.teardownAll(ctx.log);
+      throw err;
+    }
+  }
+
+  /**
+   * Tear every mounted family down in REVERSE mount order. Each teardown is isolated: a throw is
+   * logged (when a logger is supplied) and swallowed so one family's failure cannot strand another's
+   * cleanup. Safe to call more than once; the second call is a no-op.
+   */
+  async teardownAll(log?: Logger): Promise<void> {
+    while (this.#mounted.length > 0) {
+      const family = this.#mounted.pop();
+      if (!family?.teardown) continue;
+      try {
+        await family.teardown();
+      } catch (err) {
+        log?.error("agentic family teardown failed", { family: family.name, err: String(err) });
+      }
+    }
+    this.#isMounted = false;
+  }
+}

package/docs/adr/0001-cross-repo-epics-and-artifact-wait-gates.md

@@ -0,0 +1,151 @@
+# ADR 0001 — Cross-repo epics, release-ordered integration, and generic artifact wait-gates
+
+Status: **Proposed.**
+Date: 2026-08-13.
+
+> **Scope note.** This is a **nano-workforce-local** ADR — it governs how *this app's* agent
+> workforce decomposes and integrates epics. The platform-wide ADRs live in
+> `Magikcraft/nano-bpm/docs/adr` (referenced here by their number + repo, e.g. "nano-bpm ADR 0056").
+> nano-workforce's own decisions start their own series here at 0001.
+
+Relates to:
+nano-bpm **ADR 0051** (nano-workforce — the crew orchestrator this app implements),
+nano-bpm **ADR 0056** (the Nano agentic protocol — the first consumer/producer *pair* that forced this
+question: the hub epic https://github.com/nanobpm/nano-workforce/issues/142 and the worker epic
+https://github.com/jwulf/c8ctl-plugin-nano/issues/38 live in **different repos** yet share one
+published contract),
+the **review-ready poller** in `main.ts` (a bespoke "wait for an external condition, then correlate a
+message" loop — the seed this ADR generalizes into a first-class wait-gate),
+and nano-bpm **ADR 0059** (the app-hosted OpenAPI hook surface these gates would be signalled through).
+
+## Context
+
+nano-workforce executes an epic as a **single-repo** unit, and every load-bearing piece assumes it:
+
+- **The repo is epic-level, not task-level.** `Plan.repo` carries the repository; `PlanTask`
+  (`app/plan.ts`) has **no** `repo` field. Fan-out clones *the epic's* repo for every slice.
+- **Integration converges on one base branch in one repo.** The epic lands on a base branch; slices
+  PR into it; the merge-loop trial-merges the set and merges the epic (nano-bpm ADR 0051 machinery:
+  wave gates, base-branch guards, merge-loop reconciliation).
+- **There is no "publish" step and no "wait for the outside world" primitive.** The only wait nwf does
+  is the hand-rolled review-ready poller in `main.ts`, which polls GitHub and correlates a
+  `review-ready` message. It is not reusable and knows only about PR reviews.
+
+But real delivery in this ecosystem is **cross-repo by construction**. Shared libraries
+(`@nanobpm/urban`, `@nanobpm/agentic`) are published from one repo and consumed downstream (this app,
+c8ctl). The `urban → nano-workforce → c8ctl` chain is exactly a producer→consumer graph across repos
+with an npm publish in the middle. Building the agentic visibility plane surfaced three concrete gaps:
+(a) no per-task repo, (b) no release/publish step, (c) no wait-for-external-artifact primitive.
+
+The temptation is to answer all three at once by making nwf a cross-repo, release-orchestrating
+engine. That is a real redesign of the integration model and its highest-risk parts. Before paying for
+it, note that **most cross-repo coupling in practice is a *versioned contract*, not a merge order** —
+and a contract can be consumed *after* it is published, with no live cross-repo sequencing at all.
+
+## Decision
+
+### 1. Prefer contract-coupled per-repo epics over cross-repo epics (the default)
+
+When two sides of a feature share a **versioned contract** — a published package plus a **conformance
+corpus** both sides are held to — split the work into **one single-repo epic per repo**, each building
+against the **already-published** contract. They coordinate through the contract, never through a merge
+order. Neither epic waits on the other's code.
+
+The agentic visibility plane is exactly this and ships this way, as **two** epics:
+
+- **producer:** https://github.com/jwulf/c8ctl-plugin-nano/issues/38 (`nano work` → REGISTER/SERVE/relay);
+- **hub + cockpit:** https://github.com/nanobpm/nano-workforce/issues/142.
+
+Both consume the published `@nanobpm/agentic` and are held to `@nanobpm/agentic/protocol/conformance`.
+This keeps nwf's proven single-repo integration model **entirely intact** and is the default posture
+for any producer/consumer pair that can be expressed against a stable contract.
+
+### 2. A generic artifact-readiness wait-gate (not npm-specific)
+
+Generalize the review-ready poller into a **first-class, durable wait-gate**: a service task that
+**polls a declared readiness probe with backoff until it is satisfied or a timeout escalates**, then
+lets the flow proceed (or correlates a message). It is modeled on the engine (timer + receive), so a
+worker or hub restart **resumes** the wait rather than losing it.
+
+The probe is **declared as data, not code** — a `ReadinessProbe` descriptor with a `kind` and pluggable
+matchers, so authors add readiness sources without editing the BPMN or the worker:
+
+```jsonc
+// ReadinessProbe — the gate is agnostic to what "ready" means.
+{
+  "kind": "http",                       // http | command | npm | oci | git-ref | github-release | github-check | file
+  "target": "https://example/health",  // URL | shell command | "pkg@version" | "image:tag" | "owner/repo@ref" | path
+  "match": { "status": 200 },           // per-kind predicate (status/body, exit code/stdout, version present, digest, …)
+  "poll":  { "everyMs": 15000, "timeoutMs": 1800000, "backoff": "exponential" },
+  "onTimeout": "escalate"               // escalate (default) | fail | continue
+}
+```
+
+Invariants:
+
+- **Never npm-specific.** `npm` is *one* kind among many; `command` is the escape hatch that subsumes
+  almost anything (`gh`, `curl`, `docker manifest inspect`, a custom probe) for cases no built-in kind
+  covers. Adding a kind is a new matcher, not a schema change.
+- **Bounded.** A probe that never goes green must **time out and escalate** (mirroring the per-task
+  escalation path) — a hanging probe can never wedge a plan.
+- **Idempotent / resumable.** The gate only *reads* readiness; it holds no state a re-run could corrupt,
+  so a restarted worker simply re-probes.
+
+This is immediately useful well beyond releases: waiting on CI, a downstream deploy, an external
+system, a human approval, or a produced artifact.
+
+### 3. The shared-library bump stays a manual maintainer seam — for now
+
+A downstream version bump (e.g. `@nanobpm/urban` → this app) after an upstream release is handled by a
+maintainer **outside** the epic, until §4 lands. It is cheap, low-risk, and rare relative to the
+intra-repo work of an epic. This is the deliberate, documented seam that lets §1 stay simple: the
+*only* cross-repo dependency in the agentic plane (nano-ide `UrbanApp.httpServer`,
+https://github.com/nanobpm/nano-ide/issues/221 → an `@nanobpm/urban` release → a bump here) is a
+one-line human step, not a reason to build a cross-repo engine.
+
+### 4. Release-ordered cross-repo integration (the "release DAG") — deferred, sketched
+
+Some future work genuinely cannot decouple: a consumer needs a producer's **new** release *mid-epic*.
+For those cases only, model integration as a **DAG across independent per-repo merge trains**:
+
+```
+producer PRs → merge → publish → [artifact wait-gate §2] → consumer PRs open/build → merge
+```
+
+This replaces the single-epic-branch assumption **for those cases**, and requires, in order:
+
+1. **Per-task repo.** Add `repo` to `PlanTask`, derive it from each sub-issue (`parseIssue` already
+   yields `owner/repo`), and thread it into the `io.nanobpm.agentTask.repository` clone header. The
+   merge/review/finalize workers are *already* repo-parameterized (they take `repo` per PR and load the
+   merge protocol per repo), so this is mostly plan/task plumbing.
+2. **A release task type.** bump version → merge → **§2 wait-gate on artifact availability** → signal
+   downstream. Publish is at-least-once; the task must tolerate a re-run (mirror the idempotent
+   `scripts/publish.mjs` "skip already-published" discipline).
+3. **Cross-train ordering.** A meta-plan (or a first-class multi-repo epic) that sequences the per-repo
+   trains and their gates.
+
+This is its **own follow-up epic with its own design**. Do **not** build it speculatively — §1 removes
+the need for the foreseeable roadmap, and §2 is the reusable building block it will stand on.
+
+## Consequences
+
+- The agentic visibility plane ships **now** as two single-repo epics; nwf's integration model
+  (base-branch, trial-merge, merge-loop, wave gates) is untouched and unrisked.
+- nwf gains a durable **"wait for the world"** primitive it currently fakes with the bespoke review
+  poller; the poller can later be re-expressed as one `github-check`/`http` gate.
+- New surface to own: the `ReadinessProbe` kinds. A malformed or hanging probe is bounded by the
+  mandatory timeout+escalation, so it cannot stall a plan.
+- Shared-library bumps stay manual until §4 — an accepted cost given their frequency.
+- When §4 is eventually built, §1 + §2 mean it is *additive* (a new integration topology + a release
+  task) rather than a rewrite.
+
+## Open questions
+
+- **Probe extensibility model:** a curated registry of `kind`s vs leaning on the `command` escape hatch
+  for the long tail — and how a probe's credentials/secrets are supplied without leaking into logs.
+- **Where cross-train ordering lives (§4):** a meta-plan across existing epics, or a genuine
+  first-class multi-repo epic with per-task repos.
+- **Per-repo divergence when per-task repo lands:** merge protocol, required checks, Copilot-review
+  provisioning (not available on every repo), and push auth all differ per repo.
+- **Gate signalling:** in-flow receive task vs an out-of-band message correlated by an app-side poller
+  (the review-ready shape) — likely both, chosen per use.

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.49.0",
+  "version": "0.51.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.44.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