@chrono-meta/fh-gate 1.4.94 → 1.4.96

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

@@ -2,7 +2,7 @@
 name: plugin-recommender
 description: Given a task description, searches internal and external open-source ecosystems (including Codex marketplace and Claude Code marketplace) to find and recommend suitable plugins with installation guidance. Recommendation is quality-validation based (marketplace-listed + performance-validated), not source-origin based. Activates on "recommend a plugin", "what tool should I use?", "is there a plugin for this?", "recommend a tool". Also checks for duplicate installations.
 user-invocable: true
-allowed-tools: ["Grep", "GoogleWebSearch", "Bash"]
+allowed-tools: ["Read", "Grep", "Bash", "WebSearch", "WebFetch"]
 model: sonnet
 ---
 
@@ -59,7 +59,9 @@ Tier is **independent of platform origin** (Anthropic / OpenAI / community). A w
 
 2. **[Priority 1.5] Internal GHE Sister Assets (partially completed work — Tier 2)**: Check if user's task domain already exists in internal sister asset clusters. Prioritize direct use or adoption of sister assets if the user's task falls within these cluster domains.
 
-3. **[Priority 2.5] Project Reference/Contribution Path**:
+3. **[Priority 2] Organization's Internal GHE (Tier 1–4)**: Search internal GHE with keywords like `claude-plugin`, `gemini-plugin` + user keywords / API search. Replace with your organization's internal GHE orgs.
+
+4. **[Priority 2.5] Project Reference/Contribution Path**:
 
     For cases where referencing or contributing to the project itself is more appropriate than installing a plugin. Provide guidance when there's intent for medium-term contribution rather than immediate use.
 
@@ -71,9 +73,7 @@ Tier is **independent of platform origin** (Anthropic / OpenAI / community). A w
     - `plugin-recommender` [Priority 2.5]: When no immediately usable plugin is available → guide to project-level reference/contribution path (alternative to installing)
     - `cross-ecosystem-synergy-detection`: Discover hidden synergies among already-installed skills (post-install utilization optimization)
 
-    Activation condition: Automatically entered when Step 2 [Priority 1]~[Priority 2] search yields no suitable plugin.
-
-4. **[Priority 2] Organization's Internal GHE (Tier 1–4)**: Search internal GHE with keywords like `claude-plugin`, `gemini-plugin` + user keywords / API search. Replace with your organization's internal GHE orgs.
+    Activation condition: Automatically entered when Step 2 [Priority 1]~[Priority 2] search yields no suitable plugin. **This block therefore runs only after [Priority 2] has actually been executed** — the list above is in execution order (1 → 1.5 → 2 → 2.5 → 3), and the priority labels are names, not the run sequence.
 
 5. **[Priority 3] External Open-Source Ecosystem**: WebSearch / WebFetch — "best github actions for X", "claude plugin for Y", etc. Simplification guard: defer external install if internal assets suffice.
 
