Handbook

Safe edit matrix

Use this table before opening a PR from an agent or IDE automation. Higher tiers need broader tests even when the diff looks small.

Updated

Matrix

Area Typical paths Risk Run before merge Human review
Handbook prose docs/**/*.md (not contracts) Low python3 scripts/audit_docs_site.py --strict Usually no
Root README / migration stubs README.md, docs/*.md stubs Low audit_docs_site.py --strict Optional
Contract Markdown src/forge_lcdl/contracts/**/contract.md Medium–high python3 scripts/audit_contract_docs.py --strict (+ --strict-md) Recommended
Contract JSON sidecars src/forge_lcdl/contracts/**/contract.json High audit_contract_docs.py --strict --require-contract-identity Recommended
Task implementations src/forge_lcdl/tasks/**/*.py High python3 -m compileall -q src tests · pytest -q Yes
Registry / catalog **/catalog*.py, task registry modules High pytest -q tests/test_catalog_tasks.py (and related) Yes
Operators / generic / execution src/forge_lcdl/operators, generic, execution High pytest -q (targeted modules when possible) Yes
Contracts API src/forge_lcdl/contracts_api.py High pytest -q tests/test_contracts_api.py Yes
Benchmarks src/forge_lcdl/benchmarks/** Medium pytest -q / benchmark smoke per maintainer docs Optional
Scripts / audits scripts/*.py Medium Run the script you changed + dependent audits Optional
.cursor assets .cursor/rules, .cursor/skills Low–medium Align with Cursor integration Optional
Publish website forge-lcdl-website/**, Firebase config High build-site.py --link-check, check-generated-site.py --strict-diagrams --verify-rendered-diagrams, hosting verify Yes

Live Granite / gateway jobs

Optional live suites (pytest -m granite) are never required for docs-only or offline-safe task tests. Use them only when you intentionally change Granite-facing behavior (README).

Escalation cues

  • Touches runner semantics, gateway parsing, or catalog registration → full pytest -q, not only contract audits.
  • Touches schemas → contract strict audit + consider --strict-depth when adding task_id / version fields (Schema maturity).
  • Large doc moves → scripts/fix_docs_internal_links.py, scripts/resolve_doc_basenames.py, then audit_docs_site.py.

See also