@ztothez/design-engineering 2.0.0

package/knowledge-base/maintained/architecture/quality-attributes-and-evaluation.md

@@ -0,0 +1,35 @@
+# Quality Attributes And Architecture Evaluation
+
+Use this lightweight Architecture Tradeoff Analysis Method, or ATAM, workflow to build a utility tree and identify sensitivity points and trade-off points from measurable scenarios.
+
+## Step 1: Define Scenarios
+
+Write each consequential quality requirement as:
+
+```text
+source -> stimulus -> environment -> affected artifact -> response -> measurable result
+```
+
+Cover normal operation, a likely change, and a stress or failure condition. Prefer observable measures such as completion rate, response latency, recovery time, changed modules, supported viewport, or evidence requirement.
+
+## Step 2: Build A Utility Tree
+
+Group scenarios under usability, accessibility, modifiability, reliability, performance, security, portability, and variability. Rank business importance and implementation risk independently. Evaluate high-importance or high-risk scenarios first.
+
+## Step 3: Inspect Decisions
+
+For each scenario, identify:
+
+- The decision that enables or threatens it.
+- Sensitivity points where a small change strongly affects the result.
+- Trade-off points where one decision improves one attribute while weakening another.
+- Assumptions that lack current evidence.
+- Risks, non-risks, and required follow-up evidence.
+
+## Step 4: Record The Decision
+
+Record context, selected option, alternatives, rationale, affected attributes, constraints, evidence, reversal trigger, and migration cost. Do not use an architecture decision record to justify an option after the fact.
+
+## Step 5: Verify
+
+Trace scenarios through logical components, source packages, runtime processes, deployment boundaries, and representative user journeys. Static structure cannot prove runtime recovery, accessibility, usability, or performance; pair each claim with the appropriate evidence method.

package/knowledge-base/maintained/product-patterns/MASTER.md

@@ -0,0 +1,10 @@
+# Maintained Product Patterns
+
+These independently authored patterns turn the task models in the root skill into implementation-ready workspace and dashboard structures. Use them as bounded defaults, then adapt them to current product entities, evidence, risk, and stack conventions.
+
+| Product surface | Module |
+|---|---|
+| AI-assisted analysis, generation, review, or agent work | `ai-workspaces.md` |
+| Pipelines, records, jobs, obligations, media, or document operations | `operational-dashboards.md` |
+
+Every pattern requires explicit sources of truth, empty and failure states, keyboard operation, responsive recomposition, and honest evidence. Remove a region when the task does not need it; do not preserve a template shape for visual symmetry.

package/knowledge-base/maintained/product-patterns/ai-workspaces.md

@@ -0,0 +1,26 @@
+# AI Workspace Patterns
+
+## Task Model
+
+Define the practitioner, input, configuration, run boundary, generated result, evidence, review decision, and export or handoff. Separate model output from validated product state.
+
+## Workspace Structure
+
+1. Use a persistent product shell with visible workspace and environment context.
+2. Put input, configuration, and the primary run action in one owning region.
+3. Show results beside input on wide screens when comparison is frequent; use explicit Input and Results views on narrow screens.
+4. Keep findings, evidence, confidence, limitations, and approval state inspectable without hiding them behind decorative summaries.
+5. Preserve input and completed evidence across retryable failures.
+
+## Required States
+
+- Empty: explain required input and available sources without fake examples presented as current results.
+- Validating: identify invalid or unsupported input before an expensive run.
+- Running: announce progress, prevent duplicate submission, and preserve cancellation semantics.
+- Partial: retain usable output and identify missing stages or sources.
+- Error: show cause, preserved state, retry, and safe fallback.
+- Complete: connect each consequential result to evidence and available next actions.
+
+## Trust Contract
+
+Label generated, retrieved, inferred, validated, rejected, and human-approved information distinctly. Do not fabricate confidence, citations, savings, accuracy, latency, or completion. Require human approval where the product decision has legal, financial, safety, employment, security, or publication consequences.

package/knowledge-base/maintained/product-patterns/operational-dashboards.md

