@workit-dev/pi 0.0.1 → 1.0.0

package/package.json

@@ -1,10 +1,51 @@
 {
   "name": "@workit-dev/pi",
-  "version": "0.0.1",
-  "description": "OIDC trusted publishing setup package for @workit-dev/pi",
+  "version": "1.0.0",
+  "description": "Workit native extension for Pi — tools, method skills, and session continuity",
   "keywords": [
-    "oidc",
-    "trusted-publishing",
-    "setup"
-  ]
+    "agentic-coding",
+    "ai-agents",
+    "coding-agent",
+    "extension",
+    "pi",
+    "pi-package",
+    "workflow"
+  ],
+  "homepage": "https://github.com/BrainerVirus/workit#readme",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BrainerVirus/workit.git",
+    "directory": "packages/workit-pi"
+  },
+  "files": [
+    "dist/",
+    "skills/",
+    "package.json"
+  ],
+  "type": "module",
+  "main": "./dist/workit.js",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "bun scripts/build.ts"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "1.4.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "^1.4.0"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "pi": {
+    "extensions": [
+      "./dist/workit.js"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  }
 }

package/skills/workit-architecture/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: workit-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 (read the `workit-shape` skill's SKILL.md and follow it).
+6. **Hand off on approval.** Several slices go into a plan for
+   `workit fanout plan <plan.json>`, with scopes and dependencies
+   (read the `workit-fanout` skill's SKILL.md and follow it). One slice goes to a build (read the `workit-implement` skill's SKILL.md and follow it). 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 (read the `workit-test-audit` skill's SKILL.md and follow it).
+
+## 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/workit-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/workit-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
+(read the `workit-ship` skill's SKILL.md and follow it).
+
+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/workit-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 (read the `workit-test-audit` skill's SKILL.md and follow it). Until then it stays.

package/skills/workit-bdd/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: workit-bdd
+description: Turn requirements into Given/When/Then scenarios, agree the test seam, and work test-first in vertical RED/GREEN slices. Use for BDD, TDD, acceptance criteria, scenarios, Given/When/Then, write a test first.
+---
+
+# Behavior first: Given/When/Then
+
+1. **Write the scenarios.** One behavior each, in the caller's words:
+   `Given <state>, When <action>, Then <observable result>`. Include the
+   unhappy paths callers depend on (denied, empty, invalid, timeout).
+2. **Agree the seam.** The highest stable interface the scenario can be
+   observed through: a CLI verb, a public function, an HTTP route; ideally one
+   per feature. Do not test at a seam nobody agreed to. Note what each seam
+   catches and misses (a unit seam misses wiring; a CLI seam misses nothing
+   the user sees but runs slower) and cover each miss once, elsewhere.
+3. **Name tests after scenarios.** The name is the Given/When/Then sentence;
+   the body is arrange, act, assert. Expected values come from the scenario (a
+   literal from a worked example, the spec, an external contract), never from
+   the code under test. No tautological tests: a test must fail if the
+   behavior breaks, never restate the implementation.
+4. **Build in vertical slices, never horizontal ones** (every test first,
+   then every implementation: tests written ahead of any code assert guessed
+   internals). Write one vertical RED slice that fails for
+   the missing behavior and run it through the CLI so the failure is observed:
+   `workit check test`. Make the smallest change, run the same check GREEN,
+   then take the next scenario. Any edit makes the observation stale; re-run
+   before you claim it. A recorded "tests pass" is a note, and an ad-hoc
+   `workit check -- <cmd>` never satisfies the gate: only the configured
+   `test` check does. No `test` detected? Create `.workit/checks.json`, copying
+   in every check the repo already runs: once it exists it replaces the
+   detected defaults.
+5. **Mock only at system boundaries:** network, clock, randomness, other
+   processes, sometimes the filesystem. Never the unit or its own
+   collaborators; use the real thing or an in-memory adapter behind a port.
+6. **Gherkin only where the repo already uses it** (`.feature` files with
+   playwright-bdd, cucumber, jest-cucumber). Otherwise test names carry it.
+
+Reject noise: version-pin assertions, tests that mirror private structure,
+assertions inside a possibly-empty loop, smoke-only renders, duplicates. If a
+test still passes when every imported function returns `undefined`, rewrite it;
+the audit finds these (read the `workit-test-audit` skill's SKILL.md and follow it).
+
+## Example
+
+Bad: `test("calculateTotal works", () => expect(calculateTotal(items)).toBe(items.reduce((s, i) => s + i.price, 0)))`
+
+Good: `test("Given two items of 5 and 10, When totalled, Then the total is 15", () => expect(calculateTotal([{ price: 5 }, { price: 10 }])).toBe(15))`
+
+## Check
+
+```sh
+workit test-audit --diff && workit check test
+```

package/skills/workit-continue/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: workit-continue
+description: Keep work on track across interruptions and sessions - sort new input, checkpoint, hand off with a resume brief, and pick up by verifying inherited claims. Use for resume, pick up, handoff, new session, interruption, change of direction.
+---
+
+# Continue without losing the thread
+
+## New input mid-task
+
+- **Quick question:** answer it; change nothing else.
+- **Same-task adjustment:** update the affected constraint and next step, then
+  keep going.
+- **Separate request:** do not silently resume an old objective, and do not
+  drop the current one. Checkpoint it (below) if it must continue later, then
+  start the new work. Held items stay parked with their resume condition until
+  the user resumes them.
+
+## Checkpoint and hand off
+
+```sh
+workit git commit -m "wip: <state>" --all   # nothing lives only in your context
+workit handoff --note "<state in one line>" --next "<next command>" --record
+```
+
+The brief carries the branch, HEAD, dirty state, check freshness, verdict,
+rulings and the next command. Add only what it cannot know: choices still
+open, approaches that failed and why. Work spanning repos gets one brief per
+checkout, each with its branch and delivery endpoint. Notes too long for
+`--note` go in a file under `workit dir handoffs`; name its path in the note.
+
+## Pick up
+
+1. In the checkout: `workit handoff`, then `workit ledger list` and
+   `git log --oneline -10`.
+2. Trust the trail, verify the claims: re-run the checks the brief calls
+   stale, and confirm each "done" item against the goal on the real artifact
+   (a pushed SHA, a PR state, a running feature). Do not re-derive settled
+   decisions.
+3. Continue to the recorded endpoint with the brief's next command.
+
+## Example
+
+Bad: a new session re-reads the whole codebase, re-asks the user which
+approach to take, and redoes a finished slice.
+
+Good: "`workit handoff`: feature/usage at 4be1, `test` stale, verdict none,
+next `workit check test`. Re-ran it: exit 0. The brief says PR #42 is open:
+`workit pr status` confirms, CI pending. Continuing to ship (read the `workit-ship` skill's SKILL.md and follow it)."
+
+## Check
+
+```sh
+workit handoff   # read: "next command" is set and no check is listed as stale
+```

package/skills/workit-debug/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: workit-debug
+description: Find a root cause before patching - start from a red-capable deterministic repro, rank hypotheses, bisect regressions, fix at the root with a regression test. Use for bug, broken, failing, flaky, regression, error, why does.
+---
+
+# Debug from a red loop
+
+## Steps
+
+1. **Build the loop before any hypothesis.** One command that is red for the
+   user's exact symptom, deterministic, fast and runnable by you:
+   `workit check -- <repro>`. Shrink it until it fails in seconds. If the
+   symptom only shows on the running app, drive it with the project's
+   verify-<app> skill. No loop yet? Building it is the task; do not guess-patch.
+2. **Read the failure, not the summary:** the full error, the failing value,
+   and every caller on its path.
+3. **Rank three to five falsifiable hypotheses**, likeliest first. Test one at
+   a time with the loop or a tagged log line (`[DEBUG-<id>]`, removed at the
+   end with one grep). Keep a short hypothesis log so a dead idea stays dead.
+4. **Regression? Bisect it:** `git bisect start <bad> <good>` then
+   `git bisect run <repro>`. The first bad commit names the cause.
+5. **Fix at the root**, the one place every failing caller passes through.
+   Add a regression test at a seam that exercises the real bug pattern; if no
+   such seam exists, report that as a finding.
+6. **Stop rule:** after three dead hypotheses, write down what is measured and
+   what is inferred, widen the loop, or ask for the one fact only the user has.
+
+Every shipped line traces to evidence from the loop. A "might help" retry or
+guard is a hypothesis, not a fix.
+
+## Example
+
+Bad: "Probably a race; added a retry." (no repro, nothing measured)
+
+Good: "Repro: `workit check -- bun test lock.test.ts -t stale` red 10/10.
+H1 dead pid not reclaimed - confirmed: `kill(pid, 0)` throws EPERM for another
+user's pid and we treated it as dead. Fix: EPERM means alive. Loop green 10/10;
+regression test pins the EPERM case."
+
+## Check
+
+```sh
+workit check -- <repro>   # red before the fix, green after
+workit check test
+```

package/skills/workit-deslop/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: workit-deslop
+description: Remove AI slop before a PR - dead code, comments that restate the code, filler prose - with a minimal diff and identical behavior. Use for deslop, clean up, slop, tidy before PR, remove dead code, trim the PR body.
+---
+
+# Deslop code and prose
+
+Deslop removes; it never changes behavior. Its depth follows the review lane.
+
+1. **Scan first, no agent:** `workit deslop scan --diff [<base>] --json`. It
+   classes each added comment `narration`, `marker` (TODO, FIXME, HACK),
+   `suppression` (a lint or type disable with no reason), `debug` (stray logs,
+   `debugger`, `[DEBUG-` tags) or `allowed`, runs `test-audit` on changed
+   tests, and prints the lane and its passes. A marker or a lint/type
+   suppression raises `self` to `focused`.
+2. **Run the lane's passes** (each lane adds to the one below):
+   - `none` (docs only): prose. Cut filler and hedging from the PR body and
+     docs; keep real symbol names and before-to-after numbers.
+   - `self`: delete every narration, marker and debug finding, plus dead code
+     from the repo's tools (`knip`, `ts-prune`, `vulture`, unused-lint rules).
+   - `focused`: a fresh-eyes no-comments pass and a test-quality lens. Hand
+     the diff, never your verdict, to a fresh reviewer: Claude Code and Codex,
+     the `reviewer` agent; OpenCode, a child session; Cursor, a Task subagent
+     marked `ROLE: reviewer`; Pi, a supervised worker. It deletes every added
+     comment off the keep list and triages `workit test-audit --diff`
+     (read the `workit-test-audit` skill's SKILL.md and follow it).
+   - `full`: also `workit test-audit --mutate --diff` and one architect
+     sketch of the simpler shape, reported, not applied.
+3. **The keep list** (everything else goes): a licence header, an external
+   quirk (a library, OS or spec behaving oddly), `prettier-ignore` and other
+   tool directives, a lint suppression with its reason (`-- <why>`), public
+   API docs, an issue or RFC link.
+4. **No workaround comments for our own code.** Fix the root in a separate
+   `refactor:` commit, or open an issue that carries the explanation and
+   delete the comment. A "do not remove" note becomes a test, a type or a
+   lint rule.
+5. **Record one line per PR** when checks pass again:
+   `workit deslop result --removed <n> --reshapes <n> --open <n>` writes
+   `deslop: lane focused, -42 lines, 3 reshapes, 1 open` to the ledger.
+   Nothing to clean is a valid result (`--removed 0`). When a tracked task
+   lists a `pre-pr-cleanup` requirement (≤6.x tasks), this is its evidence.
+
+## Example
+
+Bad: keeping `// increment the counter` above `count += 1`, or deleting
+`// eslint-disable-next-line no-await-in-loop -- the API rate-limits parallel calls`.
+
+Good: the scan lists 6 narration, 1 marker and 1 bare `oxlint-disable`; the
+lane rises to focused; narration and the marker go, the disable gains its
+reason, a fresh reviewer drops two more comments, and a call-order assertion
+on an internal mock becomes a result assertion:
+`deslop: lane focused, -42 lines, 1 reshapes, 0 open`.
+
+## Check
+
+```sh
+workit deslop scan --diff && workit check test && workit deslop result --removed <n>
+```

package/skills/workit-fanout/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: workit-fanout
+description: Run independent slices in parallel - one worker per isolated worktree with a fixed brief and file-scope manifest, a non-author verifier per slice, results in the ledger. Use for fan out, parallelize, parallel agents, split the work, delegate, swarm.
+---
+
+# Fan out parallel workers
+
+Inline-first (workspace `delegation`): fan out only past a threshold, named as
+each slice's `reason` (explore, parallel, backstop, high-risk-verify): an
+explorer past ~3 tool calls or 10k tokens; parallel writers only for 2+ disjoint
+units of ~100+ lines each. Coupled work stays with one owner. Workit never spawns.
+
+1. **Plan the slices** (read the `workit-shape` skill's SKILL.md and follow it) in a plan file under `workit dir plans`
+   (`references/brief.md`): per slice an id, branch, REASON, 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**: `workit fanout worktree create <slice>`
+   (every host), then `workit fanout brief <slice>` (WORKTREE, SCRATCH, rules).
+   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. Assign before spawn (OpenCode: `workit worker assign`); each prompt carries
+   the brief, or a pointer: its `WORKER`, `TIER`, `TIMEBOX` and `WORKTREE` lines plus "run `workit fanout brief <slice>` and follow it"
+   (budget and model hooks read those lines), so batched OpenCode launches each bind their worker.
+   Model: the brief's `model:` and `effort:` lines (`workit models show`), else TIER (`references/orchestration.md`).
+   Claude Code: the `implementer` agent; its spawn hook drops `isolation` and refuses a prompt without a WORKTREE line.
+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); stop a finished one when its
+   report arrives (Claude Code: TaskStop). Never two live workers on one branch.
+   Removing a worktree drops its uncommitted changes: `workit fanout worktree
+   release <slice>` records `git status` in the ledger and refuses without `--force`.
+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 fix round and recheck that both fail: a decider, not a
+   third round; product choices go to the user (`references/orchestration.md`).
+7. **Verify by the workspace `verification` setting** (`workit grant show`).
+   A report is a pointer, never evidence. `proportional` (default): each slice's lane (`workit pr status`) decides; none needs no verdict, self the author's `--self`, focused and full a verifier (Claude Code: the `model` and `effort` of `workit models show --role verifier`) after the last push; one verdict at a stack's top covers its unchanged lower PRs, and a stale one with `reverify: focused` re-checks only the new diff, reusing green CI. `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. Spawn it with the brief's `verifier:` model (`workit models show --role verifier`). 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
+   (read the `workit-ship` skill's SKILL.md and follow it) up to `defaultEndpoint` from `workit grant show`.
+
+## Example
+
+Bad brief: "Do the API part and add tests." (no scope, acceptance or verify command: nobody can tell when it is done)
+
+Good brief: the output of `workit fanout brief usage-endpoint` (`references/brief.md` shows one).
+
+## Check
+
+```sh
+workit fanout check                # exit 0: in scope, no conflicts, landing order printed
+workit ledger check --branch <b>   # per slice: accepted (current, passing, independent)
+```