@bridge_gpt/mcp-server 0.2.18 → 0.2.20

package/CONDUCTOR.md

@@ -129,3 +129,78 @@ redeems the approval token and the server returns `merge.succeeded`.
 **`merge.succeeded` is the only terminal merge event.** The local SQLite conductor
 store uses schema version 5 (BAPI-413) to accommodate the `merge.pending_approval`
 type in the `events.type` CHECK constraint.
+
+## Durable execution environment hardening (BAPI-527)
+
+Worker ledger tools are made **reliable again** — this is a robustness fix for the
+worker-facing tools, **not** a new primary completion backstop. The done gate and
+supervisor remain the authority; this change only stops the worker's own
+`check_messages` / `wait_for_done_gate` calls from failing.
+
+**The invariant.** Worker-facing ledger operations run through `conductor-bin.js`
+executed **under the captured conductor Node** (`CONDUCTOR_NODE_PATH`). **The worker
+Node must never load `better-sqlite3`.** Dispatch captures the conductor process's
+own Node executable and threads it to each worker as `CONDUCTOR_NODE_PATH`, paired
+with `BAPI_CONDUCTOR_CLI_FILE` (the packaged `conductor-bin.js` path). The
+worker-side boundary (`src/conductor/worker-ledger-cli.ts`) shells out with a fixed
+**list argv** via `execFile` (never `shell: true`, never a command string) and
+passes event JSON over **stdin** (`--data-json-stdin`), so raw payloads/secrets
+never enter the process argument list. Conductor-**owned** processes (the CLI,
+supervisor, and epic runtimes) keep calling `store.ts` directly — they legitimately
+own the native load.
+
+**Fail loud, never fall back.** A missing/invalid `CONDUCTOR_NODE_PATH` or absent
+`BAPI_CONDUCTOR_CLI_FILE` raises the typed `ConductorLedgerSubprocessRuntimeError`,
+surfaced to callers as the `LEDGER_SUBPROCESS_RUNTIME_UNAVAILABLE` (503) envelope
+with a fixed, path-free, secret-free `details: { env_var, reason }` bag
+(`reason ∈ missing | invalid | cli_missing | spawn_failed | malformed_stdout`). The
+boundary **never** falls back to the worker's `process.execPath` — doing so would
+re-introduce the native load into the worker Node, the exact failure this removes.
+`CONDUCTOR_NODE_PATH` is **non-secret operational metadata**: it is inherited from
+the worker shell env injected at the spawn boundary and is **not** persisted into
+`.mcp.json`, which stays intentionally env-free.
+
+**Rejected alternatives.**
+
+- **Local HTTP sidecar** (a long-lived ledger daemon the worker talks to over a
+  port) — rejected: port conflicts, zombie-process lifecycle management, capability-
+  token handling, and a large failure surface, all disproportionate for a
+  file-backed local ledger.
+- **WASM / pure-JS SQLite in the worker** — rejected: it replaces the proven
+  `better-sqlite3` WAL / synchronous-performance behavior and is a poor fit for a
+  database file shared by multiple processes (the conductor Node and any workers).
+
+### Three protective guarantees (operator view)
+
+BAPI-527 adds three independent reliability guarantees. Each is a protective
+default; none changes the interactive (non-conductor) `start-tickets` contract.
+
+1. **Ledger operations are isolated from the worker path.** Worker `check_messages`
+   / `wait_for_done_gate` run the ledger op in a subprocess under
+   `CONDUCTOR_NODE_PATH` (details above), so a Node ABI mismatch degrades a worker
+   convenience, never the whole session.
+
+2. **Dispatch does not alter your branch.** Unattended/epic dispatch is
+   **non-mutating**: it resolves the base with a fetch-only
+   `origin/<base>` lookup and cuts new worktrees from that fetched SHA. It never
+   checks out, fast-forwards (`git merge --ff-only`), force-moves
+   (`git branch --force`), or stashes the operator's live checkout. A **live-source
+   guard** additionally refuses dispatch (or, with an explicit override, warns
+   loudly) when the conductor's base repo path equals the operator's live
+   dev-server checkout:
+   - `BAPI_CONDUCTOR_LIVE_SOURCE_PATH` — the operator's live dev-server checkout
+     path to protect.
+   - `BAPI_CONDUCTOR_ALLOW_LIVE_SOURCE_DISPATCH` — truthy (`1`/`true`/`yes`/`on`)
+     override that downgrades a collision from fatal to a loud warning.
+   The read-only `doctor` command surfaces the guard state
+   (`not-configured` / `safe` / `collision`) without mutating anything.
+
+3. **Parse runs in a separate process.** The post-merge repository re-index runs
+   out-of-process via `asyncio.create_subprocess_exec`, so the FastAPI event loop
+   stays responsive to concurrent dispatch calls while a CPU-bound parse runs. The
+   ticket enters **`parse_pending`** after merge and folds to **`done`** only when
+   `/parse-status` reports terminal success; a permanent parse failure (or the
+   `max_wait_ms` budget being exhausted) folds it to **`blocked`** with a sanitized
+   reason and never silently wedges the epic. Parse status values are `idle`,
+   `queued`, `in_progress`, `succeeded`, and `failed`; terminal failure reasons are
+   bounded and sanitized (no stderr, tracebacks, argv, or secrets).

package/README.md

@@ -266,10 +266,10 @@ For invocation, prefer the slash command — it's deterministic. A free-text exa
 These features are useful for most tickets.
 
 **1. Review Ticket**
-- **What it does:** Runs a full quality review of a ticket: clarifying questions + critique (initial round), an automatic alternate-model second opinion, then evaluates findings and produces a decision page to accept/reject them. The second-opinion pass is included by default and can be skipped with `--rounds=1`.
+- **What it does:** Runs a full quality review of a ticket: clarifying questions + critique plus an automatic alternate-model second opinion, then evaluates findings and produces a decision page to accept/reject them. The backend executor now owns all review round orchestration (including the second-opinion round) server-side; pass `--rounds=1` for a cheaper single-pass review, `--rounds=2` to force the full second-opinion review, or omit `--rounds` to let the backend's difficulty-adaptive review policy decide.
 - **When it's useful:** (Refinement) Right after a ticket is drafted, before anyone starts building — to surface gaps and tighten it.
 - **How to use it:** `/review-ticket BAPI-123` (command only — "review" as free text is easily mistaken for a freehand agent review).
-- **Flags:** `--auto` auto-accept findings / skip the approval gates · `--rounds=1` skip the automatic second-opinion review step while preserving downstream evaluation and decision-capture work (cheaper single-pass review). `--rounds=2` (default) runs the full two-round review.
+- **Flags:** `--auto` auto-accept findings / skip the approval gates · `--rounds=1` request a cheaper single-pass review (no second-opinion round) while preserving downstream evaluation and decision-capture work · `--rounds=2` force the full second-opinion review · omit `--rounds` to let the backend's difficulty-adaptive review policy decide (it falls back to a full second-opinion review when adaptive routing is disabled or the ticket's difficulty cannot be resolved).
 - **Multi-ticket fan-out:** `/review-tickets BAPI-123 BAPI-456` opens one terminal tab per ticket for parallel review with no worktrees (terminal launcher only — no `wt`/`git`). All `/review-ticket` flags apply; `--review KEY=auto,rounds=N` sets per-ticket overrides. Packaged CLI: `npx -y @bridge_gpt/mcp-server review-tickets KEY [KEY ...]`.
 
 **2. Start Tickets**
@@ -497,10 +497,13 @@ All SFCC tools are read-only and target a developer sandbox. Oversized responses
 **Custom object definitions** (needs the `sfcc` profile)
 - `custom_object_definition_attributes_get` — fetch attribute definitions for a known custom object type. OCAPI cannot enumerate custom object types, so `object_type` must already be known.
 - `custom_object_definition_attribute_search` — search attribute definitions within a known custom object type. Read-only — creating a custom object *type* isn't possible via OCAPI; that's a future v2 metadata-import capability.
+- `custom_object_definition_attribute_create` — **write** (sandbox only): create an attribute definition on a known custom object type via `PUT /custom_object_definitions/{type}/attribute_definitions/{id}`. TYPE creation is never attempted (the type must pre-exist). Echoes paste-ready OCAPI grant JSON on 403.
+- `custom_object_definition_attribute_update` — **write** (sandbox only): update an attribute definition via an ETag-conditional `PATCH …/attribute_definitions/{id}`; surfaces 409/412 conflicts and echoes grant JSON on 403.
 
 **Site preferences** (needs the `sfcc` profile; sandbox only)
 - `site_preference_get` — read a preference group's effective preferences.
 - `site_preference_search` — search/filter preferences within a group.
+- `site_preference_values_set` — **write** (sandbox only): set custom preference values via `PATCH /site_preferences/preference_groups/{group}/sandbox` with a flat map of `c_`-prefixed ids to string/number/boolean/string[] values. A bad group returns 404 `CustomPreferenceGroupNotFoundException`; echoes grant JSON on 403.
 
 ## CLI Subcommands
 
@@ -688,13 +691,13 @@ The full surface, for when you need the complete enumeration. Day-to-day, use [U
 
 ### MCP tools
 
-The server exposes **58 documented tools** (enumerated below). What's actually registered in a session depends on `BRIDGE_MCP_PROFILE`: the default `core` profile loads a trimmed subset, and the conductor/pipeline-authoring/SFCC tools are added only under their respective profiles (see [Environment Variables](#environment-variables)). Async AI tools follow a request/get pattern: call the `request_*` tool to kick off generation, then the matching `get_*` tool to retrieve the result (or pass `wait_for_result: true` to poll automatically).
+The server exposes **59 documented tools** (enumerated below). What's actually registered in a session depends on `BRIDGE_MCP_PROFILE`: the default `core` profile loads a trimmed subset, and the conductor/pipeline-authoring/SFCC tools are added only under their respective profiles (see [Environment Variables](#environment-variables)). Async AI tools follow a request/get pattern: call the `request_*` tool to kick off generation, then the matching `get_*` tool to retrieve the result (or pass `wait_for_result: true` to poll automatically).
 
 - **Connectivity & identity** — `ping`, `get_my_role`, `get_docs_dir`
 - **Jira tickets** — `get_tickets`, `get_ticket`, `create_ticket`, `update_ticket_description`, `add_comment`, `get_comments`
 - **Attachments** — `attachment` (operations: `upload`, `download`, `list`)
 - **AI generation (request/get)** — `request_plan_generation`/`get_plan`, `request_architecture`/`get_architecture`, `create_doc`/`get_doc` (design docs by `doc_type`: tdd/fsd/prd), `request_prd`/`get_prd`, `request_clarifying_questions`/`get_clarifying_questions`, `request_ticket_critique`/`get_ticket_critique`, `request_ticket_review`, `request_reimplement_context`/`get_reimplement_context`, `request_brainstorm`/`get_brainstorm`, `request_deep_research`/`get_deep_research`
-- **Other AI** — `second_opinion`, `generate_image`, `generate_decision_page`
+- **Other AI** — `second_opinion`, `generate_image`, `generate_decision_page`, `visual_diff` (deterministic pixel diff of a rendered URL vs a design comp)
 - **Ticket lifecycle** — `track_ticket`, `update_ticket_state`, `get_ticket_state`
 - **Jira status** — `get_jira_transitions`, `update_jira_status`, `resolve_target_status`
 - **Repository & CI** — `parse_repository`, `get_parse_status`, `regenerate_directory_map`, `create_pull_request`, `resolve_ci_checks`, `poll_ci_checks`
@@ -708,7 +711,7 @@ Pipelines are declarative, multi-step workflows your AI agent executes step-by-s
 | Pipeline | Description | Invoke with |
 |---|---|---|
 | `implement-ticket` | Generate a plan, execute the implementation, commit, open a PR, and monitor CI | `/implement-ticket PROJ-123` |
-| `review-ticket` | Full ticket quality review: initial clarifying questions + critique, automatic second-opinion pass (default), then evaluation and decision capture. Pass `--rounds=1` to skip the second-opinion step (`--rounds=2` is the default). | `/review-ticket PROJ-123` |
+| `review-ticket` | Full ticket quality review: clarifying questions + critique plus an automatic second-opinion pass, then evaluation and decision capture. The backend owns round orchestration; pass `--rounds=1` for a single-pass review or `--rounds=2` to force the full second-opinion review, or omit `--rounds` to let the backend decide adaptively. | `/review-ticket PROJ-123` |
 | `idea-to-ticket` | Turn an idea into a Jira Task/Spike (or Epic + children) with research, dedup, and critique | `/idea-to-ticket "<idea>"` |
 | `plan-epic` | Decompose an epic into sub-tasks with a structured exploration doc for each | `/plan-epic "<epic>"` |
 | `full-automation` | Chain: idea → ticket(s) → review each → spawn worktrees to implement | `/full-automation "<idea>"` |

package/build/agent-capabilities/probe-context.js

@@ -18,9 +18,12 @@ import { DEFAULT_PROBE_TIMEOUT_MS, } from "./types.js";
  *
  * - cursor-agent: `-p --output-format <fmt> --trust --workspace <cwd> <prompt>`.
  *   `--trust` is MANDATORY headless or the workspace-trust prompt hangs; cursor has
- *   its own `--workspace` cwd flag.
- * - claude: `-p [--output-format json] <prompt>`. Claude has NO working-dir flag —
- *   cwd is set via the spawn options, never an argument.
+ *   its own `--workspace` cwd flag. All `OutputFormat` values (including `stream-json`)
+ *   pass through the generic `--output-format <fmt>` slot.
+ * - claude: `-p [--dangerously-skip-permissions] [--model <m>] [--output-format json|
+ *   stream-json --verbose] <prompt>`. Claude has NO working-dir flag — cwd is set via
+ *   the spawn options, never an argument. `stream-json` REQUIRES `--verbose`. The
+ *   prompt is ALWAYS the final argv element so mocked prompt extraction stays valid.
  */
 export function buildHeadlessArgs(agentName, opts) {
     const fmt = opts.outputFormat ?? "text";
@@ -29,8 +32,15 @@ export function buildHeadlessArgs(agentName, opts) {
     }
     // claude (and any positional-prompt agent without a cwd flag)
     const args = ["-p"];
+    if (opts.skipPermissions === true)
+        args.push("--dangerously-skip-permissions");
+    if (typeof opts.model === "string" && opts.model.trim().length > 0) {
+        args.push("--model", opts.model);
+    }
     if (fmt === "json")
         args.push("--output-format", "json");
+    else if (fmt === "stream-json")
+        args.push("--output-format", "stream-json", "--verbose");
     args.push(opts.prompt);
     return args;
 }

package/build/agent-capabilities/probes.js

@@ -15,6 +15,30 @@ function truncate(text) {
     const flat = text.replace(/\s+/g, " ").trim();
     return flat.length > EVIDENCE_MAX ? `${flat.slice(0, EVIDENCE_MAX)}…` : flat;
 }
+/**
+ * Validate a `--output-format stream-json` stdout as a newline-delimited JSON
+ * envelope: split on newlines, discard blank lines, and require at least one
+ * non-empty line with every remaining line parsing as JSON. Advisory-only — the
+ * output-format probe uses this for telemetry validation, never executor gating.
+ */
+function validateStreamJsonLines(stdout) {
+    const lines = stdout
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0);
+    if (lines.length === 0) {
+        return { ok: false, reason: "no non-empty stream-json lines were emitted" };
+    }
+    for (const line of lines) {
+        try {
+            JSON.parse(line);
+        }
+        catch {
+            return { ok: false, reason: "a stream-json line was not parseable JSON" };
+        }
+    }
+    return { ok: true };
+}
 /** Verbatim body of the disposable `.claude/commands/echo-test.md` probe command. */
 function echoCommandBody(marker) {
     return [
@@ -190,8 +214,10 @@ const preambleMidPrompt = {
 };
 const outputFormat = {
     id: "output-format",
-    title: "Honors --output-format text and json",
-    description: "Text mode emits the plain marker; json mode emits a parseable JSON envelope.",
+    title: "Honors --output-format text, json, and stream-json",
+    description: "Text mode emits the plain marker; json mode emits a parseable JSON envelope; " +
+        "stream-json mode emits a parseable newline-delimited JSON line envelope. The " +
+        "stream-json check is advisory telemetry validation only — no executor behavior gates on it.",
     tier: "structural",
     appliesTo: ["claude", "cursor-agent"],
     spawnsAgent: true,
@@ -211,20 +237,46 @@ const outputFormat = {
             cwd: dir,
             outputFormat: "json",
         });
-        const nonExited = nonExitedResult(jsonRun);
-        if (nonExited)
-            return nonExited;
-        const { exitCode, stdout, elapsedMs } = jsonRun;
-        if (exitCode !== 0) {
-            return { status: "fail", detail: `json output-format exited ${exitCode}`, elapsedMs, evidence: truncate(stdout) };
+        const jsonNonExited = nonExitedResult(jsonRun);
+        if (jsonNonExited)
+            return jsonNonExited;
+        const jsonExited = jsonRun;
+        if (jsonExited.exitCode !== 0) {
+            return { status: "fail", detail: `json output-format exited ${jsonExited.exitCode}`, elapsedMs: jsonExited.elapsedMs, evidence: truncate(jsonExited.stdout) };
         }
         try {
-            JSON.parse(stdout.trim());
+            JSON.parse(jsonExited.stdout.trim());
         }
         catch {
-            return { status: "fail", detail: "json output-format did not emit parseable JSON", elapsedMs, evidence: truncate(stdout) };
+            return { status: "fail", detail: "json output-format did not emit parseable JSON", elapsedMs: jsonExited.elapsedMs, evidence: truncate(jsonExited.stdout) };
+        }
+        // Advisory stream-json validation (§15.2): parse the newline-delimited envelope.
+        const streamRun = await ctx.runHeadless({
+            prompt: `Do not use any tools. Output exactly the token ${marker}.`,
+            cwd: dir,
+            outputFormat: "stream-json",
+        });
+        const streamNonExited = nonExitedResult(streamRun);
+        if (streamNonExited)
+            return streamNonExited;
+        const streamExited = streamRun;
+        if (streamExited.exitCode !== 0) {
+            return { status: "fail", detail: `stream-json output-format exited ${streamExited.exitCode}`, elapsedMs: streamExited.elapsedMs, evidence: truncate(streamExited.stdout) };
+        }
+        const streamCheck = validateStreamJsonLines(streamExited.stdout);
+        if (!streamCheck.ok) {
+            return {
+                status: "fail",
+                detail: "stream-json output-format did not emit parseable newline-delimited JSON",
+                elapsedMs: streamExited.elapsedMs,
+                evidence: truncate(streamExited.stdout),
+            };
         }
-        return { status: "pass", detail: "text marker present and json parseable", elapsedMs };
+        return {
+            status: "pass",
+            detail: "text marker present, json parseable, and stream-json line-envelope parseable",
+            elapsedMs: streamExited.elapsedMs,
+        };
     },
 };
 const workspaceFlag = {
@@ -261,6 +313,204 @@ const noCwdFlag = {
         return { status: "fail", detail: `unexpected cwd flag(s) in argv: ${offenders.join(", ")}` };
     },
 };
+/** File the deny probe asks the agent to `cat`; its sole content is the allowed marker. */
+const DENY_TARGET_FILE = "deny-probe-target.txt";
+/** `permissions.deny` rule blocking the `cat` Bash command (the denied action). */
+const DENY_BASH_RULE = "Bash(cat:*)";
+/** PreToolUse matcher for the fallback hook — mirrors the conductor Bash-tool matcher style. */
+const DENY_HOOK_MATCHER = "Bash";
+/**
+ * Command body for the fallback `PreToolUse` deny hook. Emits the local block
+ * convention (`.claude/hooks/check_mutating_sql.py`): a `permissionDecision: "deny"`
+ * JSON object on stdout, exit 0. `printf` avoids echo's backslash portability
+ * differences; the JSON contains no single quotes so single-quoting is safe.
+ */
+function denyHookCommand() {
+    const payload = JSON.stringify({
+        hookSpecificOutput: {
+            hookEventName: "PreToolUse",
+            permissionDecision: "deny",
+            permissionDecisionReason: "agent-capability deny-enforcement probe fallback: tool call denied.",
+        },
+    });
+    return `printf '%s' '${payload}'`;
+}
+/** Seed the `cat` target file whose only content is the unique allowed marker. */
+async function seedDenyTargetFile(ctx, dir, marker) {
+    await ctx.deps.writeFile(join(dir, DENY_TARGET_FILE), `${marker}\n`);
+}
+/** Seed `<dir>/.claude/settings.local.json` with a minimal `permissions.deny` rule. */
+async function seedDenySettings(ctx, dir, marker) {
+    await seedDenyTargetFile(ctx, dir, marker);
+    const claudeDir = join(dir, ".claude");
+    await ctx.deps.mkdir(claudeDir, { recursive: true });
+    const settings = { permissions: { deny: [DENY_BASH_RULE] } };
+    await ctx.deps.writeFile(join(claudeDir, "settings.local.json"), `${JSON.stringify(settings, null, 2)}\n`);
+}
+/** Seed `<dir>/.claude/settings.local.json` with the `PreToolUse` deny-hook fallback. */
+async function seedDenyHook(ctx, dir, marker) {
+    await seedDenyTargetFile(ctx, dir, marker);
+    const claudeDir = join(dir, ".claude");
+    await ctx.deps.mkdir(claudeDir, { recursive: true });
+    const settings = {
+        hooks: {
+            PreToolUse: [
+                { matcher: DENY_HOOK_MATCHER, hooks: [{ type: "command", command: denyHookCommand() }] },
+            ],
+        },
+    };
+    await ctx.deps.writeFile(join(claudeDir, "settings.local.json"), `${JSON.stringify(settings, null, 2)}\n`);
+}
+/**
+ * Prompt instructing the agent to attempt the denied Bash call and echo its output.
+ * The allowed marker is deliberately NOT in the prompt — the agent can only produce
+ * it by actually running the (denied) Bash command, so the marker is un-fabricable.
+ */
+function denyProbePrompt() {
+    return [
+        "This is an agent-capability probe of permission enforcement.",
+        `Use the Bash tool to run exactly this command: cat ${DENY_TARGET_FILE}`,
+        "Then output the command's exact stdout on its own line.",
+        "Use ONLY the Bash tool for this — do not use Read, Grep, or any other tool, and do not open the file yourself.",
+        "If the Bash command is blocked, denied, or errors, output the single word DENIED and nothing else.",
+        "Do not guess, fabricate, or infer the file contents — only report what the command actually returned.",
+    ].join("\n");
+}
+/** Attach a deny-enforcement layer to a probe result's metadata (bounded, secret-free). */
+function withDenyLayer(result, layer) {
+    return { ...result, metadata: { ...(result.metadata ?? {}), layer } };
+}
+/**
+ * Classify one deny-probe headless run. Uses `nonExitedResult` first so hangs and
+ * spawn errors remain loud; a clean exit with the allowed marker means the call ran
+ * (allowed), and a clean exit without it means the call was rejected (blocked).
+ */
+function evaluateDenyRun(run, allowedMarker) {
+    const nonExited = nonExitedResult(run);
+    if (nonExited)
+        return { kind: "nonexited", result: nonExited };
+    const { exitCode, stdout, stderr, elapsedMs } = run;
+    if (exitCode !== 0) {
+        return {
+            kind: "error",
+            result: {
+                status: "fail",
+                detail: `deny-enforcement probe agent exited ${exitCode}`,
+                elapsedMs,
+                evidence: truncate(stdout || stderr),
+            },
+        };
+    }
+    if (stdout.includes(allowedMarker)) {
+        return { kind: "allowed", evidence: truncate(stdout) };
+    }
+    return { kind: "blocked", evidence: truncate(stdout || stderr) };
+}
+/**
+ * Run the shared deny-enforcement check: a no-deny CONTROL run FIRST (proving the
+ * agent actually attempts the canary call — absence of the marker in a deny run is
+ * only evidence of enforcement once the control shows the marker), then settings
+ * `permissions.deny`, and the `PreToolUse` hook fallback ONLY when the settings run
+ * exits cleanly but allows the denied call. Hangs and spawn errors are returned
+ * loudly and never fall through to the next run. Returns the probe result plus the
+ * enforcing layer. Reused by the capability probe AND the executor preflight so both
+ * share identical behavior.
+ */
+export async function runDenyEnforcementCheck(ctx, opts) {
+    const marker = ctx.marker("DENY_ALLOWED");
+    const prompt = denyProbePrompt();
+    const runOpts = { skipPermissions: true, model: opts?.model, timeoutMs: opts?.timeoutMs };
+    // 0) CONTROL: same temp-project shape and prompt, NO deny rule. The marker MUST
+    //    surface here — otherwise the agent never attempted the canary Bash call and
+    //    a marker-free deny run would be a refusal, not enforcement (NEVER a pass).
+    const controlDir = await ctx.makeTempProject((d) => seedDenyTargetFile(ctx, d, marker));
+    const controlRun = await ctx.runHeadless({ prompt, cwd: controlDir, ...runOpts });
+    const c = evaluateDenyRun(controlRun, marker);
+    if (c.kind === "nonexited")
+        return { result: withDenyLayer(c.result, "none"), layer: "none" };
+    if (c.kind === "error")
+        return { result: withDenyLayer(c.result, "none"), layer: "none" };
+    if (c.kind === "blocked") {
+        return {
+            result: withDenyLayer({
+                status: "fail",
+                detail: "control run (no deny rule) did not execute the canary call — the agent never " +
+                    "attempted the Bash command, so deny enforcement cannot be verified " +
+                    "(a refusal is NOT enforcement)",
+                elapsedMs: controlRun.elapsedMs,
+                evidence: c.evidence,
+            }, "none"),
+            layer: "none",
+        };
+    }
+    // c.kind === "allowed": the agent demonstrably attempts the call here — a
+    // marker-free clean exit in the runs below now genuinely means "rejected".
+    // 1) settings permissions.deny (preferred layer).
+    const denyDir = await ctx.makeTempProject((d) => seedDenySettings(ctx, d, marker));
+    const settingsRun = await ctx.runHeadless({ prompt, cwd: denyDir, ...runOpts });
+    const s = evaluateDenyRun(settingsRun, marker);
+    if (s.kind === "nonexited")
+        return { result: withDenyLayer(s.result, "none"), layer: "none" };
+    if (s.kind === "error")
+        return { result: withDenyLayer(s.result, "none"), layer: "none" };
+    if (s.kind === "blocked") {
+        return {
+            result: withDenyLayer({
+                status: "pass",
+                detail: "denied call rejected by settings permissions.deny",
+                elapsedMs: settingsRun.elapsedMs,
+                evidence: s.evidence,
+            }, "settings-deny"),
+            layer: "settings-deny",
+        };
+    }
+    // 2) settings deny did NOT reject — try the PreToolUse hook fallback.
+    const hookDir = await ctx.makeTempProject((d) => seedDenyHook(ctx, d, marker));
+    const hookRun = await ctx.runHeadless({ prompt, cwd: hookDir, ...runOpts });
+    const h = evaluateDenyRun(hookRun, marker);
+    if (h.kind === "nonexited")
+        return { result: withDenyLayer(h.result, "none"), layer: "none" };
+    if (h.kind === "error")
+        return { result: withDenyLayer(h.result, "none"), layer: "none" };
+    if (h.kind === "blocked") {
+        return {
+            result: withDenyLayer({
+                status: "pass",
+                detail: "settings deny did not reject; PreToolUse hook fallback rejected the call",
+                elapsedMs: hookRun.elapsedMs,
+                evidence: h.evidence,
+            }, "pretooluse-hook"),
+            layer: "pretooluse-hook",
+        };
+    }
+    // 3) allowed by BOTH — deny is not enforced on this installed CLI version.
+    return {
+        result: withDenyLayer({
+            status: "fail",
+            detail: "deny is NOT enforced for this installed Claude version under --dangerously-skip-permissions " +
+                "(neither settings permissions.deny nor a PreToolUse hook rejected the denied call)",
+            elapsedMs: hookRun.elapsedMs,
+            evidence: h.evidence,
+        }, "none"),
+        layer: "none",
+    };
+}
+const denyEnforcement = {
+    id: "deny-enforcement",
+    title: "Enforces a permissions.deny rule under --dangerously-skip-permissions",
+    description: "Runs a no-deny control run first (proving the agent actually attempts the canary call), then spawns " +
+        "claude headless with --dangerously-skip-permissions in a disposable temp project carrying a " +
+        "permissions.deny rule, attempts the denied call, and asserts it is rejected — reporting which layer " +
+        "enforced (settings-deny vs a PreToolUse hook fallback). A fail means deny is NOT enforced on the " +
+        "installed CLI (or cannot be verified) and is a load-bearing executor preflight signal.",
+    tier: "heavy",
+    appliesTo: ["claude"],
+    spawnsAgent: true,
+    async run(ctx) {
+        const { result } = await runDenyEnforcementCheck(ctx);
+        return result;
+    },
+};
 /** All probes in deterministic report order. */
 export const ALL_PROBES = [
     binaryResolves,
@@ -269,6 +519,7 @@ export const ALL_PROBES = [
     claudeCommandsResolve,
     preambleMidPrompt,
     outputFormat,
+    denyEnforcement,
     workspaceFlag,
     noCwdFlag,
 ];

package/build/agent-capabilities/reporter.js

@@ -45,6 +45,7 @@ export function formatCapabilityJson(collection) {
             detail: r.result.detail,
             elapsedMs: r.result.elapsedMs ?? null,
             evidence: r.result.evidence ?? null,
+            metadata: r.result.metadata ?? null,
         })),
     }, null, 2);
 }

