Skip to content

Factory work: a plan checked by code, one agent per ticket, a thread whose scope is the plan - #181

Draft
sdcarlson wants to merge 4 commits into
claude/factory-intakefrom
claude/factory-plan-claim
Draft

sdcarlson wants to merge 4 commits into
claude/factory-intakefrom
claude/factory-plan-claim

Conversation

@sdcarlson

@sdcarlson sdcarlson commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Admission

Class: C
Agent-platform: claude
Reviewed-by: none recorded
Admitted-by: none yet. This is the second half of the subsystem claude/factory-intake starts, and it adds a section to AGENTS.md; both are Class C, so an agent drafted this and a person with the key admits it or closes it
Evidence: tested

Objective

What happens between a ticket from intake and a Build Thread: a plan is written before any code and checked by code, one agent claims the ticket, and the thread that builds it may change the plan's files and no others.

Stacked on claude/factory-intake. The base of this pull request is that branch, so the diff shows this packet alone. It follows stations 4 and 5 of Daniel Moka's "Build Your Own Software Factory" (craftbettersoftware.com): a planning agent writes files, steps and risks, and the build keeps four rules. Here the four rules are refusals in code and records on the ledger, not labels an agent is asked to respect.

What changed

  • syberlabs/factory/plan.py (new, pure: no I/O, no model)
    • check_plan refuses a planner's output unless it is one strict JSON object naming existing files that are tracked at HEAD, new files that are not (case folded), steps and risks. A step or a note that holds hidden markup, a credential shape or the shape of an order to an AI agent is refused: a plan is text a model wrote after reading a request, so it goes through the screen the request went through.
    • assess computes from the paths, never from the planner: the class floor of every path (a policy of policy.json's shape; this repository's own file is one), the files an agent reads as instructions (CLAUDE.md, AGENTS.md, .mcp.json, .claude/**), the components the paths belong to (a file that does not exist yet belongs to every component whose declared globs match it), what depends on them, and whether a test is among the paths.
    • plan_route is an ordered rule list with two routes. A plan that names an instruction file, floors above auto, touches a sensitive component, names a risk kept for people (auth, secrets, payments, data, release, external effect), or is larger than the limit waits for a person.
  • syberlabs/factory/work.py (new). A ticket's status is derived from events every time it is asked: held, open, plan_held, plan_rejected, planned, claimed, working, ready.
    • make_plan runs the planner command in a temporary checkout of HEAD (it can read the code, and nothing else of the operator's) under the environment intake gives a decider. A person can write a plan too; it goes through the same checks.
    • approve is a human act on a held plan.
    • claim and release: the check and the append are one acquisition of the ledger's lock, so of two agents claiming at once one is refused. A claim lapses after its ttl.
    • start writes a contract whose mutable scope is exactly the plan's files and starts an attended Build Thread on it. The kernel's existing scope rule then refuses any candidate that changes another path. The thread's class is computed from the plan's paths (auto R, auto with an evidence grade P, direction C, keys X), not declared. Its objective begins Fixes owner/repository#N for a GitHub issue.
    • settle records, once, that the thread holds an accepted change. It accepts, pushes and merges nothing.
  • syberlabs/factory/work_cli.py (new): syberlabs factory work list | plan | show | approve | claim | release | start | settle.
  • syberlabs/factory/intake.py: helpers this packet needs made public (run_reader with a working directory, credential_shapes, directive_shapes, strict_loads, named_command). One behavior change: a resolution's reason is now also refused for a URL with a password in it.
  • syberlabs/factory/space.py: glob_to_regex, the existing matcher under a public name.
  • AGENTS.md: a section, "Work taken from a factory ticket", with the four rules as what will be refused. It applies to ticket work only and says so.
  • Tests: tests/test_factory_work.py (35 tests), tests/fixtures/intake/standin_planner.py, a work path in the factory simulation campaign, one more case in tests/test_factory_intake.py.
  • Docs: docs/FACTORY_WORK.md (new), updates to docs/FACTORY_INTAKE.md and docs/FACTORY.md, a row in docs/ROADMAP_STATUS.md, spec/GAPS.md entry 69.

The four rules

Rule How it is kept
An agent takes only planned work work claim refuses a ticket with no plan, or with a plan that waits for a person (ticket_unplanned)
One agent works a ticket The claim is appended under the ledger's lock after the check (ticket_claimed)
The agent follows the plan The thread's mutable scope is the plan's files; the kernel refuses anything else (candidate_out_of_scope)
The change names its request The objective begins Fixes owner/repository#N, and publish.py writes the objective into the pull request body

What did not change

  • ledger.KINDS, every schema, every golden trace, every admission rule. The new events are note events.
  • The Build Thread. work start uses Kit.start and the scope rule as they are; a person still accepts, and pushing, opening a pull request and merging are still separate acts.
  • Invariant 8: the planner gets the scrubbed environment plus the operator's allow-list, which is less than a provider gets, and nothing is called a sandbox.
  • The declared layering (test_repository_layering_has_no_drift).
  • No model is called. Nothing is pushed, posted or merged.

Two texts that disagree, reported and not resolved

AGENTS.md says editing AGENTS.md is Class C. policy.json floors AGENTS.md at auto ("AGENTS.md and new spec identities are auto, as in the charter"). This pull request declares C, the higher of the two, and the plan rule for instruction files takes neither side: a plan from a stranger's request that rewrites what the next agent is told goes to a person whatever the floors say.

Evidence

Run in a Linux sandbox, CPython 3.13.18, 2 CPUs, at 29f6b98, the packet's commit:

SYBERLABS_BASE=07466c2 PYTHONPATH=. python scripts/run_shards.py
  1575 tests discovered; floor: all 1540 tests discovered on the base are here or excused by the diff
  Ran 1575 tests in 654s
  FAILED (failures=1, skipped=25, expected failures=8)
PYTHONPATH=. python -m conformance.run
  matched 23 golden traces
PYTHONPATH=. python -m unittest tests.test_factory_work tests.test_factory_intake -q
  Ran 95 tests ... OK

The one failure is test_console.ConsoleBrowser.test_the_purchase_order_path_completes_in_a_browser (page.waitForSelector: Timeout 30000ms). It fails the same way on main at 9abce6d in this sandbox, so it is not this change.

End to end, in tests/test_factory_work.py::Building: triage a request, plan it (the planner cannot see an untracked file), claim it (a second agent is refused), start the thread, propose a change inside the plan (acceptable) and one outside (candidate_out_of_scope), accept, settle. The ticket is ready, main has not moved, and the ledger verifies.

38 defects were planted in plan.py and work.py one at a time. The tests catch each one.

The branch has moved since, with no change to this packet's code. tests.test_factory_work, tests.test_factory_intake and tests.test_gaps (99 tests) reran at the head:

  • d0a391f merges the base branch's test fix (01ad07c).
  • a5e37d9 is a mistake of mine: a merge of the base branch's docs note, committed with its conflict in spec/GAPS.md unresolved and under the wrong message. It was the head for about three minutes.
  • b68cbcb repairs it (the markers are gone, entries 68 and 69 are whole) and adds the limit "an actor is a name", below. Docs only. If you would rather not have a5e37d9 in history, squash this pull request when it merges.

CI on the head, b68cbcb: every job is green: test on CPython 3.11, 3.12 and 3.13, windows, compose, G2 to G6, G8 and its strict run, policy, and admit, the repository's own admission run on the head's exact tree (verdict: acceptable, all_checks_passed, rule admission.passed). The browser test that fails in the sandbox is skipped there (playwright for node is not installed, an allowed skip), so CI does not show it passing.

Not run in the sandbox: Windows, CPython 3.11 and 3.12, PostgreSQL, conformance.clean_install.

Known limitations

  • No model has planned through this. Only the stand-in planner ran, and no pull request was opened from a thread it started. That GitHub closes the issue on merge is GitHub's documented behavior, not something observed here.
  • A plan names files, not lines. A builder may change anything inside a planned file; the steps are guidance in the objective and nothing checks a candidate against them.
  • The floors are path globs, and the named risks are a model's words. A plan that changes what a credential is used for in a file no rule names floors at auto.
  • The class is recorded, not enforced, as before. The scope rule is what keeps a candidate off a path.
  • Not a sandbox. The planner can read every tracked file and whatever its process can reach.
  • An actor is a name. work approve --by human:ID checks that the actor's kind is human and binds the event to no key. So the rule that a plan above auto waits for a person holds against a planner and a builder that act through their commands, and not against a process that can run the approval itself.
  • A claim is a record on one ledger. Agents on two machines do not see each other's claims, and a claim that lapsed while its holder was still working lets a second agent start a second thread.
  • work start starts the thread, then records it. A claim lost in between leaves a thread that is not recorded as the ticket's; the refusal names it.
  • A step is plain text here. Where the objective is rendered as Markdown, a link or a mention in it is live.
  • Details and the rest: docs/FACTORY_WORK.md ("Limits") and spec/GAPS.md entry 69.

Questions for the owner

  1. The first consumer, as asked on claude/factory-intake.
  2. The AGENTS.md section: is this the wording you want agents to read, and should every outside request pass through intake? The section does not say so; it covers ticket work only.
  3. The built-in floors add .github/** at direction when no policy file is passed. policy.json does not list it.
  4. Binding a person's act to a key, as asked on claude/factory-intake. Of everything open here, this is the one I would settle before agents run against a ledger they can write.

Handoff

  • Branch claude/factory-plan-claim, on claude/factory-intake: the packet's commit, two merges of the base branch and the repair.
  • Next: claude/factory-review-queue (a queue for the person who merges, stacked on this branch). After that: a planning agent behind the planner command; claims across machines.

https://claude.ai/code/session_01VHrJ4jU9Q3fnCogMET5bxs


Generated by Claude Code

…whose scope is the plan

What happens between a ticket from intake and a Build Thread. Stacked on
claude/factory-intake.

- plan.py (pure): check_plan refuses a planner's output unless it is one strict JSON
  object naming files tracked at HEAD, new files that are not, steps and risks; a
  step or note with hidden markup, a credential shape or the shape of an order to an
  AI agent is refused. assess computes from the paths, never from the planner: the
  class floor (a policy of policy.json's shape), the files an agent reads as
  instructions, the components the paths belong to and what depends on them, and
  whether a test is among them. plan_route is an ordered rule list: an instruction
  file, a floor above auto, a sensitive component, a risk kept for people, or a plan
  over the limit waits for a person.
- work.py: a ticket's status is derived from events each time it is asked (held,
  open, plan_held, plan_rejected, planned, claimed, working, ready). make_plan runs
  the planner command in a temporary checkout of HEAD under the environment intake
  gives a decider; a person can write a plan and it goes through the same checks.
  claim checks and appends under one acquisition of the ledger's lock, so one of two
  agents is refused. start writes a contract whose mutable scope is exactly the
  plan's files and starts an attended Build Thread; the kernel's scope rule refuses
  any other path. The thread's class is computed from the plan's paths, and its
  objective begins "Fixes owner/repository#N" for a GitHub issue. settle records,
  once, that the thread holds an accepted change.
- work_cli.py: syberlabs factory work list|plan|show|approve|claim|release|start|settle.
- intake.py: run_reader (with a working directory), credential_shapes,
  directive_shapes, strict_loads and named_command made public for this packet; a
  resolution's reason is also refused for a URL with a password in it.
- AGENTS.md: "Work taken from a factory ticket", the four rules as what is refused.

Nothing proposes, accepts, pushes, opens a pull request or merges. No model is
called: tested with a stand-in planner (tests/test_factory_work.py, 35 tests; the
factory simulation campaign). ledger.KINDS, the schemas and the golden traces are
unchanged; the new events are note events. spec/GAPS.md entry 69 says what is open.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VHrJ4jU9Q3fnCogMET5bxs
Brings in 01ad07c, a test-only fix for a check that could fail by chance
(a digest spelling the author's name). No change to this packet's code.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VHrJ4jU9Q3fnCogMET5bxs
…ature

`work approve --by human:ID` checks that the actor's kind is human and binds the
event to no key. The rule that a plan above auto waits for a person therefore
holds against a planner and a builder that act through their commands, and not
against a process that can run the approval itself. Stated in the limits of
docs/FACTORY_WORK.md and in spec/GAPS.md entry 69 (10); the sentence comparing a
label with an event no longer says more than that. Docs only.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VHrJ4jU9Q3fnCogMET5bxs
…is an actor name

a5e37d9 is a merge of claude/factory-intake that was committed by mistake with
its conflict unresolved: spec/GAPS.md kept the conflict markers around entries
68 and 69, and the commit carried the message meant for the change below. This
commit removes the markers (entry 68 as the intake branch has it, entry 69 as
this branch has it) and makes that change:

`work approve --by human:ID` checks that the actor's kind is human and binds the
event to no key. The rule that a plan above auto waits for a person therefore
holds against a planner and a builder that act through their commands, and not
against a process that can run the approval itself. Stated in the limits of
docs/FACTORY_WORK.md and in spec/GAPS.md entry 69 (10); the sentence comparing a
label with an event no longer says more than that. Docs only.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VHrJ4jU9Q3fnCogMET5bxs
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants