Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions .github/workflows/validate.yml
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,8 @@ jobs:
node -c scripts/test-validate-governance.mjs
node -c scripts/validate-domains.mjs
node -c scripts/test-validate-domains.mjs
node -c scripts/validate-design-terminology.mjs
node -c scripts/test-validate-design-terminology.mjs
node -c scripts/validate-consumer-reference.mjs
node -c scripts/test-validate-consumer-reference.mjs
node -c scripts/consumer-reference-case-runner.mjs
Expand Down Expand Up @@ -118,6 +120,8 @@ jobs:
run: |
node scripts/validate-domains.mjs --json
node scripts/test-validate-domains.mjs
node scripts/validate-design-terminology.mjs --json
node scripts/test-validate-design-terminology.mjs

- name: Unity organization compressed wiki check
run: |
Expand Down
3 changes: 2 additions & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ description: Rules coding agents must follow when editing this governed multi-do

# Agent Instructions

This repository is StyleGallery: a governed gallery with Layout, Motion, Design Engineering, Game UI, and Platform Guides domains. Read [StyleGallery Domains](DOMAINS.md) before adding a domain, changing a domain boundary, or adapting an external source.
This repository is StyleGallery: a governed gallery with Layout, Motion, Design Engineering, Game UI, Platform Guides, and Design Terminology domains. Read [StyleGallery Domains](DOMAINS.md) before adding a domain, changing a domain boundary, or adapting an external source.

Before editing generated artifacts, validators, lifecycle state, or ownership policy, read [Governance, Lifecycle, And Docs-As-Code](GOVERNANCE.md).

Expand All @@ -18,6 +18,7 @@ Before editing generated artifacts, validators, lifecycle state, or ownership po
- Treat `consumer-reference/` as shared non-domain schema, provenance, routing, and evidence infrastructure; it owns no profile values, visual defaults, component implementation, or product CSS.
- Keep dependency direction consumer/profile -> Layout. Do not import consumer-reference records, profile data, tokens, or decorative values into `layout/**`, `patterns/**`, `scripts/pattern-data.mjs`, or `CATALOG.md`.
- Include the consumer-reference handoff field in implementation handoffs. For this repository-wide agent surface use `consumer_reference: consumer-reference/agent-native/registry.json`; otherwise use one normalized repository-relative JSON record or `not_applicable` with a sentence reason.
- When an implementation handoff relies on design-terminology records, declare the term identifiers and relation types used and whether the named sources were re-checked in the session; unverified reliance must be marked as such.
- Keep material v2, v1 trust/conformance, CLI/MCP transport, and A2A/AG-UI extension planes separate. Material admission never imports profiles, source code, fixtures, schemas, tests, `.omo`, or visual defaults.
- Validate canonical evidence v2 against its recorded immutable Git revision. Use current-authoring source checks only when creating or finalizing new capture evidence; do not recapture merely because later repository changes differ.
- Treat `consumer-reference/policies/lifecycle-dispositions.json` as the lifecycle index. Preserve named owners, caller status `unknown`, deadlines, extension dispositions, and immutable archive bindings until their machine gate authorizes a transition.
Expand Down
16 changes: 10 additions & 6 deletions DOMAINS.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,20 +19,22 @@ This manifest is the source of truth for top-level StyleGallery domains. A domai
| Design Engineering | [Design Engineering](design-engineering/index.md) | `experimental` | Product-layer craft questions and evidence-bearing decisions. | A second shared principle system or taste as proof. | Design Engineering domain owner |
| Game UI | [Game UI](game-ui/index.md) | `experimental` | Game-interface classification, hierarchy, reference records, and implementation guides nested by engine. | Reusable Layout CSS or claims that one engine structure is universal. | Game UI domain owner |
| Platform Guides | [Platform Guides](platform-guides/index.md) | `experimental` | Comparative references for a named platform and version context. | Affiliation, brand imitation, or authority over web standards. | Platform Guides domain owner |
| Design Terminology | [Design Terminology](design-terminology/index.md) | `experimental` | Source-kind classification, concept-family classification, typed term relations, and cross-system conflict cases for named vocabulary sources. | StyleGallery's own controlled vocabulary, motion terminology, visual token values, universal naming prescriptions, or authority over external vocabularies. | Design Terminology domain owner |

## Page Manifest

