@ztothez/design-engineering 2.0.0

package/knowledge-base/INDEX.md

@@ -0,0 +1,285 @@
+# ZtotheZ Design Engineering Knowledge Base
+
+This directory contains the maintained, distributable knowledge used by the ZtotheZ Design Engineering System and its root [`SKILL.md`](../SKILL.md). Treat `SKILL.md` as the primary instruction set. [`ROADMAP.md`](../ROADMAP.md) governs planned work and clean-room certification. Local historical material outside the approved retrieval scope is not an implementation authority and is not distributed.
+
+## Product Identity
+
+| Surface | Identifier |
+|---|---|
+| Product | ZtotheZ Design Engineering System |
+| Short name | ZtotheZ Design Engineering |
+| Repository | `ztothez-design-engineering` |
+| Agent Skill | `ztothez-design-engineering` |
+| MCP server | `ztothez-design-engineering` |
+| npm package | `@ztothez/design-engineering` |
+| Full CLI command | `ztothez-design` |
+| Short CLI command | `zz-design` |
+
+Both CLI commands invoke the same stdio MCP server. Use `ztothez-design --help` or `zz-design --help` for local command discovery. Historical evidence paths retain their original names and are not current product identifiers.
+
+Version 2.0 is a pre-publication identity reset, not a compatibility alias layer. Current integrations must use `run_design_quality_gate`, `aggregate_design_quality_gates`, `ZTOTHEZ_DESIGN_*` environment variables, `ZTDE-*` finding IDs, `data-ztothez-design-*` runtime annotations, and `.ztothez-design-quality-gate/` or `.ztothez-design-runtime/` output directories. Old identifiers are retained only inside archived sources and completed historical evidence.
+
+## Directory Map
+
+| Path | Contents | Use when |
+|---|---|---|
+| `maintained/architecture/` | Independently authored quality-attribute, architecture-evaluation, component-boundary, and product-platform guidance | Evaluating architecture, coupling, cohesion, trade-offs, and shared product variation |
+| `maintained/product-patterns/` | Independently authored AI-workspace and operational-dashboard contracts | Designing task-centered workspaces and operational tools without importing a template catalog |
+| `design-intelligence/` | Maintained product intake, planning, contained generation and repair, interface trust, operational information design, visual polish, brand, Figma production, asset generation, iconography, presentation, licensing, accessibility, and integrated validation modules | Running the bounded product-task through generated implementation, finding-bound repair, and human-review workflow or creating visual-system deliverables with structured provenance, tokens, accessibility, and handoff evidence |
+| `benchmarks/` | Executable product contracts, journey profiles, acceptance criteria, and anti-pattern corpora | Evaluating whether generated UI is behaviorally coherent, evidence-backed, and production-ready for a specific product domain |
+| `usability-evaluation/` | Maintained heuristic-evaluation workflow, portable schema, and review template | Conducting a UX audit, defining human-review evidence, separating automated findings from user-testing claims, or turning usability risks into acceptance criteria |
+| `retrieval-scope.yaml` | Explicit allowlist for the distributable BM25 index | Auditing or changing which knowledge files can appear in ranked retrieval |
+| `provenance.yaml` | Machine-readable ownership, license, transformation, and distribution records | Auditing every shipped knowledge artifact before release |
+| `dependencies.yaml` | Direct dependency role, boundary, license, fallback, and replacement plan | Reviewing supply-chain exposure and local fallback behavior |
+
+## Scoped Knowledge Retrieval
+
+Use `search_design_knowledge` to search the approved distributable corpus before opening deep source files. The deterministic BM25 index is governed by `retrieval-scope.yaml`, which names every eligible Markdown file and marks the root `SKILL.md` as authoritative.
+
+The tool returns:
+
+- Ranked repository-relative source paths.
+- The matching document title and section.
+- Bounded excerpts and normalized matched terms.
+- Numeric relevance scores and `high`, `medium`, or `low` confidence.
+- An explicit `no-match` result when no approved source contains the searchable query terms.
+
+Available scopes are `skill`, `architecture`, `design-intelligence`, `ux-patterns`, and `usability-evaluation`. Search all scopes only when the task crosses domains. After ranking, read the selected file through its category-specific MCP tool so constraints outside the excerpt are not lost.
+
+Ignored books, raw local research, historical conversions, and benchmark evidence are outside the retrieval manifest. A no-match result must not trigger a historical-source fallback. Refine the query, broaden approved categories, use current product evidence, consult an official standard, or record a knowledge gap instead.
+
+## Product Benchmarks
+
+Product benchmarks supplement the root skill with domain semantics and executable acceptance evidence. Validate the selected contract before implementation, load only its manifest and contract by default, and inspect its approved source-evidence summary only when a criterion needs deeper grounding.
+
+- AegisOPS SOC readiness command center: `benchmarks/aegisops/MANIFEST.md` and `benchmarks/aegisops/product-contract.yaml`.
+- AegisOPS runtime journey profiles: `benchmarks/aegisops/journeys.json`.
+- AegisOPS evidence interpretation, rejection examples, and current accessibility calibration: `benchmarks/aegisops/acceptance-criteria.md`, `benchmarks/aegisops/anti-patterns.md`, and `benchmarks/aegisops/CALIBRATION.md`.
+- SceneStart local-first demoscene learning studio: `benchmarks/scenestart/MANIFEST.md` and `benchmarks/scenestart/product-contract.yaml`.
+- SceneStart Studio, Workshop, Learn, and Release profiles: `benchmarks/scenestart/journeys.json`.
+- SceneStart evidence boundaries, rejection examples, and calibration: `benchmarks/scenestart/acceptance-criteria.md`, `benchmarks/scenestart/anti-patterns.md`, and `benchmarks/scenestart/CALIBRATION.md`.
+- System corpus manifest, portable schema, provenance, and controlled positive and negative cases: `benchmarks/corpus/corpus.yaml`, `benchmarks/corpus/corpus.schema.yaml`, `benchmarks/corpus/PROVENANCE.md`, and `benchmarks/corpus/cases/`.
+- Portable anonymous comparison contracts: `benchmarks/interface-quality/comparison-methodology.schema.yaml`, `benchmarks/interface-quality/comparison-methodology-v1.1.schema.yaml`, `benchmarks/interface-quality/review.schema.yaml`, and `benchmarks/interface-quality/review-session.schema.yaml`.
+- Solo-maintainer engineering continuation rules and claim boundaries: `benchmarks/interface-quality/SOLO-MAINTAINER-TRACK.md`.
+- Azure V2 human and interaction review method: `benchmarks/azure-optimizer/v2-human-review-methodology.yaml`. Reviewer-facing evidence remains outside the distributable knowledge corpus under `evidence/interface-quality/azure-v2-review/`.
+- Portable product-task profile, archetype activation rules, and evidence boundary: `benchmarks/portfolio-corpus/PRODUCT-TASK-CONTRACTS.md`, `benchmarks/portfolio-corpus/product-task-profile.schema.yaml`, and `benchmarks/portfolio-corpus/archetype-profiles.yaml`.
+
+Use `evaluate_corpus_benchmark` after changing retrieval, auditing, product-contract validation, anti-slop rules, or approved knowledge. CLI fallback:
+
+```bash
+npm run evaluate-corpus
+```
+
+The corpus reports recommendation relevance, abstention accuracy, architecture integrity, task completeness, anti-slop rejection, and recommendation mean reciprocal rank. Every case declares provenance and expected behavior. A passing corpus covers only its maintained cases and must not be presented as universal design or usability proof.
+
+Use `validate_product_contract` when MCP is available. CLI fallback:
+
+```bash
+npm run validate-contract -- --contract knowledge-base/benchmarks/aegisops/product-contract.yaml
+```
+
+Contract version `1.1` binds the product archetype and activated quality dimensions to observable
+primary task success, failure recovery, and narrow-viewport journeys. Missing evidence remains
+`unverified`; an executed failed task remains `failed`; unsupported capabilities remain explicit
+limitations. Do not rank products that use materially different task contracts.
+
+For final evidence, prefer the consolidated quality gate against an already-running application:
+
+```bash
+npm run quality-gate -- \
+  --contract knowledge-base/benchmarks/aegisops/product-contract.yaml \
+  --repo PATH_TO_APPLICATION \
+  --url http://127.0.0.1:3000 \
+  --profile responsive-overview
+```
+
+The gate writes contract, architecture, runtime, acceptance-criterion, screenshot, and consolidated JSON and Markdown evidence. Runtime checks include overflow, semantic clipping, independent control collisions, sticky or fixed occlusion, text contrast, touch-target size, accessible names, visible and unobscured focus, keyboard traps and forced ordering, 200% reflow and text resizing, reduced motion, media rendering, console and network failures, and configured journeys. Base state and preserved post-journey state are checked at every configured viewport. Every blocker criterion in the selected profile must be `PASS`; `UNVERIFIED` is not success. Use `--attestations PATH` only for genuine human review records. AI agents must never create self-attestations. `--skip-runtime` is available for partial diagnostics, but the resulting gate is `INCOMPLETE` and cannot pass.
+
+Runtime exemptions are narrow evidence annotations, not global suppressions:
+
+- `data-ztothez-design-allow-overlap` and `data-ztothez-design-allow-clipping`: verified intentional composition or clipping.
+- `data-ztothez-design-allow-contrast`: a background the solid-color sampler cannot model and that has separate contrast evidence.
+- `data-ztothez-design-allow-small-target`: a documented target-size standards exception with equivalent operability.
+- `data-ztothez-design-allow-focus-occlusion`: an intentional focus geometry case proven visible by another check.
+- `data-ztothez-design-allow-reflow` and `data-ztothez-design-allow-text-resize`: a standards-permitted two-dimensional region such as code or a data table, never an ordinary page-level layout exemption.
+- `data-ztothez-design-essential-motion`: motion required for the information or operation and reviewed under reduced-motion policy.
+- `data-ztothez-design-runtime-ignore`: development or browser tooling outside the product UI; never use it on application content.
+
+Place an exemption on the smallest owning element and record why it is valid. Do not annotate a page shell merely to make a gate pass.
+
+Journey profiles may declare narrowly scoped `expectedNetwork` failures for controlled recovery scenarios. Every policy matches a method, URL fragment, and HTTP status or explicit request failure, and must be observed within its declared count. Unmatched failures and unobserved expectations remain blockers.
+
+After running every contract-required profile into a separate evidence directory, produce one release decision:
+
+```bash
+npm run aggregate-gates -- \
+  --contract knowledge-base/benchmarks/aegisops/product-contract.yaml \
+  --reports .ztothez-design-quality-gate/demo-success,.ztothez-design-quality-gate/offline-recovery,.ztothez-design-quality-gate/responsive-overview \
+  --output .ztothez-design-quality-gate/release
+```
+
+The aggregator rejects missing or duplicate profiles, contract and failure-policy mismatches, incomplete reports, failed profile gates, and any blocker criterion that is failed or unverified in a required profile. This repository's `.github/workflows/quality.yml` runs build, typecheck, tests, contract validation, and a deterministic fixture gate. Adapt `ci/github-actions-design-quality-gate.example.yml` for a target product only after each required profile has a deterministic service startup command.
+
+## Architecture Routing
+
+Start with `maintained/architecture/MASTER.md`, then load one focused module:
+
+- Measurable quality scenarios, utility trees, sensitivity, and trade-offs: `maintained/architecture/quality-attributes-and-evaluation.md`.
+- Component ownership, coupling, cohesion, package direction, and contracts: `maintained/architecture/component-boundaries.md`.
+- Shared product scope, variation points, plugins, configuration, and platform economics: `maintained/architecture/product-platforms.md`.
+
+## Usability Evaluation Routing
+
+Start with `usability-evaluation/HEURISTIC_EVALUATION.md` for UX audits, redesign diagnosis, release review, or usability-test planning. It defines evidence boundaries, the expert-review sequence, finding records, severity, and the handoff to representative-user testing. Use `get_usability_evaluation` to list or read this category through MCP.
+
+Use `usability-evaluation/heuristic-review.template.yaml` to start a structured review and `usability-evaluation/heuristic-review.schema.yaml` as its portable version 1.0 contract. Validate completed review artifacts with `evaluate_heuristic_review`. CLI fallback:
+
+```bash
+npm run review-heuristics -- --review PATH_TO_HEURISTIC_REVIEW
+```
+
+Use `--candidates` for a contract-ready YAML fragment and opt into a nonzero policy result with `--fail-on-open-major`. Open severity 3 and 4 findings produce unapplied blocker acceptance-criterion candidates. Review and merge those candidates into the applicable product contract, then bind them to representative journeys. The heuristic report cannot satisfy `manual-review` evidence and must never be converted into a human attestation by an AI agent.
+
+The distributable repository intentionally excludes raw course handouts, converted books, and extended local research. Use the maintained workflow, schema, and template as the only MCP-accessible usability authority. Treat automated quality-gate findings as rendered evidence, AI-assisted expert review as likely-risk evidence, attributable human-expert review as expert evidence, and representative-user testing as task-performance evidence; never present one as another.
+
+## Product Pattern Routing
+
+For implementation work, start with `maintained/product-patterns/MASTER.md` and load only the matching project-owned pattern:
+
+- AI analysis, generation, review, and evidence workspaces: `maintained/product-patterns/ai-workspaces.md`.
+- Pipelines, records, jobs, obligations, media, and document operations: `maintained/product-patterns/operational-dashboards.md`.
+
+## Portfolio Benchmark Registry
+
+Use `benchmarks/portfolio-corpus/registry.template.yaml` to define local project authorization and
+`benchmarks/portfolio-corpus/registry.schema.yaml` as the portable version 1.0 contract. Store real
+absolute roots only in `.ztothez-design-local/portfolio-registry.yaml`, which is intentionally
+excluded from Git, retrieval, packaging, and offline releases.
+
+Use `benchmarks/portfolio-corpus/ADAPTERS.md` to select a stack adapter, declare exact stage
+commands, and distinguish supported, unsupported, and not-applicable capabilities. Adapters never
+discover and execute arbitrary package scripts.
+
+Validate before discovery or snapshot creation:
+
+```bash
+zz-design portfolio validate-registry
+zz-design portfolio inventory
+zz-design portfolio capabilities --project PROJECT_ID
+zz-design portfolio run-stage --project PROJECT_ID --stage STAGE
+zz-design portfolio snapshot --project PROJECT_ID
+```
+
+Inventory is metadata-only and does not authorize execution. Snapshot creation copies only approved
+files into `.ztothez-design-benchmarks/`, verifies the source before cleanup, and leaves all
+remediation unapplied.
+
+Run an isolated baseline or cohort benchmark and inspect its retained report:
+
+```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
+```
+
+See `benchmarks/portfolio-corpus/PORTFOLIO-RUNNER.md` for stage behavior, report fields, exit codes,
+and the current browser-verification limitations.
+
+## AI Development Environment Guide
+
+The repository paths above are the canonical references across Claude Code, Cursor, Windsurf, Antigravity, GitHub Copilot, Kiro, Codex, Qoder, and Lovable. Do not create environment-specific copies of the knowledge base.
+
+For repository-aware coding agents:
+
+1. Start the request with the root `SKILL.md` as the governing instruction source.
+2. Name the smallest relevant knowledge-base path in the request.
+3. Ask the agent to inspect those files before proposing or implementing changes.
+4. Require the agent to preserve the current stack and use only maintained guidance or approved benchmark evidence.
+5. Ask it to report which sources materially affected the implementation and which verification commands it ran.
+
+Example request:
+
+```text
+Use SKILL.md as the primary workflow. Before implementing this AI analysis screen,
+read knowledge-base/maintained/product-patterns/ai-workspaces.md and
+knowledge-base/maintained/architecture/quality-attributes-and-evaluation.md.
+Preserve the existing framework and validate the completed interaction states.
+```
+
+In Claude Code, Cursor, Windsurf, Antigravity, GitHub Copilot, Kiro, Codex, and Qoder, attach, mention, or request the repository-relative paths through the environment's normal file-context mechanism. Path syntax may differ by product, but the source files and precedence remain the same: `SKILL.md` first, targeted maintained files second.
+
+For Lovable, keep this repository synchronized with the connected Git provider so maintained files are available in project context. Refer to the same repository-relative paths in the task. If the environment cannot read non-application Markdown automatically, provide only the relevant file as task context rather than importing the whole knowledge base into application code.
+
+## Grounding Rules
+
+- `SKILL.md` overrides supporting guidance when wording or scope conflicts.
+- Prefer current project code and requirements over historical examples.
+- Load only the maintained modules relevant to the task; broad context increases duplication and contradictory guidance.
+- Do not copy private names, fixed personal color choices, obsolete framework decisions, or historical generated artifacts into new implementations.
+- Convert source concepts into measurable requirements, explicit component contracts, semantic tokens, and testable interaction states.
+- Record architectural decisions and trade-offs when deep sources materially change the implementation.
+
+## Design Intelligence Routing
+
+Start with `design-intelligence/MASTER.md` when the task includes brand identity, Figma production, generated or sourced assets, iconography, presentation design, licensing, or visual accessibility. Load only the matching focused modules.
+
+For a new independent React and TypeScript fixture, validate the brief, compile an
+implementation-ready plan, then follow `design-intelligence/generation-adapter.md`. Its CLI adapter
+requires a separate generation root and a passing local portfolio registry, and it refuses existing,
+symlinked, escaping, or portfolio-overlapping targets. The generated manifest follows
+`design-intelligence/generation-adapter.schema.yaml`.
+
+For a fresh architecture or runtime finding in a generated fixture, read
+`design-intelligence/closed-loop-repair.md` and validate the request shape with
+`design-intelligence/repair-request.schema.yaml`. Run `zz-design repair-react` only against the
+manifest-owned generated target and an already-running loopback URL. The command retains equivalent
+before and after quality-gate evidence, rejects stale or ambiguous findings, and restores original
+bytes on repeated or failed verification. It is intentionally CLI-only because MCP remains
+read-only. Automated repair output never supplies human evidence.
+
+For a new product or consequential redesign, start from `design-intelligence/product-design-brief.template.yaml` and use `design-intelligence/product-design-brief.schema.yaml` as the portable version 1.0 contract. Read `design-intelligence/product-design-brief.md`, then validate through MCP with `validate_product_design_brief`, or through CLI:
+
+```bash
+npm run validate-brief -- --brief PATH_TO_PRODUCT_DESIGN_BRIEF
+```
+
+The brief validator checks evidence-backed problems and primary audiences, measurable outcomes, task recovery, data and fallback truth, applicable states, platforms, unresolved assumptions, requirements, and acceptance coverage. Generation readiness authorizes planning only.
+
+Compile a generation-ready brief through MCP with `compile_design_plan`, or through CLI:
+
+```bash
+npm run compile-plan -- --brief PATH_TO_PRODUCT_DESIGN_BRIEF --project-root . --json
+```
+
+Read `design-intelligence/design-plan.md` and validate machine output against
+`design-intelligence/design-plan.schema.yaml`. The compiler produces stable information
+architecture, route proposals, component and state boundaries, downstream contract results,
+semantic token requirements, responsive rules, asset policy, implementation stages, verification
+obligations, and source traces. Planned contracts stay provisional; target-router integration is
+verified by the later generation adapter.
+
+For operational claims, generated results, fallback, stale or disconnected behavior, history, or exports, start from `design-intelligence/interface-trust.template.yaml` and use `design-intelligence/interface-trust.schema.yaml` as the portable version 1.0 contract. Read `design-intelligence/interface-trust.md`, then validate through MCP with `validate_interface_trust`, or through CLI:
+
+```bash
+npm run validate-trust -- --contract PATH_TO_INTERFACE_TRUST_CONTRACT
+```
+
+The trust validator checks declaration structure, source traceability, state consistency, pre-action disclosure, fallback persistence, freshness metadata, disconnected recovery, credential-like values, and history or export provenance. It does not inspect rendered placement or prove runtime service availability.
+
+For operational metrics, findings, charts, hierarchy, long labels, exceptional values, or large collections, start from `design-intelligence/information-design.template.yaml` and use `design-intelligence/information-design.schema.yaml` as the portable version 1.0 contract. Read `design-intelligence/information-design.md`, then validate through MCP with `validate_information_design`, or through CLI:
+
+```bash
+npm run validate-information -- --contract PATH_TO_INFORMATION_DESIGN_CONTRACT
+```
+
+The validator checks sources, context, metric decisions, findings, evidence, chart purpose, non-color cues, missing and stale states, scalable collections, the eight-level hierarchy, and six answer-flow task declarations. It does not inspect rendered output or turn agent-authored tasks into human evidence.
+
+Create structured evidence from `design-intelligence/design-deliverable.template.yaml`; use `design-intelligence/design-deliverable.schema.yaml` as the portable contract. Version `1.0` remains readable for non-interface manifests. Use version `2.1` with `interface-system` for visual direction, typography, composition, density, states, motion, chart contracts, rendered evidence, and human visual review. Read `design-intelligence/visual-polish.md`, then validate through MCP with `validate_design_deliverable`, or through CLI:
+
+```bash
+npm run validate-design -- --manifest PATH_TO_DESIGN_DELIVERABLE
+```
+
+The validator checks declaration structure, semantic visual bindings, token references and cycles, responsive composition, typography, density, states, motion, charts, viewport-evidence declarations, human-review attribution, mode-aware contrast, Figma mappings, brand and presentation references, asset rights records, generated-media provenance, icon semantics, and non-color cues. A structural pass can remain visually not ready. Read `visualPolish.releaseReady`; only verified viewport records and reviewer-supplied human evidence satisfy that release gate.

