@pilotspace/add 1.1.0 → 1.3.0

package/tooling/templates/CONVENTIONS.md.tmpl

@@ -1,4 +1,4 @@
-# CONVENTIONS  (survivor layer — set once, kept for the whole project)
+# CONVENTIONS  (living documentation — set once, kept for the whole project)
 
 Language/framework: <e.g. Python 3.12 / FastAPI>
 Folders: .add/tasks/<slug>/{TASK.md, tests/, src/}

package/tooling/templates/DESIGN.md.tmpl

@@ -0,0 +1,66 @@
+# {{project}} — Design (DESIGN.md)
+
+> The design source of truth for **{{project}}** ({{stage}}) — drafted {{date}}.
+> The AI drafts every UI screen against this doc; the JSON foundation below is what
+> the validators lint.
+>
+> **No UI in this project? This doc is optional — delete it.**
+
+This doc is the **prose front-door** to the UDD foundation: it carries the design
+*identity* and *intent* a human owns, then points at the named-set JSON
+(`tokens.json` · `catalog.json` · `prototypes/`) the AI renders from.
+
+## Identity
+
+Design identity is **human-owned** — set it here at specify; never let the AI invent
+a brand. Fill each prompt with your real values, then delete the comment.
+
+- **Brand color** — <!-- your one primary brand color, as your brand guide names it -->
+- **Palette** — <!-- the supporting roles: accent · surface · text · success/warn/danger -->
+- **Typeface** — <!-- the heading + body type families (and the weights you actually use) -->
+- **Voice / tone** — <!-- 2–3 words, e.g. calm · precise · warm -->
+
+Once set, these flow down into the **semantic** layer of `tokens.json` (the AI wires
+the primitives beneath them); see Foundation below.
+
+## Principles
+
+The design intent the AI drafts UI against — the persona, the one job, the feel.
+
+- **Primary user & their job** — <!-- who this is for and the one thing they hire it to do -->
+- **Design principles** — <!-- 3–5 lines, e.g. "one primary action per screen" · "never hide state" -->
+- **Accessibility floor** — <!-- e.g. WCAG AA contrast · focus-visible · hit-target ≥ 44px -->
+
+## Screens
+
+An index of the app's screens — one `design/prototypes/<name>.json` per screen (a flat
+json-render tree the catalog validates). Add a row as each screen is designed.
+
+| Screen | Prototype | Status |
+|--------|-----------|--------|
+| (worked example) | `design/prototypes/main.json` ← seed `prototype.sample.json` | sample |
+| <!-- Home --> | <!-- design/prototypes/home.json --> | <!-- draft --> |
+
+Start from `prototype.sample.json` (a clean Screen › Card › {Text, Text, Button})
+and adapt it into `design/prototypes/<name>.json` per screen.
+
+## Foundation
+
+The named-set JSON the validators lint — lives under `.add/design/`; start from the
+shipped samples, then adapt:
+
+- **Tokens** — `design/tokens.json` · the 3-layer design tokens (primitive · semantic ·
+  component). Dialect + divergences: `udd-tokens.md`. Start from `tokens.sample.json`.
+- **Catalog** — `design/catalog.json` · the component catalog (typed props + token
+  bindings). Render adapter: `udd-catalog.md`. Start from `catalog.sample.json`.
+- **Prototypes** — `design/prototypes/<name>.json` · the flat json-render screen trees
+  the catalog validates. Start from `prototype.sample.json`.
+
+`add.py check` lints this named set in place — a layer/catalog/tree/cross-file violation
+goes red with a named code; it is silent when there is no `design/` set.
+
+## Render
+
+To turn the catalog + a prototype into a live, clickable UI, follow the render recipe
+in **`udd-catalog.md`** (its `## Render recipe` section): `catalog.json` →
+`defineCatalog(...)`, then `catalog.validate(spec)` on the flat tree as-is.

package/tooling/templates/GLOSSARY.md.tmpl

@@ -1,3 +1,32 @@
 # GLOSSARY  (one name per concept — used everywhere: specs, contracts, code)
 
 <term>: <definition>
