Protocol Verification

Protocol Verification

Verify epistemic protocol consistency before commit through static checks and expert review.

Purpose

Surface potential issues in protocol definitions without blocking commits. Follow Anthropic philosophy: transparency over enforcement, user agency over automation.

Core Principles

Workflow

Phase 1: Static Checks

Run scripts/​static-checks.js against project root. This script executes without loading into context.

node ${SKILL_DIR}/​scripts/​static-checks.js ${PROJECT_ROOT}

Output format:

{
  "pass": [{ "check": "...", "file": "...", "message": "..." }],
  "fail": [{ "check": "...", "file": "...", "message": "..." }],
  "warn": [{ "check": "...", "file": "...", "message": "..." }]
}

Checks performed:

• JSON schema validation (plugin.json required fields, version format)
• Unicode notation consistency (→ not ->, ∥, ∩)
• Directive verb enforcement (call not invoke/use for tools)
• Cross-reference integrity (CLAUDE.md ↔ source files)
• Required sections in protocols (Definition, Mode Activation, Protocol, Rules)
• Tool grounding consistency (TOOL GROUNDING ↔ PHASE TRANSITIONS)
• Version staleness detection (content changes without version bump)
• Graph integrity (node/​edge validation, orphaned nodes, isolated nodes, DAG acyclicity)
• Spec-vs-impl drift (TYPES definitions ↔ PHASE TRANSITIONS/​prose usage, resolution type consistency)
• Morphism anatomy (FLOW → MORPHISM → TYPES order; deficit-as-precondition; required clauses requires/​deficit/​preserves/​invariant; canonical resolution target; Type signature)
• Cross-reference scan (protocol name consistency, deficit → resolution pairs, distinction table completeness, edge type allowlist)
• Onboard sync, precedence linear extension, partition invariant, catalog sync
• Gate type soundness (warning-level safeguard for coproduct/​prose option alignment)
• Artifact self-containment (runtime-contract view: packaged Skill.md + plugin description metadata + packaged support references). Severity-aware BANNED patterns: strict patterns (mission-bridge, axioms, derived-principles, architectural-principles, meta-principle, safeguards, A1-A7 identifiers, .claude/, docs/) surface as fail; expansion patterns (project-profile, editing-conventions, principles/, design-philosophy concepts — Stage 1/​2, Tier Factorization, Deficit Empiricism, Wirkungsgeschichte, Horizontverschmelzung, Zuhandenheit) surface as warn under Stage 1 posture
• Emit load discipline (compiled-copy coverage for Context-Question Separation, Plain emit discipline, and Round-local salience bundling across all core protocol SKILL.md files, plus Output Style source coverage)
• Framing-readout enforcement (Epistemic Ink invariant: protocol surfacing is a framing readout, not a progress meter — bans the ▓/░ progress-bar glyphs in every core protocol SKILL.md and the Output Style source, and requires the categorical-ban guard sentence to stay inscribed in the Output Style)
• Language purity (warn-level Korean character detection across project text files; whitelist preserves intentional Korean regions: **/​README_ko.md, .claude/​skills/​release/, src/, docs/, .claude/​rules/​editing-conventions.md)
• Packaged-agent contract sync (each packaged agent with a ### Realization: verdict anchor reconciled against its paired SKILL.md — realization set, advisory vocabulary, checklist categories; for an F5 zero-memory-verdict contract also the verdict-table column schema locked bidirectionally against the EvidencedFinding/SweepTrace TYPES records)

Phase 2: Expert Review

Spawn parallel Task subagents for LLM-based review. Each perspective analyzes independently.

Perspective 1: Type Design

Spawn Task subagent with prompt:

You are a Type Theory Expert analyzing protocol type design.

**Soundness check**:
- Type signatures: well-formed domain/​codomain
- State machines: transition totality
- Flow consistency: types match phase transitions
- Tool grounding: TOOL GROUNDING ↔ PHASE TRANSITIONS consistency

**Tool Grounding check**:
- External operations (dispatch) have corresponding [Tool] notation in PHASE TRANSITIONS
- Internal operations marked with "no external tool"
- Escape behavior semantics match protocol context (fallback/​Silence/​cancel)

**Necessity check**:
- Cardinality constraints (|P| ≥ 2): prose sufficient given Esc interrupt?
- Refinement types: marginal benefit for LLM interpretation?
- Principle: no type checker exists; social enforcement via prose is primary

Files: prothesis/​skills/​frame/​SKILL.md, syneidesis/​skills/​gap/​SKILL.md, horismos/​skills/​bound/​SKILL.md

Focus on Definition sections (FLOW, TYPES, PHASES, TOOL GROUNDING). Output JSON with findings array.

Perspective 2: Specification Clarity

Spawn Task subagent with prompt:

You are a Specification Clarity Expert analyzing LLM interpretability.

**LLM behavior modification**:
- Activation clarity: trigger conditions unambiguous
- Priority conflicts: supersession domain overlap
- Instruction parsability: rules actionable without implicit reasoning
- Tool binding clarity: TOOL GROUNDING section readable and actionable

**Notation complexity**:
- Flow formulas: understandable at a glance?
- Standard notation preferred (|P| ≥ 2) over custom constructors (Set²⁺)
- Section structure: FLOW → TYPES → PHASES → TOOL GROUNDING → STATE sufficient?
- [Tool] notation in PHASE TRANSITIONS: adds clarity or noise?

Principle: specification is for human/​LLM comprehension, not compiler verification.

Files: prothesis/​skills/​frame/​SKILL.md, syneidesis/​skills/​gap/​SKILL.md, horismos/​skills/​bound/​SKILL.md, CLAUDE.md

Focus on Definition, Mode Activation, Priority, Rules, TOOL GROUNDING sections. Output JSON with findings array.

Perspective 3: Claude Code Ecosystem

Spawn Task subagent with prompt:

You are a Claude Code Ecosystem Expert.

**Pattern validation**:
- Gate mandates enforced (structured presentation + turn yield, not unstructured bypass)
- Epistemic transitions correctly typed (deficit → resolved type signatures)
- User agency preserved (no automatic decisions)

**False positive filtering** (dismiss concerns from other perspectives):
- "Automatic intensity reduction" → not needed (gate interaction provides control)
- "Automatic deactivation" → not needed (user can interrupt via Esc)
- "Topic boundary detection" → context-dependent (model judgment acceptable)
- "Type-level cardinality" → prose sufficient (low violation cost, Esc recovery)

Files: prothesis/​skills/​frame/​SKILL.md, syneidesis/​skills/​gap/​SKILL.md, horismos/​skills/​bound/​SKILL.md, CLAUDE.md

Focus on Mode Activation, Rules, UX patterns. Output JSON with findings and filtered arrays.

All three subagents run in parallel. Collect results before proceeding.

Phase 3: Synthesize Findings

Combine static check results with expert review findings. Categorize by severity:

Identify convergence (all perspectives agree) and divergence (perspectives differ).

Apply Claude Code Ecosystem expert's filtered array to dismiss false positives from other perspectives.

Phase 4: Surface via Gate Interaction

Present findings via gate interaction. Format:

## Verification Results

### Critical (n issues)
- [issue 1]: [location] - [description]
- [issue 2]: [location] - [description]

### Concerns (n issues)
- [issue 1]: [location] - [description]

### Notes (n observations)
- [observation 1]

### Filtered (Claude Code context)
- [filtered issue]: [reason dismissed]

---
Select action:

Options to present:

1. Fix critical issues - Address critical findings before commit
2. Review concerns - Examine each concern individually
3. Proceed anyway - Commit with decision logged
4. Cancel - Abort verification

Phase 5: Handle User Decision

Commit message annotation (if proceeding with issues):

[verify: n critical, m concerns acknowledged]

Severity Reference

Consult references/​criteria.md for detailed severity definitions and decision matrix.

Review Checklists

Consult references/​review-checklists.md for:

• Type Design expert prompt template
• Specification Clarity expert prompt template
• Claude Code Ecosystem expert prompt template
• Known issues checklist
• Synthesis template

Error Handling

Integration Notes

With Prothesis

Verification may trigger perspective selection if findings require analysis approach decision.

With Syneidesis

Critical findings surface as high-stakes gaps. Syneidesis gap detection may augment verification.

Standalone Usage

Most common pattern: invoke /​verify before /​commit command.

Output Examples

Clean State

## Verification Results

All checks passed.

- Static checks: 16 pass, 0 fail, 0 warn
- Type/​Category review: No issues
- Instruction Design review: No issues

Ready to commit.

Issues Found

## Verification Results

### Critical (1 issue)
- State machine totality: prothesis.md:10 - Undefined transition when |perspectives(C)| < 2

### Concerns (2 issues)
- Categorical terminology: prothesis.md:35 - limit/​colimit may not match intended semantics
- Directive verb: prothesis/​skills/​frame/​SKILL.md:32 - "Invoke AskUserQuestion" should be "call"

### Notes (1 observation)
- Version: prothesis plugin.json version not bumped since last change

---
How to proceed?