return False, ["INTEGRITY.json not found"]

manifest = json.loads(manifest_path.read_text())
recorded = manifest.get("files", {})
errors = []

# Check recorded files
for rel_path, expected_hash in recorded.items():
    full = root / rel_path
    if not full.exists():
        errors.append(f"MISSING: {rel_path}")
        continue
    actual = hash_file(full)
    if actual != expected_hash:
        errors.append(f"MODIFIED: {rel_path}")

# Check for new untracked files
current = generate_manifest(plugin_dir)
for rel_path in current["files"]:
    if rel_path not in recorded:
        errors.append(f"UNTRACKED: {rel_path}")

return len(errors) == 0, errors

Verify

passed, errors = verify_manifest("my-plugin/") if passed: print("VERIFIED: All files match manifest") else: print(f"FAILED: {len(errors)} issue(s)") for e in errors: print(f" {e}")

**Output on tampered plugin:**

FAILED: 3 issue(s) MODIFIED: skills/search/SKILL.md MISSING: agency.json UNTRACKED: backdoor.py

---

## Pattern 3: Dependency Version Audit

Check that agent dependencies use pinned versions.

```python
import re

def audit_versions(config_path: str) -> list[dict]:
    """Audit dependency version pinning in a config file."""
    findings = []
    path = Path(config_path)
    content = path.read_text()

    if path.name == "package.json":
        data = json.loads(content)
        for section in ("dependencies", "devDependencies"):
            for pkg, ver in data.get(section, {}).items():
                if ver.startswith("^") or ver.startswith("~") or ver == "*" or ver == "latest":
                    findings.append({
                        "package": pkg,
                        "version": ver,
                        "severity": "HIGH" if ver in ("*", "latest") else "MEDIUM",
                        "fix": f'Pin to exact: "{pkg}": "{ver.lstrip("^~")}"'
                    })

    elif path.name in ("requirements.txt", "pyproject.toml"):
        for line in content.splitlines():
            line = line.strip()
            if ">=" in line and "<" not in line:
                findings.append({
                    "package": line.split(">=")[0].strip(),
                    "version": line,
                    "severity": "MEDIUM",
                    "fix": f"Add upper bound: {line},<next_major"
                })

    return findings

---

Pattern 4: Promotion Gate

Use integrity verification as a gate before promoting plugins.

def promotion_check(plugin_dir: str) -> dict:
    """Check if a plugin is ready for production promotion."""
    checks = {}

    # 1. Integrity manifest exists and verifies
    passed, errors = verify_manifest(plugin_dir)
    checks["integrity"] = {
        "passed": passed,
        "errors": errors
    }

    # 2. Required files exist
    root = Path(plugin_dir)
    required = ["README.md"]
    missing = [f for f in required if not (root / f).exists()]

    # Require at least one plugin manifest (supports both layouts)
    manifest_paths = [
        root / ".github/plugin/plugin.json",
        root / ".claude-plugin/plugin.json",
    ]
    if not any(p.exists() for p in manifest_paths):
        missing.append(".github/plugin/plugin.json (or .claude-plugin/plugin.json)")

    checks["required_files"] = {
        "passed": len(missing) == 0,
        "missing": missing
    }

    # 3. No unpinned dependencies
    mcp_path = root / ".mcp.json"
    if mcp_path.exists():
        config = json.loads(mcp_path.read_text())
        unpinned = []
        for server in config.get("mcpServers", {}).values():
            if isinstance(server, dict):
                for arg in server.get("args", []):
                    if isinstance(arg, str) and "@latest" in arg:
                        unpinned.append(arg)
        checks["pinned_deps"] = {
            "passed": len(unpinned) == 0,
            "unpinned": unpinned
        }

    # Overall
    all_passed = all(c["passed"] for c in checks.values())
    return {"ready": all_passed, "checks": checks}

result = promotion_check("my-plugin/")
if result["ready"]:
    print("Plugin is ready for production promotion")
else:
    print("Plugin NOT ready:")
    for name, check in result["checks"].items():
        if not check["passed"]:
            print(f"  FAILED: {name}")

---

CI Integration

Add to your GitHub Actions workflow:

- name: Verify plugin integrity
  run: |
    PLUGIN_DIR="${{ matrix.plugin || '.' }}"
    cd "$PLUGIN_DIR"
    python -c "
    from pathlib import Path
    import json, hashlib, sys

    def hash_file(p):
        h = hashlib.sha256()
        with open(p, 'rb') as f:
            for c in iter(lambda: f.read(8192), b''):
                h.update(c)
        return h.hexdigest()

    manifest = json.loads(Path('INTEGRITY.json').read_text())
    errors = []
    for rel, expected in manifest['files'].items():
        p = Path(rel)
        if not p.exists():
            errors.append(f'MISSING: {rel}')
        elif hash_file(p) != expected:
            errors.append(f'MODIFIED: {rel}')
    if errors:
        for e in errors:
            print(f'::error::{e}')
        sys.exit(1)
    print(f'Verified {len(manifest[\"files\"])} files')
    "

---

Best Practices

Practice	Rationale
Generate manifest after code review	Ensures reviewed code matches production code
Include manifest in the PR	Reviewers can verify what was hashed
Verify in CI before deploy	Catches post-review modifications
Chain hash for tamper evidence	Single hash represents entire plugin state
Exclude build artifacts	Only hash source files — .git, pycache, node_modules excluded
Pin all dependency versions	Unpinned deps = different code on every install

---

Related Resources

• OpenSSF SLSA — Supply-chain Levels for Software Artifacts
• npm Provenance — Sigstore-based package provenance
• Agent Governance Toolkit — Includes integrity verification and plugin signing
• OWASP ASI-09: Supply Chain Integrity