Factory docs, home
Page navigation

The Factory's register of work (roadmap WI1): one list per Product of what is being done, who holds it and in which lane. A claim that duplicates open or recently merged work is refused by fixed rules, unless a declared comparison, a follow-up or an open takeover allows it. It exists because several coordinators and agents, Claude, Codex or any other, built the same work in parallel and left stale lanes behind.

Status: In progress. Candidate implementation of stage 1 (WI1) in two reviewed parts: the register, and the lane reader with its reports (WI1-lanes). Three independent review rounds have run (Opus 5.5 primary, Fable 5.1 xhigh secondary): round 1 failed both, round 2 failed the primary, and round 3 passed the secondary and failed the primary on one defect and the plan's list of changed lines, which a third fix round answers and awaits re-review. Nothing is accepted, and no live register exists. Stage 2, across Products, is planned (WI2) and not built.

Intelligence: none — Claims and lane findings follow fixed rules over declared scope keys and read Git facts; a model would guess at overlap that recorded evidence must decide.

  • Source: src/work-items-core.ts (pure), src/work-items.ts (journal facade), src/work-items-git.ts (the read-only lane reader), scripts/factory-work.ts (the npm run factory:work command line)
  • Tests: test/work-items.test.ts, test/work-items-adversarial.test.ts, test/work-items-fixture.test.ts, test/work-items-git.test.ts, test/factory-work-cli.test.ts; the closures and namespaces in test/module-graph.test.ts
  • Fixtures: test/fixtures/work-items/lanes-2026-10-02.json records the facts read for the seven lanes found on 2 October 2026; claims-2026-09-29.json is reconstructed, not recorded, because no register existed
  • Design and roadmap: roadmap rows WI1 and WI2; factory model
  • Evidence drafts: docs/work-items-draft.json (register) and docs/work-items-lanes-draft.json (lane reader)
  • Human page: guide; the everyday commands are in claim work

