Skip to main content

Troubleshooting

Documentation Map​

Troubleshooting

Use this page as the short-entry fault guide. The deeper operator flows remain in the existing runbooks and testing standards.

Primary References​

  • Operations
  • Runbook
  • Deployment Verify Ops (docs/DEPLOYMENT_VERIFY_OPS.md)
  • Upgrade Operator Guide (docs/UPGRADE_OPERATOR_GUIDE.md)

Docs / Contract Drift​

Symptoms:

  • docs inventory verification fails
  • canonical docs and manifest disagree
  • local-only workspace docs appear in canonical paths

Run this check:

python3 maintenance/verify-docs-inventory-adoption.py
python3 maintenance/verify-maintenance-contracts.py

Expected posture:

  • docs/docs.manifest.yaml stays conservative
  • local-only docs such as docs/PUBLIC_SURFACES.md and docs/RUNTIME_FLOWS.md are not promoted to canonical truth

Fabric Truth Consumption Drift​

Symptoms:

  • combination safety matrix fails
  • docs-standard or voice-events contract family checks fail

Run this check:

python3 maintenance/verify-fabric-combination-safety.py
python3 maintenance/verify-voice-governance.py

For live readback:

python3 maintenance/verify-fabric-combination-safety.py --live-url `api/v`1/combinations/profiles
python3 maintenance/verify-voice-governance.py --live-via-ssh <internal-runtime-redacted><internal-runtime-redacted>

Promotion / Stage-3 Feedback Problems​

Symptoms:

  • stage-3 feedback cannot publish
  • lock evidence is missing
  • live feedback readback mismatches expected payload

Run this check:

python3 maintenance/verify-promotion-bridge.py
python3 maintenance/verify-published-feedback-check.py
python3 maintenance/verify-stage3-metrics.py

Host Attachment / Host Access Problems​

Symptoms:

  • Beam cannot verify host-bound contracts
  • SSH batch-mode contract fails
  • live stack attachment evidence is stale

Run this check:

bash ops/host/verify-ssh-batchmode-contract.sh
bash ops/host/verify-live-stack-attachment.sh

License: AGPLv3. See ../LICENSE (LICENSE).

Learn more at helpifyr.com.