| Domain | Manual hub | Governed leaves |
| --- | --- | --- |
| Layout | `layout/index.md` | Existing `GUIDE.md`, Layout-specific `guides/*.md`, and `recipes/*.md`; generated `patterns/**/*.md` and `CATALOG.md` remain at current paths. Shared `quality/**/*.md` infrastructure governs every domain without becoming a Layout leaf. |
| Motion | `motion/index.md` | `motion/vocabulary.md`, `motion/review-workflow.md`, `motion/practice-reference.md` |
| Design Engineering | `design-engineering/index.md` | `design-engineering/interface-craft.md`, `design-engineering/consumer-migration-readiness.md`, `design-engineering/reference-profiles/index.md`, `design-engineering/reference-profiles/governed-local/index.md`, `design-engineering/reference-profiles/external-adaptation/index.md` |
| Game UI | `game-ui/index.md` | `game-ui/classification.md`, `game-ui/screen-hierarchy.md`, `game-ui/reference-record.md`, `game-ui/unity/architecture.md`, `game-ui/unity/ui-systems.md`, `game-ui/unity/cli-loop.md`, `game-ui/unity/repository-map.md`, `game-ui/unity/org-wiki.md` |
| Platform Guides | `platform-guides/index.md` | `platform-guides/apple-interaction.md` |
| Motion | `motion/index.md` | `motion/vocabulary.md`, `motion/review-workflow.md`, `motion/practice-reference.md`, `motion/decision-tree.md`, `motion/motion-brief.md`, `motion/interaction-recipes.md` |
| Design Engineering | `design-engineering/index.md` | `design-engineering/interface-craft.md`, `design-engineering/consumer-migration-readiness.md`, `design-engineering/reference-profiles/index.md`, `design-engineering/reference-profiles/governed-local/index.md`, `design-engineering/reference-profiles/external-adaptation/index.md`, `design-engineering/decision-tree.md`, `design-engineering/component-contract.md`, `design-engineering/worked-examples.md` |
| Game UI | `game-ui/index.md` | `game-ui/classification.md`, `game-ui/screen-hierarchy.md`, `game-ui/reference-record.md`, `game-ui/unity/architecture.md`, `game-ui/unity/ui-systems.md`, `game-ui/unity/cli-loop.md`, `game-ui/unity/repository-map.md`, `game-ui/unity/org-wiki.md`, `game-ui/decision-tree.md`, `game-ui/screen-recipes.md`, `game-ui/verification-workflow.md` |
| Platform Guides | `platform-guides/index.md` | `platform-guides/apple-interaction.md`, `platform-guides/adaptation-workflow.md`, `platform-guides/android-interaction.md`, `platform-guides/windows-interaction.md`, `platform-guides/compatibility-matrix.md` |
| Design Terminology | `design-terminology/index.md` | `design-terminology/source-kinds.md`, `design-terminology/source-vocabularies.md`, `design-terminology/concept-families.md`, `design-terminology/relation-types.md`, `design-terminology/conflict-cases.md`, `design-terminology/comparison-workflow.md` |

## Shared Non-Domain Infrastructure

[Consumer Reference](consumer-reference/index.md) is shared schema, provenance, routing, evidence, lifecycle, and machine-retrieval infrastructure outside the five-domain contract. Its source-bound material v2 index classifies admitted pages by these five domains but does not own their prose. It owns no profile implementation, visual values, or product CSS and cannot add a sixth domain row. Consumer or profile records may depend on Layout; Layout and its generated corpus cannot import consumer-reference, profile, material-registry, or transport records.
[Consumer Reference](consumer-reference/index.md) is shared schema, provenance, routing, evidence, lifecycle, and machine-retrieval infrastructure outside the six-domain contract. Its source-bound material v2 index classifies admitted pages by these six domains but does not own their prose. It owns no profile implementation, visual values, or product CSS and cannot add a seventh domain row. Consumer or profile records may depend on Layout; Layout and its generated corpus cannot import consumer-reference, profile, material-registry, or transport records.

## External Adaptation Contract

