ai-design-context 0.4.0

package/benchmarks/todo-app.md

@@ -0,0 +1,144 @@
+# Todo App Benchmark
+
+This is the reference benchmark scenario.
+
+Do not generate comparison results in this file.
+
+## Product Brief
+
+Create a modern consumer todo app for everyday personal task management.
+
+The app should help a busy person capture tasks quickly, see what matters today, complete tasks, and inspect optional details without turning the product into a project management dashboard.
+
+## Expected User
+
+- Adult consumer managing personal errands, reminders, and daily tasks.
+- Uses mobile frequently and desktop occasionally.
+- Wants low friction more than advanced planning.
+
+## Expected Platform
+
+- Responsive web app.
+- Must work well at mobile width around 390px.
+- Desktop layout may use additional space but must preserve the same product model.
+
+## Constraints
+
+- No authentication flow required.
+- No team collaboration required.
+- No analytics dashboard.
+- No project management concepts such as sprints, roadmaps, or velocity.
+- Include realistic empty, loading, and error states.
+- Include accessible labels and touch-friendly controls.
+- Keep optional metadata secondary.
+
+## Core User Tasks
+
+- Add a task quickly.
+- See today's tasks.
+- Mark a task complete.
+- Inspect or edit task details.
+- Recover from a failed save.
+
+## Evaluation Criteria
+
+Use `docs/EVALUATION_RUBRIC.md`.
+
+Pay special attention to:
+
+- Product Thinking;
+- UX;
+- Information Architecture;
+- Mobile-first;
+- State Design;
+- Simplicity;
+- Overall Product Quality.
+
+## Baseline Prompt
+
+```text
+Design and implement a responsive todo app for everyday personal task management.
+
+The app should let a user add tasks, see today's tasks, complete tasks, and edit details.
+
+Make it modern, usable, and polished.
+```
+
+## AI Design Context Prompt
+
+```text
+Design and implement a responsive todo app for everyday personal task management.
+
+Use AI Design Context from this repository.
+
+Follow the knowledge graph:
+research -> rules -> patterns -> prompts -> reference projects -> reviews
+
+Use existing rules and patterns only. Do not invent new rules or patterns.
+
+The app should let a user add tasks, see today's tasks, complete tasks, and edit details.
+
+Prioritize low-friction capture, a stable daily home surface, mobile-first behavior, context-preserving detail, accessible touch targets, and clear empty/loading/error states.
+```
+
+## Expected Outputs
+
+Both benchmark runs should publish:
+
+- prompt used;
+- generated source code or artifact;
+- screenshots or preview links for mobile and desktop;
+- notes about tool access and model settings;
+- evaluation table using `docs/EVALUATION_RUBRIC.md`.
+
+The expected product output should include:
+
+- daily task home surface;
+- quick add task path;
+- completed task behavior;
+- detail inspection or edit behavior;
+- empty state;
+- loading state;
+- error state;
+- accessible labels;
+- mobile layout.
+
+## Evaluation Template
+
+```md
+# Todo App Evaluation
+
+Scenario: Todo App
+Model:
+Date:
+Evaluator:
+
+| Category | Baseline | AI Design Context | Notes |
+| --- | ---: | ---: | --- |
+| Product Thinking |  |  |  |
+| UX |  |  |  |
+| Information Architecture |  |  |  |
+| Navigation |  |  |  |
+| Accessibility |  |  |  |
+| Mobile-first |  |  |  |
+| Visual Hierarchy |  |  |  |
+| State Design |  |  |  |
+| Consistency |  |  |  |
+| Performance Awareness |  |  |  |
+| Simplicity |  |  |  |
+| Overall Product Quality |  |  |  |
+
+Baseline average:
+AI Design Context average:
+Difference:
+
+## Evidence Links
+
+- Baseline output:
+- AI Design Context output:
+- Mobile screenshots:
+- Desktop screenshots:
+
+## Notes
+
+```

package/checklists/DESIGN_QA.md

