@workerstack/repo 0.0.0-stage → 0.1.0

package/references/map.md

@@ -0,0 +1,107 @@
+---
+tags: [map]
+---
+
+# Map
+
+Cheap outline. Not a file dump.
+
+## Protocol
+- `node_modules/@workerstack/repo/references/cascade.md` — session agent tools; job first; spawn scout when the dump needs judgment
+- `node_modules/@workerstack/repo/references/rtk.md` — shell compression
+- `node_modules/@workerstack/repo/references/browser.md` — Lightpanda-first session CLI (`nav|snap|click|fill|scroll|wait|hover|select|shot|pdf|stop`); not MCP
+- `node_modules/@workerstack/repo/references/hooks.md` — hook policy
+- `node_modules/@workerstack/repo/references/map.md` — this file
+- `node_modules/@workerstack/repo/references/output.md` — default voice
+- `node_modules/@workerstack/repo/references/scope.md` — size gate; plan by default: research → `/write-plan` → approval → `/implement-plan`; two or more slices → `/write-roadmap`
+- `node_modules/@workerstack/repo/references/INDEX.md` — the catalog, read first: the repo's domain law, then the generated `repo:skills` (skills), `repo:refs` (reference docs) and `repo:stack` (the stack's packages) sections. INDEX always. Not if-maps-else
+
+## Agent SSOT
+- Docs SoT: `agents/skills` + `references/` (shipped in the package; a consumer reads `node_modules/@workerstack/repo/references/`). `bun repo sync` maps anything placed there. `.claude/skills/<name>` and `.agents/skills/<name>` are generated links to `agents/skills/<name>`, not SoT; no mirror scan
+- The trees come from `cli/sync/agents/` (`sources` `frontmatter` `rules` `subagents` `hooks`) via `bun repo sync`, reading the stock sources in `agents/` (exported as `@workerstack/repo/agents/*`)
+- `agents/subagents/{orchestrator,repo}.md`
+- `agents/rules/overview.md` → `AGENTS.md`
+- A consumer's own content lives in `.repo/` (below) and `references/`; both are committed, and `bun repo sync` merges them over the package's
+- Default output: `node_modules/@workerstack/repo/references/output.md` (overview.md → AGENTS.md; also agent bodies, not auto-injected)
+
+## Skills layout
+- Source: `agents/skills/<name>/SKILL.md`, the one copy (`STOCK_SKILLS_REL` in `cli/scripts/skill-conflicts.ts`) in this repo. A consumer's own skills go to `.repo/skills/<name>/`, and one named like a stock skill replaces it
+- A consumer's `bun repo sync` links each stock skill (and each `.repo/skills/<name>`) into `.agents/skills/<name>` for codex and antigravity and into `.claude/skills/<name>` for claude, as a directory symlink (a junction with an absolute target on Windows): to the generated `.agents/skills/<name>` when there is one, else straight to the skill. Optional packs (`google-workspace` `listen` `speak` `clasp`) are linked only when `agents.skills` names them. In this repo sync links both `.claude/skills/<name>` and `.agents/skills/<name>` straight to `agents/skills/<name>` with a relative link. The package ships no generated trees, so each consumer's sync makes its links
+- Read directly: Codex and Antigravity read `.agents/skills`; Grok reads `.grok/skills`, `.agents/skills` and `.claude/skills` (deduplicated by name); Cursor reads `.cursor/skills`, `.claude/skills`, `.codex/skills`, `.grok/skills` and `.agents/skills` (follows symlinks, deduplicates by realpath)
+- There is no skills generator step: `bun repo sync` only links skills; nothing wipes `.agents/skills`
+
+## Grok hand files
+- `cli/scripts/orchestrate-parent.ts` + `agents/grok/hooks/orchestrate-parent.json` — spawn/fat/stop/persist / SubagentStop intercept / session receipt
+- `bun repo sync` prunes what it wrote last run and no longer plans (the `.repo/tmp/sync.json` manifest); a path outside the manifest is never removed
+- `agents/grok/hooks/rtk.json` — RTK
+- `agents/global-settings/` — `manifest.json` (hosts `claude` `codex` `grok` `antigravity` `cursor`: `format`, `payload`, `dest` under `$HOME`) and one payload per host (`claude.json` `codex.toml` `grok.toml` `antigravity.json` `cursor.json`); `sync-global-settings.ts` (`bun repo yolo`) merges each into its dest (not auto-loaded; project `.grok/config.toml` cannot set `[features]`)
+- `agents/mcp-policy.jsonc` — MCP deny-default SSOT (`default: deny`, `allow: []`)
+- `agents/grok/{roles,hooks}/` — grok's static roles and hook configs; `bun repo sync` copies them into `.grok/roles` and `.grok/hooks`
+- `agents/skills/<name>/` — the one skills source; `bun repo sync` links each into the host skill dirs
+
+## Scripts
+- `cli/scripts/check-globals.ts` — every manifest payload key (minus `skipKeyPattern`) must be present in its `$HOME` dest; project `.grok/config.toml` sets no `[features]` or `[agent]`. Not in `bun repo sync --check`: `bun cli/scripts/check-globals.ts` in this repo and the `bun repo doctor` `globals` row everywhere
+- `cli/scripts/gate-fat-tools.ts`
+- `cli/scripts/scrub-spawn-prompt.ts`
+- `cli/scripts/job.ts` — flags `--job` `--query` `--path` `--glob` (repeatable) `--cwd`; regex in `--query` OK; never `cd &&`; unknown flags / exec shell-meta → FALLBACK
+- `cli/scripts/parse-need.ts`
+- `cli/scripts/persist-handoff.ts` — `.tmp/repo/handoffs/{serial}-{slug}-{stamp}.md`
+- `cli/scripts/persist-tmp.ts` — `.tmp/repo/{serial}-{slug}-{stamp}.{ext}` root files
+- `cli/scripts/persist-plan.ts`
+- `cli/scripts/persist-implementation.ts` — `.tmp/repo/implementations/{serial}-{slug}-{stamp}.md`
+- `cli/scripts/sync-global-settings.ts` — dry-run by default, `--apply` writes `$HOME`, `--host <id>`; report line `{action} {id} {dest}`
+- `cli/scripts/purge-global-mcps.ts`
+- `cli/scripts/emit-mcp-policy.ts`
+- `cli/scripts/emit-agent-shell-tools.ts`
+- `cli/scripts/browser.ts` — session browser rail
+- `cli/scripts/google-workspace.ts` — Sheets Docs Slides Calendar Gmail Drive
+- `cli/scripts/speak.ts` — TTS
+- `cli/scripts/listen.ts` — STT
+- `cli/scripts/setup.ts` — handheld speak / listen / google-workspace / browser (`~/.workerstack/`)
+- `cli/scripts/doctor.ts` — unified prereqs; `globals` row (ok or first drift line); optional google-workspace (`oauth` `tokens` `adc` `clasprc`), speak, clasp, ffmpeg, whisper-cli
+
+## Tmp
+- `.tmp/repo/plans/` — persist-plan; format SSOT = `node_modules/@workerstack/repo/references/plan-format.md`
+- `.tmp/repo/implementations/` — persist-implementation; format SSOT = `node_modules/@workerstack/repo/references/implementation-format.md`
+- `.tmp/repo/orchestrator-logs/` — need-intercept, session-gate, stop-block stamps
+- `.tmp/repo/` — scratch + `/tmp` dumps `{serial}-{slug}-{stamp}.{ext}` at root (not nested `tmp/`)
+- `.tmp/repo/browser/` — browser session/profile/shot/pdf (not MCP)
+- `.tmp/repo/handoffs/` — persist-handoff / `/handoff`
+- `.tmp/repo/stash/` — job / snap overflow
+- `.tmp/repo/sessions/{sid}/` — wrote/read/receipt
+- `.tmp/repo/speak/` — TTS mp3
+- `.tmp/repo/listen/` — STT wav + `latest.txt`
+
+## `.repo/` layout
+Repo-owned content, committed. In this repo `.repo/` holds `lessons/` and the ignored `tmp/`.
+- `lessons/` — one file per lesson plus the generated `INDEX.md`
+- `rules/` — extra rules, merged into `AGENTS.md` (a hand-written `AGENTS.md` that sync finds is adopted as `agents.md`); a stock rule's extra sections go to `<name>-local.md` so the stock text stays live
+- `subagents/` — extra agents; one named like a stock agent replaces it
+- `skills/` — extra skills, linked into each host tree (a real skill dir found under `.agents/skills` or `.claude/skills` moves here)
+- `settings/claude.json` — keys deep-merged into the generated `.claude/settings.json`
+- `mcp.json` — servers deep-merged into the generated `.mcp.json`
+- `hooks.jsonc` — replaces the stock hooks whole
+- `mcp-policy.jsonc` — deep-merged over the stock MCP policy
+- `permissions.json` — path deny rules added to the generated hooks
+- `global-settings/` — a payload of the stock's name here (`claude.json`, `codex.toml`, `grok.toml`, `antigravity.json`, `cursor.json`) replaces that stock payload whole in `bun repo yolo` and the `globals` check; the stock manifest stays
+- `tmp/` — ignored: `sync.json` (the manifest) and `stage/` (the build dir, removed after each sync)
+
+## Generated (do not hand-edit)
+`bun repo sync` writes these from `node_modules/@workerstack/repo` plus `.repo/` for the hosts in `agents.hosts` (default: all five; `HOST_TREES` in `cli/sync/hosts.ts` is the one table). In a consumer they are gitignored and recreated by every `bun install`; in this repo they are committed. `bun repo sync --check` reports drift.
+- `AGENTS.md` — any host on
+- `.mcp.json` — `mcpServers` from policy allow only; claude
+- claude → `.claude/`: `agents/*`, `settings.json` (MCP keys, hooks, the `.repo/settings/claude.json` merge), `skills/<name>` links
+- codex → `.codex/` (`agents/*`, `config.toml` `mcp_servers`, absent when allow empty) and `.agents/skills/<name>` links
+- antigravity → `.agents/`: `agents/*`, `skills/<name>` links, `mcp_config.json`, hooks
+- grok → `.grok/`: `agents/*`, `config.toml` (project MCP `[[permissions]]` + `[plugins] deny_default`; no `[features]`), `roles/scout.toml` and `hooks/*.json` copied from `agents/grok/`; the hook scripts stay in the package's `cli/scripts/`
+- cursor → `.cursor/`: `hooks.json` (hooks-union adds consumer extras), `agents/scout.md`; a real dir, not shipped in the package
+- release pack: `.github/workflows/ci.yml` (tracked, whole-file; the e2e job only when the root has a `test:e2e` script); a hand-written one is refused
+- always: `bunfig.toml`, the managed `.gitignore` block, `references/INDEX.md` sections `repo:skills`, `repo:refs`, `repo:packages` and `repo:stack`, `.repo/lessons/INDEX.md` when lessons exist, `.vscode/tasks.json` (committed in a consumer too)
+
+## Generator divergences
+Where `cli/sync/agents/` differs from the rulesync 43.7.0 it replaced:
+- YAML 1.2 parsing: `yes` stays a string
+- No 80-column folding of long values
+- The `agentsmd` and `codexcli` rule targets both fold into `AGENTS.md` only
+- A leading `./` in a claude hook command becomes `"$CLAUDE_PROJECT_DIR"/`
+- A bad subagent, or a rule without frontmatter, fails sync

