Skip to content

docs(adr): decline ADR 0089 Phase D (helper descent) by owner ruling - #91

Merged
wshallwshall merged 1 commit into
mainfrom
decline-phase-d
Jul 31, 2026
Merged

docs(adr): decline ADR 0089 Phase D (helper descent) by owner ruling#91
wshallwshall merged 1 commit into
mainfrom
decline-phase-d

Conversation

@wshallwshall

Copy link
Copy Markdown
Collaborator

Owner ruled 2026-07-30: helper descent is too risky. ADR 0076 Amendment B goes PROPOSED⛔ DECLINED, and ADR 0089 Phase D is not to be built.

Recorded in four places, deliberately

A decline that lives only where it was argued is a decline nobody finds. The load-bearing one is ADR 0089 itself — a session planning the next lens phase reads 0089's phase list, not an amendment to a different ADR. And 0089's own text sells Phase D as "the largest structural lever" against "265 delegating call-sites".

File Change
adr/0089 §Phase D ⛔ ruling banner above the original paragraph, which is retained unchanged
adr/0076 Amendment B status block → DECLINED, with the case and the reopening bar
adr/0076 status line Amendment B marked declined
adr/README.md index row updated (edited in place — the ledger gate rejects a second [0076] row)

Also corrects, at 0089 §Phase D: "265 delegating call-sites" is a statement-scan count, not a yield estimate. Descent makes nothing editable by itself — it swaps opaque delegating rows for helper-body rows whose editability is whatever Phases A–C already achieve inside helpers.

Decline-by-design, not deferral

The specification stays. Not as a plan — so the reasoning is auditable, and so the next reader who concludes "helper delegation is 41.8%, that's the biggest remaining win" finds the work already done rather than re-deriving it.

Reopening requires a new amendment, and must first:

  1. Answer aliasing — two call sites of one helper produce identical child row spans; expect_src matches both, so an edit to one silently rewrites the other. No ADR addresses this.
  2. Produce a real per-helper editable-share measurement, not the 218/522 heuristic superset, which never checks whether a callee resolves to a same-module def.

The yield may be negative: msg["X"] = v is not recognized (only msg.set(...) is), and the shipped samples/config/_demo_oru_transforms.py writes exclusively in that form — descending it returns six opaque rows and zero editable ones.

Promoted from precondition to recommendation

Teaching Phase A the ast.Assign-to-ast.Subscript form (msg["X"] = v) converts writes into editable rows without touching the row shape at all, and is on no phase list. It is explicitly not declined.

Incidental fix — a stale cross-reference this session introduced

BACKLOG #239's banner cited #240 (comment-only rows) from before that item was renumbered to #248. #240 is now a permanent hole, so the citation resolved to nothing — the exact failure mode the #88 erratum describes, committed by the session that wrote the erratum. Corrected, and the same banner's "~70% of the opaque mass" argument is amended: with Phase D declined it rests on comment-only rows alone, so re-measure before assuming the number moves.

Verification

python scripts/docs/backlog_status_check.py   → OK — 242 items, each declaring exactly one status
python scripts/security/scan_forbidden.py     → clean
python scripts/hooks/ledger_check.py          → no blocks
grep "#240 (comment"                          → no matches remaining

Docs-only, +44/−8 across four files. No code, no behaviour change, no number allocated.

🤖 Generated with Claude Code

Owner ruled 2026-07-30 that helper descent is too risky. ADR 0076
Amendment B goes PROPOSED -> DECLINED, and Phase D is not to be built.

Recorded in four places, because a decline that only exists where the
decline was argued is a decline nobody finds. The load-bearing one is
ADR 0089 itself: a session planning the next lens phase reads 0089's
phase list, not an amendment to a different ADR, and 0089's own text
sells Phase D as "the largest structural lever" against "265 delegating
call-sites". That paragraph is left intact with the ruling above it,
plus the correction that 265 is a statement-scan count and not a yield
estimate -- descent makes nothing editable by itself.

Decline-by-design, not deferral. The specification stays so the reasoning
is auditable and so the next reader who thinks helper delegation is the
biggest remaining win finds the work already done. Reopening takes a new
amendment, and must first answer the aliasing question (two call sites of
one helper produce identical child spans; expect_src matches both, so an
edit to one silently rewrites the other) and produce a real per-helper
measurement rather than the 218/522 heuristic superset.

Promotes the alternative from precondition to recommendation: teaching
Phase A the ast.Assign-to-ast.Subscript form (msg["X"] = v) widens what
is editable without touching the row shape, and is on no phase list.

Also fixes a stale cross-reference this session introduced: #239's banner
cited "#240 (comment-only rows)" from before that item was renumbered to
#248. #240 is now a permanent hole, so the citation pointed at nothing --
the exact failure the #88 erratum describes. The same banner's
"~70% of the opaque mass" argument is corrected: with Phase D declined it
rests on comment-only rows alone.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@wshallwshall
wshallwshall enabled auto-merge (squash) July 31, 2026 01:20
@wshallwshall
wshallwshall merged commit 8dd338e into main Jul 31, 2026
31 checks passed
@wshallwshall
wshallwshall deleted the decline-phase-d branch July 31, 2026 01:22
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant