docs: retire future-considerations.md in favour of the issue tracker - #244
Conversation
Merges the 'Introducing cgo' and 'Python Purity Is Not Enforced' entries from docs/future-considerations.md into a single ADR: they are one comparative decision, and the Python entry's rationale only reads against the Go one. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The file had been serving as a manual tracker while the repo had no real one. Its nine entries were four different kinds of thing: settled decisions, deferred work, revisit triggers, and one research record. They now live where each kind belongs. - Entries 2-3 (cgo, Python purity) became ADR-0001 in the previous commit. - Entries 1, 4, 5, 6, 7, 9 became issues #238-#243, with each entry's 'Trigger to revisit' line carried into the issue body and the trigger- gated ones labelled 'blocked'. - Entry 8 (devcontainer git plumbing) became Syndic/.dotfiles#119, since the remaining work is entirely in that repo. Eight in-repo references are repointed at the ADR or the issue that replaced them. One is not a doc reference: the commit-file-via-app selftest used the file as its 'tracked, deliberately never modified' fixture for the partial-diff case, so that moves to docs/reminder-tags.md. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…covery 'blocked' is orthogonal to the five canonical triage roles rather than a sixth one, so an issue keeps its state role alongside it. That preserves information — ready-for-agent + blocked means the brief is written and the work is grabbable the moment the trigger fires — at the cost of one thing that must not be forgotten: discovery queries have to exclude it, or an agent picks up work it cannot finish. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Syndic
left a comment
Syndic
left a comment
There was a problem hiding this comment.
Automated review pass. Verified locally: meta/scripts/test_check_no_cgo.py is 22/22 green with the new ADR-path assertion, and the agent-grabbable query genuinely folds both filters (--label enhancement returns 6 issues; adding --search "-label:blocked" returns 2). UNCHANGED_PATH: docs/reminder-tags.md is a sound fixture — the file is tracked and the workflow never writes it, and even a PR that edited it would be safe since the scratch branch is cut from the checked-out commit.
Three inline findings below, plus one that has no diff line to attach to:
.github/workflows/ci.yml:278 — pointer to a section this PR deleted
# Python (`@pypi` wheel resolution is host-bound; see CLAUDE.md "Python Purity Is
# Not Enforced"). The matching runner also keeps test execution native: ...The sweep grepped for the filename future-considerations, so it missed sites that cite the deleted file's section heading instead. "Python Purity Is Not Enforced" never existed in .claude/CLAUDE.md — it was docs/future-considerations.md's heading — and after this PR it exists nowhere: the content landed in ADR-0001 under "Enforce the same for Python — rejected". grep -rn "Python Purity Is Not Enforced" across the PR head returns zero hits.
Concretely: someone editing the platform matrix reads this comment, greps for the section, finds nothing, and the rationale for why each row's runner must match its target arch is unreachable from the only place that points at it. Suggest repointing to docs/adr/0001-go-builds-are-pure-python-is-not.md.
Worth a second sweep on heading text generally, not just the filename — that's the class of reference the current grep can't see.
Four findings from the review pass: - ci.yml's platform-matrix comment cited the section heading 'Python Purity Is Not Enforced' (and attributed it to CLAUDE.md, where it never lived). The filename sweep missed it because the quoted heading wraps across two comment lines. Repointed at the ADR, and re-swept with the text reflowed so wrapped references are visible; nothing else stale. - The four blocked issues carried no state role, contradicting the invariant this PR documents and leaving them unreachable by every discovery query — the silently-forgotten failure mode the section exists to prevent. #239 and #240 are now ready-for-agent, #242 and #243 ready-for-human, on whether the work needs a judgement call when its trigger fires. - The documented trigger marker was '**Trigger to revisit:**'; the issues use a '## Trigger to revisit' H2. Fixed the docs rather than four issue bodies. - ADR-0001 attributed the gazelle_python blocker to the purity policy, where MODULE.bazel attributes it to the pinned Go SDK. MODULE.bazel is right: check_no_cgo.py walks go.work members and the plugin is a Bazel module, so the policy check never reaches it. The ADR now records that scope limit instead, and issue #239's body was corrected to match. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
|
Re: the Confirmed, and the diagnosis about heading-vs-filename is exactly right — with a detail worth recording, because it explains why the original sweep could not have caught it. The reference wraps across two comment lines: # Python (`@pypi` wheel resolution is host-bound; see CLAUDE.md "Python Purity Is
# Not Enforced"). The matching runner also keeps test execution native: BBSo It was also wrong in a second way: it attributes the heading to Fixed in ff5cef6, repointed at For the general case, I re-swept with every tracked file reflowed — comment markers ( |
1 participant
Retires
docs/future-considerations.md, which had been serving as a manual tracker while the repohad no real one. This is the first step of migrating from the ad-hoc organisation to the structure
#235 set up.
Why the file had to be split rather than moved
Its nine entries were four different kinds of thing wearing one name:
Introducing cgo,Python Purity Is Not Enforced)._create_whl_reposskippingrequirements_files_by_platform()whenuv_lockis present". These ride with their work item;they are not independent of what they unblock.
rules_python2.2.0 establishing that its advertiseduv.lock consistency check is not actually implemented. That finding stays true whether or not the
work ever happens.
Where each went
ready-for-humanblockedrequirements_lock.txtblocked(carries the research record)ready-for-agentblockedblockedThe
blockedlabelNew, and orthogonal to the five canonical triage roles rather than a sixth one — an issue keeps
its state role alongside it.
ready-for-agent+blockedis the useful combination: the brief iswritten, so the work is grabbable the moment the trigger fires.
The cost is that discovery queries must exclude it, or an agent picks up work it cannot finish.
docs/agents/issue-tracker.mdnow carries the query(
--label ready-for-agent --search "-label:blocked", verified to filter 6 issues down to the 2unblocked ones) and
docs/agents/triage-labels.mdcarries the meaning.blockedcovers both external gating (an upstream release) and internal gating (wanting to see howa recent change behaves first). The
**Trigger to revisit:**line in each issue body says which.A
plannedlabel was considered for the internal case and deliberately deferred: with noactive-worklist concept for it to contrast with, it would land on every open issue and stop meaning
anything.
One change that isn't a doc reference
The
commit-file-via-appselftest useddocs/future-considerations.mdas its "tracked,deliberately never modified" fixture for the partial-diff case. That moves to
docs/reminder-tags.md. This is the one change CI has to prove — it needs the app credentials,so it can't be validated locally.
Validation
bazel test //...— 23/23 pass, includingtest_check_no_cgo, whose assertion on the errormessage's pointer moved to the ADR.
pre-commit run --from-ref origin/main --to-ref HEAD— clean.grep -rn future-considerations— no remaining references. The sweep found eight sites, fivemore than the two docs and one README link we knew about going in.
🤖 Generated with Claude Code