@ztothez/design-engineering 2.0.0

package/knowledge-base/benchmarks/interface-quality/review-session.schema.yaml

@@ -0,0 +1,14 @@
+$schema: https://json-schema.org/draft/2020-12/schema
+$id: https://local.ztothez-design-engineering/schemas/interface-comparison-review-session-1.0.schema.json
+title: ZtotheZ Interface Comparison Review Session
+description: Portable envelope for draft or completed human-expert and representative-user comparison sessions.
+type: object
+additionalProperties: false
+required: [version, status, session]
+properties:
+  version:
+    const: "1.0"
+  status:
+    enum: [draft, complete]
+  session:
+    $ref: review.schema.yaml#/$defs/session

package/knowledge-base/benchmarks/interface-quality/review.schema.yaml

@@ -0,0 +1,296 @@
+$schema: https://json-schema.org/draft/2020-12/schema
+$id: https://local.ztothez-design-engineering/schemas/interface-comparison-review-1.0.schema.json
+title: ZtotheZ Interface Comparison Review
+description: Version 1.0 review, claim-ledger, retained-artifact, and evidence-provenance contract.
+type: object
+additionalProperties: false
+required: [version, id, methodologyId, preparedAt, preparedBy, candidates, artifacts, stages, sessions, claims]
+properties:
+  version:
+    const: "1.0"
+  id:
+    $ref: "#/$defs/id"
+  methodologyId:
+    $ref: "#/$defs/id"
+  preparedAt:
+    type: string
+    format: date-time
+  preparedBy:
+    $ref: "#/$defs/preparedBy"
+  candidates:
+    type: array
+    minItems: 2
+    maxItems: 12
+    items:
+      $ref: "#/$defs/id"
+  artifacts:
+    type: array
+    maxItems: 10000
+    items:
+      $ref: "#/$defs/artifact"
+  stages:
+    type: array
+    maxItems: 100
+    items:
+      type: object
+      additionalProperties: false
+      required: [id, candidate, status, evidenceRefs]
+      properties:
+        id:
+          $ref: "#/$defs/id"
+        candidate:
+          $ref: "#/$defs/evidenceSubject"
+        status:
+          enum: [pass, fail, partial, not-run]
+        evidenceRefs:
+          $ref: "#/$defs/idList"
+  sessions:
+    type: array
+    maxItems: 2000
+    items:
+      $ref: "#/$defs/session"
+  claims:
+    type: array
+    minItems: 1
+    maxItems: 10000
+    items:
+      $ref: "#/$defs/claim"
+$defs:
+  id:
+    type: string
+    pattern: "^[a-z0-9][a-z0-9-]{0,63}$"
+  shortText:
+    type: string
+    minLength: 1
+    maxLength: 256
+  text:
+    type: string
+    minLength: 1
+    maxLength: 2048
+  path:
+    type: string
+    minLength: 1
+    maxLength: 1024
+  idList:
+    type: array
+    maxItems: 100
+    items:
+      $ref: "#/$defs/id"
+  evidenceLevel:
+    enum: [automated, ai-assisted-expert, human-expert, representative-user]
+  evidenceSubject:
+    anyOf:
+      - $ref: "#/$defs/id"
+      - const: comparison
+  preparedBy:
+    type: object
+    additionalProperties: false
+    required: [type, name]
+    properties:
+      type:
+        enum: [agent, human, mixed]
+      name:
+        $ref: "#/$defs/shortText"
+  accessibility:
+    type: object
+    additionalProperties: false
+    required: [standard, version, level, coverage]
+    properties:
+      standard:
+        const: WCAG
+      version:
+        enum: ["2.1", "2.2"]
+      level:
+        enum: [A, AA, AAA]
+      coverage:
+        enum: [sampled-states, declared-routes, full-product]
+  artifact:
+    type: object
+    additionalProperties: false
+    required: [id, candidate, stage, kind, path, producer, retained, scope, recordedAt, sourceRevision, sha256]
+    allOf:
+      - if:
+          properties:
+            kind:
+              const: screenshot
+        then:
+          required: [capture]
+        else:
+          not:
+            required: [capture]
+    properties:
+      id:
+        $ref: "#/$defs/id"
+      candidate:
+        $ref: "#/$defs/evidenceSubject"
+      stage:
+        $ref: "#/$defs/id"
+      kind:
+        enum: [build-report, typecheck-report, test-report, static-audit, runtime-report, journey-report, screenshot, export, source-inspection, human-review, user-session]
+      path:
+        $ref: "#/$defs/path"
+      producer:
+        enum: [automation, agent, human]
+      retained:
+        type: boolean
+      scope:
+        type: string
+        minLength: 1
+        maxLength: 1024
+      recordedAt:
+        type: string
+        format: date-time
+      sourceRevision:
+        $ref: "#/$defs/shortText"
+      sha256:
+        type: string
+        pattern: "^[a-f0-9]{64}$"
+      capture:
+        type: object
+        additionalProperties: false
+        required: [viewport, state, width, height]
+        properties:
+          viewport:
+            $ref: "#/$defs/id"
+          state:
+            $ref: "#/$defs/id"
+          width:
+            type: integer
+            minimum: 240
+            maximum: 3840
+          height:
+            type: integer
+            minimum: 240
+            maximum: 5000
+      accessibility:
+        $ref: "#/$defs/accessibility"
+  taskResult:
+    type: object
+    additionalProperties: false
+    required: [task, candidate, outcome, navigationErrors, recoveryAttempts]
+    properties:
+      task:
+        $ref: "#/$defs/id"
+      candidate:
+        $ref: "#/$defs/id"
+      outcome:
+        enum: [completed, partial, failed, not-run]
+      durationSeconds:
+        type: number
+        minimum: 0
+        maximum: 86400
+      navigationErrors:
+        type: integer
+        minimum: 0
+      recoveryAttempts:
+        type: integer
+        minimum: 0
+      comprehensionCorrect:
+        type: boolean
+      confidence:
+        type: integer
+        minimum: 1
+        maximum: 5
+      notes:
+        $ref: "#/$defs/text"
+  rating:
+    type: object
+    additionalProperties: false
+    required: [candidate, criterion, score, rationale]
+    properties:
+      candidate:
+        $ref: "#/$defs/id"
+      criterion:
+        $ref: "#/$defs/id"
+      score:
+        type: integer
+        minimum: 0
+        maximum: 4
+      rationale:
+        $ref: "#/$defs/text"
+  session:
+    type: object
+    additionalProperties: false
+    required: [id, level, origin, candidateOrder, taskResults, ratings]
+    properties:
+      id:
+        $ref: "#/$defs/id"
+      level:
+        enum: [ai-assisted-expert, human-expert, representative-user]
+      origin:
+        enum: [agent-generated, reviewer-supplied]
+      contributor:
+        $ref: "#/$defs/shortText"
+      recordedAt:
+        type: string
+        format: date-time
+      participantId:
+        $ref: "#/$defs/id"
+      blinding:
+        type: object
+        additionalProperties: false
+        required: [candidateIdentitiesWithheld, priorCandidateExposure, conflicts]
+        properties:
+          candidateIdentitiesWithheld:
+            type: boolean
+          priorCandidateExposure:
+            type: boolean
+          conflicts:
+            type: array
+            maxItems: 20
+            items:
+              type: string
+              minLength: 1
+              maxLength: 512
+      candidateOrder:
+        type: array
+        minItems: 2
+        maxItems: 12
+        items:
+          $ref: "#/$defs/id"
+      taskResults:
+        type: array
+        maxItems: 2000
+        items:
+          $ref: "#/$defs/taskResult"
+      ratings:
+        type: array
+        maxItems: 2000
+        items:
+          $ref: "#/$defs/rating"
+  claim:
+    type: object
+    additionalProperties: false
+    required: [id, candidate, kind, statement, evidenceType, evidenceRefs, sessionRefs, scope, status, limitations]
+    properties:
+      id:
+        $ref: "#/$defs/id"
+      candidate:
+        $ref: "#/$defs/evidenceSubject"
+      kind:
+        enum: [overall-result, stage-result, accessibility-conformance, design-quality, implementation-fact]
+      statement:
+        $ref: "#/$defs/text"
+      evidenceType:
+        $ref: "#/$defs/evidenceLevel"
+      evidenceRefs:
+        $ref: "#/$defs/idList"
+      sessionRefs:
+        $ref: "#/$defs/idList"
+      scope:
+        type: string
+        minLength: 1
+        maxLength: 1024
+      status:
+        enum: [verified, partial, unverified, contradicted]
+      outcome:
+        enum: [pass, fail, partial, not-evaluated]
+      limitations:
+        type: array
+        maxItems: 50
+        items:
+          type: string
+          minLength: 1
+          maxLength: 1024
+      accessibility:
+        $ref: "#/$defs/accessibility"

