refactor(sessions): decompose the sessions node into eight children - #496
Conversation
BLOCKING [consistency]: spx/21-spec-tree.enabler/76-sessions.enabler/15-session-store.enabler/session-store.md:11Reference: PR body: "Preserve assertion semantics exactly: 60 before, 60 after, every assertion moved byte-identically." Governing rule at spx/21-spec-tree.enabler/54-refactoring.enabler/refactoring.md line 15: "NEVER: change assertion semantics during a refactoring operation, refactoring moves structure, not meaning." |
BLOCKING [consistency]: .github/workflows/spec-tree-evals.yml:104Reference: CLAUDE.md, Generated Sources in Verification Scope, states that spx/local/generated-sources.toml declares the BEGIN eval-trigger-paths / END eval-trigger-paths blocks in .github/workflows/spec-tree-evals.yml as a generated relation sourced from spx//evals//eval.toml and regenerated by just build-eval-triggers. CLAUDE.md instructs: Do not hand-edit the marker-delimited paths blocks in .github/workflows/spec-tree-evals.yml; the gates eval-triggers step fails on drift. No other findings survived review. The 60 assertion count was verified line by line against the diffs removed and added hunks and totals exactly 60 both before and after the split across all nine children plus the three retained in sessions.md. Every test and eval relative path link was re-rooted correctly for its new directory depth. The renamed decision record 65-pickup-claim-verification.adr.md and all citations to it were checked repo wide with no dangling references remaining. The single eval referencing 76-sessions.enabler/sessions.md is local-completion-boundary, and its owned_paths and trigger entries were updated consistently everywhere that reference appears. |
Move the session store and the spx session command contract into 15-session-store.enabler, and claim reconciliation into 28-pickup.enabler/30-claim-verification.enabler, each with its co-located tests. Both sit below 32-session-skill-invocation.enabler because that node declares the invocation surface for flags whose behavior these concerns define. 24 of the node's 60 assertions move; 36 remain on the parent covering handoff and pickup resumption, with the compaction rules staying as cross-cutting. The count across the node and its descendants is unchanged. PLAN.md records the reserved indices, the ordering-evidence matrix, and the destination of every remaining assertion, so the rest of the composition is mechanical. Refs: spx/21-spec-tree.enabler/76-sessions.enabler
Narrow the session-store kind statement to the todo/doing transitions it actually specifies, and restate its first scenario as the CLI behavior its linked test establishes rather than the /handoff trigger judgment the test never exercises. Delete the foundation-marker exemption from session-store. The same rule already stands at spx/21-spec-tree.enabler/18-context-loading.enabler over a wider command set, so restating it here was duplication rather than a second concern. The node total falls 60 to 59 for that reason. Give 28-pickup.enabler the checkout-currency rule as its own assertion. It constrains claim reconciliation and resumption alike, and an enabler whose Assertions section carries no claim-shape heading is not valid structure. Refs: spx/21-spec-tree.enabler/76-sessions.enabler
ISSUES.md gave 36 where the node holds 35, and credited the two new children with 24 assertions where they carry 23 before the separately named currency rule. The currency assertion cited the claim-verification decision, which explains why reconciliation is needed but mandates no checkout operation. The handoff-persistence decision is what requires /pickup to fetch and check out the ref before reading. Counts surfaced by the changeset review, the citation by the spec audit. Refs: spx/21-spec-tree.enabler/76-sessions.enabler
Add the "Required by" column decomposing.md mandates, naming for each edge the successor assertion or workflow step that depends on the predecessor's contribution, and add the row for the handoff-persistence decision that constrains the session store. Replace the disposition sentence that called 15-session-store.enabler and 21-compact-continuity.pdr.md "independent peers at the same index" while assigning them 15 and 21. The checkpoint now states every sibling pair under the node, including the two decision records it never examined, and says plainly when a different-index pair is sound without an ordering edge. Both surfaced by the changeset review. Refs: spx/21-spec-tree.enabler/76-sessions.enabler
Create 25-handoff.enabler with closure, continuation-disposition, session-document, and closeout-report children, and 28-pickup.enabler/60-resumption.enabler. The 32 assertions move verbatim; the parent keeps only the three compaction rules, which are cross-cutting rather than owned by any child. Repair what the move invalidated: the [eval] link is re-rooted for its new depth and the eval's owned_paths gains the closure node so a change there still fires it; both decision records now cite the session-document child for the pointer contract that left sessions.md; and the ancestor plan's EXCLUDE worklist entry points at closure.md. The subtree total stays at 59. PLAN.md reduces to the one open question, decision placement; the composition issue is resolved and its ISSUES.md entry removed. Refs: spx/21-spec-tree.enabler/76-sessions.enabler
The occupancy-preservation rule spans document creation, artifact archiving, and branch release, so it belongs to the handoff concern as a whole rather than to closure alone. The payload command form governs the invocation that writes the document, so it moves to the session-document child. Refs: spx/21-spec-tree.enabler/76-sessions.enabler
The composition deleted this node's SPEC_TREE_FOUNDATION exemption for spx session commands, because spx/21-spec-tree.enabler/18-context-loading.enabler states the same rule over a wider command set and a spec audit rejected the restatement as duplication. Nothing in the tree recorded that, so a reader comparing the node before and after the split sees a rule vanish. The node now names where the rule lives and that no descendant restates it. Surfaced by the changeset review as a dropped assertion. Refs: spx/21-spec-tree.enabler/76-sessions.enabler
Restore the foundation-marker exemption to 15-session-store.enabler. It duplicates spx/21-spec-tree.enabler/18-context-loading.enabler, which a spec audit correctly identified, but deleting a declaration is a content change and refactoring.md forbids changing assertion semantics during tree surgery. ISSUES.md entry 2 carries the removal as its own change. The subtree total returns to 60, matching the node before the split. Move the claim-verification decision from index 65 at this node to index 20 inside 28-pickup.enabler. A decision reaches only siblings above it, so from 65 it constrained neither 30-claim-verification.enabler nor 60-resumption.enabler; from 20 it constrains both. PLAN.md stated the opposite and now states the reach each decision actually has. Both surfaced by the changeset review. Refs: spx/21-spec-tree.enabler/76-sessions.enabler
Restore the ordering-evidence matrix, extended to cover the handoff and pickup sub-children and the three decision records. decomposing.md requires the matrix recorded before index assignment, and it is the durable justification for the tree's shape rather than scaffolding the composition consumes. Disposition the four children that sit above the roughly-seven signal. Each carries one validation boundary stated across its cases, so the count is accepted here with the condition that would reopen it, matching how other nodes in this tree dispose of the same signal. Both surfaced by the changeset review. Refs: spx/21-spec-tree.enabler/76-sessions.enabler
The checkout-currency assertion cited the claim-verification decision before the move, so a pure relocation cites that decision at its renamed path. Repointing it to the handoff-persistence decision was more accurate but changed the assertion's meaning inside tree surgery, which refactoring.md forbids and which this changeset already reverted once for a deleted assertion. ISSUES.md entry 3 carries the correction, with the evidence that the cited decision states no currency rule and the one that does. Refs: spx/21-spec-tree.enabler/76-sessions.enabler
The first session-store Scenario was narrowed to the CLI behavior its linked test establishes, dropping the /handoff trigger conditions from its Given clause. The observation behind that is sound — the test drives the CLI directly and exercises neither condition — but narrowing an assertion's subject is a meaning change, and this changeset is tree surgery. With this restored, every one of the 60 assertions is byte-identical to its form before the split, apart from one citation that follows its target's rename, which refactoring.md requires of a move. ISSUES.md entry 4 carries the correction and the evidence for it. Refs: spx/21-spec-tree.enabler/76-sessions.enabler
The ordering-evidence matrix and decision-placement notes addressed siblings by bare name, which is ambiguous because numeric prefixes are sibling-local: index 20 holds both a closure node and a claim-verification decision under different parents in this node. Refs: spx/21-spec-tree.enabler/76-sessions.enabler
2e7241b to
fbaec52
Compare
|
|
No findings. |
1 participant
Summary
Background
The node carried 60 assertions against the roughly-seven signal that decomposing.md treats as requiring decomposition analysis. The changeset reviewer raised it as architecture debt on PR 494.
The concerns it held are independently governable and were tangled: the session store and its command contract, the closing flow, per-thread continuation disposition, document shape, the operator closeout, claim reconciliation, and the resumption flow.
Changes
New children under
spx/21-spec-tree.enabler/76-sessions.enabler:15-session-store.enabler(16) — the.spx/sessions/store andspx sessioncommand contract, withtest_sessions.scenario.l1.py25-handoff.enabler(1) — the occupancy-preservation rule spanning its children, with20-closure.enabler(9),40-continuation-disposition.enabler(10),60-session-document.enabler(5),80-closeout-report.enabler(2)28-pickup.enabler(1) — the checkout-currency precondition, with30-claim-verification.enabler(8) carrying both pickup verification tests, and60-resumption.enabler(5)The parent keeps the three compaction rules, which are cross-cutting rather than owned by any child.
The claim-verification decision moved from index 65 at the parent to index 20 inside the pickup node. At 65 it constrained neither pickup child, because a decision reaches only siblings above it; at 20 it constrains both.
Repaired what the move invalidated: the
[eval]link re-rooted for its new depth, the eval owned_paths gains the closure node, both decision records repointed to the session-document child, and the ancestor plan worklist repointed to closure.md.Test plan
just checkpasses all 27 selected stepsRefs
Need help on this PR? Tag
@codesmith-botwith what you need. Autofix is disabled.