Cross-spec decision propagation: a post-MVP backend decision silently diverged a later consumer spec's contract — the system view should link them

[montfort]

Summary

A real adopter case (Sentinel, dogfooding StrayMark) surfaced a class of drift StrayMark does not currently catch: a decision recorded in one spec's post-MVP backlog silently invalidated the contract assumed by a later, separate spec — and nothing connected the two. The implementation then diverged from both, and the tests passed because their mocks encoded the assumed (wrong) contract.

This is adjacent to #303 (cross-boundary contract verification at audit time) but is a different lever: it is about decision propagation across specs and the system view that should make a contract's source-of-truth singular. Filing it as a capability gap for the Loom / architecture model and the cross-artifact analysis.

The concrete case

Sentinel has two SpecKit specs authored months apart:

• spec 001 (backend MVP) modeled service health as service-level (score + state). Its post-MVP backlog item PM002 (later approved, AILOG-2026-04-24-006) extended the model to per-component health (score + state per component) and per-service metrics persisted in a versioned health_scores.details JSONB.
• spec 005 (frontend dashboard), authored later, defined the Health Dashboard (FR-010: "estado por componente y métricas (latencia P95, error rate, CPU, memoria)").

Three artifacts that should agree drifted into a triple mismatch:

1. Frontend implementation assumed a contract that matched neither — wrong field names (name vs display_name, status vs state, score vs health_score), wrong enum values (GREEN/YELLOW/RED vs OPERATIONAL/DEGRADED/MAJOR_OUTAGE/IDLE), and per-component raw metrics that were never modeled (it rendered latency/CPU/memory columns per component).
2. spec 005 FR-010 was ambiguous about granularity ("estado por componente" and "métricas" — two clauses the implementation fused into "metrics per component").
3. spec 001/PM002 — the actual source of truth for the backend contract — was never referenced by spec 005, because it lived in a different spec's post-MVP backlog. The frontend author had no thread pointing to it.

Net effect: the frontend's Health view never worked against real data. It only "passed" because e2e/unit mocks reproduced the assumed contract. The drift was invisible until the SPA ran against the real backend in staging (a runtime TypeError: t.find is not a function).

Why nothing caught it