Expand All @@ -45,7 +47,9 @@ The initial five domain leaves are independent method rewrites inspired by [emil
- If recognizable upstream expression is added later, preserve the full upstream MIT notice and record the copied material separately before merge.
- Tracked repository documents must not depend on `.omo/`; stable upstream blob links and tracked repository contracts carry contributor-facing provenance.

`design-engineering/consumer-migration-readiness.md` is the separately declared StyleGallery-local leaf. It uses `provenance_kind: local`, carries no external source fields, and remains experimental. Its presence does not change the external-adaptation inventory or make its consumer-local method universal policy.
The workflow, brief, contract, recipe, and comparison leaves added under the five non-Layout domains are StyleGallery-local synthesis with `provenance_kind: local`; their worked scenarios are proposals, not captured product evidence. The domain indexes route selection, authoring, application, and verification.

`design-engineering/consumer-migration-readiness.md` is a separately declared StyleGallery-local leaf. It uses `provenance_kind: local`, carries no external source fields, and remains experimental. Its presence does not change the external-adaptation inventory or make its consumer-local method universal policy.

## Lifecycle And Staleness

Expand Down
10 changes: 9 additions & 1 deletion GOVERNANCE.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,11 +42,18 @@ Use this file before editing repository documentation. It names which file is au
| Design Engineering domain guidance | `design-engineering/*.md` | Manual | None | `experimental` | Upstream revision, evidence boundary, or guidance changes. | `scripts/validate-domains.mjs` | Design Engineering domain owner |
| Game UI domain guidance | `game-ui/**/*.md` | Manual | None | `experimental` | Classification, hierarchy, engine implementation, evidence boundary, or route changes. | `scripts/validate-domains.mjs` | Game UI domain owner |
| Platform Guides domain guidance | `platform-guides/*.md` | Manual | None | `experimental` | Platform version, upstream revision, evidence boundary, or guidance changes. | `scripts/validate-domains.mjs` | Platform Guides domain owner |
| Design Terminology domain guidance | `design-terminology/*.md` | Manual; term and relation tables remain authoring sources | None | `experimental` | Source-kind, source-vocabulary, concept-family, relation-model, or conflict-case changes. | `scripts/validate-domains.mjs`, `scripts/validate-design-terminology.mjs` | Design Terminology domain owner |
| Pattern data and examples | `scripts/pattern-data.mjs` | Manual data source | `patterns/**/*.md`, `patterns/**/index.md`, `patterns/index.md`, `CATALOG.md` | `generated` output from `stable` source | Source-lineage URL changes, generated drift, category changes, or pattern count changes. | `scripts/validate-patterns.mjs`, `scripts/validate-catalog.mjs`, `scripts/validate-governance.mjs` | Pattern-data owner |
| Pattern generator | `scripts/generate-patterns.mjs` | Manual code source | `patterns/**/*.md`, `patterns/**/index.md`, `patterns/index.md`, `CATALOG.md` | `stable` generator, `generated` output | Generated structure changes, generated-warning changes, or generated metadata changes. | `node -c scripts/generate-patterns.mjs`, generated drift check, `scripts/validate-governance.mjs` | Pattern-data owner |
| Validation scripts | `scripts/validate-*.mjs`, `scripts/test-validate-*.mjs` | Manual code source | CI validation output | `stable` | Validator scope changes, fixture changes, or CI parity changes. | `node -c`, matching fixture tests, `.github/workflows/validate.yml` | Validation owner |
| CI workflows | `.github/workflows/validate.yml`, `.github/workflows/evidence-freshness.yml` | Manual | GitHub Actions runs and audit artifacts | `stable` | Validation step, explicit-deadline schedule, generated drift policy, or owner changes. | GitHub Actions, `scripts/validate-governance.mjs` | Repository governance owner |

## Domain Workflow Verification Boundary

The non-Layout hubs route selection, briefs/contracts, applied recipes or cases, and verification. Their local leaves declare `provenance_kind: local` and remain `experimental`. Worked examples contain expected outcomes, not captured product or engine evidence. `scripts/validate-domains.mjs` checks declared membership, provenance, sections, and routes; it does not execute those examples.

The Design Terminology Markdown tables additionally require directly located sources, labels, valid dates, explicit comparison scope and direction, and consistent relation graphs. `scripts/validate-design-terminology.mjs` and its negative fixtures check those record invariants; semantic accuracy and independent promotion review remain human judgments. Material v2 indexes only the admitted Markdown bytes. Changing the allowed document set requires updating its closed inventory, digest, package exposure, and generated registry together, without admitting code, schemas, profiles, or fixtures as material.

## Generated Artifact Policy

Generated files are not source of truth. Do not hand-edit generated artifacts to change pattern content or catalog structure.
Expand Down Expand Up @@ -98,7 +105,7 @@ Use these states in reviews and governance notes. Do not invent new lifecycle la
Default lifecycle:

- Root docs, guides, recipes, quality docs, validators, and CI are `stable` unless a page explicitly says otherwise.
- `DOMAINS.md`, the scope decision, and `layout/index.md` are `stable`; domain leaves under `motion/`, `design-engineering/`, `game-ui/`, and `platform-guides/` begin `experimental`.
- `DOMAINS.md`, the scope decision, and `layout/index.md` are `stable`; domain leaves under `motion/`, `design-engineering/`, `game-ui/`, `platform-guides/`, and `design-terminology/` begin `experimental`.
- Generated pattern docs, generated pattern indexes, and `CATALOG.md` are `generated`.
- Draft research artifacts under `.omo/` are `draft` or `experimental` and are not contributor-facing source of truth.

Expand All @@ -125,6 +132,7 @@ Consumer-reference ownership records the current truth as `owner.enforcement: "p
| `tests/**`, `playwright.config.mjs`, `consumer-reference/baselines/**`, `scripts/*baseline*.mjs`, `scripts/*sentinel*.mjs`, `scripts/*renderer-purity.mjs` | Repository governance owner with Validation owner | Pure rendering, computed semantics before screenshots, immutable browser pins, required consumer-conformance semantics, optional raster capture, calibration cardinality, and pending owner approval. |
| `game-ui/**` | Game UI domain owner | Player-task classification, hierarchy responsibility, reference records, engine-specific subtrees, and cross-engine boundaries. |
| `platform-guides/**` | Platform Guides domain owner | Platform/source/version limits, comparison boundaries, and stale review. |
| `design-terminology/**` | Design Terminology domain owner | Term-family classification, comparative system definitions, conflict-case boundaries, and external vocabulary citations. |
| `scripts/validate-*.mjs`, `scripts/test-validate-*.mjs`, `.github/workflows/validate.yml`, `.github/workflows/evidence-freshness.yml` | Validation owner | Validator scope, negative fixtures, blocking/advisory boundaries, CI parity. |

## Shared Promotion Governance
Expand Down
Loading
Loading