# DSH Visual Acceptance V0.1 PRD

> Status: product authority. `0.1.2-beta.1` is published as a GitHub Pre-release for installation and real-usage learning. It is not stable or marketplace-release approval.
> Date: 2026-08-27
> Scope: DeepSeek Harness session-level, local Web-prototype acceptance.  
> Evidence: [spike report](spike-report.md) · [architecture](architecture.en.md) · [adversarial review](adversarial-review.md) · [first-slice acceptance](first-slice-acceptance.en.md)

> This is the English release companion to [the Chinese PRD](prd-v0.1.md). Both documents describe the same requirements and release boundary; when a maintenance edit would make them disagree, update both in the same change.

## Release summary: what it is

**DSH Visual Acceptance is a local-first workbench for accepting and retesting Web prototypes.**

It serves people who use DSH or Codex to generate or change local Web pages. After an Agent says “done”, the person declares pages, viewports, themes, and states; runs a real browser check; retains screenshots and runtime facts; decides which candidates become Issues and whether a change is allowed; then retests under the same Matrix.

It is not a general vision-QA tool, automatic image/code editor, or visual score. The system produces browser facts and candidate relations. A person decides whether something is an Issue, whether a change is allowed, and whether it is resolved.

```text
Local page / localhost
  → declared acceptance Matrix
  → browser facts + screenshots
  → Finding Candidate
  → human Issue / Decision
  → copy read-only change package to Agent
  → original-Matrix Retest
  → human confirms resolved, unresolved, or regressed
```

### What the current Beta can do

- Check localhost or HTML inside the current DSH session workspace; it refuses public URLs.
- Use Quick, Standard, readable-CSS breakpoint, or up to eight Custom Checkpoints. It collects Ready, runtime failures, responsive quality facts, and content-validated PNG evidence.
- Store abnormal facts and unreached states as Finding Candidates, rather than automatically announcing a product defect.
- Let a person explicitly create project-level Issues, append Decisions, and create copyable local Markdown/JSON change packages only after `approved-fix`.
- Create a Retest by copying an immutable baseline Matrix. The system offers candidate relations; only a human can write `resolved`.
- Cancel active work and release browser, routes, and listeners when the plugin closes.

### What the current Beta does not promise

- Reference-design comparison, OCR, visual grounding, VLM inference, or AI-template-feel judgement. Retest Pixel Diff records same-Matrix change Candidates only.
- Automatic page discovery, third-party site operation, reproduction of undeclared interaction states, or public-URL testing.
- Automatic project edits or automatic sending of a change package to a DSH/Codex Agent.
- A visual-pass or deliverable claim from `reached`, a successful screenshot, or zero browser signals.
- A completed five-project pilot, subjective-visual-judgement evaluation, or full DSH Desktop compatibility.

### Minimum user result

Every Run answers four acceptance questions: **is the object correct; is the scope covered; what is the impact; who decides next?**

`Ready reached` means only the declared condition was met. A `Finding Candidate` means browser evidence deserves review. `Issue`, `approved-fix`, and `resolved` each require user action and traceable history.

## 0. Current implementation boundary

`0.1.1-closed-loop-beta` validates the deterministic foundation and minimum human loop; it is not full PRD completion.

