@ai-sdlc/orchestrator 0.9.0 → 0.10.0

package/dist/runtime/parallelism-flag.d.ts

@@ -1,7 +1,25 @@
 /**
- * Feature-flag gate for RFC-0010 parallelism. While Phases 1-4 land, the worker-pool
- * conversion in execute.ts is gated behind AI_SDLC_PARALLELISM=experimental. Phase 5
- * (hardening) flips the default to on after a soak window.
+ * Feature-flag gate for RFC-0010 parallelism. Phases 1-4 shipped behind
+ * AI_SDLC_PARALLELISM=experimental; Phase 5 (hardening) added the runbook,
+ * chaos plan, and stuck-heartbeat detection. Per maintainer directive
+ * 2026-05-01 (AISDLC-116), the calendar-based 1-week soak gate from RFC-0010
+ * Phase 5 was dropped in favor of substantive readiness — pre-flight scan
+ * of orchestrator/_events.jsonl + recent commit history showed zero
+ * parallelism-related incidents — and the flag now defaults to 'on'.
+ *
+ * Backwards-compat envelope (preserved on purpose):
+ *   - unset                       → 'on'   (new default)
+ *   - 'on' | 'true' | '1'         → 'on'
+ *   - 'experimental'              → 'experimental'  (still honored for
+ *                                                    callers pinning the
+ *                                                    pre-promotion mode)
+ *   - 'off' | 'disabled' |
+ *     'false' | '0'               → 'off'  (explicit opt-out)
+ *   - any other string            → 'on'   (fail-on rather than fail-off
+ *                                           now that 'on' is the default;
+ *                                           prevents typos like
+ *                                           'enable' from silently
+ *                                           disabling parallelism)
  */
 export declare const FLAG_NAME = "AI_SDLC_PARALLELISM";
 export type ParallelismMode = 'off' | 'experimental' | 'on';

package/dist/runtime/parallelism-flag.js

