@brainervirus/workit-claude-code 4.0.0 → 6.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brainervirus/workit-claude-code",
-  "version": "4.0.0",
+  "version": "6.0.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": "^4.0.0",
-    "@brainervirus/workit-core": "^4.0.0"
+    "@brainervirus/workit-cli": "^6.0.0",
+    "@brainervirus/workit-core": "^6.0.0"
   },
   "engines": {
     "node": ">=24"

package/skills/bdd/SKILL.md

@@ -1,51 +1,48 @@
 ---
 name: bdd
-description: Use when turning a requirement, issue or acceptance criterion into tests, or when tests should read as behavior (Given/When/Then, BDD, scenarios, acceptance tests, test names and seams)
+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
 
-Write each acceptance criterion as Given/When/Then before any code, then let
-it name the test and pick the seam. This skill shapes the scenarios; the
-RED/GREEN loop itself is workit-behavioral-tdd.
-
-## Method
-
-1. Write the scenarios. One behavior per scenario, in the user's or caller's
-   words: `Given <state>, When <action>, Then <observable result>`. Include the
-   unhappy paths a caller depends on (denied, empty, invalid, timeout).
-2. Agree the seams. Pick the highest stable interface the scenario can be
-   observed through: a CLI verb, a public function, an HTTP route. Ideally one
-   seam per feature. Write the seams down; do not test at an unagreed seam.
-3. Name the tests after the scenarios. The test name is the Given/When/Then
-   sentence; the body is arrange (Given), act (When), assert (Then). Expected
-   values come from the scenario (a literal from a worked example or the
-   spec), never from the code.
-4. Use Gherkin only where the repo already does (`.feature` files with
-   playwright-bdd, cucumber, jest-cucumber). Otherwise plain test names carry
-   the scenario; do not add a BDD framework.
-5. Build in vertical slices, one scenario at a time, with
-   workit-behavioral-tdd: run `workit check test` RED for the new scenario,
-   make the smallest change, run `workit check test` GREEN, then the next.
-6. Mock only at system boundaries: network, clock, randomness, other
-   processes, sometimes the filesystem. Never the unit or its internal
+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.
+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.
+4. **Build in vertical slices.** 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.
 
-## Completion
+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
+(workit-test-audit finds these).
 
-Every acceptance criterion maps to a named test at an agreed seam, each was
-seen RED then GREEN through `workit check test`, and the new tests have no
-tautologies:
+## Example
 
-```sh
-workit test-audit --diff && workit check test
-```
+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))`
 
-## In Claude Code
+## Check
 
-Workit operations (`task`, `evidence`, `policy`, `decision`, …) run through
-the `workit` CLI on the Bash tool: `workit <family> <action> --json`
-(`workit --help` lists the verbs). The plugin's `verifier`, `reviewer`
-and `implementer` agents take independent verification, fresh-context
-review and isolated implementation.
+```sh
+workit test-audit --diff && workit check test
+```

package/skills/continue/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: 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.
+
+## 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 with workit-ship."
+
+## Check
+
+```sh
+workit handoff   # read: "next command" is set and no check is listed as stale
+```

package/skills/debug/SKILL.md

@@ -1,49 +1,45 @@
 ---
 name: debug
-description: Use when behavior is failing, surprising, contradictory, or regressed and the root cause is not established
+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 the root cause
-
-Debugging is investigation, not a fast symptom patch. Use this method when
-assessment selects `root-cause-investigation` or behavior is failing without an
-established root cause.
-
-
-## Method
-
-1. Inspect task scope, caller authority, candidate identity, existing evidence,
-   findings, and worker/writer state with shared `task`, `policy`, `evidence`, and
-   `finding` operations.
-2. Reproduce the failure at a stable behavioral boundary. Record observed facts,
-   inferences, and unknowns with references; trace the failing value and all
-   relevant callers before editing.
-3. State the root-cause hypothesis and the smallest in-scope fix. Write a focused
-   regression at the boundary when practical, then run RED and GREEN through
-   `workit check <name>` so the results are observed, not reported.
-4. Acquire writer authority through `writer` before mutation. Reconcile the
-   candidate, evidence, and findings after the change; investigate sibling paths
-   and stale conclusions rather than assuming the first patch worked.
-
-Respect the user's scope and native authority. For a deterministic failure, make
-one focused reproduction that exercises the affected boundary and add a
-regression check when practical. If no direct reproduction exists, gather the
-available evidence and state what remains uncertain instead of inventing a red
-loop or blocking unrelated work.
-
-## Common mistakes
-
-| Mistake                               | Correction                                             |
-| ------------------------------------- | ------------------------------------------------------ |
-| Patching the nearest stack frame      | Trace the input, callers, and shared cause.            |
-| Reproducing only after editing        | Capture the failure before mutation.                   |
-| Treating one passing command as proof | Verify the affected behavior and record real evidence. |
-
-
-## In Claude Code
-
-Workit operations (`task`, `evidence`, `policy`, `decision`, …) run through
-the `workit` CLI on the Bash tool: `workit <family> <action> --json`
-(`workit --help` lists the verbs). The plugin's `verifier`, `reviewer`
-and `implementer` agents take independent verification, fresh-context
-review and isolated implementation.
+# 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/deslop/SKILL.md

@@ -1,40 +1,41 @@
 ---
 name: deslop
-description: Use before opening a PR or after implementation to remove AI slop from code and prose
+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
 
-Throughput without quality is slop. Clean it with a minimal diff — deslop
-never refactors behavior.
-
-
-## Method
-
-1. Code: delete dead helpers, redundant validators, stub references, and
-   comments that restate the code. Comments die by default; keep one only
-   with proof of an unchangeable constraint, encoded structurally if cheap.
-2. Prose (PR body, spec, docs): cut filler, keep real symbol names and
-   before→after numbers. One doc, one purpose.
-3. Keep the diff minimal: deslop removes lines, never moves logic. If a
-   cleanup wants behavior change, it becomes its own tasked change.
-
-## Completion
-
-A smaller diff with identical behavior and green checks. Report lines
-removed, not lines written.
-
-Record passing check evidence linked to the `pre-pr-cleanup` requirement id
-from the current policy (`kind: check`, `result: passed`, summary naming what
-was removed). That requirement gates `hosting.pull_request` and close. If the
-change genuinely has nothing to clean, ask for an approved limitation
-decision instead of recording evidence that did not happen.
-
-
-## In Claude Code
-
-Workit operations (`task`, `evidence`, `policy`, `decision`, …) run through
-the `workit` CLI on the Bash tool: `workit <family> <action> --json`
-(`workit --help` lists the verbs). The plugin's `verifier`, `reviewer`
-and `implementer` agents take independent verification, fresh-context
-review and isolated implementation.
+Throughput without quality is slop. Deslop only removes; it never changes
+behavior. A change that wants new behavior is its own change.
+
+1. **Find it with tools first.** The repo's dead-code and lint tools on the
+   branch diff (for example `knip`, `ts-prune`, `vulture`, `cargo udeps`, or
+   the linter's unused rules), then read the diff:
+   `git diff <base>...HEAD`.
+2. **Code.** Delete unused helpers and exports, stub references, debug
+   leftovers (`[DEBUG-` tags, stray logs), and comments that restate the next
+   line. Keep comments that say *why* (a constraint, a workaround with its
+   link), license headers and tool directives.
+3. **Prose** (PR body, spec, docs): cut filler and hedging, keep real symbol
+   names and before-to-after numbers. One doc, one purpose.
+4. **Minimal diff.** Deslop removes lines; it never moves logic. A removed
+   validator that changes behavior is not deslop.
+5. **Re-run the checks** and report lines removed, not lines written. Nothing
+   to clean is a valid result: say what you checked ("0 removals; ran knip and
+   read the diff"). When a tracked task lists a `pre-pr-cleanup` requirement,
+   record this result as its evidence.
+
+## Example
+
+Bad: deleting `// retry: the gateway drops the first request after idle (#412)`
+because "comments die".
+
+Good: deleting `// increment the counter` above `count += 1`, an unused
+`formatLegacyDate` export reported by knip, and two hedging paragraphs from the
+PR body: "-34 lines, behavior unchanged, `workit check test` exit 0".
+
+## Check
+
+```sh
+workit check test && git diff --stat <base>...HEAD
+```

package/skills/fanout/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: 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
+
+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.
+
+1. **Slice** (workit-shape): each slice gets a branch, a file-scope manifest
+   (the globs it may write) and, if it depends on another, its stack parent.
+2. **Check disjointness.** No two manifests overlap. Shared files (lockfile,
+   registry, barrel exports) belong to one slice, or to you after fan-in.
+3. **Brief each worker** with the fixed template and refuse to spawn while a
+   field is empty: GOAL, SCOPE (the manifest), CONTEXT (pointers, not pasted
+   text), ACCEPTANCE (Given/When/Then), VERIFY (exact commands), TIMEBOX,
+   FORBIDDEN, REPORT, STANDING. STANDING is every standing order and user
+   directive so far, pasted verbatim into each spawn and respawn, because
+   directives decay across resumes. Template: `references/brief.md`.
+4. **Spawn all workers in one message**, in the background, each in its own
+   worktree (Claude Code: the `implementer` agent; elsewhere
+   `git worktree add --detach ../<repo>-wt/<slug> origin/<base>`). The first
+   command a worker runs is `workit git branch <branch> --base <base>`.
+5. **Judge liveness by side effects only:** new commits and pushes
+   (`git log <branch>`), PR and check changes (`workit pr status --branch <b>`).
+   No progress past the timebox means stuck. Stop the old worker and observe
+   that it exited (a timeout is not proof). `git worktree remove --force`
+   drops its uncommitted changes, so first record `git -C <wt> status --short`
+   in the ledger or your report; only then remove the worktree. Respawn with the brief in
+   `MODE: resume` (consolidated: original, later directives, its last report):
+   the new worker runs `git switch <branch>` in its fresh worktree instead of
+   `workit git branch`. Never two live workers on one branch. Replace at most
+   twice, then re-slice or report the gap. Never chain resumes.
+6. **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.
+7. **Fan in.** Compare `git diff --name-only <base>...<b>` with the slice's
+   SCOPE: any file outside it stops the fan-in with a report. Then
+   `workit ledger check --branch <b>` for each slice; restack
+   stacked slices with `workit stack sync`. Only you touch topology: workers
+   never rebase, retarget or merge. Then 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`; ...).
+
+## Check
+
+```sh
+workit ledger check --branch <b>   # per slice: accepted (current, passing, independent)
+```

package/skills/fanout/references/brief.md

@@ -0,0 +1,56 @@
+# 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.
+
+```md
+MODE: <new | resume (a replacement continuing an existing branch)>
+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>
+TIMEBOX: <wall clock or turn budget; past it without a new commit you will be replaced>
+FORBIDDEN: <no edits outside SCOPE; no rebase, retarget, merge or force-push; no new dependencies; ...>
+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>
+  export WORKIT_SESSION_ID=<lead>-w<n>   (set by the lead; a verifier brief gets <lead>-v<n>)
+```
+
+## Worked example
+
+```md
+MODE: new
+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"
+TIMEBOX: 45 minutes
+FORBIDDEN: no edits outside SCOPE; no schema migration; no rebase or force-push; no new packages
+REPORT: as in the template
+STANDING: conventional commits; no comments that restate code; ask nothing, record rulings instead
+```
+
+## Worker rules (paste into the brief when the host has no implementer agent)
+
+1. First command. `MODE: new`: `workit git branch <branch> --base <base>` (the
+   worktree may start on a name that breaks branch policy). `MODE: resume`:
+   `git switch <branch>` (the branch exists; the lead removed the dead
+   worker's worktree after its exit, so the switch succeeds), then continue
+   from its head.
+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 commit -m "<msg>" -- <paths in SCOPE>`; push only if
+   the brief says so.
+4. Never record a verdict on your own work.

package/skills/implement/SKILL.md

@@ -1,57 +1,52 @@
 ---
 name: implement
-description: Use when implementing requested code changes in a repository. Follow its rules and host permissions; use Workit tracking and delegation only when continuity or coordination helps.
+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 within authority
-
-Implement within the user request and native host permissions. A task record and
-writer ownership are optional coordination tools. Assignment never expands the
-request, and a timeout is not proof that a worker stopped.
-
-## Method
-
-1. Inspect the repository, relevant rules, host capabilities, and current work.
-   Inspect task state only when this work is already tracked.
-2. If a helper is useful, assign one bounded objective with allowed paths,
-   applicable requirements, evidence needed, and a stopping condition. Helpers
-   cannot change scope, record binding decisions, close or pause the task, assign
-   helpers, or resolve blockers for the lead.
-3. Use writer ownership only when another Workit actor may mutate the same
-   checkout; release it when coordination ends. Cancellation remains uncertain
-   until process exit or explicit recovery.
-4. Reconcile helper reports and run the checks appropriate to the requested
-   outcome. If delegation is unavailable, continue inline when useful.
-5. Before a cross-repo mutation, resolve the actual checkout, branch and remote
-   from the request and current context. Ask only if competing plausible targets
-   remain unresolved. Branch, commit, direct push, PR-ready, merge and release
-   are distinct endpoints; perform only the authorized one under target rules.
-   Before saying done, reconcile every named deliverable against that checkout
-   and verify the requested result. For a push, observe the destination remote
-   ref and confirm it contains the delivered commit; report drift or missing
-   items as blockers instead of treating local success as remote delivery.
-
-Do not edit Workit metadata directly, create nested helper trees, widen paths, or
-create a second lifecycle. Read-only investigation and bounded reports do not
-grant product-write ownership.
-
-Do not request writer ownership for a solo edit. If a concurrent Workit writer
-cannot be fenced, stop only the conflicting managed writes; ordinary writes still
-follow the native host permission and sandbox.
-
-## Common mistakes
-
-| Mistake                                        | Correction                                          |
-| ---------------------------------------------- | --------------------------------------------------- |
-| "The helper timed out, so the writer is free"  | Observe exit or perform explicit recovery.          |
-| Letting a helper approve its own exception     | Return the decision to the lead/user.               |
-| Running a build while another writer is active | Treat builds and tests that mutate state as writes. |
-
-
-## In Claude Code
-
-Workit operations (`task`, `evidence`, `policy`, `decision`, …) run through
-the `workit` CLI on the Bash tool: `workit <family> <action> --json`
-(`workit --help` lists the verbs). The plugin's `verifier`, `reviewer`
-and `implementer` agents take independent verification, fresh-context
-review and isolated implementation.
+# 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>`.
+3. Small steps that each leave the tree green. Behavior change: write the
+   acceptance as Given/When/Then and see a test fail first (workit-bdd).
+   Mechanical change: the existing checks are enough.
+4. Run the real checks: `workit check test` (and `lint`, `typecheck` when the
+   repo has them). A recorded "tests pass" is a note; an observed run counts.
+5. Prove the feature on its real surface with the project's `verify-<app>`
+   skill (none yet? workit-verify-app writes one). Tests show branch behavior,
+   not that the feature works.
+6. Commit: `workit git commit -m "<type>: <what>" -- <paths>` (or `--all`).
+   No endpoint named? Stop here and state the next command. Push and open a
+   PR (`workit git push`, `workit pr create --fill`, then workit-ship) only when
+   that was requested, or the request implies delivery and `workit grant show`
+   reports `defaultEndpoint` `pr`; otherwise the endpoint is `commit`.
+7. Hand off verification. Never record a passing verdict on your own work.
+   Start a fresh verifier with its own session (`WORKIT_SESSION_ID=<yours>-v1`;
+   Claude Code: the `verifier` agent, which the hook gives one); it runs
+   verify-<app> and `workit ledger verdict`. 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 go to workit-fanout. When a step
+stalls on a fact, find it (read, run, prototype); ask only for a product or
+preference choice, with your recommended answer.
+
+## 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 (shared parser, not run). Verification handed
+to the verifier agent."
+
+## Check
+
+```sh
+workit check test   # then, when the endpoint was a push or beyond: workit verify-delivery push
+```