@workerstack/repo 0.0.0-stage → 0.1.0

package/references/cloudflare.md

@@ -0,0 +1,36 @@
+---
+tags: [cloudflare]
+---
+
+# Cloudflare
+
+Use `cf` for every Cloudflare task. Do not run `wrangler` yourself and do not add it to a project that has none.
+
+## Find the command
+
+```
+cf cli search "<describe the task>"
+<command from the result> --help
+cf schema <command from the result, without the leading cf>
+```
+
+`cf cli search` returns five matches. Pick one instead of repeating the search. Write the query as the action and resource type only: no names, domains, emails, account or resource IDs, or tokens. `cf schema` shows the API request detail for a command.
+
+## Project commands
+
+- `cf dev` runs the dev server (`--local` uses local resource simulations).
+- `cf deploy` deploys (`--dry-run` builds and checks without uploading).
+- `cf build` builds the project.
+- `cf workers types` generates types from `cloudflare.config.ts`.
+- `cf init workers [directory]` creates or sets up a Workers project.
+- `cf auth` manages login and profiles; `--profile <name>` picks one on any command.
+
+`cf dev` and `cf deploy` run the dev server the project declares in `package.json`: `@cloudflare/vite-plugin` (recommended), or `wrangler` for a legacy Worker project that keeps `wrangler.jsonc`. With none declared they print the install choices and stop. Ask before adding a dependency.
+
+## Docs
+
+Product docs: https://developers.cloudflare.com/ . Machine-readable index: https://developers.cloudflare.com/llms.txt .
+
+## Status
+
+`cf` is in beta, so commands and config can still change. Wrangler is not deprecated yet; Cloudflare plans to maintain it for 18 months after the `cf` beta ends.

package/references/google-workspace.md

@@ -0,0 +1,79 @@
+---
+tags: [google-workspace]
+---
+
+# google-workspace
+
+Create and edit Google Sheets, Docs, Slides, Calendar events, and Gmail from the session.
+
+```
+bun repo google-workspace whoami
+bun repo google-workspace scopes
+bun repo google-workspace login
+bun repo google-workspace sheet create --title "Q3" --csv "item,qty\nA,2"
+bun repo google-workspace sheet set --id ID --cell A1 --value x
+bun repo google-workspace sheet get --id ID --range A1:B10
+bun repo google-workspace sheet append --id ID --csv "c,3"
+bun repo google-workspace sheet clear --id ID --range A1:Z
+bun repo google-workspace doc create --title "Notes" --body "hello"
+bun repo google-workspace doc append --id ID --body "more"
+bun repo google-workspace drive list --query "mimeType='application/vnd.google-apps.spreadsheet'"
+bun repo google-workspace slide create --title "Deck"
+bun repo google-workspace meeting create --title "Standup" --start 2026-09-15T09:00:00Z --end 2026-09-15T09:15:00Z --attendees a@x.com,b@y.com
+bun repo google-workspace mail send --to you@example.com --subject hi --body hello
+bun repo google-workspace mail list
+```
+
+Each person has their own Google Cloud app. Creds stay in `~/.workerstack/` on that machine. Do not share OAuth JSON or tokens. Do not commit them. Inviting others to a meeting is attendee emails, not shared creds.
+
+Handheld (any OS): `bun repo setup google-workspace` or `bun repo setup` → google-workspace. Opens each Cloud Console page, waits, copies the Desktop JSON into `~/.workerstack/workspace/default/google-oauth.json`, then browser Allow. Non-TTY: `--creds PATH` to a Desktop download. `--account NAME` for a second Google user.
+
+Doctor reports google-workspace as optional: `ok` when Desktop OAuth JSON, tokens, gcloud ADC, or `~/.clasprc.json` exists, else `missing (optional)`. It prints source names (`oauth` `tokens` `adc` `clasprc`), not secrets. `clasprc` is Drive-only.
+
+Two Google accounts on one machine: `--account NAME` (or `WORKSPACE_ACCOUNT`). Each account, `default` included, uses `~/.workerstack/workspace/NAME/`.
+
+```
+bun repo google-workspace --account work login
+bun repo google-workspace --account work whoami
+bun repo google-workspace accounts
+```
+
+Each account needs its own Desktop JSON in that folder (`google-oauth.json`) and its own `login`.
+
+Clasp’s public OAuth client is Drive-only. Calendar and Gmail are restricted; Google blocks extra scopes on that app. Use **your** Desktop OAuth client.
+
+## Agent: setup e2e
+
+If `whoami` works but `meeting` / `mail` / `sheet set` fail with missing scope or “app is blocked”, run **this user** through `bun repo setup google-workspace` (TTY). Do not reuse another person’s JSON. Do not invent a client JSON.
+
+Local dir is created by setup (`~/.workerstack/`, mode 700 on Unix). Manual equivalent: `mkdir -p "$HOME/.workerstack" && chmod 700 "$HOME/.workerstack"` then:
+
+1. Open `https://console.cloud.google.com/projectcreate` — **Create**. Org can be their Workspace org. Note **Project ID** from the dashboard URL (`?project=`).
+2. Open `https://console.cloud.google.com/auth/overview/create?project=PROJECT_ID` (or **Google Auth Platform → Branding**).
+   - App name: anything (`autorun` is fine). That string is only the Allow screen.
+   - User support email: their address.
+   - Audience: **Internal** if the Google account is a paid Workspace org (e.g. `@rearm.co`). **Testing** + add their own address as a test user if it is a personal `@gmail.com` (Internal is not offered). APIs work on both; only this consent type changes.
+   - Next / Create through the wizard.
+3. Open `https://console.cloud.google.com/flows/enableapi?apiid=calendar-json.googleapis.com,gmail.googleapis.com,sheets.googleapis.com,docs.googleapis.com,drive.googleapis.com&project=PROJECT_ID` — **Enable**.
+4. Open `https://console.cloud.google.com/auth/clients/create?project=PROJECT_ID`.
+   - Application type: **Desktop app**.
+   - Create → **Download JSON**.
+5. Copy the download to `$HOME/.workerstack/workspace/default/google-oauth.json` (Windows: `%USERPROFILE%\.workerstack\workspace\default\google-oauth.json`). chmod 600 on Unix. Confirm it has `"installed"` and `client_id`. For `--account NAME`, use `$HOME/.workerstack/workspace/NAME/google-oauth.json`.
+6. From the repo: `bun repo google-workspace login` (or `--account NAME`) — browser Allow. Tokens write beside the JSON (`workspace/NAME/tokens.json`).
+7. Smoke:
+
+```
+bun repo google-workspace whoami
+bun repo google-workspace scopes
+bun repo google-workspace sheet create --title smoke-sheet --csv "k,v\nok,1"
+bun repo google-workspace doc create --title smoke-doc --body ok
+bun repo google-workspace slide create --title smoke-slide
+bun repo google-workspace meeting create --title smoke-meeting --start 2026-09-16T09:00:00Z --end 2026-09-16T09:15:00Z
+bun repo google-workspace mail send --to THEIR_EMAIL --subject smoke --body ok
+```
+
+`scopes` must include `calendar`, `gmail.modify` or `gmail.send`, `spreadsheets`, `documents`, `drive`. If login times out, they did not finish Allow; re-run `login`.
+
+If `google-oauth.json` is missing, `login` prints `setup: bun repo setup google-workspace`. Prefer the handheld setup (it opens the Project ID URLs). Manual steps above still work.
+
+`gcloud` on PATH is an alternate login (`gcloud auth application-default login` with the extra scopes). Still per person, still local.

