gsdd-cli 0.19.2 → 0.20.0

package/distilled/templates/delegates/mapper-arch.md

@@ -22,5 +22,5 @@ Include:
 </quality_gate>
 
 Write to: `.planning/codebase/ARCHITECTURE.md`
-Return: 3-5 sentence summary to the Orchestrator when done.
+Return: Routing summary to the Orchestrator (100-200 tokens) when done.
 Guardrails: Max Agent Hops = 3. No static directory dumps.

package/distilled/templates/delegates/mapper-concerns.md

@@ -23,5 +23,5 @@ Include:
 </quality_gate>
 
 Write to: `.planning/codebase/CONCERNS.md`
-Return: 3-5 sentence summary to the Orchestrator when done. If secrets found, STOP and report immediately.
+Return: Routing summary to the Orchestrator (100-200 tokens) when done. If secrets found, STOP and report immediately.
 Guardrails: Max Agent Hops = 3. Hard stop on secrets.

package/distilled/templates/delegates/mapper-quality.md

@@ -24,5 +24,5 @@ Include:
 </quality_gate>
 
 Write to: `.planning/codebase/CONVENTIONS.md`
-Return: 3-5 sentence summary to the Orchestrator when done.
+Return: Routing summary to the Orchestrator (100-200 tokens) when done.
 Guardrails: Max Agent Hops = 3. Rules not inventories.

package/distilled/templates/delegates/mapper-tech.md

@@ -21,5 +21,5 @@ Include:
 </quality_gate>
 
 Write to: `.planning/codebase/STACK.md`
-Return: 3-5 sentence summary to the Orchestrator when done.
+Return: Routing summary to the Orchestrator (100-200 tokens) when done.
 Guardrails: Max Agent Hops = 3. No static dependency dumps.

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

@@ -1,6 +1,6 @@
 **Role contract:** Read `.planning/templates/roles/planner.md` before starting. Reuse its planning vocabulary and quality standards, but this wrapper overrides your objective: you are reviewing plans, not authoring them.
 
-You are the fresh-context plan checker for `/gsdd-plan`.
+You are the fresh-context plan checker for `/gsdd-plan`. This is a read-only review delegate: return the JSON finding summary only, and do not edit plan artifacts yourself.
 
 Read only the explicit inputs provided by the orchestrator:
 - target phase goal and requirement IDs
@@ -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.
@@ -45,7 +47,7 @@ Verify these dimensions:
   - **Deferred excluded?** Deferred ideas from APPROACH.md must not appear in plan tasks -> `blocker` if found.
   - If `workflow.discuss` is `true` in the project config and no APPROACH.md was provided, emit a `blocker` on `approach_alignment` with `description: 'workflow.discuss is true but no APPROACH.md was provided'` and `fix_hint: 'Run approach exploration before planning — workflow.discuss=true requires an approved APPROACH.md before a plan can be emitted.'` If `workflow.discuss` is `false` or the key is absent and no APPROACH.md was provided, skip this dimension entirely.
 
