openuispec 0.1.25 → 0.1.28

package/README.md

@@ -68,7 +68,7 @@ For platform generation, treat these as hard output constraints:
 
 See the examples for concrete reference projects:
 
-- [TaskFlow](./examples/taskflow/) for a compact spec covering all 7 contract families
+- [TaskFlow](./examples/taskflow/openuispec/) for a compact spec covering all 7 contract families
 - [Todo Orbit](./examples/todo-orbit/openuispec/) for a bilingual task app with generated iOS, Android, and web targets under `examples/todo-orbit/generated/`
 
 ## Repository structure
@@ -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
 ```
@@ -152,21 +154,21 @@ Every file type has a corresponding JSON Schema in `schema/`. **Read the schema
 
 | File | Schema | Root key | Example |
 |------|--------|----------|---------|
-| `openuispec.yaml` | `openuispec.schema.json` | `spec_version` | [openuispec.yaml](./examples/taskflow/openuispec.yaml) |
-| `screens/*.yaml` | `screen.schema.json` | `<screen_id>` | [home.yaml](./examples/taskflow/screens/home.yaml) |
-| `flows/*.yaml` | `flow.schema.json` | `<flow_id>` | [create_task.yaml](./examples/taskflow/flows/create_task.yaml) |
-| `platform/*.yaml` | `platform.schema.json` | `platform` | [ios.yaml](./examples/taskflow/platform/ios.yaml) |
-| `locales/*.json` | `locale.schema.json` | (object) | [en.json](./examples/taskflow/locales/en.json) |
-| `contracts/<name>.yaml` | `contract.schema.json` | `<contract_name>` | [input_field.yaml](./examples/taskflow/contracts/input_field.yaml) |
-| `contracts/x_*.yaml` | `custom-contract.schema.json` | `<x_name>` | [x_media_player.yaml](./examples/taskflow/contracts/x_media_player.yaml) |
-| `tokens/color.yaml` | `tokens/color.schema.json` | `color` | [color.yaml](./examples/taskflow/tokens/color.yaml) |
-| `tokens/typography.yaml` | `tokens/typography.schema.json` | `typography` | [typography.yaml](./examples/taskflow/tokens/typography.yaml) |
-| `tokens/spacing.yaml` | `tokens/spacing.schema.json` | `spacing` | [spacing.yaml](./examples/taskflow/tokens/spacing.yaml) |
-| `tokens/elevation.yaml` | `tokens/elevation.schema.json` | `elevation` | [elevation.yaml](./examples/taskflow/tokens/elevation.yaml) |
-| `tokens/motion.yaml` | `tokens/motion.schema.json` | `motion` | [motion.yaml](./examples/taskflow/tokens/motion.yaml) |
-| `tokens/layout.yaml` | `tokens/layout.schema.json` | `layout` | [layout.yaml](./examples/taskflow/tokens/layout.yaml) |
-| `tokens/themes.yaml` | `tokens/themes.schema.json` | `themes` | [themes.yaml](./examples/taskflow/tokens/themes.yaml) |
-| `tokens/icons.yaml` | `tokens/icons.schema.json` | `icons` | [icons.yaml](./examples/taskflow/tokens/icons.yaml) |
+| `openuispec.yaml` | `openuispec.schema.json` | `spec_version` | [openuispec.yaml](./examples/taskflow/openuispec/openuispec.yaml) |
+| `screens/*.yaml` | `screen.schema.json` | `<screen_id>` | [home.yaml](./examples/taskflow/openuispec/screens/home.yaml) |
+| `flows/*.yaml` | `flow.schema.json` | `<flow_id>` | [create_task.yaml](./examples/taskflow/openuispec/flows/create_task.yaml) |
+| `platform/*.yaml` | `platform.schema.json` | `platform` | [ios.yaml](./examples/taskflow/openuispec/platform/ios.yaml) |
+| `locales/*.json` | `locale.schema.json` | (object) | [en.json](./examples/taskflow/openuispec/locales/en.json) |
+| `contracts/<name>.yaml` | `contract.schema.json` | `<contract_name>` | [input_field.yaml](./examples/taskflow/openuispec/contracts/input_field.yaml) |
+| `contracts/x_*.yaml` | `custom-contract.schema.json` | `<x_name>` | [x_media_player.yaml](./examples/taskflow/openuispec/contracts/x_media_player.yaml) |
+| `tokens/color.yaml` | `tokens/color.schema.json` | `color` | [color.yaml](./examples/taskflow/openuispec/tokens/color.yaml) |
+| `tokens/typography.yaml` | `tokens/typography.schema.json` | `typography` | [typography.yaml](./examples/taskflow/openuispec/tokens/typography.yaml) |
+| `tokens/spacing.yaml` | `tokens/spacing.schema.json` | `spacing` | [spacing.yaml](./examples/taskflow/openuispec/tokens/spacing.yaml) |
+| `tokens/elevation.yaml` | `tokens/elevation.schema.json` | `elevation` | [elevation.yaml](./examples/taskflow/openuispec/tokens/elevation.yaml) |
+| `tokens/motion.yaml` | `tokens/motion.schema.json` | `motion` | [motion.yaml](./examples/taskflow/openuispec/tokens/motion.yaml) |
+| `tokens/layout.yaml` | `tokens/layout.schema.json` | `layout` | [layout.yaml](./examples/taskflow/openuispec/tokens/layout.yaml) |
+| `tokens/themes.yaml` | `tokens/themes.schema.json` | `themes` | [themes.yaml](./examples/taskflow/openuispec/tokens/themes.yaml) |
+| `tokens/icons.yaml` | `tokens/icons.schema.json` | `icons` | [icons.yaml](./examples/taskflow/openuispec/tokens/icons.yaml) |
 
 Every token file **must** have a single root wrapper key matching its type:
 
@@ -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,48 @@ 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.
+
+`openuispec drift --snapshot --target <target>` requires that target output directory to already exist. If it does not, generate the target code first, then snapshot the accepted baseline.
+
+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, still needs a baseline, or has not been generated yet
+
+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
+# ensure the ios output directory already exists
+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 and the target output directory exists
+
+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, and it will not create a missing target output directory for you.
 
 ## 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

@@ -171,16 +171,19 @@ Do NOT guess the file format — skipping this step will produce invalid YAML th
 **Reference files inside the package (read in this order):**
 1. \`README.md\` — schema tables, file format reference, root keys
 2. \`spec/openuispec-v0.1.md\` — full specification (contracts, layout, expressions, etc.)
-3. \`examples/taskflow/\` — complete working example with all file types
+3. \`examples/taskflow/openuispec/\` — complete working example with all file types
 4. \`schema/\` — JSON Schemas for validation
 
 ## CLI commands
 
 \`\`\`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 after target output exists
 \`\`\`
 
 ## Learn more
@@ -215,7 +218,7 @@ Do NOT guess the file format — skipping this step will produce invalid YAML th
 **Reference files inside the package (read in this order):**
 1. \`README.md\` — schema tables, file format reference, root wrapper keys
 2. \`spec/openuispec-v0.1.md\` — full specification (contracts, layout, expressions, adaptive, etc.)
-3. \`examples/taskflow/\` — complete working example with all file types
+3. \`examples/taskflow/openuispec/\` — complete working example with all file types
 4. \`schema/\` — JSON Schemas for every file type
 
 These files are updated with each package version. Always read from the installed package,
@@ -269,9 +272,13 @@ Spec-first workflow:
 2. Update the spec first.
 3. Update the affected generated/native UI code to match the spec.
 4. Run \`openuispec validate\`.
-5. Verify the affected UI targets build/run if possible.
-6. Only then run \`openuispec drift --snapshot --target <target>\` for affected targets.
-7. Run \`openuispec drift --target <target>\` as a bookkeeping check.
+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, after that target output directory exists.
+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
@@ -286,13 +293,18 @@ Platform-first workflow:
 ### 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 --snapshot --target <t>\` — snapshot current state
+- \`openuispec drift --target <t> --explain\` — explain semantic spec drift since the target baseline
+- \`openuispec drift --snapshot --target <t>\` — snapshot current state after the target output exists
+- \`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}
@@ -499,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 after that target output directory exists
 
 Getting started (existing project):
   1. Ask AI to read your existing UI code and generate spec files:
@@ -507,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 after target output exists
 
 AI rules have been added to CLAUDE.md and AGENTS.md.
 

package/docs/implementation-notes.md

@@ -0,0 +1,119 @@
+# 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
+  - whether the output directory exists
+  - 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` should distinguish "needs generation" from "needs baseline"
+  - `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. ensure the target output directory exists
+  9. `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.
+- If the target output directory does not exist yet, the CLI should direct the user to run code generation first instead of implying that snapshot can initialize an empty target.

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>`

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

@@ -0,0 +1,25 @@
+# OpenUISpec v0.1.28
+
+This patch supersedes `v0.1.27`.
+
+## Fixes
+
+- Fixed the drift/prepare onboarding dead-end for targets that have not been generated yet.
+  - `drift --snapshot` now keeps the guard against baselining an empty target.
+  - Missing-snapshot guidance now tells users to generate the target output first when the output directory does not exist.
+- Improved `status` to distinguish:
+  - targets that need generation
+  - targets that need a baseline snapshot
+- Updated workflow docs and generated project templates to describe the generation-first requirement before snapshotting.
+- Stabilized the affected CLI tests in this repo by invoking TypeScript entrypoints through the `tsx` loader path instead of the IPC-based binary wrapper.
+
+## 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. ensure the target output directory exists
+8. `openuispec drift --snapshot --target <target>`

package/docs/stress-test-maturity-report.md

@@ -14,7 +14,7 @@ This assessment stress-tested the project at four layers:
 
 ```bash
 npm ci
-npm run validate                                # from examples/taskflow (workspace script)
+npm run validate                                # from examples/taskflow/openuispec (workspace script)
 npx tsx ../../../schema/validate.ts            # from examples/todo-orbit/openuispec
 npx tsc --noEmit
 for t in ios android web; do