@brainervirus/workit-claude-code 7.5.2 → 7.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brainervirus/workit-claude-code",
-  "version": "7.5.2",
+  "version": "7.7.0",
   "private": false,
   "description": "Workit Claude Code plugin — session and per-turn task context, branch policy on git shell commands, workit method skills, and verifier/reviewer/implementer agents",
   "keywords": [
@@ -39,8 +39,8 @@
     "build": "bun scripts/build.ts"
   },
   "devDependencies": {
-    "@brainervirus/workit-cli": "^7.5.2",
-    "@brainervirus/workit-core": "^7.5.2"
+    "@brainervirus/workit-cli": "^7.7.0",
+    "@brainervirus/workit-core": "^7.7.0"
   },
   "engines": {
     "node": ">=24"

package/skills/architecture/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: architecture
+description: Rank cited deepening refactors from churn and ledger friction; never applied unapproved. Use for architecture.
+disable-model-invocation: true
+---
+
+# Architecture: deepen the modules that cause friction
+
+User-invoked: offer it, never start it yourself. It proposes and grills; it
+never refactors without the user's approval. Use the words in
+`references/vocabulary.md` exactly and the domain words in `GLOSSARY.md`.
+
+## Deepening
+
+1. **Scope by YAGNI.** A direction the user names wins. Otherwise find hot
+   spots: churn (`git log --since=6.months --name-only --format=`, counted per
+   file, skipping lockfiles, version-bump manifests, generated files, docs and
+   `chore(release)` commits), friction in `workit ledger list --last 200`
+   (failed checks and verdicts, rulings, `retro:` decisions) and
+   `workit test-audit <paths> --json`. State the window and paths in one line.
+2. **Settled decisions stand.** Read `GLOSSARY.md`, `CODING_STANDARDS.md` and
+   ADRs when present. Never re-litigate an ADR without new evidence.
+3. **Explore organically.** A read-only explorer (Claude Code: Explore; or
+   you) walks the hot spots under the limits in `references/vocabulary.md`
+   and returns cited friction. Run the deletion test on every suspect.
+4. **Report 3-5 ranked candidates, then stop and wait for approval.** Each:
+   - files and modules;
+   - the friction, with **2 or more cited occurrences** (commit, ledger row,
+     PR, test-audit finding); a one-off is not a candidate;
+   - an interface sketch: what callers see, what moves behind the seam;
+   - what gets simpler and what becomes testable through that interface;
+   - **merge danger**: one-way or two-way door, plus blast radius (callers,
+     packages, public surface).
+   The text list is primary; offer an HTML report only if the host renders one.
+5. **Grill the chosen one**: numbered questions, each with a recommended
+   answer; challenge a weak premise with evidence first. Settle the interface,
+   the seam, the tests to replace and the migration order; a module named for
+   a new concept gets its glossary entry (call the Skill tool with `workit:shape`).
+6. **Hand off on approval.** Several slices go into a plan for
+   `workit fanout plan <plan.json>`, with scopes and dependencies
+   (call the Skill tool with `workit:fanout`). One slice goes to a build (call the Skill tool with `workit:implement`). Record the
+   choice with `workit ledger decision "architecture: <id>" --why "<why>"`;
+   offer an ADR for a lasting rejection so the next run does not repeat it.
+
+## Instruction files
+
+Restructure AGENTS.md or CLAUDE.md in three escalating passes, **each its own
+commit in one PR**, so the user can drop the later ones: remove no-ops;
+progressive disclosure into topic files; coding rules to `CODING_STANDARDS.md`
+and mechanical rules to checks. No commit adds a `workit knowledge lint`
+finding. Never scaffold an empty file (`references/instruction-files.md`).
+
+## Test sweep
+
+Run `workit test-audit <paths> --json` over the suite or one hot spot and
+report findings by module, worst first. On approval, the bad tests are
+replaced (call the Skill tool with `workit:test-audit`).
+
+## Example
+
+Bad: "The CLI is messy, so I split router.ts in five." Uncited, unapproved.
+
+Good: "1. Check runner (check.ts, evidence.ts), 3 occurrences: commits a1b2c3
+and d4e5f6 edit both for one fix; ledger row 41 is a `check` red on a hidden
+timeout. Sketch: `runCheck(spec)` returns evidence, the timeout behind it, so
+timeouts test without a shell. Two-way door, 2 callers in one package."
+
+## Check
+
+```sh
+workit knowledge lint   # no new finding after each instruction-files commit
+```

package/skills/architecture/agents/openai.yaml

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

package/skills/architecture/references/instruction-files.md

@@ -0,0 +1,52 @@
+# Instruction-files mode (AGENTS.md, CLAUDE.md)
+
+Instruction files are paid for in every session that reads them. Restructure
+them in three escalating passes. Each pass is its own commit in one PR, in
+this order, so the user can keep pass 1 and drop pass 3. Run
+`workit knowledge lint` before pass 1 and after every commit: no commit adds
+a finding, and the lint exits 0 after the last pass, or the report lists the
+findings that remain and why.
+
+After each commit, run `workit check test`. A sentence a test pins stays,
+unless the user approves changing that test. Commit each pass with
+`workit git commit -m "<type>: <pass>" -- <paths>`, then open the PR
+(call the Skill tool with `workit:ship`).
+
+Before pass 1, report the current byte counts and the plan for each pass, then
+wait for approval. A pass with nothing to do is skipped and said so, not
+padded.
+
+## Pass 1: remove no-ops
+
+Delete lines that would change no behavior if removed: "be thorough", "write
+clean code", "follow best practices", restated defaults of the host, notes
+about one past session, `path:line` references, and rules whose mistake a type,
+lint or check now prevents. Nothing moves in this pass; it only deletes.
+
+## Pass 2: progressive disclosure
+
+Keep the root file to what every session needs: commands, workflow, and
+"Read before <task>: <file>" pointers. Move topic detail (testing, release,
+hosts, architecture) into topic files under an existing docs folder, one file
+per topic, each opened by when to read it. Move text verbatim first; rewording
+belongs in pass 1 or a later change. Every pointer from AGENTS.md or
+CLAUDE.md must resolve (the lint's `broken-link` rule). The lint does not read
+topic files: check their own links and content by hand.
+
+## Pass 3: standards and checks
+
+- A judgment rule a reviewer must weigh goes to `CODING_STANDARDS.md`; the
+  root file keeps one pointer to it.
+- A mechanical rule (a forbidden import, a naming pattern, a file that must
+  exist) becomes a check instead of prose: a lint rule, a test, or a
+  configured `workit check <name>`. Show the check failing on a planted
+  violation, then delete the sentence.
+- No rule lives in two files (`duplicate-rule`).
+
+## Never
+
+- Create a file without its first real entry in the same commit. The lint
+  flags a scaffolded `CODING_STANDARDS.md` or `GLOSSARY.md` (`scaffold-file`);
+  for a topic file, that check is yours.
+- Squash the passes into one commit, or mix a behavior change into them.
+- Grow the root file past the lint's byte budget (`agents-budget`).

package/skills/architecture/references/vocabulary.md

@@ -0,0 +1,53 @@
+# Deepening vocabulary
+
+Use these words exactly in every candidate. Do not drift into "component",
+"service", "API" or "boundary".
+
+| Term | Meaning |
+| --- | --- |
+| Module | Anything with an interface and an implementation: a function, a file, a package, a slice across tiers |
+| Interface | Everything a caller must know: types, invariants, ordering, error modes, configuration, cost |
+| Depth | Behavior a caller or test reaches per unit of interface learned. Deep: much behind little. Shallow: the interface is nearly as complex as the implementation |
+| Seam | Where behavior can change without editing that place; where an interface lives |
+| Adapter | A concrete thing that fills a seam (production, in-memory, fake) |
+| Leverage | What callers gain from depth: one implementation pays back across many call sites and tests |
+| Locality | What maintainers gain: change, bugs and verification concentrate in one place |
+
+## Tests to run on a suspect
+
+- **Deletion test.** Imagine deleting the module. Complexity vanishes: it was
+  a pass-through, so inline it. Complexity reappears across callers: it earns
+  its keep. A deepening concentrates complexity; it does not just move it.
+- **Interface is the test surface.** Tests that must reach past the interface
+  mean the module has the wrong shape.
+- **One adapter is a hypothetical seam; two are a real one.** Do not add a
+  port unless something varies across it (production and test count).
+
+## What the explorer looks for
+
+- One concept that needs a hop through many small modules to understand.
+- Shallow modules: wide interface, thin implementation.
+- Pure helpers extracted only for tests while the bugs live in how they are
+  called (no locality).
+- Coupled modules leaking through their seams: one fix edits both (churn shows
+  them changing together).
+- Code that is untested, or hard to test through its current interface.
+
+The explorer is read-only (on Claude Code, the Explore agent). It reads code,
+git history, `workit ledger list` and `workit test-audit` output only: never
+session transcripts and never another workspace. It copies no secret, token
+or personal data into its findings. It returns only cited findings (file,
+commit, ledger row), never a refactor.
+
+## Dependency categories (how the deeper module is tested)
+
+1. In-process (pure, in-memory): merge and test through the new interface.
+2. Local stand-in exists (temp dir, in-memory store): test with the stand-in;
+   the seam stays internal.
+3. Owned but remote (your own service): a port at the seam, an in-memory
+   adapter in tests.
+4. Third party: an injected port, a fake adapter in tests.
+
+Replace, do not layer. An old test on a shallow module is deleted only after
+naming the break it catches and showing that a test at the deeper interface
+fails on that planted break (call the Skill tool with `workit:test-audit`). Until then it stays.

package/skills/fanout/SKILL.md

@@ -8,60 +8,60 @@ description: Run independent slices in parallel - one worker per isolated worktr
 Fan out only independent slices: disjoint files, no shared mutable state, each
 verifiable alone. Code-coupled work stays with one owner, who fans out after
 the blocking part lands. A worker whose whole job is re-running one command is
-ceremony; do it yourself.
+ceremony; do it yourself. Workit never spawns agents; you do.
 
 1. **Plan the slices** (call the Skill tool with `workit:shape`) in a plan file (`references/brief.md`):
-   per slice an id, branch, TIER, the file-scope manifest (SCOPE globs),
-   `owns` for shared files (lockfile, registry, barrels), `dependsOn` only for
-   a real dependency (independent PRs off trunk are the default), and the
-   brief fields. `workit fanout plan <plan.json>` refuses an empty or
-   placeholder (`<goal>`, `TBD`) brief field (exit 2) and two slices that may
-   write one file (exit 3) with a fix: an owner for a shared file, or a
-   dependency that serializes them. Apply it and re-run: refuse to spawn while
-   a field is empty or the plan is refused. Its `waves` say which slices may
-   run together; keep 4-6 in flight.
-2. **Brief each worker** from its slice with the fixed template: GOAL, SCOPE,
-   CONTEXT (pointers, not pasted text), ACCEPTANCE (Given/When/Then), VERIFY
-   (exact commands), TIER, TIMEBOX, SCRATCH, FORBIDDEN, REPORT, STANDING.
-   STANDING is every standing order and user directive so far, pasted
-   verbatim into each spawn and respawn: directives decay across resumes.
-3. **Spawn all workers in one message**, in the background, each in its own
-   worktree: Claude Code's `implementer` agent (first command `workit git
-   branch <branch> --base <base>`); elsewhere `workit fanout worktree create
-   <slice>`, which prints the SCRATCH dir. Refill from `fanout status`.
-4. **Judge liveness by side effects only:** `workit fanout status` (head age,
-   PR, CI, verdict, landed; STUCK past the TIMEBOX, default 30 min). Stop a
-   stuck worker and observe that it exited (a timeout is not proof). Removing
-   a worktree drops its uncommitted changes: `workit fanout worktree release
-   <slice>` records `git status` in the ledger first and refuses them without
-   `--force` (native worktrees: record `git -C <wt> status --short` first).
-   Respawn in `MODE: resume` (brief, directives, last report), same branch.
-   Never two live workers on one branch. Replace at most twice, then re-slice
-   or report the gap. Never chain resumes.
-5. **Verify each slice independently.** A fresh agent that did not write it
-   (Claude Code: the `verifier` agent) runs VERIFY and verify-<app>, then
-   `workit ledger verdict <result> --branch <b> --how "<evidence>"` under the
-   session you started it with (`WORKIT_SESSION_ID=<lead>-v<n>`, set by you,
-   never chosen by the author; Claude Code: the hook names one).
-   A worker's report is a pointer, never evidence.
-6. **Fan in** with `workit fanout check`: out-of-scope files (any file outside
-   it stops the fan-in), and `git merge-tree` conflicts with trunk and between
-   siblings, charged to the slice that lands later. Fix what it names (an
-   out-of-scope edit becomes a follow-up slice) until it exits 0. A slice
-   whose PR merged reads as landed; its dependents stop waiting. Then
-   `workit ledger check --branch <b>` per slice, land in `fanout status` order
-   and release the worktrees you made. Stacks: `workit stack plan <bottom> …
-   <top>` once, then `stack sync` and `land`. Only you touch topology: workers
-   never rebase, retarget or merge. Then ship (call the Skill tool with `workit:ship`).
+   per slice an id, branch, TIER, SCOPE globs, `owns` for shared files,
+   `dependsOn` only for a real dependency, and the brief fields. `workit fanout
+   plan <plan.json>` refuses an empty or placeholder brief field (exit 2) and
+   two slices that may write one file (exit 3) with a fix; apply it and re-run:
+   refuse to spawn while a field is empty or the plan is refused. One PR per
+   slice is the default; `"fanIn": "integration"` only when the user wants one
+   PR (`references/orchestration.md`).
+2. **Record standing orders** (`workit ledger standing add "<order>"`): every
+   user directive all workers share. Directives decay across resumes.
+3. **Brief each worker verbatim** with `workit fanout brief <slice>`: plan
+   fields, standing orders, SCRATCH, session id, fan-in rule. Never hand-edit
+   it; change the plan or the standing orders and render again.
+4. **Spawn in a rolling window**, in the background, each in its own worktree:
+   keep 4-6 in flight and refill from `spawnable` in `workit fanout status` as
+   each one finishes. Pick the model from TIER (`references/orchestration.md`).
+   Claude Code: the `implementer` agent; elsewhere first `workit fanout
+   worktree create <slice>`.
+5. **Judge liveness by side effects only:** `workit fanout status` (head age,
+   PR, CI, verdict, landed; STUCK past the TIMEBOX). Stop a stuck worker and
+   observe that it exited (a timeout is not proof). Removing a worktree drops
+   its uncommitted changes: `workit fanout worktree release <slice>` records
+   `git status` in the ledger first and refuses them without `--force`. Never
+   two live workers on one branch.
+6. **Retry once, then escalate.** A stuck or failed slice gets one retry with
+   a fresh brief (`workit fanout brief <slice> --mode resume`, same branch);
+   if that fails too, re-slice it, take it over, or report the gap. Never
+   chain resumes. A hard slice may race instead: N attempts, keep the best
+   verdict (`references/orchestration.md`).
+7. **Verify by the workspace `verification` setting** (`workit grant show`).
+   A report is a pointer, never evidence. `self`: a verifier that wrote none
+   of the slices, or you if you wrote none. `independent` or high risk: a
+   separate verifier session, never yours (doctrine: the ledger only refuses
+   authors). One verifier may take a batch of slices, one verdict per branch
+   (`workit ledger verdict <result> --branch <b> --how "<evidence>"`), in a
+   session never chosen by the author. A review panel on separate models only at high risk.
+8. **Fan in** with `workit fanout check`: out-of-scope files (any file outside
+   it stops the fan-in) and `git merge-tree` conflicts with trunk and between
+   siblings. Fix what it names until it exits 0; a merged slice reads as
+   landed. Then `workit ledger check --branch <b>` per slice, land in `fanout
+   status` order, release the worktrees you made, and `workit ledger standing
+   clear`. Only you touch topology: workers never rebase, retarget or merge,
+   except the integration-tip merge in integration mode. Then ship
+   (call the Skill tool with `workit:ship`).
 
 ## Example
 
 Bad brief: "Do the API part and add tests." (no scope, no acceptance, no
 verify command, so nobody can tell when it is done)
 
-Good brief: `references/brief.md` (GOAL: `GET /v1/usage` returns daily run
-counts; SCOPE: `src/routes/usage.ts`, `test/usage.test.ts`; VERIFY:
-`workit check test`; ...).
+Good brief: the output of `workit fanout brief usage-endpoint`
+(`references/brief.md` shows one).
 
 ## Check
 

package/skills/fanout/references/brief.md

@@ -1,8 +1,11 @@
 # Worker brief template
 
-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.
+`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 an existing branch)>
@@ -16,11 +19,12 @@ VERIFY: <exact commands, e.g. `workit check test`, the verify-<app> feature to d
 TIER: <mundane | standard | hard: how much model the slice needs>
 TIMEBOX: <wall clock or turn budget; 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 rebase, retarget, merge or force-push; no new dependencies; ...>
+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: user preferences and every directive given so far>
+STANDING: <the standing orders, verbatim: `workit ledger standing add` records each one>
   export WORKIT_SESSION_ID=<lead>-w<n>   (set by the lead; a verifier brief gets <lead>-v<n>)
 ```
 
@@ -40,7 +44,8 @@ VERIFY: `workit check test`; verify-api feature "usage"
 TIER: standard
 TIMEBOX: 45 minutes
 SCRATCH: ../app-wt/usage-endpoint/.workit-scratch
-FORBIDDEN: no edits outside SCOPE; no schema migration; no rebase or force-push; no new packages
+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
 ```
@@ -55,7 +60,9 @@ stack); `worktree` defaults to `../<repo>-wt/<id>`. `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 `timebox` such as `45 minutes`
-is the slice's STUCK threshold in `workit fanout status`.
+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
 {
@@ -90,7 +97,7 @@ is the slice's STUCK threshold in `workit fanout status`.
 }
 ```
 
