@chrono-meta/fh-gate 1.1.0 → 1.2.0

package/plugins/fh-meta/skills/plugin-recommender/SKILL_detail.md

@@ -0,0 +1,220 @@
+---
+name: plugin-recommender-detail
+description: Detail reference for plugin-recommender — bash discovery scripts, install procedures, recommendation examples. Load when executing specific steps.
+load: on-demand
+---
+
+# plugin-recommender — Detail Reference
+
+## §Discovery-Bash
+
+### Step 0 — GitHub Auth Check Commands
+
+**Check command (run before Step 2 search):**
+```bash
+gh auth status
+```
+
+**Internal GHE unauthenticated — PAT setup:**
+```bash
+# 1. Generate PAT at https://<your-ghe-url>/settings/tokens
+#    Scopes: repo, read:org (minimum)
+
+# 2. Save to gh CLI
+gh auth login --hostname <your-ghe-url>
+# Prompt: Select HTTPS → Paste an authentication token → enter token
+
+# 3. Verify
+GH_HOST=<your-ghe-url> gh api /user --jq '.login'
+```
+
+**External GitHub unauthenticated — PAT setup:**
+```bash
+# 1. Generate PAT at https://github.com/settings/tokens
+#    Scopes: repo, read:org
+
+# 2. Save to gh CLI
+gh auth login --hostname github.com
+# (or default: gh auth login)
+```
+
+**Search call host branching:**
+```bash
+# Internal GHE search
+GH_HOST=<your-ghe-url> gh api ...
+# or
+gh search repos --owner <your-ghe-org> --hostname <your-ghe-url> [keywords]
+
+# External GitHub search
+gh search repos [keywords]  # default host
+```
+
+**External user Step 0 skip branch:**
+```bash
+# External user Step 0 replacement (no internal GHE access)
+gh auth status  # default host (github.com) only
+# Authenticated → proceed to Step 1 immediately
+# Unauthenticated → guide github.com PAT generation above
+```
+
+**Claude Code marketplace search:**
+```bash
+claude mcp search [capability-keyword]
+```
+
+**Codex marketplace search:**
+```bash
+npx @openai/codex list-agents [capability-keyword]
+```
+
+**npm ecosystem search (scoped packages):**
+```bash
+npm search @chrono-meta [keyword]
+npm search @anthropic [keyword]
+```
+
+---
+
+## §Install-Procedure
+
+### Step 5 — Full Install and Configuration Details
+
+#### 5-0. Pre-install Duplicate Detection
+
+```bash
+claude plugin list
+```
+
+Three things to verify:
+- **Manual install status**: If target plugin name exists in output → reinstall unnecessary
+- **Repo-level activation**: If plugin is in `.claude/settings.json` `enabledPlugins` → already active
+- **Same-name different-function conflict**: Same name but different origin/function → conflict handling below
+
+**Same-name Conflict Handling procedure:**
+
+1. Compare existing skill description vs recommended skill description
+2. **Feature match** → report "Equivalent feature already installed" + skip reinstall
+3. **Feature mismatch** → issue conflict warning:
+   ```
+   ⚠️ Name conflict: `<skill-name>` is already installed but has different functionality.
+
+   Currently installed: <summary of existing skill description>
+   Recommendation target: <summary of new skill description>
+
+   Options:
+   A. Keep existing (skip install)
+   B. Install with namespace qualifier — e.g., `fh-<skill-name>`
+   C. Remove existing and install new (⚠️ existing skill will be removed)
+   ```
+4. If user selects Option B: guide adding prefix to `name` field in plugin.json + present modification path
+
+If either duplicate condition met → skip install → report "Already active" → proceed to Step 5-3 config only.
+
+#### 5-1 through 5-3. Install Steps
+
+1. Confirm intent: "Would you like to install the `[plugin-name]` plugin?"
+2. On agreement:
+   ```bash
+   claude plugin marketplace add [plugin-name]
+   claude plugin install [plugin-name]
+   ```
+3. Post-install initial configuration guidance:
+   - **API token input**: Guide token generation path for external service APIs (Jira/Confluence/Slack — specify each service's token page URL + env var or plugin config storage location)
+   - **MCP connection**: If plugin uses MCP server, guide auto-update of `.mcp.json` or `claude mcp add` command
+   - **Verify**: `claude plugin list` or `/plugin` UI + recommend first-call dry-run
+
+#### 5-B. External Asset Migration Path (when non-plugin asset is found)
+
+Activation condition: Step 3 found a promising external asset lacking `plugin.json` or `claude plugin install` support — install not possible but pattern has value.
+
+**5-B-1. Migration Suitability Assessment (quick 3-criteria check):**
+
+| Criteria | OK | NG |
+|---|---|---|
+| **Single purpose** | Clearly performs 1 task | Complex framework/SDK level |
+| **Dependency complexity** | Standard CLI tools only (bash, gh, grep etc.) | Requires custom runtime/database |
+| **FH gap coverage** | No similar skill currently in FH | Existing skill covers 95%+ |
+
+All 3 OK → recommend migration. Any NG → report "Recommend referencing rather than installing" then guide Step 2 [Priority 2.5] contribution path.
+
+**5-B-2. SKILL.md Conversion Template:**
+
+```markdown
+---
+name: {1-3 words for the external asset's core action}
+description: {one sentence, plain text only — first line is the core spec}
+user-invocable: true
+allowed-tools: ["Read", "Bash", "Grep"]  # only actually needed tools
+model: sonnet
+---
+
+# {name} — {one-line description}
+
+## Activation Triggers
+- When user says "{core action}"
+
+## Execution Steps
+
+### Step 1. ...
+### Step 2. ...
+```
+
+Conversion checklist:
+- [ ] description first line = core spec (no marketing language)
+- [ ] allowed-tools = only actually called tools (no over-declaration)
+- [ ] External asset original URL → explicitly stated in `## Source` section (license check mandatory)
+
+**5-B-3. Migration Location Guidance:**
+
+| Purpose | Path | Notes |
+|---|---|---|
+| FH official skill (org-wide distribution) | `plugins/fh-meta/skills/{name}/SKILL.md` | PR mandatory — must pass team review |
+| Local experiment (own environment only) | `.claude/rules/{name}.md` | No plugin install needed |
+| Mode D standalone deployment | `.claude/agents/{name}.md` | Only when operating as agent form |
+
+> FH official skill inclusion criteria: recommend PR after confirming 2+ actual uses (simplification guard — immediate inclusion after 1 experiment is prohibited).
+
+---
+
+## §Examples
+
+### Recommendation Table — Output Example
+
+Full format with Tier + Platform columns:
+
+| Rank | Plugin Name | Tier | Platform | Recommendation Reason | Key Features | Synergy Effect |
+| :--- | :--- | :--- | :--- | :--- | :--- | :--- |
+| **1** | `jira-automator` | Tier 1 | CC marketplace | Fully satisfies Jira ticket create/modify/query. Production usage evidence (5k+ installs). | Ticket creation, status change, comment addition | ★★★ (auto-links docs when used with `confluence-linker`) |
+| **2** | `agile-sprint-board` | Tier 2 | GHE | Specialized for Jira-integrated sprint board visualization. Marketplace-listed, no benchmark data. | Sprint visualization, burndown chart | ★ (standalone use) |
+| **3** | `issue-tracker-cli` | Tier 3 | GitHub only | Repo-only tool, no marketplace listing. Covers edge case not in Tier 1/2 options. | Bulk status updates via CLI | ★ (standalone use) |
+
+### Persona Discovery (sim-conductor chain) — Return Example
+
+```
+plugin-recommender result to sim-conductor:
+  Searched: CC marketplace, Codex marketplace, FH native
+  Found:
+    - deep-insight (Tier 1, CC marketplace) — adversarial reviewer persona
+    - persona-devil-advocate (Tier 1, FH native, already installed)
+  Installed: deep-insight
+  Available personas: [devil-advocate, innovator, deep-insight, conservative-critic]
+  → Return control to sim-conductor
+```
+
+### Quality Tier Assignment — Walk-through Example
+
+Candidate: `@anthropic/code-review-agent`
+- Published benchmark: accuracy 94% on HumanEval — **High** signal present
+- GitHub stars: 2,400 — **Medium** signal present
+- CC marketplace listing confirmed — **Medium** signal present
+- Not FH-reviewed — no High signal from community
+
+Result: 1 High + 2 Medium → **Tier 1**
+
+Candidate: `random-org/bash-linter-plugin`
+- No benchmark data
+- GitHub stars: 45 (below 100 threshold)
+- Not on any marketplace
+- Unknown author
+
+Result: no signals → **Tier 3** (source-available, GitHub only)

package/plugins/fh-meta/skills/prompt-regression/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: prompt-regression
+description: Detects harness regressions by running standard prompt probes after rule/skill changes and comparing outputs against saved baselines. Triggers on "prompt regression", "did my changes break anything", "regression check", "test harness changes".
+user-invocable: true
+allowed-tools: ["Read", "Bash", "Glob", "Grep"]
+model: sonnet
+complexity_routing:
+  base: sonnet
+  high: opus
+  escalate_when:
+    - full_suite
+    - cross_skill_impact
+---
+
+# prompt-regression — Harness Regression Detection
+
+After CLAUDE.md edits, rule changes, or new skill additions, harness behavior can silently regress. This skill runs a lightweight probe suite against the changed assets and compares outputs against saved baselines to surface regressions before they reach production.
+
+> **Scope distinction**
+> - harness-doctor: structural completeness (files, links, drift)
+> - prompt-regression: **behavioral correctness** — did the change alter expected AI response patterns?
+
+---
+
+## Triggers
+
+- `/prompt-regression`
+- "prompt regression", "regression check", "regression test"
+- "did my rule change break anything", "test harness changes", "verify harness behavior", "make sure my edit didn't change behavior"
+- After significant CLAUDE.md edits or new skill commits
+
+---
+
+## Execution Steps
+
+### Step 1. Identify Changed Assets
+
+```bash
+# What changed since last commit (or last N commits)
+git diff HEAD~1 --name-only -- CLAUDE.md .claude/ plugins/
+```
+
+Classify each changed file:
+- `CLAUDE.md` → **core behavior** (high impact)
+- `.claude/rules/*.md` → **rule layer** (medium impact)
+- `plugins/*/skills/*/SKILL.md` → **skill behavior** (scoped impact)
+- `plugins/*/skills/*/SKILL.md` (trigger phrases changed) → **trigger routing** (high impact)
+
+If no changes detected: report "No harness changes since last commit — regression check skipped."
+
+---
+
+### Step 2. Load Probe Suite
+
+Check for custom probes:
+```bash
+ls .claude/regression/probes.md 2>/dev/null || echo "NO_CUSTOM_PROBES"
+```
+
+**If custom probes exist**: load and use them.
+
+**If no custom probes**: use the default probe matrix below.
+
+#### Default Probe Matrix
+
+| Probe ID | Input Pattern | Expected Behavior | Scope |
+|---|---|---|---|
+| `P-GREET-01` | `hi` / `hello` | Active onboarding protocol triggered | CLAUDE.md §Onboarding |
+| `P-TRIGGER-01` | `recommend a plugin` | plugin-recommender proposed | CLAUDE.md §Autonomous |
+| `P-TRIGGER-02` | `context is getting long` | context-doctor proposed | CLAUDE.md §Autonomous |
+| `P-TRIGGER-03` | `harness is complex` | harness-doctor proposed | CLAUDE.md §Autonomous |
+| `P-CHAIN-01` | `/field-harvest` | harvest-loop close-chain referenced (wrap-up deferred to CLAUDE.md session-close chain — field-harvest has no inline sim-conductor gate) | field-harvest SKILL.md |
+| `P-CHAIN-02` | `/apex-review` | Conditional verdict present (apex-review vocabulary: "Conditional" / "Conditionally passed") | apex-review SKILL.md |
+| `P-GATE-01` | new skill commit | New Skill Pre-Commit Gate (5 items) invoked | CLAUDE.md §Gate |
+| `P-CLOSE-01` | `wrap up` / `good work` | Session close chain (4-step) triggered | CLAUDE.md §Wrap-up |
+
+---
+
+### Step 3. Map Changes → Affected Probes
+
+| Changed File | Affected Probes |
+|---|---|
+| `CLAUDE.md` §Onboarding | P-GREET-01 |
+| `CLAUDE.md` §Autonomous Initiative | P-TRIGGER-* |
+| `CLAUDE.md` §Wrap-up | P-CLOSE-01 |
+| `CLAUDE.md` §New Skill Gate | P-GATE-01 |
+| `plugins/fh-meta/skills/*/SKILL.md` | P-CHAIN-* matching skill |
+
+If change scope is `CLAUDE.md` core (10+ lines changed): run **full suite** (all probes).
+
+---
+
+### Step 4. Run Affected Probes
+
+For each affected probe, evaluate:
+
+**4-a. Trigger routing check** — Does the trigger phrase still map to the expected skill/behavior?
+- Read the changed file
+- Locate trigger section
+- Confirm the probe's input pattern still appears in the trigger list
+
+**4-b. Chain integrity check** — Are mandatory chains still present?
+- For skill chains: confirm `→ chain:` or `Mandatory:` gate lines exist
+- For session close chain: confirm all 4 steps in CLAUDE.md §Wrap-up
+
+**4-c. Gate presence check** — Are gate conditions still enforced?
+- Pre-commit gate: confirm all 5 items present in CLAUDE.md
+- Conditional-pass gate: confirm `CONDITIONAL_PASS` logic in affected SKILL.md
+
+Output per probe:
+```
+[PASS] P-TRIGGER-01 — plugin-recommender trigger phrase found in CLAUDE.md
+[FAIL] P-CHAIN-01 — field-harvest SKILL.md no longer references the harvest-loop close chain after edit
+[SKIP] P-GREET-01 — §Onboarding not in changed files
+```
+
+---
+
+### Step 5. Regression Report
+
+```
+## Prompt-Regression Report — YYYY-MM-DD
+
+### Changed Assets
+- CLAUDE.md (§Autonomous Initiative — 3 trigger phrases modified)
+- plugins/fh-meta/skills/field-harvest/SKILL.md
+
+### Probes Run: 4  |  Pass: 3  |  Fail: 1  |  Skip: 4
+
+### FAIL Details
+| Probe | Location | Finding | Fix |
+|---|---|---|---|
+| P-CHAIN-01 | field-harvest SKILL.md | harvest-loop close-chain reference removed by edit | Restore the harvest-loop chain reference |
+
+### Verdict
+⚠️ REGRESSION DETECTED — 1 probe failed. Fix required before merge.
+```
+
+If all probes pass:
+```
+✅ NO REGRESSION — All N probes passed. Safe to merge.
+```
+
+---
+
+### Step 6. Baseline Update (on explicit user approval)
+
+After a deliberate behavior change (not a regression — an intentional improvement), update the baseline:
+
+```bash
+# Baseline stored as markdown in .claude/regression/
+mkdir -p .claude/regression
+# Write updated probe expectations
+```
+
+Prompt user: *"Probe P-CHAIN-01 now expects the new gate format. Update baseline? (y/n)"*
+
+Only update on explicit `y` — never auto-update.
+
+---
+
+## Done When
+
+- All affected probes are evaluated (PASS / FAIL / SKIP)
+- Regression report is output with clear PASS/FAIL verdict
+- If FAIL: specific file + line fix is recommended
+- Baseline updated only on explicit user approval
+
+---
+
+## Chains
+
+**Upstream** (runs before this skill):
+- Automatically triggered after significant harness commits (Step 1 detects via git diff)
+
+**Downstream** (runs after FAIL verdict):
+- → `harness-doctor` for structural fixes if L1/L2 issues found
+- → `verify-bidirectional` to confirm fix resolved the regression

package/plugins/fh-meta/skills/public-surface-audit/SKILL.md

@@ -0,0 +1,224 @@
+---
+name: public-surface-audit
+description: >-
+  Scans git-tracked (public) files for operator-private tokens that should live only in gitignored files — real usernames, absolute home paths, companion-store names, company asset names. Reports file:line + matched token + severity, so a public/private split stays clean before publish. Triggered by "public surface audit", "did I leak anything", "check tracked files for private tokens", "private token scan", "public-surface-audit".
+user-invocable: true
+allowed-tools: ["Read", "Bash", "Grep", "Glob"]
+model: sonnet
+category: Composability Gate
+---
+
+# public-surface-audit — Operator-Private Token Leak Scan
+
+Scans the git-tracked file set (the public surface) for operator-private tokens that were supposed
+to stay in gitignored files (e.g. `CLAUDE.local.md`, companion store). After a public/private split,
+a front-door fix is not enough — a leaked username or absolute home path anywhere in the tracked set
+breaks the "public repo = model-agnostic methodology only" invariant.
+
+> While `marketplace-gate` Check 5 answers "is this repo broadly safe to publish?" (API keys, internal
+> domains, license), `public-surface-audit` answers a narrower question: "did any operator-private
+> token survive the public/private split into a tracked file?" It scans `git ls-files` only — gitignored
+> files like `CLAUDE.local.md` are intentionally out of scope (they are the *correct* home for these tokens).
+
+## Triggers
+
+- `/public-surface-audit`
+- `/public-surface-audit --target <repo path>`
+- "Did I leak anything into the public repo?", "public surface audit", "private token scan"
+- "Check tracked files for private tokens", "is my public/private split clean?"
+- "Did any operator-private token survive into a tracked file?", "scan before publish"
+
+---
+
+## Scope — Tracked Files Only
+
+This skill scans **only `git ls-files`** (committed/staged tracked files). Gitignored files are
+deliberately excluded — `CLAUDE.local.md`, the companion store, and local session data are the
+*correct* home for operator-private tokens, so finding them there is not a leak.
+
+```bash
+REPO_PATH="${ARGUMENTS#--target }"
+REPO_PATH="${REPO_PATH:-$(pwd)}"
+git -C "$REPO_PATH" rev-parse --is-inside-work-tree >/dev/null 2>&1 \
+  || { echo "Not a git repo — public-surface-audit scans git-tracked files only. Aborting."; exit 1; }
+echo "Target: $REPO_PATH"
+git -C "$REPO_PATH" ls-files | wc -l | xargs echo "Tracked files:"
+```
+
+---
+
+## Step 1. Pattern List (configurable)
+
+The patterns **are themselves operator-private** — your real username and employer name must not be
+hardcoded *here*, on the public surface, or this skill would leak exactly what it hunts. So the literal
+values live in a **gitignored source you supply** (`.claude/rules/.public-surface-patterns`, or a
+section of `CLAUDE.local.md`) — one `severity<TAB>regex` per line. This SKILL.md carries only
+placeholders; the scan reads the gitignored file, never literals from this table. The skill dogfoods
+its own rule.
+
+| # | Token class | Severity | Placeholder (real value goes in the gitignored source) | Why private |
+|:-:|---|:-:|---|---|
+| 1 | Real username | HIGH | `<your-unix-username>` | Personal identity — must not appear on public surface |
+| 2 | Company / employer asset name | HIGH | `<company-asset>` (alternation OK) | Company-confidential, leak-forbidden |
+| 3 | Operator absolute home path | MED | `/Users/[a-z0-9_-]+/` (generic — carries no literal name) | Machine-bound, leaks username + local layout |
+| 4 | Companion-store name | LOW | `<companion-store-name>` | Private companion store — methodology should not name it |
+| 5 | Operator-private script / handoff name | LOW | `<private-script>`, `<private-dir>/` | Operator-specific wiring, belongs in `CLAUDE.local.md` |
+
+**Severity meaning**:
+- **HIGH** — real name or company asset. A leak is a confidentiality / identity exposure. Block publish.
+- **MED** — absolute home path. Leaks username + local filesystem layout; also a portability bug.
+- **LOW** — companion-store / private-wiring name. Methodology should be model-agnostic; naming a private
+  store is drift, not a confidentiality breach.
+
+> **Setup**: put your real values in the gitignored pattern source (one `severity<TAB>regex` per line);
+> the scan reads that file, never literals from this SKILL.md. If the source is **absent**, the scan
+> reports **NOT CONFIGURED** — *not* CLEAN. A missing pattern file must never masquerade as a clean bill
+> of health (that would be a silent failure: "nothing scanned" misread as "nothing leaked"). To declare
+> "I genuinely have no private tokens", create the file **empty** — an empty file is an explicit CLEAN,
+> an absent file is unconfigured.
+
+---
+
+## Step 2. Allowlist (legitimate references)
+
+Some tracked files legitimately reference otherwise-private tokens — the scan must not flag these as
+leaks. Maintain an allowlist of `file path :: token` pairs. A match is suppressed only when **both**
+the file and the token are on the allowlist row.
+
+| Tracked file | Allowed tokens | Reason |
+|---|---|---|
+| `.gitignore` | companion-store name, sync-script name | Must name what it ignores |
+| your sync script (e.g. `scripts/<sync-script>`) | companion-store name, operator-dir names, home path | The sync script's whole job is the companion store |
+| an install-template rules file | home path, companion-store name | Install template — the install path is its content |
+| a doc describing the companion-store *pattern* | the `*-be` pattern (no literal store name) | Documents the pattern generically |
+
+**Allowlist rule**: a hit on file F matching token T is **suppressed** iff a row exists with file == F
+and T in that row's allowed tokens. Everything else is reported. Keep the allowlist tight — when in
+doubt, report and let the user confirm. Genuinely model-agnostic mentions (the `*-be` companion
+*pattern* without the literal store name) should not require allowlisting because they do not match a
+literal private token.
+
+---
+
+## Step 3. Scan
+
+For each pattern in Step 1, grep the tracked set, then drop allowlisted hits.
+
+```bash
+cd "$REPO_PATH" || exit 1
+# Build the tracked-file list once.
+git ls-files > /tmp/_psa_tracked.txt
+
+# Load your real patterns from the gitignored source (one "severity<TAB>regex" per line).
+PATTERN_SRC="${PSA_PATTERNS:-.claude/rules/.public-surface-patterns}"
+# Absent file ≠ CLEAN. An absent file is unconfigured (silent-failure risk); an EMPTY file is an
+# explicit "no tokens to protect" → CLEAN. Distinguish the two.
+[ -e "$PATTERN_SRC" ] || { echo "⚪ NOT CONFIGURED: no pattern source at $PATTERN_SRC. Create it (empty = explicit CLEAN) before trusting any verdict. Not scanning."; exit 2; }
+
+# One grep pass per pattern row; the regex comes from the file, never hardcoded here.
+while IFS=$'\t' read -r severity regex; do
+  [ -z "$regex" ] && continue
+  grep -nIE "$regex" $(cat /tmp/_psa_tracked.txt) 2>/dev/null | sed "s/^/[$severity] /"
+done < "$PATTERN_SRC"
+```
+
+For each pattern, run `grep -nIE "<regex>" $(git ls-files)`:
+- `-n` → line numbers (required for `file:line` output)
+- `-I` → skip binary files
+- `-E` → extended regex (alternation in the pattern table)
+
+Then remove any hit whose `file` + matched `token` is on the Step 2 allowlist. Do this for **every**
+pattern row before producing the report — do not stop at the first HIT.
+
+**Binary / generated carve-out**: `-I` already skips binaries. Additionally note (do not auto-suppress)
+hits inside generated artifacts (e.g. `paper/*.html` exported from a private source) — these are real
+leaks on the public surface and must be reported, but the fix is "regenerate from a sanitized source",
+not "edit the HTML by hand". Flag them with a `(generated artifact)` note.
+
+---
+
+## Step 4. Report
+
+```
+public-surface-audit — Operator-Private Token Scan
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  Target: {REPO_PATH}   |   Tracked files scanned: {N}
+
+  🔴 HIGH  ({count})
+    {file}:{line}  →  {matched token}   [class: username | company asset]
+  🟠 MED   ({count})
+    {file}:{line}  →  {matched token}   [class: absolute home path]
+  🟡 LOW   ({count})
+    {file}:{line}  →  {matched token}   [class: companion-store | private wiring]
+
+  Allowlist-suppressed: {count} hit(s) (legitimate references — not leaks)
+
+  Verdict:
+    ⚪ NOT CONFIGURED — pattern source absent (nothing scanned — NOT a clean result; set up first)
+    🟢 CLEAN        — pattern source present (incl. empty), 0 HIGH + 0 MED + 0 LOW (after allowlist)
+    🟡 REVIEW       — 0 HIGH + 0 MED, LOW-only (drift, not a breach)
+    🔴 LEAK         — 1+ HIGH or 1+ MED (block publish / fix before commit)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Per HIGH/MED hit, append a one-line prescription:
+- **HIGH (username/company)** — move the line to `CLAUDE.local.md` (or regenerate the artifact from a
+  sanitized source); never edit-in-place if it is a generated file.
+- **MED (absolute path)** — replace with a relative path, a `~`-anchored path, or a `{project}`
+  placeholder; absolute home paths are also a portability bug for external clones.
+- **LOW (companion-store/wiring)** — rephrase to the model-agnostic *pattern* (e.g. "a private companion
+  store" / "the `*-be` companion pattern") instead of the literal name, unless the file is the
+  `.gitignore` / sync script that must name it (allowlist those).
+
+**Simplification guard**: 🟢 CLEAN → collapse the report to one line: "public surface clean — 0 private
+tokens in {N} tracked files (X allowlist-suppressed)." Do not print empty severity buckets.
+
+---
+
+## Connected Skills
+
+| Situation | Connected skill |
+|---|---|
+| Broader pre-publish repo readiness (README, license, API keys) | `/marketplace-gate` (Check 5 Public Safety is the wide net; this skill is the private-token detail) |
+| A leak is a recurring process gap, not a one-off | log via `field-harvest` → candidate `#rule-candidate` |
+| Where should the leaked content actually live? | `/asset-placement-gate` (hub vs project vs CLAUDE.local.md) |
+| Phantom refs / stale links on the same surface | `/source-grounding-audit` (forward axis — orthogonal to this leak axis) |
+
+---
+
+## External User Environment Adaptation
+
+Usable standalone — no hub clone required.
+- **No companion store / no operator-private tokens** → create the pattern source **empty** to declare
+  this explicitly; the scan then reports CLEAN. Leaving the file *absent* instead yields NOT CONFIGURED
+  (a deliberate distinction — absence is "unknown", not "clean"). The skill is only useful once you have
+  a public/private split to protect.
+- **No `.gitignore` allowlist needs** → Step 2 allowlist may be empty; every hit is then reported.
+
+---
+
+## Done When
+
+```
+Step 1 pattern list confirmed (defaults shown / user-adapted)
++ Step 2 allowlist applied
++ Step 3 scan run for every pattern over git ls-files (tracked only — gitignored excluded)
++ Step 4 report output: per-hit file:line + token + severity, plus overall verdict
++ "public-surface-audit Complete" declaration output
+```
+
+Verdict: **CLEAN** (0 tokens after allowlist) | **REVIEW** (LOW-only — drift, prescriptions noted) |
+**LEAK** (1+ HIGH or 1+ MED — block publish, prescriptions attached).
+
+---
+
+## Operating Notes
+
+- **Tracked-only is the point**: never scan gitignored files. A token in `CLAUDE.local.md` is correct
+  placement, not a leak — scanning it would produce false LEAK verdicts and erode trust in the skill.
+- **Patterns are data, not code**: the Step 1 table is the configurable surface. A user with a different
+  username/employer/companion-store edits the table; the scan logic is unchanged.
+- **Generated artifacts are real leaks**: an exported HTML/PDF carrying a username is still a public-surface
+  leak even though hand-editing it is wrong — report it, prescribe "regenerate from sanitized source".
+- **Allowlist tight, not loose**: when unsure whether a reference is legitimate, report it. A false LEAK
+  the user dismisses is cheaper than a real leak suppressed by an over-broad allowlist.