@nanobpm/nano-workforce 0.102.1 → 0.103.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [0.103.0](https://github.com/nanobpm/nano-workforce/compare/v0.102.1...v0.103.0) (2026-08-19)
+
+
+### Features
+
+* **feature:** intake-time readiness gate for single-issue runs ([#295](https://github.com/nanobpm/nano-workforce/issues/295)) ([#349](https://github.com/nanobpm/nano-workforce/issues/349)) ([09b519b](https://github.com/nanobpm/nano-workforce/commit/09b519be9ff21c8821b3ec3e0687541710be718b)), closes [owner/repo#N](https://github.com/owner/repo/issues/N)
+
 ## [0.102.1](https://github.com/nanobpm/nano-workforce/compare/v0.102.0...v0.102.1) (2026-08-19)
 
 

package/app/feature.test.ts

@@ -307,3 +307,74 @@ test("startFeature: persists the real issue title when the fetch succeeds", asyn
     else process.env["GITHUB_TOKEN"] = prevTok;
   }
 });
+
+test("startFeature: no readiness ⇒ readinessProbes/probeTimeout/gateKey seeded null (gate skipped)", async () => {
+  let captured: any = null;
+  const engine = {
+    createInstance: (req: any) => {
+      captured = req;
+      return Promise.resolve({ processInstanceKey: "PI-R0" });
+    },
+  } as any;
+  await startFeature(memData({ feature_runs: { rows: [], key: "feature_key" } }), engine, PARSED, "main", false, false);
+  const v = captured.variables;
+  assertEquals(v.readinessProbes, null);
+  assertEquals(v.probeTimeout, null);
+  assertEquals(v.gateKey, null);
+  assertEquals(v.resolvedArtifacts, null);
+});
+
+test("startFeature: readiness probes seed the gate variables + a non-blank correlation key", async () => {
+  let captured: any = null;
+  const engine = {
+    createInstance: (req: any) => {
+      captured = req;
+      return Promise.resolve({ processInstanceKey: "PI-R1" });
+    },
+  } as any;
+  const probes = [
+    {
+      kind: "capability",
+      target: "github-releases:nanobpm/nano-bpm",
+      match: { package: "@nanobpm/engine-wasm", capabilityRef: "nanobpm/nano-bpm#631" },
+      onTimeout: "escalate",
+    },
+  ] as any;
+  await startFeature(
+    memData({ feature_runs: { rows: [], key: "feature_key" } }),
+    engine,
+    PARSED,
+    "main",
+    false,
+    false,
+    null,
+    { probes, probeTimeout: "PT30M" },
+  );
+  const v = captured.variables;
+  assertEquals(v.readinessProbes, probes);
+  assertEquals(v.probeTimeout, "PT30M");
+  // The preflight probe worker requires a non-blank gateKey to publish readiness-ready on.
+  assertEquals(v.gateKey, "feature-readiness:owner/repo#42");
+  assertEquals(v.resolvedArtifacts, null);
+});
+
+test("startFeature: probes without a probeTimeout fail fast (both are load-bearing together)", async () => {
+  const engine = { createInstance: () => Promise.resolve({ processInstanceKey: "PI-R2" }) } as any;
+  let threw = false;
+  try {
+    await startFeature(
+      memData({ feature_runs: { rows: [], key: "feature_key" } }),
+      engine,
+      PARSED,
+      "main",
+      false,
+      false,
+      null,
+      { probes: [{ kind: "command", target: "x" }] as any, probeTimeout: null },
+    );
+  } catch (err) {
+    threw = true;
+    assertEquals((err as Error).message.includes("probeTimeout"), true);
+  }
+  assertEquals(threw, true);
+});

package/app/feature.ts

@@ -17,8 +17,20 @@
 import type { DataLayer, EngineClient } from "@nanobpm/urban";
 import { coalesceTitle, fetchIssueTitle } from "./github.ts";
 import { ESCALATION_SLA_TIMEOUT, normalizeBaseBranch, type ParsedIssue, renderBaseBranchBrief } from "./plan.ts";
+import type { ReadinessProbe } from "./readiness.ts";
 import { deriveListBucket, deriveStage } from "./stage.ts";
 
+/** Optional intake-time readiness gate for a feature run (issue #295): the `capability`/`command`/…
+ * probes the run must ALL satisfy before its implementation agent is dispatched (parked, durably, at
+ * the leading readiness preflight in feature.bpmn), plus the single ISO-8601 bound the preflight's
+ * escalation timers fire off. Both are DERIVED once from the submitted `readiness`/`blockedOn` intake
+ * by {@link parseFeatureReadiness} (app/featureReadiness.ts). Empty/absent ⇒ the gate is skipped and
+ * the run proceeds straight to implementation, exactly as today's submissions do. */
+export interface FeatureReadinessOptions {
+  readonly probes?: ReadinessProbe[];
+  readonly probeTimeout?: string | null;
+}
+
 /** The BPMN process this module drives (resources/processes/feature.bpmn). */
 export const FEATURE_PROCESS_ID = "feature";
 
@@ -339,7 +351,22 @@ export async function startFeature(
   converge: boolean,
   autoMerge: boolean,
   customInstructions: string | null = null,
+  readiness: FeatureReadinessOptions = {},
 ) {
+  // Intake-time readiness gate (issue #295): the probes the run must satisfy before it implements,
+  // and the bound its preflight escalation timers fire off. Both are load-bearing together —
+  // `pr.readiness-probe` rejects a blank `probeTimeout` and the preflight timers read `=probeTimeout`
+  // — so a non-empty probe set seeded without a bound would incident at runtime. Fail fast at the
+  // start door instead (mirroring `startPlan`); `parseFeatureReadiness` always derives the two
+  // together, so this only fires for a mis-seeded direct caller.
+  const readinessProbes = readiness.probes && readiness.probes.length > 0 ? readiness.probes : null;
+  if (readinessProbes && (readiness.probeTimeout ?? "").trim() === "") {
+    throw new Error(
+      `startFeature(${parsed.planKey}): ${readinessProbes.length} readiness probe(s) seeded without a ` +
+        "probeTimeout — the preflight escalation timers (=probeTimeout) and pr.readiness-probe both require " +
+        "a non-blank bound. Derive it via parseFeatureReadiness before starting a gated feature.",
+    );
+  }
   // Operator free-text steering for the implementation agent (issue #172 follow-on): blank/absent →
   // null so the implement task's `appendPrompt` FEEL (`customInstructions = null`) skips the block
   // rather than appending an empty "Operator custom instructions" heading.
@@ -447,6 +474,21 @@ export async function startFeature(
       // task's `appendPrompt` FEEL (feature.bpmn). Null when none was supplied; persists on the
       // instance so it also rides the answer-loop redispatch back into the same implement task.
       customInstructions: instructions,
+      // Intake-time readiness gate (issue #295): the leading preflight the feature run parks on until
+      // every declared probe goes green (feature.bpmn `gw-readiness` → `readiness-preflight`). A
+      // submission with NO readiness carries `null` here, so the gateway routes straight to
+      // `ensure-base-branch` and the run implements immediately — behaviour unchanged for today's
+      // features. `probeTimeout` bounds the preflight's escalation timers (derived once from the same
+      // probes); `gateKey` is the non-blank correlation key the probe worker publishes
+      // `readiness-ready` on (required even in the preflight, which reads the probe's synchronous
+      // result); `resolvedArtifacts` is filled by the preflight on green — the exact `pkg@version`s
+      // first carrying each awaited capability — and rides the implement task's `appendPrompt` so the
+      // agent bumps the consumer dependency to exactly the bound version. Seeded `null` so a
+      // gate-less run still resolves the variable in that FEEL instead of raising an incident.
+      readinessProbes,
+      probeTimeout: readinessProbes ? (readiness.probeTimeout ?? null) : null,
+      gateKey: readinessProbes ? `feature-readiness:${parsed.planKey}` : null,
+      resolvedArtifacts: null,
     },
   });
   const processKey = processInstanceKey == null ? null : String(processInstanceKey);

