gsdd-cli 0.3.1 → 0.18.0

package/distilled/workflows/verify.md

@@ -1,9 +1,7 @@
 <role>
 You are the VERIFIER. Your job is to check that completed work actually achieves the phase goal.
-
 Core mindset: task completion does not equal goal achievement.
 A task can be "done" while the phase goal is still unfulfilled.
-
 You are skeptical by default. You verify claims, not promises.
 </role>
 
@@ -13,16 +11,44 @@ Before starting, read these files:
 2. `.planning/phases/{plan_id}-PLAN.md` - what was planned
 3. `.planning/phases/{plan_id}-SUMMARY.md` - what execution claims was built
 4. `.planning/SPEC.md` - requirements and constraints for the phase
-5. The relevant codebase files - the code that was actually built
+5. From the SUMMARY.md loaded in step 3, if a `<judgment>` section is present - read `<anti_regression>` rules as additional verification targets: confirm that invariants listed there were not broken by execution. Read `<active_constraints>` to calibrate verification scope.
+6. The relevant codebase files - the code that was actually built
+7. **Session-boundary fallback:** If the SUMMARY.md loaded in step 3 has no `<judgment>` section, check whether `.planning/.continue-here.bak` exists. If it does, read its `<judgment>` section. Treat `<anti_regression>` rules as additional verification targets and `<active_constraints>` to calibrate verification scope (same usage as step 5). After reading, run `gsdd file-op delete .planning/.continue-here.bak --missing ok` (auto-clean).
 
 Establish your verification basis (must-have sources, requirement scope, previous report status) before beginning code inspection. Do not jump to loose file reading until this basis is explicit.
 
 If a previous `.planning/phases/{phase_dir}/{phase_num}-VERIFICATION.md` exists, read it first and treat this as re-verification.
 </load_context>
 
+<lifecycle_preflight>
+Before code inspection or report writing, run:
+
+- `gsdd lifecycle-preflight verify {phase_num} --expects-mutation phase-status`
+
+If the preflight result is `blocked`, STOP and report the blocker instead of inferring lifecycle eligibility from prompt-local prose.
+
+Treat the preflight as an authorization seam over shared repo truth only:
+- it may authorize or reject verification
+- it does not mutate `.planning/ROADMAP.md` by itself
+- owned writes remain the verification artifact plus any explicit `gsdd phase-status` transition that occurs later on `passed`
+</lifecycle_preflight>
+
+<runtime_contract>
+Verification uses the same `Runtime` and `Assurance` types as planning and execution.
+Infer runtime from the launching surface when obvious: `.claude/` -> `claude-code`, `.codex/` or Codex portable skill -> `codex-cli`, `.opencode/` -> `opencode`, otherwise `other`.
+Assurance is ordered: `unreviewed` -> `self_checked` -> `cross_runtime_checked`.
+Use `cross_runtime_checked` only when the verifier runtime/vendor differs from the runtime that produced the artifact being verified.
+</runtime_contract>
+
+<assurance_check>
+Before code inspection, compare runtime provenance across PLAN, SUMMARY, and any prior VERIFICATION artifact.
+Treat the SUMMARY artifact's `<handoff>` and `<deltas>` blocks as first-class evidence, not optional commentary.
+When the current verification pass is weaker than the strongest prior artifact in the chain, emit a structured `<assurance_check>` with the chain runtimes/assurance values, `status`, and `warning`.
+If runtime/assurance is missing anywhere in the chain, record `status: unknown` and note the missing field as a verification concern.
+</assurance_check>
+
 <scope_boundary>
 This workflow verifies a single phase.
-
 It does verify:
 - the phase goal
 - phase must-haves
