@ztothez/design-engineering 2.0.0

package/knowledge-base/benchmarks/interface-quality/comparison-methodology-v1.1.schema.yaml

@@ -0,0 +1,288 @@
+$schema: https://json-schema.org/draft/2020-12/schema
+$id: https://local.ztothez-design-engineering/schemas/comparison-methodology-1.1.schema.json
+title: ZtotheZ Interface Comparison Methodology
+description: Version 1.1 contract for complete anonymous human review and target-versus-comparator decisions.
+type: object
+additionalProperties: false
+required: [version, id, title, preparedAt, preparedBy, candidates, viewports, states, stages, tasks, rubric, evidencePolicy, decision]
+properties:
+  version:
+    const: "1.1"
+  id:
+    $ref: "#/$defs/id"
+  title:
+    $ref: "#/$defs/shortText"
+  preparedAt:
+    type: string
+    format: date-time
+  preparedBy:
+    $ref: "#/$defs/preparedBy"
+  candidates:
+    type: array
+    minItems: 2
+    maxItems: 12
+    items:
+      type: object
+      additionalProperties: false
+      required: [id, label]
+      properties:
+        id:
+          $ref: "#/$defs/id"
+        label:
+          $ref: "#/$defs/shortText"
+  viewports:
+    type: array
+    minItems: 1
+    maxItems: 12
+    items:
+      type: object
+      additionalProperties: false
+      required: [id, width, height]
+      properties:
+        id:
+          $ref: "#/$defs/id"
+        width:
+          type: integer
+          minimum: 240
+          maximum: 3840
+        height:
+          type: integer
+          minimum: 240
+          maximum: 5000
+  states:
+    $ref: "#/$defs/requiredItems"
+  stages:
+    type: array
+    minItems: 1
+    maxItems: 50
+    items:
+      type: object
+      additionalProperties: false
+      required: [id, label, required, scope, evidenceKinds]
+      properties:
+        id:
+          $ref: "#/$defs/id"
+        label:
+          $ref: "#/$defs/shortText"
+        required:
+          type: boolean
+        scope:
+          enum: [candidate, comparison]
+        evidenceKinds:
+          type: array
+          minItems: 1
+          maxItems: 11
+          uniqueItems: true
+          items:
+            $ref: "#/$defs/artifactKind"
+  tasks:
+    type: array
+    minItems: 1
+    maxItems: 100
+    items:
+      type: object
+      additionalProperties: false
+      required: [id, prompt, successCriteria, measurements]
+      properties:
+        id:
+          $ref: "#/$defs/id"
+        prompt:
+          $ref: "#/$defs/text"
+        successCriteria:
+          type: array
+          minItems: 1
+          maxItems: 20
+          items:
+            $ref: "#/$defs/text"
+        measurements:
+          type: array
+          minItems: 1
+          uniqueItems: true
+          items:
+            enum: [task-completion, time-on-task, navigation-errors, comprehension-accuracy, recovery-attempts, confidence, perceived-visual-quality]
+  rubric:
+    type: object
+    additionalProperties: false
+    required: [scale, categories]
+    properties:
+      scale:
+        type: object
+        additionalProperties: false
+        required: [minimum, maximum, anchors]
+        properties:
+          minimum:
+            const: 0
+          maximum:
+            const: 4
+          anchors:
+            type: object
+            additionalProperties: false
+            required: ["0", "1", "2", "3", "4"]
+            properties:
+              "0": { $ref: "#/$defs/shortText" }
+              "1": { $ref: "#/$defs/shortText" }
+              "2": { $ref: "#/$defs/shortText" }
+              "3": { $ref: "#/$defs/shortText" }
+              "4": { $ref: "#/$defs/shortText" }
+      categories:
+        type: array
+        minItems: 1
+        maxItems: 20
+        items:
+          type: object
+          additionalProperties: false
+          required: [id, label, weight, criteria]
+          properties:
+            id:
+              $ref: "#/$defs/id"
+            label:
+              $ref: "#/$defs/shortText"
+            weight:
+              type: integer
+              minimum: 1
+              maximum: 100
+            criteria:
+              type: array
+              minItems: 1
+              maxItems: 30
+              items:
+                type: object
+                additionalProperties: false
+                required: [id, prompt, measurement, evidenceLevel, scoreMinimum, scoreMaximum]
+                properties:
+                  id:
+                    $ref: "#/$defs/id"
+                  prompt:
+                    $ref: "#/$defs/text"
+                  measurement:
+                    enum: [rating, comprehension, task-observation]
+                  evidenceLevel:
+                    enum: [human-expert, representative-user]
+                  scoreMinimum:
+                    const: 0
+                  scoreMaximum:
+                    const: 4
+  evidencePolicy:
+    type: object
+    additionalProperties: false
+    required: [anonymizeCandidates, counterbalanceOrder, retainArtifacts, separateEvidenceLevels, requireHumanAttribution, prohibitAgentHumanAttestation]
+    properties:
+      anonymizeCandidates: { const: true }
+      counterbalanceOrder: { const: true }
+      retainArtifacts: { const: true }
+      separateEvidenceLevels: { const: true }
+      requireHumanAttribution: { const: true }
+      prohibitAgentHumanAttestation: { const: true }
+  decision:
+    type: object
+    additionalProperties: false
+    required: [minimumCategoryScore, requireAllStagesPass, prohibitContradictedClaims, requiredEvidenceLevels, requiredStageCandidates, reviewRequirements, benchmark]
+    properties:
+      minimumCategoryScore:
+        type: number
+        minimum: 0
+        maximum: 4
+      requireAllStagesPass:
+        type: boolean
+      prohibitContradictedClaims:
+        type: boolean
+      requiredEvidenceLevels:
+        type: array
+        minItems: 1
+        maxItems: 4
+        uniqueItems: true
+        items:
+          $ref: "#/$defs/evidenceLevel"
+      requiredStageCandidates:
+        type: array
+        minItems: 1
+        maxItems: 12
+        uniqueItems: true
+        items:
+          $ref: "#/$defs/id"
+      reviewRequirements:
+        type: object
+        additionalProperties: false
+        required: [minimumHumanExpertSessions, minimumRepresentativeUserSessions, requireCompleteTaskMatrix, requireCompleteRatingMatrix, requireIdentityBlinding, minimumCounterbalancedOrders]
+        properties:
+          minimumHumanExpertSessions:
+            type: integer
+            minimum: 1
+            maximum: 100
+          minimumRepresentativeUserSessions:
+            type: integer
+            minimum: 1
+            maximum: 100
+          requireCompleteTaskMatrix:
+            type: boolean
+          requireCompleteRatingMatrix:
+            type: boolean
+          requireIdentityBlinding:
+            type: boolean
+          minimumCounterbalancedOrders:
+            type: integer
+            minimum: 1
+            maximum: 12
+      benchmark:
+        type: object
+        additionalProperties: false
+        required: [targetCandidate, comparatorCandidates, requiredCategoryIds, requireTaskMetricNonRegression]
+        properties:
+          targetCandidate:
+            $ref: "#/$defs/id"
+          comparatorCandidates:
+            type: array
+            minItems: 1
+            maxItems: 11
+            uniqueItems: true
+            items:
+              $ref: "#/$defs/id"
+          requiredCategoryIds:
+            type: array
+            minItems: 1
+            maxItems: 20
+            uniqueItems: true
+            items:
+              $ref: "#/$defs/id"
+          requireTaskMetricNonRegression:
+            type: boolean
+$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: 1024
+  preparedBy:
+    type: object
+    additionalProperties: false
+    required: [type, name]
+    properties:
+      type:
+        enum: [agent, human, mixed]
+      name:
+        $ref: "#/$defs/shortText"
+  evidenceLevel:
+    enum: [automated, ai-assisted-expert, human-expert, representative-user]
+  artifactKind:
+    enum: [build-report, typecheck-report, test-report, static-audit, runtime-report, journey-report, screenshot, export, source-inspection, human-review, user-session]
+  requiredItems:
+    type: array
+    minItems: 1
+    maxItems: 50
+    items:
+      type: object
+      additionalProperties: false
+      required: [id, label, required]
+      properties:
+        id:
+          $ref: "#/$defs/id"
+        label:
+          $ref: "#/$defs/shortText"
+        required:
+          type: boolean