package/knowledge-base/benchmarks/interface-quality/review.template.yaml

@@ -0,0 +1,43 @@
+version: "1.0"
+id: incomplete-operational-interface-review
+methodologyId: operational-interface-comparison-v1
+preparedAt: 2026-08-26T15:15:00+03:00
+preparedBy:
+  type: agent
+  name: ZtotheZ Design Engineering
+candidates: [anonymous-a, anonymous-b, anonymous-c, anonymous-d]
+artifacts:
+  - id: example-runtime
+    candidate: anonymous-a
+    stage: browser-verification
+    kind: runtime-report
+    path: evidence/example-runtime-report.json
+    producer: automation
+    retained: true
+    scope: Synthetic template evidence for one sampled browser state; not product evidence
+    recordedAt: 2026-08-26T15:10:00+03:00
+    sourceRevision: synthetic-template-v1
+    sha256: 90147b28b13930154a1a0a8df490e1cdd19b92b640d4370afcb2dfd65ac6ef8b
+    accessibility:
+      standard: WCAG
+      version: "2.2"
+      level: AA
+      coverage: sampled-states
+stages:
+  - id: browser-verification
+    candidate: anonymous-a
+    status: partial
+    evidenceRefs: [example-runtime]
+sessions: []
+claims:
+  - id: template-runtime-exists
+    candidate: anonymous-a
+    kind: implementation-fact
+    statement: The template includes one retained synthetic runtime artifact.
+    evidenceType: automated
+    evidenceRefs: [example-runtime]
+    sessionRefs: []
+    scope: Comparison template only
+    status: verified
+    limitations:
+      - This artifact does not describe or certify a product implementation.