package/knowledge-base/benchmarks/aegisops/CALIBRATION.md

@@ -0,0 +1,52 @@
+# AegisOPS Accessibility Remediation Calibration
+
+## Calibration Context
+
+- Date: 2026-08-26
+- Application: `/home/ztothez/Studio/portfolio/AegisOPS`
+- Audited frontend: `/home/ztothez/Studio/portfolio/AegisOPS/frontend`
+- UIX quality gate: version 1.9.1
+- Browser: Chromium 151.0.7922.108
+- Failure policy: warnings and errors block release
+- Human evidence: existing user-authored `attestations.yaml`; no AI-generated attestation was added
+
+## Remediation
+
+The version 1.8.0 accessibility calibration found repeated contrast and target-size failures across the viewport matrix. The repeated findings resolved to shared component ownership rather than twenty separate defects.
+
+- Raised the muted, dim, and faint foreground token hierarchy so normal text clears 4.5:1 on the darkest supported panel where each token may render.
+- Replaced the pointer-only demo toggle with a keyboard-native button using `role="switch"`, `aria-checked`, an accessible name, and a 44 by 44 CSS-pixel target.
+- Increased mission input, mode buttons, sidebar navigation, artifact downloads, and export-error dismissal to 44-pixel target contracts.
+- Increased artifact-card minimum height so larger actions do not compress or overlap card content.
+- Added product regression tests for foreground-token contrast and primary-control target contracts.
+
+No runtime exemption attributes were added.
+
+## Product Verification
+
+- Frontend tests: 4 passed.
+- ESLint: passed.
+- Next.js production build: passed.
+- Wide and mobile completed-journey screenshots were inspected after automation and showed no incoherent overlap or clipping.
+
+## Current Quality-Gate Evidence
+
+| Profile | Journey | Runtime | Acceptance | Evidence directory |
+|---|---:|---:|---:|---|
+| `demo-success` | 9 of 9 steps passed | 0 errors, 0 warnings | 6 passed | `.uix-quality-gate/aegis-demo-v191/` |
+| `offline-recovery` | 6 of 6 steps passed | 0 errors, 0 warnings | 3 passed | `.uix-quality-gate/aegis-offline-v191/` |
+| `responsive-overview` | 4 of 4 steps passed | 0 errors, 0 warnings | 2 passed | `.uix-quality-gate/aegis-responsive-v191/` |
+
+Each profile captured four base-state and four completed-journey screenshots. The demo profile retained the generated Sigma artifact through the CSP-compatible Blob evidence path. The offline profile observed the contract-required `POST /run` HTTP 500 response and preserved the user's input and recovery controls.
+
+The aggregate report at `.uix-quality-gate/aegis-release-v191/aggregate-report.json` is complete and passing:
+
+- 3 of 3 required profiles supplied and passed.
+- 9 acceptance criteria passed.
+- 0 failed criteria.
+- 0 unverified criteria.
+- 0 warning failures or unverified warning criteria.
+
+## Decision
+
+The contrast-token and control-size findings are resolved against the current UIX verifier. AegisOPS passes its complete release profile set under the strict warning-level policy. Reopen this decision if product UI changes or a newer verifier introduces evidence that invalidates these results.