| Capability | Status | Current evidence |
|---|---|---|
| Session-level `conversation.view` workbench | Implemented and exercised | Non-empty real DSH Web session |
| Manual Target / Matrix | Implemented and exercised | localhost, desktop, and 390px checkpoints |
| Browser facts and screenshots | Implemented and exercised | 2/2 Ready reached; observed state aligned; signals expandable |
| Workspace Run storage | Implemented and exercised | Atomic manifests; `0700` directory; `0600` manifest/PNG |
| Cancellation and cleanup | Implemented and exercised | `cancelled`, Host `disposed`, no acceptance Chrome left |
| Finding Candidate and project Issue | Implemented and exercised | Fixture font Candidate explicitly promoted; manual visual Issue API/UI exists |
| Decision history and change package | Implemented and exercised | Append-only `approved-fix`; local Markdown/JSON copy; no Agent send |
| Original-Matrix Retest and human confirmation | Implemented and exercised | Retest reused baseline Matrix; `still-detected` human-confirmed `unresolved` |
| Merge / split / reject | Implemented; automated tests | API/project storage covered, not a real-project pilot |
| Responsive plans and breakpoint discovery | Implemented and exercised | Quick/Standard/Breakpoint/Custom checked in DSH Web; fixture found `640px / 900px` with complete coverage |
| Deterministic quality and state recipes | Implemented; focused Spike | Bounded quality rules, screenshot validation, six controlled actions; not WCAG or real-device proof |
| Retest Pixel Diff | Implemented; focused Spike | Original-Matrix Baseline/Current/Diff only; change remains a Candidate |
| Reference-design comparison | Not implemented | Reference identity, alignment, and visual judgement remain target design |
| Provider image inference | Not implemented | CLI probing and contract spike only |
| Automatic Agent session injection | Explicitly deferred | User copies local package |

Functional requirements and acceptance criteria below remain V0.1 goals. A capability not marked implemented above must not be described in the README, demo, or release notes as present capability.

### 0.1.2 increment: Responsive Acceptance (implemented source candidate)

The next increment provides four explicit coverage plans instead of adding a wall of size toggles:

| Plan | Matrix | Job |
|---|---|---|
| Quick | `390×844` + `1280×800`, primary theme | Low-cost check after each Agent edit |
| Standard | Six layout viewports in the primary theme plus secondary-theme anchors at `390×844` and `1280×800`; eight total | Routine pre-release coverage |
| Page breakpoints | Discover readable CSS media queries and inspect both sides of selected breakpoints; eight maximum | Breakpoint-transition defects |
| Custom | One to eight user-declared Checkpoints | Special pages, states, and sizes |

The standard viewports are `360×800 / 390×844 / 768×1024 / 1024×768 / 1280×800 / 1440×900`. They are deterministic CSS layout viewports, not real devices. Without UA, touch, DPR, mobile Safari, or real-device evidence, the product must not claim device compatibility.

This increment also adds bounded deterministic quality signals, same-Matrix screenshot comparison for Retest, and safe state recipes using only `click / fill / select / press / wait / assert-ready`. Screenshot changes remain Candidates; arbitrary JavaScript and automatic resolution remain forbidden.

## 0.1.2 business and interaction model

```mermaid
flowchart LR
    U[AI product builder] --> W[DSH Visual Acceptance]
    W --> C[Coverage plan and immutable Matrix]
    C --> R[Local Chrome Runner]
    R --> E[Runtime facts / responsive screenshots / Diff candidates]
    E --> H[Human Issue and Decision]
    H --> P[Read-only change package]
    P --> A[DSH or Codex Agent]
    A --> T[Original-Matrix Retest]
    T --> H
```

```mermaid
classDiagram
    class CoveragePreset { +id +version +layoutViewports }
    class BreakpointDiscovery { +source +widths +completeness }
    class Checkpoint { +path +state +viewport +theme +actions +ready }
    class AcceptanceRun { +runId +matrixFingerprint +runKind }
    class RuntimeEvidence { +facts +screenshot +visualComparison }
    class Issue { +lifecycle +decisionHistory +verificationHistory }
    CoveragePreset "0..1" --> "1..8" Checkpoint : creates temporary Matrix
    BreakpointDiscovery "0..1" --> "1..8" Checkpoint : suggests temporary Matrix
    AcceptanceRun "1" *-- "1..8" Checkpoint : persists snapshot
    AcceptanceRun "1" *-- "0..8" RuntimeEvidence : persists
    Issue "0..*" --> "1..*" RuntimeEvidence : references
```

