docs(spec-sessions-composition-pipeline): sessions composition pipeline — shared gate, split composers, single-round wire - #529

sdd-validate — spec boundary

Boundary resolved: Spec — docs/specs/05-spec-sessions-composition-pipeline/05-spec-sessions-composition-pipeline.md was added under docs/specs/, matching *-spec-*.md. Spec gate set applied (5 gates). No plan:provided marker on linked PR; standard spec gates apply.

Gate 1 — Acceptance criteria testable ✅ Pass

All R-ID statements describe observable behaviours that can be verified as pass/fail. Every criterion is tied to at least one named proof artifact (test name or file assertion). No vague aspirational statements were found among the R-IDs.

Gate 2 — No implementation leakage ⚠️ Warning

R-IDs throughout all five units name internal symbols — function names, type names, module paths, and call-site parameter values — where a behavioural statement would be sufficient. A retrospectively derived spec carries the code's vocabulary by nature, but the gate still applies. Representative instances:

• 05-spec-sessions-composition-pipeline.md Unit 1 intro: "The composition pipeline lives in crates/sessions/src/core/compose.rs" — a file path where a sentence about the shared gate module would stand alone.
• R1.3–R1.4: name gate_vars, VarsPolicy::check, hooks.on_var_unapproved, NeedsApproval, expand_patch_sources, PatchFile as subjects of behavioural statements. A restatement focused on the observable 3-pass algorithm and per-file fan-out removes the leakage.
• R2.2: "calls compose_contribution with hooks = None, uses the process environment as home_fallback" — prescribes an internal call site and a named parameter value. Behavioural form: "the client composer runs without hook callbacks; patch expansion uses the process environment for home-directory resolution."
• R2.4: "with_env(StoredEnv) replaces the default std::env::var lookup for tests" — prescribes the test-helper method name and parameter type.
• R3.1: "SessionComposer::new(client: WireContribution)" — prescribes the constructor signature.

The Repository Standards section prescribes coding conventions that belong in CLAUDE.md, not in a feature spec: "100% docstring coverage per the pre-merge check", "Error types use #[derive(Debug, thiserror::Error)]", "#[allow(clippy::unnecessary_wraps)] on Contribution::merge includes a reason comment". None of these carries an R-ID and none is covered by a proof artifact. The section could be dropped from the spec without loss of behavioural specification.

Advisory: future revisions can reframe R-IDs as behavioural statements and leave symbol names to the implementation. This leakage does not prevent shipping the spec.

Gate 3 — Assumptions explicit i️ Info

The spec surfaces key assumptions in Context, Design Considerations, Security Considerations, Gap Analysis, and Open Questions. One implicit assumption was not fully stated:

R4.4 asserts the "kind" serde tag is a "stable discriminator" for SessionStep and R4.6 asserts serde_json round-tripping holds without data loss, but the spec does not state whether this serialised wire format is a stable versioned API contract (safe for external callers to store or forward) or a test-scope assertion about the current tree. Callers who serialise and route SessionStep messages over a persistent transport need to know. A single sentence in Design Considerations would resolve this — e.g., "The wire format is a process-internal protocol between a client binary and its local daemon; no stability guarantee is offered to external consumers."

Gate 4 — Proof artifacts present and behavioral ✅ Pass

All five demoable units carry 2–3 proof artifacts (Unit 1: 3 Tests; Units 2–3: 2 Tests each; Unit 4: 2 Tests; Unit 5: 1 Test + 1 File). Every artifact names a specific cargo test -p sessions '<test-path>' command or a file-existence assertion with expected headings. None would pass against an empty pull request — the named tests and the named file do not exist until the implementation code and documentation are present.

Gate 5 — Demoable unit sized to a reviewable PR ✅ Pass

Unit 1 (core::compose) covers the core gate pipeline and is clearly well above the 400-line floor. Units 2–5 are individually narrower but each is separated from its neighbours by a genuine dependency edge (Units 2 and 3 both depend on Unit 1's compose_contribution; Unit 4 defines the WireContribution wire boundary that Units 2 and 3 cross; Unit 5 supplies the policy types that Unit 1 gates on). No unit forms a strict produce/consume chain with a cohesive sibling that has no other consumer. All five splits are exempt from the under-sized finding.

Result

No Blockers. needs-human not applied.

Gates 1, 4, and 5 pass clean. No lifecycle label move: the spec boundary does not advance the tracking issue lifecycle.

Generated by sdd-validate for issue #529 · ◷

_{Comment @coderabbitai help to get the list of available commands.}

Closing as deferred while @evanspearman completes loadouts