package/references/hooks.md

@@ -0,0 +1,103 @@
+---
+tags: [hooks]
+---
+
+# Hooks
+
+SessionStart carries only the folder map: Claude / Codex run the `session-map` hook, which injects the code-only map `bun repo map` prints as `additionalContext` (capped under Claude Code's 10,000-char per-hook `additionalContext` limit, about 2.4k tokens, below the 5k `bun repo map` budget; cache-stable, fail-open) and logs `{rows, tokens}` to `.tmp/repo/sessions/<sid>/map.json`. Inject nothing else at SessionStart. Antigravity has no generated sessionStart. Do not register a SessionStart hook on `.grok/hooks/orchestrate-parent.json`.
+
+Grok PostToolUse / SessionStart are observe-only — do not attempt output scrub; compress via RTK / spawn / isolation facts only. Do not add PostToolUse scrub hooks. UserPromptSubmit may emit a one-line `sessionGate=ask|auto|away` plus session receipt, then up to 8 other live lines from `~/.workerstack/board/` (`hookSpecificOutput.additionalContext`). The current session's own line is omitted. Skip host Stop banners. `/ask` and `/away` exact-match slashes stamp `session-gate-{sid}` to `ask` or `away`. `/auto` unlinks. Sid-less: no stamp. Default: `auto`. The `sessionGate=` word is the effective mode: the newest `in-progress` plan or roadmap in this session's `.tmp/repo/sessions/<sid>/approvals.txt` with a valid `mode:` wins, else the stamp, else `auto`. Another session's plans never count.
+
+In `sessionGate=ask`, parent Stop on `end_turn` blocks unless the recap asks (`?`) or is exactly `[orchestrator]: wait scout`. Reason: `ask after this step`. In `sessionGate=away`, parent Stop blocks a reply whose last line ends in `?` and is not a closing line. Reason: `away: do not ask; decide, log "- decision: {question} → {choice}, because {why}" in the plan, and continue`. Both blocks share the `stop-block` counter, cap 3, so a true blocker still reaches the person. `sessionGate=auto` does not Stop-block.
+
+Claude / Codex / Antigravity / Cursor PreToolUse still run the `scrub-spawn-prompt` and `gate-fat-tools` hooks. Grok spawn/fat rewrite is the `orchestrate-parent` hook. RTK stays `.grok/hooks/rtk.json`, which runs the `rtk-grok` hook.
+Every repo hook command finds the root (`$GROK_WORKSPACE_ROOT`, else `$CLAUDE_PROJECT_DIR`, else its git top level) and runs `<root>/node_modules/.bin/repo hook <name>`. A checkout with no install prints `repo: <root>/node_modules/.bin/repo is missing; run bun install` and exits 1, which never blocks the tool call. `bun repo sync --check` fails any repo hook in another form.
+Claude Code's `WorktreeCreate` and `WorktreeRemove` come from the `claudecode` block of `hooks.jsonc` and run the `worktree` hook (60s), so its worktrees land in `.worktrees/<name>` on `wt/<name>`. Other harnesses have no such event and call `bun repo worktree add` directly.
+
+## Cursor
+
+`cursor-agent` reads `.cursor/hooks.json` (JSONC, `version: 1`, camelCase events `preToolUse` `beforeSubmitPrompt` `stop` `sessionStart`, flat `{command, timeout, matcher}` entries). `bun repo sync` writes it (`cli/sync/agents/hooks.ts`) from `hooks.jsonc` with the matchers untranslated, so the gate and orchestrate-parent matchers name Cursor's tools (`Shell`, `Read`, `Write`, `Grep`) beside the others. `hooks-union.ts` appends a consumer's autorun scripts to it as flat entries (`Write` is Cursor's write matcher). Cursor also reads `.claude/settings.json` hooks and drops a command it already has in its own file, so nothing runs twice. Cursor refuses a hook file with a symlink on its path: keep `.cursor/` a real dir. It reads `AGENTS.md`, so there is no `.cursor/rules`. `bun repo sync` generates `.cursor` in each consumer (gitignored there); it is not in the package `files`.
+
+Payload: `cursor_version`, `session_id`, `model`, `tool_name`, `tool_input`, `cwd`; no `turn_id`, no `subagent_type` (every Cursor call counts as the parent). `gate-fat-tools.ts` `harnessOf` tests a string `cursor_version` first, because `session_id` and `model` also match the Codex check. Tools the gate answers:
+
+| Tool | Input | Gate |
+| --- | --- | --- |
+| `Shell` | `command`, `cwd` | denylist, `.gitignore`, `git worktree add` and main-checkout git guards; dump, search, `curl` and `ls` rewrites |
+| `Read` | `file_path` | denylist, 200KB deny, re-read deny |
+| `Grep` | `pattern`, `file_path`, `glob` | denylist |
+| `Write` | `file_path`, `content` | main-checkout deny, scratch redirect to the root `.tmp/repo`, `.gitignore` guard; orchestrate-parent persists plans and the like |
+
+`Read` takes no offset or limit and `Grep` no `head_limit`, so the gate injects and caps neither (`limits: false` in `TOOLS.cursor`). A re-read of a file this session wrote therefore cannot say "Read with offset+limit": Cursor's reason names `bun repo job --job exec --query 'sed -n 1,200p <file>'`. `List` and `Delete` get no answer.
+
+Reply: a deny is `{"permission":"deny","user_message":reason,"agent_message":reason}`. A rewrite is Claude's nested `{"hookSpecificOutput":{"hookEventName":"PreToolUse","updatedInput":{...}}}` with no `permission` and no top-level field (Cursor reads the nested form only then; `permission` would also auto-approve). Cursor applies a rewritten `command` (Shell) and `file_path` (Write), but writes its own `content`: a persisted tmp write lands at the `.tmp/repo/` path with its `TMP_NAME:` line still in the body. Empty stdout with exit 0 allows. Invalid JSON on stdout blocks the call. `stop` may reply `{"decision":"block","reason":...}`. orchestrate-parent handles Cursor's `beforeSubmitPrompt` only to write `git-asked.json` (see Worktrees); there it stamps no `/ask` or `/away`, handles no `y` or `h`, prints no board line and adds no context.
+
+Session agent tools are on. Fat Read/Grep/Glob/Bash still gate. Writes under `.tmp/repo/plans/`, `.tmp/repo/handoffs/`, `.tmp/repo/implementations/`, `.tmp/repo/roadmaps/`, and `.tmp/repo/` root files persist via `cli/scripts/persist-plan.ts` / `persist-handoff.ts` / `persist-implementation.ts` / `persist-tmp.ts` / `persist-roadmap.ts`. The hook hands the host the absolute path of the saved file. Invalid body denies. A Write of a saved plan updates that file in place (same serial); an Edit of a saved plan is checked against the text it would produce, and a valid one runs as sent. `## Previous mistakes` entries are append-only on both. Roadmaps follow the same rules: a Write of a saved roadmap is validated and the host writes it, and an Edit is checked against the text it would produce.
+
+Writes under `.repo/lessons/` go through `bun repo lessons`: a lesson Write in a managed worktree is validated, saved, and reindexed (`INDEX.md`) there, and the same Write in the main checkout is denied with the Worktrees reason; an Edit of a lesson is denied with the Write and `lessons.ts hit` routes. Lessons match per holding checkout: the root, or the managed worktree that holds the file; an unmanaged linked worktree falls back to the caller's checkout. On any other Write or Edit, PreToolUse adds `additionalContext` for lessons whose globs match the file, each once per session (`.tmp/repo/sessions/<sid>/lessons-seen.json`). It reads only `INDEX.md` and fails open.
+
+SubagentStop (and child Stop with `subagentType`) intercepts a parseable `need:` whose jobs are all `search|exec|slice|fetch` (cap 4): runs job in-hook and continues the child with concatenated facts. Mixed/web/test, parse fail, FALLBACK, `stopHookActive`, or more than 3 intercepts per child session → empty stdout (allow stop).
+
+Stop and SubagentStop timeout is 30s (job cap is 20s). PreToolUse / UserPromptSubmit stay at 5s.
+
+The canonical hooks.jsonc event is `beforeSubmitPrompt` (→ Claude/Codex `UserPromptSubmit`), not `userPromptSubmit`.
+
+`[features] two_pass_compaction` must live in `~/.grok/config.toml` (from `agents/global-settings/grok.toml` via `bun repo yolo`). Project `.grok/config.toml` cannot set `[features]`.
+
+## Review strategy
+
+A plan or roadmap carries `strategy: default|review-fast|review-deep` (`plan-format.md`). `default` adds nothing here. For `review-*` the main session reviews and an implementer agent writes (`review-loop.md`). The code is `cli/scripts/strategy.ts`, called from `gate-fat-tools.ts` and `cli/scripts/orchestrate-parent.ts`.
+
+Stamp: a parent's save of a plan whose frontmatter holds a `review-*` strategy writes `.tmp/repo/sessions/<sid>/strategy.json`, which holds the plan's canonical path. A box tick on such a plan stamps too, so a resumed run in a new session stamps on its first save. A child's save stamps nothing. The gate writes it for every harness. orchestrate-parent calls `stampPlanSave` first for the plan Writes it persists itself. The stamp only points at the plan. `activeReview` reads the plan: it is active while `status` is `in-progress` and `strategy` is `review-*`, so `done` and `blocked` end it with no cleanup.
+
+Deny: `reviewGuard` in `processFatTools` sits right after the worktree deny, before the write branch and the scout return. While a review is active in an enforced harness, a parent write whose target is outside the root `.tmp/` is denied. The target is judged by canonical path after the scratch rewrite, not as typed. A child, a missing `sid` and an unenforced harness are not denied. Reason: `plan {n} runs strategy {s}: this session reviews. Spawn {implementer} for product writes; the plan, the journal and .tmp/ stay writable.`
+
+Implementer guards apply under every strategy: the spawn prompt names the worktree path, so the implementer's first Write is under `.worktrees/<name>` (the main-checkout deny holds for it too); an `implementer-*` child's write under `.tmp/repo/plans` or `.tmp/repo/implementations` is denied (`implementer writes product files and tests only; the reviewer writes the plan and the journal`), and so is a shell `git add` or `git commit` (`implementer never stages or commits; report the changed files and the reviewer stages them`).
+
+Test runs: a plain `bun run test …` (or `vitest`, `npm test`, `pnpm test`) from an `implementer-*` child, or from a parent while a review is active, is rewritten to `<root>/node_modules/.bin/repo job --job test --query '<command>'`. The full log goes to the stash and the caller sees the failing lines. A compound command passes through.
+
+Approval: the Stop hook blocks a reply that should ask for approval unless its last line is a closing line that names every pending item with the strategy its file holds. The block reason is `end with: ` and the line `closingLine` renders from the files. On the next prompt, a bare `y` returns `y approves plan {n}: plan {n}: run /implement-plan {n} (<path>)` and leaves the file alone. `y <strategy>` writes that strategy into each approved plan or roadmap (validated through the persist module), and the context says to re-read the file before work. An unknown word approves nothing: `unknown strategy "{word}"; use y, y default, y review-fast or y review-deep`.
+
+The closing line `closingLine` renders, for one plan: `Reply "y" to run plan {n} (strategy: {s}), or "y {a}" / "y {b}", or "h" / "h fast" / "h deep" for a fresh session.` A queue joins items with `, then ` and keeps one `or "h" …` tail.
+
+Settled review: a parent spawn whose prompt starts `/review-plan {n}` or `/review-roadmap {n}` records `{"plan {n}": <reviews at spawn>}` in `.tmp/repo/sessions/<sid>/reviews-open.json`, keyed by `plan {n}` or `roadmap {n}`, never by path. An item is settled when its file's `reviews` is above the recorded number, or nothing was recorded and `reviews` is at least 1. Stop blocks a closing line that names an unsettled item, before the approval and mode checks: `plan {n}'s review has not settled; wait for it, settle its findings with reviews bumped, then end with the closing line`, or on `reviews: 0`, `plan {n} has reviews: 0; run /review-plan {n} in a fresh agent first`. A Stop block fires once, so a `y` or `h` on an unsettled item is refused too: `y did not approve plan {n}: its review has not settled; wait for it, then end with the closing line again` (`h did not hand off …` for `h`). Unsettled items never count as pending.
+
+Handoff: `h` keeps each file's strategy; `h fast` and `h deep` write `review-fast` or `review-deep` through the same validated write as `y <strategy>`. There is no `h default`. The hook writes one handoff for the whole line through `persistHandoff`: H1 `run-plan-{n}` (or `run-{kind}-{n}-then-…`), Goal names the items, State their paths and strategies, Context the source session, Next one leaf per item in order (`/implement-plan {n}`, or `set status locked, then /implement-roadmap {n}`), Watch-outs `(none)`. The context: `h handed off plan {n} (strategy review-fast written) to <abs path>; tell the person to run /pickup {serial} in a fresh session, and do no work here`.
+
+Enforcement, from the live probe of each harness's child payload:
+
+| Harness | Child marker | Enforced |
+| --- | --- | --- |
+| claude | `agent_type` and `agent_id` | yes |
+| codex | `agent_type` and `agent_id`; shares the parent's `session_id` | yes |
+| grok | `subagentType`, own `sessionId`; `harnessOf` reports `claude` | yes, through `claude` |
+| antigravity | none; only a different `conversationId`, its only session-id key | no |
+| cursor | none; only a different `session_id` | no |
+
+An unenforced harness follows the rule as an instruction (`review-loop.md`). Cursor's `beforeSubmitPrompt` writes only `git-asked.json` in orchestrate-parent, so `y <strategy>` and `h` have no effect there and `/away` never stamps; Cursor runs Stop, so `mode:` and the Stop rules still apply. Antigravity has no Stop hook, so the settled-review and away rules are prompt-only there. Headless `cursor-agent -p` (v2026.11.05) never fires `beforeSubmitPrompt`, so no prompt can grant a git subcommand there and the git denies still apply; the Cursor IDE was not tested.
+
+`git-asked.json` (Worktrees) is keyed by sid. Claude and Codex children share the parent's sid and so its grant; a Grok, Cursor or Antigravity child has its own sid and gets none. Antigravity has no `git-asked.json`: the gate reads `lastUserInput` from the tool call, and an agy subagent's calls carry an empty one, so a child gets no grant.
+
+Main-session compaction window: a user setting, `modelSettings.<model>.autoCompactWindow` in `~/.claude/settings.json`. Each agent carries its own value in its `claudecode` block. Do not set `CLAUDE_CODE_AUTO_COMPACT_WINDOW`: it overrides every agent's value.
+
+## Worktrees
+
+The main checkout is `root` (`resolveRoots().root`), outside `<root>/.tmp` and `<root>/.worktrees`. The gate (`gate-fat-tools.ts` `sharedCheckoutReason`, `worktree.ts` `mainCheckoutWriteReason` and `sharedGitReason`) answers for every caller, parent, scout and implementer alike, on every harness whose write tools it knows. It runs beside the `git worktree add` check, ahead of `reviewGuard` and every early return.
+
+- Write: a write whose canonical target (after the scratch redirect) is in the main checkout is denied: `the main checkout is shared: run bun repo worktree add <name> and write under <root>/.worktrees/<name>; only <root>/.tmp/ is writable here`. A lesson Write is answered by orchestrate-parent before the gate, so it calls `mainCheckoutWriteReason` itself. `lessons.ts` `persistLesson`, `hitLesson` and `removeLesson` return `{ ok: false, error }` with the same text, and the CLI `hit`, `rm` and `index` exit 1; `match` and `check` stay read-only, and `writeIndex` is unguarded because `bun repo init` and `bun repo sync` call it in a consumer's main checkout.
+- Git in the main checkout: `commit`, `merge`, `cherry-pick`, `revert`, `am` and `pull` are denied with `the main checkout is shared: commit inside <root>/.worktrees/<name>, then run cd <root> && bun repo worktree finish <name>`. `stash`, `reset`, `checkout`, `switch`, `restore`, `clean` and `rebase` are denied with `git <sub> in the main checkout can destroy other sessions' work: do it inside your worktree, or run it here only when the user's message asks for git <sub>`.
+- Anywhere in the repo: a force push (`-f`, `--force`, `--force-with-lease`, `+ref`); `branch -d|-D|-f|-m|-M` of the default branch; `update-ref` of the default branch. The default branch is `origin/HEAD`, else `init.defaultBranch`, `main` or `master` when it exists locally, else the main checkout's current branch.
+- Own worktree: inside the managed worktree the effective cwd is in (`cd` and `git -C` are followed), every other git command runs, `stash`, `reset --hard`, `checkout`, `rebase` and `commit --amend` included.
+- Exception: `.tmp/repo/sessions/<sid>/git-asked.json` holds `{ "words": [...] }`, rewritten on every user prompt (an empty list clears it) by orchestrate-parent on Claude, Codex and Grok `UserPromptSubmit` and on Cursor's `beforeSubmitPrompt`, and read by the gate by sid. A named word lets that subcommand run for the turn. Bare words grant only `stash`, `commit` (so `/commit` grants it), `rebase` and `cherry-pick`; a force push needs `force push`, `force-push`, `push -f` or `push --force`; every other subcommand needs the literal `git <sub>`, since "main checkout", "clean up" and "merge to main" are everyday phrases. A negation ("don't stash") matches too, so the `AGENTS.md` line still applies. Claude and Codex children share the parent's sid and so its grant; Grok and Cursor children do not. Antigravity (1.5.3) writes no file: every tool call carries the user's message as top-level `lastUserInput`, and the gate feeds it through the same word rules. Only the main agent's calls carry it; an agy subagent's calls carry `lastUserInput: ""`, so a child gets no grant and a spawn prompt cannot grant one. Antigravity's gated tools are `write_file {Path, Content}`, `edit_file {Path, Target, Replacement}` and `run_command {CommandLine}`; `read_file {Path, StartLine, EndLine}` is not gated. Headless `cursor-agent -p` (v2026.11.05) never fires `beforeSubmitPrompt` either, so no prompt can grant a git subcommand there and the denies still apply; the Cursor IDE was not tested.
+- Fail-open: not a git repo, a repo with no commit yet, and an error inside the check let the call through. A missing `sid` or an unwritable `git-asked.json` means no grant, so the deny stands. `finish`, `prune` and the `WorktreeRemove` hook run git from node, never the shell, so the git deny cannot block them.
+- Not parsed: `bash -c '...'`, `$(...)` and `xargs git` hide a git command from the gate. An `rtk` or `env VAR=v` prefix and `cd <dir>` or `git -C <dir>` are parsed; a heredoc body is not a command.
+- Shell-write gap: `sed -i`, `>`, `tee` and `rm` write the main checkout past the write deny, and so do the `rm` hints in `bun repo doctor`. The commit deny is the backstop: the change cannot be committed there without the user's message naming commit.
+- `bun repo init` and `bun repo sync` rewrite tracked files from node, so run them inside a worktree. Run in the main checkout they leave it dirty, and only the user can commit that.
+- Unmanaged linked worktrees outside `.worktrees` (T3 Code, Claude Desktop) are outside the root, so writes there pass, `finish` cannot land them, and `/commit` there only commits. They are not "own worktree" for the git rules.
+
+`bun repo worktree add <name>` makes `<root>/.worktrees/<name>` on `wt/<name>` and prints the path. When the root has `bun.lock` it also runs `bun install --frozen-lockfile` in the new worktree (output on stderr, sub-second on a warm cache; a failure prints one line naming the command and the path still prints), so tools that look up `<cwd>/node_modules/.bin`, such as pipeline, work there.
+
+`bun repo worktree finish [<name>]` lands the branch. With no name it takes the worktree its cwd is in; from the root it exits 2 (`run finish inside .worktrees/<name> or pass its name`). It refuses a dirty worktree (any `git status --porcelain` line, untracked files included) and one mid-rebase, rebases `wt/<name>` onto the default branch inside the worktree, fast-forwards the default (`merge --ff-only` when the root has it checked out, else `fetch . wt/<name>:<default>`), then runs `git worktree remove` (never `--force`) and deletes the branch once the default holds it. If the default moved since the rebase, it rebases again, at most 3 tries (`<default> kept moving while finishing wt/<name>; run finish again`); a fast-forward that fails with the default unchanged reports git's reason with no retry (the root's own changes to the same file do this). A conflict aborts the rebase, keeps the worktree and names the files: resolve them in the worktree, rerun the checks, run `finish` again. A branch with no commits of its own is removed with `wt/<name> has no commits of its own; removed <path>`. A rerun after a crash converges: a merged branch with no worktree is deleted. `finish` never pushes. On success it prints `merged wt/<name> into <default> at <sha> and removed <path>; your shell may still be in it: cd <root>`. Run it from the root: `cd <root> && bun repo worktree finish <name>`. Run inside the worktree it removes, the work succeeds but Claude's Bash reports exit 1 (its own `pwd` fails in the deleted directory); check the `merged …` line and do not rerun.
+
+`bun repo doctor` lists a managed worktree with commits the default lacks and a last commit 7 or more days old as `stale worktree <path> (wt/<name>, last commit <n> days ago)` with the `finish <name>` command. Younger ones are live work and are not listed.
+
+`bun repo doctor` `agent models` checks that each model a generated agent names is still offered by its CLI: `.codex/agents/*.toml`, `.grok/agents/*.md`, `.grok/roles/*.toml` and `[subagents.models]` in `agents/global-settings/grok.toml`, `.agents/agents/*.md` (Antigravity) and `.cursor/agents/*.md`. Claude agents use the aliases `haiku`, `sonnet`, `opus` and are not checked. Cursor agents use `model: inherit` (the parent session's model, which any Cursor plan can run; a pinned Claude id is listed on a Free plan but refused), and `inherit` is not checked. Codex and agy are checked without running a command. Codex's list comes from `~/.codex/models_cache.json` `models[].slug` (a file). Agy's is a fixed set, the only values agy accepts for an agent's `model:`: `inherit`, `flash`, `pro` and `flash_lite`. `agy models` lists session models, which an agent file cannot name, and agy silently drops an agent whose `model:` is anything else. An agy main agent's `model:` is ignored (it runs on the session model), so the orchestrator uses `inherit`. An agy agent with no `tools:` gets a read-only default, so the orchestrator lists its tools. Grok's and Cursor's lists come from `grok models` and `cursor-agent --list-models`; those two commands run in parallel under one 20 s cap. A dropped model prints `<file>: model <id> is not offered by <cli>; offered: <ids>`. Grok or Cursor is skipped with its reason when it is not installed or its list fails or takes over 20 s, and codex when its cache is missing or malformed (`agent models  ok (skipped: ...)`). Agy is never skipped. Report only: the row never fails the run.

package/references/implementation-format.md

@@ -0,0 +1,119 @@
+# Implementation format (SSOT)
+
+Local session journal for `/implement-plan`. Not a plan, handoff, or git commit.
+
+Created when `/implement-plan` starts. Straight shots skip this file. Do not merge into the plan (plan = flip the box only).
+
+## Path
+
+`.tmp/repo/implementations/{serial}-{slug}-{YYYYMMDDTHHMMSSZ}.md`
+
+- **serial:** own counter (not plan serials). Unpadded decimal int ≥ 1. Never `0001`.
+- **filename:** unpadded serial, slug, UTC datetime stamp. Same regex as new plans: `^[0-9]+-[a-z0-9]+(-[a-z0-9]+)*-\d{8}T\d{6}Z\.md$`
+- **lookup:** integer equality on leading digits.
+- Frontmatter `serial:` line must match `^serial: [1-9][0-9]*$`.
+- New writes always stamped. Collision: increment serial, same stamp.
+
+## Link
+
+Frontmatter `plan:` is the plan serial (`6`) or `none`. Own serial stays independent.
+
+## Slugify / allocate
+
+Same as plans (`slugify`, `nextSerial` on this dir). Body line 1: `IMPL_NAME: <3-6 word name>`. Optional `IMPL_PLAN: <n|none>` (default `none`).
+
+## Frontmatter (required)
+
+```yaml
+---
+serial: 1
+plan: 6                 # unpadded int or none
+name: add-auth
+status: in-progress     # in-progress | done | blocked
+created: 2026-08-26T14:30:00Z
+source: "<≤120 chars of user task>"
+---
+```
+
+### Status machine
+
+`in-progress` → `done` | `blocked`
+
+- Fresh write: `in-progress`
+- Plan Verify done and journal caught up: `done`
+- Cannot finish: `blocked` (`## Blockers` must not be `(none)`)
+
+## Body headings (this order only)
+
+`# {slug}`, `## Done`, `## Issue`, `## Files`, `## Log`, `## Blockers`, `## Notes`
+
+No other `##` headings.
+
+| Section | Amount |
+|---|---|
+| Done | bullets. What landed and why. Past tense. Fresh: `(none)` |
+| Issue | bug root cause bullets, or `(none)` |
+| Files | repo-relative product paths as `- path` bullets. Default `/commit` stage set. No abs paths. No `.tmp/`. Fresh: `(none)` |
+| Log | append-only. Fresh: `(none)`. After each plan leaf: `N.M [x] one line` (notes, fail, skip). `[x]` allowed |
+| Blockers | open problems. `(none)` unless `status: blocked` |
+| Notes | short leftovers, or `(none)` |
+
+## Write
+
+Write under `.tmp/repo/implementations/` (any filename in that dir). Grok `orchestrate-parent.ts` runs `cli/scripts/persist-implementation.ts` on create (`IMPL_NAME:`): serial/slug from the name, injects frontmatter, rewrites path + content. Updates to an existing file keep the path; full-body writes are validated in place. Invalid create/update denies — fix the body, do not retry elsewhere.
+
+Host without that hook: name the file per **Path**, or pipe the body to `bun repo persist implementation --workspace {repo}` and use its `absPath`.
+
+Never allocate a new serial to log a leaf. Append Log, update Files/Done, flip the plan box.
+
+## Validation checklist
+
+- filename stamped unpadded; serial int equals leading digits; `name` equals slug
+- frontmatter keys: `serial`, `plan`, `name`, `status`, `created`, `source`
+- `plan` is `none` or unpadded int ≥ 1; `status` ∈ `in-progress` | `done` | `blocked`
+- headings in order only; no extra `##`
+- Done / Issue / Files / Log / Blockers / Notes: bullets and/or `(none)`; none of those sections empty
+- Files: repo-relative; reject abs and `.tmp/`
+- `status: blocked` ⇒ Blockers is not only `(none)`
+
+## Worked example
+
+File: `.tmp/repo/implementations/1-notes-export-json-20260826T143000Z.md`
+
+```markdown
+---
+serial: 1
+plan: 1
+name: notes-export-json
+status: in-progress
+created: 2026-08-26T14:30:00Z
+source: "add --json to notes export"
+---
+
+# notes-export-json
+
+## Done
+- `notes export --json` prints every note as one JSON array; the text table stays the default
+
+## Issue
+(none)
+
+## Files
+- src/cli.ts
+- src/export.ts
+- src/export.test.ts
+
+## Log
+1.1 [x] read principle-test-behavior-not-implementation
+2.1 [x] export tests for two notes and for none
+2.2 [x] new cases fail on the unknown flag
+3.1 [x] parse --json in cli.ts
+3.2 [x] print JSON.stringify of the notes in export.ts
+3.3 [x] export tests pass
+
+## Blockers
+(none)
+
+## Notes
+(none)
+```

package/references/jev.md

@@ -0,0 +1,56 @@
+---
+tags: [jev]
+---
+
+# Jev
+
+Closed external decision. The source text is already saved. The question is a yes/no or a named choice. One call. Not open research. Not code. Not job.
+
+## Availability
+
+```
+bun repo jev --available
+```
+
+Prints `yes` or `no` and exits 0. No request. No setup line.
+
+`no`: the session answers the question itself. Do not run the decision command. Do not mention Jev, a missing key, or setup.
+
+`yes`: continue below.
+
+A key is `TYPESAFE_API_KEY` or `apiKey` in `~/.workerstack/jev.json` (mode 0600). Env wins. Setup, when a person asks for it: `bun repo setup jev`. Spec: `node_modules/@workerstack/repo/references/setup.md`.
+
+## Decision
+
+Write `.tmp/repo/jev/<slug>-state.txt` (plain text or a JSON object) and `.tmp/repo/jev/<slug>-questions.json` (the System One questions map). Put every label for that study in the one map. At most 8 questions. State at most 64000 characters.
+
+```
+bun repo jev --state .tmp/repo/jev/<slug>-state.txt --questions .tmp/repo/jev/<slug>-questions.json
+```
+
+Yes/no:
+
+```json
+{ "keep": { "type": "noul", "instructions": "Does this passage promise zero retention on the default plan?" } }
+```
+
+Named choice:
+
+```json
+{
+  "endpoint": {
+    "type": "choice",
+    "instructions": "Which endpoint should the app call?",
+    "criteria": {
+      "typesafe": "Vendor host, path, and key",
+      "other": "A different host, path, or key"
+    }
+  }
+}
+```
+
+Model is `jev-1.13.0`. Stdout is at most 8 lines: model, input tokens, then one label line. Exit 0. Use that label and confidence. A low confidence is the result. Do not rephrase and call again.
+
+One request per process. UTC-day ledger `~/.workerstack/jev-usage.json` stops at 40 requests or 1000000 input tokens. A 429 or 529 retries once only when `Retry-After` is at most 2 seconds.
+
+Exit 2 means the decision call did not return a label. Answer from the sources. Do not invent a label. Do not print the key or the state.

package/references/lessons.md

@@ -0,0 +1,73 @@
+---
+tags: [lessons]
+---
+
+# Lessons
+
+Mistakes that outlive one task. One committed file per mistake under `.repo/lessons/`, with a generated index. Not host memory: everything is in the repo and reaches every machine through git.
+
+## Three layers
+
+- **Plan:** `## Previous mistakes` in each plan holds that task's details: rejected approaches, failed Verify, accepted review findings. It stays with the plan in `.tmp/`. Format: `node_modules/@workerstack/repo/references/plan-format.md`.
+- **Roadmap:** `## Previous mistakes` in a roadmap holds mistakes about the program: slice order, slice boundaries, and `slice` entries for what a child plan found that changed later slices. A roadmap saved in the old shape also logs its Decisions there; a pointer roadmap's decisions live in the slice plans. It lasts as long as the program, in `.tmp/`. Format: `node_modules/@workerstack/repo/references/roadmap-format.md`.
+- **Repo:** a lesson holds a mistake that will happen again on other tasks. A plan entry that generalizes becomes a lesson, and the entry ends with `(lesson: {slug})`.
+
+## File
+
+`.repo/lessons/{slug}.md`, at most 60 lines.
+
+```markdown
+---
+name: plan-forks
+paths: ["cli/scripts/persist-plan.ts", "agents/grok/hooks/**"]
+hits: 1
+last-hit: 2026-11-01
+evidence: ["plan 16"]
+---
+
+# Plan rewrites fork serials
+
+Rewriting a saved plan minted a new serial.
+
+## Mistake
+What went wrong, concretely.
+
+## Fix
+What to do instead.
+```
+
+- `name` is the filename slug. `paths` are repo-relative globs (`**` spans dirs; `*` and `?` stay in one segment) and each must match a file that exists.
+- `hits` counts occurrences. `evidence` keeps the 5 most recent plan serials or commits.
+- A new lesson may leave out `hits` and `last-hit`; the save fills `1` and today.
+
+## Index
+
+`.repo/lessons/INDEX.md` is generated: one row per lesson with path, globs, hits, last hit, and summary, sorted by hits. Do not edit it. Every lesson save, `hit`, and `rm` rewrites it, and `bun repo sync` rewrites it too. `bun repo sync --check` fails on index drift, an invalid lesson, or a glob that matches no file.
+
+## Write
+
+- Write, `hit`, `rm` and `index` run inside a worktree: the plan's `{serial}-{name}` (`bun repo worktree add {serial}-{name}` if it is missing), else `lesson-{slug}`, and `/correct` uses its `correct-{slug}`. The lesson then lands with that worktree's commit and `finish` (run from the root). In the main checkout the Write is denied, `hit`, `rm` and `index` exit 1 with `the main checkout is shared: run bun repo worktree add <name> and write under <root>/.worktrees/<name>; only <root>/.tmp/ is writable here`, and the library calls return `{ ok: false, error }` with that text.
+- Write the whole file. The hook validates it, renders the standard form, and reindexes; the host saves it. An Edit of a lesson is denied.
+- `bun repo lessons hit <slug> --evidence <text>` counts a repeat. The same evidence counts once.
+- `bun repo lessons rm <slug>` deletes a lesson and reindexes.
+- `bun repo lessons index` rebuilds the index. `check` runs the checks and, like `match`, is read-only, so it runs anywhere.
+
+## When to write
+
+After any of these, add a `## Previous mistakes` entry to the plan. If the mistake will happen again on other tasks, run `bun repo lessons match` on the files involved first, then `hit` the matching lesson or write a new one.
+
+- Plan feedback from the user (`/write-plan`).
+- A failed Verify, or a test that failed after a fix (`/implement-plan`).
+- `principle-attack-the-premise` firing (`/implement-plan`).
+- An accepted `/review-plan` finding (`/write-plan`).
+- Roadmap feedback, an accepted `/review-roadmap` finding (`/write-roadmap`), a child plan that changes the program, or a failed program Verify (`/implement-roadmap`). These go to the roadmap's log. Before the roadmap is `done`, each entry that outlives the program becomes a lesson with `--evidence "roadmap {n}"`.
+- An operator correction (`/correct`).
+
+At `hits: 2` the mistake is a class. `/correct` encodes it as a check (architecture, type, lint, or test), then runs `bun repo lessons rm`.
+
+## When to read
+
+- `bun repo lessons match <file...>` prints the lessons whose globs match, most hits first, 10 at most. Each file is matched against the lessons of the checkout that holds it: the root or a managed worktree; a file in an unmanaged linked worktree uses the checkout you run it from.
+- A new plan that names a matched file must cite that lesson's path in Watch-outs, or the save is denied with the lesson listed.
+- The first time a session edits a matched file, the hook adds that lesson's summary and path to the context. Each lesson is shown once per session.
+- `/review-plan` reads the matched lessons and flags one that no leaf acts on.

package/references/listen.md

@@ -0,0 +1,80 @@
+---
+tags: [listen]
+---
+
+# Listen
+
+Speech-to-text from the session. Input only. Not TTS. Not a live voice agent. Not MCP.
+
+```
+bun repo listen whoami
+bun repo listen devices
+bun repo listen rec [--seconds 8] [--device D] [--clip]
+bun repo listen start [--device D]
+bun repo listen stop [--clip]
+bun repo listen toggle [--clip]
+bun repo listen status
+bun repo listen file --path clip.wav [--clip]
+bun repo listen latest
+```
+
+`rec` records then transcribes (default 8s, cap 120s). `toggle` is the hotkey verb: first run starts, second run stops and prints the transcript. Audio and `latest.txt` live under `.tmp/repo/listen/`. `--cwd /path/to/repo` when the hotkey does not already run in the repo.
+
+## Auth and capture
+
+Handheld (any OS): `bun repo setup listen` or `bun repo setup` → listen. Prints OS install commands for ffmpeg / whisper-cli (does not run them), optional ggml download into `~/.workerstack/whisper/`, OpenAI fallback key if local STT is missing.
+
+If ffmpeg, whisper-cli, a ggml model, or `OPENAI_API_KEY` is missing, the CLI prints `setup: bun repo setup listen` and exits 1. Agents should show that line, not a stack or JSON. Do not invent a key.
+
+STT prefers **local whisper.cpp**. Install the binary; the first `listen` downloads `ggml-base.en.bin` (~142MB) into `~/.workerstack/whisper/`. No API cost after that. If the binary or download is missing, it falls back to OpenAI `whisper-1` (`OPENAI_API_KEY` or `~/.workerstack/speak.json`). Force with `LISTEN_STT=local` or `LISTEN_STT=openai`. Never commit keys.
+
+| | env | `~/.workerstack/speak.json` |
+| --- | --- | --- |
+| Local model | `WHISPER_MODEL` | `listen.whisperModel` |
+| Force engine | `LISTEN_STT` | `listen.stt` (`auto` / `local` / `openai`) |
+| OpenAI key | `OPENAI_API_KEY` | `openai.apiKey` |
+| OpenAI model | `LISTEN_MODEL` | `listen.model` (default `whisper-1`) |
+| Device | `LISTEN_DEVICE` | `listen.device` |
+| Seconds | `LISTEN_SECONDS` | `listen.seconds` |
+
+### Local Whisper (preferred)
+
+One install:
+
+- mac: `brew install whisper-cpp` (provides `whisper-cli`)
+- linux: build https://github.com/ggml-org/whisper.cpp (`whisper-cli` on PATH)
+- win: whisper.cpp release `whisper-cli.exe` on PATH
+
+Then `bun repo listen whoami` or `rec`. The first run fetches `ggml-base.en.bin` to `~/.workerstack/whisper/`. Do not pip-install OpenAI Whisper. Do not curl the model yourself unless the auto-download fails.
+
+Larger models: put another `ggml-*.bin` in that folder or set `WHISPER_MODEL`. Doctor reports `whisper-cli` as optional. `whoami` prints `stt=local` or `stt=openai`.
+
+### ffmpeg (mic only)
+
+- mac: `brew install ffmpeg`
+- linux: `sudo apt install ffmpeg`
+- win: `winget install Gyan.FFmpeg`
+
+`file` and `latest` work without a mic. Doctor reports ffmpeg as optional.
+
+`rec` detaches ffmpeg and does not attach it to the IDE TTY. AVFoundation can stall forever on a VS Code / Electron PTY even when Visual Studio Code already has Microphone access.
+
+Default devices: mac `:0` (AVFoundation audio 0), linux Pulse `default` (ALSA if the id is `hw:…`), Windows requires `--device` or `LISTEN_DEVICE` from `listen devices`.
+
+## Hotkeys
+
+Bind one key to toggle. Include `--clip` so the transcript is on the clipboard as well as `latest.txt`.
+
+```
+bun --cwd /ABS/repo repo listen toggle --clip
+```
+
+Replace `/ABS/repo` with the repo root.
+
+- **mac:** Shortcuts (Run Shell Script) or skhd: `hyper - r : bun --cwd /ABS/repo repo listen toggle --clip`
+- **win:** PowerToys Keyboard Manager or AutoHotkey: `^!r:: Run, bun --cwd C:\ABS\repo repo listen toggle --clip, C:\ABS\repo, Hide`
+- **linux:** desktop custom shortcut or sxhkd to the same command.
+
+No daemon. Each keypress is one CLI. First press records; second press transcribes.
+
+`--clip` uses `pbcopy` (mac), `clip` (win), or `wl-copy` / `xclip` / `xsel` (linux).