package/knowledge-base/benchmarks/aegisops/MANIFEST.md

@@ -0,0 +1,56 @@
+# AegisOPS Benchmark Manifest
+
+This benchmark turns independently normalized AegisOPS product evidence into executable requirements. It is not a replacement application, a style template, or permission to copy obsolete implementation details.
+
+## Authority Order
+
+1. Current AegisOPS requirements and working implementation are authoritative for behavior, data contracts, supported modes, and framework choices.
+2. `SOURCE-EVIDENCE.md` records the normalized product and design snapshot without requiring the local raw corpus.
+3. `product-contract.yaml` is the normalized benchmark contract used by ZtotheZ Design Engineering validation tools.
+4. Current task completion, state integrity, and accessible operation override historical fixed compositions.
+5. Historical implementation and submission material explains intent only and may contain obsolete technology, claims, labels, and integrations.
+6. Root `SKILL.md` remains the governing design-engineering instruction.
+
+When sources disagree, preserve current product behavior and record the discrepancy. Never silently restore an old framework, dependency, fixed layout, metric, or marketing claim.
+
+## Corpus Boundaries
+
+- AegisOPS is user-owned source material, not a third-party design-skill dependency.
+- No AegisOPS application code, images, UI-kit implementation, or submission material is imported or packaged by this benchmark.
+- `SOURCE-EVIDENCE.md` stores independently authored product observations and hashes for local provenance inputs.
+- Repeated local design-system fragments are duplicate evidence and must not be weighted as independent support.
+- Unrelated financial and roadmap material is outside this benchmark and must never be retrieved or packaged.
+
+## Benchmark Use
+
+Use this benchmark to evaluate whether an implementation:
+
+- Supports the operator's complete detection-readiness task rather than presenting a decorative SOC dashboard.
+- Preserves Single Technique, APT Group, Kill Chain, and Topology Lab semantics.
+- Exposes pipeline progress, success, failure, retry, and labeled demo fallback states.
+- Connects coverage, safety, latency, and readiness values to inspectable evidence.
+- Produces usable Sigma, SPL, playbook, VECTR, validation, and PDF artifacts where supported.
+- Keeps consequential status and controls readable and operable at every required viewport.
+- Makes authorized defensive scope explicit and avoids unsupported offensive or commercial claims.
+
+Run `npm run validate-contract -- --contract knowledge-base/benchmarks/aegisops/product-contract.yaml` before using this benchmark in a quality gate.
+
+Execute one runtime profile against an already-running application with:
+
+```bash
+npm run verify-ui -- --url URL \
+  --journeys knowledge-base/benchmarks/aegisops/journeys.json \
+  --profile responsive-overview
+```
+
+Run all required stages and produce one handoff decision with:
+
+```bash
+npm run quality-gate -- \
+  --contract knowledge-base/benchmarks/aegisops/product-contract.yaml \
+  --repo PATH_TO_AEGISOPS_FRONTEND \
+  --url URL \
+  --profile responsive-overview
+```
+
+Manual-review criteria require a human-authored attestation file. Start from `attestations.template.yaml`; do not treat an empty template as evidence. AI agents may format reviewer-provided findings but must never invent a reviewer, review time, decision, or evidence path.

