@ztothez/design-engineering 2.0.0

package/knowledge-base/benchmarks/corpus/cases/architecture-negative/src/OperationsPanel.tsx

@@ -0,0 +1,40 @@
+import { useEffect, useState } from "react";
+
+export function OperationsPanel() {
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState("");
+  const [result, setResult] = useState("");
+
+  useEffect(() => {
+    const stored = localStorage.getItem("operation-result");
+    if (stored) setResult(stored);
+  }, []);
+
+  async function runOperation() {
+    setLoading(true);
+    setError("");
+    try {
+      const response = await fetch("/api/run", { method: "POST" });
+      if (!response.ok) throw new Error("Request failed");
+      const body = await response.text();
+      localStorage.setItem("operation-result", body);
+      setResult(body);
+    } catch (caught) {
+      setError(caught instanceof Error ? caught.message : "Operation failed");
+    } finally {
+      setLoading(false);
+    }
+  }
+
+  return (
+    <main style={{ background: "#ffffff", color: "#111827", borderColor: "#0f766e" }}>
+      <h1>Operations</h1>
+      <p>{loading ? "Running" : "Ready"}</p>
+      {error ? <p role="alert">{error}</p> : null}
+      {result ? <pre>{result}</pre> : <p>No result yet</p>}
+      <button type="button" onClick={runOperation} disabled={loading}>
+        Run operation
+      </button>
+    </main>
+  );
+}

package/knowledge-base/benchmarks/corpus/cases/architecture-positive/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "architecture-positive",
+  "private": true,
+  "scripts": {
+    "build": "echo build",
+    "test": "echo test",
+    "typecheck": "echo typecheck"
+  }
+}

package/knowledge-base/benchmarks/corpus/cases/architecture-positive/src/Dashboard.tsx

@@ -0,0 +1,17 @@
+import "./theme.css";
+
+type DashboardProps = {
+  completed: number;
+  total: number;
+  onRefresh: () => void;
+};
+
+export function Dashboard({ completed, total, onRefresh }: DashboardProps) {
+  return (
+    <main>
+      <h1>Validation overview</h1>
+      <p>{completed} of {total} checks completed</p>
+      <button type="button" onClick={onRefresh}>Refresh validation</button>
+    </main>
+  );
+}

package/knowledge-base/benchmarks/corpus/cases/architecture-positive/src/theme.css

@@ -0,0 +1,15 @@
+:root {
+  --surface-canvas: #ffffff;
+  --text-primary: #111827;
+  --action-primary: #075985;
+}
+
+body {
+  background: var(--surface-canvas);
+  color: var(--text-primary);
+}
+
+button {
+  background: var(--action-primary);
+  color: var(--surface-canvas);
+}

package/knowledge-base/benchmarks/corpus/cases/task-incomplete/SOURCE-EVIDENCE.md

@@ -0,0 +1,3 @@
+# Synthetic Source Evidence
+
+This deliberately incomplete contract is project-owned test data. It contains structurally valid declarations with broken cross-references so the corpus can verify deterministic rejection.

package/knowledge-base/benchmarks/corpus/cases/task-incomplete/journeys.json

@@ -0,0 +1,20 @@
+{
+  "version": "1.0",
+  "contract": "incomplete-product",
+  "profiles": [
+    {
+      "id": "primary-flow",
+      "name": "Primary flow",
+      "environment": ["Local fixture is available"],
+      "journeys": [
+        {
+          "id": "complete-task",
+          "name": "complete-task",
+          "steps": [
+            { "action": "expectVisible", "selector": "main" }
+          ]
+        }
+      ]
+    }
+  ]
+}

package/knowledge-base/benchmarks/corpus/cases/task-incomplete/product-contract.yaml

