openuispec 0.1.24 → 0.1.27

package/README.md

@@ -137,11 +137,13 @@ openuispec/
 │       ├── openuispec/                  # Source OpenUISpec project
 │       ├── generated/                   # Generated iOS, Android, and web apps
 │       └── artifacts/                   # Screenshots and supporting outputs
-├── cli/                                 # CLI tool (openuispec init, drift, validate)
+├── cli/                                 # CLI tool (openuispec init, drift, prepare, validate)
 │   ├── index.ts                        # Entry point
 │   └── init.ts                         # Project scaffolding + AI rules
 ├── drift/                               # Drift detection (spec change tracking)
 │   └── index.ts                        # Hash-based drift checker
+├── prepare/                             # AI-ready target work bundle generation
+│   └── index.ts                        # Baseline-aware target preparation
 ├── LICENSE
 └── README.md
 ```
@@ -183,6 +185,8 @@ brand:
 
 Validate with: `openuispec validate`
 
+Use `openuispec validate semantic` to run cross-reference linting for locale keys, formatter refs, mapper refs, contracts, icons, navigation targets, and API endpoint references.
+
 ## Output directories
 
 By default, drift stores state in `generated/<target>/<project>/`. To point targets to your actual code directories, add `output_dir` to `openuispec.yaml`:
@@ -196,7 +200,45 @@ generation:
     ios: "../kmp-ui/iosApp/"
 ```
 
-Paths are relative to `openuispec.yaml`. The `.openuispec-state.json` file is stored inside each output directory.
+Paths are relative to `openuispec.yaml`. The `.openuispec-state.json` file is stored inside each output directory and records spec file hashes plus the git baseline commit metadata captured at snapshot time.
+
+Use the commands like this:
+- `openuispec validate` checks schema correctness
+- `openuispec validate semantic` checks cross-references such as locale keys, formatters, mappers, contracts, icons, navigation targets, and API endpoints
+- `openuispec drift --target <t> --explain` explains semantic spec changes since that target's accepted baseline
+- `openuispec prepare --target <t>` turns those changes into an AI-ready target update bundle
+- `openuispec status` shows every target's snapshot state, baseline commit, and whether that target is behind the current spec
+
+If a target snapshot was created before baseline metadata was added, `--explain` and `status` will tell you to re-run `openuispec drift --snapshot --target <target>` for that target.
+
+## Target update workflow
+
+When a shared spec change needs to be applied to a target:
+
+```bash
+openuispec validate
+openuispec drift --target ios --explain
+openuispec prepare --target ios
+# update the ios implementation
+openuispec drift --snapshot --target ios
+```
+
+Meaning:
+- `validate` checks schema correctness
+- `validate semantic` checks cross-reference integrity
+- `drift --explain` shows semantic spec changes since that target's accepted baseline
+- `prepare` packages those changes into an AI/developer work bundle
+- `drift --snapshot` accepts the updated state after the target UI has been updated
+
+Before picking the next platform to update, run:
+
+```bash
+openuispec status
+```
+
+to see which targets are already up to date and which ones still need to catch up with shared spec changes.
+
+`drift --snapshot` is bookkeeping. It does not prove that the target code matches the spec.
 
 ## Spec at a glance
 

package/cli/index.ts

@@ -5,7 +5,10 @@
  * Usage:
  *   openuispec init                           Create a new spec project
  *   openuispec drift [--target <t>]           Check for spec drift
- *   openuispec drift --snapshot --target <t>  Snapshot current state
+ *   openuispec drift --snapshot --target <t>  Snapshot current state + git baseline
+ *   openuispec drift --target <t> --explain   Explain semantic changes since baseline
+ *   openuispec prepare --target <t>           Build an AI-ready target update bundle
+ *   openuispec status                         Show cross-target baseline/drift status
  *   openuispec validate [group...]            Validate spec files against schemas
  */
 