package/knowledge-base/benchmarks/aegisops/SOURCE-EVIDENCE.md

@@ -0,0 +1,45 @@
+# AegisOPS Source Evidence
+
+## Snapshot
+
+- Observed: 2026-08-26
+- Ownership context: user-owned portfolio project and design material
+- Runtime dependency: none; the original files are local provenance inputs and are not distributed
+- Product domain: security-operations readiness and defensive detection engineering
+- Current implementation boundary: application behavior overrides historical design and submission material
+
+## Normalized Product Evidence
+
+- A senior SOC analyst or detection engineer selects an authorized MITRE ATT&CK technique or scenario and runs a staged Threat, Detection, Response, and Validation workflow.
+- The pipeline must expose its current stage, completion, failure, retry, and explicitly labeled demo fallback instead of replacing unavailable live evidence with unlabeled mock output.
+- Results connect scenario inputs and observables to Sigma-style detection logic, SPL hunting guidance, SOC response actions, coverage evaluation, and supported export artifacts.
+- Coverage, safety, latency, model status, and readiness values require an inspectable source. Decorative percentages or status labels are not acceptable evidence.
+- Single Technique, APT Group, Kill Chain, and Topology Lab are distinct task modes. Shared pipeline state must not erase their different inputs, progression, outputs, and recovery needs.
+- Generated security content remains bounded to authorized defensive use and known ATT&CK behavior. It is reviewable engineering output, not automatic production truth.
+
+## Normalized Design Evidence
+
+- The primary surface is an operational command center, so the current task, pipeline state, findings, evidence, recovery controls, and exports take precedence over promotional content.
+- Semantic status colors distinguish live, ready, warning, fallback, and failure states, but color is never the only carrier of meaning.
+- Agent stages use stable identity and ordering while component composition adapts to available width. A historical desktop mockup is not permission for fixed-width clipping.
+- Typography, contrast, focus, target size, keyboard operation, reflow, text resizing, and reduced-motion behavior remain quality-gate concerns even when historical visual material omitted them.
+- The interface uses restrained operational language. Claims about coverage, performance, hardware, models, integrations, or commercial impact require current evidence.
+
+## Provenance Boundaries
+
+- No original application code, UI kit implementation, image, slide, submission text, or archived skill is imported by this benchmark.
+- The distributable benchmark contains independently normalized behavioral requirements, acceptance criteria, journeys, anti-patterns, and source hashes only.
+- Repeated local design-system copies are duplicate evidence and must not increase a recommendation's weight.
+- Unrelated local financial and roadmap data is outside this product benchmark and must never be retrieved or packaged.
+
+## Local Snapshot Hashes
+
+| Local provenance input | SHA-256 |
+|---|---|
+| Design-system handbook | `75281f7dc0fc279b583c87ce2e135ea74ec798be33859f7f2ca356e9e28f7663` |
+| Command-center composition | `f0c81df7551d2e26d57291863be0b5a5846b51f5a72924d0c21b5762525a6ca1` |
+| Desktop visual reference | `866a06f75c08b2097bf9275d39308f414ead234b37c62cf63a7a6627b76f5b67` |
+| Historical product README | `504c0d8fda01a4fee9b18a7110a0125cddbfc2cf797a424e9cb5f78d35dcda05` |
+| Historical submission framing | `238121f7d0ee0c3f037bbb60ed5adb50d05ae116ea08d60a690c573cd5592150` |
+
+A hash change is a review trigger, not proof that the benchmark or product regressed. Inspect current product behavior before revising this normalized record.

