Skip to content

spec(epic): Claude Code-style lab refinements: repositories, one sidebar, a status line, a harness and plan mode (FIX-2592) - #4873

Merged
jhoffner merged 3 commits into
mainfrom
epic/claude-code-style-refinements
Nov 7, 2026
Merged

jhoffner merged 3 commits into
mainfrom
epic/claude-code-style-refinements

Conversation

@jhoffner

@jhoffner jhoffner commented Nov 6, 2026 •

Copy link
Copy Markdown
Collaborator
A team that… Today After this epic
works in the lab every day Two views hide half the sessions One sidebar; the keys cross all sessions
starts a session on a repository Picks a "project". A new repository needs a restart Picks a type and a repository. Adds one in Settings while the lab runs; its runs use a git worktree of it
waits on a long turn Scrolls down to see the status The working line stays in view
asks for a code change A Coder chip picks a worker. Plan mode is broken Picks a harness, then one of its models. Signs a plan off before work starts
builds on the workspace or harness packages Repositories are fixed at host start. No harness package is asked about plan mode Add and remove repositories at run time. Each harness says its models and plan mode

Goal: In the Claude Code-style lab, a person registers a repository once in Settings, starts either kind of session on it from one sidebar, and chooses a harness and one of its models. Where the harness has a plan mode, the person signs the plan off before work starts. Every run uses a git worktree of the real repository.

flowchart LR
  A["a real lab · started with no repository · a browser"] --> L1["leg a · add a repository in Settings · run on it · restart"]
  A --> L2["leg b · both session types in one sidebar · a long turn"]
  A --> L3["leg c · pick a harness · its models · the run reports both"]
  A --> L4["leg d · a plan · changes asked · sign-off · then work"]
  L1 -->|"a worktree in that repository's own git · list survives"| P["PASS · the epic's goal is met"]
  L2 -->|"one list · keys cross it · line in view"| P
  L3 -->|"the run's own harness and model"| P
  L4 -->|"no file changed before sign-off"| P
  C["control · today's main"] -.-> A
  A -.->|"under the control"| F["must FAIL · every leg"]
Loading

Four legs, because the repository leg alone passes while the lab still cannot pick a model. The closure issue FIX-2596 runs the check and reports each leg by itself. Today's main must fail every leg.

What's in the box: the lab's sidebar, dialog, Settings, working line, harness and model choice and plan mode; the packages' runtime registration and each harness's plan mode. A fence: registering a repository is an operator act, refused by the package unless the host is built to allow it. Not built: workstreams and members in any screen, the trust flag, live join, rename and search, a live-checkout opt-out, any workforce package change

The fence is the cost of the worktree: a run acts with the operator's own access to the repository. The package refuses registration unless the host is built to allow it; the lab allows it by the bind.

Why now. The owner's review of the lab found these gaps together. The pieces exist: FIX-2403's checks are merged, FIX-2369 ER-5 puts a run in a worktree, and FIX-2458's spec gives each harness a model list.

The set: six issues and a closure issue. FIX-2458 and FIX-2585 are consumed, not owned. As of 2026-11-06 all are in Backlog. The spec links to the live state.

Who owns what: eleven rules across FIX-2593, 2597, 2594, 2595, 2598, 2599, the closure and the coordinator, each rule with exactly one owner

Every rule has one owner. Two owners would be a seam. No owner would be a gap.

Sign off

The goal, at that size: four legs, in the browser. If wrong: we ship a lab that adds repositories and still cannot pick a model.

The set's debt: slightly up. The lab loses a switch, a private list, a hand list and a plan worker. The packages gain two entries, one a permanent public call. If wrong: a project row that nobody can delete.

The objective. It serves goals 1 and 4 of docs/objectives.md, narrowly. It does not move the Phase 1 finish line, except through one new goal in the closure.

A run uses a worktree of the real repository, and the package registers one while running · D2

A worktree of the real repository, chosen, beside a copy under the data folder. Decides it: where the person sees the work. Price: the run acts with the operator's access, and the lab waits on a package entry

It comes down to where the work lands. If wrong: a run moves a branch the operator did not expect.

Open · Adding a repository in Settings: on at any bind, or only at loopback? · Q1

On at loopback and off elsewhere, recommended, beside on whatever the bind. Decides it: whether a second person can reach the lab. Price: a check of the bind and a flag

I recommend loopback only. A signed-in user is not the operator. If wrong: a flag nobody needed.

Open · What does the sidebar call the coordinator group? · Q2

Coordinators, recommended, beside Workstreams and Project Sessions. Decides it: whether the word clashes with one nearby. Price: a line of help for a newcomer

I recommend Coordinators. Workstreams is a Shift Manager palette group. Project Sessions puts project back beside Repository. If wrong: one label changes.

What would change my mind on D2: an operator who refuses a run access to a repository's branches. Reasoning and the rules every child obeys: DECISIONS.md.

Analysis: right approach, with folds. The host now keeps the list of admitted repositories. Removal is refused while a worktree exists. FIX-2597 waits behind FIX-2458. A review moved the registration gate into the package (ER-4). DECISIONS.md → Analysis.

Reviewers · look here

  • Is it one epic or two? The harness, model and plan work shares no decision with the repository work. I recommend two epics. The owner kept one set. A wrong answer delays the repository half behind plan mode's diagnosis.
  • Decisions → ER-1. The host keeps the admitted list, not the project rows. If it falls, FIX-2593 and FIX-2594 change.

Not here: any single issue's approach. Those are the spec PRs.

Spec · Decisions · Linear FIX-2592 · Project: Workforce: Shift Manager · merges after human approval and required checks

How to review this — an epic-spec, not an implementation plan

This is an epic-spec: the shared objective and cross-cutting decisions for a set of
issues, in a retained document set. It is not any one issue's implementation design, and it
is not a schedule.

In scope to challenge:

  • The objective and the goal in SPEC.md — is this body of work worth doing, and is the
    goal the real need at full size, or a smaller one the set could meet while the need stays
    unmet? Would the closure issue's check fail if the goal were not met?
  • Whether the set overbuilds. Each issue can earn its place while the whole is too much.
    That question can only be asked here.
  • The set's debt in SPEC.md — something the set overlaps and doesn't name, or adds and
    doesn't list.
  • Builds on / Adds in that same section — an Adds item that does not name the existing
    piece it considered, or that is a second mechanism for something we already have
    (orchestration.md).
  • A cross-cutting decision in DECISIONS.md — shared surface, naming, sequencing, contracts.
  • A rule in DECISIONS.md → Who owns what with no owner, or two.
  • A missing issue the objective implies, or one in the set that doesn't serve it.

Out of scope — owned by the individual issue specs:

  • Any single issue's approach, architecture, file layout, or test plan.
  • Anything that touches exactly one issue. It belongs on that issue's spec PR.
  • The figures, at the pixel level, and routine status movement since the dated snapshot.
  • POC production polish. End-state experiments under the owning spec's poc/
    show shape and scoping, not shippable implementation. Directional evidence, experimental
    isolation and absence of secrets/generated dependencies remain in scope.

Feedback in the second list is routed to the issue it concerns as an implementer note, not
folded in here.

Required repository checks, approvals and review-thread policy still govern merge.
Optional comments are triaged, not a reason to grind to zero or restart the design review.

🤖 Generated with Claude Code

jhoffner and others added 2 commits November 6, 2026 17:43
…sidebar, a status line, a harness and plan mode

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…2597 behind FIX-2458, the choice rides the task

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@jhoffner jhoffner self-assigned this Nov 6, 2026
@vercel

vercel Bot commented Nov 6, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
flow-state-dev-build-site Ready Ready Preview Nov 6, 2026 11:28pm UTC
flow-state-dev-docs Ready Ready Preview Nov 6, 2026 11:28pm UTC
1 Skipped Deployment
Project Deployment Actions Updated
flow-state-dev-ui Ignored Ignored Preview Nov 6, 2026 11:28pm UTC

Request Review

@linear-code

linear-code Bot commented Nov 6, 2026

Copy link
Copy Markdown

FIX-2592

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 6, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-06T23:27:45.922828Z 61b4b6d New commits
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

jhoffner commented Nov 6, 2026

Copy link
Copy Markdown
Collaborator Author