+
+# ADD method vocabulary (domain-standard names; bridges to legacy terms)
+GOAL: the one durable outcome a project (and each milestone) runs toward — the loop's orientation anchor, declared as the lowercase `goal:` line in PROJECT.md / MILESTONE.md and surfaced by status/guide every session; distinct from a task's §1 Must (a single required behavior, not the whole-project outcome).
+deep verify: the deepened Verify evidence (v20) required beyond passing tests — for a task that produced code, that every new symbol is referenced (wiring) and no new dead/unused code exists; for prose/non-code, a recorded no-skim semantic read; which path applies is resolver-judged and the engine never classifies (a rubric, not add.py).
+earned green: the build-integrity property — the green is EARNED when the implementation makes the UNCHANGED red suite pass by GENERAL behavior, not by overfitting src to the test fixtures, vacuous/tautological asserts, or stubbing real logic away; task 1's tamper tripwire protects it mechanically and the adversarial refute-read by judgment, and a confirmed earned-green failure is HARD-STOP-class (never auto-passed, never RISK-ACCEPTED).
+adversarial refute-read: the verify-gate, whole-suite specialization of run.md's adversarial verify — an independent reviewer (a subagent under autonomy:auto is recommended; the engine never spawns one) prompted to argue "the green was NOT earned", scoring the earned-green cheats (overfit · vacuous · stub) the mechanical tripwire cannot see.
+bounded self-heal: the verify-gate loop (heal-then-escalate) that gives a CONFIRMED cheat — mechanical tamper (the tripwire) or a reported earned-green failure (`add.py heal --reason`) — a chance to redo honestly before it stops: the engine returns the task to build, COUNTS the attempt, CAPS it at 3 (`HEAL_CAP`), and on the next confirmed cheat forces a HARD-STOP that escalates to the human. The counter is MONOTONIC — it never auto-resets (cmd_phase is unguarded, so a reset would be a zero-human cap bypass). The engine counts/caps/escalates; the AGENT does the honest re-build (never the engine). An honest build passes even at the cap (the cap bites a CONTINUED cheat, never a recovery); a gamed green is never auto-passed, never RISK-ACCEPTED-waived.
+onboarding: the install -> first-milestone path (formerly "on-ramp").
+primary flow: the solid forward path of the flow diagram — a phase starts only when its input exists (formerly "forward spine").
+ground: the phase-0 preamble before specify — the AI gathers the real current codebase a task touches (files, symbols, signatures, conventions) into a §0 grounding map; AI-owned, adds no gate (the one approval stays at the contract freeze).
+grounding map / anchors: the §0 GROUND artifact — the real files/symbols/conventions a task touches plus the anchors the frozen contract cites; task-specific delta only (defers to PROJECT.md / CONVENTIONS.md), surfaced by status/check (measure, never block).
+cross-cutting concern: a concern running through every step rather than being one step — security, testing, observability, cost (formerly "spine / continuous concern").
+working state: everything an agent loads each session — skill router, active phase, PROJECT/MILESTONE/TASK, state.json (formerly "state surface").
+audit trail: the reference record read by people, never auto-loaded into agent context (formerly "story surface").
+method rationale: the why behind every rule — the AIDD book, loaded on demand, never duplicated (formerly "trust layer").
+failing-first suite: the test suite written before code, confirmed red for the right reason — a missing implementation (formerly "red safety net").
+non-functional review: the deliberate post-evidence check of what tests rarely catch — concurrency, security, architecture (formerly "blind-spot checks").
+change scope: the files a locked run may and may not touch (formerly "touch-boundary"; the <touch_boundary> XML prompt tag keeps its name).
+automated quality gate: the evidence-based Verify resolver under autonomy auto — may auto-PASS on complete evidence; security always escalates (formerly "evidence auto-gate").
+autonomy level: the explicit per-task Verify resolver setting on an ordered ladder — manual | conservative | auto (manual < conservative < auto): auto (the seeded default) auto-PASSes on complete evidence, conservative keeps a human at the gate, manual is the strict floor (the human owns the gate; nothing auto-resolves); declared in the TASK.md header, human-reviewed at the freeze (formerly "autonomy dial").
+auto-ready goal: a milestone goal whose every exit criterion CITES a verifier `(verify: <test|command|metric>)` — so the engine can self-verify the result against the goal without human judgement. This is the prerequisite by which autonomy is EARNED by goal-clarity (the autonomy level then governs who resolves Verify, but a clarified goal is what makes a self-verifying run meaningful). `add.py check` WARNs (never red) the active milestone until its goal is auto-ready (total >= 1 AND every criterion cited) and `status` surfaces it (`goal-ready: auto-ready ✓` / cited-of-total); a zero-criteria goal is NOT auto-ready and is milestone-shaping's nudge, not this WARN's. The lint forces a citation slot per criterion (raising the floor) but cannot PROVE the citation is real — the human still owns whether it is honest (citation-theater is the accepted, irreducible floor; the freeze gate and autonomy behavior are unchanged by it).
+living documentation: the durable project artifacts — conventions, glossary, frozen contracts — that outlive any particular code (formerly "survivor layer").
+scope level: the granularity a decision lives at — intake level (request -> versioned scope), milestone level, setup/foundation level, task level (formerly "altitude").
+baseline approval: the one human gate that freezes the AI-drafted foundation, first scope, and first contract together — runs as `add.py lock` (formerly "the lock-down").
+lesson learned: a single learning a loop produces, tagged by the competency it improves — the `- [DDD · open]` grammar and deltas.md/`add.py deltas` machine names stay (formerly "competency delta").
+lowest-confidence flag: the AI's ranked declaration of the 1–2 points most likely to be wrong in what a human is asked to approve — each with why + cost-if-wrong; the ⚠ glyph keeps its name as the machine marker (formerly "least-sure flag").
+decision point: a stop for human judgment — the contract-freeze approval, an escalated verify gate, intake confirmation, milestone close; the machine names seam (--json owner enum, decide key) and seam-audit (CI job) keep their names (formerly "seam").
+retrospective consolidation: gathering confirmed lessons learned at milestone close and writing them append-only into the versioned foundation — human-confirmed, never self-approved; the machine names fold.md, the folded status, and add.py deltas keep their names (formerly "the fold / fold ritual").
+specification bundle: a task's spec, scenarios, contract, and failing tests drafted as one piece and approved by a person once at the contract freeze (formerly "the one-approval front").

