gsdd-cli 0.19.3 → 0.21.0

package/distilled/DESIGN.md

@@ -72,6 +72,7 @@
 59. [Continuity Authority And Planning-State Drift](#d59---continuity-authority-and-planning-state-drift)
 60. [Release Closeout Contract](#d60---release-closeout-contract)
 61. [Deliberate Subagent Contract](#d61---deliberate-subagent-contract)
+62. [Repo-Native UI Proof Contract](#d62---repo-native-ui-proof-contract)
 
 ---
 
@@ -956,8 +957,9 @@ Implementation lives under `bin/lib/`:
 | E5 | ERROR | `.planning/templates/delegates/` missing or empty |
 | E6 | ERROR | `.planning/templates/research/` missing or empty |
 | E7 | ERROR | `.planning/templates/codebase/` missing or empty |
-| E8 | ERROR | `.planning/templates/` missing critical root files (`spec.md`, `roadmap.md`, `auth-matrix.md`) |
+| E8 | ERROR | `.planning/templates/` missing critical root files (`spec.md`, `roadmap.md`, `auth-matrix.md`, `ui-proof.md`) |
 | E9 | ERROR | `.planning/templates/brownfield-change/` missing or missing critical files (`CHANGE.md`, `HANDOFF.md`, `VERIFICATION.md`) |
+| E10 | ERROR | Known UI proof bundle metadata is unparseable or fails deterministic privacy/claim validation |
 | W1 | WARN | `generation-manifest.json` missing |
 | W2 | WARN | Manifest-tracked installed templates/helpers modified locally (hash mismatch vs manifest) |
 | W3 | WARN | Manifest-tracked installed templates/helpers missing from disk but listed in manifest |
@@ -2813,6 +2815,48 @@ Posture compatibility is part of that closeout contract: `repo_closeout` and `ru
 
 ---
 
+## D62 - Repo-Native UI Proof Contract
+
+**Decision (2026-04-28):** UI-sensitive work should carry a compact planned proof-slot contract and, when executed, an observed UI proof bundle that references artifacts by path or link while preserving the existing closure evidence kinds: `code`, `test`, `runtime`, `delivery`, and `human`.
+
+**Context:**
+- UI proof targets the recurring failure mode where agents claim a UI works or looks good without rendered proof, matched observations, or explicit human judgment.
+- The contract defines proof slots, proof bundles, comparison statuses, fail-closed agent guardrails, deterministic metadata validation, privacy metadata, and health visibility without adding a browser-provider framework.
+- GSD's archived planner, executor, and verifier roles preserve strong lifecycle discipline, but they do not provide this UI-specific planned-vs-observed proof model. GSDD keeps the lifecycle leverage and adds a repo-native UI proof substrate without adding a browser-provider framework.
+
+**Decision:**
+- Planning must classify UI-sensitive work and require either `ui_proof_slots` or an explicit `no_ui_proof_rationale`.
+- Planned slots record claim, route/state, required evidence kinds, minimum observations, environment/viewport, manual-acceptance requirement, claim limit, and requirement IDs.
+- Observed proof bundles record claim, requirement/slot IDs, route/state, environment, viewport, evidence inputs, commands/manual steps, observations, artifacts, privacy metadata, result, and claim limits.
+- Verification compares planned slots to observed bundles using `satisfied`, `partial`, `missing`, `waived`, `deferred`, and `not_applicable`; waiver and deferral are not proof.
+- UI correctness claims fail closed unless rendered proof is matched exactly to claim, route/state, observation, evidence kind, artifact path or manual step, privacy metadata, result, and claim limit, or an explicit waiver/deferment narrows the claim.
+- Human acceptance may close a narrowed claim and record proof debt, but it must not convert missing or mismatched non-human evidence into `satisfied` proof.
+- Screenshots, traces, videos, reports, accessibility scans, Gherkin, and visual diffs are artifact types or activities mapped onto the five existing evidence kinds, not new evidence kinds.
+- Source annotations, AST/cAST findings, semantic search hits, comments, and Semble-like retrieval may discover proof obligations, but they are discovery hints only and do not satisfy proof slots.
+- Visual taste, accessibility judgment, baseline acceptance, subjective polish/layout quality, and privacy publication require human evidence or explicit waiver, and human approval does not replace required `code`, `test`, `runtime`, or `delivery` evidence.
+- Deterministic metadata enforcement keeps the evidence and comparison-status vocabularies unchanged: artifact entries require `visibility`, `retention`, `sensitivity`, and `safe_to_publish`; raw screenshots, traces, videos, DOM snapshots, and reports default to `local_only` plus `safe_to_publish: false`; `bin/lib/ui-proof.mjs` validates required bundle/observation fields, structured command/manual-step entries, fixed evidence kinds, claim/result statuses, comparison statuses, claim limits, privacy metadata, safe artifact references, and public/tracked/delivery proof claims backed by local-only, unsafe, unsanitized, or privacy-contradictory artifacts.
+- `gsdd health` reports invalid known UI proof bundles as E10 using the same validator, staying read-only and metadata-only.
+
+**Leverage:**
+- Lost: UI-sensitive work now carries a small proof-contract burden, and invalid proof metadata can degrade/break health before agents can claim rendered UI outcomes.
+- Kept: repo-native markdown artifacts, optional project tooling, fixed closure evidence kinds, generated-surface freshness, and the plan/execute/verify separation.
+- Gained: exact claim-to-proof traceability, strict comparison statuses, privacy and claim-limit metadata, fail-closed overclaim guardrails, deterministic metadata validation, and health-visible protection against unsafe public proof claims.
+
+**Evidence:**
+- `distilled/templates/ui-proof.md`
+- `distilled/workflows/plan.md`, `distilled/workflows/execute.md`, `distilled/workflows/quick.md`, `distilled/workflows/verify.md`
+- `agents/planner.md`, `agents/executor.md`, `agents/verifier.md`, `distilled/templates/delegates/plan-checker.md`
+- `bin/lib/templates.mjs`, `bin/lib/ui-proof.mjs`, `bin/lib/health.mjs`, `bin/lib/rendering.mjs`
+- `tests/phase.test.cjs`, `tests/gsdd.guards.test.cjs`, `tests/gsdd.health.test.cjs`, `tests/gsdd.init.test.cjs`
+- GSD comparison: the upstream planner, executor, and verifier role patterns preserve lifecycle rigor, but they do not define UI proof slots or planned-vs-observed UI proof bundles.
+
+**Consequences:**
+- Future UI-related phases must not add new evidence kinds by treating artifact types as proof categories.
+- Future dogfood or runtime validation must not upgrade artifact counts or human waivers into proof.
+- Generated runtime surfaces and local templates must stay freshness-checkable through `gsdd update --templates` and health diagnostics.
+
+---
+
 ## Maintenance
 
 This document is updated when:

package/distilled/EVIDENCE-INDEX.md

@@ -485,6 +485,13 @@
 - GSD comparison source: `get-shit-done/workflows/new-project.md`
 - `tests/gsdd.guards.test.cjs`, `tests/gsdd.invariants.test.cjs`
 
+## D62 — Repo-Native UI Proof Contract
+- `distilled/templates/ui-proof.md`
+- `distilled/workflows/plan.md`, `distilled/workflows/execute.md`, `distilled/workflows/quick.md`, `distilled/workflows/verify.md`
+- `agents/planner.md`, `agents/executor.md`, `agents/verifier.md`, `distilled/templates/delegates/plan-checker.md`
+- `bin/lib/templates.mjs`, `bin/lib/ui-proof.mjs`, `bin/lib/health.mjs`, `bin/lib/rendering.mjs`
+- `tests/phase.test.cjs`, `tests/gsdd.guards.test.cjs`, `tests/gsdd.health.test.cjs`, `tests/gsdd.init.test.cjs`
+
 ---
 
 ## Maintenance

package/distilled/templates/delegates/plan-checker.md

@@ -34,6 +34,8 @@ Verify these dimensions:
 - `anti_regression_capture`: known prior failures, compatibility risks, and behavior that must not regress are represented in tasks or verification.
 - `escalation_integrity`: tasks include checkpoints or escalation when evidence, permissions, user decisions, or risky ambiguity are required.
 - `closure_honesty`: the plan's done criteria and evidence limits support only claims that execution can actually prove.
+- `closure_honesty`: for UI proof, reject agent-only `looks good` closure, artifact-count proof, unsupported evidence kinds, and human acceptance that converts missing/mismatched non-human evidence into `satisfied` proof. Waiver, deferment, proof debt, or narrowed-claim language is acceptable only when the stronger UI claim is not treated as proven.
+- `closure_honesty`: for UI proof privacy, require artifact `visibility`, `retention`, `sensitivity`, and `safe_to_publish`, require `gsdd ui-proof validate` or `gsdd health` when bundle metadata exists, and reject public/tracked/delivery/publication proof claims backed by local-only or `safe_to_publish: false` artifacts.
 - `high_leverage_review`: high-leverage surfaces have a second-pass review or equivalent contradiction/staleness check before completion.
 - `approach_alignment`: when APPROACH.md is provided, verify that plan tasks implement the chosen approaches from the user's decisions. Check:
   - **Alignment proof valid?** When `workflow.discuss` is `true`, APPROACH.md must record `alignment_status: user_confirmed` or `alignment_status: approved_skip`. Missing alignment proof, unknown status, or agent-discretion-only proof -> `blocker` with `fix_hint` telling the planner to revise APPROACH.md through real user alignment or an explicit user-approved skip.

package/distilled/templates/ui-proof.md

@@ -0,0 +1,174 @@
+# UI Proof Bundle Template
+
+Use this template when work affects rendered UI or when a plan defines `ui_proof_slots`. Keep the bundle compact, claim-specific, and attached to the relevant phase, quick task, or brownfield change.
+
+UI proof uses the existing closure evidence kinds only: `code`, `test`, `runtime`, `delivery`, and `human`. Screenshots, traces, videos, reports, accessibility scans, Gherkin, visual diffs, and manual notes are artifact types or activities that map onto those evidence kinds. They are not new evidence kinds.
+
+## Planned Proof Slots
+
+Every UI-sensitive plan needs either at least one slot under `ui_proof_slots` or an explicit `no_ui_proof_rationale` explaining why no rendered UI proof is required.
+
+```yaml
+ui_proof_slots:
+  - slot_id: ui-01
+    requirement_id: REQ-01
+    claim: "User can complete the changed flow without a broken rendered UI."
+    route_state: "/example route, role, data state, and UI state to inspect"
+    required_evidence_kinds: [test, runtime]
+    optional_evidence_kinds: [human]
+    minimum_observations:
+      - "Changed control is visible and usable in the stated state."
+      - "Expected interaction completes without console/runtime error."
+    environment:
+      app_url: "http://localhost:3000"
+      data_state: "synthetic or seeded data"
+    viewport:
+      width: 1280
+      height: 720
+      notes: "Use project default unless responsive behavior is part of the claim."
+    manual_acceptance_required: false
+    claim_limit: "Does not prove cross-browser layout, full accessibility conformance, production delivery, or unrelated UI states."
+no_ui_proof_rationale: null
+```
+
+Slot rules:
+- Keep each slot tied to one exact UI claim.
+- Use the lightest proof that can catch a botched rendered experience for that claim.
+- Source annotations, AST/cAST findings, semantic search hits, comments, and Semble-like retrieval may help discover proof obligations. They are discovery hints only; they do not satisfy proof slots.
+- Do not add Playwright, Cypress, Storybook, Cucumber, CI, browser MCP, or visual-regression tooling by default.
+- Human approval is required for visual taste, accessibility judgment, baseline acceptance, subjective polish/layout quality, and privacy publication decisions.
+- Human approval does not replace required non-human evidence when the slot requires `code`, `test`, `runtime`, or `delivery` evidence.
+
+## Observed Proof Bundle
+
+Create or update this bundle during execution or verification when planned UI proof slots exist. JSON is the canonical machine-readable proof bundle format. Markdown proof files must include fenced JSON for deterministic validation.
+
+```json
+{
+  "proof_bundle_version": 1,
+  "scope": {
+    "work_item": "phase-or-quick-or-brownfield-id",
+    "requirement_ids": ["REQ-01"],
+    "slot_ids": ["ui-01"],
+    "claim": "User can complete the changed flow without a broken rendered UI."
+  },
+  "route_state": {
+    "route": "/example",
+    "state": "role, data state, feature flag, loading/error/empty state, or component story"
+  },
+  "environment": {
+    "app_url": "http://localhost:3000",
+    "browser": "project default or manual browser",
+    "browser_version": "record if known",
+    "os": "record if relevant",
+    "data_state": "synthetic or seeded data"
+  },
+  "viewport": {
+    "width": 1280,
+    "height": 720,
+    "device_scale_factor": "record if relevant"
+  },
+  "evidence_inputs": {
+    "kinds": ["test", "runtime"],
+    "tools_used": ["manual"]
+  },
+  "commands_or_manual_steps": [
+    {
+      "command": "npm run test:e2e -- changed-flow.spec.ts",
+      "exit_code": 0,
+      "result": "passed",
+      "attempts": 1
+    },
+    {
+      "manual_step": "Open /example as synthetic user and complete the changed interaction.",
+      "result": "passed"
+    }
+  ],
+  "observations": [
+    {
+      "observation": "Changed control is visible and completes the flow.",
+      "claim": "User can complete the changed flow without a broken rendered UI.",
+      "route_state": {
+        "route": "/example",
+        "state": "role, data state, feature flag, loading/error/empty state, or component story"
+      },
+      "evidence_kind": "runtime",
+      "artifact_refs": ["test-results/changed-flow-report/index.html"],
+      "privacy": {
+        "data_classification": "synthetic",
+        "raw_artifacts_safe_to_publish": false,
+        "retention": "temporary_review"
+      },
+      "result": "passed",
+      "claim_limit": "Does not prove Safari/WebKit behavior."
+    }
+  ],
+  "artifacts": [
+    {
+      "path": "test-results/changed-flow-report/index.html",
+      "type": "report",
+      "visibility": "local_only",
+      "retention": "temporary_review",
+      "sensitivity": "possible",
+      "safe_to_publish": false,
+      "notes": "Local report only; not public proof."
+    }
+  ],
+  "privacy": {
+    "data_classification": "synthetic",
+    "redactions": [],
+    "raw_artifacts_safe_to_publish": false,
+    "retention": "Keep metadata bundle; keep raw artifacts only while needed for review or failed proof triage."
+  },
+  "manual_acceptance": {
+    "required": false,
+    "reviewer": null,
+    "result": "not_applicable"
+  },
+  "result": {
+    "claim_status": "passed",
+    "comparison_status_by_slot": {
+      "ui-01": "satisfied"
+    }
+  },
+  "claim_limits": [
+    "Does not prove Safari/WebKit behavior.",
+    "Does not prove full WCAG conformance.",
+    "Does not prove deployed production behavior."
+  ]
+}
+```
+
+Bundle rules:
+- Reference raw screenshots, traces, videos, DOM snapshots, reports, accessibility scans, Gherkin, and visual diffs by path or link. Do not store raw binary or sensitive artifacts inline.
+- Each observation must identify the claim, route/state, evidence kind, artifact references behind it, privacy metadata, result, and claim limit it supports.
+- Every observation `artifact_refs` value must match an `artifacts[].path` or `artifacts[].url` value.
+- Artifact count is never proof. Unsupported or weakly linked artifacts are `partial`, `missing`, `waived`, or `deferred`, not `satisfied`.
+- Each artifact must record the locked privacy fields `visibility`, `retention`, `sensitivity`, and `safe_to_publish`.
+- Raw screenshots, traces, videos, DOM snapshots, and reports default to `visibility: local_only` plus `safe_to_publish: false` unless explicitly classified as sanitized and safe to publish.
+- Local-only or `safe_to_publish: false` artifacts can support local review only; they must not back tracked, public, delivery, release, or publication proof claims.
+- Human acceptance may close a narrowed claim only by recording waiver, deferment, or proof debt; it must not upgrade missing or mismatched non-human proof to `satisfied`.
+- Quick-mode UI proof should use deterministic synthetic IDs such as `quick-001` and `quick-001-ui-01` when roadmap requirement IDs do not exist.
+
+## Deterministic Validation
+
+Use `gsdd ui-proof validate <path>` on JSON proof-bundle metadata or markdown fenced JSON before relying on a bundle for closure; add `--claim <public|publication|tracked|delivery|release>` only when validating that stronger proof use. Use `gsdd ui-proof compare <planned-slots-json> [observed-bundle-json ...]` when verifying planned proof slots against observed bundles through the deterministic product-facing path. Required observed-bundle top-level fields are `proof_bundle_version`, `scope`, `route_state`, `environment`, `viewport`, `evidence_inputs`, `commands_or_manual_steps`, `observations`, `artifacts`, `privacy`, `result`, and `claim_limits`. The validator checks required bundle and observation fields, structured command/manual-step entries, fixed evidence kinds, `result.claim_status`, observation `result`, comparison statuses, non-empty claim limits, locked artifact and observation privacy fields, observation-to-artifact references, workspace-relative/http(s) artifact references, and explicit public/tracked/delivery proof claims that rely on local-only, unsafe, unsanitized, or privacy-contradictory artifacts. `claim_status`, observation `result`, and command/manual-step `result` use `passed`, `failed`, `partial`, `waived`, `deferred`, or `not_applicable`. It is metadata-only and does not inspect raw screenshot, trace, video, DOM, or report contents.
+
+## Comparison Statuses
+
+Use these statuses when comparing planned slots to observed proof:
+
+| Status | Meaning | Claim impact |
+| --- | --- | --- |
+| `satisfied` | Required observations and evidence kinds are present, scoped, and inspectable for the exact claim. | Supports the scoped UI claim. |
+| `partial` | Some proof exists, but observations, artifact references, evidence kinds, privacy metadata, or assurance are weaker than planned. | Record a reduced claim or gap. |
+| `missing` | Required proof is absent. | Blocks the UI claim unless explicitly waived or deferred. |
+| `waived` | A human or approved plan waiver accepts the risk. | Does not prove the UI claim. |
+| `deferred` | Proof moved to later work. | Current work must not claim the UI behavior is proven. |
+| `not_applicable` | Accepted rationale says no UI proof is required. | No UI proof gap for that claim. |
+
+Proof debt notes should name the slot, claim, route/state, missing or weak linkage, human acceptance basis, narrowed claim limit, and follow-up trigger.
+
+## Claim Boundary
+
+A UI proof bundle proves only the scoped claim, route/state, environment, viewport, observations, and evidence kinds it records. It does not imply broad visual quality, cross-browser coverage, full accessibility conformance, production delivery, release readiness, or public proof unless those dimensions are explicitly planned, evidenced, and classified safe to publish.

package/distilled/workflows/audit-milestone.md

@@ -126,6 +126,7 @@ Combine:
 - Integration checker's report (wiring gaps, auth gaps, broken flows, requirements integration map)
 - Evidence observations by kind (`code`, `test`, `runtime`, `delivery`, `human`) from phase verifications, summaries, integration findings, and delivery metadata
 - Release claim posture observations: selected `release_claim_posture`, unsupported claims, waivers, deferrals, and contradiction checks for public, runtime, delivery, planning-drift, and generated-surface claims
+- UI proof debt from phase/quick proof bundles or verification gaps, preserving the rule that waiver/deferment/human acceptance narrows claims rather than satisfying missing proof
 
 ## 5. 3-Source Cross-Reference
 

package/distilled/workflows/execute.md

@@ -164,6 +164,11 @@ Before reporting a task complete:
 - if an API change is involved, hit the endpoint or targeted integration path
 - A task is not complete because code was written. It is complete when the intended verification path actually passes.
 
+### UI Proof Execution
+If the plan defines non-empty `ui_proof_slots`, create or update the observed UI proof bundle before claiming completion; required top-level fields are `proof_bundle_version`, `scope`, `route_state`, `environment`, `viewport`, `evidence_inputs`, `commands_or_manual_steps`, `observations`, `artifacts`, `privacy`, `result`, and `claim_limits`.
+Use existing UI tooling when available and cheap; manual/browser proof is acceptable when it records route/state, steps, observations, artifact references, and claim limits. Do not install Playwright, Cypress, Cucumber, Storybook, browser MCP, CI, or visual-regression tooling by default. Screenshots, traces, videos, reports, accessibility scans, Gherkin, visual diffs, and manual notes map onto existing evidence kinds, not new evidence kinds; reference raw artifacts by path/link instead of storing them inline.
+Each artifact entry must include `visibility`, `retention`, `sensitivity`, and `safe_to_publish`; raw screenshots, traces, videos, DOM snapshots, and reports default to `local_only` and `safe_to_publish: false` unless explicitly sanitized. Use `gsdd ui-proof validate <path>` when bundle metadata exists, adding `--claim <...>` only 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 decisions require human evidence or explicit waiver; artifact count, source comments, AST/cAST findings, semantic search, and Semble-like retrieval are not proof. If evidence does not match the slot claim, route/state, observation, artifact path/manual step, privacy metadata, result, and claim limit, record proof debt, waiver, deferment, or reduced claim language rather than `satisfied` proof.
+
 ### Git Guidance
 
 ```bash
@@ -440,20 +445,14 @@ Execution is done when all of these are true:
 </success_criteria>
 
 <completion>
-Report to the user what was accomplished, then present the next step:
-
+Report what was accomplished, then present the next step:
 ---
 **Completed:** Plan execution — created `.planning/phases/{phase_dir}/{plan_id}-SUMMARY.md`.
-
 **Next step:** Check `.planning/config.json` → `workflow.verifier`:
 - If `true`: run `/gsdd-verify` — verify that the phase goal was achieved
 - If `false` (or key missing): run `/gsdd-progress` — check status and route to the next phase
 
-Also available:
-- `/gsdd-plan` — plan the next wave (if more plans remain in this phase)
-- `/gsdd-quick` — handle a sub-hour task outside the phase cycle
-- `/gsdd-pause` — save context for later if stopping work
-
+Also available: `/gsdd-plan` for the next wave, `/gsdd-quick` for sub-hour work, or `/gsdd-pause` to save context.
 Consider clearing context before starting the next workflow for best results.
 ---
 </completion>

package/distilled/workflows/plan-milestone-gaps.md

@@ -15,6 +15,18 @@ If no audit file exists: stop and direct the user to run `/gsdd-audit-milestone`
 If audit status is `passed`: stop and direct the user to run `/gsdd-complete-milestone` instead.
 </prerequisites>
 
+<repo_root_helper_contract>
+All `node .planning/bin/gsdd.mjs ...` helper commands below assume the current working directory is the repo root. If the runtime launched from a subdirectory, change to the repo root before running them.
+</repo_root_helper_contract>
+
+<lifecycle_preflight>
+Before writing ROADMAP gap-closure phases or phase directories, run:
+
+- `node .planning/bin/gsdd.mjs lifecycle-preflight plan-milestone-gaps`
+
+If the preflight result is `blocked`, STOP and report the blocker. This workflow intentionally mutates planning truth, so it must not proceed through pre-existing planning-state drift.
+</lifecycle_preflight>
+
 <load_context>
 Before starting, read these files:
 
@@ -144,6 +156,14 @@ Create a directory for each gap closure phase:
 
 No files inside — `/gsdd-plan` populates them.
 
+## 8. Rebaseline Planning Fingerprint
+
+After confirming the ROADMAP update and phase directories exist, run:
+
+- `node .planning/bin/gsdd.mjs session-fingerprint write --allow-changed ROADMAP.md`
+
+This records the user-confirmed ROADMAP mutation so the recommended `/gsdd-plan [N]` handoff does not immediately block on expected `planning_state_drift`. The `--allow-changed ROADMAP.md` guard must fail if `SPEC.md` or `config.json` also drifted after preflight; stop and reconcile that unexpected drift instead of rebaselining it. Do not run this if the ROADMAP write failed or the phase directories are missing.
+
 </process>
 
 <success_criteria>
@@ -155,6 +175,7 @@ No files inside — `/gsdd-plan` populates them.
 - [ ] User confirmed gap closure plan before ROADMAP.md was updated
 - [ ] ROADMAP.md updated with new gap closure phases
 - [ ] Phase directories created
+- [ ] `session-fingerprint write` ran after the reviewed ROADMAP update so `/gsdd-plan [N]` is not stranded by expected planning drift
 </success_criteria>
 
 **MANDATORY: `.planning/ROADMAP.md` must be updated on disk before this workflow is complete. If the write fails, STOP and report the failure. Without the updated ROADMAP, the phase cycle cannot begin.**

package/distilled/workflows/plan.md

@@ -135,6 +135,10 @@ Also verify milestone truth is not self-contradictory across the planning surfac
 If any of these are missing or contradictory, STOP. Report the exact missing contract field or contradiction. Do not improvise a stronger phase contract from chat context alone.
 </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`, `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.
+</ui_proof_planning>
 <goal_backward_planning>
 Plan backward from success criteria.
 
@@ -192,6 +196,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.
@@ -221,6 +227,7 @@ Schema rules:
 - `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
@@ -607,7 +614,7 @@ Planning is done when all of these are true:
 - [ ] Plan self-check passed
 - [ ] Success criteria from `ROADMAP.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`, `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`, `ui_proof_slots` or `no_ui_proof_rationale`, `closure_claim_limit`, `parallelism_budget`, `leverage`, 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`
@@ -620,18 +627,12 @@ Planning is done when all of these are true:
 
 <completion>
 Report to the user what was accomplished, then present the next step:
-
 ---
 **Completed:** Phase planning — created `.planning/phases/{phase_dir}/{plan_id}-PLAN.md`.
 **Planning stops here:** `gsdd-plan` ends after the plan artifact is written. Do not start implementation in this same run, and do not treat imperative handoff text as execution authorization.
 Installed generated runtime surfaces are trusted through rendering, not reviewer memory: `npx -y gsdd-cli health` compares any local generated skill/adapter surfaces against current render output, and `npx -y gsdd-cli update` regenerates them when they drift. Bare `gsdd health` / `gsdd update` are equivalent only when globally installed.
-
 **Next workflow:** `/gsdd-execute` — start execution in a separate run when the user explicitly wants implementation to begin
-
-Also available:
-- `/gsdd-plan` — create additional plans for the same phase (if multi-wave)
-- `/gsdd-progress` — check overall project status
-
+Also available: `/gsdd-plan` for another wave, or `/gsdd-progress` for overall status.
 Consider clearing context before starting the next workflow for best results.
 ---
 </completion>

package/distilled/workflows/quick.md

@@ -118,6 +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, 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.
+- Keep UI 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
 
@@ -263,6 +267,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: `.planning/quick/$NEXT_NUM-$SLUG/$NEXT_NUM-SUMMARY.md`
+- If the quick plan defines `ui_proof_slots`, create or update `.planning/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`
+- 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:** `.planning/quick/$NEXT_NUM-$SLUG/$NEXT_NUM-SUMMARY.md`
 **Return:** Summary file path and completion status.

package/distilled/workflows/verify.md

@@ -128,6 +128,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>
+If the plan 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 the plan records only `no_ui_proof_rationale`, verify the rationale instead of requiring a bundle. 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`. 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.
+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>
+
 <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
@@ -423,13 +429,9 @@ 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` — route to the next phase or milestone audit.
 If status is `gaps_found`: **Next step:** `/gsdd-plan` — re-plan to close the identified gaps.
 If status is `human_needed`: **Next step:** `/gsdd-verify-work`, then rerun `/gsdd-verify` with UAT results.
-
 Consider clearing context before starting the next workflow for best results.
-
 </completion>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gsdd-cli",
-  "version": "0.19.3",
+  "version": "0.21.0",
   "description": "Workspine — a repo-native delivery spine for long-horizon AI-assisted work, with directly validated support for Claude Code, Codex CLI, and OpenCode, published as gsdd-cli.",
   "type": "module",
   "bin": {