@@ -91,16 +91,18 @@ When queried for a specific capability (e.g., "adversarial reviewer for bash cod
 0. **Platform built-ins (Tier 0)** — does a built-in skill/command already cover the capability? Check the live session's available-skills list before any plugin search. A built-in that covers ~80% beats installing a plugin for the rest
 1. **Installed locally** — `.claude/agents/`, `plugins/` in current cwd
 2. **FH native skills** — always-loaded knowledge in `plugins/fh-meta/` and `plugins/fh-commons/`
-3. **Claude Code marketplace** — `claude mcp search [capability]` or known CC registry (see verified targets above)
-4. **Codex marketplace** — `npx @openai/codex list-agents [capability]` or known Codex registry
+3. **Claude Code marketplace** — `claude plugin list --available --json` (marketplace plugins; `--available` **requires** `--json`) + `claude plugin marketplace list` to see which marketplaces are even configured. There is **no** CLI keyword-search subcommand — filter the JSON yourself, and fall back to the known CC registry (see verified targets above) for anything not in a configured marketplace
+4. **Codex marketplace** — `npx --yes @openai/codex plugin list --available --json` (optionally `-m <marketplace>`) + `npx --yes @openai/codex plugin marketplace list`. Same limitation: no keyword search, filter the JSON
 5. **npm ecosystem** — `@chrono-meta/`, `@anthropic/`, and other known-quality scoped packages
 
+⚠️ **A failed or empty discovery lane is NOT "no candidates".** Both CLIs above list only *configured* marketplaces, and a non-zero exit / empty array means the lane did not answer — not that nothing exists. Report each lane's state explicitly (`EXECUTED` / `EMPTY` / `FAILED: <stderr>`) and never render a `FAILED` lane as a zero result; a lane that could not run must be re-run or replaced by the web-search fallback (Priority 3) before you tell the user nothing was found.
+
 **Discovery priority**: built-in (Tier 0) > installed > FH native > Tier 1 (any platform) > Tier 2 > Tier 3 > Tier 4
 **Tier 0 guard**: FH native wins over a built-in only when the FH skill adds governance the built-in lacks (e.g. `/goal` → `goal-quench` adds budget+quality gates; code diff review stays with built-in `/code-review`, FH-asset coherence with `hub-cc-pr-reviewer`)
 
 **When sim-conductor chains here for persona discovery**: apply the same platform-aware search scoped to persona/simulation/review capability tags. Return discovered agents with their Tier rating so sim-conductor can decide whether to install or use a built-in brief.
 
-For discovery bash commands (`claude mcp search`, `npx @openai/codex list-agents`, npm scoped search), see `SKILL_detail.md §Discovery-Bash`.
+For discovery bash commands (`claude plugin list --available --json`, `npx --yes @openai/codex plugin list --available --json`, npm scoped search), see `SKILL_detail.md §Discovery-Bash`.
 
 ### Step 2.6: Quality Validation Signals
 
@@ -149,7 +151,8 @@ When user selects desired plugin from recommendation list, help with installatio
 ## Constraints
 
 - **Recommendations, not guarantees**: Does not guarantee plugin performance, stability, or security.
-- **Inbound supply-chain risk (Tier 3/4)**: a Tier 3/4 candidate (§Tier Classification Table) has no marketplace vetting — public skill registries have shipped malicious skills at scale (pointers: [HN 47370624](https://news.ycombinator.com/item?id=47370624) — 824 malicious skills reported on ClawHub; [HN 48678603](https://news.ycombinator.com/item?id=48678603) — Snyk ToxicSkills study. Secondary sources — verify before quoting figures). Flag this explicitly to the user before recommending a Tier 3/4 candidate.
+- **Inbound supply-chain risk — EVERY tier, not just 3/4**: public skill registries have shipped malicious skills at scale (pointers: [HN 47370624](https://news.ycombinator.com/item?id=47370624) — 824 malicious skills reported on ClawHub; [HN 48678603](https://news.ycombinator.com/item?id=48678603) — Snyk ToxicSkills study. Secondary sources — verify before quoting figures). ⚠️ **The channel in both incidents was the marketplace listing itself — i.e. Tier 1/2.** An earlier version of this bullet scoped the warning to Tier 3/4, which inverted its own evidence: it warned loudest exactly where vetting exists and stayed silent where the cited attacks landed. Flag the risk before recommending **any** candidate; a high Tier means *listed and maintained*, never *audited for intent*.
+- **Install string must be resolved, not relayed**: the `<name>` in an install command frequently comes from a web-search result. Before surfacing it, confirm the name resolves to the intended repository (owner/repo matches the source you are citing) — a plausible near-name is the cheapest form of this attack, and installation is irreversible on the machine that runs it.
 - **User consent required**: Does not auto-install without explicit consent.
 - **Search scope limitations**: Only searches within configured search space.
 
@@ -213,9 +216,34 @@ sim-conductor needs persona X (no installed/built-in match)
 
 ```
 All Steps 0~5 completed
-+ Recommendation list table output (top 2~3 items, Tier + Platform + synergy grade included)
-+ Install completed after user selection (or install skipped / 5-B migration path guided)
+  — mandatory-pass: each step produced its stated output, or is
+    explicitly marked N/A with the reason
+
++ Recommendation list table output (top 2~3 items, Tier + Platform + synergy
+  grade included)
+  — mandatory-pass: the table exists with all three columns populated
+
++ Every discovery lane reported with an explicit state
+  (EXECUTED / EMPTY / FAILED: <stderr>)
+  — measured: count lanes attempted vs lanes reporting a state; the two
+    numbers must match. A FAILED lane rendered as "no candidates" is a FAIL
+    of this condition, not a pass — the CLI lanes have no keyword search and
+    see only configured marketplaces, so an empty result is routinely a
+    non-answer rather than an absence (`not found` != `0`)
+
++ Install completed after user selection (or install skipped / 5-B migration
+  path guided)
+  — mandatory-pass: explicit user consent recorded before any install ran
+
 + Duplicate detection results reported
+  — mandatory-pass: `claude plugin list` output consulted in this run
+
++ Every install string surfaced to the user resolves to the repository it is
+  cited from (§Constraints — resolved, not relayed)
+  — judged; adversarial pairing: in the same run, resolve one candidate name
+    you already know is correct AND check one near-name variant. If the
+    procedure cannot separate that pair, the resolution check is
+    UNCALIBRATED and no install string may be presented as verified
 ```
 
 ## Failure Response

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

@@ -57,16 +57,24 @@ gh auth status  # default host (github.com) only
 # Unauthenticated → guide github.com PAT generation above
 ```
 
-**Claude Code marketplace search:**
+**Claude Code marketplace discovery** (there is **no** `search` subcommand — `claude mcp search` does not
+exist and exits 1 with `unknown command 'search'`; list, then filter yourself):
 ```bash
-claude mcp search [capability-keyword]
+claude plugin marketplace list --json      # which marketplaces are configured at all
+claude plugin list --available --json      # installed + available marketplace plugins (--available REQUIRES --json)
 ```
 
-**Codex marketplace search:**
+**Codex marketplace discovery** (`list-agents` does not exist either — the real noun is `plugin`):
 ```bash
-npx @openai/codex list-agents [capability-keyword]
+npx --yes @openai/codex plugin marketplace list
+npx --yes @openai/codex plugin list --available --json      # add -m <marketplace> to scope
 ```
 
+> **Lane-state reporting (mandatory).** Neither CLI supports a keyword query, and both see only
+> *configured* marketplaces. Record each lane as `EXECUTED` / `EMPTY` / `FAILED: <stderr>` and carry
+> that state into the recommendation. **A `FAILED` lane must never be rendered as "no candidates"** —
+> re-run it or fall back to Priority 3 web search before reporting an empty result.
+
 **npm ecosystem search (scoped packages):**
 ```bash
 npm search @chrono-meta [keyword]
@@ -113,11 +121,20 @@ If either duplicate condition met → skip install → report "Already active"
 #### 5-1 through 5-3. Install Steps
 
 1. Confirm intent: "Would you like to install the `[plugin-name]` plugin?"
-2. On agreement:
+2. On agreement — **the two commands take different arguments**: `marketplace add` takes a *source*
+   (`<owner/repo>`, a URL, or a local path), never a plugin name; only `install` takes the plugin name.
    ```bash
-   claude plugin marketplace add [plugin-name]
-   claude plugin install [plugin-name]
+   # Usage: claude plugin marketplace add [options] SOURCE
+   #   SOURCE = owner/repo, a URL, or a local path — NEVER a plugin name
+   SOURCE="owner/repo"
+   PLUGIN="plugin-name"        # optionally "plugin-name@marketplace" to disambiguate
+
+   claude plugin marketplace add "$SOURCE"
+   # Usage: claude plugin install|i [options] PLUGIN
+   claude plugin install "$PLUGIN"
    ```
+   Skip the `marketplace add` line when the plugin already resolves from a configured marketplace
+   (check `claude plugin marketplace list`).
 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

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

@@ -1,8 +1,8 @@
 ---
 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".
+description: Statically checks harness assets against a known-answer probe set after rule/skill changes — inspects the changed source for the trigger phrases, chain links and gate conditions each probe expects, and reports PASS/FAIL/SKIP per probe. Source inspection only; it does not run live sessions, so it catches assets that no longer SAY the right thing, not models that stop DOING it. Triggers on "prompt regression", "did my changes break anything", "regression check", "test harness changes".
 user-invocable: true
-allowed-tools: ["Read", "Bash", "Glob", "Grep"]
+allowed-tools: ["Read", "Write", "Bash", "Glob", "Grep"]
 model: sonnet
 complexity_routing:
   base: sonnet
@@ -58,8 +58,15 @@ ls .claude/regression/probes.md 2>/dev/null || echo "NO_CUSTOM_PROBES"
 ```
 
 **If custom probes exist**: load and use them. The hub repo ships its golden probe set
-(known-answer offline eval, 32 probes with check classes) at exactly this path — when
-present it is canonical and supersedes the default matrix below.
+(known-answer offline eval, **33 probes** with check classes — 27 mandatory-pass · 1 measured ·
+5 judged, of which 2 rows are inert deletion anchors, so live coverage is 31) at exactly this path
+— when present it is canonical and supersedes the default matrix below.
+
+> Count from the file, not from this line: `grep -cE '^\| *`[A-Z][A-Z0-9-]*-[0-9]+` *\|'
+> .claude/regression/probes.md`. Both this number and the tally inside `probes.md` read `32` until
+> 2026-08-12, when the actual count was 33 — a probe had been added to section A without touching
+> either summary. A count duplicated in two files rots independently; if the two disagree, the file
+> wins and both get corrected.
 
 **If no custom probes** (e.g. Mode C install without the hub repo): use the default
 probe matrix below.
@@ -93,7 +100,23 @@ If change scope is `CLAUDE.md` core (10+ lines changed): run **full suite** (all
 
 ---
 
-### Step 4. Run Affected Probes
+### Step 4. Evaluate Affected Probes (static source inspection)
+
+**What this step is, stated plainly.** Every check below reads the changed *source* and asks whether
+the text a probe expects is still there. No live session is started, no model is prompted, no output
+is compared against a recorded transcript. The description said "running standard prompt probes …
+comparing outputs against saved baselines", which reads as live execution; the honest label is a
+**known-answer static check**.
+
+**What it therefore cannot catch** — say this in the report, do not leave it implied:
+- a rule that is still present but has stopped *firing* (salience loss, ordering, competition
+  from another rule)
+- a trigger phrase present in the file but shadowed by a higher-priority route
+- any behavior change that leaves the source text identical
+
+Those need a dispatched blind sim at the target tier (`sim-conductor`, or the target-tier sim gate in
+`.claude/rules/fh_4axis_gate.md`). A green report here means *the assets still say the right thing*.
+Treating it as behavioral evidence is the misread this section exists to prevent.
 
 For each affected probe, evaluate:
 
@@ -150,24 +173,44 @@ If all probes pass:
 
 After a deliberate behavior change (not a regression — an intentional improvement), update the baseline:
 
+Prompt user first: *"Probe `G-GATE-03` now expects the new gate format. Update baseline? (y/n)"*
+Only update on explicit `y` — never auto-update.
+
+On `y`, actually perform the write. The previous version of this step was three lines of which two
+were comments — it created the directory and stopped, so "baseline updated" was reported by a step
+that had written nothing.
+
 ```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)"*
+Then **use the `Write` tool** on `.claude/regression/probes.md` (create it from the SKILL.md default
+matrix if absent) to apply the approved edit. Each approved change edits the probe's row in place —
+Expected Behavior, Scope, and Class — and:
 
-Only update on explicit `y` — never auto-update.
+- update the `**Count**:` tally line **in the same edit** if a row was added or removed, including
+  the per-section breakdown and the class counts (a stale tally is exactly how the `32`/`33`
+  mismatch was introduced)
+- append a one-line note under `**Baseline**:` recording the date and the reason for the change
+- never rewrite rows the user did not approve
+
+Confirm afterwards by re-reading the file and reporting the row's new content plus the recount —
+`grep -cE '^\| *`[A-Z][A-Z0-9-]*-[0-9]+` *\|' .claude/regression/probes.md`. Do not report a
+baseline update whose result you have not read back.
 
 ---
 
 ## Done When
 
-- All affected probes are evaluated (PASS / FAIL / SKIP) — class: mandatory-pass
+- All affected probes are evaluated (PASS / FAIL / SKIP) and the three counts sum to the number of
+  probes selected in Step 3 — class: measured (`PASS + FAIL + SKIP == selected`)
 - Regression report is output with clear PASS/FAIL verdict — class: mandatory-pass
+- The report states its own scope: **static source inspection, no live session run** — a green
+  verdict is never presented as behavioral evidence — class: mandatory-pass
 - If FAIL: specific file + line fix is recommended — class: judged, paired with verify-bidirectional (the fix recommendation is re-checked, not trusted as-is)
-- Baseline updated only on explicit user approval — class: mandatory-pass (HITL)
+- Baseline updated only on explicit user approval, and the written file is **read back** and its
+  probe count reported — class: mandatory-pass (HITL). Approval alone does not close this: a step
+  that prompts, gets `y`, and writes nothing satisfied the old wording.
 
 ---
 

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

@@ -38,7 +38,9 @@ deliberately excluded — `CLAUDE.local.md`, the companion store, and local sess
 *correct* home for operator-private tokens, so finding them there is not a leak.
 
 ```bash
-REPO_PATH="${ARGUMENTS#--target }"
+ARGS="${ARGUMENTS//--json/}"            # strip flags first — "--json" alone must not become the path
+REPO_PATH="${ARGS#--target }"
+REPO_PATH="$(printf '%s' "$REPO_PATH" | xargs)"
 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; }
@@ -50,12 +52,18 @@ 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.
+The pattern source is **two layers, matching the mechanical scan layer** (`scripts/psa_scan_lib.sh`,
+shared with the pre-commit/pre-push/pre-publish hooks — this skill must render the same verdict the
+hooks would, or the same repo state gets two answers):
+
+1. **`.claude/rules/.public-surface-patterns.defaults`** — committed, universal placeholder-grade
+   patterns (safe to publish; carries no operator literal).
+2. **`.claude/rules/.public-surface-patterns`** — **gitignored, operator literals** (or `PSA_PATTERNS`
+   env override). Your real username and employer name live *only* here — hardcoding them in a tracked
+   file would leak exactly what this skill hunts. One `severity<TAB>regex` per line.
+
+The scan reads the **union of both layers**. This SKILL.md carries only placeholders; the skill
+dogfoods its own rule.
 
 | # | Token class | Severity | Placeholder (real value goes in the gitignored source) | Why private |
 |:-:|---|:-:|---|---|
@@ -71,12 +79,16 @@ its own rule.
 - **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.
+> **Setup**: put your real values in the gitignored override (one `severity<TAB>regex` per line).
+> Degrade states, by layer — never collapse them:
+> - **Neither layer present** → **NOT CONFIGURED** — *not* CLEAN. A missing pattern source must never
+>   masquerade as a clean bill of health ("nothing scanned" misread as "nothing leaked").
+> - **Defaults only** (override absent) → scan runs, but the verdict carries the label
+>   `operator literals NOT CONFIGURED — universal patterns only; identity/company classes UNSCANNED`.
+>   This mirrors what the hooks scan in the same state, instead of reporting NOT CONFIGURED while the
+>   hook path quietly scans defaults (two verdicts for one repo state — the divergence this line closes).
+> - To declare "I genuinely have no private tokens", create the override **empty** — an empty file is
+>   an explicit declaration, an absent file is unconfigured.
 
 ---
 
@@ -86,6 +98,11 @@ Some tracked files legitimately reference otherwise-private tokens — the scan
 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.
 
+**Where the filled allowlist lives**: a populated allowlist row *names private tokens*, so it belongs
+in a **gitignored** source beside the pattern override (`.claude/rules/.public-surface-allowlist`, or a
+section of `CLAUDE.local.md`) — never in a tracked file. The table below shows generic shapes only; a
+tracked copy of your real allowlist would itself be the leak this skill scans for.
+
 | Tracked file | Allowed tokens | Reason |
 |---|---|---|
 | `.gitignore` | companion-store name, sync-script name | Must name what it ignores |
@@ -172,11 +189,17 @@ class of leak). Diagnostic-only: this step never writes — it reports, the oper
 Report per-hit `file:line → matched token [class]` grouped by severity, then the overall verdict.
 **Verdict thresholds** (behavioral — these define the gate):
 
-- ⚪ **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)
+- ⚪ **NOT CONFIGURED** — no pattern layer present (nothing scanned — NOT a clean result; set up first)
+- 🟢 **CLEAN** — pattern source present (incl. empty override), 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)
 
+**Every verdict line carries a `coverage:` qualifier** — `full` (both layers loaded) or
+`defaults-only` (override absent: operator identity/company classes UNSCANNED). The qualifier exists
+because the enum alone cannot preserve the defaults-only state: `CLEAN (coverage: defaults-only)` on
+an operator-configured checkout is missing evidence, not a pass — publish-gating callers there must
+require `coverage: full`.
+
 > **Detail**: See `SKILL_detail.md §Report-Template` — the full human-report ASCII layout (severity
 > buckets, allowlist-suppressed line) — read when formatting the Step 4 report.
 
@@ -207,7 +230,9 @@ enforceable (FH's "enforcement is a hook, not a prompt" principle). Imported fro
 authoritative — never gate on `counts` alone**: a counts-only check (`HIGH==0 && MED==0`) misreads
 `NOT_CONFIGURED` (which also has zero counts) as a pass. A caller blocks when `verdict` is `LEAK` **or**
 `NOT_CONFIGURED` — an unconfigured scan is not a pass (the same silent-failure guard as the human path:
-absence ≠ CLEAN).
+absence ≠ CLEAN). The JSON carries the same `coverage` field as Step 4; on an operator-configured
+checkout a publish-gating caller additionally blocks on `coverage: "defaults-only"` (identity/company
+classes unscanned there — zero counts prove nothing about the classes that never ran).
 
 ---
 
@@ -236,15 +261,24 @@ Usable standalone — no hub clone required.
 ## 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
+Step 1 pattern source resolved (both layers checked; absent/partial
+  states rendered as their labeled degrade state, never as CLEAN)      — mandatory-pass
++ Step 2 allowlist applied (from a gitignored source)                  — mandatory-pass
++ Step 3 scan run for every pattern over git ls-files (tracked only —
+  gitignored excluded), malformed pattern rows counted and reported,
+  never silently dropped                                               — measured (hit + malformed counts)
++ Step 3b/3c run (FP-hygiene on matched tokens; ignore-verification
+  for expected-private paths) or explicitly skipped with reason        — mandatory-pass
++ Step 4 report output: per-hit file:line + token + severity, plus
+  overall verdict                                                      — mandatory-pass
++ "public-surface-audit Complete" declaration output                   — mandatory-pass
 ```
 
 Verdict: **CLEAN** (0 tokens after allowlist) | **REVIEW** (LOW-only — drift, prescriptions noted) |
-**LEAK** (1+ HIGH or 1+ MED — block publish, prescriptions attached).
+**LEAK** (1+ HIGH or 1+ MED — block publish, prescriptions attached) | **NOT_CONFIGURED** (no pattern
+source — nothing scanned, not a pass; same 4-value enum as Step 5 `--json`. An earlier version of this
+enum had 3 values here, so a session following only Done When would force absent-config into CLEAN/
+REVIEW/LEAK — re-opening the exact silent-pass the body closes).
 
 ---
 

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

@@ -11,19 +11,58 @@ 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"
+# ── Single-source preference: when the shared library exists, use it and write NO second loop ──
+# scripts/psa_scan_lib.sh owns loading + row validation + exemptions for the hook layer; a hand-rolled
+# copy here is a second normalizer with its own leniency (the divergence class this rewrite removed).
+if [ -r "scripts/psa_scan_lib.sh" ]; then
+  . scripts/psa_scan_lib.sh
+  psa_load ".claude/rules/.public-surface-patterns.defaults" \
+           "${PSA_PATTERNS:-.claude/rules/.public-surface-patterns}"
+  { [ "$PSA_DEFAULTS_OK" -eq 1 ] || [ "$PSA_OVERRIDE_PRESENT" -eq 1 ]; } \
+    || { echo "⚪ NOT CONFIGURED: neither pattern layer present. Not scanning."; exit 2; }
+  [ "$PSA_BAD_ROWS" -gt 0 ] \
+    && { echo "HARNESS_ERROR: $PSA_BAD_ROWS unusable pattern row(s) — verdict cannot be CLEAN"; exit 10; }
+  # Feed every tracked file as path<TAB>line, the stream psa_scan_tagged consumes. Sourcing the lib
+  # without these calls is a no-op scan — measured on this repo (PSA_STREAM stayed unset), so the
+  # calls are spelled out here rather than pointed at.
+  while IFS= read -r f; do
+    awk -v p="$f" '{printf "%s\t%s\n", p, $0}' "$f" 2>/dev/null
+  done < /tmp/_psa_tracked.txt | psa_scan_tagged
+  [ "$PSA_OVERRIDE_PRESENT" -eq 1 ] \
+    || echo "coverage: defaults-only — operator literals NOT CONFIGURED (identity/company classes UNSCANNED)"
+else
+  # ── Standalone fallback (no hub scripts in this repo) — validated loop, malformed rows COUNTED ──
+  PSA_DEFAULTS=".claude/rules/.public-surface-patterns.defaults"
+  PATTERN_SRC="${PSA_PATTERNS:-.claude/rules/.public-surface-patterns}"
+  SRC_LIST=""
+  [ -e "$PSA_DEFAULTS" ] && SRC_LIST="$PSA_DEFAULTS"
+  [ -e "$PATTERN_SRC" ]  && SRC_LIST="$SRC_LIST $PATTERN_SRC"
+  [ -n "$SRC_LIST" ] || { echo "⚪ NOT CONFIGURED: no pattern source (neither defaults nor override). Not scanning."; exit 2; }
+
+  MALFORMED=0
+  cat $SRC_LIST > /tmp/_psa_rows.txt    # no pipe into the loop — a piped while runs in a subshell and loses MALFORMED
+  # `|| [ -n "$severity" ]` keeps a final row that lacks a trailing newline — `read` alone drops it silently.
+  while IFS=$'\t' read -r severity regex || [ -n "$severity" ]; do
+    case "$severity" in ''|'#'*) continue ;; esac                     # blank / comment rows
+    if [ -z "$regex" ]; then                                          # no tab separator → malformed, VISIBLE
+      MALFORMED=$((MALFORMED+1)); echo "MALFORMED ROW (no <TAB>): $severity" >&2; continue
+    fi
+    printf 'x\n' | grep -qE "$regex" 2>/dev/null
+    rc=$?                                                             # plain rc capture — `if !` would negate $?
+    if [ "$rc" -ge 2 ]; then                                          # grep rc≥2 = invalid regex, not "no match"
+      MALFORMED=$((MALFORMED+1)); echo "MALFORMED ROW (bad regex): $regex" >&2; continue
+    fi
+    grep -nIE "$regex" $(cat /tmp/_psa_tracked.txt) | sed "s/^/[$severity] /"
+  done < /tmp/_psa_rows.txt
+  # Malformed rows poison the verdict: part of the pattern file never scanned → CLEAN is unprovable.
+  [ "$MALFORMED" -gt 0 ] && { echo "HARNESS_ERROR: $MALFORMED malformed pattern row(s) — verdict cannot be CLEAN"; exit 10; }
+fi
 ```
 
+**Why the fallback validates instead of skipping**: the previous loop dropped a malformed row with a
+bare `continue` and discarded grep's stderr — a broken pattern file scanned "clean" by silently not
+scanning. `not found ≠ 0`: a row that never ran is not a row with zero hits.
+
 For each pattern, run `grep -nIE "<regex>" $(git ls-files)`:
 - `-n` → line numbers (required for `file:line` output)
 - `-I` → skip binary files

package/plugins/fh-meta/skills/return-path-gate/SKILL.md

@@ -66,7 +66,27 @@ find plugins/ -name "SKILL.md" | sort
 find plugins/ -path "*[name]/SKILL.md"
 ```
 
-If 0 SKILL.md files are in scope, output: "No SKILL.md files in scope — audit skipped." and stop.
+If 0 SKILL.md files are in scope, **distinguish the two causes before stopping** — a failed scope
+command and a genuinely empty scope both render as zero lines, and only one of them is skippable:
+
+```bash
+git rev-parse --git-dir >/dev/null 2>&1 \
+  || { echo "HARNESS_ERROR: git unavailable — scope could NOT be measured (not an empty scope)"; exit 10; }
+
+# Repo-liveness alone is NOT enough: a broken ref (e.g. missing origin/main in --pr mode) fails the
+# scope command with rc=1 and empty output while rev-parse stays green. Capture the scope command's
+# OWN exit status — before the grep, which legitimately returns 1 on no-match:
+scope_out=$(git diff --name-only origin/main...HEAD 2>&1); scope_rc=$?
+[ "$scope_rc" -ne 0 ] \
+  && { echo "HARNESS_ERROR: scope command failed (rc=$scope_rc): $scope_out"; exit 10; }
+printf '%s\n' "$scope_out" | grep "SKILL\.md"
+# (same rc-capture shape applies to the default and --all scope commands)
+```
+
+With both controls green and genuinely 0 files in scope, output:
+"No SKILL.md files in scope — audit skipped (control: git rev-parse OK)." and stop.
+A HARNESS_ERROR is a distinct non-pass — it must never be reported as "audit skipped", because this
+skill is pipeline-conductor's Step 0.5 pre-flight and a tooling-down skip would render as a pass there.
 
 ---
 
@@ -221,11 +241,19 @@ Next actions:
 ## Done When
 
 ```
-Step 0 scope determined; SKILL.md files identified
-+ Step 1 two-pass extraction complete (Pass A caller-wait + Pass B callee-output evaluated separately)
-+ Step 2 every (caller → callee) pair classified CLOSED or OPEN with two-dimension severity
-+ Step 3 fix prescriptions output for each OPEN chain (core FH skills: proposal-only)
-+ Step 4 summary report with CLOSED/OPEN counts output
+Step 0 scope determined; a failed scope command reported as
+  HARNESS_ERROR, never as empty scope                           — mandatory-pass
++ Step 1 two-pass extraction complete (Pass A caller-wait +
+  Pass B callee-output evaluated separately)                    — mandatory-pass
++ Step 2 every (caller → callee) pair classified CLOSED or
+  OPEN with two-dimension severity                              — judged (adversarial pairing:
+  before ANY chain is reported OPEN, the ground-truth CLOSED
+  pair from §Operating Notes must classify CLOSED in the same
+  run — an instrument that cannot separate the known pair
+  reports nothing)
++ Step 3 fix prescriptions output for each OPEN chain
+  (core FH skills: proposal-only)                               — mandatory-pass
++ Step 4 summary report with CLOSED/OPEN counts output          — measured (counts)
 ```
 
 > Fix prescriptions are text output only (Write not in allowed-tools). Prescription application is manual and out of scope for this skill. Verification of applied fixes requires re-running `/return-path-gate --skill [name]`.
@@ -254,4 +282,5 @@ Verdict: PASS (0 HIGH severity OPEN chains) | CONDITIONAL_PASS (MEDIUM/LOW sever
 - **CONDITIONAL_PASS gate is the highest-risk gap**: A chain where CONDITIONAL_PASS conditions are listed by the callee but the caller has no enforcement path is OPEN even if other verdict paths fold correctly.
 - **Scope default is narrow by design**: Default captures modified + newly added files (not just staged changes). Use `--pr` for PR-relative mode in worktrees, `--all` for periodic sweeps.
 - **Core FH skill prescriptions are proposals only**: Edits to harvest-loop, steel-quench, sim-conductor, and other core skills require deliberate review — output proposal notes, not standard prescriptions.
-- **Reference pattern**: `knowledge/shared/harness-core/return_path_gate.md` defines the canonical closed-loop structure and verified instances (apex-review → sim-conductor, agent-composer ↔ deliberation). These are the ground-truth CLOSED examples for calibrating classification.
+- **Reference pattern**: `knowledge/shared/harness-core/return_path_gate.md` defines the canonical closed-loop structure and verified instances (apex-review → sim-conductor, agent-composer ↔ deliberation). These are the ground-truth CLOSED examples for calibrating classification — and that calibration is a Done When condition (Step 2's adversarial pairing), not an optional note.
+- **The Pass A signal list is a closed English keyword list — know its degrade direction**: synonyms ("blocks until", "halts on") and non-English documentation will read as false OPEN. That direction is by design (over-report, never silent-close), but treat an OPEN verdict on unconventional wording as a candidate for human reading before prescribing a fix.