gsdd-cli 0.28.0 → 0.29.1

package/distilled/workflows/plan.md

@@ -131,11 +131,21 @@ If the selected target is `brownfield-change`, do not require ROADMAP phase memb
 Also verify that `HANDOFF.md` is judgment-only context and does not contradict the operational status, scope, or next action in `CHANGE.md`. If any brownfield contract field is missing or contradictory, STOP and repair the brownfield contract before planning.
 </phase_contract_gate>
 
-<ui_proof_planning>
-For UI-sensitive work, include compact `ui_proof_slots` with `slot_id`, optional `requirement_id`, `claim`, `route_state`, fixed evidence kinds (`code`, `test`, `runtime`, `delivery`, `human`), `minimum_observations`, `expected_artifact_types`, `validation_command`, `environment`, `viewport`, `manual_acceptance_required`, and `claim_limit`; otherwise set `no_ui_proof_rationale`.
-Do not create slots for backend-only, CLI-only, docs-only, or refactor-only work unless the plan claims a visible UI outcome. Evidence must later match claim, route/state, observation, artifact path, evidence kind, privacy metadata, result, and claim limit; local-only or unsafe artifacts cannot support public, publication, tracked, delivery, or release proof claims. Human approval does not replace required `code`, `test`, `runtime`, or `delivery` evidence.
-For live rendered UI proof, plan `agent-browser` as the default runtime evidence path and existing Playwright/package-script browser tests as the repeatable regression path when the repo already has them. If the runtime does not provide `agent-browser`, require the plan to state that availability constraint and name the closest project-native interactive browser fallback before narrowing the claim. The planner chooses the viewport set, but each slot must explain why the chosen viewport(s) are enough for the claim or narrow the claim limit; responsive claims need desktop/mobile or equivalent state coverage. Do not plan new browser infrastructure by default, and use Playwright scripting only for checks `agent-browser` cannot cover cleanly, such as JS-disabled, structured console, or multi-context verification.
-</ui_proof_planning>
+<browser_proof_planning>
+For UI-sensitive work, set `browser_proof_required: true` and add a `## Browser Proof Plan` section. For backend-only, CLI-only, docs-only, or refactor-only work that claims no visible UI outcome, set `browser_proof_required: false` with a short `browser_proof_rationale`.
+
+The Browser Proof Plan is plain markdown, not a JSON slot schema. It must name:
+- `Routes/states:` exact route(s), screen(s), or UI states to inspect
+- `Viewports:` desktop and mobile for responsive or layout-sensitive claims, or a narrowed claim explaining why one viewport is enough
+- `Runtime path:` `agent-browser` preferred; Playwright or another project-native browser fallback must explain the availability constraint
+- `Evidence kind:` `runtime` for live browser observation or `test` for a repeatable browser-regression command
+- `Evidence command:` a runnable command that can reproduce or validate the browser proof, or `No-command rationale:` when the runtime path is manual/interactive only and the claim is narrowed accordingly
+- `Observations:` rendered DOM/behavior, interaction steps, and console/network observations when relevant
+- `Artifacts:` screenshot/report/log paths if produced, with local-only vs publishable privacy/safety note
+- `Claim limit:` the exact claim the observation can support
+
+Evidence must later match route/state, viewport, observation, artifact path, evidence kind, privacy/safety note, result, and claim limit. Human approval does not replace required `code`, `test`, `runtime`, or `delivery` evidence. Existing Playwright/package-script browser tests remain canonical repeatable regression evidence when present. Do not plan new browser infrastructure by default; use Playwright scripting only for checks `agent-browser` cannot cover cleanly, such as JS-disabled, structured console, or multi-context verification.
+</browser_proof_planning>
 <goal_backward_planning>
 Plan backward from success criteria.
 
@@ -195,18 +205,8 @@ anti_regression_targets:
   - Existing session middleware behavior remains unchanged for already-supported routes.
 known_unknowns:
   - Exact copy wording for auth errors may still need product confirmation.
-ui_proof_slots: []
-no_ui_proof_rationale: Not UI-sensitive; scoped work does not claim a visible UI outcome.
-high_leverage_surfaces: []
-second_pass_required: false
-closure_claim_limit: Do not claim phase completion until verification satisfies the evidence contract for the scoped truths.
-parallelism_budget:
-  max_concurrent_plans: 1
-  safe_parallelism: []
-leverage:
-  lost: Slightly more planning ceremony for this plan.
-  kept: Existing auth/session architecture and repo conventions.
-  gained: Explicit anti-drift boundaries and fail-closed escalation.
+browser_proof_required: false
+browser_proof_rationale: Not UI-sensitive; scoped work does not claim a visible UI outcome.
 must_haves:
   truths:
     - User can sign in with email and password.
@@ -225,11 +225,9 @@ Schema rules:
 - `requirements` must not be empty
 - `files-modified` should list the files this plan is expected to touch
 - `must_haves` must trace back to roadmap success criteria
-- `non_goals`, `hard_boundaries`, `escalation_triggers`, and `closure_claim_limit` must not be empty
-- include `ui_proof_slots` for UI-sensitive work or `no_ui_proof_rationale` otherwise
-- `leverage.lost`, `leverage.kept`, and `leverage.gained` must all be explicit
-- `second_pass_required: true` if `high_leverage_surfaces` is non-empty
-- `parallelism_budget.max_concurrent_plans` must stay `1` unless the plan proves disjoint write ownership
+- `non_goals`, `hard_boundaries`, `escalation_triggers`, and `approval_gates` must be explicit
+- include `browser_proof_required` and `browser_proof_rationale`
+- if `browser_proof_required: true`, include a `## Browser Proof Plan` section with route/state, viewport, runtime path, evidence kind, evidence command or no-command rationale, observations, artifacts, and claim limit
 </plan_schema>
 
 <task_format>
@@ -326,16 +324,8 @@ anti_regression_targets:
   - Existing user route behavior outside the new list view remains unchanged.
 known_unknowns:
   - Final empty-state copy may still need product confirmation.
-high_leverage_surfaces: []
-second_pass_required: false
-closure_claim_limit: Do not claim phase completion until verification confirms the scoped truths with the required evidence.
-parallelism_budget:
-  max_concurrent_plans: 1
-  safe_parallelism: []
-leverage:
-  lost: Slightly more planning ceremony for stronger execution boundaries.
-  kept: Existing route/component conventions and repo-native workflow.
-  gained: Better anti-drift enforcement and more honest closure limits.
+browser_proof_required: true
+browser_proof_rationale: Visible route changes require rendered browser proof.
 must_haves:
   truths:
     - Users can view the list page.
@@ -382,6 +372,16 @@ must_haves:
 ## Approval Gates
 - [Decision or side-effect boundaries that require explicit user approval]
 
+## Browser Proof Plan
+Routes/states: [Exact routes or UI states to inspect, or `N/A` when not required]
+Viewports: [Desktop/mobile coverage or narrowed viewport claim]
+Runtime path: [agent-browser preferred; explain fallback availability constraints]
+Evidence kind: [runtime or test]
+Evidence command: [Runnable command, or use `No-command rationale:` for narrowed manual/interactive proof]
+Observations: [Rendered behavior, interaction steps, console/network observations]
+Artifacts: [Screenshot/report/log paths plus local-only or publishable safety note]
+Claim limit: [Exact claim this proof can support]
+
 <checks>
 <plan_check>
 checker: self | cross_runtime
@@ -408,13 +408,8 @@ notes: [What the checker actually validated or why it was skipped]
 ## Success Criteria
 - [What must be true when this plan is complete]
 
-## High-Leverage Review
-- [Which high-leverage surfaces are touched and whether a second pass is required]
-
-## Leverage Review
-- Lost: [What leverage this plan sacrifices]
-- Kept: [What existing leverage or conventions it preserves]
-- Gained: [What leverage this plan creates]
+## Second-Pass Review
+- [Shared/high-risk surfaces to re-check for contradictions, stale assumptions, and overclaims before closure]
 
 ## Notes
 [Gotchas, implementation notes, or explicit assumptions]
@@ -505,12 +500,9 @@ After the planner produces a draft plan, an independent checker reviews it in fr
 6. `must_have_quality` - success criteria are specific, observable, and reflected in tasks
 7. `context_compliance` - locked decisions are honored and deferred ideas stay out of scope
 8. `goal_achievement` - the plan, if executed perfectly, actually achieves the stated phase goal: goal addressed (tasks deliver the goal), success criteria reachable (each criterion traceable to a task verify output), and outcome observable (a human or automated check can confirm the goal was met)
-9. `scope_boundaries` - anti-goals and hard boundaries are explicit, enforceable, and reflected in the task set
-10. `anti_regression_capture` - anti-regression targets are named and mapped to verification
-11. `escalation_integrity` - stop-and-challenge triggers and approval gates are present where side effects or ambiguity warrant them
-12. `closure_honesty` - closure claim limit prevents the plan from overclaiming what verification can prove
-13. `high_leverage_review` - high-leverage surfaces and second-pass obligations are recorded honestly
-14. `approach_alignment` - when APPROACH.md exists, plans implement the chosen approaches, not alternatives. Blocker if plan contradicts an explicit user choice. Warning if plan drifts from recommendation without justification. When `workflow.discuss: true`, missing, proofless, agent-discretion-only, or invalid APPROACH.md is a blocker before a plan can be accepted.
+9. `approach_alignment` - when APPROACH.md exists, plans implement the chosen approaches, not alternatives. Blocker if plan contradicts an explicit user choice. Warning if plan drifts from recommendation without justification. When `workflow.discuss: true`, missing, proofless, agent-discretion-only, or invalid APPROACH.md is a blocker before a plan can be accepted.
+
+The smaller dimension set still preserves the old failure coverage: scope boundaries are checked under `scope_sanity`, anti-regression and escalation under `context_compliance`, closure honesty and browser-proof specificity under `goal_achievement`, and second-pass review under the final shared-surface review before closure.
 ### Invoking the Checker
 1. If `.work/config.json` has `workflow.planCheck: false`, skip the independent checker. Perform the planner self-check below and report `reduced_assurance`. This does not skip the earlier alignment-proof gate when `workflow.discuss: true`.
 2. If plan checking is enabled, check if your runtime provides a `gsdd-plan-checker` agent.