package/references/output.md

@@ -0,0 +1,47 @@
+---
+tags: [output]
+---
+
+# Output
+
+en-US default. Detail behind the reply rules in `overview.md`, which stays the source for voice and shape.
+
+Cue names are examples too: example, e.g., for instance, such as, and so on, `…`, `etc.`, a sketched sentence, or one labeled case. Do not reuse one reply for every turn. Pick the count and the form for this case.
+
+A closed instruction stays literal. Cues of that kind include only, exactly, just these, verbatim, no others, a schema, an identifier, a command, or quoted text. When an open cue and a closed cue both apply, the closed cue wins.
+
+Do not invent a question or let the close introduce new numbers. Completed work uses past verbs and paths. If more work remains, say what. Ask in English when a choice is real.
+
+`/su`, `/bro`, `/unslop`, `/blast-radius`, `/correct`, `/teach`, plan files, commit subjects, and job stdout keep their own shape. `/bro` restates a reply that missed the voice in `overview.md`. `/explain` keeps the shape and may lengthen the middle. Repo children do not talk to the user.
+
+Job stdout is a sentence plus up to 6 dash facts, cap 8 lines, and an optional `stash=` receipt.
+
+## Example: waiting on the user
+
+One case of the class "the user must act before we can finish". Copy the shape, not the words.
+
+Cold:
+
+> We're waiting on four things, and only the first is mine to do now.
+>
+> 1. Local main isn't pushed. It's 10 commits ahead of origin, including my test fix. Nothing below can start until those commits reach origin.
+> 2. The first public-sync run after that push. It should copy the generated code into each public repo.
+> 3. Publish secrets. None of the public repos I checked has its own secrets or variables. They may be set at the org level, but my token can't read org settings.
+> 4. Your go to publish.
+>
+> Should I push main myself, or keep waiting?
+
+Partner:
+
+> We're one push away from the first releases, and most of what's left is yours.
+>
+> **You**
+> - Push main, or tell me to. It's 10 commits ahead, including another session's work.
+> - NuGet (`org/sdk-csharp`): add a trusted publishing policy for `release.yml`, and the repo variable `NUGET_USER`.
+> - Maven (`org/sdk-java`): add the user token as `MAVEN_CENTRAL_USERNAME` and `MAVEN_CENTRAL_PASSWORD`, and the GPG key as `MAVEN_GPG_PRIVATE_KEY` plus `MAVEN_GPG_PASSPHRASE`. Skip any already set at the org level; my token can't see org settings.
+>
+> **Me**: writing the test that blocks a release when the spec differs from prod, now. After the push I run the public sync, cut the releases, and verify each registry on Linux, macOS and Windows.
+>
+> Say "publish" when the secrets are in.
+
+The partner reply opens on the goal, groups the user's steps by where they do them, says what the agent does next, and ends on one action.