@@ -0,0 +1,22 @@
+# Operational Dashboard Patterns
+
+## Start With Work, Not Metrics
+
+Identify the highest-frequency decision and the records, jobs, or obligations needed to make it. The first viewport should expose current scope, exceptions, and the next action. Metrics summarize current evidence; they do not replace the work surface.
+
+## Shared Structure
+
+1. Scope header: period, workspace, environment, destination, or queue.
+2. Evidence-backed summary: a small set of definitions with current source and time context.
+3. Work controls: search, filters, sorting, saved views, and selection count where needed.
+4. Main records surface: stable columns, textual status, ownership, timestamps, and row actions.
+5. Detail or inspector: history, evidence, validation, and recovery actions.
+6. Lifecycle actions: import, export, backup, migration, reset, archive, or delete only when the product owns those states.
+
+## Operational States
+
+Use waiting, active, blocked, failed, completed, overdue, partial, and cancelled only when the domain defines them. Every status needs text and a current source of truth. Preserve user input and filters after recoverable failures. Explain destination, overwrite, retention, and external processing before consequential actions.
+
+## Responsive Behavior
+
+Recompose dense tables into prioritized records or horizontal regions with explicit affordances. Keep filters and bulk actions reachable, preserve selected scope, and avoid competing page-level scroll containers. Verify long identifiers, localized labels, 200 percent reflow, text resizing, and touch targets.

package/knowledge-base/provenance.yaml

