@workit-dev/pi 0.0.1 → 1.0.0

package/skills/workit-fanout/references/brief.md

@@ -0,0 +1,141 @@
+# Worker brief template
+
+`workit fanout brief <slice>` renders this brief from the plan, the standing
+orders in force (`workit ledger standing list`) and the slice's scratch dir;
+pass its output verbatim. The template below is what it fills in. Every field
+is required. A brief with an empty field is not spawned. Point to files and
+ledger rows instead of pasting their content. Size the slice so the worker
+finishes it in about 150k tokens of context; split a larger one first.
+
+```md
+MODE: <new | resume (a replacement continuing a branch with commits)>
+WORKER: <slice id: a spawn prompt that names it binds that worker on OpenCode>
+GOAL: <one observable outcome, in the user's terms>
+SCOPE: <file-scope manifest: the globs this worker may write; everything else is read-only>
+  branch: <type>/<slug>   base: <trunk or parent branch>
+CONTEXT: <pointers: spec section, ledger decisions, the neighbour file to imitate>
+ACCEPTANCE:
+  - Given <state>, When <action>, Then <observable result>
+VERIFY: <exact commands, e.g. `workit check test`, the verify-<app> feature to drive>
+TIER: <mundane | standard | hard: how much model the slice needs>
+TIMEBOX: <wall clock, N tool calls (hard: 180, else 120) and the call by which the full gates ran (60%); past it without a new commit you will be replaced>
+SCRATCH: <your own temp dir: the one `fanout worktree create` printed, else `mktemp -d`; never a shared path>
+FORBIDDEN: <no edits outside SCOPE; no new dependencies; ...>
+FAN-IN: <one PR per slice: no rebase, retarget, merge or force-push | integration: merge the integration tip before reporting, nothing else>
+REPORT: branch, head SHA, files changed, each VERIFY command with its exit code,
+  each ACCEPTANCE line met / not met, rulings you made (`workit ledger ruling`),
+  anything out of scope as a follow-up, not a diff.
+STANDING: <the standing orders, verbatim: `workit ledger standing add` records each one>
+WORKTREE: <the path `workit fanout worktree create <slice>` made; the worker runs `workit <verb> --cwd <it> …` there>
+  <identity line, per the lead's host: see "Identity and git rules per host" below>
+```
+
+## Worked example
+
+```md
+MODE: new
+WORKER: usage-endpoint
+GOAL: `GET /v1/usage` returns the workspace's run count per UTC day for the last 7 days.
+SCOPE: src/routes/usage.ts, src/queries/usage.ts, test/usage.test.ts
+  branch: feature/usage-endpoint   base: main
+CONTEXT: spec docs/usage/spec.md "Behavior"; ledger decision "counts are per UTC day";
+  imitate src/routes/runs.ts for auth and error shape.
+ACCEPTANCE:
+  - Given 3 runs today and 1 yesterday, When GET /v1/usage, Then the last two entries are {"runs":1} and {"runs":3}
+  - Given no auth header, When GET /v1/usage, Then the status is 401
+VERIFY: `workit check test`; verify-api feature "usage"
+TIER: standard
+TIMEBOX: 45 minutes, 120 tool calls (run your full VERIFY gates by call 72)
+SCRATCH: ~/.local/state/workit/worktrees/app/usage-endpoint/.workit-scratch
+FORBIDDEN: no edits outside SCOPE; no schema migration; no new packages
+FAN-IN: one PR per slice. Never rebase, retarget, merge or force-push: the lead owns topology.
+REPORT: as in the template
+STANDING: conventional commits; no comments that restate code; ask nothing, record rulings instead
+WORKTREE: ~/.local/state/workit/worktrees/app/usage-endpoint  (made by `workit fanout worktree create usage-endpoint`; yours alone)
+```
+
+## Plan file
+
+`workit fanout plan <plan.json>` (keep it in `workit dir plans`) records the slices before any spawn. Each
+slice carries the brief fields the plan checks (goal, scope, acceptance,
+verify, forbidden must be filled; tier is mundane, standard or hard). `base`
+defaults to the trunk, or to the branch of a single `dependsOn` slice (a
+stack); `worktree` defaults to `<state>/worktrees/<repo>/<id>` (`workit dir state`). `owns` claims a shared
+file another slice's glob also matches. Globs that match no file yet are compared
+through a sample path. Use `/` as the separator; a backslash only escapes
+literal brackets: `"app/\\[id\\]/page.tsx"`. A `reason` (`explore`, `parallel`, `backstop` or `high-risk-verify`) is rendered as the brief's `REASON:` line and is
+required unless the workspace sets `delegation` to `lead-orchestrates`. A `timebox` such as `45 minutes`
+is the slice's STUCK threshold in `workit fanout status`. `"fanIn":
+"integration"` (with an integration branch as `trunk`) is the one-PR mode in
+`orchestration.md`; the default `"prs"` lands one PR per slice.
+
+```json
+{
+  "name": "usage",
+  "trunk": "main",
+  "slices": [
+    {
+      "id": "usage-endpoint",
+      "branch": "feature/usage-endpoint",
+      "tier": "standard",
+      "scope": ["src/routes/usage.ts", "src/queries/usage.ts", "test/usage.test.ts"],
+      "owns": ["package.json"],
+      "goal": "GET /v1/usage returns the run count per UTC day for the last 7 days",
+      "acceptance": ["Given no auth header, When GET /v1/usage, Then the status is 401"],
+      "verify": ["workit check test"],
+      "forbidden": ["no edits outside SCOPE", "no rebase or force-push"],
+      "reason": "parallel",
+      "context": "docs/usage/spec.md Behavior",
+      "timebox": "45 minutes"
+    },
+    {
+      "id": "usage-docs",
+      "branch": "docs/usage",
+      "tier": "mundane",
+      "dependsOn": ["usage-endpoint"],
+      "scope": ["docs/usage/**"],
+      "goal": "The API guide documents GET /v1/usage",
+      "acceptance": ["Given the guide, When a reader looks up usage, Then the response shape is shown"],
+      "verify": ["workit check docs"],
+      "forbidden": ["no edits outside SCOPE"]
+    }
+  ]
+}
+```
+
+## Identity and git rules per host
+
+`workit fanout brief` renders the identity line, the model lines and RULES 1
+and 3 for the worker's host: `--host <host>` (claude_code, codex, opencode,
+cursor, pi), else the lead's (`WORKIT_HOST`, or the host's own session
+variable). With no known host it warns on stderr and names the valid ones.
+RULE 3 carries the host's concrete Co-Authored-By line as a `--trailer`.
+
+| Lead's host | Identity line | RULES 1 and 3 |
+| --- | --- | --- |
+| Claude Code | `Session: your env already has WORKIT_SESSION_ID (the lead's id)`; no `export`, no hand-minted id (SubagentStart issues `<lead>:<agent id>` only to verifiers and reviewers, never to an implementer, so the worker's commits carry the lead's id) | `workit git branch <branch> --base <base>`, `workit git commit -m <msg> -- <paths in SCOPE>` in the Workit worktree (the spawn hook drops `isolation`); only a host-isolated `.claude/worktrees/agent-<id>` takes plain git, as its SubagentStart text says, since that isolation refuses a git wrapper |
+| OpenCode, Pi, Codex | `Session: your host already sets WORKIT_SESSION_ID in your shell`; export nothing (the host derives the id and an export cannot replace it) | `workit git branch <branch> --base <base>`, `workit git commit -m <msg> -- <paths in SCOPE>` |
+| Cursor, CI, a plain terminal | `export WORKIT_SESSION_ID=<lead>-w-<slice>` (`+try<n>` for a race attempt): declared, not checked | the same `workit git` forms |
+
+Once `workit fanout worktree create <slice>` made the worktree, the brief's
+WORKTREE line names it and RULES 1 and 3 run against it on every host:
+`workit git --cwd <worktree> commit …`, `workit check --cwd <worktree> <name>`,
+one verb per call. The worktree is already on the branch (MODE new or resume),
+so no branch command comes first. Without one, `MODE: resume` is
+`git switch <branch>` (the branch exists), then continue from its head. A race
+attempt (`--attempt <n>`) follows its host's row with the branch
+`<branch>-try<n>`.
+
+## Worker rules (`workit fanout brief` appends them as RULES)
+
+1. Work only in WORKTREE, already on the branch, one verb per call against it
+   (`workit <verb> --cwd <worktree> …`); Workit's hooks deny an implementer's change
+   outside it. With no worktree made yet: create the branch (`MODE: new`) or
+   `git switch` to it (`MODE: resume`), as the table above says.
+2. Decide ambiguities yourself and record them:
+   `workit ledger ruling "<what>" --why "<why>" --cost-if-wrong "<cost>"`.
+   Stop only for an irreversible action, a security-sensitive one, or a side
+   effect outside the worktree.
+3. Commit with `workit git --cwd <worktree> commit -m "<msg>" --trailer "<host's Co-Authored-By>" -- <paths in SCOPE>`;
+   push only if the brief says so.
+4. Never record a verdict on your own work.

package/skills/workit-fanout/references/orchestration.md

@@ -0,0 +1,169 @@
+# Running a fanout
+
+How the lead picks models, keeps workers flowing, retries, races, verifies
+and fans in. Workit records and checks; the host's own subagents run the work.
+
+## TIER to model
+
+TIER is a field of each slice and of its brief. Role models come from the
+workspace (`models.roles`; `fanout.tierModels` still feeds the implementer
+tiers) and, on Claude Code, built-in defaults: the brief has a `model:` line
+(with `effort:` when set) under TIER and a `verifier:` line; `workit fanout
+status` names the model next to each spawnable slice; `workit models show
+[--role r] [--host h] --json` lists every role (decider, implementer tiers,
+verifier, reviewer, explore, babysit). Pass exactly that `model` (and `effort`
+where the host's spawn call takes one) on the spawn call: a subagent that
+passes none inherits your model. Scouting and PR babysitting use the `explore`
+and `babysit` roles. A role with no model (other hosts without config) runs
+on the host's model, and TIER only sizes the timebox and decides whether to
+race. Claude Code's built-in defaults, when nothing is configured:
+
+| Role or TIER | `model` on the Agent call |
+| --- | --- |
+| decider | `fable`, effort `high` |
+| hard | `opus` |
+| standard | `sonnet` |
+| mundane | `haiku` |
+| verifier | `sonnet` |
+| reviewer | `opus` |
+| explore, babysit | `haiku` |
+
+Claude Code and OpenCode also get the role's model set on the spawn by
+Workit; a configured one beats a `model` you pass unless
+`models.allowLeadOverride` is true. A general spawn takes
+`models.roles.default`, or the role its prompt's `ROLE: <role>` line names.
+`models.lead` (your own model) is advisory. `workit models show` marks each
+role `enforced` or `advisory` per host: on advisory, pass the model.
+
+## Rolling window
+
+Keep 4-6 workers in flight on Claude Code; elsewhere as many as the host runs
+in the background, never more than 6. Do not wait for a whole wave: when one
+worker finishes (its notification, or a new head or PR in `workit fanout
+status`), verify it, then spawn the next slice from `spawnable` in the same
+status output. A slice whose dependencies landed, or a stacked child whose
+parent is verified, appears there by itself.
+
+## Retry, then escalate
+
+A slice is retried when it is STUCK, its worker exits without meeting
+ACCEPTANCE, or its verdict fails. Stop the worker and observe that it exited.
+Release its worktree: `workit fanout worktree release <slice>` (it records
+`git status` first), and create it again for the retry. Then spawn one fresh
+worker with `workit fanout brief <slice> --mode resume`: same branch, and the
+brief points at its head and its ledger rows (last report, verdicts,
+rulings). If the retry fails too, escalate instead of a third worker:
+re-slice it smaller (`workit fanout plan` again), take it over yourself, or
+report the gap to the user.
+
+## Stuck calls: the decider
+
+A failed review gets one fix round and one recheck (the changed hunks only).
+If the recheck fails, or a worker and a reviewer disagree, spawn a decider
+instead of a third round. A decider is a fresh read-only agent, not the author
+or the reviewer. It returns three things: the options, a pick by
+reversibility (the option cheapest to undo wins a tie), and the exact change
+list. The fixer applies that list once, then one focused recheck follows.
+
+- Hard call (shared contract, security, migration): two deciders on different
+  models (Claude Code, OpenCode, Cursor: the `decider` role model and a
+  different `model` on the spawn, kept on a configured decider role only with
+  `models.allowLeadOverride`; Codex and Pi: one decider). If they disagree, you take the
+  more reversible option.
+- Record it: `workit ledger decision "<pick>" --by decider --why "<why it is
+  the more reversible>" --view "<decider A: view>" --view "<decider B: view>"`.
+  The row is listed as a decider call; it is never the user's answer to a
+  product choice and never a verdict.
+- A product choice, or authority nobody here has, is not a decider's call:
+  ask the user with your recommendation.
+
+## Race a hard slice
+
+When a hard slice has an uncertain approach and a cheap VERIFY, run 2-3
+attempts at once instead of retrying in series. `workit fanout brief <slice>
+--attempt <n>` gives each attempt its own branch (`<branch>-try<n>`), session
+and scratch dir. Each attempt needs its own worktree, and `fanout worktree
+create` makes only the slice's own one, so run the attempts one after another
+there on every host.
+Verify every attempt, keep the one with the best verdict (accepted first,
+then the fewest changed files, then the earliest), point the slice branch at
+it (`git branch <branch> <winner>`), have the verifier record the verdict on
+`<branch>` (same head), and delete the losing attempt branches.
+
+## Verification
+
+Follow the workspace `verification` setting (`workit grant show`); the
+worker never records a verdict on its own work.
+
+- `self` (the default): a verifier that wrote none of the slices records the
+  verdicts. A lead that authored none of the slices may record them in its
+  own session.
+- `independent`, and any slice at high risk: a separate verifier session
+  records them, never the lead's own; at high risk one verifier per slice,
+  plus a review panel (below). This is doctrine, not enforced: the ledger
+  only tells a branch's authors from everyone else, and a lead that wrote
+  none of it counts as independent.
+
+Which session id a verdict carries, per host:
+
+- Claude Code: subagents inherit your `WORKIT_SESSION_ID`, so the
+  SubagentStart hook names each `verifier` and `reviewer` its own session
+  (`<lead>:<agent id>`) and a token only that subagent sees, passed exactly as
+  `--session` and `--token`: the hook records the ids it issues, and only
+  those, with their token, are accepted. An `implementer` is issued
+  none: it keeps your id in its env for its workit commands and commits.
+- Codex: the `workit-verifier` and `workit-reviewer` agents get the same
+  issued `--session` and `--token` from SubagentStart; any other verifier passes
+  `--as verifier`.
+- OpenCode: a child session's shell already has
+  `WORKIT_SESSION_ID=<lead>:<child>`; Pi: a supervised worker's shell has
+  `<lead>:<worker session>`. Set nothing for a verifier there.
+- Cursor (no session id in the shell): the brief sets the verifier's
+  `WORKIT_SESSION_ID=<lead>:verifier-<random hex>`, a fresh suffix per
+  verifier. Cursor cannot check it: it is declared, not derived.
+- A worker's commits: on Claude Code the lead's `WORKIT_SESSION_ID` already in
+  its env (SubagentStart issues no implementer id; no export, so the
+  lead authored those commits: a verifier or reviewer records the verdict, not
+  the lead); on OpenCode, Pi and Codex the id the host already
+  puts in its shell; on Cursor, CI and a plain terminal the brief's
+  `export WORKIT_SESSION_ID=<lead>-w-<slice>` (see `brief.md`, "Identity and
+  git rules per host"). A verdict under an id you made up (`<lead>-v1`,
+  `<lead>:v1`) is refused as `forged_session` on Claude Code, Codex,
+  OpenCode and Pi.
+
+A batch verifier takes several slices on one surface in one session: for
+each branch it checks out the head, runs that slice's VERIFY, and records its
+own `workit ledger verdict <result> --branch <b> --how "<evidence>"`. Every
+verdict is keyed to that branch's head SHA; a slice whose head moves after
+it needs a new one. Batch at most what fits one context, about 4 slices.
+
+## Review panel (high risk only)
+
+At risk=high only, 2-3 fresh reviewers (read the `workit-review` skill's SKILL.md and follow it), each on a model
+other than the author's (Claude Code: a different `model`), each records
+`workit ledger verdict <result> --kind review --branch <b> --how "<findings>"`.
+Land only when every panel verdict passes. Below high risk a panel costs
+more than it finds.
+
+## Integration-branch fan-in (one PR)
+
+Only when the user wants one PR for the whole fanout:
+
+1. Cut the integration branch (`workit git branch <integration> --base
+   <trunk>`) and plan with `"fanIn": "integration"` and `--trunk
+   <integration>`. Planning refuses integration mode on origin's default
+   branch.
+2. Every brief then tells the worker to merge the integration tip into its
+   branch before reporting (the fast-forward rule). That merge is the only
+   one a worker makes, and only in this mode.
+3. Land each verified slice with `git merge --ff-only <slice-branch>` in the
+   integration checkout. Not a fast-forward (the tip moved since the worker
+   merged)? Resume the worker to merge again; never a merge commit of your own.
+4. `workit fanout check` gates against the integration branch; a slice whose
+   tip is on it reads as landed. When all have landed, ship the integration
+   branch as one PR (read the `workit-ship` skill's SKILL.md and follow it).
+
+## Stacks
+
+For stacked slices (`dependsOn` one parent): `workit stack plan <bottom> …
+<top>` once, then `workit stack sync` and `workit stack land`.

package/skills/workit-implement/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: workit-implement
+description: Build a requested change in small verified steps - follow local patterns, run real checks with workit check, prove it on the running app, hand verification to a non-author. Use for implement, build, add a feature, make the change, code it.
+---
+
+# Implement and prove it works
+
+## Steps
+
+1. Read before writing: the files you will touch, their callers, and one
+   neighbour that already does something similar. Copy its patterns, names and
+   error handling. Repo rules (AGENTS.md, CLAUDE.md, lint config) win.
+2. On the default branch? Branch first: `workit git branch --kind feature --slug <s>` (host note: a Claude Code host-isolated worktree uses plain `git switch -c`).
+   Tracking it? Judge once: `workit policy assess --judge risk=normal behavior=yes
+   product-choice=no plan=no` (trivial and no for a mechanical fix). Already
+   judged? Cite the plan with `--ref <path>` or record the decision; don't re-judge.
+3. Small steps that each leave the tree green. Behavior change: write the
+   acceptance as Given/When/Then and see a test fail first (read the `workit-bdd` skill's SKILL.md and follow it).
+   Mechanical change: the existing checks are enough. No tautological tests:
+   a test must fail if the behavior breaks, never restate the implementation.
+4. Run the real checks, local-first: the targeted test or check for the file
+   you touched while you work, then the full configured set once at the end
+   (`workit check test`, plus `lint` and `typecheck` when the repo has them),
+   not after every edit. Heavy work runs under one machine-wide lease: an ad-hoc
+   suite is `workit check --heavy -- <cmd>`, never a hand-made flock; a busy
+   lease waits and names its holder (`workit lock status`). A tool warning is a finding: fix it in this PR in the right layer, or record the false positive with evidence; pre-existing ones get their own PR.
+5. Prove the feature on its real surface with the project's `verify-<app>`
+   skill; none yet? Write one (read the `workit-verify-app` skill's SKILL.md and follow it). Tests show branch behavior,
+   not that the feature works. The report carries what you observed: a UI
+   change a screenshot or console/network check (chrome devtools or
+   agent-browser), an API a quoted real response. App not runnable? Say so
+   plainly, never claim success.
+6. Commit: `workit git commit -m "<type>: <what>" -- <paths>` (or `--all`); Co-Authored-By goes in with `--trailer "Co-Authored-By: <name> <email>"`. Host note: a Workit worktree (`workit fanout worktree create`) takes `workit git --cwd <worktree> …`; a Claude Code host-isolated one (`.claude/worktrees/agent-<id>`) takes plain git (its SubagentStart text: isolation refuses a git wrapper). One file holding two changes: stage one change's hunks with `workit git stage --patch <file>` (a `git diff -- <file>` cut to them), then `workit git commit -m "<msg>" --staged` (exactly the index); a path staged in part commits only its staged hunks (`--whole` takes the file).
+   No endpoint named? Stop here and state the next command. Hand delivery to
+   ship, which pushes and opens the PR with its body shape (read the `workit-ship` skill's SKILL.md and follow it), only
+   when that was requested, or the request implies delivery and the effective
+   endpoint in `workit grant show` is `pr`, `green` or `merged`; `green` and
+   `merged` keep babysitting. Otherwise it is `commit`.
+7. Verify as far as the review lane asks (`workit policy assess`, `workit pr
+   status`). Lane none: no verdict. Lane self: after `workit check test` passes,
+   record `workit ledger verdict tests-verified --self --how "<what you ran>"`;
+   it reads self-reviewed, never verified, and is enough. Focused, full, high
+   risk or `verification: self|independent` merges: one fresh verifier per PR after the last push, its own host-derived session (Claude Code: the `verifier` agent with the `model` (and `effort`) of `workit models show --role verifier`; Codex:
+   the `verifier` agent; OpenCode: a child session; Pi: a supervised worker),
+   never a hand-minted id. Before saying done, reconcile
+   every named deliverable against the target checkout and observe it (for a push:
+   `workit verify-delivery push`).
+
+Independent slices that could run in parallel: fan them out (read the `workit-fanout` skill's SKILL.md and follow it).
+One `implementer` slice: `workit fanout worktree create <slice>` before spawning,
+then `workit fanout brief <slice>`; no host isolation (Workit's hooks confine it).
+
+Stay inline by default (workspace `delegation: inline-first`). Hand work off
+only past the thresholds: an explorer after about 3 tool calls or 10k tokens
+of searching, parallel writers for 2 or more disjoint units of about 100+
+lines each.
+
+## Example
+
+Bad: "Done - added the --since flag, tests pass." (no check ran this turn; the
+flag was never invoked)
+
+Good: "Added `--since`. measured: `workit check test` exit 0;
+`mytool log --since 2d` printed 3 entries against the fixture repo. inferred:
+the GitLab path behaves the same (not run). Handed to the verifier agent."
+
+## Check
+
+```sh
+workit check test   # then, when the endpoint was a push or beyond: workit verify-delivery push
+```

package/skills/workit-retro/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: workit-retro
+description: Find repeated friction in recent sessions; propose cited fixes ranked by enforcer strength, never applied. Use for retro.
+disable-model-invocation: true
+---
+
+# Retro: turn repeated friction into enforcers
+
+User-invoked: offer it, never start it yourself. Run it after a session, PR,
+stack or fan-in, including ones that went well; a smooth session still shows
+where agents searched too long, worked around a tool or re-ran a check. Retro
+proposes and stops. Nothing changes until the user approves.
+
+1. **Scope.** Default: this repository's work since the last retro (its
+   `retro:` row in `workit ledger list --type decision`), else the last ~10
+   sessions. State the window in one line.
+2. **Read through workit, cheapest first.** Every finding cites these:
+   - `workit ledger list --last 200`: rulings, failed/self verdicts, handoffs,
+     check runs, CI reruns, `skill.loaded` rows (skipped skills: routing).
+   - `workit pr status --pr <n>` for each recent PR: threads, failing checks.
+   - `git log --oneline -50`, plus reverts and fixups after review.
+   - `workit knowledge lint`: today's AGENTS.md and need-based files.
+   - Session transcripts **only if the user opts in**, and only this
+     workspace's (`references/sources.md`). Never read other projects.
+
+   Cite by location (ledger row, PR, commit, session file and line). Never
+   copy secrets, tokens or personal data from any source into the report.
+3. **Group into classes.** Navigation cost (many searches before the right
+   file, a stale doc followed), repeated mistakes, workarounds (a hand-run
+   command where a verb exists, a skipped step), unstable checks (the same
+   `workit check <name>` red then green with no change). A class needs **2 or
+   more cited occurrences**; a one-off is not a learning.
+4. **Name the strongest enforcer that works**, strongest first: architecture
+   or types (the mistake cannot be written) > lint rule > configured check
+   (`.workit/checks.json`, `workit check <name>`) or CI job > test >
+   `CODING_STANDARDS.md` (judgment the reviewer reads) > AGENTS.md pointer
+   (navigation only). A mechanical rule gets a check, not prose: a check can
+   fail, a sentence cannot. From types to test, the proof is that the new
+   enforcer fails on the cited past mistake. A rule whose mistake can no
+   longer happen is deleted.
+5. **Upstream.** Friction a workit skill, verb or hook caused, or a rule for
+   agent behaviour, becomes an issue or PR on BrainerVirus/workit, not a host
+   memory (one host reads it). Never fork a local copy. Use a minimal synthetic
+   repro: no private repo name, path, code, ledger text, PR, thread or transcript.
+   Show the exact draft; once approved: `workit issue create --repo BrainerVirus/workit`.
+6. **Bloat guards.** AGENTS.md stays within 8 KB: each addition names what it
+   removes. Create `CODING_STANDARDS.md` or `GLOSSARY.md` only in the same
+   edit as its first real entry, never as a scaffold. Edit steering text by
+   `references/steering.md`; `workit knowledge lint` passes after the slice.
+7. **Report one ranked list, then stop** (save it under `workit dir retros`):
+   Accepted (proposed), Backlog, Dropped, each with its citations, enforcer
+   and reason. Each approved item becomes a slice to build (read the `workit-implement` skill's SKILL.md and follow it)
+   and ship (read the `workit-ship` skill's SKILL.md and follow it), a tracker issue, or `.out-of-scope/<concept>.md` when
+   rejected and likely to return. Record the user's answer so the next retro
+   starts there: `workit ledger decision "retro: <accepted ids>" --why "<window>"`.
+
+## Example
+
+Bad: "Agents seem lost in the build. Added 'read the build docs carefully' to
+AGENTS.md." One vague occurrence, no citation, a no-op line, auto-applied.
+
+Good: "Navigation, 3 occurrences (rulings 12, 19; PR #88 thread): agents sought
+check names in package.json, missing `.workit/checks.json`. Enforcer: AGENTS.md
+pointer, +74 bytes, minus the stale Commands paragraph (-210). Unstable check,
+2 occurrences (ledger rows 31, 44: `e2e` red then green on one SHA): a debug
+slice to fix the check. Approve?"
+
+## Check
+
+```sh
+workit knowledge lint   # exit 0 before and after each approved slice
+```

package/skills/workit-retro/agents/openai.yaml

@@ -0,0 +1,3 @@
+# Codex: user-invoked only (the counterpart of disable-model-invocation).
+policy:
+  allow_implicit_invocation: false

package/skills/workit-retro/references/sources.md

@@ -0,0 +1,35 @@
+# Session transcripts (opt-in, this workspace only)
+
+Transcripts are the most expensive source and can hold private material. Read
+them only after the user says yes to a question such as "Also read the last 10
+session transcripts for this workspace? (local files, read-only)". The default
+is no: the ledger, `pr status` and git are enough for most retros.
+
+## Where they live
+
+Typical locations; confirm each exists. Resolve the path from this workspace's
+absolute path, never with a wildcard across projects. If a host's layout
+differs from the one below, say so and skip it rather than search wider.
+
+| Host | Location |
+| --- | --- |
+| Claude Code | `~/.claude/projects/<folder>/*.jsonl`, one folder per path from `git worktree list`: the absolute path with every `/` and `.` replaced by `-`. Compute each folder name; never glob for it |
+| Codex | `~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl`. To filter, parse only line 1 (`session_meta`) and read only its `cwd` field; skip files whose `cwd` is not this workspace without reading or reporting anything else from them |
+| Cursor | `~/.cursor/projects/<workspace slug>/agent-transcripts/` |
+| Pi | `~/.pi/agent/sessions/--<workspace path, / replaced by ->--/*.jsonl` |
+| OpenCode | this project's sessions from `opencode session list`, read with `opencode export <id>` |
+
+Linked worktrees of the same repository count as this workspace; other
+repositories never do.
+
+## How to read them
+
+- Newest first, at most the agreed number of sessions.
+- On a host with subagents, one read-only analyst per lens, each returning
+  only cited occurrences (session file plus line or message index):
+  - navigation: searches and reads before the right file was found, stale docs
+    followed;
+  - tool economy: hand-run commands where a `workit` verb exists, repeated
+    reads of the same file, long outputs nobody used;
+  - repeated work: the same fix or check redone, a step undone later;
+  - request conflicts: instructions the agent had to reconcile or ask about.

package/skills/workit-retro/references/steering.md

@@ -0,0 +1,39 @@
+# Editing steering text (AGENTS.md, CODING_STANDARDS.md, skills)
+
+Steering text is paid for on every session that reads it. Each line must
+change what an agent does; everything else is cost.
+
+## Write
+
+- **Point, do not copy.** Link the file or name the command; never paste its
+  content. A pointer says when to follow it: "Read before editing a hook:
+  `docs/agents/hosts.md`".
+- **Say what done looks like.** "Run `bun run check`; it must exit 0" beats
+  "make sure everything works".
+- **Concrete over adjectives.** A command, a path, a number. Prefer the action
+  to take over a list of things to avoid.
+- **One rule, one home.** A rule with an enforcer (type, lint, check, test)
+  appears in steering text at most as a pointer to that enforcer. The same
+  sentence in AGENTS.md and CODING_STANDARDS.md is a defect
+  (`duplicate-rule`).
+- **Judgment goes to CODING_STANDARDS.md**, which the reviewer reads; only
+  navigation goes to AGENTS.md.
+
+## Cut
+
+- **No-ops.** Delete lines that would not change any behavior if removed:
+  "be thorough", "write clean code", "keep it concise", "follow best
+  practices".
+- **Session residue.** No notes about one session, no implementation detail
+  the code already shows, no `path:line` references (they go stale).
+- **Dead rules.** A rule whose mistake can no longer happen (a type or check
+  now prevents it) is deleted, not kept "for context".
+
+## Budget
+
+- AGENTS.md stays within 8 KB (`workit knowledge lint`, rule
+  `agents-budget`). A proposal that adds text names what it removes, or shows
+  the byte count still holds.
+- A need-based file (`CODING_STANDARDS.md`, `GLOSSARY.md`) is created in the
+  same edit as its first real entry. Headers-only or "TBD" files fail the lint
+  (`scaffold-file`).

package/skills/workit-review/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: workit-review
+description: Independent review of a diff, branch or PR - intent fidelity and standards as separate axes, test quality, blast radius - recorded as a non-author verdict. Use for review, code review, check this PR or MR, is this safe, blast radius.
+---
+
+# Review independently
+
+Review the candidate, never the author's summary of it. A session that wrote a
+commit on the branch cannot record a passing verdict: if that is you, hand the
+review to a fresh agent with its own host-derived session: Claude Code and
+Codex, the `reviewer` or `verifier` agent (`--session` and `--token` from SubagentStart);
+OpenCode, a child session; Pi, a supervised worker. On Claude Code pass the
+`model` and `effort` of `workit models show --role <verifier|reviewer>`. Never hand-mint one such
+as `<lead>-v1`: it is refused as `forged_session`.
+An author's `--self` verdict reads self-reviewed and never counts as
+independent; `type-check-only` never proves a behavior change.
+Depth follows the review lane in `workit pr status`: focused reads the diff and
+runs its tests; full also drives the real surface (verify-<app>). Review once
+per PR after its last push; a second pass on an unchanged head is waste.
+A stale verdict showing `reverify: focused (<files>)` in `workit pr status`: re-check only
+those files since the judged head and reuse green CI there (no fresh install, no full suite).
+
+1. Pin the candidate: `git rev-parse HEAD`, the base, `git diff <base>...HEAD`;
+   for a PR, `workit pr status --json` (checks, unresolved threads).
+2. Find the intent: acceptance criteria, spec, PR body, and the recorded
+   choices (`workit ledger list --type decision`).
+3. Judge two axes separately, never merged or re-ranked:
+   - **Spec:** does the diff do what the acceptance says? Missing, creep or
+     wrong; quote the line.
+   - **Standards:** repo rules first (`CODING_STANDARDS.md` when present),
+     then a smell baseline (unclear name, long function, duplicated logic,
+     leaky abstraction). Judgment only; lint owns nits.
+4. **Tests:** run suites under the heavy-check lease (`workit check test`,
+   `workit check --heavy -- <cmd>`); `workit test-audit --diff`. Would each new test fail if the
+   behavior broke? Triage the findings (read the `workit-test-audit` skill's SKILL.md and follow it). Every configured check (`packaging`
+   too) needs a run or green CI on the head, or `verified` is refused: see `pr status`.
+5. **Blast radius:** for each touched contract, caller, config or migration,
+   state the one fact it is safe because of and run the proof. Anything
+   unproven is labeled UNPROVEN, never assumed safe: `references/impact.md`.
+6. Each finding: file:line, severity (blocker, major, minor, nit), evidence
+   (hunk, test or command output), concrete fix. Introduced issues get fixed;
+   pre-existing ones become follow-ups; inconclusive ones escalate.
+7. Record the verdict:
+   `workit ledger verdict verified|failed|blocked --kind review --branch <b> --how "<what you ran and read>"`
+   under your own session (the one the lead or the hook gave you).
+8. **Bound the loop.** A failed verdict gets one fix round and one recheck of
+   the changed hunks. Still failing, or stuck: no third round; the lead spawns
+   a decider (read the `workit-fanout` skill's SKILL.md and follow it). A product choice goes to the user.
+9. **Harness note** (optional): friction caused by the repo or harness, not
+   the change (a flaky fixture, a missing check, a misleading doc or skill
+   line), goes on its own `Harness note:` line in the report and any PR
+   comment, never as a finding or in the verdict, so a later retro finds it.
+
+## Example
+
+Bad: "Error handling could be improved." (no place, no consequence, no proof)
+
+Good: "blocker - src/pay.ts:88: `catch {}` swallows the gateway's 402, so the
+order is marked paid. Repro: `workit check -- bun test pay.test.ts -t declined`
+fails with this diff. Fix: rethrow `PaymentDeclined`."
+
+## Check
+
+```sh
+workit ledger check --pr <n>   # accepted only when current, passing and independent
+```

package/skills/workit-review/references/impact.md

@@ -0,0 +1,24 @@
+# Blast radius beyond the diff
+
+A small diff is not a small risk. For every surface the change touches, name
+the one fact it is safe because of and run the proof.
+
+1. List what the change touches: exported symbols and every caller
+   (`git grep -nw <symbol>`), shared state, wire or file formats, config keys,
+   migrations, CLI flags and outputs, public types.
+2. For each: the fact it is safe because of (a type boundary, an existing test
+   that covers the path, an unreachable branch, a version gate) and the command
+   that proves it.
+3. Run the proofs with `workit check -- <cmd>` so the result is observed.
+4. Anything you could not prove is a finding labeled UNPROVEN with what would
+   prove it. Never fold it into "looks safe".
+5. A fix belongs at the shared root (one guard that every caller passes
+   through), not copied per caller.
+
+Example note:
+
+| Surface | Safe because | Proof |
+| --- | --- | --- |
+| `parseRange()` (4 callers) | callers pass validated input; new branch only for `--since` | `workit check -- bun test range.test.ts` exit 0 |
+| `config.json` `since` key | additive, old readers ignore unknown keys | `workit check -- bun test config-compat.test.ts` exit 0 |
+| GitLab adapter | UNPROVEN - no fixture for relative dates | add a `gitlab/relative-since.json` fixture |