Coverage choice and breakpoint suggestions are temporary. Runs, Evidence, Issues, Decisions, and Verifications are workspace-persisted business entities; this is not a database ER diagram.

```mermaid
sequenceDiagram
    actor U as User
    participant W as Workbench
    participant B as Local browser
    participant A as Agent
    U->>W: Enter Target and choose coverage
    opt Page-breakpoint plan
      W->>B: Read-only media-query discovery
      B-->>W: Widths and completeness
      W-->>U: Review exact Matrix
    end
    U->>W: Run confirmed Matrix
    W->>B: Replay state recipe per Checkpoint
    alt Cancelled, unreached, or invalid evidence
      B-->>W: Explicit failure evidence
      W-->>U: Recoverable result; no pass claim
    else Completed
      B-->>W: Facts, screenshot, optional Diff
      W-->>U: Candidates and responsive overview
      U->>W: Create Issue and approve a fix
      W-->>U: Copy read-only package
      U->>A: User hands package to Agent
      A-->>U: Change completed
      U->>W: Original-Matrix Retest
      W-->>U: Candidate relations
      U->>W: Human verification
    end
```

```mermaid
flowchart TD
    A[Open Visual Acceptance] --> B[Enter local Target]
    B --> C{Coverage plan}
    C -->|Quick| D[2 Checkpoints]
    C -->|Standard| E[8 Checkpoints]
    C -->|Page breakpoints| F[Discover and confirm both sides]
    C -->|Custom| G[Declare page, state, recipe, and Ready]
    D --> H[Run confirmed Matrix]
    E --> H
    F --> H
    G --> H
    H --> I{Result}
    I -->|Cancelled / failed / unreached| C
    I -->|Completed| J[Responsive evidence overview]
    J --> K{Track a finding?}
    K -->|No| L[Keep Run]
    K -->|Yes| M[Issue and Decision]
    M --> N[User-managed Agent change]
    N --> O[Original-Matrix Retest]
    O --> P[Human verification]
```

## 1. Product conclusion

V0.1 delivers a retestable acceptance loop, not another generic vision toolkit:

```text
confirm object → declare Matrix → reach state → collect facts/candidates
→ human decision → copy approved change package → user gives it to Agent
→ retest under the same conditions
```

## 2. Problem, AI role, users, and goals

### Problem

After AI generates a page, a user must manually assemble browser checks, screenshot comparison, aesthetic judgement, business-state checks, and change history. Without a shared object and history, “generated” is mistaken for “deliverable”.

### Why not use AI for everything

Browser/rule evidence must answer page opening, resource and font loading, console/request failures, horizontal overflow, and URL/selector/state reachability. AI may only create candidate judgements where rules are incomplete: hierarchy, density, visual naturalness/template feel, or possibly missing product states. It is never final arbiter and cannot overwrite deterministic failure.

### Target user and JTBD

Target users are solo builders, AI product managers, and small-team leads using DSH to generate or change local Web products.

> When an Agent finishes a page change, I need to find evidence-backed issues across specified pages, viewports, themes, and states; decide which changes are allowed; and confirm the change introduced no regression.

### Objectives

- **O1:** Every conclusion traces to Target, Checkpoint, and Evidence.
- **O2:** Runtime facts, visual facts, experience candidates, and product candidates remain distinct.
- **O3:** Humans retain final control over allowed changes, risk acceptance, and rejection.
- **O4:** The same Matrix can replay and an Issue can retest.
- **O5:** Runtime acceptance works when no visual Provider exists.

### Non-goals

General image QA/generation/video acceptance; automatic discovery of every page/state; unconfirmed project modification; automatic aesthetic verdicts; a single composite score; CI/CD, collaboration, and cloud dashboards; native app/device testing; Codex Skill; and tight coupling to the user's other DSH plugins.

## 3. Core concepts and information architecture

- **Acceptance Project:** acceptance configuration and history for one local project.
- **Acceptance Run:** immutable execution with Target/environment/Matrix snapshot, evidence, and Issue outcome.
- **Checkpoint:** one page × state × viewport × theme with a Ready condition.
- **Finding Candidate:** a detectable signal that needs a person before it becomes an Issue.
- **Issue:** a trackable problem; never equivalent to model output.
- **Decision:** append-only human choice: `approved-fix`, `accepted-risk`, `dismissed`, or `deferred`.
- **Retest relation:** an inspectable relationship between baseline and current result, not a final verdict.

The full V0.1 information architecture has object/scope, runtime state, issue/decision, evidence detail, and retest relations. The current Beta compresses these into one session-level result area, avoiding a second DSH page and keeping filters/crops/Providers deferred.

## 4. Primary flow

1. Open **Visual Acceptance** in the current DSH session.
2. Enter local HTML or localhost; select Quick coverage or add manual Checkpoints.
3. Confirm Target and Matrix; the system validates Ready conditions. Reference images and build fingerprint are later scope.
4. The Host starts a one-off Runner, sets viewport/theme per Checkpoint, waits for Ready, and collects facts/screenshots.
5. Deterministic signals become Candidates. Visual Provider calls are deferred.
6. For each issue, answer: object correct? scope covered? impact? who decides?
7. A human chooses `approved-fix`, `accepted-risk`, `dismissed`, or `deferred`.
8. Only an approved Issue yields a local read-only Markdown/JSON package. The user copies it to an Agent.
9. Replay the same Matrix after the change. Show `new-candidate`, `still-detected`, `possibly-resolved`, `regressed`, `not-verifiable`, or `needs-human-review`; only human confirmation writes `resolved`.

## 5. Functional requirements

### Target and Matrix

- **FR-001** Create a workspace-local Acceptance Project.
- **FR-002** Confirm reference image, target address, and target fingerprint when those capabilities are available.
- **FR-003** Manually declare page, state, viewport, theme, and Ready condition; a non-default state needs a discriminating Ready selector/text.
- **FR-004** Never count undeclared pages as coverage.
- **FR-005** Record Ready failure as `unreached`, never passing.
- **FR-006** Provide versioned Quick, Standard, Page-breakpoint, and Custom coverage plans and list the final Checkpoints before execution.
- **FR-007** Standard coverage fits six layout viewports and two secondary-theme anchors into the eight-Checkpoint cap without a hidden Cartesian product.
- **FR-008** Page-breakpoint coverage records source, discovered widths, and completeness; unreadable stylesheets produce an explicit partial result.
- **FR-009** A coverage plan only generates a pre-run Matrix. Once created, a Run persists exact Checkpoints and cannot change when Presets evolve.

### Deterministic checks

- **FR-010** Record browser, OS, requested viewport, layout/visual viewport, and theme.
- **FR-011** Collect console errors and uncaught exceptions.
- **FR-012** Collect failed requests and HTTP 4xx/5xx.
- **FR-013** Record image load state and `naturalWidth`.
- **FR-014** Calculate horizontal overflow relative to the requested CSS viewport.
- **FR-015** Produce a screenshot for every executed Checkpoint.
- **FR-016** Validate screenshot format, dimensions, and content; retry a blank-like capture once, then create an explicit Candidate if it remains blank rather than silently accepting it.
- **FR-017** Record Viewport Meta and bounded accessibility-rule signals while stating that automated rules are not a complete accessibility audit.
- **FR-018** Detect visible interactive elements that cross horizontal viewport bounds; normal vertical scrolling is not a finding.
- **FR-019** Present multi-viewport results per Checkpoint and optionally cluster Candidates by rule; clustering cannot merge formal Issues automatically.

### Providers and AI judgement