@@ -0,0 +1,102 @@
+---
+id: CHECK-00001
+alias: CHECK-DESIGN-QA
+slug: design-qa
+title: Design QA Checklist
+object_type: checklist
+status: draft
+version: 0.4.0
+category: design-qa
+tags:
+  - checklist
+  - review
+  - design-qa
+maturity: seed
+risk_level: medium
+relationships:
+  - type: related_to
+    target: RULE-00001
+  - type: related_to
+    target: RULE-00002
+  - type: related_to
+    target: RULE-00003
+  - type: related_to
+    target: RULE-00004
+  - type: related_to
+    target: RULE-00005
+  - type: related_to
+    target: RULE-00006
+  - type: related_to
+    target: RULE-00007
+  - type: related_to
+    target: RULE-00008
+  - type: related_to
+    target: RULE-00009
+  - type: related_to
+    target: RULE-00010
+  - type: related_to
+    target: RULE-00011
+  - type: related_to
+    target: RULE-00012
+  - type: related_to
+    target: RULE-00013
+  - type: related_to
+    target: RULE-00014
+  - type: related_to
+    target: RULE-00015
+  - type: related_to
+    target: RULE-00016
+  - type: related_to
+    target: RULE-00017
+---
+
+# Design QA Checklist
+
+Use this checklist after applying research, rules, and patterns.
+
+## Rule Coverage
+
+- `PRD-001` - Is the repeated daily action prioritized?
+- `PRD-002` - Can users capture before organizing?
+- `IA-001` - Is there one stable home surface?
+- `IA-002` - Are core objects, states, and relationships clear?
+- `UX-001` - Are primary mobile actions thumb-reachable?
+- `UX-002` - Are advanced controls progressively disclosed?
+- `UX-003` - Can users inspect without losing context?
+- `VIS-001` - Are semantic tokens used for visual decisions?
+- `A11Y-001` - Are touch targets at least 44x44 CSS pixels?
+- `A11Y-002` - Are validation errors specific, textual, and recoverable?
+- `A11Y-003` - Does every keyboard-operable control retain visible focus?
+- `A11Y-004` - When non-essential motion exists, can users reduce or disable it?
+- `PERF-001` - Does asynchronous content preserve surrounding layout geometry?
+- `VIS-002` - Do expressive materials preserve content and primary-action priority?
+- `UX-004` - Does motion explain state continuity with reduced-motion and platform fallbacks?
+- `UX-005` - When work is delegated to an agent, are status, result, and intervention points observable?
+- `UX-006` - Are consequential actions confirmed with preserved object, consequence, and recovery context?
+
+## Pattern Coverage
+
+- Does the screen use a documented pattern when one applies?
+- Is the pattern appropriate for the product context?
+- Did the pattern preserve the user's primary job?
+- Did the pattern avoid copying a source product blindly?
+- If consequential side effects exist, did the screen use or explicitly reject `PAT-007`?
+
+## Final Checks
+
+- Product goal is clear.
+- Primary and secondary actions are visually distinct.
+- Empty, loading, error, success, and disabled states are accounted for.
+- Mobile layout works at 390px width.
+- Accessibility basics are present: labels, focus, contrast, target size, and textual error recovery.
+- State changes avoid unexpected layout shifts.
+- Motion, when present, has a reduced-motion equivalent.
+- Platform-specific visual effects and interaction APIs have appropriate fallbacks.
+- Visual direction cites observable references instead of imitating a brand.
+- Consequential actions preserve critical context through confirmation, challenge, error, retry, and success states.
+- Before broad design work, the agent asked whether to show multiple options or proceed with one conservative implementation path.
+
+## Evidence Boundary
+
+- Mark unrendered, unmeasured, or untested behavior as a gap rather than a pass.
+- Cite the reviewed artifact, prompt, reference project, or benchmark evidence in the resulting review object.

package/checklists/GENERATED_INDEX.md