package/references/plan-format.md

@@ -0,0 +1,264 @@
+# Plan format (SSOT)
+
+Local session checklist. Not a design doc, PR stack, or DAG.
+
+## Path
+
+`.tmp/repo/plans/{serial}-{slug}-{YYYYMMDDTHHMMSSZ}.md`
+
+- **serial:** unpadded decimal int only (`1`, `12`, `10000`). **Never** `0001`, never quoted `"0001"` / `"1"`. Serial ≥ 1.
+- **filename:** unpadded serial, slug, UTC datetime stamp (`6-sync-global-settings-20260826T143000Z.md`, not `0001-slug.md`). Stamp is `created` with `-` and `:` dropped (keep `T` and `Z`).
+- **lookup:** integer equality on leading digits (`1` matches `1-foo-20260826T143000Z.md` and legacy `1-foo.md`; also `0001-foo.md` if an old padded file still exists).
+- **valid filename (new):** `^[0-9]+-[a-z0-9]+(-[a-z0-9]+)*-\d{8}T\d{6}Z\.md$`
+- **valid filename (legacy):** `^[0-9]+-[a-z0-9]+(-[a-z0-9]+)*\.md$` (no stamp; still accepted for existing files)
+- Frontmatter line must match `^serial: [1-9][0-9]*$`. Leading zeros are invalid (YAML octal / VS Code warning).
+- **New writes** always use the stamped filename. Collision: increment serial, rebuild filename, same stamp.
+
+## Slugify (`PLAN_NAME`)
+
+Send `PLAN_NAME: <name>` as the body's first line. The save reads the name from it and drops the line wherever it sits above the first `##` outside a code fence, so a body that opens with `commit:` or `strategy:` lines still saves with the card right under the title. A `PLAN_NAME:` line inside a fence or below the first `##` stays as text.
+
+1. lower
+2. non `[a-z0-9]` → `-`
+3. collapse `-`, strip edges
+4. trim to 50 chars; if cut on `-`, strip trailing `-`
+5. empty → `unnamed`
+6. strip trailing `.lock` if any
+
+## Allocate next serial (repo, bash)
+
+```bash
+mkdir -p .tmp/repo/plans
+next=1
+for f in .tmp/repo/plans/*; do
+  [ -f "$f" ] || continue
+  b=$(basename "$f")
+  case "$b" in
+    [0-9]*.md) n=${b%%-*}; n=$((10#$n)); [ "$n" -ge "$next" ] && next=$((n+1));;
+  esac
+done
+# filename prefix: unpadded decimal "$next" (1, 12, 10000)
+```
+
+Collision: if target path exists, increment and retry (max 5).
+
+## Frontmatter (required)
+
+```yaml
+---
+serial: 1
+name: add-auth
+status: ready          # ready | in-progress | done | blocked
+reviews: 0             # settled /review-plan rounds; never lowered or removed
+created: 2026-08-26T14:30:00Z    # UTC ISO-8601 seconds + Z; no milliseconds
+source: "<≤120 chars of user task>"
+commit: feat: <subject>
+strategy: default      # default | review-fast | review-deep
+mode: away             # optional: ask | auto | away
+---
+```
+
+`name` is the slug only (no datetime). `source` ≤120 chars.
+
+`strategy` is required. It says how the plan gets implemented:
+
+- `default`: the main session does the work, as it always has. No extra rules apply.
+- `review-fast`: the main session only reviews. Each phase goes to the `implementer-fast` agent. The reviewer reads the real diff, reruns the tests and sends findings back. A second attempt goes to `implementer-deep`.
+- `review-deep`: the same loop, with `implementer-deep` from the first attempt.
+
+A save with no `strategy` or an unknown value is denied with `strategy: default|review-fast|review-deep`. A body line `strategy: {value}` moves into the frontmatter after `commit:`, like `commit:`. A line inside a code fence is not moved. The person can change the value with `y <strategy>` when approving, or `h fast` / `h deep` when handing off.
+
+`mode` is optional: `ask`, `auto` or `away`. While the plan is `in-progress`, its `mode` wins over the session's `/ask` or `/away` flag, for the session that saved it only. `/write-plan` writes it only when the session runs `/away` or the person asked for a mode. A body line `mode: {value}` moves into the frontmatter after `strategy:`, like `strategy:`; a line inside a code fence is not moved. Another value is denied with `mode: ask|auto|away`.
+
+`reviews` counts the `/review-plan` rounds whose findings the writer settled: a whole number with no sign or leading zero, `0` on a new plan. The writer bumps it in the same save that applies a round's findings, even a round with no findings. It never goes down, and once present it cannot be removed, so every Write that sends full frontmatter carries the current `reviews`. The count proves a round ran and was settled, not that the review was good.
+
+`created` for **new writes:** `new Date().toISOString()` with milliseconds stripped (`.\d{3}Z` → `Z`), e.g. `2026-08-26T14:30:00Z`. Existing files may still have `created: YYYY-MM-DD`.
+
+### Status machine
+
+`ready` → `in-progress` → `done` | `blocked`
+
+- Fresh write: `ready`
+- Implement start: `in-progress`, only with `reviews` ≥ 1. The save denies the move with `reviews: 0`, and a missing `reviews` counts as 0. A plan already `in-progress` without the key stays editable
+- All boxes `[x]`: `done`
+- Cannot finish: `blocked` (leave remaining `[ ]`)
+
+## Body headings (this order only)
+
+`# {slug}`, the card, `## Goal`, `## Usage`, `## Context`, `## Constraints`, `## Watch-outs`, `## Steps`, `## Verify`, `## Previous mistakes`
+
+No other `##` headings. A plan saved before `## Usage` or `## Previous mistakes` existed stays valid without them; a fresh save needs both. Lines inside a code fence are never headings or checkboxes. No PR Plan, Key Decisions, or DAG.
+No required Why heading. Optional why footnote only (not a `##`). Pick2 file plan stays how-first; missing Why heading does not block.
+
+## Card
+
+The 5 lines a person reads first: right after `# {slug}` and one blank line, then a blank line before `## Goal`.
+
+```markdown
+WHAT   notes export --json prints a JSON array
+WHY    scripts parse notes without the table
+RISK   empty notebook must print []
+TOUCH  src/cli.ts, src/export.ts (+ test)
+DONE   bun run test; --json | JSON.parse ok
+```
+
+- Labels `WHAT`, `WHY`, `RISK`, `TOUCH`, `DONE`, in that order, each padded to 7 columns so the text starts at column 8. The text is never empty.
+- Each line is at most 120 characters.
+- The card sums up Goal and Steps for a person reviewing at a glance. It does not replace `## Goal`, which tools and `/review-plan` read.
+- Fresh writes only. An update to a plan saved without a card stays valid.
+- Each failing line has its own deny: `start with the 5-line card after the title: WHAT, WHY, RISK, TOUCH, DONE`, `card line 2 must start with WHY`, `card line 4 (TOUCH) is 131 characters; the limit is 120`.
+
+## Size
+
+At most 100 lines above `## Previous mistakes`, frontmatter included. More than that is two or more slices: write a roadmap with `/write-roadmap`. A fresh save over the cap is denied with `131 lines above ## Previous mistakes, the cap is 100; split it into a roadmap (/write-roadmap)`. An update over 100 lines is denied only when it is longer than the saved file, so a legacy plan can still flip boxes. `## Previous mistakes` never counts: it grows during the run.
+
+## Previous mistakes
+
+This plan's own log of what went wrong. Last heading, after Verify, no checkboxes. A new plan writes `(none)`.
+
+- Entry: `- {source}: {what was wrong} → {what changed}`, optionally ending ` (lesson: {slug})`.
+- `source`: `feedback` (the user sent the plan back), `verify` (a Verify or test failed after a fix), `review` (an accepted `/review-plan` finding), `premise` (an assumption turned out wrong), `decision` (a choice made under away instead of asking).
+- A decision entry is `- decision: {question} → {choice}, because {why}`.
+- Append-only. A save that edits or drops an existing entry is denied and names the entry.
+- An entry that will happen again on other tasks also becomes a lesson: `node_modules/@workerstack/repo/references/lessons.md`.
+
+## Revisions
+
+A Write of a saved plan updates that file: same path, serial, and `created`. The given `status` and `[x]` boxes are kept. A body without frontmatter keeps the saved frontmatter. An Edit of a saved plan is checked against the text it would produce and runs as sent when valid. Never save a revision as a new plan.
+
+## Checkbox grammar
+
+- Open: `[ ]` (space in box required)
+- Done: `[x]` (accept `[X]`, write `[x]`)
+- Line: `^{id} [ ] {text}$` with optional 0–2 space indent
+- `{id}` = `N` / `N.M` / `N.M.K` (digits + dots). **Not** `1. [ ]`. **Not** GitHub `- [ ]`
+- Fresh plans: all `[ ]`, never `[x]`
+- Marking done: only flip the box. No renumber, delete, or rewrite leaf text
+- Depth 2 default (`N` phase + `N.M` leaf). 3rd level only if a leaf would itself be a mini-plan
+- Every phase `N` has ≥1 leaf `N.M`. The session agent **executes leaves**. Roll up: all children `[x]` ⇒ parent `[x]`
+- Verify = last numbered phase, same grammar
+- A Read leaf (``N.M [ ] read `principle-…` ``) sits in the phase it gates, before the leaves it governs. A phase whose every leaf reads a principle gates nothing and is denied on a fresh write: `phase 1 only reads principles; move each read into the phase it gates`. An update is denied only when the saved file had no such phase. Verify reads `principle-prove-it-works` beside its command leaves
+- Done plan: every checkbox `[x]`, `status: done`
+
+## Parallel phases
+
+A phase line may end `(parallel: <path>, <path>, …)`, listing every file its leaves write, repo-relative and comma-separated:
+
+```markdown
+2 [ ] Parser (parallel: src/parse.ts, src/parse.test.ts)
+2.1 [ ] add the parser in src/parse.ts
+3 [ ] Printer (parallel: src/print.ts, src/print.test.ts)
+3.1 [ ] add the printer in src/print.ts
+```
+
+- Adjacent parallel phases form a group whose phases can run at the same time. A group needs two or more phases, and no two of its lists may share a path.
+- Paths are compared as written, never resolved on disk; `\` reads as `/`, so `src\cli.ts` and `src/cli.ts` are the same path.
+- Denies: `parallel phases 2 and 3 both list src/cli.ts; parallel phases need disjoint files`, `phase 4 is parallel alone; parallel needs two or more adjacent phases`, `phase 2 is parallel with no files; list the files it writes after parallel:`.
+- Under a review strategy a group runs at once as `references/review-loop.md` says; `bun repo phase-files <plan> <phases>` checks that each phase wrote only its list.
+- Every path a parallel phase's leaves name sits in its list. The save cannot see that; `/review-plan` checks it.
+
+## Prose vs steps
+
+| Section | Amount |
+|---|---|
+| Goal | 1–3 sentences. What “done” means. |
+| Usage | What a person or agent types and sees once the plan lands: each new or changed command, flag, output, error message, or file, in fenced blocks, with the before for each changed one. Internal steps nobody types or reads need none. A plan with no visible change writes one line: `No visible change:` and why. |
+| Context / Constraints / Watch-outs | bullets only. Watch-outs: non-obvious footguns; empty allowed (`(none)`). A new plan that names a file a lesson matches cites that lesson path in Watch-outs, or the save is denied. Context includes `Task type:`, `Named checks:` from `node_modules/@workerstack/repo/references/scope.md` ## Types, and a skip-with-reason when a named check is dropped. |
+| Steps | bulk of the file; each leaf = one coherent edit or one file-level action |
+| Verify | 1–5 runnable leaves (cmd or observable) |
+
+Tests live in Steps (not a new heading). New behavior or a bug: a failing test leaf before the impl leaf. Other behavior change: a test leaf immediately after the impl leaf. Docs, rename-only, config-only, generated: no test leaf. Verify is the end gate (project cmd or named subset), not a substitute for those leaves. Do not re-run the whole suite after every leaf unless it is cheap.
+
+Thinker cites **repo-relative paths** (`cli/scripts/x.ts`). The plan's worktree `{serial}-{name}` does not exist until the serial is saved, so `/implement-plan` applies each path inside that worktree; an absolute path under the root is accepted too and names the same path there. Leaves must be implementable without re-planning. Product fork → pick the narrowest default, state it under Constraints, still emit steps.
+
+## Validation checklist
+
+- filename matches new stamped regex or legacy unstamped; new writes unpadded + stamp (`1-foo-20260826T143000Z.md` not `0001-foo.md`); serial int equals leading digits; `name` equals slug after stripping optional trailing `-\d{8}T\d{6}Z`
+- frontmatter `serial` line matches `^serial: [1-9][0-9]*$` (unpadded decimal ≥ 1; reject `0001`, `"0001"`, `0`, `01`)
+- frontmatter keys: `serial`, `name`, `status`, `reviews`, `created`, `source`, `strategy`. `strategy` is required and is `default`, `review-fast` or `review-deep`; a save without it, or with another value, is invalid. Optional `mode` is `ask`, `auto` or `away`; another value is invalid. `reviews` matches `^(0|[1-9][0-9]*)$`, is `0` on a fresh write, is not lowered or removed on an update, and is ≥ 1 for a change into `in-progress`; a legacy plan without it stays valid. Optional `commit:` is a Conventional Commits subject (`type(scope): subject`, scope optional, imperative lowercase, no trailing period). A new plan includes it. A plan with no `commit` key stays valid. A present `commit` that is not that subject is invalid
+- `status` ∈ `ready` | `in-progress` | `done` | `blocked`; `created` `YYYY-MM-DDTHH:MM:SSZ` (new writes) or legacy `YYYY-MM-DD`; `source` ≤120
+- headings in order only; no extra `##`; `## Usage` right after `## Goal`, required on a fresh write and optional on an update to a plan saved without it, holding a fenced block or a `No visible change:` line; lines inside code fences are never headings or checkboxes; `## Previous mistakes` last and required on a fresh write, entries valid and append-only on an update; fresh write cites every matched lesson in Watch-outs; no required Why heading (optional footnote only)
+- ≥1 `N.M [ ]` leaf; every phase has ≥1 leaf; Verify is last numbered phase
+- `PLAN_NAME:` dropped wherever it sits above the first `##` outside a fence
+- ≤100 lines above `## Previous mistakes`, frontmatter included; an update over 100 only when no longer than the saved file
+- no phase whose every leaf reads a principle, on a fresh write or on an update whose saved file had none
+- `(parallel: …)` phases come in adjacent groups of two or more, each with a non-empty list, lists disjoint after `\` → `/`
+- checkbox grammar (`N [ ]` / `N.M [ ]` / `N.M.K [ ]`); no `- [ ]`; no `1. [ ]`
+- fresh write: the card right after `# {slug}` and one blank line, `WHAT` `WHY` `RISK` `TOUCH` `DONE` in order, padded to 7 columns, text non-empty, each line ≤120 characters; zero `[x]` / `[X]`; Goal 1–3 sentences; Context/Constraints/Watch-outs bullets; Context includes `Task type:`, `Named checks:`, and a skip-with-reason when a named check is dropped; frontmatter includes `commit:` and `strategy:`; Verify 1–5 leaves
+
+## Worked example
+
+File: `.tmp/repo/plans/1-notes-export-json-20260826T143000Z.md`
+
+````markdown
+---
+serial: 1
+name: notes-export-json
+status: ready
+reviews: 0
+created: 2026-08-26T14:30:00Z
+source: "add --json to notes export"
+commit: feat(notes): add --json to notes export
+strategy: default
+---
+
+# notes-export-json
+
+WHAT   notes export --json prints every note as one JSON array
+WHY    scripts read notes without parsing the text table
+RISK   an empty notebook must print [], and the table stays the default
+TOUCH  src/cli.ts, src/export.ts (+ test)
+DONE   bun run test passes; notes export --json | JSON.parse exits 0
+
+## Goal
+`notes export --json` prints every note as one JSON array on stdout, so scripts read notes without parsing the text table. The text table stays the default.
+
+## Usage
+Before:
+
+```console
+$ notes export --json
+error: unknown flag --json
+```
+
+After:
+
+```console
+$ notes export --json
+[{"id":1,"title":"groceries","updated":"2026-08-26T14:00:00Z"}]
+$ notes export
+1  groceries  2026-08-26 14:00
+```
+
+## Context
+- Task type: feature
+- Named checks: failing test before impl; read `principle-test-behavior-not-implementation`
+- `/home/ecomet/Development/example-app/src/cli.ts` parses flags; `/home/ecomet/Development/example-app/src/export.ts` prints the table
+- Rejected: a separate `notes json` command, which splits one export into two
+
+## Constraints
+- Keys are `id`, `title`, `updated`, in that order; `updated` is ISO 8601 UTC
+- No new dependency
+
+## Watch-outs
+- An empty notebook prints `[]`, not nothing
+
+## Steps
+1 [ ] Failing test
+1.1 [ ] read `principle-test-behavior-not-implementation`
+1.2 [ ] in `/home/ecomet/Development/example-app/src/export.test.ts`, `notes export --json` on two notes prints a two-element array with those keys, and on none prints `[]`
+1.3 [ ] run `bun run test export`; the new cases fail on the unknown flag
+2 [ ] Implement
+2.1 [ ] parse `--json` in `/home/ecomet/Development/example-app/src/cli.ts`
+2.2 [ ] in `/home/ecomet/Development/example-app/src/export.ts`, print `JSON.stringify` of the notes when `--json` is set
+2.3 [ ] run the test from 1.3; all pass
+
+## Verify
+3 [ ] Verify
+3.1 [ ] read `principle-prove-it-works`
+3.2 [ ] `bun run test` passes
+3.3 [ ] `notes export --json | node -e "JSON.parse(require('fs').readFileSync(0, 'utf8'))"` exits 0
+
+## Previous mistakes
+(none)
+````

