Skip to content

Commit e07b613

Browse files
remigiusz-antczakRemigiusz Antczakclaude
authored
feat(skill): 1.101.0 — wave 22 pre-hydration dead-controls (#256) and the read-first ask-ledger (#257) (#263)
Two owner-filed content lenses, each added to an already-routed reference (no SKILL.md edits — both are at the 24000-byte budget; no new files). #256 — product-ux-quality.md: a write control gated on client-only state (useAuth/useSession) is server-rendered `disabled` and enables only after hydration. For the SSR -> hydration window it is in the LOADING data state, not the permanent-disabled class that owes an explanation (#240): render it as loading (skeleton/spinner), or optimistic-enabled only when the click is captured and replayed so the handler is never a no-op (a dropped pre-hydration click is the dead-control / no-op-handler trust defect). Adds an interaction-completeness bullet, a pre-ship checklist item, a gate-1 `not-dead-before-hydration` detector, the fourth gate-1 timing class, and — per the independent review — the real pre-hydration capture primitive in testing-and-evals.md the detector cites (server-HTML / JS-disabled / throttled snapshot), so the gate has a routed positive control rather than a citation to an absent instrument. The static `disabled={!session}` tell stays an `unverified` lead; missing capture is could-not-check and fails open. #257 — fast-agentic-delivery.md: extends the unattended-work-loop rule so the durable backlog is also indexed by the owner's ask-set (one row per request: id, ask, status, evidence, next action), updated at each milestone and READ to answer "what's left" in one or two tool calls, never reconstructed from the transcript. A row is done only on the canonical surface (merged-to-default SHA / live URL) — project-state.md's receipt discipline, linked not restated. Distinct from the review-side end-of-session claim audit (method.md, #244) and the feedback-coverage map (roles.md). Lockstep version bump (deep-code-review, agentic-delivery, idea-critic, plugin) to 1.101.0; two new evals (dcr 102, agentic-delivery 27); SHA256SUMS regenerated. Tests: 67/67 CI gates pass; both evals.json valid; secrets + privacy scans clean; install.sh syntax OK; independent dogfood review FIX-FIRST -> one Medium fixed. Co-authored-by: Remigiusz Antczak <remigiusz@antczak.io> Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
1 parent 6281492 commit e07b613

11 files changed

Lines changed: 156 additions & 13 deletions

File tree

‎.claude-plugin/plugin.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
"name": "deep-code-review",
33
"description": "Perun — bring the thunder to your codebase. A portable, evidence-grounded quality bar for building with AI agents: the flagship deep-code-review skill (default install is review-only), plus opt-in overlays — gated delivery, an idea critic, a suite conductor, and stage-aware product, growth, positioning, business-ops, and output-safety specialists.",
44
"skills": "./.claude/skills",
5-
"version": "1.100.0",
5+
"version": "1.101.0",
66
"author": {
77
"name": "deep-code-review contributors"
88
},
Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
1.100.0
1+
1.101.0

‎.claude/skills/agentic-delivery/evals/evals.json‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -267,6 +267,17 @@
267267
"Bounds concurrency -- stops admission on rising swap / low headroom; names the 246-worktree / 99 GB stall as the inverse failure to avoid",
268268
"Holds BOTH halves at once (refill on quiet AND stop at the ceiling), not one at the expense of the other"
269269
]
270+
},
271+
{
272+
"id": "ask-indexed-read-first-request-ledger-in-long-sessions",
273+
"prompt": "In a 7-hour unattended run the owner has asked 'how much is left?' six times. Each time my agent re-reads about a thousand lines of transcript to rebuild the list, and a couple of items got re-done because their 'done' status was based on a branch existing. We already run an end-of-session reconciliation. What's missing?",
274+
"expected_output": "The end-of-session reconciliation is a run-once, review-side audit -- it does not fix MID-session drift, which is your actual failure. The durable backlog the loop already keeps must ALSO be indexed by the owner's ask-set: one row per distinct request (id, ask, status, evidence, next action), updated at each milestone, not only at the end. 'What's remaining' is then answered by READING that ledger -- one or two tool calls -- never by an O(N) re-scan of the transcript that silently re-litigates settled items. And a row is done only when its evidence points at the CANONICAL surface (a merged-to-default SHA or a live URL), not a branch that merely contains the fix -- project-state.md's receipt discipline (a checkpoint is a recorded claim, not evidence). The fix is not another audit; it is making the ledger a live, ask-indexed, read-first artifact. (fast-agentic-delivery.md.)",
275+
"expectations": [
276+
"Names mid-session drift as distinct from the end-of-session / review-side reconciliation, which does not fix it",
277+
"Requires the durable backlog to carry the ask-set (one row per owner request) updated at each milestone",
278+
"Answers 'what's left' by reading the ledger in one or two tool calls, not by re-scanning the transcript",
279+
"Marks a row done only on the canonical surface (merged-to-default SHA / live URL), not branch existence -- links project-state.md receipt discipline"
280+
]
270281
}
271282
]
272283
}

