Thirty-six rule identifiers are cited in code and enforced by tests but defined in no document

[MelbourneDeveloper]

TL;DR

Thirty-six rule identifiers are quoted in the code and enforced by tests, but no document anywhere defines them. Behaviour is being locked in by tests that point at rules nobody can read, and the project's stated way of tracing a rule to its code and its tests silently returns nothing for all thirty-six.

Details

Throughout the code and the tests, comments cite a rule by a short bracketed identifier so anyone can search for that identifier and find the written rule, the code implementing it, and the tests holding it. That three-way trace is the project's core convention for keeping documents, code and tests honest with one another.

For thirty-six of those identifiers the written rule does not exist. Searching for them finds the code and the tests and nothing else. Twenty of the thirty-six appear in shipped code, not just in tests, so the gap is not confined to test scaffolding. Some are cited heavily — one appears in five separate shipped files, another in four.

This matters most where a test enforces the missing rule. The comparison panel is a live example: a test actively keeps two commands deleted and cites a rule identifier for why, and that rule is written down nowhere. Anyone trying to work out whether that decision was correct, or whether it may be revisited, has no document to consult and no way to tell whether the test is protecting a considered decision or an accident that has since calcified. The same applies to the ranking rule, which the project's own contributor instructions use as the worked example of how identifiers are supposed to be traceable.

The list also includes identifiers for language handling, logging, reporting context, severity banding, noise filtering and repair behaviour — so this is spread across most areas of the product rather than isolated to one recent change.

Steps To Reproduce

1. Clone the repository.
2. Search the code and tests for bracketed rule identifiers, and search the documents for the same identifiers.
3. Compare the two lists — thirty-six identifiers appear only in code and tests.
4. Pick [VSIX-PAIR-COMPARE] and search the documents folder for it — there are no matches, while the code and tests reference it more than ten times.
5. Pick [RANK-SCORE], the identifier the contributor instructions use as their example, and search the documents folder for it — no matches.

Details (for AI)

# environment
deslop --version: 0.0.0-dev (workspace build, commit 77b4681b)
os: macOS 26.6.2
surface: repo

# how the list was produced
grep -rhoE "\[[A-Z][A-Z0-9]+(-[A-Z0-9]+)+\]" clients/vscode/src crates/*/src crates/*/tests \
  --include="*.rs" --include="*.ts" --include="*.tsx" | sort -u > /tmp/ids_code.txt
grep -rhoE "\[[A-Z][A-Z0-9]+(-[A-Z0-9]+)+\]" docs/ | sort -u > /tmp/ids_docs.txt
comm -23 /tmp/ids_code.txt /tmp/ids_docs.txt      # -> 36 identifiers

# the 36 orphans (searched against ALL of docs/, not just docs/specs)
[AUTOFIX-CONSOLIDATE-CODE-ACTION] [BRACKETED-ID] [CLI-TEXT]
[CLONE-NOISE] [CLONE-NOISE-DART-WIDGET-SCAFFOLD] [CLONE-NOISE-EMBEDDING-ROLE]
[CORPUS-SCORE-GATE] [DESLOP-LIVE] [FACET-GROUP-BY-SEVERITY] [FUSED-RANK-MASS]
[LANG-CAND-DART] [LANG-CAND-GO] [LANG-CAND-JAVASCRIPT] [LANG-CAND-KOTLIN]
[LANG-CAND-TYPESCRIPT] [LOCATION-LINE-COLUMN] [LSP-CLI-HELP] [LSP-IPC]
[LSP-SEVERITY-BAND] [MCP-JSONRPC] [MCP-ROOT-CANONICAL]
[MCP-TOOL-REPORT-PAGINATION] [MCP-TOOL-REPORT-QUERY] [MCP-TOOLS-FIND-SIMILAR]
[PARSE-FSHARP-NORMALIZE] [PARSE-PHP-NORMALIZE] [PERF-SAMPLE]
[PIPELINE-SIGNATURE-FALLBACK] [PRINCIPLES-LOGGING] [RANK-SCORE]
[REPAIR-COSINE-MERGE] [REPAIR-RENAME-ANCHOR-MASS] [REPORTING-CONTEXT]
[SKIP-BREAKING-CI] [SPEC-ID] [TEST-ONE-BINARY] [TESTS-NO-INDEXING]
[VSIX-PAIR-COMPARE] [VSIX-REACTIVITY-DIRTY] [VSIX-SETTINGS-RANKING]

# 20 of them appear in production source, not only tests
[REPORTING-CONTEXT]            5 production files
[PRINCIPLES-LOGGING]           4
[LANG-CAND-JAVASCRIPT]         3
[FACET-GROUP-BY-SEVERITY]      2
[LANG-CAND-TYPESCRIPT]         2
[LSP-CLI-HELP]                 2
[LSP-SEVERITY-BAND]            2
[REPAIR-COSINE-MERGE]          2
[RANK-SCORE]                   1   # the worked example in AGENTS.md
[VSIX-PAIR-COMPARE]            0 production, 10+ across src and tests

# a test enforcing an undocumented rule
clients/vscode/src/test/unit/package-menus.unit.test.ts:17-23
  // [VSIX-PAIR-COMPARE] The retired implicit-compare commands. A single tree
  // row or hover can never name both endpoints of a pair, so these must stay
  // gone from every contribution surface.
  const IMPLICIT_COMPARE_COMMANDS = [
    "deslop.compareWithCanonical",
    "deslop.compareOccurrenceWithCanonical",
  ] as const;

# standing rules this breaks
AGENTS.md "Spec ids must be cross referenced across tests, code specs and plans ALWAYS"
AGENTS.md "Code, specs, and tests MUST agree. Where they don't, STOP and report."
AGENTS.md "Code and tests carry the ID in a comment so `grep [PARSE-` finds
           spec -> code -> tests."

# scope
affected surfaces: repo | cli | vsix | lsp | mcp
related issues: #524 (the [VSIX-PAIR-COMPARE] instance), #521, #522

Acceptance Criteria (for AI)

• Every bracketed rule identifier cited anywhere in clients/vscode/src, crates/*/src or crates/*/tests resolves to a section in docs/; a check asserts the orphan count is zero.
• That check runs as part of the lint gate, so a newly invented identifier cannot merge without its written rule.
• Each of the thirty-six listed identifiers is either given a written section carrying that identifier, or renamed to the existing identifier it meant, or removed together with the code and tests that cite it — with no test left enforcing a rule that no document states.
• [VSIX-PAIR-COMPARE] specifically has a written section stating the comparison rules, and it agrees with whatever is decided in Compare takes four clicks, cannot target the canonical occurrence, and cites a spec rule that does not exist #524.
• [RANK-SCORE] resolves to a written section, since the contributor instructions use it as the worked example of a traceable identifier.
• Searching any one identifier returns its document, its code and its tests; asserted for at least three of the previously orphaned identifiers.

Screenshots

None.