gsdd-cli 0.28.0 → 0.29.0

package/bin/lib/plan-constants.mjs

@@ -7,11 +7,6 @@ export const PLAN_CHECK_DIMENSIONS = [
   'must_have_quality',
   'context_compliance',
   'goal_achievement',
-  'scope_boundaries',
-  'anti_regression_capture',
-  'escalation_integrity',
-  'closure_honesty',
-  'high_leverage_review',
   'approach_alignment',
 ];
 

package/distilled/DESIGN.md

@@ -72,7 +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)
+62. [Repo-Native Browser Proof Contract](#d62---repo-native-browser-proof-contract)
 63. [Computed-First Control Map](#d63---computed-first-control-map)
 64. [Work-Native Continuity Authority](#d64---work-native-continuity-authority)
 
@@ -961,7 +961,7 @@ Implementation lives under `bin/lib/`:
 | E7 | ERROR | `.planning/templates/codebase/` missing or empty |
 | 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 |
+| E10 | RETIRED | Retired UI proof bundle metadata validator; current browser proof uses plan declarations and markdown observation records |
 | 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 |
@@ -2372,9 +2372,13 @@ Sub-gap (b) was closed by D28's `<persistence>` mandate and guarded by G30. Sub-
   - `escalation_triggers`
   - `approval_gates`
   - `anti_regression_targets`
-  - `closure_claim_limit`
-  - `parallelism_budget`
-  - `leverage` (`lost / kept / gained`)
+  - `known_unknowns`
+  - `browser_proof_required`
+  - `browser_proof_rationale`
+  - `must_haves`
+- Keep high-risk review pressure in the plan body through Evidence Contract,
+  Stop-And-Challenge, Approval Gates, and Second-Pass Review sections instead
+  of expanding the frontmatter into a control-plane schema.
 - Upgrade planner checking to block missing anti-drift contract fields instead of treating them as optional prose quality.
 - Thread the new contract through execution and verification so the fields constrain what execution may do and what closure may claim.
 
@@ -2822,49 +2826,47 @@ Posture compatibility is part of that closeout contract: `repo_closeout` and `ru
 
 ---
 
-## D62 - Repo-Native UI Proof Contract
+## D62 - Repo-Native Browser Proof Contract
 
-**Decision (2026-04-28; revised 2026-05-09):** 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`. For live rendered UI proof, `agent-browser` is the default runtime evidence path for consumers, while existing Playwright tests remain the canonical repeatable browser-regression path when present. The deterministic `ui-proof` validator remains provider-agnostic structural validation, but it now validates planned slot specificity, concise tool provenance, local artifact path existence when validating from files, raw-artifact safety for paths and URLs, and failed/partial proof classification so the workflow cannot degrade back into unstructured "looks good" review. Direct phase verification also treats plan frontmatter as the UI-proof declaration authority and fails closed on missing phase prerequisites, empty `ui_proof_slots: []` without `no_ui_proof_rationale`, and invalid required UI proof.
+**Decision (2026-04-28; revised 2026-05-09; revised 2026-07-08):** UI-sensitive work should carry a compact browser-proof declaration in plan frontmatter and, when executed, a plain markdown observation record that references artifacts by path or link while preserving the existing closure evidence kinds: `code`, `test`, `runtime`, `delivery`, and `human`. For live rendered UI proof, `agent-browser` is the default runtime evidence path for consumers, while existing Playwright tests remain the canonical repeatable browser-regression path when present. Direct phase verification treats `browser_proof_required` and `browser_proof_rationale` as the declaration authority and fails closed on missing phase prerequisites, invalid browser-proof frontmatter, a missing `## Browser Proof Plan` when proof is required, or a required browser-proof plan that omits route/state, viewport, runtime path, evidence kind, evidence command or no-command rationale, observations, artifacts with privacy/safety posture, and claim limit.
 
 **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.
+- Browser 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 plan declarations, Browser Proof Plan sections, observation records, fail-closed agent guardrails, privacy/safety notes, and claim limits without adding a browser-provider framework or a separate JSON validator.
+- GSD's archived planner, executor, and verifier roles preserve strong lifecycle discipline, but they do not provide this UI-specific browser observation model. GSDD keeps the lifecycle leverage and adds a repo-native browser proof substrate without adding a browser-provider framework.
 - OneShot's QC guidance and Vercel's `agent-browser` skill converge on an interactive browser loop for snapshots, ref-based interaction, screenshots, and network/console-adjacent inspection. GSDD adapts that as a default workflow instruction, not as a hard validator dependency.
 
 **Decision:**
-- Planning must classify UI-sensitive work and require either `ui_proof_slots` or an explicit `no_ui_proof_rationale`.
-- Direct phase verification must read `ui_proof_slots` and `no_ui_proof_rationale` from plan frontmatter only; body prose, fenced examples, and stale sidecars are not declaration authority.
-- Direct phase verification must fail nonzero with structured blockers when no matching plan or summary exists, or when `ui_proof_slots: []` lacks a nonblank `no_ui_proof_rationale`.
-- When an explicit no-UI rationale exists, stale UI-proof sidecars are warning-level cleanup signals, not proof and not blockers.
-- Planned slots record claim, route/state, required evidence kinds, minimum observations, expected artifact types, runnable validation command, 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.
-- Planned slots must be tight enough for the plan checker to reject vague proof: specific route/state, viewport rationale or narrowed claim limit, minimum observations, expected artifact types, runnable validation, and matchability back to the exact UI claim.
+- Planning must classify UI-sensitive work with `browser_proof_required: true|false` and a nonblank `browser_proof_rationale`.
+- Direct phase verification must read browser-proof declaration authority from plan frontmatter only. Body prose and stale sidecars are not declaration authority.
+- Direct phase verification must fail nonzero with structured blockers when no matching plan or summary exists, when browser-proof frontmatter is invalid, or when a required Browser Proof Plan is missing or incomplete.
+- When browser proof is not required and the rationale is explicit, stale browser-proof observations are warning-level cleanup signals, not proof and not blockers. Legacy `ui_proof_slots: []` with a meaningful `no_ui_proof_rationale` is treated as a compatibility warning rather than a blocker; legacy non-empty `ui_proof_slots` still require migration because required rendered proof cannot be inferred losslessly.
+- Browser Proof Plan sections record route/state, viewport coverage, runtime path, evidence kind, evidence command or narrowed no-command rationale, observations, artifacts, privacy/safety note, and claim limit.
+- Observation records record the exact plan artifact, actual route/state, viewport, runtime path, evidence kind, command/manual step, rendered observations, artifacts, result, privacy/safety note, stale-after trigger, and claim limit.
+- Browser Proof Plan sections must be tight enough for the plan checker to reject vague proof: specific route/state, viewport coverage or narrowed claim, runtime path, supported evidence kind, rendered observations, artifacts/privacy notes, evidence command or no-command rationale, and claim limit.
 - The planner chooses viewport coverage, but responsive or layout-sensitive claims require desktop/mobile or equivalent state coverage unless the claim is explicitly narrowed.
 - Execution defaults to `agent-browser` for live UI runtime proof: open the route/state, capture interactive snapshots/refs where relevant, exercise the changed flow, capture screenshots for planned viewport(s), and record relevant console/network observations.
 - Existing Playwright tests or package scripts remain the canonical repeatable browser-regression evidence when present. Playwright scripting is reserved for checks `agent-browser` cannot cover cleanly, such as JS-disabled behavior, structured console listeners, or multi-context testing.
-- 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.
+- Direct verification fails closed unless each required browser-proof plan has a repo-local, parser-compatible, explicitly passing observation that names the exact plan artifact and carries supported evidence semantics, privacy/safety posture, and bounded claim scope. The workflow verifier still owns substantive judgment about whether the recorded observation actually supports the route/state, viewport, artifact, and 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.
+- 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 browser proof.
 - 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 validation keeps the evidence and comparison-status vocabularies unchanged: planned slots require specific claim, route/state, evidence, expected artifacts, validation, viewport, and claim-limit fields; 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, concise `tools_used` IDs, claim/result statuses, comparison statuses, failure classification for failed/partial proof, claim limits, privacy metadata, safe artifact references, local artifact path existence when validating file-backed bundles, 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 avoiding raw artifact content inspection.
-- Failed UI proof is reported through existing GSDD gap/proof-debt language. Product behavior defects, missing or blocked infrastructure, flaky harnesses, and ambiguous specs explain causes, but they do not add new evidence kinds, result statuses, or comparison statuses.
+- The current contract is validator-light by design: direct phase verification checks declaration shape, required Browser Proof Plan fields, observation record shape, safe linked-record boundaries, exact plan references, explicit pass/fail posture, supported evidence-kind labels, and bounded claim wording. It does not inspect raw screenshot pixels, report contents, or visual quality; substantive rendered proof remains a workflow/role obligation captured in summaries or observation records.
+- Failed browser proof is reported through the failure-cause names in `distilled/references/proof-rules.md`: product behavior defects, missing or blocked infrastructure, flaky harnesses, and ambiguous specs explain causes, but they do not add new evidence kinds.
 
 **Leverage:**
-- Lost: UI-sensitive work now carries a small proof-contract burden, and default live proof guidance adds slightly more specificity for planners/checkers to enforce.
-- Kept: repo-native markdown artifacts, optional project tooling, fixed closure evidence kinds, generated-surface freshness, the plan/execute/verify separation, and provider-agnostic deterministic metadata validation.
-- Gained: exact claim-to-proof traceability, strict comparison statuses, privacy and claim-limit metadata, fail-closed overclaim guardrails, deterministic metadata validation, a concrete live browser evidence path, and health-visible protection against unsafe public proof claims.
+- Lost: UI-sensitive work still carries a small proof-contract burden, and direct verification checks only shape rather than raw screenshot/report contents.
+- Kept: repo-native markdown artifacts, optional project tooling, fixed closure evidence kinds, generated-surface freshness, the plan/execute/verify separation, and a concrete live browser evidence path.
+- Gained: a much simpler consumer contract, exact claim-to-observation traceability, privacy/safety notes, claim limits, and fail-closed overclaim guardrails without a non-existent validator command.
 
 **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/phase.mjs`, `bin/lib/rendering.mjs`
+- `bin/lib/templates.mjs`, `bin/lib/health.mjs`, `bin/lib/phase.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.
+- GSD comparison: the upstream planner, executor, and verifier role patterns preserve lifecycle rigor, but they do not define browser-proof plan declarations or observation records.
 - OneShot QC source: `https://github.com/oneshot-repo/OneShot/tree/main/skills`
 - Vercel `agent-browser` docs: `https://github.com/vercel-labs/agent-browser/blob/main/skill-data/core/SKILL.md` and `https://agent-browser.dev/snapshots`
 - Playwright docs: `https://playwright.dev/docs/trace-viewer`, `https://playwright.dev/docs/next/screenshots`, and `https://playwright.dev/mcp/tools/tracing`

package/distilled/EVIDENCE-INDEX.md

@@ -486,11 +486,11 @@
 - 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
+## D62 — Repo-Native Browser 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`
+- `bin/lib/templates.mjs`, `bin/lib/health.mjs`, `bin/lib/phase.mjs`, `bin/lib/rendering.mjs`
 - `tests/phase.test.cjs`, `tests/gsdd.guards.test.cjs`, `tests/gsdd.health.test.cjs`, `tests/gsdd.init.test.cjs`
 - OneShot QC/browser policy: https://github.com/oneshot-repo/OneShot/tree/main/skills
 - Vercel agent-browser docs: https://github.com/vercel-labs/agent-browser/blob/main/skill-data/core/SKILL.md, https://agent-browser.dev/snapshots
@@ -503,7 +503,7 @@
 - Agent-hostile UI semantics source: https://dev.to/ratikkoka/your-ui-is-invisible-to-ai-agents-heres-how-to-fix-it-1ib3
 - Browser-harness efficiency source: https://dev.to/louaiboumediene/the-ai-harness-why-your-ai-coding-agent-is-only-as-smart-as-the-repo-you-put-it-in-cml
 - Dynamic-UI harness brittleness source: https://tessl.io/blog/webmcp-making-web-apps-faster-and-cheaper-for-ai-agents/
-- Long-term pitfalls carried forward: do not accept screenshot-free "looks good" claims, weak planned slots, unverified artifact paths, stale interactive refs after page mutation, partial/failed proof without failure classification, raw artifact publication without privacy metadata, browser contention in parallel checks, or semantic/selector-poor UI that forces fragile coordinate inspection.
+- Long-term pitfalls carried forward: do not accept screenshot-free "looks good" claims, weak browser-proof plans, unverified artifact paths, stale interactive refs after page mutation, partial/failed proof without failure classification, raw artifact publication without privacy/safety notes, browser contention in parallel checks, or semantic/selector-poor UI that forces fragile coordinate inspection.
 - Supporting spec/runtime docs: https://openspec.dev/, https://www.lean-spec.dev/docs/guide/first-principles, https://help.openai.com/en/articles/11369540-codex-in-chatgpt, https://docs.claude.com/en/docs/agents-and-tools/agent-skills, https://docs.github.com/en/copilot/concepts/prompting/response-customization
 
 ## D63 — Computed-First Control Map

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

@@ -13,31 +13,30 @@ Read only the explicit inputs provided by the orchestrator:
 Do NOT inherit the planner's hidden reasoning. Treat the current plans as untrusted drafts that must prove they will achieve the phase goal before execution.
 
 Verify these dimensions:
-- `requirement_coverage`: every phase requirement is covered by at least one concrete task
+- `requirement_coverage`: every phase requirement is covered by at least one concrete task.
 - `task_completeness`: every executable task has files, action, verify, and done fields. Additionally check verify quality:
   - **Runnable?** Does `<verify>` contain at least one command that an executor can run programmatically (e.g., a shell command, test runner invocation, curl request)? If ALL verify items are observational text with no runnable command -> `blocker`.
   - **Fast?** Do verify commands complete quickly? Flag full E2E suites (playwright, cypress, selenium) without a faster smoke test -> `warning`. Flag watch-mode flags (`--watchAll`, `--watch`) -> `blocker`. Flag arbitrary delays > 30s -> `warning`.
   - **Ordered?** If a verify command references a test file, does an earlier task in the plan create that file? If the referenced file has no prior task producing it -> `blocker`.
-- `dependency_correctness`: ordering, dependencies, and plan structure are coherent
-- `key_link_completeness`: important wiring/integration links are planned, not just isolated artifacts
-- `scope_sanity`: plans are sized so an executor can complete them without context collapse
-- `must_have_quality`: success criteria and must-haves are specific, observable, and reflected in tasks
+  - **Browser proof command?** If the plan requires browser proof, the Browser Proof Plan names a runnable evidence command or an explicit narrowed no-command rationale. A rendered-UI claim with neither is a `blocker`.
+- `dependency_correctness`: ordering, dependencies, and plan structure are coherent.
+- `key_link_completeness`: important wiring/integration links are planned, not just isolated artifacts.
+- `scope_sanity`: plans are sized so an executor can complete them without context collapse, and hard boundaries, anti-goals, and explicit out-of-scope items are preserved in task scope.
+- `must_have_quality`: success criteria and must-haves are specific, observable, and reflected in tasks.
 - `context_compliance`: locked decisions are honored and deferred ideas stay out of scope. Additionally check scope consistency:
   - **Must-have coverage?** Every must-have requirement mapped to this phase in SPEC.md must appear in at least one plan task. A must-have that silently disappears from the plan is a `blocker`.
   - **Deferred exclusion?** Items marked "Nice to Have", "Deferred", or "Out of Scope" in SPEC.md must not appear as plan tasks. Present → `blocker`.
   - **Cross-surface consistency?** If SPEC.md marks an item as must-have but APPROACH.md marks it as deferred (or vice versa), surface the contradiction → `blocker`. Include a `fix_hint` asking the planner to resolve the conflict with the user before proceeding.
+  - **Anti-regression captured?** Known prior failures, compatibility risks, and behavior that must not regress are represented in tasks or verification.
+  - **Escalation preserved?** Tasks include checkpoints or escalation when evidence, permissions, user decisions, or risky ambiguity are required.
+  - **Abstraction justified?** Reject a task or refactor whose only rationale is "cleaner code" without reducing risk, removing meaningful duplication, simplifying a consumer path, or matching an existing repo pattern.
 - `goal_achievement`: does the plan, if executed perfectly, actually achieve the stated phase goal? Check:
   - **Goal addressed?** Compare the phase goal statement to the plan's collective task outputs. Would successful completion of all tasks deliver the goal? If the goal says "users can authenticate" but tasks only set up database schema → `blocker`.
   - **Success criteria reachable?** Are the phase success criteria from ROADMAP.md achievable through the planned tasks? Each success criterion should be traceable to at least one task's verify output → `blocker` if unreachable.
   - **Outcome observable?** After execution, could a human or automated check confirm the goal was met? Plans that produce only internal artifacts with no user-visible or testable outcome → `warning`.
-- `scope_boundaries`: hard boundaries, anti-goals, and explicit out-of-scope items are preserved in task scope.
-- `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 planning, reject weak slots that omit a specific route/state, viewport rationale or narrowed viewport claim limit, minimum observations, expected artifact types, runnable validation, or a way to compare observed proof back to the planned claim. Treat under-specified viewport coverage as a blocker for responsive or layout-sensitive claims. `agent-browser` is the default live runtime evidence path; do not block a slot solely for using another project-native browser path, but require the plan to explain the `agent-browser` availability constraint and fallback choice.
-- `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.
+  - **Claim honest?** Done criteria and evidence limits support only claims that execution can actually prove. For browser proof, reject agent-only "looks good" closure, artifact-count proof, unsupported evidence kinds, and human acceptance that replaces required code, test, runtime, or delivery evidence.
+  - **Browser proof specific?** Required browser proof names exact route/state, viewport coverage or a narrowed viewport claim, runtime path, evidence kind, rendered observations, artifacts/privacy notes, and claim limit. Under-specified viewport coverage is a blocker for responsive or layout-sensitive claims, and fallback browser tooling must state the `agent-browser` availability constraint.
+  - **Second pass present?** Shared or high-leverage surfaces have a final contradiction/staleness review 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.
   - **Canonical proof fields present?** APPROACH.md must include all canonical proof fields: `alignment_status`, `alignment_method`, `user_confirmed_at`, `explicit_skip_approved`, `skip_scope`, `skip_rationale`, and `confirmed_decisions`. Missing fields -> `blocker`.
@@ -56,7 +55,7 @@ Return JSON only as a single finding summary object with this shape:
   "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",

package/distilled/templates/ui-proof.md

@@ -1,200 +1,100 @@
-# UI Proof Bundle Template
+# Browser Proof Observation 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.
+Use this template when work affects rendered UI or when a plan sets
+`browser_proof_required: true`. Keep the record 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.
+Browser proof uses the existing closure evidence kinds only: `code`, `test`,
+`runtime`, `delivery`, and `human`. Screenshots, traces, videos, reports,
+accessibility scans, visual diffs, and manual notes are artifacts or activities
+that map onto those evidence kinds. They are not new evidence kinds.
 
-For live rendered UI evidence, default to `agent-browser`: open the route, capture an interactive snapshot/refs when interaction is part of the claim, exercise the changed flow, capture screenshots for the planned viewport(s), and record console/network observations when they affect the claim. If the repo already has Playwright tests or a package script wrapping them, those remain the canonical repeatable regression path; use them as `test` evidence and use `agent-browser` for complementary live runtime proof. Do not introduce new Playwright, Cypress, Storybook, CI, browser MCP, or visual-regression infrastructure just to satisfy this template. Use Playwright scripting only for checks `agent-browser` cannot cover cleanly, such as JS-disabled behavior, structured console listeners, or multi-context testing.
+For live rendered UI evidence, default to `agent-browser`: open the route,
+capture interactive refs when interaction is part of the claim, exercise the
+changed flow, capture screenshots for planned viewport(s), and record
+console/network observations when they affect the claim. If the repo already
+has Playwright tests or a package script wrapping them, those remain the
+repeatable regression path; use them as `test` evidence and use browser
+observation for complementary runtime proof.
 
-Tool availability is part of the proof record. In runtimes where `agent-browser` is not available, first state that availability constraint, then use the closest project-native interactive browser path and record the fallback in `evidence_inputs.tools_used`, `commands_or_manual_steps`, and `claim_limits`. A fallback can support a narrowed local runtime claim, but it must not silently pretend that the default `agent-browser` path ran.
+Do not introduce new Playwright, Cypress, Storybook, CI, browser MCP, or visual
+regression infrastructure just to satisfy this template. Use Playwright
+scripting only for checks `agent-browser` cannot cover cleanly, such as
+JS-disabled behavior, structured console listeners, or multi-context testing.
 
-## Planned Proof Slots
+Tool availability is part of the proof record. In runtimes where
+`agent-browser` is not available, first state that availability constraint, then
+use the closest project-native interactive browser path and narrow the claim to
+what that fallback actually proves.
 
-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.
+## Plan Declaration
 
-```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."
-    expected_artifact_types: [screenshot, report]
-    validation_command: "gsdd ui-proof compare {work_item_dir}/ui-proof-slots.json {work_item_dir}/UI-PROOF.md"
-    environment:
-      app_url: "http://localhost:3000"
-      data_state: "synthetic or seeded data"
-    viewport:
-      width: 1280
-      height: 720
-      notes: "State why this viewport is enough for the claim, or add separate slots/observations for mobile, desktop, or responsive states."
-    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
-```
+Every UI-sensitive plan should contain:
 
-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.
-- Specify the route/state, viewport choice, minimum observations, expected artifact types, and runnable validation path tightly enough that a checker can reject vague proof before execution.
-- The planner chooses the viewport set, but the slot must explain the choice. Include desktop and mobile proof when the claim covers responsive layout or when the changed surface is likely to behave differently across those sizes; otherwise narrow the claim limit.
-- 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.
-
-Replace placeholders such as `{work_item_dir}` with the current phase, quick-task, or brownfield-change directory before running commands or validating the bundle.
-
-```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": "agent-browser default; record fallback when unavailable",
-    "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": ["playwright", "agent-browser"]
-  },
-  "commands_or_manual_steps": [
-    {
-      "command": "npm run test:e2e -- changed-flow.spec.ts",
-      "exit_code": 0,
-      "result": "passed",
-      "attempts": 1
-    },
-    {
-      "command": "agent-browser open http://localhost:3000/example && agent-browser snapshot -i && agent-browser screenshot {work_item_dir}/artifacts/example-1280.png --full",
-      "result": "passed",
-      "attempts": 1
-    },
-    {
-      "manual_step": "Using agent-browser refs, complete the changed interaction as a synthetic user and check for visible breakage or relevant console/network failures.",
-      "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", "{work_item_dir}/artifacts/example-1280.png"],
-      "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."
-    },
-    {
-      "path": "{work_item_dir}/artifacts/example-1280.png",
-      "type": "screenshot",
-      "visibility": "local_only",
-      "retention": "temporary_review",
-      "sensitivity": "possible",
-      "safe_to_publish": false,
-      "notes": "Local screenshot only; not public proof unless sanitized and reclassified."
-    }
-  ],
-  "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"
-    },
-    "failure_classification": null
-  },
-  "claim_limits": [
-    "Does not prove Safari/WebKit behavior.",
-    "Does not prove full WCAG conformance.",
-    "Does not prove deployed production behavior."
-  ]
-}
+```yaml
+browser_proof_required: true
+browser_proof_rationale: Visible route or interaction changes require rendered browser proof.
 ```
 
-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.
-- Classify failed UI proof using existing GSDD gap/proof-debt language: `product_bug`, `missing_infra`, `flaky_harness`, or `ambiguous_spec`. Do not add new result statuses or evidence kinds for those causes.
+Plans that do not claim rendered UI behavior should contain:
 
-## Deterministic Validation
+```yaml
+browser_proof_required: false
+browser_proof_rationale: CLI/docs/backend-only work; no visible UI behavior is claimed.
+```
 
-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 planned-slot fields are `slot_id`, `claim`, `route_state`, `required_evidence_kinds`, `minimum_observations`, `expected_artifact_types`, `validation_command`, `environment`, `viewport`, `manual_acceptance_required`, and `claim_limit`. 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 planned-slot specificity, required bundle and observation fields, structured command/manual-step entries, fixed evidence kinds, concise `tools_used` IDs, `result.claim_status`, observation `result`, comparison statuses, failure classification for failed/partial proof, non-empty claim limits, locked artifact and observation privacy fields, observation-to-artifact references, workspace-relative/http(s) artifact references, existing local artifact paths when validating from files, 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`; failed/partial proof uses `product_bug`, `missing_infra`, `flaky_harness`, or `ambiguous_spec`. It does not inspect raw screenshot, trace, video, DOM, or report contents and does not require any specific browser provider such as `agent-browser`.
+When browser proof is required, the plan body should include:
+
+```markdown
+## Browser Proof Plan
+Routes/states: /example route, role, data state, and UI state to inspect
+Viewports: Desktop 1280px and mobile 390px, or a narrowed viewport claim
+Runtime path: agent-browser preferred; explain fallback constraints if unavailable
+Evidence kind: runtime
+No-command rationale: agent-browser/manual refs were required for this local runtime; claim is limited to the observed session.
+Observations: Changed control is visible, interaction completes, no relevant console/network failures
+Artifacts: .work/.../artifacts/example-1280.png (local-only unless sanitized)
+Claim limit: Proves only this changed route/state and viewport set
+```
 
-## Comparison Statuses
+If no command can reproduce the proof because the runtime path is manual or
+interactive only, replace `Evidence command:` with:
 
-Use these statuses when comparing planned slots to observed proof:
+```markdown
+No-command rationale: agent-browser/manual refs were required for this local runtime; claim is limited to the observed session.
+```
 
-| 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. |
+## Observation Record
+
+Write one record per checked flow:
+
+```markdown
+## Browser Proof Observation
+
+- Plan: 01-example/01-PLAN.md
+- Flow: /example route, role, data state, and UI state checked
+- Viewports: 1280x720 desktop, 390x844 mobile
+- Runtime path: agent-browser
+- Evidence kind: runtime
+- No-command rationale: agent-browser/manual refs were required for this local runtime; claim is limited to the observed session.
+- Observed: Changed control rendered, interaction completed, no relevant console/network failures
+- Artifacts:
+  - .work/.../artifacts/example-1280.png — local-only, not safe to publish
+  - .work/.../artifacts/example-390.png — local-only, not safe to publish
+- Privacy/safety: artifacts are local-only and not safe to publish unless sanitized
+- Result: passed
+- Claim limit: Proves only the scoped route/state, data setup, and viewport set.
+- Stale after: route markup, interaction behavior, data fixture, or viewport assumptions change.
+```
 
-Proof debt notes should name the slot, claim, route/state, missing or weak linkage, human acceptance basis, narrowed claim limit, and follow-up trigger.
+For failed or partial proof, use the failure-cause names defined in
+`distilled/references/proof-rules.md` and record the narrowed claim or 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.
+Browser proof proves only the scoped route/state, environment, viewport,
+observations, artifacts, 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 safe to publish.

package/distilled/workflows/audit-milestone.md

@@ -126,7 +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
+- Browser-proof debt from phase/quick observation records 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

@@ -107,7 +107,7 @@ For each task in the plan, follow this loop:
 
 ### Frontmatter And Task Semantics
 The executor consumes the plan schema defined by `/gsdd-plan`:
-- frontmatter keys: `phase`, `plan`, `type`, `wave`, `depends_on`, `files-modified`, `autonomous`, `requirements`, `must_haves`, `tdd`
+- frontmatter keys: `phase`, `plan`, `type`, `wave`, `depends_on`, `files-modified`, `autonomous`, `requirements`, `browser_proof_required`, `browser_proof_rationale`, `must_haves`, `tdd`
 - task types:
   - `type="auto"` - proceed without pausing
   - `type="checkpoint:user"` - stop for a required user decision or human-only step
@@ -164,11 +164,10 @@ 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 `agent-browser` as the default live UI proof path. Record the planned route/state open, interactive snapshots/refs when interaction is part of the claim, changed-flow interaction, screenshots for planned viewport(s), and relevant console/network observations. If `agent-browser` is unavailable, record the availability constraint and the closest project-native interactive browser fallback in the proof bundle instead of silently treating the fallback as the default path. If the repo already has Playwright tests or a package script wrapping them, run the relevant targeted test as canonical repeatable regression evidence; keep `agent-browser` as complementary runtime proof. Use Playwright scripting only for checks `agent-browser` cannot cover cleanly, such as JS-disabled, structured console, or multi-context verification. 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.
-Classify failed UI proof using existing gap/proof-debt language: `product_bug`, `missing_infra`, `flaky_harness`, or `ambiguous_spec`. Do not add new evidence kinds or result statuses for those causes.
+### Browser Proof Execution
+If the plan sets `browser_proof_required: true`, execute the `## Browser Proof Plan` before claiming completion. Record the exact `Plan:` artifact path plus route/state, viewport(s), runtime path, evidence kind, evidence command or narrowed no-command rationale, observations, artifact paths, privacy/safety note, result, and claim limit in the summary or a linked observation record.
+Use `agent-browser` as the default live browser proof path. Record the planned route/state open, interactive snapshots/refs when interaction is part of the claim, changed-flow interaction, screenshots for planned viewport(s), and relevant console/network observations. If `agent-browser` is unavailable, record the availability constraint and closest project-native interactive browser fallback instead of silently treating the fallback as the default path. If the repo already has Playwright tests or a package script wrapping them, run the relevant targeted test as canonical repeatable regression evidence; keep browser runtime observation as complementary proof. Use Playwright scripting only for checks `agent-browser` cannot cover cleanly, such as JS-disabled, structured console, or multi-context verification. 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. Raw screenshots, traces, videos, DOM snapshots, and reports default to local-only and unsafe to publish unless explicitly sanitized. 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 planned route/state, viewport, observation, artifact path/manual step, privacy note, result, and claim limit, record proof debt, waiver, deferment, or reduced claim language rather than satisfied proof. Use the failure-cause names in `distilled/references/proof-rules.md` when proof fails or is partial.
 
 ### Git Guidance