Skip to content

Commit 50d6fc3

Browse files
committed
refactor(engine): make the ADR briefing budget a built-in check
The briefing budget is a property of the engine, not a governance decision this project happens to hold: `briefAdr` truncates every project's ADRs at the same cap, so every archgate user has the same blind spot. Shipping it as a dogfooded ADR plus companion rules put the check in the wrong place, and the symptoms showed it — the rule read `DEFAULT_MAX_SECTION_CHARS` out of `src/engine/context.ts` and hardcoded a fallback everywhere else, and it reimplemented `extractAdrSections` because ARCH-024 forbids a rule file from importing engine code. Moving it into the CLI dissolves both problems: the check now imports the same cap and the same extractor that perform the truncation, so they cannot disagree. The parity test that existed only to detect that drift is deleted along with them. - `src/engine/adr-sections.ts` owns `BRIEFED_SECTIONS`, `DEFAULT_MAX_SECTION_CHARS`, `extractAdrSections`, `truncateSection`, and `collectBriefingBudgetWarnings`. Extracted into its own module because `context.ts` already imports `runner.ts`, so measuring from the runner would have closed an import cycle. - `archgate check` reports every overflowing section as a `[briefing]` advisory, in console, CI annotations, and JSON (`briefingWarnings`). Measured over ALL ADRs, including `rules: false` ones — ARCH-024 is the worst offender and has no companion rules at all, so a rules-only check would have missed it. - Advisory by design: it never affects `pass`. Sections that enumerate normative identifiers have an irreducible floor above the cap, and a blocking check would be unfixable and would train authors to suppress it. Removes GEN-005 and its companion rules. The four ADRs that declare a deliberate overflow now point at the built-in check instead. Documented in all three locales; ADR count drops to 46 rules. Signed-off-by: Rhuan Barreto <rhuan@barreto.work>
1 parent b138de6 commit 50d6fc3

20 files changed

Lines changed: 404 additions & 399 deletions

.archgate/adrs/ARCH-005-testing-standards.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -190,7 +190,7 @@ Code reviewers MUST verify:
190190

191191
### Exceptions
192192

193-
**Documented briefing-budget overflow ([GEN-005](./GEN-005-adr-briefing-budget.md)):** the `Do's and Don'ts` section exceeds the `review-context` briefing cap. The section is ordered so the `Decision` and all ten `**DO**` items fit inside the window; the overflow is the `**DON'T**` list, where each item is the terse inverse of a visible Do or of a Decision convention. Shortening it further would drop a distinct anti-pattern, so the overflow stands and consumers MUST open the full ADR for the Don'ts.
193+
**Documented briefing-budget overflow** (reported by rchgate check)**:** the `Do's and Don'ts` section exceeds the `review-context` briefing cap. The section is ordered so the `Decision` and all ten `**DO**` items fit inside the window; the overflow is the `**DON'T**` list, where each item is the terse inverse of a visible Do or of a Decision convention. Shortening it further would drop a distinct anti-pattern, so the overflow stands and consumers MUST open the full ADR for the Don'ts.
194194

195195
## References
196196

.archgate/adrs/ARCH-022-ast-aware-rule-context.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -159,7 +159,7 @@ Code reviewers MUST verify, for any PR implementing or modifying `ctx.ast()`:
159159

160160
Any proposal to add a bundled multi-language parser (tree-sitter, WASM grammars, or otherwise) to broaden `ctx.ast()`'s guarantees beyond this ADR's scope MUST be documented as a separate ADR, reviewed against [ARCH-006](./ARCH-006-dependency-policy.md)'s dependency-approval process, and approved by the project maintainer before implementation begins.
161161

162-
**Documented briefing-budget overflow ([GEN-005](./GEN-005-adr-briefing-budget.md)):** the `Decision` and `Do's and Don'ts` sections exceed the `review-context` briefing cap and MUST NOT be shortened further. They carry a security boundary that degrades if partially stated: the four ordered guardrails and their marker names, the `-I` isolation invariant, the `assertNoSymlinkInPath` exemptions, the temp-file hardening modes, and the per-language comment serializer contracts. The `Decision` is front-loaded so a truncated briefing still delivers the guardrail sequence; consumers MUST open the full ADR for the rest.
162+
**Documented briefing-budget overflow** (reported by rchgate check)**:** the `Decision` and `Do's and Don'ts` sections exceed the `review-context` briefing cap and MUST NOT be shortened further. They carry a security boundary that degrades if partially stated: the four ordered guardrails and their marker names, the `-I` isolation invariant, the `assertNoSymlinkInPath` exemptions, the temp-file hardening modes, and the per-language comment serializer contracts. The `Decision` is front-loaded so a truncated briefing still delivers the guardrail sequence; consumers MUST open the full ADR for the rest.
163163

