@soleur/opencode 0.0.0-stage → 1.0.0

package/skills/constraint-scaffold/references/constraint-gates-workflow.template

@@ -0,0 +1,69 @@
+name: constraint-gates (L1 import boundary)
+
+# GENERATED by `plugins/soleur/skills/constraint-scaffold` (ADR-071). Always-runs
+# + internal path-check: the job fires on every PR and reports a real conclusion,
+# but exits 0 fast when the target app is untouched — so a required check never
+# deadlocks pending-forever on a `paths:` filter. The agent — never the founder —
+# owns this file. Recovery is automatic: when this gate trips on a PR, the two-stage
+# auto-recovery dispatcher (fix-constraints-stage-a/b, ADR-074) fixes the import and
+# opens a follow-up PR if it is auto-fixable; otherwise a maintainer re-runs the
+# constraint-scaffold skill locally (or runs `--refresh-baseline`).
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+permissions:
+  contents: read
+
+# Stateless lint gate — a mid-run cancel leaves nothing half-written; a
+# superseding PR push makes every earlier run's verdict stale anyway. The
+# SHA arm is dormant (no push trigger today): if one is ever added, `main`
+# runs still never cancel each other.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event_name == 'pull_request' && github.ref || github.sha }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  constraint-gates:
+    name: L1 import-boundary gate
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        with:
+          fetch-depth: 0
+
+      - name: Detect target changes
+        id: changed
+        env:
+          BASE_REF: ${{ github.event.pull_request.base.ref }}
+        run: |
+          set -euo pipefail
+          # No --depth here: a shallow fetch can leave the merge-base unreachable,
+          # making the three-dot diff fail under `set -e` and redden every
+          # non-target PR. checkout already used fetch-depth: 0 (full history).
+          git fetch --no-tags origin "$BASE_REF"
+          changed_files=$(git -c core.quotePath=false diff --name-only "origin/${BASE_REF}...HEAD")
+          if grep -qE '^__TARGET_DIR__/' <<<"$changed_files"; then
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+            echo "__TARGET_DIR__/** unchanged in this PR — constraint-gates passes (no-op)."
+          fi
+
+      - name: Setup Node.js
+        if: steps.changed.outputs.changed == 'true'
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: __TARGET_DIR__/package-lock.json
+
+      - name: Install dependencies
+        if: steps.changed.outputs.changed == 'true'
+        working-directory: __TARGET_DIR__
+        run: npm ci --ignore-scripts
+
+      - name: Run constraint gates (fail-closed)
+        if: steps.changed.outputs.changed == 'true'
+        run: bash __TARGET_DIR__/scripts/constraint-gates.sh

package/skills/constraint-scaffold/references/depcruise-config.template

