@bridge_gpt/mcp-server 0.1.17 → 0.2.0

package/build/chain-orchestrator.js

@@ -15,10 +15,13 @@
  *   - Stage 3 (start-tickets) is special-cased: the orchestrator does NOT call
  *     ``runPipeline``; it emits an ``agent_task`` envelope naming the exact
  *     ``/start-tickets ...`` command for the host agent to invoke in-session.
- *   - Cross-stage variables (created_ticket_keys -> review fan-out ->
- *     reviewed_ticket_keys -> start-tickets) are resolved server-side. Missing
- *     cross-stage variables produce a typed ``VALIDATION`` failure — never a
- *     placeholder value.
+ *   - Cross-stage variables (child_ticket_keys -> review fan-out ->
+ *     reviewed_ticket_keys -> start-tickets) are resolved server-side. The
+ *     idea-to-ticket stage emits a structured payload that keeps the Epic
+ *     ``epic_parent_key`` separate from the implementable ``child_ticket_keys``,
+ *     so the Epic parent is handed to NEITHER the review fan-out NOR
+ *     start-tickets. Missing cross-stage variables produce a typed
+ *     ``VALIDATION`` failure — never a placeholder value.
  */
 import { runPipeline, resumePipeline, peekPipelineRun } from "./pipeline-orchestrator.js";
 import { toStringVariable, substituteChainValue } from "./chain-utils.js";
@@ -174,6 +177,13 @@ const JIRA_KEY_EXACT = /^[A-Z][A-Z0-9]+-\d+$/;
  * keys merely *mentioned* by an earlier step (e.g. duplicate-detection search
  * hits) can never be mistaken for this run's creations. A string / no-field
  * input returns `[]`, which the caller treats as fail-closed.
