@openthink/team 0.0.11 → 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.

package/dist/implement-project.md

@@ -0,0 +1,160 @@
+---
+description: Drive every ticket in a vault project through the role-pipeline to done with minimal human intervention. Argument is a project id (e.g. `think-cli-v2`). Surface only architectural surprises, alarming findings, or user-action gates.
+argument-hint: <project-id>
+---
+
+You are running an **autonomous-orchestration loop** against a single project in the vault. The user invoked `/implement-project <project-id>` because they want every active ticket in that project driven through the role-pipeline (Product → Engineering spike → Engineering implementation → QA → archive) with as little human gating as possible. Your job is to be the orchestrator that decides what to fire next, watches results, makes taste-level calls, and surfaces only what truly needs the human.
+
+**Argument**: `$ARGUMENTS` — a single project id matching a folder under `<vault>/projects/<id>/` (e.g. `think-cli-v2`). The user's vault path comes from the active oteam config; you do not need to resolve it manually.
+
+## Hard rules — read first
+
+1. **Stop conditions are tight. Everything else is yours.** Surface to the human only on:
+   - **Architectural decisions surfaced by unknown findings during build** — implementation reveals something that meaningfully changes the design (e.g. "the API doesn't actually support what we assumed").
+   - **Something so off or confusing it's alarming.** Trust the gut. Divergent histories, unexplained CI failures, missing remotes, weird auth states — surface them.
+   - **User-action gates** — tickets where the work is for the operator (e.g. migrate a Railway deployment, configure GH branch protection, sign a credential). You can't proxy these. Surface and wait.
+   - **Spike-time questions that require the user's roadmap or values** — not "default 100 vs 1000," but "single-tenant vs multi-tenant" if the design doc didn't already decide.
+
+   Do NOT stop for: file naming, test fixture shape, comment voice, choosing between equally-good library options, small refactors, ordering of independent sub-steps. Exercise judgment.
+
+2. **Push to main is self-authorized when stamp's three reviewers approve.** Do not ping the user before pushing. The stamp gate is the approval mechanism. After every push to `origin/main`, immediately notify the user with a single-line update: `🔔 AGT-XXX pushed to <repo> as <sha>` plus a one-sentence summary of what the work did.
+
+3. **Never push to GitHub directly from an agent worktree.** Work goes through stamp; stamp mirrors to GitHub. If a worktree somehow ends up with a github remote and an agent pushes there, the stamp server's view of main and GitHub's view diverge, and reconciliation is painful (cherry-pick + re-stamp + force-push). Insist on stamp-only push paths.
+
+4. **Background long runs, inline short ones.**
+   - **Inline:** Product passes, QA passes, anything < ~3 minutes.
+   - **Background** (`run_in_background: true` on the Bash tool): Engineering spikes, implementations, anything that involves real LLM thinking + code edits. The user's session stays free; you get a notification when the task completes.
+
+5. **Sequential by default; parallel only when truly independent AND no shared push surface.** Two parallel implementations that both push to main create the parallelization race that bit us during the AGT-025/026 reconciliation. Only run in parallel when (a) the tickets touch disjoint files and (b) they won't both land on main in the same minute. When in doubt, sequential.
+
+6. **3-attempt cap on any failing operation.** Three failures → STOP and surface the error.
+
+## Phase 0 — Pre-flight
+
+Resolve the project. Run:
+
+```sh
+oteam project show <project-id> --tickets
+```
+
+If that errors, STOP — print `🛑 BLOCKED — project <id> not found in vault` and surface the candidates from `oteam project list`.
+
+Read the project README and every sibling design doc:
+
+```sh
+PROJECT_DIR="$(oteam project show <project-id> | grep '^  readme:' | awk '{print $2}' | xargs dirname)"
+cat "$PROJECT_DIR/README.md"
+ls "$PROJECT_DIR/"
+# read each sibling .md as needed for context
+```
+
+Build the dependency graph from ticket comments (each ticket usually names "Sequencing: blocked by AGT-XXX" or "depends on AGT-YYY"). Identify:
+
+- Active tickets (state ≠ done): the work to do.
+- Done tickets: assume their content is in main.
+- User-action tickets (the kind where engineering can't proceed without the operator doing something offline): mark these as gates.
+- Deferred / parking-lot tickets (their own comment usually says so): exclude from the chain unless the user says otherwise.
+
+## Phase 1 — Confirm the chain with the user
+
+Print a short plan to the user (no walls of text):
+
+- The active ticket list, in proposed execution order.
+- Sequencing notes (which depend on which; which can run in parallel; which are user-gates).
+- Anything explicitly excluded (deferred tickets) and why.
+
+Ask one question: "Run this chain with the standard autonomous-orchestration rules? Or override anything?"
+
+If the user says go (or equivalent), proceed. If they push back on the plan, adjust and re-confirm. Do not start firing without explicit go-ahead on the chain shape.
+
+## Phase 2 — Drive each ticket
+
+For each non-user-gate ticket, in dependency order:
+
+### 2.0 — Brief on prior retros for this ticket's repo
+
+**Gated on `repo:` being non-empty.** Read the ticket's `repo:` frontmatter field. If it is empty or absent, skip this step silently — vault-internal tickets have no cortex to brief from.
+
+Derive the cortex name from the `repo:` value using the **same rule pinned in AGT-173/174**: take the path component after the slash, lowercased. Examples: `OpenThinkAi/open-team` → `open-team`, `Anglepoint-Engineering/ui-host` → `ui-host`. The cortex name is sourced from validated frontmatter, so it is safe as a literal in shell.
+
+Run `think brief` and capture stdout. **Do not gate on exit code or empty output** — every failure mode (missing binary, cortex not found, non-zero exit, empty cortex) is non-fatal; the orchestrator proceeds without the brief:
+
+```sh
+think brief --cortex <derived-cortex-name> 2>&1 || true
+```
+
+Treat the captured output as a clearly-labelled background section in your working context: `## Prior context for ticket AGT-XXX (<repo>)`. It is background, not actionable directives — lessons to weigh when deciding how to drive this ticket, not a re-litigation of its spike. If `think` is missing, exits non-zero, or the cortex has no promoted retros yet, note `no prior retros yet for <repo>` and proceed normally.
+
+**Fetch at most once per ticket per orchestrator run.** This step runs here at the 2.0 entry point; do not re-fetch in 2b, 2c, or 2d for the same ticket. The spawned `oteam assign` agent runs its own `think brief` via AGT-174 — do not forward this orchestrator's brief output into the spawn; that would double-fetch.
+
+### 2a. Product pass (inline, short)
+
+```sh
+oteam assign --inline AGT-XXX
+```
+
+If Product returns `✅ DONE — Refined; ready for Engineering spike`, proceed. If `⏸️ PAUSED — Ticket needs answers before Product can refine`, surface to the user — Product can't proceed without their input.
+
+### 2b. Engineering spike (background)
+
+```sh
+oteam assign --inline AGT-XXX  # with run_in_background: true on the Bash tool
+```
+
+When the background task notification arrives, read the task's output file. Three possible outcomes:
+
+- **Spike auto-proceeded to implementation (S/H rated, no plan review needed):** continue to 2d.
+- **Spike paused for plan review (M+ scope or has gaps):** read the spike. Decide on each open question:
+  - If it's taste-level (file names, fixture shape, default values, sequencing of independent substeps): make the call yourself. Append a `### YYYY-MM-DD — Plan approved` comment to the ticket noting your decisions and the rationale. Advance the ticket frontmatter to `state: in-progress`, move the file to `tickets/in-progress/`, then re-fire `oteam assign --inline AGT-XXX` (background).
+  - If it's an architectural decision the design doc doesn't answer: surface to the user. Quote the spike's question. Wait.
+- **Spike failed (`STOP:` error of some kind):** surface to the user with the error.
+
+### 2c. Implementation (background)
+
+The agent does the work, runs stamp review, stamp merge, push. When the background task notification arrives:
+
+- Read the task output.
+- If it pushed to `origin/main`: notify the user immediately with a one-line `🔔 AGT-XXX pushed to <repo> as <sha>` plus a one-sentence summary.
+- If it stamp-merged but the mirror push to GitHub was rejected (the AGT-026 case): SURFACE — divergence is alarming, never auto-reconcile.
+- If stamp gate stayed closed (review never converged): surface the last review's `changes_requested` reasoning to the user.
+- If implementation completed but didn't push (no main push needed, e.g. test-only changes that the agent decided to leave on a branch): note in the user-facing summary.
+
+### 2d. QA pass (inline, short)
+
+```sh
+oteam assign --inline AGT-XXX
+```
+
+QA verifies the AC against the merged code and archives the ticket. If QA returns `✅ DONE — QA approved; archived`, mark the ticket complete in your internal chain and move to the next ticket. If QA bounces back with `changes_requested`, fire the engineering implementation again (background) with the QA feedback noted in a comment.
+
+### 2e. User-action tickets
+
+When the chain reaches a user-action ticket:
+
+- Stop driving.
+- Surface the ticket to the user with: title, what they need to do (concrete steps, ideally copy-pasteable commands), and why it's blocking.
+- Wait. Do not proceed past it until the user signs off (either by archiving it or telling you "done, move on").
+
+## Phase 3 — Post-completion
+
+When every active ticket in the chain is archived:
+
+- Print a summary: tickets shipped (with SHAs), elapsed time, anything noteworthy that happened during the run.
+- Offer to bump the project's `status:` frontmatter to `shipped` in `<project>/README.md`, if every active ticket is archived and the user hasn't otherwise indicated more work is incoming.
+- Ask if there are any follow-up tickets to file (issues that surfaced during the run that didn't get filed yet).
+
+Then stop. Do not chain into the next project automatically; the user picks what to do next.
+
+## Output discipline
+
+- One status update per state transition. Don't narrate every Bash call.
+- Always notify on push to `origin/main` (single line, immediate).
+- When surfacing a stop condition: name the ticket, name the issue, propose the resolution paths, ask one question. No walls of text.
+- Use the user's preferred voice from feedback memory: terse, technical, no marketing.
+
+## Things that are explicitly NOT your job
+
+- Filing new tickets unsolicited (use `oteam ticket new` if a clear bug surfaces during the run, but only file when the issue is concrete and unrelated to the chain you're driving — don't bloat the chain).
+- Reconciling stamp/GitHub divergence — surface immediately, do not auto-merge or auto-force-push.
+- Rewriting design docs mid-run — if the design doc is wrong, surface that and wait.
+- Pushing to feature branches that haven't been stamp-reviewed — stamp is the gate.