@@ -0,0 +1,230 @@
+/**
+ * Layer-1 constraint gate — client -> server-secret import boundary.
+ *
+ * GENERATED by `plugins/soleur/skills/constraint-scaffold` (ADR-071, Option D).
+ * The agent — never the founder — owns this file. Recovery is automatic: when
+ * this gate trips on a PR, the two-stage auto-recovery dispatcher
+ * (fix-constraints-stage-a/b, ADR-074) fixes the offending import and opens a
+ * follow-up PR if it is auto-fixable; a real leak the agent cannot fix is
+ * surfaced for a maintainer (who re-runs the constraint-scaffold skill locally,
+ * or runs `--refresh-baseline`). The gate stays informational/non-blocking. Do NOT hand-edit.
+ *
+ * Mechanism: dependency-cruiser matches modules by PATH and cannot see the
+ * `"use client"` directive, so this config is executable CommonJS that computes
+ * the client-module `from` set at require-time by scanning `app/**` + `components/**`
+ * for a leading `"use client"` directive. The set is RECOMPUTED every run and
+ * NEVER committed as a static list — a stale list would be blind to a newly added
+ * client file (the exact leak this gate exists to catch). An empty from-set while
+ * `"use client"` files exist is a HARD ERROR, not a silently-disabled rule.
+ *
+ * Two rules (ADR-071 + the 2026-07-01 #5777 amendment):
+ *   1. `no-client-to-server-secret` — DIRECT edges: a "use client" module
+ *      value-imports `server/**` directly.
+ *   2. `no-client-to-server-secret-transitive` — TRANSITIVE reach: a "use client"
+ *      module reaches `server/**` through a chain of value imports (e.g. a
+ *      non-client `lib/` helper that value-imports a server secret). This is the
+ *      dependency hop the direct rule is blind to (#5777, NG5 of #5765).
+ *
+ * `options.tsPreCompilationDeps` is `false` (v1 set it `true`): dependency-cruiser
+ * v16 `reachable` rules are schema-locked to `{path,pathNot,reachable}` and CANNOT
+ * filter `dependencyTypesNot` per-rule, so the ONLY way to keep the transitive rule
+ * from following a build-time-erased `import type` hop is to elide type-only edges
+ * from the graph GLOBALLY. With type-only edges gone, the direct rule no longer
+ * needs `dependencyTypesNot:["type-only"]` (its violation set is byte-identical
+ * before/after the flip — proven at build time, locked by boundary.test.sh). Both
+ * rules therefore ignore type-only imports for free. See ADR-071 §Amendment 2026-07-01.
+ */
+const fs = require("fs");
+const path = require("path");
+
+const ROOT = __dirname;
+const CLIENT_DIRS = ["app", "components"];
+const SOURCE_EXT = /\.(?:tsx?|jsx?|mjs|cjs)$/;
+// The secret set: the whole server tree is server-only (reads server-only secrets).
+const SECRET_PATH = "^server/";
+// Value-safe server modules the TRANSITIVE rule excludes via `to.pathNot`. These
+// carry NO secret values — they are code-static registries / editorial metadata a
+// client may legitimately reach through a helper:
+//   server/domain-leaders.ts            — static leader array, no secrets
+//   server/providers.ts                 — env-var NAMES as metadata (never reads process.env)
+//   server/team-names-validation.ts     — pure validation, no secrets
+//   server/scope-grants/action-class-map.ts — code-static action-class registry (no imports, no env)
+// COUPLING: this is the SAME "known value-safe server modules" set the DIRECT rule
+// grandfathers via its baseline (.dependency-cruiser-known-violations.json). Two
+// hand-maintained copies that can drift — a future editor MUST update both, and any
+// module added here MUST be security-reviewed value-safe (no process.env value read,
+// no secret import) and covered by the boundary.test.sh drift guard (D4). Excluding a
+// module here does NOT blind a client to OTHER server modules (it is a `to` filter,
+// never a `from` filter). See ADR-071 §Amendment 2026-07-01 and the D3c drift guard.
+// SOLEUR-DEBT: pathNot allowlist is a hand-maintained fail-open backstopped only by the
+// D4 content-invariant drift guard; relocate these 4 modules OUT of server/** so the
+// exclusion is enforced by LOCATION (deletes pathNot + the guard). Upgrade trigger: next
+// time one of the 4 is edited to add a runtime value, OR a 5th value-safe module would
+// need adding here. Tracked: #5850.
+// End-anchored to the exact module file (`\.<ext>$`) — a bare trailing `\.` would
+// prefix-match dot-suffixed SIBLINGS (`server/providers.server.ts`,
+// `server/domain-leaders.data.ts`) and silently exempt them from the transitive
+// rule too; those are natural Next.js names and must stay WATCHED.
+const VALUE_SAFE_PATH =
+  "^server/(domain-leaders|providers|team-names-validation|scope-grants/action-class-map)\\.(?:[cm]?[jt]sx?)$";
+
+function walk(dir, acc) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch (e) {
+    if (e && e.code === "ENOENT") return acc; // dir absent is fine; cwd check below
+    throw e;
+  }
+  for (const entry of entries) {
+    if (entry.name === "node_modules" || entry.name === ".next") continue;
+    const full = path.join(dir, entry.name);
+    if (entry.isSymbolicLink()) {
+      // A symlinked source file is neither isFile() nor isDirectory() as a
+      // Dirent, so the branches below would silently DROP it from the scan —
+      // excluding it from the client from-set = fail open (a symlinked client
+      // module could leak unflagged). Resolve the link; hard-error on a
+      // symlinked source file rather than skipping it.
+      let target;
+      try {
+        target = fs.statSync(full); // follows the symlink
+      } catch {
+        continue; // broken/dangling link: not a readable source file
+      }
+      if (target.isFile() && SOURCE_EXT.test(entry.name)) {
+        throw new Error(
+          "constraint-scaffold: symlinked source file " +
+            full +
+            " — refusing to silently skip it (would fail the import-boundary scan open)",
+        );
+      }
+      continue; // symlinked directory / non-source: not scanned (out of v1 scope)
+    }
+    if (entry.isDirectory()) {
+      walk(full, acc);
+    } else if (entry.isFile() && SOURCE_EXT.test(entry.name)) {
+      acc.push(full);
+    }
+  }
+  return acc;
+}
+
+function isUseClient(file) {
+  let rest = fs.readFileSync(file, "utf8");
+  // Skip leading blank lines and leading comments before the directive. A
+  // license/eslint banner (`// ...` line-comment or `/* ... */` block-comment)
+  // before `"use client"` is valid Next.js; treating such a file as non-client
+  // would leave its server value-imports UNFLAGGED (a silent leak).
+  for (;;) {
+    rest = rest.replace(/^\s+/, "");
+    if (rest.startsWith("//")) {
+      const nl = rest.indexOf("\n");
+      if (nl === -1) return false;
+      rest = rest.slice(nl + 1);
+      continue;
+    }
+    if (rest.startsWith("/*")) {
+      const end = rest.indexOf("*/");
+      if (end === -1) return false;
+      rest = rest.slice(end + 2);
+      continue;
+    }
+    break;
+  }
+  // The directive, allowing a trailing `;` and/or a trailing line/block comment
+  // on the same line: `"use client"; // hydration`.
+  const firstLine = rest.split(/\r?\n/, 1)[0];
+  return /^(['"])use client\1\s*;?\s*(?:\/\/.*|\/\*.*)?$/.test(firstLine);
+}
+
+function reEscape(s) {
+  // Escape every regex metacharacter — route groups like `app/(dashboard)/`
+  // carry `(` / `)` and filenames carry `.`.
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function computeClientFromSet() {
+  // A wrong cwd (config required from outside the target root) would make the
+  // whole scan blind. Require at least one client dir to exist — else hard fail.
+  const presentDirs = CLIENT_DIRS.filter((d) => fs.existsSync(path.join(ROOT, d)));
+  if (presentDirs.length === 0) {
+    throw new Error(
+      "constraint-scaffold: neither app/ nor components/ found under " +
+        ROOT +
+        " — gate cannot scan client modules (wrong cwd or empty input)",
+    );
+  }
+  const files = [];
+  for (const d of presentDirs) walk(path.join(ROOT, d), files);
+  const clientFiles = files.filter(isUseClient);
+  let fromSet = clientFiles.map((f) => {
+    const rel = path.relative(ROOT, f).split(path.sep).join("/");
+    return "^" + reEscape(rel) + "$";
+  });
+  // Test seam: simulate a scan-vs-map divergence (found client files but the
+  // mapped set came back empty) to prove the guard below is live. Test-only.
+  if (process.env.CONSTRAINT_SCAFFOLD_TEST_FORCE_EMPTY === "1") fromSet = [];
+  if (clientFiles.length > 0 && fromSet.length === 0) {
+    throw new Error(
+      "constraint-scaffold: client-module from-set is empty while " +
+        clientFiles.length +
+        ' "use client" files exist — refusing to emit a silently-disabled rule',
+    );
+  }
+  // No client modules at all: match nothing (a regex that never matches) rather
+  // than `[]`, which dependency-cruiser would treat as match-anything.
+  if (fromSet.length === 0) fromSet = ["(?!)"];
+  return fromSet;
+}
+
+// Compute the client-module from-set ONCE and share it across both rules so the
+// fail-closed guards inside computeClientFromSet (empty-from-set hard error, the
+// `(?!)` never-match sentinel, the "neither app/ nor components/" hard error, the
+// symlinked-source hard error) apply to BOTH rules identically.
+const clientFrom = computeClientFromSet();
+
+module.exports = {
+  forbidden: [
+    {
+      name: "no-client-to-server-secret",
+      severity: "error",
+      comment:
+        'A "use client" module must not take a value (non-type-only) import on the ' +
+        "server-only tree (server/**) — that ships a server secret into the browser " +
+        "bundle. Use `import type` for types, or move the value behind a server boundary.",
+      from: { path: clientFrom },
+      // No `dependencyTypesNot:["type-only"]` — type-only edges are elided globally
+      // by `tsPreCompilationDeps:false` (see header), so this rule flags exactly the
+      // value edges it flagged under v1's `true` + `dependencyTypesNot` (proven
+      // byte-identical; a flip regression could only SHRINK the value-edge set, so
+      // boundary.test.sh floors the direct baseline at >=10).
+      to: { path: SECRET_PATH },
+    },
+    {
+      name: "no-client-to-server-secret-transitive",
+      severity: "error",
+      comment:
+        'A "use client" module must not TRANSITIVELY reach the server-only tree ' +
+        "(server/**) through a chain of value imports — a non-client helper that " +
+        "value-imports a server secret ships that secret into the browser bundle. " +
+        "Break the chain, or use `import type`. (Type-only hops are elided globally, " +
+        "so a client -> `import type` helper -> server chain does NOT flag.)",
+      from: { path: clientFrom },
+      // `pathNot` excludes the known value-safe server modules (VALUE_SAFE_PATH) so
+      // the reachable baseline stays EMPTY: dependency-cruiser softens `reachability`
+      // violations per-ORIGIN (`from`+rule name only, ignoring `to`/`via`), so
+      // baselining even one value-safe transitive path would blind that client to
+      // EVERY future transitive secret. We never baseline a reachability entry — we
+      // exclude value-safe targets here and FIX real leaks (D2/D3, ADR-071 amendment).
+      to: { path: SECRET_PATH, pathNot: VALUE_SAFE_PATH, reachable: true },
+    },
+  ],
+  options: {
+    tsConfig: { fileName: "tsconfig.json" },
+    // false (v1: true) — elide type-only edges globally so the reachable rule cannot
+    // follow a build-time-erased `import type` hop (its `to` is schema-locked and
+    // cannot filter dependency-types per-rule). The direct rule's output is unchanged.
+    tsPreCompilationDeps: false,
+    doNotFollow: { path: "node_modules" },
+  },
+};

package/skills/constraint-scaffold/references/fix-constraints-stage-a.template

@@ -0,0 +1,240 @@
+name: fix-constraints-stage-a
+
+# Stage A — UNTRUSTED producer of the two-stage constraint-gate recovery (ADR-074, #5814).
+# GENERATED by `plugins/soleur/skills/constraint-scaffold` into __TARGET_DIR__'s CI. The agent
+# — never the founder — owns this file and gate maintenance. Runs on `pull_request` — NOT the
+# privileged issue_comment / pull-request-target trigger — holds NO write token, and treats
+# running PR-head code as
+# the EXPECTED, safe thing (`pull_request` is CodeQL's designated untrusted context). If the
+# L1 constraint-gate is red on a same-repo PR, it dispatches the agent to FIX it (fix-only —
+# never grows the suppression baseline), re-verifies the gate is green, and uploads the fix
+# as a full-post-image-contents artifact (per-file sha256 + meta.json) for the privileged
+# Stage B (fix-constraints-stage-b, workflow_run) to apply. No commit, no push, no repo-write
+# scope here.
+#
+# SECURITY: `permissions: contents: read` ONLY. The write capability lives exclusively in
+# Stage B, which never executes this untrusted tree (Git Data API, no checkout/no apply). The
+# name: field above is load-bearing — Stage B's `on: workflow_run: workflows:` matches it by
+# NAME, not by filename; a rename here silently stops recovery. Manual retry: re-run this
+# workflow (workflow_dispatch) or push a commit to the PR.
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+    paths:
+      - '__TARGET_DIR__/app/**'
+      - '__TARGET_DIR__/components/**'
+      - '__TARGET_DIR__/server/**'
+      - '__TARGET_DIR__/.dependency-cruiser.cjs'
+      - '__TARGET_DIR__/.dependency-cruiser-known-violations.json'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  # One agent dispatch per head SHA — a push-storm on one PR can't fan out N paid runs.
+  group: fix-constraints-a-${{ github.event.pull_request.head.sha || github.sha }}
+  cancel-in-progress: true
+
+jobs:
+  produce:
+    # Loop guard: Stage B opens `soleur/fix-constraints/<pr>` follow-up PRs; those must never
+    # re-dispatch Stage A (github.head_ref is empty on workflow_dispatch → guard passes).
+    if: >-
+      github.event_name == 'workflow_dispatch' ||
+      !startsWith(github.head_ref, 'soleur/fix-constraints/')
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout the PR head (immutable SHA)
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        with:
+          # pull_request checks out the ephemeral merge ref by default; pin to the immutable
+          # head SHA so the tree the gate runs on == the tree Stage B attests via head_sha.
+          ref: ${{ github.event.pull_request.head.sha }}
+          persist-credentials: false
+
+      - name: Preflight — API key present?
+        id: preflight
+        # Self-contained key-presence gate: sets ok=true iff ANTHROPIC_API_KEY is set (fork PRs
+        # get no secret → ok=false → the fix agent is skipped). The Soleur dogfood swaps this for
+        # a richer `./.github/actions/anthropic-preflight` composite that ALSO soft-skips on
+        # billing-cap / transient API errors; tenants get this minimal check so the template
+        # depends on no repo-local action.
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+        run: |
+          if [ -n "${ANTHROPIC_API_KEY:-}" ]; then
+            echo "ok=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "ok=false" >> "$GITHUB_OUTPUT"
+            echo "::notice::ANTHROPIC_API_KEY not set — skipping the fix agent (recovery is same-repo only)."
+          fi
+
+      - name: Setup Bun                          # the gate's depcruise binary lives in node_modules
+        uses: oven-sh/setup-bun@3d267786b128fe76c2f16a390aa2448b815359f3 # v2.1.2
+        with:
+          bun-version-file: ".bun-version"
+
+      - name: Install dependencies (no postinstall scripts over untrusted PR code)
+        working-directory: __TARGET_DIR__
+        # --ignore-scripts kills the postinstall ACE vector on fork-controlled package.json.
+        # (It does NOT stop the gate's own .dependency-cruiser.cjs from running — that is the
+        # accepted Stage-A residual, bounded by the capped/rotatable key + no write token.)
+        run: npm ci --ignore-scripts
+
+      - name: Run the constraint-gate (capture rc)
+        id: gate
+        run: |
+          set +e
+          bash __TARGET_DIR__/scripts/constraint-gates.sh
+          echo "rc=$?" >> "$GITHUB_OUTPUT"
+
+      - name: Dispatch agent to fix the gate (fix-only)
+        if: steps.gate.outputs.rc != '0' && steps.preflight.outputs.ok == 'true'
+        id: agent
+        uses: anthropics/claude-code-action@20f0b248c5003db4b9ca43c45e17949bcdc36d2d # v1.0.236
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          # `id-token: write` is deliberately ABSENT here (untrusted pull_request
+          # context — see ADR-074): the explicit input is the only safe token
+          # path. Verified at the pinned SHA: inputs.github_token ->
+          # OVERRIDE_GITHUB_TOKEN makes setupGitHubToken return BEFORE
+          # getOidcToken. Without it the agent step OIDC-hard-fails ~15 s in —
+          # the latent defect the dogfood copy carried until its repair.
+          github_token: ${{ github.token }}
+          # Model pin + action SHA mirror claude-code-review.yml verbatim (CI-validated).
+          # Pin freshness is model-launch-review's job — do NOT substitute a model id from memory.
+          claude_args: '--model claude-sonnet-5-5 --max-turns 20 --allowedTools Bash,Read,Write,Edit,Glob,Grep'
+          prompt: |
+            A constraint-gate tripped on this PR. Run `__TARGET_DIR__/scripts/constraint-gates.sh`,
+            read the failure, and FIX the offending import so a client ("use client") module no longer
+            value-imports the server-only tree (server/**). Make file edits ONLY under
+            __TARGET_DIR__/{app,components,server}.
+            You are FIX-ONLY: do NOT run the constraint-scaffold generator, do NOT pass
+            --refresh-baseline, and do NOT edit .dependency-cruiser-known-violations.json — growing
+            the suppression baseline would whitelist a real client->server-secret leak and is a
+            maintainer-only local action, never an auto-recovery path.
+            If the failure is not a real leak you can fix with an import change, make NO edits.
+            Do NOT commit or push — the workflow owns delivery.
+
+      - name: Re-run the gate to VERIFY the fix
+        # Assert the invariant — never trust "agent exited 0" (it exits 0 even on give-up).
+        if: steps.agent.outcome == 'success'
+        id: verify
+        run: |
+          set +e
+          bash __TARGET_DIR__/scripts/constraint-gates.sh
+          echo "rc=$?" >> "$GITHUB_OUTPUT"
+          # `git status --porcelain` (not `git diff`) so a fix that CREATES a new in-scope
+          # file (untracked) counts as changed — `git diff` ignores untracked files.
+          if [ -z "$(git status --porcelain)" ]; then
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Build recovery artifact (full post-image contents + per-file sha256 + meta.json)
+        # Only when the agent produced a real, verified-green change. FIX-ONLY + in-scope:
+        # any changed path outside __TARGET_DIR__/{app,components,server} (incl. the baseline
+        # JSON, constraint-gates.sh, .github/**, *.cjs) ABORTS the artifact — baseline growth is
+        # maintainer-only; auto-recovery never ships an out-of-scope edit.
+        if: steps.verify.outputs.rc == '0' && steps.verify.outputs.changed == 'true'
+        id: artifact
+        env:
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+          HEAD_REF: ${{ github.event.pull_request.head.ref }}
+        run: |
+          set -euo pipefail
+          staging="${RUNNER_TEMP}/fix-constraints-patch"
+          rm -rf "$staging"; mkdir -p "$staging/files"
+          # Stage ALL agent changes (tracked edits AND new untracked in-scope files; git add
+          # respects .gitignore so node_modules etc. are excluded), then enumerate them
+          # NUL-delimited so any filename survives. Out-of-scope edits are still enumerated
+          # here so the allowlist below can ABORT on them (never silently ship a partial fix).
+          git add -A
+          mapfile -d '' changed < <(git diff --cached --name-only -z)
+          if [ "${#changed[@]}" -eq 0 ]; then
+            echo "::notice::no changed files — nothing to deliver"; exit 0
+          fi
+          # Positive-charset, end-anchored allowlist + explicit absolute/`..` reject (matches
+          # Stage B's validator; defense-in-depth so the producer's scope boundary does not rely
+          # on a git-diff normalization invariant).
+          allow_re='^__TARGET_DIR__/(app|components|server)/[A-Za-z0-9._/-]+$'
+          files_json='[]'
+          for f in "${changed[@]}"; do
+            if [[ "$f" == /* ]] || [[ "$f" == *".."* ]] || [[ ! "$f" =~ $allow_re ]]; then
+              echo "::error::agent edited an out-of-scope path (${f}) — auto-recovery is fix-only and in-scope-only; no artifact produced. A maintainer must review."
+              # Record the give-up reason so the marker step (below) can tell Stage B to comment.
+              echo "giveup_reason=edited an out-of-scope path" >> "$GITHUB_OUTPUT"
+              exit 0   # no recovery artifact => a give-up marker is produced instead
+            fi
+            dest="$staging/files/$f"
+            mkdir -p "$(dirname "$dest")"
+            cp "$f" "$dest"
+            sha="$(sha256sum "$f" | awk '{print $1}')"
+            files_json="$(jq -c --arg p "$f" --arg s "$sha" '. + [{path:$p, sha256:$s}]' <<<"$files_json")"
+          done
+          jq -n --arg pr "$PR_NUMBER" --arg sha "$HEAD_SHA" --arg ref "$HEAD_REF" \
+                --argjson files "$files_json" \
+            '{pr_number: ($pr|tonumber), head_sha: $sha, head_ref: $ref, files: $files, touches_baseline: false}' \
+            > "$staging/meta.json"
+          echo "dir=${staging}" >> "$GITHUB_OUTPUT"
+          echo "produced=true" >> "$GITHUB_OUTPUT"
+
+      - name: Upload recovery artifact
+        if: steps.artifact.outputs.produced == 'true'
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: fix-constraints-patch-${{ github.event.pull_request.number }}
+          path: ${{ steps.artifact.outputs.dir }}
+          retention-days: 1
+          if-no-files-found: error
+
+      - name: Build give-up marker (red gate, no in-scope fix delivered)
+        # The gate was RED but no recovery artifact was produced (no key, agent didn't run,
+        # made no edits, still red after the fix, or greened via an out-of-scope path). Emit a
+        # tiny marker so the privileged Stage B can post ONE "maintainer needed" comment on the
+        # PR — the founder is NEVER left silently deadlocked (plan AC: no terminal state is
+        # silent). No marker when the gate was already green (nothing tripped → no comment).
+        if: steps.gate.outputs.rc != '0' && steps.artifact.outputs.produced != 'true'
+        id: giveup
+        env:
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+          PREFLIGHT_OK: ${{ steps.preflight.outputs.ok }}
+          AGENT_OUTCOME: ${{ steps.agent.outcome }}
+          VERIFY_RC: ${{ steps.verify.outputs.rc }}
+          ARTIFACT_REASON: ${{ steps.artifact.outputs.giveup_reason }}
+        run: |
+          set -euo pipefail
+          if [ "${PREFLIGHT_OK}" != 'true' ]; then
+            reason="the fix agent could not run (API key unavailable or a fork PR)"
+          elif [ -n "${ARTIFACT_REASON}" ]; then
+            reason="${ARTIFACT_REASON}"
+          elif [ "${AGENT_OUTCOME}" != 'success' ]; then
+            reason="the fix agent did not complete"
+          elif [ "${VERIFY_RC}" != '0' ]; then
+            reason="the gate was still red after the agent's attempt"
+          else
+            reason="the agent made no edits — this gate may not be auto-fixable"
+          fi
+          staging="${RUNNER_TEMP}/fix-constraints-giveup"
+          rm -rf "$staging"; mkdir -p "$staging"
+          jq -n --arg pr "$PR_NUMBER" --arg sha "$HEAD_SHA" --arg r "$reason" \
+            '{pr_number: ($pr|tonumber), head_sha: $sha, reason: $r}' > "$staging/meta.json"
+          echo "dir=${staging}" >> "$GITHUB_OUTPUT"
+          echo "produced=true" >> "$GITHUB_OUTPUT"
+
+      - name: Upload give-up marker
+        if: steps.giveup.outputs.produced == 'true'
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: fix-constraints-giveup-${{ github.event.pull_request.number }}
+          path: ${{ steps.giveup.outputs.dir }}
+          retention-days: 1
+          if-no-files-found: error