package/app/featureReadiness.test.ts

@@ -0,0 +1,165 @@
+// Unit coverage for the feature-intake readiness gate desugaring (issue #295).
+//
+// `parseFeatureReadiness` turns a submitted feature's optional `readiness`/`blockedOn` intake into the
+// `readinessProbes` + `probeTimeout` process variables the feature.bpmn preflight runs. These tests
+// pin the desugaring: full descriptors round-trip through `parseProbe`, `blockedOn` desugars to
+// `capability` probes (with `consumerPackage`) or `command` state probes (fallback), the bound is
+// derived, and malformed intake fails loudly at submit.
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import { parseFeatureReadiness } from "./featureReadiness.ts";
+
+const ENV = { NANO_READINESS_POLL_TIMEOUT: "PT30M" } as Record<string, string | undefined>;
+
+test("parseFeatureReadiness: no intake ⇒ empty probes, null bound (gate skipped)", () => {
+  assertEquals(parseFeatureReadiness(undefined, ENV), { probes: [], probeTimeout: null });
+  assertEquals(parseFeatureReadiness({}, ENV), { probes: [], probeTimeout: null });
+  assertEquals(parseFeatureReadiness({ readiness: [], blockedOn: [] }, ENV), { probes: [], probeTimeout: null });
+});
+
+test("parseFeatureReadiness: blockedOn + consumerPackage ⇒ capability probes with derived bound", () => {
+  const out = parseFeatureReadiness(
+    { blockedOn: ["nanobpm/nano-bpm#631", "nanobpm/nano-bpm#808"], consumerPackage: "@nanobpm/engine-wasm" },
+    ENV,
+  );
+  assertEquals(out.probes.length, 2);
+  assertEquals(out.probes[0], {
+    kind: "capability",
+    target: "github-releases:nanobpm/nano-bpm",
+    match: { package: "@nanobpm/engine-wasm", capabilityRef: "nanobpm/nano-bpm#631" },
+    onTimeout: "escalate",
+  });
+  assertEquals(out.probes[1].match?.capabilityRef, "nanobpm/nano-bpm#808");
+  // Every derived probe shares the env default, so the bound is that default.
+  assertEquals(out.probeTimeout, "PT30M");
+});
+
+test("parseFeatureReadiness: blockedOn without consumerPackage ⇒ command state probes (merged-is-enough)", () => {
+  const out = parseFeatureReadiness({ blockedOn: ["octo/cat#7"] }, ENV);
+  assertEquals(out.probes[0], {
+    kind: "command",
+    target: "gh api repos/octo/cat/issues/7 --jq .state",
+    match: { stdoutIncludes: "closed" },
+    onTimeout: "escalate",
+  });
+  assertEquals(out.probeTimeout, "PT30M");
+});
+
+test("parseFeatureReadiness: full readiness descriptors round-trip through parseProbe", () => {
+  const out = parseFeatureReadiness(
+    {
+      readiness: [
+        { kind: "http", target: "https://example.test/health", match: { status: 200 } },
+        { kind: "command", target: "make ready" },
+      ],
+    },
+    ENV,
+  );
+  assertEquals(out.probes.length, 2);
+  assertEquals(out.probes[0].kind, "http");
+  assertEquals(out.probes[0].match?.status, 200);
+  assertEquals(out.probes[1].kind, "command");
+});
+
+test("parseFeatureReadiness: readiness + blockedOn concatenate", () => {
+  const out = parseFeatureReadiness(
+    { readiness: [{ kind: "command", target: "make ready" }], blockedOn: ["octo/cat#7"] },
+    ENV,
+  );
+  assertEquals(out.probes.length, 2);
+  assertEquals(out.probes[0].kind, "command");
+  assertEquals(out.probes[1].target, "gh api repos/octo/cat/issues/7 --jq .state");
+});
+
+test("parseFeatureReadiness: a longer per-probe budget wins the derived bound", () => {
+  const out = parseFeatureReadiness(
+    {
+      readiness: [
+        { kind: "command", target: "a", poll: { timeoutMs: 60_000 } },
+        { kind: "command", target: "b", poll: { timeoutMs: 3_600_000 } },
+      ],
+    },
+    ENV,
+  );
+  assertEquals(out.probeTimeout, "PT3600S");
+});
+
+test("parseFeatureReadiness: a bare repo#N handle is rejected (cannot name a provenance repo)", () => {
+  let threw = false;
+  try {
+    parseFeatureReadiness({ blockedOn: ["nano-bpm#631"], consumerPackage: "@nanobpm/engine-wasm" }, ENV);
+  } catch (err) {
+    threw = true;
+    assertEquals((err as Error).message.includes("owner/repo#123"), true);
+  }
+  assertEquals(threw, true);
+});
+
+test("parseFeatureReadiness: a handle whose repo carries shell metacharacters is rejected (no injection into the command probe)", () => {
+  // The `command` fallback interpolates `parsed.repo` into a shell string run via `exec`. `parseIssue`'s
+  // `owner/repo#N` branch matches `[^#]+` for the slug, so a crafted handle could smuggle `;`/`$()`/backticks
+  // into the readiness worker's shell. Desugaring MUST reject any repo that isn't a valid GitHub slug.
+  for (const evil of [
+    "octo/cat; rm -rf /#7",
+    "octo/cat$(touch pwned)#7",
+    "octo/`whoami`#7",
+    "octo/cat rm#7",
+  ]) {
+    let threw = false;
+    try {
+      parseFeatureReadiness({ blockedOn: [evil] }, ENV);
+    } catch (err) {
+      threw = true;
+      assertEquals((err as Error).message.includes("owner/repo"), true);
+    }
+    assertEquals(threw, true);
+  }
+});
+
+test("parseFeatureReadiness: a non-string blockedOn entry is rejected", () => {
+  let threw = false;
+  try {
+    parseFeatureReadiness({ blockedOn: [42] }, ENV);
+  } catch {
+    threw = true;
+  }
+  assertEquals(threw, true);
+});
+
+test("parseFeatureReadiness: a blank consumerPackage is rejected", () => {
+  let threw = false;
+  try {
+    parseFeatureReadiness({ blockedOn: ["octo/cat#7"], consumerPackage: "   " }, ENV);
+  } catch (err) {
+    threw = true;
+    assertEquals((err as Error).message.includes("consumerPackage"), true);
+  }
+  assertEquals(threw, true);
+});
+
+test("parseFeatureReadiness: a malformed readiness descriptor fails loudly (unknown kind)", () => {
+  let threw = false;
+  try {
+    parseFeatureReadiness({ readiness: [{ kind: "bogus", target: "x" }] }, ENV);
+  } catch {
+    threw = true;
+  }
+  assertEquals(threw, true);
+});
+
+test("parseFeatureReadiness: a non-array readiness/blockedOn is rejected", () => {
+  let a = false;
+  let b = false;
+  try {
+    parseFeatureReadiness({ readiness: { kind: "command", target: "x" } }, ENV);
+  } catch {
+    a = true;
+  }
+  try {
+    parseFeatureReadiness({ blockedOn: "octo/cat#7" }, ENV);
+  } catch {
+    b = true;
+  }
+  assertEquals(a, true);
+  assertEquals(b, true);
+});

