@ztothez/design-engineering 2.0.0

package/knowledge-base/design-intelligence/design-plan.md

@@ -0,0 +1,78 @@
+# Deterministic Design Plan Compiler
+
+Use this module after a version 1.0 product design brief is generation-ready and before production
+UI generation. The compiler turns product intent into an inspectable implementation boundary while
+preserving unresolved evidence as provisional or blocked work.
+
+## Compile Sequence
+
+1. Validate the brief. A draft or semantically invalid brief produces a blocked plan.
+2. Canonically hash the brief and record the compiler version. The same brief and compiler version
+   must produce the same plan without timestamps or environment-dependent identifiers.
+3. Build the six-level decision flow for every task: context and provenance, primary outcome and
+   action, impact and exceptions, evidence, bounded next action, then recovery and verification.
+4. Establish one stable task-oriented design route per task. The later generation adapter must map
+   it to an existing target router without collision and report unsupported integration.
+5. Separate the task shell, domain-state controller, decision summary, evidence detail, and bounded
+   action and recovery component. Rendering components do not own service or domain state.
+6. Assign every declared interface state to one domain-state controller and preserve its behavior,
+   disclosure, and recovery contract.
+7. Evaluate every downstream declaration. Existing product-task, interface-trust,
+   information-design, and design-deliverable files must remain inside the project root and pass
+   their maintained validators. Planned contracts remain provisional. Invalid or unavailable
+   existing contracts block implementation.
+8. Declare semantic color, typography, spacing, shape, motion, and data-visualization roles. Do not
+   generate raw design values at the planning stage.
+9. Preserve declared platforms, viewports, input modes, and constraints. Require browser evidence
+   for responsive order, reflow, text resize, focus, targets, and reduced motion.
+10. Derive assets only from brand or content requirements. Do not add decorative assets by default.
+    Every required asset needs purpose, provenance, rights, alternatives, and failure behavior.
+11. Copy acceptance methods and expected evidence into verification obligations. Human methods
+    remain future evidence requirements and never become generated attestations.
+
+## Readiness States
+
+- `blocked`: the brief is not generation-ready or a declared existing downstream contract is
+  invalid, unavailable, or outside the allowed root.
+- `provisional`: planning can continue, but a downstream contract or target route still requires
+  confirmation.
+- `ready`: every applicable downstream contract and target integration decision is confirmed. A
+  ready plan still does not prove implementation or release quality.
+
+`planningReady` authorizes bounded contract and architecture work. `implementationReady` authorizes
+the next generation adapter only after all implementation prerequisites are confirmed. Neither
+status authorizes release.
+
+## Traceability
+
+Every decision and generated section references one or more stable traces:
+
+- `brief`: a specific brief field or record.
+- `standard`: an independently maintained ZtotheZ design-engineering rule.
+- `assumption`: an explicit assumption already recorded in the brief.
+
+The compiler rejects its own output if any trace reference is missing. It does not introduce silent
+assumptions, generated personas, fake routes, unsupported data behavior, or human evidence.
+
+## Commands
+
+```bash
+npm run compile-plan -- \
+  --brief path/to/product-design-brief.yaml \
+  --project-root . \
+  --json
+```
+
+Installed clients can use `zz-design compile-plan`. MCP clients can call
+`compile_design_plan`. MCP uses `ZTOTHEZ_DESIGN_BRIEF_ROOTS`; the brief and every declared existing
+downstream contract must stay inside the matched configured root.
+
+Use `design-plan.schema.yaml` as the portable version 1.0 output contract.
+
+## Evidence Limits
+
+- Determinism proves repeatable transformation, not that the plan is the best product solution.
+- Contract validation proves declaration consistency, not rendered or runtime behavior.
+- A confirmed design route is not proof that a target application's router can accept it unchanged.
+- Token requirements do not prove visual composition, contrast, or responsive behavior.
+- Human-expert and representative-user obligations require attributable evidence outside the plan.

package/knowledge-base/design-intelligence/design-plan.schema.yaml

