@soleur/opencode 0.0.0-stage → 1.0.0

package/skills/kb-search/SKILL.md

@@ -0,0 +1,276 @@
+---
+name: kb-search
+description: "This skill should be used when searching the knowledge base for files matching keywords or YAML frontmatter facets (tag, category) across domains."
+---
+
+<!-- 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 -->
+
+# KB Search
+
+Search the knowledge base across all domains. Returns learnings-scoped title matches first (tier 1, cap 8), then learnings-content matches (tier 2, cap 12). Optional `--tag` and `--category` flags filter `knowledge-base/project/learnings/` by YAML frontmatter before grep runs, cutting result-set noise during cross-referencing.
+
+## Arguments
+
+<search_query> #$ARGUMENTS </search_query>
+
+Accepted forms:
+
+- `soleur:kb-search <keyword>` — existing behavior, unchanged.
+- `soleur:kb-search --tag <value>` — filter learnings by frontmatter `tags:`.
+- `soleur:kb-search --category <value>` — filter learnings by frontmatter `category:`.
+- `soleur:kb-search --tag <value> --category <value> <keyword>` — combine (AND).
+- `soleur:kb-search --no-paraphrase <keyword>` — sensitive-query manual override; skips Phase 2.5 entirely. Use when the query carries a secret, customer name, or in-flight incident reference (anything you would not want forwarded to a paraphrase generator).
+- `soleur:kb-search --clear-cache` — remove `.soleur/cache/kb-search/query-paraphrases.ndjson`. The cache regenerates lazily on the next non-`--no-paraphrase` invocation.
+
+If `$ARGUMENTS` is empty, ask: "What would you like to search for in the knowledge base?"
+
+### Flag Semantics
+
+- Values are matched **case-insensitively** and **as literals** (fixed-string, not regex). `--tag n+1` matches the literal tag `n+1`.
+- Duplicate flags (`--tag a --tag b`) error with usage hint.
+- Unknown flags (`--taag`) error with usage hint listing supported flags.
+- Faceted queries scope to `knowledge-base/project/learnings/` only; other KB subtrees are skipped for facet lookups.
+- Tag-only or category-only queries emit `title + path` per file (no content snippet). Combined with a keyword, snippets come from the keyword match.
+
+## Privacy & Cost
+
+- Runtime paraphrase is inline; no countable spend. If Option B is ever adopted, caps land with it.
+- Operator queries MAY be sent to the Anthropic API (Haiku) by [scripts/learning-retrieval-bench.sh](../../../../scripts/learning-retrieval-bench.sh) only when the operator runs the bench-rerun gate (explicit opt-in via the existing `--confirm` flag). No runtime invocation forwards queries outside the executing agent's existing context.
+- Use `--no-paraphrase` for queries containing secrets, customer PII, or in-flight incident details. The skill auto-refuses paraphrase when the query matches the sensitive-shape regex (value-shape blobs + vendor key prefixes for Anthropic, OpenAI, GitHub, AWS, Stripe, Slack, JWT — see Phase 2.5 for the full byte-exact regex); `--no-paraphrase` is the manual override for queries that are sensitive but don't trip the regex (e.g., a customer name as a bare topic keyword).
+- Cache location: `.soleur/cache/kb-search/query-paraphrases.ndjson` (gitignored per `.soleur/` convention; refuses to write outside `.soleur/cache/`). File mode 0600, directory mode 0700 (re-applied on every append so a pre-existing looser-mode directory is hardened). The cache row stores `{sha256, query, variants, cached_at}` — `query` is stored in plaintext to enable manual inspection / debugging; rely on the directory + file modes (and `--clear-cache`) for confidentiality. TTL: 14 days.
+
+## Execution
+
+**Support-persona path (no Bash).** If you are running as the **Soleur
+Support** persona — your system prompt identifies you as "Soleur Support"
+and `kb-search` is your only loaded skill — do NOT execute any of the
+`bash`/` ```bash ` blocks in the phases below. On the support surface
+every non-safe-bash Bash call is denied AND records a support escalation
+that renders a false "Ask an agent" handoff at turn end. The corpus is
+already on disk under the session cwd: `knowledge-base/INDEX.md`,
+`knowledge-base/kb-tags.txt`, `knowledge-base/kb-categories.txt`, and
+`knowledge-base/project/learnings/*.md` are committed inside the deployed
+plugin root (all `knowledge-base/…` paths in the support section are
+relative to the support session cwd = plugin root, i.e.
+`plugins/soleur/knowledge-base/` at repo root — not the operator KB,
+which `denyReadExtra` obscures) — there is no index generator to run
+there (the `--soft` ensure call is for operator checkouts; skip it
+silently). If a Bash call IS denied with a read-only app-help message, do
+not retry Bash — switch to this path.
+
+| Phase | Tool-path equivalent |
+|---|---|
+| 0 arg parse | unchanged — pure in-context |
+| 1 facet validation | Read `knowledge-base/kb-tags.txt` and/or `kb-categories.txt`; match the flag value case-insensitively as a WHOLE LINE (fixed-string semantics — do not reproduce the `\b` regex, see #8473); on miss emit the same `No matches. Valid values: …` output |
+| 2 facet filter | Glob `knowledge-base/project/learnings/*.md`, then Read each file's frontmatter (the corpus is ~a dozen files) or Grep `^tags:`/`^category:` lines; AND-combine flags as today |
+| 2.5 paraphrase | still runs inline (Option C is agent-inline); SKIP both `kb-search-cache.sh` calls — every non-allowlisted Bash call on this surface denies AND records a support escalation (the cache write would fail in the read-only sandbox anyway) |
+| 3 keyword search | Tier 1: Grep `knowledge-base/INDEX.md` for the keyword, keep only links rooted at `knowledge-base/project/learnings/` (cap 8); Tier 2: Grep content under `knowledge-base/project/learnings/` excluding `archive/` (cap 12). When facet flags were given, restrict BOTH tiers to the Phase-2 surviving file list (same AND semantics as the bash path). Same dedupe-by-path merge |
+| 4 display | unchanged, EXCEPT the zero-result remediation: drop the scripts/ensure-kb-index.sh regenerate suggestion (a shell-out denies + escalates on this surface) — offer the spelling/keyword/tag-file suggestions only |
+| `--clear-cache` | unavailable on the support path (it needs a delete — there is no tool for it); say so instead of attempting it |
+
+### Phase 0: Parse Arguments
+
+Parse `$ARGUMENTS` into `$TAG`, `$CATEGORY`, and `$KEYWORD`. Track whether each flag was already seen to detect duplicates. On duplicate or unknown flag, emit:
+
+```text
+Usage: soleur:kb-search [--tag VALUE] [--category VALUE] [KEYWORD]
+```
+
+Then exit without searching.
+
+### Phase 1: Facet Validation (only if `--tag` or `--category` supplied)
+
+**Regenerate first — the facet files are untracked caches (ADR-235), so they are routinely absent in a fresh clone and routinely stale on a branch that just added a learning.** This call is the fix for the #8177 class, where a search reported "no prior art" for a file written minutes earlier. It is silent and costs ~60 ms when the index is already fresh; it only regenerates (~3 s) when something eligible changed.
+
+```bash
+[ -f scripts/ensure-kb-index.sh ] && bash scripts/ensure-kb-index.sh --soft || true
+```
+
+Then validate. **A missing artifact is NOT an error here** — `--soft` cannot regenerate in a repo that has no generator, which is every self-hosted install, and exiting 1 there would make `--tag` unusable with a Soleur-only remediation the user cannot run. Fall back to reading the frontmatter directly:
+
+The two arms below are ONE `if/else`, not two blocks (#8384 review). An earlier draft ended the
+fallback with the comment "skip the artifact check" and then ran the artifact check
+unconditionally anyway — so on a fresh checkout the fallback passed, the artifact grep failed
+on the absent file, and the user was told `Valid values: knowledge-base/kb-tags.txt`, naming a
+file that did not exist. That is the exact Soleur-only remediation ADR-235 says this change
+removes. The earlier draft also grepped `^tags:` only, so a `--category`-only query (where
+`$TAG` is empty) degenerated to "any line starting with `tags:`" and ALWAYS hit.
+
+```bash
+tag_lc=$(printf '%s' "${TAG:-}" | tr '[:upper:]' '[:lower:]')
+cat_lc=$(printf '%s' "${CATEGORY:-}" | tr '[:upper:]' '[:lower:]')
+if [ ! -f knowledge-base/kb-tags.txt ] || [ ! -f knowledge-base/kb-categories.txt ]; then
+  # No facet cache and no way to build one: validate each supplied value against the corpus
+  # itself. Whole-word, case-insensitive, over its OWN frontmatter line only -- one branch per
+  # flag, each guarded on the flag being set, so an empty value can never degenerate the regex.
+  if [ -n "$TAG" ] \
+     && ! git grep -ilE "^tags:.*\\b${TAG}\\b" -- 'knowledge-base/**/*.md' >/dev/null 2>&1; then
+    echo "No matches for --tag ${TAG}."
+    exit 0
+  fi
+  if [ -n "$CATEGORY" ] \
+     && ! git grep -ilE "^category:[[:space:]]*${CATEGORY}[[:space:]]*$" -- 'knowledge-base/**/*.md' >/dev/null 2>&1; then
+    echo "No matches for --category ${CATEGORY}."
+    exit 0
+  fi
+  # Every supplied value is real. Continue to Phase 2 -- the artifact checks in the else-arm
+  # are NOT reached.
+else
+  # Facet caches present: validate each supplied value against its artifact (case-insensitive,
+  # fixed-string, whole-line). On miss, emit and exit.
+  if [ -n "$TAG" ] && ! grep -Fxq "$tag_lc" knowledge-base/kb-tags.txt; then
+    echo "No matches. Valid values: knowledge-base/kb-tags.txt"
+    exit 0
+  fi
+  if [ -n "$CATEGORY" ] && ! grep -Fxq "$cat_lc" knowledge-base/kb-categories.txt; then
+    echo "No matches. Valid values: knowledge-base/kb-categories.txt"
+    exit 0
+  fi
+fi
+```
+
+### Phase 2: Filter Learnings by Frontmatter (only if `--tag` or `--category` supplied)
+
+Walk `knowledge-base/project/learnings/*.md`. For each file, parse YAML frontmatter with the same awk idiom the index generator uses:
+
+```awk
+/^---$/ { c++; next }
+c != 1 { next }
+# then match on ^tags: or ^category:
+```
+
+Accept both inline (`tags: [a, b]`) and block (`tags:\n  - a`) forms. Compare values case-insensitively. Collect the surviving file paths.
+
+If both flags are supplied, a file must match BOTH to survive (AND).
+
+### Phase 2.5: Paraphrase Pre-Pass (Stage 2, #4176)
+
+<!-- stage-2-paraphrase-union-v1 -->
+
+Stage 2 (#4176) adaptive pre-pass — runs after Phase 3 has produced a baseline two-tier grep result for `$KEYWORD`, and only when that result is sparse. The agent paraphrases inline within its own context (Option C runtime); no runtime API call is generated by this skill.
+
+**Trigger condition (ALL must hold):**
+
+1. `$KEYWORD` is non-empty (facet-only queries skip).
+2. Phase 3's two-tier grep returned **< 5 unique paths** (combined tier-1 + tier-2 dedupe-by-path count).
+3. `--no-paraphrase` was NOT passed.
+4. `$KEYWORD` does NOT match the sensitive-shape regex below (case-insensitive). The regex blends value-shape anchoring (assignment-blobs, postgres dsn=) and vendor-prefix anchoring (Anthropic, OpenAI, GitHub, AWS, Stripe, Slack, JWT triple-blob) — prefix anchors avoid blocking topic-keyword queries like `"JWT token refresh"` or `"keypress event"` while still catching credential paste-throughs. Known false-positive: a `gh<letter>_`-prefixed identifier slug ≥36 in-class chars (e.g. `ghs_token-format-sentinel…`, a feature name this repo's own convention generates) trips the guard — the refusal is recoverable via `--no-paraphrase`. Source of truth is `SENSITIVE_QUERY_REGEX` in [scripts/learning-retrieval-bench.sh](../../../../scripts/learning-retrieval-bench.sh); [plugins/soleur/test/kb-search-lockstep.test.sh](../../../test/kb-search-lockstep.test.sh) asserts byte-equality across both files.
+
+   ```text
+   ((=|:)[[:space:]]*[a-zA-Z0-9+/]{16,}|sk-(ant-)?[a-zA-Z0-9_-]{20,}|sk_live_[a-zA-Z0-9]{20,}|pk_live_[a-zA-Z0-9]{20,}|rk_live_[a-zA-Z0-9]{20,}|ghp_[a-zA-Z0-9._~+/=-]{36}|gho_[a-zA-Z0-9._~+/=-]{36}|ghs_[a-zA-Z0-9._~+/=-]{36}|ghu_[a-zA-Z0-9._~+/=-]{36}|ghr_[a-zA-Z0-9._~+/=-]{36}|github_pat_[a-zA-Z0-9._~+/=-]{40,}|AKIA[0-9A-Z]{16}|ASIA[0-9A-Z]{16}|xox[abprs]-[a-zA-Z0-9-]{10,}|eyJ[A-Za-z0-9_-]{15,}\.[A-Za-z0-9_-]{15,}\.[A-Za-z0-9_.+/=-]{15,}|dsn=)
+   ```
+
+If any condition fails, skip Phase 2.5 and return Phase 3's result unchanged.
+
+**Sensitive-query guard (manual override = `--no-paraphrase`):** when condition 4 fails, emit and exit:
+
+```text
+kb-search: refusing to paraphrase query containing sensitive value-shape token. Pass --no-paraphrase to explicitly bypass.
+```
+
+**Cache lookup:**
+
+```bash
+variants=$(bash "${CLAUDE_PLUGIN_ROOT}/skills/kb-search/scripts/kb-search-cache.sh" lookup "$KEYWORD")
+```
+
+On hit (newline-separated variants, < 14 days old) skip variant generation and go straight to union execution. On miss (empty output) proceed.
+
+**Variant generation (Option C agent-inline):**
+
+> Generate exactly 3 paraphrase variants of `$KEYWORD`. Each variant should use different vocabulary while preserving semantic intent (swap verbs for nouns where natural, substitute domain-canonical synonyms). Output one variant per line, no preamble.
+
+**Cache write:**
+
+```bash
+bash "${CLAUDE_PLUGIN_ROOT}/skills/kb-search/scripts/kb-search-cache.sh" append "$KEYWORD" "$v1" "$v2" "$v3"
+```
+
+**Union execution:** for each of the 4 strings (original `$KEYWORD` + 3 variants), run Phase 3's two-tier grep under its own per-tier 8+12 caps. The 4 per-variant ranked lists are then merged into a single flat hit-count rerank capped at 20 — per-tier identity does not survive the union (by design — union-by-hit-count is the new ranking signal), and 20 is the absolute ceiling on what kb-search returns.
+
+**Fallback policy:** paraphrase failure (rate limit, network, model refusal, all variants empty) → emit to stderr and fall back to Phase 3's baseline result:
+
+```text
+kb-search: WARN — paraphrase generation failed: <cause> — falling back to baseline grep
+```
+
+Per-session cap breach (executing agent has generated more paraphrase calls than is sane in one session) → emit `kb-search: WARN — paraphrase cap reached — falling back to baseline grep` and use the baseline result.
+
+### Phase 3: Keyword Search
+
+- **Facet-only (no keyword):** Emit one line per surviving file in `- [Title](path)` form (title read from frontmatter or first `# heading`).
+- **Keyword-only (no facets):** Run the two-tier search with per-tier caps so tier-1 noise titles cannot starve tier-2 content matches (see #4119):
+  1. **Tier 1 (cap 8):** Run `[ -f scripts/ensure-kb-index.sh ] && bash scripts/ensure-kb-index.sh --soft || true` first (untracked cache — see Phase 1; the call is idempotent, so a second one after Phase 1 costs only the ~60 ms probe), then grep `knowledge-base/INDEX.md` for the keyword, then restrict to lines whose link target is rooted under `knowledge-base/project/learnings/`. Anchor the filter so future paths like `sessions/learnings-retrospective/` cannot leak.
+  2. **Tier 2 (cap 12):** Grep `knowledge-base/project/learnings/**/*.md` content for the keyword. Exclude `archive/`.
+- Output tier-1 first, then tier-2, deduped by path. Maximum 20 total; each tier self-caps.
+- **Facets + keyword:** Apply keyword grep **only** to the facet-filtered file list (not the whole KB). Use `grep -F` (fixed-string).
+
+Missing `INDEX.md` after the ensure call → the repo has no generator (a self-hosted install). Note it and continue with the Tier-2 content grep only; never exit non-zero on this, and never print a remediation naming a script the user does not have.
+
+### Phase 4: Display Results
+
+Title matches come first, then content matches. Cap total at 20; if truncated, append:
+
+```text
+Showing top 20 of N matches. Narrow the query for more specific results.
+```
+
+Zero results → suggest:
+
+- Check spelling
+- Try broader or alternative keywords
+- For `--tag`/`--category` misses, inspect `knowledge-base/kb-tags.txt` or `kb-categories.txt`
+- Run `bash scripts/ensure-kb-index.sh` to refresh the untracked caches (Soleur repo only; it is a no-op when they are already fresh)
+
+## Examples
+
+### Tag filter with keyword
+
+```text
+soleur:kb-search --tag eager-loading rails
+```
+
+Returns learnings tagged `eager-loading` whose content matches `rails`.
+
+### Category filter alone
+
+```text
+soleur:kb-search --category performance-issues
+```
+
+Returns all learnings with `category: performance-issues` as title+path.
+
+### Combined facets
+
+```text
+soleur:kb-search --tag n+1 --category performance-issues
+```
+
+Returns learnings tagged `n+1` AND categorized as `performance-issues`.
+
+### Miss with hint
+
+```text
+soleur:kb-search --tag nonexistent-tag
+# Output:
+# No matches. Valid values: knowledge-base/kb-tags.txt
+```
+
+The agent can read the artifact in a follow-up round-trip to self-correct.
+
+## Output Format
+
+```text
+## Title Matches
+
+1. [Title](knowledge-base/path) — title match
+2. [Title](knowledge-base/path) — title match
+
+## Content Matches
+
+3. [Title](knowledge-base/path) — content match (line N: "...snippet...")
+```
+
+Tag-only or category-only output uses the `## Title Matches` block only, without snippets.

