From cd5fe0f4026c43af78ab0f80f78d661e88faedc0 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 18 Aug 2026 13:44:52 +0000 Subject: [PATCH 1/2] docs(issues): stop the issues skills pointing at the retired visual register MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Ledger issue #338 retired the legacy ISSUES-LIST.html on 2026-08-18, making docs/outstanding-issues.md the sole canonical cross-platform register. Three instruction surfaces still told sessions to refresh the retired artifact: - .claude/skills/issues/SKILL.md carried a whole "Refresh the visual register" section with an absolute-Windows-path PowerShell command, plus an `issues list` trigger that opened the retired HTML. - AGENTS.md described reconciliation as refreshing the visual register. - .agents/skills/ledger/SKILL.md referenced it in its step 6. The stale instructions have a real cost: a container session that follows them cannot run the Windows script, so it dutifully reports a "stale visual register" that no longer exists as a concept. That happened during the 2026-08-18 evening reconciliation (PR #2120). Replace the section with a short statement that the canonical ledger is the register, naming #338 so the retirement is not silently re-litigated. The canonical .agents entry is word-budgeted, so its line is shortened rather than extended — check:skills enforces a 220-word ceiling and went red on a longer replacement. Also queue one follow-up: the serialized issues:reconcile operation has no interlock, and two reconcile PRs (#2119, #2120) were open simultaneously. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01C6WXAK931ZPgisknbCTnpR --- .agents/skills/ledger/SKILL.md | 2 +- .claude/skills/issues/SKILL.md | 33 +++++++------------ AGENTS.md | 5 +-- .../a5f073f9-c82a-4d42-86af-0a36159a9403.json | 14 ++++++++ 4 files changed, 30 insertions(+), 24 deletions(-) create mode 100644 docs/outstanding-issues-inbox/a5f073f9-c82a-4d42-86af-0a36159a9403.json diff --git a/.agents/skills/ledger/SKILL.md b/.agents/skills/ledger/SKILL.md index 2f780d9cd4..7a69649e20 100644 --- a/.agents/skills/ledger/SKILL.md +++ b/.agents/skills/ledger/SKILL.md @@ -10,6 +10,6 @@ description: Sweep the current session, repo/task context, local task files, and 3. Report tasks, risks/blockers, and up to three `/ledger` suggestions before writing. 4. Keep high-confidence items only; dedupe against open rows by intent and reference duplicates as `#NNN`. 5. Queue with `npm run issues:add -- --pri P2 --type issue --summary "" --detail "<detail>" --source "session YYYY-MM-DD /ledger sweep"` — never hand-edit. It creates one inbox record; a dedicated branch runs `npm run issues:reconcile`. If nothing is new, create no request. -6. Run `npm run check:outstanding-issues` as a read-only validation when useful. Do not refresh the visual register: canonical Markdown changes only at reconciliation. +6. Run `npm run check:outstanding-issues` as a read-only validation when useful. Canonical Markdown changes only at reconciliation. 7. Commit the immutable inbox request file when asked; run `npm run issues:reconcile` only from a serialized current-main worktree after the request branch lands. Never push without an explicit ask. 8. Full procedure and fields: `.claude/skills/ledger/SKILL.md`. diff --git a/.claude/skills/issues/SKILL.md b/.claude/skills/issues/SKILL.md index 87d9e98847..039da93031 100644 --- a/.claude/skills/issues/SKILL.md +++ b/.claude/skills/issues/SKILL.md @@ -20,8 +20,9 @@ the report; record that fetch separately because the report itself performs no p ## Trigger - User types `/issues` (optionally with a subcommand or filter below). -- User says **`issues list`**: refresh the artifact from the current worktree's - `docs/outstanding-issues.md`, then open `C:\Users\joshs\OneDrive\ISSUES-LIST.html` in Codex. +- User says **`issues list`**: read the queue back from the current worktree's + `docs/outstanding-issues.md`. There is no separate artifact to open — see "The canonical + ledger is the register" below. - User asks to add / close / update / list / capture an outstanding task, recommendation, or issue. ## Default: `/issues` (read-only) @@ -102,27 +103,17 @@ part of an ordinary product PR. - Respect the repo's RAG/clinical/privacy flagging rules if an item _itself_ touches a protected surface — recording it here is fine, but acting on it later still needs the usual gate. -## Refresh the visual register +## The canonical ledger is the register -`docs/outstanding-issues.md` remains the canonical rendered source. Queueing a request does not -change it, so do not refresh the visual artifact after `add`, `update`, `done`, `capture`, or a -ledger sweep. Refresh only after a successful reconciliation or before opening an `issues list`: +`docs/outstanding-issues.md` is the sole canonical, cross-platform register. Read it directly, or +through `npm run issues:report -- --json`. There is no second artifact to refresh, and no step of +this skill produces one. -```powershell -& 'C:\Users\joshs\.codex\scripts\refresh-issues-list.ps1' -LedgerPath (Join-Path (Get-Location) 'docs\outstanding-issues.md') -``` - -Require the decisive `ISSUES_LIST_UPDATED` line. The stable artifact is -`C:\Users\joshs\OneDrive\ISSUES-LIST.html`. If refresh fails, do not undo a valid ledger mutation; -report that the Markdown source is current and the visual artifact is stale. Still proceed to the -reconciliation handoff — a stale visual artifact must not invalidate a successful canonical -transaction. - -**This step is unavailable off the operator's Windows machine.** The script and the artifact are -both absolute Windows paths, so a Linux, container, or cloud session cannot run it and cannot -verify it — the artifact drifts silently from the moment such a session reconciles. Do not -improvise a substitute renderer or write the HTML by hand; report the register as stale, name the -reconciliation commit that made it so, and leave the refresh to the operator. +The legacy `ISSUES-LIST.html` visual register was **retired on 2026-08-18** by ledger issue `#338`, +precisely because it could only be refreshed from one Windows machine and so drifted silently as +work moved to container and cloud sessions. Do not refresh it, do not report it as stale after a +reconciliation, and do not improvise a substitute renderer — a reconciliation that updates the +canonical Markdown is complete on its own. ## Persist the memory (commit) diff --git a/AGENTS.md b/AGENTS.md index 81a7952bc5..b493acc7c3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -958,8 +958,9 @@ to the recommended queue. - `/issues add|done|update|capture …` queue immutable request files under `docs/outstanding-issues-inbox/`; ordinary branches never edit the canonical ledger. Commit a request only when explicitly asked, and never push unless requested or already handing off. - One deliberately serialized fresh-base branch later runs `npm run issues:reconcile` and refreshes - the visual register after the canonical transaction succeeds. + One deliberately serialized fresh-base branch later runs `npm run issues:reconcile`, which alone + edits the canonical ledger. That transaction is the whole deliverable: the legacy `ISSUES-LIST.html` + visual register was retired by `#338` on 2026-08-18, so there is no second artifact to refresh. - Proactively offer to `capture` unresolved follow-ups, deferrals, and known risks into the ledger before a session's context is lost — that is what keeps it a memory rather than a stale list. - **An open row is not evidence that nobody is building it.** Some rows do carry a progress marker in diff --git a/docs/outstanding-issues-inbox/a5f073f9-c82a-4d42-86af-0a36159a9403.json b/docs/outstanding-issues-inbox/a5f073f9-c82a-4d42-86af-0a36159a9403.json new file mode 100644 index 0000000000..1a1b5fa46d --- /dev/null +++ b/docs/outstanding-issues-inbox/a5f073f9-c82a-4d42-86af-0a36159a9403.json @@ -0,0 +1,14 @@ +{ + "version": 2, + "id": "a5f073f9-c82a-4d42-86af-0a36159a9403", + "createdOn": "2026-08-18", + "action": "add", + "payload": { + "pri": "P2", + "type": "rec", + "summary": "The serialized issues:reconcile operation has no interlock, and two reconcile PRs were open simultaneously on 2026-08-18", + "detail": "AGENTS.md requires npm run issues:reconcile to run from ONE deliberately serialized fresh-base branch, but nothing enforces that: the reconciler's own guards (stale base, dirty canonical file, cross-worktree lock) are all local to a single machine and cannot see a second reconcile branch already pushed. On 2026-08-18 two were open at once — PR #2110/#2119 (claude/issues-reconcile-20260818, 'reconcile 74 queued requests') and PR #2120 (claude/issues-reconcile-2026-08-18-evening, 88 requests). Both merged. It only came out clean by luck of ordering: #2120 merged first and had already applied a superset of the 74, so GitHub's squash of #2119 collapsed to a 1-line review record and the canonical ledger was left correct (verified after the fact on main 4575cf57: 365 rows, 48 open, 0 pending, 339 applied, check:outstanding-issues and check:ledger-write-discipline both green). Had #2119 merged first, #2120's recorded transaction would no longer have equalled the canonical diff and check:ledger-write-discipline would have gone red on a branch that must never be synced from main — the documented recovery is to close the PR and redo the whole reconcile from a fresh base. Next: give the reconcile path a cheap pre-flight interlock rather than relying on operator discipline — e.g. have issues:reconcile refuse (or loudly warn) when git ls-remote --heads origin shows another unmerged branch carrying inbox renames under docs/outstanding-issues-inbox/applied/, which needs no provider tooling beyond a remote ref listing and no GitHub API call. Related to #292 (duplicate concurrent work) but distinct: this is a serialization invariant on a single canonical file, not two sessions building the same feature.", + "source": "session 2026-08-18 evening reconcile; PRs #2119 and #2120 both open and merged same day", + "issueUlid": "01M0AHM1XDEH9VA63ZZAT9XPH3" + } +} From dae0e707c9028c5e5681e32ec5f54cf80c4de3c5 Mon Sep 17 00:00:00 2001 From: Claude <noreply@anthropic.com> Date: Tue, 18 Aug 2026 14:08:24 +0000 Subject: [PATCH 2/2] docs(ledger): record the #2120 prlanded verification and this review Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01C6WXAK931ZPgisknbCTnpR --- ...47d9ce4c41758e474d87071283c5c52543e48b01b71fb1c7be6.record.md | 1 + ...8b740f3154b9d6732135c8663968e76f3b6d90c02261583ca72.record.md | 1 + 2 files changed, 2 insertions(+) create mode 100644 docs/branch-review-records/919dacc65e8ee47d9ce4c41758e474d87071283c5c52543e48b01b71fb1c7be6.record.md create mode 100644 docs/branch-review-records/e2220e1f5f8658b740f3154b9d6732135c8663968e76f3b6d90c02261583ca72.record.md diff --git a/docs/branch-review-records/919dacc65e8ee47d9ce4c41758e474d87071283c5c52543e48b01b71fb1c7be6.record.md b/docs/branch-review-records/919dacc65e8ee47d9ce4c41758e474d87071283c5c52543e48b01b71fb1c7be6.record.md new file mode 100644 index 0000000000..0b60f99847 --- /dev/null +++ b/docs/branch-review-records/919dacc65e8ee47d9ce4c41758e474d87071283c5c52543e48b01b71fb1c7be6.record.md @@ -0,0 +1 @@ +| 2026-08-18 | claude/post-reconcile-review-2026-08-18 | cd5fe0f4026c43af78ab0f80f78d661e88faedc0 | retire stale visual-register instructions in issues/ledger skills + AGENTS.md; queue reconcile-serialization follow-up | clean — three instruction surfaces no longer point at the ISSUES-LIST.html artifact #338 retired; check:skills regression introduced and fixed within the diff (220-word canonical budget) | verify:pr-local (22/22 gates, 0 failed, 0 unreached); test:ci-workflows 325 passed; check:skills exit 0 (was 1 mid-change, baseline re-measured); format (whole tree) | diff --git a/docs/branch-review-records/e2220e1f5f8658b740f3154b9d6732135c8663968e76f3b6d90c02261583ca72.record.md b/docs/branch-review-records/e2220e1f5f8658b740f3154b9d6732135c8663968e76f3b6d90c02261583ca72.record.md new file mode 100644 index 0000000000..ac09912b48 --- /dev/null +++ b/docs/branch-review-records/e2220e1f5f8658b740f3154b9d6732135c8663968e76f3b6d90c02261583ca72.record.md @@ -0,0 +1 @@ +| 2026-08-18 | claude/issues-reconcile-2026-08-18-evening | ed19e1435049e284088c0e8d042465004390c4de | prlanded | clean — PR #2120 merged as squash ed19e143; two-dot content diff against branch tip 0771039f is empty, all 90 files landed including the review record, no orphaned late commit from the auto-merge race | git diff --stat ed19e143 0771039f (empty); ledger record 6b6d74c4 present on main; check:outstanding-issues on main 4575cf57 (365 rows, 48 open, 0 pending / 339 applied) |