@@ -0,0 +1,196 @@
+version: "1.0"
+policy:
+  coverage: exact-distribution
+  approvedStatuses: [approved]
+  distributionLicense: ISC
+sources:
+  - id: ztothez-maintained
+    origin: original
+    owner: ZtotheZ
+    license: ISC
+    evidence: Git history and repository-authored source files.
+    reuse: Approved for distribution as part of ZtotheZ Design Engineering.
+  - id: aegisops-owner-evidence
+    origin: user-owned
+    owner: ZtotheZ
+    license: owner-authorized benchmark use
+    evidence: knowledge-base/benchmarks/aegisops/SOURCE-EVIDENCE.md
+    reuse: Approved benchmark contract, summaries, journeys, and evidence templates.
+  - id: scenestart-owner-evidence
+    origin: user-owned
+    owner: ZtotheZ
+    license: owner-authorized benchmark use
+    evidence: knowledge-base/benchmarks/scenestart/SOURCE-EVIDENCE.md
+    reuse: Approved benchmark contract, summaries, journeys, and evidence templates.
+  - id: azure-optimizer-owner-evidence
+    origin: user-owned
+    owner: ZtotheZ
+    license: owner-authorized benchmark use
+    evidence: knowledge-base/benchmarks/azure-optimizer/SOURCE-EVIDENCE.md
+    reuse: Approved comparison contract, bounded source summary, journeys, acceptance criteria, and anti-patterns.
+  - id: ztothez-corpus
+    origin: original
+    owner: ZtotheZ
+    license: ISC
+    evidence: knowledge-base/benchmarks/corpus/PROVENANCE.md
+    reuse: Synthetic cases and corpus contracts are approved for distribution.
+artifactSets:
+  - id: maintained-core
+    source: ztothez-maintained
+    status: approved
+    reviewedBy: ZtotheZ
+    reviewedAt: "2026-08-26T00:00:00+03:00"
+    transformation: Independently authored and maintained from project requirements, owner evidence, and publicly identified standards without copied reference-product implementation.
+    paths:
+      - README.md
+      - ROADMAP.md
+      - SKILL.md
+      - V2-ROADMAP.md
+      - V3-ROADMAP.md
+      - V4-ROADMAP.md
+      - clean-room-ux-design-spec.md
+      - docs/installation.md
+      - knowledge-base/INDEX.md
+      - knowledge-base/dependencies.yaml
+      - knowledge-base/provenance.yaml
+      - knowledge-base/retrieval-scope.yaml
+      - knowledge-base/design-intelligence/MASTER.md
+      - knowledge-base/design-intelligence/asset-generation.md
+      - knowledge-base/design-intelligence/brand-systems.md
+      - knowledge-base/design-intelligence/closed-loop-repair.md
+      - knowledge-base/design-intelligence/design-deliverable.schema.yaml
+      - knowledge-base/design-intelligence/design-deliverable.template.yaml
+      - knowledge-base/design-intelligence/design-plan.md
+      - knowledge-base/design-intelligence/design-plan.schema.yaml
+      - knowledge-base/design-intelligence/figma-production.md
+      - knowledge-base/design-intelligence/generation-adapter.md
+      - knowledge-base/design-intelligence/generation-adapter.schema.yaml
+      - knowledge-base/design-intelligence/iconography.md
+      - knowledge-base/design-intelligence/information-design.md
+      - knowledge-base/design-intelligence/information-design.schema.yaml
+      - knowledge-base/design-intelligence/information-design.template.yaml
+      - knowledge-base/design-intelligence/interaction-recovery-verification.md
+      - knowledge-base/design-intelligence/interface-trust.md
+      - knowledge-base/design-intelligence/interface-trust.schema.yaml
+      - knowledge-base/design-intelligence/interface-trust.template.yaml
+      - knowledge-base/design-intelligence/licensing-and-provenance.md
+      - knowledge-base/design-intelligence/presentation-design.md
+      - knowledge-base/design-intelligence/product-design-brief.md
+      - knowledge-base/design-intelligence/product-design-brief.schema.yaml
+      - knowledge-base/design-intelligence/product-design-brief.template.yaml
+      - knowledge-base/design-intelligence/repair-request.schema.yaml
+      - knowledge-base/design-intelligence/repair-request.template.yaml
+      - knowledge-base/design-intelligence/visual-accessibility.md
+      - knowledge-base/design-intelligence/visual-polish.md
+      - knowledge-base/maintained/architecture/MASTER.md
+      - knowledge-base/maintained/architecture/component-boundaries.md
+      - knowledge-base/maintained/architecture/product-platforms.md
+      - knowledge-base/maintained/architecture/quality-attributes-and-evaluation.md
+      - knowledge-base/maintained/product-patterns/MASTER.md
+      - knowledge-base/maintained/product-patterns/ai-workspaces.md
+      - knowledge-base/maintained/product-patterns/operational-dashboards.md
+      - knowledge-base/usability-evaluation/HEURISTIC_EVALUATION.md
+      - knowledge-base/usability-evaluation/heuristic-review.schema.yaml
+      - knowledge-base/usability-evaluation/heuristic-review.template.yaml
+      - knowledge-base/benchmarks/interface-quality/README.md
+      - knowledge-base/benchmarks/interface-quality/SOLO-MAINTAINER-TRACK.md
+      - knowledge-base/benchmarks/interface-quality/comparison-methodology.schema.yaml
+      - knowledge-base/benchmarks/interface-quality/comparison-methodology-v1.1.schema.yaml
+      - knowledge-base/benchmarks/interface-quality/comparison-methodology.template.yaml
+      - knowledge-base/benchmarks/interface-quality/evidence/example-runtime-report.json
+      - knowledge-base/benchmarks/interface-quality/review.schema.yaml
+      - knowledge-base/benchmarks/interface-quality/review-session.schema.yaml
+      - knowledge-base/benchmarks/interface-quality/review.template.yaml
+      - knowledge-base/benchmarks/portfolio-corpus/ADAPTERS.md
+      - knowledge-base/benchmarks/portfolio-corpus/PORTFOLIO-RUNNER.md
+      - knowledge-base/benchmarks/portfolio-corpus/PROMOTED-RULES.md
+      - knowledge-base/benchmarks/portfolio-corpus/PRODUCT-TASK-CONTRACTS.md
+      - knowledge-base/benchmarks/portfolio-corpus/archetype-profiles.yaml
+      - knowledge-base/benchmarks/portfolio-corpus/product-task-profile.schema.yaml
+      - knowledge-base/benchmarks/portfolio-corpus/registry.schema.yaml
+      - knowledge-base/benchmarks/portfolio-corpus/registry.template.yaml
+      - knowledge-base/benchmarks/portfolio-corpus/rule-holdout-evaluation.template.json
+      - knowledge-base/benchmarks/portfolio-corpus/rule-promotion-evidence.template.json
+      - knowledge-base/benchmarks/portfolio-corpus/rule-fixtures/component-size-abstention.json
+      - knowledge-base/benchmarks/portfolio-corpus/rule-fixtures/component-size-negative.json
+      - knowledge-base/benchmarks/portfolio-corpus/rule-fixtures/component-size-positive.json
+      - knowledge-base/benchmarks/portfolio-corpus/rule-fixtures/interactive-integrity-abstention.json
+      - knowledge-base/benchmarks/portfolio-corpus/rule-fixtures/interactive-integrity-negative.json
+      - knowledge-base/benchmarks/portfolio-corpus/rule-fixtures/interactive-integrity-positive.json
+      - knowledge-base/benchmarks/portfolio-corpus/rule-fixtures/raw-design-values-abstention.json
+      - knowledge-base/benchmarks/portfolio-corpus/rule-fixtures/raw-design-values-negative.json
+      - knowledge-base/benchmarks/portfolio-corpus/rule-fixtures/raw-design-values-positive.json
+      - knowledge-base/benchmarks/portfolio-corpus/v3-qualification-evidence.template.json
+      - knowledge-base/benchmarks/portfolio-corpus/v3-command-evidence.template.json
+  - id: aegisops-benchmark
+    source: aegisops-owner-evidence
+    status: approved
+    reviewedBy: ZtotheZ
+    reviewedAt: "2026-08-26T00:00:00+03:00"
+    transformation: Owner-authorized product behavior was normalized into project contracts, bounded evidence summaries, journeys, anti-patterns, and review records.
+    paths:
+      - knowledge-base/benchmarks/aegisops/CALIBRATION.md
+      - knowledge-base/benchmarks/aegisops/MANIFEST.md
+      - knowledge-base/benchmarks/aegisops/SOURCE-EVIDENCE.md
+      - knowledge-base/benchmarks/aegisops/acceptance-criteria.md
+      - knowledge-base/benchmarks/aegisops/anti-patterns.md
+      - knowledge-base/benchmarks/aegisops/attestations.template.yaml
+      - knowledge-base/benchmarks/aegisops/attestations.yaml
+      - knowledge-base/benchmarks/aegisops/journeys.json
+      - knowledge-base/benchmarks/aegisops/product-contract.yaml
+  - id: azure-optimizer-benchmark
+    source: azure-optimizer-owner-evidence
+    status: approved
+    reviewedBy: ZtotheZ
+    reviewedAt: "2026-08-26T00:00:00+03:00"
+    transformation: Owner-authorized implementations were normalized into one independently authored comparison task contract without distributing candidate source code.
+    paths:
+      - knowledge-base/benchmarks/azure-optimizer/SOURCE-EVIDENCE.md
+      - knowledge-base/benchmarks/azure-optimizer/V2-IMPLEMENTATION.md
+      - knowledge-base/benchmarks/azure-optimizer/acceptance-criteria.md
+      - knowledge-base/benchmarks/azure-optimizer/anti-patterns.md
+      - knowledge-base/benchmarks/azure-optimizer/journeys.json
+      - knowledge-base/benchmarks/azure-optimizer/product-contract.yaml
+      - knowledge-base/benchmarks/azure-optimizer/v2-journeys.json
+      - knowledge-base/benchmarks/azure-optimizer/v2-human-review-methodology.yaml
+  - id: scenestart-benchmark
+    source: scenestart-owner-evidence
+    status: approved
+    reviewedBy: ZtotheZ
+    reviewedAt: "2026-08-27T11:05:01+03:00"
+    transformation: Owner-authorized product behavior and attributable maintainer review were normalized into project contracts, bounded evidence summaries, journeys, anti-patterns, review templates, and acceptance attestations.
+    paths:
+      - knowledge-base/benchmarks/scenestart/CALIBRATION.md
+      - knowledge-base/benchmarks/scenestart/MANIFEST.md
+      - knowledge-base/benchmarks/scenestart/SOURCE-EVIDENCE.md
+      - knowledge-base/benchmarks/scenestart/acceptance-criteria.md
+      - knowledge-base/benchmarks/scenestart/anti-patterns.md
+      - knowledge-base/benchmarks/scenestart/attestations.template.yaml
+      - knowledge-base/benchmarks/scenestart/attestations.yaml
+      - knowledge-base/benchmarks/scenestart/human-review.md
+      - knowledge-base/benchmarks/scenestart/human-review.template.md
+      - knowledge-base/benchmarks/scenestart/journeys.json
+      - knowledge-base/benchmarks/scenestart/product-contract.yaml
+  - id: corpus-benchmark
+    source: ztothez-corpus
+    status: approved
+    reviewedBy: ZtotheZ
+    reviewedAt: "2026-08-26T00:00:00+03:00"
+    transformation: Independently authored positive and negative behavioral cases with source-specific provenance records and no imported reference implementation.
+    paths:
+      - knowledge-base/benchmarks/corpus/PROVENANCE.md
+      - knowledge-base/benchmarks/corpus/README.md
+      - knowledge-base/benchmarks/corpus/cases/anti-slop-negative/package.json
+      - knowledge-base/benchmarks/corpus/cases/anti-slop-negative/src/FakeDashboard.tsx
+      - knowledge-base/benchmarks/corpus/cases/anti-slop-positive/package.json
+      - knowledge-base/benchmarks/corpus/cases/anti-slop-positive/src/Progress.tsx
+      - knowledge-base/benchmarks/corpus/cases/architecture-negative/package.json
+      - knowledge-base/benchmarks/corpus/cases/architecture-negative/src/OperationsPanel.tsx
+      - knowledge-base/benchmarks/corpus/cases/architecture-positive/package.json
+      - knowledge-base/benchmarks/corpus/cases/architecture-positive/src/Dashboard.tsx
+      - knowledge-base/benchmarks/corpus/cases/architecture-positive/src/theme.css
+      - knowledge-base/benchmarks/corpus/cases/task-incomplete/SOURCE-EVIDENCE.md
+      - knowledge-base/benchmarks/corpus/cases/task-incomplete/journeys.json
+      - knowledge-base/benchmarks/corpus/cases/task-incomplete/product-contract.yaml
+      - knowledge-base/benchmarks/corpus/corpus.schema.yaml
+      - knowledge-base/benchmarks/corpus/corpus.yaml

package/knowledge-base/retrieval-scope.yaml

@@ -0,0 +1,43 @@
+version: "1.0"
+authority: SKILL.md
+categories:
+  skill:
+    label: Authoritative Agent Skill
+    files:
+      - SKILL.md
+  architecture:
+    label: Maintained architecture and design engineering
+    files:
+      - knowledge-base/maintained/architecture/MASTER.md
+      - knowledge-base/maintained/architecture/component-boundaries.md
+      - knowledge-base/maintained/architecture/product-platforms.md
+      - knowledge-base/maintained/architecture/quality-attributes-and-evaluation.md
+  design-intelligence:
+    label: Maintained design intelligence
+    files:
+      - knowledge-base/design-intelligence/MASTER.md
+      - knowledge-base/design-intelligence/asset-generation.md
+      - knowledge-base/design-intelligence/brand-systems.md
+      - knowledge-base/design-intelligence/closed-loop-repair.md
+      - knowledge-base/design-intelligence/design-plan.md
+      - knowledge-base/design-intelligence/figma-production.md
+      - knowledge-base/design-intelligence/generation-adapter.md
+      - knowledge-base/design-intelligence/iconography.md
+      - knowledge-base/design-intelligence/information-design.md
+      - knowledge-base/design-intelligence/interaction-recovery-verification.md
+      - knowledge-base/design-intelligence/interface-trust.md
+      - knowledge-base/design-intelligence/licensing-and-provenance.md
+      - knowledge-base/design-intelligence/presentation-design.md
+      - knowledge-base/design-intelligence/product-design-brief.md
+      - knowledge-base/design-intelligence/visual-accessibility.md
+      - knowledge-base/design-intelligence/visual-polish.md
+  ux-patterns:
+    label: Maintained product and dashboard patterns
+    files:
+      - knowledge-base/maintained/product-patterns/MASTER.md
+      - knowledge-base/maintained/product-patterns/ai-workspaces.md
+      - knowledge-base/maintained/product-patterns/operational-dashboards.md
+  usability-evaluation:
+    label: Usability and heuristic evaluation
+    files:
+      - knowledge-base/usability-evaluation/HEURISTIC_EVALUATION.md