package/skills/kb-search/scripts/kb-search-cache.sh

@@ -0,0 +1,123 @@
+#!/usr/bin/env bash
+# kb-search-cache.sh — NDJSON cache helper for the Stage 2 (#4176) paraphrase
+# pre-pass. Pure local I/O; never reaches Anthropic. Three subcommands:
+#
+#   lookup <query>                       — sha256-keyed cache lookup with
+#                                          14-day TTL. Echoes variants
+#                                          (newline-separated) on hit, empty
+#                                          on miss/expired. Always exit 0.
+#   append <query> <v1> [v2] [v3]        — append one NDJSON row keyed by
+#                                          sha256 of <query>. Creates the
+#                                          cache directory chmod 700 on
+#                                          first call.
+#   clear                                — remove the cache file.
+#
+# Cache location: $REPO_ROOT/.soleur/cache/kb-search/query-paraphrases.ndjson.
+# `.soleur/` is gitignored (see .gitignore — `.soleur/` line; the repo
+# precedent for local agent state, no ~/.cache/soleur/ exists). chmod 700
+# is load-bearing on multi-user dev machines, symbolic on single-user
+# laptops. The cache file inherits a 077 umask via subshell wrap on every
+# append (mode 0600) so it is not group/other-readable even when the
+# operator's default umask is permissive.
+#
+# KB_SEARCH_CACHE_DIR override is permitted ONLY when it resolves to a path
+# under $REPO_ROOT/.soleur/cache/ — arbitrary world-writable override paths
+# are refused to prevent silent confidentiality downgrade.
+
+set -euo pipefail
+
+REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+DEFAULT_CACHE_DIR="$REPO_ROOT/.soleur/cache/kb-search"
+CACHE_DIR="${KB_SEARCH_CACHE_DIR:-$DEFAULT_CACHE_DIR}"
+CACHE_FILE="$CACHE_DIR/query-paraphrases.ndjson"
+TTL_SECONDS=1209600  # 14 days.
+
+# Refuse caches outside the repo's .soleur/cache/ tree. Operator-set
+# KB_SEARCH_CACHE_DIR is honored only when it expands to a path inside the
+# canonical .soleur/cache/ prefix. Anything else (e.g., /tmp, /shared/foo)
+# would silently bypass the chmod 700 directory guard for operators who
+# default-umask to 0002 / 0022.
+ALLOWED_PREFIX="$REPO_ROOT/.soleur/cache/"
+case "$CACHE_DIR/" in
+  "$ALLOWED_PREFIX"*) ;;
+  *)
+    echo "kb-search-cache: refusing CACHE_DIR='$CACHE_DIR' (must be under '$ALLOWED_PREFIX')" >&2
+    exit 2
+    ;;
+esac
+
+usage() {
+  cat >&2 <<'USAGE'
+Usage:
+  kb-search-cache.sh lookup <query>
+  kb-search-cache.sh append <query> <variant1> [variant2] [variant3]
+  kb-search-cache.sh clear
+USAGE
+  exit 2
+}
+
+cmd="${1:-}"
+[[ -z "$cmd" ]] && usage
+
+case "$cmd" in
+  lookup)
+    query="${2:-}"
+    [[ -z "$query" ]] && usage
+    [[ -f "$CACHE_FILE" ]] || exit 0
+    hash=$(printf '%s' "$query" | sha256sum | awk '{print $1}')
+    # jq parse error → cache miss (treat malformed NDJSON as no-cache). The
+    # `2>/dev/null` + `|| true` keeps `set -e` happy when jq returns 5
+    # (parse error) on any line.
+    row=$(jq -c --arg h "$hash" 'select(.sha256 == $h)' "$CACHE_FILE" 2>/dev/null | head -1 || true)
+    [[ -z "$row" ]] && exit 0
+    cached_at=$(printf '%s' "$row" | jq -r '.cached_at // empty' 2>/dev/null || true)
+    [[ -z "$cached_at" ]] && exit 0
+    # ISO 8601 UTC `Z`-suffixed. `date -u -d` accepts the form.
+    cached_epoch=$(date -u -d "$cached_at" +%s 2>/dev/null || echo 0)
+    [[ "$cached_epoch" -eq 0 ]] && exit 0
+    now_epoch=$(date -u +%s)
+    age=$((now_epoch - cached_epoch))
+    if (( age > TTL_SECONDS )); then
+      exit 0
+    fi
+    printf '%s' "$row" | jq -r '.variants[]?' 2>/dev/null || true
+    exit 0
+    ;;
+  append)
+    query="${2:-}"
+    [[ -z "$query" ]] && usage
+    shift 2
+    (( $# == 0 )) && usage
+    variants=("$@")
+    # Create dir if absent. chmod 700 unconditionally on every append so a
+    # pre-existing directory (created by a different tool with looser perms)
+    # is hardened on first append — `mkdir -p` is a no-op on existing dirs
+    # and would otherwise leave the inherited mode in place.
+    mkdir -p "$CACHE_DIR"
+    chmod 700 "$CACHE_DIR"
+    hash=$(printf '%s' "$query" | sha256sum | awk '{print $1}')
+    cached_at=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+    # Build the variants array via jq from positional args. `--args` reads
+    # remaining strings safely (no shell injection through paraphrase content).
+    # umask 077 in a subshell forces mode 0600 on the cache file even if the
+    # operator's default umask is 0002/0022 — without this the file is
+    # group/other-readable and `chmod 700` on the directory alone does not
+    # protect against same-process / privileged readers.
+    ( umask 077
+      jq -nc --arg sha "$hash" --arg q "$query" --arg ts "$cached_at" \
+        --args '{sha256:$sha, query:$q, variants:$ARGS.positional, cached_at:$ts}' \
+        -- "${variants[@]}" \
+        >> "$CACHE_FILE"
+    )
+    # Defense in depth: if the file existed pre-append with looser perms,
+    # the umask 077 subshell does not retroactively tighten it. Apply 0600
+    # explicitly post-append (idempotent on already-correct files).
+    chmod 600 "$CACHE_FILE"
+    ;;
+  clear)
+    rm -f "$CACHE_FILE"
+    ;;
+  *)
+    usage
+    ;;
+esac