package/references/review-loop.md

@@ -0,0 +1,48 @@
+---
+tags: [review-loop]
+---
+
+# Review loop
+
+Read this when the plan's `strategy` is `review-fast` or `review-deep`. You are the reviewer. An implementer agent writes the product code. Values: `plan-format.md`. Gate rules: `hooks.md`.
+
+## Start
+
+The first action, at start or on resume, is a plan save (a status or box edit). It stamps the session. Until it runs, the gate does not know this session reviews.
+
+## Phases
+
+- Phases run in order; each goes to one implementer: `implementer-fast` first on `review-fast`, `implementer-deep` on `review-deep` (`implementerOf(strategy, 1)`). A parallel group spawns its implementers in one message. Each brief lists its phase's files as the only ones it writes; that list is guidance, and `bun repo phase-files` is the check. A parallel implementer runs only its phase's tests, never `sync` or the full suite. After the round, run `phase-files`, then stage each passed phase by name, one at a time, and run the full suite once. A failed phase reruns alone.
+- The brief is that phase's leaves, plus the findings to fix. The agent file holds the rest of its rules. The spawn prompt names the plan's worktree path (`<root>/.worktrees/{serial}-{name}`): a Claude subagent starts in the parent's cwd, the root, where the gate denies a product write. Run `bun repo worktree add {serial}-{name}` first if it is missing.
+- A Read leaf in a phase goes to that phase's implementer with the brief: it reads the principle, you do not. You read only `principle-prove-it-works`, before Verify.
+- Your own product writes are denied. The plan, the journal and `.tmp/` stay writable.
+- Only you tick boxes and write the journal. Write one entry per round.
+
+## Review
+
+- Read the implementer's report: `changed:`, `tests:`, `status:`. A missing report or a status other than `done` is a failed round.
+- Read the real `git diff` in the worktree and rerun the phase's tests yourself. Do not trust the report.
+- Send findings back to the same implementer. Continue it where the harness allows. Otherwise respawn it with the findings and the current diff.
+- A phase passes when the diff matches its leaves and your test run is green.
+
+## Baseline
+
+The index is the baseline. After a phase passes, stage only the implementer's `changed:` files that the phase's leaves name: `git add -- <files>`. Never `git add -A` on this shared tree. The next phase's `git diff` (unstaged) then shows only that phase. The implementer never stages or commits.
+
+## Escalate
+
+After 3 failed rounds, a missing report or a status other than `done`, spawn `implementerOf(strategy, 2)` fresh with the findings. If that one fails the same way, set the plan `blocked` and add a `- blocked:` journal entry.
+
+## Commit
+
+One commit at the end, in the worktree, as `implement-plan` says; `/commit` then runs `finish` from the root. It holds only this plan's files.
+
+## Dumps
+
+You and the implementer send big output through `bun repo job`. The gate rewrites a plain test run to `--job test`. Use `--job exec` for any other large command. Neither of you spawns scout for the implementer's work.
+
+## Not enforced
+
+The gate denies your product writes on claude (Grok runs through it) and codex.
+
+Not enforced on: antigravity, cursor. There, make no product writes yourself; every product edit goes through the implementer.