+ *
+ * NOTE: This flat helper FLATTENS parent (`epic_key`) and `child_ticket_keys`
+ * into a single list. The full-automation chain fan-out must NOT use it — it
+ * would fold the Epic parent into the implementable list and hand the parent to
+ * review / start-tickets. The chain drives fan-out from the structured
+ * `extractCreatedTicketPayload` path instead; this helper remains only for
+ * non-chain compatibility callers that expect a flat single-ticket list.
  */
 export function extractCreatedTicketKeys(source) {
     const preferredKeys = [
@@ -267,24 +277,140 @@ function tryParseJson(raw) {
         return undefined;
     }
 }
+function isValidJiraKey(value) {
+    return typeof value === "string" && JIRA_KEY_EXACT.test(value);
+}
 /**
- * Derive the keys created by a completed idea-to-ticket child run AUTHORITATIVELY
- * from the upload step's structured output — never by scanning the whole
- * transcript. The upload step (`upload-and-track.md`) is the LAST step of the
- * idea-to-ticket pipeline and the chain never passes `skip_steps`, so it is the
- * final entry of `results`. Its `result` is parsed for a `{ created_ticket_keys }`
- * payload. Returns `[]` (→ caller fails closed) if the payload is absent or
- * malformed, so dedup-search hits from earlier steps can never become targets.
+ * Normalize a PARSED, STRUCTURED upload payload into a {@link CreatedTicketPayload}.
+ * Accepts only a parsed JSON object — never a string, array, null, number, or
+ * free text — so Jira keys merely mentioned in prose can never become
+ * review/start-tickets targets. Two authoritative shapes are recognized:
+ *
+ *   - Epic: ``{ epic_parent_key, child_ticket_keys }`` — ``epic_parent_key`` only
+ *     (the legacy ``epic_key`` alias is rejected for a clean break); at least one
+ *     valid child key required; the parent must not appear in the children.
+ *   - Single-ticket: ``{ created_ticket_keys: [key] }`` — exactly one valid key,
+ *     normalized into ``child_ticket_keys`` (with ``created_ticket_keys`` kept as
+ *     a compatibility alias). A multi-key flat ``created_ticket_keys`` WITHOUT
+ *     ``epic_parent_key`` is treated as malformed rather than guessing the first
+ *     key is the parent.
+ *
+ * Returns ``{ ok: false, error }`` on any malformed shape so the caller can fail
+ * the chain with a clear validation message.
  */
-export function extractCreatedKeysFromCompletedChild(childEnv) {
+export function extractCreatedTicketPayload(source) {
+    if (source === null || typeof source !== "object" || Array.isArray(source)) {
+        return {
+            ok: false,
+            error: "Upload payload must be a structured JSON object; the chain never " +
+                "harvests Jira keys from free text, arrays, null, or numbers.",
+        };
+    }
+    const obj = source;
+    const hasEpicParent = "epic_parent_key" in obj;
+    const hasLegacyEpicKey = "epic_key" in obj;
+    const hasCreated = "created_ticket_keys" in obj;
+    // Epic path — driven exclusively by the explicit `epic_parent_key` field.
+    if (hasEpicParent) {
+        const parent = obj.epic_parent_key;
+        if (!isValidJiraKey(parent)) {
+            return {
+                ok: false,
+                error: `Epic payload "epic_parent_key" must be a valid Jira key; got ${JSON.stringify(parent)}.`,
+            };
+        }
+        const rawChildren = obj.child_ticket_keys;
+        if (!Array.isArray(rawChildren) || rawChildren.length === 0) {
+            return {
+                ok: false,
+                error: 'Epic payload requires "child_ticket_keys" with at least one ' +
+                    "implementable child ticket key.",
+            };
+        }
+        const children = [];
+        for (const c of rawChildren) {
+            if (!isValidJiraKey(c)) {
+                return {
+                    ok: false,
+                    error: `Epic payload "child_ticket_keys" must contain only valid implementable Jira keys; got ${JSON.stringify(c)}.`,
+                };
+            }
+            if (c === parent) {
+                return {
+                    ok: false,
+                    error: `Epic parent ${parent} must not appear in "child_ticket_keys" (parent leakage).`,
+                };
+            }
+            children.push(c);
+        }
+        return { ok: true, payload: { epic_parent_key: parent, child_ticket_keys: children } };
+    }
+    // Reject the legacy `epic_key` alias explicitly: the chain accepts only
+    // `epic_parent_key` for the Epic parent (clean break, no alias recognition).
+    if (hasLegacyEpicKey) {
+        return {
+            ok: false,
+            error: 'Epic payload must use "epic_parent_key"; the legacy "epic_key" alias ' +
+                "is not accepted by the chain.",
+        };
+    }
+    // Single-ticket path — exactly one implementable key, normalized to children.
+    if (hasCreated) {
+        const raw = obj.created_ticket_keys;
+        if (!Array.isArray(raw) || raw.length !== 1 || !isValidJiraKey(raw[0])) {
+            return {
+                ok: false,
+                error: 'Single-ticket payload "created_ticket_keys" must contain exactly ' +
+                    "one valid implementable Jira key. A multi-key list is malformed " +
+                    '(the legacy "first key is the Epic parent" convention is not accepted).',
+            };
+        }
+        const key = raw[0];
+        return { ok: true, payload: { child_ticket_keys: [key], created_ticket_keys: [key] } };
+    }
+    return {
+        ok: false,
+        error: 'Upload payload has no recognized "epic_parent_key"/"child_ticket_keys" ' +
+            'or single-ticket "created_ticket_keys" fields.',
+    };
+}
+/**
+ * Derive the structured {@link CreatedTicketPayload} created by a completed
+ * idea-to-ticket child run AUTHORITATIVELY from the upload step's structured
+ * output — never by scanning the whole transcript. The upload step
+ * (`upload-and-track.md`) is the LAST step of the idea-to-ticket pipeline and the
+ * chain never passes `skip_steps`, so it is the final entry of `results`. Its
+ * `result` is parsed (with `parseStructuredAgentResult` when it is a string) and
+ * passed to {@link extractCreatedTicketPayload}. Returns a validation error if
+ * the payload is absent or malformed, so dedup-search hits from earlier steps can
+ * never become targets.
+ */
+export function extractCreatedTicketPayloadFromCompletedChild(childEnv) {
     const results = childEnv.results;
-    if (!Array.isArray(results) || results.length === 0)
-        return [];
+    if (!Array.isArray(results) || results.length === 0) {
+        return {
+            ok: false,
+            error: "idea-to-ticket child produced no results; cannot extract an upload payload.",
+        };
+    }
     const uploadResult = results[results.length - 1]?.result;
     const payload = typeof uploadResult === "string"
         ? parseStructuredAgentResult(uploadResult)
         : uploadResult;
-    return extractCreatedTicketKeys(payload);
+    return extractCreatedTicketPayload(payload);
+}
+/**
+ * Compatibility wrapper over {@link extractCreatedTicketPayloadFromCompletedChild}
+ * that returns ONLY the normalized implementable `child_ticket_keys` (never the
+ * Epic parent) on success, and `[]` on any structured-extraction failure — so
+ * legacy callers keep their flat-array contract without ever guessing
+ * parent/child roles.
+ */
+export function extractCreatedKeysFromCompletedChild(childEnv) {
+    const extraction = extractCreatedTicketPayloadFromCompletedChild(childEnv);
+    if (!extraction.ok)
+        return [];
+    return extraction.payload.child_ticket_keys;
 }
 /**
  * True when ``token`` appears in a failed child envelope's failure-text fields:
@@ -305,12 +431,29 @@ function failedEnvelopeMentions(env, token) {
     }
     return false;
 }
-/** Heuristic, no-LLM one-line stage summary. */
-export function summarizeStageCompletion(pipelineName, keys) {
-    const joined = keys.join(", ");
+/**
+ * Heuristic, no-LLM one-line stage summary. idea-to-ticket passes a structured
+ * {@link CreatedTicketPayload} so the summary distinguishes the Epic parent from
+ * implementable children; review / start-tickets pass a flat `string[]` of keys
+ * (wording preserved).
+ */
+export function summarizeStageCompletion(pipelineName, keysOrPayload) {
     if (pipelineName === "idea-to-ticket") {
-        return `Created tickets: ${joined}`;
+        if (!Array.isArray(keysOrPayload)) {
+            const payload = keysOrPayload;
+            const children = payload.child_ticket_keys.join(", ");
+            if (payload.epic_parent_key) {
+                return `Created Epic ${payload.epic_parent_key} and implementable children: ${children}`;
+            }
+            return `Created ticket: ${children}`;
+        }
+        // Backward-compatible flat-array form.
+        return `Created tickets: ${keysOrPayload.join(", ")}`;
     }
+    const keys = Array.isArray(keysOrPayload)
+        ? keysOrPayload
+        : keysOrPayload.child_ticket_keys;
+    const joined = keys.join(", ");
     if (pipelineName === "review-ticket") {
         return `Reviewed tickets: ${joined}`;
     }
@@ -504,7 +647,12 @@ function buildStageVariables(stage, args, extra = {}) {
     }
     return resolved;
 }
-/** Resolve a fan-out / cross-stage input list from prior stage outputs. */
+/**
+ * Resolve a fan-out / cross-stage input list from prior stage outputs. This
+ * helper is intentionally KEY-SPECIFIC: it never searches alternate field names,
+ * so a recipe asking for `child_ticket_keys` will not silently fall back to
+ * `created_ticket_keys`.
+ */
 function resolveCrossStageList(row, stageIndex, key) {
     for (let i = stageIndex - 1; i >= 0; i--) {
         const outputs = row.stages[i]?.outputs;
@@ -514,6 +662,50 @@ function resolveCrossStageList(row, stageIndex, key) {
     }
     return null;
 }
+/**
+ * Scan stage outputs STRICTLY BEFORE ``stageIndex`` and return the first valid
+ * string ``epic_parent_key``. Non-string / empty values are ignored. Used as a
+ * second-layer guard so the Epic parent can be filtered out of the start-tickets
+ * handoff even if an upstream persisted stage output is malformed.
+ */
+export function resolvePriorEpicParentKey(row, stageIndex) {
+    for (let i = 0; i < stageIndex; i++) {
+        const candidate = row.stages[i]?.outputs?.epic_parent_key;
+        if (typeof candidate === "string" && candidate.trim() !== "") {
+            return candidate;
+        }
+    }
+    return null;
+}
+/**
+ * Resolve the start-tickets stage's configured fan-out input and defensively
+ * filter out any key equal to the prior ``epic_parent_key``. Fails closed (a
+ * validation-oriented message) when the configured input is missing/empty, or
+ * when excluding the Epic parent leaves no implementable keys. This is the
+ * belt-and-suspenders second layer; the primary fix excludes the parent before
+ * review via the structured extractor.
+ */
+export function resolveStartTicketKeys(row, stageIndex, fanOutInput) {
+    const configured = resolveCrossStageList(row, stageIndex, fanOutInput);
+    if (!configured || configured.length === 0) {
+        return {
+            ok: false,
+            error: `Missing cross-stage variable "${fanOutInput}" for start-tickets.`,
+        };
+    }
+    const epicParent = resolvePriorEpicParentKey(row, stageIndex);
+    const filtered = epicParent
+        ? configured.filter((k) => k !== epicParent)
+        : configured;
+    if (filtered.length === 0) {
+        return {
+            ok: false,
+            error: `No implementable tickets remain for start-tickets after excluding the ` +
+                `Epic parent ${epicParent}.`,
+        };
+    }
+    return { ok: true, keys: filtered };
+}
 // ---------------------------------------------------------------------------
 // Child-pipeline envelope handling
 // ---------------------------------------------------------------------------
@@ -633,22 +825,37 @@ async function handleChildPipelineEnvelope(persistence, recipe, row, childEnv, o
         }
         return { kind: "advanced", row: updated };
     }
-    // Single-child stage (idea-to-ticket): finalize. Derive created keys ONLY from
-    // the upload step's structured payload — never the whole transcript — so
-    // duplicate-detection search hits cannot become review/start-tickets targets.
-    const keys = extractCreatedKeysFromCompletedChild(childEnv);
-    if (keys.length === 0) {
+    // Single-child stage (idea-to-ticket): finalize. Derive the STRUCTURED payload
+    // ONLY from the upload step's structured output — never the whole transcript —
+    // so duplicate-detection search hits cannot become review/start-tickets
+    // targets. The Epic parent (`epic_parent_key`) is kept SEPARATE from the
+    // implementable `child_ticket_keys` so it is handed to NEITHER review NOR
+    // start-tickets. `created_ticket_keys` is persisted as an implementable-only
+    // compatibility alias (= children) and never carries the Epic parent.
+    const extraction = extractCreatedTicketPayloadFromCompletedChild(childEnv);
+    if (!extraction.ok) {
+        return {
+            kind: "fail",
+            envelope: await failChainValidation(persistence, recipe, row, extraction.error),
+        };
+    }
+    const payload = extraction.payload;
+    if (payload.child_ticket_keys.length === 0) {
         return {
             kind: "fail",
-            envelope: await failChainValidation(persistence, recipe, row, "idea-to-ticket produced no structured created_ticket_keys payload; cannot continue the chain."),
+            envelope: await failChainValidation(persistence, recipe, row, "idea-to-ticket produced no implementable child tickets; full automation cannot continue without implementable tickets."),
         };
     }
     const stages = cloneStages(row.stages);
     const stage = stages[idx];
     stage.status = "completed";
     stage.pipeline_run_id = null;
-    stage.outputs = { created_ticket_keys: keys };
-    stage.summary = summarizeStageCompletion(stageRecipe.pipeline_name, keys);
+    stage.outputs = {
+        child_ticket_keys: payload.child_ticket_keys,
+        created_ticket_keys: payload.child_ticket_keys,
+        ...(payload.epic_parent_key ? { epic_parent_key: payload.epic_parent_key } : {}),
+    };
+    stage.summary = summarizeStageCompletion(stageRecipe.pipeline_name, payload);
     let updated;
     try {
         updated = await persistence.patchRun(row.chain_run_id, {
@@ -815,14 +1022,18 @@ async function startStartTicketsStage(persistence, recipe, row) {
     const stageRecipe = recipe.stages[idx];
     const total = recipe.stages.length;
     const fanOutInput = stageRecipe.fan_out_input ?? "reviewed_ticket_keys";
-    const keys = resolveCrossStageList(row, idx, fanOutInput);
-    if (!keys || keys.length === 0) {
-        return failChainValidation(persistence, recipe, row, `Missing cross-stage variable "${fanOutInput}" for start-tickets.`);
+    // Second-layer guard: filter the Epic parent out of the start keys even if an
+    // upstream persisted stage output is malformed (the primary exclusion happens
+    // before review via the structured extractor).
+    const resolution = resolveStartTicketKeys(row, idx, fanOutInput);
+    if (!resolution.ok) {
+        return failChainValidation(persistence, recipe, row, resolution.error);
     }
+    const keys = resolution.keys;
     // Hands-off chain runs (auto_approve=true, the default) spawn the
     // implementation agents auto-approved too, so they don't stall on approval
     // gates. A --require-approval run (auto_approve=false) spawns them interactive.
-    const autoApproveFlag = row.args.auto_approve === true ? " --auto-approve" : "";
+    const autoApproveFlag = row.args.auto_approve === true ? " --auto" : "";
     const command = `/start-tickets ${keys.join(" ")}${autoApproveFlag}`;
     const stages = cloneStages(row.stages);
     stages[idx].status = "paused";
@@ -1018,7 +1229,10 @@ export async function resumeFullAutomation(deps, input) {
                     chain_total: total,
                 });
             }
-            const startedKeys = resolveCrossStageList(row, idx, stageRecipe.fan_out_input ?? "reviewed_ticket_keys") ?? [];
+            // Persist started_ticket_keys WITHOUT the Epic parent, using the same
+            // defensive filter as startStartTicketsStage.
+            const startResolution = resolveStartTicketKeys(row, idx, stageRecipe.fan_out_input ?? "reviewed_ticket_keys");
+            const startedKeys = startResolution.ok ? startResolution.keys : [];
             const stages = cloneStages(row.stages);
             stages[idx].status = "completed";
             stages[idx].pipeline_run_id = null;