package/tooling/templates/MILESTONE.md.tmpl

@@ -1,6 +1,7 @@
 # MILESTONE: {{title}}
 
 goal: {{goal}}
+rationale: <why this scope — the confirmed intake classification (bucket + reason)>
 stage: {{stage}} · status: active · created: {{date}}
 
 > SDD living doc for this milestone. Keep it THIN: breadth, shared decisions, and

package/tooling/templates/PROJECT.md.tmpl

@@ -1,4 +1,4 @@
-# PROJECT — survivor layer (cross-milestone context)
+# PROJECT — living documentation (cross-milestone context)
 
 > The durable foundation that outlives every milestone and feeds context into each
 > TDD⇄ADD loop. Read this FIRST in any session. Keep it lean — one screen, not a
@@ -7,6 +7,9 @@
 > that is the re-entrant arrow from the engine down to the foundation.
 
 slug: {{project}} · stage: {{stage}} · updated: {{date}}
+autonomy: auto   <!-- project default — new tasks inherit this rung (manual < conservative < auto); lower a single task in its TASK.md header when it needs a human gate. -->
+goal:
+<!-- set at setup — the outcome this project runs toward; status/guide surface it every session -->
 
 ---
 
@@ -22,8 +25,8 @@ slug: {{project}} · stage: {{stage}} · updated: {{date}}
 <!-- The spec is a living document, not a frozen plan. This section POINTS to the
      active milestone + frozen contracts; it does not duplicate them. -->
 - Active milestone → `.add/milestones/<slug>/MILESTONE.md`  (see `add.py status`)
-- Frozen contracts (survivor): the contracts other work builds against.
-- Settled vs still open:
+- Frozen contracts (living docs): the contracts other work builds against.
+- Settled vs still open: <frozen contracts · open questions>
 
 ## Users (UDD) — UI/UX: design before code
 <!-- UI/UX-Driven Development: users use the interface, not the spec. Capture the

package/tooling/templates/TASK.md.tmpl

@@ -1,9 +1,10 @@
 # TASK: {{title}}
 
 slug: {{slug}} · created: {{date}} · stage: {{stage}}
-phase: specify   <!-- specify -> scenarios -> contract -> tests -> build -> verify -> observe -> done -->
-<!-- high-risk/method-defining scope? declare `risk: high` on the slug line above and lower
-     the dial with `autonomy: conservative` — the engine refuses an unguarded completion
+autonomy: {{autonomy}}   <!-- inherited from the project default (PROJECT.md); explicit level: manual < conservative < auto (visible · overridable) — lower below if a high-risk task needs it. -->
+phase: ground   <!-- ground -> specify -> scenarios -> contract -> tests -> build -> verify -> observe -> done -->
+<!-- high-risk/method-defining scope? declare `risk: high` on the slug line above and lower the
+     autonomy level to `manual` or `conservative` — the engine refuses an unguarded completion
      (`unguarded_high_risk_auto`, run.md guard). A comment is never a declaration. -->
 
 > One file = one task. Fill sections top-to-bottom; the `add` skill drives each phase.
