vinta-ai-workflows 0.7.0-alpha2 → 0.7.0-alpha4

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-alpha4 on 2026-09-13 -->
+<!-- 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 -->
 
@@ -217,6 +219,105 @@ the project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Fixed
 
+- **An agent can write in its own lane.** Every adapter declared
+  `permissionControl: true` and passed no policy at all: claude-code was spawned
+  as `-p --output-format stream-json …` with no `--permission-mode`, and codex as
+  `exec --json` with no sandbox and no approval flag, under a comment saying it
+  took both on the command line. So a headless run asked before its first write,
+  emitted a `permission_request`, rendered it in the transcript — and nothing
+  anywhere answered. The phase failed reporting a permission system it could not
+  see, having written nothing.
+
+  `run` and `serve` now take `--permission <ask|auto|full>`, defaulting to
+  `auto`. **The operator sets it, never the workflow document**: the document is
+  committed and shared, and a file in a repository should not be able to tell
+  someone else's machine to run agents without approvals.
+
+  Both CLIs refuse combinations that looked reasonable, and both were found by
+  running them rather than reading them: codex rejects `--sandbox` alongside
+  `--approve-for-me`, and `codex exec resume` accepts neither — passing the
+  fresh-spawn policy there turned a `stale_session` refusal, which the scheduler
+  retries cold, into a `fatal` one that fails the node.
+
+  This reverses a documented decision. The README said the daemon passed no
+  permission flags and that a committed `.claude/settings.json` was what made a
+  run able to write; that is now the narrowing layer on top of a mode, not the
+  only thing standing between an agent and a blocked lane.
+- **`purge --lanes --branches` clears what a failed run leaves behind.** A run's
+  lane worktrees are not under `runs/`, so no purge ever reached them: three
+  failed attempts at one plan left twelve worktrees, twelve summaries, and a set
+  of `plan/<id>/phase-*` branches still checked out — which is what makes the
+  *next* run of that plan impossible, since git refuses to check out a branch a
+  second worktree holds.
+
+  One rule decides both: **never delete the only copy of work.** A phase can
+  leave work committed on its branch or uncommitted in its worktree, and both
+  count — so a branch carrying commits no other branch has is kept, a lane with
+  a dirty tree is kept, and each is listed with the command to remove it by
+  hand. Untracked files count as work: a phase that wrote three new modules and
+  never committed them is exactly the case worth protecting.
+
+  Emptiness is measured as "carries no commit another branch does not already
+  have", not as "merged into HEAD". The latter is relative to wherever the
+  operator is standing, so on a feature branch — the checkout this is most often
+  run from — every empty phase branch looked unmerged and nothing was ever
+  cleaned up.
+
+  `--dry-run` and `--yes` work as they already did, and a worktree that will not
+  go is named rather than counted.
+
+- **`doctor` now catches, before a lane exists, the failures that used to take a
+  run each.** Four consecutive runs of one plan failed four different ways, and
+  every one of them was knowable at minute zero from the workflow and the repo.
+  - **Every `prompt_ref` and `plan_context_ref` is resolved against
+    `base_branch`**, with `git cat-file -e`, which reads the branch's tree and
+    so cannot be satisfied by a working-tree copy — the working tree being
+    exactly what a lane will not have. It distinguishes the three cases, because
+    they have three different fixes: never committed, **staged but never
+    committed** (`git add` alone does not put a file in a branch), and committed
+    on a different branch. The last offers both routes out — merge it, or point
+    `base_branch` at the branch that has it — since only the operator knows
+    which they want.
+  - **Phase branches held by another worktree** are reported with the directory
+    to remove. Lane directories are named per run and phase branches per
+    workflow, so a failed run leaves worktrees holding the branch names the next
+    run will try to cut, and git refuses to check out a branch twice. Nothing
+    cleans those up: `purge` deletes run state under `.vinta-ai-maestro/runs/`,
+    and lane worktrees are not there. `doctor` does not delete them either — a
+    failed lane's worktree is the only place its state survives — but it now
+    names each one and the exact command.
+
+- **A failed node records why.** `node_status` carried `{"status":"failed"}` and
+  nothing else, so two runs failing for two unrelated reasons produced identical
+  journal rows and the cause survived only in the operator's terminal. The
+  reason is now persisted — **sanitized**, not raw: errors the package builds
+  itself are identifiers by construction and are kept verbatim, and anything
+  else is reduced to its kind, the rule `recycleStage` already followed. The
+  journal is durable and API-served, and an exception message from a dependency
+  is exactly how repository content gets into one. Blocked dependents record
+  which node blocked them.
+
+- **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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vinta-ai-workflows",
-  "version": "0.7.0-alpha2",
+  "version": "0.7.0-alpha4",
   "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.