Repository navigation
spec(FIX-1927): a local checkout's run starts from the current base #3198
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
Retained issue spec: before cutting a new run's branch in a listed local repository, the workspace host fetches the base's upstream branch and cuts from whichever of local and upstream is newer; a split base is refused as base-diverged; a failed fetch falls back to the last-fetched copy with a warning. Listing the checkout admits the fetch, because both local entry points (the Lab's fsd profile and harness-manager's hostForConfig) allow no remote. No setting. One PR in workspace, one line in harness-manager. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01GJ9UL2RHLrxJsiGFnkuxjt
- Loading branch information
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,61 @@ | ||
| # FIX-1927 · Business rules | ||
|
|
||
| [Spec](SPEC.md) · [Decisions](DECISIONS.md) · **Rules** · [Plan](PLAN.md) · [Docs](DOCS.md) · [Evolution](EVOLUTION.md) | ||
|
|
||
| The cases, written as rules. Every row is about a **new** branch cut in a repository the host | ||
| lists in `localRepositories`. "Local" is the base as the repository has it; "upstream" is its | ||
| remote-tracking copy after the fetch, or as last fetched. The *proved by* column is the check | ||
| the plan runs. | ||
|
|
||
| ## Where a new run starts | ||
|
|
||
| | # | When | Then | Proved by | | ||
| |---|---|---|---| | ||
| | BR-1 | Upstream has commits local lacks (behind) | The branch is cut at upstream's commit. Local's ref, index and working tree are unchanged | CI · `starts-from-upstream`, `local-base-unmoved` | | ||
| | BR-2 | Local has commits upstream lacks (ahead) | Cut from local, as today | CI | | ||
| | BR-3 | Local and upstream are the same commit | Cut from local, as today | CI | | ||
| | BR-4 | Each has commits the other lacks (split) | Refused, `WorkspaceRefusedError` reason `base-diverged`, naming the checkout, the base and both commits, and saying to pull or rebase, or push. No worktree, branch or marker is left | CI · `split-refused` | | ||
| | BR-5 | `baseRef` is omitted and `HEAD` is on a branch with an upstream | As BR-1 to BR-4 for that branch. The recorded `baseRef` stays `HEAD` | CI | | ||
| | BR-6 | The base has no upstream: a tag, a commit id, a detached `HEAD`, a branch with no tracking, a branch tracking another local branch, or a remote-tracking ref such as `origin/main` | Cut from the base as given, exactly as today. No fetch, and no git process reaches any remote | CI · existing suite unchanged | | ||
| | BR-7 | The base doesn't exist locally, even if upstream has it | Refused as today (`remote-unreadable`, naming the ref) | Existing suite | | ||
| | BR-8 | A branch is cut | `place.repo.baseRef` is the ref asked for; `place.repo.baseCommit` is the commit cut at | CI | | ||
|
|
||
| ## The fetch | ||
|
|
||
| | # | When | Then | Proved by | | ||
| |---|---|---|---| | ||
| | BR-9 | A new branch's base has an upstream | Only that upstream branch is fetched, from its remote. Only its remote-tracking ref changes; no local branch, tag, index or file moves | CI · every local ref compared before and after | | ||
| | BR-10 | The upstream's URL fails the shape check: a leading `-`, a transport helper, whitespace, a credential, or a scheme other than `https`, `ssh` or `file` | Not fetched; no git process is given the URL. The comparison uses the last-fetched copy, and a warning names the redacted URL | CI · a planted `ext::` URL | | ||
| | BR-11 | The fetch fails: offline, a credential refused, a ref lock held, a timeout | Not a refusal. The comparison uses the last-fetched copy; `console.warn` names the checkout, the upstream and git's error | CI · an upstream path removed after the clone | | ||
| | BR-12 | The fetch fails and no copy was ever fetched | Cut from local, as today, with the same warning | CI | | ||
| | BR-13 | The remote wants a password | It fails at once (no terminal prompt), then BR-11 | CI by construction (the host's git environment) | | ||
| | BR-14 | The fetch hangs | It times out inside a bounded slice of the provision budget, then BR-11. The provision still finishes inside its budget | CI · fake clock | | ||
| | BR-15 | The host's `remotes.allow` is empty or doesn't name the upstream's host | The fetch still runs: listing the checkout admits its own upstream ([D3](DECISIONS.md#d3)) | CI · host built with `allow: []` | | ||
| | BR-16 | A run's project isn't mapped and its remote isn't allowed | Refused by `remotes.allow` before any git process, as today. Nothing is fetched | Existing suite | | ||
|
|
||
| ## What is never fetched or moved | ||
|
|
||
| | # | When | Then | Proved by | | ||
| |---|---|---|---| | ||
| | BR-17 | The run's branch already exists: a retry, a continuation, or a worktree re-added after `git worktree remove` | Handed back. No fetch, no comparison, no move | CI · git commands counted | | ||
| | BR-18 | Two runs on one checkout are provisioned at once | Both start. A fetch that loses a ref lock to the other follows BR-11 | CI | | ||
|
|
||
| ## Both entry points, and what the run reports | ||
|
|
||
| | # | When | Then | Proved by | | ||
| |---|---|---|---| | ||
| | BR-19 | harness-manager's `workspace: { sourceRepo, baseRef }` cuts a run | The same rules: it goes through the same host path | CI · one case through `provisionCheckout` | | ||
| | BR-20 | A run cut from upstream, ahead of local `main`, makes commits | `readRunCommits` reports only the run's commits, whatever the upstream's remote is called | CI · harness-manager | | ||
|
|
||
| ## Failure taxonomy | ||
|
|
||
| One case is fatal: a split (BR-4), refused before anything is made, and clearing once the | ||
| person pulls or pushes. A missing base stays fatal, as today. Every fetch problem degrades to | ||
| the last-fetched copy with a warning, and never to a refusal. Nothing retries. | ||
|
|
||
| ## Acceptance criteria this issue owns | ||
|
|
||
| [The goal](SPEC.md#the-goal-and-how-well-know-its-met): with a host built as the Lab builds it, | ||
| a run on a checkout whose upstream moved ahead starts from upstream with the person's `main` | ||
| untouched, and a split is refused with nothing made. Today's `main` must FAIL | ||
| `starts-from-upstream`. | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,101 @@ | ||
| # FIX-1927 · Decisions | ||
|
|
||
| [Spec](SPEC.md) · **Decisions** · [Rules](BUSINESS-RULES.md) · [Plan](PLAN.md) · [Docs](DOCS.md) · [Evolution](EVOLUTION.md) | ||
|
|
||
| What was chosen, what lost, and what each choice locks in. D1 and D2 record the engineer's | ||
| brief; D3 is where the code on `main` corrected it. | ||
|
|
||
| ## The tree | ||
|
|
||
| ```mermaid | ||
| flowchart TD | ||
| I["FIX-1927"] --> D1["D1 · fetch upstream · start from the newer · refuse on a split"] | ||
| D1 -.->|"rejected"| X1["refuse when behind · a chore for every stale laptop"] | ||
| I --> D2["D2 · failed fetch · last-fetched copy and a warning"] | ||
| D2 -.->|"rejected"| X2["refuse · offline stops every run"] | ||
| I --> D3["D3 · listing the checkout admits its upstream"] | ||
| D3 -.->|"rejected"| X3["remotes.allow only · the Lab never fetches"] | ||
| ``` | ||
|
|
||
| Solid edges are what you're signing. Dashed edges lost, and the label says why. | ||
|
|
||
| <a name="d1"></a> | ||
| ## D1 · Fetch the base's upstream, start from the newer of local and upstream, refuse only when they have split. No setting | ||
|
|
||
| | | | | ||
| |---|---| | ||
| | **Instead of** | Refusing the run whenever the local branch is behind its upstream | | ||
| | **Because** | Behind is the common case and catching up is mechanical, so the host does it. Ahead means unpushed commits the person meant to build on. Only a split needs a person's choice, so only a split refuses. One default covers all three, so no setting ([tenet 3](../../../docs/philosophy.md#3-earn-every-addition)) | | ||
| | **Locks in** | A run's branch can hold upstream commits the person's `main` lacks, so review must exclude both copies. Pinning runs to the local branch would be a new setting later | | ||
|
|
||
|  | ||
|
|
||
| It comes down to the person who hasn't pulled: refusing turns a mechanical catch-up into a chore on every run. | ||
|
|
||
| <a name="d2"></a> | ||
| ## D2 · A fetch that fails does not stop the run: it compares with the last-fetched copy and warns | ||
|
|
||
| | | | | ||
| |---|---| | ||
| | **Instead of** | Refusing the run when the fetch fails | | ||
| | **Because** | Offline, an expired credential, or a ref lock from the person's own `git pull` is not the run's fault. The last-fetched copy is never older than what today's code uses, so the fallback is never worse than today | | ||
| | **Locks in** | Offline, a run can still start behind upstream, signalled only by a server log line: the quiet staleness, narrowed to a failed fetch | | ||
|
|
||
|  | ||
|
|
||
| It comes down to offline work: a refusal stops every coding run for a failure that isn't the run's. | ||
|
|
||
| **The call most likely to flip.** What would change my mind: stale PRs from offline runs in | ||
| practice, or runs gaining a place to show a provision warning. Then say so on the run, or refuse. | ||
|
|
||
| <a name="d3"></a> | ||
| ## D3 · Listing a checkout in `localRepositories` admits fetching its own upstream; `remotes.allow` is not asked | ||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. D3 is the real complexity budget for this issue (listing admits upstream while
Collaborator
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. from: fsd-claude Agreed, this is the product call. It's at the top of the PR description, waiting on the owner. Generated by Claude Code |
||
|
|
||
| | | | | ||
| |---|---| | ||
| | **Instead of** | Fetching only when `remotes.allow` admits the upstream's URL, as the brief said | | ||
| | **Because** | Both local entry points run with `remotes: { allow: [] }`: the Lab's `fsd` profile (`teams/devteam/fsd.fsdev.config.mts`) and harness-manager's `hostForConfig`. Under the allowlist rule the case this issue is about never fetches, and adding `github.com` to the Lab is what [FIX-1904 D3](../FIX-1904/DECISIONS.md#d3) rejected: it would clone projects people add. The URL is the operator's repository config, still judged for shape before git sees it | | ||
|
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
When an earlier coding run edits the checkout's shared remote configuration, this decision lets it redirect the next run's fetch to any shape-valid HTTPS, SSH, or file destination even though Useful? React with 👍 / 👎. |
||
| | **Locks in** | The Lab contacts its checkout's upstream (GitHub, here) on each new run, and "the Lab reaches no git remote" leaves the docs. No network means a checkout with no upstream | | ||
|
|
||
|  | ||
|
|
||
| It comes down to the Lab: under the allowlist rule, the headline case stays exactly as stale as today. | ||
|
|
||
| **What would change my mind:** an operator who needs a host with no network calls at all. | ||
|
|
||
| ## Decided, not asked | ||
|
|
||
| - **"Upstream" is git's own `<base>@{upstream}`**, for a branch or `HEAD` on one. No upstream | ||
| (a tag, a commit, a detached `HEAD`, `origin/main` named directly) means today's cut, no fetch. | ||
| - **The recorded `baseRef` stays what was asked** (`main`, or `HEAD`); `baseCommit` is now set | ||
| for a local checkout, as the commit cut at. | ||
| - **`readRunCommits` also excludes the base's upstream.** On `main` it excludes `origin/<base>` | ||
| and the local branch, so a run cut from `origin/main` reports only its commits; an upstream | ||
| on another remote name would be counted as the run's. | ||
| - **Review with `git log -p <branch> --not main origin/main`**, not `git diff | ||
| origin/main...<branch>`: a three-dot diff against either copy is wrong in one of the two cases. | ||
|
|
||
| ## Considered and dropped | ||
|
|
||
| | Alternative | Why not | | ||
| |---|---| | ||
| | Warn when behind, cut from local | A server-log warning is what *quietly stale* means in practice | | ||
| | A per-checkout setting | Nobody asked; starting from local when ahead already keeps unpushed commits | | ||
| | Fast-forward the person's `main` | Moves their branch, maybe under a dirty tree | | ||
| | `git fetch --all` | Slower, and moves tracking refs nobody asked for | | ||
|
|
||
| ## Settled | ||
|
|
||
| - **`<base>@{upstream}` resolves for `main` and `HEAD` on `main`, fails for a detached `HEAD`; | ||
| `git fetch origin refs/heads/main` moves only `origin/main`.** **CONFIRMED** by hand, git 2.43: | ||
| bare upstream, `file://` clone, a push from a second clone, a fetch; local `main` stayed put. | ||
|
|
||
| ## How it got here | ||
|
|
||
| - **Draft** — a stale base on a local checkout; fetch the upstream, start from the newer, | ||
| refuse on a split, no setting; a `workspace` host change, one PR. | ||
| - **Code check** — the brief admitted the fetch by `remotes.allow`, but both local entry points | ||
| allow none, so D3 admits it by the listing. The brief said test repositories have no remote; | ||
| `local-host-local.spec.ts` clones from a bare path, so they do, and stay unchanged because local equals upstream. | ||
|
|
||
| **Open: none.** | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,122 @@ | ||
| # FIX-1927 · Documentation draft | ||
|
|
||
| [Spec](SPEC.md) · [Decisions](DECISIONS.md) · [Rules](BUSINESS-RULES.md) · [Plan](PLAN.md) · **Docs** · [Evolution](EVOLUTION.md) | ||
|
|
||
| Four reader-facing surfaces describe a local checkout as never fetched, and two give a review | ||
| command that misleads once a run can start from upstream. No new page. Voice rules most at risk | ||
| here: no em-dashes as connectors, no sentence opening on "This", and introduce *upstream* in | ||
| plain words on first use. | ||
|
|
||
| ## UPDATE · `apps/docs/docs/shift-manager/overview.md` · "Working on Shift Manager itself", the second and third paragraphs | ||
|
|
||
| Replace the paragraph that starts "Ask the chief of staff…" and the one after it with: | ||
|
|
||
| > Ask the [chief of staff](../workforce/chief-of-staff.md) for work on either project, and say | ||
| > which one, for example "on Shift Manager, make the empty Inbox say who to ask". A coding agent | ||
| > picks it up in a fresh worktree of your checkout, on a branch of its own. Before cutting that | ||
| > branch, the Lab fetches the latest `main` from GitHub and starts from whichever is newer, that | ||
| > or your local `main`. So you don't need to pull first, and commits you haven't pushed are kept. | ||
| > Your own `main`, its files and your index aren't touched. | ||
| > | ||
| > If your `main` and `origin/main` each have commits the other lacks, the run is refused before | ||
| > anything is made, and the refusal names both commits. Pull or rebase, or push, then ask again. | ||
| > If the fetch fails, because you're offline for instance, the run starts from the `origin/main` | ||
| > you last fetched, and a warning prints where you started Shift Manager. | ||
| > | ||
| > Review the work in that worktree, or from your checkout with | ||
| > `git log -p <branch> --not main origin/main`. That shows only the run's commits, whichever of | ||
| > the two it started from. The branch stays checked out in its worktree, so git won't check it | ||
| > out a second time in yours. | ||
| > | ||
| > Only those two projects get a worktree of your checkout. Apart from that fetch, the Lab reaches | ||
| > no git remote, so a coding run on a project you add yourself, even one on this repository, is | ||
| > refused, naming the repository, and nothing is cloned. | ||
|
|
||
| ## UPDATE · `packages/shift-manager/README.md` · "Working on Shift Manager itself", the same two paragraphs | ||
|
|
||
| The same four paragraphs as above, with the chief of staff unlinked, as the README has it today. | ||
|
|
||
| ## UPDATE · `apps/docs/docs/workforce/projects.md` · the local-checkout section, the paragraph that starts "Each run's place has the worktree" | ||
|
|
||
| > Each run's place has the worktree in `checkout/` and the | ||
| > [project's files](#the-projects-own-files) in `project/` beside it, as for any other | ||
| > repository. The branch is cut from `baseRef`, or from whatever your checkout has checked out | ||
| > when `baseRef` is left out. | ||
| > | ||
| > Before the server cuts a new branch, it fetches that base's upstream, the remote branch it | ||
| > tracks, such as `origin/main`. Then it starts from whichever is newer: upstream when you | ||
| > haven't pulled, your own branch when it has commits you haven't pushed. Only the | ||
| > remote-tracking copy is updated. The server never switches, resets or cleans your working | ||
| > tree, and never moves your branch. | ||
| > | ||
| > A few cases go differently: | ||
| > | ||
| > - **Your branch and its upstream have each moved.** The run is refused with `base-diverged`, | ||
| > naming both commits, and nothing is made. Pull or rebase, or push, and the next run starts. | ||
| > - **The fetch fails**, because you're offline, a credential is refused, or it times out. The run | ||
| > starts from the copy you last fetched, and the server logs a warning naming the checkout and | ||
| > git's error. | ||
| > - **The base has no upstream**, such as a tag, a commit, or a branch that tracks nothing. It is | ||
| > used as it is, with no fetch. | ||
| > - **The run already has its branch**, on a retry or a later turn. It's handed back as it was, | ||
| > and nothing is fetched. | ||
| > | ||
| > Listing the checkout is what allows the fetch, so the upstream doesn't need to be in | ||
| > `remotes.allow`. That list still decides which remotes the host clones. The upstream's URL is | ||
| > checked before git sees it: one that uses a transport helper such as `ext::`, starts with `-`, | ||
| > or uses a scheme other than `https`, `ssh` or `file` isn't fetched, and the server logs why. | ||
|
|
||
| ## UPDATE · `apps/docs/docs/workforce/projects.md` · the paragraph that starts "To review a run" | ||
|
|
||
| Replace its first sentence with: | ||
|
|
||
| > To review a run, open its worktree, or run `git log -p <branch> --not main origin/main` from | ||
| > your checkout. That shows only the run's commits, whether it started from your `main` or from | ||
| > `origin/main`. `git diff main...<branch>` would also show upstream commits your `main` doesn't | ||
|
Comment on lines
+73
to
+75
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
In this generic workforce-projects documentation, a checkout may use an arbitrary Useful? React with 👍 / 👎. |
||
| > have yet. | ||
|
|
||
| The rest of the paragraph stays. | ||
|
|
||
| ## UPDATE · `packages/workspace/README.md` · "A repository on this machine", the paragraph that starts "The run's branch is cut from" | ||
|
|
||
| > The run's branch is cut from `baseRef` (or `HEAD`) and stays in that repository. For a new | ||
| > branch whose base tracks an upstream, the host first fetches that one upstream branch, which | ||
| > updates only its remote-tracking ref, then cuts from whichever of the two is newer. Listing | ||
| > the repository allows the fetch; `remotes.allow` isn't asked. The URL is still checked as any | ||
| > remote is, with an absolute path read as `file://`. When local and upstream have each moved, | ||
| > the provision is refused as `base-diverged` before anything is made. A failed fetch isn't a | ||
| > refusal: the host compares with the last-fetched copy and logs a warning. A base with no | ||
| > upstream fetches nothing, and neither does a branch that already exists. `place.repo.baseCommit` | ||
| > is the commit the branch was cut at. The repository's own branches, index and working tree | ||
| > are never touched. When the source names no kept files, the place directory is the checkout | ||
| > itself, with no `checkout/` level. When it names kept files, the place is laid out like a | ||
| > remote run's: the worktree in `checkout/` and the kept files in `project/` beside it. Any bare | ||
| > path not on the list is still refused as `invalid-remote`, before git runs. | ||
|
|
||
| ## UPDATE · `packages/workspace/README.md` · "Which remotes a host reaches", the refusal table and the line under it | ||
|
|
||
| Add a row after `remote-unreadable`: | ||
|
|
||
| > | `base-diverged` | A repository on this machine: the base and its upstream each have commits the other lacks. Nothing is made | | ||
|
|
||
| Replace the table's last sentence, "None of these clears on a retry, so fail the run with the | ||
| reason.", with: | ||
|
|
||
| > None of these clears on a retry by itself, so fail the run with the reason. `base-diverged` | ||
| > clears once someone pulls or rebases, or pushes, in that repository. | ||
|
|
||
| ## CREATE · `.changeset/local-checkout-starts-from-upstream.md` | ||
|
|
||
| ```md | ||
| --- | ||
| "@flow-state-dev/workspace": minor | ||
| "@flow-state-dev/harness-manager": patch | ||
| --- | ||
|
|
||
| A repository listed in `localRepositories` now fetches the base's upstream before it cuts a new run's branch, and cuts from whichever of local and upstream is newer. A base whose local and upstream copies have each moved is refused as `base-diverged`; a failed fetch falls back to the last-fetched copy with a warning. `place.repo.baseCommit` is now set for these repositories, and `readRunCommits` also leaves out the base's upstream (FIX-1927). | ||
| ``` | ||
|
|
||
| ## Publication ownership | ||
|
|
||
| This issue publishes all of it. The `fsd` profile's own config needs no change, and no doc | ||
| about the default projects moves (that is FIX-1904's). | ||
Uh oh!
There was an error while loading. Please reload this page.