Yttrigen

From Sandbox to Production: The Governed SDLC Landscape

Platform 10 min read

New here? ValidKeep governs regulated software with linked atomic files in Git and deterministic npx validkeep verify (no LLM in the audit path). Optional ysbuild helps author specs; verify is the impartial gate either way.

Start with the ecosystem map for the platform stack (assurance profile, landscape profile, CLI, ValidKeep Hub). Then read the atomic model ($D_x$, $R_x$, $C_x$, $L_x$) if notation like $C_x$ is unfamiliar. Operational Qualification (OQ) and Performance Qualification (PQ) are explained in their own articles.

Multiple changes can be in flight without ad hoc promotion. The landscape profile declares branch topology, hosting classes, test cycle types, and ValidKeep Hub status gates. Promotion from sandbox to production is mechanical: each environment has rules; GitHub CI and ValidKeep Hub ledger state enforce them together.

Environment ladder

The High Assurance landscape defines a promotion ladder. Branches are not arbitrary folder names; they carry hosting and test-cycle semantics:

  • sandbox and prototype: uncontrolled experimentation; headless test cycles on MiniHub
  • localdev: developer machine rehearsal before CR formalization
  • devcr/<CR#>: formal realization of an approved Change Request; CR-bound test cycles
  • integration: long-lived online dry-run; PRs only from approved devcr branches when ValidKeep Hub status allows
  • verifyrelease/<Release#>: single active verification release; release-bound PQ telemetry
  • main: production truth; merge only from verifyrelease after implementation approval
Governed SDLC branch ladder Promotion ladder (High Assurance landscape) sandbox Headless cycles prototype Headless cycles localdev Local rehearsal formal CR / release promotion devcr CR-bound cycles integration Online dry-run verifyrelease Release-bound PQ main Production Landscape profile defines branches and hosting; assurance profile defines atomic trace rules
Branches and test cycle types are declared in the landscape profile; obligation algebra lives in the assurance profile.

Hosting classes

Each environment declares a hosting class in landscape YAML:

  • none: local-only verification; no deployed runtime required
  • container: Studio sandbox containers for prototype work
  • online: GitHub Actions CI plus Cloudflare Workers (or equivalent) for integration and release environments

Test cycle types

Three cycle types tie to the ladder (see also Features: Governed SDLC):

  • Headless (sandbox): run OQ drivers and PQ probes locally or on MiniHub without a formal CR
  • CR-bound (devcr): formal module qualification attached to a Change Request ledger entry
  • Release-bound (verifyrelease): aggregate PQ telemetry for release sign-off

CR-101 narrative (pediatric dose calculator)

Consider CR-101 adding a neonatal dose rule to a pediatric calculator module:

  1. Draft: developer scopes modules in ValidKeep Hub, prototypes in sandbox, pins a commit SHA
  2. Realization: branch devcr/CR-101; atomic files updated (calc.rx.md, calc.cx.md, OQ cases); every push runs npx validkeep verify + scope check
  3. Informal testing: developer attests CR-bound cycles pass on devcr
  4. Integration: PR to integration when ValidKeep Hub unlocks; online environment dry-run
  5. Release requested: CR assigned to active verifyrelease branch
  6. Production: merge verifyrelease to main after QA signatures on ValidKeep Hub evidence
CR-101 lifecycle swimlane CR-101 pediatric calculator (simplified) Draft Realization Informal test Integration Release main devcr/CR-101 PR when ValidKeep Hub unlocks verifyrelease Scope change loop: zero-orphan verify fails → rx/cx/oqtest update → Realization re-approval ValidKeep Hub status gates permit Git actions at each transition
Simplified CR-101 flow: landscape branches and ValidKeep Hub ledger status move together.

Status gates bridge ValidKeep Hub and Git

Landscape status_gates map ValidKeep Hub CR statuses to permitted Git actions. Annotated excerpt from the High Assurance landscape profile:

status_gates:
  - action: pr_to_integration
    requires:
      cr_status: Integration Testing
  - action: merge_verifyrelease
    requires:
      release_status: Formal Testing Approval Pending
  - action: pr_to_main
    requires:
      release_status: Approved for Implementation

The ledger is not decorative; it gates CI and PR workflows.

What landscape does not do

Landscape does not define obligation algebra ($O_x = C_x$, trace edges, OQ and PQ separation). That is the assurance profile job. Landscape does not author specs; humans or optional ysbuild agents do. Verify always reads assurance rules from validkeep.yaml.

Where to go next