@@ -0,0 +1,7 @@
+# Generated Checklists Index
+
+This file is generated from registry metadata. Do not edit manually.
+
+| ID | Alias | Title | Category | Status | Maturity | File Path | Rule Coverage | Used By |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| CHECK-00001 | CHECK-DESIGN-QA | Design QA Checklist | design-qa | draft | seed | checklists/DESIGN_QA.md | related_to: PRD-001 / RULE-00001 Daily Actions First<br>related_to: PRD-002 / RULE-00002 Low-Friction Capture Before Organization<br>related_to: IA-001 / RULE-00003 One Stable Home Surface<br>related_to: IA-002 / RULE-00004 Define The Object Model Before Screens<br>related_to: UX-001 / RULE-00005 Thumb-Zone Primary Actions<br>related_to: UX-002 / RULE-00006 Progressively Disclose Power<br>related_to: UX-003 / RULE-00007 Preserve Context During Inspection<br>related_to: VIS-001 / RULE-00008 Semantic Tokens Only<br>related_to: A11Y-001 / RULE-00009 44x44 Touch Targets<br>related_to: A11Y-002 / RULE-00010 Textual Input Error Recovery<br>related_to: PERF-001 / RULE-00011 Reserve Layout Space For Asynchronous Content<br>related_to: A11Y-003 / RULE-00012 Visible Keyboard Focus<br>related_to: A11Y-004 / RULE-00013 Reduce Non-Essential Interaction Motion<br>related_to: VIS-002 / RULE-00014 Keep Expression Subordinate To Content<br>related_to: UX-004 / RULE-00015 Use Motion To Explain State Continuity<br>related_to: UX-005 / RULE-00016 Expose Agent Work And Intervention<br>related_to: UX-006 / RULE-00017 Confirm Consequential Actions With Preserved Context | requires: PROMPT-DESIGN-EVIDENCE-REVIEW / PROMPT-00005 Design Evidence Review Prompt<br>requires: REVIEW-TODO-BENCHMARK / REVIEW-00001 Todo App Benchmark Reference Review<br>requires: REVIEW-TODO-RUNNABLE-FIXTURE / REVIEW-00002 Todo Runnable Fixture Review<br>requires: PROMPT-PROTOTYPE-REVIEW / PROMPT-00002 Prototype Review Prompt<br>requires: REVIEW-CONSEQUENTIAL-ACTION-CONFIRMATION / REVIEW-00003 Consequential Action Confirmation Validation Review |

package/docs/AGENT_CONTEXT.md

