@soleur/opencode 0.0.0-stage → 1.0.0

package/skills/skill-creator/workflows/verify-skill.md

@@ -0,0 +1,226 @@
+# Workflow: Verify Skill Content Accuracy
+
+<required_reading>
+**Read these reference files NOW:**
+
+1. references/skill-structure.md
+</required_reading>
+
+<purpose>
+Audit checks structure. **Verify checks truth.**
+
+Skills contain claims about external things: APIs, CLI tools, frameworks, services. These change over time. This workflow checks if a skill's content is still accurate.
+</purpose>
+
+<process>
+## Step 1: Select the Skill
+
+```bash
+ls ~/.claude/skills/
+```
+
+Present numbered list, ask: "Which skill should I verify for accuracy?"
+
+## Step 2: Read and Categorize
+
+Read the entire skill (SKILL.md + workflows/ + references/):
+
+```bash
+cat ~/.claude/skills/{skill-name}/SKILL.md
+cat ~/.claude/skills/{skill-name}/workflows/*.md 2>/dev/null
+cat ~/.claude/skills/{skill-name}/references/*.md 2>/dev/null
+```
+
+Categorize by primary dependency type:
+
+| Type | Examples | Verification Method |
+|------|----------|---------------------|
+| **API/Service** | manage-stripe, manage-gohighlevel | Context7 + WebSearch |
+| **CLI Tools** | build-macos-apps (xcodebuild, swift) | Run commands |
+| **Framework** | build-iphone-apps (SwiftUI, UIKit) | Context7 for docs |
+| **Integration** | setup-stripe-payments | WebFetch + Context7 |
+| **Pure Process** | create-agent-skills | No external deps |
+
+Report: "This skill is primarily [type]-based. I'll verify using [method]."
+
+## Step 3: Extract Verifiable Claims
+
+Scan skill content and extract:
+
+**CLI Tools mentioned:**
+
+- Tool names (xcodebuild, swift, npm, etc.)
+- Specific flags/options documented
+- Expected output patterns
+
+**API Endpoints:**
+
+- Service names (Stripe, Meta, etc.)
+- Specific endpoints documented
+- Authentication methods
+- SDK versions
+
+**Framework Patterns:**
+
+- Framework names (SwiftUI, React, etc.)
+- Specific APIs/patterns documented
+- Version-specific features
+
+**File Paths/Structures:**
+
+- Expected project structures
+- Config file locations
+
+Present: "Found X verifiable claims to check."
+
+## Step 4: Verify by Type
+
+### For CLI Tools
+
+```bash
+# Check tool exists
+which {tool-name}
+
+# Check version
+{tool-name} --version
+
+# Verify documented flags work
+{tool-name} --help | grep "{documented-flag}"
+```
+
+### For API/Service Skills
+
+Use Context7 to fetch current documentation:
+
+```
+mcp__context7__resolve-library-id: {service-name}
+mcp__context7__get-library-docs: {library-id}, topic: {relevant-topic}
+```
+
+Compare skill's documented patterns against current docs:
+
+- Are endpoints still valid?
+- Has authentication changed?
+- Are there deprecated methods being used?
+
+### For Framework Skills
+
+Use Context7:
+
+```
+mcp__context7__resolve-library-id: {framework-name}
+mcp__context7__get-library-docs: {library-id}, topic: {specific-api}
+```
+
+Check:
+
+- Are documented APIs still current?
+- Have patterns changed?
+- Are there newer recommended approaches?
+
+### For Integration Skills
+
+WebSearch for recent changes:
+
+```
+"[service name] API changes 2026"
+"[service name] breaking changes"
+"[service name] deprecated endpoints"
+```
+
+Then Context7 for current SDK patterns.
+
+### For Services with Status Pages
+
+WebFetch official docs/changelog if available.
+
+## Step 5: Generate Freshness Report
+
+Present findings:
+
+```
+## Verification Report: {skill-name}
+
+### ✅ Verified Current
+- [Claim]: [Evidence it's still accurate]
+
+### ⚠️ May Be Outdated
+- [Claim]: [What changed / newer info found]
+  → Current: [what docs now say]
+
+### ❌ Broken / Invalid
+- [Claim]: [Why it's wrong]
+  → Fix: [What it should be]
+
+### ℹ️ Could Not Verify
+- [Claim]: [Why verification wasn't possible]
+
+---
+**Overall Status:** [Fresh / Needs Updates / Significantly Stale]
+**Last Verified:** [Today's date]
+```
+
+## Step 6: Offer Updates
+
+If issues found:
+
+"Found [N] items that need updating. Would you like me to:"
+
+1. **Update all** - Apply all corrections
+2. **Review each** - Show each change before applying
+3. **Just the report** - No changes
+
+If updating:
+
+- Make changes based on verified current information
+- Add verification date comment if appropriate
+- Report what was updated
+
+## Step 7: Suggest Verification Schedule
+
+Based on skill type, recommend:
+
+| Skill Type | Recommended Frequency |
+|------------|----------------------|
+| API/Service | Every 1-2 months |
+| Framework | Every 3-6 months |
+| CLI Tools | Every 6 months |
+| Pure Process | Annually |
+
+"This skill should be re-verified in approximately [timeframe]."
+</process>
+
+<verification_shortcuts>
+
+## Quick Verification Commands
+
+**Check if CLI tool exists and get version:**
+
+```bash
+which {tool} && {tool} --version
+```
+
+**Context7 pattern for any library:**
+
+```
+1. resolve-library-id: "{library-name}"
+2. get-library-docs: "{id}", topic: "{specific-feature}"
+```
+
+**WebSearch patterns:**
+
+- Breaking changes: "{service} breaking changes 2026"
+- Deprecations: "{service} deprecated API"
+- Current best practices: "{framework} best practices 2026"
+</verification_shortcuts>
+
+<success_criteria>
+Verification is complete when:
+
+- [ ] Skill categorized by dependency type
+- [ ] Verifiable claims extracted
+- [ ] Each claim checked with appropriate method
+- [ ] Freshness report generated
+- [ ] Updates applied (if requested)
+- [ ] User knows when to re-verify
+</success_criteria>