@@ -0,0 +1,78 @@
+version: "1.0"
+id: incomplete-product
+name: Incomplete Product Fixture
+status: benchmark
+purpose: Verify that broken product-task references are rejected instead of accepted as complete.
+authority:
+  behavior: The synthetic source evidence defines this controlled fixture.
+  visual: Task and state integrity override decoration.
+  precedence:
+    - path: SOURCE-EVIDENCE.md
+      role: Synthetic fixture declaration
+      authority: primary
+actors:
+  - id: operator
+    name: Operator
+    goals: [Complete one bounded task]
+    responsibilities: [Review the resulting evidence]
+modes:
+  - id: primary
+    name: Primary
+    purpose: Complete the bounded task.
+    input: Valid local input.
+    outputs: [missing-output]
+stateMachines:
+  - id: task
+    initial: idle
+    states:
+      - id: idle
+        category: idle
+        userVisible: true
+        requirement: Input remains editable.
+      - id: complete
+        category: success
+        userVisible: true
+        requirement: Result evidence is visible.
+    transitions:
+      - from: idle
+        to: missing-state
+        trigger: Submit valid input
+outputs:
+  - id: result
+    name: Result
+    sourceOfTruth: Current validated task state.
+    requiredEvidence: [Structured result]
+metrics:
+  - id: completion
+    name: Completion
+    definition: Whether the current task reached its validated terminal state.
+    sourceOfTruth: Current state machine.
+    format: status
+    evidenceRequired: true
+constraints:
+  outOfScope: [Unrelated workflows]
+  prohibitedClaims: [Completion without current evidence]
+  mockData:
+    allowedEnvironments: [test]
+    mustBeLabeled: true
+    prohibitedInProduction: true
+    fallbackDisclosure: Test data must remain visibly labeled.
+acceptanceCriteria:
+  - id: complete-current-task
+    title: Complete current task
+    severity: blocker
+    requirement: The current task reaches a terminal state with evidence.
+    evidence: [contract, runtime]
+    appliesToModes: [missing-mode]
+verification:
+  journeyFile: journeys.json
+  viewports:
+    - name: desktop
+      width: 1280
+      height: 800
+  bindings:
+    - profile: primary-flow
+      journey: complete-task
+      actor: missing-actor
+      mode: primary
+      acceptanceCriteria: [missing-criterion]

package/knowledge-base/benchmarks/corpus/corpus.schema.yaml