package/knowledge-base/benchmarks/aegisops/acceptance-criteria.md

@@ -0,0 +1,42 @@
+# AegisOPS Acceptance Criteria
+
+The machine-readable criteria live in `product-contract.yaml`. This document explains how reviewers should interpret their evidence.
+
+## Product Coherence
+
+- A mode changes the task model, accepted input, progress semantics, and result grouping. It is not merely a selected visual tab.
+- The selected scenario remains identifiable in every generated output and export.
+- The four agent stages have distinct responsibilities. Their outputs must not collapse into interchangeable generic text.
+- Validation reports both covered and missing observables. A high score without inspectable evidence is a failure.
+
+## State And Recovery
+
+- Idle explains the required input and does not imply that results already exist.
+- Running identifies progress, prevents duplicate submission, retains input, and keeps unrelated navigation usable.
+- Success exposes artifacts and evidence without replacing the operator's input or history.
+- Error explains the recoverable cause, preserves the scenario, and presents retry and Demo mode guidance.
+- Demo mode is labeled before and after execution. Historical AMD or ROCm evidence must not appear as a current live measurement.
+
+## Responsive Operation
+
+At 375, 768, 1024, and 1440 CSS pixels:
+
+- Hero status, mission controls, pipeline metadata, readiness gates, logs, and agent status remain readable.
+- Dense two-column desktop groups stack or adapt before labels and values collide.
+- No `overflow: hidden` container may conceal operational text or controls.
+- Logs and data regions may scroll internally when clearly bounded, but the page must not create competing horizontal scroll regions.
+- Primary run, retry, and export actions remain reachable by keyboard and pointer.
+
+## Evidence Standard
+
+An acceptance criterion passes only when the required evidence type exists:
+
+- `contract`: the requirement and source of truth are explicitly defined.
+- `runtime`: browser assertions prove rendered behavior.
+- `screenshot`: the complete viewport can be inspected without clipping or overlap.
+- `network`: request status and returned data support the UI claim.
+- `accessibility`: names, focus behavior, announcements, and non-color cues are verified.
+- `export`: downloaded content matches the current run and expected format.
+- `manual-review`: a qualified reviewer checks semantic or safety quality that cannot be inferred from presentation alone.
+
+Passing screenshots alone never prove product coherence, metric validity, or export integrity.