package/knowledge-base/benchmarks/portfolio-corpus/ADAPTERS.md

@@ -0,0 +1,68 @@
+# Portfolio Stack Adapters
+
+Stack adapters convert local registry declarations into bounded benchmark capabilities. They do not
+discover and execute package scripts. The local registry must select an adapter, declare each
+capability, and provide an exact command for every executable stage.
+
+## Supported Adapters
+
+| Adapter | Intended project | Browser stages |
+|---|---|---|
+| `react-vite` | React with Vite or TanStack Router | Supported when declared |
+| `nextjs` | Next.js frontend | Supported when declared |
+| `angular` | Angular frontend | Supported when declared |
+| `static-web` | Static HTML, CSS, and JavaScript | Supported when declared |
+| `node-python-fullstack` | Frontend with a Node or Python service | Supported when declared |
+| `python-source` | Source-only Python or desktop tool | Not applicable |
+
+Every adapter reports all eight portfolio stages. An undeclared or commandless stage is
+`unsupported`. A stage outside the adapter's product surface is `not-applicable`. Neither status is
+reported as a pass or a product defect.
+
+## Command Contract
+
+Declare commands under `project.execution.commands`. Each stage may have at most one command.
+
+```yaml
+technology:
+  framework: React with Vite
+  packageManager: npm
+  entrypoint: package.json
+  adapter: react-vite
+capabilities:
+  - stage: production-build
+    status: supported
+    reason: The product has a reviewed production build.
+execution:
+  fixtureMode: disconnected
+  networkPolicy: denied
+  lifecycleScripts: false
+  allowedEnvironmentVariables: []
+  localPorts: []
+  commands:
+    - stage: production-build
+      command: npm
+      arguments: [run, build]
+      cwd: .
+      timeoutMs: 120000
+      maxOutputBytes: 2097152
+      allowDependencyNetwork: false
+```
+
+The executor passes arguments directly without a shell. Adapter policy permits only known
+executables and stage-specific package scripts. Direct Node and Python commands must name a
+contained relative script and cannot use eval or command-string flags. The snapshot runner then
+enforces the working-directory boundary, environment allowlist, network policy, timeout, process
+group cleanup, output ceiling, and post-run source mutation check.
+
+## Workflow
+
+1. Validate the local registry.
+2. Inspect effective capability support with `zz-design portfolio capabilities --project ID`.
+3. Resolve every warning or accept it as a documented limitation.
+4. Execute one declared stage with `zz-design portfolio run-stage --project ID --stage STAGE`.
+5. Treat `unsupported` and `not-applicable` as limitations, never successful product evidence.
+6. Treat command-policy errors, nonzero exits, and timeouts as failed execution evidence.
+
+Original projects remain read-only. All executable commands run in disposable snapshots managed by
+the mutation guard.

package/knowledge-base/benchmarks/portfolio-corpus/PORTFOLIO-RUNNER.md

@@ -0,0 +1,131 @@
+# Local Portfolio Benchmark Runner
+
+The runner benchmarks authorized projects without executing inside their original roots. It creates
+one disposable snapshot per project, runs only commands explicitly declared in the local registry,
+checks the original source digest after execution, and retains a private structured report.
+
+## Commands
+
+```bash
+zz-design portfolio baseline --project PROJECT_ID --run baseline-001
+zz-design portfolio benchmark --cohort development --run development-001
+zz-design portfolio benchmark --cohort holdout --run holdout-001
+zz-design portfolio verify-unchanged --run development-001
+zz-design portfolio report --run development-001
+zz-design portfolio evaluate-rule --candidate rule.json --evidence rule-evidence.json --dev-run development-001 --holdout-run holdout-001
+zz-design portfolio qualify-v3 --evidence qualification-evidence.json --dev-run development-001 --holdout-run holdout-001
+```
+
+Omit `--run` from `baseline` or `benchmark` to generate a timestamped run ID. Reports are written to
+`.ztothez-design-benchmarks/runs/RUN_ID/report.json` with owner-only file permissions. Run IDs may
+contain letters, numbers, periods, underscores, and hyphens.
+
+## Execution Model
+
+1. Validate the local registry and reject unapproved roots or commands.
+2. Capture the project's source digest and Git revision when available.
+3. Copy approved files into a disposable workspace.
+4. Resolve the declared adapter and execute supported stages in fixed order.
+5. Serve a declared static fixture on an approved loopback port when browser evidence is enabled.
+6. Run the product contract, static audit, browser journeys, accessibility checks, acceptance
+   evaluation, and optional structured heuristic review against the snapshot.
+7. Stop the fixture server in all success and failure paths.
+8. Continue to the next project after findings, limitations, or unsafe configuration.
+9. Compare the original source against its pre-run digest before cleanup.
+10. Checksum retained reports, screenshots, and exports, then remove the disposable snapshot.
+
+The runner never discovers arbitrary package scripts. Network access, lifecycle scripts, allowed
+environment variable names, timeouts, commands, arguments, and working directories come from the
+validated local registry.
+
+## Exit Codes
+
+| Code | Meaning |
+| --- | --- |
+| `0` | All applicable stages passed. |
+| `1` | One or more stages produced product or source findings. |
+| `2` | No findings occurred, but evidence is incomplete because a stage was unsupported or not applicable. |
+| `3` | At least one project had unsafe or invalid execution configuration. |
+| `4` | The original source changed or source-integrity verification failed. |
+
+Higher-severity integrity and configuration conditions take precedence over findings and
+limitations when a cohort contains mixed results.
+
+## Browser Verification Declaration
+
+Declare `verification` only when the snapshot contains a static fixture directory and a complete
+product contract. The port must also appear in `execution.localPorts`, fixture mode must be
+`local-fixture`, and both `local-fixture-server` and `browser-journeys` must be supported capabilities.
+Dynamic services that cannot produce a disconnected static fixture remain an explicit verifier
+limitation rather than receiving a false pass.
+
+## Rule Promotion Evidence
+
+Rule promotion is fail closed. It requires complete development and holdout cohort reports plus a
+version 1.0 evidence document. The evidence document binds positive, negative, and abstention
+fixtures; V1/V2, retrieval, corpus, MCP, package, and independence gates; project-specific holdout
+evaluations; documentation; tests; and migration guidance to checksummed repository-relative files.
+The CLI verifies every checksum and rejects missing files, path traversal, and symlink escape before
+evaluating the candidate.
+
+A missing holdout project or candidate-specific holdout report is `unverified`, never `unaffected`.
+Recurrence-backed candidates require the candidate report code in every declared authoring
+project's retained development report. Holdout IDs must match the locked cohort exactly. Regression
+or unverified outcomes block promotion, and an all-abstention result cannot establish benefit or
+non-regression.
+
+Start from `rule-promotion-evidence.template.json` and use
+`rule-holdout-evaluation.template.json` for each locked holdout. Leave gates failing until their
+artifacts exist, and keep private run evidence under `.ztothez-design-benchmarks/`. The CLI parses
+each referenced holdout report and verifies its candidate, report code, run, project, source digest,
+applicability, execution, regression, and outcome fields; a matching checksum alone is insufficient.
+
+## V3 Qualification Evidence
+
+V3 qualification requires explicit checksummed CI and release evidence. No fixture or gate defaults
+to passing. The evaluator enforces 12 eligible projects, five domains, three frontend stacks, four
+archetypes, three locked holdouts, complete development and holdout reports, and executed
+source-only, browser-only, and full-stack paths. Framework names and capability declarations alone
+do not establish a benchmark path.
+
+Start from `v3-qualification-evidence.template.json`. The qualification report emits only claims
+whose specific criteria passed. Local qualification remains failed until the ignored registry and
+retained runs satisfy every threshold; synthetic CI tests cannot substitute for the local corpus.
+
+Generate a complete local evidence set with:
+
+```bash
+npm run v3:evidence -- \
+  --dev-run DEVELOPMENT_RUN \
+  --holdout-run HOLDOUT_RUN \
+  --output .ztothez-design-benchmarks/evidence/v3-final
+```
+
+Every command report references checksummed stdout and stderr logs. The script executes maintained
+rule fixtures, exact CI categories, package and offline-release checks, browser-only and full-stack
+snapshot fixtures, candidate-specific holdout evaluation, and final qualification. Its output must
+remain under `.ztothez-design-benchmarks/`.
+
+`benefited` in a rule holdout report means the candidate rule detected its intended condition in a
+locked product. It does not mean the source product was remediated. `unaffected` means the
+applicable rule executed without that finding. Product source is never changed by this workflow.
+
+GitHub Actions runs the public synthetic subset with `--ci-only`. That subset validates the runner's
+execution paths and negative controls; it does not replace the private local corpus or support a
+claim that a private product passed browser or full-stack verification.
+
+## Read-Only MCP Access
+
+Local portfolio MCP access is disabled by default. Enable it explicitly for a trusted local MCP
+process:
+
+```bash
+export ZTOTHEZ_DESIGN_PORTFOLIO_MCP=enabled
+export ZTOTHEZ_DESIGN_PORTFOLIO_REGISTRY="$PWD/.ztothez-design-local/portfolio-registry.yaml"
+export ZTOTHEZ_DESIGN_PORTFOLIO_REPORT_ROOT="$PWD/.ztothez-design-benchmarks/runs"
+export ZTOTHEZ_DESIGN_PORTFOLIO_EVIDENCE_ROOT="$PWD/.ztothez-design-benchmarks/evidence"
+```
+
+`list_portfolio_projects` lists IDs and effective capabilities.
+`get_portfolio_benchmark_report` reads a completed run or one project summary. Neither tool exposes
+source roots or starts project commands.

