docs(specs): bug-shaped prebuild for ADR-0018 mechanical enforcement guard (DeepSeek #11) #354

Merged

pdurlej merged 7 commits from claude/c-batch/adr-0018-mechanical-enforcement-guard-prebuild into main

2026-05-23 10:30:29 +02:00

claude commented

2026-05-17 22:30:24 +02:00

Collaborator

Summary

Bug-shaped prebuild for DeepSeek 2026-05-14 deep review finding #11 (in state/deep-reviews/2026-05-14-platform-deep-review.md): ADR-0018 declares 'workarounds are explicitly forbidden' but enforcement relies on convention (cousin dispatches must STOP). Mechanical CI gate makes the rule actually load-bearing.

What's in

policies/adr-0018-debt-markers.yaml (canonical pattern list — to be created by codex slice 1)
.forgejo/workflows/adr-0018-debt-guard.yml + .forgejo/scripts/adr-0018-debt-guard.py (slice 2)
control-plane/platformctl/tests/test_adr_0018_debt_guard.py (10 test cases)

How it works

Workflow scans PR diff (added lines only) for debt markers (TODO/HACK/FIXME/XXX/workaround/temporary/for-now/etc.). For each match: checks 3 escape hatches:

Inline annotation: # TODO(expires: YYYY-MM-DD, tracked: #N)
PR body link: Tracked: #N (tech-debt-temporary, expires YYYY-MM-DD)
Operator override: label adr-0018-exempt + reason in PR comment (audit-logged)

If no escape hatch satisfies → red check + idempotent comment naming untracked lines.

Sister to #86 (security-sensitive label) — same mechanical-gate pattern.

Files

docs/specs/adr-0018-mechanical-enforcement-guard/{README,01-reproduction,02-expected-vs-actual,03-pattern-list,04-minimal-fix-surface,05-acceptance-and-tests}.md
prompts/codex-adr-0018-mechanical-enforcement-guard.md

Tier

Trivial per ADR-0007 (docs-only prebuild). Downstream slices each Lite.

Part of batch C (process/governance) prebuild shift, 5/6.
Refs DeepSeek 2026-05-14 finding #11; ADR-0018; #86; #243; #49

## Summary Bug-shaped prebuild for DeepSeek 2026-05-14 deep review finding #11 (in `state/deep-reviews/2026-05-14-platform-deep-review.md`): ADR-0018 declares 'workarounds are explicitly forbidden' but enforcement relies on convention (cousin dispatches must STOP). Mechanical CI gate makes the rule actually load-bearing. ## What's in - `policies/adr-0018-debt-markers.yaml` (canonical pattern list — to be created by codex slice 1) - `.forgejo/workflows/adr-0018-debt-guard.yml` + `.forgejo/scripts/adr-0018-debt-guard.py` (slice 2) - `control-plane/platformctl/tests/test_adr_0018_debt_guard.py` (10 test cases) ## How it works Workflow scans PR diff (added lines only) for debt markers (TODO/HACK/FIXME/XXX/workaround/temporary/for-now/etc.). For each match: checks 3 escape hatches: 1. **Inline annotation:** `# TODO(expires: YYYY-MM-DD, tracked: #N)` 2. **PR body link:** `Tracked: #N (tech-debt-temporary, expires YYYY-MM-DD)` 3. **Operator override:** label `adr-0018-exempt` + reason in PR comment (audit-logged) If no escape hatch satisfies → red check + idempotent comment naming untracked lines. Sister to #86 (security-sensitive label) — same mechanical-gate pattern. ## Files - `docs/specs/adr-0018-mechanical-enforcement-guard/{README,01-reproduction,02-expected-vs-actual,03-pattern-list,04-minimal-fix-surface,05-acceptance-and-tests}.md` - `prompts/codex-adr-0018-mechanical-enforcement-guard.md` ## Tier Trivial per ADR-0007 (docs-only prebuild). Downstream slices each Lite. Part of batch C (process/governance) prebuild shift, 5/6. Refs DeepSeek 2026-05-14 finding #11; ADR-0018; #86; #243; #49

claude added 7 commits

2026-05-17 22:30:24 +02:00

docs(specs): #11 ADR-0018 mechanical enforcement README 29f6d2ae4f

docs(specs): #11 ADR-0018 01-reproduction 95bf3d42ee

docs(specs): #11 ADR-0018 02-expected-vs-actual 2d39117425

docs(specs): #11 ADR-0018 03-pattern-list 0c6c9c3141

docs(specs): #11 ADR-0018 04-minimal-fix-surface 0dd25593f0

docs(specs): #11 ADR-0018 05-acceptance-and-tests be03a3ba1b

docs(prompts): #11 ADR-0018 codex execution prompt

base-is-main / guard (pull_request) Successful in 1s

Details

canary-required / collect-diff (pull_request) Successful in 3s