Background
PR #594 scrubbed ~130 bare acceptance-criteria tags (AC-1.1, AC-14, …) that pointed at an external GitHub-issue AC list a code reader cannot open. While doing that, a sibling pattern surfaced: bare §x.y / Source §N L### "source proposal" provenance annotations scattered across the code, specs, and docs.
The governing principle (from the PR-description policy added alongside #594, and stated directly): referencing valid links is fine; referencing internal content that might change is not. A bare §N.M L### pointer at an out-of-repo proposal document is an unresolvable reference to mutable internal content — and the embedded line numbers rot the moment that document changes.
Current-state violations
- 160
§-reference lines across 61 tracked files (python/examples/voice/*.py, python/scenario/*, specs/*.feature, docs/**/*.mdx). Examples: # Source §8 L1243-1257, Source §6.3, L931-967 and §8 emotional escalation.
- ~159 of the 160 are bare/non-linkable — only ~1 is an actual hyperlink to an openable in-repo target.
- The "source proposal" document is not in the repository — no proposal / design / RFC file exists (grep finds none; only the feature specs themselves). So these refs point at something a reader cannot reach, and which has no stable anchor.
Why now
The hygiene rationale and the safe transform are already proven by PR #594 (drop the tag, keep the human-readable substance; comments/docstrings only; behavioral-logic and Gherkin-step/scenario-count lines untouched, guarded by the feature-file contract test). Doing the § sweep while that pattern is fresh — but as a separate change so it does not block #594 — closes the whole class of unresolvable-internal-reference smell in one follow-up.
Scope notes (for investigation to refine)
Classification: Refactor
Status: stub — filed deliberately as standalone follow-up to PR #594. Not auto-investigated per request; run /investigate when prioritized.
Background
PR #594 scrubbed ~130 bare acceptance-criteria tags (
AC-1.1,AC-14, …) that pointed at an external GitHub-issue AC list a code reader cannot open. While doing that, a sibling pattern surfaced: bare§x.y/Source §N L###"source proposal" provenance annotations scattered across the code, specs, and docs.The governing principle (from the PR-description policy added alongside #594, and stated directly): referencing valid links is fine; referencing internal content that might change is not. A bare
§N.M L###pointer at an out-of-repo proposal document is an unresolvable reference to mutable internal content — and the embedded line numbers rot the moment that document changes.Current-state violations
§-reference lines across 61 tracked files (python/examples/voice/*.py,python/scenario/*,specs/*.feature,docs/**/*.mdx). Examples:# Source §8 L1243-1257,Source §6.3, L931-967 and §8 emotional escalation.Why now
The hygiene rationale and the safe transform are already proven by PR #594 (drop the tag, keep the human-readable substance; comments/docstrings only; behavioral-logic and Gherkin-step/scenario-count lines untouched, guarded by the feature-file contract test). Doing the
§sweep while that pattern is fresh — but as a separate change so it does not block #594 — closes the whole class of unresolvable-internal-reference smell in one follow-up.Scope notes (for investigation to refine)
§x.y/Source §N L###tags; preserve the description each annotates.§-ref already expressed as a working hyperlink to an in-repo file.Classification: Refactor
Status: stub — filed deliberately as standalone follow-up to PR #594. Not auto-investigated per request; run /investigate when prioritized.