164164
## References
165165

.archgate/adrs/ARCH-024-rule-file-sandbox-boundary.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -148,7 +148,7 @@ Code reviewers MUST verify, for any PR touching `src/engine/rule-scanner.ts`, `s
148148

149149
Any proposal to widen `ALLOWED_MODULES` beyond `node:`-prefixed specifiers, to follow imports transitively rather than refuse them, or to remove the import-time scan in `writeImportedAdrs()` MUST be documented as a separate ADR and approved by the project maintainer before implementation. Moving `.rules.ts` execution into a real sandbox (worker, subprocess, or restricted-resolver VM) is the sanctioned direction for strengthening this boundary and likewise warrants its own ADR — it would change the nature of the guarantee, not just its coverage.
150150

151-
**Documented briefing-budget overflow ([GEN-005](./GEN-005-adr-briefing-budget.md)):** the `Decision` and `Do's and Don'ts` sections exceed the `review-context` briefing cap and MUST NOT be shortened further. Both enumerate identifiers whose omission would change what this ADR governs: the banned-global list, the five `.constructor` spellings, the `AstNodeSchema` field names, the four allowed module forms, and the seven numbered clauses cited by ID elsewhere in the repository. Consumers reading a truncated briefing MUST open the full ADR.
151+
**Documented briefing-budget overflow** (reported by rchgate check)**:** the `Decision` and `Do's and Don'ts` sections exceed the `review-context` briefing cap and MUST NOT be shortened further. Both enumerate identifiers whose omission would change what this ADR governs: the banned-global list, the five `.constructor` spellings, the `AstNodeSchema` field names, the four allowed module forms, and the seven numbered clauses cited by ID elsewhere in the repository. Consumers reading a truncated briefing MUST open the full ADR.
152152

153153
## References
154154

.archgate/adrs/GEN-004-concise-forward-only-code-comments.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -137,7 +137,7 @@ Reviewers MUST verify on every PR touching project TypeScript:
137137
- **Suppressions**: genuine false positives only, always with a stated reason.
138138
- **No directory-level exemptions**: there are no per-path carve-outs from either rule. Test files, fixtures, lint plugins, and the ADR companion rules files are all in scope, and any future exemption MUST be recorded here rather than added silently to `.oxlintrc.json`.
139139

140-
**Documented briefing-budget overflow ([GEN-005](./GEN-005-adr-briefing-budget.md)):** the `Decision` section exceeds the `review-context` briefing cap and MUST NOT be shortened further. Its floor is set by the two TSDoc tag lists, which are preserved tag-for-tag because both enforcement layers trust them and MUST stay in sync. The section is ordered so the 5-line bound, the narration prohibition, and the agent-memory exemption precede the cut; only the Scope path list is truncated, and those paths are already carried in every `review-context` payload as this ADR's `files` globs.
140+
**Documented briefing-budget overflow** (reported by rchgate check)**:** the `Decision` section exceeds the `review-context` briefing cap and MUST NOT be shortened further. Its floor is set by the two TSDoc tag lists, which are preserved tag-for-tag because both enforcement layers trust them and MUST stay in sync. The section is ordered so the 5-line bound, the narration prohibition, and the agent-memory exemption precede the cut; only the Scope path list is truncated, and those paths are already carried in every `review-context` payload as this ADR's `files` globs.
141141

142142
## References
143143

.archgate/adrs/GEN-005-adr-briefing-budget.md

Lines changed: 0 additions & 110 deletions
This file was deleted.

.archgate/adrs/GEN-005-adr-briefing-budget.rules.ts

Lines changed: 0 additions & 139 deletions
This file was deleted.

0 commit comments

Comments
 (0)