@@ -528,7 +520,7 @@ After the planner produces a draft plan, an independent checker reviews it in fr
      "summary": "One sentence overall assessment",
      "issues": [
        {
-         "dimension": "requirement_coverage | task_completeness | dependency_correctness | key_link_completeness | scope_sanity | must_have_quality | context_compliance | goal_achievement | scope_boundaries | anti_regression_capture | escalation_integrity | closure_honesty | high_leverage_review | approach_alignment",
+         "dimension": "requirement_coverage | task_completeness | dependency_correctness | key_link_completeness | scope_sanity | must_have_quality | context_compliance | goal_achievement | approach_alignment",
          "severity": "blocker | warning",
          "description": "What is wrong",
          "plan": "01-PLAN",
@@ -587,9 +579,9 @@ For each task:
 - [ ] `escalation_triggers` force stop-and-challenge instead of silent interpretation
 - [ ] `approval_gates` appear anywhere side effects or irreversible choices could happen
 - [ ] `anti_regression_targets` are concrete enough for verification to check later
-- [ ] `closure_claim_limit` prevents the executor from claiming more than the evidence can support
-- [ ] `leverage.lost`, `leverage.kept`, and `leverage.gained` are explicit and defensible
-- [ ] If `high_leverage_surfaces` is non-empty, `second_pass_required` is true and named in the plan body
+- [ ] Evidence contract and claim limits prevent the executor from claiming more than verification can support
+- [ ] Browser-proof-required plans include route/state, viewport, runtime path, evidence kind, evidence command or no-command rationale, observations, artifacts/privacy-safety posture, and claim limit
+- [ ] Shared or high-risk surfaces are named for a second-pass contradiction/staleness review
 
 ### Red Flags
 - A success criterion has no task covering it
@@ -615,14 +607,14 @@ Planning is done when all of these are true:
 - [ ] Plan self-check passed
 - [ ] Success criteria from `ROADMAP.md`, or Done When criteria from `CHANGE.md`, are represented as must-haves
 - [ ] Goal-backward derivation from criteria to artifacts to key links to tasks is explicit
-- [ ] Every plan has frontmatter with `phase`, `plan`, `type`, `wave`, `depends_on`, `files-modified`, `autonomous`, `requirements`, `non_goals`, `hard_boundaries`, `escalation_triggers`, `approval_gates`, `anti_regression_targets`, `ui_proof_slots` or `no_ui_proof_rationale`, `closure_claim_limit`, `parallelism_budget`, `leverage`, and `must_haves`
+- [ ] Every plan has frontmatter with `phase`, `plan`, `type`, `wave`, `depends_on`, `files-modified`, `autonomous`, `requirements`, `non_goals`, `hard_boundaries`, `escalation_triggers`, `approval_gates`, `anti_regression_targets`, `known_unknowns`, `browser_proof_required`, `browser_proof_rationale`, and `must_haves`
 - [ ] Every plan frontmatter records `runtime` and `assurance`
 - [ ] Every plan records checker outcome in a structured `<checks>` block
 - [ ] Every task has XML structure with `id`, `type`, `files`, `action`, `verify`, and `done`
 - [ ] Every task has at least one runnable verify command
 - [ ] Plan sizing stays within 2-5 tasks, preferring 2-3
 - [ ] Locked decisions from `.work/SPEC.md` and APPROACH.md are honored
-- [ ] Plan body includes explicit `## Anti-Goals`, `## Hard Boundaries`, `## Evidence Contract`, `## Common Pitfalls`, `## Stop-And-Challenge`, `## Approval Gates`, and `## Leverage Review` sections
+- [ ] Plan body includes explicit `## Anti-Goals`, `## Hard Boundaries`, `## Evidence Contract`, `## Common Pitfalls`, `## Stop-And-Challenge`, `## Approval Gates`, and `## Second-Pass Review` sections; UI-sensitive plans also include `## Browser Proof Plan`
 - [ ] Any git guidance stays repo-native and follows `.work/config.json`
 </success_criteria>
 

package/distilled/workflows/quick.md

@@ -118,11 +118,10 @@ Delegate to the planner role in quick mode.
 - No research phase, no ROADMAP requirements
 - Do NOT extract phase requirement IDs — there is no active phase
 - Derive must-haves directly from the task description
-- If the quick task is UI-sensitive, include proportional `ui_proof_slots` with slot_id, claim, route_state, required_evidence_kinds, minimum_observations, expected_artifact_types, validation_command, environment, viewport, manual_acceptance_required, and claim_limit; otherwise include a short `no_ui_proof_rationale`
-- UI proof slots must be matchable to exact observed evidence later: claim, route/state, observation, evidence kind, artifact path or manual step, privacy metadata, result, and claim limit. Discovery hints from source comments, AST/cAST, semantic search, or Semble-like retrieval do not satisfy proof.
-- Observed artifact metadata must include `visibility`, `retention`, `sensitivity`, and `safe_to_publish`; raw screenshots, traces, videos, DOM snapshots, and reports are local-only/unsafe by default. Use `gsdd ui-proof validate <path>` or `gsdd health` when a bundle exists; add `--claim <...>` only for public, publication, tracked, delivery, or release proof use.
+- If the quick task is UI-sensitive, include proportional `browser_proof_required: true`, a short `browser_proof_rationale`, and a plain Browser Proof Plan naming route/state, viewport, runtime path, evidence kind, evidence command or narrowed no-command rationale, observations, artifacts, and claim limit; otherwise set `browser_proof_required: false` with a short rationale.
+- Browser proof must be matchable to exact observed evidence later: route/state, viewport, observation, evidence kind, artifact path or manual step, privacy/safety note, result, and claim limit. Discovery hints from source comments, AST/cAST, semantic search, or Semble-like retrieval do not satisfy proof.
 - For live rendered UI proof, default to `agent-browser` snapshots/refs, interactions, screenshots, and relevant console/network observations. If unavailable, state the availability constraint and closest project-native interactive browser fallback before narrowing the claim. Existing Playwright/package-script browser tests remain the canonical repeatable regression path when present. The viewport set is plan-owned, but under-specified viewport coverage is weak proof; explain the chosen viewport(s) or narrow the claim limit.
-- Keep UI proof proportional: do not scaffold Playwright, Cypress, Cucumber, Storybook, CI, browser MCP, or visual-regression tooling by default
+- Keep browser proof proportional: do not scaffold Playwright, Cypress, Cucumber, Storybook, CI, browser MCP, or visual-regression tooling by default.
 - Ignore <planning_process> Step 1 requirement extraction; use inline goal-backward planning only
 - Target minimal context usage
 
@@ -162,8 +161,8 @@ Read `.work/config.json`.
 
 **Constraints:**
 - Check 5 dimensions by default: `requirement_coverage`, `task_completeness`, `dependency_correctness`, `scope_sanity`, `must_have_quality`
-- If the quick plan contains `ui_proof_slots` or a rendered UI claim, also check `closure_honesty` so weak UI proof slots block execution
-- Skip: `key_link_completeness`, `context_compliance`, `goal_achievement`, `approach_alignment`
+- If the quick plan contains a rendered UI claim, check `goal_achievement` so weak browser proof blocks execution.
+- Skip: `key_link_completeness`, `context_compliance`, and `approach_alignment`; skip `goal_achievement` only when the quick plan has no rendered UI claim
 - Maximum 1 revision cycle (if blockers found, send back to planner once, then accept result)
 - Blocker threshold: only block on `task_completeness` or `scope_sanity` violations
 - Warnings for other dimensions are noted but do not block
@@ -269,8 +268,8 @@ Delegate to the executor role.
 - Skip the <state_updates> section of your role contract entirely
 - Do NOT update ROADMAP.md phase status or SPEC.md current state
 - Create summary at: `.work/quick/$NEXT_NUM-$SLUG/$NEXT_NUM-SUMMARY.md`
-- If the quick plan defines `ui_proof_slots`, create or update `.work/quick/$NEXT_NUM-$SLUG/UI-PROOF.md` with fenced JSON containing required top-level fields: `proof_bundle_version`, `scope`, `route_state`, `environment`, `viewport`, `evidence_inputs`, `commands_or_manual_steps`, `observations`, `artifacts`, `privacy`, `result`, and `claim_limits`
-- For live UI proof, record `agent-browser` in `evidence_inputs.tools_used` when used, the exact commands or manual ref-based steps, screenshot/report artifact paths, and any relevant console/network observations. If `agent-browser` was unavailable, record that availability constraint and fallback tool explicitly. If existing Playwright tests supplied regression evidence, record the package command and result separately from the `agent-browser` runtime observation.
+- If the quick plan requires browser proof, create or update `.work/quick/$NEXT_NUM-$SLUG/UI-PROOF.md` as a plain observation record with route/state, viewport, runtime path, evidence command or narrowed no-command rationale, observations, artifacts, privacy/safety note, result, and claim limit.
+- For live browser proof, record `agent-browser` when used, the exact commands or manual ref-based steps, screenshot/report artifact paths, and any relevant console/network observations. If `agent-browser` was unavailable, record that availability constraint and fallback tool explicitly. If existing Playwright tests supplied regression evidence, record the package command and result separately from the runtime observation.
 - Human approval for visual taste, accessibility judgment, baseline acceptance, subjective polish/layout quality, or privacy publication does not replace required `code`, `test`, `runtime`, or `delivery` evidence
 
 **Output:** `.work/quick/$NEXT_NUM-$SLUG/$NEXT_NUM-SUMMARY.md`

package/distilled/workflows/verify.md

@@ -129,12 +129,12 @@ Rules:
 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>
 
-<ui_proof_comparison>
-Before closure, direct `gsdd verify <phase>` and this workflow must fail closed when the target phase has no matching PLAN.md or SUMMARY.md; report structured prerequisite blockers instead of treating missing artifacts as an empty success. Read UI proof declaration authority from the plan frontmatter contract only: body prose, fenced examples, stale sidecars, and markdown snippets do not declare UI proof intent. If frontmatter defines non-empty `ui_proof_slots`, compare planned UI proof against observed bundles before closure. Prefer `gsdd ui-proof compare <planned-slots-json> [observed-bundle-json ...]` when planned slots are available as JSON or fenced JSON; otherwise perform the same field-by-field comparison and record reduced assurance if no deterministic command could run. If frontmatter records `ui_proof_slots: []`, it must also contain a nonblank `no_ui_proof_rationale`; otherwise verification blocks. If the plan records only `no_ui_proof_rationale`, verify the rationale instead of requiring a bundle, and treat stale planned/observed sidecars as warnings rather than proof or blockers. Each observed bundle must include top-level `proof_bundle_version`, `scope`, `route_state`, `environment`, `viewport`, `evidence_inputs`, `commands_or_manual_steps`, `observations`, `artifacts`, `privacy`, `result`, and `claim_limits`.
-Classify each slot as exactly one of: `satisfied`, `partial`, `missing`, `waived`, `deferred`, or `not_applicable`. Deterministic comparison issues include `severity` and `fix_hint`; use those as the normal repair feedback loop before closing verification. Waiver/deferment narrows the claim; it is not proof. Screenshots, traces, videos, reports, accessibility scans, Gherkin, visual diffs, and manual notes are artifact types or activities mapped onto existing evidence kinds, not new evidence kinds. Artifact count is never proof; each artifact must tie to the slot claim, route/state, observation, artifact path/link, privacy metadata, and claim limit.
-For live UI runtime proof, expect `agent-browser` as the default captured tool unless the observed bundle explains a project-native equivalent or an availability constraint. Do not fail solely because another browser tool was used, but downgrade vague proof that lacks exact route/state, planned viewport coverage or rationale, interactive steps/refs where relevant, screenshot/report artifacts, or relevant console/network observations. Existing Playwright tests count as canonical repeatable regression evidence, not a replacement for scoped runtime evidence when the slot requires `runtime`.
-Artifact privacy metadata must include `visibility`, `retention`, `sensitivity`, and `safe_to_publish`; raw screenshots, traces, videos, DOM snapshots, and reports default to local-only and unsafe unless sanitized. Run `gsdd ui-proof validate <path>` or treat `gsdd health` E10 as blocking; add `--claim <...>` when relying on the bundle for public, tracked, delivery, release, or publication proof. Visual taste, accessibility judgment, baseline acceptance, subjective polish/layout quality, and privacy publication require human evidence or explicit waiver; human approval does not replace required `code`, `test`, `runtime`, or `delivery` evidence. Source annotations, AST/cAST findings, semantic search, comments, and Semble-like retrieval are discovery hints only.
-</ui_proof_comparison>
+<browser_proof_comparison>
+Before closure, direct `gsdd verify <phase>` and this workflow must fail closed when the target phase has no matching PLAN.md or SUMMARY.md; report structured prerequisite blockers instead of treating missing artifacts as an empty success. Read browser-proof declaration authority from the plan frontmatter: `browser_proof_required` and `browser_proof_rationale`. Body prose and stale sidecars do not declare proof intent. If `browser_proof_required: false`, verify the rationale is nonblank; legacy `ui_proof_slots: []` with meaningful `no_ui_proof_rationale` is a compatibility warning, not a blocker. If `browser_proof_required: true`, verify the plan contains a `## Browser Proof Plan` with route/state, viewport, runtime path, evidence kind, evidence command or narrowed no-command rationale, observations, artifacts with privacy/safety posture, and claim limit. Direct verification requires each required browser-proof plan to have a repo-local, parser-compatible `## Browser Proof Observation` that names the exact `Plan:` artifact, uses a supported evidence kind, records an explicit passing result, and keeps the claim limit bounded.
+For live UI runtime proof, expect `agent-browser` as the default captured tool unless the observation record explains a project-native equivalent or an availability constraint. Do not fail solely because another browser tool was used, but downgrade vague proof that lacks exact route/state, planned viewport coverage or rationale, interactive steps/refs where relevant, screenshot/report artifacts, relevant console/network observations, privacy/safety note, or a narrowed claim limit. Existing Playwright tests count as canonical repeatable regression evidence, not a replacement for scoped runtime evidence when browser proof requires runtime observation.
+Waiver/deferment narrows the claim; it is not proof. Screenshots, traces, videos, reports, accessibility scans, Gherkin, visual diffs, and manual notes are artifact types or activities mapped onto existing evidence kinds, not new evidence kinds. Artifact count is never proof; each artifact must tie to the route/state, observation, artifact path/link, privacy note, and claim limit. Direct verification checks the record shape and references; the verifier workflow remains responsible for judging whether the recorded observation substantively supports the claim.
+Raw screenshots, traces, videos, DOM snapshots, and reports default to local-only and unsafe unless sanitized. Visual taste, accessibility judgment, baseline acceptance, subjective polish/layout quality, and privacy publication require human evidence or explicit waiver; human approval does not replace required `code`, `test`, `runtime`, or `delivery` evidence. Source annotations, AST/cAST findings, semantic search, comments, and Semble-like retrieval are discovery hints only. Use the failure-cause names in `distilled/references/proof-rules.md` when proof fails or is partial.
+</browser_proof_comparison>
 
 <verification_levels>
 Check every artifact at three levels. A common failure mode is a file that exists but is still a stub.

package/docs/USER-GUIDE.md

@@ -233,6 +233,14 @@ Global install writes Workspine-managed files under selected agent homes and rec
 
 If `gsdd-cli` is globally installed, you can use the shorter `gsdd ...` form for the same commands. Generated workflow helper calls do not use the global binary; they run through `node .work/bin/gsdd.mjs ...` from the repo root.
 
+Browser-proof contract migration: `update` refreshes templates, skills,
+adapters, and helper code, but it does not rewrite historical phase artifacts.
+Old no-UI plans that use `ui_proof_slots: []` with a meaningful
+`no_ui_proof_rationale` continue to verify with a compatibility warning. Old
+plans with non-empty `ui_proof_slots` must be migrated to
+`browser_proof_required: true` plus a `## Browser Proof Plan` before they can
+close through direct verification.
+
 Normal user flow:
 
 1. Run `npx -y gsdd-cli init`.
@@ -259,7 +267,7 @@ Other CLI commands that remain available outside the first-run path:
 | Command | Purpose |
 |---------|---------|
 | `gsdd find-phase [N]` | Show phase info as JSON (for agent consumption) |
-| `gsdd verify <N>` | Run phase artifact and UI-proof closure checks for phase N; exits nonzero when verification is blocked |
+| `gsdd verify <N>` | Run phase artifact and browser-proof closure checks for phase N; exits nonzero when verification is blocked |
 | `gsdd scaffold phase <N> [name]` | Create a new phase plan file |
 
 ### Platform flags for `--tools`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gsdd-cli",
-  "version": "0.28.0",
+  "version": "0.29.1",
   "description": "Workspine — plan, execute, and verify AI-assisted work from files in your repo, with proof before done. Published as gsdd-cli.",
   "type": "module",
   "bin": {