Handbook

Handbook go / no-go checklist

Run these commands when closing a docs-heavy batch (no secrets in logs). Go means all gates below passed on the recorded SHAs.

Updated

This checklist aligns with prompt pack 15 (production review). Use --strict --strict-md as the primary contract gate; add --strict-depth when you require JSON task_id / version fields on every sidecar (see audit_contract_docs.py --require-contract-identity).

Recorded revisions

Fill with git rev-parse HEAD before publishing:

Repo Commit
forge-lcdl (paste)
forge-lcdl-website (paste)
forge-lcdl submodule (forge-lcdl-website/forge-lcdl) (paste)

Commands (forge-lcdl) — pack parity

cd forge-lcdl
git status --short
git log -1 --oneline
python3 -m compileall -q src tests scripts examples
python3 scripts/audit_docs_site.py --strict
python3 scripts/audit_contract_docs.py --strict --strict-md
python3 scripts/audit_contract_docs.py --schema-depth-report
python3 scripts/generate_task_catalog_md.py --check
pytest -q tests/docs tests/reference tests/examples
pytest -q -m "not granite"

Supplementary identity gate (fails if any sidecar lacks task_id / version):

python3 scripts/audit_contract_docs.py --require-contract-identity

Optional combined strict run:

python3 scripts/audit_contract_docs.py --strict --strict-md --strict-depth --require-contract-identity

Commands (forge-lcdl-website)

cd forge-lcdl-website
git submodule status --recursive
git -C forge-lcdl log -1 --oneline
pip install markdown
python3 generator/build-site.py --link-check
python3 scripts/check-generated-site.py --strict-diagrams --verify-rendered-diagrams
bash scripts/verify-hosting-target.sh
python3 scripts/inspect_handbook_html.py

Live URL (when reachable):

python3 scripts/inspect_handbook_html.py --url https://lcdl.forgesdlc.com/

Manual browser paths (prompt 15)

Spot-check: /, /docs/start/getting-started.html (path as emitted), tutorials 101 / 201 / 301, /examples/, /reference/, /reference/task-catalog.html, /enterprise/, /agents/, contribute publishing page.

Results log

Gate Result Notes
compileall
audit_docs_site --strict
audit_contract_docs --strict --strict-md
audit_contract_docs --require-contract-identity optional
schema-depth-report informational
generate_task_catalog --check
pytest docs/reference/examples
pytest -m "not granite"
audit_docs_site (default) PASS 2026-05-17 remediation batch (183 files scanned)
build-site --link-check PASS 227 HTML pages emitted locally
check-generated-site --strict-diagrams PASS includes --verify-rendered-diagrams
verify-hosting-target
inspect_handbook_html PASS local --index website/index.html; primary nav IDs OK

Verdict

GO only when required rows are PASS, submodule SHAs match intent, and live or offline HTML evidence is archived (see MASTER-REMEDIATION-REPORT.md).

Residual risks

  • Granite / live gateway not covered by -m "not granite".
  • Firebase Hosting must deploy the same website/ tree produced above.
  • Submodule drift: always git submodule status before declaring GO.