@openthink/team 0.0.12 → 0.0.13

package/README.md

@@ -1,6 +1,6 @@
 # open-team
 
-Source-agnostic vault-driven role pipeline for spawning Claude agents against tickets. Lifts the "Assign to agent" + role-pipeline flow out of agentic-desktop's Swift code into a standalone npm CLI.
+Source-agnostic workspace-driven role pipeline for spawning Claude agents against tickets. Lifts the "Assign to agent" + role-pipeline flow out of agentic-desktop's Swift code into a standalone npm CLI.
 
 ## Install
 
@@ -42,7 +42,7 @@ Flags:
 
 ## Workspace setup
 
-`open-team` reads from a workspace directory ("vault" is Obsidian's word; oteam doesn't depend on Obsidian). Layout:
+`open-team` reads from a workspace directory (no Obsidian required). Layout:
 
 ```
 openteam/
@@ -56,7 +56,7 @@ openteam/
 
 A ticket's `state:` frontmatter must always match its containing folder under `tickets/`.
 
-For the simplest single-workspace setup, run `oteam init` (creates and registers `~/openteam/`). To use an existing tree, register it via `oteam config vault add <path>` or set `PRODUCT_VAULT_PATH`. For multiple workspaces (personal + work, etc.) see [Config & multiple vaults](#config--multiple-vaults).
+For the simplest single-workspace setup, run `oteam init` (creates and registers `~/openteam/`). To use an existing tree, register it via `oteam config workspace add <path>` or set `PRODUCT_VAULT_PATH`. For multiple workspaces (personal + work, etc.) see [Config & multiple workspaces](#config--multiple-workspaces).
 
 ## Subcommands
 
@@ -65,12 +65,11 @@ oteam pull <source> <ref>             # ingest external item → tickets/triage/
 oteam pull --project <name> ...       # tag the new ticket with a project
 oteam assign <ticket-or-id>           # drive role pipeline (full path or AGT-NNN)
 oteam assign --inline <path>          # … or run inline in current terminal
-oteam assign --no-stamp <id>          # one-shot override of stamp.enforce (clones from GitHub)
 oteam list [--state <state>]          # list active tickets
 oteam list --project <name>           # filter by project frontmatter
-oteam archive <ticket-id>             # move done ticket to archive/YYYY-MM/
-oteam config vault add <path>         # register a vault under a name
-oteam config vault list               # show registered vaults + default
+oteam archive <ticket-id>             # move done ticket to archive/YYYY-MM/ + reap workspace
+oteam config workspace add <path>     # register a workspace under a name
+oteam config workspace list           # show registered workspaces + default
 oteam config stamp set --host <url>   # configure stamp host post-init
 oteam config stamp set --enforce on   # require repos be stamp-registered
 oteam config stamp clear              # remove the stamp block
@@ -84,7 +83,7 @@ oteam telemetry summary [--days N] [--phase X] [--model Y]
 oteam telemetry tail [-n 20]          # last N telemetry lines (raw JSONL)
 ```
 
-Most commands accept `--vault <name-or-path>` to operate on a specific vault.
+Most commands accept `--workspace <name-or-path>` (or the back-compat alias `--vault`) to operate on a specific workspace.
 
 ### Tagging tickets by project
 
