Waterline G1 (m-stdlib side): layer tag, CI caller, tracker, runbook

.github/workflows/ci.yml

@@ -16,6 +16,11 @@ on:
   pull_request:
 
 jobs:
+  # m/v waterline G1 gate (engine-free) — m-stdlib is layer m; the gate
+  # scans src/*.m for any ^VSL* (v-layer) reference.
+  arch:
+    uses: vista-cloud-dev/.github/.github/workflows/arch-waterline.yml@main
+
   m-stdlib:
     runs-on: ubuntu-latest
     container:

dist/repo.meta.json

@@ -4,9 +4,10 @@
   "repo": "https://github.com/m-dev-tools/m-stdlib",
   "role": "Pure-M runtime standard library — STD* modules",
   "language": ["m"],
+  "layer": "m",
   "license": "AGPL-3.0",
   "agent_instructions": "AGENTS.md",
-  "verified_on": "2026-05-10",
+  "verified_on": "2026-06-13",
   "exposes": {
     "modules": "dist/stdlib-manifest.json",
     "errors": "dist/errors.json"

docs/memory/MEMORY.md

@@ -2,6 +2,7 @@
 
 One line per memory file. Content lives in the files, not here.
 
+- [waterline-g1-gate](waterline-g1-gate.md) — the m/v waterline **G1 gate** (`m arch check` in m-cli) — dependency-direction (v→m only); how `layer` is declared (dist/ meta vs root `repo.meta.json` for m-cli's gitignored dist/), check-manifest doesn't schema-validate the meta, and the v-cli registry-regen `go mod tidy` dep. Built s12 (loose end C).
 - [t0b2-msl-kids-base](t0b2-msl-kids-base.md) — VSL T0b.2 (MSL KIDS-install-as-green): **YDB leg GREEN — 15/15 test-in-place** after the m-ydb gbldir (`e5dcf85`) + v-pkg streamed-install (`aa1991f`) fixes. **IRIS leg (s9):** `raises^STDASSERT` **now ported to IRIS** (try/catch `irisRaises` branch; YDB byte-identical) → STDFMT/STDARGS clean + STDASSERTTST 40/40 both engines + STDUUID P2 gone; remaining IRIS crashes are **non-raises**. **(s10):** file I/O made dual-engine — STDFS portable facade (`$$openRead/Write/Append`+`readLn`) + STDOS.env IRIS arm + 5 consumers migrated; **STDFSTST 50/50 both engines, YDB full 2098/0**. **But the consumer SUITES still don't go green on IRIS** — separate non-file blockers (STDJSON **byte-mode** parser, STDCSV **`@cb@` indirection**, **wide-char** descriptions). file-I/O ≠ green suites; see §s10. Full 15/15 needs byte-mode + callback-idiom + wide-char work (out of file-I/O scope). ≤8-char-name decision keeps STDASSERT/STDSEMVER as a rename follow-up.
 - [vsl-doc-gaps-v0.2](vsl-doc-gaps-v0.2.md) — how the VistA Standard Library architecture doc's §12 VDL gaps resolved at v0.2; the vdocs `XU:XU:UG` over-collapse defect that blocks gold-promotion of the Kernel feature guides.
 - [msl-vsl-coordination-plan](msl-vsl-coordination-plan.md) — the MSL↔VSL coordination model (contract-as-coupling, serialize-contract/parallelize-adapters, milestones M0–M5); VSL repo doesn't exist yet (M0 pending); future-modules-plan now organized around two demos (A inbound FHIR / B outbound S3) with a STD+VSL dependency-ordered master table.

docs/memory/waterline-g1-gate.md

@@ -0,0 +1,55 @@
+---
+name: waterline-g1-gate
+description: The m/v waterline G1 dependency-direction gate (`m arch check`) — how layer is declared, the dist/-gitignore gotcha, and the v-cli registry-regen dependency.
+metadata:
+  type: project
+---
+
+The m/v waterline **G1 gate** (ADR `docs/background/m-v-waterline-adr.md` §3.2,
+the "land first" gate) was built 2026-06-13 (s12): `m arch check` in m-cli
+(`internal/arch`, branch `arch-waterline-g1`). G1 = dependency-direction:
+`v → m` allowed, `m → v` forbidden. For an `m`-layer repo it runs two arms —
+Go dep closure (`go list -deps -json` → fail on any `vista-cloud-dev/v-*`
+module) and an M-source scan (`.m` files for `^VSL*` references). A `v`-layer
+repo passes trivially. Exit 3 + violation list on any m → v edge.
+
+**Non-obvious — where the `layer` tag lives differs per repo (heterogeneous).**
+`ResolveLayer` looks in priority order: `dist/repo.meta.json`,
+`dist/v-contract.json`, then **root `repo.meta.json`**, then a `--layer`
+override.
+- m-stdlib + v-pkg **commit `dist/`** (drift-gated artifacts) → tag lives in
+  `dist/repo.meta.json` / `dist/v-contract.json`.
+- **m-cli's `dist/` is gitignored** (`/dist/`), so its layer tag had to live in
+  a NEW **root** `repo.meta.json` (m-cli had no committed meta artifact at all
+  before this). Any future Go tool repo with a gitignored `dist/` needs the same
+  root-level meta.
+
+**m-stdlib `make check-manifest` does NOT schema-validate `repo.meta.json`** — it
+only asserts the file is tracked + clean. So adding `"layer": "m"` was safe;
+remember to bump `verified_on` (guardrail).
+
+**v-cli registry regen has a hidden dep.** `dist/v-registry.json` aggregates
+v-pkg's contract via a dev `replace => ../v-pkg`. When v-pkg's `pkgcli` gained
+the lifecycle verbs (install/verify/uninstall) it started importing
+`mdriver.Client` from `m-driver-sdk` — so regenerating the registry in v-cli
+first needs `go mod tidy` (airgapped: `GOPROXY=file://…`) to pull
+`m-driver-sdk v0.3.0` into v-cli's module graph, else `make registry` fails
+`missing go.sum entry`.
+
+**All 8 ecosystem repos are now tagged (s12):** m-cli/m-stdlib/m-driver-sdk/
+m-ydb/m-iris = `m`; v-pkg/v-cli/v-stdlib = `v`. The 5 later ones each got a
+**root `repo.meta.json`** (the layer is a repo property — deliberately NOT in
+v-pkg's generated `dist/v-contract.json` or v-cli's aggregate
+`dist/v-registry.json`; `ResolveLayer` falls through to root). The 3 `m` repos
+gate clean on the Go arm; the `v` repos pass trivially. **CI enforcement WIRED (s12):** the reusable
+`.github/.github/workflows/arch-waterline.yml` (ADR §3.3.2) runs `m arch check`
+in any repo (one-line `arch:` caller). All 8 repos call it; verified green on
+real CI (v-stdlib v-layer + m-cli Go-arm). **Two CI gotchas:** the workflow
+must build `m` via `git clone --branch ${ref}` + `go build` — NOT
+`go install …@main`, because the Go proxy caches the `@main` branch→commit
+resolution and lags a fresh m-cli merge ~30 min (would build a stale `m`
+without `arch check`). And v-cli's dev `replace => ../v-pkg` would break the
+Go-arm's `go list` in CI — harmless only because v-cli is layer v (arch skips
+the Go arm). v-stdlib scaffold (T0b.1) is done. See
+[[msl-vsl-coordination-plan]] and the VSL tracker
+(`docs/tracking/vsl-implementation-tracker.md` § s12).

docs/plans/msl-vsl-orchestration-kickoff.md

@@ -0,0 +1,170 @@
+---
+title: MSL ⟷ VSL Orchestration & Kickoff Runbook
+status: active
+created: 2026-06-14
+plan: docs/plans/vsl-implementation-plan.md
+tracker: docs/tracking/vsl-implementation-tracker.md
+doc_type: [PLANNING]
+---
+
+# MSL ⟷ VSL Orchestration & Kickoff Runbook
+
+> The durable "how we run the multi-repo MSL⟷VSL effort" doc — the analog of
+> the driver effort's `coordination-model.md`. Point every new session at this
+> file. It answers: which repo am I in, how do repos hand off, where do clean
+> session boundaries fall, and how the gatekeeping/CI standard is kept
+> unambiguous and enforced across all repos.
+>
+> Companion docs: the milestone plan
+> [`vsl-implementation-plan.md`](vsl-implementation-plan.md), the live
+> [`vsl-implementation-tracker.md`](../tracking/vsl-implementation-tracker.md),
+> the waterline rule `docs/background/m-v-waterline-adr.md` (org `docs` repo),
+> and per-repo memory under each repo's `docs/memory/`.
+
+---
+
+## 0. The one-paragraph model
+
+The ecosystem is layered by the **m/v waterline**: engine-neutral `m-*` below,
+VistA-specific `v-*` above, dependency flowing **one way, `v → m`**. The MSL⟷VSL
+build follows that spine — **m-stdlib (`STD*`) → v-stdlib (`VSL*`) → consumer
+(`VPNG`/`VWEB`)** — and the *only* coupling between layers is a single tagged
+artifact, the **seam contract** (m-stdlib's `seams` block, pinned by v-stdlib).
+So the discipline is: **serialize the seam, parallelize the consumers**, one
+**session ↔ one repo ↔ one branch**, and every stop is a clean, pushed,
+documented increment.
+
+---
+
+## 1. Phasing — stabilize → standardize → implement
+
+Do **not** start feature work on a stale baseline. The phases are ordered.
+
+### Phase A — Stabilize (get `main` canonical everywhere)
+The prerequisite. Most repos' real work currently lives on long-lived feature
+branches; `main` is behind. Until `main` is the source of truth, the gates
+(`@main` workflow refs, `go install …@<tag|main>`, CI) enforce against code that
+isn't really there. Per repo, **leaf-first** (`m` before `v`):
+1. Land the active feature branch → `main` via PR (CI green) — or consciously abandon it.
+2. Clear dependabot PRs.
+3. Prune merged/dead local branches (one `main` + at most one active work branch).
+4. **Exit gate:** every repo's `main` builds, gates green, and its `layer` tag +
+   `arch:` CI caller are *on main* (so the gate actually enforces).
+
+**Landing order & dependencies:**
+| # | Repo | Branch | Note |
+|---|------|--------|------|
+| 1 | m-driver-sdk | `coordination` | leaf (the seam); land + tag a release |
+| 2 | m-ydb | `m-ydb-driver` | pins SDK *tag* → independent of SDK main |
+| 3 | m-iris | `m-iris-driver` | pins SDK *tag* → independent of SDK main |
+| 4 | m-cli | (already on main) | prune leftover local branches only |
+| 5 | v-pkg | `refile-v-pkg` | the m-kids→v-pkg refile; land **then tag** (e.g. v0.1.0) |
+| 6 | v-cli | `chore/registry-…` | **blocked**: drop dev `replace => ../v-pkg`, pin v-pkg's new tag, then land (else go-ci is red in CI) |
+| 7 | m-stdlib | `arch-waterline-g1-mstdlib` | waterline + this runbook |
+| 8 | v-stdlib | (caller already on main) | prune local |
+
+### Phase B — Standardize the substrate (one unambiguous, enforced way)
+Make the org discipline `source-tag → generate → registry → red-gate` concrete
+and self-enforcing:
+1. **One meta artifact, one location.** Standardize on **root `repo.meta.json`**
+   (language-agnostic, not buried in generated `dist/`) with a tiny schema
+   (`id, layer, language, verification_commands, consumes, exposes`). `m arch
+   check` validates its presence/shape. (Migrate m-stdlib/v-pkg off
+   `dist/…` once tooling reads root first.)
+2. **Finish the gate suite** in the same `m arch check` + same reusable
+   workflow: **G2** (no VistA symbols below the waterline), **G3**
+   (transport-monopoly — only m-driver-sdk runs a driver/builds the envelope),
+   **G4** (seam-pin — tagged SDK, no `replace`). G1 (dependency-direction) is
+   done.
+3. **The meta-gate (keystone).** A scheduled org job (ADR §3.3.4) that walks
+   every repo and asserts each declares a valid `layer`, calls
+   `arch-waterline.yml`, and is in an ecosystem registry. **This is what makes
+   the standard enforced rather than conventional** — drift goes red
+   automatically.
+4. **One reusable CI per language.** `go-ci.yml` + `arch-waterline.yml` exist;
+   add **`m-ci.yml`** (fmt/lint/test/coverage + arch, modeled on m-stdlib's CI)
+   so every M repo gets an identical pipeline from one line.
+5. **Pin the seam deterministically.** Tag an m-cli release; set the workflow's
+   `m-cli-ref` to the tag (not floating `main`) so CI stops drifting under
+   m-cli's main.
+
+### Phase C — Implement MSL⟷VSL (T0b.3 onward)
+Only on a clean, standardized substrate. Follow the tracker's `Repo` column in
+dependency order: T0b.3 (four drift gates + `seams` block) → T0b.4 (freeze seam
+v1, tag MSL, v-stdlib pins) → T1.1 STDENV seam → T1.2 VSLCFG → T1.3 VSL KIDS
+base → T1.4/T1.5 VPNG consumer + determinism ledger → M2–M6 (parallel-safe once
+M1 is green).
+
+---
+
+## 2. Which repo am I in?
+
+The repo that **owns the current tracker task** (the tracker's `Repo` column).
+The dependency spine is **m-stdlib → v-stdlib → consumer**, always lower-first.
+
+- **m-stdlib is the anchor** for the MSL side: it holds the canonical tracker,
+  the milestone plan, and the **seam contract** everything pins. Cross-cutting
+  planning/tracking edits happen here.
+- A task that names `v-stdlib` / a consumer / a driver / m-cli is done in *that*
+  repo, in its own session.
+
+## 3. Orchestration & handoffs
+
+- **One session ↔ one repo ↔ one branch.** Never edit two repos in one session.
+  `cd` into the sub-repo before starting.
+- **The coupling is exactly one artifact: the seam contract.** m-stdlib emits a
+  `seams` block in its manifest and **tags** a seam version; v-stdlib **pins**
+  that tag and a drift gate asserts it. Serialize the seam, parallelize the
+  consumers (same shape as the driver effort's "serialize the SDK").
+- **Cross-repo features go sequentially, leaf repo first.** Lower layer
+  implemented + verified + (for a seam change) tagged, *then* the upper layer
+  consumes the tag.
+- **Frozen-seam window:** when the upper layer needs a new shape, it records
+  `needs seam: X` in its tracker and does **not** bump the seam itself; the
+  m-stdlib (anchor) session batches it into the next tagged seam.
+
+### Clean git handoffs
+The **Increment Protocol is the handoff mechanism**. Every increment ends at a
+*verified* state with: memory updated (`<repo>/docs/memory/`), tracker row +
+Status/Resume line updated, and a commit pushed to the working branch. That
+leaves every repo at a clean, pushed, documented point — which *is* the handoff.
+Add a **tag at each seam boundary** (m-stdlib tags `seams-vN`; the v-stdlib
+session pins it). Never switch repos mid-change.
+
+The cross-session state lives in two places, never in your head:
+1. the tracker's **Status / Resume line** (cross-repo "where we are / what's next"), and
+2. each repo's **`docs/memory/`** (per-repo non-obvious facts).
+
+## 4. When to start a new session
+
+- **Repo boundary** — the next task is in a different repo (the cleanest cut).
+- **Seam freeze** — lower repo tagged → start a fresh upper-repo session to consume it.
+- **~50% context** — *finish the current increment first* (verified + pushed +
+  Resume line updated), then start fresh. Never hand off mid-change.
+- **Per increment** — each verified increment is a valid boundary.
+
+### New-session recipe
+1. `cd` into the repo that owns the next task.
+2. Read its `CLAUDE.md` + `docs/memory/MEMORY.md` + the tracker's Status/Resume line.
+3. Confirm the branch (`git branch --show-current`); branch off `main` if landing a new increment.
+4. Run the repo's gate to confirm a clean baseline (`make check` / `make check-fast` / `m arch check .`).
+5. Begin — TDD-first, one increment, then run the Increment Protocol.
+
+## 5. The standardized, enforced "one way" (target end-state)
+
+Every repo, with no exception, has:
+- a root **`repo.meta.json`** declaring `layer` (+ `verification_commands`, `consumes`, `exposes`);
+- a **`ci.yml`** that calls the **reusable workflows** — `arch-waterline.yml`
+  (universal G1–G4) + the language CI (`go-ci.yml` / `m-ci.yml`);
+- the **Increment Protocol** as its commit/push/memory/tracker rhythm;
+- and is covered by the **meta-gate** (declares a layer, calls the workflow, is
+  in the ecosystem registry) — the backstop that turns the standard from a
+  convention into a gate.
+
+Compliance is a **build artifact, not a review habit**: a new repo earns trust
+by adding its `tag → registry → gate` triple, not by being watched.
+
+---
+
+*Keep this runbook in lockstep with `vsl-implementation-plan.md` and the
+tracker. Update it when the orchestration model itself changes.*