@@ -55,6 +58,18 @@ async function main(): Promise<void> {
       break;
     }
 
+    case "prepare": {
+      const { runPrepare } = await import("../prepare/index.js");
+      runPrepare(rest);
+      break;
+    }
+
+    case "status": {
+      const { runStatus } = await import("../status/index.js");
+      runStatus(rest);
+      break;
+    }
+
     case "validate": {
       const { runValidate } = await import("../schema/validate.js");
       runValidate(rest);
@@ -72,10 +87,13 @@ Usage:
   openuispec init                           Create a new spec project
   openuispec update-rules                   Update AI rules to match installed version
   openuispec drift [--target <t>]           Check for spec drift
-  openuispec drift --snapshot --target <t>  Snapshot current state
+  openuispec drift --snapshot --target <t>  Snapshot current state + git baseline
+  openuispec drift --target <t> --explain   Explain semantic changes since baseline
+  openuispec prepare --target <t>           Build an AI-ready target update bundle
+  openuispec status                         Show cross-target baseline/drift status
   openuispec validate [group...]            Validate spec files
 
-Validate groups: manifest, tokens, screens, flows, platform, locales, contracts
+Validate groups: manifest, tokens, screens, flows, platform, locales, contracts, semantic
 
 Docs: https://openuispec.rsteam.uz
 `);

package/cli/init.ts

@@ -178,9 +178,12 @@ Do NOT guess the file format — skipping this step will produce invalid YAML th
 
 \`\`\`bash
 openuispec validate             # Validate spec files against schemas
+openuispec validate semantic    # Run semantic cross-reference linting
 openuispec validate screens     # Validate only screens
-openuispec drift --target ${targets[0]}    # Check for spec drift
-openuispec drift --snapshot --target ${targets[0]}  # Snapshot current state
+openuispec status               # Show cross-target baseline/drift status
+openuispec drift --target ${targets[0]} --explain   # Explain semantic spec drift
+openuispec prepare --target ${targets[0]}          # Build an AI-ready target update bundle
+openuispec drift --snapshot --target ${targets[0]} # Snapshot current state + git baseline
 \`\`\`
 
 ## Learn more
@@ -252,24 +255,56 @@ This means the project has existing UI code but hasn't been specced yet. Your jo
 4. **Extract tokens** — scan for colors, fonts, spacing and create files in \`${specDir}/tokens/\`.
 5. **Update the manifest** — fill in \`data_model\` and \`api.endpoints\` in \`${specDir}/openuispec.yaml\`.
 
-## Making UI changes
-1. Read the relevant spec files before modifying any UI code.
-2. If the change requires a spec update, modify the spec FIRST, then update code.
-3. Never modify generated code without updating the spec.
-4. When adding a new screen, create the corresponding spec file.
-5. When removing a screen, remove the spec file and update flow references.
-
-## After modifying spec files
-1. Run \`openuispec validate\` to check specs against the schema.
-2. **Update the generated code** for each affected platform to match the new spec.
-3. Run \`openuispec drift --snapshot --target <target>\` to baseline the updated state.
-4. Run \`openuispec drift\` to verify no untracked drift remains.
+## OpenUISpec Source Of Truth
+
+OpenUISpec spec files are the primary source of truth for UI behavior across platforms.
+
+### Start from spec when:
+- the request changes screen structure
+- the request changes navigation
+- the request changes fields, actions, validation, or data binding
+- the request changes tokens, variants, contracts, flows, or localization
+- the request affects more than one platform
+- the request is phrased in product/UI terms rather than platform-code terms
+
+Spec-first workflow:
+1. Read \`${specDir}/openuispec.yaml\` and the relevant spec files first.
+2. Update the spec first.
+3. Update the affected generated/native UI code to match the spec.
+4. Run \`openuispec validate\`.
+5. Run \`openuispec validate semantic\`.
+6. Run \`openuispec drift --target <target> --explain\` to inspect semantic changes since that target's baseline.
+7. Run \`openuispec prepare --target <target>\` to build the AI/developer work bundle for that target.
+8. Verify the affected UI targets build/run if possible.
+9. Only then run \`openuispec drift --snapshot --target <target>\` for affected targets.
+10. Run \`openuispec drift --target <target> --explain\` again to confirm no spec changes remain for that target.
+11. Use \`openuispec status\` to see which other targets are still behind the updated spec.
+
+### Start from platform code when:
+- the change is platform-specific polish
+- the change is a local bug fix that does not alter shared semantic behavior
+- the request explicitly asks for an iOS-only, Android-only, or web-only adjustment
+
+Platform-first workflow:
+1. Update native/platform code.
+2. If the change affects shared semantics, sync the spec afterward.
+3. If the change is intentionally platform-specific, document it in \`platform/*.yaml\` when appropriate.
+
+### Never do this:
+- Do not snapshot drift immediately after changing spec unless the UI code has also been updated.
+- Do not treat \`openuispec drift\` as proof that generated UI matches the spec.
+- Do not skip \`--explain\` / \`prepare\` when another platform needs to catch up with shared spec changes.
+- Do not modify generated UI without checking whether the spec must change first.
 
 ## CLI commands
 - \`openuispec init\` — scaffold a new spec project
 - \`openuispec validate [group...]\` — validate spec files against schemas
+- \`openuispec validate semantic\` — run semantic cross-reference linting
 - \`openuispec drift --target <t>\` — check for spec drift
+- \`openuispec drift --target <t> --explain\` — explain semantic spec drift since the target baseline
 - \`openuispec drift --snapshot --target <t>\` — snapshot current state
+- \`openuispec prepare --target <t>\` — build an AI-ready target update bundle
+- \`openuispec status\` — show cross-target baseline/drift status
 - \`openuispec update-rules\` — update AI rules to match installed package version
 - \`openuispec drift --all\` — include stubs in drift check
 ${RULES_END_MARKER}
@@ -476,7 +511,7 @@ Getting started (new project):
   2. Create screens in ${specDir}/screens/ (one YAML per screen)
   3. Create flows in ${specDir}/flows/ (multi-step navigation)
   4. Ask AI to generate native code from the spec
-  5. Run \`openuispec drift --snapshot --target ${targets[0]}\` to baseline
+  5. Run \`openuispec drift --snapshot --target ${targets[0]}\` to baseline the first accepted target state
 
 Getting started (existing project):
   1. Ask AI to read your existing UI code and generate spec files:
@@ -484,11 +519,15 @@ Getting started (existing project):
   2. Spec screens incrementally: stub → draft → ready
   3. Only ready/draft screens are tracked by drift detection
   4. Run \`openuispec validate\` to check specs against the schema
+  5. Use \`openuispec drift --target ${targets[0]} --explain\` and \`openuispec prepare --target ${targets[0]}\` before asking AI to update a target
 
 Commands:
   openuispec validate             Validate spec files
-  openuispec drift --target ios   Check for spec changes
-  openuispec drift --snapshot --target ios   Save current state
+  openuispec validate semantic   Check semantic cross-references
+  openuispec status   Show cross-target baseline/drift status
+  openuispec drift --target ios --explain   Explain semantic spec changes
+  openuispec prepare --target ios   Build an AI-ready target update bundle
+  openuispec drift --snapshot --target ios   Save current state + git baseline
 
 AI rules have been added to CLAUDE.md and AGENTS.md.
 

package/docs/implementation-notes.md

@@ -0,0 +1,115 @@
+# Implementation Notes
+
+## Drift baseline metadata
+
+- `.openuispec-state.json` now stores:
+  - spec file hashes
+  - snapshot timestamp
+  - target
+  - git baseline metadata: `kind`, `commit`, `branch`
+- Snapshot behavior:
+  - `kind: git_commit` means the tracked spec files matched `HEAD` exactly at snapshot time
+  - `kind: working_tree` means the snapshot was taken from a dirty spec working tree
+- This baseline metadata is a pointer to the accepted spec state for a target. It is not a proof that the target UI code is aligned.
+- Backward compatibility:
+  - older `.openuispec-state.json` files do not include `baseline`
+  - `drift --explain` and `status` must report that clearly and ask the user to re-run `openuispec drift --snapshot --target <target>`
+  - hash-only snapshots are still valid for basic drift counts
+
+## Drift `--explain`
+
+- Document that `openuispec drift --target <target> --explain` explains **spec changes since that target's own snapshot baseline**, not platform code changes.
+- Call out the common cross-platform workflow:
+  - iOS developer updates shared spec and iOS code, then snapshots only `ios`
+  - Android developer pulls later without updating `generated/android/.../.openuispec-state.json`
+  - `openuispec drift --target android --explain` should then show the shared spec changes Android still needs to apply
+- Clarify that if another developer also updates and commits a target's `.openuispec-state.json`, that target will no longer see those spec changes as drift.
+- Clarify that `--explain` requires an exact `git_commit` baseline. If the snapshot was taken from a dirty working tree, explanations are intentionally unavailable until the target is re-snapshotted from a clean commit.
+- Current behavior:
+  - compares baseline spec files from git to current working-tree spec files
+  - parses YAML/JSON semantically
+  - reports property-level changes
+  - text and JSON output both include semantic explanations
+- Current limitation:
+  - explanations are spec-only
+  - no platform-code verification is attempted
+
+## `prepare` command
+
+- `openuispec prepare --target <target>` is the operational bridge between spec drift and AI implementation work.
+- It should be documented as:
+  1. read the target's snapshot baseline
+  2. compute semantic spec changes since that baseline
+  3. produce an AI-ready bundle with likely target scope
+- Current output includes:
+  - project and target
+  - output directory
+  - likely code roots
+  - baseline commit info
+  - semantic change summary
+  - per-spec-file work items
+  - best-effort candidate target files
+  - next-step guidance
+- Important positioning:
+  - `prepare` does not generate code
+  - `prepare` does not verify code correctness
+  - `prepare` packages the spec delta into scoped implementation work for AI or developers
+
+## Semantic linting
+
+- `openuispec validate semantic` is now the high-signal semantic consistency pass on top of schema validation.
+- Current checks:
+  - locale key references from `$t:...`
+  - formatter references from `format:...`
+  - mapper references from `map:...`
+  - contract references
+  - icon references
+  - screen/flow destination references
+  - API endpoint references
+  - submit-form `form_id` references
+  - locale coverage against the default locale
+- Token validation behavior:
+  - validates app-level references for `color.*`, `spacing.*`, `typography.*`, and `elevation.*`
+  - token resolution is normalized to actual token-family shapes, not raw YAML object paths
+  - skips dynamic token expressions such as `color.priority.{task.priority}`
+  - skips token-default checking inside contract definition files to avoid false positives on contract-local token names
+- Icon validation behavior:
+  - uses icon registry + custom icons + declared variant suffixes
+  - treats generated variants like `checkmark_list_fill` as valid when the base icon exists and `_fill` is a declared suffix
+  - skips dynamic/data-driven icon strings such as `item.icon` or `{project.icon}`
+- Current limitation:
+  - semantic lint is intentionally heuristic
+  - it validates stable cross-references, not full behavioral correctness
+
+## `status` command
+
+- `openuispec status` is the cross-target overview command.
+- Current output includes, per target:
+  - output directory
+  - snapshot present or missing
+  - snapshot timestamp
+  - baseline kind / commit / branch
+  - changed / added / removed spec file counts
+  - `behind` boolean
+  - `explain_available` boolean
+  - note for missing or legacy snapshots
+- Important positioning:
+  - `status` answers "which targets are behind shared spec changes?"
+  - `status` does not verify code alignment
+- Real-world behavior to document:
+  - if `web` was re-snapshotted after the new baseline metadata was added, but `ios` and `android` still have older state files, `status` should show:
+    - `web`: baseline available, explain available
+    - `ios` / `android`: snapshot exists, but no baseline metadata, explain unavailable with re-snapshot note
+
+## Workflow docs follow-up
+
+- Recommended target workflow now is:
+  1. `openuispec validate`
+  2. `openuispec validate semantic`
+  3. `openuispec status`
+  4. `openuispec drift --target <target> --explain`
+  5. `openuispec prepare --target <target>`
+  6. update target UI code
+  7. build/run and review
+  8. `openuispec drift --snapshot --target <target>`
+- `drift --snapshot` should continue to be described as bookkeeping/baselining, not as proof that the target implementation matches the spec.

package/docs/release-notes-v0.1.26.md

@@ -0,0 +1,64 @@
+# OpenUISpec v0.1.26
+
+This release expands OpenUISpec as a spec-management and AI-orchestration tool for multi-platform UI work.
+
+## New features
+
+- `openuispec drift --target <target> --explain`
+  Explains semantic spec changes since a target's accepted baseline instead of only reporting file drift.
+
+- Git baseline metadata in `.openuispec-state.json`
+  Drift snapshots now record the git baseline commit and branch for each target.
+
+- `openuispec prepare --target <target>`
+  Produces an AI-ready target update bundle with:
+  - semantic change summary
+  - likely code roots
+  - candidate target files
+  - next-step guidance
+
+- `openuispec validate semantic`
+  Adds semantic cross-reference linting for:
+  - locale keys
+  - formatter refs
+  - mapper refs
+  - contract refs
+  - icon refs
+  - navigation targets
+  - API endpoint refs
+  - submit-form refs
+
+- `openuispec status`
+  Shows cross-target snapshot state, baseline metadata, and which targets are behind the current spec.
+
+## Workflow updates
+
+Recommended target workflow is now:
+
+1. `openuispec validate`
+2. `openuispec validate semantic`
+3. `openuispec status`
+4. `openuispec drift --target <target> --explain`
+5. `openuispec prepare --target <target>`
+6. update target UI
+7. `openuispec drift --snapshot --target <target>`
+
+`drift --snapshot` remains a bookkeeping step. It does not prove target code alignment.
+
+## Docs and rule updates
+
+- Public README updated for `--explain`, `prepare`, `validate semantic`, and `status`
+- Project scaffolding/rules updated in `init`
+- Sample AI rules and sample spec README updated to match the new workflow
+
+## Reliability improvements
+
+- Added regression tests for:
+  - `drift --explain` + `prepare`
+  - semantic linting
+  - cross-target `status`
+- CI now runs the test suite in addition to schema validation
+
+## Sample fix
+
+- Fixed Todo Orbit sample semantic linting by adding the missing `pencil` icon token

package/docs/release-notes-v0.1.27.md

@@ -0,0 +1,28 @@
+# OpenUISpec v0.1.27
+
+This patch supersedes `v0.1.26`.
+
+## Fix
+
+- Fixed npm install / publish lifecycle breakage caused by naming the repo script `prepare`.
+  - The package now uses `prepare:target` for the repo-local helper script.
+  - `openuispec prepare --target <target>` remains the CLI command.
+
+## Includes from v0.1.26
+
+- `openuispec drift --target <target> --explain`
+- git baseline metadata in `.openuispec-state.json`
+- `openuispec prepare --target <target>`
+- `openuispec validate semantic`
+- `openuispec status`
+- updated workflow docs, AI rules, tests, CI, and sample fixes
+
+## Recommended workflow
+
+1. `openuispec validate`
+2. `openuispec validate semantic`
+3. `openuispec status`
+4. `openuispec drift --target <target> --explain`
+5. `openuispec prepare --target <target>`
+6. update target UI
+7. `openuispec drift --snapshot --target <target>`