package/knowledge-base/benchmarks/portfolio-corpus/PRODUCT-TASK-CONTRACTS.md

@@ -0,0 +1,29 @@
+# Product Task Contracts
+
+Product task contracts prevent a generic dashboard checklist from replacing the actual purpose of
+a product. Contract version `1.1` adds an archetype-aware `benchmark` block to the existing actors,
+modes, states, outputs, acceptance criteria, journeys, and viewports.
+
+## Required Workflow
+
+1. Select the closest archetype from `archetype-profiles.yaml`.
+2. Declare whether the product surface is browser, desktop, or source-only.
+3. Mark all seven quality dimensions as required or not applicable and explain every decision.
+4. Define at least one primary task from observable start state to observable success.
+5. Define at least one visible failure and recovery path.
+6. Bind browser tasks to an existing journey, route, and viewport no wider than 768 CSS pixels.
+7. Keep missing evidence as `unverified`, executed failure as `failed`, and unsupported capability as
+   `limitation`.
+8. Compare implementations only when they share the same task-contract ID, archetype, primary task
+   intent, and observable success.
+
+## Evidence Boundary
+
+A valid contract proves that the task and evidence requirements are coherent. It does not prove the
+product completed the task. Runtime and acceptance evidence establish behavior later. Missing
+runtime results are not product failures, and an executed failed journey is not a verifier
+limitation.
+
+Source-only tools can activate source audit, architecture, state, and maintainability requirements
+without declaring browser routes or responsive evidence. Browser products cannot omit their narrow
+task path or call it not applicable.

