v0.17.6 feat: governance prose clarity (EXP-0001) - #7
Merged
Conversation
Adds PROSE-SENTENCE-LEN, PROSE-STACKED-QUALIFIER, and LEDGER-LENGTH findings to `constitution audit` -- all severity:warn, never blocking. Extends LedgerEntry and Adr to capture body text (previously metadata-only: version/date/title, id/status/serves), adds a self-initializing baseline-snapshot mechanism (.constitution/prose-baseline.json) to isolate new findings from pre-existing dense text for false-positive-rate tracking during the WARN-ONLY window. Also fixes two pre-existing bugs found while calibrating against real text: - parseExperiment's section() regex used the 'm' flag, which makes `$` match end-of-line rather than end-of-file -- silently truncated any multi-line Hypothesis/Metric/Decision-rule section to its first physical line. Went unnoticed since every prior experiment fixture used single-line sections. - The baseline-snapshot write path produced duplicate array entries whenever 2+ fields (e.g. Article Principle and Fitness) shared the same (code, where) key -- deduped with a Set before writing. 41 new/updated tests in cli/test/engine.test.ts and cli/test/experiments.test.ts, including regression guards against the real repo's known-bad calibration examples (Article F-II's current text, Ledger entry [0.17.0]).
…ce, EXP-0001 Adds templates/ledger-entry.md (150-word cap, points narrative to BUILDLOG.md instead of the ledger) and tightens templates/article.md and templates/adr.md with plain-prose guidance -- one idea per sentence, no stacking a second qualifier onto a first. Pre-registers experiments/EXP-0001-governance-prose-clarity.md per F-III: hypothesis, WARN-ONLY enforcement, false-positive-rate metric, a frozen decision rule (15-commit window, <20% threshold), and the guardrail catch-rate check against the two real calibration cases. process/amendment-lifecycle.md gets one line pointing at the new ledger-entry template.
Adds Amendments Ledger entry [0.17.6] (82 words, no narrative -- dogfoods the new ledger-entry template in the same change that introduces it). Bumps cli/package.json and package-lock.json to 0.17.6 to match, per this self-hosted repo's F-II pin/ledger axis collapse. Fixes .gitignore's blanket `.constitution/` exclusion: git can't un-ignore a file whose parent directory is itself excluded, so the directory-level pattern is now `.constitution/*` with a negation for prose-baseline.json -- the EXP-0001 evidence file needs to be committed so the WARN-ONLY window's false-positive-rate tracking is consistent across commits and CI, not re-seeded from scratch on every fresh checkout. Includes the regenerated, duplicate-free baseline snapshot. Reorganizes TODOS.md into the canonical component/priority format and records two items found during this work: the delta-based ratification gate (Approach C, deferred fast-follow) and a pre-existing parseBoldBullets truncation bug (out of scope for this change). Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
…ices README.md's Repo map and AGENTS.md's governance map both enumerated top-level directories but omitted the new experiments/ dir (EXP-0001, this repo's own WARN-ONLY governance-prose-clarity experiment), and README's template parenthetical was missing ledger-entry.md (plus two pre-existing omissions: governance-map.md, constitution.md). Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Governance engine — new WARN-ONLY checks (EXP-0001)
PROSE-SENTENCE-LEN,PROSE-STACKED-QUALIFIER, andLEDGER-LENGTHfindings toconstitution audit— allseverity: warn, never blocking. ExtendsLedgerEntry/Adrto capture body text (previously metadata-only) and adds a self-initializing baseline-snapshot mechanism (.constitution/prose-baseline.json) so pre-existing dense text doesn't contaminate the false-positive-rate tracking during the WARN-ONLY window.parseExperiment's section parser silently truncated multi-line sections (anm-flag regex bug), and the baseline-write path produced duplicate keys when 2+ fields shared a location.Governance docs
templates/ledger-entry.md(150-word cap, points narrative toBUILDLOG.md); tightenedtemplates/article.md/templates/adr.mdwith plain-prose guidance.experiments/EXP-0001-governance-prose-clarity.md(F-III: hypothesis, WARN-ONLY enforcement, 15-commit window, <20% false-positive threshold, frozen decision rule) — this framework's first real experiment file.README.md/AGENTS.mdupdated to surface the newexperiments/directory andledger-entry.mdtemplate in their indices.Release bookkeeping
cli/package.json,CONSTITUTION.mdheader + new Amendments Ledger entry[0.17.6], dogfooding the new ledger-entry template in the same change that introduces it)..gitignore's blanket.constitution/exclusion (git can't un-ignore a file whose parent directory is itself excluded) so the baseline snapshot can actually be committed.TODOS.mdinto the canonical format; recorded two deferred items (a delta-based ratification gate fast-follow, and a pre-existingparseBoldBulletstruncation bug found but out of scope here).Test Coverage
Tests: 23 → 41 (+18 new), all passing. Coverage of the new code: 78% → 100% after closing 6 gaps found by the ship coverage audit (Article Fitness/Why, Statute rule/Why, and ADR-body
checkProsecall sites were previously only exercised via Article Principle).Pre-Landing Review
7 issues found (4 testing gaps, 3 maintainability notes) — all addressed: 4 coverage-closing tests added, 2 mechanical fixes applied (
[NEW]tag in CLI text output for non-baseline findings; a code comment linking the tunable thresholds to the experiment doc), 1 design judgment resolved per your choice (strengthenedaudit()'s doc-comment rather than a rename/split, given the churn cost outweighed the risk today).Design Review
No frontend files changed — design review skipped.
Eval Results
No prompt-related files changed — evals skipped.
Scope Drift
Scope Check: CLEAN. Delivered exactly what was reviewed (T1-T10), plus two legitimately-discovered bug fixes that were necessary prerequisites, not scope creep.
Plan Completion
10/10 plan-eng-review items (T1-T10) DONE. T11 (delta-based ratification gate, Approach C) correctly deferred to
TODOS.mdby design — not part of this PR.TODOS
TODOS.md reorganized into the canonical component/priority format. 0 items completed by this PR (both recorded items are explicitly deferred future work). 2 items remaining.
Documentation
README.md's Repo map andAGENTS.md's governance map both omitted the newexperiments/top-level directory (this repo's own WARN-ONLY EXP-0001 governance-prose-clarity experiment, dogfoodingprocess/experiment-lifecycle.md). Added a line to each.README.md's template parenthetical was missingledger-entry.md(the new template added in this branch); also filled in two pre-existing omissions (governance-map.md,constitution.md) while there.CONSTITUTION.md([0.17.6]) andcli/package.json's version field are this repo's changelog equivalent and were already updated and in sync; left untouched.cli/README.md,docs/architecture.md, andtemplates/AGENTS.mdwere audited but need no changes.Adversarial Review
Claude adversarial subagent (Codex not installed) caught one real, concrete bug before its connection dropped mid-response: the baseline-snapshot write path produced duplicate keys (39 written, 35 unique on the real repo) whenever 2+ fields shared a location. Fixed, tested, and the baseline regenerated cleanly (35/35 unique).
Test plan
🤖 Generated with Claude Code