-## Worker rules (paste into the brief when the host has no implementer agent)
+## Worker rules (`workit fanout brief` appends them as RULES)
 
 1. First command. `MODE: new`: `workit git branch <branch> --base <base>` (the
    worktree may start on a name that breaks branch policy). `MODE: resume`:

package/skills/fanout/references/orchestration.md

@@ -0,0 +1,117 @@
+# 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. Map it where the host lets you
+pick a model per spawn; nothing in the workspace config routes it.
+
+| TIER | Claude Code (`model` on the Agent call) | Hosts without a per-spawn model |
+| --- | --- | --- |
+| scouting (read-only search, not a slice) | `haiku` | host default |
+| mundane | `sonnet` | host default |
+| standard | omit it (inherits yours) | host default |
+| hard | omit it (inherits yours); consider a race | host default |
+
+OpenCode takes a subagent's model from its agent config: pick a configured
+agent whose model fits the TIER, else the default. Codex, Cursor and Pi run
+every worker on the host's model, so TIER only sizes the timebox and decides
+whether to race.
+
+## 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>` (native
+worktrees: record `git -C <wt> status --short` first). 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.
+
+## 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: Claude Code's
+`implementer` isolates natively; on other hosts `fanout worktree create` makes
+only the slice's own worktree, so run the attempts one after another there.
+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>`), passed as `--session`; that one wins over any
+  `<lead>-v<n>` in a brief. An `implementer` uses the session its brief
+  exports for its workit commands.
+- Other hosts: the session the brief sets wins: `export
+  WORKIT_SESSION_ID=<lead>-w-<slice>` from `workit fanout brief` for a
+  worker, `<lead>-v<n>` (or `--as verifier`) for a verifier you start.
+
+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 (call the Skill tool with `workit:review`), 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 (call the Skill tool with `workit:ship`).
+
+## Stacks
+
+For stacked slices (`dependsOn` one parent): `workit stack plan <bottom> …
+<top>` once, then `workit stack sync` and `workit stack land`.