• The truth was distributed across 3 documents with no edges between them. The contract producer (backend handler), the decision that shaped it (PM002, in another spec's backlog), and the consumer (frontend spec + code) were not linked in any StrayMark artifact.
• A post-MVP decision in spec A is invisible to spec B. PM002 changed what spec 001 promised, but spec 005 was authored against spec 001's original shape. Nothing flagged "a consumer spec depends on a contract that a later decision changed."
• Mocks encoded the assumption, not the contract. Green tests gave false confidence — they verified the code against the same wrong model it was built on.

The generalizable pattern

A decision (AILOG/AIDEC/PM/Charter) that changes a contract in one spec does not propagate to downstream specs/components that consume that contract, and no view makes the contract's source-of-truth singular. The drift only manifests at runtime, at the consumer boundary.

This is the SpecKit↔StrayMark gap in miniature: SpecKit decisions are per-spec and time-sliced; the system they describe is one graph. StrayMark's promise is to be that graph ("the cognitive discipline … so AI agents stay coherent across many turns"), but today it doesn't link a decision to the cross-spec contracts it invalidates.

Proposal (capability directions)

1. Cross-spec contract provenance / dependency edges. Let a spec (or component) declare "consumes contract X produced by component/spec Y." Then a decision that touches Y's contract can surface "N downstream consumers may be affected," including consumers in other specs and in post-MVP backlogs.
2. Decision → contract → consumer linking in the system view (Loom / architecture model). When a post-MVP/PM decision changes a contract, the model should connect it to every consumer so "where is the truth for this contract?" has one answer, not three. A consumer built against a stale shape would show as a dangling/aged edge.
3. Drift signal at authoring time, not just audit time. Audit-prompt: add cross-boundary contract verification (client-consumes-server in monorepo) #303 adds cross-boundary verification to the audit prompt (after the fact). This asks for the same coherence to be a structural property of the model — so the gap is visible while authoring spec 005, not discovered in staging.
4. "Mock encodes assumption" smell. Optional/longer-term: flag tests whose fixtures assert a contract shape that no producing handler/schema corroborates (the false-green amplifier here).

Evidence (adopter: Sentinel)

• Remediation of the runtime crash + full bidirectional contract audit: AILOG-2026-06-24-001 (Sentinel), follow-ups FU-005-005 / FU-005-006.
• Backend source of truth: internal/modules/statuscenter/handler.go (getServiceHealthOutput, componentResponse), health_details.go (JSONB v2: metrics + components), interfaces/status.go (HealthState enum).
• The decision that drifted: AILOG-2026-04-24-006 (PM002, per-component health), in spec 001's post-MVP backlog — never referenced by spec 005's FR-010.

Relation to existing issues

• Audit-prompt: add cross-boundary contract verification (client-consumes-server in monorepo) #303 (cross-boundary contract verification in the audit prompt): complementary — detection at audit time. This issue argues for the same coherence as a structural/visual property (authoring + system view), and adds the cross-spec decision propagation dimension that audit-time checks of a single diff won't surface.

---

Filed from real adopter remediation (Sentinel). The triple-mismatch and "mock encodes the assumption" pattern were the load-bearing lessons.

[montfort]

Picked this up as the canonical motivating case for Baton — a new sibling experiment (alongside Loom) whose first capability, the Coherence Bridge, is exactly the lever this issue asks for: make the contract's source-of-truth singular and surface cross-spec decision propagation structurally, not just at audit time.

Scoping/planning landed in #305 (docs only):

• SpecKit integration research (experiment-baton/02-speckit-integration-research.md) — verified against the real SpecKit v0.11.3 install in Sentinel (.specify/). Three integration seams, all of which would have caught this case:

  1. Read — ingest .specify/memory/** + specs/** (incl. post-mvp-backlog.md) into the governance/architecture graph (the intent plane Loom never reads today).
  2. Activate — a StrayMark SpecKit extension with a hook on before_implement → coherence check at authoring time (this issue's proposal feat: add status subcommand #3).
  3. Model — cross-spec contract provenance edges (this issue's proposal feat: rebrand to Strange Days Tech + CLI scaffolder + repo restructure #1/refactor: consolidate distribution files under dist/ and update docs #2): spec005:FR-010 --consumes--> statuscenter:health-contract <--defines-- PM-002, so "where is the truth?" has one answer, not three.

• Phase 1 charter (experiment-baton/CHARTER-01-coherence-bridge.md) — read-only, no model orchestration. Its graduation gate is literally: the diagnostic, run read-only against Sentinel, catches at least one real drift (this case and/or the unimplemented PolicyEngine) that human review let through.

On the specific triple-mismatch: confirmed in Sentinel that the information existed in three disconnected places (specs/001/post-mvp-backlog.md PM-002 / AILOG-2026-04-24-006; the backend contract in statuscenter/handler.go + interfaces/status.go; the consumer spec 005 FR-010 + assumed types.gen.ts) with no edge between them — and the .specify/memory/ architecture docs (including a designed-but-unimplemented PolicyEngine) sit outside StrayMark's view entirely.

Relation to #303 kept as documented: complementary. #303 = detection in the audit prompt (post-hoc); Baton = structural property at authoring + system view. They should share the contract model rather than diverge. The "mock encodes the assumption" smell (proposal #4) is captured as a longer-term finding class.

Leaving this issue open as the tracking anchor for the capability.

[montfort]

Phase 1 of Baton (the Coherence Bridge) is complete and validated read-only against Sentinel — this issue's capability is now real. (PRs #305, #307, #308, #309, #310, #311, #312.)

The catch, on real data. Run read-only against Sentinel (HEAD 24d5a66, zero mutation verified), the bridge surfaces a real, previously-unflagged instance of exactly this issue's pattern:

[C4] spec '005-frontend-dashboard' consumes contract 'services.public-visibility'
     but never references its defining decision(s): PM-001, AILOG-2026-04-21-002

A consumer spec depends on a contract a decision in another spec defined, without acknowledging it — cross-spec decision propagation, caught structurally. The intent overlay additionally surfaces real intended, not implemented gaps (DevPortal, UsageGuard).

What shipped (all three proposal directions from this issue):

1. Cross-spec contract provenance edges — consumer --consumes--> contract <--defines-- decision, keyed across languages by the normalized endpoint (the join a Go handler and a TS type share).
2. Decision → contract → consumer linking in a system view — the Loom-consumable intent overlay (intended vs emergent vs code).
3. Drift as a structural property — the coherence CLI is CI-gateable (exit 1 on blocking). Authoring-time enforcement (proposal feat: add status subcommand #3, the strongest form) is the next Charter: Baton: activation seam — SpecKit extension hooking before_implement for authoring-time coherence #316.

Honest limitation. The Sentinel run reports 0 blocking by design: the field/enum-level health mismatch (C2/C3) doesn't isolate on web/src/api/types.gen.ts, where all generated types share sparse endpoint anchors and collapse into one coarse contract. Fixing the keying is the top follow-up (#313). Full write-up: experiment-baton/03-sentinel-dogfood-report.md.

Follow-ups filed: #313 (per-type→endpoint keying — unblocks C2/C3), #314 (explicit component→path mapping to make C1 trustworthy), #315 (graceful EPIPE), #316 (the activation seam — before_implement hook).

The "mock encodes the assumption" smell (proposal #4) remains a documented future finding class. Keeping this issue open as the tracking anchor for the capability; closing the loop here on Phase 1.

[montfort]

Cross-link with #306, and the seam that splits proposal #4

Reviewing this umbrella after the activation seam (#316, merged in #318), pairing it with #306 (verification fidelity) clarifies where proposal #4 ("mock encodes the assumption" smell) actually belongs — and it is not a fresh standalone issue.

The kinship (#304 ↔ #306)

Both issues are the same root failure seen through two lenses: a boundary drawn for convenience silently substitutes a part for the whole, and the substitution is invisible in the record.

• Cross-spec decision propagation: a post-MVP backend decision silently diverged a later consumer spec's contract — the system view should link them #304 — topological axis (where truth lives). The contract's source of truth lives far away (PM-002 in another spec's post-MVP backlog). The consumer encodes a local stand-in (the mock with assumed field names) instead of pointing at the distant source. Remedy: structural edges to the distant truth.
• Verification fidelity: a 'verified/resolved' claim should record *what reality* it was checked against (proxy vs the condition that matters) #306 — fidelity axis (against which reality a "verified" claim was checked). Even when you know what to verify, you verify against a proxy (an isolated test env, local CPU stress, the doc itself) rather than the condition that matters (real CI, the source). Remedy: record what reality the check ran against.

Proposal #4 is the intersection, and it splits along the seam

The "mock encodes the assumption" smell is exactly where #304 and #306 overlap. The same artifact (the mock) is simultaneously:

• a missing edge to a distant truth (Cross-spec decision propagation: a post-MVP backend decision silently diverged a later consumer spec's contract — the system view should link them #304 lens), and
• a convenient proxy that gives false green (Verification fidelity: a 'verified/resolved' claim should record *what reality* it was checked against (proxy vs the condition that matters) #306 lens).

It therefore splits cleanly into two remediations, each with its own home — filing it as a third orphan issue would itself be the anti-pattern both issues describe (encoding an accessory thing locally when it belongs in two places farther away):

Half of proposal #4	Nature	Home
Detector — flag fixtures asserting a contract no producer corroborates	structural coherence-engine finding	here (#304), behind the same blocker #313 (needs reliable contract keying first)
Evidence convention — a verified claim states what was run and against which reality (proxy:local-stress vs real:CI, doc-assertion vs source-read)	AILOG convention + lint nudge	#306 (framework territory, not Baton)

Close condition for this umbrella

The three proposal directions (#1 provenance edges, #2 decision→contract→consumer in the system view, #3 authoring-time structural drift via the before_implement hook) all shipped in Baton Phase 1 + the activation seam (#316, merged #318). But the original motivating triple-mismatch is still only half-caught: C4 (consumer doesn't reference the defining decision) fires on Sentinel; the field/enum-level mismatch (C2/C3) does not, because generated type files collapse onto sparse endpoint anchors.

This issue's blocker to close is #313 (per-type → endpoint contract keying). When #313 lands and C2/C3 fire on the Sentinel case, #304's own motivating case is caught end-to-end and this umbrella can close. Proposal #4's detector half rides the same #313 dependency; its convention half lives on in #306.

[montfort]

Status update — #313 landed (consumer half of the field/enum catch)

#313 is merged (#320, AILOG-2026-06-26-001). The consumer side of this umbrella's field/enum catch (C2/C3) now works: a generated types.gen.ts whose interfaces carry no per-type endpoint anchor is keyed by call-site binding (api.get<HealthSnapshot>(/services/${id}/health) → services.health) instead of collapsing onto one coarse services blob. Proven on a new anchorless fixture (C2 + C3 fire on the correct contract); validated read-only on Sentinel, where the consumers now spread across services.health / audit.records / incidents / incidents.reopen.

Why the Sentinel run still reports 0 blocking — and why that's correct. Sentinel's types.gen.ts was remediated to match the Go backend, so there is no live drift to flag; de-collapsing introduced no false positives. The C4 cross-spec finding still fires.

Revised close condition. The original motivating triple-mismatch (wrong field names, wrong enums, phantom per-component metrics) is now catchable end-to-end except for one remaining piece: the producer side has the symmetric keying gap. Sentinel's Go backend uses huma, which registers routes in one block while response structs sit far below, so the producer mis-keys away from services.health (the contract shows producer=None). Filed as #319. C2/C3 cannot fire on an un-remediated repo until both halves key correctly.

So this umbrella's field/enum half closes when #319 lands (the consumer half, #313, is done). The C4 cross-spec-decision half already shipped in Phase 1.

Also noted — language boundary (#321). The extractor is calibrated to Sentinel's Go⇄TS stack; the call-site binding from #313 and the producer keying from #319 are, respectively, the TS and Go halves of what should become a language-agnostic LanguageAdapter seam (role inferred from signal, not language) when a second adopter on a different stack appears. Tracked in #321 so the boundary is explicit; not on this umbrella's critical path.

Where the field/enum catch stands

• Consumer keying (Baton: per-type → endpoint contract keying for generated type files (unblocks C2/C3) #313): ✅ done
• Producer keying (Baton: producer-side route keying for handler-framework Go (huma route-registration ↔ output struct) #319): ⬜ open — the remaining blocker for end-to-end C2/C3
• Cross-spec decision propagation (C4): ✅ shipped (Phase 1)
• Language-agnostic extraction (Baton: language-agnostic contract-shape extraction (codescan is Go⇄TS-specific; decouple role from language) #321): ⬜ open — boundary marker, N=2 trigger, off critical path