-
Notifications
You must be signed in to change notification settings - Fork 4
docs: land DR-0013/DR-0014 and the issue-queue verdict layer #406
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from all commits
4f46174
eafd4e1
2f49c6d
cb6e9c6
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,76 @@ | ||
| # DR-0013 affected-host compilation isolation | ||
|
|
||
| Status: active | ||
| Date: 2026-09-30 | ||
|
|
||
| ## Decision | ||
|
|
||
| The development host recorded in issue #403 (Windows, `Win11ProW X64`, the | ||
| machine that owns this repository's checkout) is an **isolation-excluded | ||
| host**. While it is excluded: | ||
|
|
||
| - Do not run `cargo build`, `cargo test`, `cargo check`, `cargo clippy`, | ||
| `cargo run`, or `cargo nextest` at the workspace root. The repository's | ||
| verification policy (the user-level agent instructions file, outside this | ||
| checkout) requires `cargo test --workspace --no-fail-fast` after a change; | ||
| that requirement is **suspended on this host** and must be satisfied on | ||
| another host or in CI. | ||
| - Do not run `cargo clean` or otherwise mutate `target/`. | ||
| - Any repair whose acceptance depends on running the suite executes on a | ||
| different host, and its evidence is the CI run, not this machine. | ||
| - Read-only work is unaffected: source reading, `gh` queries, `git` queries, | ||
| and static file measurement are allowed. | ||
|
|
||
| The exclusion is lifted only by a new decision record that cites the | ||
| authorization the #403 report says it is waiting on. It is not lifted by | ||
| passing tests, by elapsed time, or by the absence of new crashes. | ||
|
|
||
| ## Why | ||
|
|
||
| Issue #403 was filed 2026-09-29 and states the constraint directly: "Do not | ||
| reproduce, build, or run the full test suite on the affected Windows host." | ||
| This host is that machine. A session on 2026-09-30 started | ||
| `cargo test --workspace --no-fail-fast` here and had to be terminated after | ||
| several test binaries had already run; the exclusion would have been honored | ||
| by any session that read the open `bug` issues first, and none should depend | ||
| on that. | ||
|
|
||
| The host does not fail from resource exhaustion, and the record must not | ||
| imply otherwise. Measured on 2026-09-30: 32 logical processors, 93.7 GB RAM, | ||
| pagefile allocated 68 GB with a 1.4 GB peak usage, all four physical | ||
| disks report `Healthy`, and the System event log holds **zero** WHEA-Logger | ||
| records in the preceding 7 days. Six `Kernel-Power 41` restarts fall on | ||
| 2026-09-29 between 03:55 and 19:17; three carry `BugCheckCode` 0, and the | ||
| other three carry `BugCheckCode` 26 (`0x1A`, `MEMORY_MANAGEMENT`) with | ||
| `BugcheckParameter1` 63 (`0x3F`, pagefile inpage error). `Ntfs` event 98 | ||
| entries in the same window read "volume is healthy; no action needed" and are | ||
| health-check records, not corruption reports. | ||
|
|
||
| So the crash is real and repeatable, and "compilation exhausted memory" is | ||
| **not** a supported explanation. #403 itself holds causation open pending an | ||
| authorized dump analysis that this account cannot perform. This record does | ||
| not settle causation; it isolates the host so that a repair can proceed | ||
| without betting the machine on an unproven theory. | ||
|
|
||
| `docs/decisions/README.md` exists because a scope rule decided in one | ||
| session's chat is invisible to the next session, and #208 is the recorded | ||
| case: an exact-lock PR was produced in parallel with a floor-pinned session. | ||
| An unstated "don't run the suite on this box" rule fails the same way, at a | ||
| higher cost, because the failure mode is a crash rather than a wrong PR. | ||
|
|
||
| ## Enforcement | ||
|
|
||
| - This record, plus the #403 body, are the two places a session must be able | ||
| to read before running a build or test command. The cost is one `gh issue | ||
| view 403` and one listing of `docs/decisions/`. | ||
| - Agent instructions in `AGENTS.md` carry the "check #403 before compiling" | ||
| line for this repository; that file is the surface a new agent reads first. | ||
| - Convention only: no gate mechanically blocks `cargo test` on this host. The | ||
| cost of a mechanical guard (a wrapper that refuses, shadowing cargo) exceeds | ||
| the cost of the rule until a second host needs the same protection. | ||
| - The verified resource-pressure defect in #403 is a **separate** matter and is | ||
| not blocked by this record: `crates/code-intel-cli/src/snapshot.rs` | ||
| `digest_worktree` retains every scoped file in `records` and | ||
| `hash_records` concatenates them into a second `canonical` buffer before | ||
| hashing, so peak allocation scales with whole-tree content times two. It is | ||
| repairable, and repairing it does not require compiling here. |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,122 @@ | ||
| # DR-0014 issue convergence verdict rule | ||
|
|
||
| Status: active | ||
| Date: 2026-09-30 | ||
| Amended: 2026-09-30 (convergence pass; see "Amendment" below) | ||
|
|
||
| ## Decision | ||
|
|
||
| Convergence of this repository's issue queue means: **every open issue carries | ||
| an explicit verdict of `do`, `freeze`, or `close`.** It does not mean the | ||
| backlog reaches zero, and it does not mean open issues reach zero. | ||
|
|
||
| An issue is converged when it is either: | ||
|
|
||
| - **done** — the work shipped, or | ||
| - **frozen** — `backlog`, with a written reason for why it is out of the current | ||
| scope, or | ||
| - **closed** — it is obsolete, superseded, or already satisfied by merged work, | ||
| with a comment saying which. | ||
|
|
||
| A session that opens implementation work on a `backlog` issue without first | ||
| recording why it is no longer frozen is violating this record. DR-0007 already | ||
| makes GitHub Issues the delivery source of truth, so the verdict lives in the | ||
| issue, never in a planning document. | ||
|
|
||
| ## Amendment (2026-09-30 convergence pass) | ||
|
|
||
| The original rule defined the three verdicts but said nothing about **the | ||
| act of auditing them**, and the pass found three ways a queue can look | ||
| converged while it is not. These are now part of the rule. | ||
|
|
||
| ### 1. A label is not a verdict | ||
|
|
||
| `backlog` was on 65 issues while 27 of them carried **no comment at all**. The | ||
| rule already required "a written reason"; enforcement did not say what to do | ||
| about labels applied in bulk on 2026-08-03 that never got one. Those 27 now | ||
| carry reasons. | ||
|
|
||
| **A verdict is a comment carrying evidence, not a label.** A label may be | ||
| applied in bulk; the reason may not. | ||
|
|
||
| ### 2. `claimed` is a claim about a session, and it goes stale silently | ||
|
|
||
| The pass found **four** zombie claims — #302, #47, #193, and | ||
| #395/#396/#397 — all with the same shape: a claim comment naming a branch, no | ||
| push, no PR. Three of them (DR-0004 names the 48h bar) had been open for 37-40 | ||
| days. Two of them additionally contradicted themselves: #47 was both `backlog` | ||
| and `claimed` at once, which the two label definitions make impossible. | ||
|
|
||
| DR-0004 says a stale claim is releasable after 48h. This record adds the part | ||
| DR-0004 cannot enforce: **`claimed` is a statement about a live session, so a | ||
| reviewer must treat a claim as unverified until the branch is confirmed to | ||
| exist.** A claim comment is an assertion, not evidence. | ||
|
Comment on lines
+51
to
+53
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win Check claim freshness as well as ref existence. DR-0004 permits takeover when a claim has had no push for 48 hours. An old branch can still exist, so confirming the ref does not establish that the claimed session is live. Require the audit to check the last-push age, or state that ref existence is only one part of verification. See Also applies to: 55-56 🤖 Prompt for AI Agents |
||
|
|
||
| **Verifying a claim means checking the named ref exists** — in local heads, in | ||
| origin refs, and in any other ref. A comment that names a branch is not a | ||
| branch. | ||
|
|
||
| ### 3. "Work exists" is not "work delivered" | ||
|
|
||
| The pass found four distinct states that a raw open-issue count cannot | ||
| distinguish: | ||
|
|
||
| | State | Case found | | ||
| |---|---| | ||
| | Shipped but ticket open | #383 — fix merged via PR #388 | | ||
| | Implemented, in remote, never PR'd | #123 — 2 commits on `origin/issue-307-bounds-oversize-input`, no PR | | ||
| | Implemented, in local branch, never pushed to `main` | #363 — commit `e923a70`, PR #364 closed as misrouted | | ||
| | Implemented, uncommitted, evidence gone | #393 — code on disk, `target/issue-393-verification/` deleted | | ||
| | Claimed, implemented, **worktree deleted** | #395/#396/#397 — branch has 0 commits ahead of main, directory gone | | ||
|
|
||
| The last row is the reason the other four matter: the same missing step — a | ||
| push — that would have saved #395/#396/#397 also separates "delivered" from | ||
| "written down" in every other row. | ||
|
Comment on lines
+72
to
+74
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win Include the commit step in the work-preservation rule. Line 70 says the branch had zero commits ahead of 🤖 Prompt for AI Agents |
||
|
|
||
| **Do not close an issue because the code looks done.** Check where the work | ||
| actually is: merged into `main`, on a remote branch, on a local branch, | ||
| uncommitted, or gone. Each state has a different correct verdict. | ||
|
|
||
| ## Why | ||
|
|
||
| On 2026-09-30 the open queue held **96 issues, 65 of them `backlog`**. The | ||
| `backlog` label's own definition reads `Frozen: not in the v1 convergence scope` — so those 65 are decisions *not* to build, not unfinished work. The oldest, #14, has sat since 2026-07-24, 68 days. | ||
|
|
||
| A session told to "do all the outstanding work" reads 96 and attempts 96. That | ||
| session dies before its first PR, and the queue it leaves behind is no better | ||
| than the one it inherited. The failure is not stamina; it is that the input | ||
| number and the actual obligation are different numbers, and only the label | ||
| distinguishes them. | ||
|
|
||
| The same day produced two concrete instances of the cost. Issue #383 was still | ||
| open and still `claimed` although PR #388 had already merged its fix — a | ||
| ticket that looks like work and is not. Issue #302 held a claim from | ||
| 2026-08-21 whose branch existed in neither local heads nor origin refs; a claim | ||
| that looks like an active session and is not. Both were invisible in a raw | ||
| count of open issues. | ||
|
|
||
| Issue #267 compounds it. It was unparked on 2026-09-14 and named #269 as its | ||
| first frontier, but #270 through #273 remained `backlog` with no matching | ||
| unpark record. The precondition was met and nothing moved, which no count of | ||
| open issues can reveal. | ||
|
|
||
| The convergence pass turned both of those into patterns: a bulk-applied label | ||
| with no reason behind it, and a claim that outlived its branch by weeks. The | ||
| three amendments above exist so that the next pass does not rediscover them | ||
| from scratch. | ||
|
|
||
| ## Enforcement | ||
|
|
||
| - Convention only: no gate inspects issue labels. The cost of a mechanical check | ||
| is higher than the cost of the rule while the queue is being reduced by hand. | ||
| - A session claiming convergence cites per-issue verdicts, or it claims nothing. | ||
| - When citing a `do` verdict, state **where the work is**, per amendment §3. A | ||
| verdict without that is incomplete. | ||
| - When auditing `claimed`, confirm the named ref exists, per amendment §2. | ||
| - The survey that motivated this record is `docs/problem-inventory-2026-09-30.md`; | ||
| the open handoff is `docs/handoff-2026-09-30-issue-convergence.md` (it was | ||
| first written into `.superpowers/sdd/`, a directory gitignored with `*`, and | ||
| moved here so a worktree can see it). | ||
| - This record does **not** retract DR-0005. Being under the open-PR ceiling | ||
| permits starting new work; it does not oblige a session to do backlog items, | ||
| and a session that unfreezes a `backlog` issue does so explicitly. | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Align the open-issue verdicts with the convergence states.
Lines 9–10 require every open issue to have a
do,freeze, orcloseverdict. Lines 13–19 define convergence usingdone,frozen, orclosed, but do not mapdoto any of those states. State whether an open issue with adoverdict is converged before its work ships. Otherwise, sessions can reach different convergence results.Also applies to: 13-19
🤖 Prompt for AI Agents