package/app/featureReadiness.ts

@@ -0,0 +1,151 @@
+// nano-workforce — feature-intake readiness gate desugaring (issue #295).
+//
+// The intake-time half of the durable readiness gate for a SINGLE-issue feature run. A submitted
+// feature may carry an optional `readiness` (one or more full {@link ReadinessProbe} descriptors) or
+// the ergonomic shorthand `blockedOn` — a list of upstream issue/PR handles the feature must wait to
+// land before its implementation agent is dispatched. This module turns either form into the SAME
+// `readinessProbes` + `probeTimeout` process variables the (existing) readiness-gate preflight in
+// `resources/processes/feature.bpmn` runs — reusing the production probe kinds, the escalation form,
+// and the `capability` late-bind primitive verbatim (derivation over duplication). No new subsystem:
+// this is intake plumbing on top of `app/readiness.ts` (#258) and the `capability` kind (#274).
+//
+// `blockedOn` desugars per handle:
+//   • With a declared `consumerPackage` (the cross-repo case — e.g. a wfd feature gated on
+//     `@nanobpm/engine-wasm` carrying `nanobpm/nano-bpm#631`) → a `capability` probe that resolves
+//     "which published `pkg@version` FIRST carries this handle?" from publish provenance and
+//     late-binds the resolved `pkg@version` back into the run (`resolvedArtifacts`), so the agent can
+//     bump the consumer dependency to exactly that version.
+//   • Without a `consumerPackage` (no published-artifact edge applies) → a `command` probe that goes
+//     green once the referenced issue/PR is closed/merged (`gh api …/issues/<n> --jq .state`), the
+//     "merged is enough" fallback.
+//
+// The derivation is pure (no I/O, no engine) so it is trivially unit-testable — the seam
+// `startFeature` calls at submit to seed the gate.
+import { parseIssue } from "./plan.ts";
+import {
+  DEFAULT_READINESS_TIMEOUT,
+  parseProbe,
+  type ReadinessProbe,
+  readinessTimeout,
+} from "./readiness.ts";
+import { isoDurationToMs } from "./reviewWait.ts";
+
+/** The raw intake shape a submitted feature may carry (all optional). `readiness` is one or more
+ * full {@link ReadinessProbe} descriptors; `blockedOn` is the ergonomic shorthand — a list of
+ * upstream `owner/repo#N` handles; `consumerPackage` is the npm package whose publish provenance the
+ * `blockedOn` shorthand resolves the handles against (e.g. `@nanobpm/engine-wasm`). */
+export interface FeatureReadinessInput {
+  readonly readiness?: unknown;
+  readonly blockedOn?: unknown;
+  readonly consumerPackage?: unknown;
+}
+
+/** The desugared gate: the probes the feature must satisfy before it implements, and the single
+ * ISO-8601 bound the preflight's escalation timers fire off (the LONGEST of the probes' derived
+ * timeouts, so no probe is cut short). `probes` is empty when the feature declared no readiness —
+ * the gate is then skipped and the run proceeds straight to implementation (behaviour unchanged). */
+export interface FeatureReadiness {
+  readonly probes: ReadinessProbe[];
+  readonly probeTimeout: string | null;
+}
+
+function isNonEmptyString(v: unknown): v is string {
+  return typeof v === "string" && v.trim() !== "";
+}
+
+/** A valid GitHub `owner/repo` slug: both segments are restricted to the characters GitHub itself
+ * allows (alphanumerics, `-`, `_`, `.`). `parseIssue`'s shorthand branch matches `[^#]+` for the
+ * slug, so it would otherwise admit shell metacharacters (`;`, `$( )`, backticks, spaces) that get
+ * interpolated verbatim into the `command` probe's `exec` string (and the `capability` target).
+ * Constraining the slug here shuts that injection surface for the whole `blockedOn` desugaring. */
+const GITHUB_SLUG = /^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/;
+
+/** Normalise a single `blockedOn` handle into a `capability` (with `consumerPackage`) or `command`
+ * (fallback) probe. The handle MUST parse as a full `owner/repo#N` reference — a bare `repo#N`
+ * cannot name a provenance source repo unambiguously, so it fails loudly here rather than desugaring
+ * to a probe that can never resolve. */
+function desugarHandle(handle: string, consumerPackage: string | null): ReadinessProbe {
+  const parsed = parseIssue(handle.trim());
+  if (!parsed) {
+    throw new Error(
+      `feature readiness: blockedOn handle '${handle}' must be a full 'owner/repo#123' reference ` +
+        "(a bare 'repo#123' cannot name the upstream provenance repo)",
+    );
+  }
+  // `parsed.number` is numeric (via `Number`), but `parsed.repo` is an unconstrained slug that lands in
+  // a shell `command` target — reject anything that isn't a plain GitHub `owner/repo` before we build it.
+  if (!GITHUB_SLUG.test(parsed.repo)) {
+    throw new Error(
+      `feature readiness: blockedOn handle '${handle}' has an invalid 'owner/repo' slug — only ` +
+        "alphanumerics, '-', '_' and '.' are allowed in each segment",
+    );
+  }
+  if (consumerPackage) {
+    // The `capability` edge (#274): resolve which published `<consumerPackage>@version` first carries
+    // this upstream handle and late-bind that `pkg@version` back into the run. The provenance source
+    // repo is the handle's own repo (where the upstream lands and publishes).
+    return {
+      kind: "capability",
+      target: `github-releases:${parsed.repo}`,
+      match: { package: consumerPackage, capabilityRef: parsed.planKey },
+      // A stuck/never-publishing upstream must ESCALATE (bounded) — never fail or proceed unbound.
+      onTimeout: "escalate",
+    };
+  }
+  // Fallback (no published-artifact edge): "merged is enough". `gh` reads its token from the ambient
+  // env (like the `github-check`/`capability` kinds), and PRs are issues in the REST API, so a single
+  // `/issues/<n>` state check covers both an issue being closed and a PR being merged (→ closed).
+  return {
+    kind: "command",
+    target: `gh api repos/${parsed.repo}/issues/${parsed.number} --jq .state`,
+    match: { stdoutIncludes: "closed" },
+    onTimeout: "escalate",
+  };
+}
+
+/** Parse + desugar a feature's optional intake readiness into the gate's `readinessProbes` +
+ * `probeTimeout`. Accepts EITHER the full `readiness` descriptor list OR the `blockedOn` shorthand
+ * (or both — they concatenate). Returns an empty probe set (gate skipped) when neither is present.
+ *
+ * Throws a descriptive error on a malformed descriptor (via {@link parseProbe}), a `blockedOn` entry
+ * that is not a string, an unparseable handle, or a `consumerPackage` that is present but blank — a
+ * mis-declared gate must fail loudly at submit, never wait forever at runtime. */
+export function parseFeatureReadiness(
+  input: FeatureReadinessInput | null | undefined,
+  env: Record<string, string | undefined> = process.env,
+): FeatureReadiness {
+  const probes: ReadinessProbe[] = [];
+  if (input && input.consumerPackage !== undefined && !isNonEmptyString(input.consumerPackage)) {
+    throw new Error("feature readiness: 'consumerPackage' must be a non-blank package name when supplied");
+  }
+  const consumerPackage = input && isNonEmptyString(input.consumerPackage) ? input.consumerPackage.trim() : null;
+
+  if (input?.readiness !== undefined && input.readiness !== null) {
+    if (!Array.isArray(input.readiness)) {
+      throw new Error("feature readiness: 'readiness' must be an array of probe descriptors");
+    }
+    for (const raw of input.readiness) probes.push(parseProbe(raw));
+  }
+
+  if (input?.blockedOn !== undefined && input.blockedOn !== null) {
+    if (!Array.isArray(input.blockedOn)) {
+      throw new Error("feature readiness: 'blockedOn' must be an array of 'owner/repo#123' handles");
+    }
+    for (const raw of input.blockedOn) {
+      if (!isNonEmptyString(raw)) {
+        throw new Error("feature readiness: each 'blockedOn' entry must be a non-blank 'owner/repo#123' handle");
+      }
+      probes.push(desugarHandle(raw, consumerPackage));
+    }
+  }
+
+  if (probes.length === 0) return { probes: [], probeTimeout: null };
+
+  // One bound governs the whole preflight's escalation timers — the LONGEST of the probes' derived
+  // timeouts (via the canonical `readinessTimeout`), so no probe is cut short. Mirrors the epic
+  // lowering (app/planLowering.ts) so the feature and epic gates derive the bound identically.
+  const probeTimeout = probes
+    .map((p) => readinessTimeout(p, env))
+    .reduce((a, b) => (isoDurationToMs(b, DEFAULT_READINESS_TIMEOUT) > isoDurationToMs(a, DEFAULT_READINESS_TIMEOUT) ? b : a));
+  return { probes, probeTimeout };
+}

package/e2e/feature-preflight.e2e.ts

@@ -0,0 +1,191 @@
+// End-to-end proof for the intake-time readiness gate seeded into a single-issue feature run
+// (issue #295). Boots the whole app against the WASM engine + virtual clock and drives the REAL
+// `feature.bpmn` with `readinessProbes` seeded — the exact shape `startFeature` seeds for a gated
+// submission — proving the leading readiness-preflight executes on the engine BEFORE the fan-out
+// head (`ensure-base-branch`) and the implement agent:
+//   • GATED — a feature seeded with a probe that is ready runs the reused `pr.readiness-probe`
+//     worker inside the multi-instance preflight, releases through `pf_gw → pf_end`, and only THEN
+//     reaches `ensure-base-branch` and `implement-task` — it never implements before the gate is
+//     green, and never escalates.
+//   • UNGATED — a feature seeded with `readinessProbes = null` skips the gate entirely
+//     (`gw-readiness → ensure-base-branch`), implementing immediately as today's ungated features do.
+//
+// The probe is a deterministic shell builtin (`true`) with a bound artifact, so the gate itself is
+// hermetic (no network, no GitHub). The fan-out head (`pr.ensure-base-branch`) that follows a green
+// gate is handled by the shared hermetic admit-github stub (installAdmitGithub) like the sibling
+// preflight e2e, so the whole flow runs offline. The implement agent (`senior:feature`) has no
+// worker registered here, so the instance simply parks on `implement-task` after the gate — we
+// assert on the cumulative taken sequence flows (the WASM engine folds completed variables away).
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { after, before, describe, test } from "node:test";
+import { fileURLToPath } from "node:url";
+import { bootTestApp, type TestApp } from "@nanobpm/urban-testkit";
+import { admitGithubState, installAdmitGithub } from "./support/github-admit.ts";
+
+const APP_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+const GITHUB_ENV_OVERRIDES: Record<string, string> = {
+  NANO_PR_GITHUB_TRANSPORT: "token",
+  GITHUB_TOKEN: "",
+};
+const savedEnv = new Map<string, string | undefined>();
+
+interface TakenFlow {
+  from: string;
+  to: string;
+}
+
+function takenFlows(app: TestApp): string[] {
+  const snapshot = app.snapshot();
+  const flows = Array.isArray(snapshot.takenSequenceFlows) ? snapshot.takenSequenceFlows : [];
+  return flows
+    .filter((f): f is TakenFlow => typeof f === "object" && f !== null && "from" in f && "to" in f)
+    .map((f) => `${f.from}->${f.to}`);
+}
+
+// The full variable set `startFeature` seeds onto a feature instance (app/feature.ts). We seed it
+// directly so we can inject `readinessProbes` (and the derived `probeTimeout`/`gateKey`) without
+// standing up a whole upstream-dependency set. `baseBranch` is the admit-github default branch, so
+// the fan-out head reads it without creating a ref.
+function featureVars(overrides: Record<string, unknown>): Record<string, unknown> {
+  return {
+    featureKey: "owner/repo#7",
+    repo: "owner/repo",
+    issue: "owner/repo#7",
+    issueNumber: 7,
+    issueUrl: "https://github.com/owner/repo/issues/7",
+    task: {
+      id: "issue-7",
+      title: "owner/repo#7",
+      prompt: "Implement the GitHub issue owner/repo#7 end to end.",
+    },
+    converge: true,
+    autoMerge: false,
+    claimIssue: true,
+    answer: null,
+    status: null,
+    question: null,
+    summary: null,
+    pr: null,
+    escalationSlaTimeout: "PT24H",
+    escalationAssignee: null,
+    baseBranch: "main",
+    baseBranchBrief: "",
+    customInstructions: null,
+    readinessProbes: null,
+    probeTimeout: null,
+    gateKey: null,
+    resolvedArtifacts: null,
+    ...overrides,
+  };
+}
+
+async function boot(): Promise<{ app: TestApp; dbDir: string }> {
+  const dbDir = mkdtempSync(join(tmpdir(), "nwf-feature-preflight-"));
+  const app = await bootTestApp(APP_ROOT, { env: { NANO_APP_DB_URL: `file:${join(dbDir, "app.db")}` } });
+  return { app, dbDir };
+}
+
+describe("single-issue feature intake readiness gate (feature.bpmn, issue #295)", () => {
+  let restoreGithub: (() => void) | undefined;
+
+  before(() => {
+    for (const [k, v] of Object.entries(GITHUB_ENV_OVERRIDES)) {
+      savedEnv.set(k, process.env[k]);
+      process.env[k] = v;
+    }
+    // `pr.ensure-base-branch` reads the base ref via the token transport, which would throw
+    // `no GitHub transport available` under an empty token. Pin the shared hermetic admit-github
+    // stub (dummy token + fetch intercept) like the sibling preflight e2e so base-branch admission
+    // is deterministic and offline.
+    restoreGithub = installAdmitGithub(admitGithubState("owner/repo", "main"));
+  });
+  after(() => {
+    restoreGithub?.();
+    for (const [k, v] of savedEnv) {
+      if (v === undefined) delete process.env[k];
+      else process.env[k] = v;
+    }
+  });
+
+  test("GATED: a feature with a green probe parks on the preflight, releases green, and only THEN implements", async () => {
+    const { app, dbDir } = await boot();
+    try {
+      const { processInstanceKey } = await app.engine.createInstance({
+        processDefinitionId: "feature",
+        variables: featureVars({
+          // The shape `startFeature` seeds for a gated submission — here a hermetic green probe that
+          // binds a version, standing in for the `capability` probe (whose green/bind path is
+          // unit-tested in featureReadiness.test).
+          readinessProbes: [
+            {
+              kind: "command",
+              target: "true",
+              resolvedArtifact: "@scope/pkg@1.4.0",
+              poll: { everyMs: 5, timeoutMs: 5000, backoff: "fixed" },
+            },
+          ],
+          probeTimeout: "PT30M",
+          gateKey: "feature-readiness:owner/repo#7",
+        }),
+      });
+      await app.settle();
+
+      const flows = takenFlows(app);
+      // The feature was gated: it entered the preflight (not the ungated skip) and released green.
+      assert.ok(
+        flows.includes("gw-readiness->readiness-preflight"),
+        `a gated feature enters the preflight (flows: ${flows.join(", ")})`,
+      );
+      assert.ok(flows.includes("pf_gw->pf_end"), "the probe went green and settled the preflight");
+      // Only AFTER the gate does it reach ensure-base-branch and then implement-task — the gate is a
+      // true PREFLIGHT, not a parallel afterthought.
+      assert.ok(
+        flows.includes("readiness-preflight->ensure-base-branch"),
+        "the green gate leads into the fan-out head",
+      );
+      assert.ok(
+        flows.includes("ensure-base-branch->implement-task"),
+        `the run reaches the implement agent only after the gate (flows: ${flows.join(", ")})`,
+      );
+      // A green probe never escalates.
+      const tasks = await app.engine.searchUserTasks({ processInstanceKey });
+      assert.equal(
+        tasks.filter((t) => t.elementId === "readiness-escalation-pf").length,
+        0,
+        "a green preflight never opens an escalation task",
+      );
+    } finally {
+      await app.stop();
+      rmSync(dbDir, { recursive: true, force: true });
+    }
+  });
+
+  test("UNGATED: readinessProbes = null skips the gate and implements immediately", async () => {
+    const { app, dbDir } = await boot();
+    try {
+      await app.engine.createInstance({
+        processDefinitionId: "feature",
+        variables: featureVars({ featureKey: "owner/repo#8", issue: "owner/repo#8", readinessProbes: null }),
+      });
+      await app.settle();
+
+      const flows = takenFlows(app);
+      assert.ok(
+        flows.includes("gw-readiness->ensure-base-branch"),
+        `an ungated feature skips straight to the fan-out head (flows: ${flows.join(", ")})`,
+      );
+      assert.ok(!flows.includes("gw-readiness->readiness-preflight"), "an ungated feature never enters the preflight");
+      assert.ok(
+        flows.includes("ensure-base-branch->implement-task"),
+        "an ungated feature reaches the implement agent",
+      );
+    } finally {
+      await app.stop();
+      rmSync(dbDir, { recursive: true, force: true });
+    }
+  });
+});