gsdd-cli 0.16.1 → 0.18.1

package/distilled/workflows/verify.md

@@ -13,13 +13,26 @@ Before starting, read these files:
 4. `.planning/SPEC.md` - requirements and constraints for the phase
 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).
+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 `node .planning/bin/gsdd.mjs 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:
+
+- `node .planning/bin/gsdd.mjs 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 `node .planning/bin/gsdd.mjs 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`.
@@ -75,28 +88,41 @@ Also check for orphan requirements:
 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-check` or `user-confirmation` proof in the proof contract step below. Code-evidence alone is insufficient.
-- If no → `risk: normal`. Code-evidence or repo-test is sufficient.
+- 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>
 
-<proof_contract>
-Before beginning artifact inspection, classify each must-have truth by its required proof type. This step separates "did the artifact pass levels 1–3?" from "did the outcome have the right kind of proof?"
-Proof types (from SPEC.md `VerificationEvidence`):
-- `repo-test` — a passing automated test in the repo directly exercises this outcome
-- `code-evidence` — source inspection confirms the implementation is present and wired
-- `runtime-check` — a live execution confirms the behavior (script, curl, manual run)
-- `user-confirmation` — a human observer confirmed the user-visible outcome
+<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:
 
-Assign required proof type per truth using the risk classification from `<must_haves>`:
-- `risk: high` truths (behavioral/UX changes, user-visible outcomes without acceptance criteria) → require `runtime-check` or `user-confirmation`. Code-evidence alone is **not sufficient**.
-- `risk: normal` truths (structural or content changes) → `code-evidence` is sufficient. `repo-test` is always valid regardless of risk level.
+| 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`            |
 
-If the required proof type cannot be collected programmatically (e.g., runtime environment unavailable) → route that truth to `human_verification` in the report, not to `gaps`.
+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 proof-type requirement and still fail Level 2 (substantive) or Level 3 (wired). Both checks must run.
-</proof_contract>
+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.
@@ -215,6 +241,12 @@ 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
@@ -226,7 +258,9 @@ re_verification:
 gaps:
   - truth: "Users can create a user from the page"
     status: failed
-    proof_type: runtime-check # required proof type for this truth
+    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:
@@ -304,10 +338,11 @@ Status rules:
 
 Frontmatter guidance:
 - `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 proof exists through other means; use `severity: blocker` only when the required proof type (`runtime-check`, `repo-test`, or `user-confirmation` where mandated) could not be satisfied by any available evidence
+- 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>
@@ -346,7 +381,7 @@ If you cannot write the file (permissions, path issue), STOP and report the bloc
 
 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.
+After writing VERIFICATION.md, if `status: passed`, run `node .planning/bin/gsdd.mjs 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>
@@ -365,7 +400,7 @@ Verification is done when all of these are true:
 - [ ] 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`
+- [ ] If status is `passed`, ROADMAP.md phase entry is `[x]` via `node .planning/bin/gsdd.mjs 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)

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 a repo-native delivery spine with portable multi-runtime workflow surfaces, 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 they do not carry equal runtime proof or equal ergonomics today:
+
+- **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`