@@ -0,0 +1,159 @@
+$schema: https://json-schema.org/draft/2020-12/schema
+$id: https://ztothez.dev/schemas/corpus-benchmark-1.0.schema.json
+title: ZtotheZ Design Engineering Corpus Benchmark
+type: object
+additionalProperties: false
+required: [version, id, description, thresholds, sources, cases]
+properties:
+  version:
+    const: "1.0"
+  id:
+    $ref: "#/$defs/id"
+  description:
+    type: string
+    minLength: 1
+    maxLength: 1024
+  thresholds:
+    type: object
+    additionalProperties: false
+    required: [overallMinimumScore, dimensions]
+    properties:
+      overallMinimumScore:
+        type: number
+        minimum: 0
+        maximum: 1
+      dimensions:
+        type: object
+        additionalProperties: false
+        required:
+          - recommendation-relevance
+          - abstention
+          - architectural-integrity
+          - task-completeness
+          - anti-slop-rejection
+        properties:
+          recommendation-relevance: { $ref: "#/$defs/threshold" }
+          abstention: { $ref: "#/$defs/threshold" }
+          architectural-integrity: { $ref: "#/$defs/threshold" }
+          task-completeness: { $ref: "#/$defs/threshold" }
+          anti-slop-rejection: { $ref: "#/$defs/threshold" }
+  sources:
+    type: array
+    minItems: 1
+    items:
+      type: object
+      additionalProperties: false
+      required: [id, title, origin, owner, license, evidence, redistribution]
+      properties:
+        id: { $ref: "#/$defs/id" }
+        title: { type: string, minLength: 1, maxLength: 256 }
+        origin: { enum: [user-owned, licensed-standard] }
+        owner: { type: string, minLength: 1, maxLength: 256 }
+        license: { type: string, minLength: 1, maxLength: 128 }
+        sourceUrl: { type: string, format: uri }
+        evidence: { $ref: "#/$defs/path" }
+        redistribution: { type: string, minLength: 1, maxLength: 512 }
+  cases:
+    type: array
+    minItems: 5
+    items:
+      oneOf:
+        - $ref: "#/$defs/retrievalCase"
+        - $ref: "#/$defs/auditCase"
+        - $ref: "#/$defs/contractCase"
+$defs:
+  id:
+    type: string
+    pattern: "^[a-z0-9][a-z0-9-]{0,63}$"
+  path:
+    type: string
+    minLength: 1
+    maxLength: 1024
+  threshold:
+    type: object
+    additionalProperties: false
+    required: [minimumScore]
+    properties:
+      minimumScore: { type: number, minimum: 0, maximum: 1 }
+      minimumMeanReciprocalRank: { type: number, minimum: 0, maximum: 1 }
+  caseBase:
+    type: object
+    required: [id, kind, dimension, polarity, source, derivation, expected]
+    properties:
+      id: { $ref: "#/$defs/id" }
+      polarity: { enum: [positive, negative] }
+      source: { $ref: "#/$defs/id" }
+      derivation: { type: string, minLength: 1, maxLength: 1024 }
+  retrievalCase:
+    allOf:
+      - $ref: "#/$defs/caseBase"
+      - type: object
+        additionalProperties: false
+        required: [id, kind, dimension, polarity, source, derivation, query, expected]
+        properties:
+          id: { $ref: "#/$defs/id" }
+          kind: { const: retrieval }
+          dimension: { enum: [recommendation-relevance, abstention] }
+          polarity: { enum: [positive, negative] }
+          source: { $ref: "#/$defs/id" }
+          derivation: { type: string, minLength: 1, maxLength: 1024 }
+          query: { type: string, minLength: 1, maxLength: 512 }
+          categories:
+            type: array
+            minItems: 1
+            maxItems: 10
+            items: { type: string }
+          expected:
+            type: object
+            additionalProperties: false
+            required: [status]
+            properties:
+              status: { enum: [matches, no-match] }
+              path: { $ref: "#/$defs/path" }
+              maxRank: { type: integer, minimum: 1, maximum: 20 }
+  auditCase:
+    allOf:
+      - $ref: "#/$defs/caseBase"
+      - type: object
+        additionalProperties: false
+        required: [id, kind, dimension, polarity, source, derivation, target, expected]
+        properties:
+          id: { $ref: "#/$defs/id" }
+          kind: { const: audit }
+          dimension: { enum: [architectural-integrity, anti-slop-rejection] }
+          polarity: { enum: [positive, negative] }
+          source: { $ref: "#/$defs/id" }
+          derivation: { type: string, minLength: 1, maxLength: 1024 }
+          target: { $ref: "#/$defs/path" }
+          policy: { type: object }
+          expected:
+            type: object
+            additionalProperties: false
+            required: [verdict]
+            properties:
+              verdict: { enum: [accept, reject] }
+              requiredRuleIds: { type: array, items: { type: string } }
+              forbiddenRuleIds: { type: array, items: { type: string } }
+              maximumFindings: { type: integer, minimum: 0 }
+  contractCase:
+    allOf:
+      - $ref: "#/$defs/caseBase"
+      - type: object
+        additionalProperties: false
+        required: [id, kind, dimension, polarity, source, derivation, contract, expected]
+        properties:
+          id: { $ref: "#/$defs/id" }
+          kind: { const: contract }
+          dimension: { const: task-completeness }
+          polarity: { enum: [positive, negative] }
+          source: { $ref: "#/$defs/id" }
+          derivation: { type: string, minLength: 1, maxLength: 1024 }
+          contract: { $ref: "#/$defs/path" }
+          expected:
+            type: object
+            additionalProperties: false
+            required: [verdict]
+            properties:
+              verdict: { enum: [accept, reject] }
+              requiredIssueCodes: { type: array, items: { type: string } }
+              forbiddenIssueCodes: { type: array, items: { type: string } }

package/knowledge-base/benchmarks/corpus/corpus.yaml