package/knowledge-base/benchmarks/aegisops/anti-patterns.md

@@ -0,0 +1,19 @@
+# AegisOPS Anti-Patterns
+
+Use these as rejection examples when generating or reviewing an AegisOPS implementation.
+
+| Anti-pattern | Why it fails | Required correction |
+|---|---|---|
+| Decorative SOC shell | Panels and terminal styling exist, but the operator cannot complete a scenario-to-detection workflow | Start from the selected mode, input contract, pipeline state, evidence, and exports; apply styling afterward |
+| Untraceable coverage score | A percentage appears without covered and missing observables or a validator source | Bind the score to structured validation evidence and expose the supporting lists |
+| Fake live infrastructure | Static model, GPU, endpoint, latency, or throughput values appear as current status | Measure current requests or label the values as bundled demo provenance |
+| Hidden demo fallback | Precomputed output is presented without a persistent Demo mode label | Label fallback before submission, in progress, in results, and in exports |
+| Fixed mockup layout | The 1600 by 1000 reference is scaled or clipped at smaller widths | Recompose dense rows, stack panels, and verify all required viewports |
+| Clipped operational status | `overflow: hidden` conceals a status pill, gate value, label, or action | Allow the content to wrap or change layout; use `data-ztothez-design-allow-clipping` only for verified non-semantic decoration |
+| Colliding gate labels | Readiness labels and values overlap in narrow cards | Increase track constraints, stack label and value, or reduce simultaneous columns |
+| Color-only readiness | Green, amber, or red is the only indication of gate state | Add explicit READY, PENDING, PASS, WARNING, or ERROR text and assistive-technology output |
+| Generic agent cards | Every agent shows interchangeable copy with no input/output contract | Expose each stage's role, progress, evidence contribution, and completion state |
+| Cleared failure state | A request failure removes the scenario or partial evidence | Preserve input and prior evidence, explain the failure, and provide retry and fallback actions |
+| Export theater | Download buttons generate placeholders or content unrelated to the visible run | Generate from the current structured result and verify filename, MIME type, content, and failure handling |
+| Raw backend failure | Stack traces, proxy internals, or unexplained status codes are shown to the operator | Log diagnostics outside JSON-RPC or UI output and present actionable recovery copy |
+| Unsupported claims | Historical hackathon cost, performance, or superiority language is reused as fact | Remove it or attach current, reviewable evidence and scope |

