vinta-ai-workflows 0.7.0-alpha1 → 0.7.0-alpha3

package/CHANGELOG.md

@@ -7,6 +7,8 @@ the project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [0.7.0] — YYYY-MM-DD
 
+<!-- pre-release: 0.7.0-alpha3 on 2026-09-12 -->
+<!-- pre-release: 0.7.0-alpha2 on 2026-09-12 -->
 <!-- pre-release: 0.7.0-alpha1 on 2026-09-11 -->
 
 ### Added
@@ -216,6 +218,61 @@ the project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Fixed
 
+- **Two diagnostics that named the symptom and hid the cause.** Both came out of
+  one real run, and neither was a wrong answer — just an unusable one.
+  - **A phase whose plan is not committed** failed with `prompt_ref "…" names no
+    readable file`, against a path that was spelled correctly. A lane is a fresh
+    worktree of the base branch, so a plan sitting untracked in the operator's
+    checkout is in the one place the run cannot look. The message now names the
+    directory it resolved against and says why a plan is often not in it.
+  - **A lane summary the daemon could not accept** reported `summary unreadable`
+    and advised deleting the lane — which takes its forked databases with it,
+    over what turned out to be two wrong fields. `doctor` now names the fields
+    and what was expected, and offers repair before deletion. A file that does
+    not parse at all still reports as unreadable, because there is no field to
+    name. Neither message carries the offending *value*: a summary holds
+    database names and connection variables, and the value that failed
+    validation is the likeliest thing in it to be one.
+
+  `prepare-worktree` gained the rule that would have prevented the summary in
+  the first place — its `|` alternatives are closed sets read by machine, `null`
+  is how you say "none", and a strategy outside the set should be the closest
+  one plus a `note:` rather than a fourth word.
+
+- **`npx vinta-ai-maestro` now runs.** The published package pointed its `bin` at
+  `src/cli/bin.ts` and relied on Node stripping the types at startup — which Node
+  refuses to do anywhere under `node_modules`, unconditionally and with no flag to
+  override. So the CLI worked from a checkout and died on first run once installed,
+  with `ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`.
+
+  `packages/vinta-ai-maestro` now builds: `tsc` emits `dist/` with
+  `rewriteRelativeImportExtensions` (the source imports `.ts` specifiers, which
+  emitted JS cannot keep), vite writes the daemon's UI into `dist/ui`, and the
+  shebang is rewritten from the source's `--experimental-transform-types` form to
+  a plain `#!/usr/bin/env node` — a compiled entry point has no types left to
+  transform, and should not ask Node for a flag it is free to retire. `prepack`
+  runs the build, so a tarball can never be cut from a stale `dist/`.
+
+  Three packaging faults surfaced with it, each of which broke an install on its
+  own:
+  - **The UI was never in the tarball.** `serve` resolves its static root as
+    `dist/ui` and refuses to read outside it, so it would have booted and answered
+    every page with "build the UI first". The build now asserts `dist/ui/index.html`
+    exists rather than trusting a vite config that writes outside its own root.
+  - **`tailwindcss` and `tw-animate-css` were imported but never declared.** They
+    resolved only through pnpm's `.bin` shim setting `NODE_PATH`; building by any
+    other path failed to resolve them. Both are now devDependencies.
+  - **Everything the UI imports was a runtime dependency.** React, xterm,
+    lucide-react and the three workspace packages are bundled into `dist/ui` by
+    vite and cannot be loaded at runtime — yet a consumer installed all of them,
+    and two carried `workspace:*` specifiers that no registry understands. Moved to
+    devDependencies; the published package now declares six runtime dependencies
+    instead of fourteen.
+
+  CI packs the tarball, installs it into a throwaway project and runs the binary
+  from `node_modules`. Every previous check ran from a checkout, which is the one
+  place this class of bug cannot appear.
+
 - **Lane provisioning serializes `git worktree add`, not only the database
   template.** `prepare-worktree` previously named one serialization point; there
   are two. Git rewrites `.git/worktrees/` metadata on every add, and concurrent
@@ -238,22 +295,25 @@ the project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   nothing produces a merge commit full of markers that passes into the wave
   branch unnoticed.
 
-> The repository also gained `packages/vinta-ai-maestro/`, a **private workspace
-> package** that executes these workflows. It is not published and is not part of
-> the `vinta-ai-workflows` package — the root `files` whitelist excludes
-> `packages/`, so nothing in it is installed by `npx vinta-ai-workflows install`.
-> What ships from that work is the two generated schemas above and the skill
-> changes that produce and consume them.
+> The repository also gained `packages/vinta-ai-maestro/`, the workspace package
+> that executes these workflows. It is published as its own npm package,
+> `vinta-ai-maestro`, carrying the same version as `vinta-ai-workflows`, and is
+> run with `npx vinta-ai-maestro`. It is not part of the `vinta-ai-workflows`
+> tarball — the root `files` whitelist excludes `packages/`, so nothing in it is
+> installed by `npx vinta-ai-workflows install`. What ships from that work into
+> the skills package is the two generated schemas above and the skill changes
+> that produce and consume them.
 >
 > Its browser UI is now built on `packages/design-system/` (`vinta-design-system`),