package/references/roadmap-format.md

@@ -0,0 +1,104 @@
+# Roadmap format (SSOT)
+
+Ordered program of child plans. Not a plan, a handoff, or a design doc.
+
+## Path
+
+`.tmp/repo/roadmaps/{serial}-{slug}-{YYYYMMDDTHHMMSSZ}.md`
+
+- **serial:** unpadded decimal int ≥ 1. Never `0001`.
+- **filename:** `^[0-9]+-[a-z0-9]+(-[a-z0-9]+)*-\d{8}T\d{6}Z\.md$`
+- Create mints the next serial. A later write of an existing file keeps that path and serial. The hook validates the update and the host writes it. An Edit of a saved roadmap is checked against the text it would produce, and a valid one runs as sent.
+- Child plans stay in `.tmp/repo/plans/`.
+
+## Frontmatter
+
+```yaml
+---
+serial: 1
+name: auth-program
+status: draft          # draft | locked | in-progress | done | blocked
+reviews: 0             # settled /review-roadmap rounds; never lowered or removed
+created: 2026-10-25T18:00:00Z
+source: "<≤120 chars>"
+strategy: default      # default | review-fast | review-deep
+mode: away             # optional: ask | auto | away
+---
+```
+
+`draft` → `locked` → `in-progress` → `done` | `blocked`.
+
+`strategy` is required: `default`, `review-fast` or `review-deep`. It means what it means in a plan (see `plan-format.md`). On a roadmap it is the default its slices copy: each slice plan starts with the roadmap's value, unless that slice's scope argues for another. A save with no `strategy` or an unknown value is denied with `strategy: default|review-fast|review-deep`. A body-only save may send a bare `strategy: {value}` line above `ROADMAP_NAME:`, and a save that omits it keeps the saved value. The person can change the value with `y <strategy>` when approving, or `h fast` / `h deep` when handing off.
+
+`mode` is optional: `ask`, `auto` or `away`, as in a plan (see `plan-format.md`). A body-only save may send a bare `mode: {value}` line above `ROADMAP_NAME:`, and a save that omits it keeps the saved value. Another value is denied with `mode: ask|auto|away`.
+
+`/implement-roadmap` refuses `draft`.
+
+`reviews` counts the `/review-roadmap` rounds whose findings the writer settled. It starts at `0`, never goes down, and once present cannot be removed. A body-only save sends it as a bare `reviews: {n}` line above `ROADMAP_NAME:`, and a save that omits it keeps the saved count. Moving into `locked` needs `reviews` ≥ 1; a missing key counts as 0. A roadmap already past `draft` without the key stays editable.
+
+## Body (this order only)
+
+A roadmap is pointers: what each slice ships, in order. Decisions, Usage, context and the why of each slice go into that slice's plan, which `/implement-roadmap` writes.
+
+```
+# auth-program
+
+WHAT   auth ships as two slices: reserved types first, then the commit diff pass
+WHY    later slices add skills, so their names must be reserved first
+RISK   init and INDEX drift apart when a name changes
+TOUCH  init reserved names, INDEX, commit skills
+DONE   both slices done; repo init lists auth-types
+
+## Order
+1 [ ] auth types: Reserved names list the new skills.
+      Location: /home/me/app/.tmp/repo/plans/14-auth-types-20261025T165531Z.md
+2 [ ] commit diff pass: Commit skills strip narrating comments.
+
+## Verify
+3 [ ] Verify
+3.1 [ ] both child plans have finished Verify
+
+## Previous mistakes
+(none)
+```
+
+- **Card:** the 5 lines after `# {slug}` and one blank line, as in a plan (`plan-format.md`): WHAT, WHY, RISK, TOUCH, DONE, text at column 8, at most 120 characters each.
+- **Headings:** `## Order`, `## Verify`, `## Previous mistakes`, nothing else. Lines inside a code fence are never headings. A new roadmap with any other `##` is denied with `a new roadmap has only ## Order, ## Verify and ## Previous mistakes; move ## {heading} into the slice plans`.
+- **Slice:** one line, `N [ ] {title, 2–6 words}: {one sentence}`. The sentence says what that slice's plan ships. A slice that breaks it is denied with `slice N needs "N [ ] {title, 2–6 words}: {one sentence}"`.
+- **Location:** an optional indented line under the slice. Omit it in a draft. `/implement-roadmap` sets it to the absolute plan path `/write-plan` reported; a slice that has one does not get a second plan. A relative `.tmp/repo/plans/{file}` also resolves.
+- `[x]` only after that child plan's Verify is done.
+- **Verify:** 1–5 runnable program gates, same `N.M [ ]` grammar as plans.
+- **Previous mistakes:** `(none)`, or one entry per line. Append-only.
+- **Cap:** at most 60 lines above `## Previous mistakes`, frontmatter included, `Location:` lines not counted, so filling them in mid-run never trips it. A fresh save past 60 is denied with `{n} lines above ## Previous mistakes, the cap is 60; move detail into the slice plans`; an update only when it grows past both 60 and the saved file.
+
+A roadmap has at least two slices. One slice is `/write-plan`.
+
+### Roadmaps saved before pointers
+
+A roadmap saved with `## Goal` keeps that shape and its rules for every later save, even one that deletes `## Goal`: the saved file decides. Its headings are `# {slug}`, `## Goal` (1–3 sentences), `## Usage`, `## Context`, `## Decisions`, `## Order`, `## Watch-outs`, `## Verify`, `## Previous mistakes`; Context, Decisions and Watch-outs are bullets, each decision naming the rejected alternative. Each slice is `N [ ] Title: {2–6 words}` with indented `Goal:` (one sentence), `Why:` (one or two sentences) and the optional `Location:`. It has no card and no cap. One saved before `## Usage` or `## Previous mistakes` existed stays valid without them.
+
+## Previous mistakes
+
+Mistakes about the program: slice order, slice boundaries, a premise later slices lean on, and on an old-shape roadmap a Decision that turned out wrong. A mistake inside one slice stays in that child plan.
+
+```
+- {feedback|verify|review|premise|decision|slice}: {what was wrong} → {what changed}
+- decision: {question} → {choice}, because {why}
+```
+
+- `feedback`, `review`, `premise` and `decision` mean what they mean in a plan. `verify` is a failed program Verify gate.
+- `slice` is roadmap-only: what child plan N found that changed the Order or a later slice (or a Decision on an old-shape roadmap). The same save makes that change.
+- Optional ` (lesson: {slug})` at the end when the entry is also a lesson.
+- `/implement-roadmap` copies each entry that touches a slice into that slice's plan Watch-outs, and promotes entries that outlive the program to lessons before `done`.
+
+## Validation checklist
+
+- filename stamped and unpadded; `name` equals the slug
+- `status` is one of the five values; `source` ≤120; `strategy` is one of the three values; `mode`, when present, is `ask`, `auto` or `away`
+- a new roadmap: the card; only Order, Verify and Previous mistakes, in that order; ≥2 one-line slices, title 2–6 words, one sentence; at most 60 lines above Previous mistakes without `Location:` lines
+- an update keeps the saved file's shape; an old-shape one keeps the old checks: headings in order, Goal 1–3 sentences, bulleted Context, Decisions and Watch-outs, ≥2 slices each with Title (2–6 words), one-sentence Goal and Why (1–2 sentences)
+- Location, when present, is the absolute plan path (a relative `.tmp/repo/plans/{file}` still resolves)
+- Verify has 1–5 leaves
+- `## Previous mistakes` is last, required on a fresh create, and keeps every saved entry unchanged and in order
+- `reviews` is a whole number, never lower than the saved one; `locked` needs at least 1
+- a fresh create is `draft`, `reviews: 0`, and has no `[x]`

