@tablation/crew 0.15.0 → 0.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tablation/crew",
-  "version": "0.15.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
@@ -556,11 +567,23 @@ if `report_type` is either of those.
    `in_progress` and the next `fixed` push again — a plain fast-forward, never
    `--force`; if the push is rejected, someone else moved the branch, so stop
    and say so on the ticket instead of forcing it.
-   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.
+   The runner checks this when your session ends: if the ticket is at `fixed`
+   and `<remote>/<branch>` is missing or not at your worktree's HEAD, it sets
+   the ticket back to `in_progress` (still yours) with an event saying what it
+   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.
+   **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,12 +56,23 @@ 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 —
    `git worktree add <the digest's worktree> <name>` from the ticket's repo
    checkout (git creates the local tracking branch) — and carry on. Only
    **MISSING** (gone locally and on the remote) means there is nothing to test.
+   **Name the sha you test.** Your starting comment states the
+   `<remote>/<branch>` tip you fetched. The runner records the pushed tip as an
+   event comment on the ticket, `pushed <sha> to <remote>/<branch>`; if the tip
+   you fetched differs from the latest such event, say so in that same comment
+   and verify the remote tip anyway — the remote is the only git truth, and the
+   difference is information, not a reason to refuse. If the branch is not on
+   the remote at all, bounce the ticket to `in_progress` with that reason.
 5. **Run it.** The builder left its worktree in place for you: `cd` into it,
    `nvm use` if the repository pins a version, and `eval` the **`ports`** hook
    for this worktree's own ports (anything already listening on them is a dead
@@ -120,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
@@ -538,11 +549,23 @@ if `report_type` is either of those.
    `in_progress` and the next `fixed` push again — a plain fast-forward, never
    `--force`; if the push is rejected, someone else moved the branch, so stop
    and say so on the ticket instead of forcing it.
-   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.
+   The runner checks this when your session ends: if the ticket is at `fixed`
+   and `<remote>/<branch>` is missing or not at your worktree's HEAD, it sets
+   the ticket back to `in_progress` (still yours) with an event saying what it
+   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.
+   **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

@@ -54,6 +54,13 @@ 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?
+   **Name the sha you test.** Your starting comment states the
+   `<remote>/<branch>` tip you fetched. The runner records the pushed tip as an
+   event comment on the ticket, `pushed <sha> to <remote>/<branch>`; if the tip
+   you fetched differs from the latest such event, say so in that same comment
+   and verify the remote tip anyway — the remote is the only git truth, and the
+   difference is information, not a reason to refuse. If the branch is not on
+   the remote at all, bounce the ticket to `in_progress` with that reason.
 5. **Run it.** The builder left its worktree in place for you: `cd` into it,
    `nvm use` if the repository pins a version, and `eval` the **`ports`** hook
    for this worktree's own ports (anything already listening on them is a dead
@@ -111,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"