package/skills/skill-security-scan/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: skill-security-scan
+description: "This skill should be used when scanning Claude Code skills or agent files for advisory security risks: code-execution, prompt-injection, supply-chain, filesystem-boundary, telemetry. Emits LOW-RISK | REVIEW | HIGH-RISK."
+---
+
+<!-- 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 -->
+
+# skill-security-scan
+
+<!--
+Pattern provenance: portions of the detection-pattern taxonomy and the five-category
+breakdown are adapted from alirezarezvani/claude-skills (skill-security-auditor),
+licensed under the MIT License. The verbatim license text is preserved at
+[LICENSES/skill-security-auditor.MIT.txt](../../../../LICENSES/skill-security-auditor.MIT.txt).
+No verbatim code is copied; only the conceptual taxonomy and category framing.
+-->
+
+Advisory static-analysis gate that scans a SKILL.md or agent markdown file for five
+categories of security risk. Emits one of `LOW-RISK | REVIEW | HIGH-RISK` plus a
+findings report, with a mandatory advisory disclaimer footer. **Advisory only:**
+output is not a security audit, certification, or warranty. The skill executes in
+the operator's environment under the operator's account; the operator remains
+responsible for review.
+
+## Detection categories
+
+1. **Code-execution anti-patterns** — dynamic-eval primitives, shell-spawn with
+   user-controlled args, obfuscation signatures. See
+   [references/rules/code-exec.yaml](./references/rules/code-exec.yaml).
+2. **Prompt-injection** — frontmatter role-hijack and body proximity-gated patterns,
+   with Soleur prose allowlist. See
+   [references/regex-patterns.md](./references/regex-patterns.md).
+3. **Supply-chain risk** — osv.dev batch query against parsed manifest references,
+   with ecosystem allowlist + REVIEW-on-unknown + network-error-as-REVIEW.
+4. **Filesystem boundary violations** — path traversal, symlink-out, write attempts
+   to credential dotfiles. See
+   [references/rules/filesystem-boundary.yaml](./references/rules/filesystem-boundary.yaml).
+5. **Third-Party Telemetry Surface** — utm-tagged links, redirect-tracking domains,
+   outbound-beacon URLs, vendor-branding footers. URL host-aware allowlist (not raw
+   substring match — adversarial `https://attacker.com/?ref=soleur.ai` is detected
+   as host=attacker.com). See
+   [references/first-party-allowlist.yaml](./references/first-party-allowlist.yaml).
+
+## Verdict semantics
+
+| Verdict | Meaning | Operator action |
+|---|---|---|
+| `LOW-RISK` | No findings, or only finding-level metadata WARN tags | Proceed silently |
+| `REVIEW` | At least one category emitted REVIEW | Read findings; decide |
+| `HIGH-RISK` | At least one category emitted HIGH-RISK | Block-by-default; override via structured artifact |
+
+Aggregation rule: max-severity across the five categories wins. Per-finding
+`severity: WARN` contributes `REVIEW` to the aggregate verdict, never `HIGH-RISK`
+alone.
+
+## Invocation
+
+Scan a file:
+
+```bash
+bash "${CLAUDE_PLUGIN_ROOT}/skills/skill-security-scan/scripts/run-scan.sh" < path/to/SKILL.md
+```
+
+Scan stdin content (used by `soleur:engineering:discovery:agent-finder` post-fetch / `skill-creator` post-scaffold
+integrations):
+
+```bash
+echo "$skill_md_content" | bash "${CLAUDE_PLUGIN_ROOT}/skills/skill-security-scan/scripts/run-scan.sh"
+```
+
+**No verdict line means REVIEW.** If the output carries no `LOW-RISK`/`REVIEW`/`HIGH-RISK` verdict — the script
+crashed, or the shell printed `No such file or directory` because the plugin root did not resolve — treat the
+skill as **REVIEW**, never LOW-RISK (ADR-179 A18).
+
+Output: markdown findings table on stdout, mandatory advisory disclaimer footer
+(non-removable), and `.scan-meta.json` persisted under
+`$XDG_RUNTIME_DIR/skill-security-scan-<pid>/` (or `SKILL_SCAN_META_BASE` when
+set; `/tmp` when neither is set). Retention is bounded by the scanner's own
+startup age-reap: `skill-security-scan-*` dirs older than
+`SKILL_SCAN_META_REAP_MIN` minutes (default 10080 = 7 days) are reaped at the
+next invocation, and the same knob bounds a sibling sweep under
+`${TMPDIR:-/tmp}` covering `skill-scan-*` scratch orphans, stranded
+`skill-security-scan-*` crossover dirs, and `sss-write.*.err` hook captures
+(#6789, #6760). One knob, two scopes: shrinking it shrinks BOTH the Art. 32
+evidence window and the scratch floor — and both sweeps clamp to a 60-minute
+minimum because a lower floor can reap a concurrent scan's live scratch or
+live meta dir.
+The dir is deliberately NOT EXIT-trap-cleaned: the override flow reads the
+path after the scan exits.
+
+## Override mechanism
+
+When the scanner returns `HIGH-RISK` and the operator judges the finding to be a
+false-positive or accepted-risk, override by committing a structured artifact:
+
+```
+knowledge-base/engineering/security/skill-overrides/YYYY-MM-DD-<slug>.md
+```
+
+The artifact is the sole audit-trail (no git trailer involved — squash-merge-safe).
+Schema: [references/override-artifact-schema.json](./references/override-artifact-schema.json).
+Process: [references/override-mechanism.md](./references/override-mechanism.md).
+
+## Self-defense
+
+The scanner is itself an attack surface. Defenses:
+
+- **Rule-pack SHA pinning** via [references/rules/manifest.yaml](./references/rules/manifest.yaml).
+  `run-scan.sh` validates rule-file SHAs at every run; tampering → REVIEW with
+  reason `rule pack tampered`.
+- **OSV untrusted-input handling**: schema validation, body-size cap, ecosystem
+  allowlist (unknown ecosystem → REVIEW, never LOW-RISK), network-failure →
+  REVIEW.
+- **Fail-loud self-test**:
+  [scripts/run-self-test.sh](./scripts/run-self-test.sh) runs the scanner over
+  known-malicious + known-clean fixtures; any false-negative or false-positive on
+  the seed set fails the test loudly. Wired into CI per
+  `.github/workflows/skill-security-scan-corpus.yml`.
+
+## PII redaction
+
+Findings persisted to `.scan-meta.json` and override artifacts run through
+email/IP/IBAN-shape redaction before write (per gdpr-gate `GDPR-DataMin-1`).
+Operator-facing stdout is unredacted; persisted forms are redacted. Sentry mirrors
+of scanner errors use `reportSilentFallback(err, { feature: 'skill-security-scan',
+extra: { ...redacted } })`.
+
+## Integrations
+
+- `skill-creator` Step 5: post-validation scan before packaging.
+- `soleur:engineering:discovery:agent-finder` §4b.5: cooperative-fast-path scan post-fetch / pre-write.
+- PreToolUse hook on `Write` to `.claude/skills/**` and `.claude/agents/**`:
+  load-bearing block-on-HIGH-RISK gate at the tool layer.
+- Lefthook commit-time advisory: belt-and-suspenders for IDE / CLI commit paths.
+- CI pre-merge required check + post-merge audit: defense-in-depth against
+  tool-layer bypass.
+
+See [references/override-mechanism.md](./references/override-mechanism.md) for
+operator workflows.

package/skills/skill-security-scan/references/disclaimer.md

@@ -0,0 +1,21 @@
+# Mandatory advisory disclaimer (CLO Decision 1)
+
+This text is appended verbatim by `run-scan.sh` to every scanner output. It is
+the SINGLE point of insertion (per plan Sharp Edge #9). Per-script outputs do
+NOT include the disclaimer; the aggregator does.
+
+```
+---
+Advisory static analysis only. LOW-RISK does not constitute a security audit,
+certification, or warranty of safety. The skill executes in your environment
+under your account; you remain responsible for review.
+
+Scanner version: <version>  Rule pack: <sha-prefix>  Scanned: <ISO-8601>
+```
+
+The token `<version>` is replaced with the value of `scanner_version` from the
+manifest. `<sha-prefix>` is the first 12 hex chars of the rule-pack manifest
+SHA. `<ISO-8601>` is the scan timestamp in `date -u +"%Y-%m-%dT%H:%M:%SZ"`.
+
+The disclaimer is required regardless of verdict — including LOW-RISK — so
+that downstream consumers cannot infer "no warning" as a positive certification.

package/skills/skill-security-scan/references/first-party-allowlist.yaml

@@ -0,0 +1,38 @@
+# First-party allowlist for category 5 (telemetry-surface).
+#
+# Matched on URL host segment after parsing (NOT raw substring).
+# Adversarial `https://attacker.com/redirect?ref=soleur.ai` MUST trip detection
+# (host = attacker.com, NOT in this list). See R14 / Sharp Edge #23.
+#
+# Hosts use domain-suffix matching: a literal entry `soleur.ai` matches
+# `soleur.ai` and any subdomain `*.soleur.ai`. The wildcard form `*.soleur.ai`
+# is equivalent and provided for documentation clarity.
+
+domains:
+  - soleur.ai
+  - "*.soleur.ai"
+  - soleur.dev
+  - "*.soleur.dev"
+  - github.com           # Soleur is hosted on github.com/jikig-ai
+  - github.io            # for github pages docs
+  - jikigai.com
+  - "*.jikigai.com"
+  - anthropic.com        # Claude Code surface
+  - "*.anthropic.com"
+  - claude.com           # Claude Code surface
+  - "*.claude.com"
+
+# Approved utm_campaign IDs.  utm-tagged links to non-allowlisted campaigns
+# emit REVIEW (never HIGH-RISK on their own).
+utm_campaigns:
+  - soleur-launch
+  - soleur-blog
+  - soleur-docs
+  - soleur-discord
+  - soleur-github
+  - soleur-x
+  - soleur-bluesky
+  - soleur-linkedin
+  - soleur-hn
+  - soleur-indiehackers
+  - soleur-reddit

package/skills/skill-security-scan/references/override-artifact-schema.json

@@ -0,0 +1,68 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://soleur.ai/schemas/skill-security-scan/override-artifact.json",
+  "title": "Skill Security Scan Override Artifact",
+  "description": "Frontmatter schema for knowledge-base/engineering/security/skill-overrides/YYYY-MM-DD-<slug>.md. The artifact alone is the audit-trail; no git trailer is involved (squash-merge-safe).",
+  "type": "object",
+  "required": [
+    "skill",
+    "source",
+    "findings_json",
+    "justification",
+    "approver",
+    "scanner_version",
+    "rule_pack_sha256",
+    "verdict",
+    "timestamp"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "skill": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*$",
+      "description": "Skill slug. Lowercase + hyphens only; rejects regex meta-chars to prevent bash interpolation hazards in filename matching."
+    },
+    "source": {
+      "type": "string",
+      "minLength": 1,
+      "description": "URL or 'skill-creator' (where the skill content originated)."
+    },
+    "findings_json": {
+      "description": "Inline JSON copy of the .scan-meta.json findings_summary at override time, or a path string referencing the .scan-meta.json file.",
+      "oneOf": [
+        { "type": "string" },
+        { "type": "object" }
+      ]
+    },
+    "justification": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Free-text rationale explaining why the operator accepts the HIGH-RISK or REVIEW verdict."
+    },
+    "approver": {
+      "type": "string",
+      "format": "email",
+      "description": "git config user.email of the operator approving the override."
+    },
+    "scanner_version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$",
+      "description": "Semver of the scanner at override time."
+    },
+    "rule_pack_sha256": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{8,64}$",
+      "description": "SHA-256 (or sha-prefix ≥8 chars) of the rule-pack manifest at override time. Mismatch with current manifest indicates stale findings; operator must re-run scanner and update the artifact."
+    },
+    "verdict": {
+      "type": "string",
+      "enum": ["HIGH-RISK", "REVIEW"],
+      "description": "Verdict the operator is overriding. LOW-RISK never requires an override."
+    },
+    "timestamp": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO-8601 timestamp of override creation."
+    }
+  }
+}