@@ -12,26 +13,45 @@ phase: specify   <!-- specify -> scenarios -> contract -> tests -> build -> veri
 
 ---
 
+## 0 · GROUND — the real codebase ▸ docs/02-the-flow.md
+
+Touches (files · symbols · signatures): <path:symbol — what it is / how it is keyed>
+Context (working folder): <docs · todos · config · data the task touches — task-delta only>
+Honors (patterns / conventions): <PROJECT.md / CONVENTIONS.md anchors — task-delta only, never a re-scan>
+Anchors the contract cites: <the symbols §3 will name>
+
+---
+
 ## 1 · SPECIFY — the rules ▸ docs/03-step-1-specify.md
 
 Feature: <name>
 Framings weighed: <chosen> (chosen) · <alternative> · <alternative>
 Must:
+<must>
   - <required behavior>
+</must>
 Reject:
+<reject>
   - <bad input / situation> -> "<error_code>"
+</reject>
 After:
+<after>
   - <state that is true once it succeeds>
-Assumptions — least-sure first:
-  ⚠ <the one assumption most likely to be wrong> — least sure because <why>; if wrong: <cost>
+</after>
+Assumptions — lowest-confidence first:
+<assumptions>
+  ⚠ <the one assumption most likely to be wrong> — lowest confidence because <why>; if wrong: <cost>
   - [ ] <next assumption, ranked> — confirm or deny; never carry an open one forward
+</assumptions>
 
-<!-- EXIT: every rule stated, every rejection named; assumptions ranked least-sure first, the top one or two ⚠-flagged with why + cost (or, for trivial scope, an honest "none material" that still names the single biggest risk). -->
+<!-- EXIT: every rule stated, every rejection named; assumptions ranked lowest-confidence first, the top one or two ⚠-flagged with why + cost (or, for trivial scope, an honest "none material" that still names the single biggest risk). -->
 
 ---
 
 ## 2 · SCENARIOS — pass/fail cases ▸ docs/04-step-2-scenarios.md
 
+<scenarios>
+
 ```gherkin
 Scenario: <short name>
   Given <starting situation>
@@ -40,6 +60,8 @@ Scenario: <short name>
   And <what must remain unchanged>   # required for every rejection
 ```
 
+</scenarios>
+
 <!-- EXIT: one scenario per Must AND per Reject; each result is observable. -->
 
 ---