@@ -35,7 +61,6 @@ Cross-phase integration audit is handled by `distilled/workflows/audit-milestone
 
 <reverification_mode>
 If a previous `VERIFICATION.md` exists:
-
 1. Load the previous `status`, `score`, and structured `gaps`.
 2. Focus full verification on previously failed items.
 3. Run quick regression checks on items that previously passed.
@@ -46,7 +71,6 @@ If no previous `VERIFICATION.md` exists, perform an initial verification pass.
 
 <must_haves>
 Establish what must be true before the phase can be called complete.
-
 Source priority:
 1. plan frontmatter `must_haves`
 2. roadmap success criteria
@@ -60,11 +84,48 @@ For each truth:
 Also check for orphan requirements:
 - requirements expected by roadmap scope but claimed by no plan
 - requirements that no verified truth, artifact, or key link actually satisfies
+
+Risk classification:
+For each truth, assess: does it involve a behavioral change, UX change, or user-visible outcome without a clear, relevant acceptance criterion?
+
+- If yes → mark it `risk: high`. This truth will require runtime-grade evidence in the evidence contract step below. `code` alone is insufficient.
+- If no → `risk: normal`. `code` is the floor, and `test` is preferred when the repo has a direct automated check.
+
+This is the verifier's own internal judgment — not a field imported from the plan. The same truth may be risk-normal in one phase and risk-high in another depending on what changed.
 </must_haves>
 
+<evidence_contract>
+Before beginning artifact inspection, classify the phase closure posture and apply the fixed evidence kinds. This step separates "did the artifact pass levels 1–3?" from "did the outcome have the right kind of evidence?"
+
+Stable evidence kinds:
+- `code` — source inspection confirms the implementation is present and wired
+- `test` — a passing automated check in the repo directly exercises the outcome
+- `runtime` — a live execution confirms the behavior (script, curl, manual run)
+- `delivery` — shipped or distributable proof exists (merged PR, packaged artifact, published doc/proof pack, release evidence)
+- `human` — a human observer confirmed a visual or judgment-based outcome
+
+Delivery posture:
+- `repo_only` — the phase outcome stays inside repo truth; no shipped runtime or external delivery claim is needed
+- `delivery_sensitive` — the phase claims a live behavior, shipped UX, install/release posture, or other externally consumed runtime outcome
+
+Apply the shared `verify` matrix:
+
+| delivery_posture     | required evidence | recommended evidence       | cannot carry closure alone |
+| -------------------- | ----------------- | -------------------------- | -------------------------- |
+| `repo_only`          | `code`            | `test`                     | `human`, `delivery`        |
+| `delivery_sensitive` | `code`, `runtime` | `test`, `delivery`, `human` | `code`, `human`            |
+
+Rules:
+- repo-only work must not invent `runtime` or `delivery` proof just to satisfy a template
+- delivery-sensitive closure must not pass on prose, `code`-only inspection, or `human` confirmation without the required `runtime` evidence
+- `human` evidence supports ambiguous or visual outcomes; it does not replace required `code` or `runtime` evidence
+- if a required evidence kind cannot be collected, record it in `missing_evidence`; route purely human-observable follow-up to `human_verification` only when the blocking runtime/delivery requirement is already satisfied
+
+Note: this step does NOT replace levels 1–3. An artifact can satisfy the evidence-kind requirement and still fail Level 2 (substantive) or Level 3 (wired). Both checks must run.
+</evidence_contract>
+
 <verification_levels>
 Check every artifact at three levels. A common failure mode is a file that exists but is still a stub.
-
 ### Level 1: Exists
 Does the artifact physically exist?
 
@@ -75,7 +136,6 @@ ls -la tests/users.route.test.ts
 
 ### Level 2: Substantive
 Is the artifact real code, or a placeholder?
-
 Stub detection patterns:
 - empty function body
 - placeholder return such as `null`, `[]`, or `{}`
@@ -90,7 +150,6 @@ If any required artifact is a stub at Level 2, that supporting truth fails.
 
 ### Level 3: Wired
 Is the artifact connected to the phase flow it is supposed to support?
-
 Examples:
 - component -> page or route
 - form -> handler
@@ -104,20 +163,19 @@ If an artifact exists and is substantive but not wired, mark it as unwired.
 <key_link_checks>
 Check phase-local key links explicitly:
 
-| Link Type | What To Check |
-|-----------|----------------|
-| Component -> API | Request is made and response is used |
-| API -> storage | Query or write occurs and result is returned |
-| Form -> handler | Submit path triggers real work, not only `preventDefault()` |
-| State -> render | State is actually displayed or consumed |
-| Config -> runtime | Config is loaded where the behavior depends on it |
+| Link Type         | What To Check                                               |
+| ----------------- | ----------------------------------------------------------- |
+| Component -> API  | Request is made and response is used                        |
+| API -> storage    | Query or write occurs and result is returned                |
+| Form -> handler   | Submit path triggers real work, not only `preventDefault()` |
+| State -> render   | State is actually displayed or consumed                     |
+| Config -> runtime | Config is loaded where the behavior depends on it           |
 
 Use direct file inspection and targeted grep. Do not inflate this into a milestone-wide audit.
 </key_link_checks>
 
 <anti_pattern_scan>
 Scan the phase output for anti-patterns:
-
 ```bash
 grep -rn "TODO\\|FIXME\\|HACK\\|XXX" src/
 grep -rn "catch.*{}" src/
