Back to Details

integrity-validation

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Integrity Validation System

完整性验证系统

Overview

概述

The Integrity Validation System prevents future component loss by:
  • Pre-operation inventory taking
  • Post-operation verification
  • Automatic detection of missing components
  • Immediate alerts for discrepancies
完整性验证系统通过以下方式防止未来组件丢失：
  • 操作前清单盘点
  • 操作后验证
  • 自动检测缺失组件
  • 针对差异发出即时警报

Core Components

核心组件

1. Pre-Operation Validation

1. 操作前验证

python
undefined
python
undefined

Before any major operation (restructuring, refactoring, migration)

在任何重大操作（重构、代码优化、迁移）之前

pre_operation_inventory = { "agents": list_all_agents(), "commands": list_all_commands(), "skills": list_all_skills(), "patterns": list_all_patterns(), "critical_files": identify_critical_files() }
pre_operation_inventory = { "agents": list_all_agents(), "commands": list_all_commands(), "skills": list_all_skills(), "patterns": list_all_patterns(), "critical_files": identify_critical_files() }

Store snapshot

存储快照

store_validation_snapshot("pre_operation", pre_operation_inventory)
undefined
store_validation_snapshot("pre_operation", pre_operation_inventory)
undefined

2. Post-Operation Validation

2. 操作后验证

python
undefined
python
undefined

After operation completes

操作完成后

post_operation_inventory = { "agents": list_all_agents(), "commands": list_all_commands(), "skills": list_all_skills(), "patterns": list_all_patterns(), "critical_files": identify_critical_files() }
post_operation_inventory = { "agents": list_all_agents(), "commands": list_all_commands(), "skills": list_all_skills(), "patterns": list_all_patterns(), "critical_files": identify_critical_files() }

Compare and report discrepancies

对比并报告差异

differences = compare_inventories(pre_operation_inventory, post_operation_inventory) if differences.missing_components: alert_missing_components(differences) suggest_recovery_options(differences)
undefined
differences = compare_inventories(pre_operation_inventory, post_operation_inventory) if differences.missing_components: alert_missing_components(differences) suggest_recovery_options(differences)
undefined

3. Critical Components Registry

3. 关键组件注册表

Critical Components (must exist):
  • All commands in categories (dev/, analyze/, validate/, debug/, learn/, workspace/, monitor/)
  • Core agents (orchestrator, code-analyzer, quality-controller, test-engineer)
  • Essential skills (pattern-learning, code-analysis, quality-standards)
  • Plugin manifest (.claude-plugin/plugin.json)
Warning Components (should exist):
  • Documentation files (README.md, STRUCTURE.md)
  • Configuration files
  • Helper scripts (lib/ directory)
Optional Components (nice to have):
  • Example files
  • Test files
  • Development tools
必须存在的关键组件:
  • 所有分类下的commands（dev/、analyze/、validate/、debug/、learn/、workspace/、monitor/）
  • 核心agents（orchestrator、code-analyzer、quality-controller、test-engineer）
  • 必备skills（pattern-learning、code-analysis、quality-standards）
  • 插件清单文件（.claude-plugin/plugin.json）
建议存在的警告组件:
  • 文档文件（README.md、STRUCTURE.md）
  • 配置文件
  • 辅助脚本（lib/目录）
可选组件（锦上添花）:
  • 示例文件
  • 测试文件
  • 开发工具

Validation Rules

验证规则

Pre-Operation Rules

操作前规则

  1. Mandatory Inventory: Must capture all components before any major operation
  2. Critical Identification: Mark components that cannot be lost
  3. Baseline Creation: Establish known-good state
  4. Backup Trigger: Auto-trigger backup for critical components
  1. 强制清单: 任何重大操作前必须捕获所有组件
  2. 关键标识: 标记不可丢失的组件
  3. 基线创建: 建立已知良好状态
  4. 备份触发: 自动触发关键组件的备份

Post-Operation Rules

操作后规则

  1. Immediate Validation: Run within 5 seconds of operation completion
  2. Difference Detection: Identify missing, added, or modified components
  3. Severity Assessment: Classify issues (critical, warning, info)
  4. Auto-Recovery: Offer automatic restoration for critical components
  1. 即时验证: 操作完成后5秒内运行
  2. 差异检测: 识别缺失、新增或修改的组件
  3. 严重程度评估: 对问题进行分类（关键、警告、信息）
  4. 自动恢复: 为关键组件提供自动恢复选项

Alert Classification

警报分类

  • CRITICAL: Core agents or commands missing (immediate action required)
  • HIGH: Essential skills or patterns missing (action recommended)
  • MEDIUM: Documentation or configuration missing (investigate)
  • LOW: Optional components missing (note for next release)
  • CRITICAL（关键）: 核心agents或commands缺失（需立即处理）
  • HIGH（高优先级）: 必备skills或patterns缺失（建议处理）
  • MEDIUM（中优先级）: 文档或配置缺失（需调查）
  • LOW（低优先级）: 可选组件缺失（记录到下一版本）

Integration Points

集成点

Major Operations That Require Validation

需要验证的重大操作

  • /workspace:improve
    - Plugin modifications
  • /dev:release
    - Release preparation
  • Command restructuring or categorization
  • Agent or skill modifications
  • File system reorganization
  • /workspace:improve
    - 插件修改
  • /dev:release
    - 发布准备
  • 命令重构或分类
  • Agent或Skill修改
  • 文件系统重组

Automatic Triggers

自动触发条件

  • File operations in commands/ directory
  • Modifications to agents/ directory
  • Changes to skills/ directory
  • Plugin manifest updates
  • commands/目录下的文件操作
  • agents/目录的修改
  • skills/目录的变更
  • 插件清单更新

Implementation Architecture

实现架构

Validation Flow

验证流程

python
async def validate_operation_integrity(operation_type):
    # 1. Pre-operation snapshot
    pre_snapshot = await create_inventory_snapshot()

    # 2. Execute operation
    await execute_operation(operation_type)

    # 3. Post-operation validation
    post_snapshot = await create_inventory_snapshot()

    # 4. Compare and analyze
    issues = compare_snapshots(pre_snapshot, post_snapshot)

    # 5. Handle issues
    if issues.critical:
        await handle_critical_issues(issues)
    elif issues.warnings:
        await suggest_improvements(issues)

    return issues
python
async def validate_operation_integrity(operation_type):
    # 1. 操作前快照
    pre_snapshot = await create_inventory_snapshot()

    # 2. 执行操作
    await execute_operation(operation_type)

    # 3. 操作后验证
    post_snapshot = await create_inventory_snapshot()

    # 4. 对比分析
    issues = compare_snapshots(pre_snapshot, post_snapshot)

    # 5. 处理问题
    if issues.critical:
        await handle_critical_issues(issues)
    elif issues.warnings:
        await suggest_improvements(issues)

    return issues

Storage Format

存储格式

json
{
  "validation_snapshot": {
    "operation": "command_restructure",
    "timestamp": "2025-01-27T10:30:00Z",
    "pre_inventory": {
      "commands": {
        "count": 23,
        "files": ["commands/dev/auto.md", "commands/analyze/project.md", ...]
      },
      "agents": {
        "count": 19,
        "files": ["agents/orchestrator.md", "agents/code-analyzer.md", ...]
      }
    },
    "post_inventory": {
      "commands": {
        "count": 22,
        "files": ["commands/dev/auto.md", "commands/analyze/project.md", ...]
      },
      "agents": {
        "count": 19,
        "files": ["agents/orchestrator.md", "agents/code-analyzer.md", ...]
      }
    }
  }
}
json
{
  "validation_snapshot": {
    "operation": "command_restructure",
    "timestamp": "2025-01-27T10:30:00Z",
    "pre_inventory": {
      "commands": {
        "count": 23,
        "files": ["commands/dev/auto.md", "commands/analyze/project.md", ...]
      },
      "agents": {
        "count": 19,
        "files": ["agents/orchestrator.md", "agents/code-analyzer.md", ...]
      }
    },
    "post_inventory": {
      "commands": {
        "count": 22,
        "files": ["commands/dev/auto.md", "commands/analyze/project.md", ...]
      },
      "agents": {
        "count": 19,
        "files": ["agents/orchestrator.md", "agents/code-analyzer.md", ...]
      }
    }
  }
}

Success Metrics

成功指标

  • Detection Rate: 100% of missing components detected within 10 seconds
  • False Positive Rate: <5% (accurate issue identification)
  • Recovery Success: 95% of critical issues automatically resolvable
  • Performance Impact: <2 seconds overhead for validation
  • 检测率: 100%的缺失组件在10秒内被检测到
  • 误报率: <5%（准确识别问题）
  • 恢复成功率: 95%的关键问题可自动解决
  • 性能影响: 验证带来的开销<2秒

When to Apply

应用场景

Always Apply:
  • Before any file system restructuring
  • After any command categorization changes
  • During release preparation
  • After any major refactoring
Recommended:
  • After adding new agents or skills
  • After modifying plugin manifest
  • After any automated file operations
  • Weekly integrity checks
必须应用:
  • 任何文件系统重构之前
  • 任何命令分类变更之后
  • 发布准备期间
  • 任何重大重构之后
推荐应用:
  • 添加新agents或skills之后
  • 修改插件清单之后
  • 任何自动文件操作之后
  • 每周完整性检查

Failure Prevention

故障预防

This system specifically prevents:
  1. Lost Commands: Detects when commands are moved or deleted
  2. Missing Agents: Identifies when agent files are removed
  3. Broken References: Finds when cross-references are broken
  4. Configuration Drift: Detects when configuration becomes inconsistent
  5. Documentation Gaps: Identifies when documentation falls out of sync
本系统专门预防以下问题:
  1. 命令丢失: 检测命令被移动或删除的情况
  2. Agent缺失: 识别Agent文件被移除的情况
  3. 引用断裂: 发现跨引用失效的情况
  4. 配置漂移: 检测配置不一致的情况
  5. 文档缺口: 识别文档与实际情况不同步的情况

Recovery Process

恢复流程

  1. Immediate Detection: Missing component identified within 5 seconds
  2. Alert Generation: Clear, actionable alert with severity level
  3. Backup Search: Search backups for missing component
  4. Auto-Restoration: If found in recent backup, auto-restore
  5. Git Recovery: If not in backup, check Git history
  6. Template Recreation: If not found, create from template
  7. Manual Guidance: Provide clear instructions for manual recovery
  1. 即时检测: 5秒内识别缺失组件
  2. 警报生成: 带有严重程度的清晰、可执行警报
  3. 备份搜索: 在备份中查找缺失组件
  4. 自动恢复: 如果在近期备份中找到，自动恢复
  5. Git恢复: 如果不在备份中，检查Git历史
  6. 模板重建: 如果未找到，从模板创建
  7. 手动指导: 提供清晰的手动恢复说明