chore(strings): sweep internal ADR/issue citations from shipped tool DESCRIPTIONS; decide machine enforcement for the ADR-number rule #79

New issue

Closed

opened 2026-07-15 04:27:36 +00:00 by hexajon · 0 comments

hexajon commented

2026-07-15 04:27:36 +00:00

(Migrated from codeberg.org)

Location inventory (from the #15 build, verified against the branch at the time):

internal/mcp/tools_help.go ~326, ~350, ~356, ~399
internal/mcp/help_generated.go (regenerates — fix the sources)
internal/mcp/tools_worktrees.go:71, 81
internal/mcp/tools_localgit.go:716
internal/mcp/tools_auth.go:182
internal/opspec/paramdocs.go:517
internal/service/workflow/finish.go:1341
internal/format/git/status.go:35
internal/mcp/hooks_claude.go:67
internal/cmd/auth/use_ssh.go:29 (path approximate)
internal/mcp/description_drift.go:789–808 carries 'ADR 0005' in contributor-facing lint diagnostics — deliberately out of scope (not shipped user-facing text); confirm and leave.

Second deliverable — machine enforcement (decision deferred from #15's escalation): the danglingref lint catches #NNN/issue NNN but not ADR NNNN, and cannot distinguish an in-scope refusal string from a doc comment. After this sweep removes the last legitimate description citations, evaluate extending the pattern to ADR \d+ over the shipped-string scan set (with an allowlist if needed), so a future refusal or description can't reintroduce a citation. Until then the rule is held by hand-sweep + per-refusal negative test assertions (added in #15).

Acceptance:

No shipped tool description or parameter doc carries an internal ADR/issue citation (rule stated in place, or citation dropped).
Reference docs regenerated; gate green.
Enforcement decision recorded (lint extended, or a documented reason it stays test-held).

Follow-up split out of #15 (its pinned scope covered hooks + steer/refusal string constants only). Tool DESCRIPTIONS also ship with the binary/plugin and still carry internal ADR/issue citations — ghost references for any user outside this org. Same class of problem as #15's swept strings, mechanical sweep: state the rule in place of the citation. Location inventory (from the #15 build, verified against the branch at the time): - internal/mcp/tools_help.go ~326, ~350, ~356, ~399 - internal/mcp/help_generated.go (regenerates — fix the sources) - internal/mcp/tools_worktrees.go:71, 81 - internal/mcp/tools_localgit.go:716 - internal/mcp/tools_auth.go:182 - internal/opspec/paramdocs.go:517 - internal/service/workflow/finish.go:1341 - internal/format/git/status.go:35 - internal/mcp/hooks_claude.go:67 - internal/cmd/auth/use_ssh.go:29 (path approximate) - internal/mcp/description_drift.go:789–808 carries 'ADR 0005' in contributor-facing lint diagnostics — deliberately out of scope (not shipped user-facing text); confirm and leave. Second deliverable — machine enforcement (decision deferred from #15's escalation): the danglingref lint catches `#NNN`/`issue NNN` but not `ADR NNNN`, and cannot distinguish an in-scope refusal string from a doc comment. After this sweep removes the last legitimate description citations, evaluate extending the pattern to `ADR \d+` over the shipped-string scan set (with an allowlist if needed), so a future refusal or description can't reintroduce a citation. Until then the rule is held by hand-sweep + per-refusal negative test assertions (added in #15). Acceptance: - No shipped tool description or parameter doc carries an internal ADR/issue citation (rule stated in place, or citation dropped). - Reference docs regenerated; gate green. - Enforcement decision recorded (lint extended, or a documented reason it stays test-held).

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

sixfold-space/madtea#79

No description provided.

Rows
Columns