@@ -0,0 +1,111 @@
+# Agent Context CLI
+
+`npm run context` converts a task, review target, or known graph object into a compact, traceable context bundle. It is a read-only local tool: no network, authentication, or registry writes are involved.
+
+## Installed npm Package
+
+After installing `ai-design-context` as a dev dependency, run the packaged CLI from the product repository:
+
+```bash
+npx --no-install ai-design-context context --task quick-capture --platform mobile --intent implement
+npx --no-install ai-design-context context --review REF-00001 --intent qa
+npx --no-install ai-design-context context --object PAT-00002 --format json
+```
+
+The installed CLI always reads its own graph, not a `registry/` directory in the consuming project. Markdown lists absolute paths so the agent can open the selected files. JSON preserves the relative graph `path`, adds an `absolutePath` to anchors and objects, and adds the package's `knowledgeRoot` at the top level. These reading paths depend on the installation location and must not be used as stable object identifiers.
+
+`npx ai-design-context init` appends a marked block to `AGENTS.md` and creates only missing starter-kit files. It preserves current project instructions, populated files, and existing marked blocks. It rejects malformed markers, symlinked destinations, and incompatible file/directory destinations before creating templates. Installation itself performs no initialization.
+
+Retrieval is lexical and read-only. A `--review` query matches a known graph object or phrase; it does not inspect or judge arbitrary files in the product repository. Resolve relevant context, then inspect the implementation separately. See [installation](../starter-kit/INSTALL_WITH_AGENT.md) for pre-publication tarball use.
+
+## Commands
+
+```bash
+# Design or implement a feature.
+npm run context -- --task quick-capture --platform mobile --intent implement
+npm run context -- --task "build a shopping list" --intent implement
+
+# Review an implementation, benchmark artifact, or reference fixture.
+npm run context -- --review examples/todo-reference --intent qa
+
+# Resolve an exact stable object.
+npm run context -- --object PAT-00002 --format json
+```
+
+Exactly one of `--task`, `--review`, or `--object` is required.
+
+## Output Contract
+
+Markdown is the human default. `--format json` emits only this stable shape on stdout:
+
+```json
+{
+  "query": { "mode": "task", "value": "quick-capture", "platform": "mobile", "intent": "implement" },
+  "anchors": [],
+  "objects": []
+}
+```
+
+Every entry in `anchors` and `objects` retains `id`, `alias`, `title`, `type`, `status`, `maturity`, and `path`, and now adds a `reason` object. Consumers should allow additive fields. For example:
+
+```json
+{
+  "id": "RULE-00002",
+  "alias": "PRD-002",
+  "title": "Low-Friction Capture Before Organization",
+  "type": "rule",
+  "status": "draft",
+  "maturity": "seed",
+  "path": "rules/product/PRD-002.md",
+  "reason": { "kind": "dependency", "source": "PAT-00002", "relationship": "requires" }
+}
+```
+
+## Matching And Scope
+
+Task and review modes search stable registry fields and object Markdown. An exact ID, alias, slug, or registry path wins first. Otherwise, whole Unicode words must match; titles rank above slugs, aliases, categories, and incidental body mentions. Shorter focused titles break otherwise equal title matches. One highest-ranked anchor is selected, with stable ID ordering as the final tie-breaker.
+
+The small English filler set (`a`, `an`, `the`, `please`, `build`, `create`, `implement`, `make`, `for`, `me`) is ignored in non-exact queries. Thus `build a shopping list` and `shopping list` resolve alike. Unknown subject terms are not dropped. This is lexical retrieval, not translation or semantic search: use a known slug or ID when a paraphrase or another language has no matching words. A query containing only fillers fails instead of selecting arbitrary knowledge.
+
+Object mode matches only an exact ID, alias, slug, or registry path and does not apply filler handling.
+
+From the anchor the resolver includes:
+
+- Direct `related_to` neighbors for research, rules, and patterns, without recursively following optional neighbors.
+- Rules derived from a research anchor through `derived_from` or `inspired_by`.
+- Direct review prompts and checklists for anchors and those derived rules; reviews that `validate` a reference-project anchor.
+- All transitive registered `requires`, `derived_from`, `inspired_by`, and `implements` dependencies of every selected object; `validates` targets of selected reviews and reference projects.
+
+Dependencies are followed to completion even across cycles. A missing registered dependency is an error. The resolver does not walk backward from every shared rule into every consuming pattern or generation prompt. Broad review checklists remain available as gates, but their optional `related_to` links do not automatically select the whole graph. Follow those links explicitly when broadening a review. Non-registry observation sources remain in the research files and must be read there.
+
+Platform matching is additive. It selects at most one matching rule or pattern from eligible types **before** ranking, then includes its dependencies and direct context under the same rules. A platform with no match adds nothing. Platform matching does not replace the task anchor or prove applicability.
+
+There is no hard object-count cap: completeness of required dependencies takes priority over a fixed limit. Large mandatory graphs may still produce large bundles.
+
+## Selection Reasons
+
+Markdown explains the selection beside each object. JSON records the first deterministic inclusion reason:
+
+| `reason.kind` | Meaning | Additional fields |
+| --- | --- | --- |
+| `match` | Exact match or highest-ranked lexical match | `field`, `terms` matched in that field |
+| `platform` | Added by the platform query | `value`, `field`, `terms` |
+| `dependency` | Outgoing mandatory or validation edge from a selected object | `source`, `relationship` |
+| `related` | Direct optional neighbor of a seed object | `source`, `relationship` |
+| `derived_rule` | Rule points back to selected research | `source` (research), `relationship` |
+| `review` | Review gate points back to the selected object | `source` (reviewed object), `relationship` |
+
+For `derived_rule` and `review`, the stored graph edge points from the returned object to `reason.source`. For `dependency` and `related`, it points from `reason.source` to the returned object. A reason explains inclusion; it is not a confidence score or a claim of validation.
+
+`--intent implement` gives an implementation-first use order. `--intent qa` gives an evidence-and-checklist-first use order. Task mode defaults to `implement`; review mode defaults to `qa`.
+
+An unmatched query returns a non-zero exit code; with `--format json` the error is a JSON object on stderr.
+
+## Agent Use
+
+1. Resolve context before proposing product or UI changes.
+2. Read the listed research and rules before applying a pattern or prompt.
+3. Treat `draft` and `seed` objects as guidance with explicit limits, not as validated truth.
+4. Use listed checklists and reviews as quality gates.
+5. If no context matches, capture an observation or research need; do not invent a rule to fill the gap.
+6. Use `reason` to distinguish task matches, required knowledge, and review gates. Apply only guidance relevant to the current task.

package/docs/BENCHMARK.md

