The governance engine: parse/audit/lock/tone/ops planes in the CLI (v0.17.0)

[chinmaygit]

What changed

Overhaul session 1 (standing goal: make constitution an installable AI-governance product). The CLI grows from installer to deterministic governance engine — cli/src/engine/: typed model + parser for the existing document formats, structural audit, the firewall lock, tone rendering, the ops plane, L4 compile packs, a ratification queue, and a self-healing doctor. Full design in docs/architecture.md; the session-by-session record (including what broke and how it was fixed) in BUILDLOG.md.

Highlights:

• Firewall as a CI gate (F-IV mechanized) — constitution.lock.json records canonical hashes of ratified L0/L1 units; constitution firewall fails on changed/added/removed ratified text. lock accept and ratify refuse non-TTY sessions (agents can't cross by accident). The lock in this PR was accepted and committed by Chinmay (13f0678); constitution firewall runs clean against it.
• Tone as a view, never a fork — constitution render <unit> --tone plain|casual|formal; renders are derived artifacts cache-keyed by canonical hash + transform version, stale by construction on amendment, pruned by doctor. One canonical text, ever.
• Ops plane, separate from the law — .constitution/ holds events (constitution feature <verb>), the Kanban board (constitution board [--html] with a governance-health strip), compile packs, tone caches, and the proposals queue. Volume lives there; the law never grows from usage.
• Self-healing split by the firewall — constitution doctor fixes below (stale caches, version sync via constitution.config.json, scaffold gaps) and drafts above (proposals with status: PROPOSED, ruled on only by interactive human constitution ratify).
• Deterministic L4 compile input — constitution compile "<task>" emits the complete canonical law pack + briefing contract; judgment stays in the compile-prompt skill.
• Non-interactive constitution init --name N --ratifier R --agents a,b; CI workflow (.github/workflows/governance.yml); README + docs/ rewritten as a product; two new cli/AGENTS.md statutes (engine determinism, failing-first tests).

Why

Shrink the intent→shipped gap and make it checkable: the law plane stays small and durable, everything voluminous is pushed into the ops plane, and the firewall becomes something CI can prove held rather than something an audit notices later.

Verification (all actually run)

• npm run build (strict tsc) clean; npm test — 14/14 vitest cases, including a dogfood test that parses and audits this very repo (0 errors).
• constitution audit on this repo: 0 errors, honest warnings only (F-III HOLDS+UNGUARDED mechanization debt).
• constitution firewall: clean against the human-accepted lock; lock tests prove edits/unaccepted-ratifications/repeals trip it while conformance updates and paragraph reflow don't.
• lock accept < /dev/null refuses with the F-IV message (non-TTY guard demonstrated).
• Tarball standard from ledger [0.16.11]: packed 0.17.0, npm-installed into a scratch consumer, non-interactive init, then audit/feature/compile --out/board/doctor from the installed binary — all working.

For the reviewer

• Ledger entry [0.17.0] is agent-authored and explicitly pending your review; no Article text, status, or L0 line was touched anywhere (below the firewall throughout — the clean constitution firewall run is the proof).
• Untested, stated plainly: tone generation with a real LLM (claude -p couldn't auth nested in-session; stub-tested + honest-degradation verified), the interactive ratify TTY flow end-to-end (logic unit-tested), and publishing 0.17.0 to GitHub Packages (needs your npm auth).
• Deferred queue for session 2 is at the bottom of BUILDLOG.md (skills consuming engine output, DSAMind adoption, live dashboard).

🤖 Generated with Claude Code