- **FR-020** Probe Provider availability and version before use.
- **FR-021** Provider calls are cancellable and time-bounded.
- **FR-022** Provider output carries source, version, and capability declaration.
- **FR-023** Runtime facts work without a Provider.
- **FR-024** AI experience/product judgement defaults to `needs-human-review`.
- **FR-025** AI judgement cannot overwrite deterministic browser facts.
- **FR-026** A Retest compares same-size baseline/current screenshots and records algorithm, threshold, changed pixels, and Diff evidence.
- **FR-027** Missing baselines, invalid evidence, dimension mismatch, or incompatible environments produce `not-comparable`, never “visually resolved”.
- **FR-028** Visual Diff can only create a Finding Candidate; formal Issue, baseline acceptance, and resolution remain human actions.
- **FR-029** Reference-design comparison and historical regression baselines are distinct types; this increment implements only original-Matrix Retest comparison.

### Issues, evidence, handoff, and retest

- **FR-030** Issue includes ID, Target, Finding, Evidence, Impact, Suggestion, and Decision Owner.
- **FR-031** Store lifecycle, decision, and verification separately.
- **FR-032** Generate an Issue-candidate fingerprint.
- **FR-033** Users can correct merge, split, and regression relations.
- **FR-034** A later Run cannot overwrite a human Decision.
- **FR-040** Only `approved-fix` Issues enter a change package.
- **FR-041** Package states allowed and forbidden modification scope.
- **FR-042** The system never edits the target project directly.
- **FR-043** Users can create a Retest using the original Matrix.
- **FR-044** Retest distinguishes new, still detected, possibly resolved, regressed, not verifiable, and needs human review; only a human writes `resolved`.
- **FR-045** A Checkpoint may persist a bounded state recipe using `click / fill / select / press / wait / assert-ready`.
- **FR-046** A state recipe cannot run arbitrary JavaScript, Shell, cross-origin navigation, file upload, or credential access.
- **FR-047** Every action records order, result, and failure reason; action failure makes the Checkpoint `unreached` instead of fabricating state reproduction.
- **FR-048** `fill` and `select` values are user-declared test data and are redacted or represented only as value presence in change packages.
- **FR-049** State recipes participate in Checkpoint Key and Matrix Fingerprint; Retest replays the original recipe.

### Local data and lifecycle

- **FR-050** Runs, Issues, Decisions, and Evidence default to local workspace storage.
- **FR-051** Closing the plugin releases Chrome, ports, listeners, and temporary directories.
- **FR-052** Disabling the plugin cannot affect native DSH sessions.
- **FR-053** Data schemas are versioned and support future migration.

## 6. Uncertainty, safety, fallback, and performance

| Type | UI language | Auto-verdict allowed? |
|---|---|---|
| Runtime fact | “Browser check” + raw value | Yes |
| Visual fact | “Diff/grounding evidence” + Provider | Depends on capability |
| Experience judgement | “AI candidate” + reason/uncertainty | No |
| Product judgement | “Product confirmation needed” + missing-state evidence | No |

Do not present uncalibrated percentage confidence. When a Provider lacks a reliable interval, show source, evidence sufficiency, and `needs-human-review`.

The product must never edit a project without confirmation, describe a Provider capability as an executed fact, label `unreached` as pass, mislabel static scanning as browser verification, upload page/Cookie/token/input data, hide individual failures behind a score, or fabricate results after Provider failure. All Runs/screenshots/Decisions remain local by default. Any future remote model must disclose provider and exact image scope for every call.

| Failure | Required behavior |
|---|---|
| No Provider | Skip visual/AI layer; continue runtime facts |
| Provider timeout | `unavailable`; do not retry a paid call |
| State not reached | `unreached` with failure evidence |
| Blank screenshot | Retry once; otherwise block visual conclusion for the Checkpoint |
| Chrome cannot start | Fail the Run; do not pretend a static scan is a browser check |
| Issue relationship uncertain | Create a candidate relation for human confirmation |
| DSH Client incompatible | Disable UI Adapter; preserve local data; do not affect host session |

