randomparity / randomparity/kdive

Amend ADR-0537: its dedup rationale misreads issue #1485

Open Beginner friendly
#1,813 2 comments 0 reactions 0 assignees View on GitHub
area:mcp-api effort:S priority:P3 status:needs-human type:docs
Dominant language
Python
Stars
0
Forks
0
Avg merge
1h 26m
Merged PRs (30d)
311

Description

## Problem

`docs/adr/0537-mcp-protocol-version-drift-two-clocks.md` records, in `## Consequences`, a
factual claim about issue #1485 that is false in three independent ways. Commit
`b66e2a5c9` states the same claim in its message as a *measured* result, and it is the
stated justification for that commit's change to the dedup search.

The ADR predicts the drift cron's first run will file nothing. It filed #1812. The
shipped behaviour is correct — #1812 is a properly-titled tracking issue naming the actual
revision, and the dedup will match it on every subsequent run, in any state — so this is
not a code defect. It is a wrong premise preserved in an accepted decision record, which
is the artifact a future reader trusts when they next touch this workflow.

## Evidence

`docs/adr/0537-mcp-protocol-version-drift-two-clocks.md`, `## Consequences`:

> It will not file anything, because issue #1485 ("Investigate MCP 2026-07-28 Spec Update
> Requirements") is already open and names that revision — the dedup finds it and the run
> passes quietly.

Measured against the live repository on 2026-08-04:

| Claim | Actual |
|---|---|
| #1485 is titled "Investigate MCP **2026-07-28** Spec Update Requirements" | Titled "Investigate MCP **2026-06-18** Spec Update Requirements" — a different revision |
| #1485 "is already open" | Closed 2026-08-04T10:14:12Z |
| #1485 "names that revision" | Its body links a *2026-06-18* release candidate; the string `2026-07-28` appears nowhere. `gh issue list --state all --search "2026-07-28"` does not return it |
| "It will not file anything" | The cron filed #1812 at 2026-08-04T10:20:37Z |

The dedup cannot match #1485 on any code path.
`.github/workflows/mcp-spec-drift.yml:134-137` searches `"${NEWEST} in:title"` and then
filters client-side with `select(.title | contains("${NEWEST}"))`. Both halves match on
**title**. #1485's title does not contain `2026-07-28`, so the `--label area:mcp-api`
conjunct that `b66e2a5c9` removed was never what hid it.

That commit's message asserts the opposite as a measurement:

> Measured: issue #1485 ("Investigate MCP 2026-07-28 Spec Update Requirements") is open
> and names the exact revision this cron reports, but carries no area:mcp-api label. The
> label-filtered query returns nothing for it; the unfiltered one returns it.

The unfiltered query does not return it either.

Two further ADR statements are downstream of the same premise and are now also untrue as
written — `#1485 does not carry this workflow's labels, and a label-filtered query would
have missed it and duplicated it on day one`, and `so #1485 stays open until that work is
scheduled`.

## Expected

A reader of ADR-0537 can see that its dedup rationale was based on a misread issue title,
that the dedup matches on title alone, and that the first cron run filed #1812 rather than
deduping. The original prose stays intact — `docs/adr/README.md:22-30` makes a merged ADR
append-only outside `## Status`, and the records CI gate reports `E-REWRITE` on a changed
line.

Removing the label conjunct from the search is still defensible on its own merits — an
issue tracking the revision under a different label set would now be found — so the code
needs no change. Only the record does.

## Proposed approach

Append one amendment block to ADR-0537's `## Consequences` section, in the form
`docs/adr/README.md:24-26` mandates:

```
### Amendment (YYYY-MM-DD): the first cron run filed #1812 rather than deduping on #1485 (#NNNN)
```

It should state why it is an amendment, name the claim it qualifies, give the corrected
facts about #1485 from the table above, record that the dedup matches on title so the
label conjunct was never the operative filter, and note that the removal of that conjunct
remains justified independently.

Scope is one file and one PR. No change to
`.github/workflows/mcp-spec-drift.yml`, `scripts/check_mcp_spec_version.py`, or
`src/kdive/mcp/__init__.py`.

Verify with `just records-check` (or whichever recipe runs the `docs/adr/` gate) to confirm
the appended block parses as an amendment and reports no `E-REWRITE`.

## Notes

Found while scoping #1812, which is parked at `status:blocked` — adopting `2026-07-28`
needs `mcp` 2.x, which no stable `fastmcp-slim` accepts. This issue is independent of that
blocker and can land at any time.

No `risk:` label assigned: the value has not been judged by a human, and absence is the
correct third state rather than a default.

Contributor guide

Open the contributing guide

Research direction

Read docs/adr/0537-mcp-protocol-version-drift-two-clocks.md and the amendment rules in docs/adr/README.md:22-30, then run just records-check to understand the gate. Append the required amendment under Consequences, preserving the original prose and recording the corrected #1485 and #1812 facts. Done means the amendment parses and the check reports no E-REWRITE; do not change the workflow or Python files.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
1/5
Estimated time
1-3 hours
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
82/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.