package/build/agents.generated.js

@@ -8,7 +8,7 @@ export const AGENTS = {
             "model": "opus",
             "color": "blue"
         },
-        "body": "\nYou are an elite software engineering project manager and technical analyst with deep expertise in codebase archaeology and Jira ticket crafting. You excel at understanding complex codebases, identifying relevant existing code, and translating problem descriptions into precisely-scoped, actionable Jira tickets that engineers can pick up and execute with minimal ambiguity.\n\n## Your Mission\n\nGiven a problem description from the user, you will:\n1. Conduct thorough codebase research to understand the existing architecture, patterns, and relevant code\n2. Write a structured Jira ticket as a new markdown file that references specific files, functions, and patterns from the codebase\n\n## Phase 1: Deep Codebase Research\n\nThis is the most critical phase. You MUST spend significant time here before writing anything. Do NOT rush this phase.\n\n### Research Protocol\n\n1. **Understand the Problem Space**: Re-read the user's problem description carefully. Identify the domain, the affected areas, and the type of change needed (new feature, bug fix, refactor, enhancement).\n\n2. **Map the Relevant Architecture**: \n   - Search for files, modules, and directories related to the problem domain\n   - Read the key source files thoroughly — do not skim\n   - Trace code paths: how does data flow through the relevant parts of the system?\n   - Identify controller -> helper -> service -> model chains if applicable\n\n3. **Identify Extension Points**:\n   - What existing code can be reused or extended?\n   - What patterns does the codebase already use for similar functionality?\n   - Are there helper functions, utilities, or base classes that should be leveraged?\n   - Are there configuration files, metadata definitions, or templates that need modification?\n\n4. **Identify Constraints**:\n   - What conventions does the project follow? (Check CLAUDE.md, README, existing patterns)\n   - What testing patterns are used?\n   - Are there ES5 limitations, specific framework patterns, or platform constraints?\n\n5. **Catalog Your Findings**: Keep mental notes of every relevant file path, function name, pattern, and architectural decision you discover. You will reference these in the ticket.\n\n### Research Depth Guidelines\n- Read at least 5-15 relevant source files in full, more if the problem is complex\n- Follow import chains to understand dependencies\n- Check test files to understand expected behaviors and testing patterns\n- Review configuration and metadata files if relevant\n- Search for TODO comments, known limitations, or related existing issues in the code\n\n## Phase 2: Write the Jira Ticket\n\nAfter completing research, create a new markdown file with the ticket. Use the naming convention `tickets/TICKET-<short-descriptive-name>.md`. If the `tickets/` directory does not exist, create it.\n\n### Ticket Structure\n\nThe markdown file MUST contain exactly these sections:\n\n```markdown\n# [Concise Title Describing the Task]\n\n## Summary\n\n[2-4 sentences describing what this task is about, why it matters, and the high-level approach. Be specific — reference the actual system components involved.]\n\n## Requirements\n\n[Numbered list of specific, actionable requirements. Each requirement should be a clear unit of work.]\n\n1. **[Requirement Title]**: [Description of what needs to be done.]\n   - *Relevant code*: `path/to/file.js` — `functionName()` [brief note on how this code relates]\n   - *Relevant code*: `path/to/other/file.js` — [brief note]\n\n2. **[Requirement Title]**: [Description]\n   - *Relevant code*: ...\n\n[Continue for all requirements]\n\n## Acceptance Criteria\n\n[Bullet list. Each criterion is a testable, verifiable condition.]\n\n- [Specific, testable criterion]\n- [Another criterion]\n- [Continue as needed]\n\n## Materials & Access\n\n[Trailing audit-trail section — always the LAST section of the draft. Inventory every material the ticket references, grouped by source. Use monospace backticks for file paths and other technical provenance. Redact any embedded secrets.]\n\n### Reachable Local Files\n\n- `path/to/local/file.ext` — [what it is; will be gathered and attached post-create]\n\n### External/Auth-Gated Links\n\n- [Name or purpose] — `https://example.com/...` (record-only; external/auth-gated)\n\n### Binary/Image Materials (Record-Only)\n\n- `path/to/screenshot.png` — [sanitized location/access note; not attached]\n```\n\n### Writing Guidelines\n\n**Summary**:\n- Be concrete, not abstract. Name the actual components, cartridges, or subsystems involved.\n- State the \"why\" — what problem does this solve or what value does it add?\n- Mention the general technical approach if it's clear from the research.\n\n**Requirements**:\n- Each requirement should represent a logical unit of work\n- Order requirements in a logical implementation sequence when possible\n- ALWAYS cite relevant existing files and functions when they exist. Use exact file paths relative to the project root.\n- Explain HOW the existing code relates: \"extend this function\", \"follow this pattern\", \"reuse this helper\", \"modify this configuration\"\n- If a requirement involves creating new files, suggest where they should live based on existing project structure conventions\n- Be specific about what needs to change vs. what needs to be created new\n- Include requirements for tests, documentation, and configuration/metadata changes if applicable\n\n**Acceptance Criteria**:\n- Every criterion must be independently verifiable\n- Cover functional requirements, edge cases, testing, and non-functional requirements\n- Include criteria for backwards compatibility if relevant\n- Include criteria for test coverage\n- Use plain `-` bullets (Jira's ADF has no native checkbox, so `- [ ]` renders as literal text)\n\n**Materials Completeness Inventory**:\n- After the draft is written, INVENTORY every material the ticket references: local file paths, URLs/links, named docs/designs, screenshots, and specs. This pass only INVENTORIES and RECORDS — it does NOT attach anything. The actual attachment of reachable local files happens post-create (after the Jira `ticket_key` exists) via a separate gather-and-attach step.\n- Classify each material by source using a scheme-based rule (no network probe required):\n  - **Local filesystem paths** named in the ticket body are the only **low-risk** materials — eligible to be gathered and attached post-create.\n  - Every **`http(s)` URI is external/auth-gated** — regardless of whether the user explicitly linked it (an explicitly-linked Confluence or Google Doc URL is still external/auth-gated) — and is **record-only** here.\n  - **Binary/image materials** (screenshots, PDFs, etc.) are **record-only** — document them with sanitized location/access notes; do NOT attempt to attach them.\n- Write the trailing `## Materials & Access` section (the LAST section of the draft) grouping items under the sub-headings *Reachable Local Files*, *External/Auth-Gated Links*, and *Binary/Image Materials (Record-Only)*, using bulleted lists. Use monospace formatting (backticks) for technical provenance such as file paths.\n- **Redact secrets before writing anything**: before writing any URL or access note, sanitize and redact embedded credentials, SAS tokens, API keys, and basic-auth secrets using a high-visibility placeholder such as `[REDACTED_TOKEN]`. A location/access note must NEVER expose a plaintext secret.\n\n### Regression Completeness Pass (Gated)\n\nAfter the draft (including its `## Materials & Access` section) is written, run this pass. It is a non-blocking, **warn-not-halt** completeness check — it never blocks or fails ticket creation, and it never modifies the Requirements or Acceptance Criteria text directly.\n\n1. **Check the gate first.** Call the `config_field` MCP tool with `operation` set to `\"get\"` and `field_name` set to `enable_regression_checks`. If the tool returns an error, `null`, or any value other than the literal string `\"true\"`, **skip this entire pass** — the draft is produced exactly as it would be without this section (byte-for-byte unchanged). The recommended default for this flag is OFF (unset) for safe rollout; only proceed past this step when it is explicitly `\"true\"`.\n\n2. **Derive the touched-symbol set.** From the draft's Requirements and *Relevant code* citations (or, if the ticket references an existing diff/PR, that diff/PR), extract the specific function/class/symbol names the proposed change touches.\n\n3. **Run the deterministic core.** Execute:\n   ```bash\n   npx -y @bridge_gpt/mcp-server regression-check --mode lightweight --json --symbols <derived,symbol,names>\n   ```\n   This is the same subcommand the standalone `regression-reviewer` agent and `regression-check` command use — do not hand-roll your own `ast-grep`/`ripgrep` discovery.\n\n4. **Fail-open on a degraded or failed run.** If the command errors, or `summary.degraded_flags` is non-empty, record that the pass ran degraded (or could not run) and proceed — the draft is still produced. Never halt ticket creation because this subcommand was unavailable.\n\n5. **Cross-check against Requirements + Acceptance Criteria.** Parse the JSON `findings` array (`symbol`, `call_sites.by_file`, `broad_mentions`). For each symbol, compare its real call-sites and broad mentions against what the draft's Requirements and Acceptance Criteria already cover. Flag any affected caller, migration, or contract (a file with a real call-site or an uninspected broad mention) that the criteria do NOT mention.\n\n6. **Record the flags — never rewrite Requirements/Acceptance Criteria.** Append a `[WARNING]` block immediately before the `## Materials & Access` section, listing each flagged item:\n   ```markdown\n   ## Regression Completeness Notes\n\n   [WARNING] The following systems were not explicitly addressed in the Requirements or Acceptance Criteria above:\n   - `path/to/affected_caller.py` — calls `changed_symbol` (N real call-sites); not mentioned in Requirements\n   - `path/to/config.yml` — broad mention of `changed_symbol`; verify this reference is unaffected\n\n   Degraded: [list summary.degraded_flags, or \"none — full structural analysis ran\"]\n   ```\n   If no flags were raised and the run was not degraded, write a single line instead: `Regression completeness pass: no unaddressed systems found.` If the run was degraded with zero findings either way, state that explicitly rather than implying a clean pass.\n\n### Output Formatting (Jira upload)\n\nThe ticket is uploaded to Jira, which converts the Markdown to Atlassian Document Format (ADF) and hard-caps the description at **32,767 characters**. Keep the output clean and within budget:\n\n- **Length**: aim for under ~30,000 characters. If the scope genuinely needs more, split into a parent ticket plus sub-tickets rather than one oversized ticket.\n- **Acceptance Criteria**: plain `-` bullets, not `- [ ]` (ADF has no native checkbox).\n- **No images**: do not embed images or use relative image links. This \"No images\" rule applies strictly to inline images in the description body; it does NOT restrict the attachments produced by the Materials Completeness Inventory / gather-and-attach pass.\n- **No empty headings**: every heading must have text on its line.\n- **Placeholders**: prefer `{placeholder}` over `<placeholder>`.\n\n## Quality Standards\n\n- **No vague language**: Replace \"should handle errors properly\" with \"should catch LLM provider timeouts and return a normalized error response with errorType 'TimeoutError'\"\n- **No assumptions without evidence**: Only reference code you actually read during research. If you're unsure about something, say so explicitly in the ticket.\n- **Appropriate scope**: The ticket should represent a coherent, deliverable unit of work. If the problem is too large, note that it may need to be broken into sub-tasks, but still write the parent ticket.\n- **Developer empathy**: Write as if the developer picking this up has general project knowledge but hasn't recently worked on this specific area. Give them enough context to get started quickly.\n\n## Important Reminders\n\n- Do NOT skip or abbreviate the research phase. The quality of the ticket depends entirely on the depth of your codebase understanding.\n- Do NOT make up file paths or function names. Only reference code you have actually found and read.\n- DO create the markdown file — do not just output the content to the chat. Write it to disk.\n- If the project has specific conventions (from CLAUDE.md or similar), ensure your ticket's requirements align with those conventions.\n"
+        "body": "\nYou are an elite software engineering project manager and technical analyst with deep expertise in codebase archaeology and Jira ticket crafting. You excel at understanding complex codebases, identifying relevant existing code, and translating problem descriptions into precisely-scoped, actionable Jira tickets that engineers can pick up and execute with minimal ambiguity.\n\n## Your Mission\n\nGiven a problem description from the user, you will:\n1. Conduct thorough codebase research to understand the existing architecture, patterns, and relevant code\n2. Write a structured Jira ticket as a new markdown file that references specific files, functions, and patterns from the codebase\n\n## Phase 1: Deep Codebase Research\n\nThis is the most critical phase. You MUST spend significant time here before writing anything. Do NOT rush this phase.\n\n### Research Protocol\n\n1. **Understand the Problem Space**: Re-read the user's problem description carefully. Identify the domain, the affected areas, and the type of change needed (new feature, bug fix, refactor, enhancement).\n\n2. **Map the Relevant Architecture**: \n   - Search for files, modules, and directories related to the problem domain\n   - Read the key source files thoroughly — do not skim\n   - Trace code paths: how does data flow through the relevant parts of the system?\n   - Identify controller -> helper -> service -> model chains if applicable\n\n3. **Identify Extension Points**:\n   - What existing code can be reused or extended?\n   - What patterns does the codebase already use for similar functionality?\n   - Are there helper functions, utilities, or base classes that should be leveraged?\n   - Are there configuration files, metadata definitions, or templates that need modification?\n\n4. **Identify Constraints**:\n   - What conventions does the project follow? (Check CLAUDE.md, README, existing patterns)\n   - What testing patterns are used?\n   - Are there ES5 limitations, specific framework patterns, or platform constraints?\n\n5. **Catalog Your Findings**: Keep mental notes of every relevant file path, function name, pattern, and architectural decision you discover. You will reference these in the ticket.\n\n### Research Depth Guidelines\n- Read at least 5-15 relevant source files in full, more if the problem is complex\n- Follow import chains to understand dependencies\n- Check test files to understand expected behaviors and testing patterns\n- Review configuration and metadata files if relevant\n- Search for TODO comments, known limitations, or related existing issues in the code\n\n### Consuming a Comp→Codebase Map (optional upstream input)\n\nYou may be handed a precomputed comp→codebase map (`comp-analysis.json`) produced by an **upstream orchestrating vision step** (the recipe's `comp-analysis.md` step, or the `/write-ticket` Stage 0.5 pre-draft pass). That upstream step is a frontier vision model that already opened the design comp, classified it, and mapped its regions to concrete existing code. You remain **text-only**: you **must not open images**, embed images, download attachments, or perform any vision analysis yourself — you only read the JSON map as focused research input.\n\n- **When the map is missing or has `applicable: false`** (a backend-only request, a no-comp request, a non-design request, or a degraded/unreadable comp): **ignore the artifact entirely**. Do NOT mention comp analysis, design comps, visual fidelity, map artifacts, or image-derived requirements at all — unless the user's original request independently requires those materials. A backend-only or no-comp ticket must read exactly as it would with no map present.\n- **When the map has `applicable: true`**: read it in full before drafting and treat it as authoritative, focused research. Before citing any file the map names (component, template, token, or route), **inspect/read that concrete file yourself** — the standing rule that you do not make up file paths, function names, components, tokens, or routes still applies to map-sourced references.\n- **Class-appropriate depth** (mirror the map's `fidelity_classification.class`, the same shared taxonomy the downstream final plan reviewer uses):\n  - `full comp` (confident) → you may write exact component/template/token/route Requirements.\n  - `wireframe` → write layout/structure Requirements only; defer color, type, spacing, and component polish to the repo design system, not the wireframe.\n  - `annotated-screenshot-of-existing-UI` → write delta-only Requirements (change only the annotated region; preserve the rest).\n  - `unknown` / low confidence → use the design-system floor rather than pixel-exact Requirements.\n\n  Hard rule: exact/strict mapping depth is used ONLY for a confidently-classified full comp. Fail toward the design system, never toward reproducing an ambiguous image.\n\n## Phase 2: Write the Jira Ticket\n\nAfter completing research, create a new markdown file with the ticket. Use the naming convention `tickets/TICKET-<short-descriptive-name>.md`. If the `tickets/` directory does not exist, create it.\n\n### Ticket Structure\n\nThe markdown file MUST contain exactly these sections:\n\n```markdown\n# [Concise Title Describing the Task]\n\n## Summary\n\n[2-4 sentences describing what this task is about, why it matters, and the high-level approach. Be specific — reference the actual system components involved.]\n\n## Requirements\n\n[Numbered list of specific, actionable requirements. Each requirement should be a clear unit of work.]\n\n1. **[Requirement Title]**: [Description of what needs to be done.]\n   - *Relevant code*: `path/to/file.js` — `functionName()` [brief note on how this code relates]\n   - *Relevant code*: `path/to/other/file.js` — [brief note]\n\n2. **[Requirement Title]**: [Description]\n   - *Relevant code*: ...\n\n[Continue for all requirements]\n\n## Acceptance Criteria\n\n[Bullet list. Each criterion is a testable, verifiable condition.]\n\n- [Specific, testable criterion]\n- [Another criterion]\n- [Continue as needed]\n\n## Materials & Access\n\n[Trailing audit-trail section — always the LAST section of the draft. Inventory every material the ticket references, grouped by source. Use monospace backticks for file paths and other technical provenance. Redact any embedded secrets.]\n\n### Reachable Local Files\n\n[Only files NOT tracked in version control. Do NOT list version-controlled code or in-repo docs here — those are already in the repo and are cited inline as *Relevant code*.]\n\n- `path/to/local/file.ext` — [what it is; not in version control; will be gathered and attached post-create]\n\n### External/Auth-Gated Links\n\n- [Name or purpose] — `https://example.com/...` (record-only; external/auth-gated)\n\n### Design/UI Comps (Fetchable)\n\n- `attachment_id: 10421` — `checkout-comp.png` (`image/png`); fetch via the Jira attachment download capability into a worktree `file_path` at implementation time.\n\n### Binary/Image Materials (Record-Only)\n\n- `path/to/screenshot.png` — [sanitized location/access note; not attached]\n```\n\n### Writing Guidelines\n\n**Summary**:\n- Be concrete, not abstract. Name the actual components, cartridges, or subsystems involved.\n- State the \"why\" — what problem does this solve or what value does it add?\n- Mention the general technical approach if it's clear from the research.\n\n**Requirements**:\n- Each requirement should represent a logical unit of work\n- Order requirements in a logical implementation sequence when possible\n- ALWAYS cite relevant existing files and functions when they exist. Use exact file paths relative to the project root.\n- Explain HOW the existing code relates: \"extend this function\", \"follow this pattern\", \"reuse this helper\", \"modify this configuration\"\n- If a requirement involves creating new files, suggest where they should live based on existing project structure conventions\n- Be specific about what needs to change vs. what needs to be created new\n- Include requirements for tests, documentation, and configuration/metadata changes if applicable\n- **Design/UI Requirements (when an `applicable: true` comp→codebase map is provided)**: cite the mapped components, Jinja2 templates, CSS/SCSS tokens or design-system styles, and routes from the map with concrete phrasing — \"reuse `X` component\", \"extend template `Y`\", \"use token/style `Z`\", \"wire route `R`\" — so the ticket expresses HOW to realize the comp in code that already exists, not generic \"match the comp\" prose. Keep the depth class-appropriate per the map's classification.\n\n**Acceptance Criteria**:\n- Every criterion must be independently verifiable\n- Cover functional requirements, edge cases, testing, and non-functional requirements\n- Include criteria for backwards compatibility if relevant\n- Include criteria for test coverage\n- Use plain `-` bullets (Jira's ADF has no native checkbox, so `- [ ]` renders as literal text)\n- **Design/UI tickets**: whenever the ticket references or attaches a design comp (mockup, wireframe, or design/UI reference), ALWAYS include an explicit **visual-fidelity acceptance criterion**. Word it so the implementing agent must fetch/open the comp by its `attachment_id` or path and verify **class-appropriate** visual fidelity against it — strict pixel/visual match only for a full comp; layout-only for a wireframe; current-state-plus-delta for an annotated screenshot; the repo design-system floor otherwise. Do not settle for inert \"record-only\" prose that the implementing agent cannot act on. When an `applicable: true` comp→codebase map (`comp-analysis.json`) is available, the criterion should reference BOTH the concrete comp source AND the comp→codebase map, so the implementing agent verifies fidelity against the same components/tokens the Requirements already cite rather than a bare \"match the comp\".\n\n**Materials Completeness Inventory**:\n- After the draft is written, INVENTORY every material the ticket references: local file paths, URLs/links, named docs/designs, screenshots, and specs. This pass only INVENTORIES and RECORDS — it does NOT attach anything. The actual attachment of reachable local files happens post-create (after the Jira `ticket_key` exists) via a separate gather-and-attach step.\n- Classify each material by source using a scheme-based rule (no network probe required):\n  - **Local filesystem paths** named in the ticket body are the only **low-risk** materials — but ONLY when the file is **not tracked in version control**. Before listing a local file as attachable, determine its VCS status by running `git ls-files --error-unmatch -- <path>` (exit code `0` means the file is tracked). A version-controlled file is **already available in the repository** — source code, in-repo docs, configs, and any other committed file — and **MUST NOT be attached**; it is cited inline as *Relevant code* in Requirements instead of being re-uploaded. Only local files that are **not tracked in version control** (external technical docs/specs, design comps, or generated artifacts a reviewer dropped locally — including files outside any repo, untracked, or gitignored) are eligible to be gathered and attached post-create. **Never upload code** or any file already in version control.\n  - Every **`http(s)` URI is external/auth-gated** — regardless of whether the user explicitly linked it (an explicitly-linked Confluence or Google Doc URL is still external/auth-gated) — and is **record-only** here.\n  - **Binary/image materials** (ordinary screenshots, PDFs, and unrelated binaries) are **record-only** — document them with sanitized location/access notes; do NOT attempt to attach them. This record-only rule does not apply to local design/UI comp images (see next bullet).\n  - **Design/UI comps** (a mockup, wireframe, or design reference for a design/UI ticket) are the exception to record-only: when the comp has an `attachment_id`, local path, or other executable fetch path, record it as a **fetchable reference** so the implementing agent can download it into its worktree and open it. For a Jira attachment comp, record its `attachment_id`, filename, and MIME type when known, plus a note that the executor should use the Jira attachment download capability to save it to a worktree `file_path`. A **local design/UI comp image** — a reachable local file whose executable local path resolves and whose extension maps to an allowlisted image MIME type (`image/png`, `image/jpeg`, `image/webp`, `image/gif`) — is also recorded under *Design/UI Comps (Fetchable)* and is additionally eligible for post-create attachment through the allowlisted binary upload path (the gather-and-attach step uploads it, not just references it). An external/auth-gated design link or a Jira `attachment_id` reference on another ticket remains fetchable/reference material for implementation-time download, not a local re-upload target. Ordinary screenshots/PDFs/unrelated binaries with no fetch path and no design relevance stay record-only.\n  - **Comp→codebase map** (`comp-analysis.json`): when the final ticket references the map, inventory it as a **reachable local text file** under *Reachable Local Files* (it is a low-risk local JSON text artifact, gatherable like any other local file — distinct from the design-comp material exception above, which governs the fetchable image itself). The version-control gate still applies: attach it only when it is **not tracked in version control** (a generated artifact normally is not); if it happens to be committed, it is already available in the repo and is not re-uploaded.\n- Write the trailing `## Materials & Access` section (the LAST section of the draft) grouping items under the sub-headings *Reachable Local Files*, *External/Auth-Gated Links*, *Design/UI Comps (Fetchable)* (only when a fetchable design/UI comp exists), and *Binary/Image Materials (Record-Only)*, using bulleted lists. Use monospace formatting (backticks) for technical provenance such as file paths.\n- **Redact secrets before writing anything**: before writing any URL or access note, sanitize and redact embedded credentials, SAS tokens, API keys, and basic-auth secrets using a high-visibility placeholder such as `[REDACTED_TOKEN]`. A location/access note must NEVER expose a plaintext secret.\n\n### Regression Completeness Pass (Gated)\n\nAfter the draft (including its `## Materials & Access` section) is written, run this pass. It is a non-blocking, **warn-not-halt** completeness check — it never blocks or fails ticket creation, and it never modifies the Requirements or Acceptance Criteria text directly.\n\n1. **Check the gate first.** Call the `config_field` MCP tool with `operation` set to `\"get\"` and `field_name` set to `enable_regression_checks`. If the tool returns an error, `null`, or any value other than the literal string `\"true\"`, **skip this entire pass** — the draft is produced exactly as it would be without this section (byte-for-byte unchanged). The recommended default for this flag is OFF (unset) for safe rollout; only proceed past this step when it is explicitly `\"true\"`.\n\n2. **Derive the touched-symbol set.** From the draft's Requirements and *Relevant code* citations (or, if the ticket references an existing diff/PR, that diff/PR), extract the specific function/class/symbol names the proposed change touches.\n\n3. **Run the deterministic core.** Execute:\n   ```bash\n   npx -y @bridge_gpt/mcp-server regression-check --mode lightweight --json --symbols <derived,symbol,names>\n   ```\n   This is the same subcommand the standalone `regression-reviewer` agent and `regression-check` command use — do not hand-roll your own `ast-grep`/`ripgrep` discovery.\n\n4. **Fail-open on a degraded or failed run.** If the command errors, or `summary.degraded_flags` is non-empty, record that the pass ran degraded (or could not run) and proceed — the draft is still produced. Never halt ticket creation because this subcommand was unavailable.\n\n5. **Cross-check against Requirements + Acceptance Criteria.** Parse the JSON `findings` array (`symbol`, `call_sites.by_file`, `broad_mentions`). For each symbol, compare its real call-sites and broad mentions against what the draft's Requirements and Acceptance Criteria already cover. Flag any affected caller, migration, or contract (a file with a real call-site or an uninspected broad mention) that the criteria do NOT mention.\n\n6. **Record the flags — never rewrite Requirements/Acceptance Criteria.** Append a `[WARNING]` block immediately before the `## Materials & Access` section, listing each flagged item:\n   ```markdown\n   ## Regression Completeness Notes\n\n   [WARNING] The following systems were not explicitly addressed in the Requirements or Acceptance Criteria above:\n   - `path/to/affected_caller.py` — calls `changed_symbol` (N real call-sites); not mentioned in Requirements\n   - `path/to/config.yml` — broad mention of `changed_symbol`; verify this reference is unaffected\n\n   Degraded: [list summary.degraded_flags, or \"none — full structural analysis ran\"]\n   ```\n   If no flags were raised and the run was not degraded, write a single line instead: `Regression completeness pass: no unaddressed systems found.` If the run was degraded with zero findings either way, state that explicitly rather than implying a clean pass.\n\n### Output Formatting (Jira upload)\n\nThe ticket is uploaded to Jira, which converts the Markdown to Atlassian Document Format (ADF) and hard-caps the description at **32,767 characters**. Keep the output clean and within budget:\n\n- **Length**: aim for under ~30,000 characters. If the scope genuinely needs more, split into a parent ticket plus sub-tickets rather than one oversized ticket.\n- **Acceptance Criteria**: plain `-` bullets, not `- [ ]` (ADF has no native checkbox).\n- **No images**: do not embed images or use relative image links. This \"No images\" rule applies strictly to inline images in the description body; it does NOT restrict the attachments produced by the Materials Completeness Inventory / gather-and-attach pass, nor does it forbid recording a fetchable design/UI comp reference (its `attachment_id` or path).\n- **No empty headings**: every heading must have text on its line.\n- **Placeholders**: prefer `{placeholder}` over `<placeholder>`.\n\n## Quality Standards\n\n- **No vague language**: Replace \"should handle errors properly\" with \"should catch LLM provider timeouts and return a normalized error response with errorType 'TimeoutError'\"\n- **No assumptions without evidence**: Only reference code you actually read during research. If you're unsure about something, say so explicitly in the ticket.\n- **Appropriate scope**: The ticket should represent a coherent, deliverable unit of work. If the problem is too large, note that it may need to be broken into sub-tasks, but still write the parent ticket.\n- **Developer empathy**: Write as if the developer picking this up has general project knowledge but hasn't recently worked on this specific area. Give them enough context to get started quickly.\n\n## Important Reminders\n\n- Do NOT skip or abbreviate the research phase. The quality of the ticket depends entirely on the depth of your codebase understanding.\n- Do NOT make up file paths or function names. Only reference code you have actually found and read.\n- DO create the markdown file — do not just output the content to the chat. Write it to disk.\n- If the project has specific conventions (from CLAUDE.md or similar), ensure your ticket's requirements align with those conventions.\n"
     },
     "refactor-reviewer": {
         "frontmatter": {

package/build/backend-warnings.js

@@ -0,0 +1,44 @@
+// Shared helper for surfacing non-blocking backend warnings (BAPI-545) as
+// user-visible MCP tool text. The Tier-4 ticket-text routes (PRD, FSD,
+// clarifying questions, ticket critique, ticket review, create_doc) attach a
+// disclosure to their JSON response body when no VCS connection exists but
+// still succeed — this never changes tool success/failure status, it only
+// appends non-blocking text.
+// Extracts warning strings from a parsed backend JSON response. Accepts the
+// real backend shape (a singular `warning: string | null` field, as used by
+// the Tier-4 trigger endpoints' MessageResponse) and, defensively, a
+// `warnings` array of strings or `{ message: string }` objects (in case a
+// future backend response adopts the list shape instead). Invalid/empty
+// values are ignored; never throws.
+export function extractBackendWarnings(body) {
+    if (body === null || typeof body !== "object") {
+        return [];
+    }
+    const record = body;
+    const warnings = [];
+    if (typeof record.warning === "string" && record.warning) {
+        warnings.push(record.warning);
+    }
+    if (Array.isArray(record.warnings)) {
+        for (const entry of record.warnings) {
+            if (typeof entry === "string" && entry) {
+                warnings.push(entry);
+            }
+            else if (entry !== null &&
+                typeof entry === "object" &&
+                typeof entry.message === "string" &&
+                entry.message) {
+                warnings.push(entry.message);
+            }
+        }
+    }
+    return warnings;
+}
+// Appends a non-blocking warning section to existing tool output text.
+// Returns `text` unchanged (byte-for-byte) when `warnings` is empty.
+export function appendBackendWarningsToText(text, warnings) {
+    if (!warnings.length) {
+        return text;
+    }
+    return `${text}\n\n**Warning:** ${warnings.join(" ")}`;
+}