package/knowledge-base/benchmarks/portfolio-corpus/PROMOTED-RULES.md

@@ -0,0 +1,31 @@
+# V3 Promoted Rule Set
+
+These independently authored rules convert recurring portfolio findings into deterministic design-engineering checks. They do not contain project source, product-specific styling, private evidence, or copied third-party implementation.
+
+## Semantic Token Boundary
+
+- Report code: `ZTDE-DESIGN-001`
+- Boundary: flag repeated raw color, spacing, and radius values in authored interface styles when semantic tokens should define the visual system.
+- Accept: declared semantic tokens and token references.
+- Abstain: generated drawing code and contexts where literal values are part of a data or canvas operation.
+- Migration: introduce semantic tokens by role, replace repeated literals incrementally, and verify contrast and composition after migration.
+
+## Interactive Control Integrity
+
+- Report code: `ZTDE-SLOP-003`
+- Boundary: flag rendered interactive controls that expose an action affordance without an action contract.
+- Accept: controls connected to an explicit event or form behavior.
+- Abstain: test-only fixtures and non-production examples excluded by audit policy.
+- Migration: bind the control to a real task action, provide pending, success, empty, and error states where relevant, then verify keyboard operation.
+
+## Component Review Threshold
+
+- Report code: `ZTDE-ARCH-001`
+- Boundary: flag rendering components above the maintained 400-line review threshold.
+- Accept: focused rendering components below the threshold.
+- Abstain: long non-rendering modules where component-size analysis is not applicable.
+- Migration: separate domain state, data access, rendering regions, and reusable controls along existing ownership boundaries. Do not split files mechanically when responsibilities remain coupled.
+
+## Verification
+
+Each rule has a maintained positive, negative, and abstention fixture under `rule-fixtures/`. The regression suite materializes every fixture and executes the production repository auditor. Candidate-specific holdout reports and local portfolio evidence remain private and excluded from package output.

package/knowledge-base/benchmarks/portfolio-corpus/archetype-profiles.yaml

@@ -0,0 +1,26 @@
+version: "1.0"
+profiles:
+  - id: operational-dashboard
+    interfaces: [browser, desktop]
+    requiredDimensions: [truthful-disclosure, information-design, visual-system, accessibility, responsive-structure, state-integrity, maintainability]
+  - id: ai-workspace
+    interfaces: [browser, desktop]
+    requiredDimensions: [truthful-disclosure, information-design, visual-system, accessibility, responsive-structure, state-integrity, maintainability]
+  - id: content-site
+    interfaces: [browser]
+    requiredDimensions: [information-design, visual-system, accessibility, responsive-structure, maintainability]
+  - id: utility
+    interfaces: [browser, desktop, source-only]
+    requiredDimensions: [truthful-disclosure, information-design, accessibility, state-integrity, maintainability]
+  - id: full-stack-workflow
+    interfaces: [browser, desktop]
+    requiredDimensions: [truthful-disclosure, information-design, visual-system, accessibility, responsive-structure, state-integrity, maintainability]
+
+evidencePolicy:
+  missingEvidence: unverified
+  failedBehavior: failed
+  unsupportedCapability: limitation
+
+comparisonPolicy:
+  crossContractRanking: false
+  requirement: Compare implementations only when archetype, task-contract ID, and observable primary task success match.