@nanobpm/nano-workforce 0.50.0 → 0.52.0

package/app/agentic/loader.test.ts

@@ -0,0 +1,79 @@
+// Unit tests for the agentic family DISCOVERY loader (ADR 0056, H0 / #143).
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import { noopLog } from "../../test/log.ts";
+import { loadAgenticFamilies } from "./loader.ts";
+
+/** A discovered family module's source: exports a named `family` with the given `name`. */
+function familyModuleSource(name: string): string {
+  return `export const family = { name: ${JSON.stringify(name)}, mount() {}, teardown() {} };\n`;
+}
+
+async function withTempDir(fn: (dir: string) => Promise<void>): Promise<void> {
+  const dir = await mkdtemp(join(tmpdir(), "agentic-loader-"));
+  try {
+    await fn(dir);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+}
+
+test("discovers *.family.ts modules in sorted (deterministic) order", async () => {
+  await withTempDir(async (dir) => {
+    await writeFile(join(dir, "relay.family.ts"), familyModuleSource("relay"));
+    await writeFile(join(dir, "presence.family.ts"), familyModuleSource("presence"));
+    await writeFile(join(dir, "blackboard.family.ts"), familyModuleSource("blackboard"));
+    const families = await loadAgenticFamilies(dir, noopLog());
+    // Sorted by filename: blackboard.family.ts < presence.family.ts < relay.family.ts.
+    assertEquals(families.map((f) => f.name), ["blackboard", "presence", "relay"]);
+  });
+});
+
+test("ignores non-family files, test files, and READMEs", async () => {
+  await withTempDir(async (dir) => {
+    await writeFile(join(dir, "presence.family.ts"), familyModuleSource("presence"));
+    await writeFile(join(dir, "presence.family.test.ts"), "export const nope = 1;\n");
+    await writeFile(join(dir, "helper.ts"), "export const nope = 2;\n");
+    await writeFile(join(dir, "README.md"), "# families\n");
+    const families = await loadAgenticFamilies(dir, noopLog());
+    assertEquals(families.map((f) => f.name), ["presence"]);
+  });
+});
+
+test("a missing families directory yields no families (not an error)", async () => {
+  const families = await loadAgenticFamilies(join(tmpdir(), "does-not-exist-agentic-xyz"), noopLog());
+  assertEquals(families, []);
+});
+
+test("accepts a default export as well as a named `family` export", async () => {
+  await withTempDir(async (dir) => {
+    await writeFile(
+      join(dir, "def.family.ts"),
+      "export default { name: 'viaDefault', mount() {} };\n",
+    );
+    const families = await loadAgenticFamilies(dir, noopLog());
+    assertEquals(families.map((f) => f.name), ["viaDefault"]);
+  });
+});
+
+test("skips a module that exports no valid family, without crashing discovery", async () => {
+  await withTempDir(async (dir) => {
+    await writeFile(join(dir, "ok.family.ts"), familyModuleSource("ok"));
+    // No `family`/`default`; and a malformed one (missing mount).
+    await writeFile(join(dir, "empty.family.ts"), "export const something = 1;\n");
+    await writeFile(join(dir, "bad.family.ts"), "export const family = { name: 'bad' };\n");
+    const families = await loadAgenticFamilies(dir, noopLog());
+    assertEquals(families.map((f) => f.name), ["ok"]);
+  });
+});
+
+test("the real families/ directory discovers the copyable example no-op", async () => {
+  const families = await loadAgenticFamilies(undefined, noopLog());
+  assert(
+    families.some((f) => f.name === "example"),
+    "expected the shipped example family to be discovered",
+  );
+});

package/app/agentic/loader.ts

@@ -0,0 +1,84 @@
+// nano-workforce — the agentic family DISCOVERY loader (ADR 0056, H0 / #143).
+//
+// Siblings drop a `*.family.ts` module into `app/agentic/families/`; this loader finds it by
+// convention and imports it. There is deliberately NO central registration array for siblings to
+// append to (that would merely relocate the shared-file collision the plan review flagged): a family
+// is discovered purely by living in the conventional directory with the conventional suffix.
+//
+// A discovered module contributes its family via a default export OR a named `family` export. Any
+// `*.test.ts` file is ignored (test files never carry a family), and a module that exports no valid
+// family is skipped with a warning rather than crashing boot.
+import { readdir } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import type { Logger } from "@nanobpm/urban";
+import type { AgenticFamily } from "./registry.ts";
+
+/** The conventional directory holding sibling family modules, resolved next to this loader. */
+export const FAMILIES_DIR = join(dirname(fileURLToPath(import.meta.url)), "families");
+
+/** The filename suffix a family module must carry to be discovered. */
+const FAMILY_SUFFIX = ".family.ts";
+
+/** Read a property off an unknown object without an unsafe cast. */
+function prop(obj: object, key: string): unknown {
+  return Object.hasOwn(obj, key) ? Object.getOwnPropertyDescriptor(obj, key)?.value : undefined;
+}
+
+/** A type guard proving an unknown value structurally satisfies {@link AgenticFamily}. */
+function isAgenticFamily(candidate: unknown): candidate is AgenticFamily {
+  if (!candidate || typeof candidate !== "object") return false;
+  const name = prop(candidate, "name");
+  if (typeof name !== "string" || name.trim() === "") return false;
+  if (typeof prop(candidate, "mount") !== "function") return false;
+  const teardown = prop(candidate, "teardown");
+  return teardown === undefined || typeof teardown === "function";
+}
+
+/** Structurally validate a discovered module's contribution as an {@link AgenticFamily}. */
+function asFamily(mod: unknown): AgenticFamily | undefined {
+  if (!mod || typeof mod !== "object") return undefined;
+  const candidate = prop(mod, "family") ?? prop(mod, "default");
+  return isAgenticFamily(candidate) ? candidate : undefined;
+}
+
+/**
+ * Discover every family module under `dir` (default {@link FAMILIES_DIR}), imported in a stable
+ * (sorted-by-filename) order so mount/teardown order is deterministic across hosts. A missing
+ * directory yields no families (the epic's first slice ships before any sibling exists). A module
+ * that fails to import or exports no valid family is logged and skipped, never fatal to boot.
+ */
+export async function loadAgenticFamilies(
+  dir: string = FAMILIES_DIR,
+  log?: Logger,
+): Promise<AgenticFamily[]> {
+  let entries: string[];
+  try {
+    entries = await readdir(dir);
+  } catch (err) {
+    // A missing families directory is the expected steady state before any sibling lands.
+    if (err && typeof err === "object" && "code" in err && err.code === "ENOENT") return [];
+    throw err;
+  }
+  const files = entries
+    .filter((name) => name.endsWith(FAMILY_SUFFIX))
+    .sort();
+  const families: AgenticFamily[] = [];
+  for (const name of files) {
+    const href = pathToFileURL(join(dir, name)).href;
+    let mod: unknown;
+    try {
+      mod = await import(href);
+    } catch (err) {
+      log?.error("agentic family module failed to import", { file: name, err: String(err) });
+      continue;
+    }
+    const family = asFamily(mod);
+    if (!family) {
+      log?.warn("agentic family module exported no valid family; skipping", { file: name });
+      continue;
+    }
+    families.push(family);
+  }
+  return families;
+}

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/db/migrations/023_agentic_presence.sql

@@ -0,0 +1,30 @@
+-- Agentic visibility plane — presence & registry (ADR 0056, H1 / #144).
+--
+-- The durable supply mirror behind the agentic channel's presence family. A worker that opens the
+-- channel and sends `register` lands one row here (keyed by its instance id) carrying its declared
+-- enrolment capability (cognition/weight/family/host — an ENROLMENT attribute, NEVER a routing
+-- token), the connection it registered on, and its own heartbeat-refreshed `last_seen` liveness.
+-- Heartbeats refresh `last_seen`; `deregister`, an observed disconnect, or the presence-TTL sweep
+-- remove the row. This is the read-only supply feed the enrolment epic (#152) reads — it is advisory
+-- and NEVER gates a BPMN sequence flow.
+--
+-- The very same DDL is the single source of truth the runtime's `PresenceStore` applies through
+-- `ensureSchema()` (@nanobpm/agentic/presence, `PRESENCE_SCHEMA_SQL`). Keeping the two application
+-- paths (this boot migration and the store's guard) statement-for-statement identical is what stops
+-- a production/boot schema drift. Forward-only and additive: `CREATE ... IF NOT EXISTS` only.
+--
+-- This is the reserved prefix H0 pre-allocated for H1 (023) so parallel wave-1 siblings never
+-- independently grab "the next" migration number (H3 → 024_agentic_transcript, H4 → 025_agentic_blackboard).
+CREATE TABLE IF NOT EXISTS agentic_presence (
+  instance      TEXT PRIMARY KEY,
+  connection_id TEXT NOT NULL,
+  identity      TEXT NOT NULL,
+  cognition     TEXT,
+  weight        REAL,
+  family        TEXT,
+  host          TEXT,
+  registered_at TEXT NOT NULL,
+  last_seen     INTEGER NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_agentic_presence_last_seen ON agentic_presence (last_seen);
+CREATE INDEX IF NOT EXISTS idx_agentic_presence_connection ON agentic_presence (connection_id);

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.