@@ -141,7 +140,7 @@ Where the clone comes from is governed by oteam config (`~/.open-team/config.jso
 
 | `stamp` config                                 | Mode      | Clone source                                           | Behaviour                                                                                       |
 |------------------------------------------------|-----------|--------------------------------------------------------|-------------------------------------------------------------------------------------------------|
-| absent / `null`                                | no-stamp  | `git@github.com:<repo>.git`                            | Default. No stamp config files are read. `oteam` works against any git repo.                    |
+| absent / `null`                                | plain     | `git@github.com:<repo>.git`                            | Default. No stamp config files are read. `oteam` works against any git repo.                    |
 | `{ host, enforce: false }`                     | soft      | `git@github.com:<repo>.git`                            | Stamp host is recorded for tooling that asks for it; `oteam assign` does not gate.              |
 | `{ host, enforce: true }`                      | enforce   | `<host>/srv/git/<basename>.git` (the stamp server)     | The clone IS the gate: clone failure exits non-zero before any spawn. AGT-050 behaviour.        |
 
@@ -157,11 +156,7 @@ oteam config stamp set --enforce off  # … or back off
 oteam config stamp clear              # remove the stamp block entirely
 ```
 
-`oteam assign --no-stamp` is a per-run override: it forces the github clone path even when `stamp.enforce: true` is set. The persistent setting is `oteam config stamp set --enforce off`; `--no-stamp` is convenient when you want to spawn a one-off agent without touching config.
-
-> **Migration note.** Earlier `oteam` builds read `~/.stamp/server.yml` directly. This version does not — to keep the AGT-050 stamp gate in place after upgrade, run `oteam init` and paste the host (or `oteam config stamp set --host <url> --enforce on`).
-
-Stale workspaces from prior assigns are GC'd at spawn time: any `/tmp/open-team-issues/agt-N/` directory whose ticket id has no matching ticket in the active vault is `rm -rf`'d before the new clone. The current run's workspace is also `rm -rf`'d before its clone, so re-assigns are hermetic.
+Stale workspaces from prior assigns are GC'd at spawn time: any `/tmp/open-team-issues/agt-N/` directory whose ticket id has no matching ticket in the active workspace is `rm -rf`'d before the new clone. The current run's workspace is also `rm -rf`'d before its clone, so re-assigns are hermetic.
 
 ## Per-phase model selection
 
@@ -225,33 +220,61 @@ Knobs:
 - `oteam config telemetry set off` opts out — no JSONL writes occur. Re-enable with `oteam config telemetry set on`. Default is on.
 - Telemetry is best-effort: a write failure (read-only dir, missing session file, malformed log) writes one line to stderr and does not fail the role-pipeline phase. Token fields the agent SDK doesn't expose are omitted from the line rather than recorded as zero.
 
-## Config & multiple vaults
+## Config & multiple workspaces
 
-`open-team` supports any number of named vaults via `~/.open-team/config.json`. Register them with:
+`open-team` supports any number of named workspaces via `~/.open-team/config.json`. The on-disk key is `vaults` for back-compat with earlier builds; conceptually these are workspaces. Register them with:
 
 ```sh
-oteam config vault add ~/Documents/product-vault           # auto-name "product-vault"; first add becomes default
-oteam config vault add ~/Documents/work-vault --name work
-oteam config vault list
-oteam config vault default --set work
-oteam config vault remove work                              # clears default if it pointed here
+oteam config workspace add ~/Documents/my-workspace           # auto-name "my-workspace"; first add becomes default
+oteam config workspace add ~/Documents/work-workspace --name work
+oteam config workspace list
+oteam config workspace default --set work
+oteam config workspace remove work                            # clears default if it pointed here
 ```
 
-Paths are resolved to absolute at `add` time, so the registration survives `cd`. Removing the default vault clears `default` and forces an explicit `--vault` on every subsequent command until you set a new one — there is no silent promotion.
+The `oteam config vault ...` form also works as a silent back-compat alias (`oteam config vault add` and `oteam config workspace add` register the same thing).
+
+Paths are resolved to absolute at `add` time, so the registration survives `cd`. Removing the default workspace clears `default` and forces an explicit `--workspace` on every subsequent command until you set a new one — there is no silent promotion.
 
 ### Resolution precedence (most-specific wins)
 
-| # | Source                                            | Notes                                                |
-|---|---------------------------------------------------|------------------------------------------------------|
-| 1 | `--vault <name-or-path>` flag                     | Per-command override                                 |
-| 2 | `PRODUCT_VAULT_PATH` env var                      | One-off shell override; also propagated to spawns    |
-| 3 | `default` in `~/.open-team/config.json`           | Set via `oteam config vault default --set <name>`    |
-| 4 | `~/Documents/product-vault`                       | Implicit fallback if no config exists                |
+| # | Source                                                    | Notes                                                         |
+|---|-----------------------------------------------------------|---------------------------------------------------------------|
+| 1 | `--workspace <name-or-path>` flag (or `--vault` alias)    | Per-command override                                          |
+| 2 | `PRODUCT_VAULT_PATH` env var                              | One-off shell override; also propagated to spawns             |
+| 3 | `default` in `~/.open-team/config.json`                   | Set via `oteam config workspace default --set <name>`         |
+| 4 | `~/Documents/product-vault`                               | Implicit fallback if no config exists                         |
 
 `oteam assign` adds two niceties on top:
 
-- **AGT-NNN shorthand**: `oteam assign AGT-001` walks `<vault>/tickets/<state>/` for a file whose basename starts with `AGT-001-`.
-- **Vault auto-detection from path**: passing a full path that lives inside a registered vault root makes that vault the active one for the run, even if it's not the default. The spawned `_role-run` then inherits `PRODUCT_VAULT_PATH=<that-vault>` so any follow-up `oteam pull/list/...` from the agent lands in the same vault.
+- **AGT-NNN shorthand**: `oteam assign AGT-001` walks `<workspace>/tickets/<state>/` for a file whose basename starts with `AGT-001-`.
+- **Workspace auto-detection from path**: passing a full path that lives inside a registered workspace root makes that workspace the active one for the run, even if it's not the default. The spawned `_role-run` then inherits `PRODUCT_VAULT_PATH=<that-workspace>` so any follow-up `oteam pull/list/...` from the agent lands in the same workspace.
+
+## Claim-on-assign (preventing double-pickup)
+
+When multiple operators or agents work the same workspace, two of them can race on the same ticket — both run `oteam assign` and both spin up role pipelines against the same GitHub issue. To prevent that, `oteam assign` can claim the underlying GH issue (sets `assignees`) before driving the pipeline:
+
+```sh
+oteam config bot-identity set <github-login>      # e.g. your own login, or a dedicated bot account
+oteam config bot-identity show
+oteam config bot-identity clear                   # disable claim-on-assign
+```
+
+When `botIdentity` is set, every `oteam assign` run on a github-sourced ticket does the following pre-flight before any expensive setup:
+
+1. GET the issue from `source.url`.
+2. If state is `closed` → exit 1 (refuses to drive the pipeline on resolved work).
+3. If already assigned to someone other than `botIdentity` → exit 1 (someone else has it).
+4. PATCH `assignees: [botIdentity]`. Re-read the response.
+5. If assignees came back empty, the operator's `gh` token has no push access on the repo (GitHub silently drops assignee changes without it) → exit 1 with a hint.
+6. If assignees != `[botIdentity]` (race with another writer) → exit 1.
+7. Otherwise the claim is held; proceed.
+
+When `botIdentity` is empty (the default), the pre-flight is skipped — backwards-compatible with configs that predate the field.
+
+Per-invocation override: `OTEAM_BOT_IDENTITY=<login> oteam assign …`. Useful when one operator runs occasionally under a different identity (e.g. testing with a personal account) without rewriting the persisted config.
+
+Manual tickets (`source.type: manual`) and tickets with no parseable GH URL skip the claim entirely — there's nothing to claim.
 
 ## Migration from agentic-desktop
 
@@ -260,7 +283,7 @@ agentic-desktop now keeps only the PR-side modules (`GitHubPRs`, `AIReview*`, `C
 Migration steps:
 
 1. `npm install -g @openthink/team` (or `npm link` from a local clone).
-2. Either set `PRODUCT_VAULT_PATH` if your vault isn't at `~/Documents/product-vault`, or register it via `oteam config vault add <path>` (see [Config & multiple vaults](#config--multiple-vaults)).
+2. Either set `PRODUCT_VAULT_PATH` if your workspace isn't at `~/Documents/product-vault`, or register it via `oteam config workspace add <path>` (see [Config & multiple workspaces](#config--multiple-workspaces)).
 3. Optionally set `OTEAM_MONITORED_ORGS=Org1,Org2` to route those repos' tickets to the "work" kitty socket (preserves the personal/work split agentic-desktop had).
 4. Delete `~/Library/Application Support/AgenticDesktop/vault-assignments.json` (panel-indicator state, no longer used).
 5. Use `oteam pull github <ref>` instead of clicking "Assign to agent" on the Issues panel.

package/dist/assign-ticket.md

@@ -13,7 +13,7 @@ You are working a `product-vault` ticket. The user invoked `oteam assign <path>`
 3. **No commits, no PRs, no Linear.** Vault tickets do not necessarily map to a code repo. Only act on code if the ticket's `repo:` field is set AND the work demands it.
 4. **STOP at every role-handoff boundary.** When your role is done, write a STOP marker (visual banner per Output discipline below) and let the human decide whether to continue.
 5. **3-attempt cap on any failing operation.** If a step fails (e.g., file mv fails, frontmatter parse fails, build/test fails), you get 3 tries before STOPPing.
-6. **Never read or write inside `$HOME/Development/<repo>`.** That tree may have uncommitted in-flight work; entangling with it is a sterile-field violation. For repo-bound tickets, the `oteam` runner has already prepared an isolated agent worktree at `/tmp/open-team-issues/<ticket-id-lowercased>/repo` and spawned you cd'd into it — that's your only valid working directory. The runner clones from the stamp server when `stamp.enforce: true` is set in `~/.open-team/config.json`, otherwise from GitHub directly; either way, the worktree is isolated from your primary, so AC-shaped requirements like "primary's `git remote -v` is byte-equal before/after a spawn" are satisfied by construction. If your `$PWD` is not the prepared workspace (e.g. you invoked the slash command by hand outside of `oteam assign`), set up the workspace yourself before reading any repo file — see Phase 3 Step 0.
+6. **Never read or write inside `$HOME/Development/<repo>`.** That tree may have uncommitted in-flight work; entangling with it is a sterile-field violation. For repo-bound tickets, the `oteam` runner has already prepared an isolated agent worktree at `/tmp/open-team-issues/<ticket-id-lowercased>/repo` and spawned you cd'd into it — that's your only valid working directory. The runner clones from the URI recorded for the repo in `~/.open-team/config.json` and sets your cwd to it; the worktree is isolated from your primary, so AC-shaped requirements like "primary's `git remote -v` is byte-equal before/after a spawn" are satisfied by construction. If your `$PWD` is not the prepared workspace (e.g. you invoked the slash command by hand outside of `oteam assign`), set up the workspace yourself before reading any repo file — see Phase 3 Step 0.
 
 ## Phase 0 — Read the ticket
 
@@ -65,9 +65,9 @@ If your appended system context flags the **AGT-107 haiku-downshift heuristic**
 
 ## Phase 3 — Engineering agent (state: refined → spike phase)
 
-**Step 0 — Workspace is already prepared.** When `oteam assign` spawned you against a repo-bound ticket, it already cloned `/tmp/open-team-issues/<ticket-id-lowercased>/repo` (from the stamp server when `stamp.enforce: true` is set in `~/.open-team/config.json`; from GitHub otherwise, or when `--no-stamp` was passed) and set your cwd to it. Confirm with `pwd` and `git remote -v`; for stamp-governed repos you should see exactly one remote, `origin`, pointing at `ssh://git@<stamp-host>:<port>/srv/git/<basename>.git`.
+**Step 0 — Workspace is already prepared.** When `oteam assign` spawned you against a repo-bound ticket, it already cloned `/tmp/open-team-issues/<ticket-id-lowercased>/repo` from the URI recorded for the repo in `~/.open-team/config.json` and set your cwd to it. Confirm with `pwd` and `git remote -v`; you should see exactly one remote, `origin`, pointing at the URI recorded for this repo.
 
-Cost trade: a fresh stamp clone adds a few seconds vs. the older `git worktree add` fast path. That's an intentional trade for AC-grade isolation — the agent worktree shares no `.git/objects` and no remotes with your primary, and removing or renaming any remote inside the worktree cannot leak back to your daily flow.
+Cost trade: a fresh clone per assign adds a few seconds vs. the older `git worktree add` fast path. That's an intentional trade for AC-grade isolation — the agent worktree shares no `.git/objects` and no remotes with your primary, and removing or renaming any remote inside the worktree cannot leak back to your daily flow.
 
 If you invoked `/assign-ticket` by hand (no `oteam assign` wrapper) and the workspace doesn't exist yet, set it up the same way the runner would:
 
@@ -77,19 +77,19 @@ WORKSPACE="/tmp/open-team-issues/$TICKET_ID_LC"
 # REPO_SLUG is "<owner>/<name>" from `repo:` if set, else inferred from the
 # ticket. When inferring, name it explicitly in your spike notes so the human
 # can correct you.
-REPO_BASE=$(basename "$REPO_SLUG")
 mkdir -p "$WORKSPACE"
 cd "$WORKSPACE"
 rm -rf repo
-SERVER_HOST=$(awk '/^host:/ { print $2 }' "$HOME/.stamp/server.yml" 2>/dev/null)
-SERVER_PORT=$(awk '/^port:/ { print $2 }' "$HOME/.stamp/server.yml" 2>/dev/null)
-if [ -n "$SERVER_HOST" ] && [ -n "$SERVER_PORT" ] && \
-   git clone "ssh://git@${SERVER_HOST}:${SERVER_PORT}/srv/git/${REPO_BASE}.git" repo 2>/dev/null; then
-    : # cloned from stamp; origin points at the stamp URL
-else
-    # No stamp config or repo not on stamp server — fall back to GitHub.
-    git clone "git@github.com:${REPO_SLUG}.git" repo
+# Look up the recorded clone URI. `oteam config repo show` prints two lines
+# (clone-uri: ..., added: ...) on success, or "(no entry for ...)" on miss.
+CLONE_URI=$(oteam config repo show "$REPO_SLUG" 2>/dev/null | awk '/^clone-uri:/ { print $2 }')
+if [ -z "$CLONE_URI" ]; then
+    # No recorded URI yet — fall back to the GitHub HTTPS default. Running
+    # `oteam assign` interactively will prompt once and record it; hand-running
+    # this slash command skips the prompt and uses the public default.
+    CLONE_URI="git@github.com:${REPO_SLUG}.git"
 fi
+git clone -- "$CLONE_URI" repo
 cd repo
 ```
 
@@ -175,8 +175,8 @@ Read `CLAUDE.md`, `AGENTS.md`, `README.md` at the repo root if present.
 
 **2. Verify the worktree shape and compute the merge mode.** Run `git remote -v` and check whether `.stamp/` exists in the worktree. Three shapes are valid:
 
-- **Stamp-governed (default).** Exactly one remote, `origin`, pointing at `ssh://git@<stamp-host>:<port>/srv/git/<basename>.git`. The runner clones with that shape on purpose; no rename / re-add is required, and adding a `github` remote here would defeat the AGT-050 invariant. `MODE` will resolve to `stamp` and routing goes through the stamp-protected branch (5a) at the end of Step 5.
-- **Local-stamp.** `origin` points at `git@github.com:<owner>/<repo>.git` AND the worktree contains a `.stamp/` directory. The repo carries stamp config but no stamp server is in use (typically a `--no-stamp` run against a stamp-aware repo). `MODE` will resolve to `local-stamp` and routing goes through 5c — `stamp review` + `stamp merge` produce a signed merge commit locally, which is then pushed to GitHub as the PR head for human review. `stamp push` is intentionally not invoked (no stamp server); `stamp verify <merge-sha>` still works against the PR head from any clone with the trusted public keys.
+- **Stamp-governed.** Exactly one remote, `origin`, pointing at a non-GitHub URI (the stamp server). `MODE` will resolve to `stamp` and routing goes through the stamp-protected branch (5a) at the end of Step 5.
+- **Local-stamp.** `origin` points at `git@github.com:<owner>/<repo>.git` AND the worktree contains a `.stamp/` directory. The repo carries stamp config but `origin` is GitHub, not a stamp server. `MODE` will resolve to `local-stamp` and routing goes through 5c — `stamp review` + `stamp merge` produce a signed merge commit locally, which is then pushed to GitHub as the PR head for human review. `stamp push` is intentionally not invoked (no stamp server); `stamp verify <merge-sha>` still works against the PR head from any clone with the trusted public keys.
 - **Plain GitHub.** `origin` points at `git@github.com:<owner>/<repo>.git` and there is no `.stamp/` directory. `MODE` will resolve to `plain` and routing goes through 5b — `git push origin <feature>` + `gh pr create`.
 
 Compute `MODE` once, here, from the worktree's actual state — every subsequent step branches on this single variable:
@@ -241,13 +241,9 @@ When tests pass:
 ```sh
 git add -A
 COMMIT_BODY="Refs <ticket-id>"
-# GitHub-bound paths (plain, local-stamp): append a `Fixes <gh-issue-url>`
-# trailer so the eventual PR merge auto-closes the GH issue. The
-# stamp-governed path skips this trailer — those worktrees have no github
-# remote, the merge gets pushed to the stamp server, and GH never sees a
-# commit that would trigger auto-close. QA Phase 5 closes the GH issue
-# explicitly via `gh issue close`, so behaviour is preserved either way.
-if [ "<source.type>" = "github" ] && [ "$MODE" != "stamp" ]; then
+# When the source is a GitHub issue, append a `Fixes <gh-issue-url>` trailer
+# so the PR merge (or stamp push that mirrors to GitHub) auto-closes the issue.
+if [ "<source.type>" = "github" ]; then
     COMMIT_BODY="$COMMIT_BODY"$'\n'"Fixes <linked-github URL>"
 fi
 git commit -m "<one-line summary>
@@ -260,6 +256,14 @@ Never use `--no-verify`. Fix hook failures at the root cause.
 
 **5. Route by `$MODE`** (set in Step 2): `stamp` → 5a, `plain` → 5b, `local-stamp` → 5c.
 
+**Push gate (AGT-099).** If your appended system context includes a `# Push step: disabled by oteam config` block, the operator has set `push: off` in `~/.open-team/config.json`. Run every step in 5a/5b/5c up to (but not including) the outbound push command, then print:
+
+```
+push disabled by oteam config; merge commit is local at <sha>; run 'git push origin' manually when ready
+```
+
+substituting `<sha>` with `git rev-parse HEAD` after the merge (5a/5c) or after the last feature commit (5b). In 5b/5c, also skip `gh pr create` and leave `linked-pr:` empty — there is no pushed branch for the PR to reference. Note the held push in the wrap-up comment. Step 6 (stamp retro routing) still runs because it does not depend on the push.
+
 #### 5a — Stamp-protected repo
 
 Run review and merge. Capture the review's combined output (stdout + stderr) to a known tempfile so Step 6 can route any `STAMP-RETRO` candidates the reviewers emit. Re-run the entire `tee` block on every round of the 5-round iteration — `$STAMP_REVIEW_OUT` is reassigned to a fresh `mktemp` each round, so Step 6 reads only the last (gate-opening) run; prior tempfiles are left behind for the OS to reap.