Factory docs, home
Page navigation

Pre-release documentation. Proposed designs are labelled in the page; acceptance evidence is maintained in the build review. Local paths appear as placeholders. Current state: Build review.

Use these commands to record who is doing which work in a project, to see the register's refusal when someone else already holds it, and to read which lanes are finished or left behind. They expose the candidate Work items module. The register is a SQLite journal that you own and create once; the commands never create one themselves, apart from init.

Prepare

Use Node 26.8.1 or later from the repository root. Choose where the register lives and create it once:

npm run factory:work -- init --journal /absolute/path/to/work-items.sqlite

Without --journal, every command uses <home directory path>. That default belongs to the command line alone; the module takes whatever journal it is handed. init refuses an existing path and a missing parent directory.

Each project needs its settings once, as a request file. Settings carry the integration ref (usually refs/remotes/origin/main), the branch prefixes your lanes use, the paths to ignore, and how long a lane can sit before it counts as stale:

{ "productId": "example", "revision": 1, "integrationRef": "refs/remotes/origin/main",
  "lanePrefixes": ["feature/"], "ignoredPaths": ["site/", "*-receipt.json"],
  "recordedBy": { "kind": "coordinator", "id": "my-coordinator", "provider": null, "session": null } }
npm run factory:work -- configure --journal /absolute/path/to/work-items.sqlite --input settings.json

Keep every ignored path short. A path you ignore is one that two people can change at once without the register noticing, so list only files that every change touches, such as registries and generated output.

Claim work

The common path builds the request from flags, writes it to a new file you name, and then runs it:

npm run factory:work -- claim --product example --item login-fix \
  --title "Fix the login redirect" --kind packet \
  --key task:login-fix --key path:src/login.ts --key path:test/login.test.ts \
  --holder-kind coordinator --holder my-coordinator --provider anthropic \
  --branch feature/login-fix --save /absolute/path/to/login-fix-request.json

Choose keys that identify the work: a task, roadmap, epic or issue ID, the module slug, and the paths you will change. Up to 32 keys are accepted, and a directory key such as path:src/auth/ covers every file beneath it. The host defaults to this machine's name.

The command prints one JSON document. After an unknown effect, such as a crash or a closed terminal, run the same request again, exactly as saved:

npm run factory:work -- claim --input /absolute/path/to/login-fix-request.json

The register answers a repeat with its recorded result and replayed: true.

Start from a branch

--repo takes the real path of the checkout, not a symbolic link to it. With --from-branch and --repo, the claim takes its path keys from what the branch has already changed, collapsed to at most 32 keys. Add --key for task, roadmap and module keys. The item defaults to the branch's last segment when that is a valid item ID.

npm run factory:work -- claim --product example --from-branch feature/login-fix --repo /absolute/path/to/repo \
  --title "Fix the login redirect" --kind packet --key task:login-fix \
  --holder-kind coordinator --holder my-coordinator --save /absolute/path/to/login-fix-request.json

--repo also checks the commits that landed on the integration ref in the last recentMergedDays. If your paths duplicate one of them, the claim is refused as LANDED and names the commits. Proceed with --follows-commit <hash> if yours builds on it, or --acknowledge commit:<hash> if you know about it. keys --product example --repo <root> --branch <name> prints the keys without claiming anything, to backfill lanes that already exist.

Read a refusal

A refusal names the work it collides with: the item, its holder, its state and lane, the shared keys and how much of each side's files overlap. The exit status says what to do next.

  • DUPLICATE (65): the work is the same. Coordinate with its holder, take it over openly, mark yours as a follow-up, or declare a comparison. Never work around a refusal by choosing new keys; the register compares real paths too.
  • OVERLAP (65): the work touches the same files or module. If you have talked to the holder, repeat the claim with --acknowledge <item> for each item named.
  • HELD (65): the branch or worktree is already held, or you are not the holder of the item you tried to move.
  • LANDED (65): commits already on the integration ref carry the work. See above.

To take over an item, with a reason that is recorded and shown to the previous holder:

npm run factory:work -- claim --product example --item login-fix \
  --holder-kind coordinator --holder other-coordinator \
  --takeover-reason "the first holder's session ended" \
  --branch feature/login-fix-2 --save /absolute/path/to/takeover-request.json

Keep it current

The other commands take a request file. Each request carries a requestId that you choose once and keep for a retry.

CommandUse it to
advanceMove your item to in-progress, in-review or merged; add a pull request or commit link; add an observed scope when it reaches review
releaseGive the item up, or close it with close: true and a reason
supersedeClose an item as superseded by another item or a commit
compare, concludeDeclare a comparison on purpose, and name its winner
proposeRecord work nobody holds yet
list, summaryRead the register; both are read-only

An item with a merged state needs a commit link. A merged item stays in the register for a while, so a follow-up that reuses its keys is allowed when it says follows.

When the owner is the one acting, the request must carry reason holding the owner's own words. The register checks that the words are present, not that they are true.

Find the lanes left behind

npm run factory:work -- stale --product example --repo /absolute/path/to/repo

The report is read-only unless you add --record, which journals it and sets each item's last finding; a report observed after the register's clock (a future --at) is refused, not recorded. Every lane has a standing (merged, superseded, likely-superseded, possibly-superseded, stale, active or unknown), the evidence, a proposed action as a word, and who confirms it. The command never deletes a branch or a worktree. Remove a lane yourself, only when it is clean, idle and not locked, and after you have saved a bundle of it. A dirty worktree is proposed as preserve-then-remove: save the uncommitted work first, and ask the owner.

The exit status is 2 when some lane could not be read, so the Counts are a lower bound. Use --at to read at another instant and --host to name this machine.

When an item reaches review, advance with --repo derives the files the branch really changed and checks them against other open work:

npm run factory:work -- advance --input advance.json --repo /absolute/path/to/repo --save /absolute/path/to/advance-derived.json

The derived request is saved before it runs, so a retry repeats it exactly.

Exit statuses

0 completed. 2 a stale report with partial coverage. 64 invalid input. 65 refused (duplicate, overlap, held, state, comparison, revision or conflict). 66 unavailable input, store, item or Git repository (a Git read failed). 70 corrupt store or unexpected error. 75 a limit or contention.

Every result carries effect: not-started, unknown or recorded. A refusal records nothing. After an unknown effect, repeat the same request.

See the contract and limits for every refusal code and bound.

Source: docs/how-to/claim-work.md