gsdd-cli 0.3.1 → 0.16.1

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,31 @@ 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>
 
+<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 +48,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 +58,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 +71,35 @@ 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-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.
+
+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
+
+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.
+
+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`.
+
+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>
+
 <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 +110,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 +124,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 +137,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 +157,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 +165,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 +175,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,12 +185,33 @@ 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
@@ -170,12 +226,19 @@ re_verification:
 gaps:
   - truth: "Users can create a user from the page"
     status: failed
+    proof_type: runtime-check # required proof type for this truth
+    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 +252,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 +303,33 @@ 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
 - 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
+- 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 +343,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 +360,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 +375,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/package.json

@@ -1,18 +1,20 @@
 {
   "name": "gsdd-cli",
-  "version": "0.3.1",
-  "description": "GSDD — a portable, spec-driven development kernel for AI coding agents. Works with Claude Code, Codex CLI, OpenCode, Cursor, Copilot, and Gemini CLI.",
+  "version": "0.16.1",
+  "description": "Northline — a repo-native workflow kernel for long-horizon AI software delivery, with directly validated support for Claude Code, Codex CLI, and OpenCode, published as gsdd-cli.",
   "type": "module",
   "bin": {
     "gsdd": "bin/gsdd.mjs"
   },
   "scripts": {
-    "test:gsdd": "node tests/gsdd.init.test.cjs && node tests/gsdd.models.test.cjs && node tests/gsdd.manifest.test.cjs && node tests/gsdd.plan.adapters.test.cjs && node tests/gsdd.audit-milestone.test.cjs && node tests/gsdd.invariants.test.cjs && node tests/gsdd.guards.test.cjs && node tests/gsdd.health.test.cjs && node tests/gsdd.scenarios.test.cjs"
+    "test": "npm run test:gsdd",
+    "test:gsdd": "node tests/gsdd.init.test.cjs && node tests/gsdd.models.test.cjs && node tests/gsdd.consumer-ceremony.test.cjs && node tests/gsdd.manifest.test.cjs && node tests/gsdd.plan.adapters.test.cjs && node tests/gsdd.audit-milestone.test.cjs && node tests/gsdd.invariants.test.cjs && node tests/gsdd.guards.test.cjs && node tests/gsdd.health.test.cjs && node tests/gsdd.scenarios.test.cjs && node tests/gsdd.cross-runtime.test.cjs"
   },
   "devDependencies": {
-    "semantic-release": "^24.2.3",
     "@semantic-release/changelog": "^6.0.3",
-    "@semantic-release/git": "^10.0.1"
+    "@semantic-release/exec": "^7.1.0",
+    "@semantic-release/git": "^10.0.1",
+    "semantic-release": "^24.2.3"
   },
   "engines": {
     "node": ">=18"