package/knowledge-base/benchmarks/interface-quality/comparison-methodology.schema.yaml

@@ -0,0 +1,235 @@
+$schema: https://json-schema.org/draft/2020-12/schema
+$id: https://local.ztothez-design-engineering/schemas/comparison-methodology-1.0.schema.json
+title: ZtotheZ Interface Comparison Methodology
+description: Version 1.0 contract for anonymous, task-based, evidence-separated interface comparisons.
+type: object
+additionalProperties: false
+required: [version, id, title, preparedAt, preparedBy, candidates, viewports, states, stages, tasks, rubric, evidencePolicy, decision]
+properties:
+  version:
+    const: "1.0"
+  id:
+    $ref: "#/$defs/id"
+  title:
+    $ref: "#/$defs/shortText"
+  preparedAt:
+    type: string
+    format: date-time
+  preparedBy:
+    $ref: "#/$defs/preparedBy"
+  candidates:
+    type: array
+    minItems: 2
+    maxItems: 12
+    items:
+      type: object
+      additionalProperties: false
+      required: [id, label]
+      properties:
+        id:
+          $ref: "#/$defs/id"
+        label:
+          $ref: "#/$defs/shortText"
+  viewports:
+    type: array
+    minItems: 1
+    maxItems: 12
+    items:
+      type: object
+      additionalProperties: false
+      required: [id, width, height]
+      properties:
+        id:
+          $ref: "#/$defs/id"
+        width:
+          type: integer
+          minimum: 240
+          maximum: 3840
+        height:
+          type: integer
+          minimum: 240
+          maximum: 5000
+  states:
+    $ref: "#/$defs/requiredItems"
+  stages:
+    type: array
+    minItems: 1
+    maxItems: 50
+    items:
+      type: object
+      additionalProperties: false
+      required: [id, label, required, scope, evidenceKinds]
+      properties:
+        id:
+          $ref: "#/$defs/id"
+        label:
+          $ref: "#/$defs/shortText"
+        required:
+          type: boolean
+        scope:
+          enum: [candidate, comparison]
+        evidenceKinds:
+          type: array
+          minItems: 1
+          maxItems: 11
+          uniqueItems: true
+          items:
+            $ref: "#/$defs/artifactKind"
+  tasks:
+    type: array
+    minItems: 1
+    maxItems: 100
+    items:
+      type: object
+      additionalProperties: false
+      required: [id, prompt, successCriteria, measurements]
+      properties:
+        id:
+          $ref: "#/$defs/id"
+        prompt:
+          $ref: "#/$defs/text"
+        successCriteria:
+          type: array
+          minItems: 1
+          maxItems: 20
+          items:
+            $ref: "#/$defs/text"
+        measurements:
+          type: array
+          minItems: 1
+          uniqueItems: true
+          items:
+            enum: [task-completion, time-on-task, navigation-errors, comprehension-accuracy, recovery-attempts, confidence, perceived-visual-quality]
+  rubric:
+    type: object
+    additionalProperties: false
+    required: [scale, categories]
+    properties:
+      scale:
+        type: object
+        additionalProperties: false
+        required: [minimum, maximum, anchors]
+        properties:
+          minimum:
+            const: 0
+          maximum:
+            const: 4
+          anchors:
+            type: object
+            additionalProperties: false
+            required: ["0", "1", "2", "3", "4"]
+            properties:
+              "0": { $ref: "#/$defs/shortText" }
+              "1": { $ref: "#/$defs/shortText" }
+              "2": { $ref: "#/$defs/shortText" }
+              "3": { $ref: "#/$defs/shortText" }
+              "4": { $ref: "#/$defs/shortText" }
+      categories:
+        type: array
+        minItems: 1
+        maxItems: 20
+        items:
+          type: object
+          additionalProperties: false
+          required: [id, label, weight, criteria]
+          properties:
+            id:
+              $ref: "#/$defs/id"
+            label:
+              $ref: "#/$defs/shortText"
+            weight:
+              type: integer
+              minimum: 1
+              maximum: 100
+            criteria:
+              type: array
+              minItems: 1
+              maxItems: 30
+              items:
+                type: object
+                additionalProperties: false
+                required: [id, prompt, measurement, evidenceLevel, scoreMinimum, scoreMaximum]
+                properties:
+                  id:
+                    $ref: "#/$defs/id"
+                  prompt:
+                    $ref: "#/$defs/text"
+                  measurement:
+                    enum: [rating, comprehension, task-observation]
+                  evidenceLevel:
+                    enum: [human-expert, representative-user]
+                  scoreMinimum:
+                    const: 0
+                  scoreMaximum:
+                    const: 4
+  evidencePolicy:
+    type: object
+    additionalProperties: false
+    required: [anonymizeCandidates, counterbalanceOrder, retainArtifacts, separateEvidenceLevels, requireHumanAttribution, prohibitAgentHumanAttestation]
+    properties:
+      anonymizeCandidates: { const: true }
+      counterbalanceOrder: { const: true }
+      retainArtifacts: { const: true }
+      separateEvidenceLevels: { const: true }
+      requireHumanAttribution: { const: true }
+      prohibitAgentHumanAttestation: { const: true }
+  decision:
+    type: object
+    additionalProperties: false
+    required: [minimumCategoryScore, requireAllStagesPass, prohibitContradictedClaims, requiredEvidenceLevels]
+    properties:
+      minimumCategoryScore:
+        type: number
+        minimum: 0
+        maximum: 4
+      requireAllStagesPass:
+        type: boolean
+      prohibitContradictedClaims:
+        type: boolean
+      requiredEvidenceLevels:
+        type: array
+        minItems: 1
+        maxItems: 4
+        uniqueItems: true
+        items:
+          $ref: "#/$defs/evidenceLevel"
+$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: 1024
+  preparedBy:
+    type: object
+    additionalProperties: false
+    required: [type, name]
+    properties:
+      type:
+        enum: [agent, human, mixed]
+      name:
+        $ref: "#/$defs/shortText"
+  evidenceLevel:
+    enum: [automated, ai-assisted-expert, human-expert, representative-user]
+  artifactKind:
+    enum: [build-report, typecheck-report, test-report, static-audit, runtime-report, journey-report, screenshot, export, source-inspection, human-review, user-session]
+  requiredItems:
+    type: array
+    minItems: 1
+    maxItems: 50
+    items:
+      type: object
+      additionalProperties: false
+      required: [id, label, required]
+      properties:
+        id:
+          $ref: "#/$defs/id"
+        label:
+          $ref: "#/$defs/shortText"
+        required:
+          type: boolean