@@ -0,0 +1,170 @@
+# Benchmark
+
+AI Design Context must be evaluated by generated product quality, not by how complete the documentation looks.
+
+This benchmark compares two outputs for the same product brief:
+
+```text
+Baseline AI -> AI + AI Design Context
+```
+
+## Purpose
+
+The benchmark exists to answer one question:
+
+Does using AI Design Context produce better AI-generated consumer product experiences than using the same AI system without this repository?
+
+The benchmark does not prove universal design quality. It tests whether the repository improves output on repeatable product scenarios.
+
+## Evaluation Philosophy
+
+Evaluation should be:
+
+- comparative: score baseline and AI Design Context outputs side by side;
+- reproducible: use the same model, brief, temperature, and output target;
+- evidence-based: publish prompts, outputs, screenshots or code, and scores;
+- conservative: do not claim improvement without measured results;
+- practical: score product quality, not adherence to repository wording.
+
+The reviewer should not reward an output for mentioning AI Design Context. Reward only visible product quality.
+
+## Benchmark Process
+
+1. Choose one benchmark scenario from `benchmarks/`.
+2. Select one model and one generation surface.
+3. Generate the baseline output using only the scenario brief.
+4. Generate the AI Design Context output using the same scenario brief plus the repository instructions.
+5. Keep model, temperature, context window, tool access, and implementation target the same.
+6. Review both outputs using `docs/EVALUATION_RUBRIC.md`.
+7. Store prompts, outputs, screenshots or links, evaluator notes, and scores in `evidence/`.
+8. Declare `evidence_level` as `directional` or `rendered` in both run metadata files, then run `npm run benchmark:validate`.
+9. Report aggregate score and per-category differences.
+
+## Required Run Metadata
+
+Each benchmark run must record:
+
+- benchmark scenario;
+- date;
+- model name;
+- model provider;
+- generation surface;
+- temperature or sampling settings;
+- tools available;
+- implementation target;
+- baseline prompt;
+- AI Design Context prompt;
+- evaluator name or handle;
+- rubric version;
+- links to generated outputs.
+
+If this metadata is missing, the result is not reproducible enough to count.
+
+`rendered` runs must list at least one repository-local screenshot file for both baseline and AI Design Context outputs. Each screenshot must be a regular image file stored inside its matching `baseline/` or `ai-design-rules/` directory. Preview links can be supplementary, but do not replace stored visual evidence. `directional` runs remain useful for learning but must record their limitation.
+
+## Scoring Model
+
+Use `docs/EVALUATION_RUBRIC.md`.
+
+Every dimension is scored from `0` to `10`.
+
+Total score:
+
+```text
+sum(all dimensions) / number of dimensions
+```
+
+Report:
+
+- baseline total;
+- AI Design Context total;
+- absolute difference;
+- per-category differences;
+- reviewer notes.
+
+Do not collapse scores into a single claim without showing category scores.
+
+## Reproducibility Requirements
+
+To make results comparable:
+
+- use the exact scenario file without editing the brief;
+- use the same LLM for both runs;
+- use the same implementation target for both runs;
+- use the same time budget for both runs;
+- use the same tool access for both runs;
+- use the same evaluator or at least two independent evaluators;
+- publish raw outputs and scores;
+- do not fix one output manually before scoring.
+
+If implementation fails, record the failure and score the observable output.
+
+## Limitations
+
+This benchmark cannot remove all subjectivity.
+
+Known limitations:
+
+- design scoring has reviewer judgment;
+- different models may respond differently to long context;
+- implementation quality can affect perceived design quality;
+- small scenarios do not prove enterprise-scale validity;
+- current rules and patterns are seed-level, not complete.
+
+Benchmark results should guide rule, pattern, prompt, and skill evolution. They should not be used as marketing claims unless the evidence is public and reproducible.
+
+## Result Storage
+
+Store future results in `evidence/`.
+
+Do not add synthetic scores. Do not invent studies. Do not compare against private internal systems.
+
+## Next Rendered Run: Todo
+
+Use `benchmarks/todo-app.md` for the first paired rendered run of the next release. It exercises the updated Daily Home Surface (`PAT-001`, `VIS-002`) and Context-Preserving Preview (`PAT-005`, `UX-004`) alongside existing capture, accessibility, and recovery guidance. This is a run protocol, not a completed experiment or evidence of improvement.
+
+The [first execution on 2026-09-28](../evidence/todo/2026-09-28-codex-paired-todo/README.md) stores a completed pair and an internal unblinded evaluation. Keep this protocol for repeats; the recorded result does not establish general improvement.
+
+### Freeze The Setup
+
+Before either generation starts, record one shared setup in the run notes:
+
+- The scenario file, its hash, the knowledge revision, and any uncommitted knowledge patch used by the rules run.
+- The exact common brief: the Product Brief, Expected User, Expected Platform, Constraints, and Core User Tasks sections from `benchmarks/todo-app.md`, unchanged and identical in both prompts.
+- One model/provider/version, generation surface, exposed sampling settings, tool set, and time budget. Record unexposed settings as unexposed; do not invent values.
+- The implementation target: static HTML, CSS, and JavaScript served locally, with no build dependencies or external assets. Use the same target for both runs.
+- The same deterministic task data, browser/version, viewport sizes, and storage-reset procedure for both evaluations.
+
+Give both runs the same technical requirement to document how the evaluator can reproduce empty, loading, failed-save, and successful-save states. Local test hooks are acceptable; do not expose test controls as product features. Let each run design its interface from the same brief.
+
+Use two fresh generation sessions with no shared conversation or output access. Give the baseline only the common brief and shared technical setup. Give the rules session those same inputs plus the pinned knowledge source and instructions to retrieve context for `daily-home-surface`, `quick-capture`, and `context-preserving-preview`, with `--platform mobile`, before implementation. Save the exact returned context and actual prompts. Both sessions must have equivalent tool access; document any isolation limitations.
+
+Do not use the existing runnable Todo fixture as either generated result. Do not manually improve one output before scoring. A failure to build, render, or reproduce a required state is a recorded result.
+
+### Capture The Same Tasks
+
+Evaluate both outputs at **390 × 844** and **1440 × 900** CSS pixels, at the same browser zoom and device scale. Reset storage and use the same task data before each sequence. Save these local artifacts inside each run type's `screenshots/` directory:
+
+| Artifact suffix | Action and observable evidence |
+| --- | --- |
+| `default.png` | Open the populated daily surface; inspect current work and the primary action. |
+| `empty.png` | Reset to no tasks; inspect the starting action. |
+| `saving.png` | Submit a task under controlled delay; inspect input retention and layout stability. |
+| `save-error.png` | Cause a failed save; inspect error text, retained input, and retry. |
+| `saved.png` | Retry successfully; inspect feedback and duplicate prevention. |
+| `completed.png` | Mark a task complete; inspect state clarity and remaining work. |
+| `detail.png` | Open task details after scrolling; inspect the relation to the source list. |
+| `keyboard-focus.png` | Reach a core action by keyboard; inspect visible focus and accessible naming. |
+| `detail-reduced-motion.png` | Repeat detail opening with reduced motion; inspect equivalent information and controls. |
+
+Prefix each filename with `mobile-` or `desktop-`. Record the exact reproduction steps with each capture. If a state cannot be reached, record it as missing; do not create a substitute screenshot that pretends to show the state.
+
+Screenshots do not prove timing, focus restoration, or interruption behavior. Record interaction results separately: close the preview and verify source position/focus; close or change selection during opening and check for stale content; repeat with reduced motion; verify retry and task completion. Performance observations remain qualitative unless measurements are actually collected.
+
+### Score And Publish Evidence
+
+Use the same evaluator and `docs/EVALUATION_RUBRIC.md` for both outputs. Score visible behavior, include a note and artifact reference for each category, and report all category differences as well as the averages. If possible, score anonymous A/B outputs before revealing their conditions. Disclose whether evaluation was blinded and whether the evaluator participated in generation; a parent agent reviewing its own team's output is not independent evaluation.
+
+Store completed runs using `evidence/TEMPLATE.md`, including raw source, prompts, settings, screenshots, state coverage, evaluator identity, and limitations. Run `npm run benchmark:validate`. The validator currently checks artifact presence, metadata consistency, and image signatures; it does not enforce this state matrix or judge visual quality. The evaluator must check those manually.
+
+Do not create scored evidence entries or change rule maturity while preparation is incomplete. One completed pair remains a small-sample result; it cannot establish universal improvement or isolate the effect of context retrieval from pattern changes. Repeated pairs or a separate previous-version comparison are needed for those stronger claims.