@@ -1,16 +1,37 @@
 /**
- * Feature-flag gate for RFC-0010 parallelism. While Phases 1-4 land, the worker-pool
- * conversion in execute.ts is gated behind AI_SDLC_PARALLELISM=experimental. Phase 5
- * (hardening) flips the default to on after a soak window.
+ * Feature-flag gate for RFC-0010 parallelism. Phases 1-4 shipped behind
+ * AI_SDLC_PARALLELISM=experimental; Phase 5 (hardening) added the runbook,
+ * chaos plan, and stuck-heartbeat detection. Per maintainer directive
+ * 2026-05-01 (AISDLC-116), the calendar-based 1-week soak gate from RFC-0010
+ * Phase 5 was dropped in favor of substantive readiness — pre-flight scan
+ * of orchestrator/_events.jsonl + recent commit history showed zero
+ * parallelism-related incidents — and the flag now defaults to 'on'.
+ *
+ * Backwards-compat envelope (preserved on purpose):
+ *   - unset                       → 'on'   (new default)
+ *   - 'on' | 'true' | '1'         → 'on'
+ *   - 'experimental'              → 'experimental'  (still honored for
+ *                                                    callers pinning the
+ *                                                    pre-promotion mode)
+ *   - 'off' | 'disabled' |
+ *     'false' | '0'               → 'off'  (explicit opt-out)
+ *   - any other string            → 'on'   (fail-on rather than fail-off
+ *                                           now that 'on' is the default;
+ *                                           prevents typos like
+ *                                           'enable' from silently
+ *                                           disabling parallelism)
  */
 export const FLAG_NAME = 'AI_SDLC_PARALLELISM';
 export function readParallelismMode(env = process.env) {
     const raw = env[FLAG_NAME]?.trim().toLowerCase();
+    if (raw === undefined || raw === '')
+        return 'on';
     if (raw === 'experimental')
         return 'experimental';
-    if (raw === 'on' || raw === 'true' || raw === '1')
-        return 'on';
-    return 'off';
+    if (raw === 'off' || raw === 'disabled' || raw === 'false' || raw === '0')
+        return 'off';
+    // 'on' / 'true' / '1' / any other value → 'on' (default-on, fail-on)
+    return 'on';
 }
 export function isParallelismEnabled(env) {
     return readParallelismMode(env) !== 'off';

package/dist/runtime/port-allocator.d.ts

@@ -14,6 +14,17 @@ export declare class PortAllocationError extends Error {
     readonly attemptedPorts: number[];
     constructor(message: string, worktreePath: string, attemptedPorts: number[]);
 }
+/**
+ * Derive a deterministic port for `worktreePath` by hashing its absolute form with MD5
+ * and mapping the first two bytes into [basePort + PORT_RANGE_OFFSET_MIN,
+ * basePort + PORT_RANGE_OFFSET_MAX].
+ *
+ * **Collision risk**: the output space is only 900 ports wide. When called with multiple
+ * independent (e.g. mkdtemp-generated) paths, two or more paths may map to the same port.
+ * For n=3 paths the birthday probability is ~0.33%. Integration tests that need to assert
+ * port distinctness MUST use pre-chosen, manually-verified paths rather than random
+ * temporaries — see the module-level JSDoc for the recommended assertion pattern.
+ */
 export declare function deterministicPort(worktreePath: string, basePort?: number): number;
 export declare function allocatePort(worktreePath: string, options?: AllocatePortOptions): Promise<number>;
 export declare function allocateContiguousPorts(worktreePath: string, options: AllocateContiguousOptions): Promise<number[]>;

package/dist/runtime/port-allocator.js

@@ -1,3 +1,22 @@
+/**
+ * Deterministic port allocator for git worktrees.
+ *
+ * `deterministicPort` maps an absolute worktree path to a port number in a fixed
+ * 900-port range (DEFAULT_BASE_PORT + PORT_RANGE_OFFSET_MIN … PORT_RANGE_OFFSET_MAX)
+ * by hashing the path with MD5 and taking the first two bytes modulo the range span.
+ *
+ * **Hash-collision caveat**: the 900-port range is finite. When multiple worktree paths
+ * are fed through `deterministicPort` in a single test, birthday-paradox collisions are
+ * possible. For n=3 paths the probability is roughly (n*(n-1)/2) / span ≈ 0.33%. Over
+ * thousands of CI runs this causes spurious "distinct ports" assertion failures.
+ *
+ * **Integration-test guidance**: do NOT assert `new Set(ports).size === n` unless the
+ * test controls the exact path strings and has pre-verified they hash to distinct values.
+ * Instead assert:
+ *   - each port is in [DEFAULT_BASE_PORT + PORT_RANGE_OFFSET_MIN, DEFAULT_BASE_PORT + PORT_RANGE_OFFSET_MAX]
+ *   - calling allocatePort twice for the same path returns the same value (idempotency)
+ *   - ports[i] === deterministicPort(h.path) (the core deterministic-port property)
+ */
 import { createHash } from 'node:crypto';
 import { resolve } from 'node:path';
 import { createServer } from 'node:net';
@@ -16,6 +35,17 @@ export class PortAllocationError extends Error {
         this.name = 'PortAllocationError';
     }
 }
+/**
+ * Derive a deterministic port for `worktreePath` by hashing its absolute form with MD5
+ * and mapping the first two bytes into [basePort + PORT_RANGE_OFFSET_MIN,
+ * basePort + PORT_RANGE_OFFSET_MAX].
+ *
+ * **Collision risk**: the output space is only 900 ports wide. When called with multiple
+ * independent (e.g. mkdtemp-generated) paths, two or more paths may map to the same port.
+ * For n=3 paths the birthday probability is ~0.33%. Integration tests that need to assert
+ * port distinctness MUST use pre-chosen, manually-verified paths rather than random
+ * temporaries — see the module-level JSDoc for the recommended assertion pattern.
+ */
 export function deterministicPort(worktreePath, basePort = DEFAULT_BASE_PORT) {
     const absolute = resolve(worktreePath);
     const digest = createHash('md5').update(absolute).digest();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdlc/orchestrator",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "AI-SDLC Orchestrator — long-running runtime that drives issues through the complete SDLC with AI agents",
   "license": "Apache-2.0",
   "repository": {
@@ -42,10 +42,11 @@
     }
   },
   "dependencies": {
+    "@inquirer/prompts": "^7.0.0",
     "better-sqlite3": "^11.0.0",
     "commander": "^12.0.0",
     "yaml": "^2.7.0",
-    "@ai-sdlc/reference": "0.9.0"
+    "@ai-sdlc/reference": "0.10.0"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.0",