What it hides

  • One register per Product, one transaction. work-items:product:<product> holds the Product's settings, items and comparisons. The duplicate check and the claim are one journal transaction, so racing claimants re-plan at the next version and the second sees the first. work-items:index lists the configured Products so a read can enumerate them. The index is written first: a crash between the two leaves a harmless entry that the retry completes.
  • Product-scoped and provider-neutral. A holder is {kind, id, provider, session}: kind is coordinator, session, agent, stage or owner, and provider is a label such as anthropic or openai with no provider logic attached. A coordinator session is one kind of holder among several, and the Factory's own lifecycle stages hold work the same way (WI1d). Two Products never conflict, and building the Factory itself is the Product software-factory.
  • Attribution, never authority. The register records who claims to hold what. The Product gate decides who may deliver. Any writer of the journal can claim as anyone, and a command that acts as the owner proves only that a reason holding the owner's words was given.
  • Scope keys (sf-work-scope/1). A claim declares 1 to 32 canonical, sorted kind:value keys. Identity kinds: task, roadmap, issue, pr, episode, slice (<sliceId>/<revision>), occurrence, signal, opportunity. Area kinds: path (repo-relative POSIX, NFC, compared lower-cased; a trailing / makes a directory prefix) and module. epic is context and never decides alone. capability and dependency are portable kinds, stored now and compared across Products by WI2. Case variants, NFD against NFC, ./ and .. segments, a trailing / on a file and a directory key over its files cannot evade the rules: paths with dot segments are refused, and the rest compare equal.
  • The duplicate rules (sf-work-similarity/1). They run inside the journal decision against every open item and every item merged within recentMergedDays, after the Product's ignored paths are removed. A claim is a DUPLICATE if it shares an identity key, if at least 80% of one side's paths (and at least 3) lie inside the other's, or if the symmetric cover is at least 60% with at least 2 paths on each side. A duplicate cannot be acknowledged. It proceeds only as a variant of a declared comparison that includes the conflicting item, as a follow-up of the conflicting item once it is merged, or as a takeover of that item. Any other shared path, module or capability is an OVERLAP, which proceeds only when the claim acknowledges exactly those items. Thresholds are frozen constants with a digest, SIMILARITY_RULES_DIGEST, recorded in every result.
  • Declare small, change large. Advancing to in-review can carry an observed scope, the paths the lane actually changed (collapsed by collapsePaths to at most 32 keys). The rules then run again with the observed paths added, so a claimant who declared two paths and changed twenty is refused or must acknowledge. Items in the same comparison (a variant, and an item the comparison names, each exempt from the other), the follow-up target and acknowledged items are exempt. No observed scope is derived at merged: by then the lane's diff is empty.
  • State machine. proposed to claimed to in-progress to in-review to merged, forward only (a claimed item may skip forward), with exits to superseded or abandoned from any open state. release returns a held item to proposed with no holder. Closed items are terminal: new work on closed work is a new item that follows it. merged needs a commit link.
  • Takeover. claim with takeover: {itemId, reason} takes an open held item openly. The previous holder and lane move to previousLanes and the log. A takeover of an item that changed within staleAfterHours, or whose last lane finding is active and recent, is recorded with active: true, and the summary and the next report list it with the previous holder, so that holder is told.
  • Comparisons. A comparison is declared by the owner or by the current holder of every compared item. Variants are ordinary items claimed with comparison: <id>; a comparison holds at most 4 items in all. While it is open, no item in it can merge. conclude names the winner and closes every other open item in it as superseded with the reason comparison-lost, in one command. A comparison past its deadline is reported as overdue and never closed automatically.
  • The lane reader. gitLaneReader in src/work-items-git.ts reads, per branch under the Product's lane prefixes, per worktree outside the primary checkout (including one on a branch outside the prefixes, which is never left out) and per open item's lane, the facts the classifier takes: the tip and its time, the merge base with the integration ref, all commits ahead (including merges), patch-equivalent commits (git cherry), the changed paths, whether each changed file's final blob landed in a later integration commit, the three best-matching integration commits (coverage, Jaccard; ties by later time, then hash), the share of the lane's added lines already in the integration ref's version of the same file (at least 20 lines of at least 8 non-space characters, else unknown) and the worktree's state. It runs only allow-listed read-only subcommands under a fixed environment, never fetches, writes or refreshes an index, and passes --no-ext-diff and --no-textconv to every diff and log, with signature display (log.showSignature), submodule display and the hooks path pinned off. A worktree is read only when the repository configures no filter.* driver, and a worktree path that is a symbolic link is unknown, never read through, so the programs a repository can name (diff, textconv, filter, fsmonitor, hooks, gpg) are never started. Any failed call or exceeded bound makes that lane unknown with a reason; nothing is computed from partial output.
  • Lane facts and the classifier (pure). classifyLane takes the facts a lane reader returns (LaneFacts, sf-work-lanes/1) and applies a fixed order: unknown first (another host, an unread lane, a clock that disagrees; never stale), then merged (the tip is on the integration ref), superseded exactly (the register says so, every ahead commit is patch-equivalent (Git does not report merges as patch-equivalent, so merge-only changes block that inference), or every changed file's blob landed), likely-superseded and possibly-superseded (idle past the bound, with two heuristic signals), stale, and active. Each finding carries its evidence, a proposed action as a word and who confirms it. The owner is never the default confirmer, and a dirty worktree turns a removal into preserve-then-remove, which goes to the owner through the ask ledger. A lane that an open item names, with no commits of its own yet and touched within the bound, is active, not merged. A lane an open item names whose tip is no later than the item's claim of it has no commits since the claim: it is stale (asking the holder) or active, never merged. A finding describes a lane, not an item: on an open item, merged and superseded carry own-commits-not-established, and neither gives a non-holder authority to close it.
  • Reports and the summary. buildLaneReport turns facts and a register into a report: lane findings, item findings (stale-never-started, merged-unrecorded, merge-unverified), overdue comparisons, takeovers of active items since the last report and collisions between active lanes whose real paths overlap. recordReport journals one and sets each item's last finding. summarise (sf-work-summary/1) is computed on demand and never stored. Item Counts are exact because they come from the register; lane Counts are exact only when every lane was read.
  • Retention. Closed items form a ring of 128, evicted oldest first by closedAt. A command that would leave the register at or above the soft limit of 655,360 bytes first evicts closed items in the same order; the hard limit is 786,432. When the open items alone reach the soft limit, a new item is refused. The byte limit governs when items are large: a typical merged item with eight keys and two links is about 1.5 KB, so the ceilings of 128 open and 128 closed items bind first, while an item at every per-item maximum measures 32,511 bytes and the byte limit binds at about 20 of them. Eviction is named in work-items.items-evicted, the summary reports recent-merged coverage as partial once eviction reaches into the window, and an evicted item ID may be used again.

Public interface

src/work-items.ts, in WorkRegister(journal, clock); the constructor reads no clock and runs nothing.

NameWhat
configure(input)Records a Product's settings, revision by revision: the integration ref, lane prefixes, ignored paths, staleAfterHours and recentMergedDays. A Product with no settings refuses every other command (NOT_CONFIGURED)
propose(input)Records work with no holder; the duplicate rules apply as to a claim
claim(input)Claims new work, an existing proposed item, or takes an item over (takeover)
advance(input)Moves a held item to in-progress, in-review or merged, adding links, a new lane or an observed scope
release(input)Returns an item to proposed, or closes it as abandoned with close: true
supersede(input)Closes an item as superseded by another item or a commit. Allowed for the holder or the owner only. No lane finding gives anyone else that authority: Git cannot tell an open item's own commits from commits its branch inherited or picked, so a merged or superseded lane on an open item is confirmed by its holder, or by the coordinator after an open takeover
compare(input), conclude(input)Declare a comparison; name its winner
recordReport(report)Journals one sf-work-lanes/1 report
read(product), list(filter), products(), summary(now?), history(product, page?)Read-only

src/work-items-git.ts has gitLaneReader(options?), which returns a LaneReader: readLanes(root, settings, items, at, identity) returns an sf-work-lanes/1 LaneFactsSet; landedSince(root, settings, at) lists the non-merge commits on the integration ref within recentMergedDays, with their non-ignored paths; changedPaths(root, settings, branch) gives a branch's non-ignored changes and the collapsed path: keys. gitRunner is the allow-listed runner, exported so its refusals can be tested directly. Options: an absolute gitPath (/usr/bin/git by default), timeoutMs (100 to 30,000, default 10,000) and maxOutputBytes (at most 16 MiB). At most four Git processes run at once and a report has a 120 second deadline, after which unread lanes are unknown: deadline.

Every write carries a caller-chosen requestId, chosen once per intent and kept in the request, and every result is a Recorded: its command ID, the aggregate version, replayed, retained, the item or comparison, the rules digest, the overlaps that were allowed and the IDs evicted.

src/work-items-core.ts is the pure part: normaliseScope, collapsePaths, prepareScope, compareScopes, classifyLane, buildLaneReport, summarise, parseRegister, parseLaneFacts, parseLaneReport, the input parsers, WORK_ITEMS_LIMITS, SIMILARITY_RULES and its digest, and WorkItemsError. Its runtime closure is canonical JSON and Node's buffer and crypto: no journal, Portfolio, branch health, process or network (asserted in test/module-graph.test.ts).

Journal records

No SQLite schema change. The module owns the aggregate prefix work-items: and the command prefix work-items/.

  • Aggregates. work-items:product:<product> and work-items:index. work-items:portfolio is reserved for stage 2 and unused.
  • Command IDs. work-items/configure/<product>/<revision>; work-items/<verb>/<product>/<24 hex>, where the hex is the SHA-256 of the item or comparison ID and the request ID; work-items/report/<product>/<24 hex>; work-items/index/<product>. They fit the journal's 128 characters.
  • Replay. Each applied command ID is kept with the version it produced in the item's log (a comparison, a configure and the last report keep their own). A retry whose command ID is recorded is executed again at that version, so the journal answers from its receipt: an identical retry replays, different content is CONFLICT. A VersionConflictError re-plans, up to 16 rounds, then CONTENDED.
  • Retries after eviction. When the journal holds a receipt for the identical request and the register no longer records it, the answer is the receipt's with retained: false if the register has evicted anything, and CORRUPT if it has not. A report may also age out when a newer report replaces it. Different content under the same command ID is CONFLICT either way.
  • Events are listed with their data fields in the observability catalogue, under the prefix work-items..
  • Bounds. Every bound refuses whole (LIMIT) and never cuts: 64 Products; 128 open and 128 closed items; 32 scope keys of at most 200 bytes; 16 links, 16 acknowledgements and 4 previous lanes per item; 16 log entries per item (the last is kept for the command that closes it); 16 open and 16 concluded comparisons; 120 characters in a title and 280 in a reason; 65,536 bytes in a request file.

Refusals

WorkItemsErrorCode: INVALID (shape, grammar, plain data, a command acting as the owner without its reason), LIMIT, NOT_CONFIGURED, NOT_FOUND, DUPLICATE and OVERLAP (with conflicts naming each item, its holder, state, lane, the shared keys and the measured covers), LANDED (the command line's pre-check found landed commits that already carry the work), HELD (not the holder, or a lane already held), STATE (an illegal transition or a closed item), COMPARISON, REVISION, CONFLICT, CONTENDED, CORRUPT and GIT_FAILED (a Git call the lane reader needed failed or returned something unreadable; a bound overrun inside a lane read makes that lane unknown instead). Stored state that fails validation is CORRUPT and is never repaired.

Command line

npm run factory:work -- <verb> (how to): init, configure, propose, claim, advance, release, supersede, compare, conclude, list, summary, stale and keys. It opens an existing journal only (init creates one and refuses an existing path or a missing parent directory), defaults the journal to <home directory path> in the command line alone, reads a regular UTF-8 JSON request of at most 64 KiB, and prints one JSON document with effect of not-started, unknown or recorded. The flags form of claim writes the request to --save before it executes, so a retry after an unknown effect is the same request with --input. With --repo, claim also checks the commits landed on the integration ref within the Product's recent-merged window and is refused as LANDED when its paths duplicate one of them, unless it follows that commit (follows: {kind: "commit", sha}) or acknowledges it as commit:<hash>. This check runs outside the journal transaction, which is safe because commits only accumulate, and it is advisory to the register. claim --from-branch adds the path keys a branch's diff gives. advance --repo to in-review derives the observed scope from the item's branch and writes the derived request to --save before it executes. stale reads every lane and prints a report; it journals it only with --record, and refuses to record a report observed after the register's clock (INVALID, exit 64), so a later takeover of an active item is never hidden behind it. keys prints the keys a branch's diff suggests, so existing lanes can be backfilled into the register. Exit codes: 0 completed (for stale, every lane was read); 2 a stale report with partial coverage; 64 invalid; 65 refused; 66 unavailable (an input, the store, an item or the Git repository); 70 corrupt or unexpected; 75 limit or contention.

Independent adoption gate

This records the gate in docs/composability.md. The module is not offered as independently usable until WI1b.

  1. Contract. Met in source. This page documents the entry points, inputs and outputs, codes, stable IDs, protocols and bounds. Dependencies: Node 26.8.1 or later with node:sqlite through the journal, and Git for the lane reader only. Importing starts nothing: the constructor reads no clock and the reader runs nothing until called.
  2. External consumer. Gap, tracked as WI1b: there is no package entry, because the distribution lists are shared with lanes in flight. The prevention register defers its entry for the same reason.
  3. Substitution. Met in tests. The core takes a caller-owned journal and clock; the classifier and report run on the recorded capture, on hand-built facts and on the real Git reader; a substitute lane reader cannot turn a claim into an authority, because findings are facts and the state machine decides.
  4. Failure and state. Met in tests: duplicates, invalid input, restart and crash replay, replay after eviction, corruption refused, contention, an unknown effect and every bound. No migration is needed.
  5. Composition. Met in part: the Factory uses the same contract through the command line, and the closure tests enforce the dependency direction. Lifecycle composition is WI1d.

Not established

  • Attribution only. Holders are attributed, not authenticated. Any writer of the journal can claim as anyone, and a command acting as the owner proves only that a reason was given. The file is trusted local storage.
  • Dedup is only as good as the keys. The path rules, the observed-scope check at in-review and the collision finding narrow the gap but cannot close it for work that declares nothing, skips in-review or has not yet touched a file.
  • Heuristics are a hypothesis. The lane thresholds were measured on one fixture of six lanes. Ports that move code to other files evade the two signals. The module proposes; a holder, the coordinator or the owner confirms.
  • Git facts are local and as read. There is no fetch, so the integration ref is as fresh as the last fetch. Remote-only branches are never read, and other hosts' worktrees are unknown. A report's Counts are exact only for the lanes this host can see. A repository that configures a filter driver has unknown worktree state.
  • No PR state. Nothing here reads a pull request (WI1c). A squash-merged lane in another Product can stand as likely superseded rather than merged.
  • A merged lane on an open item is not exact. An open item's lane whose tip is on the integration ref may hold none of the item's work: Git reads a branch cut after the claim the same way, so that finding is never exact. A lane whose commits predate its claim, such as a backfilled one, reads stale rather than merged once it is idle, which asks the holder instead of deciding.
  • No cleanup. Branches and worktrees are never deleted or bundled by the module.
  • Not wired. There is no wiring into lifecycle stages, the Product gate, the owner digest, Attention, the dashboard or a dispatcher (WI1c, WI1d), and no scheduled reports. A finding that needs the owner is meant to go through the ask ledger; nothing sends it yet.
  • No Portfolio check. A configured Product ID is not checked against Portfolio's registry.
  • Single host. The journal is single-host: no network filesystem or second machine.
  • The byte limit governs for large items. Typical items stay far under it, but a Product whose items each sit at the per-item maxima (32,511 bytes measured) holds only about 20 open ones, against about 270 typical ones. Eviction under byte pressure can shorten recent-merged coverage, which the summary reports as partial. Once anything is evicted, a state that lost a log entry reads as an eviction (retained: false), not as corruption.
  • Adoption gate point 2 is open (WI1b).
  • No cross-Product detection (WI2).
  • The reader reproduces one capture. Run over the bundles of the 2 October sweep, it gave the numbers the planner measured by hand for the six unmerged lanes; that is one fixture, not a calibration.
  • Nothing accepted yet. Reviews are in progress and none has passed both reviewers; the plan is not acceptance, and every epic stays open; WI1 adds evidence toward E06 only.

Reports bind the exact register version read before Git inspection; a concurrent change refuses recording with CONFLICT. Replays retain their original result. Active takeover notices use committed journal versions, so notices at the same clock instant are retained until included in a recorded report.

Source: docs/agents/work-items.md