Second look + architecture pass (spec PR #4873)

Read SPEC.md and DECISIONS.md against packages/workspace/src/local-host.ts. This is a spec PR, so the findings are about direction and seams, not code. Ordered by how much they change the approach.

1. Split the epic (agree with the PR's own recommendation, and I'd go further)

The harness/model/plan legs (FIX-2597/2598/2599) share no decision with the repository legs (FIX-2593/2594). The spec says so itself. They differ in the following ways:

  • They touch different packages.
  • They have different blockers: FIX-2458 and a plan-mode diagnosis, versus a published-package change.
  • Leg d needs a real signed-in Claude Code, and leg a doesn't.

Keeping one set means the closure (FIX-2596) can't run until the slowest leg lands. The repository half is held behind leg d's real-Claude requirement. Suggestion: two epics and two closures. If the owner wants one set, make the closure legs independently reportable, so a leg-d environment problem doesn't block a leg-a pass.

2. ER-1: the lock and the persisted list need one owner of "what is admitted"

local-host.ts builds localRepositories as an immutable Set and derives fetchPins from it at construction (lines ~643-644). It is then read in at least 6 places (1378, 1392, 2013, 2038, 2054, 2191). Making it mutable at run time is more than "extends the same set":

  • Each read site currently assumes the set is fixed for the host's lifetime. Concurrent add/remove against an in-flight land, nestedWorktrees or push check can see a repository appear or vanish mid-operation.
  • ER-3 checks "no worktree exists" before removal. A run can create a worktree between that check and the removal. Say whether registration state and worktree creation share one lock. The spec names "the host's in-use lock", so state that it is the same lock.
  • Suggestion: have FIX-2593 expose one RepositoryRegistry (add / remove / list / has) and route all six read sites through it, instead of leaving a bare Set that something mutates. That is the deepening opportunity here. It is also the natural home for the persisted file and the CLAUDE_CODE_STYLE_REPOSITORIES seed, which are otherwise two writers to one list.

3. ER-4 / Q1: the gate should live in the package, not the lab

ER-4 assigns "decided by the transport" to FIX-2594 (the lab). But the epic's own argument is that the registration call is a package capability that grants operator-level access. If the lab is the only place that checks the bind, any other host app built on the package gets an ungated register().

  • Suggestion: FIX-2593's register takes an explicit capability or option, such as allowRuntimeRegistration on the host, default off. The lab sets it from the bind. This also removes the flag you'd otherwise add in the lab. It keeps BP-031 true at the right layer and answers Q1 structurally.
  • Q1 recommendation (loopback only) is right. One caution: "bound to loopback" is a property of the process, not of a request. Behind a reverse proxy or a port-forward (e.g. a cloud devbox, which is how this repo is used) the app sees loopback while the caller is remote. The spec should say the check is on the bind address plus an explicit operator flag, never on req.ip/Host.

4. D2: "worktree of the real repository" has an unstated cost

  • Git refuses to check out one branch in two worktrees, and worktree metadata (.git/worktrees) is written into the operator's repository. Neither the spec nor the closure's leg a covers an operator mid-rebase or on a dirty or detached HEAD in the real checkout. Leg a should include "operator's checkout is dirty / on the branch the run wants".
  • Pruning: a crashed run leaves .git/worktrees/<id> in the operator's repo. ER-3 refuses removal while worktrees exist, so a stale one blocks removal permanently with no retire state ("No retire state"). Say how a stale worktree is reconciled, e.g. git worktree prune on startup and on the refusal path.

5. FIX-2595 should drop out of the set

The spec already concedes it is "five lines beside a sticky pattern the lab already has" and the one the set could cut. A child with a spec route, a spec PR and a closure leg for a 5-line change is the restraint failure the analysis names. Ship it as adhoc-quick-fix and keep leg b to the sidebar. That also removes the Thread.tsx/Entry.tsx merge-order seam in "Coordination seams".

6. Plan sign-off: don't leave the mechanism open past the spec

FIX-2599 "picks one" of the review stop or the tool-approval hold. ER-10 and the plan leg already depend on it. Recommend deciding in the epic: reuse the existing review stop. Rationale: it is already a user-visible hold with Resolve/Request changes, which matches leg d ("changes asked, sign-off, then work"). A tool-approval hold models a different thing (a single call), and the spec says "no new kind of hold".

7. Smaller notes

  • Q2: agree on Coordinators. Nothing to add.
  • "The set's debt: about flat" counts a persisted list and a published-API addition as flat. I'd call it slightly positive, because a public registration API is permanent (the spec says so). Fine, but say positive.
  • ER-10: storing the harness/model choice in task input vs session state vs a harness-manager feed is left to FIX-2598. That's a three-way fork that FIX-2599 and the closure depend on. If it needs a package child, that child should be named now so it isn't discovered after FIX-2597 merges.
  • specs/issues/FIX-2369, FIX-2585 and FIX-2152 are cited as decision sources but aren't in specs/issues/ in this checkout (only FIX-2403 and FIX-2458 are). Confirm the links resolve on main, or the "Already here" table cites docs reviewers can't open.

Verdict

Direction is sound. Highest value changes before merge: (1) split or decouple the closure legs, (2) specify the registry/locking model for runtime registration, (3) put the registration gate in the package, (5) cut FIX-2595 to a quick fix.


Generated by Claude Code

Comment thread specs/epics/FIX-2592/SPEC.md Resolved
Comment thread specs/epics/FIX-2592/SPEC.md Resolved
jhoffner added a commit that referenced this pull request Nov 6, 2026
FIX-2592, Claude Code-style refinements, is filed under the project with
its epic spec in review as #4873 and seven children, all Backlog. It gets a
row, a graph node related to FIX-2152, and an arc lane with a filing tick.
Re-derived from Linear and the implementation PRs: FIX-2516's epic spec
merged Nov 5 as #4766 (amendment #4787 open), so it moves to in flight with
10 children; FIX-2369 78 of 95 done; FIX-2152 48 of 51 done; FIX-2490 6 of
13 unchanged. Counts 6 done, 4 in flight, 9 not started, 1 dropped. Now
line and in-flight bars moved to Nov 6 23:17 UTC.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…nes and excludes, each leg reported alone

ER-4 moves to FIX-2593 (registration off unless the host is built to allow it); ER-3 prunes a crashed run's worktree and excludes a concurrent add; the closure reports each leg by itself; SPEC rows match ER-3 on occupancy and Remove; FIX-2597's graph edge and figure no longer carry model lists; debt read slightly up; predecessor anchors made exact.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@gitar-bot

gitar-bot Bot commented Nov 6, 2026

Copy link
Copy Markdown
Code Review ✅ Approved 2 closed / 2 findings

🟢 Low risk · The PR adds epic specifications and diagrams only; these document proposed behavior without changing executable code or runtime interfaces.

Epic spec for Claude Code-style lab refinements (repositories in Settings, one sidebar, working line, harness and model choice, plan mode) with its decisions and ownership rules. Two prior spec inconsistencies were resolved: Remove no longer reuses setRepository and the in-use lock, and the flow graph and end-state figure now give FIX-2597 the model lists. No open findings remain.

✅ 2 closed
✅ Quality: SPEC says Remove reuses setRepository and the in-use lock; ER-3 forbids both

📄 specs/epics/FIX-2592/SPEC.md:135 📄 specs/epics/FIX-2592/SPEC.md:144 📄 specs/epics/FIX-2592/DECISIONS.md:130 📄 specs/epics/FIX-2592/DECISIONS.md:162-164 📄 specs/epics/FIX-2592/DECISIONS.md:207-211
SPEC's 'Already here' row says setRepository on a project and the host's in-use lock are reused as "the one occupancy signal, and Remove". The 'Adds' row for FIX-2593 also lists the in-use lock among the guards it extends. DECISIONS says the opposite. ER-3 refuses removal based on what git worktree list shows under the host's root, because the analysis found the in-memory lock was unsafe across a restart and a review wait. The 'Decided in review' list also says Remove unregisters the repository from the host list, with "No setRepository(null)". FIX-2593 and FIX-2594 will be written against this spec, so an implementer who follows the SPEC table rebuilds the removal path the analysis rejected. Fix: change both SPEC rows so occupancy comes from git's worktree list and Remove means unregistering from the host's list.

✅ Quality: Flow graph and end-state figure still give FIX-2597 the model lists

📄 specs/epics/FIX-2592/SPEC.md:95 📄 specs/epics/FIX-2592/SPEC.md:80 📄 specs/epics/FIX-2592/DECISIONS.md:136 📄 specs/epics/FIX-2592/figures/end-state.svg
The analysis fold moved the model lists to FIX-2458. ER-9 says "Models are FIX-2458's", and the set table says FIX-2597 only adds plan mode and lifts out the model-choice shape. Some places still use the old ownership. In the flow graph, the FIX-2597 node is labelled "harness packages: models and plan mode", and its edge to FIX-2598 hands over "the model lists and the capability". The FIX-2597 box in end-state.svg says "Each harness: its models, a plan mode?". The 'Five teams' row also says FIX-2458 already gives the packages a model list, but its build has not merged. A reader of the graph would expect FIX-2597 to deliver model lists, which repeats the ownership overlap that ER-9 was written to remove. Fix: relabel the FIX-2597 node as 'plan mode and the choice shape', and its edge as 'the plan capability and the choice shape'.

Verification

Rules No rules evaluated

Functional validation Not enabled

Set up

For more verification details, comment gitar display:verbose.

Options

Auto-apply is off → Gitar will not commit updates to this branch.
Display: compact → Showing compact verification results.

Comment with these commands to change the behavior for this request:

Auto-apply Compact
gitar auto-apply:on         
gitar display:verbose         

Was this helpful? React with 👍 / 👎 | Gitar

@jhoffner
jhoffner added this pull request to the merge queue Nov 7, 2026
Merged via the queue into main with commit 5ff9960 Nov 7, 2026
23 of 25 checks passed
@jhoffner
jhoffner deleted the epic/claude-code-style-refinements branch November 7, 2026 00:17

This branch was successfully deployed

1 active deployment
Preview – flow-state-dev-docs — 61b4b6d2 Deployed Nov 6, 2026 by vercel[bot]
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