@rasensio/aidlc-content 1.85.0 → 1.87.0

package/docs/state-and-concurrency.md

@@ -38,6 +38,10 @@ and the `worktree_path` it was taken from. It goes **stale** after `claim_timeou
 60, set in `.aidlc/config.yaml`) — a long conversation will outlive its own claim, and re-claiming
 renews it.
 
+Completing an instance releases its claim: the `aidlc transition` that completes it removes the claim
+file and logs the release. A claim left on a completed instance by an older CLI is orphaned —
+`aidlc status` warns about it and `aidlc status --prune` removes it.
+
 Note the wrinkle, because it will bite you: `owner` in a phase file is a *label*, not a lock. Nothing
 in the CLI writes it. The ownership gate resolves the current actor from the live claim, falling back
 to `$USER` when no claim is live. So a phase file whose `owner` was hand-written to one identity,
@@ -73,8 +77,13 @@ inside it before starting the agent session.
   concurrency check told a second session in the same checkout it had "nothing to collide on",
   while the roadmap read a `.aidlc/` that did not exist. It was deleted rather than kept beside the
   new one: a helper answering the wrong question is how one mistake reached five callers.
-  `aidlc start --worktree` in a nested project still writes to the new worktree's top; that is
-  item-20261009-worktree-start-in-nested-project.
+  `worktree.ts` `createWorktree` uses the same path rule through `projectPathInCheckout`: the new
+  worktree goes beside the *checkout*, not beside the project, and the instance, its cost shim and
+  its actions use the worktree's copy of the project. For a project at `packages/<name>` the project's
+  `../` is still inside the repository, so a worktree there showed up in the main checkout as an
+  untracked folder that `git add -A` would commit, and the state landed at a top no command reads.
+  The `Worktree:` line `aidlc start` prints names that copy, because it is the directory to work
+  in and the one autopilot launches its agent in; a `Checkout:` line names the top when it differs.
 - `packages/cli/src/state` — instance folders, `phase-<name>.yaml`, and the append-only
   `transitions.log`.
 - `packages/cli/src/commands/claim.ts` — the `claim` and `release` commands, which also write the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rasensio/aidlc-content",
-  "version": "1.85.0",
+  "version": "1.87.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/skills/03-entry-point.md

@@ -86,7 +86,7 @@ Two sessions sharing one checkout collide on **git**, not on state: creating a b
 3. A live claim that does **not** share this working directory: say so in one line and proceed with no gate. Knowing another instance is in flight is useful even when it cannot interfere; silence would be worse.
 4. Not a git repo, or no live claim sharing this working directory → proceed normally, no gate.
 5. A live claim sharing this working directory → present exactly three options and proceed with none until one is chosen:
-   1. **Start in a separate worktree (recommended)** — `git worktree add -b <prefix>/<YYYYMMDD>-<name> <worktree_dir>/<repo>-<name> main` (prefix per template: bugfix→fix, micro-task/spike→chore, else feat; `worktree_dir` from the `concurrency:` config block, default `../`). Do all further work for the new instance inside that worktree; set `AIDLC_WORKTREE=1` before firing `on-instance-start` actions so the branch action no-ops. CLI shortcut: `aidlc start <template> --name <name> --worktree`.
+   1. **Start in a separate worktree (recommended)** — `git worktree add -b <prefix>/<YYYYMMDD>-<name> <worktree_dir>/<repo>-<name> main` (prefix per template: bugfix→fix, micro-task/spike→chore, else feat; `worktree_dir` from the `concurrency:` config block, default `../`, resolved from the repository's top and `<repo>` its directory name — for a project below the repository root, never from the project). Do all further work for the new instance inside that worktree's copy of the project (`<worktree>/<project path>`); set `AIDLC_WORKTREE=1` before firing `on-instance-start` actions so the branch action no-ops. CLI shortcut: `aidlc start <template> --name <name> --worktree`.
    2. **Stop** — come back when the other instance is done.
    3. **Continue in this checkout, no code changes** — record `branch: null` in the new `instance.yaml`; entering Implementation stays blocked until a branch exists. CLI shortcut: `aidlc start <template> --name <name> --no-code`.
 6. `concurrency.mode: forbid` in config replaces the menu with a hard stop while another session is live — **any** live session, sharing this working directory or not. Someone choosing a hard stop is choosing it for reasons this gate should not second-guess.