The specification in specs/hal-engine-doc-gates/spec.md has drifted significantly from the actual implementation and needs to be brought back in sync.
- Review current HAL Engine behavior and update spec.md to reflect actual functionality
- Ensure all documented APIs, parameters, and behaviors match the codebase
- Check reviewers validate the spec accurately represents the implementation
Missing symbols (heuristic)
- function:
accepts a citation whose name matches the declaration it points at — A citation whose name matches the declaration it points at is accepted
- function:
reports a citation whose line has moved away from the test it names — A citation whose line has moved away from the test it names is reported
- function:
names the line the cited test actually sits on, so the repair is obvious — The report names the line the test actually sits on
- function:
reports a citation carrying no test name at all — A citation carrying no name at all is reported
- function:
reports a name no declaration in the cited file has — A name no declaration in the cited file has is reported
- function:
repoints a drifted citation from the name it carries — --fix repoints a drifted citation from the name it carries
- function:
fills in a missing name from the declaration the line points at — --fix fills in a missing name from the declaration its line points at
- function:
leaves a citation that already agrees with its declaration untouched — --fix leaves a citation that already agrees untouched
- function:
reports a name that two declarations share, rather than choosing between them — A name matching two declarations is reported rather than repointed
- function:
refuses to rewrite an ambiguous citation — --fix leaves an ambiguous citation exactly as it found it
- function:
refuses to write a name that would break the markdown label — A name carrying a bracket is refused rather than written into a label it would break
- function:
reports a citation of a test declared with xit, which never runs — A citation of a test declared xit is reported
- function:
reports a citation of a test declared with .skip the same way — One declared .skip is reported the same way
- function:
reports a root-relative href, which the drift check would never read — A root-relative href is reported
- function:
reports an href starting ./, which this gate would otherwise have skipped — An href starting ./ is reported
What you should actually do
- Decide the direction first: is the spec stale, or is the code wrong? For a
reconstruction-grade spec the answer is almost always "update the spec".
- If you update the spec, fix the diverged items above and re-verify every
([validated by …](…)) link and #Lnn anchor on the statements you touch.
- If this is a false positive — the named items are endpoints, fields, or methods
rather than top-level symbols, and the behaviour still matches — close this as
stale rather than editing the spec.
Managed by Lore · created by spec-drift · Lore-Task: b388029a-1732-405f-a936-8e774cc0e774
The specification in
specs/hal-engine-doc-gates/spec.mdhas drifted significantly from the actual implementation and needs to be brought back in sync.Missing symbols (heuristic)
accepts a citation whose name matches the declaration it points at— A citation whose name matches the declaration it points at is acceptedreports a citation whose line has moved away from the test it names— A citation whose line has moved away from the test it names is reportednames the line the cited test actually sits on, so the repair is obvious— The report names the line the test actually sits onreports a citation carrying no test name at all— A citation carrying no name at all is reportedreports a name no declaration in the cited file has— A name no declaration in the cited file has is reportedrepoints a drifted citation from the name it carries— --fix repoints a drifted citation from the name it carriesfills in a missing name from the declaration the line points at— --fix fills in a missing name from the declaration its line points atleaves a citation that already agrees with its declaration untouched— --fix leaves a citation that already agrees untouchedreports a name that two declarations share, rather than choosing between them— A name matching two declarations is reported rather than repointedrefuses to rewrite an ambiguous citation— --fix leaves an ambiguous citation exactly as it found itrefuses to write a name that would break the markdown label— A name carrying a bracket is refused rather than written into a label it would breakreports a citation of a test declared with xit, which never runs— A citation of a test declaredxitis reportedreports a citation of a test declared with .skip the same way— One declared.skipis reported the same wayreports a root-relative href, which the drift check would never read— A root-relative href is reportedreports an href starting ./, which this gate would otherwise have skipped— An href starting./is reportedWhat you should actually do
reconstruction-grade spec the answer is almost always "update the spec".
([validated by …](…))link and#Lnnanchor on the statements you touch.rather than top-level symbols, and the behaviour still matches — close this as
stale rather than editing the spec.
Managed by Lore · created by
spec-drift· Lore-Task: b388029a-1732-405f-a936-8e774cc0e774