@@ -0,0 +1,209 @@
+version: "1.0"
+id: ztothez-design-engineering-core-corpus
+description: Deterministic positive and negative cases for approved retrieval, architecture integrity, task completeness, and anti-slop enforcement.
+
+thresholds:
+  overallMinimumScore: 1
+  dimensions:
+    recommendation-relevance:
+      minimumScore: 1
+      minimumMeanReciprocalRank: 0.75
+    abstention:
+      minimumScore: 1
+    architectural-integrity:
+      minimumScore: 1
+    task-completeness:
+      minimumScore: 1
+    anti-slop-rejection:
+      minimumScore: 1
+
+sources:
+  - id: ztothez-corpus-fixtures
+    title: ZtotheZ independently authored corpus fixtures
+    origin: user-owned
+    owner: ZtotheZ
+    license: ISC
+    evidence: knowledge-base/benchmarks/corpus/PROVENANCE.md
+    redistribution: Synthetic cases are project-owned and distributable under the repository license.
+  - id: aegisops-product
+    title: AegisOPS product benchmark
+    origin: user-owned
+    owner: ZtotheZ
+    license: owner-authorized benchmark use
+    evidence: knowledge-base/benchmarks/aegisops/SOURCE-EVIDENCE.md
+    redistribution: The maintained contract and evidence summary are approved for this repository and package.
+  - id: scenestart-product
+    title: SceneStart product benchmark
+    origin: user-owned
+    owner: ZtotheZ
+    license: owner-authorized benchmark use
+    evidence: knowledge-base/benchmarks/scenestart/SOURCE-EVIDENCE.md
+    redistribution: The maintained contract and evidence summary are approved for this repository and package.
+  - id: w3c-wcag-22
+    title: Web Content Accessibility Guidelines 2.2
+    origin: licensed-standard
+    owner: World Wide Web Consortium
+    license: W3C Document License 2015
+    sourceUrl: https://www.w3.org/TR/WCAG22/
+    evidence: knowledge-base/benchmarks/corpus/PROVENANCE.md
+    redistribution: No specification text is redistributed; the case records an independently authored query and local expected path.
+
+cases:
+  - id: relevance-brand-contract
+    kind: retrieval
+    dimension: recommendation-relevance
+    polarity: positive
+    source: ztothez-corpus-fixtures
+    derivation: Original query based on the maintained brand-system deliverable contract.
+    query: brand mark clear space minimum size allowed backgrounds promise voice principles
+    categories: [design-intelligence]
+    expected:
+      status: matches
+      path: knowledge-base/design-intelligence/brand-systems.md
+      maxRank: 2
+
+  - id: relevance-figma-production
+    kind: retrieval
+    dimension: recommendation-relevance
+    polarity: positive
+    source: ztothez-corpus-fixtures
+    derivation: Original query based on the maintained Figma production workflow.
+    query: Figma variable collections modes component properties interactive states documentation
+    categories: [design-intelligence]
+    expected:
+      status: matches
+      path: knowledge-base/design-intelligence/figma-production.md
+      maxRank: 2
+
+  - id: relevance-generated-asset-provenance
+    kind: retrieval
+    dimension: recommendation-relevance
+    polarity: positive
+    source: ztothez-corpus-fixtures
+    derivation: Original query based on the maintained generated-asset provenance contract.
+    query: generated asset provider model prompt record human contributions reference rights provenance
+    categories: [design-intelligence]
+    expected:
+      status: matches
+      path: knowledge-base/design-intelligence/asset-generation.md
+      maxRank: 2
+
+  - id: relevance-accessible-color
+    kind: retrieval
+    dimension: recommendation-relevance
+    polarity: positive
+    source: w3c-wcag-22
+    derivation: Independently authored conformance query derived from WCAG contrast and use-of-color concepts without copied normative text.
+    query: normal text contrast ratio non-color status cues semantic tokens
+    categories: [design-intelligence]
+    expected:
+      status: matches
+      path: knowledge-base/design-intelligence/visual-accessibility.md
+      maxRank: 2
+
+  - id: abstain-unknown-proprietary-catalog
+    kind: retrieval
+    dimension: abstention
+    polarity: negative
+    source: ztothez-corpus-fixtures
+    derivation: Synthetic out-of-scope identifier that must not trigger archive fallback.
+    query: qzvorn proprietary nebula catalog 8841
+    categories: [design-intelligence]
+    expected:
+      status: no-match
+
+  - id: abstain-unrelated-domain
+    kind: retrieval
+    dimension: abstention
+    polarity: negative
+    source: ztothez-corpus-fixtures
+    derivation: Synthetic unrelated-domain query used to verify explicit abstention.
+    query: cryogenic turbine bearing alloy phase diagram zxqv
+    categories: [design-intelligence]
+    expected:
+      status: no-match
+
+  - id: architecture-clean-boundaries
+    kind: audit
+    dimension: architectural-integrity
+    polarity: positive
+    source: ztothez-corpus-fixtures
+    derivation: Small project-owned component with semantic tokens, accessible controls, and explicit repository scripts.
+    target: knowledge-base/benchmarks/corpus/cases/architecture-positive
+    expected:
+      verdict: accept
+      maximumFindings: 0
+      forbiddenRuleIds: [ZTDE-ARCH-001, ZTDE-ARCH-002, ZTDE-DESIGN-001]
+
+  - id: architecture-mixed-monolith
+    kind: audit
+    dimension: architectural-integrity
+    polarity: negative
+    source: ztothez-corpus-fixtures
+    derivation: Project-owned rejection fixture combining a large render surface, persistence and network orchestration, and repeated raw colors.
+    target: knowledge-base/benchmarks/corpus/cases/architecture-negative
+    policy:
+      componentLineWarning: 20
+      mixedResponsibilitiesMinLines: 20
+      rawColorWarningCount: 3
+    expected:
+      verdict: reject
+      requiredRuleIds: [ZTDE-ARCH-001, ZTDE-ARCH-002, ZTDE-DESIGN-001]
+      forbiddenRuleIds: [ZTDE-SLOP-001, ZTDE-SLOP-002]
+
+  - id: task-aegisops-complete
+    kind: contract
+    dimension: task-completeness
+    polarity: positive
+    source: aegisops-product
+    derivation: Maintained owner-authorized product contract and journeys.
+    contract: knowledge-base/benchmarks/aegisops/product-contract.yaml
+    expected:
+      verdict: accept
+      forbiddenIssueCodes: [CONTRACT-SCHEMA, CONTRACT-UNKNOWN-REFERENCE]
+
+  - id: task-scenestart-complete
+    kind: contract
+    dimension: task-completeness
+    polarity: positive
+    source: scenestart-product
+    derivation: Maintained owner-authorized product contract and journeys from a second operational domain.
+    contract: knowledge-base/benchmarks/scenestart/product-contract.yaml
+    expected:
+      verdict: accept
+      forbiddenIssueCodes: [CONTRACT-SCHEMA, CONTRACT-UNKNOWN-REFERENCE]
+
+  - id: task-broken-references
+    kind: contract
+    dimension: task-completeness
+    polarity: negative
+    source: ztothez-corpus-fixtures
+    derivation: Synthetic contract with valid structure but unknown outputs, states, modes, actors, and criteria.
+    contract: knowledge-base/benchmarks/corpus/cases/task-incomplete/product-contract.yaml
+    expected:
+      verdict: reject
+      requiredIssueCodes: [CONTRACT-UNKNOWN-REFERENCE]
+      forbiddenIssueCodes: [CONTRACT-PARSE]
+
+  - id: anti-slop-functional-surface
+    kind: audit
+    dimension: anti-slop-rejection
+    polarity: positive
+    source: ztothez-corpus-fixtures
+    derivation: Project-owned surface with derived metrics and functional controls.
+    target: knowledge-base/benchmarks/corpus/cases/anti-slop-positive
+    expected:
+      verdict: accept
+      maximumFindings: 0
+      forbiddenRuleIds: [ZTDE-SLOP-001, ZTDE-SLOP-002]
+
+  - id: anti-slop-mock-and-placeholder
+    kind: audit
+    dimension: anti-slop-rejection
+    polarity: negative
+    source: ztothez-corpus-fixtures
+    derivation: Project-owned rejection fixture containing a simulated production result and a nonfunctional navigation control.
+    target: knowledge-base/benchmarks/corpus/cases/anti-slop-negative
+    expected:
+      verdict: reject
+      requiredRuleIds: [ZTDE-SLOP-001, ZTDE-SLOP-002]

