Skip to content

docs(spec): retire the dev-services identifier guard requirements - #109

Merged
inkatze merged 1 commit into
mainfrom
chore/retire-identifier-guard
Aug 7, 2026
Merged

docs(spec): retire the dev-services identifier guard requirements#109
inkatze merged 1 commit into
mainfrom
chore/retire-identifier-guard

Conversation

@inkatze

@inkatze inkatze commented Aug 7, 2026

Copy link
Copy Markdown
Owner

Retires REQ-D1.2 through REQ-D1.5 on the operator's decision, closing the last open entry in the specs/dev-services queue.

Why

The rule block is committed by design (D-9), so the guard works on a fresh checkout and in CI. That makes the artifact protecting the private identifiers a public list of patterns for them, in a public repo.

D-8's own body says this outright:

match an identifier without containing a pattern for it, so this decision necessarily writes the private identifiers into a tracked file in a public repo

and accepted it on the grounds that the identifiers already appear in published git history. So this is a decision reversed on its merits, not on new information — the cost was seen and weighed at kickoff, and judged differently now. Both superseded decisions say so explicitly, because a future reader should not have to wonder whether the risk was simply overlooked.

No variant avoids the trade: a rule cannot match an identifier without containing a pattern for it. Hence withdrawn rather than reworked.

Retired, not deleted

My first attempt removed the four bullets. spec-validate rejected it:

ERROR REQ-D1.2 renumbered or removed since origin/main
      (stable IDs are never reused; supersede instead)

Correct, and I was wrong. The bodies and IDs stay exactly as written, each marked Retired (2026-08-07), and their four test-spec entries likewise — a frozen record is not edited (D-20), so the marker carries the change.

Also corrected

These were live claims that would have become false the moment the REQs retired — the exact stale-statement shape this bundle's Task 5 existed to remove:

Where What
requirements.md Scope the In-scope bullet promising a hygiene backstop, and the Out-of-scope bullet whose reasoning leaned on it guarding new commits
REQ-D1.1 lost the scanner-configuration carve-out granted for the retired rules, so its prohibition is now absolute
test-spec.md REQ-D1.1 dropped [test + design-level][design-level]. The enforcement genuinely got weaker; the pin now says so rather than presenting as still covered
design.md D-8 and D-9 marked superseded, bodies intact
tasks.md Task 1's citations reduced to REQ-D1.1; reference bullet moved from Awaiting input to Out of scope, withdrawing the operator action

What stays

scripts/gitleaks-identifier-rules.sh and its harness cases remain — unwired and inert, refusing visibly with no source file. They cost nothing, and a revival is a regeneration rather than a rewrite. No private-project-identifier block has ever existed in .gitleaks.toml, so nothing was removed from the scanner; the guard was never active.

kickoff-brief.md is untouched. It is the signed-off record of what was agreed on 2026-08-05, and editing it would falsify history rather than amend a decision.

Verification

spec-validate 0 errors / 0 warnings. yamllint, gitleaks, syntax-check, ansible-lint pass. stale-declarations-test.sh passes.

One consequence worth stating: this changes the bundle's content anchor, so the kickoff sign-off's anchor line no longer matches and a future /orchestrate here would halt wanting a /spec-kickoff delta re-walkthrough. Academic while the bundle is complete, but not a surprise I want you to find later.

REQ-D1.2 through REQ-D1.5 required the pre-commit secret scanner to carry
rules matching the private project identifiers, built by a tracked
generator from an untracked machine-local file. Retired on the operator's
decision.

The reason is a trade the design saw and accepted, and the operator
declined. The rule block is committed by design (D-9) so the guard works
on a fresh checkout and in CI. That makes the artifact protecting the
identifiers a public list of patterns for them, in a public repo. D-8's
own body says so outright -- "match an identifier without containing a
pattern for it, so this decision necessarily writes the private
identifiers into a tracked file in a public repo" -- and accepted it on
the grounds that they already appear in published git history. No
variant of the guard avoids the trade, so the requirements are withdrawn
rather than reworked.

Retired, not deleted. The first attempt removed the four bullets and
spec-validate rejected it: stable IDs are never reused, supersede
instead. So the bodies and IDs stay exactly as written, each marked
`Retired (2026-08-07)`, and their four test-spec entries likewise. A
frozen record is not edited (D-20); the marker carries the change.

Also corrected, because they were the stale-claim shape this bundle's
own Task 5 existed to remove:

  requirements.md  the In-scope bullet promising a hygiene backstop, and
                   the Out-of-scope bullet whose reasoning leaned on that
                   backstop guarding new commits
  REQ-D1.1         lost the scanner-configuration carve-out it granted
                   for the retired rules, so its prohibition is now
                   absolute
  test-spec.md     REQ-D1.1 dropped from [test + design-level] to
                   [design-level]; the enforcement genuinely got weaker
                   and the pin now says so rather than presenting as
                   still covered
  design.md        D-8 and D-9 marked superseded, bodies intact
  tasks.md         Task 1's citations reduced to REQ-D1.1; its reference
                   bullet moved from Awaiting input to Out of scope,
                   withdrawing the operator action it requested

The shipped mechanism stays. scripts/gitleaks-identifier-rules.sh and
its harness cases are unwired and inert -- they refuse visibly with no
source file -- so they cost nothing and a revival is a regeneration
rather than a rewrite. No `private-project-identifier` block has ever
existed in .gitleaks.toml, so nothing was removed from the scanner.

kickoff-brief.md is untouched: it is the signed-off record of what was
agreed on 2026-08-05, and editing it would falsify history rather than
amend a decision.

spec-validate passes 0/0. Note this changes the content anchor, so the
kickoff sign-off's anchor line no longer matches and a future
/orchestrate on this bundle would halt wanting a delta re-walkthrough.
Academic while the bundle is complete; stated so it is not a surprise.

Claude-Session: https://claude.ai/code/session_01F8oKrXASMQSXMVjSvuJpn9
@inkatze
inkatze merged commit cf22d10 into main Aug 7, 2026
9 of 12 checks passed
@inkatze
inkatze deleted the chore/retire-identifier-guard branch August 7, 2026 21:57
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant