# https://github.com/Emasoft/claude-plugins-validation Project Manual

Generated at: 2026-07-28 20:17:34 UTC

## Table of Contents

- [Overview and Getting Started](#page-1)
- [Core Validation Features and Security Scanning](#page-2)
- [Architecture and Internal Components](#page-3)
- [Operations, Workflows, and Common Failure Modes](#page-4)

<a id='page-1'></a>

## Overview and Getting Started

### Related Pages

Related topics: [Core Validation Features and Security Scanning](#page-2), [Architecture and Internal Components](#page-3)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/Emasoft/claude-plugins-validation/blob/main/README.md)
- [CHANGELOG.md](https://github.com/Emasoft/claude-plugins-validation/blob/main/CHANGELOG.md)
- [.claude-plugin/plugin.json](https://github.com/Emasoft/claude-plugins-validation/blob/main/.claude-plugin/plugin.json)
- [scripts/cli.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/cli.py)
- [scripts/cpv_validation_common.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/cpv_validation_common.py)
- [scripts/publish.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/publish.py)
- [scripts/skillaudit/__init__.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/skillaudit/__init__.py)
</details>

# Overview and Getting Started

Claude Plugins Validation (CPV) is a Claude Code plugin that validates *other* Claude Code plugins. It ships as a standard `.claude-plugin` repository so it can be installed into any Claude Code environment, and it exposes a CLI entry point — `cpv-remote-validate` — for use from scripts and CI. Source: [README.md:1-40]().

The project is at release `v3.23.1` (2026-07-28), which fixed orchestrator progress-marker dispatching. Source: [CHANGELOG.md:5-12]().

## What CPV Does

CPV runs a structured battery of checks against a target plugin tree:

- **Structure** — manifest (`plugin.json`), command/skill/agent frontmatter, and required file presence.
- **Skill audit** (`skillaudit`) — a set of detectors that flag risky patterns (filesystem writes, agent-manipulation vectors, MCP schema poisoning, etc.).
- **Canonical pipeline** — a templated `publish.py` that downstream plugins vendor to run their own build / test / gate flow.

The whole pipeline is parameterized by severity tiers (e.g., `MAJOR`, `NIT`, demoted) and a `--strict` flag that promotes warnings to failures. Source: [README.md:40-90]().

## Installation

CPV is installed like any other Claude Code plugin: point Claude Code at the marketplace entry declared in `.claude-plugin/plugin.json`, then invoke the bundled CLI. Source: [.claude-plugin/plugin.json:1-20]().

A minimal local install from this repo:

```bash
git clone https://github.com/Emasoft/claude-plugins-validation.git
# then add it as a plugin in Claude Code, or invoke the CLI directly:
python scripts/cli.py --help
```

Source: [scripts/cli.py:1-40]().

## Basic Usage

The user-facing command is `cpv-remote-validate plugin . --strict`, which validates the current directory as a plugin with warnings promoted to errors. Source: [README.md:60-95]().

Common invocations:

| Goal | Command |
| --- | --- |
| Full strict validation | `cpv-remote-validate plugin . --strict` |
| CI preflight grade | `cpv-remote-validate ci-preflight .` |
| Skill-audit only | `cpv-remote-validate skillaudit .` |
| Run vendored publish | `python scripts/publish.py --gate` |

Source: [scripts/cli.py:40-120]().

### Workflow at a Glance

```mermaid
flowchart LR
  A[Target plugin tree] --> B[cpv-remote-validate]
  B --> C{Structure checks}
  B --> D{Frontmatter checks}
  B --> E[skillaudit detectors]
  C --> F[Report]
  D --> F
  E --> F
  F --> G{Gate --strict?}
  G -- pass --> H[Ship]
  G -- fail --> I[Fix and re-run]
```

Source: [scripts/cpv_validation_common.py:1-60]().

## Known Gotchas When Getting Started

Community-reported false positives and scope bugs that beginners should be aware of:

- **`skillaudit:filesystem FS_WRITE`** can fire on PROSE inside install docs that merely *name* `~/.zshrc` in a bash comment. Source: [issue #177](https://github.com/Emasoft/claude-plugins-validation/issues/177).
- **`skillaudit:agent_manipulation MCP_SCHEMA_POISON`** can fire on a `description:` frontmatter field of a wikimem memory note. Source: [issue #178](https://github.com/Emasoft/claude-plugins-validation/issues/178).
- **`--strict` scope** may include non-shippable tracked content (project memory, test fixtures) and even gitignored files. Source: [issue #176](https://github.com/Emasoft/claude-plugins-validation/issues/176).
- The canonical `publish.py` template hardcodes `timeout=300` inside its generic `run()` helper, which can make pytest gates unsatisfiable for real suites. Source: [issue #179](https://github.com/Emasoft/claude-plugins-validation/issues/179).
- `cpv_validation_common.py` itself can trip Bandit `B108` on its own data constants, blocking `publish.py --gate` for any plugin that vendors it. Source: [issue #172](https://github.com/Emasoft/claude-plugins-validation/issues/172).

If your first run produces a wall of findings, check whether they fall into one of these known classes before changing your plugin.

## Next Steps

1. Run `cpv-remote-validate plugin .` (non-strict) first to see baseline findings.
2. Review which detectors fire and consult the `skillaudit` source for what each detector actually matches. Source: [scripts/skillaudit/__init__.py:1-40]().
3. If you maintain a downstream plugin, vendor `scripts/publish.py` as your CI gate and adjust the hardcoded timeout. Source: [scripts/publish.py:1-60]().
4. Track upstream issues — several common false positives are tracked and being triaged.

---

<a id='page-2'></a>

## Core Validation Features and Security Scanning

### Related Pages

Related topics: [Overview and Getting Started](#page-1), [Architecture and Internal Components](#page-3), [Operations, Workflows, and Common Failure Modes](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [scripts/validate_plugin.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/validate_plugin.py)
- [scripts/validate_security.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/validate_security.py)
- [scripts/cpv_skillaudit_native.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/cpv_skillaudit_native.py)
- [scripts/cpv_snyk_agent_scanner.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/cpv_snyk_agent_scanner.py)
- [scripts/cpv_validation_common.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/cpv_validation_common.py)
- [skills/cpv-plugin-validation-skill/SKILL.md](https://github.com/Emasoft/claude-plugins-validation/blob/main/skills/cpv-plugin-validation-skill/SKILL.md)
</details>

# Core Validation Features and Security Scanning

## Purpose and Scope

The **claude-plugins-validation** (CPV) plugin provides two coordinated layers of validation for Claude Code plugins:

1. **Structural validation** — verifying that plugin manifests, agent definitions, skill frontmatter, command files, and the shipped file tree conform to the Claude Code plugin schema.
2. **Security scanning** — detecting prompt-injection patterns, unsafe filesystem writes, agent-manipulation vectors, and dependency-level vulnerabilities that would compromise an agent at runtime.

Both layers are exposed through `cpv-remote-validate`, the canonical CLI entry point, and orchestrated together in the **canonical-pipeline** workflow used by downstream plugins such as `ai-maestro-plugin`, `ai-maestro-janitor`, and `ai-maestro-chief-of-staff`. Source: [skills/cpv-plugin-validation-skill/SKILL.md:1-40]()

## Architecture of the Validation Pipeline

The validation pipeline is composed of independent detectors that run in sequence and emit findings classified by severity (BLOCKER / MAJOR / MINOR / NIT) and category (e.g. `skillaudit:filesystem`, `skillaudit:agent_manipulation`, `bandit`, `snyk`).

| Layer | Module | Role |
|---|---|---|
| Structural | `scripts/validate_plugin.py` | Manifest, frontmatter, tree-shape checks |
| Security | `scripts/validate_security.py` | Aggregator + severity grading |
| Skill-audit | `scripts/cpv_skillaudit_native.py` | Anti-injection / FS-write / agent-manip detectors |
| Dependency | `scripts/cpv_snyk_agent_scanner.py` | Snyk-style supply-chain analysis |
| Shared | `scripts/cpv_validation_common.py` | Constants, severity helpers, shared utilities |

Source: [scripts/validate_plugin.py:1-30](), [scripts/validate_security.py:1-25](), [scripts/cpv_skillaudit_native.py:1-30](), [scripts/cpv_snyk_agent_scanner.py:1-25]()

## Structural Validation Features

`validate_plugin.py` is the canonical front door for plugin integrity. It enforces:

- **Manifest schema** — `.claude-plugin/plugin.json` must contain required keys (`name`, `version`, `description`) and conform to the published schema.
- **Skill frontmatter** — each `SKILL.md` is parsed and validated against the recognized field set. Unknown fields raise a `[WARNING] Unknown frontmatter field '...'` finding (community-reported for `background`, a valid CC v2.1.218 field — see issue #173). Source: [scripts/validate_plugin.py:120-180]()
- **Agent and command files** — frontmatter must declare `name`, `description`, and (where required) the `model` and `tools` fields.
- **Tree hygiene** — `--strict` mode traverses every tracked file under the plugin root. Community reports show this scope is currently too wide: it grades `project-memory/` notes and test fixtures that are not part of the shipped plugin surface (issue #176). Source: [scripts/validate_plugin.py:200-260]()

When invoked as `cpv-remote-validate plugin . --strict`, structural findings are emitted alongside security findings and aggregated by `validate_security.py`.

## Security Scanning: `skillaudit`

The `skillaudit` engine — implemented natively in `cpv_skillaudit_native.py` — is CPV's primary anti-injection defense. It runs four detector families:

1. **`filesystem FS_WRITE`** — flags code or prose that writes into agent-readable locations (e.g. shell comments naming `~/.zshrc`). Issue #177 documents a false-positive on install documentation that merely *mentions* a path inside a bash comment.
2. **`agent_manipulation MCP_SCHEMA_POISON`** — flags descriptions or frontmatter that try to alter MCP tool schemas at runtime. Issue #178 reports a false-positive on a wikimem memory-note `description:` field that legitimately summarizes tool behavior.
3. **Defensive guardrail detectors** — four detectors that identify anti-injection guardrails *as* injection attempts. Issue #170 shows these retroactively break previously-green releases by demoting safe defensive code to NIT under `--strict`.
4. **Capability-vs-live scoring** — proposed in issue #174: today CPV only inspects the plugin tree, not its dependencies. The feature request asks CPV to score capability (declared) vs live (observed) writer behavior.

Source: [scripts/cpv_skillaudit_native.py:30-120](), [scripts/cpv_skillaudit_native.py:200-340]()

Findings are demoted to NIT (needs-review) by default and only escalate to BLOCKER when the matched text is executable. Source: [scripts/validate_security.py:60-140]()

## Dependency and Static Analysis

Two additional scanners harden the supply chain:

- **`bandit`** — Python AST static analysis. Issue #172 documents a self-tripping bug: `cpv_validation_common.py` constants include the string `B108` (hardcoded /tmp path) which bandit then flags against itself, blocking `publish.py --gate` for every plugin that vendors the module.
- **`snyk_agent_scanner`** (`cpv_snyk_agent_scanner.py`) — extends Snyk-style scanning to *agent-context writers*: components that emit files an agent later loads as instructions. Issue #174 asks CPV to walk *dependencies*, not just the plugin tree, and to score capability vs live separately.

Source: [scripts/cpv_snyk_agent_scanner.py:40-160](), [scripts/cpv_validation_common.py:20-90]()

## Known Limitations and Community-Reported Edge Cases

The following recurring failure modes are tracked in the issue tracker and shape current development priorities:

- **Validate-hang in canonical pipeline** — `publish.py`'s `run()` helper hardcodes `timeout=300`, which is unsatisfiable for real test suites and triggers a 25–30 min hang after CPV has already built (issues #179, #180).
- **False-positive surface** — defensive anti-injection code, documentation prose, and memory-note descriptions are routinely flagged by skillaudit (issues #170, #177, #178).
- **Over-broad `--strict` scope** — non-shippable tracked files (project memory, fixtures, gitignored paths) are graded (issue #176).
- **Schema drift** — new CC frontmatter fields (`background` in v2.1.218) are not yet recognized (issue #173).

These limitations are addressed in the latest release **v3.23.1** (orchestrator progress-marker fix) and feed into the next upgrade cycle of the canonical-pipeline regen process. Source: [CHANGELOG.md:1-20](), [scripts/cpv_validation_common.py:1-20]()

---

<a id='page-3'></a>

## Architecture and Internal Components

### Related Pages

Related topics: [Core Validation Features and Security Scanning](#page-2), [Operations, Workflows, and Common Failure Modes](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [scripts/cpv_batch_orchestrator.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/cpv_batch_orchestrator.py)
- [scripts/cpv_batch_planner.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/cpv_batch_planner.py)
- [scripts/cpv_scan_cache.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/cpv_scan_cache.py)
- [scripts/cpv_parallel_runner.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/cpv_parallel_runner.py)
- [scripts/cpv_re2_matcher.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/cpv_re2_matcher.py)
- [agents/cpv-agent.md](https://github.com/Emasoft/claude-plugins-validation/blob/main/agents/cpv-agent.md)
</details>

# Architecture and Internal Components

Claude Plugins Validation (CPV) is a self-validating framework that lints, audits, and grades Claude Code and Claude Code-compatible plugin repositories. The internal architecture is decomposed into focused Python scripts under `scripts/` coordinated by an agent definition in `agents/`, with the goal of producing a deterministic, cacheable, and parallelisable validation pipeline that can be regenerated ("upgraded") in place by downstream consumers such as `publish.py`.

## Core Components

The system's runtime is organised around five cooperating modules plus one agent facade.

### Scan Cache

`scripts/cpv_scan_cache.py` is the persistence layer that lets repeated validation runs avoid recomputing file-level diffs and detector results. It stores fingerprints (hashes of file content plus the detector set version) keyed by plugin path, so that unchanged files are skipped on subsequent runs. This module is the substrate that makes `--strict` re-runs and CI preflight grading affordable in repos with thousands of files; the v3.23.1 orchestrator fix that moved progress-marker emission from worker threads to the dispatcher relied on this cache to remain deterministic. Source: [scripts/cpv_scan_cache.py]().

### RE2 Matcher

`scripts/cpv_re2_matcher.py` wraps Google's RE2 library for the pattern matching that underpins every `skillaudit:*` detector. RE2 guarantees linear-time matching and avoids catastrophic-backtracking ReDoS that would otherwise make plugin trees with large Markdown sections costly to scan. All detectors that emit findings such as `agent_manipulation MCP_SCHEMA_POISON` or `filesystem FS_WRITE` (see issues #177 and #178) execute their signatures through this matcher. Source: [scripts/cpv_re2_matcher.py]().

### Batch Planner

`scripts/cpv_batch_planner.py` turns a plugin tree into a directed acyclic graph of work units: each node is a `(file, detector_set)` tuple, and edges express inter-detector dependencies (e.g. frontmatter extraction must complete before `skillaudit` runs). The planner reads `.gitignore` and the canonical "shippable surface" definition so that non-shippable tracked content — files such as `project-memory/` notes and test fixtures flagged by issue #176 — are excluded from `--strict` scope. Source: [scripts/cpv_batch_planner.py]().

### Parallel Runner

`scripts/cpv_parallel_runner.py` executes the planner's DAG across a worker pool. It is responsible for thread/worker lifecycle, timeout enforcement, and structured result aggregation. The orchestrator-level bug fixed in v3.23.1 ("Emit progress markers from the dispatcher, not worker threads") lives at the boundary between this runner and the orchestrator, indicating that worker threads previously emitted markers asynchronously and produced nondeterministic ordering in CI logs. Source: [scripts/cpv_parallel_runner.py]().

### Batch Orchestrator

`scripts/cpv_batch_orchestrator.py` is the top-level dispatcher. It owns the CLI entry point (`cpv-remote-validate`), wires together the planner, runner, cache, and matcher, and emits progress markers, severity grading (MAJOR/NIT), and the final exit-status contract that downstream `publish.py --gate` consumes. Because community issue #180 reports the orchestrator hanging for 25–30 minutes after CPV has built successfully, the orchestrator is also the locus of timeout-cap enforcement for the whole validate step. Source: [scripts/cpv_batch_orchestrator.py]().

### Agent Facade

`agents/cpv-agent.md` exposes the same validation toolchain to Claude itself as a slash-invokable agent, so that a model session can request `cpv-remote-validate plugin . --strict` through conversation rather than shell. The agent facade delegates to the orchestrator script and inherits its cache, planner, and detector set without reimplementation. Source: [agents/cpv-agent.md]().

## Workflow and Data Flow

A canonical validate run follows the sequence below. Each stage hands structured artefacts to the next, and the cache short-circuits unchanged work.

| Stage | Module | Input | Output |
|---|---|---|---|
| Plan | `cpv_batch_planner.py` | plugin root, `.gitignore`, shippable-surface list | DAG of `(file, detector_set)` nodes |
| Match | `cpv_re2_matcher.py` | file content, detector signatures | per-file finding list |
| Run | `cpv_parallel_runner.py` | DAG | worker-pool results |
| Cache | `cpv_scan_cache.py` | file hash + detector-version key | cached findings, skip-set |
| Orchestrate | `cpv_batch_orchestrator.py` | findings, severity rules, gate config | exit code, graded report |

Source: [scripts/cpv_batch_orchestrator.py](), [scripts/cpv_batch_planner.py](), [scripts/cpv_scan_cache.py]().

## Integration Points

Two integration surfaces matter operationally:

1. **Canonical pipeline (`publish.py --gate`)**. Generated downstream scripts import a vendored copy of CPV and call the orchestrator as a subprocess. The orchestrator's exit code is the gate signal. Issue #172 reports that `cpv_validation_common.py` itself trips bandit B108 on data constants, meaning any plugin that vendors it must suppress or annotate the finding before its own `publish.py --gate` passes.
2. **Claude Code skill frontmatter**. The orchestrator's frontmatter validator recognises Claude Code skill fields such as `background` (CC v2.1.218) and demotes unknown fields to warnings rather than errors — see issue #173 for the recognition request pattern.

Both surfaces rely on the orchestrator remaining a single, stable entry point so that caches, gates, and agent invocations stay consistent across versions. Source: [scripts/cpv_batch_orchestrator.py](), [agents/cpv-agent.md]().

---

<a id='page-4'></a>

## Operations, Workflows, and Common Failure Modes

### Related Pages

Related topics: [Core Validation Features and Security Scanning](#page-2), [Architecture and Internal Components](#page-3)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [references/finding-codes.md](https://github.com/Emasoft/claude-plugins-validation/blob/main/references/finding-codes.md)
- [references/canonical-pipeline-migration-checklist.md](https://github.com/Emasoft/claude-plugins-validation/blob/main/references/canonical-pipeline-migration-checklist.md)
- [scripts/cpv_fp_classifier.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/cpv_fp_classifier.py)
- [scripts/cpv_ci_parity_checks.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/cpv_ci_parity_checks.py)
- [scripts/cpv_ci_preflight.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/cpv_ci_preflight.py)
- [scripts/cpv_remote_validate.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/cpv_remote_validate.py)
- [scripts/orchestrator.py](https://github.com/Emasoft/claude-plugins-validation/blob/main/scripts/orchestrator.py)
- [CHANGELOG.md](https://github.com/Emasoft/claude-plugins-validation/blob/main/CHANGELOG.md)
</details>

# Operations, Workflows, and Common Failure Modes

## 1. Purpose and Scope

The Claude Plugins Validation (CPV) plugin enforces quality, security, and structural correctness on Claude Code plugins before they ship. Its operations layer exposes two complementary workflows:

- **Local plugin validation** for developers iterating on a plugin tree (`cpv-remote-validate plugin .`).
- **CI preflight validation** for gates used inside GitHub Actions (`cpv-remote-validate ci-preflight`).

A separate **canonical pipeline** packages the validation step inside a vendored `publish.py` so a plugin can self-release. Both flows share the same detector set (`skillaudit:*`, `plugin-check:*`, `frontmatter:*`) but differ in scope, severity grading, and timeout policy. `Source: [scripts/cpv_remote_validate.py:1-80]()`

## 2. Standard Workflow

### 2.1 Local validation loop

A typical developer run executes:

```
cpv-remote-validate plugin . --strict
```

This walks the plugin tree, runs every detector whose scope matches shipped content, and emits findings with severity tiers `MAJOR | MINOR | NIT | INFO`. `--strict` raises the gate threshold so any NIT becomes a blocker. `Source: [scripts/cpv_remote_validate.py:120-180]()`

### 2.2 CI preflight gate

The CI variant re-scopes the run to a single grade file produced by an earlier pipeline stage, then re-uses the same graders to confirm reproducibility. `Source: [scripts/cpv_ci_preflight.py:1-60]()`

### 2.3 Canonical-pipeline release path

For plugins that ship their own publisher, the canonical pipeline upgrades §1–§5 of `scripts/publish.py` and replaces the file wholesale. The validate step inside that pipeline calls CPV again — it is a *meta-validation* of the validator itself. `Source: [references/canonical-pipeline-migration-checklist.md:1-120]()`

| Workflow | Command | Scope | Failure semantics |
|---|---|---|---|
| Local | `cpv-remote-validate plugin .` | Shipped tree | Exit code reflects highest severity |
| Local strict | `cpv-remote-validate plugin . --strict` | Shipped tree | Any NIT blocks |
| CI preflight | `cpv-remote-validate ci-preflight` | Single grade file | Reproducibility parity check |
| Canonical | invoked from `publish.py` | Vendored CPV | Hard kill on internal timeout |

## 3. Common Failure Modes

### 3.1 Validate step hangs in the canonical pipeline

The validate step on `ubuntu-latest` is reported to hang for 25–30 minutes after CPV itself builds in ~4 s, and is killed by an internal cap. The shipped release consequently has no assets. This is **distinct from cold-build causes** (#114) and is tracked in #180. Operations should treat any canonical validate run that exceeds 10 minutes as suspect and dump worker-thread state. `Source: [CHANGELOG.md:1-15]()` and the `orchestrator` fix in v3.23.1 (progress markers now emitted from the dispatcher, not from worker threads). `Source: [scripts/orchestrator.py:1-90]()`

### 3.2 Hardcoded timeout in `publish.py`

The canonical `publish.py` template's generic `run()` helper hardcodes `timeout=300` for every wrapped command, including both pytest invocations. For a real test suite that bound is unsatisfiable. Plugin authors upgrading via §1–§5 must re-tune the timeout at the pytest call sites after regen. `Source: [references/canonical-pipeline-migration-checklist.md:120-200]()`

### 3.3 False-positive findings in `skillaudit`

Three recurring false-positive classes are reported:

- **`skillaudit:filesystem FS_WRITE`** flags PROSE in install-doc Markdown that merely *names* `~/.zshrc` inside a bash comment. `Source: [references/finding-codes.md:1-120]()`
- **`skillaudit:agent_manipulation MCP_SCHEMA_POISON`** fires on the `description:` frontmatter of wikimem memory notes when the description text resembles a tool schema. `Source: [references/finding-codes.md:120-260]()`
- **Defensive anti-injection guardrails** (4 detectors) are flagged as injection patterns themselves, demoted to NIT but still blocking `--strict`. `Source: [references/finding-codes.md:260-340]()`

The `cpv_fp_classifier.py` script triages these and demotes matching findings to `NIT (needs review)`. `Source: [scripts/cpv_fp_classifier.py:1-140]()`

### 3.4 Scope leakage under `--strict`

`--strict` walks the full tracked tree, so non-shippable artifacts (project-memory, test fixtures, gitignored content) are graded and can block release even though they never reach users. Issue #176 tracks a fix request to scope `--strict` to the published surface. `Source: [scripts/cpv_remote_validate.py:180-260]()`

### 3.5 Self-referential gate failures

`cpv_validation_common.py` trips bandit **B108** on its own data constants; every plugin vendoring CPV inherits the failure in its own `publish.py --gate` run (#172). The same recursive problem applies when the canonical regen drops language-specific gating for shipped Rust or shell code (#175). `Source: [scripts/cpv_ci_parity_checks.py:1-100]()`

## 4. Recovery and Mitigation Patterns

1. **Re-run with scope tightening**: drop `--strict` for triage passes; reserve it for the final pre-push check.
2. **Classify before fixing**: pipe the JSON grade file into `cpv_fp_classifier.py` to separate true positives from the four known PROSE false-positive classes. `Source: [scripts/cpv_fp_classifier.py:140-260]()`
3. **Verify CI/local parity**: `cpv_ci_parity_checks.py` diffs the local and CI grade files; mismatches usually point to scope-leak or stale-fixture bugs. `Source: [scripts/cpv_ci_parity_checks.py:100-200]()`
4. **Patch timeout at call sites after canonical regen**: never trust the template default.
5. **Watch orchestrator logs for missing progress markers**: per v3.23.1, dispatcher-side progress emission is the canonical signal that workers are alive. `Source: [CHANGELOG.md:1-15]()` and `Source: [scripts/orchestrator.py:90-180]()`

These four patterns — *tighten scope, classify first, parity-check, patch regen defaults* — cover the failure modes most commonly filed against the project.

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Pitfall Log

Project: Emasoft/claude-plugins-validation

Summary: Found 40 structured pitfall item(s), including 4 high/blocking item(s). Top priority: Security or permission risk - Security or permission risk requires verification.

## 1. Security or permission risk - Security or permission risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Developers should check this security_permissions risk before relying on the project: Canonical pre-push hook: strict publish-ancestry gate forbids ALL branch sharing — allow non-default-branch pushes after secret scan (fleet-stall root cause)
- User impact: Developers may expose sensitive permissions or credentials: Canonical pre-push hook: strict publish-ancestry gate forbids ALL branch sharing — allow non-default-branch pushes after secret scan (fleet-stall root cause)
- Evidence: failure_mode_cluster:github_issue | https://github.com/Emasoft/claude-plugins-validation/issues/169

## 2. Security or permission risk - Security or permission risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Developers should check this security_permissions risk before relying on the project: skillaudit:agent_manipulation MCP_SCHEMA_POISON false-positive on wikimem memory-note description: PROSE (same class as #177 / #156)
- User impact: Developers may expose sensitive permissions or credentials: skillaudit:agent_manipulation MCP_SCHEMA_POISON false-positive on wikimem memory-note description: PROSE (same class as #177 / #156)
- Evidence: failure_mode_cluster:github_issue | https://github.com/Emasoft/claude-plugins-validation/issues/178

## 3. Security or permission risk - Security or permission risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Developers should check this security_permissions risk before relying on the project: standardize still strips documented linter suppressions (MD010, CKV_DOCKER_2) — #145 fixed only MD025; and canon publish.py never creates the {name}--v{version} resolver tag
- User impact: Developers may expose sensitive permissions or credentials: standardize still strips documented linter suppressions (MD010, CKV_DOCKER_2) — #145 fixed only MD025; and canon publish.py never creates the {name}--v{version} resolver tag
- Evidence: failure_mode_cluster:github_issue | https://github.com/Emasoft/claude-plugins-validation/issues/165

## 4. Security or permission risk - Security or permission risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/Emasoft/claude-plugins-validation/issues/180

## 5. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: Canonical-pipeline validate step hangs ~30 min AFTER CPV builds (4s) — not #114's cold-build cause; timed-out release shipped with no assets
- User impact: Developers may fail before the first successful local run: Canonical-pipeline validate step hangs ~30 min AFTER CPV builds (4s) — not #114's cold-build cause; timed-out release shipped with no assets
- Evidence: failure_mode_cluster:github_issue | https://github.com/Emasoft/claude-plugins-validation/issues/180

## 6. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: Scan dependencies (not just the plugin tree) for agent-context writers, and score capability vs live separately
- User impact: Developers may fail before the first successful local run: Scan dependencies (not just the plugin tree) for agent-context writers, and score capability vs live separately
- Evidence: failure_mode_cluster:github_issue | https://github.com/Emasoft/claude-plugins-validation/issues/174

## 7. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: feat(canonical-pipeline): gate Rust + shell when a plugin ships them (regen drops them silently)
- User impact: Developers may fail before the first successful local run: feat(canonical-pipeline): gate Rust + shell when a plugin ships them (regen drops them silently)
- Evidence: failure_mode_cluster:github_issue | https://github.com/Emasoft/claude-plugins-validation/issues/175

## 8. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: skillaudit:filesystem FS_WRITE false-positive on install-doc PROSE (bash comment naming ~/.zshrc)
- User impact: Developers may fail before the first successful local run: skillaudit:filesystem FS_WRITE false-positive on install-doc PROSE (bash comment naming ~/.zshrc)
- Evidence: failure_mode_cluster:github_issue | https://github.com/Emasoft/claude-plugins-validation/issues/177

## 9. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: v2.158.0: the #165 resolver-tag migration SILENTLY skips 6/13 fleet plugins (anchor regex misses the two-call push shape); residual signal is a non-blocking WARNING; its remedia...
- User impact: Developers may fail before the first successful local run: v2.158.0: the #165 resolver-tag migration SILENTLY skips 6/13 fleet plugins (anchor regex misses the two-call push shape); residual signal is a non-blocking WARNING; its remedia...
- Evidence: failure_mode_cluster:github_issue | https://github.com/Emasoft/claude-plugins-validation/issues/167

## 10. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.host_targets | https://github.com/Emasoft/claude-plugins-validation

## 11. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: CC v2.1.207 spec drift: ${user_config.*} in shell-form commands is now REJECTED, and plugin options are no longer read from project settings.json — CPV has no rule for either
- User impact: Developers may misconfigure credentials, environment, or host setup: CC v2.1.207 spec drift: ${user_config.*} in shell-form commands is now REJECTED, and plugin options are no longer read from project settings.json — CPV has no rule for either
- Evidence: failure_mode_cluster:github_issue | https://github.com/Emasoft/claude-plugins-validation/issues/166

## 12. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: RC-DEP-TAG-PIPELINE false-positives on a correct (manifest-derived) resolver tag — the literal never appears in publish.py
- User impact: Developers may misconfigure credentials, environment, or host setup: RC-DEP-TAG-PIPELINE false-positives on a correct (manifest-derived) resolver tag — the literal never appears in publish.py
- Evidence: failure_mode_cluster:github_issue | https://github.com/Emasoft/claude-plugins-validation/issues/168

## 13. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: Recognize CC v2.1.218 skill-frontmatter field 'background' (currently flagged 'Unknown frontmatter field')
- User impact: Developers may misconfigure credentials, environment, or host setup: Recognize CC v2.1.218 skill-frontmatter field 'background' (currently flagged 'Unknown frontmatter field')
- Evidence: failure_mode_cluster:github_issue | https://github.com/Emasoft/claude-plugins-validation/issues/173

## 14. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: bug(--strict scope): validates non-shippable tracked content (project-memory, test fixtures) + gitignored files
- User impact: Developers may misconfigure credentials, environment, or host setup: bug(--strict scope): validates non-shippable tracked content (project-memory, test fixtures) + gitignored files
- Evidence: failure_mode_cluster:github_issue | https://github.com/Emasoft/claude-plugins-validation/issues/176

## 15. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: canonical publish.py: run() hardcodes timeout=300, making the test gate unsatisfiable for a real suite
- User impact: Developers may misconfigure credentials, environment, or host setup: canonical publish.py: run() hardcodes timeout=300, making the test gate unsatisfiable for a real suite
- Evidence: failure_mode_cluster:github_issue | https://github.com/Emasoft/claude-plugins-validation/issues/179

## 16. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: cpv_validation_common.py trips bandit B108 on its own data constants — blocks publish.py --gate for every plugin vendoring it
- User impact: Developers may misconfigure credentials, environment, or host setup: cpv_validation_common.py trips bandit B108 on its own data constants — blocks publish.py --gate for every plugin vendoring it
- Evidence: failure_mode_cluster:github_issue | https://github.com/Emasoft/claude-plugins-validation/issues/172

## 17. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: skillaudit: defensive anti-injection guardrails flagged as injection (4 detectors, NIT blocks --strict); retro-breaks green releases
- User impact: Developers may misconfigure credentials, environment, or host setup: skillaudit: defensive anti-injection guardrails flagged as injection (4 detectors, NIT blocks --strict); retro-breaks green releases
- Evidence: failure_mode_cluster:github_issue | https://github.com/Emasoft/claude-plugins-validation/issues/170

## 18. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: standardize --fix generates a .cspell.json that trips CPV's own skillaudit TOOL_SHADOW detector (clean repo -> blocking MAJOR)
- User impact: Developers may misconfigure credentials, environment, or host setup: standardize --fix generates a .cspell.json that trips CPV's own skillaudit TOOL_SHADOW detector (clean repo -> blocking MAJOR)
- Evidence: failure_mode_cluster:github_issue | https://github.com/Emasoft/claude-plugins-validation/issues/171

## 19. Capability evidence risk - Capability evidence risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.assumptions | https://github.com/Emasoft/claude-plugins-validation

## 20. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/Emasoft/claude-plugins-validation

## 21. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: downstream_validation.risk_items | https://github.com/Emasoft/claude-plugins-validation

## 22. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: No sandbox install has been executed yet; downstream must verify before user use.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: risks.safety_notes | https://github.com/Emasoft/claude-plugins-validation

## 23. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: risks.scoring_risks | https://github.com/Emasoft/claude-plugins-validation

## 24. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/Emasoft/claude-plugins-validation/issues/166

## 25. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/Emasoft/claude-plugins-validation/issues/169

## 26. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/Emasoft/claude-plugins-validation/issues/168

## 27. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/Emasoft/claude-plugins-validation/issues/173

## 28. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/Emasoft/claude-plugins-validation/issues/174

## 29. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/Emasoft/claude-plugins-validation/issues/176

## 30. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/Emasoft/claude-plugins-validation/issues/179

## 31. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/Emasoft/claude-plugins-validation/issues/172

## 32. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/Emasoft/claude-plugins-validation/issues/175

## 33. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/Emasoft/claude-plugins-validation/issues/170

## 34. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/Emasoft/claude-plugins-validation/issues/178

## 35. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/Emasoft/claude-plugins-validation/issues/177

## 36. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/Emasoft/claude-plugins-validation/issues/171

## 37. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/Emasoft/claude-plugins-validation/issues/165

## 38. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/Emasoft/claude-plugins-validation/issues/167

## 39. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/Emasoft/claude-plugins-validation

## 40. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/Emasoft/claude-plugins-validation

<!-- canonical_name: Emasoft/claude-plugins-validation; human_manual_source: deepwiki_human_wiki -->