package/knowledge-base/benchmarks/interface-quality/README.md

@@ -0,0 +1,26 @@
+# Interface Quality Comparison
+
+This directory defines the versioned method used to compare truthful disclosure, information design, visual polish, and task performance across anonymized interface candidates.
+
+## Workflow
+
+1. Copy `comparison-methodology.template.yaml` for V1 evidence-integrity checks, or implement `comparison-methodology-v1.1.schema.yaml` when complete human matrices and target-versus-comparator decisions are required.
+2. Keep candidate labels anonymous. Store any identity mapping outside reviewer-facing artifacts.
+3. Copy `review.template.yaml` and record retained automated artifacts, required-stage outcomes, reviewer-supplied sessions, task observations, ratings, and structured claims.
+4. Run `npm run validate-comparison -- --methodology PATH --review PATH`.
+5. For V1.1, configure minimum expert and user sessions, complete matrices, counterbalanced orders, required-stage candidates, the anonymous target, comparators, required categories, and task non-regression.
+6. Keep session envelopes compatible with `review-session.schema.yaml`. Store reviewer-supplied files inside the review evidence root with top-level `status: complete`, then run `npm run compile-comparison -- --methodology PATH --base-review PATH --sessions DIRECTORY --output PATH`.
+7. Treat `passed` as evidence-integrity validation. Read `humanReview.requirementsMet` and `benchmarkDecision.passed` independently. Treat `releaseReady` as the combined decision requiring every configured gate.
+
+## Evidence Boundary
+
+- Automated evidence proves only the rendered, compiled, network, contract, or journey facts it measured.
+- AI-assisted expert evidence records an agent's reasoned inspection and cannot become human evidence through formatting.
+- Human-expert evidence requires reviewer-supplied contributor and timestamp metadata.
+- Representative-user evidence requires reviewer-supplied attribution, a pseudonymous participant identifier, and observed task results.
+- Pixel differences detect change, not quality. A changed screenshot baseline requires functional evidence and attributable review.
+- A passing schema does not establish that a claim is true. Every verified claim needs retained evidence whose scope matches the claim.
+- A score matrix is complete only when every required candidate-task and candidate-criterion cell is present at the correct evidence level. `not-run` is evidence of non-completion, not permission to omit a cell.
+- Benchmark release requires the anonymous target to meet the category floor, equal or exceed every configured comparator category, and avoid configured task-metric regression.
+
+The templates contain no fabricated human sessions. They are expected to be structurally valid and not release-ready until real review evidence is supplied.

