From 5e02b85efa7f9edd839f9df69137c7d80822f0ac Mon Sep 17 00:00:00 2001 From: chelsealong Date: Thu, 3 Sep 2026 18:12:12 +0000 Subject: [PATCH 1/3] fix(templates): stop /constitution from stacking Sync Impact Reports (#4431) Step 4 of the constitution command only said to prepend the Sync Impact Report as an HTML comment, with no instruction to remove a previous one. Each run therefore added another report block on top of the last, growing the raw file (and the token cost of reading it) without bound. Now the step explicitly requires removing any existing report comment before adding the new one. Assisted-by: Claude (model: claude-sonnet-5, autonomous) --- templates/commands/constitution.md | 5 +++- .../test_constitution_template_sync_report.py | 24 +++++++++++++++++++ 2 files changed, 28 insertions(+), 1 deletion(-) create mode 100644 tests/test_constitution_template_sync_report.py diff --git a/templates/commands/constitution.md b/templates/commands/constitution.md index 7b2f3684fb..eb6aed96b3 100644 --- a/templates/commands/constitution.md +++ b/templates/commands/constitution.md @@ -109,7 +109,10 @@ Follow this execution flow: - Ensure each Principle section: succinct name line, paragraph (or bullet list) capturing non‑negotiable rules, explicit rationale if not obvious. - Ensure Governance section lists amendment procedure, versioning policy, and compliance review expectations. -4. Produce a Sync Impact Report (prepend as an HTML comment at top of the constitution file after update): +4. Produce a Sync Impact Report as an HTML comment at the top of the constitution file after update: + - If the file already starts with an HTML comment (e.g. a Sync Impact Report from a prior run), + remove it entirely before adding the new one. The file must never carry more than one Sync + Impact Report; replace, never stack. - Version change: old → new - List of modified principles (old title → new title if renamed) - Added sections diff --git a/tests/test_constitution_template_sync_report.py b/tests/test_constitution_template_sync_report.py new file mode 100644 index 0000000000..42310eb8c8 --- /dev/null +++ b/tests/test_constitution_template_sync_report.py @@ -0,0 +1,24 @@ +"""Covers #4431: /constitution must not stack Sync Impact Report comments. + +The Outline step that produces the Sync Impact Report only said to "prepend" +it as an HTML comment, with no instruction to remove a previous one. Every +run of /constitution therefore added another comment block on top of the +last, growing the raw constitution file (and the token cost of reading it) +without bound. +""" + +from pathlib import Path + +REPO_ROOT = Path(__file__).parent.parent +CONSTITUTION_TEMPLATE = REPO_ROOT / "templates" / "commands" / "constitution.md" + + +def test_sync_impact_report_step_instructs_removing_prior_report(): + content = CONSTITUTION_TEMPLATE.read_text(encoding="utf-8") + step = content.split("Produce a Sync Impact Report", 1)[1].split("\n\n", 1)[0] + assert "remove" in step.lower(), ( + "Step 4 must instruct removing/replacing any existing Sync Impact " + "Report comment before adding the new one, otherwise reports stack " + "on every /constitution run" + ) + assert "never stack" in step.lower() or "not stack" in step.lower() From 609dc5878b818507199a70bc74bd151daf7119c4 Mon Sep 17 00:00:00 2001 From: chelsealong Date: Thu, 3 Sep 2026 18:48:51 +0000 Subject: [PATCH 2/3] docs(templates): state the Sync Impact Report's temporary lifecycle MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Per review on #4432/#4431: the growth this fixed isn't a functional bug in the intended workflow — the report is scratch material for human review and is expected to be removed before the constitution file is committed. Step 4 now says so explicitly, alongside the existing replace-not-stack instruction for runs where a prior report was left in place. --- templates/commands/constitution.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/templates/commands/constitution.md b/templates/commands/constitution.md index eb6aed96b3..431045ecc0 100644 --- a/templates/commands/constitution.md +++ b/templates/commands/constitution.md @@ -109,10 +109,12 @@ Follow this execution flow: - Ensure each Principle section: succinct name line, paragraph (or bullet list) capturing non‑negotiable rules, explicit rationale if not obvious. - Ensure Governance section lists amendment procedure, versioning policy, and compliance review expectations. -4. Produce a Sync Impact Report as an HTML comment at the top of the constitution file after update: - - If the file already starts with an HTML comment (e.g. a Sync Impact Report from a prior run), - remove it entirely before adding the new one. The file must never carry more than one Sync - Impact Report; replace, never stack. +4. Produce a Sync Impact Report as an HTML comment at the top of the constitution file after update. + This report is temporary scratch material for human review of the amendment, not governance + content; it is expected to be removed before the amended constitution file is committed. + - If the file already starts with an HTML comment (e.g. a Sync Impact Report left over because + it was not removed before a prior commit), remove it entirely before adding the new one. The + file must never carry more than one Sync Impact Report; replace, never stack. - Version change: old → new - List of modified principles (old title → new title if renamed) - Added sections From e3870d684e19b2db96d06fc7d9dc299270dee529 Mon Sep 17 00:00:00 2001 From: chelsealong Date: Tue, 8 Sep 2026 16:17:49 +0000 Subject: [PATCH 3/3] docs(templates): drop the Sync Impact Report de-dupe instruction Per review, Step 4 should stay documentation-only: the report is temporary, review-only material removed before commit, so /constitution shouldn't auto-strip a pre-existing HTML comment (which could delete unrelated leading content). Retarget the regression test to pin the documented lifecycle instead of the removed de-dupe behavior. --- templates/commands/constitution.md | 3 --- .../test_constitution_template_sync_report.py | 25 ++++++++++--------- 2 files changed, 13 insertions(+), 15 deletions(-) diff --git a/templates/commands/constitution.md b/templates/commands/constitution.md index 431045ecc0..0eff198043 100644 --- a/templates/commands/constitution.md +++ b/templates/commands/constitution.md @@ -112,9 +112,6 @@ Follow this execution flow: 4. Produce a Sync Impact Report as an HTML comment at the top of the constitution file after update. This report is temporary scratch material for human review of the amendment, not governance content; it is expected to be removed before the amended constitution file is committed. - - If the file already starts with an HTML comment (e.g. a Sync Impact Report left over because - it was not removed before a prior commit), remove it entirely before adding the new one. The - file must never carry more than one Sync Impact Report; replace, never stack. - Version change: old → new - List of modified principles (old title → new title if renamed) - Added sections diff --git a/tests/test_constitution_template_sync_report.py b/tests/test_constitution_template_sync_report.py index 42310eb8c8..6900eb1c07 100644 --- a/tests/test_constitution_template_sync_report.py +++ b/tests/test_constitution_template_sync_report.py @@ -1,10 +1,9 @@ -"""Covers #4431: /constitution must not stack Sync Impact Report comments. +"""Covers #4431: /constitution's Sync Impact Report must be documented as +temporary, review-only material rather than committed governance content. -The Outline step that produces the Sync Impact Report only said to "prepend" -it as an HTML comment, with no instruction to remove a previous one. Every -run of /constitution therefore added another comment block on top of the -last, growing the raw constitution file (and the token cost of reading it) -without bound. +The Outline step that produces the Sync Impact Report must state that it is +scratch material for human review and is expected to be removed before the +amended constitution file is committed. """ from pathlib import Path @@ -13,12 +12,14 @@ CONSTITUTION_TEMPLATE = REPO_ROOT / "templates" / "commands" / "constitution.md" -def test_sync_impact_report_step_instructs_removing_prior_report(): +def test_sync_impact_report_step_documents_temporary_lifecycle(): content = CONSTITUTION_TEMPLATE.read_text(encoding="utf-8") step = content.split("Produce a Sync Impact Report", 1)[1].split("\n\n", 1)[0] - assert "remove" in step.lower(), ( - "Step 4 must instruct removing/replacing any existing Sync Impact " - "Report comment before adding the new one, otherwise reports stack " - "on every /constitution run" + assert "temporary" in step.lower(), ( + "Step 4 must document that the Sync Impact Report is temporary, " + "review-only material, not governance content" + ) + assert "removed before" in step.lower() and "committed" in step.lower(), ( + "Step 4 must state the report is expected to be removed before the " + "amended constitution file is committed" ) - assert "never stack" in step.lower() or "not stack" in step.lower()