@tablation/crew 0.16.0 → 0.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tablation/crew",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "A standing team of headless agents that picks work off a Tablation board, does it on a machine you control, and reports back.",
   "type": "module",
   "license": "MIT",

package/prompts/default/personas/common.md

@@ -379,6 +379,17 @@ if `report_type` is either of those.
    not from this checkout's working
    state, is deliberate: the primary checkout may have anything going on.
    `cd` into the worktree and do everything else below there.
+   **`crew worktree <number>` does all of this for you and is the preferred
+   route** — it prints the worktree's path on stdout. It cuts from
+   `<remote>/<branch>` when the branch is already pushed (another ship built
+   it, or an earlier run of yours), fresh from `<remote>/<base>` when no
+   branch exists anywhere, fast-forwards a clean stale worktree at the same
+   path, and re-cuts one whose branch is gone from the remote and which holds
+   no work of its own. It exits 1 and leaves the directory alone when that
+   worktree has uncommitted changes or commits that are not on the remote
+   (someone may be editing it by hand) — say so in a ticket comment and carry
+   on from a fresh worktree path only if a person says so. **A missing
+   worktree is never a reason to stop.**
 2. A worktree is a clean checkout, so it is missing exactly the files git
    ignores — which are usually the ones without which nothing runs. Copy the
    files the Environment section lists across from the primary checkout, then
@@ -562,11 +573,17 @@ if `report_type` is either of those.
    found, and QA never sees it. When it matches, the runner records
    `pushed <sha> to <remote>/<branch>` on the ticket itself; you still state the
    sha in your last progress comment.
-   Leave the worktree and branch exactly where they are, unmerged: QA boots
-   *your worktree* on its derived ports to test the fix, so removing it
-   would leave QA nothing to test. Your last progress comment is what QA
-   reads first — say what you changed, how you verified it, which ports and
-   database the worktree uses, and anything you could not test yourself.
+   **Your worktree is yours for this run only, and the branch on the remote is
+   what QA tests.** Leave the branch exactly where it is, unmerged, and do not
+   remove the worktree by hand: when your session ends at a verified push the
+   runner removes it (nothing on this ship's disk is needed again). The one
+   exception is a repo that declares a `handoff` hook — there the worktree is
+   kept, because a server you left running serves from it; the runner records
+   that on the ticket, and QA on another ship cuts its own worktree from the
+   remote instead. Your last progress comment is what QA reads first — say what
+   you changed, how you verified it, which ports and database you used, and
+   anything you could not test yourself. A later run, on any ship, starts from
+   `<remote>/<branch>`, so anything not committed and pushed is gone.
 
 ## Question and Investigation tickets
 

package/prompts/default/personas/lane-qa.md

@@ -56,6 +56,10 @@ human review, so "probably fine" is not a pass.
    Does the change actually do what the comment claims? Does it handle the
    empty/error/permission path, or only the happy one? Does it touch
    anything the ticket never mentioned?
+   **You never need the builder's worktree.** Cut your own from the remote
+   branch with `crew worktree <number>` (prints its path) — unless the builder's
+   hand-off event says its ship kept a worktree and a server for you, in which
+   case you may open that URL instead. Remove yours when you hand the ticket on.
    **A branch on the remote is testable.** The builder may be on another ship:
    the digest's `branch` column then reads `<name> (on origin only)` and no
    worktree exists here yet. Cut one from the remote branch —
@@ -127,7 +131,12 @@ human review, so "probably fine" is not a pass.
    write itself conditional on the `updated_at` you just read, with an
    `X-Expected-Updated-At` header; a 409 means the same thing.
 
-   - **It holds up** → `status` = `verified`, and clear `assignee_id`. That
+   - **It holds up** → `status` = `verified`, and clear `assignee_id`. When
+     the Issues table has a `verified_sha` column, set it in the same write to
+     the full sha of the branch head you tested (`git rev-parse HEAD` in the
+     worktree): for a repo that hands work to human review, the crew compares
+     the branch against it every cycle and sends the ticket back to you if a
+     reviewer's commit moves it. That
      is the merge trigger: the release phase will squash-merge the branch,
      bump the version, and deploy this cycle or the next. Say in
      the comment what you exercised, so the record shows what "verified"

package/prompts/dev-qa/personas/common.md

@@ -361,6 +361,17 @@ if `report_type` is either of those.
    not from this checkout's working
    state, is deliberate: the primary checkout may have anything going on.
    `cd` into the worktree and do everything else below there.
+   **`crew worktree <number>` does all of this for you and is the preferred
+   route** — it prints the worktree's path on stdout. It cuts from
+   `<remote>/<branch>` when the branch is already pushed (another ship built
+   it, or an earlier run of yours), fresh from `<remote>/<base>` when no
+   branch exists anywhere, fast-forwards a clean stale worktree at the same
+   path, and re-cuts one whose branch is gone from the remote and which holds
+   no work of its own. It exits 1 and leaves the directory alone when that
+   worktree has uncommitted changes or commits that are not on the remote
+   (someone may be editing it by hand) — say so in a ticket comment and carry
+   on from a fresh worktree path only if a person says so. **A missing
+   worktree is never a reason to stop.**
 2. A worktree is a clean checkout, so it is missing exactly the files git
    ignores — which are usually the ones without which nothing runs. Copy the
    files the Environment section lists across from the primary checkout, then
@@ -544,11 +555,17 @@ if `report_type` is either of those.
    found, and QA never sees it. When it matches, the runner records
    `pushed <sha> to <remote>/<branch>` on the ticket itself; you still state the
    sha in your last progress comment.
-   Leave the worktree and branch exactly where they are, unmerged: QA boots
-   *your worktree* on its derived ports to test the fix, so removing it
-   would leave QA nothing to test. Your last progress comment is what QA
-   reads first — say what you changed, how you verified it, which ports and
-   database the worktree uses, and anything you could not test yourself.
+   **Your worktree is yours for this run only, and the branch on the remote is
+   what QA tests.** Leave the branch exactly where it is, unmerged, and do not
+   remove the worktree by hand: when your session ends at a verified push the
+   runner removes it (nothing on this ship's disk is needed again). The one
+   exception is a repo that declares a `handoff` hook — there the worktree is
+   kept, because a server you left running serves from it; the runner records
+   that on the ticket, and QA on another ship cuts its own worktree from the
+   remote instead. Your last progress comment is what QA reads first — say what
+   you changed, how you verified it, which ports and database you used, and
+   anything you could not test yourself. A later run, on any ship, starts from
+   `<remote>/<branch>`, so anything not committed and pushed is gone.
 
 ## Question and Investigation tickets
 

package/prompts/dev-qa/personas/lane-qa.md

@@ -118,7 +118,12 @@ human review, so "probably fine" is not a pass.
    write itself conditional on the `updated_at` you just read, with an
    `X-Expected-Updated-At` header; a 409 means the same thing.
 
-   - **It holds up** → `status` = `verified`, and clear `assignee_id`. That
+   - **It holds up** → `status` = `verified`, and clear `assignee_id`. When
+     the Issues table has a `verified_sha` column, set it in the same write to
+     the full sha of the branch head you tested (`git rev-parse HEAD` in the
+     worktree): for a repo that hands work to human review, the crew compares
+     the branch against it every cycle and sends the ticket back to you if a
+     reviewer's commit moves it. That
      is the merge trigger: the release phase will squash-merge the branch,
      bump the version, and deploy this cycle or the next. Say in
      the comment what you exercised, so the record shows what "verified"