@@ -53,20 +75,24 @@ Scenario: <short name>
 Schema: <tables/fields touched, and access pattern>
 ```
 
-Status: DRAFT   <!-- becomes: FROZEN @ v1 once approved. Changing a frozen contract = change request back to SPECIFY. -->
-<!-- The freeze IS the one approval. Lead it with the bundle's least-sure flag: the 1–2 points
-     most likely wrong across the whole bundle, tagged [spec|scenario|contract|test], with why + cost.
-     The §1 ⚠ assumptions are its first feeder; a flag may point at a scenario or the contract too. See run.md. -->
-
-<!-- EXIT: frozen + every spec rejection has a contracted response + names match GLOSSARY + the bundle's least-sure flag was surfaced at the freeze (or an honest "none material"). -->
+Status: DRAFT
+<!-- The freeze IS the one approval — lead it with the bundle's lowest-confidence flag: the 1–2
+     points most likely wrong across the whole bundle, tagged [spec|scenario|contract|test], each
+     with why + cost (the §1 ⚠ assumptions feed it; a flag may point at a scenario or the contract
+     too — see run.md). Approved -> Status: FROZEN @ vN — approved by <name>. Changing a frozen
+     contract = change request back to SPECIFY.
+     EXIT: frozen + every spec rejection has a contracted response + names match GLOSSARY + the
+     bundle's lowest-confidence flag was surfaced at the freeze (or an honest "none material"). -->
 
 ---
 
-## 4 · TESTS — red safety net ▸ docs/06-step-4-tests.md
+## 4 · TESTS — failing-first suite (red) ▸ docs/06-step-4-tests.md
 
 Coverage target: <e.g. 90%>
 Plan (one test per scenario, asserting behavior not internals):
+<test_plan>
   - test_<scenario>: arrange <Given> / act <When> / assert <Then> + assert <unchanged>
+</test_plan>
 
 Tests live in: `./tests/` · MUST run red (missing implementation) before Build.
 <!-- declare paths as backticked tokens on this line: `./…` = this task dir ·
@@ -80,24 +106,38 @@ Tests live in: `./tests/` · MUST run red (missing implementation) before Build.
 
 ## 5 · BUILD — AI writes code ▸ docs/07-step-5-build.md
 
+Scope (may touch): `./src/`   <fill before the §3 freeze — every file the build may write>
+Strategy (ordered batches): <1. … 2. … — the planned build order; guidance, not enforced>
 Safety rule (feature-specific): <e.g. debit+credit in one atomic transaction>
 Code lives in: `./src/`
 Constraints: do NOT change any test or the contract; allow-list packages only; ask if unclear.
 
-<!-- EXIT: all green; coverage held; no test/contract touched; no unlisted dependency. -->
+<!-- Scope tokens, backticked, FIRST declaring line: `./…` = this task dir · a token
+     with "/" = project root · a bare name = sibling of the previous token's dir ·
+     outside-root resolutions are dropped fail-closed · a DIRECTORY token covers its
+     whole subtree (containment — diverges from §4's non-recursive counting) ·
+     absent line = UNDECLARED (pre-existing tasks grandfathered, never retro-red) ·
+     engine enforcement (touched ⊆ declared) lands in scope-gate-enforce.
+     EXIT: all green; coverage held; no test/contract touched; no unlisted dependency. -->
 
 ---
 
-## 6 · VERIFY — evidence + blind-spot checks ▸ docs/08-step-6-verify.md
+## 6 · VERIFY — evidence + non-functional review ▸ docs/08-step-6-verify.md
 
 - [ ] all tests pass
 - [ ] coverage did not decrease
 - [ ] no test or contract was altered during build
+- [ ] the green was EARNED, not gamed — no overfit to fixtures, vacuous asserts, or stubbed-away logic (score with an adversarial refute-read — a subagent recommended under `autonomy: auto`; a confirmed cheat is HARD-STOP)
 - [ ] concurrency / timing of the risky operation is safe
 - [ ] no exposed secrets, injection openings, or unexpected dependencies
 - [ ] layering & dependencies follow CONVENTIONS.md
 - [ ] a person reviewed and approved the change
 
+### Deep checks — do not skim (fill the path that applies; the resolver judges which)
+- [ ] WIRING (code) — every new symbol is referenced; record where / how confirmed
+- [ ] DEAD-CODE (code) — no new unused or orphaned symbol introduced
+- [ ] SEMANTIC (prose / non-code) — read in full, not skimmed: <what read · what confirmed>
+
 ### GATE RECORD
 Outcome: <PASS | RISK-ACCEPTED | HARD-STOP>
 If RISK-ACCEPTED -> owner: <name> · ticket: <link> · expires: <date>   (never for a security gap)

package/tooling/templates/catalog.sample.json

@@ -0,0 +1,38 @@
+{
+  "components": {
+    "Screen": {
+      "description": "The root viewport container.",
+      "hasChildren": true,
+      "props": {
+        "background": { "type": "token", "token": "color" },
+        "padding": { "type": "token", "token": "dimension" }
+      }
+    },
+    "Card": {
+      "description": "A surface that groups related content.",
+      "hasChildren": true,
+      "props": {
+        "background": { "type": "token", "token": "color" },
+        "gap": { "type": "token", "token": "dimension" },
+        "elevation": { "type": "enum", "values": ["none", "sm", "md"] }
+      }
+    },
+    "Text": {
+      "description": "A run of styled text.",
+      "props": {
+        "content": { "type": "string" },
+        "color": { "type": "token", "token": "color" },
+        "weight": { "type": "enum", "values": ["regular", "bold"] }
+      }
+    },
+    "Button": {
+      "description": "A primary call-to-action.",
+      "props": {
+        "label": { "type": "string" },
+        "variant": { "type": "enum", "values": ["primary", "secondary"] },
+        "background": { "type": "token", "token": "color" },
+        "disabled": { "type": "boolean" }
+      }
+    }
+  }
+}

package/tooling/templates/prototype.sample.json

@@ -0,0 +1,48 @@
+{
+  "root": "screen",
+  "elements": {
+    "screen": {
+      "type": "Screen",
+      "props": {
+        "background": "{semantic.color.surface}",
+        "padding": "{semantic.space.inset-md}"
+      },
+      "children": ["welcome-card"]
+    },
+    "welcome-card": {
+      "type": "Card",
+      "props": {
+        "background": "{semantic.color.surface}",
+        "gap": "{semantic.space.inset-sm}",
+        "elevation": "sm"
+      },
+      "children": ["title", "subtitle", "cta"]
+    },
+    "title": {
+      "type": "Text",
+      "props": {
+        "content": "Welcome to ADD",
+        "color": "{semantic.color.text}",
+        "weight": "bold"
+      }
+    },
+    "subtitle": {
+      "type": "Text",
+      "props": {
+        "content": "Spec-and-tests-first, render-ready.",
+        "color": "{semantic.color.text}",
+        "weight": "regular"
+      }
+    },
+    "cta": {
+      "type": "Button",
+      "props": {
+        "label": "Get started",
+        "variant": "primary",
+        "background": "{semantic.color.accent}",
+        "disabled": false
+      },
+      "on": { "click": [{ "action": "navigate", "to": "onboarding" }] }
+    }
+  }
+}

package/tooling/templates/tokens.sample.json

@@ -0,0 +1,55 @@
+{
+  "primitive": {
+    "color": {
+      "$type": "color",
+      "blue-500": { "$value": "#3B82F6" },
+      "slate-900": { "$value": "#0F172A" },
+      "white": { "$value": "#FFFFFF" }
+    },
+    "space": {
+      "$type": "dimension",
+      "2": { "$value": "8px" },
+      "4": { "$value": "16px" }
+    },
+    "font": {
+      "family": {
+        "$type": "fontFamily",
+        "sans": { "$value": ["Inter", "system-ui", "sans-serif"] }
+      },
+      "weight": {
+        "$type": "fontWeight",
+        "regular": { "$value": 400 },
+        "bold": { "$value": 700 }
+      }
+    },
+    "motion": {
+      "$type": "duration",
+      "fast": { "$value": "150ms" }
+    }
+  },
+  "semantic": {
+    "color": {
+      "$type": "color",
+      "accent": { "$value": "{primitive.color.blue-500}" },
+      "text": { "$value": "{primitive.color.slate-900}" },
+      "surface": { "$value": "{primitive.color.white}" }
+    },
+    "space": {
+      "$type": "dimension",
+      "inset-sm": { "$value": "{primitive.space.2}" },
+      "inset-md": { "$value": "{primitive.space.4}" }
+    }
+  },
+  "component": {
+    "button": {
+      "bg": { "$type": "color", "$value": "{semantic.color.accent}" },
+      "label": { "$type": "color", "$value": "{semantic.color.surface}" },
+      "padding": { "$type": "dimension", "$value": "{semantic.space.inset-md}" }
+    },
+    "card": {
+      "bg": { "$type": "color", "$value": "{semantic.color.surface}" },
+      "text": { "$type": "color", "$value": "{semantic.color.text}" },
+      "gap": { "$type": "dimension", "$value": "{semantic.space.inset-sm}" }
+    }
+  }
+}

package/tooling/templates/udd-catalog.md

@@ -0,0 +1,122 @@
+# UDD catalog + content trees — the render-ready half
+
+The token foundation (`udd-tokens.md`) says what a UI is *made of*; this layer says
+what it is *built from* and *laid out as*. A **catalog** declares the components and
+their typed props; a **content tree** is a flat, json-render-shaped prototype that
+binds those props to semantic tokens. `catalog.sample.json` + `prototype.sample.json`
+are a worked pair that validates clean against each other.
+
+## The foundation is a NAMED SET (Fork A)
+
+```
+.add/design/tokens.json            the task-1 dialect (primitive · semantic · component)
+.add/design/catalog.json           the component catalog (this doc)
+.add/design/prototypes/<name>.json one flat content tree per prototype screen/flow
+```
+
+Each file lints independently — the token validator never sees the catalog, the
+catalog/tree validator never sees the tokens. The cross-file check (a tree's
+token-prop actually resolving to a semantic token of the right `$type`) is the
+**composer's** job — `add.py check` wires it in the udd-check-lint task.
+
+## CATALOG — components and typed props
+
+```
+{ "components": { "<Name>": {
+    "description"?: str,
+    "hasChildren"?: bool        (default false — only containers may hold children),
+    "props": { "<prop>": PropSpec } } } }
+```
+
+A **PropSpec** is exactly one of:
+
+| PropSpec | the tree value it accepts |
+|----------|---------------------------|
+| `{ "type": "string" }`  | a JSON string |
+| `{ "type": "number" }`  | a JSON number (not a bool) |
+| `{ "type": "boolean" }` | a JSON bool |
+| `{ "type": "enum", "values": ["a","b"] }` | a string in `values` |
+| `{ "type": "token", "token": "<$type>" }` | a `{semantic.…}` alias (see below) |
+
+`<$type>` is a task-1 token type — `color · dimension · number · fontFamily ·
+fontWeight · duration`.
+
+## CONTENT TREE — a flat json-render `Spec`
+
+Pinned to **vercel-labs/json-render v0.19.0 / commit `4e4dc46`** (the milestone's
+named top risk: young-project schema drift). The tree mirrors json-render's `Spec`
+exactly, so it is render-ready as-is:
+
+```
+{ "root": "<id>",
+  "elements": { "<id>": {
+      "type": "<Name>",          a catalog component name
+      "props": { … },            keys ⊆ the component's declared props
+      "children"?: ["<id>", …]   only if the component hasChildren; ids ∈ elements
+  } } }
+```
+
+- A `token` prop's value is the **alias form** `"{semantic.dotted.path}"` from the
+  token dialect — it MUST target the `semantic` layer. (Whether that semantic token
+  exists and matches the prop's `$type` is resolved by the composer, which has
+  `tokens.json`.)
+- json-render's optional `state` / `on` / `visible` / `repeat` are **passed through**
+  — render-compatible (a clickable prototype) but NOT linted, keeping the validator
+  lean. Interactivity rules stay additive for a later task.
+
+## Validation — the named reds
+
+`_catalog_tree_violations(catalog, tree)` returns `[]` for a valid pair, else one
+`(code, path, detail)` per violation, in deterministic order. The eight codes:
+
+| code | when |
+|------|------|
+| `tree_cites_uncataloged_component` | an element `type` is not in the catalog |
+| `unknown_prop` | a props key not declared on the element's component |
+| `prop_type_mismatch` | a value's form ≠ its PropSpec (incl. a token prop given a non-alias literal) |
+| `non_semantic_prop_token` | a token-prop alias does not target the `semantic` layer |
+| `dangling_child` | a child id absent from `elements` |
+| `children_not_allowed` | children on a component whose `hasChildren` is false |
+| `missing_root` | `root` absent, or names an id not in `elements` |
+| `malformed_catalog` | a PropSpec with unknown `type`, or a token prop naming an unknown `$type` |
+
+The validator lints **shape only** — pure, stdlib, tool-agnostic, no rendering. It is
+SEPARATE from `_token_layer_violations`; udd-check-lint composes both inside
+`add.py check`.
+
+## Render recipe — catalog.json → json-render
+
+json-render authors a catalog in TypeScript (`defineCatalog`), not JSON, so our
+`catalog.json` is adapted by a thin (~20-line) loader. The content tree needs no
+adapter — it is a json-render `Spec` already:
+
+```ts
+import { defineCatalog } from "json-render";
+import { z } from "zod";
+import catalogJson from "./catalog.json";
+import spec from "./prototypes/welcome.json";
+
+const PROP = {                       // PropSpec → a Zod field
+  string:  () => z.string(),
+  number:  () => z.number(),
+  boolean: () => z.boolean(),
+  enum:    (p) => z.enum(p.values),
+  token:   () => z.string(),         // "{semantic.…}" — resolved to a CSS value at render
+};
+
+const components = Object.fromEntries(
+  Object.entries(catalogJson.components).map(([name, c]) => [name, {
+    hasChildren: c.hasChildren ?? false,
+    props: z.object(
+      Object.fromEntries(Object.entries(c.props).map(([k, p]) => [k, PROP[p.type](p)])),
+    ),
+  }]),
+);
+
+const catalog = defineCatalog(z, { components });
+catalog.validate(spec);              // the flat tree feeds json-render AS-IS
+```
+
+Resolving a `{semantic.…}` alias to a concrete CSS value (via `tokens.json`) is the
+renderer's binding step — out of scope for the foundation, which only guarantees the
+SHAPE is render-ready. The renderer itself is never bundled with the method.

package/tooling/templates/udd-tokens.md

@@ -0,0 +1,79 @@
+# UDD tokens — the compact-DTCG dialect
+
+The token foundation a UI project drafts from. Three layers, a fail-closed
+citation rule, and value forms compacted for the AI economy. Aligned with the
+**Design Tokens Format Module 2025.10** (Final Community Group Report, 28 Oct 2025
+— <https://www.designtokens.org/tr/2025.10/format/>); every divergence is NAMED
+below. `tokens.sample.json` is a worked example that validates clean.
+
+## Identity values are human-owned — discuss at specify
+
+The dialect checks a token's **shape**; its identity **value** — the brand
+color, the palette seed, the typeface — is design *direction*, not an AI
+default. During **specify**, surface identity tokens for discussion with the
+user; never invent a brand value. Shape is verifiable; identity is a human
+decision.
+
+## The three layers (a convention, not a DTCG feature)
+
+A token's **layer is its top-level group name** — `primitive`, `semantic`, or
+`component`. DTCG itself defines groups, `$type`, and aliases but no tier model;
+the layering and the citation rule below are ours.
+
+```
+primitive   raw literal values        (no alias — the source of truth)
+semantic    intent, cites primitives  (e.g. color.accent → primitive.color.blue-500)
+component   parts, cite semantics      (e.g. button.bg → semantic.color.accent)
+```
+
+## The citation rule (fail-closed)
+
+- a `primitive` token's `$value` MUST be a literal — never an alias.
+- a `semantic` token's `$value` MUST be a literal OR an alias to a `primitive` only.
+- a `component` token's `$value` MUST be a literal OR an alias to a `semantic` only.
+
+No layer-skipping, no sideways or upward citation. An **alias** is the DTCG curly
+form `"{layer.dotted.path}"` used as a `$value`; chains are allowed (each hop is
+checked); the chain must terminate in a literal.
+
+## Token shape (kept from DTCG)
+
+- a **token** is an object with `$value` (required); optional `$type`,
+  `$description`.
+- `$type` is optional on a token and **inherited** from the nearest parent group
+  that sets it.
+- a **group** is any object without `$value`.
+
+## Value forms — supported `$type`s (NAMED divergences from DTCG 2025.10)
+
+| `$type`      | compact form (ours)                    | DTCG 2025.10 form        |
+|--------------|----------------------------------------|--------------------------|
+| `color`      | `"#RRGGBB"` / `"#RRGGBBAA"`            | object `{colorSpace,…}` ⟵ DIVERGES |
+| `dimension`  | `"<n><unit>"`, unit ∈ px·rem·em·%·vh·vw | object `{value,unit}` ⟵ DIVERGES   |
+| `number`     | JSON number                            | JSON number              |
+| `fontWeight` | `100`–`900` or a keyword string        | number / keyword         |
+| `duration`   | `"<n>ms"` / `"<n>s"`                    | object `{value,unit}` ⟵ DIVERGES   |
+| `fontFamily` | string or array of strings             | string / array           |
+
+Composites (`shadow`, `typography`, `border`) and the rarer DTCG types
+(`cubicBezier`, `strokeStyle`, `gradient`, `transition`) are **deferred** —
+additive later without breaking this dialect.
+
+## Validation — the named reds
+
+`_token_layer_violations(tokens)` returns `[]` for a valid file, else one
+`(code, path, detail)` per violation. The six codes:
+
+| code | when |
+|------|------|
+| `unknown_layer` | a top-level group is not primitive/semantic/component |
+| `unknown_type` | a token's resolved `$type` is outside the supported set |
+| `unresolved_alias` | `{a.b.c}` points at no token bearing a `$value` |
+| `cross_layer_citation` | an alias skips or inverts a layer |
+| `primitive_has_alias` | a primitive token's `$value` is an alias, not a literal |
+| `malformed_value` | a literal `$value` does not match the form for its `$type` |
+
+The validator lints **shape only** — stdlib, tool-agnostic, no rendering. The
+`add.py check` wiring (named reds) and the catalog/prototype-tree rules arrive in
+later udd-design-foundation tasks. To render: point a json-render-style renderer
+at the component layer (see the milestone's render recipe).