package/knowledge-base/benchmarks/aegisops/attestations.template.yaml

@@ -0,0 +1,3 @@
+version: "1.0"
+contract: aegisops
+attestations: []

package/knowledge-base/benchmarks/aegisops/attestations.yaml

@@ -0,0 +1,115 @@
+version: "1.0"
+contract: aegisops
+attestations:
+  - criterion: evidence-backed-results
+    status: pass
+    reviewer: "ZtotheZ"
+    reviewedAt: "2026-08-25T19:30:00+03:00"
+    notes: |
+      Inspected three claims about the generated Sigma rule and detection pipeline:
+
+      1. CLAIM: Rule refers to T1059.001
+         EVIDENCE: Rule ID explicitly tagged `attack.t1059.001`, mapped to correct technique,
+         referenced in MITRE ATT&CK link (https://attack.mitre.org/techniques/T1059.001/).
+         Screenshot UI shows mission input targeting T1059.001 directly.
+         STATUS: ✓ PASS
+
+      2. CLAIM: Detection logic traces to observable Windows signals
+         EVIDENCE: Rule breaks into five concrete signal layers:
+         - Office parent (WINWORD/EXCEL/OUTLOOK) spawning powershell.exe with -EncodedCommand
+         - PowerShell Event ID 4104 script block logging with Invoke-Expression/IEX patterns
+         - Sysmon Event ID 11 temp file writes to AppData\Local\Temp\*.ps1
+         - Sysmon Event ID 3 network connections from powershell.exe to ports 80/443/5985
+         - Windows Event ID 4624 LogonType 3 for lateral WinRM movement detection
+         All observables are real Windows events; no fabricated fields or invented event codes.
+         STATUS: ✓ PASS
+
+      3. CLAIM: No unrelated or fabricated outputs
+         EVIDENCE: Verified all EventIDs (4104, 11, 3, 4624) are real Windows security events.
+         All field names (ParentImage, CommandLine, ScriptBlockText) are authentic Windows log fields.
+         False positives are realistic (Office macros, IT admin tools, patch management) not generic padding.
+         Rule marked as "experimental" status—honest about maturity level.
+         STATUS: ✓ PASS
+
+      OVERALL: All three claims verified. The Sigma rule is real, properly mapped to T1059.001,
+      uses observable Windows signals, and contains no fabrication. Ready for detection engineering use.
+    evidence:
+      - ".uix-quality-gate/aegis-demo-evidence/runtime/journey-single-technique-success.png"
+      - ".uix-quality-gate/aegis-demo-evidence/runtime/journey-single-technique-success-step-9-sigma_T1059.001.yml"
+
+  - criterion: evidence-backed-metrics
+    status: pass
+    reviewer: "ZtotheZ"
+    reviewedAt: "2026-08-25T19:30:00+03:00"
+    notes: |
+      Inspected how displayed metrics (coverage=97%, product_readiness=96%, safety_verdict=PASS)
+      trace to the structured demo result.
+
+      EVIDENCE CHAIN:
+      1. Source: demo_output.py contains hardcoded DEMO_VERIFIER_OUTPUT with JSON metrics:
+         - coverage_score: 97
+         - product_readiness_score: 96
+         - safety_verdict: "PASS"
+         - verdict: "PASS"
+
+      2. Pipeline: DEMO_INVOKE_RESULT wraps this output and is returned by server.py when
+         demo mode is active (line 356: "if req.demo_mode: result = DEMO_INVOKE_RESULT")
+
+      3. SSE Stream: server.py parses verifier output via _parse_verifier() (lines 80-99),
+         extracting coverage, product_readiness, safety_verdict, and passing to frontend
+         in the "done" SSE event payload
+
+      4. Frontend: page.tsx receives metrics in run.scores object and displays them in:
+         - Console logs (line 186: coverage=${run.scores.coverage}%)
+         - Alert history cards (line 294: coverage {run.scores.coverage}%)
+         - Readiness gates (derived from run.scores status)
+
+      VERIFICATION:
+      - Screenshots show Coverage Gate READY, Product Readiness ENABLED, Safety Gate PASS
+      - These match the demo_output.py metrics exactly (97%, 96%, PASS)
+      - Verifier model labeled "Qwen Validator Demo" (from demo_output.py line 691)
+      - System status shows "OFFLINE · DEMO FALLBACK ACTIVE" when endpoint unreachable
+
+      ASSESSMENT: Metrics are fully traceable to structured demo data. No live computation;
+      all values come from hardcoded demo result. Frontend correctly presents verifier model
+      name and validation verdict. System can distinguish demo vs. live mode via SSE flag.
+
+      PARTIAL NOTE: Individual metric cards could benefit from explicit "Demo" badge watermark
+      for additional clarity (currently relies on system-level "Demo Fallback" indicator).
+      This is a UI/UX enhancement, not a correctness issue.
+
+      STATUS: ✓ PASS
+    evidence:
+      - ".uix-quality-gate/aegis-demo-evidence/runtime/journey-single-technique-success.png"
+      - "/home/ztothez/Studio/portfolio/AegisOPS/demo_output.py"
+      - "/home/ztothez/Studio/portfolio/AegisOPS/server.py"
+      - "/home/ztothez/Studio/portfolio/AegisOPS/frontend/src/app/page.tsx"
+
+  - criterion: authorized-scope
+    status: pass
+    reviewer: "ZtotheZ"
+    reviewedAt: "2026-08-25T19:30:00+03:00"
+    notes: |
+      Inspected the generated output for zero-day claims, unauthorized exploitation,
+      offensive guidance, and unsupported production-readiness claims.
+
+      The material is explicitly framed as authorized purple-team validation for public
+      MITRE ATT&CK technique T1059.001. Validation commands are described as non-weaponized
+      telemetry references, use placeholders for sensitive values, and support detection
+      engineering rather than exploitation.
+
+      The Sigma rule remains experimental and requires environment-specific tuning,
+      baselining, fleet logging verification, and another validation run before promotion.
+      Documented limitations include SIEM correlation requirements, backend-specific regex,
+      separate Sysmon DNS coverage, and cross-host authentication aggregation. These gaps
+      prevent the output from implying complete or automatic production readiness.
+
+      Response guidance is limited to defensive triage, containment, hunting, mitigation,
+      hardening, and escalation. Deployment and suppression decisions require owner review.
+
+      PASS: authorized defensive scope is explicit; no zero-day, unauthorized-use, or
+      automatic-production claims were found.
+    evidence:
+      - ".uix-quality-gate/aegis-demo-evidence/runtime/journey-single-technique-success-step-9-sigma_T1059.001.yml"
+      - "knowledge-base/benchmarks/aegisops/product-contract.yaml"
+      - "/home/ztothez/Studio/portfolio/AegisOPS/demo_output.py"