@@ -0,0 +1,621 @@
+$schema: http://json-schema.org/draft-07/schema#
+type: object
+properties:
+  version:
+    type: string
+    const: "1.0"
+  compilerVersion:
+    type: string
+    pattern: ^\d+\.\d+\.\d+$
+  id:
+    type: string
+    pattern: ^[a-z0-9][a-z0-9-]{0,127}$
+  product:
+    type: string
+    minLength: 1
+    maxLength: 2048
+  sourceBrief:
+    type: object
+    properties:
+      id:
+        type: string
+        pattern: ^[a-z0-9][a-z0-9-]{0,127}$
+      version:
+        type: string
+        const: "1.0"
+      file:
+        type: string
+        minLength: 1
+        maxLength: 2048
+      digest:
+        type: string
+        pattern: ^[a-f0-9]{64}$
+      generationReady:
+        type: boolean
+    required:
+      - id
+      - version
+      - file
+      - digest
+      - generationReady
+    additionalProperties: false
+  status:
+    type: string
+    enum:
+      - blocked
+      - provisional
+      - ready
+  planningReady:
+    type: boolean
+  implementationReady:
+    type: boolean
+  traces:
+    minItems: 1
+    maxItems: 10000
+    type: array
+    items:
+      type: object
+      properties:
+        id:
+          type: string
+          pattern: ^[a-z0-9][a-z0-9-]{0,127}$
+        kind:
+          type: string
+          enum:
+            - brief
+            - standard
+            - assumption
+        reference:
+          type: string
+          minLength: 1
+          maxLength: 2048
+        description:
+          type: string
+          minLength: 1
+          maxLength: 2048
+      required:
+        - id
+        - kind
+        - reference
+        - description
+      additionalProperties: false
+  decisions:
+    minItems: 1
+    maxItems: 10000
+    type: array
+    items:
+      type: object
+      properties:
+        id:
+          type: string
+          pattern: ^[a-z0-9][a-z0-9-]{0,127}$
+        status:
+          type: string
+          enum:
+            - confirmed
+            - provisional
+            - blocked
+        statement:
+          type: string
+          minLength: 1
+          maxLength: 2048
+        rationale:
+          type: string
+          minLength: 1
+          maxLength: 2048
+        traceRefs:
+          minItems: 1
+          maxItems: 100
+          type: array
+          items:
+            type: string
+            pattern: ^[a-z0-9][a-z0-9-]{0,127}$
+      required:
+        - id
+        - status
+        - statement
+        - rationale
+        - traceRefs
+      additionalProperties: false
+  informationArchitecture:
+    minItems: 1
+    type: array
+    items:
+      type: object
+      properties:
+        id:
+          type: string
+          pattern: ^[a-z0-9][a-z0-9-]{0,127}$
+        order:
+          type: integer
+          minimum: 1
+          maximum: 9007199254740991
+        label:
+          type: string
+          minLength: 1
+          maxLength: 2048
+        purpose:
+          type: string
+          minLength: 1
+          maxLength: 2048
+        contentRefs:
+          minItems: 1
+          type: array
+          items:
+            type: string
+            minLength: 1
+            maxLength: 2048
+        traceRefs:
+          minItems: 1
+          maxItems: 100
+          type: array
+          items:
+            type: string
+            pattern: ^[a-z0-9][a-z0-9-]{0,127}$
+      required:
+        - id
+        - order
+        - label
+        - purpose
+        - contentRefs
+        - traceRefs
+      additionalProperties: false
+  routes:
+    minItems: 1
+    type: array
+    items:
+      type: object
+      properties:
+        id:
+          type: string
+          pattern: ^[a-z0-9][a-z0-9-]{0,127}$
+        path:
+          type: string
+          pattern: ^\/[a-z0-9/-]*$
+        taskRef:
+          type: string
+          pattern: ^[a-z0-9][a-z0-9-]{0,127}$
+        status:
+          type: string
+          enum:
+            - confirmed
+            - provisional
+            - blocked
+        purpose:
+          type: string
+          minLength: 1
+          maxLength: 2048
+        traceRefs:
+          minItems: 1
+          maxItems: 100
+          type: array
+          items:
+            type: string
+            pattern: ^[a-z0-9][a-z0-9-]{0,127}$
+      required:
+        - id
+        - path
+        - taskRef
+        - status
+        - purpose
+        - traceRefs
+      additionalProperties: false
+  components:
+    minItems: 1
+    type: array
+    items:
+      type: object
+      properties:
+        id:
+          type: string
+          pattern: ^[a-z0-9][a-z0-9-]{0,127}$
+        taskRef:
+          type: string
+          pattern: ^[a-z0-9][a-z0-9-]{0,127}$
+        boundary:
+          type: string
+          minLength: 1
+          maxLength: 2048
+        responsibility:
+          type: string
+          minLength: 1
+          maxLength: 2048
+        ownsState:
+          maxItems: 20
+          type: array
+          items:
+            type: string
+        inputs:
+          maxItems: 30
+          type: array
+          items:
+            type: string
+            minLength: 1
+            maxLength: 2048
+        outputs:
+          maxItems: 30
+          type: array
+          items:
+            type: string
+            minLength: 1
+            maxLength: 2048
+        traceRefs:
+          minItems: 1
+          maxItems: 100
+          type: array
+          items:
+            type: string
+            pattern: ^[a-z0-9][a-z0-9-]{0,127}$
+      required:
+        - id
+        - taskRef
+        - boundary
+        - responsibility
+        - ownsState
+        - inputs
+        - outputs
+        - traceRefs
+      additionalProperties: false
+  stateOwnership:
+    minItems: 1
+    type: array
+    items:
+      type: object
+      properties:
+        state:
+          type: string
+        taskRefs:
+          minItems: 1
+          type: array
+          items:
+            type: string
+            pattern: ^[a-z0-9][a-z0-9-]{0,127}$
+        ownerComponentRef:
+          type: string
+          pattern: ^[a-z0-9][a-z0-9-]{0,127}$
+        behavior:
+          type: string
+          minLength: 1
+          maxLength: 2048
+        recovery:
+          type: string
+          minLength: 1
+          maxLength: 2048
+        disclosure:
+          type: string
+          minLength: 1
+          maxLength: 2048
+        traceRefs:
+          minItems: 1
+          maxItems: 100
+          type: array
+          items:
+            type: string
+            pattern: ^[a-z0-9][a-z0-9-]{0,127}$
+      required:
+        - state
+        - taskRefs
+        - ownerComponentRef
+        - behavior
+        - recovery
+        - disclosure
+        - traceRefs
+      additionalProperties: false
+  contracts:
+    minItems: 4
+    maxItems: 4
+    type: array
+    items:
+      type: object
+      properties:
+        kind:
+          type: string
+          enum:
+            - product-task
+            - interface-trust
+            - information-design
+            - design-deliverable
+        declaration:
+          type: string
+          enum:
+            - planned
+            - exists
+            - not-applicable
+        validation:
+          type: string
+          enum:
+            - planned
+            - validated
+            - invalid
+            - not-applicable
+        source:
+          type: string
+          maxLength: 1024
+        passed:
+          type: boolean
+        findings:
+          type: integer
+          minimum: 0
+          maximum: 9007199254740991
+        reason:
+          type: string
+          minLength: 1
+          maxLength: 2048
+        traceRefs:
+          minItems: 1
+          maxItems: 100
+          type: array
+          items:
+            type: string
+            pattern: ^[a-z0-9][a-z0-9-]{0,127}$
+      required:
+        - kind
+        - declaration
+        - validation
+        - passed
+        - findings
+        - reason
+        - traceRefs
+      additionalProperties: false
+  tokenRequirements:
+    minItems: 1
+    type: array
+    items:
+      type: object
+      properties:
+        id:
+          type: string
+          pattern: ^[a-z0-9][a-z0-9-]{0,127}$
+        category:
+          type: string
+          enum:
+            - color
+            - typography
+            - spacing
+            - shape
+            - motion
+            - data-visualization
+        roles:
+          minItems: 1
+          type: array
+          items:
+            type: string
+            minLength: 1
+            maxLength: 2048
+        rule:
+          type: string
+          minLength: 1
+          maxLength: 2048
+        traceRefs:
+          minItems: 1
+          maxItems: 100
+          type: array
+          items:
+            type: string
+            pattern: ^[a-z0-9][a-z0-9-]{0,127}$
+      required:
+        - id
+        - category
+        - roles
+        - rule
+        - traceRefs
+      additionalProperties: false
+  responsiveBehavior:
+    minItems: 1
+    type: array
+    items:
+      type: object
+      properties:
+        platformRef:
+          type: string
+          pattern: ^[a-z0-9][a-z0-9-]{0,127}$
+        viewports:
+          minItems: 1
+          type: array
+          items:
+            type: integer
+            minimum: 240
+            maximum: 9007199254740991
+        inputModes:
+          minItems: 1
+          type: array
+          items:
+            type: string
+        rules:
+          minItems: 1
+          type: array
+          items:
+            type: string
+            minLength: 1
+            maxLength: 2048
+        traceRefs:
+          minItems: 1
+          maxItems: 100
+          type: array
+          items:
+            type: string
+            pattern: ^[a-z0-9][a-z0-9-]{0,127}$
+      required:
+        - platformRef
+        - viewports
+        - inputModes
+        - rules
+        - traceRefs
+      additionalProperties: false
+  assets:
+    type: object
+    properties:
+      status:
+        type: string
+        enum:
+          - confirmed
+          - provisional
+          - blocked
+      requirements:
+        type: array
+        items:
+          type: object
+          properties:
+            id:
+              type: string
+              pattern: ^[a-z0-9][a-z0-9-]{0,127}$
+            purpose:
+              type: string
+              minLength: 1
+              maxLength: 2048
+            rightsRequired:
+              type: boolean
+            alternativesRequired:
+              type: boolean
+            traceRefs:
+              minItems: 1
+              maxItems: 100
+              type: array
+              items:
+                type: string
+                pattern: ^[a-z0-9][a-z0-9-]{0,127}$
+          required:
+            - id
+            - purpose
+            - rightsRequired
+            - alternativesRequired
+            - traceRefs
+          additionalProperties: false
+      rule:
+        type: string
+        minLength: 1
+        maxLength: 2048
+      traceRefs:
+        minItems: 1
+        maxItems: 100
+        type: array
+        items:
+          type: string
+          pattern: ^[a-z0-9][a-z0-9-]{0,127}$
+    required:
+      - status
+      - requirements
+      - rule
+      - traceRefs
+    additionalProperties: false
+  implementationStages:
+    minItems: 1
+    type: array
+    items:
+      type: object
+      properties:
+        id:
+          type: string
+          pattern: ^[a-z0-9][a-z0-9-]{0,127}$
+        order:
+          type: integer
+          minimum: 1
+          maximum: 9007199254740991
+        name:
+          type: string
+          minLength: 1
+          maxLength: 2048
+        exitCondition:
+          type: string
+          minLength: 1
+          maxLength: 2048
+        status:
+          type: string
+          enum:
+            - confirmed
+            - provisional
+            - blocked
+        traceRefs:
+          minItems: 1
+          maxItems: 100
+          type: array
+          items:
+            type: string
+            pattern: ^[a-z0-9][a-z0-9-]{0,127}$
+      required:
+        - id
+        - order
+        - name
+        - exitCondition
+        - status
+        - traceRefs
+      additionalProperties: false
+  verificationObligations:
+    minItems: 1
+    type: array
+    items:
+      type: object
+      properties:
+        id:
+          type: string
+          pattern: ^[a-z0-9][a-z0-9-]{0,127}$
+        acceptanceCriterionRef:
+          type: string
+          pattern: ^[a-z0-9][a-z0-9-]{0,127}$
+        taskRefs:
+          minItems: 1
+          type: array
+          items:
+            type: string
+            pattern: ^[a-z0-9][a-z0-9-]{0,127}$
+        method:
+          type: string
+        blocking:
+          type: boolean
+        expectedEvidence:
+          type: string
+          minLength: 1
+          maxLength: 2048
+        traceRefs:
+          minItems: 1
+          maxItems: 100
+          type: array
+          items:
+            type: string
+            pattern: ^[a-z0-9][a-z0-9-]{0,127}$
+      required:
+        - id
+        - acceptanceCriterionRef
+        - taskRefs
+        - method
+        - blocking
+        - expectedEvidence
+        - traceRefs
+      additionalProperties: false
+  blockers:
+    type: array
+    items:
+      type: string
+      minLength: 1
+      maxLength: 2048
+  limitations:
+    minItems: 1
+    type: array
+    items:
+      type: string
+      minLength: 1
+      maxLength: 2048
+required:
+  - version
+  - compilerVersion
+  - id
+  - product
+  - sourceBrief
+  - status
+  - planningReady
+  - implementationReady
+  - traces
+  - decisions
+  - informationArchitecture
+  - routes
+  - components
+  - stateOwnership
+  - contracts
+  - tokenRequirements
+  - responsiveBehavior
+  - assets
+  - implementationStages
+  - verificationObligations
+  - blockers
+  - limitations
+additionalProperties: false