package/docs/DESIGNLINT_READINESS.md

@@ -0,0 +1,110 @@
+# DesignLint Readiness
+
+DesignLint v0 is implemented as a small, deterministic relationship checker.
+
+This document defines its current scope and the richer validation that can follow metadata migration.
+
+## Inputs
+
+DesignLint should consume:
+
+- `schema/*.schema.json` for object validation;
+- `registry/objects.json` for ID resolution;
+- `registry/relationships.json` for graph edges;
+- YAML front matter from knowledge objects after migration;
+- generated indexes after registry-backed indexing exists.
+
+## Required Metadata
+
+DesignLint requires stable metadata:
+
+- `id`
+- `alias`
+- `slug`
+- `title`
+- `object_type`
+- `status`
+- `version`
+- `category`
+- `relationships`
+- `last_reviewed_at`
+- `maturity`
+- `risk_level`
+
+Optional metadata such as `platform`, `product_type`, `surface`, `applies_to`, and `does_not_apply_to` will improve context matching.
+
+## DesignLint v0
+
+Run it with:
+
+```bash
+npm run lint:design
+```
+
+It reads only registered objects and typed registry relationships. It fails when:
+
+- a rule has no upstream research via `derived_from` or `inspired_by`;
+- a pattern does not `require` a rule;
+- a prompt has no pattern, rule, or checklist reference;
+- a checklist has no rule or pattern coverage;
+- a reference project does not implement a prompt and validate a prompt or pattern;
+- a review does not require a checklist and validate a knowledge object.
+
+It does not judge prose, visual quality, or whether a relationship is substantively well chosen. `npm run validate` remains responsible for synchronizing registry relationships with front matter.
+
+## Future Validation
+
+With the schema-first foundation, DesignLint can later validate:
+
+- object metadata matches the correct schema;
+- IDs are globally unique;
+- aliases are not reused within the same object type;
+- slugs are file-safe;
+- relationship types are allowed;
+- relationship targets exist;
+- deprecated objects are not used by active prompts;
+- patterns require rules;
+- prompts require patterns and rules;
+- reference projects validate patterns and prompts;
+- rules trace back to research;
+- orphan objects are detected;
+- manual indexes match registry output.
+
+## Current Validation Layer
+
+`tools/validate-knowledge.mjs` is the first lightweight validation step.
+
+It currently validates:
+
+- YAML front matter on migrated research, rules, patterns, prompts, checklists, reviews, and reference projects;
+- required metadata fields;
+- object ID prefixes for migrated object types;
+- unique aliases and slugs within the migrated set;
+- registry coverage for migrated files;
+- registry relationship source and target IDs;
+- front matter relationship targets that point to registered IDs or existing files;
+- duplicate IDs, aliases, slugs, and raw JSON keys;
+- local Codex skill metadata and generated-index freshness.
+
+This is a metadata migration guard. It complements DesignLint v0 rather than replacing it.
+
+## Not Implemented Yet
+
+The current repository does not yet include:
+
+- registry-backed observations;
+- schema validation in CI;
+- graph traversal;
+- stale-object detection;
+- relationship-quality evaluation;
+- visual or runtime product evaluation.
+
+## Readiness Standard
+
+Before DesignLint rules are implemented, the repository should have:
+
+- metadata front matter on every knowledge object;
+- complete registry coverage;
+- generated indexes;
+- relationship validation;
+- a stable ID allocation process.

package/docs/DESIGN_SYSTEM.md

@@ -0,0 +1,23 @@
+# Design System
+
+AI Design Context is not a design system or component library.
+
+This document defines how agents should think when a product already has design-system structure.
+
+## Order Of Decisions
+
+```text
+tokens -> themes -> components -> screens
+```
+
+## Agent Guidance
+
+- Reuse existing tokens before creating new visual values.
+- Use semantic names for color, spacing, typography, and state.
+- Do not create one-off styles when an existing token or component fits.
+- Do not treat components as the product model.
+- Let rules and patterns decide behavior; let the design system keep execution consistent.
+
+## Boundary
+
+AI Design Context can describe how design-system decisions should be used by agents. It does not ship production components, token packages, or UI kit assets.