package/references/rtk.md

@@ -0,0 +1,27 @@
+---
+tags: [rtk]
+---
+
+# RTK
+
+Shell stdout compression. PreToolUse: Bash → `rtk <cmd>`. Not Read/Grep/Glob/prompts/images.
+
+Grok PostToolUse is observe-only — do not attempt output scrub; compress via RTK / spawn / isolation facts only.
+
+## Commands
+
+ls · tree · read · smart · git · gh · glab · clasp · aws · psql · pnpm · err · test · json · deps · env · find · diff · log · dotnet · docker · kubectl · oc · summary · grep · rg · init · wget · wc · gain · cc-economics · config · jest · vitest · prisma · tsc · next · lint · prettier · format · playwright · lightpanda · cargo · npm · npx · curl · discover · session · telemetry · learn · run · proxy · pipe · trust · untrust · verify · ruff · pytest · mypy · rake · rubocop · rspec · pip · go · gt · golangci-lint · gradlew · mvn · hook-audit · rewrite · hook · help
+
+**git:** diff · log · status · show · add · commit · push · pull · branch · fetch · stash (list show pop apply drop push) · worktree
+**cargo:** build · test · clippy · check · install · nextest
+**go:** test · build · vet
+**docker:** ps · images · logs · compose (ps logs build)
+**gh:** pr · issue · run · repo
+**clasp:** login · logout · create · clone · pull · push · status · open · run · deploy · logs · setting
+
+Flags: `-v`/`-vv`/`-vvv` · `--ultra-compact` · `--skip-env` · `-h` · `-V`
+
+Unknown cmds passthrough. `rtk run` unfiltered.
+
+**playwright:** test-runner family only — not the browser rail.
+**lightpanda:** browser-rail CDP via `bun repo browser` (not MCP, not env).