package/skills/legal-audit/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: legal-audit
+description: "This skill should be used when auditing existing legal documents for compliance gaps, outdated clauses, missing disclosures, and cross-document consistency. It scans a project for legal documents and displays findings inline."
+---
+
+<!-- soleur-cloud-mode:start -->
+**Cloud Mode (Devin):** before pipeline work run `bash "${CLAUDE_PLUGIN_ROOT}/scripts/cloud-detect.sh"`. If `CLAUDE_PLUGIN_ROOT` is unset (cloud exec shells do not export it), resolve the root by IDENTITY, never by script basename: for `d` in `"$HOME/.local/share/devin/cli/plugins/cache"` and `/opt/.devin/plugins`, skip unless `[ -d "$d" ]`, then `MANIFEST="$(find "$d" -path '*/.claude-plugin/plugin.json' -exec grep -l '"name"[[:space:]]*:[[:space:]]*"soleur"' {} + 2>/dev/null | head -1)"`, `ROOT="${MANIFEST%/.claude-plugin/plugin.json}"` — one resolution, two consumers: `$ROOT/scripts/cloud-detect.sh` and `$ROOT/scripts/precommit-guard.sh`. (Shape check, not authentication: a planted `{"name":"soleur"}` dir passes — ADR-179 A11.) `local` or `not-local:no-devin-env` proceeds normally; any other `not-local:<reason>` applies `<plugin-root>/devin/INSTRUCTIONS.md` §Cloud Mode: emit the `--banner`, fan out sequentially with `Reviewed-Coverage: sequential-fallback` disclosure (never claim an independent review ran), `message_user` ack before any secrets read or production mutation, and run `precommit-guard.sh` before any `git commit` — hooks do not fire in cloud.
+<!-- soleur-cloud-mode:end -->
+
+<!-- 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 -->
+
+# Legal Compliance Auditor
+
+Scan a project's existing legal documents and audit them for compliance gaps, outdated clauses, missing disclosures, and cross-document consistency. Findings are displayed inline in the conversation.
+
+**Cross-reference:** If `gdpr-gate` flags a new PII column (Art. 9 or otherwise), run this skill against the privacy policy to verify the disclosure landed.
+
+## Phase 0: Discovery
+
+Scan the project for existing legal documents. Search common locations:
+
+- `docs/legal/`
+- `legal/`
+- `pages/legal/`
+- Root directory files matching: `terms*`, `privacy*`, `cookie*`, `gdpr*`, `disclaimer*`, `acceptable-use*`, `dpa*`
+
+Use the **Glob tool** with patterns like `**/legal/**/*.md`, `**/privacy*`, `**/terms*`.
+
+Present the discovered documents and use the **AskUserQuestion tool** to confirm scope:
+
+"Found N legal documents. Audit all of them, or select specific files?"
+
+If no legal documents are found, report: "No legal documents found in this project. Use `soleur:legal-generate` to create them.
+
+> **Or:** If you're handling an inbound MSA, DSAR, AI-vendor terms review, OSS-license question, or breach notice, see `knowledge-base/legal/recommended-tools.md` for downstream specialist tools."
+
+## Phase 1: Context
+
+Use the **AskUserQuestion tool** to ask which jurisdictions to audit against:
+
+- US
+- EU/GDPR
+- UK
+- Multiple (specify)
+
+Read each document in the confirmed scope.
+
+## Phase 2: Audit
+
+Invoke the `soleur:legal:legal-compliance-auditor` agent via the **Task tool** with all documents and jurisdiction context.
+
+If the user's input includes the word `benchmark` (either via `args` parameter or natural language), append the benchmark trigger to the Task prompt. Otherwise, send the standard audit prompt unchanged.
+
+**Standard audit prompt:**
+
+```
+Task soleur:legal:legal-compliance-auditor: "Audit the following legal documents for [jurisdiction] compliance.
+
+Documents:
+[Include full content of each document]
+
+Check each document individually for compliance gaps, then cross-reference all documents for consistency."
+```
+
+**Benchmark audit prompt** (append to the standard prompt above):
+
+```
+"Additionally, run benchmark mode: check against the GDPR Art 13/14 regulatory disclosure checklist and compare against peer SaaS policies."
+```
+
+## Phase 3: Report
+
+<critical_sequence>
+
+Display all findings inline in the conversation. NEVER write audit findings to files -- this is a hard requirement for open-source repositories.
+
+</critical_sequence>
+
+After displaying findings, use the **AskUserQuestion tool**:
+
+- **Fix Critical/High** -- Generate fix suggestions for the most severe findings
+- **Done** -- End the audit
+
+If "Fix Critical/High" is selected, present specific text changes the user can apply to address each Critical and High finding. The user applies fixes manually.
+
+### When to escalate (inline-conversation only)
+
+After displaying findings, scan each finding's category against the threshold catalog at [`knowledge-base/legal/recommended-tools.md`](../../../knowledge-base/legal/recommended-tools.md).
+
+For each finding that matches a threshold, append a one-line escalation pointer:
+
+> **When to escalate:** &lt;threshold name&gt;. See `knowledge-base/legal/recommended-tools.md#&lt;anchor&gt;`.
+
+For statutory-deadline thresholds (DSAR, breach), interpolate the deadline into a dedicated `### Escalation required` H3 above the findings list (NOT a trailing blockquote — deadline-sensitive). Format:
+
+---
+
+### Escalation required — 72h deadline (GDPR Art. 33 — breach-notice-triage)
+
+See `knowledge-base/legal/recommended-tools.md#breach-notice-triage`.
+
+---
+
+**Zero-findings + threshold-in-flight catch.** If the audit produces zero findings AND the project contains regulated-data surfaces (privacy policy, ToS mentioning data processing, breach-response doc, anything matching `**/{privacy,terms,gdpr,dpa,disclaimer}*`):
+
+1. **ALWAYS append the full threshold catalog pointer at the bottom of the report.** A clean audit does NOT mean no threshold is in flight — a founder mid-DSAR may have a clean privacy policy.
+2. **Additionally, surface a top-of-report deadline-check banner**: a single inline-prose question asking the user to confirm whether any of the deadline-bearing thresholds (DSAR Art. 12 — 30 days; breach Art. 33 — 72 hours from awareness) is in flight right now. If yes, the founder should treat the corresponding `### Escalation required` H3 (with its statutory deadline interpolated into the heading) as the primary output of this audit — the catalog at the bottom is secondary.
+
+This dual surfacing closes the failure mode where a founder under deadline pressure runs an audit on docs that happen to be clean and never sees the deadline H3 (because no finding triggered it via category-match alone).
+
+**Inline only.** NEVER write the escalation pointer or catalog pointer to a file — Phase 3 `<critical_sequence>` (above) applies to every output of this skill.
+
+## Important Guidelines
+
+- Audit findings are conversation-only -- never persist to files in the repository
+- Cross-document consistency checks only run when 2+ documents are in scope
+- If a document references another document type that does not exist in the project, flag it as a CRITICAL finding
+- Do not modify the audited documents -- only report findings and suggest fixes
+
+## CI gates over `docs/legal/**` (#7387)
+
+Five gates ride this path. Reproduce any of them locally before pushing:
+
+- `bash scripts/lint-legal-scope-block-placement.sh --base origin/main` — added scope blocks:
+  referent/section agreement, attachment, discharge. `--print-vocab` lists every accepted
+  phrasing; a locality assertion whose referent it does not recognise is reported as
+  NOT CHECKED rather than silently skipped.
+- `bash scripts/lint-legal-mirror-drift-baseline.sh --base origin/main` — canonical↔mirror drift
+  ratchet. Reducing drift always passes; growth, reordering, and in-place edits of an
+  already-drifting line fail. A revert or an urgent publication that must land despite it sets
+  `SOLEUR_LEGAL_DRIFT_ACCEPT='<reason>'`, which downgrades to a warning and records the reason.
+- `apps/web-platform/scripts/check-tc-document-sha.sh` — raw-file SHA pin; re-pin
+  `apps/web-platform/lib/legal/legal-doc-shas.ts` after any canonical edit.
+- `apps/web-platform/test/legal-doc-consistency.test.ts` — heading-sequence parity.
+- The `EXPECTED_COUNT` sentinel in the SHA guard, cross-checked by a vitest harness.
+
+**Gates measure agreement, not truth (#7349).** All five gates compare the two surfaces against
+each other. None asks whether the agreed text is correct, so two byte-identical copies of a false
+sentence pass every one of them. Three defects shipped past a full green run in #7349 that way: a
+controllership statement drift-reduction copied onto the published page, a duplicated clause left
+behind by a half-applied replacement, and "eleven processing activities" in a document whose
+register carries thirty-five. Read the prose; do not read the drift number and stop.
+
+**`BODY_EQUIVALENCE_DOCS` is a one-way ratchet.** `terms-and-conditions`, `acceptable-use-policy`
+and `disclaimer` are enrolled; each was verified at ZERO normalised drift immediately before
+enrolment, because enrolling a drifted document turns a required check red on arrival. Once
+enrolled, any edit landing on one surface only reds that check — which is the point. `--print-vocab`
+and a mutation check (inject a line, confirm the guard fails, remove it) are the two ways to prove
+an enrolment is live rather than decorative.
+
+**Two measurement traps that cost real rounds in #7349.** `collapse()` normalises `[0-9]+ AI
+agents` but NOT a bare `[0-9]+ agents`, so count divergence between the record and the published
+page can be invisible to the drift gate. And a grep for `Article ` will not match the corpus's <!-- markdownlint-disable-line MD038 -->
+plural `Articles 15 through 22` — use `Articles? 1[5-9]`.
+
+**The mirror is the published surface.** `docs/legal/<doc>.md` is the canonical record;
+`plugins/soleur/docs/pages/legal/<doc>.md` is what users read at soleur.ai/legal/. `docs/legal/`
+is in no Eleventy input tree and is read by no route, so a canonical-only edit changes nothing a
+user sees — and exits 2 as an unpaired document.