Skip to content

fix: remove own scratch and dependency installs at every handoff (#267) - #268

Merged
lukemaj merged 1 commit into
mainfrom
task/handoff-scratch-cleanup
Nov 13, 2026
Merged

lukemaj merged 1 commit into
mainfrom
task/handoff-scratch-cleanup

Conversation

@lukemaj

@lukemaj lukemaj commented Nov 13, 2026

Copy link
Copy Markdown
Contributor

What changed: The core Handoff section now requires every agent, whatever the outcome, to remove the scratch files, snapshot copies and dependency installs it created before its final handoff, using the harness session scratchpad when one exists.
Why: Only Delivery Finalization required cleanup, after a terminal delivery outcome, so reviews, proof runs, repros and abandoned attempts left about 220 GB of scratch on bestia and idle node_modules on all three machines.
So what: Independent review runs on the exact head; then the user decides the merge.

Closes #267

Change

  • global/AGENTS.md Handoff: one paragraph. Covers every outcome (merged, review, research, proof run, experiment, failed or abandoned); keep evidence in the Issue, PR or durable record; disposable files go in the harness session scratchpad, otherwise one named task folder; anything kept is named in the handoff with reason and next owner; remove only what you created, and the finalization module's exceptions for dirty, shared, user-owned, active and ambiguous resources still apply.
  • tests/test_operations_contract.py: test_every_handoff_removes_the_agents_own_scratch asserts each clause inside the Handoff section (red before the edit: 7 failures; green after).
  • Version 17.4.7 -> 17.4.8 (patch: tightens an existing rule) via versionctl prepare patch; CHANGELOG entry.

Placement: the core is the only always-loaded owner. finalization.md loads only at a terminal disposition and orchestration.md only when delegating, so a read-only reviewer or abandoned attempt never reached either. The new text points at finalization for safety exceptions instead of duplicating them.

Elon record

  • Requirements and who asked: Luke, 2026-11-13: agents clean up their own scratch and dependency installs for every outcome, using the harness scratchpad; keeps named with reason and owner; existing safety rules unchanged.
  • Deleted: A new procedure, a duplicate rule in orchestration.md, and machine automation (the runbook idle-cleanup job owns that).
  • Bottleneck: Non-delivery work never loads finalization.md, so the obligation must live in the always-loaded core.
  • Checked myself: Read the Handoff section, orchestration.md, finalization.md and implementation.md in full; ran the new test red then green; versionctl release-check on 24300c7: release candidate OK: v17.4.8.

Proof

  • python3 -m unittest tests.test_operations_contract: 22 tests OK.
  • Full suite: result posted as a PR comment.
  • Website impact: none (instruction text only; no public page describes this rule).

🤖 Generated with Claude Code

Only Delivery Finalization required cleanup, after a terminal outcome, so
reviews, proof runs, experiments and abandoned attempts left their scratch
and node_modules behind. The core Handoff section now requires every agent
to remove what it created, use the harness session scratchpad, and name
anything it keeps.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@lukemaj

lukemaj commented Nov 13, 2026

Copy link
Copy Markdown
Contributor Author

What: PASS: independent review found no actionable findings at exact head 24300c741e9eb3ce02258fa3a1d3117b791646f7.
Why: The Handoff rule satisfies all four acceptance criteria in #267 while preserving ownership and cleanup safety boundaries.
So what: Review is complete; the user retains the final merge decision.

Reviewed the complete diff against base bdc91d138162b53d75f2c88caff9be14baa8ce96, Issue #267 including non-goals, and the surrounding core and operations references using the code-review procedure and verification reference.

Acceptance and cleared concerns, all locations at the reviewed head:

  • AC1: global/AGENTS.md:352-356 requires removal of task-created temporary files, scratch folders, snapshots and dependency installs before final handoff for every outcome, including failed or abandoned work, and preserves evidence in a durable record.
  • AC2: global/AGENTS.md:356-357 requires harness session scratchpad use when available, otherwise one clearly named task folder, covered by the removal obligation.
  • AC3: global/AGENTS.md:358 requires retained items to be named with their reason and next owner, covering later steps, stacks and user needs.
  • AC4: global/AGENTS.md:358-360 explicitly says “Remove only what you created” and preserves dirty, shared, user-owned, active and ambiguous resource exceptions. It does not authorize deleting another agent's or the user's resources.
  • Correct owner: the always-loaded core reaches read-only and unsuccessful work without requiring terminal delivery finalization. It preserves terminal branch/worktree retirement in skills/operations/references/finalization.md:4-17, eligibility and exceptions at :28-61, durable handoff ownership in orchestration.md:100-105, and workspace continuation in implementation.md:3-9. Scratch cleanup does not authorize premature workspace retirement. No new procedure, Reconciliation change or machine automation was introduced.
  • tests/test_operations_contract.py:185-199 is a meaningful deterministic instruction-contract regression: it checks the actual Handoff section, normalizes whitespace, and guards the cleanup timing, categories, durable evidence, scratch location, retention report, ownership restriction and finalization reference. It does not claim behavioral compliance by a model.
  • VERSION:1, all five mirrors declared in .version-policy.json, and CHANGELOG.md:6-10 consistently advance 17.4.7 to 17.4.8. Patch classification, date 2026-11-13 and Issue reference are appropriate.

Verification performed by this review:

  • PYTHONDONTWRITEBYTECODE=1 python3 -m unittest tests.test_operations_contract: 22 tests passed on the exact head.
  • In-memory execution of the new test with words() supplied the base commit's Handoff text: seven assertion failures, zero errors. No baseline files or checkout changes were required.
  • git status --short remained empty. No scratch was retained and no checkout was changed.

Limits: this review ran the scoped operations contract suite, not the full repository suite or release-check. Behavioral Live Verification remains pending normal user work, per repository policy. A separately delegated read-only reviewer also returned PASS with no actionable findings after checking the same candidate and acceptance criteria.

@lukemaj

lukemaj commented Nov 13, 2026

Copy link
Copy Markdown
Contributor Author

Full local suite on 24300c7: python3 -m unittest discover -s tests -p 'test_*.py' -> Ran 513 tests, OK. CI validate success; review/independent success on 24300c7.

@lukemaj
lukemaj merged commit 60c1252 into main Nov 13, 2026
2 checks passed
@lukemaj
lukemaj deleted the task/handoff-scratch-cleanup branch November 13, 2026 20:25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Agents remove their own scratch and dependency installs at every handoff

1 participant