Skip to content

Factory: Guard trunk conflicts, file follow-ups for partial PRs, and keep worktrees in the checkout - #1115

Merged
epeicher merged 3 commits into
trunkfrom
update/factory-run-refinements
Nov 21, 2026
Merged

epeicher merged 3 commits into
trunkfrom
update/factory-run-refinements

Conversation

@epeicher

@epeicher epeicher commented Nov 21, 2026 •

Copy link
Copy Markdown
Collaborator

What it does

A full /factory run over the queue (twenty jobs) stopped or went wrong in several places. This branch fixes them:

  • Worktrees: job worktrees and the trunk site's worktree live under factory/worktrees/ in the checkout that runs the factory.
  • Trunk conflicts: job push refuses a branch that conflicts with trunk and names the files, and job ci reports a conflicting PR as CI: FAIL with the reason.
  • Partial deliveries: a job intake narrowed opens its PR with Related to #<issue>, and merging it files the parts intake left out as new factory issues.
  • PR body edits: job body <job> <file> replaces the body of the job's own PR, so a builder never runs gh pr edit.
  • Stale agents: job queue warns when the main checkout's agents or /factory skill differ from this checkout's.
  • Agent instructions: intake and triage read code from the trunk checkout; reviewers write their file before replying; the UX and UI reviewers list what they looked at; the runtime reviewer takes its screenshot pairs again every round; scratch files stay in the job's worktree.
  • Smaller fixes: the gate stops its PHPUnit stack when it exits, the Slack notice for a held PR carries the reporter's reason, and a queue hold row names what is ahead of it.

Rationale

Each item is something the run hit:

  • Worktrees. A Claude Code worktree session may only write inside its own folder. Job worktrees sat beside the checkout (<name>-factory/<job-id>), so every builder was refused its first edit.
  • Trunk conflicts. GitHub runs no pull_request checks on a PR that conflicts with its base. After another Pages PR merged, a factory PR passed all five reviews and then waited ten minutes for checks that could not start; CI: NONE would have sent a fixable job to a maintainer.
  • Partial deliveries. Intake rescopes umbrella issues to one slice. The PR still said Closes, so merging it would have closed an issue with work left in it and nothing queued for the rest.
  • PR body edits. gh pr edit sits behind the operator's permission prompt, so a builder that updated its PR body in a later round stopped the run until someone answered.
  • Stale agents. A worktree session loads .claude/agents/ and the skill from the main checkout while the scripts run from the session's checkout. This run started with the previous day's agents stepping the new scripts.
  • Agent instructions. Intake read the orchestrating checkout, which was on a feature branch. One reviewer returned its review as a reply and wrote no file. Two UX and UI reviews came back as a pass in about fifteen seconds with nothing looked at. A round 2 runtime review saved no pairs, so the PR kept round 1's screenshots. Two builders overwrote each other's PR body draft in a shared temp folder.

For conflicts, failing the gate was the other option. It costs a round and still spawns no fix, while refusing the push lets the builder merge trunk inside the round it is already in.

Implementation

All in factory/bin/job unless noted. docs/software-factory.md covers each change.

Conflicts. One helper answers both commands:

def conflicts(job):
    """Files where the job's branch conflicts with the latest base branch."""
    git(job, "fetch", "--quiet", "origin", BASE)
    res = git(job, "merge-tree", "--write-tree", "--name-only", f"origin/{BASE}", "HEAD", check=False)
    if res.returncode == 0:
        return []
    return res.stdout.split("\n\n", 1)[0].splitlines()[1:] or [f"(git merge-tree failed: {res.stderr.strip()})"]

cmd_push dies on a non-empty list. cmd_ci asks GitHub for mergeable on each poll and writes CI: FAIL at once when no check has reported and the PR is CONFLICTING. That keeps the normal path: a red CI is a failed round, and the builder reads ci.md.

Follow-ups. Intake writes a ## Follow-ups section (### <title> plus a few sentences each) when it sets RESCOPED: yes. On → merged, when the PR's closingIssuesReferences lacks the job's issue, file_followups() creates one issue per entry with the queue label, up to max_followups (new in factory/config.json, default 5). It records each in followups.json as it goes, so a failed gh issue create stops the move and a retry files only what is missing. The umbrella issue gets one comment naming them and leaves the queue. own_issues() reads Related to #<n> from the PR's first line, so another checkout still sees the issue as taken. Refs #<n>, which the open factory PRs carry, reads the same.

job body. For an issue job in build only. It refuses a file outside the worktree, a PR whose head is not the job's branch, and a body that does not open with Closes #<issue> or Related to #<issue>. The Screenshots block and the Playground preview block are copied from the live body when the new one leaves them out.

Worktrees. WORKTREES = FACTORY / "worktrees"; sync() adopts a job whose worktree was moved there. factory/trunk.sh and factory/seed.sh use the same folder, .gitignore ignores it, and phpcs.xml.dist excludes it so host phpcs does not walk every job's copy of the plugin.

Gate. factory/checks.sh sets an EXIT trap that stops the tests stack it started.

Testing instructions

From a Claude Code worktree of this branch, with the main checkout on trunk:

  1. factory/bin/job queue. Stderr names the agent files that differ from the main checkout's; stdout lists the queue as before. After the main checkout pulls this branch, the warning is gone.
  2. factory/trunk.sh, then ls factory/worktrees/: trunk is there, and git status shows nothing new.
  3. vendor/bin/phpcs -n with job worktrees present finishes in about the time it takes without them.

What the run itself showed on this code:

Not exercised on a live job: job push refusing a conflicting branch (only the passing path ran), and job body called by a builder. I checked job body, the merged transition and the review transitions against a stubbed gh on throwaway jobs; those scripts are not part of this branch.

Open WordPress Playground Preview

@epeicher
epeicher enabled auto-merge (squash) November 21, 2026 18:06
@epeicher
epeicher merged commit cd1b8f9 into trunk Nov 21, 2026
7 checks passed
@epeicher
epeicher deleted the update/factory-run-refinements branch November 21, 2026 18:11
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.

1 participant