From 43860076a7ea98e162076b1dfc8dd8856950074b Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Wed, 7 Oct 2026 09:32:40 +0000 Subject: [PATCH 1/3] Offer optional worktree isolation when planning overlaps another task. Detect other in-flight work at plan start and record continue, wait, or isolate for a cold-start implement. Keep the procedure in one shared reference so review, correction, and reconcile follow that checkout. Co-authored-by: Dennis Geldmacher --- CHANGELOG.md | 2 + docs/auto-work.md | 2 +- docs/behavior-validation.md | 21 +++- docs/manual-workflow.md | 12 +++ docs/methodology-sources.md | 4 + references/concurrent-work.md | 97 +++++++++++++++++++ references/implementation-work.md | 2 +- scripts/context-limits.json | 57 ++++++++++- scripts/measure-context.mjs | 9 ++ skills/auto-work/references/operation.md | 2 +- skills/auto-work/references/reviewer.md | 2 +- skills/correct-work/SKILL.md | 2 +- .../engineering-work/references/hillclimb.md | 2 +- .../references/pause-safely.md | 2 +- .../references/session-pickup.md | 2 +- skills/implement-work/SKILL.md | 2 +- skills/learn-from-work/SKILL.md | 2 +- skills/plan-work/SKILL.md | 2 + skills/review-work/SKILL.md | 2 +- skills/verification-work/SKILL.md | 2 +- skills/work-status/SKILL.md | 2 +- tests/concurrent-work.test.mjs | 32 ++++++ tests/context.test.mjs | 13 +++ 23 files changed, 256 insertions(+), 19 deletions(-) create mode 100644 references/concurrent-work.md create mode 100644 tests/concurrent-work.test.mjs diff --git a/CHANGELOG.md b/CHANGELOG.md index fc4bfbf..f253a3b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,8 @@ ## Unreleased +- Warn at plan start when another plan or implementation is already active on the same repository, and offer continue, wait, or an optional git worktree. Review, correction, learning, and verification follow that checkout; merge and worktree removal stay explicitly requested. + ## 7.8.0 - Learn from the session or its log about navigation, wasteful tool use, and steering instructions that do not change behavior. Mechanical lessons become checks; judgment lessons become standards the reviewer applies, so implementation context stays lean. Review keeps plan or spec deviation separate from repository standards or simplicity. diff --git a/docs/auto-work.md b/docs/auto-work.md index e521d96..13f5e23 100644 --- a/docs/auto-work.md +++ b/docs/auto-work.md @@ -27,7 +27,7 @@ For Dark, say “Use auto-work dark” and give the same concrete goal, scope, a ## What happens next -1. **Plan:** the agent inspects the project and defines the change and its checks. In Light, you approve it before implementation. Existing approval for the same plan and scope remains valid. +1. **Plan:** the agent inspects the project and defines the change and its checks. In Light, you approve it before implementation. Existing approval for the same plan and scope remains valid. If another task is already changing this repository, or your checkout has unrelated edits, planning uses the same warn-and-choose check as [manual planning](manual-workflow.md#when-another-task-already-uses-this-repository): continue carefully, wait, or isolate on a branch and worktree. The plan records the choice. Review reads that checkout and does not merge it. 2. **Implement:** the agent makes the agreed changes and reports the checks and result. 3. **Review:** a fresh separate agent checks the work against the plan without changing it. The implementation stays unchanged while it is being reviewed. 4. **Correct if needed:** the executor addresses findings, then a fresh reviewer checks the result again. A correction can also collect missing proof without changing code. diff --git a/docs/behavior-validation.md b/docs/behavior-validation.md index a342e1f..26e574f 100644 --- a/docs/behavior-validation.md +++ b/docs/behavior-validation.md @@ -103,9 +103,28 @@ For each example ask: What is the result? What does it mean for the goal? What f | Necessary work and checks are sufficient; no concrete question remains. | Deliver the phase report without another search or test loop. Reuse applicable instructions; load optional references only for the relevant case. | [Working agreement](../references/workflow.md) | | A current Review establishes that the goal is achieved. | State completion without adding a required learning, release, or other phase. Status repeats only a relevant next action and does not reopen finished work. | [Review](../skills/review-work/SKILL.md), [status](../skills/work-status/SKILL.md), settings example | +## Concurrent checkouts + +Walk through these cases against [planning](../skills/plan-work/SKILL.md), [concurrent work](../references/concurrent-work.md), [implementation requirements](../references/implementation-work.md), [review](../skills/review-work/SKILL.md), and [correction](../skills/correct-work/SKILL.md). Record the passages inspected and the working state outside the repository. This is an instruction-level check, not an observed agent run. + +| Situation | Expected decision | Instructions to inspect | +|---|---|---| +| The checkout is clean and no other plan, implementation, worktree, or documented unfinished task names this repository. | Plan in place. Ask no checkout question and create no worktree. | [Planning](../skills/plan-work/SKILL.md) | +| Another git worktree is implementing on this repository, or this checkout is dirty with edits this task must leave untouched. | Warn, and offer continue carefully, wait, or isolate, with one recommendation. Recommend isolate. Planning records the choice and does not create the worktree. Continuing in place stays available. | [Planning](../skills/plan-work/SKILL.md), [concurrent work](../references/concurrent-work.md) | +| The human chooses to continue in the dirty checkout. | Record continue. Later edits preserve the unrelated files. Do not treat the warning as a lock. | [Concurrent work](../references/concurrent-work.md), [correction](../skills/correct-work/SKILL.md) | +| The other workstream is mid-edit on the same files this task must change. | Recommend wait. The plan may finish. Hold product edits until that blocker clears. | [Concurrent work](../references/concurrent-work.md) | +| Dark Auto-Work has a clear overlap and the commissioned goal did not pick a checkout. | Record the recommendation and follow it. Pause before edits when the other owner or the overlapping files are unclear. | [Concurrent work](../references/concurrent-work.md), [Auto-Work operation](../skills/auto-work/references/operation.md) | +| Implementation is cold-started from a plan that already says isolate, with a base, branch, and path. | Create the worktree when it is missing, then edit only there. Do not repeat the choice interview. Commit, push, and merge stay unauthorized. | [Implementation requirements](../references/implementation-work.md), [concurrent work](../references/concurrent-work.md) | +| Review is opened from the primary checkout while the change exists only in the recorded worktree. | Review that worktree and branch, read-only. A primary checkout without the change is the wrong tree. Missing access is missing proof. | [Review](../skills/review-work/SKILL.md), [concurrent work](../references/concurrent-work.md) | +| Correction findings apply to isolated work, and the primary checkout has unrelated edits. | Patch the recorded worktree. Leave the primary checkout untouched. Folding the branch back is a later explicit reconcile, not part of correction. | [Correction](../skills/correct-work/SKILL.md), [concurrent work](../references/concurrent-work.md) | +| The human asks to merge the isolated branch and remove its worktree. The destination checkout is clean. | Merge into the named destination, recheck there, then remove only the worktree this assignment added. Delete the branch only if they also asked and it is merged. | [Concurrent work](../references/concurrent-work.md) | +| The human asks to merge, and the destination checkout is dirty with unrelated edits. | Stop and show that dirt. Do not stash, commit, or merge over it. | [Concurrent work](../references/concurrent-work.md) | +| The human discards the isolated attempt. The worktree still has uncommitted files. | Do not merge. Show that work. Remove the worktree only after they confirm the discard. Leave worktrees this assignment did not create. | [Concurrent work](../references/concurrent-work.md) | +| Learning or a verifier run happens while the accepted product change still lives only in the worktree. | Edit project guidance and drive the product there. A git worktree does not replace test-data or process isolation. A repeated collision prefers a check or this procedure over a copied project rule. | [Learning](../skills/learn-from-work/SKILL.md), [verification](../skills/verification-work/SKILL.md), [concurrent work](../references/concurrent-work.md) | + ## Context budgets -`npm run context-budget` estimates instruction size from the built host packages. Its flat scenarios cover required planning references, individual phases, selected playbooks, learning, verifier inspection/creation/maintenance, and Auto-Work including delivery. Shared documents count once per scenario. Discovery counts the advertised names and descriptions, including Cursor command aliases. These are aggregate scenario budgets, not individual skill length limits. +`npm run context-budget` estimates instruction size from the built host packages. Its flat scenarios cover required planning references, individual phases, selected playbooks, learning, verifier inspection/creation/maintenance, and Auto-Work including delivery. Overlap and isolated-checkout upper bounds (`planConcurrent`, `reviewConcurrent`, `correctionConcurrent`, `autoWorkConcurrent`, `learningConcurrent`, `verificationConcurrent`, and portable `implementationConcurrent`) add the concurrent-work reference only for that case. Default phase scenarios omit it. Shared documents count once per scenario. Discovery counts the advertised names and descriptions, including Cursor command aliases. These are aggregate scenario budgets, not individual skill length limits. Every scenario has a fixed hard limit; excess size, missing limits, and obsolete limits fail validation. Initial limits used the largest host value plus 10%, rounded up to 100 estimated tokens. Original baselines and explicit revisions remain recorded in the repository's `scripts/context-limits.json`. Normal checks never update limits. diff --git a/docs/manual-workflow.md b/docs/manual-workflow.md index 18d953d..b564feb 100644 --- a/docs/manual-workflow.md +++ b/docs/manual-workflow.md @@ -52,6 +52,14 @@ The implementation follows the approved scope and preserves unrelated changes. I A successful implementation report is the input to review. It does not mean review has already happened. +### When another task already uses this repository + +At the start of planning, the agent checks this repository for another active plan or implementation. That includes another git worktree, this branch checked out twice, a documented unfinished task, or unrelated edits that implementation would otherwise change. A clean checkout with no other active work continues as usual. Planning does not create a worktree, and a plan does not have to use one. + +When there is overlap, you get a warning and three choices: continue carefully in this checkout, wait, or isolate the work on its own branch and git worktree. Isolation is the usual recommendation when someone else is already changing this repository, or when your checkout has unrelated edits that should stay untouched. You can still continue in place. Waiting holds edits until the other work releases the files it is changing. + +The plan records the choice. Implementation follows that record, and creates the worktree only after the plan allows isolate. Review and correction use that same checkout. Merging the branch back, or removing the worktree after you discard the attempt, happens only when you ask. + ## Review and correction ### 3. Request a review @@ -129,6 +137,10 @@ After correction, request a fresh review. A positive review might conclude: > The goal is achieved. Exported rows match the active filter, columns match the visible selection, and empty exports retain their headers. The required checks support the current change. +### Plan while another task is in progress + +> Another worktree already has an orders export in progress, and this checkout has unrelated edits. I recommend isolating this plan on its own branch and worktree. You can continue carefully here, or wait until that export lands. Say which you want. A worktree is only for this overlap, not for every plan. + ### Review a resumed settings change > Earlier save-test results still apply to the unchanged code and test conditions. The required keyboard check is missing, so completion is unconfirmed. Request that check; no code change is needed unless it reveals a defect. diff --git a/docs/methodology-sources.md b/docs/methodology-sources.md index f8a6378..ac8ebcb 100644 --- a/docs/methodology-sources.md +++ b/docs/methodology-sources.md @@ -49,6 +49,10 @@ Session-environment lessons and the split between plan or spec deviation and rep Automated checks were already on the ladder. This adaptation does not add a `/retro` command, a required `CODING_STANDARDS.md`, parallel review subagents, or the Fowler smell baseline. It does not adopt `/implement-spec`, which conflicts with Auto-Work, the written plan handoff, and host-configured models. Grill-me, grill-with-docs, and a required glossary stay out, as [Vague-scope planning](#vague-scope-planning) already records. Packaged instructions remain original Workflow wording. This note attributes the ideas; it does not load the upstream skills. +## Concurrent checkouts + +Optional git worktrees for overlapping tasks are original instructions in `references/concurrent-work.md`. They are not a playbook and not a separate skill. Planning stays read-only. The native plan is the cold-start record Implement follows, including the continue, wait, or isolate choice. The removed controller worktrees, sandboxes, and sealed plan artifacts stay removed. Visual parity still has no mandatory worktree. A repeated checkout collision stays an environment lesson under the existing correction ladder: prefer a check, or this shared procedure, over a new project rule that copies the steps. + ## Shared integration decisions Each method remains one reference file. Catalog and skill entrypoints load only the selected method. The playbooks describe useful result content, not mandatory user-document headings, metadata, or machine state. diff --git a/references/concurrent-work.md b/references/concurrent-work.md new file mode 100644 index 0000000..be8ab06 --- /dev/null +++ b/references/concurrent-work.md @@ -0,0 +1,97 @@ +# Concurrent work + +Read this when planning finds another active workstream on this repository, when a dirty checkout should stay untouched, or when a plan already records continue, wait, or isolate. A clean checkout with no other active plan or implementation stays where it is: no worktree, and no extra question. + +Continuing in the current checkout remains a valid choice. This check warns and offers options. It does not lock the repository or require a worktree for every plan. + +The plan in the native task is the cold-start record. Implementation, review, correction, learning, and verification follow that record. There is no side registry. + +## Detect overlap + +1. Identify the repository by its git common directory (`git rev-parse --git-common-dir`) and list checkouts with `git worktree list --porcelain`. Linked worktrees of that common directory are the same repository. +2. Stay read-only while detecting. Use status and listing only. +3. Inspect other worktrees and the branches they have checked out, this checkout's branch and uncommitted changes, unfinished plans or implementation reports already in this task or supplied with it that name this repository, and host-visible sessions for this repository when the host already exposes them. Do not search unrelated private conversations. +4. Overlap is another worktree of this repository, this branch checked out in more than one worktree, a documented unfinished plan or implementation for this repository, or uncommitted changes this assignment did not make when the next edit would land in that checkout. +5. Local branches with no worktree, no unfinished handoff, and no host-visible task are not overlap. This assignment's own recorded worktree is not a new overlap. + +## Choose + +When overlap exists, warn and offer three options. Mark one as the recommendation the human can accept or steer. This is one checkout choice, separate from a vague-scope product round. Ask it only when detection finds overlap. + +- **Continue carefully.** Edit this checkout. Preserve unrelated changes. A later merge may be messier, and that is acceptable when the human wants one checkout. +- **Wait.** The plan can still be finished. Hold edits until the other workstream releases the checkout or the overlapping files. Name who is in the way and what to recheck. Do not poll without a new request. +- **Isolate.** Use a dedicated branch and a git worktree so this workstream does not edit the other checkout. + +Recommend **isolate** when another workstream is active on this repository, or when implementation would otherwise change a dirty checkout this task must leave untouched. Recommend **wait** when that other workstream is mid-edit on the same files and branching from that state would drop their unfinished work. Recommend **continue carefully** when the human wants one checkout, or when a worktree cannot be created. + +Standalone and Light planning record the choice and do not create the worktree. Light approval of the plan accepts the recorded choice. Dark Auto-Work records the recommendation and may follow it when the commissioned goal did not pick otherwise. Pause before edits when the other owner or the overlapping files are unclear. An explicit continue, wait, or isolate from the human overrides the recommendation. + +Silence while planning is still read-only is not approval to create a worktree. Record the decision in the plan: + +- repository common directory +- choice: continue, wait, or isolate +- for continue: which unrelated changes must be preserved +- for wait: what blocks edits +- for isolate: base revision, branch, worktree path, and whether the worktree has been created +- that review, correction, learning, verification, and reconcile follow this reference + +A later executor that has only the plan uses these fields and does not repeat the choice. + +## Isolate + +Create the branch and worktree at the start of implementation, after the plan records isolate. That recorded choice authorizes this bounded git setup only. It does not authorize commit, push, merge, or deletion. + +1. Choose a base that excludes unrelated dirty work. A clean HEAD can be the base. When the checkout is dirty, use the committed HEAD or the branch the plan names, and leave that dirty checkout untouched. +2. Create a branch named for this assignment. Leave a branch that is checked out elsewhere, or that holds commits the plan did not accept, as it is. +3. Add the worktree outside the current working tree: `git worktree add -b `. Keep the path on the same machine, outside the source tree, and off a symlink that leaves the intended parent. A sibling directory or the host's existing worktree directory both fit. +4. Record the path, branch, and base in the plan. Leave the original checkout on its current branch. +5. When `git worktree add` fails, report the command and the error. Ask the human whether to continue carefully or wait. Do not treat a failed add as an existing worktree. +6. When the host cannot place a worktree outside the checkout, say so and use continue carefully or wait. + +Isolation keeps the other checkout intact. Later merge conflicts remain possible and are handled at reconcile. + +## Implement + +Edit only the checkout the plan names. When the choice is isolate and the worktree is missing, create it before the first product edit. When the shell is in a different checkout, move to the recorded path before editing. When the choice is continue, preserve the unrelated changes named in the plan. When the choice is wait, do not edit until the recorded blocker has cleared, then re-read the checkout and continue in the recorded place. + +A cold start follows the plan's fields. It does not open a new choice unless those fields are missing and this checkout now has other in-flight work. + +## Review + +Review the branch and worktree the plan records. A primary checkout that does not contain the change is the wrong tree. Stay read-only: leave merge, commit, worktree removal, and copying files back for an explicitly requested reconcile. When the recorded path is unavailable, report that missing checkout as missing proof. + +Auto-Work gives the reviewer the path, branch, and this reference. The executor still makes no concurrent writes to that worktree while review runs. + +## Correct + +Apply findings in the same worktree and branch. Leave every other checkout untouched. Unrelated edits in the chosen checkout stay in place. Copying the result onto the original branch is reconcile, which needs its own explicit git request. + +## Reconcile or abandon + +Merge, rebase, worktree removal, and branch deletion need an explicit request. Commissioned delivery covers only the destinations it names. + +**Reconcile** when the human asks to fold the isolated work back, or delivery includes that merge: + +1. Name the destination branch and checkout. Update it from elsewhere only when that fetch or pull is authorized. +2. When the destination checkout is dirty, stop and show that dirt. Continue only in a checkout that can take the merge, or under a new explicit instruction. Do not stash or commit that dirt as part of reconcile. +3. Merge or rebase the assignment branch into the named destination. Keep changes that are not part of this assignment. Resolve conflicts inside this assignment's edits. Stop for a human decision when a conflict changes the goal, acceptance, or someone else's unfinished work. +4. Recheck the affected behavior on the merged result. A passing result in the worktree is not yet proof of the merged tree. +5. After the requested merge succeeds, remove only the worktree this assignment added (`git worktree remove `). Delete the branch only when the human asks and the branch is merged. Leave every other worktree in place. + +**Abandon** when the human discards the isolated attempt: + +1. Do not merge. +2. Show uncommitted and unpushed work in that worktree. Remove it only after the human confirms the discard. Use `git worktree remove --force` only with that confirmation, and only when a normal remove refuses dirty or untracked files. +3. Delete the branch only when the human confirms and the branch exists for this abandoned attempt. Leave branches and worktrees this assignment did not create. + +## Learning and verification + +Save project guidance on the checkout that holds the accepted work. While that result exists only in the worktree, edit there. After reconcile, edit the destination that received the merge. Leave the other checkout unchanged. + +Drive verifiers and product checks against the checkout that contains the implementation. A git worktree does not replace test-data, port, or process isolation. When safe isolation for a shared running instance is unavailable, report that constraint. + +A repeated collision between workstreams is an environment lesson. Follow the learning guidance: prefer a check that can see the collision, or this shared procedure, over a new project rule that copies these steps. + +## Resume + +A pause record includes the choice, path, branch, base, and whether the worktree exists. On pickup, confirm the path still exists and matches the branch before editing, reviewing, or reconciling. A missing worktree is a gap. Recreate it only when the plan still says isolate and implementation is authorized, using the recorded base. Do not invent a new base that drops uncommitted work you can no longer see. diff --git a/references/implementation-work.md b/references/implementation-work.md index 5715937..52df25c 100644 --- a/references/implementation-work.md +++ b/references/implementation-work.md @@ -2,7 +2,7 @@ Apply the [working agreement](workflow.md); read it if missing or uncertain. Resolve the applicable plan and implementation assignment, including material amendments. Inspect the current repository before editing; clarify consequential gaps or contradictions. In expressly commissioned Dark Auto-Work, its in-scope plan is authorized by the human goal assignment; standalone implementation still requires an approved plan. -Implement planned outcomes and pending north-star updates from explicit user decisions, preserving unrelated edits. Choose tools, steps and proportionate checks using project guidance. Fix bounded implementation problems within this phase. New goals, permissions, dependencies outside scope or material tradeoffs need a human decision. Follow [project readiness](project-readiness.md) for direction, prerequisite or feedback gaps; repair commissioned setup and offer additions outside its scope. +Before the first edit, follow the plan's continue, wait, or isolate choice in [concurrent work](concurrent-work.md). When no choice is recorded, still read it if this checkout already holds other in-flight work. Implement planned outcomes and pending north-star updates from explicit user decisions, preserving unrelated edits. Choose tools, steps and proportionate checks using project guidance. Fix bounded implementation problems within this phase. New goals, permissions, dependencies outside scope or material tradeoffs need a human decision. Follow [project readiness](project-readiness.md) for direction, prerequisite or feedback gaps; repair commissioned setup and offer additions outside its scope. For explicitly accepted verifier creation or maintenance in the plan, follow its assignment through [verification-work](../skills/verification-work/SKILL.md). Complete the first required end-to-end trial at implementation close when product and verifier are ready together. Preserve evidence through cleanup and report failed or missing necessary proof. An unaccepted suggestion does not authorize verifier edits. diff --git a/scripts/context-limits.json b/scripts/context-limits.json index e7effdb..6b63738 100644 --- a/scripts/context-limits.json +++ b/scripts/context-limits.json @@ -59,7 +59,7 @@ "discovery": 600, "plan": 2900, "review": 1800, - "correction": 1200, + "correction": 1400, "learning": 2200, "explanation": 900, "status": 1100, @@ -109,11 +109,11 @@ "setupInspection": 2400, "setupImplementation": 3000, "maintenanceInspection": 2500, - "maintenanceUpdate": 3000, + "maintenanceUpdate": 3400, "planSetupGap": 3900, "doctorSetupGap": 3900, "reviewSetup": 3100, - "correctionSetup": 2600, + "correctionSetup": 2900, "autoWorkSetup": 8600, "setupVerifierCreation": 6100, "maintenanceVerifierUpdate": 6100, @@ -122,7 +122,7 @@ "autoWorkMaintenanceVerifierUpdate": 11700, "setupMethodAssessment": 3400, "maintenanceMethodAssessment": 3400, - "planSetupProposal": 4500, + "planSetupProposal": 5100, "doctorSetupProposal": 4900, "setupMethod:behavior-tests": 4400, "maintenanceMethod:behavior-tests": 4500, @@ -153,7 +153,14 @@ "autoWorkSetupPackageVerifier": 15300, "autoWorkMaintenancePackageVerifier": 15300, "setupAllSelectedMethods": 12100, - "maintenanceAllSelectedMethods": 12100 + "maintenanceAllSelectedMethods": 12100, + "planConcurrent": 5200, + "reviewConcurrent": 4500, + "correctionConcurrent": 4000, + "autoWorkConcurrent": 10000, + "learningConcurrent": 4900, + "verificationConcurrent": 5300, + "implementationConcurrent": 4100 }, "additions": { "projectSetup": { @@ -213,6 +220,18 @@ "setupAllSelectedMethods": 10943, "maintenanceAllSelectedMethods": 10951 } + }, + "concurrentWork": { + "method": "Initial largest host scenario plus 10%, rounded up to 100 estimated tokens. Frozen after introduction; existing limits unchanged.", + "maxima": { + "planConcurrent": 4644, + "reviewConcurrent": 4035, + "correctionConcurrent": 3559, + "autoWorkConcurrent": 9027, + "learningConcurrent": 4427, + "verificationConcurrent": 4763, + "implementationConcurrent": 3637 + } } }, "revisions": [ @@ -386,6 +405,34 @@ "limit": 3900 } } + }, + { + "date": "2026-10-07", + "reason": "Hold a short concurrency pointer in plan, correction, and shared implementation instructions. The concurrent-work reference itself stays in separate upper-bound scenarios. Document lists for these four scenarios are unchanged.", + "selection": "Only correction, correctionSetup, maintenanceUpdate, and planSetupProposal exceeded their limits after those pointers. The other existing limits remain unchanged. This criterion does not trigger future automatic changes or approvals.", + "method": "Largest current host measurement plus 10%, rounded up to 100 estimated tokens. Existing baselines are retained; normal checks never update limits.", + "scenarios": { + "correction": { + "maximum": 1218, + "previousLimit": 1200, + "limit": 1400 + }, + "correctionSetup": { + "maximum": 2605, + "previousLimit": 2600, + "limit": 2900 + }, + "maintenanceUpdate": { + "maximum": 3022, + "previousLimit": 3000, + "limit": 3400 + }, + "planSetupProposal": { + "maximum": 4574, + "previousLimit": 4500, + "limit": 5100 + } + } } ] } diff --git a/scripts/measure-context.mjs b/scripts/measure-context.mjs index 62bef2c..ead851b 100644 --- a/scripts/measure-context.mjs +++ b/scripts/measure-context.mjs @@ -90,6 +90,15 @@ function scenarios(root, host) { for (const name of readdirSync(join(root, "skills/engineering-work/references")).filter(name => name.endsWith(".md") && name !== "catalog.md").sort()) { cases[`planMethod:${name.slice(0, -3)}`] = [...plan, catalog, skill("engineering-work"), `skills/engineering-work/references/${name}`]; } + // Upper bounds for an overlap or an already isolated checkout. Default phases omit this reference. + const concurrent = "references/concurrent-work.md"; + cases.planConcurrent = [...plan, concurrent]; + cases.reviewConcurrent = [...cases.review, concurrent]; + cases.correctionConcurrent = [...cases.correction, concurrent]; + cases.autoWorkConcurrent = [...cases.autoWork, concurrent]; + cases.learningConcurrent = [...cases.learning, concurrent]; + cases.verificationConcurrent = [...cases.verificationInspect, concurrent]; + if (host === "agent-plugins") cases.implementationConcurrent = [...cases.implementation, concurrent]; return cases; } diff --git a/skills/auto-work/references/operation.md b/skills/auto-work/references/operation.md index e406522..86edfea 100644 --- a/skills/auto-work/references/operation.md +++ b/skills/auto-work/references/operation.md @@ -6,7 +6,7 @@ Light and Dark share the same phases and evidence requirements. Light places hum Use one identifiable assignment and plan in the native task. Existing applicable approvals remain valid. Before mutation, resolve consequential product, architecture, scope, permission, and acceptance ambiguities. In Dark, a sufficiently specified human goal authorizes preparing its implementation plan without a second approval; it never authorizes inventing consequential missing requirements. Plan-only requests remain read-only in either mode. -After planning, Light waits for approval unless the applicable plan is already approved. Implement, report, obtain independent Review, correct named findings, and re-review. A verification-only correction may collect missing proof without code changes. Each phase remains distinct, but the Auto-Work assignment commissions its in-scope transitions in advance. The reviewer returns its judgment to the executor; it does not repair findings or run delivery. +Before the first edit, use the plan's recorded continue, wait, or isolate choice. When it is missing, apply the concurrency check in [planning](../../plan-work/SKILL.md). After planning, Light waits for approval unless the applicable plan is already approved. Implement, report, obtain independent Review, correct named findings, and re-review. A verification-only correction may collect missing proof without code changes. Each phase remains distinct, but the Auto-Work assignment commissions its in-scope transitions in advance. The reviewer returns its judgment to the executor; it does not repair findings or run delivery. After positive Review, Light presents the result and supporting evidence for human acceptance. Plan approval, silence, a status question, or approval of one earlier revision is not acceptance of a changed result. Once the reviewed result is accepted, finish repository work or execute the already commissioned delivery. Dark can finish repository work after positive Review and necessary checks; delivery has its own requirements. diff --git a/skills/auto-work/references/reviewer.md b/skills/auto-work/references/reviewer.md index 1409c08..2bcbe91 100644 --- a/skills/auto-work/references/reviewer.md +++ b/skills/auto-work/references/reviewer.md @@ -1,6 +1,6 @@ # Independent review in Auto-Work -For each initial or post-correction Review, start a fresh separate native agent. Give it the applicable plan and assignment, active mode, implementation or correction report, exact current workspace or revision, relevant raw evidence, and the learning collection through an accessible reference, or the full collection when the reviewer cannot access that reference. Give access to the packaged [review skill](../../review-work/SKILL.md) and its linked references. A copied implementation conclusion is not independent evidence. Do not give the reviewer the answer it should reach. +For each initial or post-correction Review, start a fresh separate native agent. Give it the applicable plan and assignment, active mode, implementation or correction report, exact current workspace or revision, relevant raw evidence, and the learning collection through an accessible reference, or the full collection when the reviewer cannot access that reference. When the plan records an isolated branch or worktree, give the reviewer that path, branch, and [concurrent work](../../../references/concurrent-work.md). Give access to the packaged [review skill](../../review-work/SKILL.md) and its linked references. A copied implementation conclusion is not independent evidence. Do not give the reviewer the answer it should reach. Use available host read-only restrictions and explicitly require repository-read-only behavior, including untracked files. Inherit the parent's model settings. Do not create global agent configurations, weaken host permissions, or substitute a self-review when delegation is unavailable. A separate context provides separation of judgment, not a guarantee of correctness or a new sandbox; describe actual host restrictions honestly. diff --git a/skills/correct-work/SKILL.md b/skills/correct-work/SKILL.md index 5fdaf72..7b7ec33 100644 --- a/skills/correct-work/SKILL.md +++ b/skills/correct-work/SKILL.md @@ -5,7 +5,7 @@ description: "Fix requested review findings within the approved plan." # correct-work -Apply the [working agreement](../../references/workflow.md); read it if missing or uncertain. A natural-language request to fix review findings suffices; an unrelated bug report does not select this review-correction phase. Read the applicable plan, latest relevant review, and human correction instruction or expressly commissioned Auto-Work assignment with remaining correction budget. Identify the commissioned findings and their expected fixes and rechecks. Compare them with the current repository; resolve stale or conflicting instructions before dependent changes. +Apply the [working agreement](../../references/workflow.md); read it if missing or uncertain. A natural-language request to fix review findings suffices; an unrelated bug report does not select this review-correction phase. Read the applicable plan, latest relevant review, and human correction instruction or expressly commissioned Auto-Work assignment with remaining correction budget. Identify the commissioned findings and their expected fixes and rechecks. Compare them with the current repository; resolve stale or conflicting instructions before dependent changes. When that plan records another branch or worktree, read [concurrent work](../../references/concurrent-work.md) and correct there. Correct named defects and pending north-star updates from explicit user decisions within the assignment. Preserve unrelated changes and resolve routine details yourself. Do not broaden the goal, modify protected work without permission, weaken tests to hide a defect, or include unrelated improvements. diff --git a/skills/engineering-work/references/hillclimb.md b/skills/engineering-work/references/hillclimb.md index cfd7587..81ae627 100644 --- a/skills/engineering-work/references/hillclimb.md +++ b/skills/engineering-work/references/hillclimb.md @@ -13,7 +13,7 @@ Use for sustained improvement of one measurable outcome under an agreed budget a 5. Keep a concise decision trail in the native task: hypothesis, bounded change, before/after result, relevant checks, and keep-or-revert decision. Read prior attempts so the search accumulates evidence. 6. Ground each hypothesis in a specific mechanism. Make one bounded change, measure with the fixed procedure, and run the regression gate. Accept improvement only beyond noise with the guardrails green. A simplification with equivalent performance can be retained only if the approved scope includes that benefit; it is not a metric win. -7. Remove a failed attempt's own changes before proceeding. Do not revert pre-existing work or combine unmeasured changes. Any parallel experiments need authorized collaboration and isolated mutable state, chosen by the executor. +7. Remove a failed attempt's own changes before proceeding. Do not revert pre-existing work or combine unmeasured changes. Any parallel experiments need authorized collaboration and isolated mutable state, chosen by the executor. When that isolation is another checkout of this repository, use [concurrent work](../../../references/concurrent-work.md). 8. On a plateau, inspect rejected ideas and reconsider the cost mechanism. Try another justified strategy while budget and useful hypotheses remain. Do not lower correctness or success criteria to claim progress. 9. Stop when the target is met, the budget is exhausted, a real blocker prevents useful work, or remaining ideas do not justify their marginal cost. Explain which condition ended the run. A budget stop or plateau is not success when the target remains unmet. diff --git a/skills/engineering-work/references/pause-safely.md b/skills/engineering-work/references/pause-safely.md index 39e5b50..719e608 100644 --- a/skills/engineering-work/references/pause-safely.md +++ b/skills/engineering-work/references/pause-safely.md @@ -7,7 +7,7 @@ Use when the human asks to pause or requests a handoff for a restart or interrup 1. Start no new work. Bring the current bounded step to a safe stopping point only within the existing authority, or leave its incomplete state explicit. Do not hide a broken check or undo unrelated edits to create a clean-looking tree. 2. Identify any running operations owned by this task. Use available controls to stop or settle them safely where authorized, preserving results already produced. Do not cancel unrelated tasks or imply background work stopped without observing it. 3. Inspect what is actually saved and what remains only an intention. Preserve modified files, untracked artifacts, and pre-existing changes. A dirty working tree is a valid pause state; committing, resetting, cleaning, or pushing is not required to make it durable. -4. Provide the resume information in the native task: applicable plan and assignment, completed work, actual repository state, checks and limitations, useful artifact locations, unresolved decisions, and the next action. Link existing reports instead of duplicating them where the receiver can access them. +4. Provide the resume information in the native task: applicable plan and assignment, completed work, actual repository state, checks and limitations, useful artifact locations, unresolved decisions, and the next action. When this task uses an isolated worktree, include its path, branch, base, and choice. Link existing reports instead of duplicating them where the receiver can access them. Reconcile and worktree removal follow [concurrent work](../../../references/concurrent-work.md) and wait for an explicit request. 5. If moving to another executor, use the host's available task references or complete supplied text. If a necessary artifact cannot be accessed there, name that gap. Do not invent an external note path or automatically persist learning to compensate. ## Result diff --git a/skills/engineering-work/references/session-pickup.md b/skills/engineering-work/references/session-pickup.md index 31fb50a..6955755 100644 --- a/skills/engineering-work/references/session-pickup.md +++ b/skills/engineering-work/references/session-pickup.md @@ -6,7 +6,7 @@ Use to resume or take over prior work from task references, supplied reports, or 1. Locate the applicable plan, current assignment, relevant implementation and review reports, open decisions, and prior next action. Use accessible task references or complete supplied text. Start with the overview and latest outcome, then read back to the decisions that affect pending work. 2. Keep access scoped to the supplied task and project. Do not glob through unrelated private conversations. Summarize long records with available tools while retaining useful source pointers; do not invent missing content from a title or summary. -3. Inspect the actual branch or worktree, current diff, and relevant history. Distinguish completed changes, uncommitted work, unrelated edits, and pending work. A pushed branch or a prior agent's statement is evidence of state, not proof of human authorization. +3. Inspect the actual branch or worktree, current diff, and relevant history. Distinguish completed changes, uncommitted work, unrelated edits, and pending work. When the handoff names an isolated worktree, confirm that path and branch still match, and read [concurrent work](../../../references/concurrent-work.md) before editing, reviewing, or reconciling it. A pushed branch or a prior agent's statement is evidence of state, not proof of human authorization. 4. Compare inherited observations with the current repository and original goal. Reuse established work that remains applicable. Recheck affected claims when code, environment, evidence, or acceptance changed; avoid repeating everything solely to recreate a trail. 5. Resolve conflicting plans, missing consequential decisions, or unclear authority before dependent execution. Name the exact missing information. Continue independent read-only grounding when useful. 6. Identify the next outcome: resume the authorized execution, provide the already completed answer, reassess a changed conclusion, or explain a failed attempt. Select the relevant method for remaining work only within the current assignment. The receiving executor needs the applicable plan and applicable reports, not just a playbook ID. diff --git a/skills/implement-work/SKILL.md b/skills/implement-work/SKILL.md index 45157db..8bd62af 100644 --- a/skills/implement-work/SKILL.md +++ b/skills/implement-work/SKILL.md @@ -5,4 +5,4 @@ description: "Implement an approved plan within the current assignment." # implement-work -Apply the shared [implementation requirements](../../references/implementation-work.md). In standalone work, resolve the human-approved plan and implementation instruction, then recommend a separately commissioned Review. In an expressly commissioned Auto-Work sequence, return the implementation report to its independent review step. +Apply the shared [implementation requirements](../../references/implementation-work.md). When the plan records another branch or worktree, read [concurrent work](../../references/concurrent-work.md) before editing. In standalone work, resolve the human-approved plan and implementation instruction, then recommend a separately commissioned Review. In an expressly commissioned Auto-Work sequence, return the implementation report to its independent review step. diff --git a/skills/learn-from-work/SKILL.md b/skills/learn-from-work/SKILL.md index f5150e3..b16e6f5 100644 --- a/skills/learn-from-work/SKILL.md +++ b/skills/learn-from-work/SKILL.md @@ -5,4 +5,4 @@ description: "Save review-confirmed lessons when requested." # learn-from-work -Apply the [working agreement](../../references/workflow.md); read it if missing or uncertain. A human request to save reviewed project lessons commissions bounded guidance updates; noticing a candidate or offering learning does not. Identify candidates from the available collection and completed Reviews; name missing context rather than inventing lessons. For candidates, follow the [learning guidance](../../references/learning-work.md) through reconciliation, proportionate prevention, authorized updates, read-back, and the complete outcome report. Otherwise explain that no supported learning is available. Learning does not authorize publication or another phase. +Apply the [working agreement](../../references/workflow.md); read it if missing or uncertain. A human request to save reviewed project lessons commissions bounded guidance updates; noticing a candidate or offering learning does not. Identify candidates from the available collection and completed Reviews; name missing context rather than inventing lessons. When the accepted work lives on an isolated branch or worktree, read [concurrent work](../../references/concurrent-work.md) and save project guidance on that checkout. For candidates, follow the [learning guidance](../../references/learning-work.md) through reconciliation, proportionate prevention, authorized updates, read-back, and the complete outcome report. Otherwise explain that no supported learning is available. Learning does not authorize publication or another phase. diff --git a/skills/plan-work/SKILL.md b/skills/plan-work/SKILL.md index 6f95e2d..86676b1 100644 --- a/skills/plan-work/SKILL.md +++ b/skills/plan-work/SKILL.md @@ -7,6 +7,8 @@ description: "Plan repository implementation when requested." Apply the [working agreement](../../references/workflow.md); read it if missing or uncertain. A natural-language request for an implementation plan selects planning; routine reasoning within implementation does not start a separate planning phase. Inspect the repository and applicable saved project lessons, checking their current relevance, before asking questions it can answer. Planning is read-only; verification inspection does not start the product. +Before questions, inspect this repository's worktrees, this checkout's uncommitted changes, and any unfinished plan or implementation already documented for it. When another workstream is active, or this checkout is dirty with work this task must leave untouched, read [concurrent work](../../references/concurrent-work.md) and record continue, wait, or isolate in the plan so implementation can cold-start. A clean sole checkout needs no worktree and no extra question. + Check relevant plan choices against the north star, assignment and success criteria; resolve consequential conflicts with the user. Stop when goal, boundaries, interfaces and checks suffice. Clear assignments need no interview or advance design of routine details. When the assignment is vague or underspecified (missing the goal, boundaries, interfaces, success checks, or a material trade-off that would change the plan), an optional short decision round may ask only what blocks a sound plan. Offer a concrete recommendation the user can accept or steer, in a few focused questions. Do not add a separate skill for that round, require a glossary, expand a design tree, or turn planning or Auto-Work into an interview gate. diff --git a/skills/review-work/SKILL.md b/skills/review-work/SKILL.md index 6aacd57..9b338a1 100644 --- a/skills/review-work/SKILL.md +++ b/skills/review-work/SKILL.md @@ -5,7 +5,7 @@ description: "Review Workflow implementation or corrections against its plan, re # review-work -Apply the [working agreement](../../references/workflow.md); read it if missing or uncertain. Use for a requested assessment of implementation or corrections, not merely an explanation of existing findings or a progress summary. Identify the applicable plan, implementation or correction report, and current working state. A delegated Auto-Work review follows the same rubric; return its result to the executor without requiring the human to change host modes. +Apply the [working agreement](../../references/workflow.md); read it if missing or uncertain. Use for a requested assessment of implementation or corrections, not merely an explanation of existing findings or a progress summary. Identify the applicable plan, implementation or correction report, and current working state. When that plan records another branch or worktree, read [concurrent work](../../references/concurrent-work.md) and review that checkout. A delegated Auto-Work review follows the same rubric; return its result to the executor without requiring the human to change host modes. Remain repository-read-only, including tracked and untracked files. Select inspections and tests whose effects are permitted; put any permitted transient outputs outside the repository. If a necessary check would mutate the repository or cross another permission boundary, record the missing evidence. Do not fix code, tests, documents, or verifiers during Review. diff --git a/skills/verification-work/SKILL.md b/skills/verification-work/SKILL.md index 3f318cf..9af07a7 100644 --- a/skills/verification-work/SKILL.md +++ b/skills/verification-work/SKILL.md @@ -5,6 +5,6 @@ description: "Create or maintain project verifiers." # verification-work -Apply the [working agreement](../../references/workflow.md); read it if missing or uncertain. Read the [verification guidance](../../references/verification-work.md). Use for work on concrete verifier instructions. Task-level coverage questions use [workflow-doctor](../workflow-doctor/SKILL.md); ordinary test execution needs no additional verification-work invocation. Default to read-only `inspect`, without starting the product. +Apply the [working agreement](../../references/workflow.md); read it if missing or uncertain. Read the [verification guidance](../../references/verification-work.md). Use for work on concrete verifier instructions. Task-level coverage questions use [workflow-doctor](../workflow-doctor/SKILL.md); ordinary test execution needs no additional verification-work invocation. Default to read-only `inspect`, without starting the product. When the product under test lives on an isolated branch or worktree, read [concurrent work](../../references/concurrent-work.md) and drive that checkout. For accepted `create` work, read [creation](./references/create.md). For accepted `maintain` or `maintain full` work, read [maintenance](./references/maintain.md). Planning may read the applicable reference to prepare the proposal; execution follows the shared guidance and applicable implementation or correction assignment. diff --git a/skills/work-status/SKILL.md b/skills/work-status/SKILL.md index b98c5bc..70d0609 100644 --- a/skills/work-status/SKILL.md +++ b/skills/work-status/SKILL.md @@ -5,6 +5,6 @@ description: "Summarize a Workflow task's documented progress, open points, and # work-status -Apply the [working agreement](../../references/workflow.md); read it if missing or uncertain. Stay read-only. Summarize documented progress; explaining a finding's reasoning uses [explain-work](../explain-work/SKILL.md), and judging current work requires a commissioned Review. From the available plan, assignments, and reports, explain what is complete and what remains uncertain. Identify the supporting documents and working state. Do not manufacture status from an identifier or treat absent reports as completion. Distinguish a completed phase from an achieved goal. If work remains, give the next useful action, who takes it, and why; ask for missing context precisely. Follow the documented phase outcome without starting another phase. If the goal is established as achieved, state that no further Workflow step is required. +Apply the [working agreement](../../references/workflow.md); read it if missing or uncertain. Stay read-only. Summarize documented progress; explaining a finding's reasoning uses [explain-work](../explain-work/SKILL.md), and judging current work requires a commissioned Review. From the available plan, assignments, and reports, explain what is complete and what remains uncertain. Identify the supporting documents and working state. When the plan records an isolated branch or worktree, name that checkout and whether reconcile is still open. Do not manufacture status from an identifier or treat absent reports as completion. Distinguish a completed phase from an achieved goal. If work remains, give the next useful action, who takes it, and why; ask for missing context precisely. Follow the documented phase outcome without starting another phase. If the goal is established as achieved, state that no further Workflow step is required. For Auto-Work, name the active or pending mode, phase, consumed and remaining correction rounds, latest independent Review, missing acceptance or delivery evidence, and next actor where relevant. Repository checks, human acceptance, and delivery are distinct outcomes. A status question does not reset or cancel the assignment; do not infer a mode switch or completion from it. diff --git a/tests/concurrent-work.test.mjs b/tests/concurrent-work.test.mjs new file mode 100644 index 0000000..1644cb5 --- /dev/null +++ b/tests/concurrent-work.test.mjs @@ -0,0 +1,32 @@ +import assert from "node:assert/strict"; +import { readFileSync } from "node:fs"; +import { join } from "node:path"; +import test from "node:test"; +import { defaultRoot, publicSkills } from "../scripts/build-plugin-targets.mjs"; + +const read = (path) => readFileSync(join(defaultRoot, path), "utf8"); + +test("concurrent work is a shared reference, not a new skill or a mandatory worktree", () => { + assert.ok(!publicSkills.includes("worktree-isolation")); + assert.ok(!publicSkills.includes("reconcile-worktree")); + const reference = read("references/concurrent-work.md"); + for (const phrase of ["Continue carefully", "**Wait.**", "**Isolate.**", "does not lock the repository", "git worktree add -b", "Reconcile or abandon", "cold-start record"]) { + assert.ok(reference.includes(phrase), phrase); + } + assert.match(read("skills/plan-work/SKILL.md"), /clean sole checkout needs no worktree/); + for (const path of [ + "skills/plan-work/SKILL.md", + "skills/review-work/SKILL.md", + "skills/correct-work/SKILL.md", + "skills/implement-work/SKILL.md", + "skills/learn-from-work/SKILL.md", + "skills/verification-work/SKILL.md", + "references/implementation-work.md", + "skills/auto-work/references/reviewer.md", + "skills/engineering-work/references/session-pickup.md", + "skills/engineering-work/references/pause-safely.md", + "skills/engineering-work/references/hillclimb.md", + ]) assert.match(read(path), /concurrent-work\.md/, path); + assert.match(read("skills/auto-work/references/operation.md"), /continue, wait, or isolate/); + assert.match(read("skills/work-status/SKILL.md"), /whether reconcile is still open/); +}); diff --git a/tests/context.test.mjs b/tests/context.test.mjs index 99724b5..584bbc0 100644 --- a/tests/context.test.mjs +++ b/tests/context.test.mjs @@ -67,6 +67,19 @@ test("context covers packaged instructions once, including required planning and assert.ok(scenarios["planMethod:refactoring"].documents.includes("skills/engineering-work/references/refactoring.md")); assert.ok(!scenarios.autoWork.documents.includes("skills/auto-work/references/delivery.md")); assert.ok(scenarios.autoWorkDelivery.documents.includes("skills/auto-work/references/delivery.md")); + const concurrent = "references/concurrent-work.md"; + for (const name of ["plan", "review", "correction", "autoWork", "learning", "verificationInspect"]) { + assert.ok(!scenarios[name].documents.includes(concurrent), `${host} ${name}`); + } + for (const [name, base] of [["planConcurrent", "plan"], ["reviewConcurrent", "review"], ["correctionConcurrent", "correction"], ["autoWorkConcurrent", "autoWork"], ["learningConcurrent", "learning"], ["verificationConcurrent", "verificationInspect"]]) { + assert.ok(scenarios[name].documents.includes(concurrent), `${host} ${name}`); + for (const path of scenarios[base].documents) assert.ok(scenarios[name].documents.includes(path), `${host} ${name} ${path}`); + } + assert.equal(scenarios.implementationConcurrent === undefined, host !== "agent-plugins"); + if (host === "agent-plugins") { + assert.ok(!scenarios.implementation.documents.includes(concurrent)); + assert.ok(scenarios.implementationConcurrent.documents.includes(concurrent)); + } assert.ok(!scenarios.verificationCreation.documents.includes("skills/verification-work/references/maintain.md")); } } finally { rmSync(item.parent, { recursive: true, force: true }); } From 37e3aca5793d65ca4662464f76117cde3850d3ab Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Wed, 7 Oct 2026 09:59:36 +0000 Subject: [PATCH 2/3] Tighten when a worktree is overlap and when isolation may start. Count only in-flight worktrees, let wait win on mid-edit files, and create a worktree at the first implementation step when a reviewer can read that checkout. Co-authored-by: Dennis Geldmacher --- CHANGELOG.md | 2 +- docs/behavior-validation.md | 13 +++++++------ docs/manual-workflow.md | 4 ++-- docs/methodology-sources.md | 2 +- references/concurrent-work.md | 19 ++++++++++++------- skills/auto-work/references/reviewer.md | 2 +- skills/plan-work/SKILL.md | 2 +- tests/concurrent-work.test.mjs | 4 +++- 8 files changed, 28 insertions(+), 20 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index f253a3b..8e1bbd6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,7 +2,7 @@ ## Unreleased -- Warn at plan start when another plan or implementation is already active on the same repository, and offer continue, wait, or an optional git worktree. Review, correction, learning, and verification follow that checkout; merge and worktree removal stay explicitly requested. +- Warn at plan start when another plan or implementation is already active on the same repository, and offer continue, wait, or an optional git worktree. A clean idle worktree is not overlap. Wait wins when the same files are mid-edit. Isolate only when a reviewer can use that checkout, and create it at the first implementation step. Review, correction, learning, and verification follow that checkout; merge and worktree removal stay explicitly requested. ## 7.8.0 diff --git a/docs/behavior-validation.md b/docs/behavior-validation.md index 26e574f..394eb4f 100644 --- a/docs/behavior-validation.md +++ b/docs/behavior-validation.md @@ -109,13 +109,14 @@ Walk through these cases against [planning](../skills/plan-work/SKILL.md), [conc | Situation | Expected decision | Instructions to inspect | |---|---|---| -| The checkout is clean and no other plan, implementation, worktree, or documented unfinished task names this repository. | Plan in place. Ask no checkout question and create no worktree. | [Planning](../skills/plan-work/SKILL.md) | -| Another git worktree is implementing on this repository, or this checkout is dirty with edits this task must leave untouched. | Warn, and offer continue carefully, wait, or isolate, with one recommendation. Recommend isolate. Planning records the choice and does not create the worktree. Continuing in place stays available. | [Planning](../skills/plan-work/SKILL.md), [concurrent work](../references/concurrent-work.md) | +| The checkout is clean and no other plan, implementation, or documented unfinished task names this repository. Another worktree exists and is clean: no uncommitted changes, no in-flight commits named by a handoff or host task, and no unfinished plan for that checkout. | Plan in place. Ask no checkout question and create no worktree. A clean idle worktree is not another workstream. | [Planning](../skills/plan-work/SKILL.md), [concurrent work](../references/concurrent-work.md) | +| Another git worktree is implementing on this repository, or this checkout is dirty with edits this task must leave untouched, and a fresh reviewer can use the intended worktree as its workspace. | Warn, and offer continue carefully, wait, or isolate. The first matching rule recommends isolate. Planning records the choice and does not create the worktree. Continuing in place stays available. | [Planning](../skills/plan-work/SKILL.md), [concurrent work](../references/concurrent-work.md) | +| Isolate would fit, but the host cannot give a fresh reviewer the intended worktree as its workspace. | Recommend continue carefully. Say that independent review would be unable to read the isolated checkout. Still offer wait. | [Concurrent work](../references/concurrent-work.md), [Auto-Work reviewer](../skills/auto-work/references/reviewer.md) | | The human chooses to continue in the dirty checkout. | Record continue. Later edits preserve the unrelated files. Do not treat the warning as a lock. | [Concurrent work](../references/concurrent-work.md), [correction](../skills/correct-work/SKILL.md) | -| The other workstream is mid-edit on the same files this task must change. | Recommend wait. The plan may finish. Hold product edits until that blocker clears. | [Concurrent work](../references/concurrent-work.md) | -| Dark Auto-Work has a clear overlap and the commissioned goal did not pick a checkout. | Record the recommendation and follow it. Pause before edits when the other owner or the overlapping files are unclear. | [Concurrent work](../references/concurrent-work.md), [Auto-Work operation](../skills/auto-work/references/operation.md) | -| Implementation is cold-started from a plan that already says isolate, with a base, branch, and path. | Create the worktree when it is missing, then edit only there. Do not repeat the choice interview. Commit, push, and merge stay unauthorized. | [Implementation requirements](../references/implementation-work.md), [concurrent work](../references/concurrent-work.md) | -| Review is opened from the primary checkout while the change exists only in the recorded worktree. | Review that worktree and branch, read-only. A primary checkout without the change is the wrong tree. Missing access is missing proof. | [Review](../skills/review-work/SKILL.md), [concurrent work](../references/concurrent-work.md) | +| The other workstream is mid-edit on the same files this task must change. | The first rule recommends wait, ahead of isolate. The plan may finish. Hold product edits until that blocker clears. | [Concurrent work](../references/concurrent-work.md) | +| Dark Auto-Work has a clear overlap, a readable review workspace, and the commissioned goal did not pick a checkout. | Record isolate in the plan. Create the worktree only as the first implementation step, for the named branch and path. Pause and do not create it when the other owner or the overlapping files are unclear. Commit, push, and merge stay unauthorized. | [Concurrent work](../references/concurrent-work.md), [Auto-Work operation](../skills/auto-work/references/operation.md) | +| Implementation is cold-started from a plan that already says isolate, with a base, branch, and path, and the owner and files are clear. | Create the worktree when it is missing, then edit only there. Do not repeat the choice interview. Commit, push, and merge stay unauthorized. | [Implementation requirements](../references/implementation-work.md), [concurrent work](../references/concurrent-work.md) | +| Review is opened from the primary checkout while the change exists only in the recorded worktree. | Start the reviewer with that worktree as its workspace. Review that branch, read-only. A primary checkout without the change is the wrong tree. When the path cannot be read, missing access is missing proof. | [Review](../skills/review-work/SKILL.md), [concurrent work](../references/concurrent-work.md), [Auto-Work reviewer](../skills/auto-work/references/reviewer.md) | | Correction findings apply to isolated work, and the primary checkout has unrelated edits. | Patch the recorded worktree. Leave the primary checkout untouched. Folding the branch back is a later explicit reconcile, not part of correction. | [Correction](../skills/correct-work/SKILL.md), [concurrent work](../references/concurrent-work.md) | | The human asks to merge the isolated branch and remove its worktree. The destination checkout is clean. | Merge into the named destination, recheck there, then remove only the worktree this assignment added. Delete the branch only if they also asked and it is merged. | [Concurrent work](../references/concurrent-work.md) | | The human asks to merge, and the destination checkout is dirty with unrelated edits. | Stop and show that dirt. Do not stash, commit, or merge over it. | [Concurrent work](../references/concurrent-work.md) | diff --git a/docs/manual-workflow.md b/docs/manual-workflow.md index b564feb..feebfae 100644 --- a/docs/manual-workflow.md +++ b/docs/manual-workflow.md @@ -54,9 +54,9 @@ A successful implementation report is the input to review. It does not mean revi ### When another task already uses this repository -At the start of planning, the agent checks this repository for another active plan or implementation. That includes another git worktree, this branch checked out twice, a documented unfinished task, or unrelated edits that implementation would otherwise change. A clean checkout with no other active work continues as usual. Planning does not create a worktree, and a plan does not have to use one. +At the start of planning, the agent checks this repository for another active plan or implementation. A git worktree counts when it has uncommitted work, in-flight commits named by a task, or an unfinished plan for that checkout. A clean idle worktree does not. The same branch checked out twice, a documented unfinished task, or unrelated edits that implementation would otherwise change also count. A clean checkout with no other active work continues as usual. Planning does not create a worktree, and a plan does not have to use one. -When there is overlap, you get a warning and three choices: continue carefully in this checkout, wait, or isolate the work on its own branch and git worktree. Isolation is the usual recommendation when someone else is already changing this repository, or when your checkout has unrelated edits that should stay untouched. You can still continue in place. Waiting holds edits until the other work releases the files it is changing. +When there is overlap, you get a warning and three choices: continue carefully in this checkout, wait, or isolate the work on its own branch and git worktree. Waiting is the recommendation when the other task is mid-edit on the same files. Isolation is the recommendation when someone else is already changing this repository, or when your checkout has unrelated edits that should stay untouched, and a later review can read that worktree. When a review could not see it, the recommendation stays in the current checkout and says why. You can still choose otherwise. The plan records the choice. Implementation follows that record, and creates the worktree only after the plan allows isolate. Review and correction use that same checkout. Merging the branch back, or removing the worktree after you discard the attempt, happens only when you ask. diff --git a/docs/methodology-sources.md b/docs/methodology-sources.md index ac8ebcb..a6e4166 100644 --- a/docs/methodology-sources.md +++ b/docs/methodology-sources.md @@ -51,7 +51,7 @@ Automated checks were already on the ladder. This adaptation does not add a `/re ## Concurrent checkouts -Optional git worktrees for overlapping tasks are original instructions in `references/concurrent-work.md`. They are not a playbook and not a separate skill. Planning stays read-only. The native plan is the cold-start record Implement follows, including the continue, wait, or isolate choice. The removed controller worktrees, sandboxes, and sealed plan artifacts stay removed. Visual parity still has no mandatory worktree. A repeated checkout collision stays an environment lesson under the existing correction ladder: prefer a check, or this shared procedure, over a new project rule that copies the steps. +Optional git worktrees for overlapping tasks are original instructions in `references/concurrent-work.md`. They are not a playbook and not a separate skill. A clean idle worktree is not overlap. The first matching rule recommends wait, then isolate only when a reviewer can use that checkout as its workspace, then continue. Planning stays read-only. The native plan is the cold-start record Implement follows, including the continue, wait, or isolate choice. Creating the worktree is the first implementation step, and Dark pauses when the other owner or the overlapping files are unclear. The removed controller worktrees, sandboxes, and sealed plan artifacts stay removed. Visual parity still has no mandatory worktree. A repeated checkout collision stays an environment lesson under the existing correction ladder: prefer a check, or this shared procedure, over a new project rule that copies the steps. ## Shared integration decisions diff --git a/references/concurrent-work.md b/references/concurrent-work.md index be8ab06..13e3122 100644 --- a/references/concurrent-work.md +++ b/references/concurrent-work.md @@ -11,8 +11,8 @@ The plan in the native task is the cold-start record. Implementation, review, co 1. Identify the repository by its git common directory (`git rev-parse --git-common-dir`) and list checkouts with `git worktree list --porcelain`. Linked worktrees of that common directory are the same repository. 2. Stay read-only while detecting. Use status and listing only. 3. Inspect other worktrees and the branches they have checked out, this checkout's branch and uncommitted changes, unfinished plans or implementation reports already in this task or supplied with it that name this repository, and host-visible sessions for this repository when the host already exposes them. Do not search unrelated private conversations. -4. Overlap is another worktree of this repository, this branch checked out in more than one worktree, a documented unfinished plan or implementation for this repository, or uncommitted changes this assignment did not make when the next edit would land in that checkout. -5. Local branches with no worktree, no unfinished handoff, and no host-visible task are not overlap. This assignment's own recorded worktree is not a new overlap. +4. Overlap is uncommitted changes this assignment did not make when the next edit would land in that checkout, a documented unfinished plan or implementation that names this repository, or this branch checked out in another worktree that has those changes or that unfinished task. Another worktree counts only when that checkout has uncommitted changes, or commits the branch this task would use does not contain and a handoff, a host-visible task, or that checkout's current work identifies. +5. A clean idle worktree is not overlap. A local branch with no worktree, no unfinished handoff, and no host-visible task is not overlap. This assignment's own recorded worktree is not a new overlap. ## Choose @@ -22,9 +22,14 @@ When overlap exists, warn and offer three options. Mark one as the recommendatio - **Wait.** The plan can still be finished. Hold edits until the other workstream releases the checkout or the overlapping files. Name who is in the way and what to recheck. Do not poll without a new request. - **Isolate.** Use a dedicated branch and a git worktree so this workstream does not edit the other checkout. -Recommend **isolate** when another workstream is active on this repository, or when implementation would otherwise change a dirty checkout this task must leave untouched. Recommend **wait** when that other workstream is mid-edit on the same files and branching from that state would drop their unfinished work. Recommend **continue carefully** when the human wants one checkout, or when a worktree cannot be created. +Use the first matching rule. One recommendation. -Standalone and Light planning record the choice and do not create the worktree. Light approval of the plan accepts the recorded choice. Dark Auto-Work records the recommendation and may follow it when the commissioned goal did not pick otherwise. Pause before edits when the other owner or the overlapping files are unclear. An explicit continue, wait, or isolate from the human overrides the recommendation. +1. The other workstream is mid-edit on files this task must change, and a branch from that state would drop their unfinished work. Recommend **wait**. +2. Another workstream is active, or implementation would change a dirty checkout this task must leave untouched, and a fresh reviewer can use the intended worktree as its workspace. Recommend **isolate**. +3. That same overlap exists, and a fresh reviewer cannot use the intended worktree as its workspace. Recommend **continue carefully**, and say that independent review would be unable to read the isolated checkout. Still offer wait. +4. The human wants one checkout, or a worktree cannot be created. Recommend **continue carefully**. + +Standalone and Light planning record the recommendation and do not create the worktree. Light approval of the plan accepts the recorded choice. `git worktree add` runs only as the first implementation step, and only for the branch and path named in the plan. That step still does not authorize commit, push, merge, or deletion. Dark may take it when the commissioned sequence's plan recommends isolate and both the other owner and the overlapping files are clear. When either is unclear, pause and do not create the worktree. An explicit continue, wait, or isolate from the human overrides the recommendation. Silence while planning is still read-only is not approval to create a worktree. Record the decision in the plan: @@ -39,7 +44,7 @@ A later executor that has only the plan uses these fields and does not repeat th ## Isolate -Create the branch and worktree at the start of implementation, after the plan records isolate. That recorded choice authorizes this bounded git setup only. It does not authorize commit, push, merge, or deletion. +Create the branch and worktree as the first implementation step, after the plan records isolate and the other owner and overlapping files are clear. Light approval or that clear Dark continuation authorizes this bounded git setup only. It does not authorize commit, push, merge, or deletion. When the owner or the files are unclear, pause and leave the worktree uncreated. 1. Choose a base that excludes unrelated dirty work. A clean HEAD can be the base. When the checkout is dirty, use the committed HEAD or the branch the plan names, and leave that dirty checkout untouched. 2. Create a branch named for this assignment. Leave a branch that is checked out elsewhere, or that holds commits the plan did not accept, as it is. @@ -58,9 +63,9 @@ A cold start follows the plan's fields. It does not open a new choice unless tho ## Review -Review the branch and worktree the plan records. A primary checkout that does not contain the change is the wrong tree. Stay read-only: leave merge, commit, worktree removal, and copying files back for an explicitly requested reconcile. When the recorded path is unavailable, report that missing checkout as missing proof. +Review the branch and worktree the plan records. A primary checkout that does not contain the change is the wrong tree. Stay read-only: leave merge, commit, worktree removal, and copying files back for an explicitly requested reconcile. Start a delegated reviewer with that worktree as its workspace. When the recorded path cannot be read, report that missing checkout as missing proof. -Auto-Work gives the reviewer the path, branch, and this reference. The executor still makes no concurrent writes to that worktree while review runs. +Auto-Work gives the reviewer the path, branch, and this reference, and starts it in that workspace when the host can. The executor still makes no concurrent writes to that worktree while review runs. ## Correct diff --git a/skills/auto-work/references/reviewer.md b/skills/auto-work/references/reviewer.md index 2bcbe91..bade35a 100644 --- a/skills/auto-work/references/reviewer.md +++ b/skills/auto-work/references/reviewer.md @@ -1,6 +1,6 @@ # Independent review in Auto-Work -For each initial or post-correction Review, start a fresh separate native agent. Give it the applicable plan and assignment, active mode, implementation or correction report, exact current workspace or revision, relevant raw evidence, and the learning collection through an accessible reference, or the full collection when the reviewer cannot access that reference. When the plan records an isolated branch or worktree, give the reviewer that path, branch, and [concurrent work](../../../references/concurrent-work.md). Give access to the packaged [review skill](../../review-work/SKILL.md) and its linked references. A copied implementation conclusion is not independent evidence. Do not give the reviewer the answer it should reach. +For each initial or post-correction Review, start a fresh separate native agent. Give it the applicable plan and assignment, active mode, implementation or correction report, exact current workspace or revision, relevant raw evidence, and the learning collection through an accessible reference, or the full collection when the reviewer cannot access that reference. When the plan records an isolated branch or worktree, start the reviewer with that checkout as its workspace and give it the path, branch, and [concurrent work](../../../references/concurrent-work.md). When that path cannot be read, report missing proof. Give access to the packaged [review skill](../../review-work/SKILL.md) and its linked references. A copied implementation conclusion is not independent evidence. Do not give the reviewer the answer it should reach. Use available host read-only restrictions and explicitly require repository-read-only behavior, including untracked files. Inherit the parent's model settings. Do not create global agent configurations, weaken host permissions, or substitute a self-review when delegation is unavailable. A separate context provides separation of judgment, not a guarantee of correctness or a new sandbox; describe actual host restrictions honestly. diff --git a/skills/plan-work/SKILL.md b/skills/plan-work/SKILL.md index 86676b1..4444031 100644 --- a/skills/plan-work/SKILL.md +++ b/skills/plan-work/SKILL.md @@ -7,7 +7,7 @@ description: "Plan repository implementation when requested." Apply the [working agreement](../../references/workflow.md); read it if missing or uncertain. A natural-language request for an implementation plan selects planning; routine reasoning within implementation does not start a separate planning phase. Inspect the repository and applicable saved project lessons, checking their current relevance, before asking questions it can answer. Planning is read-only; verification inspection does not start the product. -Before questions, inspect this repository's worktrees, this checkout's uncommitted changes, and any unfinished plan or implementation already documented for it. When another workstream is active, or this checkout is dirty with work this task must leave untouched, read [concurrent work](../../references/concurrent-work.md) and record continue, wait, or isolate in the plan so implementation can cold-start. A clean sole checkout needs no worktree and no extra question. +Before questions, inspect other worktrees for in-flight work, this checkout's uncommitted changes, and any unfinished plan or implementation already documented for this repository. A clean idle worktree is not another workstream. When another workstream is active, or this checkout is dirty with work this task must leave untouched, read [concurrent work](../../references/concurrent-work.md) and record continue, wait, or isolate in the plan so implementation can cold-start. A clean sole checkout needs no worktree and no extra question. Check relevant plan choices against the north star, assignment and success criteria; resolve consequential conflicts with the user. Stop when goal, boundaries, interfaces and checks suffice. Clear assignments need no interview or advance design of routine details. diff --git a/tests/concurrent-work.test.mjs b/tests/concurrent-work.test.mjs index 1644cb5..2f67c8d 100644 --- a/tests/concurrent-work.test.mjs +++ b/tests/concurrent-work.test.mjs @@ -10,10 +10,12 @@ test("concurrent work is a shared reference, not a new skill or a mandatory work assert.ok(!publicSkills.includes("worktree-isolation")); assert.ok(!publicSkills.includes("reconcile-worktree")); const reference = read("references/concurrent-work.md"); - for (const phrase of ["Continue carefully", "**Wait.**", "**Isolate.**", "does not lock the repository", "git worktree add -b", "Reconcile or abandon", "cold-start record"]) { + for (const phrase of ["Continue carefully", "**Wait.**", "**Isolate.**", "does not lock the repository", "git worktree add -b", "Reconcile or abandon", "cold-start record", "A clean idle worktree is not overlap.", "Use the first matching rule.", "as its workspace", "first implementation step"]) { assert.ok(reference.includes(phrase), phrase); } assert.match(read("skills/plan-work/SKILL.md"), /clean sole checkout needs no worktree/); + assert.match(read("skills/plan-work/SKILL.md"), /clean idle worktree is not another workstream/); + assert.match(read("skills/auto-work/references/reviewer.md"), /as its workspace/); for (const path of [ "skills/plan-work/SKILL.md", "skills/review-work/SKILL.md", From 9d4501ef6cab2db4dc15763dcbda26c3de58e3b5 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Wed, 7 Oct 2026 10:11:51 +0000 Subject: [PATCH 3/3] Record whether an overlapping checkout is clear before creating a worktree. Count another worktree only for uncommitted work or a named handoff, and treat an unclear reviewer workspace or a missing clarity field as a pause. Co-authored-by: Dennis Geldmacher --- CHANGELOG.md | 2 +- docs/behavior-validation.md | 6 +++--- docs/manual-workflow.md | 2 +- docs/methodology-sources.md | 2 +- references/concurrent-work.md | 12 +++++++----- tests/concurrent-work.test.mjs | 2 +- 6 files changed, 14 insertions(+), 12 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 8e1bbd6..fc4eb39 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,7 +2,7 @@ ## Unreleased -- Warn at plan start when another plan or implementation is already active on the same repository, and offer continue, wait, or an optional git worktree. A clean idle worktree is not overlap. Wait wins when the same files are mid-edit. Isolate only when a reviewer can use that checkout, and create it at the first implementation step. Review, correction, learning, and verification follow that checkout; merge and worktree removal stay explicitly requested. +- Warn at plan start when another plan or implementation is already active on the same repository, and offer continue, wait, or an optional git worktree. A clean idle worktree is not overlap, and commits that only exist on its branch do not count. Wait wins when the same files are mid-edit. Isolate only when this host can start a reviewer outside the current checkout. The plan records whether the other owner and overlapping files are clear, and implementation creates the worktree only then. Review, correction, learning, and verification follow that checkout; merge and worktree removal stay explicitly requested. ## 7.8.0 diff --git a/docs/behavior-validation.md b/docs/behavior-validation.md index 394eb4f..fbd5c83 100644 --- a/docs/behavior-validation.md +++ b/docs/behavior-validation.md @@ -109,13 +109,13 @@ Walk through these cases against [planning](../skills/plan-work/SKILL.md), [conc | Situation | Expected decision | Instructions to inspect | |---|---|---| -| The checkout is clean and no other plan, implementation, or documented unfinished task names this repository. Another worktree exists and is clean: no uncommitted changes, no in-flight commits named by a handoff or host task, and no unfinished plan for that checkout. | Plan in place. Ask no checkout question and create no worktree. A clean idle worktree is not another workstream. | [Planning](../skills/plan-work/SKILL.md), [concurrent work](../references/concurrent-work.md) | +| The checkout is clean and no other plan, implementation, or documented unfinished task names this repository. Another worktree has commits on its own branch and no uncommitted changes, and no handoff or host task names that checkout. | Plan in place. Ask no checkout question and create no worktree. Commits that only exist on that branch are not overlap. | [Planning](../skills/plan-work/SKILL.md), [concurrent work](../references/concurrent-work.md) | | Another git worktree is implementing on this repository, or this checkout is dirty with edits this task must leave untouched, and a fresh reviewer can use the intended worktree as its workspace. | Warn, and offer continue carefully, wait, or isolate. The first matching rule recommends isolate. Planning records the choice and does not create the worktree. Continuing in place stays available. | [Planning](../skills/plan-work/SKILL.md), [concurrent work](../references/concurrent-work.md) | -| Isolate would fit, but the host cannot give a fresh reviewer the intended worktree as its workspace. | Recommend continue carefully. Say that independent review would be unable to read the isolated checkout. Still offer wait. | [Concurrent work](../references/concurrent-work.md), [Auto-Work reviewer](../skills/auto-work/references/reviewer.md) | +| Isolate would fit, but this host cannot start a child agent with a workspace outside the current checkout, or that ability is unclear. | Recommend continue carefully. Say that independent review would be unable to read the isolated checkout. Do not assume a sibling directory is visible. Still offer wait. | [Concurrent work](../references/concurrent-work.md), [Auto-Work reviewer](../skills/auto-work/references/reviewer.md) | | The human chooses to continue in the dirty checkout. | Record continue. Later edits preserve the unrelated files. Do not treat the warning as a lock. | [Concurrent work](../references/concurrent-work.md), [correction](../skills/correct-work/SKILL.md) | | The other workstream is mid-edit on the same files this task must change. | The first rule recommends wait, ahead of isolate. The plan may finish. Hold product edits until that blocker clears. | [Concurrent work](../references/concurrent-work.md) | | Dark Auto-Work has a clear overlap, a readable review workspace, and the commissioned goal did not pick a checkout. | Record isolate in the plan. Create the worktree only as the first implementation step, for the named branch and path. Pause and do not create it when the other owner or the overlapping files are unclear. Commit, push, and merge stay unauthorized. | [Concurrent work](../references/concurrent-work.md), [Auto-Work operation](../skills/auto-work/references/operation.md) | -| Implementation is cold-started from a plan that already says isolate, with a base, branch, and path, and the owner and files are clear. | Create the worktree when it is missing, then edit only there. Do not repeat the choice interview. Commit, push, and merge stay unauthorized. | [Implementation requirements](../references/implementation-work.md), [concurrent work](../references/concurrent-work.md) | +| Implementation is cold-started from a plan that already says isolate, with a base, branch, and path. One plan says the other owner and the overlapping files are clear. Another omits that field. | Create the worktree only for the plan that says they are clear, then edit only there. When the field is missing or unclear, pause and leave the worktree uncreated. Do not repeat the choice interview. Commit, push, and merge stay unauthorized. | [Implementation requirements](../references/implementation-work.md), [concurrent work](../references/concurrent-work.md) | | Review is opened from the primary checkout while the change exists only in the recorded worktree. | Start the reviewer with that worktree as its workspace. Review that branch, read-only. A primary checkout without the change is the wrong tree. When the path cannot be read, missing access is missing proof. | [Review](../skills/review-work/SKILL.md), [concurrent work](../references/concurrent-work.md), [Auto-Work reviewer](../skills/auto-work/references/reviewer.md) | | Correction findings apply to isolated work, and the primary checkout has unrelated edits. | Patch the recorded worktree. Leave the primary checkout untouched. Folding the branch back is a later explicit reconcile, not part of correction. | [Correction](../skills/correct-work/SKILL.md), [concurrent work](../references/concurrent-work.md) | | The human asks to merge the isolated branch and remove its worktree. The destination checkout is clean. | Merge into the named destination, recheck there, then remove only the worktree this assignment added. Delete the branch only if they also asked and it is merged. | [Concurrent work](../references/concurrent-work.md) | diff --git a/docs/manual-workflow.md b/docs/manual-workflow.md index feebfae..43037d0 100644 --- a/docs/manual-workflow.md +++ b/docs/manual-workflow.md @@ -54,7 +54,7 @@ A successful implementation report is the input to review. It does not mean revi ### When another task already uses this repository -At the start of planning, the agent checks this repository for another active plan or implementation. A git worktree counts when it has uncommitted work, in-flight commits named by a task, or an unfinished plan for that checkout. A clean idle worktree does not. The same branch checked out twice, a documented unfinished task, or unrelated edits that implementation would otherwise change also count. A clean checkout with no other active work continues as usual. Planning does not create a worktree, and a plan does not have to use one. +At the start of planning, the agent checks this repository for another active plan or implementation. A git worktree counts when it has uncommitted work, or a handoff or host task names that checkout. Commits that only exist on its branch do not. An unfinished plan for this repository also counts. A clean idle worktree does not. The same branch checked out twice, a documented unfinished task, or unrelated edits that implementation would otherwise change also count. A clean checkout with no other active work continues as usual. Planning does not create a worktree, and a plan does not have to use one. When there is overlap, you get a warning and three choices: continue carefully in this checkout, wait, or isolate the work on its own branch and git worktree. Waiting is the recommendation when the other task is mid-edit on the same files. Isolation is the recommendation when someone else is already changing this repository, or when your checkout has unrelated edits that should stay untouched, and a later review can read that worktree. When a review could not see it, the recommendation stays in the current checkout and says why. You can still choose otherwise. diff --git a/docs/methodology-sources.md b/docs/methodology-sources.md index a6e4166..4429800 100644 --- a/docs/methodology-sources.md +++ b/docs/methodology-sources.md @@ -51,7 +51,7 @@ Automated checks were already on the ladder. This adaptation does not add a `/re ## Concurrent checkouts -Optional git worktrees for overlapping tasks are original instructions in `references/concurrent-work.md`. They are not a playbook and not a separate skill. A clean idle worktree is not overlap. The first matching rule recommends wait, then isolate only when a reviewer can use that checkout as its workspace, then continue. Planning stays read-only. The native plan is the cold-start record Implement follows, including the continue, wait, or isolate choice. Creating the worktree is the first implementation step, and Dark pauses when the other owner or the overlapping files are unclear. The removed controller worktrees, sandboxes, and sealed plan artifacts stay removed. Visual parity still has no mandatory worktree. A repeated checkout collision stays an environment lesson under the existing correction ladder: prefer a check, or this shared procedure, over a new project rule that copies the steps. +Optional git worktrees for overlapping tasks are original instructions in `references/concurrent-work.md`. They are not a playbook and not a separate skill. A clean idle worktree is not overlap. The first matching rule recommends wait, then isolate only when this host can start a child workspace outside the current checkout, then continue. Planning stays read-only. The native plan is the cold-start record Implement follows, including the continue, wait, or isolate choice and whether the other owner and overlapping files are clear. Creating the worktree is the first implementation step, and only when that field says clear. A missing field pauses. Commits that only exist on another branch are not overlap. The removed controller worktrees, sandboxes, and sealed plan artifacts stay removed. Visual parity still has no mandatory worktree. A repeated checkout collision stays an environment lesson under the existing correction ladder: prefer a check, or this shared procedure, over a new project rule that copies the steps. ## Shared integration decisions diff --git a/references/concurrent-work.md b/references/concurrent-work.md index 13e3122..174ca25 100644 --- a/references/concurrent-work.md +++ b/references/concurrent-work.md @@ -11,8 +11,8 @@ The plan in the native task is the cold-start record. Implementation, review, co 1. Identify the repository by its git common directory (`git rev-parse --git-common-dir`) and list checkouts with `git worktree list --porcelain`. Linked worktrees of that common directory are the same repository. 2. Stay read-only while detecting. Use status and listing only. 3. Inspect other worktrees and the branches they have checked out, this checkout's branch and uncommitted changes, unfinished plans or implementation reports already in this task or supplied with it that name this repository, and host-visible sessions for this repository when the host already exposes them. Do not search unrelated private conversations. -4. Overlap is uncommitted changes this assignment did not make when the next edit would land in that checkout, a documented unfinished plan or implementation that names this repository, or this branch checked out in another worktree that has those changes or that unfinished task. Another worktree counts only when that checkout has uncommitted changes, or commits the branch this task would use does not contain and a handoff, a host-visible task, or that checkout's current work identifies. -5. A clean idle worktree is not overlap. A local branch with no worktree, no unfinished handoff, and no host-visible task is not overlap. This assignment's own recorded worktree is not a new overlap. +4. Overlap is uncommitted changes this assignment did not make when the next edit would land in that checkout, or a documented unfinished plan or implementation that names this repository. Another worktree counts only when that checkout has uncommitted changes, or when a handoff or host-visible task names both this repository and that checkout. The same branch checked out in another worktree counts when that checkout has those changes or that unfinished task. +5. A clean idle worktree is not overlap. Commits that only exist on its branch do not count. A local branch with no worktree, no unfinished handoff, and no host-visible task is not overlap. This assignment's own recorded worktree is not a new overlap. ## Choose @@ -22,6 +22,8 @@ When overlap exists, warn and offer three options. Mark one as the recommendatio - **Wait.** The plan can still be finished. Hold edits until the other workstream releases the checkout or the overlapping files. Name who is in the way and what to recheck. Do not poll without a new request. - **Isolate.** Use a dedicated branch and a git worktree so this workstream does not edit the other checkout. +A fresh reviewer can use the intended worktree when this host can start a child agent with a workspace outside the current checkout. When that is unclear, it cannot. Do not assume a sibling directory is visible. + Use the first matching rule. One recommendation. 1. The other workstream is mid-edit on files this task must change, and a branch from that state would drop their unfinished work. Recommend **wait**. @@ -37,7 +39,7 @@ Silence while planning is still read-only is not approval to create a worktree. - choice: continue, wait, or isolate - for continue: which unrelated changes must be preserved - for wait: what blocks edits -- for isolate: base revision, branch, worktree path, and whether the worktree has been created +- for isolate: base revision, branch, worktree path, whether the worktree has been created, and whether the other owner and the overlapping files are clear - that review, correction, learning, verification, and reconcile follow this reference A later executor that has only the plan uses these fields and does not repeat the choice. @@ -57,9 +59,9 @@ Isolation keeps the other checkout intact. Later merge conflicts remain possible ## Implement -Edit only the checkout the plan names. When the choice is isolate and the worktree is missing, create it before the first product edit. When the shell is in a different checkout, move to the recorded path before editing. When the choice is continue, preserve the unrelated changes named in the plan. When the choice is wait, do not edit until the recorded blocker has cleared, then re-read the checkout and continue in the recorded place. +Edit only the checkout the plan names. When the choice is isolate and the worktree is missing, create it before the first product edit only if the plan says the other owner and the overlapping files are clear. When that field is missing or unclear, pause and leave the worktree uncreated. When the shell is in a different checkout, move to the recorded path before editing. When the choice is continue, preserve the unrelated changes named in the plan. When the choice is wait, do not edit until the recorded blocker has cleared, then re-read the checkout and continue in the recorded place. -A cold start follows the plan's fields. It does not open a new choice unless those fields are missing and this checkout now has other in-flight work. +A cold start follows the plan's fields, including that clarity field. It does not open a new choice unless those fields are missing and this checkout now has other in-flight work. A missing clarity field is a pause, not permission to create the worktree. ## Review diff --git a/tests/concurrent-work.test.mjs b/tests/concurrent-work.test.mjs index 2f67c8d..6f340cf 100644 --- a/tests/concurrent-work.test.mjs +++ b/tests/concurrent-work.test.mjs @@ -10,7 +10,7 @@ test("concurrent work is a shared reference, not a new skill or a mandatory work assert.ok(!publicSkills.includes("worktree-isolation")); assert.ok(!publicSkills.includes("reconcile-worktree")); const reference = read("references/concurrent-work.md"); - for (const phrase of ["Continue carefully", "**Wait.**", "**Isolate.**", "does not lock the repository", "git worktree add -b", "Reconcile or abandon", "cold-start record", "A clean idle worktree is not overlap.", "Use the first matching rule.", "as its workspace", "first implementation step"]) { + for (const phrase of ["Continue carefully", "**Wait.**", "**Isolate.**", "does not lock the repository", "git worktree add -b", "Reconcile or abandon", "cold-start record", "A clean idle worktree is not overlap.", "Commits that only exist on its branch do not count.", "workspace outside the current checkout", "Use the first matching rule.", "as its workspace", "first implementation step", "whether the other owner and the overlapping files are clear", "A missing clarity field is a pause"]) { assert.ok(reference.includes(phrase), phrase); } assert.match(read("skills/plan-work/SKILL.md"), /clean sole checkout needs no worktree/);