glm-5.2
5941280bca
Address the root cause of rework-causing hedging: the architect was
put in a logical bind where it couldn't express justified uncertainty
('the pieces exist but the shape isn't clear yet'). The only options
were 'decide now' (premature) or 'deferred(scope)' (false — the
information isn't missing, it's un-synthesized). The agent picked
deferred(scope) with a circular blocking condition (OQ-64 blocked on
OQ-55, OQ-55 needs OQ-64) because there was no honest way to say 'I
can see the pieces but I can't see the shape.'
Changes to the architect role spec:
- Add deferred(unclear) state: the pieces exist but the composition
isn't clear; resolution requires investigation (work through
examples, POC), not waiting. Has an investigation target and an
impacts field.
- Add 'Impacts' field to the OQ format: what does this block
downstream? Be specific ('blocks the first hub deployment because
the hub dials workers' not 'blocks the hub crate'). The triage
signal that makes deferral urgency visible — the field that would
have made the AlknetClient circular hedge visible.
- Add circular-reasoning guard to self-review: 'check that your
blocking condition isn't a prerequisite of the thing you're
deferring.'
- Trim anti-patterns #9-#11 (hedging synonyms catalog, ~40 lines):
detection belongs in the reviewer, not the architect's self-review.
The architect is too close to its own reasoning to see its own
circular hedges.
- Trim door-types section (30→10 lines): keep the one-paragraph
summary, cut the elaboration.
Changes to the architecture-reviewer role spec:
- Add Decision Quality (F) category: false-deferral check
distinguishing three cases — (1) hedging on a resolved decision, (2)
false deferral / circular hedge (the blocking condition is a
prerequisite of the thing being deferred), (3) legitimate deferral.
- Add Impacts Field Coverage (G) category: check that unresolved OQs
have specific impacts fields.
- Note: the Decision Quality category is often the highest-value
check on poorly-defined projects — the architect cannot self-review
it (circular reasoning is invisible from inside the circle).
Retrofit existing OQs:
- Add Impacts field to all 16 unresolved OQs (10 deferred, 6 open).
- Update OQ-63 (TlsError shape) to reflect ADR-087's client-side
addition — the error type now covers both server and client
variants.
- Move OQ-65 (WebSocket carrying channels) to alknet-http theme
(done in prior commit; this commit adds its impacts field).
- Verified: no circular reasoning found in existing deferrals. The
AlknetClient hedge (OQ-64) was the circular one; it's already
resolved by ADR-087.
2.2 KiB
2.2 KiB
OQ-57: Two-Pump Helper Extraction to alknet-core
- Origin:
docs/research/alknet-channels/poc-summary.md§Issues Surfaced #7;docs/architecture/decisions/078-two-pump-shutdown-on-completion.md - Status: deferred(scope)
- Door type: two-way (additive — a helper function does not change any API surface; handlers that inline the pattern continue to work)
- Priority: low
- Impacts: None — the two-pump contract is decided (ADR-078) and handlers implement it inline. Would reduce ~10 lines of copy-paste per handler when extracted; not a capability gate.
- Blocked on: a second two-pump handler existing, so the shape
convergence is observable. The tunnel handler is the first two-pump
consumer; the SSH
direct-tcpipchannel will be the second. Extracting the helper from one consumer (the tunnel) would bake in a shape that the second consumer (SSH) might not fit — thefn pump_bidi<R, W>(recv: R, send: W, ...) -> impl Futuresignature is a cross-crate API surface if it lives inalknet-core. The trigger is: two real two-pump handlers exist and their inline implementations have converged on the same shape. - Resolution: Not yet decidable. The shutdown-on-completion contract
is decided (ADR-078) — a two-pump handler MUST shut down the opposite
sink when one pump completes, or it deadlocks. The helper extraction is
an implementation convenience: ~10 lines of inline code per handler vs. a
shared function in
alknet-core. The contract is pinned; only the extraction is deferred. The helper is extracted when two real consumers exist and their shapes converge, so the extraction is grounded in two implementations rather than guessed from one. - What does NOT block on this: the two-pump pattern is documented
(ADR-078) and the tunnel handler implements it inline. The SSH crate's
direct-tcpiphandler will implement it inline too. Both work without a shared helper. The friction is copy-paste with documentation (~10 lines), not a missing capability. - Cross-references: ADR-078 (the shutdown-on-completion contract),
ADR-074 (the
accept_bithat yields the stream pair the pumps operate on),docs/research/alknet-channels/poc-summary.md§Issues Surfaced #7