@bridge_gpt/mcp-server 0.2.18 → 0.2.19

package/build/mcp-invoke.js

@@ -32,10 +32,15 @@ import { getThirdPartyTargetDefinition, resolveThirdPartyTargetEnv, validateThir
 export function getMcpInvokeUsage() {
     return [
         "Usage:",
-        "  npx -y @bridge_gpt/mcp-server mcp-invoke --target <target> --project-root <ABS_WORKTREE_PATH>",
+        "  node <abs>/mcp_server/build/index.js mcp-invoke --target <target> --project-root <ABS_WORKTREE_PATH>",
+        "",
+        "  (npm-channel fallback may invoke the same shim through a package spec, e.g.",
+        "   npx -y @bridge_gpt/mcp-server@latest mcp-invoke --target <target> --project-root <ABS_WORKTREE_PATH>)",
         "",
         "Internal worktree shim: resolves the target's launch command and credentials",
         "from the given project root, then spawns the real MCP server over stdio.",
+        "Argument parsing is identical regardless of how this process was launched",
+        "(absolute-path node invocation vs npm-channel npx).",
         "",
         "Flags:",
         "  --target <target>            MCP target to launch. 'bapi' launches the Bridge",
@@ -264,11 +269,22 @@ export async function resolveBapiInvocation(projectRoot, deps) {
     if (!credResult.ok) {
         return { ok: false, error: `failed to resolve credentials: ${credResult.error}` };
     }
-    const env = buildChildEnv(deps.env, {
+    const overlay = {
         BAPI_API_KEY: credResult.credentials.apiKey,
         BAPI_PROJECT_ROOT: projectRoot,
         BAPI_REPO_NAME: repoName,
-    });
+    };
+    // BAPI-527: `CONDUCTOR_NODE_PATH` is NON-SECRET operational metadata (the
+    // captured conductor Node path used by the worker-ledger CLI subprocess).
+    // `buildChildEnv` already inherits the full parent env, so this re-affirms the
+    // pass-through explicitly and ONLY when present — it is a non-secret allowlist
+    // entry, never a credential. It is emphatically NOT the MCP server's re-exec
+    // command: the spawned command stays `deps.execPath` + `[scriptPath]` below.
+    const conductorNodePath = deps.env.CONDUCTOR_NODE_PATH;
+    if (typeof conductorNodePath === "string" && conductorNodePath.trim().length > 0) {
+        overlay.CONDUCTOR_NODE_PATH = conductorNodePath;
+    }
+    const env = buildChildEnv(deps.env, overlay);
     return {
         ok: true,
         invocation: { command: deps.execPath, args: [deps.scriptPath], env },

package/build/mcp-provisioning.js

@@ -18,9 +18,9 @@
  * to avoid a runtime import cycle.
  */
 import path from "path";
-import { VERSION } from "./version.generated.js";
 import { readBridgeConfig } from "./bridge-config.js";
 import { getThirdPartyTargetDefinition, validateThirdPartyTargetManifestEntry, } from "./third-party-mcp-targets.js";
+import { buildMcpShimCommand, } from "./mcp-server-invocation.js";
 // ---------------------------------------------------------------------------
 // Pure helpers
 // ---------------------------------------------------------------------------
@@ -55,27 +55,27 @@ export function serverNameForMcpTarget(target) {
     return target === "bapi" ? "bridge-api" : target;
 }
 /**
- * Build a secret-free shim entry for any target. `args` are version-pinned and
- * carry the target name plus the absolute project root; there is intentionally
- * no `env` block.
+ * Build a secret-free shim entry for any target from a structured invocation.
+ * The command/args carry the target name plus the absolute project root; there is
+ * intentionally no `env` block. The absolute-build-path form serializes as
+ * `{ command: "node", args: ["<abs>/build/index.js", "mcp-invoke", …] }` (the
+ * node executable is a single substitutable field), and the npm-channel fallback
+ * as `{ command: "npx", args: ["-y", "<spec>", "mcp-invoke", …] }`.
+ *
+ * BAPI-527: `.mcp.json` remains intentionally ENV-FREE. `CONDUCTOR_NODE_PATH`
+ * (the captured conductor Node path for the worker-ledger CLI subprocess) is NOT
+ * written here — it is inherited at runtime from the worker SHELL env that
+ * `start-tickets` injects at the spawn boundary, never stored as a registration
+ * value. Keeping the shim env-free preserves the credential-safety invariant
+ * (secrets are resolved by the `mcp-invoke` shim at launch, not persisted in the
+ * worktree) and equally avoids persisting non-secret operational metadata here.
  */
-export function buildShimMcpServerEntry(target, absoluteWorktreePath) {
-    return {
-        command: "npx",
-        args: [
-            "-y",
-            `@bridge_gpt/mcp-server@${VERSION}`,
-            "mcp-invoke",
-            "--target",
-            target,
-            "--project-root",
-            absoluteWorktreePath,
-        ],
-    };
+export function buildShimMcpServerEntry(target, absoluteWorktreePath, invocation) {
+    return buildMcpShimCommand(invocation, target, absoluteWorktreePath);
 }
 /** Back-compat wrapper around `buildShimMcpServerEntry("bapi", ...)`. */
-export function buildBridgeApiShimMcpServerEntry(absoluteWorktreePath) {
-    return buildShimMcpServerEntry("bapi", absoluteWorktreePath);
+export function buildBridgeApiShimMcpServerEntry(absoluteWorktreePath, invocation) {
+    return buildShimMcpServerEntry("bapi", absoluteWorktreePath, invocation);
 }
 /**
  * Convert all supported manifest `mcp` entries into a map of server name -> shim
@@ -84,12 +84,12 @@ export function buildBridgeApiShimMcpServerEntry(absoluteWorktreePath) {
  * or incomplete non-`bapi` targets are skipped with a secret-free warning (they
  * never appear in the returned entries).
  */
-export function buildMcpServerEntriesForManifest(manifest, absoluteWorktreePath) {
+export function buildMcpServerEntriesForManifest(manifest, absoluteWorktreePath, invocation) {
     const entries = {};
     const warnings = [];
     for (const mcp of manifest.mcp) {
         if (mcp.target === "bapi") {
-            entries[serverNameForMcpTarget("bapi")] = buildShimMcpServerEntry("bapi", absoluteWorktreePath);
+            entries[serverNameForMcpTarget("bapi")] = buildShimMcpServerEntry("bapi", absoluteWorktreePath, invocation);
             continue;
         }
         const definition = getThirdPartyTargetDefinition(mcp.target);
@@ -102,9 +102,9 @@ export function buildMcpServerEntriesForManifest(manifest, absoluteWorktreePath)
             warnings.push(`MCP target '${mcp.target}' registration skipped: ${validation.error}.`);
             continue;
         }
-        entries[serverNameForMcpTarget(mcp.target)] = buildShimMcpServerEntry(mcp.target, absoluteWorktreePath);
+        entries[serverNameForMcpTarget(mcp.target)] = buildShimMcpServerEntry(mcp.target, absoluteWorktreePath, invocation);
     }
-    return { entries, warnings };
+    return { entries, warnings, registrationForm: invocation.form };
 }
 /** Both registration files written for every provisioned worktree. */
 export function getWorktreeMcpRegistrationTargets(worktreePath, platform) {
@@ -305,7 +305,7 @@ export async function provisionMcpRegistrationForWorktree(row, deps) {
     if (!normalized.ok) {
         return { ...row, status: "spawn-failed", error: `MCP provisioning failed: ${normalized.error}` };
     }
-    const built = buildMcpServerEntriesForManifest(read.manifest, normalized.path);
+    const built = buildMcpServerEntriesForManifest(read.manifest, normalized.path, deps.mcpServerInvocation);
     if (Object.keys(built.entries).length === 0) {
         // Nothing supported to write (e.g. a manifest with no bapi target and no
         // supported Tier-2 targets). Surface any warnings but leave status unchanged.
@@ -318,10 +318,16 @@ export async function provisionMcpRegistrationForWorktree(row, deps) {
             return { ...row, status: "spawn-failed", error: `MCP provisioning failed: ${result.error}` };
         }
     }
+    // Record the resolved registration form for audit (path-free — the form label
+    // only, never the absolute server entry path, which could leak a username).
+    let result = { ...row, mcpRegistrationForm: built.registrationForm };
+    result = withWarnings(result, built.warnings);
+    if (built.registrationForm !== "absolute-build-path") {
+        result = withWarning(result, "MCP registration used npm-channel fallback because an on-disk build entry was not resolvable.");
+    }
     // Pre-approve the just-registered servers so Claude Code does not prompt to
     // trust them in this fresh worktree path. Best-effort: a failure here only
     // loses the convenience of skipping the prompt, so warn and still spawn.
-    let result = withWarnings(row, built.warnings);
     const serverNames = Object.keys(built.entries);
     const trust = await writeClaudeServerTrustSettings(normalized.path, serverNames, deps);
     if (!trust.ok) {

package/build/mcp-registration-doctor.js

@@ -35,22 +35,42 @@ function flagValue(args, flag) {
     return undefined;
 }
 /**
- * True when `entry` is a secret-free Bridge API shim registration that launches
- * `npx -y @bridge_gpt/mcp-server@<version> mcp-invoke --target bapi
- * --project-root <worktreeRoot>`. The `--target` must be `bapi` and the
- * `--project-root` must match the given worktree exactly.
+ * True when `entry` is a secret-free Bridge API shim registration pointing at
+ * THIS worktree. Two forms are accepted (BAPI-526):
+ *
+ *   - Absolute-build-path (PRIMARY): an absolute `node` (or absolute Node-path)
+ *     invocation of the conductor's own compiled server, e.g.
+ *     `{ command: "node", args: ["<abs>/mcp_server/build/index.js", "mcp-invoke",
+ *     "--target", "bapi", "--project-root", "<worktreeRoot>"] }`. `command` may be
+ *     any non-empty string ("node" or a future absolute Node path); `args[0]` is a
+ *     non-empty server entry path.
+ *   - npm-channel (LEGACY/FALLBACK): `{ command: "npx", args: ["-y",
+ *     "@bridge_gpt/mcp-server@<spec>", "mcp-invoke", "--target", "bapi",
+ *     "--project-root", "<worktreeRoot>"] }`.
+ *
+ * In both forms `--target` must be `bapi` and `--project-root` must match the
+ * given worktree exactly. The server entry path is NOT required to sit under any
+ * particular username/path prefix.
  */
 export function isBridgeApiShimEntry(entry, worktreeRoot) {
     if (!entry || typeof entry !== "object" || Array.isArray(entry))
         return false;
     const candidate = entry;
-    if (candidate.command !== "npx")
+    if (typeof candidate.command !== "string" || candidate.command.length === 0)
         return false;
     if (!Array.isArray(candidate.args))
         return false;
     const args = candidate.args.filter((a) => typeof a === "string");
-    if (!args.some((a) => a.startsWith("@bridge_gpt/mcp-server")))
-        return false;
+    if (candidate.command === "npx") {
+        // npm-channel fallback: must reference the package spec.
+        if (!args.some((a) => a.startsWith("@bridge_gpt/mcp-server")))
+            return false;
+    }
+    else {
+        // Absolute-build-path: first arg must be a non-empty server entry path.
+        if (typeof args[0] !== "string" || args[0].length === 0)
+            return false;
+    }
     if (!args.includes("mcp-invoke"))
         return false;
     if (flagValue(args, "--target") !== "bapi")

package/build/mcp-server-invocation.js

@@ -0,0 +1,152 @@
+/**
+ * Shared, dependency-injected model for how a dispatched worker launches the
+ * Bridge MCP `mcp-invoke` shim (BAPI-526, Change A).
+ *
+ * The conductor used to register each dispatched worktree's `.mcp.json` against
+ * an EXACT npm version (`npx -y @bridge_gpt/mcp-server@<VERSION> mcp-invoke …`).
+ * When that version was built but not yet published, `npx` returned ETARGET/404
+ * and the worker had NO Bridge MCP tools. This module lets provisioning instead
+ * invoke the conductor's own on-disk build by ABSOLUTE PATH
+ * (`node <abs>/mcp_server/build/index.js mcp-invoke …`) — removing the
+ * npm-registry publish dependency and guaranteeing the worker runs the exact MCP
+ * code the conductor is running. A resolvable npm-channel spec remains the
+ * fallback when an on-disk build entry cannot be resolved (published-package
+ * install).
+ *
+ * SCOPE BOUNDARY (BAPI-526 is detection/registration only): this selects WHICH
+ * server file is invoked (`node <absPath>/index.js` vs `npx @…`). It does NOT
+ * change WHICH Node binary runs that file — the `nodeExecutable` field is kept as
+ * a single substitutable value (never string-concatenated into the command) so
+ * the later Ticket 3 (P2) work can point it at `CONDUCTOR_NODE_PATH` without
+ * re-plumbing argv construction.
+ */
+import path from "node:path";
+export const MCP_SERVER_PACKAGE_NAME = "@bridge_gpt/mcp-server";
+/**
+ * Resolvable npm-channel fallback spec. Deliberately a moving channel (`@latest`)
+ * rather than an exact generated version pin, so the fallback path can never
+ * reintroduce the ETARGET/404 failure the absolute-path form exists to remove.
+ */
+export const DEFAULT_MCP_SERVER_NPM_CHANNEL_SPEC = "@bridge_gpt/mcp-server@latest";
+/**
+ * Build the concrete `{ command, args }` launch pair for a target + worktree from
+ * a structured invocation. Pure — no filesystem or process access. The
+ * `nodeExecutable` is returned as the standalone `command`, never concatenated
+ * with the server entry path, so `CONDUCTOR_NODE_PATH` can substitute it later.
+ */
+export function buildMcpShimCommand(invocation, target, absoluteWorktreePath) {
+    if (invocation.form === "absolute-build-path") {
+        return {
+            command: invocation.nodeExecutable,
+            args: [
+                invocation.serverEntryPath,
+                "mcp-invoke",
+                "--target",
+                target,
+                "--project-root",
+                absoluteWorktreePath,
+            ],
+        };
+    }
+    return {
+        command: "npx",
+        args: [
+            "-y",
+            invocation.packageSpec,
+            "mcp-invoke",
+            "--target",
+            target,
+            "--project-root",
+            absoluteWorktreePath,
+        ],
+    };
+}
+/**
+ * Secret-free, path-free audit label for summaries and diagnostics. Returns ONLY
+ * the registration form; never the server entry path, username, argv, or package
+ * cache path (any of which can leak a username through a filesystem path).
+ */
+export function formatMcpShimInvocationForAudit(invocation) {
+    return invocation.form;
+}
+/**
+ * Resolve the package root from a module URL by walking the module file path and
+ * locating the nearest `src` or `build` path segment; the package root is the
+ * portion BEFORE that segment. Returns forward-slash form so it is deterministic
+ * across platforms (Node accepts forward slashes on Windows). Does NOT consult
+ * `process.cwd()`. Returns `null` when neither `src` nor `build` appears.
+ */
+export function resolvePackageRootFromModuleUrl(moduleUrl) {
+    // Parse the URL's pathname directly rather than via fileURLToPath: on Windows,
+    // fileURLToPath throws ERR_INVALID_FILE_URL_PATH for a drive-less `file:///…`
+    // URL, whereas the pathname (`/repo/mcp_server/…`) is available on every
+    // platform. This keeps resolution deterministic across POSIX and Windows.
+    let pathname;
+    try {
+        pathname = decodeURIComponent(new URL(moduleUrl).pathname);
+    }
+    catch {
+        return null;
+    }
+    // A real Windows `import.meta.url` is `file:///C:/…`, whose pathname is
+    // `/C:/…`; strip the leading slash so the drive letter leads (Node accepts
+    // forward slashes on Windows). Drive-less POSIX pathnames are left unchanged.
+    if (/^\/[A-Za-z]:/.test(pathname)) {
+        pathname = pathname.slice(1);
+    }
+    // Split on both separators so a Windows-materialized path (backslashes) and a
+    // posix path both segment identically.
+    const segments = pathname.split(/[\\/]/);
+    let markerIndex = -1;
+    for (let i = segments.length - 1; i >= 0; i--) {
+        if (segments[i] === "src" || segments[i] === "build") {
+            markerIndex = i;
+            break;
+        }
+    }
+    if (markerIndex <= 0)
+        return null;
+    return segments.slice(0, markerIndex).join("/");
+}
+/** Manual basename that tolerates either path separator. */
+function basenameAnySep(filePath) {
+    const segments = filePath.split(/[\\/]/);
+    return segments[segments.length - 1] ?? "";
+}
+/**
+ * Resolve how the worker MCP shim should be launched, preferring the conductor's
+ * own on-disk build by absolute path and falling back to a resolvable npm channel.
+ *
+ * Resolution order (never uses `process.cwd()`):
+ *   1. `<packageRoot>/build/index.js` derived from `deps.moduleUrl`.
+ *   2. `deps.argv1` when it is absolute, exists, and its basename is `index.js`.
+ *   3. npm-channel fallback (`deps.npmPackageSpec ?? DEFAULT_MCP_SERVER_NPM_CHANNEL_SPEC`).
+ *
+ * NOTE (scope boundary): this ticket changes WHICH server file is invoked, not
+ * WHICH Node runtime runs it. `nodeExecutable` defaults to `"node"` (NOT
+ * `process.execPath`) to preserve today's worker runtime selection; Ticket 3 (P2)
+ * can later inject `CONDUCTOR_NODE_PATH` into this single field.
+ */
+export function resolveMcpShimInvocationForRuntime(deps) {
+    const nodeExecutable = deps.nodeExecutable ?? "node";
+    const packageRoot = resolvePackageRootFromModuleUrl(deps.moduleUrl);
+    if (packageRoot) {
+        const candidate = `${packageRoot}/build/index.js`;
+        if (deps.fileExists(candidate)) {
+            return { form: "absolute-build-path", nodeExecutable, serverEntryPath: candidate };
+        }
+    }
+    const argv1 = deps.argv1;
+    if (typeof argv1 === "string" &&
+        argv1.length > 0 &&
+        path.isAbsolute(argv1) &&
+        basenameAnySep(argv1) === "index.js" &&
+        deps.fileExists(argv1)) {
+        return { form: "absolute-build-path", nodeExecutable, serverEntryPath: argv1 };
+    }
+    return {
+        form: "npm-channel",
+        command: "npx",
+        packageSpec: deps.npmPackageSpec ?? DEFAULT_MCP_SERVER_NPM_CHANNEL_SPEC,
+    };
+}

package/build/pipelines.generated.js

@@ -702,7 +702,7 @@ export const INSTRUCTIONS = {
     "explore-epic-codebase.md": "Perform a holistic, epic-level codebase exploration.\n\n## Epic Description\n\n{epic_description}\n\n## Instructions\n\n1. Read the research findings from `{docs_dir}/epic-plans/{epic_slug}/research-findings.md` to establish context. If the file does not exist or is empty, proceed without it.\n\n2. Explore the codebase with a focus on breadth rather than depth. The goal is to build a \"lay of the land\" understanding for the entire epic, not to deeply analyze any single sub-task. Search by filename pattern, search file contents by text pattern, and read relevant files to find:\n   - Files, modules, and directories relevant to the epic\n   - Architectural patterns used in similar features\n   - Integration points and dependencies between modules\n   - Existing conventions for the type of work this epic involves\n   - Database models, API routes, agent flows, and utilities that may be affected\n\n3. Build a mental model of:\n   - What exists today that relates to the epic\n   - What patterns and conventions are used in similar features\n   - What dependencies, data flows, and integration points are involved\n   - What areas of the codebase will likely need changes\n\n4. Write the exploration findings to `{docs_dir}/epic-plans/{epic_slug}/codebase-exploration.md` with this structure:\n\n```markdown\n# Codebase Exploration\n\n## Architecture Overview\n{High-level description of how the relevant parts of the codebase are structured.}\n\n## Relevant Code Areas\n{List of key files, modules, and directories with brief descriptions of their relevance to the epic.}\n\n## Existing Patterns\n{Patterns and conventions discovered that should be followed when implementing the epic.}\n\n## Integration Points\n{Dependencies, data flows, and integration points that the epic will need to account for.}\n\n## Potential Challenges\n{Any architectural constraints, technical debt, or complexity that could affect implementation.}\n```\n\n## Return\n\nConfirm the codebase exploration was written to `{docs_dir}/epic-plans/{epic_slug}/codebase-exploration.md` and return a concise summary of the discovered codebase areas, naming the key files and patterns relevant to the epic.\n",
     "explore-epic-subtasks.md": "Perform focused code explorations for each approved sub-task.\n\n## Instructions\n\n1. Read the approved decomposition from `{docs_dir}/epic-plans/{epic_slug}/epic-plan.md`.\n\n2. Create the explorations directory:\n   ```\n   mkdir -p {docs_dir}/epic-plans/{epic_slug}/explorations/\n   ```\n\n3. For each sub-task in the decomposition, perform a focused exploration:\n   - Search for specific files and patterns relevant to the sub-task\n   - Identify implementation options and tradeoffs\n   - Reference the holistic codebase exploration (`{docs_dir}/epic-plans/{epic_slug}/codebase-exploration.md`) and research findings (`{docs_dir}/epic-plans/{epic_slug}/research-findings.md`) for context\n   - Default to lightweight exploration — only go deeper when the holistic exploration left significant gaps for a specific sub-task\n\n4. Write an exploration document for each sub-task to `{docs_dir}/epic-plans/{epic_slug}/explorations/NN-{subtask-slug}.md` (using zero-padded numbering, e.g., `01-add-pipeline-json.md`, `02-create-instruction-files.md`).\n\n5. Each exploration document MUST include these exactly named sections:\n\n```markdown\n# {Sub-task title}\n\n## Context\n{Brief description of the sub-task scope and its role within the epic.}\n\n## Relevant Code\n{Specific files, functions, and patterns relevant to this sub-task. Reference with file_path:line_number format.}\n\n## Implementation Options\n{Viable approaches for implementing the sub-task. For each option: description, pros, cons.}\n\n## Recommendation\n{Which option to pursue and why. Include any caveats or risks.}\n```\n\n6. **Word count guidance**: Target 300-500 words per document. Keep the exploration lightweight. Only exceed this limit if the holistic codebase exploration left significant gaps for a specific sub-task.\n\n## Return\n\nConfirm one exploration document was written per sub-task under `{docs_dir}/epic-plans/{epic_slug}/explorations/` and return a concise summary of the discovered code areas and recommended approaches across the sub-tasks.\n",
     "frame-goals-and-nfrs.md": "Frame the business goals, desired end-state, and non-functional requirements (NFRs) for this work before any functional decomposition or drafting. When the goals and the desired end-state of the system are clear, the functional requirements become much easier to design accurately. This step is documentary: it records the framing and classifies what is unclear. It does NOT pause and does NOT generate a decision page (interactive surfaces handle that separately).\n\n## Inputs\n\n- The idea or epic description for this run, plus any prior planning artifacts the earlier steps wrote into this run's working directory under `{docs_dir}` (for example: research findings, codebase exploration, resolved uncertainties, duplicate assessment). Read whichever of these exist; proceed without the ones that do not.\n\n## Instructions\n\n1. From the inputs, derive and state plainly:\n   - **Business goal** — the business value this work delivers and why it matters.\n   - **Desired end-state** — the concrete state the system should reach once this work is done.\n   - **System behavior** — how the system must behave to complete its task (the quality attributes in prose, not a feature list).\n\n2. Identify the non-functional requirements. Consider every one of these canonical NFR categories and include the ones that genuinely apply (omit categories that do not):\n   - security/privacy\n   - performance/latency\n   - reliability/failure-modes\n   - observability/auditability\n   - accessibility/UX\n   - data-integrity/migration\n   - compatibility\n   - operability/config\n   - compliance/SOC2\n   - rollout/reversibility\n\n   For each NFR you include, write three things: the `requirement`, its `implication` (what this requirement changes about the implementation), and a `status`. **An NFR with no concrete implication is boilerplate — drop it rather than record it.**\n\n3. Classify each NFR's `status` with this rubric:\n   - `confirmed` — only if it is explicitly stated in the idea/description/standards or is directly observable in the codebase.\n   - `assumed` — only if it is a low-risk, conventional, and reversible default.\n   - `open` — if it touches architecture, the data model, security, user-visible behavior, migration, or irreversible Jira creation and is not settled. Be willing to mark things `open`: surfacing an unclear NFR is the point of this step.\n\n4. If this work is an epic (it will be decomposed into multiple sub-tasks or child tickets), draft a provisional **recommended implementation order**. For each slice, record a short title, its hard prerequisites (`depends_on` — what must land first), any soft sequencing preferences (`recommended_after` — not hard blockers), and a one-line rationale. Keep hard prerequisites separate from soft sequencing. Do not create Jira dependency links — the order is delivered into the epic downstream.\n\n5. Write the framing to a file named `goals-and-nfrs.md` in this run's working directory — the **same directory the earlier exploration/research steps in this pipeline wrote to** under `{docs_dir}`. Getting this path right matters: downstream steps read `goals-and-nfrs.md` from that exact directory and silently degrade (they see no framing) if it lands elsewhere. The directory differs by pipeline:\n   - **plan-epic**: the epic plan directory, `docs/epic-plans/<epic-slug>/` (alongside `codebase-exploration.md` and `epic-plan.md`).\n   - **idea-to-ticket**: the run directory, `docs/idea-to-ticket/<slug>-<run-id>/` (alongside `research-pack.md` and `resolved-uncertainties.md`).\n\n   Use this structure (no markdown tables, no `- [ ]` checkboxes — BAPI-320 hygiene):\n\n```markdown\n# Goals & Non-Functional Requirements\n\n## Business Goal\n{business goal}\n\n## Desired End-State\n{desired end-state}\n\n## System Behavior\n{how the system must behave to complete its task}\n\n## Non-Functional Requirements\n- **{nfr category}** ({confirmed, assumed, or open}): {the requirement}. Implication: {what it changes about the implementation}.\n- ...\n\n## Recommended Implementation Order\n(Epics only; omit this section for a single task or spike.)\n1. {slice title} — depends on: {hard prerequisites or \"none\"}; recommended after: {soft preferences or \"none\"}. Rationale: {one line}.\n2. ...\n```\n\n## Return\n\nConfirm `goals-and-nfrs.md` was written, report the counts of `confirmed` / `assumed` / `open` NFRs, and state whether a recommended implementation order was produced (epics) or skipped (single task/spike).\n",
-    "gather-and-attach-materials.md": "Post-create materials-completeness step. Gather the reachable local text materials a freshly-created ticket references and attach them via `attachment` (operation: `\"upload\"`), while recording everything that is record-only. This is the POST-CREATE half of the upload-time materials-completeness pass (BAPI-423); the PRE-CREATE half — inventorying and writing the `## Materials & Access` section into the draft — already ran in the `jira-ticket-writer` agent.\n\n## Inputs\n\n- `{ticket_number}` — the real Jira key of the already-created ticket (e.g. `BAPI-423`). Attachment is a POST-CREATE step; never attempt to attach before the key exists.\n- `{draft_file_path}` — path to the draft markdown that carries the trailing `## Materials & Access` section.\n- `{auto_approve_external}` — the unattended-vs-interactive signal (named for consistency with `upload-and-track.md`). **Polarity is counter-intuitive: `\"true\"` means UNATTENDED, which is the MORE restrictive mode here** — skip all prompts AND keep external/auth-gated materials record-only (never auto-attach them). It does NOT grant permission to attach external materials. Any other value (including `\"false\"`, missing, or empty) means an interactive invocation that MAY prompt for external/auth-gated materials. Invocations from `write-ticket` and `full-automation` are always unattended (`\"true\"`) for this step.\n\n## Instructions\n\n> **Orchestrator-directed step.** This agent task is authorized to call `attachment` (operations: `list`, `upload`) and `update_ticket_description` as directed below.\n\n1. **Read the record.** Read `{draft_file_path}` and parse its trailing `## Materials & Access` section. Collect the inventoried items grouped under *Reachable Local Files*, *External/Auth-Gated Links*, and *Binary/Image Materials (Record-Only)*. If there is no `## Materials & Access` section, there is nothing to gather — return a no-op success.\n\n2. **Deduplicate first.** Call the `attachment` MCP tool with `operation` set to `\"list\"` and `ticket_number` set to `{ticket_number}` BEFORE uploading anything, so a resumed or re-run invocation does not re-attach a material that is already present. Compare against the deterministic filenames computed in step 4 and skip any that already exist.\n\n3. **Source classification (scheme-based, no network probe).** Honor the classification already recorded in the draft:\n   - **Reachable Local Files** (local filesystem paths) are the only **low-risk** materials eligible for auto-attach — proceed to step 4.\n   - **External/Auth-Gated Links** (every `http(s)` URI, even if explicitly linked) are **record-only** on unattended paths. If `{auto_approve_external}` is `\"true\"` (or the invocation is from `write-ticket` / `full-automation`), leave them record-only and never auto-attach. (Mind the polarity: `auto_approve_external = \"true\"` means we are in unattended mode, so external materials must stay record-only — `\"true\"` is NOT permission to attach them.) Only an explicitly interactive invocation (`auto_approve_external` is any non-`\"true\"` value) may prompt the user to confirm before attaching.\n   - **Binary/Image Materials** are **record-only** in this step: the `attachment` tool's `upload` operation is UTF-8 text only, so never attempt a binary upload. (Binary-upload capability is the fast-follow sibling ticket BAPI-424.)\n\n4. **Gather and size-tier each reachable local text material.** For each low-risk local text material:\n   - Read the local file from disk.\n   - If the content exceeds **200,000 characters**, SKIP the upload and RECORD it (note the path and that it was skipped for size) — do not attach it.\n   - If the content is **<= 200,000 characters**, upload it RAW via `attachment` (operation: `\"upload\"`). Do NOT summarize locally: the backend already summarizes attached text at plan time, so the size tiers are backend behavior this step defers to. The agent performs NO local summarization.\n   - Use a deterministic, sanitized filename of the form `{ticket_number}-material-{hash}.md` (using the `{ticket_number}` input from the Inputs section), where `{hash}` is the first 8 hex characters of the SHA-256 digest of the sanitized absolute source path. Pin this algorithm exactly (SHA-256, first 8 hex chars, of the sanitized absolute path) — do NOT substitute another hash — so the same source always maps to the same filename and the dedup in step 2 works across separate sessions and re-runs. Keep the sanitized source provenance inside the attachment body, not only in the filename.\n\n5. **`attachment` upload parameter discipline (Zod).** When calling `attachment` with `operation: \"upload\"`, pass `ticket_number`, the attachment filename, and the text content. OMIT the optional parameters `link_type` and `replace_existing` entirely when they are unused — do NOT pass `null` or empty strings for them. The Zod schemas reject `null`/empty values, so an unused optional parameter must be omitted rather than nulled.\n\n6. **Redact secrets everywhere.** Before writing any URL or access note ANYWHERE — the Jira `## Materials & Access` record, any warning or final-report output, and any local intermediate file — sanitize and redact embedded credentials, SAS tokens, API keys, and basic-auth secrets using a high-visibility placeholder such as `[REDACTED_TOKEN]`. Mirror the backend `_redact_forge_fields()` / `_sanitize_jira_error_message()` patterns. A location/access note must never expose a plaintext secret.\n\n7. **Warn, never halt (error handling).** This step must NEVER halt, prompt-to-fail, or fail the overarching command because a material could not be gathered or attached. Follow the warn-not-halt convention:\n   - If an `attachment` upload call fails (or a file disappeared between inventory and upload), warn gracefully and continue with the next material.\n   - On such a post-create attach failure, call `update_ticket_description` to record the failure in the issue's `## Materials & Access` record (the material became unavailable only after the issue existed). `update_ticket_description` is an existing MCP tool, not a backend change.\n   - Everything knowable PRE-CREATE was already written into the description at create time, so `update_ticket_description` is reserved for these rarer post-create attach failures. This complements the existing `partial_success` recording convention in `upload-and-track.md`.\n   - Apply the step 6 redaction to every warning and recorded note.\n\n## Return\n\nConfirm the outcome: which local materials were attached (with their deterministic filenames), which were skipped/recorded (over-size, external/auth-gated, or binary/image), any attach failures recorded via `update_ticket_description`, and that no failure halted the run.\n",
+    "gather-and-attach-materials.md": "Post-create materials-completeness step. Gather the reachable local text materials a freshly-created ticket references and attach them via `attachment` (operation: `\"upload\"`), while recording everything that is record-only. This is the POST-CREATE half of the upload-time materials-completeness pass (BAPI-423); the PRE-CREATE half — inventorying and writing the `## Materials & Access` section into the draft — already ran in the `jira-ticket-writer` agent.\n\n## Inputs\n\n- `{ticket_number}` — the real Jira key of the already-created ticket (e.g. `BAPI-423`). Attachment is a POST-CREATE step; never attempt to attach before the key exists.\n- `{draft_file_path}` — path to the draft markdown that carries the trailing `## Materials & Access` section.\n- `{auto_approve_external}` — the unattended-vs-interactive signal (named for consistency with `upload-and-track.md`). **Polarity is counter-intuitive: `\"true\"` means UNATTENDED, which is the MORE restrictive mode here** — skip all prompts AND keep external/auth-gated materials record-only (never auto-attach them). It does NOT grant permission to attach external materials. Any other value (including `\"false\"`, missing, or empty) means an interactive invocation that MAY prompt for external/auth-gated materials. Invocations from `write-ticket` and `full-automation` are always unattended (`\"true\"`) for this step.\n\n## Instructions\n\n> **Orchestrator-directed step.** This agent task is authorized to call `attachment` (operations: `list`, `upload`) and `update_ticket_description` as directed below.\n\n1. **Read the record.** Read `{draft_file_path}` and parse its trailing `## Materials & Access` section. Collect the inventoried items grouped under *Reachable Local Files*, *External/Auth-Gated Links*, *Design/UI Comps (Fetchable)* (when present), and *Binary/Image Materials (Record-Only)*. If there is no `## Materials & Access` section, there is nothing to gather — return a no-op success.\n\n2. **Deduplicate first.** Call the `attachment` MCP tool with `operation` set to `\"list\"` and `ticket_number` set to `{ticket_number}` BEFORE uploading anything, so a resumed or re-run invocation does not re-attach a material that is already present. Compare against the deterministic filenames computed in step 4 and skip any that already exist.\n\n3. **Source classification (scheme-based, no network probe).** Honor the classification already recorded in the draft:\n   - **Reachable Local Files** (local filesystem paths) are the only **low-risk** materials eligible for auto-attach — proceed to step 4.\n   - **External/Auth-Gated Links** (every `http(s)` URI, even if explicitly linked) are **record-only** on unattended paths. If `{auto_approve_external}` is `\"true\"` (or the invocation is from `write-ticket` / `full-automation`), leave them record-only and never auto-attach. (Mind the polarity: `auto_approve_external = \"true\"` means we are in unattended mode, so external materials must stay record-only — `\"true\"` is NOT permission to attach them.) Only an explicitly interactive invocation (`auto_approve_external` is any non-`\"true\"` value) may prompt the user to confirm before attaching.\n   - **Binary/Image Materials** are **record-only** in this step: the `attachment` tool's `upload` operation is UTF-8 text only, so never attempt a binary upload. (Binary-upload capability is the fast-follow sibling ticket BAPI-424.)\n   - **Design/UI Comps (Fetchable)** are **not uploaded by this step**. A fetchable design/UI comp is a reference (an `attachment_id` or path) to a comp that already lives on the Jira ticket (or is fetched at implementation time); this gather step neither re-uploads it nor UTF-8-encodes its bytes. Leave each such comp reference recorded with its `attachment_id`/path in the `## Materials & Access` record so a later implementation agent can download it into its worktree via the Jira attachment download capability.\n\n4. **Gather and size-tier each reachable local text material.** For each low-risk local text material:\n   - Read the local file from disk.\n   - If the content exceeds **200,000 characters**, SKIP the upload and RECORD it (note the path and that it was skipped for size) — do not attach it.\n   - If the content is **<= 200,000 characters**, upload it RAW via `attachment` (operation: `\"upload\"`). Do NOT summarize locally: the backend already summarizes attached text at plan time, so the size tiers are backend behavior this step defers to. The agent performs NO local summarization.\n   - Use a deterministic, sanitized filename of the form `{ticket_number}-material-{hash}.md` (using the `{ticket_number}` input from the Inputs section), where `{hash}` is the first 8 hex characters of the SHA-256 digest of the sanitized absolute source path. Pin this algorithm exactly (SHA-256, first 8 hex chars, of the sanitized absolute path) — do NOT substitute another hash — so the same source always maps to the same filename and the dedup in step 2 works across separate sessions and re-runs. Keep the sanitized source provenance inside the attachment body, not only in the filename.\n\n5. **`attachment` upload parameter discipline (Zod).** When calling `attachment` with `operation: \"upload\"`, pass `ticket_number`, the attachment filename, and the text content. OMIT the optional parameters `link_type` and `replace_existing` entirely when they are unused — do NOT pass `null` or empty strings for them. The Zod schemas reject `null`/empty values, so an unused optional parameter must be omitted rather than nulled.\n\n6. **Redact secrets everywhere.** Before writing any URL or access note ANYWHERE — the Jira `## Materials & Access` record, any warning or final-report output, and any local intermediate file — sanitize and redact embedded credentials, SAS tokens, API keys, and basic-auth secrets using a high-visibility placeholder such as `[REDACTED_TOKEN]`. Mirror the backend `_redact_forge_fields()` / `_sanitize_jira_error_message()` patterns. A location/access note must never expose a plaintext secret.\n\n7. **Warn, never halt (error handling).** This step must NEVER halt, prompt-to-fail, or fail the overarching command because a material could not be gathered or attached. Follow the warn-not-halt convention:\n   - If an `attachment` upload call fails (or a file disappeared between inventory and upload), warn gracefully and continue with the next material.\n   - On such a post-create attach failure, call `update_ticket_description` to record the failure in the issue's `## Materials & Access` record (the material became unavailable only after the issue existed). `update_ticket_description` is an existing MCP tool, not a backend change.\n   - Everything knowable PRE-CREATE was already written into the description at create time, so `update_ticket_description` is reserved for these rarer post-create attach failures. This complements the existing `partial_success` recording convention in `upload-and-track.md`.\n   - Apply the step 6 redaction to every warning and recorded note.\n\n## Return\n\nConfirm the outcome: which local materials were attached (with their deterministic filenames), which were skipped/recorded (over-size, external/auth-gated, or binary/image), any attach failures recorded via `update_ticket_description`, and that no failure halted the run.\n",
     "get-prd.md": "# get_prd\n\nRetrieve an already-generated **Product Requirements Document (PRD)** for a Jira\nticket.\n\nThis tool only **fetches** an existing PRD — it does **not** start or trigger\ngeneration. If no PRD exists yet (or you need a fresh one), call `request_prd`\nfirst; it starts the async generation and `get_prd` retrieves the result once\nprocessing completes.\n\nThe PRD is product/stakeholder-facing: problem framing, goals, non-goals, target\nusers, success metrics, product requirements, scope, and risks. Present the\nreturned markdown verbatim without summarizing.\n\n## Parameters\n\n| Parameter | Type | Default | Description |\n| --- | --- | --- | --- |\n| `ticket_number` | string | — | Jira ticket key in `PROJECT-NUMBER` format (e.g. `BAPI-123`). |\n| `save_locally` | boolean | `true` | Save the retrieved PRD to a local file. Set to `false` to skip saving. |\n\nLocal saves go to `BAPI_DOCS_DIR/prd/{ticket}-prd-plan.md`.\n\n## Return\n\n- The full PRD as markdown text when one exists.\n- A `404` / not-found response when no PRD is ready yet — that means generation\n  has not run, not that the tool failed. Call `request_prd` to generate one.\n",
     "learn-architecture.md": "## Objective\n\nExplore the codebase to identify architectural principles, directory conventions, design patterns, and data flow, then draft `architecture_instructions` for the project config.\n\n## Instructions\n\n### Phase 1 — Principles Research\n\nResearch the codebase to identify architectural principles and conventions. For each area below, examine at least 5 representative files. Cite file paths for every pattern. Include code examples (5-15 lines) showing correct usage. Where relevant, include a WRONG example showing the common mistake.\n\nFor each pattern, classify its evidence level:\n- `ENFORCED` — consistently followed across the codebase, violations would be bugs\n- `CONVENTION` — commonly observed, occasional deviations exist\n- `ASPIRATIONAL` — intended direction, not yet consistently applied\n\nResearch areas:\n1. **Architectural coding patterns**: Search `api/routes/` and `api/library/` for separation of concerns, layer boundaries, function-vs-class decisions. Read files matching `*_lib.py`, `*_utils.py`, `*_helpers.py` to document module naming suffix conventions.\n2. **Design patterns**: Search for factory functions, strategy patterns, middleware chains, registry patterns, and dependency injection in `api/` and `src/python/`. Cite concrete usage with file path and function name.\n3. **Dependency management**: Read `requirements.in`, `requirements-dev.in`, and `package.json` files to document how dependencies are declared and organized.\n4. **Error handling architecture**: Search for `log_exception_to_sentry` and `HTTPException` usage patterns across `api/routes/` to document the system-wide error propagation strategy.\n5. **Configuration management**: Search for `os.environ` and `get_config_field` usage to document the two-tier system (env vars vs. database config).\n6. **Tech stack detection**: Read `requirements.in`, `package.json`, and `main.py` to identify primary languages, frameworks, and key libraries.\n7. **Security architecture**: Read `api/routes/setup/auth.py` and search for `require_api_key`, `require_api_session`, and `verify_repo_access` to document authentication and authorization design.\n8. **Agent prompting conventions**: Read files in `src/python/llms/agents/` to document prompt construction, section headers, dynamic content delimiters, and role-based personas.\n\nScope exclusion: Do NOT document testing patterns. Skip the `tests/` directory entirely.\n\nWrite findings to `{docs_dir}/tmp/architecture-principles.md`.\n\n### Phase 2 — Structure & Data Flow Research\n\n1. Call the `regenerate_directory_map` MCP tool to get a fresh directory map.\n2. Read the principles document from Phase 1.\n3. Research and document:\n   - **Directory conventions**: For each major directory, document purpose, file naming, internal structure, and an example file.\n   - **Module boundaries and import patterns**: Which directories are distinct modules and how they interact. Document import restrictions.\n   - **Data flow patterns**: Trace 2-3 complete request paths (synchronous, async background task, agent orchestration).\n   - **Integration patterns**: How external services (Jira, GitHub/Bitbucket, LLMs, Pinecone, PostgreSQL) are integrated.\n   - **Background task patterns**: The async task lifecycle with `asyncio.create_task`, semaphores, and error reporting.\n\nWrite findings to `{docs_dir}/tmp/architecture-structure.md`.\n\n### Phase 3 — Draft\n\n1. Read both research documents.\n2. Combine into a single `architecture_instructions` draft with these required sections:\n   - **1. Core Principles** — Each principle with evidence level and explanation.\n   - **2. Layered Architecture** — Layer separation, dependency rule, agent vs orchestration logic.\n   - **3. Directory Conventions** — Purpose, naming, structure for each major directory.\n   - **4. Data Flow Patterns** — Complete request path traces with file paths.\n   - **5. Technical Standards** — Coding style, async patterns, database, schema, LLM integration, config, dependencies.\n   - **6. Error Handling & Monitoring** — Error propagation strategy, Sentry integration, Langfuse tracing.\n   - **7. Security & Authentication** — Auth architecture, session model, permission model.\n   - **8. Agent Prompting Conventions** — Prompt construction, section headers, content delimiters.\n   - **9. Integration Points** — External service clients and their calling patterns.\n   - **10. AI Code Generation Guidelines** — Anti-patterns, duplication avoidance, pattern compliance checklist.\n\n3. Write the draft to `{docs_dir}/standards/architecture_instructions.md`.\n\n## Return\n\nReturn a brief summary of what was learned about the project's architecture (core principles, directory conventions, data flow), citing the key files inspected, and confirm the draft was written to `{docs_dir}/standards/architecture_instructions.md`.\n",
     "learn-backend-correctness.md": "## Objective\n\nExplore the codebase to identify correctness standards for backend code, then draft the corresponding correctness standards document.\n\n## Target Type\n\n- **Type**: `backend_correctness`\n- **Field name**: `backend_correctness_standards`\n- **Scope**: Server-side code: Python, Ruby, Go, Java, C#, Node.js server code, API routes, business logic.\n\n## Instructions\n\n### Phase 1 — Explore Correctness Patterns\n\nFocus on implementation correctness: how to write code that is correct, idiomatic, and robust within this project's conventions.\n\n1. **File Type Detection**: Search by filename pattern for files matching `**/*.py` in `api/` and `src/python/`. If very few or no files exist, note this and draft minimal instructions.\n\n2. **Convention Analysis**: Read 3-5 representative files in `api/routes/` and `api/library/` to identify:\n   - Structure patterns (imports, exports, class structure, function ordering)\n   - Naming conventions (variables, functions, classes, files)\n   - Framework conventions and idioms\n   - Best practices followed\n   - Issues and inconsistencies\n\n   Also read files to document:\n   - Error handling implementation (try/except ordering, Sentry calls) with CORRECT/WRONG examples\n   - Authentication implementation (auth check sequence) with code examples\n   - Database call patterns (`postgres_helpers` (bool, result) tuple handling) with CORRECT/WRONG examples\n   - Input validation patterns (Pydantic models, naming conventions)\n   - HTTP client patterns (error handling, JiraError sanitization)\n   - Async implementation patterns (`asyncio.to_thread()` for blocking code)\n\n### Phase 2 — Draft\n\nDraft correctness standards as clear, actionable instructions for an AI code generation agent. Cover:\n- Code structure and organization requirements\n- Naming conventions to follow\n- Framework-specific patterns and idioms\n- Security requirements relevant to this code type\n- Performance considerations\n- Common mistakes to avoid\n- Guards against common AI weaknesses: duplicative code, verbose implementations, security vulnerabilities\n\nAlso include:\n- Route handler boilerplate (auth -> validation -> business logic -> error handling)\n- Database interaction patterns with CORRECT/WRONG examples\n- Exception handling pattern (specific first, HTTPException re-raise, generic with Sentry)\n- Sentry reporting patterns and common mistakes\n- Input sanitization rules (JiraError headers, raw exception messages)\n\nWrite the draft to `{docs_dir}/standards/backend_correctness_standards.md`.\n\n## Return\n\nReturn a brief summary of what was learned about backend correctness conventions (structure, naming, error handling, auth, DB patterns), citing the key files inspected, and confirm the draft was written to `{docs_dir}/standards/backend_correctness_standards.md`.\n",