‎.claude/skills/agentic-delivery/references/fast-agentic-delivery.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -579,6 +579,20 @@ backlog until a termination condition fires*, not *do the one thing, then wait*.
579579
conversation, which a compaction or a handoff can drop. The
580580
**queue-a-requirement-to-a-file** rule above is this same discipline applied to
581581
*incoming* scope; this applies it to the *standing* backlog.
582+
- **Index the backlog by the owner's ask, and answer "what's left" by reading it — never by
583+
reconstructing from the transcript.** The file above is a ranked *work* list; a long or
584+
unattended session also needs it to carry the **ask-set** — one row per distinct owner
585+
request (id, ask, status, evidence, next action) — updated **at each milestone**, not only
586+
at the end. When the owner asks "what's remaining" (often after a gap), the answer is *read
587+
the ledger*, answerable in one or two tool calls — not an O(N) re-scan of hundreds of turns
588+
that silently re-litigates settled items. A row is *done* only when its evidence points at
589+
the **canonical surface** — a merged-to-default SHA or a live URL — not a branch that merely
590+
contains the fix (`project-state.md`'s Acceptance and Artifacts receipts, and *a checkpoint
591+
is a recorded claim, not evidence*). This is the runtime, ask-indexed form of the
592+
feedback-coverage map (`roles.md`); it is distinct from the review-side reconciliation that
593+
audits a report's own claims against the artifact before closing (`method.md`, the
594+
`deep-code-review` skill), which runs **once at the end** rather than being read live
595+
throughout.
582596
- **Name the termination conditions up front, each with its evidence.** The loop ends
583597
when the backlog is empty; when every remaining item is *blocked* on another party —
584598
including an item whose next step is an owner-approved action (push, merge, deploy:
Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
1.100.0
1+
1.101.0

‎.claude/skills/deep-code-review/evals/evals.json‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1073,6 +1073,17 @@
10731073
"Requires each claim to carry its method + viewport (+ route coverage) so results are comparable",
10741074
"Reconciles by a controlled follow-up changing one variable at a time, not by declaring a winner"
10751075
]
1076+
},
1077+
{
1078+
"id": "pre-hydration-write-control-is-loading-not-dead",
1079+
"prompt": "On our app's home and weekly pages, the Add comment / Submit update / Ask AI buttons render disabled for the first few seconds on a cold load, then go live once the page finishes loading. They read from a client-side useSession hook. A reviewer filed it as a 'disabled control needs an explanation' issue. Is that the right call, and how do we gate it?",
1080+
"expected_output": "No -- this is a different class from the contextually-disabled control that owes an explanation. That control STAYS disabled; these WILL enable themselves once the client bundle hydrates and useSession resolves. During the SSR -> hydration window they are in the LOADING data state, so they must LOOK loading -- a skeleton or spinner affordance -- not a bare dead-looking disabled button. The fix is a loading affordance, or optimistic-enabled ONLY if the click is captured and replayed after hydration so the handler is never a no-op; an enabled button whose pre-hydration click is silently dropped is the dead-control / no-op-handler trust defect, not a fix. Gate it as an unverified LEAD, not a finding: the static disabled={!session} pattern with no loading sibling is confirmed only by a pre-hydration render (a snapshot before the client bundle runs); where the harness cannot capture one, report could-not-check and fail open, never a silent pass. (product-ux-quality.md.)",
1081+
"expectations": [
1082+
"Reclassifies as the LOADING data state during the SSR -> hydration window, not the permanent contextually-disabled class that owes an explanation",
1083+
"Requires a loading affordance (skeleton/spinner) or optimistic-enabled with the click replayed after hydration; a dropped pre-hydration click is the no-op-handler defect",
1084+
"Treats the static disabled={!session} pattern as an unverified lead confirmed only by a pre-hydration render; missing capture is could-not-check / fail-open, not a pass",
1085+
"Does not conflate it with the permanent-disabled-needs-explanation rule"
1086+
]
10761087
}
10771088
]
10781089
}

‎.claude/skills/deep-code-review/references/product-ux-quality.md‎

Lines changed: 29 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -328,6 +328,23 @@ until it renders:
328328
an attainable alternative**, not left visibly dead — unless its discoverability is
329329
explicitly wanted (`frontend-a11y.md` owns the disabled-control *contrast*
330330
exemption; this owns the *recoverability*).
331+
- **A control disabled only until client state resolves is *loading*, not disabled —
332+
render it as loading, never dead.** A write control (add, submit, compose) gated on
333+
client-only state — `useAuth` / `useSession`, a hydration flag — is server-rendered in
334+
its `disabled` default, then enabled once the client bundle resolves. For the seconds of
335+
that SSR → hydration window it looks like a permanent dead control (the *no-dead-controls*
336+
class above), but it is really in the **loading** data state (the five-states rule) and
337+
must *look* loading — a skeleton or spinner affordance — not a bare disabled button with no
338+
reason. This is a distinct class from the *contextually-unavailable* case just above: that
339+
control **stays** disabled and owes an explanation; this one **will** enable itself and owes
340+
a loading affordance. Optimistic-enabled (render it enabled, act on the click) is allowed
341+
**only** when the click is captured and replayed after hydration, so the handler is never a
342+
no-op — an enabled control whose pre-hydration click is dropped is the *dead control / no-op
343+
handler* trust defect above, not a fix. The static tell — `disabled={!session}` on a write
344+
action with no loading sibling — is an **`unverified` lead, not a finding**: only a
345+
**pre-hydration render** (a snapshot taken before the client bundle runs,
346+
`testing-and-evals.md`) confirms it, so where the harness cannot capture one the gate reports
347+
*could-not-check* and fails **open**.
331348
- **Reviewable change history, and no silent AI edits.** Any surface where an
332349
edit is itself a decision of record (a value, a target, an assignment, an
333350
owner) needs a visible who/what/when history behind the current value, not a
@@ -476,6 +493,7 @@ often lost — the on-screen chart carries axes and a readout the serialiser dro
476493
- [ ] One shared component per concept — reused/extended, not reimplemented per page; a fix landed in the shared component, not one caller; **searched the tree for a duplicate twin (a duplicated visible string/heading) a diff-scoped review would miss**?
477494
- [ ] Interaction loops close — read-back on every input (no write-only), WYSIWYG not raw markup, no dead controls — checked on the route that actually renders?
478495
- [ ] Every **disabled action explains its cause and a recovery path** — the unmet prerequisite + a concrete next step, in **reachable** text (nearby or a focusable wrapper/popover, not a tooltip on the disabled element, which may get no hover/focus); an action permanently unavailable to the current role is hidden or replaced, not a dead end?
496+
- [ ] **No write control renders as a dead/disabled default during the SSR → hydration window** — a control gated on client-only state (auth/session) shows a loading affordance (skeleton/spinner) or is optimistically enabled with its click **replayed** after hydration (never a dropped no-op), not a bare disabled button; confirmed on a **pre-hydration** snapshot, and *could-not-check* (no pre-hydration capture) fails **open**, not a silent pass?
479497
- [ ] Drawers overlay (don't navigate away); collapse scope correct; no dead controls?
480498
- [ ] Verified live in the running product, in more than the happy-path state — **including the default state a user lands on** (signed-out / no-role / default route / local default), not only a mock or a hand-picked persona view?
481499
- [ ] Any "matches / exact / parity" claim checked against the **default served state of the tree under review** as the canonical surface (not whichever tree happens to hold the port — name url · branch · sha, `report-format.md`) — and if it rests on a non-default surface, does it **name** that surface and say the default was not checked?
@@ -653,6 +671,11 @@ task:
653671
- **disabled-looks-disabled** — a functionally disabled control is *visibly*
654672
disabled (cursor / opacity / painted colour, not only the attribute; the
655673
*no-dead-controls* interaction-completeness rule above, seen in the render);
674+
- **not-dead-before-hydration** — a write control gated on client-only state shows a
675+
loading affordance (or is optimistic-enabled with a **replayed** click), not a bare
676+
disabled default, in the **pre-hydration** render; the static `disabled={!session}` tell
677+
is an `unverified` lead until that snapshot confirms it (principle 2), so a harness that
678+
cannot capture pre-hydration reports *could-not-check*, never a pass;
656679
- **state named** — which data state the shot is of (empty / loading / error /
657680
populated), so an absence reads honestly (gate 2's state coverage; the
658681
empty≠all-clear rule above);
@@ -677,7 +700,12 @@ task:
677700
shot cannot see them, so on a `FULL` review they are ruled across the **rendered
678701
route sweep**'s matrix (above). **Gutters and optional-slot reservation read at
679702
rest** (the latter in the absent-slot data variant) — check them on the per-change
680-
shot too, and re-confirm in the sweep rather than defer to it.
703+
shot too, and re-confirm in the sweep rather than defer to it. And
704+
**not-dead-before-hydration reads only before the client bundle runs** — a fourth timing
705+
class neither the at-rest shot nor the mid-scroll sweep can see, because both capture the
706+
*post-hydration* render; it needs a snapshot taken inside the SSR → hydration window (a
707+
pre-hydration or CPU-throttled capture, `testing-and-evals.md`), and where the harness
708+
cannot take one the item is *could-not-check*, not clean.
681709

682710
A screenshot with an unstated inspection is an artifact read as the verification
683711
it is not.

‎.claude/skills/deep-code-review/references/testing-and-evals.md‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -160,6 +160,52 @@ fix, like any regression test. This is the mechanical proof behind the
160160
screenshot-inspection checklist's **overlap** and **clip** items
161161
(`product-ux-quality.md` gate 1).
162162

163+
## Capturing the pre-hydration render — the disabled-until-hydrated write control
164+
165+
The geometry assertions above run against the *hydrated* DOM, and one gate-1 defect is
166+
invisible there: a write control gated on client-only state (`useSession` / `useAuth`) is
167+
server-rendered `disabled` and enables only once the client bundle hydrates, so for the
168+
SSR → hydration window it looks like a permanent dead control (`product-ux-quality.md` gate 1,
169+
*not-dead-before-hydration*). Catching it needs a snapshot taken **before the client bundle
170+
runs** — three captures, cheapest first:
171+
172+
- **Server HTML** — fetch the route's server-rendered markup with no JS executed (the raw
173+
SSR/SSG response, the same bytes the user first receives) and parse it.
174+
- **JS-disabled render** — load the route with scripting off (Playwright:
175+
`browser.newContext({ javaScriptEnabled: false })`), which freezes the pre-hydration paint.
176+
- **Throttled capture** — screenshot within the hydration window under slow-CPU emulation;
177+
least reliable (a race), used only when the two above cannot reach the route.
178+
179+
The assertion is the same across all three: a control that **will** become interactive must
180+
not present as a bare `disabled` (or `aria-disabled="true"`) with **no loading sibling in its
181+
container** in that pre-hydration snapshot — it carries a skeleton/spinner affordance, or is
182+
optimistically enabled (its click captured for replay, never a no-op).
183+
184+
```js
185+
// Playwright: the pre-hydration paint must not show a dead write control.
186+
const ctx = await browser.newContext({ javaScriptEnabled: false });
187+
const page = await ctx.newPage();
188+
await page.goto(url); // server HTML, no hydration
189+
// scope to the control's own wrapper so the affordance is a sibling, not page-global
190+
// (a page-wide match would pass on any unrelated spinner; a broken scope that matches
191+
// nothing would fail every disabled control — stricter than the standard, gate 1 forbids):
192+
const box = page.locator('[data-testid="composer"]'); // the write control's container
193+
const btn = box.getByRole('button', { name: /add|submit|post/i });
194+
const disabled = (await btn.getAttribute('disabled')) !== null
195+
|| (await btn.getAttribute('aria-disabled')) === 'true';
196+
const affordance = await box
197+
.locator('[aria-busy="true"], [data-loading], .skeleton, [role="status"]').count() > 0;
198+
expect(disabled && !affordance).toBe(false); // dead-until-hydrated is the defect
199+
```
200+
201+
This is the **positive control** for the *not-dead-before-hydration* detector — the instrument
202+
that converts the static `disabled={!session}` *lead* into a finding (principle 2: *an absence
203+
is evidence only after a positive control fires*). Where the harness cannot produce any of the
204+
three captures for a route, the item is **could-not-check** and fails **open**; a missing
205+
snapshot is not a clean pass (`product-ux-quality.md` gate 1). It complements
206+
`domain-checklists.md`'s SSR/static-HTML inspection, which catches hydration-*nesting* faults
207+
in the same server-rendered output.
208+
163209
## A rewritten browser spec names its retired coverage and pins the wiring it can no longer reach
164210

