@soleur/opencode 0.0.0-stage → 1.0.0

package/skills/linear-fetch/SKILL.md

@@ -0,0 +1,247 @@
+---
+name: linear-fetch
+description: "This skill should be used when a user input contains a Linear issue reference (e.g., SOL-39 or linear.app/.../issue/<ID>) and the downstream agent needs the screenshots embedded in the issue as visual context."
+allowed-tools:
+  - Bash
+  - mcp__linear-server__get_issue
+  - mcp__linear-server__list_comments
+  - mcp__linear-server__extract_images
+preconditions:
+  - Linear MCP server is authenticated (mcp__linear-server__authenticate has been run for this session)
+---
+
+<!-- grok-harness-invoke:start -->
+**Grok Build (`plugins/soleur/lib/harness.ts` `invokeSkill()`):** Read this SKILL.md in this process and run it to completion. A one-segment `soleur:<name>` in this document names a SKILL — on Grok Build, Read `plugins/soleur/skills/<name>/SKILL.md` in this process; it is not a nested tool_use. A multi-segment id such as `soleur:<domain>:<name>` names an AGENT: spawn it, never Read it, and on Grok Build spawn_subagent takes the id with its colons replaced by hyphens (`agentIdToGrokSubagentType`). **Claude Code:** Skill tool for a skill (`soleur:<name>`), Task tool with `subagent_type` for an agent. Forbidden is executing a subset, not the Read.
+<!-- grok-harness-invoke:end -->
+
+# Linear Issue Image Context
+
+This skill detects Linear issue references in caller input, fetches the issue body and recent comments, and streams the embedded screenshots directly into the active model conversation. The caller (typically `soleur:one-shot` Step 0a or `soleur:brainstorm` Phase 0.4) receives two return artifacts and is responsible for choosing the right one for each downstream consumer.
+
+## Caller Contract
+
+This skill returns **two artifacts**. Mixing them up is the load-bearing failure mode the skill exists to prevent.
+
+1. **Agent context** — the full markdown blob (description + comment bodies) with Linear image content blocks streamed into the active conversation by `mcp__linear-server__extract_images`. **Callers MUST NOT write this artifact to disk, a PR body, a commit message, or any file under `knowledge-base/`.** The Linear image URLs inside it (`uploads.linear.app/*`) are signed bearer credentials that grant public-internet read access for their validity window.
+2. **Persist-safe summary** — the same text with every `uploads.linear.app/*` URL redacted to the literal token `[linear-image: REDACTED]`. **Callers MUST use this variant for any persistence**: writes to `knowledge-base/`, PR descriptions, commit messages, learning files, downstream subagent prompts.
+
+The redaction primitive lives at [scripts/redact-linear-urls.sh](./scripts/redact-linear-urls.sh). It uses a **case-insensitive hostname match** (`[Hh][Tt][Tt][Pp][Ss]?://[Uu][Pp][Ll][Oo][Aa][Dd][Ss]\.[Ll][Ii][Nn][Ee][Aa][Rr]\.[Aa][Pp][Pp]/`) — DNS is case-insensitive and `https://Uploads.Linear.App/...` serves the same signed bearer credential as the lowercase form. The URL path uses a positive ASCII-only character class (RFC 3986 unreserved + reserved set), so Unicode separators (U+2028, U+2029, NBSP) and markdown/HTML terminators (`< > " ' ) ]`) all terminate the match cleanly. The full justification per character is inline in the script. The companion CI `pii-grep` job in `.github/workflows/pr-quality-guards.yml` mirrors the case-insensitive matching with `grep -iE`.
+
+The repository is public on GitHub. A single leaked `uploads.linear.app` URL is a `single-user incident` brand-survival event per `knowledge-base/project/specs/archive/20261013-014038-feat-linear-issue-image-context/spec.md`.
+
+## Phases
+
+### Phase A — Reference detection
+
+Scan the input string for substrings matching either:
+
+- The identifier shape `[A-Z]{2,}-[0-9]+` (matches `SOL-39`, `LIN-12`, `ENG-100`, but also `PR-123`, `HTTP-200`, `CVE-2024` — false positives are handled in Phase B, not at the regex level), OR
+- The URL shape `linear\.app/[^/]+/issue/([A-Z]+-[0-9]+)` — extract the captured identifier.
+
+Uppercase each captured identifier and deduplicate (case-sensitive after uppercasing, exact-match on the number — `SOL-39` and `sol-39` collapse to one entry).
+
+If more than 5 distinct identifiers match, use the `AskUserQuestion` tool to ask the user how to proceed before any MCP call:
+
+- **Header:** "Linear cap"
+- **Question:** "Found N Linear references; the default cap is 5 to bound prompt size and MCP cost. Process the first 5, all N, or abort?"
+- **Options:** "Process first 5 (default)", "Process all (may bloat context)", "Abort". The "Other" escape is appended automatically by the runtime.
+
+Take the user's choice as the working set for Phase B.
+
+If 5 or fewer matches, proceed directly.
+
+If zero matches, return immediately with no disclosure line — the skill is a no-op for inputs that do not reference Linear.
+
+### Phase B — Fetch + comment scan
+
+For each identifier in the working set:
+
+1. Invoke `mcp__linear-server__get_issue(id=<identifier>)`. On a `404 Not Found` response, silently drop the identifier — this converts false-positive matches like `PR-123` or `CVE-2024` into no-ops with no user-visible failure. On any other failure (`403`, network error, token expired), emit the warning from Phase E and skip to the next identifier; do not abort.
+2. Invoke `mcp__linear-server__list_comments(issueId=<identifier>, orderBy="createdAt", limit=250)`. The MCP schema (verified at Phase 0 of the plan) supports `orderBy: createdAt | updatedAt` and `limit` up to 250. The schema does NOT expose an order-direction parameter, so the response order is treated as ambiguous: parse each comment's `createdAt` field and sort client-side **descending**, then take the first 10 entries as "10 most-recent by creation time." If the response contains 10 or fewer comments, skip the sort.
+3. Concatenate the issue description and the 10 most-recent comment bodies into a single markdown blob, delimited as `\n\n--- comment by <author.displayName> on <createdAt> ---\n\n` between each block.
+
+### Phase B.0 — Pre-fetch preflight (blob-independent; runs BEFORE Phase C)
+
+**Run this fence before invoking `extract_images`, and abort the whole skill on a non-zero exit.**
+
+Both checks below are **blob-independent** — they interrogate the plugin installation, not the
+issue. Until #7450 they sat in Phase D, *after* Phase C had already streamed the issue's image
+content blocks into the conversation. So on every halt path the signed `uploads.linear.app`
+bearer URLs were already in the parent transcript, and the "fail closed" refusal protected only
+the artifact nobody had produced yet. A guard that cannot run before the exposure is not a guard
+against it. Nothing here depends on the blob, so nothing forced that ordering.
+
+```bash
+[ -f "${CLAUDE_PLUGIN_ROOT}/.claude-plugin/plugin.json" ] \
+  && grep -q '"name"[[:space:]]*:[[:space:]]*"soleur"' "${CLAUDE_PLUGIN_ROOT}/.claude-plugin/plugin.json" \
+  || { echo "SOLEUR_LINEAR_FETCH_HALT reason=plugin-root-unverified root=[${CLAUDE_PLUGIN_ROOT}]"
+       echo "linear-fetch: cannot verify the Soleur plugin installation — stopping before anything is fetched." >&2
+       echo "  Resolved plugin root: [${CLAUDE_PLUGIN_ROOT}]" >&2
+       echo "  If that is EMPTY: no Soleur plugin is loaded in this session. Install it and start a NEW session — re-running here resolves the same empty root." >&2
+       echo "  If it names a path: that path is not a Soleur install (a repo checkout is not an install). Run 'claude plugin update soleur@soleur-marketplace' (or the id 'claude plugin list' prints, if you added the repository directly), then RESTART Claude Code — plugin changes apply only on restart. If you installed with --scope project or --scope local, pass the same scope. Reinstall only if that does not clear it." >&2
+       echo "  Nothing has been fetched yet, so nothing has leaked." >&2
+       exit 2; }
+SCRUBBER="${CLAUDE_PLUGIN_ROOT}/skills/linear-fetch/scripts/redact-linear-urls.sh"
+[[ -r "$SCRUBBER" ]] || { echo "SOLEUR_LINEAR_FETCH_HALT reason=scrubber-unreadable scrubber=[$SCRUBBER]"
+       echo "linear-fetch: the redaction primitive is missing from an otherwise valid Soleur install — stopping." >&2
+       echo "  Expected at: [$SCRUBBER]" >&2
+       echo "  The install is partial or out of date. Run 'claude plugin update soleur@soleur-marketplace' (or the id 'claude plugin list' prints, if you added the repository directly), then RESTART Claude Code — plugin changes apply only on restart. If you installed with --scope project or --scope local, pass the same scope. Reinstall only if that does not clear it." >&2
+       echo "  Nothing has been fetched yet, so nothing has leaked." >&2
+       exit 2; }
+echo "SOLEUR_LINEAR_FETCH_PREFLIGHT_OK scrubber=present"
+```
+
+If this fence exits non-zero, **stop**: do not invoke `extract_images`, do not emit
+`agent_context`, and do not emit a disclosure line. The correct operator-visible outcome is the
+halt message above, not a partially-fetched issue.
+
+### Phase C — Image passthrough
+
+For each issue's combined markdown blob from Phase B, invoke `mcp__linear-server__extract_images(markdown=<blob>)`. The MCP server resolves Linear-authenticated CDN URLs server-side and streams the underlying image bytes back into the active conversation as image content blocks. The skill never sees the bytes, never writes them to disk, never re-fetches them.
+
+Count the image content blocks returned per issue (call this `N_images_total`), and count how many were extracted from comment bodies specifically (call this `M_comments_with_images`). The MCP response shape should make this distinguishable; if not, infer from the per-source split by passing description and comments through `extract_images` separately.
+
+### Phase D — Disclosure & dual-artifact return
+
+For each issue, emit exactly one disclosure line to stdout based on the Phase C counts:
+
+<!-- markdownlint-disable MD038 -->
+<!-- #7927: MD038 on this table is cosmetic. Verified with the repo's own markdown-it:
+     every span here renders with no edge space (CommonMark strips a single leading and
+     trailing space), except one where the leading space is the point -- the cell
+     documents a string that is APPENDED, so its space is content. A disable-line comment
+     cannot be used: GFM discards anything past a row's closing pipe. -->
+| Condition | Disclosure line |
+|---|---|
+| Images present | `Detected <ID> — fetched issue + N_images_total images from description and M_comments_with_images comments.` |
+| Text-only (description and comments had zero `uploads.linear.app` references and `extract_images` returned zero images) | `Detected <ID> — text-only issue, no images.` |
+| Soft anomaly (description or comments contained `uploads.linear.app` URLs but `extract_images` returned zero images) | `Detected <ID> — N image URLs found but extraction returned 0 images (soft anomaly).` |
+| Comment cap hit (`list_comments` returned exactly 250 — Linear MCP's per-call limit, may have more comments past the cap) | append ` (comment cap hit — may be missing newer comments)` to the appropriate line above. The skill takes the 10 most-recent from the 250-window, so very high-volume issues may miss comments past position 250. Cursor pagination is a v1.1 follow-up (issue filed at plan finalization). |
+<!-- markdownlint-enable MD038 -->
+
+Construct the two return artifacts:
+
+- **agent_context** — emit the full markdown blob inline in the conversation, so the parent's message history holds both the text and the image content blocks from `extract_images`. The parent retains these for downstream phases (one-shot Steps 3+, brainstorm Phase 2 Synthesis, brainstorm Phase 3 Capture). Per `2026-05-12-task-subagent-prompt-text-only.md`, image content blocks do NOT propagate to Task subagents — design accordingly.
+- **persist_safe_summary** — produce by piping the full markdown blob through the redaction primitive, resolved from the **deployed plugin root** (ADR-179's canonical bare anchor, no fallback arm). The redacted text is the only artifact callers may persist. Return it as a fenced text block clearly labeled `PERSIST-SAFE SUMMARY (use this for any write to disk):` so the parent skill cannot confuse it with the agent_context.
+
+  **The exit-code dispatch below is load-bearing, and this site had none before #7450.** With no
+  guard, an unresolved root yields exit `127` and **empty stdout** — and empty stdout is exactly
+  the shape an agent can mistake for "the redacted text" and persist. Empty output is a failure,
+  never a clean summary. The default arm was removed, not re-pointed: `review/SKILL.md` instructs
+  `gh pr checkout`, so that arm resolved this scrubber from the reviewed party's tree.
+
+  The identity and readability checks are NOT repeated here — they ran in **Phase B.0**, before
+  anything was fetched. What remains is the blob-dependent half.
+
+  Substitute the full markdown blob verbatim between the heredoc delimiters. **The delimiter is
+  quoted (`<<'LINEAR_BLOB'`), which is load-bearing twice over**: it stops the shell expanding
+  issue text that Linear users control, and it keeps the blob off disk. The pre-#7450 form
+  (`bash "$SCRUBBER" <blob-tmpfile>`) wrote the **un-redacted, bearer-URL-bearing** blob to a file
+  that was never created, named, or removed by any step in this skill, on all four halt paths —
+  while the prose two paragraphs up still described the operation as piping.
+
+  ```bash
+  # RE-DERIVED, not inherited. Phase B.0 is a SEPARATE Bash call, and shell state does not
+  # persist across calls — so `$SCRUBBER` is EMPTY here unless it is defined in this fence.
+  # Assuming otherwise is not a theoretical risk: it shipped, and it bricked this skill on
+  # every invocation (`bash: : No such file or directory` -> reason=scrubber-nonzero-exit ->
+  # rc 2, so `persist_safe_summary` could never be produced and every caller hard-stopped).
+  # It failed CLOSED only because the anchor is quoted; unquoted, `bash $SCRUBBER <<'…'`
+  # executes the heredoc, i.e. runs Linear issue text as a shell script.
+  # B.0 still owns the identity preflight and the readability check — those are the
+  # blob-independent halts that must precede the fetch. This line is the same bare anchor,
+  # re-stated where it is used.
+  SCRUBBER="${CLAUDE_PLUGIN_ROOT}/skills/linear-fetch/scripts/redact-linear-urls.sh"
+
+  # The scrubber reads stdin and writes redacted text to stdout.
+  PERSIST_SAFE="$(bash "$SCRUBBER" <<'LINEAR_BLOB'
+  <the full markdown blob from Phase B, verbatim>
+  LINEAR_BLOB
+  )" || { echo "SOLEUR_LINEAR_FETCH_HALT reason=scrubber-nonzero-exit"
+          echo "linear-fetch: the redaction primitive exited non-zero — stopping." >&2
+          echo "  Nothing is persisted. Do NOT fall back to agent_context; it carries the bearer URLs." >&2
+          echo "  What to do: re-run once. If it repeats, this is a Soleur defect — file it with the exit status; do not hand-copy the issue text." >&2
+          exit 2; }
+
+  [ -n "$PERSIST_SAFE" ] \
+    || { echo "SOLEUR_LINEAR_FETCH_HALT reason=redaction-empty-output"
+         echo "linear-fetch: redaction produced EMPTY output — stopping." >&2
+         echo "  Empty output is a failure, not a clean summary. Do NOT persist it." >&2
+         echo "  What to do: re-run once. If it repeats, this is a Soleur defect — file it; do not paste the issue text by hand." >&2
+         exit 2; }
+
+  # Redaction must have HAPPENED, not merely have run. A scrubber that returns its input
+  # unchanged is non-empty and exits 0, so every other guard here stays green while the
+  # artifact labelled PERSIST-SAFE still carries the signed bearer URLs. This is also the
+  # only check on this path that does not depend on the anchor being trustworthy.
+  # Herestring, not a pipe: under `set -o pipefail` a `grep -q` that matches early closes
+  # the pipe, the producer takes SIGPIPE, and the pipeline reports failure on a match.
+  if grep -qiE 'uploads\.linear\.app' <<<"$PERSIST_SAFE"; then
+    echo "SOLEUR_LINEAR_FETCH_HALT reason=redaction-ineffective"
+    echo "linear-fetch: redaction did NOT remove the signed uploads.linear.app URLs — stopping." >&2
+    echo "  The scrubber ran and returned output, but the output still carries bearer credentials." >&2
+    echo "  Do NOT persist this text." >&2
+    echo "  This is a SOLEUR DEFECT, not a problem with your issue: the scrubber ran and returned bearer URLs anyway." >&2
+    echo "  What to do: do NOT retry — a retry will produce the same result. File this with the issue identifier (not its contents)." >&2
+    exit 2
+  fi
+
+  # Emit it. Shell state does not persist across Bash calls, so a block that assigns
+  # PERSIST_SAFE and never prints it cannot produce the artifact it exists to produce.
+  printf '%s\n' "$PERSIST_SAFE"
+  ```
+
+  On any halt above, `persist_safe_summary` **does not exist**. Callers must treat its absence as a hard stop and MUST NOT substitute `agent_context` — see the absent-artifact contract in [one-shot](../one-shot/SKILL.md) Step 0a and [brainstorm](../brainstorm/SKILL.md) Phase 0.4. `agent_context` carries the signed `uploads.linear.app` bearer URLs this primitive exists to remove, so falling back to it converts a refusal into the exact leak.
+
+**Telemetry redaction (TR7).** This skill MUST NOT include the matched Linear identifier, the issue title, any image URL, or any signed-URL fragment in incident telemetry (`.claude/hooks/lib/incidents.sh emit_incident`). If telemetry is ever emitted from inside this skill, use generic strings only (e.g., `linear-fetch applied`). The current implementation has zero `emit_incident` call sites; a future maintainer adding one must pass the [assert-no-linear-telemetry.sh](./scripts/assert-no-linear-telemetry.sh) assertion or extend the assertion to cover the new emission shape.
+
+### Phase E — Failure handling
+
+For any MCP failure that is NOT a benign 404 false-positive:
+
+- Emit a one-line warning to stdout: `Linear fetch failed for <ID>: <reason>. Continuing without image context.`
+- Do NOT abort the parent skill. The original identifier text remains in `$ARGUMENTS`; the downstream agent can still reason about the issue from prose alone.
+- Do NOT include the matched identifier in any telemetry emission per TR7. The warning above is operator-facing stdout, not telemetry — the identifier is permitted in the warning so the operator can take corrective action.
+
+The most common reasons (and what they mean):
+
+| Reason | What it usually means |
+|---|---|
+| `MCP tool not found` | Linear MCP server is not registered for this session. Run `mcp__linear-server__authenticate`. |
+| `403 Forbidden` | Token is valid but lacks access to the issue's workspace. Confirm Linear workspace membership. |
+| `Network timeout` | Linear API unreachable. Try again, or work offline from prose only. |
+| `Token expired` | OAuth token rotation needed. Re-run `mcp__linear-server__authenticate`. |
+
+## Caller invocation contract
+
+This skill is invoked via the `Skill` tool from inside another skill (not directly by the operator). Two known callers as of v1:
+
+- `soleur:one-shot` Step 0a — parent fetches once, retains images for Steps 3+, substitutes `persist_safe_summary` into the Steps 1-2 Task subagent's prompt template.
+- `soleur:brainstorm` Phase 0.4 — parent fetches once, retains images for Phase 2 Synthesis and Phase 3 Capture, embeds `persist_safe_summary` in Phase 0.5 domain-leader prompts.
+
+The skill does NOT modify `soleur:plan`, `soleur:fix-issue`, or `soleur:work` in v1. Those are tracked as a v2 follow-up issue at plan-finalization time.
+
+## Manual Test Runbook
+
+The 10 spec acceptance-test scenarios. Operators run these against a real Linear workspace before marking the post-merge acceptance criteria done. Each step lists: input to type into Claude Code, expected disclosure, and post-condition to verify.
+
+1. **Happy path — single-issue, description-only image.** Pick a real `SOL-*` issue whose description contains one Linear-CDN-hosted image (markdown shape `![](URL)`). Type `fix <ID>` into a `soleur:one-shot`-routed prompt. Expected: disclosure `Detected <ID> — fetched issue + 1 images from description and 0 comments.` Visual check: the image is rendered inline in the current conversation. Persist check: the plan subagent's plan document at `knowledge-base/project/plans/...` contains zero `uploads.linear.app` matches (`grep -c` returns 0).
+2. **Happy path — comments-only image.** Pick an issue with a text-only description and one image attached in a comment. Same invocation. Expected: `fetched issue + 1 images from description and 1 comments.`
+3. **Text-only issue.** Pick an issue with no images anywhere. Expected: `text-only issue, no images.`
+4. **Multi-issue input.** Type `compare <ID-1> and <ID-2>`. Expected: two disclosure lines, one per issue.
+5. **404 issue.** Type `fix SOL-999999` (or any non-existent identifier). Expected: silent no-op, no warning printed (false-positive path).
+6. **False-positive identifier.** Type `the PR-123 we shipped`. Expected: silent no-op for `PR-123` (404 → silently dropped). No warning, no MCP error surfacing to the operator.
+7. **Comments cap.** Pick an issue with 15+ comments, several of which contain images. Expected: only 10 most-recent processed; the disclosure's `M_comments_with_images` count is at most 10.
+8. **Persist-safe round-trip.** After a `soleur:brainstorm` invocation that triggered the skill, run `grep -c 'uploads.linear.app' knowledge-base/project/brainstorms/<latest>.md`. Expected: `0`.
+9. **CI grep gate fires.** Create a fixture branch outside Claude Code, manually `git add` and `git commit` a file containing `https://uploads.linear.app/TEST-FIXTURE-NOT-REAL.png`, push, and open a PR. Expected: the `pii-grep` CI job fails the PR with a clear `::error::` annotation pointing at `knowledge-base/project/specs/archive/20261013-014038-feat-linear-issue-image-context/spec.md`.
+10. **Telemetry redaction.** Run any skill that emits incident telemetry while the conversation has linear-fetch context. Inspect `.claude/incidents/*.jsonl` after the test run. Expected: zero lines contain a Linear identifier (`SOL-\d+` or similar) or `uploads.linear.app`.
+
+If any scenario fails post-merge, file a P1 follow-up issue, leave `#3635` open, and do not mark the skill production-ready until the failure is reproduced and fixed.
+
+## Sharp Edges
+
+- The `LINEAR_CDN_PATTERNS` array in [scripts/redact-linear-urls.sh](./scripts/redact-linear-urls.sh) is intentionally extensible (currently one pattern: `uploads.linear.app`). If Linear introduces a new CDN hostname (`cdn.linear.app`, `linear-assets.com`), add a new pattern to the array AND update the CI `pii-grep` workflow regex in the same PR. The redaction primitive's unit-test fixtures must also gain a matching fixture per new pattern.
+- The character class excludes single quote via the bash `$'\x27'` ANSI-C escape (so the regex literal contains `'`). This works on bash 5.x (Linux) and bash 3.2 (macOS) but the test runbook explicitly tests on both before declaring the script production-ready.
+- `list_comments` `orderBy` direction is not exposed in the MCP schema; client-side `createdAt desc` sort + take-10 is the hard fallback to remain order-independent. Do not assume server-side direction.
+- The skill must be invoked via the `Skill` tool, not run as a CLI. The `Skill` invocation places the image content blocks from `extract_images` into the caller's conversation; a standalone CLI run would lose the images entirely.
+- `extract_images` may return zero images for an issue whose markdown contains `uploads.linear.app` URLs (e.g., an upstream Linear bug, transient CDN failure, expired URL inside the issue). The Phase D soft-anomaly disclosure exists precisely so this case is operator-visible and not silent.

package/skills/linear-fetch/scripts/assert-no-linear-telemetry.sh

@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+# Assert that a telemetry payload (or any text passed via stdin or as
+# the first argument file path) contains no Linear identifiers, no Linear
+# CDN URLs, and no UUID-style Linear IDs. Used to enforce spec TR7.
+#
+# Usage:
+#   echo "$payload" | bash assert-no-linear-telemetry.sh
+#   bash assert-no-linear-telemetry.sh /path/to/file.jsonl
+#
+# Exit 0 if clean. Exit 1 if any forbidden pattern matches. The first
+# offending pattern is printed to stderr with the matched substring.
+#
+# Forbidden patterns:
+#   1. Linear issue identifier:  [A-Z]{2,}-[0-9]+  (matches SOL-39, LIN-12, etc.)
+#   2. Linear CDN URL:           uploads\.linear\.app
+#   3. Linear UUID-style ID:     8-4-4-4-12 hex (Linear's internal issue IDs)
+#
+# Note: this helper is INTENTIONALLY strict. Operator-facing stdout (the
+# Phase E warning line that names the failed identifier) is NOT routed
+# through this assertion — only telemetry payloads emitted to
+# .claude/hooks/lib/incidents.sh are gated. The skill currently has zero
+# emit_incident call sites; this helper exists so a future maintainer
+# adding one cannot regress TR7 silently.
+#
+# Known limitations (security-sentinel P2-1, P2-2):
+#   1. Base64-encoded payloads are NOT decoded before pattern check. A
+#      caller that base64-encodes Linear identifiers or URLs in telemetry
+#      will silently pass this gate. If telemetry shapes start including
+#      encoded fields, add a base64-decode pre-pass (detect strings of
+#      shape `^[A-Za-z0-9+/=]{16,}$`, decode, recurse).
+#   2. URL-fragment-only leaks (e.g., `?sig=<long_base64>&expires=<ts>`
+#      without the hostname) are NOT caught. A future maintainer pasting
+#      signed-URL query params separately from the host would bypass.
+#      Consider adding a fourth pattern matching `\?[a-zA-Z]+=[A-Za-z0-9_-]{32,}`.
+# These limitations are acceptable for the current zero-emit_incident
+# baseline; revisit if the skill grows real telemetry emissions.
+
+set -eu
+
+if [[ $# -ge 1 && -r "$1" ]]; then
+  input=$(cat "$1")
+else
+  input=$(cat -)
+fi
+
+# Pattern 1: Linear issue identifier shape.
+if grep -qE '\b[A-Z]{2,}-[0-9]+\b' <<<"$input"; then
+  match=$(printf '%s' "$input" | grep -oE '\b[A-Z]{2,}-[0-9]+\b' | head -n 1)
+  echo "FAIL: telemetry payload contains Linear identifier shape: $match" >&2
+  exit 1
+fi
+
+# Pattern 2: Linear CDN hostname (any form, signed-URL fragments included).
+if grep -qiE 'uploads\.linear\.app' <<<"$input"; then
+  echo "FAIL: telemetry payload contains uploads.linear.app reference" >&2
+  exit 1
+fi
+
+# Pattern 3: UUID-style ID (Linear's internal issue UUIDs).
+if grep -qE '\b[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}\b' <<<"$input"; then
+  match=$(printf '%s' "$input" | grep -oE '\b[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}\b' | head -n 1)
+  echo "FAIL: telemetry payload contains UUID-style identifier: $match" >&2
+  exit 1
+fi
+
+exit 0

package/skills/linear-fetch/scripts/redact-linear-urls.sh

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+# Redact uploads.linear.app URLs from stdin. Writes redacted text to
+# stdout; writes redaction count to stderr.
+#
+# Brand-survival: a regression here means a uploads.linear.app signed URL
+# can leak into a committed artifact on a public-GitHub repo. See
+# knowledge-base/project/specs/archive/20261013-014038-feat-linear-issue-image-context/spec.md FR7
+# and the plan's User-Brand Impact section.
+#
+# Hostname matching is case-insensitive (DNS is case-insensitive — a URL like
+# https://Uploads.Linear.App/x.png resolves to the same CDN host as the
+# lowercase form and still serves the signed bearer credential). The hostname
+# is encoded as bracketed character classes ([Hh][Tt]...) because BSD sed
+# (macOS) does not portably support the `s///gI` case-insensitive flag, so
+# we cannot rely on a flag in the substitution path.
+#
+# URL-path character class is a POSITIVE match against the RFC 3986 unreserved
+# + reserved set (ASCII only). This is more conservative than the prior
+# negated class:
+#   - Multi-byte UTF-8 sequences (U+2028, U+2029, NBSP, etc.) automatically
+#     terminate the match at the first non-ASCII byte. POSIX [:space:] is
+#     ASCII-only and would let the redactor consume past Unicode separators
+#     (security-sentinel P2-3 + cq-regex-unicode-separators-escape-only).
+#   - Markdown/HTML terminators (< > " ' ) ]) are not in the set, so URLs
+#     end correctly inside autolinks, HTML attributes, and markdown links.
+#
+# Adding a new CDN hostname (e.g., cdn.linear.app) requires:
+#   1. A new entry in LINEAR_CDN_PATTERNS below.
+#   2. An updated regex in .github/workflows/pr-quality-guards.yml pii-grep.
+#   3. A matching fixture in redact-linear-urls.test.sh.
+# The parity test (parity.test.sh, when added) enforces 1 and 2 stay in sync.
+#
+# set -e is on; pipefail is intentionally off because `grep -oE` returns
+# exit 1 on zero matches — a benign condition we count and continue past.
+
+set -eu
+
+LINEAR_CDN_PATTERNS=(
+  $'[Hh][Tt][Tt][Pp][Ss]?://[Uu][Pp][Ll][Oo][Aa][Dd][Ss]\\.[Ll][Ii][Nn][Ee][Aa][Rr]\\.[Aa][Pp][Pp]/[A-Za-z0-9._~:/?#@!$&*+,;=%-]+'
+)
+
+input=$(cat -)
+count=0
+output="$input"
+for pattern in "${LINEAR_CDN_PATTERNS[@]}"; do
+  matches=$(printf '%s' "$output" | grep -oE "$pattern" | wc -l | tr -d '[:space:]')
+  count=$((count + matches))
+  output=$(printf '%s' "$output" | sed -E "s#$pattern#[linear-image: REDACTED]#g")
+done
+printf '%s' "$output"
+printf '%s' "$count" >&2

package/skills/linear-fetch/scripts/render-caller-template.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+# Substitute a placeholder in a template (stdin) with a value (arg 1).
+# Used by persist-safe-integration.test.sh to simulate the runtime
+# substitution that one-shot Step 0a and brainstorm Phase 0.4 perform
+# when threading persist_safe_summary into downstream prompts.
+#
+# Usage:
+#   echo "$template" | bash render-caller-template.sh "$summary"
+#
+# The placeholder is the literal string __PERSIST_SAFE_SUMMARY__ — chosen
+# to be visually distinct from $ARGUMENTS (one-shot template) and {desc}
+# (brainstorm template) so test fixtures can mirror either real template
+# by writing the placeholder in the right spot.
+#
+# Implementation note: awk is used (not sed) so the substitution value
+# can contain arbitrary characters including /, &, \, and newlines
+# without escaping. The placeholder itself is 24 chars of fixed-shape
+# alphanumeric + underscore — no regex metacharacters.
+
+set -eu
+
+VALUE="${1:?usage: render-caller-template.sh <value>}"
+TEMPLATE=$(cat -)
+PLACEHOLDER='__PERSIST_SAFE_SUMMARY__'
+
+# Use awk for arbitrary-content substitution — no sed escaping needed.
+printf '%s' "$TEMPLATE" | awk -v val="$VALUE" -v ph="$PLACEHOLDER" '
+{
+  line = $0
+  while ((p = index(line, ph)) > 0) {
+    printf "%s%s", substr(line, 1, p-1), val
+    line = substr(line, p + length(ph))
+  }
+  print line
+}
+'

package/skills/linear-fetch/test/assert-no-linear-telemetry.test.sh

@@ -0,0 +1,113 @@
+#!/usr/bin/env bash
+# Tests for assert-no-linear-telemetry.sh — TR7 telemetry-redaction gate.
+#
+# Run via:  bash plugins/soleur/skills/linear-fetch/scripts/assert-no-linear-telemetry.test.sh
+
+set -eu
+
+# Owning trap (ADR-129). These files allocated tempfiles with no cleanup for as long as they
+# sat under scripts/, where no runner reached them; relocating them into test/ put them in
+# the lint's scope and surfaced it.
+_LF_TMPS=()
+_lf_cleanup() { [[ ${#_LF_TMPS[@]} -gt 0 ]] && rm -f "${_LF_TMPS[@]}"; return 0; }
+trap _lf_cleanup EXIT INT TERM HUP
+_lf_mktemp() { local t; t="$(mktemp)" || return 1; _LF_TMPS+=("$t"); printf '%s' "$t"; }
+
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../scripts" && pwd)"
+SCRIPT="$SCRIPT_DIR/assert-no-linear-telemetry.sh"
+
+PASS=0
+FAIL=0
+fail() { echo "  FAIL: $1"; FAIL=$((FAIL+1)); }
+pass() { echo "  pass: $1"; PASS=$((PASS+1)); }
+
+# Helper: pipe $1 through script, capture exit code.
+run_assert() {
+  set +e
+  printf '%s' "$1" | bash "$SCRIPT" >/dev/null 2>/dev/null
+  RC=$?
+  set -e
+}
+
+# ------------------------------------------------------------------------
+# Clean cases — must exit 0.
+# ------------------------------------------------------------------------
+echo "Test 1: empty payload"
+run_assert ""
+[[ "$RC" == "0" ]] && pass "exit 0 on empty" || fail "rc=$RC"
+
+echo "Test 2: generic telemetry text (no Linear refs)"
+run_assert "linear-fetch applied"
+[[ "$RC" == "0" ]] && pass "exit 0 on generic" || fail "rc=$RC"
+
+echo "Test 3: JSON-like telemetry without Linear refs"
+run_assert '{"rule": "hr-gdpr-gate", "action": "applied", "duration_ms": 12}'
+[[ "$RC" == "0" ]] && pass "exit 0" || fail "rc=$RC"
+
+# ------------------------------------------------------------------------
+# Forbidden patterns — must exit 1.
+# ------------------------------------------------------------------------
+echo "Test 4: Linear identifier SOL-39"
+run_assert "telemetry for SOL-39 processed"
+[[ "$RC" == "1" ]] && pass "exit 1 on SOL-39" || fail "rc=$RC"
+
+echo "Test 5: Linear identifier ENG-1234"
+run_assert "ENG-1234 in payload"
+[[ "$RC" == "1" ]] && pass "exit 1 on ENG-1234" || fail "rc=$RC"
+
+echo "Test 6: uploads.linear.app URL"
+run_assert "see https://uploads.linear.app/TEST-FIXTURE-NOT-REAL.png"
+[[ "$RC" == "1" ]] && pass "exit 1 on CDN URL" || fail "rc=$RC"
+
+echo "Test 7: uploads.linear.app case-insensitive"
+run_assert "Uploads.Linear.App/X.PNG"
+[[ "$RC" == "1" ]] && pass "exit 1 on case-insensitive CDN" || fail "rc=$RC"
+
+echo "Test 8: UUID-style ID"
+run_assert "issue 9e0a3888-fd38-49cd-87cb-83cdcecca199 done"
+[[ "$RC" == "1" ]] && pass "exit 1 on UUID" || fail "rc=$RC"
+
+# ------------------------------------------------------------------------
+# Edge cases — should NOT trigger false positives.
+# ------------------------------------------------------------------------
+echo "Test 9: PR-123 alone should NOT trigger (matches identifier shape but no Linear ref)"
+# Actually PR-123 DOES match [A-Z]{2,}-[0-9]+ — this is the spec's R2
+# false-positive class. The assertion is intentionally conservative:
+# any [A-Z]{2,}-[0-9]+ in telemetry is forbidden, even if it's a GitHub
+# PR reference. Telemetry should use generic strings or specific
+# whitelisted IDs (hashed/anonymized) instead.
+run_assert "see PR-123 for context"
+[[ "$RC" == "1" ]] && pass "exit 1 on PR-123 (conservative)" || fail "rc=$RC"
+
+echo "Test 10: lowercase identifier sol-39 should NOT trigger (case-sensitive on prefix)"
+run_assert "sol-39 is lowercase"
+[[ "$RC" == "0" ]] && pass "exit 0 on lowercase" || fail "rc=$RC"
+
+# ------------------------------------------------------------------------
+# File-path arg mode.
+# ------------------------------------------------------------------------
+echo "Test 11: file-path argument with clean content"
+tmp=$(_lf_mktemp)
+printf 'linear-fetch applied\n' > "$tmp"
+set +e
+bash "$SCRIPT" "$tmp" >/dev/null 2>/dev/null
+RC=$?
+set -e
+rm -f "$tmp"
+[[ "$RC" == "0" ]] && pass "exit 0 on clean file" || fail "rc=$RC"
+
+echo "Test 12: file-path argument with forbidden content"
+tmp=$(_lf_mktemp)
+printf 'SOL-39 in file\n' > "$tmp"
+set +e
+bash "$SCRIPT" "$tmp" >/dev/null 2>/dev/null
+RC=$?
+set -e
+rm -f "$tmp"
+[[ "$RC" == "1" ]] && pass "exit 1 on dirty file" || fail "rc=$RC"
+
+# ------------------------------------------------------------------------
+echo
+echo "Results: $PASS passed, $FAIL failed"
+exit $((FAIL > 0 ? 1 : 0))

package/skills/linear-fetch/test/parity.test.sh

@@ -0,0 +1,112 @@
+#!/usr/bin/env bash
+# Cross-artifact parity test for the load-bearing redaction rail.
+#
+# The plan's User-Brand Impact section names a 2-layer defense (in-skill
+# redaction + CI grep) "with no shared bypass." That guarantee depends on
+# both files covering the SAME set of CDN hostnames. This test asserts
+# the property: for each canonical hostname, both the redaction script
+# and the CI workflow must contain a reference to it.
+#
+# Without this test, the only enforcement is the "Sharp Edges" SKILL.md
+# note that says "update both sites." Reviewer agents flagged the bare-
+# convention approach as schema-drift-prone (learning
+# 2026-05-10-handshake-schema-drift-and-stale-precondition-budgets.md).
+#
+# Update CANONICAL_HOSTS below when LINEAR_CDN_PATTERNS gains a new
+# hostname — the test will then enforce that the workflow grew the
+# matching pattern in the same PR.
+#
+# Run via:  bash plugins/soleur/skills/linear-fetch/scripts/parity.test.sh
+
+set -eu
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../scripts" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../../../../.." && pwd)"
+REDACTOR="$SCRIPT_DIR/redact-linear-urls.sh"
+WORKFLOW="$REPO_ROOT/.github/workflows/pr-quality-guards.yml"
+
+# Canonical hostname set the redactor and CI grep both must cover.
+# When a new hostname (e.g., cdn.linear.app) is added to LINEAR_CDN_PATTERNS,
+# add it here AND ensure the workflow's pii-grep regex covers it.
+CANONICAL_HOSTS=("uploads.linear.app")
+
+PASS=0
+FAIL=0
+fail() { echo "  FAIL: $1"; FAIL=$((FAIL+1)); }
+pass() { echo "  pass: $1"; PASS=$((PASS+1)); }
+
+# Build a case-insensitive bracket pattern for a lowercase hostname.
+# Example: "uploads.linear.app" -> "[Uu][Pp][Ll][Oo][Aa][Dd][Ss]\.[Ll][Ii][Nn][Ee][Aa][Rr]\.[Aa][Pp][Pp]"
+case_bracket_pattern() {
+  local host="$1"
+  local out=""
+  local i c upper
+  for ((i = 0; i < ${#host}; i++)); do
+    c="${host:$i:1}"
+    if [[ "$c" == "." ]]; then
+      # The redactor file stores hostnames inside a bash $'...' ANSI-C
+      # string, so a literal `.` in the regex is escaped as `\\.` (two
+      # backslashes followed by a dot — bash's ANSI-C parser collapses
+      # this to one backslash + dot at runtime). We grep the on-disk
+      # representation, so we need the double-backslash form here.
+      out+='\\.'
+    else
+      upper="${c^^}"
+      out+="[${upper}${c}]"
+    fi
+  done
+  printf '%s' "$out"
+}
+
+# Files exist sanity check.
+[[ -r "$REDACTOR" ]] || { echo "ERROR: redactor not readable at $REDACTOR" >&2; exit 2; }
+[[ -r "$WORKFLOW" ]] || { echo "ERROR: workflow not readable at $WORKFLOW" >&2; exit 2; }
+
+for host in "${CANONICAL_HOSTS[@]}"; do
+  echo "Host: $host"
+
+  # Redactor encodes hostnames as [Cc][Hh]... bracketed case-insensitive
+  # sequences. Build the expected pattern and grep for it.
+  case_pat=$(case_bracket_pattern "$host")
+  if grep -qF "$case_pat" "$REDACTOR"; then
+    pass "redactor LINEAR_CDN_PATTERNS covers $host (matched: $case_pat)"
+  else
+    fail "redactor missing $host — expected to find literal '$case_pat'"
+  fi
+
+  # Workflow uses `grep -iE` so the literal lowercase form is what appears
+  # in the regex. (Other prose mentions in comments don't affect the gate's
+  # behavior but do satisfy this presence-check, which is fine — the test's
+  # job is to assert co-presence, not exhaustive line-by-line equivalence.)
+  if grep -qF "$host" "$WORKFLOW"; then
+    pass "workflow references $host"
+  else
+    fail "workflow does NOT reference $host — pii-grep would not catch leaks of this host"
+  fi
+done
+
+# Test 2: no orphan host in the workflow (a hostname appearing in the
+# workflow's actual regex but NOT in CANONICAL_HOSTS would indicate the
+# parity test itself is stale). Heuristic: extract `[a-z0-9-]+\.linear\.app`
+# literals from the workflow's gate steps and assert each is in
+# CANONICAL_HOSTS.
+echo
+echo "Workflow orphan-host check"
+workflow_hosts=$(grep -oE '[a-z0-9-]+\\\.linear\\\.app' "$WORKFLOW" | sed -E 's/\\\././g' | sort -u || true)
+canonical_set=$(printf '%s\n' "${CANONICAL_HOSTS[@]}" | sort -u)
+orphan=""
+while IFS= read -r wh; do
+  [[ -z "$wh" ]] && continue
+  if ! printf '%s\n' "$canonical_set" | grep -cFx >/dev/null "$wh"; then
+    orphan+="$wh "
+  fi
+done <<< "$workflow_hosts"
+if [[ -z "${orphan// /}" ]]; then
+  pass "no orphan hosts in workflow"
+else
+  fail "workflow references hosts not in CANONICAL_HOSTS: $orphan"
+fi
+
+echo
+echo "Results: $PASS passed, $FAIL failed"
+exit $((FAIL > 0 ? 1 : 0))