os-sdlc phase 3: design the real transition map (map-as-data) #328

New issue

Closed

opened 2026-08-09 13:07:12 +00:00 by jared · 1 comment

jared commented

2026-08-09 13:07:12 +00:00

Owner

Design pass for the phase 3 transition table, superseding the skeleton's SkeletonTable constant. Must answer, with ADRs where consequential:

Full row schema for the real pipeline (~30 rows): state, agent, gate_command, on_success, on_failure routing, per-row retry cap.
Maps become DATA, not Ruby constants: storage format (SQLite tables vs YAML loaded into TransitionTable), map selection as an optional /os-sdlc:implement argument, agents reusable across maps.
Loop-safety conventions enforced at map load: success edges form a DAG (topologically sortable); every failure edge carries a finite retry cap; exhausted cap routes to an escalation state. Termination provable statically, validated in TransitionTable#validate!.
Handoff design: what each state's output feeds into the next state's brief; exact brief naming/format/retention (open item from ADR-0109).
Verdict token format the Runner parses (APPROVE/REQUEST-CHANGES) and green-gate failure routing (open items in architecture.md).
Note (do not schema for yet): future map patterns — parallel fan-in (two programmers + adjudicator), second-opinion states, non-code workflows; ticket concept stays but boundary noted so a generic run/workflow instance can replace it later.
Reference: the deleted phase-1 stepper in git history encodes the real sequencing/retry knowledge — mine it, don't reinvent.

Design pass for the phase 3 transition table, superseding the skeleton's SkeletonTable constant. Must answer, with ADRs where consequential: - Full row schema for the real pipeline (~30 rows): state, agent, gate_command, on_success, on_failure routing, per-row retry cap. - Maps become DATA, not Ruby constants: storage format (SQLite tables vs YAML loaded into TransitionTable), map selection as an optional /os-sdlc:implement argument, agents reusable across maps. - Loop-safety conventions enforced at map load: success edges form a DAG (topologically sortable); every failure edge carries a finite retry cap; exhausted cap routes to an escalation state. Termination provable statically, validated in TransitionTable#validate!. - Handoff design: what each state's output feeds into the next state's brief; exact brief naming/format/retention (open item from ADR-0109). - Verdict token format the Runner parses (APPROVE/REQUEST-CHANGES) and green-gate failure routing (open items in architecture.md). - Note (do not schema for yet): future map patterns — parallel fan-in (two programmers + adjudicator), second-opinion states, non-code workflows; ticket concept stays but boundary noted so a generic run/workflow instance can replace it later. Reference: the deleted phase-1 stepper in git history encodes the real sequencing/retry knowledge — mine it, don't reinvent.

jared referenced this issue

2026-08-09 13:07:17 +00:00

os-sdlc phase 3: map validator + dry-run simulator #329

jared referenced this issue

2026-08-09 13:07:21 +00:00

os-sdlc phase 3: grow real states onto the skeleton #330

jared referenced this issue

2026-08-09 13:07:25 +00:00

os-sdlc: seam-designer agent in front of test-writer #331

jared referenced this issue

2026-08-09 13:07:29 +00:00

os-sdlc phase 3.5: recovery CLI for stalled pipelines #332

jared commented

2026-08-11 18:20:52 +00:00

Author

Owner

Resolution

Done: Design pass complete: full row schema, YAML map-as-data storage with selection order, load-time loop-safety validation (success DAG, capped failure edges, provable termination), push handoff/brief design closing ADR-0109's open item, first-line verdict token format, green-gate failure routing, park-and-notify escalation, future-map boundary noted (sharding/fan-in deferred).

Evidence: ADR-0112 docs/adr/0112-os-sdlc-transition-maps-are-yaml-data-with-load-time-termination-proofs-the-stepper-runs-all-gates.md; ADR-0113 docs/adr/0113-push-handoffs-assembled-by-the-runner-first-line-verdict-file-replaces-the-adr-0098-sidecar-escalation-is-park-and-notify.md (supersedes 0098); architecture.md open items resolved; draft maps/default.yaml

Follow-ups: Build ticket filed: #341

Approved-by: jaredmswanson@gmail.com

## Resolution **Done:** Design pass complete: full row schema, YAML map-as-data storage with selection order, load-time loop-safety validation (success DAG, capped failure edges, provable termination), push handoff/brief design closing ADR-0109's open item, first-line verdict token format, green-gate failure routing, park-and-notify escalation, future-map boundary noted (sharding/fan-in deferred). **Evidence:** ADR-0112 docs/adr/0112-os-sdlc-transition-maps-are-yaml-data-with-load-time-termination-proofs-the-stepper-runs-all-gates.md; ADR-0113 docs/adr/0113-push-handoffs-assembled-by-the-runner-first-line-verdict-file-replaces-the-adr-0098-sidecar-escalation-is-park-and-notify.md (supersedes 0098); architecture.md open items resolved; draft maps/default.yaml **Follow-ups:** Build ticket filed: #341 Approved-by: jaredmswanson@gmail.com

jared closed this issue

2026-08-11 18:20:52 +00:00

jared referenced this issue from a commit

2026-08-13 15:08:12 +00:00

docs(os-sdlc): phase-3 transition-map design pass — ADR-0112/0113, map-as-data draft (#328)

jared referenced this issue

2026-08-13 18:11:58 +00:00

os-sdlc phase 3: map validator + dry-run simulator #329

jared referenced this issue

2026-08-13 18:11:58 +00:00

os-sdlc phase 3: grow real states onto the skeleton #330

jared referenced this issue