package/skills/skill-security-scan/references/override-mechanism.md

@@ -0,0 +1,171 @@
+# skill-security-scan override mechanism
+
+When the scanner returns `HIGH-RISK` or `REVIEW` and the operator judges the
+finding to be a false-positive or accepted-risk, override by committing a
+**structured artifact** under `knowledge-base/engineering/security/skill-overrides/`.
+
+The artifact alone is the audit-trail. **No git trailer is involved** — the
+`Skill-Security-Ack:` trailer was dropped during plan review (DHH + simplicity
+HIGH-confidence cut, Kieran P0-2). This eliminates squash-merge invariant
+concerns: the artifact appears in `git diff main...HEAD --diff-filter=A`
+regardless of merge strategy.
+
+## Artifact location and naming
+
+```
+knowledge-base/engineering/security/skill-overrides/YYYY-MM-DD-<slug>.md
+```
+
+- `YYYY-MM-DD` — ISO-8601 date the override was created.
+- `<slug>` — skill slug, lowercase + hyphens only, regex `^[a-z][a-z0-9-]*$`.
+  Capital letters and regex meta-characters are rejected (prevents bash
+  interpolation hazards in the filename match).
+
+## Artifact frontmatter schema
+
+Validated against [override-artifact-schema.json](./override-artifact-schema.json).
+
+```yaml
+---
+skill: <slug>
+source: <url-or-skill-creator>
+findings_json: <inline-JSON-or-path-to-.scan-meta.json>
+justification: <free-text explaining why operator accepts the verdict>
+approver: <git config user.email>
+scanner_version: 0.1.0
+rule_pack_sha256: <prefix ≥ 8 chars from .scan-meta.json>
+verdict: HIGH-RISK | REVIEW
+timestamp: <ISO-8601>
+---
+
+# Override: <skill-slug>
+
+## Findings (verdict: <verdict>)
+<path to .scan-meta.json — see "PII safety" below>
+
+## Justification
+<free-text rationale>
+```
+
+## Operator workflow
+
+1. Operator hits HIGH-RISK on a third-party skill they want to install.
+2. Scanner emits findings + suggested override-artifact path + the runtime
+   path to the redacted `.scan-meta.json` (printed on stdout).
+3. Operator inspects the findings, decides override is appropriate.
+4. Operator creates the artifact (manual or via `skill-creator` Step 5):
+
+   ```bash
+   cat > knowledge-base/engineering/security/skill-overrides/$(date -u +%Y-%m-%d)-<slug>.md <<EOF
+   ---
+   skill: <slug>
+   source: <where-the-skill-came-from>
+   findings_json: <path-to-redacted-.scan-meta.json>
+   justification: <rationale>
+   approver: $(git config user.email)
+   scanner_version: 0.1.0
+   rule_pack_sha256: <prefix-from-scan-meta>
+   verdict: HIGH-RISK
+   timestamp: $(date -u +%Y-%m-%dT%H:%M:%SZ)
+   ---
+
+   # Override: <slug>
+
+   ## Findings
+   <path to .scan-meta.json>
+
+   ## Justification
+   <text>
+   EOF
+   ```
+
+5. Operator commits the artifact in the same PR as the skill install.
+6. CI pre-merge gate (job `skill-security-scan` in `pr-quality-guards.yml`) and the PreToolUse
+   hook on Write run `parse-override.sh` to validate. Valid artifact → install
+   accepted.
+
+### PII safety — findings provenance
+
+The `findings_json` field MUST carry **redacted bytes from the persisted
+`.scan-meta.json`** — never an inline copy typed from scanner stdout. Reason:
+scanner stdout (which the operator sees during review) is intentionally
+unredacted for in-terminal inspection; the persisted `.scan-meta.json` runs
+through `redact_pii()` (email, IPv4, IBAN, JWT, Anthropic/OpenAI keys, GitHub
+PAT/OAuth, GitLab PAT, Doppler tokens, Slack tokens, AWS keys). Copy-pasting
+from terminal scrollback lands raw PII / secrets in a permanent git artifact
+retained "for repository lifetime" per Art. 32 evidence retention. The
+path form is the default because it cannot be mis-pasted.
+
+`parse-override.sh` enforces this: artifacts whose body contains a raw email
+pattern outside the `approver:` field are rejected with `invalid_schema`.
+
+The path form is valid only inside the retention window: the scanner's startup
+reap removes `skill-security-scan-*` dirs older than `SKILL_SCAN_META_REAP_MIN`
+minutes (default 10080 = 7 days), and `$XDG_RUNTIME_DIR` is cleared on logout
+regardless (#6789, #6760). For a reference that must outlive the window, embed
+the findings inline — the schema's `oneOf` admits an object form — copied from
+the **redacted `.scan-meta.json`**, never from scanner stdout (the mandate
+above is about where the bytes come from, not the YAML shape). Two mechanics
+matter: the presence check (#10167) counts `findings_json` present iff the
+`findings_json:` key line carries non-whitespace, non-null content OR a
+following *indented* line does before the block ends — so both the inline
+`findings_json: {…}` form and the block mapping (`findings_json:` then
+indented `key: value` lines) are accepted, while `findings_json:` bare,
+whitespace-only, `null`/`~`, a same-line comment (`findings_json: # …`,
+reads as null), or `findings_json:{…}` (no separation space — YAML reads that
+as a scalar, not a mapping) still report missing. And the
+source bytes must still be the redacted file.
+
+## Multiple overrides per PR
+
+A single PR may install multiple skills. Each skill's override is one artifact
+file. `parse-override.sh` enumerates all matched artifacts independently;
+there is no shared state.
+
+## Stale findings
+
+If the rule pack updates between override creation and PR merge, the artifact's
+`rule_pack_sha256` will no longer match the current `manifest.yaml` SHA.
+`parse-override.sh` reports this as `stale_findings` and the CI gate fails with
+an instruction to re-run the scan and update the artifact.
+
+## Retention
+
+Override artifacts are retained for the **repository lifetime** as Article 32
+evidence (GDPR Art. 6(1)(c) lawful basis: legal obligation; Art. 6(1)(f):
+legitimate interest in maintaining audit trail). Future operators must NOT
+bulk-delete them. PII in the embedded `findings_json` is redacted at scan-time
+per `GDPR-DataMin-1` (email/IPv4/IBAN-shape).
+
+## Defense-in-depth
+
+The override mechanism is the LAST gate. Earlier gates:
+
+1. **PreToolUse hook on Write** (`.claude/hooks/skill-security-scan-write.sh`)
+   — load-bearing tool-layer block on `HIGH-RISK without override artifact`.
+2. **Cooperative-fast-path in soleur:engineering:discovery:agent-finder §4b.5** — surfaces findings to
+   operator before the Write attempt.
+3. **Cooperative-fast-path in skill-creator Step 5** — same as above for
+   scaffold workflows.
+4. **Lefthook commit-time advisory** (`.claude/hooks/skill-security-scan.sh`)
+   — belt-and-suspenders for IDE / manual `git commit` paths.
+5. **CI pre-merge required check** (job `skill-security-scan` in `pr-quality-guards.yml`) —
+   Layer C: blocks merge if any new HIGH-RISK skill install lacks a valid
+   override artifact.
+6. **CI post-merge audit** (`skill-security-scan-postmerge.yml`) — Layer D:
+   re-validates on push to main. Auto-files `compliance/critical` issue if
+   pre-merge gate was bypassed via admin merge or force-push.
+7. **Branch protection** — `main` requires the `skill-security-scan PR gate` check (job `skill-security-scan` in `pr-quality-guards.yml`)
+   pre-merge status check. Bypassing requires explicit admin action that
+   auto-files a compliance issue.
+
+## Future extensions (NOT implemented in v1)
+
+The original brainstorm and CTO Decision 12 contemplated a `soleur:plan`-aware
+skip-and-warn mode for the scanner. Phase 6 of the plan removed this for v1
+because `soleur:plan` does not scaffold or fetch skills — those code paths
+live in `skill-creator` and `soleur:engineering:discovery:agent-finder` only. If a future plan-time
+scaffolding workflow emerges, re-evaluate this design with a tracking issue.
+The `SKILL_SECURITY_SCAN_PLAN_MODE` env-flag idea is preserved here as
+documented future-extension guidance only; it is not implemented in this v1
+release.