Performance target: p95 ≤ 90 seconds for four local Checkpoints; default Ready timeout 10 seconds; maximum eight Checkpoints per Run. Fixture runs around 20–23 seconds for four Checkpoints/two rounds are not real-project performance evidence. Remote paid inference remains off by default; proposed AI analysis target is p95 ≤ 30 seconds, then degrade on timeout.

## 7. Quality gates, rollout, and acceptance

### Deterministic gate

- 0 missed known console/request/image/overflow problems in fixed fixtures;
- 0 false positives for normal state;
- reproducible runtime facts for repeated same-environment runs;
- `unreached` recognition 100%;
- invalid screenshots fail explicitly.

### Issue/retest gate

- same-issue ID retention 100% in controlled corpus;
- human Decision retention 100%;
- every automatic relation in real pilots is correctable by a person;
- low automatic-matching accuracy never justifies overwriting history.

### AI-candidate gate

Before publishing subjective AI judgement, use a blind set of at least 20 fixed examples: P1/P2 human-kept precision ≥80%, complete evidence citation 100%, deterministic-fact conflict 0%, and core findings consistent ≥80% across three identical inputs. Otherwise publish runtime facts and manual Issues only.

### Rollout

1. **Phase 0, completed:** real DSH Web fixture loop Run → Candidate → Issue → Decision → change package → original-Matrix Retest → human confirmation. Still add Desktop light/dark/reopen checks and 20 AI-eval samples.
2. **Phase 1:** five real local projects, at least two retests each; local HTML/localhost only; remote Provider off; collect human corrections every Run.
3. **Phase 2:** limited release after deterministic, Issue, and client-lifecycle gates; enable one validated visual Provider and retain an AI kill switch.

Rollback if the plugin affects native DSH session load, Chrome/ports cannot release, automatic change bypasses confirmation, `unreached`/Provider failure is reported as pass, or project content uploads without confirmation.

### V0.1 acceptance criteria

- **AC-001 Complete loop:** for a local project with default/empty/error states, two Runs show Matrix coverage, evidence, human decisions, and new/unresolved/resolved/regressed categories.
- **AC-002 Layer separation:** browser facts and AI Candidates have distinct source labels; browser acceptance works with Provider off.
- **AC-003 Human control:** unapproved Issues cannot create packages; accepted risk and dismissed survive retest; packages can copy only, never auto-send.
- **AC-004 Lifecycle:** install/close/disable/reopen does not create duplicate Views, Chrome, ports, or listeners.
- **AC-005 Claim boundary:** unreached state, invalid screenshot, or Provider failure appears as failure—never “passed”.
- **AC-006 Responsive coverage:** Quick produces two and Standard exactly eight Checkpoints. Page-breakpoint mode shows discovery source/completeness and exact boundary-side widths. Preset updates never mutate old Runs.
- **AC-007 Deterministic quality:** controlled missing viewport meta, image alt, form label, button name, duplicate ID, and horizontally offscreen control cases produce traceable Candidates without claiming complete WCAG conformance.
- **AC-008 Visual comparison:** same-Matrix Retest stores baseline/current/Diff evidence; identical screenshots report zero change, controlled changes create Candidates, and non-comparable inputs explicitly degrade. Visual changes never auto-create Issues or write `resolved`.
- **AC-009 State recipes:** a fixture reaches declared state through the allowed actions; invalid selectors, failed actions, cancellation, and timeout retain failure evidence and never claim reproduction.

## 8. Pre-release decisions still open

1. Keep the real Client surface as `conversation.view` only, or later add a session-header shortcut?
2. Select the first real visual Provider: ModLens, Agent Vision Toolkit CLI, or another implementation?
3. Should the workspace data directory be added to a target project's `.gitignore` by default?
4. Keep remote URLs deferred for V0.1 (current recommendation), or add them later with an explicit Host allowlist?
5. Which real pages form the 20-example AI Candidate evaluation set?