1---2name: pipeline-auditor-protocol3description: Loaded by the pipeline-auditor agent to audit Superpipelines pipeline bundles against compliance, CAD, topology, and bundle hygiene rules.4---56# Pipeline Auditor — Operational Protocol78<glossary>9 <term name="Compliance Matrix">The full checklist in `compliance-matrix.md` covering layout, frontmatter, topology, runtime safety (criteria 1–25), and resolver consolidation (PR-01..PR-05, PR-07..PR-10).</term>10 <term name="Severity Bands">Classification levels from SEV-0 (Critical/Blocking) to SEV-3 (Informational/Style).</term>11 <term name="Audit Report">A generated Markdown document summarizing findings with quoted evidence and remediation paths.</term>12</glossary>1314<invariant>15The Auditor is strictly read-only; it cannot modify files. Remediation must be routed to the `pipeline-architect`.16</invariant>1718## Operating Modes1920<operating_modes>21| Mode | Trigger | Scope |22| :--- | :--- | :--- |23| **FULL** | Direct invocation or first audit. | Entire pipeline bundle: all agents, skills, and topology. |24| **DELTA** | Triggered by mutation commands. | Changed files plus immediate neighbors and the entry skill. |25| **SCOPE-WIDE** | `audit-steps --all` command. | FULL audit across all registered pipelines in all scope roots. |26</operating_modes>2728## Workflow2930<protocol>31### 1. LOCATE32- Resolve paths via `sk-pipeline-paths`.33- **FULL**: Glob all agents and skills; read `topology.json` and the registry.34- **DELTA**: Target only changed files and their graph neighbors.35- **SCOPE-WIDE**: Iterate through all scope roots and registered pipelines.3637### 2. AUDIT38- **Detect layout FIRST**: determine whether the bundle is **data-only** (CAD agents + `entry.md` under `.superpipelines/pipelines/{P}/`) or **legacy old-root** (zero-body agents + `run-{P}` skill under tool dirs), per `references/compliance-matrix.md` § "Pipeline layout & criterion applicability". Apply criteria by layout: legacy layout/frontmatter/Lean-Agent criteria (1, 4, 5, 8, 9, 10, 10a, 19) are **N/A on data-only** — CAD-01..CAD-10 govern there instead. Never FAIL a conformant CAD against a legacy-only criterion.39- **Compliance Matrix**: Execute the full compliance check in `references/compliance-matrix.md` (criteria 1-25 including 10a, resolver consolidation criteria PR-01..PR-05 and PR-07..PR-10, canonical agent-def criteria CAD-01..CAD-10, and bundle-maintenance criteria BUNDLE-01..BUNDLE-07 when auditing the Superpipelines bundle), honoring the layout applicability table.40- **Topology Rules**: Verify graph validity, agent coverage, and edge consistency via `references/topology-rules.md`.41- Assign severity per `references/severity-classification.md` and select fixes from `references/fix-templates.md`.4243### 3. REPORT44- The auditor is read-only (`disallowedTools: Write, Edit, Bash`) and NEVER writes the report file or mutates `registry.json`. Persistence is the orchestrator's responsibility (see `commands/audit-steps.md` REPORTING).45- Render the full report per `references/audit-report-template.md` as inline output in the agent's response, together with the executive summary.46- Hand the orchestrator an explicit registry-update instruction: the target `audit/latest.md` path and the `last_audit` timestamp value to record.47- Record every audit, even those with zero findings.4849### 4. FIX ROUTING50- Auditor remains read-only.51- **SEV-0/1**: Route to `pipeline-architect` with the remediation plan.52- **SEV-2/3**: Surface to the user for manual decision.5354### Model-Tier Resolution Criteria (v2.0)5556| ID | Criterion | SEV | Detection |57|---|---|---|---|58| MT-01 | Hardcoded model ID in skill body | SEV-2 | `grep -E "claude-(sonnet\|opus\|haiku)-[0-9]\|gpt-5\.[0-9]\|gemini-3\." skills/**/SKILL.md skills/**/references/*.md` returns matches outside `skills/sk-platform-dispatch/profiles/` |59| MT-02 | Agent missing both `model_tier:` and `model:` | SEV-1 | Agent frontmatter has neither field. Runtime resolver tolerates (defaults to `fast`) but scaffold-time auditor blocks: explicit declaration required for v2.0+ agents. |60| MT-03 | Agent has explicit `model:` without comment justification | SEV-3 | Escape hatch in use. Surface to reviewer; do not block. Distinguish by `plugin_version`: if absent or `< 2.0.0` → v1 legacy (Phase 0.45 migrates automatically); if `>= 2.0.0` → intentional v2 escape hatch (advisory only). |61| MT-04 | Profile JSON missing `model_tiers_version` field | SEV-2 | Required for drift detection. |62| MT-05 | Preference file references a model not in any profile's catalog | SEV-2 | Compare every `prefs.platforms[*].tiers[*]` value against the union of all profiles' `model_tiers[*].model`. Mismatch likely typo or stale ID. |63| MT-06 | Agent has `effort_tier:` set on a platform with `effort_field_name == null` | SEV-3 | Effort will be silently ignored on this platform — inform user. Detection requires knowing the source/runtime tier. |6465### Resolution6667- MT-01: Move the hardcoded ID to a profile JSON; reference via `platform_profile.model_tiers[tier]`.68- MT-02: Add `model_tier:` to the agent (architect should have done this in Phase 4).69- MT-03: Add a comment line above `model:` documenting WHY the escape hatch is needed.70- MT-04: Add `"model_tiers_version": "YYYY-MM-DD"` to the profile.71- MT-05: Run `/superpipelines:change-models` Mode F (catalog refresh) to reconcile.72- MT-06: Either drop `effort_tier:` or accept that it's a no-op on this platform.73</protocol>7475<invariants>76- Cite `file:line` and quote evidence verbatim for every finding.77- DELTA mode must ignore findings outside the changed scope to prevent unrelated blocking.78- NEVER skip the compliance matrix checks, regardless of file appearance.79- NEVER create or modify pipeline components directly.80- Criterion 22 (PORTABILITY CHECK) applies in FULL and DELTA modes. FULL scope: all agents, skills, and topology.json. DELTA scope: changed files only — PLUS the entry skill unconditionally (entry skill is always in scope for portability checks regardless of which files changed).81</invariants>8283## Reference Files8485- `${CLAUDE_PLUGIN_ROOT}/skills/pipeline-auditor-references/references/compliance-matrix.md`86- `${CLAUDE_PLUGIN_ROOT}/skills/pipeline-auditor-references/references/canonical-agent-def.md`87- `${CLAUDE_PLUGIN_ROOT}/skills/pipeline-auditor-references/references/topology-rules.md`88- `${CLAUDE_PLUGIN_ROOT}/skills/pipeline-auditor-references/references/severity-classification.md`89- `${CLAUDE_PLUGIN_ROOT}/skills/pipeline-auditor-references/references/audit-report-template.md`90- `${CLAUDE_PLUGIN_ROOT}/skills/pipeline-auditor-references/references/fix-templates.md`
gustavo-meilus