package/knowledge-base/benchmarks/interface-quality/SOLO-MAINTAINER-TRACK.md

@@ -0,0 +1,35 @@
+# Solo-Maintainer Validation Track
+
+Use this track when an attributed project maintainer can perform expert inspection but independent experts or representative users are not currently available. It authorizes continued engineering only. It does not establish independent preference, representative-user comprehension, statistical confidence, or external release approval.
+
+## Required Evidence
+
+1. Preserve the anonymous comparison methodology and external release thresholds unchanged.
+2. Record the maintainer review as `human-expert` and `reviewer-supplied`.
+3. Disclose candidate exposure, identity knowledge, and conflicts accurately.
+4. Score every human-expert criterion for every candidate with an observable rationale.
+5. Preserve the completed source session and checksum through `compile-comparison`.
+6. Require all target build, typecheck, architecture-audit, browser-verification, and product-journey stages to pass.
+7. Require the target to meet the configured category floor and equal or exceed the configured comparator for every maintainer-scored category.
+
+## Allowed Claim
+
+When the assessment passes, report:
+
+```text
+Engineering may proceed under attributed solo-maintainer review. Independent human and representative-user validation remains pending.
+```
+
+Do not replace this with claims such as `human validated`, `user tested`, `preferred by users`, `externally approved`, or `release validated`.
+
+## Command
+
+```bash
+npm run assess-maintainer -- \
+  --methodology knowledge-base/benchmarks/azure-optimizer/v2-human-review-methodology.yaml \
+  --review evidence/interface-quality/azure-v2-review/review.completed.yaml \
+  --output evidence/interface-quality/azure-v2-review/maintainer-assessment.json \
+  --require-engineering-ready
+```
+
+The generated report deliberately separates `engineeringReady`, `externalReleaseReady`, and `externalValidationPending`.