-Return JSON only as a single object with this shape:
+Return JSON only as a single finding summary object with this shape:
 
 ```json
 {

package/distilled/templates/delegates/researcher-architecture.md

@@ -26,5 +26,5 @@ Your output informs phase structure in ROADMAP.md. Include:
 
 Write to: `.planning/research/ARCHITECTURE.md`
 Use template: `.planning/templates/research/architecture.md` (if it exists)
-Return: 3-5 sentence summary of key findings to the Orchestrator when done.
+Return: Human-read structured summary to the Orchestrator (300-500 tokens) when done.
 Guardrails: Max Agent Hops = 3.

package/distilled/templates/delegates/researcher-features.md

@@ -26,5 +26,5 @@ Your output feeds SPEC requirements. Categorize explicitly:
 
 Write to: `.planning/research/FEATURES.md`
 Use template: `.planning/templates/research/features.md` (if it exists)
-Return: 3-5 sentence summary of key findings to the Orchestrator when done.
+Return: Human-read structured summary to the Orchestrator (300-500 tokens) when done.
 Guardrails: Max Agent Hops = 3.

package/distilled/templates/delegates/researcher-pitfalls.md

@@ -26,5 +26,5 @@ Your output prevents mistakes in roadmap and planning. For each pitfall:
 
 Write to: `.planning/research/PITFALLS.md`
 Use template: `.planning/templates/research/pitfalls.md` (if it exists)
-Return: 3-5 sentence summary of key findings to the Orchestrator when done.
+Return: Human-read structured summary to the Orchestrator (300-500 tokens) when done.
 Guardrails: Max Agent Hops = 3.

package/distilled/templates/delegates/researcher-stack.md

@@ -26,5 +26,5 @@ Your output feeds the roadmapper. Be prescriptive:
 
 Write to: `.planning/research/STACK.md`
 Use template: `.planning/templates/research/stack.md` (if it exists)
-Return: 3-5 sentence summary of key findings to the Orchestrator when done.
+Return: Human-read structured summary to the Orchestrator (300-500 tokens) when done.
 Guardrails: Max Agent Hops = 3.

package/distilled/templates/delegates/researcher-synthesizer.md

@@ -11,7 +11,7 @@ Read these files (all should exist):
 Cross-reference them. Surface conflicts and dependencies between findings. Do NOT do new research — synthesize what exists.
 
 SUMMARY.md MUST include:
-1. **Key Findings** — top 5-7 bullets across all 4 dimensions
+1. **Key Findings** — the highest-signal findings across all 4 dimensions
 2. **Implications for Roadmap** — suggested phase groupings derived from architecture build order + pitfall avoidance (this is the critical handoff to the roadmapper)
 3. **Research Flags** — which phases need deeper research vs standard patterns
 4. **Confidence Assessment** — per domain: stack / features / architecture / pitfalls
@@ -27,5 +27,5 @@ Use template: `.planning/templates/research/summary.md` (if it exists)
 </quality_gate>
 
 Write to: `.planning/research/SUMMARY.md`
-Return: 5-7 bullet key findings to the Orchestrator when done.
+Return: Agent-mediated structured summary to the Orchestrator (500-800 tokens) when done.
 Guardrails: Max Agent Hops = 2. Do not do new research — synthesize only.

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. 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

@@ -110,7 +110,7 @@ With phase context collected, delegate cross-phase integration checking:
 
 **Task:** Verify cross-phase wiring, API coverage, auth protection, and E2E user flows. Return structured integration report with wiring summary, API coverage, auth protection, E2E flow status, and Requirements Integration Map.
 
-**Return:** Structured integration report (wiring, APIs, auth protection, flows, requirements map).
+**Return:** Structured integration report summary (wiring, APIs, auth protection, flows, requirements map). The checker is read-only; the auditor owns the milestone audit artifact.
 </delegate>
 
 If the runtime supports spawning a subagent: spawn the integration checker as a separate read-only context for independent verification.
@@ -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/map-codebase.md

@@ -102,7 +102,7 @@ Parallel: (use parallelization value from .planning/config.json)
 Context: Current working directory. DO NOT share conversation history.
 Instruction: Read `.planning/templates/delegates/mapper-tech.md` for full task instructions. Follow them exactly.
 Output: `.planning/codebase/STACK.md`
-Return: 3-5 sentence summary to Orchestrator.
+Return: Routing summary to Orchestrator (100-200 tokens); full findings stay in the output artifact.
 Guardrails: Max Agent Hops = 3. No static dumps. Never read .env contents.
 </delegate>
 
@@ -112,7 +112,7 @@ Parallel: (use parallelization value from .planning/config.json)
 Context: Current working directory. DO NOT share conversation history.
 Instruction: Read `.planning/templates/delegates/mapper-arch.md` for full task instructions. Follow them exactly.
 Output: `.planning/codebase/ARCHITECTURE.md`
-Return: 3-5 sentence summary to Orchestrator.
+Return: Routing summary to Orchestrator (100-200 tokens); full findings stay in the output artifact.
 Guardrails: Max Agent Hops = 3. No static directory dumps. Never read .env contents.
 </delegate>
 
@@ -122,7 +122,7 @@ Parallel: (use parallelization value from .planning/config.json)
 Context: Current working directory. DO NOT share conversation history.
 Instruction: Read `.planning/templates/delegates/mapper-quality.md` for full task instructions. Follow them exactly.
 Output: `.planning/codebase/CONVENTIONS.md`
-Return: 3-5 sentence summary to Orchestrator.
+Return: Routing summary to Orchestrator (100-200 tokens); full findings stay in the output artifact.
 Guardrails: Max Agent Hops = 3. Rules not inventories. Never read .env contents.
 </delegate>
 
@@ -132,7 +132,7 @@ Parallel: (use parallelization value from .planning/config.json)
 Context: Current working directory. DO NOT share conversation history.
 Instruction: Read `.planning/templates/delegates/mapper-concerns.md` for full task instructions. Follow them exactly. Hard stop if secrets found -- report immediately.
 Output: `.planning/codebase/CONCERNS.md`
-Return: 3-5 sentence summary to Orchestrator. If secrets found, STOP and report immediately.
+Return: Routing summary to Orchestrator (100-200 tokens); full findings stay in the output artifact. If secrets found, STOP and report immediately.
 Guardrails: Max Agent Hops = 3. Hard stop on secrets. Never read .env contents.
 </delegate>
 </mapping>

package/distilled/workflows/new-project.md

@@ -232,7 +232,7 @@ Parallel: (use parallelization value from .planning/config.json)
 Context: Project goal: [user's stated goal]. Milestone context: [greenfield|subsequent]. DO NOT share conversation history.
 Instruction: Read `.planning/templates/delegates/researcher-stack.md` for full task instructions. Apply the project goal and milestone context provided above.
 Output: `.planning/research/STACK.md`
-Return: 3-5 sentence summary to Orchestrator; full findings stay in the output artifact.
+Return: Human-read structured summary to Orchestrator (300-500 tokens); full findings stay in the output artifact.
 Guardrails: Max Agent Hops = 3.
 </delegate>
 
@@ -242,7 +242,7 @@ Parallel: (use parallelization value from .planning/config.json)
 Context: Project goal: [user's stated goal]. Milestone context: [greenfield|subsequent]. DO NOT share conversation history.
 Instruction: Read `.planning/templates/delegates/researcher-features.md` for full task instructions. Apply the project goal and milestone context provided above.
 Output: `.planning/research/FEATURES.md`
-Return: 3-5 sentence summary to Orchestrator; full findings stay in the output artifact.
+Return: Human-read structured summary to Orchestrator (300-500 tokens); full findings stay in the output artifact.
 Guardrails: Max Agent Hops = 3.
 </delegate>
 
@@ -252,7 +252,7 @@ Parallel: (use parallelization value from .planning/config.json)
 Context: Project goal: [user's stated goal]. Milestone context: [greenfield|subsequent]. DO NOT share conversation history.
 Instruction: Read `.planning/templates/delegates/researcher-architecture.md` for full task instructions. Apply the project goal and milestone context provided above.
 Output: `.planning/research/ARCHITECTURE.md`
-Return: 3-5 sentence summary to Orchestrator; full findings stay in the output artifact.
+Return: Human-read structured summary to Orchestrator (300-500 tokens); full findings stay in the output artifact.
 Guardrails: Max Agent Hops = 3.
 </delegate>
 
@@ -262,14 +262,14 @@ Parallel: (use parallelization value from .planning/config.json)
 Context: Project goal: [user's stated goal]. Milestone context: [greenfield|subsequent]. DO NOT share conversation history.
 Instruction: Read `.planning/templates/delegates/researcher-pitfalls.md` for full task instructions. Apply the project goal and milestone context provided above.
 Output: `.planning/research/PITFALLS.md`
-Return: 3-5 sentence summary to Orchestrator; full findings stay in the output artifact.
+Return: Human-read structured summary to Orchestrator (300-500 tokens); full findings stay in the output artifact.
 Guardrails: Max Agent Hops = 3.
 </delegate>
 
 **After all 4 researchers complete**, synthesize based on `researchDepth`:
 
 **If `researchDepth: "fast"`:** Synthesize inline.
-You hold 4 x 3-5 sentence summaries. Write `.planning/research/SUMMARY.md` directly using `.planning/templates/research/summary.md`. Cross-reference the summaries. Do NOT spawn another agent.
+You hold 4 human-read structured summaries. Write `.planning/research/SUMMARY.md` directly using `.planning/templates/research/summary.md`. Cross-reference the summaries. Do NOT spawn another agent.
 
 **If `researchDepth: "balanced"` or `"deep"`:** Spawn synthesizer to read the full research files.
 
@@ -279,11 +279,11 @@ Parallel: false
 Context: Researcher summaries returned above. DO NOT share conversation history.
 Instruction: Read `.planning/templates/delegates/researcher-synthesizer.md` for full task instructions.
 Output: `.planning/research/SUMMARY.md`
-Return: 5-7 bullet key findings to Orchestrator; full synthesis stays in the output artifact.
+Return: Agent-mediated structured summary to Orchestrator (500-800 tokens); full synthesis stays in the output artifact.
 Guardrails: Max Agent Hops = 2. Do not do new research — synthesize only.
 </delegate>
 
-*Why the split:* The synthesizer reads the 4 full research files and cross-references specific data points (build order constraints, pitfall-to-phase mappings, feature-architecture conflicts) that 3-5 sentence summaries omit. This depth matters for `balanced`/`deep` runs where the roadmapper needs rich "Implications for Roadmap." For `fast` runs, orchestrator inline synthesis is the acceptable trade-off.
+*Why the split:* The synthesizer reads the 4 full research files and cross-references specific data points (build order constraints, pitfall-to-phase mappings, feature-architecture conflicts) that returned summaries omit. This depth matters for `balanced`/`deep` runs where the roadmapper needs rich "Implications for Roadmap." For `fast` runs, orchestrator inline synthesis is the acceptable trade-off.
 
 Display key findings before moving to spec creation.
 
@@ -345,7 +345,7 @@ Do NOT proceed to roadmap creation until the developer explicitly approves.
 
 <roadmap_creation>
 After `SPEC.md` is approved, you must create `ROADMAP.md`.
-Since you are an Orchestrator with fresh context, you DO NOT need to spawn a subagent for this—write it yourself directly, retaining full thoroughness.
+Since you are an Orchestrator with fresh context, you DO NOT need to spawn a subagent for this; write it yourself directly, retaining full thoroughness. Research and synthesis delegation above are artifact-backed inputs; roadmap creation remains direct and sequential.
 
 Break `SPEC.md` requirements into executable phases:
 

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
@@ -436,14 +443,14 @@ Run the approach explorer.
 
 ### Running the Approach Explorer
 **Primary path — inline conversation with research subagents:**
-The conversation with the user runs inline in the main context. For each technical gray area, a read-only research subagent is spawned to isolate heavy codebase and documentation reads, returning only compressed summaries.
+The conversation with the user runs inline in the main context. For each technical gray area, a read-only research subagent is spawned to isolate heavy codebase and documentation reads, returning only compressed summaries while full detail stays out of the orchestrator context.
 
 1. Load context: read ONLY locked decisions from `.planning/SPEC.md` and the target phase goal/requirements from `.planning/ROADMAP.md`.
 
 2. Identify 3-4 domain-specific gray areas. Classify each as **taste** (preference, no research needed), **technical** (trade-offs, research first), or **hybrid** (both).
 
 3. For each **technical or hybrid** gray area, spawn a read-only research subagent.
-   Use the prompt template from `.planning/templates/roles/approach-explorer.md` (`<research_subagent_prompt>` section), substituting the gray area name, classification, phase context, and relevant codebase files. Each subagent returns a structured summary under 1000 tokens.
+   Use the prompt template from `.planning/templates/roles/approach-explorer.md` (`<research_subagent_prompt>` section), substituting the gray area name, classification, phase context, and relevant codebase files. Each subagent returns a structured summary and does not write implementation artifacts.
 
 4. Present each gray area to the user individually:
    - For taste areas: ask directly
@@ -488,7 +495,7 @@ The approach explorer's full role contract is at `.planning/templates/roles/appr
 
 <plan_check_orchestration>
 ### How Plan Checking Works
-After the planner produces a draft plan, an independent checker reviews it in fresh context. The checker does not inherit the planner's hidden reasoning; it treats the plan as an untrusted draft.
+After the planner produces a draft plan, an independent checker reviews it in fresh context. The checker does not inherit the planner's hidden reasoning; it treats the plan as an untrusted draft and returns a structured summary of findings rather than editing the plan directly.
 
 ### What The Checker Verifies
 1. `requirement_coverage` - every phase requirement is covered by at least one concrete task
@@ -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. 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.2",
+  "version": "0.20.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": {