package/knowledge-base/usability-evaluation/HEURISTIC_EVALUATION.md

@@ -0,0 +1,115 @@
+# Heuristic Evaluation and Usability Evidence
+
+Use this maintained reference for UX audits, release reviews, redesign diagnosis, and benchmark creation. It operationalizes the evidence boundaries and evaluation methods required by this system without depending on the local raw research corpus.
+
+## Evidence Boundaries
+
+Keep these evidence types distinct:
+
+| Evidence | What it can establish | What it cannot establish |
+|---|---|---|
+| Automated runtime inspection | Rendered overflow, clipping, collisions, missing names, broken focus, blank media, console failures, network behavior, and journey assertions | Whether terminology matches the user's mental model or whether the complete task is understandable and efficient |
+| Expert heuristic evaluation | Likely usability problems, violated interaction principles, inconsistent conventions, missing recovery, and cognitive burden | Actual prevalence or impact for representative users |
+| Moderated or unmoderated usability testing | Whether intended users can complete intended tasks in the intended context; observed errors, recovery, and comprehension | Population-level rates from a small qualitative sample |
+| Analytics and quantitative studies | Frequency, funnels, task timing, abandonment, and comparative measurements when instrumentation and sampling are valid | Root cause without qualitative or task evidence |
+
+Never report an automated or heuristic result as proof that users succeeded. Treat heuristic findings as testable risk hypotheses and use representative-user testing for consequential workflows.
+
+## Expert Evaluation Workflow
+
+1. Define the intended users, domain, critical tasks, supported devices, environment, and states. Do not evaluate an abstract screen without its task contract.
+2. Select relevant heuristics and domain rules. Weight them by task risk instead of treating every principle as equally important.
+3. Brief evaluators with the same scope, tasks, evidence format, and product assumptions. Prefer evaluators with domain knowledge; use multiple independent reviewers for consequential work.
+4. First pass: use the interface freely to understand its interaction model, boundaries, and likely focus areas.
+5. Second pass: execute representative tasks and inspect each relevant state against the chosen heuristics.
+6. Record one concrete problem per finding. Name the location, state, trigger, observed behavior, affected user outcome, evidence, and violated principle.
+7. Debrief across evaluators. Merge duplicates, challenge false alarms, preserve disagreements, and prioritize remediation.
+8. Convert material findings into acceptance criteria and regression checks. Retest corrected behavior and use representative users where assumptions remain.
+
+## Nielsen Interaction Heuristics
+
+Apply the ten principles contextually:
+
+1. Keep system status visible with timely, truthful feedback.
+2. Match user language, domain concepts, natural order, and real-world conventions.
+3. Preserve user control with cancel, back, undo, retry, and clear exits where applicable.
+4. Maintain internal consistency and follow platform and industry standards.
+5. Prevent errors before relying on error messages.
+6. Prefer recognition over recall; keep choices, context, and instructions available.
+7. Support efficient repeat use without making novice paths opaque.
+8. Remove irrelevant information and visual competition without hiding required task context.
+9. Explain errors in user language, identify the cause, preserve work, and provide recovery.
+10. Provide concise, searchable, task-focused help when the interface cannot be self-explanatory.
+
+## Finding Record
+
+Use `heuristic-review.template.yaml` as the starting artifact and validate it against `heuristic-review.schema.yaml`. The executable TypeScript schema is authoritative for the MCP server and CLI. Each file records the reviewed target, representative tasks, evidence provenance, findings, resolution decisions, and validation methods.
+
+Use the following numeric severity scale in structured reviews:
+
+- `0`: not a usability problem after review.
+- `1`: cosmetic; no meaningful task impairment.
+- `2`: minor; localized friction with a clear workaround.
+- `3`: major; materially harms comprehension, efficiency, recovery, or task completion.
+- `4`: catastrophic; prevents a critical task, creates unsafe ambiguity, or makes consequential controls inaccessible.
+
+Each evidence entry must identify one evidence level:
+
+- `automated`: browser, source, network, accessibility, or other deterministic inspection.
+- `ai-assisted-expert`: an agent-assisted heuristic interpretation; never human evidence.
+- `human-expert`: attributable expert review with contributor and timestamp.
+- `representative-user`: attributable usability-session evidence with a privacy-preserving participant reference and timestamp.
+
+Example finding excerpt:
+
+```yaml
+id: export-recovery-missing
+title: Failed export has no safe recovery action
+task: export-current-report
+heuristic:
+  id: error-recovery
+  name: Help users recognize, diagnose, and recover from errors
+location: Reports view at mobile-375 in export-error state
+trigger: Attempt an export while the export service is unavailable.
+observation: The failure removes the export action and does not explain whether the report was preserved.
+evidence:
+  - level: automated
+    source: runtime/export-error/report.json
+    detail: The journey found no visible retry control after the failed response.
+impact: The user cannot determine whether retry is safe or whether work was lost.
+severity: 3
+confidence: high
+status: open
+remediation: Preserve the report, show the failure cause, and provide Retry and Dismiss actions.
+validation:
+  method: representative-user-test
+  procedure: Repeat the recovery task and confirm that users understand report preservation and retry safety.
+```
+
+Do not derive severity from visual prominence alone. Consider task criticality, affected users, frequency or reach, recoverability, and consequence.
+
+Run `evaluate_heuristic_review` through MCP or use the CLI fallback:
+
+```bash
+npm run review-heuristics -- --review PATH_TO_HEURISTIC_REVIEW
+```
+
+Use `--candidates` to print only the contract fragment. Use `--fail-on-open-major` when a CI or local policy should return exit code 2 for open severity 3 or 4 findings.
+
+The evaluator converts each open severity 3 or 4 finding into an unapplied blocker acceptance-criterion candidate. Review the generated YAML before merging it into a product contract. The review artifact is never a manual acceptance attestation, and the evaluator never edits contracts or attestation files.
+
+## Usability Testing Handoff
+
+When expert or automated evidence cannot resolve a user assumption:
+
+1. State the research question and target user group.
+2. Write representative tasks with precise outcomes, realistic context, and coverage of essential UI areas.
+3. Separate novice and expert groups when their skills or performance expectations differ.
+4. Pilot the protocol before recruiting the full group.
+5. Ask facilitators and observers not to coach, correct, or bias participants during the task.
+6. Record behavior and one observation per note; collect subjective feedback after task performance.
+7. Fix significant findings and run another small formative round rather than relying on one large final test.
+
+## Provenance Boundary
+
+The distributable workflow is self-contained. Local course handouts, converted books, and extended research notes may support future independently authored revisions, but they are not shipped, retrieved through MCP, or required at runtime. Add a rule to this maintained document only after its provenance and reuse status are recorded during the clean-room certification phase.

