Skip to content

doctor: check results cite private-tracker issue numbers, one of which links to an unrelated public issue #205

Closed

Description

@Paul-Kyle

palinode doctor attaches a linked_issue to some check results, and --format json prints it (palinode/diagnostics/formatters.py:59). Three values ship from the diagnostics package, and all three are issue numbers from the private development tracker rather than this repository's:

Value Where On this tracker
#1025 (6×) palinode/diagnostics/checks/git_identity.py 55, 69, 77, 93, 120, 128 Does not exist — issues here reach ~204
#190 (2×) palinode/diagnostics/checks/memory_dir.py 27, 39 #190 — "Use one rounding rule for match percentages", unrelated to memory directories
#371 (2×) palinode/diagnostics/checks/recall_write_health.py 36 and 122 Does not exist

#190 is the worst of the three because it does not look broken. Someone debugging a missing memory directory follows the link and lands on a rounding-rule issue, with no signal the reference was never meant for this repository.

#371 is the one to be careful with. Line 36 is _LINKED_ISSUE = "#371", a module constant referenced by six CheckResult branches — so a search for linked_issue="# will not find it. Line 122 is a bare #371 inside a remediation message, which the user reads directly. Fix both.

A guard for this rule already exists, and it has a hole. tests/test_no_issue_refs_user_surface.py enforces the no-bare-reference rule across CLI help, MCP schema descriptions, Python comments, docstrings, CI workflow comments, and root config files. It does not scan string literals, which is where all ten of these live. Its docstring explains the rule and the escape hatch: a bare #NNN is unfollowable; a full public URL is fine.

What the PR should do:

1. Fix all ten references. For each, either cite the full public URL if a public issue genuinely covers it, or remove the reference and let the message stand on its own. linked_issue is str | None (types.py:24) and None is already the default for most checks, so removal is valid and usually right. Do not invent a mapping to keep the field populated. In recall_write_health.py, that means the constant and the mention inside the remediation text.

2. Add a guard scoped to this package. A new test asserting that no string constant in palinode/diagnostics/ carries a bare issue reference — constants included, which is what makes it catch the _LINKED_ISSUE shape. The existing file already walks source with tokenize (_comment_refs_in, line 151); an ast pass over string constants is the simpler route here, and either is fine.

Scope it to palinode/diagnostics/ and say so in the test's docstring. Do not widen it to the whole repository: there are further bare references elsewhere in palinode/ whose correctness has not been assessed, and — more importantly — intentional fixtures would fail, including this guard's own test_bare_number_is_rejected (line 304), which contains "Issue #100: the body was mangled." on purpose. A repository-wide policy is a separate decision and not part of this issue.

Verify it bites: put a bare #1234 into one of the fixed values, confirm your new test fails, then remove it. A guard nobody has watched fail is a guard nobody knows works — which is how ten references survived a rule written to forbid them.

Scope: the three check modules and tests/test_no_issue_refs_user_surface.py. No behaviour change to any check — only reference strings and the new test.

Context, not scope: the same class was fixed in the parity registry in #204 last week; that thread has the reasoning.

Comment here to claim it. Please wait to be assigned before opening a PR — two contributors landed on one issue once because we had no such line.

Activity

  1. Kaap10 commented on Sep 12, 2026

    @Kaap10
    Contributor

    Hi @Paul-Kyle, I'd like to work on this.

    I will:

    1. Clean up the 10 bare issue references across git_identity.py, memory_dir.py, and recall_write_health.py (removing linked_issue where appropriate and updating the remediation text).
    2. Add an AST-based test in tests/test_no_issue_refs_user_surface.py scoped to palinode/diagnostics/ to assert that no string constants contain bare #NNN references.
    3. Verify the new test fails against the bare references before fix and passes after.
    4. Add an entry to docs/CHANGELOG.md under ## Unreleased.

    Please assign this to me!

  2. Paul-Kyle commented on Sep 12, 2026

    @Paul-Kyle
    MemberAuthor

    Assigned — thanks for picking this up. Your inventory is right, including the part a grep cannot see: recall_write_health.py holds its reference in the _LINKED_ISSUE constant rather than a literal at the call site.

    Scoping the new test to palinode/diagnostics/ is the right call, and worth keeping even though a repo-wide version looks tempting: the existing tests/test_no_issue_refs_user_surface.py can't simply be widened, because a repo-wide string scan rejects that file's own test_bare_number_is_rejected fixture.

    Ten occurrences across the three modules you named. The changelog entry goes under one of the existing headings in ## Unreleased — please add your bullet there rather than adding a new heading.

  3. Kaap10 commented on Sep 12, 2026

    @Kaap10
    Contributor

    Hi @Paul-Kyle, I have opened PR #207 for this issue.

    All 10 bare issue references have been cleaned up, the AST guard test has been added to tests/test_no_issue_refs_user_surface.py scoped to palinode/diagnostics/, and all CI test and security suites are passing.

    Ready for your review whenever you have time!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

bugSomething isn't workinggood first issueGood for newcomers

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions