Troubleshooting
Purpose
This page is the canonical v1.6 troubleshooting surface for jhf-deployment.
It stays command-first and bounded, while deeper runbooks remain supporting truth.
Reader Outcome
This page should help an operator quickly separate:
- deployment-owned docs or contract drift
- deployment-owned preflight/postdeploy guardrail drift
- foreign runtime-owner failures that deployment should only classify and hand off
Run This Check
python scripts/validate_docs_platform_v1_6.py
For deployment-owned source-truth drift:
python3 scripts/validate-doc-governance.py --repo-root "$(git rev-parse --show-toplevel)"
python3 maintenance/verify-maintenance-contracts.py
On Windows/Codex Desktop, run the validator from the intended worktree with an
explicit Git top-level. Never invoke an absolute validator path from
., because that is a workspace rather than the trusted repository
root:
py scripts\validate-doc-governance.py --repo-root "$(git rev-parse --show-toplevel)"
Supporting Docs
First Handoff Rule
If the deployment-owned docs, metadata, and guardrail checks are green but the live lane still fails, classify the remaining problem as an external runtime-owner blocker instead of recreating runtime truth locally in jhf-deployment.
AGPLv3. See ../LICENSE (LICENSE).
Learn more at helpifyr.com.