package/knowledge-base/usability-evaluation/heuristic-review.schema.yaml

@@ -0,0 +1,210 @@
+$schema: https://json-schema.org/draft/2020-12/schema
+$id: https://local.ztothez-design-engineering/schemas/heuristic-review-1.0.schema.json
+title: ZtotheZ Design Engineering Heuristic Review
+description: >-
+  Versioned expert-review artifact. Evidence levels are descriptive provenance and do not
+  constitute product-contract acceptance attestations.
+type: object
+additionalProperties: false
+required: [version, id, product, target, preparedAt, preparedBy, tasks, findings]
+properties:
+  version:
+    const: "1.0"
+  id:
+    $ref: "#/$defs/id"
+  product:
+    $ref: "#/$defs/shortText"
+  target:
+    $ref: "#/$defs/text"
+  preparedAt:
+    type: string
+    format: date-time
+  preparedBy:
+    type: object
+    additionalProperties: false
+    required: [type, name]
+    properties:
+      type:
+        enum: [agent, human, mixed]
+      name:
+        $ref: "#/$defs/shortText"
+  tasks:
+    type: array
+    minItems: 1
+    maxItems: 100
+    items:
+      $ref: "#/$defs/task"
+  findings:
+    type: array
+    maxItems: 1000
+    items:
+      $ref: "#/$defs/finding"
+$defs:
+  id:
+    type: string
+    pattern: "^[a-z0-9][a-z0-9-]{0,47}$"
+  shortText:
+    type: string
+    minLength: 1
+    maxLength: 256
+  text:
+    type: string
+    minLength: 1
+    maxLength: 2048
+  task:
+    type: object
+    additionalProperties: false
+    required: [id, actor, scenario, successCriteria, modes]
+    properties:
+      id:
+        $ref: "#/$defs/id"
+      actor:
+        $ref: "#/$defs/shortText"
+      scenario:
+        type: string
+        minLength: 1
+        maxLength: 1024
+      successCriteria:
+        type: array
+        minItems: 1
+        maxItems: 20
+        items:
+          type: string
+          minLength: 1
+          maxLength: 512
+      modes:
+        type: array
+        minItems: 1
+        maxItems: 20
+        items:
+          $ref: "#/$defs/id"
+  evidence:
+    type: object
+    additionalProperties: false
+    required: [level, source, detail]
+    properties:
+      level:
+        enum: [automated, ai-assisted-expert, human-expert, representative-user]
+      source:
+        type: string
+        minLength: 1
+        maxLength: 1024
+      detail:
+        $ref: "#/$defs/text"
+      contributor:
+        $ref: "#/$defs/shortText"
+      recordedAt:
+        type: string
+        format: date-time
+    allOf:
+      - if:
+          properties:
+            level:
+              enum: [human-expert, representative-user]
+          required: [level]
+        then:
+          required: [contributor, recordedAt]
+  resolution:
+    type: object
+    additionalProperties: false
+    required: [rationale, decidedBy, decidedAt]
+    properties:
+      rationale:
+        $ref: "#/$defs/text"
+      decidedBy:
+        $ref: "#/$defs/shortText"
+      decidedAt:
+        type: string
+        format: date-time
+  finding:
+    type: object
+    additionalProperties: false
+    required:
+      - id
+      - title
+      - task
+      - heuristic
+      - location
+      - trigger
+      - observation
+      - impact
+      - evidence
+      - severity
+      - confidence
+      - status
+      - remediation
+      - validation
+    properties:
+      id:
+        $ref: "#/$defs/id"
+      title:
+        type: string
+        minLength: 1
+        maxLength: 160
+      task:
+        $ref: "#/$defs/id"
+      heuristic:
+        type: object
+        additionalProperties: false
+        required: [id, name]
+        properties:
+          id:
+            $ref: "#/$defs/id"
+          name:
+            $ref: "#/$defs/shortText"
+      location:
+        type: string
+        minLength: 1
+        maxLength: 1024
+      trigger:
+        type: string
+        minLength: 1
+        maxLength: 1024
+      observation:
+        $ref: "#/$defs/text"
+      impact:
+        $ref: "#/$defs/text"
+      evidence:
+        type: array
+        minItems: 1
+        maxItems: 50
+        items:
+          $ref: "#/$defs/evidence"
+      severity:
+        type: integer
+        minimum: 0
+        maximum: 4
+      confidence:
+        enum: [high, medium, low]
+      status:
+        enum: [open, resolved, accepted-risk]
+      remediation:
+        $ref: "#/$defs/text"
+      validation:
+        type: object
+        additionalProperties: false
+        required: [method, procedure]
+        properties:
+          method:
+            enum:
+              - runtime
+              - accessibility
+              - screenshot-review
+              - expert-review
+              - representative-user-test
+              - analytics
+          procedure:
+            $ref: "#/$defs/text"
+      resolution:
+        $ref: "#/$defs/resolution"
+    allOf:
+      - if:
+          properties:
+            status:
+              const: open
+          required: [status]
+        then:
+          not:
+            required: [resolution]
+        else:
+          required: [resolution]