Diagnostics & Health Monitoring
Relevant source files
The following files were used as context for generating this wiki page:
Diagnostics and Health Monitoring in the IDAHO-VAULT project encompasses a multi-layered strategy for ensuring system stability, security integrity, and operational status. The system utilizes automated Python scripts, GitHub Actions workflows, and external audit tools to monitor the health of the vault, validate service connectivity, and ensure that sensitive credentials remain protected.
The primary focus is on detecting "degraded" states in the automation layer, such as failures in GitHub Actions, API connectivity issues (e.g., the Bill Tracker API 403 errors), and secret scanning findings. Monitoring results are synthesized into human-readable reports and machine-parsable logs to facilitate rapid recovery from volatile states.
Sources: research_ Claude Code Dispatch.md, SECRET-SCANNING-REPORT.md:5-10
System Health Architecture
The monitoring architecture consists of local execution scripts, cloud-based GitHub Actions, and structured audit logs. It is designed to verify the integrity of the canonical knowledge layer while identifying friction in the external integration layers.
Monitoring Flow
The health monitoring process follows a structured sequence from initial script execution to the generation of a final diagnostic report.
The system prioritizes the canonical source (GitHub repository) and anchors infrastructure to the Google Cloud Platform (GCP).
Sources: research_ Claude Code Dispatch.md, TEST_EXECUTION_SUMMARY.md:5-10
Validation & Testing Framework
The framework includes comprehensive syntax validation and automated test execution across dozens of scripts within the .github/scripts/ directory.
Core Validation Components
The system monitors 41 primary script files and 6 test files to ensure functional readiness.
| Component | Target Directory | Responsibility |
|---|---|---|
| Script Audit | .github/scripts/ | Validates syntax and logic of 41 operational scripts. |
| Test Suite | tests/ | Executes 6 pytest files to verify topology and rollover. |
| Portability Check | Root / !/ | Ensures stability across Windows, macOS, and Linux. |
| Manifest Update | Root | Syncs execution inventory and tool state. |
Sources: TEST_EXECUTION_SUMMARY.md:14-60, audit-results.txt, VAULT-CONVENTIONS.from-pushable-2026-05-08.md:12-20
Diagnostic Sequence
Test execution involves dynamic module loading to isolate environments during health checks.
Sources: TEST_EXECUTION_SUMMARY.md:85-110
Security & Secret Scanning
A critical health metric is the presence of unauthorized secrets within the vault. The project utilizes a "belt-and-suspenders" approach to secret scanning.
Scanning Methodology
- Approved Workflow: Uses
.github/scripts/check_secret_patterns.pyvia GitHub Actions to scan daily. - Third-Party Scanning: Integrates
detect-secretsandtruffleHogfor comprehensive coverage. - External Layer: Employs GitGuardian for real-time external monitoring.
Findings and Triage
Monitoring reports categorize findings into false positives (e.g., .npmrc files in plugin directories) and critical blockers.
| Finding Type | Example Paths | Resolution Status |
|---|---|---|
| Legitimate Config | .op/, .factory/certs/ | Approved False Positive |
| Placeholder | Documentation - Discord - OAuth2.md | Logged for Review |
| Script Error | truffleHog Scan | Configuration Blocker |
Sources: SECRET-SCANNING-REPORT.md:15-50, VAULT-CONVENTIONS.from-pushable-2026-05-08.md:460-480
Automated Audit Execution
Health monitoring is frequently triggered by specialized Python utilities that perform "sweeps" or "audits" of specific vault sub-systems.
Key Monitoring Scripts
sort_audit.py: Monitors vault structure for misplaced or unsorted files.wayback_audit.py: Performs a dead link check and audits URL preservation in the Wayback Machine.validate_content.py: A comprehensive script utilizing regex and argparse to verify vault content structure.stale_bot_prs.py: Monitors the lifecycle of Pull Requests to prevent coordination drift.
Sources: VAULT-CONVENTIONS.from-pushable-2026-05-08.md:420-445, TEST_EXECUTION_SUMMARY.md:65-75
MCP Logging Requirement
For automated health actions mediated by the Model Context Protocol (MCP), a mandatory structured log must be emitted.
mcp_action_log:
action_type: "read_resource"
system_or_resource_id: "idaho-vault-api"
initiating_agent: "agent:claude-code"
outcome: "success"
retry_count: 0
related_ref: "PR#128"
Sources: VAULT-CONVENTIONS.from-pushable-2026-05-08.md:505-530
Recovery & Remediation Status
The project tracks the current health status of the "automation layer" separate from the "knowledge layer."
Health Status Definitions
- ACTIVE (Degraded): Core content is intact, but automation (e.g., GitHub Actions, 1Password injection) is failing.
- Yellow (Recovery): Partial automation functionality restored; blockers identified and triaged.
- Green (Healthy): All CI/CD pipelines passing; API connectivity verified.
Known Blockers
Current health logs indicate significant friction in:
- 1Password Secret Injection: Prevents automated pipeline authentication.
- Bill Tracker API: Returning
403 FORBIDDENerrors. - Identity Sync: Protocol remains unverified.
Sources: research_ Claude Code Dispatch.md, research/AUDIT-IMPLEMENTATION-kanto-june4-2026.md
Summary
Diagnostics & Health Monitoring serves as the immune system for the IDAHO-VAULT, bridging the gap between volatile automation states and the stable canonical knowledge base. By combining syntax validation, secret scanning, and structured MCP logging, the system ensures that Logan's personal journalism research remains accessible and secure even when external integrations face degradation.