165211
The geometry assertions above prove a rendered claim you can still reach. This is the

‎.claude/skills/idea-critic/VERSION‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
1.100.0
1+
1.101.0

‎CHANGELOG.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,39 @@
33
All notable changes to this repository are documented here. Format loosely
44
follows Keep a Changelog; versioning follows Semantic Versioning.
55

6+
## [1.101.0] — 2026-09-17
7+
8+
Wave 22 of the dogfooding batch: a control disabled only until client state hydrates is
9+
*loading*, not dead (#256); and a long unattended session answers "what's left" from a
10+
durable, ask-indexed ledger, not by re-reading the transcript (#257).
11+
12+
### Added — deep-code-review
13+
- **`product-ux-quality.md` — a control disabled only until client state resolves is
14+
*loading*, not disabled** (#256). A write control gated on client-only state
15+
(`useAuth`/`useSession`, a hydration flag) is server-rendered in its `disabled` default and
16+
looks like a permanent dead control for the SSR → hydration window, but it is in the
17+
**loading** data state and must *look* loading (skeleton/spinner) — distinct from the
18+
contextually-unavailable control that stays disabled and owes an explanation. Optimistic-
19+
enabled is allowed only when the click is captured and replayed after hydration (never a
20+
dropped no-op, which is the dead-control trust defect). The static `disabled={!session}`
21+
tell is an `unverified` lead confirmed only by a pre-hydration render — a fourth gate-1
22+
timing class, and could-not-check fails open. Adds an interaction-completeness bullet, a
23+
pre-ship checklist item, a gate-1 inspection detector, the timing-class extension, and the
24+
**pre-hydration capture primitive** its detector cites (a real server-HTML / JS-disabled /
25+
throttled snapshot procedure in `testing-and-evals.md`, so the gate has a routed positive
26+
control and is not a citation to an absent instrument). One new eval (102 total).
27+
28+
### Added — agentic-delivery
29+
- **`fast-agentic-delivery.md` — index the backlog by the owner's ask, and read it to answer
30+
"what's left"** (#257). Extends the unattended-work-loop rule: the durable backlog the loop
31+
already keeps must also carry the **ask-set** (one row per owner request: id, ask, status,
32+
evidence, next action), updated at each milestone; "what's remaining" is answered by reading
33+
that ledger in one or two tool calls, never by an O(N) transcript re-scan that re-litigates
34+
settled items. A row is done only on the canonical surface (a merged-to-default SHA or a
35+
live URL), not a branch that merely contains the fix — `project-state.md`'s receipt
36+
discipline, not restated. Distinct from the review-side end-of-session claim audit
37+
(`method.md`, #244) and the feedback-coverage map (`roles.md`). One new eval (27 total).
38+
639
## [1.100.0] — 2026-09-17
740

841
Wave 21 of the dogfooding batch: a coordinator's throughput follows its own cadence and the

0 commit comments

Comments
 (0)