docs(spec): retire the dev-services identifier guard requirements - #109
Merged
Conversation
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
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
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.
Retires REQ-D1.2 through REQ-D1.5 on the operator's decision, closing the last open entry in the
specs/dev-servicesqueue.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:
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-validaterejected it: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:
requirements.mdScopetest-spec.md[test + design-level]→[design-level]. The enforcement genuinely got weaker; the pin now says so rather than presenting as still covereddesign.mdtasks.mdWhat stays
scripts/gitleaks-identifier-rules.shand 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. Noprivate-project-identifierblock has ever existed in.gitleaks.toml, so nothing was removed from the scanner; the guard was never active.kickoff-brief.mdis 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-validate0 errors / 0 warnings.yamllint,gitleaks,syntax-check,ansible-lintpass.stale-declarations-test.shpasses.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
/orchestratehere would halt wanting a/spec-kickoffdelta re-walkthrough. Academic while the bundle is complete, but not a surprise I want you to find later.