@@ -125,6 +183,7 @@ grep -rn "console.log" src/ --include="*.ts" --include="*.js" | grep -v test | g
 ```
 
 Also look for:
+
 - placeholder components
 - static mock responses where live behavior is expected
 - orphaned files added in the phase but never referenced
@@ -132,6 +191,7 @@ Also look for:
 
 <grouped_gaps>
 Before finalizing the report, group related failures by concern:
+
 - truth failures that share the same broken artifact or key link
 - requirement failures caused by the same missing implementation seam
 - human-verification items that belong to the same user-visible flow
@@ -141,6 +201,7 @@ Do not return a flat symptom list when the same underlying breakage explains mul
 
 <requirements_coverage>
 Requirements coverage is not optional bookkeeping. For each phase requirement:
+
 1. Collect the phase requirements from the strongest available planning source
 2. Restate each requirement in concrete implementation terms
 3. Map each requirement to the truths, artifacts, and key links that should satisfy it
@@ -150,15 +211,42 @@ Requirements coverage is not optional bookkeeping. For each phase requirement:
 Orphaned requirements must be reported even if the overall phase otherwise looks strong.
 </requirements_coverage>
 
+<git_delivery_collection>
+Before writing the verification report, collect delivery metadata for the current branch and emit it in frontmatter.
+
+Run these checks:
+
+- `git rev-parse --abbrev-ref HEAD` -> current branch name for `branch`
+- `git rev-list --count "main..HEAD"` -> commit count for `commits_ahead_of_main`
+- `gh pr list --head "<branch>" --state all --json state,number,title,url --limit 1` -> PR state for `pr_state`
+- `git status --short` -> detect uncommitted local changes that should be mentioned as a delivery warning
+
+Recording rules:
+
+- Always write a `<git_delivery_check>` block in frontmatter with real observed values for `branch`, `commits_ahead_of_main`, and `pr_state`.
+- If `main` does not exist or the count command fails, set `commits_ahead_of_main: unknown` and note the failure in the report body.
+- If no PR matches the current branch, set `pr_state: none`.
+- If `gh` is unavailable or the PR query fails, set `pr_state: unknown` and note the failure in the report body.
+- Missing PR, unmerged commits, or a dirty worktree are delivery warnings only. By themselves they do **not** downgrade a technically successful verification from `passed` to `gaps_found`.
+- If the phase already has substantive implementation gaps, keep those gaps primary and include delivery observations as warning-level supporting context.
+</git_delivery_collection>
+
 <report_format>
 Write `.planning/phases/{phase_dir}/{phase_num}-VERIFICATION.md` with structured frontmatter first:
-
 ```markdown
 ---
 phase: 01-foundation
+runtime: opencode
+assurance: cross_runtime_checked
 verified: 2026-03-11T12:00:00Z
 status: gaps_found
 score: 2/3 must-haves verified
+delivery_posture: delivery_sensitive
+evidence_contract:
+  required_kinds: [code, runtime]
+  recommended_kinds: [test, delivery, human]
+  observed_kinds: [code]
+  missing_kinds: [runtime]
 re_verification:
   previous_status: gaps_found
   previous_score: 1/3
@@ -170,12 +258,21 @@ re_verification:
 gaps:
   - truth: "Users can create a user from the page"
     status: failed
+    required_evidence: [code, runtime]
+    observed_evidence: [code]
+    missing_evidence: [runtime]
+    severity: blocker # blocker = required proof absent; warning = artifact missing but proof exists via other means
     reason: "Form submits, but route returns placeholder data"
     artifacts:
       - path: "src/routes/users.ts"
         issue: "POST handler returns static object"
     missing:
       - "Persist submitted data before returning it"
+<git_delivery_check>
+  branch: "feature/branch-name"
+  commits_ahead_of_main: 0
+  pr_state: "open"
+</git_delivery_check>
 human_verification:
   - test: "Open the users page and submit the form"
     expected: "The new user appears in the rendered list"
@@ -189,33 +286,41 @@ human_verification:
 **Status:** [passed | gaps_found | human_needed]
 **Re-verification:** [Yes or No]
 
+## Verification Basis
+
+- Plan runtime / assurance: [runtime] / [assurance]
+- Summary runtime / assurance: [runtime] / [assurance]
+- Verification runtime / assurance: [runtime] / [assurance]
+- Handoff status: [clean | downgraded | unknown]
+- Deltas reviewed: [count and classes]
+
 ## Goal Achievement
 
 ### Observable Truths
 
-| # | Truth | Status | Evidence |
-|---|-------|--------|----------|
-| 1 | [truth] | VERIFIED | [evidence] |
+| #   | Truth   | Status   | Evidence   |
+| --- | ------- | -------- | ---------- |
+| 1   | [truth] | VERIFIED | [evidence] |
 
 ### Artifact Verification
 
 | Artifact | Exists | Substantive | Wired | Notes |
-|----------|--------|-------------|-------|-------|
+| -------- | ------ | ----------- | ----- | ----- |
 
 ### Key Link Verification
 
-| From | To | Via | Status | Notes |
-|------|----|-----|--------|-------|
+| From | To  | Via | Status | Notes |
+| ---- | --- | --- | ------ | ----- |
 
 ### Requirements Coverage
 
 | Requirement | Status | Evidence |
-|-------------|--------|----------|
+| ----------- | ------ | -------- |
 
 ### Anti-Patterns
 
 | Pattern | Location | Severity | Impact |
-|---------|----------|----------|--------|
+| ------- | -------- | -------- | ------ |
 
 ### Human Verification Required
 
@@ -232,25 +337,34 @@ Status rules:
 - use `human_needed` when automated checks pass but one or more human-verification items remain
 
 Frontmatter guidance:
-- `phase`, `verified`, `status`, and `score` are the minimal report fields
+- `phase`, `runtime`, `assurance`, `verified`, `status`, and `score` are the minimal report fields
+- `delivery_posture` plus `evidence_contract.required_kinds|recommended_kinds|observed_kinds|missing_kinds` must reflect the shared verify matrix actually used for this phase
 - when gaps or human checks exist, keep them machine-readable in frontmatter — do not collapse them into prose-only body text
 - keep `re_verification`, `gaps`, and `human_verification` structured when they materially help re-verification, gap closure, or explicit human handoff
+- keep `<git_delivery_check>` in frontmatter with the observed `branch`, `commits_ahead_of_main`, and `pr_state` values from the delivery checks above
+- use `severity: warning` in gaps when an artifact is missing but required evidence still exists through other means; use `severity: blocker` only when one or more required evidence kinds in `missing_evidence` could not be satisfied
+- if verification runs in the same runtime/vendor as execution, cap frontmatter `assurance` at `self_checked`
+- if verification runs in a different runtime/vendor than execution, set frontmatter `assurance: cross_runtime_checked`
 </report_format>
 
 <next_steps>
 Based on the verification result:
 
 ### `passed`
+
 - phase is ready to move forward
 - communicate that the phase goal was verified successfully
 
 ### `gaps_found`
+
 Present a focused recommendation:
+
 1. fix inline if the gaps are small and local
 2. re-plan if the gaps reveal a design problem
 3. explicitly accept the known issue only if the developer chooses to
 
 ### `human_needed`
+
 - list the exact manual checks
 - state the expected outcome for each one
 - do not convert human-needed status into passed until those checks are acknowledged
@@ -264,6 +378,10 @@ File: `.planning/phases/{phase_dir}/{phase_num}-VERIFICATION.md`
 This is non-negotiable. Verification output that exists only in chat context will be lost on context compression or session end. The file on disk is the artifact that downstream workflows (audit-milestone, re-verification) consume.
 
 If you cannot write the file (permissions, path issue), STOP and report the blocker to the user. Do NOT silently skip the write.
+
+Before any ROADMAP closure step, confirm the required phase `SUMMARY.md` still exists on disk. If `SUMMARY.md` is missing, STOP and report the blocker — do NOT treat verification as terminally successful and do NOT close ROADMAP state from conversation context alone.
+
+After writing VERIFICATION.md, if `status: passed`, run `gsdd phase-status {phase_num} done` to close the phase entry in `.planning/ROADMAP.md`. Execute is the primary owner of ROADMAP status, but execute can be interrupted before its state_updates run. Verify is the terminal workflow and must close the ROADMAP entry when it confirms the phase is complete. If the helper cannot update ROADMAP.md (path issue, missing phase, invalid state), STOP and report the blocker — do NOT complete verification without closing the phase.
 </persistence>
 
 <success_criteria>
@@ -277,7 +395,12 @@ Verification is done when all of these are true:
 - [ ] Requirements coverage was evaluated
 - [ ] Anti-pattern scan was run
 - [ ] `VERIFICATION.md` was written with structured frontmatter and a full report
+- [ ] `VERIFICATION.md` frontmatter records `runtime` and `assurance`
+- [ ] `VERIFICATION.md` frontmatter records git delivery metadata for the current branch
+- [ ] Verification explicitly reviewed SUMMARY `<handoff>` and `<deltas>` content
 - [ ] Status is one of `passed`, `gaps_found`, or `human_needed`
+- [ ] The required phase `SUMMARY.md` still exists before any ROADMAP closure on passed status
+- [ ] If status is `passed`, ROADMAP.md phase entry is `[x]` via `gsdd phase-status`
 - [ ] The developer was informed of the result and recommended next step
 - [ ] Related failures grouped by concern, not returned as a flat symptom list
 - [ ] Requirements coverage chain completed (collect, restate, map, report, check orphans)
@@ -287,21 +410,24 @@ Verification is done when all of these are true:
 Report the verification result to the user, then present the next step:
 
 ---
+
 **Completed:** Phase verification — created `.planning/phases/{phase_dir}/{phase_num}-VERIFICATION.md`.
 
 If status is `passed`:
-**Next step:** `/gsdd:progress` — check status and route to the next phase or milestone audit
+**Next step:** `/gsdd-progress` — check status and route to the next phase or milestone audit
 
 If status is `gaps_found`:
-**Next step:** `/gsdd:plan` — re-plan to close the identified gaps
+**Next step:** `/gsdd-plan` — re-plan to close the identified gaps
 
 If status is `human_needed`:
-**Next step:** Complete the manual checks listed above, then run `/gsdd:verify` again
+**Next step:** `/gsdd-verify-work` — run conversational UAT to test items interactively and capture results in UAT.md
+- After UAT is complete, run `/gsdd-verify` again with the UAT results as additional context
 
 Also available:
-- `/gsdd:execute` — fix gaps inline without re-planning (small fixes only)
-- `/gsdd:pause` — save context for later if stopping work
+
+- `/gsdd-execute` — fix gaps inline without re-planning (small fixes only)
+- `/gsdd-pause` — save context for later if stopping work
 
 Consider clearing context before starting the next workflow for best results.
----
+
 </completion>

package/docs/BROWNFIELD-PROOF.md

@@ -0,0 +1,95 @@
+# Brownfield Proof
+
+This is the strongest tracked public proof for Workspine's release-floor claim: a real brownfield-style consumer repo that used the shipped workflow contract, hit a real failure, and recovered through the same `plan -> execute -> verify` loop.
+
+## What this proves
+
+In a fresh consumer repo, Workspine produced:
+
+- durable planning artifacts
+- runnable workflow entry surfaces
+- a concrete phase plan
+- a real execution summary
+- a failed verification
+- a real fix
+- a successful re-verification
+
+That proves the repo-native delivery contract is not just conceptual.
+
+## Public proof pack
+
+Open the tracked proof pack:
+
+- [Consumer proof pack index](proof/consumer-node-cli/README.md)
+
+Key exported artifacts:
+
+- [brief.md](proof/consumer-node-cli/brief.md)
+- [SPEC.md](proof/consumer-node-cli/SPEC.md)
+- [ROADMAP.md](proof/consumer-node-cli/ROADMAP.md)
+- [01-01-PLAN.md](proof/consumer-node-cli/phases/01-foundation/01-01-PLAN.md)
+- [01-01-SUMMARY.md](proof/consumer-node-cli/phases/01-foundation/01-01-SUMMARY.md)
+- [01-VERIFICATION.md](proof/consumer-node-cli/phases/01-foundation/01-VERIFICATION.md)
+
+## The worked flow
+
+### 1. Initialize a fresh consumer repo
+
+The exported proof pack comes from a new non-framework project that used the shipped `gsdd init` flow.
+
+The generated surface included:
+
+- portable `.agents/skills/gsdd-*`
+- consumer `.planning/` state
+- a Codex-native checker adapter
+- a compact consumer `AGENTS.md`
+
+### 2. Plan real work
+
+The consumer brief required a named greeting:
+
+- `node index.js --name Ada` should print `Hello, Ada!`
+
+That requirement is preserved in the exported [brief](proof/consumer-node-cli/brief.md), [spec](proof/consumer-node-cli/SPEC.md), and [phase plan](proof/consumer-node-cli/phases/01-foundation/01-01-PLAN.md).
+
+### 3. Execute and hit a real miss
+
+The first implementation missed the named-greeting requirement:
+
+- `node index.js --name Ada` returned `Hello, world!`
+
+That miss is preserved in the exported [verification report](proof/consumer-node-cli/phases/01-foundation/01-VERIFICATION.md).
+
+### 4. Verify, fix, and re-verify
+
+The consumer repo then followed the same framework contract to:
+
+- identify the failed requirement
+- update the implementation and test path
+- re-run verification
+- close with a passing result
+
+The final passing behavior is:
+
+- `node index.js --name Ada` returns `Hello, Ada!`
+
+## Why this matters
+
+This proof is stronger than a polished README claim because it shows the exact behavior Workspine is trying to preserve:
+
+- plan from durable artifacts
+- execute against real repo state
+- let verification catch a real miss
+- recover without losing the thread
+
+That is the release-floor claim in practice.
+
+## What this does not prove
+
+This proof does not claim:
+
+- equal runtime ergonomics across every supported runtime
+- parity validation on Cursor, Copilot, or Gemini CLI
+- enterprise-hardening or orchestration-platform behavior
+
+Those are outside the current proof floor.

package/docs/RUNTIME-SUPPORT.md

@@ -0,0 +1,77 @@
+# Runtime Support Matrix
+
+Workspine is designed as a portable multi-runtime delivery framework, but the proof bar is not the same for every runtime today.
+
+This matrix is the release-floor truth surface.
+
+## Support tiers
+
+### Directly validated
+
+The workflow contract has direct repo proof for these runtimes:
+
+- **Claude Code**
+- **Codex CLI**
+- **OpenCode**
+
+These are the strongest public runtime claims.
+
+### Same core workflow
+
+These runtimes use the same portable workflow surfaces, but this release does not claim equal runtime proof or equal ergonomics:
+
+- **Cursor**
+- **GitHub Copilot**
+- **Gemini CLI**
+
+### Fallback / manual use
+
+Any tool that can read the generated markdown workflows can still use the framework manually, but that is outside the current native-proof story.
+
+## Current runtime surfaces
+
+| Runtime | Current claim | Entry surface | Notes |
+| --- | --- | --- | --- |
+| Claude Code | Directly validated | `.claude/skills/`, `.claude/commands/`, `.claude/agents/` | Native surface was a mandatory Phase 32 validation target; installed generated files are freshness-checked locally |
+| OpenCode | Directly validated | `.opencode/commands/`, `.opencode/agents/` | Native command and checker path; installed generated files are freshness-checked locally |
+| Codex CLI | Directly validated | `.agents/skills/gsdd-*` plus `.codex/agents/gsdd-plan-checker.toml` | Portable skill entry, native checker adapter, mandatory Phase 32 validation target |
+| Cursor | Same core workflow | `.agents/skills/gsdd-*` | Skills-native path; generated skill files are freshness-checked locally, but the runtime is not claimed as parity-validated |
+| GitHub Copilot | Same core workflow | `.agents/skills/gsdd-*` | Skills-native path; generated skill files are freshness-checked locally, but the runtime is not claimed as parity-validated |
+| Gemini CLI | Same core workflow | `.agents/skills/gsdd-*` | Skills-native path; governance is optional, generated skill files are freshness-checked locally, and parity is not claimed |
+
+## Generated-surface freshness
+
+The authored source contract stays in `distilled/workflows/*`. Generated runtime-facing files are trusted only through deterministic rendering:
+
+- `gsdd health` compares any installed generated surfaces under `.agents/skills/`, `.claude/`, `.opencode/`, and `.codex/` against current render output.
+- `gsdd update` regenerates drifted generated surfaces from the authored workflow and delegate sources.
+- Missing generated surfaces are not treated as drift unless the corresponding runtime surface is actually installed locally.
+
+## What stays portable
+
+The portable invariant for this release is the workflow contract:
+
+- planning
+- checking and revision loops
+- execution discipline
+- verification
+- handoff and durable repo artifacts
+
+## What does not stay equal yet
+
+This release does **not** claim that every runtime has:
+
+- the same native adapter richness
+- the same invocation ergonomics
+- the same validation depth
+- the same checker/orchestration mechanics
+
+Portable contract does not mean equal UX everywhere.
+
+## Proof references
+
+- `README.md`
+- `docs/BROWNFIELD-PROOF.md`
+- `docs/proof/consumer-node-cli/README.md`
+- `docs/VERIFICATION-DISCIPLINE.md`
+- `gsdd health` / `gsdd update`