@ztothez/design-engineering 2.0.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 ZtotheZ
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
+SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION
+OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
+CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,448 @@
+# ZtotheZ Design Engineering System
+
+[![Quality](https://github.com/ztothez/ztothez-design-engineering/actions/workflows/quality.yml/badge.svg)](https://github.com/ztothez/ztothez-design-engineering/actions/workflows/quality.yml)
+
+ZtotheZ Design Engineering is a local-first Agent Skill, MCP server, and deterministic quality gate for building production UI and UX systems. It combines product semantics, software architecture, usability evaluation, browser verification, and evidence-backed acceptance criteria.
+
+This project focuses on design engineering instead of style recommendation. It checks whether an interface supports real tasks, exposes coherent states, uses maintainable component boundaries, remains accessible, and produces verifiable evidence.
+
+## Current Capabilities
+
+- Production-ready Agent Skill in [`SKILL.md`](SKILL.md).
+- Scoped MCP access to architecture, Figma, design-system, UX-pattern, and usability guidance.
+- Independently authored brand, Figma production, asset-generation, iconography, presentation, licensing, and visual-accessibility modules.
+- Versioned product design briefs that block generation when users, tasks, data behavior, recovery, assumptions, or acceptance evidence are materially undefined.
+- Versioned design-deliverable manifests with deterministic visual direction, semantic token, typography, composition, density, state, motion, chart, rendered-evidence, contrast, provenance, icon, and presentation validation.
+- Versioned interface-trust contracts for data mode, connection, result origin, freshness, fallback disclosure, and provenance-preserving records.
+- Versioned operational information-design contracts for decision metrics, evidence-backed findings, chart purpose, hierarchy, exceptional states, and scalable collections.
+- A bounded nine-stage interface workflow linking product task, truthful state, information hierarchy, interaction states, visual direction, semantic tokens, implementation, automated evidence, and attributable human review.
+- Repository architecture audits for coupling, component size, raw design values, mock production paths, network states, accessible names, and placeholder interactions.
+- Structured heuristic reviews with evidence provenance and severity-based acceptance candidates.
+- Browser verification for responsive layout, clipping, overlap, focus, contrast, target sizing, keyboard behavior, text resizing, reflow, reduced motion, media, console errors, and network failures.
+- Opt-in V2 browser contracts for persistent data-mode disclosure, trust-stage and fixture-state coverage, chart names and alternatives, masked dynamic regions, and checksum-based screenshot regression detection.
+- Product contracts with declarative task journeys and acceptance criteria.
+- Consolidated quality gates and multi-profile release decisions.
+- Executable AegisOPS and SceneStart benchmark contracts.
+- Versioned positive and negative corpus benchmarks with provenance, per-dimension scoring, recommendation MRR, and explicit abstention checks.
+- Exact provenance and dependency inventories with active-reference isolation checks.
+- A self-contained offline runtime with approved knowledge, a serialized retrieval index, production dependencies, and SHA-256 integrity evidence.
+- GitHub Actions verification with retained fixture evidence.
+- A local-only portfolio registry and disposable snapshot boundary for non-destructive cross-product benchmarking.
+
+Ranked BM25 knowledge retrieval and exact filename reads are available now. The versioned retrieval scope contains only explicitly approved distributable files and excludes local raw research and legacy archives.
+
+## Requirements
+
+- Node.js 22 or newer
+- npm
+- Chromium for browser verification
+- Linux, macOS, or Windows with a Chromium executable supported by Playwright
+
+## Quick Start
+
+```bash
+git clone https://github.com/ztothez/ztothez-design-engineering.git
+cd ztothez-design-engineering
+npm ci
+npx --no-install playwright-core install chromium
+npm run build
+npm test
+```
+
+Build, install, and verify the distributable package:
+
+```bash
+npm run package:smoke
+npm run release:pack
+npm run release:check
+npm install -g ./.ztothez-design-release/ztothez-design-engineering-2.0.0.tgz
+zz-design --version
+```
+
+See [`docs/installation.md`](docs/installation.md) for source and package installation plus exact setup for Codex, Claude Code, Cursor, Windsurf, Antigravity, GitHub Copilot, Kiro, Qoder, and Lovable.
+
+Start the stdio MCP server:
+
+```bash
+npm start
+```
+
+The server writes diagnostics to standard error. Standard output remains reserved for MCP JSON-RPC messages.
+
+## MCP Configuration
+
+Build the project first, then register the compiled entrypoint as a stdio MCP server. Use absolute paths in agent configuration files.
+
+```json
+{
+  "mcpServers": {
+    "ztothez-design-engineering": {
+      "command": "node",
+      "args": [
+        "/absolute/path/to/ztothez-design-engineering/dist/cli/index.js"
+      ],
+      "env": {
+        "ZTOTHEZ_DESIGN_ENGINEERING_ROOT": "/absolute/path/to/ztothez-design-engineering"
+      }
+    }
+  }
+}
+```
+
+Use the equivalent stdio MCP fields in Claude Code, Cursor, Windsurf, Antigravity, GitHub Copilot, Kiro, Codex, Qoder, or another MCP-capable environment. Lovable Desktop can register the same executable as a custom local MCP server.
+
+The package declares two equivalent MCP executable names:
+
+- `ztothez-design`
+- `zz-design`
+
+The release archive is checked against an explicit distribution allowlist and installed into an empty temporary project during `npm run package:smoke`. Raw research and historical sources are not included. `npm run release:check` verifies the offline runtime, checksums, approved retrieval index, and launch path without using the repository's installed packages.
+
+## MCP Tools
+
+| Tool | Purpose |
+|---|---|
+| `search_design_knowledge` | Search approved knowledge with deterministic BM25 ranking, source paths, excerpts, confidence, and explicit no-match output. |
+| `evaluate_corpus_benchmark` | Score maintained positive and negative cases for retrieval, abstention, architecture, task completeness, and anti-slop behavior. |
+| `get_architecture_spec` | List or read approved architecture guidance. |
+| `get_figma_system_rules` | List or read Figma and design-system guidance. |
+| `get_design_intelligence` | List or read maintained brand, asset, icon, presentation, licensing, and visual-accessibility modules. |
+| `validate_product_design_brief` | Validate evidence-backed product intent, primary audiences, outcomes, tasks, data, states, assumptions, requirements, and generation readiness. |
+| `compile_design_plan` | Deterministically compile a valid brief into traceable architecture, contract, token, responsive, asset, stage, and verification decisions. |
+| `validate_design_deliverable` | Validate visual polish, semantic tokens, responsive composition, states, motion, charts, evidence readiness, contrast, provenance, icons, and presentations. |
+| `validate_interface_trust` | Validate operational claims, source traceability, fallback and stale states, disconnected recovery, and history or export provenance. |
+| `validate_information_design` | Validate metrics, findings, chart decisions, value states, large collections, operational hierarchy, and answer-flow tasks. |
+| `evaluate_interface_comparison` | Validate anonymous comparison methods, required stages, retained claim evidence, and attributable human or representative-user records. |
+| `get_dashboard_pattern` | List or read approved dashboard and UX patterns. |
+| `get_usability_evaluation` | List or read usability-evaluation guidance and schemas. |
+| `validate_product_contract` | Validate a product archetype, primary tasks, recovery states, narrow paths, sources, journeys, and cross-references. |
+| `evaluate_heuristic_review` | Validate a structured review and derive candidates from unresolved severity 3 and 4 findings. |
+| `audit_repository_architecture` | Scan a repository against deterministic architecture and anti-slop rules. |
+| `verify_ui_runtime` | Run browser checks and capture runtime evidence. |
+| `run_design_quality_gate` | Combine contract, audit, runtime, acceptance, and human evidence into one decision. |
+| `aggregate_design_quality_gates` | Combine required journey-profile reports into a release decision. |
+| `list_portfolio_projects` | List explicitly enabled local benchmark IDs and effective capabilities without source roots. |
+| `get_portfolio_benchmark_report` | Read a completed local benchmark summary without starting commands. |
+
+Knowledge tools enforce category boundaries, Markdown-only reads, file-size limits, and path-traversal protection. `SKILL.md` remains authoritative when supporting documents conflict.
+
+Search before opening deep reference files:
+
+```text
+Call search_design_knowledge with:
+query: "semantic design tokens for operational status states"
+categories: ["skill", "design-intelligence", "architecture"]
+limit: 5
+```
+
+The search index is defined by `knowledge-base/retrieval-scope.yaml`. A no-match response is a valid result. Do not replace it with content from ignored research or legacy archives.
+
+## Command Line Workflows
+
+Validate and inventory the ignored local portfolio registry:
+
+```bash
+zz-design portfolio validate-registry
+zz-design portfolio inventory
+```
+
+Create, verify, and delete a disposable snapshot without running a command in the original project:
+
+```bash
+zz-design portfolio snapshot --project scenestart
+```
+
+Use `--keep` only when an isolated adapter needs the snapshot for a later local stage. The local
+registry lives at `.ztothez-design-local/portfolio-registry.yaml`; snapshots live under
+`.ztothez-design-benchmarks/`. Both are excluded from Git and package output. Linux executable
+stages use Bubblewrap and fail closed when process isolation is unavailable.
+
+Run a complete isolated baseline or cohort and verify source integrity:
+
+```bash
+zz-design portfolio baseline --project scenestart --run scenestart-baseline
+zz-design portfolio benchmark --cohort development --run development-001
+zz-design portfolio verify-unchanged --run development-001
+zz-design portfolio report --run development-001
+```
+
+Projects with a declared static fixture and product contract also run browser journeys, the
+consolidated quality gate, optional heuristic review, and checksummed artifact capture.
+
+Audit a repository:
+
+```bash
+npm run audit -- --repo PATH_TO_APPLICATION --fail-on error
+```
+
+Validate a product contract:
+
+```bash
+npm run validate-contract -- \
+  --contract knowledge-base/benchmarks/aegisops/product-contract.yaml \
+  --project-root .
+```
+
+Evaluate a heuristic review:
+
+```bash
+npm run review-heuristics -- \
+  --review knowledge-base/usability-evaluation/heuristic-review.template.yaml
+```
+
+Validate a product design brief before planning generation:
+
+```bash
+npm run validate-brief -- \
+  --brief knowledge-base/design-intelligence/product-design-brief.template.yaml
+```
+
+The installed CLI provides the same report with `zz-design validate-brief --brief PATH`.
+
+Compile the validated brief into a deterministic, traceable design plan:
+
+```bash
+npm run compile-plan -- \
+  --brief knowledge-base/design-intelligence/product-design-brief.template.yaml \
+  --project-root . \
+  --json
+```
+
+The installed CLI equivalent is `zz-design compile-plan`. Planned downstream contracts remain
+provisional rather than being reported as implementation-ready.
+
+Generate a new independent React and TypeScript fixture from a ready plan:
+
+```bash
+mkdir -p .ztothez-design-generated
+zz-design generate-react \
+  --plan path/to/ready-design-plan.json \
+  --generation-root .ztothez-design-generated \
+  --output .ztothez-design-generated/example-app \
+  --portfolio-registry .ztothez-design-local/portfolio-registry.yaml \
+  --json
+```
+
+The output directory must not exist. Generation fails when the plan is not implementation-ready,
+the registry is invalid, a path is symlinked or escaping, or the target overlaps a read-only
+portfolio root. Version 1.0 creates a new independent fixture only; it does not patch an existing
+repository. See `knowledge-base/design-intelligence/generation-adapter.md`.
+
+Repair one supported finding in a generated fixture with retained before and after evidence:
+
+```bash
+zz-design repair-react \
+  --request path/to/repair-request.yaml \
+  --generation-root .ztothez-design-generated \
+  --target .ztothez-design-generated/example-app \
+  --portfolio-registry .ztothez-design-local/portfolio-registry.yaml \
+  --contract knowledge-base/benchmarks/aegisops/product-contract.yaml \
+  --project-root . \
+  --url http://127.0.0.1:4173 \
+  --profile responsive-overview \
+  --output .ztothez-design-repair/example \
+  --fail-on warning
+```
+
+The URL must be loopback and already running. Repairs are limited to exact, digest-bound
+replacements in generation-manifest-owned files. Repeated or failed verification restores the
+original target and produces an unresolved report. See
+`knowledge-base/design-intelligence/closed-loop-repair.md`.
+
+For a versioned browser task contract, `knowledge-base/design-intelligence/interaction-recovery-verification.md`
+adds retained start, success, failure, preserved-state, keyboard, export, and offline checkpoints.
+Only states declared applicable by the task and data model are verified; unsupported automation remains
+an explicit limitation.
+
+Validate a design-intelligence deliverable:
+
+```bash
+npm run validate-design -- \
+  --manifest knowledge-base/design-intelligence/design-deliverable.template.yaml
+```
+
+Verify an instrumented interface across the maintained responsive matrix and both implemented
+themes:
+
+```bash
+npm run verify-ui -- --url http://127.0.0.1:4173 --color-schemes light,dark
+```
+
+Composition verification is opt-in through `data-ztothez-design-composition="1.0"`. It checks
+decision order, action and region limits, status meaning, evidence-backed visual claims, rendered
+focus, state and chart contrast, and asset metadata without prescribing a universal style.
+
+Validate interface trust and data provenance:
+
+```bash
+npm run validate-trust -- \
+  --contract knowledge-base/design-intelligence/interface-trust.template.yaml
+```
+
+Validate operational information design:
+
+```bash
+npm run validate-information -- \
+  --contract knowledge-base/design-intelligence/information-design.template.yaml
+```
+
+Validate an interface comparison and require complete release evidence:
+
+```bash
+npm run validate-comparison -- \
+  --methodology knowledge-base/benchmarks/interface-quality/comparison-methodology.template.yaml \
+  --review knowledge-base/benchmarks/interface-quality/review.template.yaml \
+  --require-release-ready
+```
+
+Omit `--require-release-ready` while preparing an honest incomplete review. Structural validation can pass while the release decision remains blocked by missing stages or evidence classes.
+
+Compile only reviewer-supplied sessions marked `complete`:
+
+```bash
+npm run compile-comparison -- \
+  --methodology knowledge-base/benchmarks/azure-optimizer/v2-human-review-methodology.yaml \
+  --base-review evidence/interface-quality/azure-v2-review/review.yaml \
+  --sessions evidence/interface-quality/azure-v2-review/reviewer-packet/completed-sessions \
+  --output evidence/interface-quality/azure-v2-review/review.completed.yaml \
+  --require-release-ready
+```
+
+The compiler hashes each source session and reports matrix completeness, counterbalancing, category scores, task metrics, and the anonymous target-versus-comparator decision. It rejects draft templates and never creates human observations.
+
+Assess a disclosed maintainer review without claiming independent validation:
+
+```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 solo-maintainer track may authorize continued engineering when the target stages and maintainer-scored categories pass. It never changes the anonymous comparison thresholds or converts maintainer evidence into representative-user or external release evidence.
+
+Evaluate the maintained system corpus:
+
+```bash
+npm run evaluate-corpus
+```
+
+Verify a running interface:
+
+```bash
+npm run verify-ui -- \
+  --url http://127.0.0.1:3000 \
+  --journeys knowledge-base/benchmarks/aegisops/journeys.json \
+  --profile responsive-overview \
+  --output .ztothez-design-runtime/responsive-overview
+```
+
+Create and then compare a screenshot baseline while masking only declared dynamic regions:
+
+```bash
+npm run verify-ui -- \
+  --url http://127.0.0.1:3000 \
+  --dynamic-selector "[data-runtime-clock]" \
+  --screenshot-baseline evidence/runtime/screenshots.json \
+  --update-screenshot-baseline
+
+npm run verify-ui -- \
+  --url http://127.0.0.1:3000 \
+  --dynamic-selector "[data-runtime-clock]" \
+  --screenshot-baseline evidence/runtime/screenshots.json
+```
+
+Screenshot matching establishes only that the captured pixels and masking policy are unchanged in the current environment. It does not establish visual quality, task success, or approval of an intentional change.
+
+When Playwright cannot launch Chromium directly in a managed environment, start Chromium with a
+loopback CDP endpoint and set `ZTOTHEZ_DESIGN_CHROMIUM_CDP_URL` to its HTTP origin. Only loopback
+origins are accepted:
+
+```bash
+chromium --headless --no-sandbox --remote-debugging-address=127.0.0.1 \
+  --remote-debugging-port=9222 --user-data-dir=/tmp/ztothez-design-cdp about:blank
+
+ZTOTHEZ_DESIGN_CHROMIUM_CDP_URL=http://127.0.0.1:9222 npm run verify-ui -- \
+  --url http://127.0.0.1:3000
+```
+
+Run a complete profile quality gate:
+
+```bash
+npm run quality-gate -- \
+  --contract knowledge-base/benchmarks/aegisops/product-contract.yaml \
+  --repo PATH_TO_APPLICATION \
+  --project-root . \
+  --url http://127.0.0.1:3000 \
+  --profile responsive-overview \
+  --output .ztothez-design-quality-gate/responsive-overview \
+  --fail-on error
+```
+
+Run `npm run COMMAND -- --help` for the complete options supported by each CLI workflow.
+
+## Evidence Model
+
+The system keeps evidence types distinct:
+
+1. Automated evidence records deterministic source, contract, browser, network, and state checks.
+2. AI-assisted expert evidence identifies likely usability risks but does not represent user behavior.
+3. Human-expert evidence requires an attributable reviewer.
+4. Representative-user evidence records observed task performance with appropriate study context.
+
+AI agents must never create human attestations or present generated observations as representative-user evidence. Open severity 3 and 4 heuristic findings become acceptance-criterion candidates that require review before contract integration.
+
+## Knowledge Precedence
+
+Use sources in this order:
+
+1. Current product requirements and repository behavior.
+2. Root [`SKILL.md`](SKILL.md).
+3. The selected benchmark contract and manifest.
+4. Maintained files in [`knowledge-base/`](knowledge-base/INDEX.md).
+5. Public standards or official platform documentation when the maintained corpus has a declared gap.
+
+Historical research is outside the supported workflow. It is not a runtime dependency, retrieval fallback, implementation authority, or source to copy into production code. The clean-room constraints in [`clean-room-ux-design-spec.md`](clean-room-ux-design-spec.md) govern all new capabilities.
+
+## Repository Layout
+
+| Path | Purpose |
+|---|---|
+| `SKILL.md` | Authoritative Agent Skill instructions. |
+| `src/server.ts` | MCP server and tool registration. |
+| `src/audit/` | Static repository audit engine. |
+| `src/runtime/` | Browser verification and evidence capture. |
+| `src/contracts/` | Product-contract and journey validation. |
+| `src/heuristics/` | Structured heuristic-review evaluation. |
+| `src/design-intelligence/` | Design-deliverable schema, provenance, token, contrast, icon, and presentation validation. |
+| `src/interface-trust/` | Interface-state truth, claim-source traceability, and history or export provenance validation. |
+| `src/information-design/` | Operational metric, finding, chart, hierarchy, collection, and answer-flow validation. |
+| `src/product-brief/` | Evidence-backed product intake and generation-readiness validation. |
+| `src/comparison/` | Anonymous comparison, claim-ledger, evidence-integrity, and release-readiness validation. |
+| `src/corpus/` | Versioned corpus loading, deterministic case evaluation, scoring, and reporting. |
+| `src/retrieval/` | Approved-scope Markdown indexing and deterministic BM25 search. |
+| `src/quality-gate/` | Consolidated profile quality gate. |
+| `src/repair/` | Finding-bound generated-fixture repair, rollback, and before/after evidence. |
+| `src/aggregate/` | Multi-profile release aggregation. |
+| `cli/` | Stdio server and command-line entrypoints. |
+| `knowledge-base/` | Approved maintained guidance, schemas, benchmarks, provenance, and dependency records. |
+| `tests/` | Contract, MCP, audit, runtime, and quality-gate regression tests. |
+| `ci/` | Deterministic fixture and product-workflow example. |
+| `.github/workflows/quality.yml` | Active repository quality workflow. |
+
+## Development
+
+```bash
+npm run build
+npm run typecheck
+npm test
+npm run independence:check
+npm run release:check
+```
+
+The active GitHub workflow also validates clean-room isolation, both benchmark contracts, the maintained corpus, packed installation, offline release, an archive-free workspace mirror, and the deterministic browser fixture gate. It uploads the resulting evidence. See [`ci/README.md`](ci/README.md) before adapting the multi-profile workflow to a product repository.
+
+## Project Status
+
+All nine V1, V2, and V3 roadmap items are implemented. See [`ROADMAP.md`](ROADMAP.md), [`V2-ROADMAP.md`](V2-ROADMAP.md), and [`V3-ROADMAP.md`](V3-ROADMAP.md) for evidence-backed status and completion criteria. V2 includes an external anonymous human visual comparison of five candidates; it validates the static visual questions asked and does not claim interactive representative-user testing. V4 Items 1 through 5 implement evidence-gated product briefs, deterministic design-plan compilation, contained React and TypeScript fixture generation, rendered visual-composition and asset enforcement, and bounded finding-driven repair with rollback. Item 6 adds versioned executable interaction and recovery checkpoints while preserving the boundary between runtime, human-review, and representative-user evidence. The remaining closed-loop delivery program is defined in [`V4-ROADMAP.md`](V4-ROADMAP.md).

package/ROADMAP.md

@@ -0,0 +1,127 @@
+# ZtotheZ Design Engineering Roadmap
+
+This roadmap tracks the work required to turn the skill, local knowledge base, MCP server, and quality gate into an independently owned design-engineering system. [`SKILL.md`](SKILL.md) remains the authoritative operating instruction; roadmap items describe future engineering work, not capabilities that may be claimed before validation.
+
+## Current Foundation
+
+- Usability guidance is available through MCP.
+- Heuristic reviews use a versioned schema with evidence provenance.
+- Browser verification covers responsive integrity, accessibility, focus, contrast, target sizing, text resizing, reflow, and reduced motion.
+- The published repository runs a deterministic GitHub Actions quality workflow and retains fixture-gate evidence.
+- AegisOPS provides the first executable product benchmark.
+- Approved design knowledge is available through deterministic, authority-aware BM25 retrieval with explicit abstention.
+- Independently authored design-intelligence modules and a versioned deliverable manifest provide executable checks for tokens, provenance, visual accessibility, icon semantics, and presentation structure.
+- A versioned positive and negative corpus measures retrieval relevance, abstention, architectural integrity, task completeness, and anti-slop rejection with attributable provenance and release thresholds.
+- Exact provenance, dependency boundaries, archive-free operation, isolated package installation, and offline runtime integrity are release-certified.
+
+## Roadmap Items
+
+Status definitions:
+
+- **Done:** every stated deliverable has current passing evidence.
+- **Partial:** implementation evidence exists, but at least one stated deliverable or current acceptance condition is incomplete.
+- **Not started:** no implementation of the roadmap-specific capability exists.
+
+### 1. Publish And Activate CI
+
+Status: **Done**
+
+Initialize and publish the repository, run `.github/workflows/quality.yml` on GitHub, and retain the first complete passing evidence artifact.
+
+Evidence: the repository is published at `https://github.com/ztothez/ztothez-design-engineering` with `main` tracking `origin/main`. GitHub Actions run `32947084426` passed build, typecheck, both benchmark-contract validations, all 21 regression tests, the deterministic fixture quality gate, and artifact upload. The retained `ztothez-design-fixture-quality-gate` artifact was created on 2026-08-26 with 14-day retention.
+
+### 2. AegisOPS Product Workflow
+
+Status: **Done**
+
+Add deterministic `demo-success`, `offline-recovery`, and `responsive-overview` environments to the AegisOPS repository. Run each profile independently and aggregate them into one release decision.
+
+Evidence: `knowledge-base/benchmarks/aegisops/` contains the contract and all three journey profiles. `.uix-quality-gate/aegis-release-strict/aggregate-report.json` and `.uix-quality-gate/aegis-release-final/aggregate-report.json` both pass with 3 of 3 profiles and 9 of 9 acceptance criteria verified.
+
+### 3. Resolve AegisOPS Findings
+
+Status: **Done**
+
+Correct the verified contrast-token and control-size failures, rerun all required profiles, and preserve attributable human-review evidence separately from automated evidence.
+
+Evidence: foreground tokens and primary target contracts were corrected without exemptions, and AegisOPS product tests, lint, and production build pass. The current strict reports at `.uix-quality-gate/aegis-demo-v191/`, `.uix-quality-gate/aegis-offline-v191/`, and `.uix-quality-gate/aegis-responsive-v191/` each pass with zero runtime errors and warnings. `.uix-quality-gate/aegis-release-v191/aggregate-report.json` passes with 3 of 3 profiles and 9 of 9 criteria. Existing user-authored attestations remain separate from automated evidence. See `knowledge-base/benchmarks/aegisops/CALIBRATION.md`.
+
+### 4. SceneStart Product Benchmark
+
+Status: **Done**
+
+Create a second product contract, task journeys, acceptance criteria, anti-patterns, and human-review template for SceneStart. Use it to prove the system generalizes beyond a security-operations dashboard.
+
+Evidence: `knowledge-base/benchmarks/scenestart/` contains the contract, four journey profiles, acceptance criteria, anti-patterns, human-review template, source evidence, and calibration. Contract tests pass, multi-route verification is implemented, and CSP-compatible Blob export evidence is covered by regression tests and real Studio and Release profile artifacts. SceneStart accessibility and Workshop-to-Studio state continuity are separately recorded product findings, not missing benchmark deliverables.
+
+### 5. Scoped Knowledge Retrieval
+
+Status: **Done**
+
+Add deterministic full-text or BM25 retrieval across approved knowledge categories. Return source paths, excerpts, confidence, and explicit no-match results while keeping `SKILL.md` authoritative.
+
+Evidence: `knowledge-base/retrieval-scope.yaml` explicitly approves 17 project-owned Markdown files across five categories and marks `SKILL.md` authoritative. `src/retrieval/` builds a deterministic 140-chunk Markdown index, applies BM25 ranking with bounded title and authority boosts, and returns source paths, sections, bounded excerpts, scores, confidence, matched terms, and explicit `no-match` reports. The `search_design_knowledge` MCP tool exposes structured and Markdown output. `tests/fixtures/retrieval-cases.yaml`, `tests/retrieval.test.ts`, and `tests/mcp.test.ts` verify ranking, category isolation, authority precedence, abstention, archive exclusion, category-escape rejection, and MCP behavior. The maintained corpus migration replaced historical architecture, Figma, and UX routes with independently authored modules under `knowledge-base/maintained/` and `knowledge-base/design-intelligence/`. The complete 35-test regression suite passes.
+
+### 6. Installation And Packaging
+
+Status: **Done**
+
+Package the MCP server and document repeatable installation for Codex, Claude Code, Cursor, Windsurf, Antigravity, GitHub Copilot, Kiro, Qoder, and Lovable.
+
+Evidence: package `@ztothez/design-engineering` defines Node.js 22 compatibility, ESM exports, public scoped-package metadata, and the equivalent `ztothez-design` and `zz-design` executable aliases. Its explicit `files` allowlist includes the compiled runtime, authoritative skill, approved retrieval corpus, usability schemas, and benchmark contracts while excluding source archives, raw research, and tests. `npm run package:check` validates every approved retrieval file and benchmark artifact against the packed manifest. `npm run package:smoke` installs the 250-file tarball into an empty temporary project, verifies both CLI metadata contracts, rejects historical knowledge paths, starts the installed server over stdio, lists MCP tools, and exercises architecture, dashboard, retrieval, and corpus operations. `npm run release:pack` also creates a self-contained offline runtime, serialized knowledge index, manifest, and SHA-256 checksums; `npm run release:check` verifies integrity and launches that runtime outside the source tree. `docs/installation.md` documents repeatable setup for Codex, Claude Code, Cursor, Windsurf, Antigravity, GitHub Copilot, Kiro, Qoder, and Lovable Desktop. `.github/workflows/quality.yml` runs the packed-install and offline-release checks and retains the release directory as a CI artifact.
+
+### 7. Design Intelligence Expansion
+
+Status: **Done**
+
+Add independently authored, structured modules for brand systems, Figma workflows, asset generation, iconography, presentation design, licensing, and visual-accessibility verification.
+
+Evidence: `knowledge-base/design-intelligence/` contains an independently authored coordinating module and seven focused modules for brand systems, Figma production, asset generation, iconography, presentation design, licensing and provenance, and visual accessibility. The versioned `design-deliverable.schema.yaml` and passing `design-deliverable.template.yaml` define a portable contract for token architecture, brand references, Figma mappings, asset rights and generation provenance, icon semantics, presentation masters, and mode-aware contrast evidence. `src/design-intelligence/` implements deterministic `ZTDE-DI-*` findings, reference validation, token-cycle detection, WCAG contrast calculations, non-color-cue checks, and explicit limits around rendered proof and legal clearance. The `validate_design_deliverable` MCP tool and `validate-design` CLI expose the workflow with external-root restrictions. `get_design_intelligence` and the approved retrieval manifest expose the maintained guidance without admitting legacy archives. CI validates the maintained template, package checks enforce its distribution allowlist, packed-install smoke testing passes, and the complete 30-test regression suite covers valid, invalid, traversal, retrieval, and MCP behavior.
+
+### 8. Corpus Benchmarking
+
+Status: **Done**
+
+Build positive and negative benchmark sets from user-owned projects and appropriately licensed sources. Measure recommendation relevance, abstention, architectural integrity, task completeness, and anti-slop rejection.
+
+Evidence: `knowledge-base/benchmarks/corpus/` contains a versioned portable schema, executable manifest, provenance record, project-owned synthetic repositories, an incomplete task-contract fixture, and owner-authorized AegisOPS and SceneStart cases. The 13 maintained cases include 8 positive and 5 negative expectations across recommendation relevance, abstention, architectural integrity, task completeness, and anti-slop rejection. The corpus records four provenance sources, including user-owned product evidence and a W3C WCAG 2.2 reference under the W3C Document License 2015 without redistributing specification text. `src/corpus/` implements bounded loading, project-root containment, deterministic case evaluation, per-dimension scoring, mean reciprocal rank, provenance-preserving reports, and strict thresholds. `evaluate_corpus_benchmark` exposes structured MCP results with traversal protection, and `npm run evaluate-corpus` writes JSON and Markdown evidence when given `--output`. Calibration identified and corrected single-generic-term retrieval overmatching. The maintained corpus passes 13 of 13 cases at 100 percent across all five dimensions with recommendation MRR 0.75 against a 0.75 floor. All 35 regression tests, packed-install MCP smoke testing, and the package allowlist pass. The active GitHub workflow evaluates the corpus and is configured to retain its JSON and Markdown reports as a dedicated artifact.
+
+### 9. Clean-Room Independence And Supply Resilience
+
+Status: **Done**
+
+Implement [`clean-room-ux-design-spec.md`](clean-room-ux-design-spec.md) as an independently owned capability specification. External design products, including UI/UX Pro Max and UX Pilot, are comparative references only; they must not become production dependencies, sources of copied implementation, or authorities over this system.
+
+Evidence: the active retrieval and exact-read routes now use independently authored architecture, product-pattern, design-intelligence, and usability modules. `knowledge-base/provenance.yaml` records exact ownership, license, review, and transformation coverage for all 62 shipped guidance artifacts. `knowledge-base/dependencies.yaml` records all seven direct dependency versions, licenses, narrow infrastructure boundaries, fallbacks, and replacement triggers. `npm run independence:check` validates both manifests, audits all 97 locked production packages against the license policy, and scans 137 active files for prohibited archive authority paths. Retrieval and corpus cases preserve explicit no-match behavior and category isolation. `npm run package:smoke` proves the installed package contains no historical knowledge paths and exercises its installed MCP server. `npm run release:pack` creates an offline runtime with 4,243 files from 94 copied production package roots, 17 approved documents, a 140-chunk serialized index, manifest, and checksums; `npm run release:check` verifies it and launches the CLI without repository dependencies. `npm run independence:archive-smoke` creates an isolated workspace with no reference archives and passes build, typecheck, all 35 regressions including MCP and retrieval, corpus evaluation, and the Chromium fixture quality gate. The active CI workflow runs and retains these independence proofs. The ZtotheZ Design Engineering identity remains consistent across the skill, package, MCP server, CLI, rules, reports, and CI.
+
+#### Independence Rules
+
+1. Do not import, execute, package, install, or call reference-project code, CLIs, hosted services, catalogs, templates, or update channels from production paths.
+2. Keep reference repositories removable. The build, tests, MCP server, retrieval, quality gate, generated skill, and installer must continue to work when all reference archives are absent.
+3. Reimplement observable capabilities from independently designed contracts. Do not copy or translate source code, internal structure, proprietary wording, or unverified assets.
+4. Build knowledge from independently authored rules, user-owned material, public standards, official platform documentation, and sources with recorded reuse rights.
+5. Record provenance, license status, version, freshness, and transformation history for every distributable catalog or asset.
+6. Preserve local-first operation. After installation, core design guidance, retrieval, auditing, and quality-gate behavior must not require a vendor account or remote design service.
+7. Treat commodity open-source libraries as replaceable infrastructure, not product authorities. Keep them lockfile-pinned, license-audited, isolated behind narrow interfaces, and covered by substitution or fallback plans.
+8. Maintain explicit no-match and abstention behavior. A missing independent rule must never be silently filled from an archived reference dataset.
+9. Preserve the independently owned ZtotheZ Design Engineering identity across distributable files and document any future compatibility or installation transition.
+
+#### Deliverables
+
+- A machine-readable provenance and license manifest for distributable knowledge and assets.
+- A dependency inventory separating strategic capabilities from replaceable infrastructure.
+- CI checks that reject imports and runtime paths into reference archives.
+- Retrieval tests proving archived reference content is excluded from approved search categories.
+- Behavioral compatibility tests based on inputs, outputs, states, and errors rather than reference internals.
+- A product and package identity owned by this project.
+- An offline release bundle containing the authoritative skill, schemas, knowledge indexes, and quality-gate runtime.
+
+#### Completion Criteria
+
+Item 9 is complete only when reference archives can be moved outside the workspace and all builds, tests, MCP operations, retrieval evaluations, fixture gates, and installation smoke tests still pass. Every shipped knowledge artifact must have acceptable provenance, and no supported workflow may require continued access to a reference vendor or repository.
+
+## Execution Order
+
+SceneStart product remediation can proceed separately from skill development. AegisOPS remediation is complete against the current verifier and must be reopened if later product or verifier changes invalidate its evidence.
+
+All roadmap items are complete. The Item 9 independence rules remain release constraints for every future change to the skill, maintained knowledge, dependencies, retrieval, quality-gate runtime, packaging, or agent integrations.