package/knowledge-base/benchmarks/interface-quality/comparison-methodology.template.yaml

@@ -0,0 +1,181 @@
+version: "1.0"
+id: operational-interface-comparison-v1
+title: Anonymous operational interface quality comparison
+preparedAt: 2026-08-26T15:00:00+03:00
+preparedBy:
+  type: agent
+  name: ZtotheZ Design Engineering
+candidates:
+  - id: anonymous-a
+    label: Candidate A
+  - id: anonymous-b
+    label: Candidate B
+  - id: anonymous-c
+    label: Candidate C
+  - id: anonymous-d
+    label: Candidate D
+viewports:
+  - id: mobile
+    width: 375
+    height: 812
+  - id: tablet
+    width: 768
+    height: 1024
+  - id: desktop
+    width: 1024
+    height: 768
+  - id: wide
+    width: 1440
+    height: 1000
+states:
+  - id: initial
+    label: Initial product state
+    required: true
+  - id: loading
+    label: Analysis in progress
+    required: true
+  - id: result
+    label: Completed result
+    required: true
+  - id: fallback
+    label: Backend failure with disclosed fallback
+    required: true
+  - id: disconnected
+    label: Disconnected state
+    required: true
+  - id: export
+    label: Exported result with provenance
+    required: true
+stages:
+  - id: build
+    label: Production build
+    required: true
+    scope: candidate
+    evidenceKinds: [build-report]
+  - id: typecheck
+    label: Static type verification
+    required: true
+    scope: candidate
+    evidenceKinds: [typecheck-report]
+  - id: architecture-audit
+    label: Architecture and anti-slop audit
+    required: true
+    scope: candidate
+    evidenceKinds: [static-audit]
+  - id: browser-verification
+    label: Browser and responsive verification
+    required: true
+    scope: candidate
+    evidenceKinds: [runtime-report, screenshot]
+  - id: product-journeys
+    label: Product-specific journey verification
+    required: true
+    scope: candidate
+    evidenceKinds: [journey-report]
+  - id: human-review
+    label: Attributable human and representative-user review
+    required: true
+    scope: comparison
+    evidenceKinds: [human-review, user-session]
+tasks:
+  - id: identify-data-origin
+    prompt: Identify whether the displayed data is live, simulated, cached, imported, or unavailable.
+    successCriteria:
+      - Correctly identifies data origin and connection state.
+      - Locates freshness and environment information without documentation.
+    measurements: [task-completion, time-on-task, navigation-errors, comprehension-accuracy, confidence]
+  - id: identify-priority
+    prompt: Find the highest-priority problem and explain why it should be addressed first.
+    successCriteria:
+      - Selects the intended highest-priority finding.
+      - Identifies impact and supporting evidence.
+    measurements: [task-completion, time-on-task, navigation-errors, comprehension-accuracy, confidence]
+  - id: identify-next-action
+    prompt: Identify the recommended next action and how its success will be verified.
+    successCriteria:
+      - Locates the remediation action.
+      - Identifies the stated validation method.
+    measurements: [task-completion, time-on-task, navigation-errors, recovery-attempts, confidence]
+  - id: recognize-fallback
+    prompt: Start analysis and determine whether live processing or a fallback produced the result.
+    successCriteria:
+      - Correctly identifies the processing path.
+      - Finds the result-level limitation or provenance statement.
+    measurements: [task-completion, time-on-task, navigation-errors, comprehension-accuracy, confidence]
+  - id: verify-export-provenance
+    prompt: Export the result and verify that data origin, freshness, environment, and limitations are retained.
+    successCriteria:
+      - Completes the export.
+      - Correctly identifies all required provenance fields.
+    measurements: [task-completion, time-on-task, navigation-errors, comprehension-accuracy, confidence]
+rubric:
+  scale:
+    minimum: 0
+    maximum: 4
+    anchors:
+      "0": Absent, misleading, or unusable
+      "1": Present but materially deficient
+      "2": Functional and understandable
+      "3": Polished and consistently implemented
+      "4": Exceptional and supported by evidence
+  categories:
+    - id: truthful-disclosure
+      label: Truthful interface disclosure
+      weight: 30
+      criteria:
+        - id: disclosure-speed
+          prompt: Data origin, connection, environment, and freshness are identifiable without documentation.
+          measurement: comprehension
+          evidenceLevel: representative-user
+          scoreMinimum: 0
+          scoreMaximum: 4
+        - id: disclosure-consistency
+          prompt: Disclosure persists through action, result, history, fallback, error, and export states.
+          measurement: task-observation
+          evidenceLevel: human-expert
+          scoreMinimum: 0
+          scoreMaximum: 4
+    - id: information-design
+      label: Operational information design
+      weight: 35
+      criteria:
+        - id: priority-comprehension
+          prompt: Priority, impact, evidence, next action, and validation method form one understandable path.
+          measurement: comprehension
+          evidenceLevel: representative-user
+          scoreMinimum: 0
+          scoreMaximum: 4
+        - id: decision-density
+          prompt: Visible metrics and charts support identifiable decisions without decorative duplication.
+          measurement: rating
+          evidenceLevel: human-expert
+          scoreMinimum: 0
+          scoreMaximum: 4
+    - id: visual-polish
+      label: Visual hierarchy and polish
+      weight: 35
+      criteria:
+        - id: visual-rhythm
+          prompt: Spacing, alignment, typography, density, and emphasis appear intentional and coherent.
+          measurement: rating
+          evidenceLevel: human-expert
+          scoreMinimum: 0
+          scoreMaximum: 4
+        - id: responsive-composition
+          prompt: Composition remains balanced, legible, and task-focused at every required viewport.
+          measurement: task-observation
+          evidenceLevel: human-expert
+          scoreMinimum: 0
+          scoreMaximum: 4
+evidencePolicy:
+  anonymizeCandidates: true
+  counterbalanceOrder: true
+  retainArtifacts: true
+  separateEvidenceLevels: true
+  requireHumanAttribution: true
+  prohibitAgentHumanAttestation: true
+decision:
+  minimumCategoryScore: 3
+  requireAllStagesPass: true
+  prohibitContradictedClaims: true
+  requiredEvidenceLevels: [automated, ai-assisted-expert, human-expert, representative-user]

package/knowledge-base/benchmarks/interface-quality/evidence/example-runtime-report.json

@@ -0,0 +1,11 @@
+{
+  "version": "1.0",
+  "fixture": true,
+  "scope": "Synthetic comparison-template evidence only",
+  "viewport": {
+    "width": 375,
+    "height": 812
+  },
+  "state": "initial",
+  "result": "sampled"
+}