-> a second private workspace package: oklch tokens in three layers mirroring
+> a second workspace package: oklch tokens in three layers mirroring
 > `vinta-schedule-design-system`, six run-status **tones** (`idle`, `active`,
 > `wait`, `attention`, `ok`, `error` — waiting is amber and failure is red, never
 > the same hue), shadcn/ui components on Tailwind CSS v4, a small layout kit, and
 > a light/dark/system theme. The run graph and the pipeline editor are re-skinned
 > through their own custom properties, so the canvas and the badges beside it
-> share one palette. Equally unpublished: nothing in it reaches `npx
-> vinta-ai-workflows install`.
+> share one palette. It and `vinta-dag-editor` publish on their own cadence
+> (`0.1.0`) as dependencies of `vinta-ai-maestro`; nothing in either reaches
+> `npx vinta-ai-workflows install`.
 
 ## [0.6.1] — 2026-08-17
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vinta-ai-workflows",
-  "version": "0.7.0-alpha1",
+  "version": "0.7.0-alpha3",
   "description": "Bootstrap AI tooling (AGENTS.md, skills, sub-agents) across Claude Code, Codex, Cursor, and VS Code + GitHub Copilot.",
   "type": "module",
   "packageManager": "pnpm@10.33.0",

package/skills/vinta-derive-skills/resources/foundation-skills/prepare-worktree/SKILL.md

@@ -355,7 +355,7 @@ state:
     files: [.env, .envrc, ...]
   dev_db:
     engine: postgres | mysql | sqlite | mongo | redis
-    strategy: fork | share | stub
+    strategy: fork | share | stub     # closed set — see "The summary is read by machine"
     forked_name: <forked db name>   # null when share / stub
     connection_url_var: DATABASE_URL
     reset_cmd: <shell command that returns this DB to the state of a fresh checkout>
@@ -365,7 +365,7 @@ state:
     # instead of reusing this worktree across a migration boundary.
   test_db:
     engine: ...
-    strategy: fork | share
+    strategy: fork | share            # closed set, as above
     forked_name: ...
     connection_url_var: TEST_DATABASE_URL
     reset_cmd: <same idea, for the test DB>   # null when not resettable
@@ -467,6 +467,14 @@ Every step gated on user confirmation when the worktree has un-pushed branches.
 
 - **Symlink for reads, copy for writes, fork for state.** This is the only mental model that scales. Default to fork when unsure — disk is cheap, corrupted main-checkout DBs are not.
 - **Never share a writable DB across worktrees by default.** The race conditions are subtle and the failure mode is silent data corruption.
+### The summary is read by machine
+
+This file is not a note to the next human. [vinta-ai-maestro](https://github.com/vintasoftware/vinta-ai-workflows/tree/main/packages/vinta-ai-maestro) parses it to decide whether a lane can be handed to another phase, so **every `|` above is a closed set and every key is required** — `null` is how you say "none", and omitting the key is not the same thing.
+
+A value outside the set makes the lane unusable by the daemon. It does not fail loudly at write time; it fails later, as `doctor` reporting the lane and the field it could not accept, long after the worktree and its forked databases exist. Seen in the wild: a `strategy: create-empty-and-migrate` invented to describe a database that had been created empty and migrated by hand, with `reset_cmd` left off entirely. Neither is in the spec, and the pair cost eleven lanes their readability.
+
+If none of the listed strategies describes what you did, **the honest record is the closest one plus a `note:`** — the schema keeps `note` free-form for exactly this. A database created empty and migrated is a `fork` whose `reset_cmd` re-runs that same creation; a database you could not provision at all is a `stub`. What it must never be is a fourth word.
+
 - **`COMPOSE_PROJECT_NAME` does not isolate `external:`/fixed-`name:` volumes or fixed host ports — always run the [4a](#4a--neutralize-compose-isolation-leaks) generator.** For a compose-delivered DB the data volumes are forked *unconditionally* (independent of `schema_change` and `test_db_strategy`): the worktree runs its own server, and two servers on one volume is corruption. "Share the DB" only ever means share a connection to a single already-running server, never a second server on shared storage. The fix is a generated, out-of-tree override + a `COMPOSE_FILE` line in the copied `.env` — never an edit to any tracked compose file. Verify the volume-differs invariant before declaring the worktree runnable.
 - **Every fork decision lands in `.vinta-ai-workflows/worktrees/<name>.yaml`.** Teardown reads it; humans grep it; agents resuming a stalled plan read it. No decision lives only in conversation memory.
 - **Worktree root governed by runtime conventions.** claude-code uses `.claude/worktrees/`; other harnesses use sibling dirs. Don't fight the harness — match it.