From ed9309de88df099b9ad556c55a1d34e9017f5c46 Mon Sep 17 00:00:00 2001 From: Sree Raman <1271305+sreejithraman@users.noreply.github.com> Date: Mon, 9 Nov 2026 14:19:48 -0500 Subject: [PATCH 01/10] Drive scripted verify browser checks with Playwright's bundled Chromium Co-Authored-By: Claude Opus 5.5 --- SOURCES.md | 4 +++- skills/verify/references/web.md | 25 ++++++++++++++++++++----- 2 files changed, 23 insertions(+), 6 deletions(-) diff --git a/SOURCES.md b/SOURCES.md index c61f2f1..c6f07c1 100644 --- a/SOURCES.md +++ b/SOURCES.md @@ -729,7 +729,9 @@ explicit. Concurrent and long checks plan resource ownership; authorized harness isolation changes prove concurrent isolation and independent cleanup. Imported interface criteria retain full requested audit coverage. Web and iOS -checks follow the requested deployment or Simulator/device target. The iOS +checks follow the requested deployment or Simulator/device target. Scripted web +checks launch Playwright's bundled Chromium unless they need the shipping browser, +and close it in the script. The iOS reference reuses project harnesses and prefers XCTest with XCUIAutomation for new iOS UI workflow tests, Swift Testing for new Swift unit tests, and XCTest for performance tests. Suite execution preserves target identity, required-check diff --git a/skills/verify/references/web.md b/skills/verify/references/web.md index 9e36fab..38cc6b7 100644 --- a/skills/verify/references/web.md +++ b/skills/verify/references/web.md @@ -3,8 +3,8 @@ Use the requested deployment and the browser environment already attached to the task when possible. For a local change, start or locate the development server; for a live site, open its URL. -Reach the exact route or state under test. Record the URL, viewport/device mode, -and relevant console or network evidence. +Reach the exact route or state under test. Record the URL, browser and version, +viewport/device mode, and relevant console or network evidence. In T3 Code, follow the injected collaborative-browser instructions for tool selection and recovery. Start with `preview_status`, then `preview_open` when @@ -15,6 +15,21 @@ resolve the actual URL and port from the running process or app environment. The [T3 runtime instructions](https://github.com/pingdotgg/t3code/blob/c71ca063dfcd8c2e3dcb2bd92adbb2180cbbece3/apps/server/src/provider/T3OrchestrationInstructions.ts) and live tools supply the current interaction contract. +## Scripted browser checks + +Extend the project's Playwright Test setup for a repeatable check; its fixtures +close the browser. Use the Playwright library for a one-off proof script. See +[Playwright library](https://playwright.dev/docs/library). + +- Launch Playwright's bundled Chromium, with no `channel` or `executablePath`. + Install it with `npx playwright install chromium`. Use a branded channel such as + `channel: 'chrome'` only when the check needs the shipping browser, such as for + release parity or a Chrome-only feature. Its headless mode differs, so record the + channel with the browser version. See [Playwright browsers](https://playwright.dev/docs/browsers). +- Close the context and browser in a `finally` block. Bound the run with + Playwright's timeouts so it exits through that block. A killed branded Chrome + leaves a copy of its app on disk. + ## Observe and interact - Capture a browser snapshot or inspect the DOM and accessibility tree before @@ -49,9 +64,9 @@ applicable contracts into assertions: - Check supported appearance changes and browser-chrome hints in the actual target mode. Inspect focus zoom and keyboard/input hints on relevant fields. -Record browser/version, device or simulator, orientation, display mode, and input -method. Emulation can establish layout and some input behavior but does not -establish every hardware/browser assertion. Use target hardware when available +Also record the device or simulator, orientation, display mode, and input method. +Emulation can establish layout and some input behavior but does not establish +every hardware/browser assertion. Use target hardware when available for keyboard, chrome, safe areas, gestures, and touch feel; mark unavailable checks `blocked` or `untested` rather than calling them passed. See [Chrome's Device Mode limitations](https://developer.chrome.com/docs/devtools/device-mode#limitations). From 1e7ba836506d360894496a6972c1c50fea24371e Mon Sep 17 00:00:00 2001 From: Sree Raman <1271305+sreejithraman@users.noreply.github.com> Date: Mon, 9 Nov 2026 14:30:28 -0500 Subject: [PATCH 02/10] Keep verify proof small and delete run scratch Verify splits a run's files into run scratch, deleted when the run ends, and small kept proof that Repo Cleanup removes once the work lands. Simulator Lifecycle checks free space and load before device work. Co-Authored-By: Claude Opus 5.5 --- SOURCES.md | 18 ++++--- skills/implement/SKILL.md | 8 +-- skills/repo-cleanup/SKILL.md | 5 +- skills/simulator-lifecycle/SKILL.md | 8 +++ .../references/project-runners.md | 16 +++--- skills/verify/SKILL.md | 54 +++++++++++++------ skills/verify/references/ios.md | 10 ++-- 7 files changed, 81 insertions(+), 38 deletions(-) diff --git a/SOURCES.md b/SOURCES.md index c6f07c1..2924365 100644 --- a/SOURCES.md +++ b/SOURCES.md @@ -712,7 +712,8 @@ One automatically discoverable skill owns real-workflow selection, launch, drivi acceptance judgments, evidence, and cleanup. It writes no docs in any repo, except formal check records under the formal reference's conditions: it uses a temporary plan without a map, reads a map when one exists, and reports drift. Adds a read-only doctor before driving, red-first reproduction against the base -revision, rerunnable scripts, and refusal of an assertion with no independent +revision, run-scratch scripts with an offer to turn repeat checks into a test or +recipe, and refusal of an assertion with no independent expectation or way to run it. Formal checks use one conditional reference, also reached when a change touches an existing check. It retains tool selection, code/model correspondence, bounds, negative controls, counterexample replay, @@ -741,8 +742,10 @@ automated and needs assertion coverage beyond a successful command. Targeted suites preserve required integration gates, reconcile every selected test and attempt, and require matching runtime evidence for pre-existing failure claims. Terminal and service checks use process or PTY driving, bounded completion, public -protocols, and fresh persisted-output reads. Keeps bounded reproduction attempts, -failed-attempt evidence, authorization, isolation, redaction, run-owned cleanup, +protocols, and fresh persisted-output reads. Separates deleted run scratch from +small kept proof that lasts until the work lands or is abandoned; builds stay in +the build system and are named by SHA plus hash. Keeps bounded reproduction attempts, +outcome counts, authorization, isolation, redaction, run-owned cleanup, and separate defect-reproduction reporting. Authenticated workflows reuse designated test accounts and standing scope, delegate application sign-in and command/API credential use to `agent-login`, @@ -766,8 +769,9 @@ evidence limits. Greetings and attribution instructions are omitted. Accepts merge completion handoffs from `merge`. Cleanup includes verified task-owned development processes, simulator/emulator installs, disposable test -data, and temporary devices created solely for the task. Reused devices are -preserved and shut down only when the task booted them and no consumer remains. +data, Verify's kept proof, and temporary devices created solely for the task. +Reused devices are preserved and shut down only when the task booted them and no +consumer remains. Cleanup reconstructs process, device, and install ownership from available session history and tool results, with logs, current state, and optional handoffs as supporting evidence. Discovery and cleanup rules live together in @@ -1176,7 +1180,9 @@ than test phones. Adds host-routing, retained-target and shared-requester owners gates plus fresh lease-identity requirements, and links local run/handoff, runner-integration and adoption references, including bounded iOS agent-device helper preparation, bounded failure diagnostics and bridge capability -checks. Failure guidance defers to host recovery instructions and preserves unresolved +checks. Checks free disk space and load before device work and holds or reports +when either is critical. Project runners reuse the worktree's DerivedData. +Failure guidance defers to host recovery instructions and preserves unresolved ownership conflicts. Owns T3 Device panel routing, returned driver and session flags, and Xcode and platform tool routes for reaching a device. Adds a last-resort, coordinated CoreSimulator restart for repeated iOS boot failures before a grant, guarded by a local script. Runtime lease rules stay with `simlock instructions`. Technical citations use checked upstream source diff --git a/skills/implement/SKILL.md b/skills/implement/SKILL.md index dc5d46c..8b20a1b 100644 --- a/skills/implement/SKILL.md +++ b/skills/implement/SKILL.md @@ -88,10 +88,10 @@ through Merge. Name the branch or assumption provisional work rests on. It can build and prove, and is reviewed only when the caller asks for review or a PR. Provisional work never merges and never crosses into destructive or outward-facing actions on your own initiative. The user's explicit scrap of this -outcome allows only its scoped cleanup through Repo Cleanup: its branch, PR, and -worktree; work built on it still gets its own choice. Land becomes Try, but a -requested PR state, draft or review-ready, can still be reached. Publish a -provisional PR with the **Provisional** section from PR's +outcome allows only its scoped cleanup through Repo Cleanup: its branch, PR, +worktree, and kept verification proof; work built on it still gets its own +choice. Land becomes Try, but a requested PR state, draft or review-ready, can +still be reached. Publish a provisional PR with the **Provisional** section from PR's [body guide](../pr/references/pr-body.md); that section is where its status lives, and you remove it only after its condition is met and affected proof is refreshed. If its base changes, restack and recheck it. If its base is scrapped, diff --git a/skills/repo-cleanup/SKILL.md b/skills/repo-cleanup/SKILL.md index bc3f3a7..7caa287 100644 --- a/skills/repo-cleanup/SKILL.md +++ b/skills/repo-cleanup/SKILL.md @@ -10,7 +10,8 @@ Clean up only resources whose owner and disposal reason are established. A merge 1. **Inventory.** Resolve the repository, worktrees, default and task branches, relevant pull requests, and candidate resources. Include review surfaces, development apps and their servers/watchers, simulator/emulator devices and - installs, slot claims, runtime files, build folders, and local or remote refs + installs, slot claims, runtime files, build folders, Verify's + [kept proof](../verify/SKILL.md#keep-proof-not-runs), and local or remote refs as applicable. Follow [development resource discovery](references/development-resources.md#identify-resources) for apps, processes, simulator/emulator devices, and installs. Refresh remote refs before judging branch tips. @@ -92,4 +93,4 @@ Clean up only resources whose owner and disposal reason are established. A merge and recovery details such as recorded branch heads or reflogs. State partial cleanup plainly. -An explicit cleanup request or a handoff from [merge](../merge/SKILL.md) after an authorized merge covers disposal of verified task-owned temporary resources, including development processes, simulator/emulator installs, disposable test data, and temporary devices created for the task, in that scope. It does not authorize unrelated or uncertain targets. +An explicit cleanup request or a handoff from [merge](../merge/SKILL.md) after an authorized merge covers disposal of verified task-owned temporary resources, including development processes, simulator/emulator installs, disposable test data, kept verification proof, and temporary devices created for the task, in that scope. It does not authorize unrelated or uncertain targets. diff --git a/skills/simulator-lifecycle/SKILL.md b/skills/simulator-lifecycle/SKILL.md index b5e17ef..1122beb 100644 --- a/skills/simulator-lifecycle/SKILL.md +++ b/skills/simulator-lifecycle/SKILL.md @@ -19,6 +19,14 @@ Apply the [run ownership guard](references/workflow.md#choose-the-route-before-a before following reuse, release or cancellation advice: a shared requester may belong to a sibling run. +Check the machine before you acquire or boot any device, or start a device build or +test run. Read free space with `df -h ~` and the 1-minute load average with `uptime`, +and compare the load with the CPU count (`sysctl -n hw.logicalcpu` or `nproc`). Less +than 10% free space, or a load above twice the CPU count, is critical. Then hold the +device work, continue independent work, and recheck when that runs out. If it is +still critical, report both numbers as the blocker. Free space only through +[Repo Cleanup](../repo-cleanup/SKILL.md)'s ownership checks. + In T3, acquisition and interactive control must follow its documented route to the same SimLock lease; an ordinary panel session is not proof of that lease. Before acquiring, read [run and handoff conventions](references/workflow.md) for diff --git a/skills/simulator-lifecycle/references/project-runners.md b/skills/simulator-lifecycle/references/project-runners.md index f4d1515..e1a5987 100644 --- a/skills/simulator-lifecycle/references/project-runners.md +++ b/skills/simulator-lifecycle/references/project-runners.md @@ -23,17 +23,19 @@ The runner must: occur. A one-shot detached lease needs a supported renewal owner; choosing a long TTL alone is insufficient. Observe lease loss and stop device-dependent work before any further command. -- Allocate a unique run directory for DerivedData, intermediate app builds, - temporary fixtures and logs. Put retained results outside the disposable - directory. Record created paths and process identities as they are created. +- Build into the worktree's normal DerivedData so later runs reuse it, and + serialize builds that share it. Allocate a unique run directory for temporary + fixtures and logs, and put Verify's + [kept proof](../../verify/SKILL.md#keep-proof-not-runs) outside it. Record + created paths and process identities as they are created. - Capture PIDs at spawn and use existing ownership-checked stop tooling. Recheck start identity, executable/workspace and other consumers immediately before stopping. Await all run-owned writers, including test helpers and descendants; a root process exiting is insufficient if it left children running. -- Export required screenshots, logs and result bundles before releasing. Keep - failure evidence. Release through the same interface in teardown even when - acquisition only partly succeeded; reconcile an uncertain grant by request/run - identity before requesting another device. +- Export the device's screenshots and logs that kept proof needs before + releasing, because SimLock wipes the device. Release through the same + interface in teardown even when acquisition only partly succeeded; reconcile + an uncertain grant by request/run identity before requesting another device. - Bound queued acquisition and use supported cancellation only for a request proven to belong to this run. Killing a waiting CLI process does not necessarily cancel its queued request. Reconcile whether it was cancelled or granted, and release an eventual diff --git a/skills/verify/SKILL.md b/skills/verify/SKILL.md index 399346b..248a799 100644 --- a/skills/verify/SKILL.md +++ b/skills/verify/SKILL.md @@ -19,9 +19,32 @@ It owns its prerequisites, verdicts, and repo writes. The steps below apply to p claims. A model doesn't replace them, and ordinary workflows need no new model. Look for existing formal checks by function, not by name. -Keep plans, scripts, and evidence in the session scratch directory. Verify writes no -docs in any repo, including a repo's verification map. If the user asks to create or -change a map, follow [verification maps](../setup-sreestack/references/verification-map.md). +Verify writes no docs in any repo, including a repo's verification map. If the user +asks to create or change a map, follow [verification maps](../setup-sreestack/references/verification-map.md). + +## Keep proof, not runs + +A run leaves two kinds of files. Keep them in separate places from the start. + +**Run scratch** is anything you could produce again: plans, helper and rerun scripts, +per-step snapshots, result bundles, and intermediate reruns. Put it in a temporary +directory of its own outside the repo, and delete that directory when the run ends, +pass or fail. Leave builds and DerivedData where the build system puts them, so later +runs reuse them. Name a build by commit SHA plus artifact hash instead of copying the +build or its inputs, such as source trees and Pods. + +**Kept proof** is what a reader needs to trust the verdicts: + +- the verdict table; +- the captures behind each verdict: screenshots, recordings, transcripts, or responses; +- the log excerpts a verdict or finding cites; +- build identity: commit SHA plus artifact hash. + +For repeated attempts, keep the outcome counts, plus captures only for failures behind +a finding that is still open. Put kept proof in the host's session scratch directory, +or in a task folder under the OS temp directory when the host has none, and give its +absolute path in your report. Owner reports and chiefs read it until the work lands +or is abandoned. [Repo Cleanup](../repo-cleanup/SKILL.md) removes it then. ## Choose what to prove @@ -92,8 +115,9 @@ options in the repo and the environment. Follow who drives an interface and with which model. The driver reports what it saw, and you keep the verdicts. -Prefer a script you can rerun over steps by hand. Put repeatable setup, driving, and -evidence capture in it, and give the rerun command in your report. +Prefer a script in run scratch over steps by hand. Put repeatable setup, driving, and +capture in it. When the same check runs again on a later commit, offer to turn it into +a committed test or a verification-map recipe. **Run a read-only doctor before you drive.** Run the map's doctor if it has one, then check whatever it doesn't cover, without changing state: @@ -158,14 +182,15 @@ target exists, and take them from current state. dependencies. Before running them, connect each assertion to a real check, and confirm the target, fixtures, filters, optional checks, and retries. Afterward, reconcile every selected test with its result: actual skips, unmet preconditions, and unfinished tests. -Count a duplicate test once for coverage and keep every attempt's outcome. Exercise +Count a duplicate test once for coverage and record every attempt's outcome. Exercise uncovered assertions yourself. A green command, zero tests, partial results, or a passing rerun can't establish a pass. Keep required broader gates, and report any you didn't run. **When something doesn't change:** Record it before you retry. Retry once, only when -evidence shows the target moved or the interface hadn't settled, and record the retry as -its own attempt. A repeated failure is evidence. After a stuck interface or a surprising -result, check instance health and restore known state, even if the process looks fine. +evidence shows the target moved or the interface hadn't settled, and record the retry's +outcome as its own attempt. A repeated failure is evidence. After a stuck interface or a +surprising result, check instance health and restore known state, even if the process +looks fine. **Intermittent reports:** Choose the attempt count before you start, and use it on both sides. Use about 3 divided by the failure rate, so about 30 attempts for 1 in 10. Restore @@ -201,15 +226,14 @@ or another revision's results don't show that. State the limits of the compariso ## Clean up and report -Keep failed attempts and the screenshots, snapshots, logs, transcripts, or responses -behind each verdict. Visual claims need visual captures. +Visual claims need visual captures in the [kept proof](#keep-proof-not-runs). -Stop only the processes and sessions this run started, and remove their disposable data, -after success or failure. Leave reused services and source fixtures running. Then open -the kept evidence to confirm it survived. +After success or failure, stop only the processes and sessions this run started, remove +their disposable data, and delete the run scratch. Leave reused services and source +fixtures running. Then open the kept proof to confirm it survived. Give each workflow and entry point its actions, expected and observed results, and -evidence location. Give every assertion one verdict: +the kept proof's path. Give every assertion one verdict: - `passed`: the observed result matched. - `failed`: the observed result differed. diff --git a/skills/verify/references/ios.md b/skills/verify/references/ios.md index 21e36b1..87c76d5 100644 --- a/skills/verify/references/ios.md +++ b/skills/verify/references/ios.md @@ -51,8 +51,9 @@ delivery path from [authenticated verification](authenticated-verification.md). Map selected test methods to required workflow assertions. Inspect test-plan configurations, selection filters, disabled tests, skips, expected failures, and retries. Reconcile the tests actually executed with the selected assertions under -Verify's main procedure. Retain the runner's exit status and result bundle, -including screenshots, attachments, logs, and every attempt needed for the verdict. +Verify's main procedure. Record the runner's exit status. Export the screenshots, +attachments, and log excerpts a verdict cites from the result bundle into +[kept proof](../SKILL.md#keep-proof-not-runs); the bundle itself is run scratch. Pair public UI actions with explicit outcome assertions. Prefer accessibility identifiers and meaningful labels. Wait for observable states with bounded @@ -103,8 +104,9 @@ hardware is unavailable, report the device-specific assertions as blocked. ## Evidence -Record the command and toolchain, scheme/test plan, build and target identity, -fixture state, selected tests, per-assertion outcomes, and artifact locations. +Record the command and toolchain, scheme/test plan, build identity as commit SHA +plus app hash, target identity, fixture state, selected tests, and per-assertion +outcomes in [kept proof](../SKILL.md#keep-proof-not-runs). Capture the workflow states needed to support visual claims. Use [interface review](interface-review.md) for relevant visual, Dynamic Type, keyboard, focus, touch-target, and assistive-technology checks. Exercise VoiceOver From 8fe6922c0a97c2e3f6dd1883c55b68f352a573df Mon Sep 17 00:00:00 2001 From: Sree Raman <1271305+sreejithraman@users.noreply.github.com> Date: Mon, 9 Nov 2026 14:59:12 -0500 Subject: [PATCH 03/10] Keep verify proof in task state and lock shared builds through their last reader Co-Authored-By: Claude Opus 5.5 --- SOURCES.md | 8 +++++--- skills/implement/SKILL.md | 4 ++-- skills/repo-cleanup/SKILL.md | 8 +++++--- .../references/project-runners.md | 18 +++++++++++------- skills/verify/SKILL.md | 18 +++++++++--------- skills/verify/references/ios.md | 6 +++--- skills/verify/references/web.md | 5 +++-- 7 files changed, 38 insertions(+), 29 deletions(-) diff --git a/SOURCES.md b/SOURCES.md index 2924365..8bfab40 100644 --- a/SOURCES.md +++ b/SOURCES.md @@ -743,8 +743,9 @@ suites preserve required integration gates, reconcile every selected test and attempt, and require matching runtime evidence for pre-existing failure claims. Terminal and service checks use process or PTY driving, bounded completion, public protocols, and fresh persisted-output reads. Separates deleted run scratch from -small kept proof that lasts until the work lands or is abandoned; builds stay in -the build system and are named by SHA plus hash. Keeps bounded reproduction attempts, +small kept proof in a per-task folder under the XDG state directory that lasts +until the work lands or is abandoned; builds stay in the build system and are +named by SHA plus hash. Keeps bounded reproduction attempts, outcome counts, authorization, isolation, redaction, run-owned cleanup, and separate defect-reproduction reporting. Authenticated workflows reuse designated test accounts and standing scope, @@ -1181,7 +1182,8 @@ gates plus fresh lease-identity requirements, and links local run/handoff, runner-integration and adoption references, including bounded iOS agent-device helper preparation, bounded failure diagnostics and bridge capability checks. Checks free disk space and load before device work and holds or reports -when either is critical. Project runners reuse the worktree's DerivedData. +when either is critical. Project runners reuse the worktree's DerivedData and +hold one exclusion from build through the last install or test read of its products. Failure guidance defers to host recovery instructions and preserves unresolved ownership conflicts. Owns T3 Device panel routing, returned driver and session flags, and Xcode and platform tool routes for reaching a device. Adds a last-resort, coordinated CoreSimulator restart for repeated iOS boot failures before a grant, guarded by a local script. Runtime lease rules stay diff --git a/skills/implement/SKILL.md b/skills/implement/SKILL.md index 8b20a1b..f3e20dc 100644 --- a/skills/implement/SKILL.md +++ b/skills/implement/SKILL.md @@ -219,8 +219,8 @@ The owner report carries every field that applies: delivery state against it. - **Layers:** each PR, branch, or local artifact, with its link, head, base, revisions, and working-tree state. -- **Proof:** each required assertion's verdict and evidence, and what is blocked - or untested. +- **Proof:** each required assertion's verdict and evidence, the kept proof's + absolute path, and what is blocked or untested. - **Shown:** what you showed and how to open it, with what it needs, such as a login or a running server and its stop action. - **Waits:** pending PRs, live helpers and watchers, and the events they await. diff --git a/skills/repo-cleanup/SKILL.md b/skills/repo-cleanup/SKILL.md index 7caa287..794d782 100644 --- a/skills/repo-cleanup/SKILL.md +++ b/skills/repo-cleanup/SKILL.md @@ -10,9 +10,9 @@ Clean up only resources whose owner and disposal reason are established. A merge 1. **Inventory.** Resolve the repository, worktrees, default and task branches, relevant pull requests, and candidate resources. Include review surfaces, development apps and their servers/watchers, simulator/emulator devices and - installs, slot claims, runtime files, build folders, Verify's - [kept proof](../verify/SKILL.md#keep-proof-not-runs), and local or remote refs - as applicable. Follow [development resource discovery](references/development-resources.md#identify-resources) + installs, slot claims, runtime files, build folders, the task's folder under + Verify's [kept-proof root](../verify/SKILL.md#keep-proof-not-runs), and local + or remote refs as applicable. Follow [development resource discovery](references/development-resources.md#identify-resources) for apps, processes, simulator/emulator devices, and installs. Refresh remote refs before judging branch tips. Prefer project cleanup commands over hand-written deletion. For each candidate, @@ -44,6 +44,8 @@ Clean up only resources whose owner and disposal reason are established. A merge and simulator/emulator installs and devices, follow [development resource cleanup](references/development-resources.md#clean-up). Measure and remove exact task-owned build folders, keeping retained app data. + Remove only the finished or abandoned task's own kept-proof folder, and leave + the root and other tasks' folders. Remove a shared build cache only after approval, when no build is active and no other worktree can use it. diff --git a/skills/simulator-lifecycle/references/project-runners.md b/skills/simulator-lifecycle/references/project-runners.md index e1a5987..e2e761b 100644 --- a/skills/simulator-lifecycle/references/project-runners.md +++ b/skills/simulator-lifecycle/references/project-runners.md @@ -23,18 +23,22 @@ The runner must: occur. A one-shot detached lease needs a supported renewal owner; choosing a long TTL alone is insufficient. Observe lease loss and stop device-dependent work before any further command. -- Build into the worktree's normal DerivedData so later runs reuse it, and - serialize builds that share it. Allocate a unique run directory for temporary - fixtures and logs, and put Verify's - [kept proof](../../verify/SKILL.md#keep-proof-not-runs) outside it. Record - created paths and process identities as they are created. +- Allocate a unique run directory for temporary fixtures and logs, and put + Verify's [kept proof](../../verify/SKILL.md#keep-proof-not-runs) outside it. + Record created paths and process identities as they are created. +- Build into the worktree's normal DerivedData so later runs reuse it. Hold one + exclusion from the build through the last install or test read of its + products, including `test-without-building`. A run that can't wait builds + into its own product root inside its run directory, through the project's + supported option such as `-derivedDataPath`, and deletes that root with the + run directory. - Capture PIDs at spawn and use existing ownership-checked stop tooling. Recheck start identity, executable/workspace and other consumers immediately before stopping. Await all run-owned writers, including test helpers and descendants; a root process exiting is insufficient if it left children running. - Export the device's screenshots and logs that kept proof needs before - releasing, because SimLock wipes the device. Release through the same - interface in teardown even when acquisition only partly succeeded; reconcile + releasing. Release through the same interface in teardown even when + acquisition only partly succeeded; reconcile an uncertain grant by request/run identity before requesting another device. - Bound queued acquisition and use supported cancellation only for a request proven to belong to this run. Killing a waiting CLI process does not necessarily diff --git a/skills/verify/SKILL.md b/skills/verify/SKILL.md index 248a799..65e659b 100644 --- a/skills/verify/SKILL.md +++ b/skills/verify/SKILL.md @@ -30,21 +30,23 @@ A run leaves two kinds of files. Keep them in separate places from the start. per-step snapshots, result bundles, and intermediate reruns. Put it in a temporary directory of its own outside the repo, and delete that directory when the run ends, pass or fail. Leave builds and DerivedData where the build system puts them, so later -runs reuse them. Name a build by commit SHA plus artifact hash instead of copying the -build or its inputs, such as source trees and Pods. +runs reuse them. Record a build by its build identity instead of copying it or its +inputs, such as source trees and Pods. **Kept proof** is what a reader needs to trust the verdicts: - the verdict table; -- the captures behind each verdict: screenshots, recordings, transcripts, or responses; +- the captures behind each verdict, visual for a visual claim: screenshots, + recordings, transcripts, or responses; - the log excerpts a verdict or finding cites; - build identity: commit SHA plus artifact hash. For repeated attempts, keep the outcome counts, plus captures only for failures behind -a finding that is still open. Put kept proof in the host's session scratch directory, -or in a task folder under the OS temp directory when the host has none, and give its -absolute path in your report. Owner reports and chiefs read it until the work lands -or is abandoned. [Repo Cleanup](../repo-cleanup/SKILL.md) removes it then. +a finding that is still open. Put kept proof in +`${XDG_STATE_HOME:-~/.local/state}/verify-proof///`, where `` is the +branch name or another task slug, and give its absolute path in your report. It lasts +until the work lands or is abandoned; then [Repo Cleanup](../repo-cleanup/SKILL.md) +removes that task's folder. ## Choose what to prove @@ -226,8 +228,6 @@ or another revision's results don't show that. State the limits of the compariso ## Clean up and report -Visual claims need visual captures in the [kept proof](#keep-proof-not-runs). - After success or failure, stop only the processes and sessions this run started, remove their disposable data, and delete the run scratch. Leave reused services and source fixtures running. Then open the kept proof to confirm it survived. diff --git a/skills/verify/references/ios.md b/skills/verify/references/ios.md index 87c76d5..7db9315 100644 --- a/skills/verify/references/ios.md +++ b/skills/verify/references/ios.md @@ -104,9 +104,9 @@ hardware is unavailable, report the device-specific assertions as blocked. ## Evidence -Record the command and toolchain, scheme/test plan, build identity as commit SHA -plus app hash, target identity, fixture state, selected tests, and per-assertion -outcomes in [kept proof](../SKILL.md#keep-proof-not-runs). +Record the command and toolchain, scheme/test plan, build identity, target +identity, fixture state, selected tests, and per-assertion outcomes in +[kept proof](../SKILL.md#keep-proof-not-runs). Capture the workflow states needed to support visual claims. Use [interface review](interface-review.md) for relevant visual, Dynamic Type, keyboard, focus, touch-target, and assistive-technology checks. Exercise VoiceOver diff --git a/skills/verify/references/web.md b/skills/verify/references/web.md index 38cc6b7..b5e1bcb 100644 --- a/skills/verify/references/web.md +++ b/skills/verify/references/web.md @@ -17,8 +17,9 @@ and live tools supply the current interaction contract. ## Scripted browser checks -Extend the project's Playwright Test setup for a repeatable check; its fixtures -close the browser. Use the Playwright library for a one-off proof script. See +Use the project's Playwright Test check when it already has one for this +behavior; its fixtures close the browser. Otherwise write a script with the +Playwright library in [run scratch](../SKILL.md#keep-proof-not-runs). See [Playwright library](https://playwright.dev/docs/library). - Launch Playwright's bundled Chromium, with no `channel` or `executablePath`. From 75e0d1d2ce767055047eaaadb3f80d3f095765a1 Mon Sep 17 00:00:00 2001 From: Sree Raman <1271305+sreejithraman@users.noreply.github.com> Date: Mon, 9 Nov 2026 15:15:45 -0500 Subject: [PATCH 04/10] Send disposable Xcode output to run scratch and name proof folders deterministically Co-Authored-By: Claude Opus 5.5 --- SOURCES.md | 17 +++++---- skills/repo-cleanup/SKILL.md | 13 +++++-- skills/simulator-lifecycle/SKILL.md | 13 +++---- .../references/project-runners.md | 8 ++--- skills/verify/SKILL.md | 35 +++++++++++++------ skills/verify/references/ios.md | 15 +++++++- 6 files changed, 68 insertions(+), 33 deletions(-) diff --git a/SOURCES.md b/SOURCES.md index 8bfab40..6504b1e 100644 --- a/SOURCES.md +++ b/SOURCES.md @@ -743,9 +743,11 @@ suites preserve required integration gates, reconcile every selected test and attempt, and require matching runtime evidence for pre-existing failure claims. Terminal and service checks use process or PTY driving, bounded completion, public protocols, and fresh persisted-output reads. Separates deleted run scratch from -small kept proof in a per-task folder under the XDG state directory that lasts -until the work lands or is abandoned; builds stay in the build system and are -named by SHA plus hash. Keeps bounded reproduction attempts, +small kept proof in per-run folders under a per-task folder in the XDG state +directory that lasts until the work lands or is abandoned; proof from runs tied +to no task stays in session scratch. Only a worktree's own builds stay in the +build system and are named by SHA plus hash; the iOS reference sends overlapping +runs, disposable-checkout builds and result bundles into run scratch. Keeps bounded reproduction attempts, outcome counts, authorization, isolation, redaction, run-owned cleanup, and separate defect-reproduction reporting. Authenticated workflows reuse designated test accounts and standing scope, @@ -770,7 +772,8 @@ evidence limits. Greetings and attribution instructions are omitted. Accepts merge completion handoffs from `merge`. Cleanup includes verified task-owned development processes, simulator/emulator installs, disposable test -data, Verify's kept proof, and temporary devices created solely for the task. +data, Verify's kept proof, the Xcode DerivedData of removed worktrees, and +temporary devices created solely for the task. Reused devices are preserved and shut down only when the task booted them and no consumer remains. Cleanup reconstructs process, device, and install ownership from available @@ -1181,9 +1184,9 @@ than test phones. Adds host-routing, retained-target and shared-requester owners gates plus fresh lease-identity requirements, and links local run/handoff, runner-integration and adoption references, including bounded iOS agent-device helper preparation, bounded failure diagnostics and bridge capability -checks. Checks free disk space and load before device work and holds or reports -when either is critical. Project runners reuse the worktree's DerivedData and -hold one exclusion from build through the last install or test read of its products. +checks. Checks free disk space and load once before acquiring a device, on the +machine that runs it, and holds or reports when either is critical. Project +runners follow Verify's iOS build output rules. Failure guidance defers to host recovery instructions and preserves unresolved ownership conflicts. Owns T3 Device panel routing, returned driver and session flags, and Xcode and platform tool routes for reaching a device. Adds a last-resort, coordinated CoreSimulator restart for repeated iOS boot failures before a grant, guarded by a local script. Runtime lease rules stay diff --git a/skills/repo-cleanup/SKILL.md b/skills/repo-cleanup/SKILL.md index 794d782..72463ce 100644 --- a/skills/repo-cleanup/SKILL.md +++ b/skills/repo-cleanup/SKILL.md @@ -10,9 +10,10 @@ Clean up only resources whose owner and disposal reason are established. A merge 1. **Inventory.** Resolve the repository, worktrees, default and task branches, relevant pull requests, and candidate resources. Include review surfaces, development apps and their servers/watchers, simulator/emulator devices and - installs, slot claims, runtime files, build folders, the task's folder under - Verify's [kept-proof root](../verify/SKILL.md#keep-proof-not-runs), and local - or remote refs as applicable. Follow [development resource discovery](references/development-resources.md#identify-resources) + installs, slot claims, runtime files, build folders, the task's kept-proof + folder, found from the repo and branch by Verify's + [naming](../verify/SKILL.md#keep-proof-not-runs), and local or remote refs as + applicable. Follow [development resource discovery](references/development-resources.md#identify-resources) for apps, processes, simulator/emulator devices, and installs. Refresh remote refs before judging branch tips. Prefer project cleanup commands over hand-written deletion. For each candidate, @@ -59,6 +60,12 @@ Clean up only resources whose owner and disposal reason are established. A merge task changes, with no retained ignored data. Leave the current worktree in place for Codex. + When you remove a worktree, also remove its Xcode DerivedData folders. These + are the folders in Xcode's DerivedData location, `~/Library/Developer/Xcode/DerivedData` + by default, whose `info.plist` has a `WorkspacePath` inside the removed + worktree: it starts with the worktree's absolute path plus `/`. Leave every + other DerivedData folder, including folders without that key. + Before deleting any branch, recheck its tip and worktree use. For merged work, the tip must still equal the source head verified at merge time or be reachable from the intended base. If neither can be proved, retain the branch. Retain diff --git a/skills/simulator-lifecycle/SKILL.md b/skills/simulator-lifecycle/SKILL.md index 1122beb..6de7794 100644 --- a/skills/simulator-lifecycle/SKILL.md +++ b/skills/simulator-lifecycle/SKILL.md @@ -19,12 +19,13 @@ Apply the [run ownership guard](references/workflow.md#choose-the-route-before-a before following reuse, release or cancellation advice: a shared requester may belong to a sibling run. -Check the machine before you acquire or boot any device, or start a device build or -test run. Read free space with `df -h ~` and the 1-minute load average with `uptime`, -and compare the load with the CPU count (`sysctl -n hw.logicalcpu` or `nproc`). Less -than 10% free space, or a load above twice the CPU count, is critical. Then hold the -device work, continue independent work, and recheck when that runs out. If it is -still critical, report both numbers as the blocker. Free space only through +Check the machine that runs the device once, before you acquire or boot it. For a +remote device host, run the check through that host's access. Read free space with +`df -h "$HOME"` and the 1-minute load average with `uptime`, and compare the load +with the CPU count (`sysctl -n hw.logicalcpu` or `nproc`). Less than 10% free space, +or a load above twice the CPU count, is critical. Then hold the device work, continue +independent work, and recheck when that runs out. If it is still critical, report +both numbers as the blocker. Free space only through [Repo Cleanup](../repo-cleanup/SKILL.md)'s ownership checks. In T3, acquisition and interactive control must follow its documented route to diff --git a/skills/simulator-lifecycle/references/project-runners.md b/skills/simulator-lifecycle/references/project-runners.md index e2e761b..f3af17e 100644 --- a/skills/simulator-lifecycle/references/project-runners.md +++ b/skills/simulator-lifecycle/references/project-runners.md @@ -26,12 +26,8 @@ The runner must: - Allocate a unique run directory for temporary fixtures and logs, and put Verify's [kept proof](../../verify/SKILL.md#keep-proof-not-runs) outside it. Record created paths and process identities as they are created. -- Build into the worktree's normal DerivedData so later runs reuse it. Hold one - exclusion from the build through the last install or test read of its - products, including `test-without-building`. A run that can't wait builds - into its own product root inside its run directory, through the project's - supported option such as `-derivedDataPath`, and deletes that root with the - run directory. +- Place Xcode DerivedData and result bundles by Verify's + [build output](../../verify/references/ios.md#build-output) rules. - Capture PIDs at spawn and use existing ownership-checked stop tooling. Recheck start identity, executable/workspace and other consumers immediately before stopping. Await all run-owned writers, including test helpers and descendants; diff --git a/skills/verify/SKILL.md b/skills/verify/SKILL.md index 65e659b..7d2e5fd 100644 --- a/skills/verify/SKILL.md +++ b/skills/verify/SKILL.md @@ -27,11 +27,12 @@ asks to create or change a map, follow [verification maps](../setup-sreestack/re A run leaves two kinds of files. Keep them in separate places from the start. **Run scratch** is anything you could produce again: plans, helper and rerun scripts, -per-step snapshots, result bundles, and intermediate reruns. Put it in a temporary -directory of its own outside the repo, and delete that directory when the run ends, -pass or fail. Leave builds and DerivedData where the build system puts them, so later -runs reuse them. Record a build by its build identity instead of copying it or its -inputs, such as source trees and Pods. +per-step snapshots, result bundles, intermediate reruns, and builds no later run +reuses. Put it in a temporary directory of its own outside the repo, and delete that +directory when the run ends, pass or fail. Only the worktree's own builds stay where +the build system puts them, for its later runs to reuse; [iOS build output](references/ios.md#build-output) +says where Xcode writes. Record a build by its build identity instead of copying it or +its inputs, such as source trees and Pods. **Kept proof** is what a reader needs to trust the verdicts: @@ -42,11 +43,25 @@ inputs, such as source trees and Pods. - build identity: commit SHA plus artifact hash. For repeated attempts, keep the outcome counts, plus captures only for failures behind -a finding that is still open. Put kept proof in -`${XDG_STATE_HOME:-~/.local/state}/verify-proof///`, where `` is the -branch name or another task slug, and give its absolute path in your report. It lasts -until the work lands or is abandoned; then [Repo Cleanup](../repo-cleanup/SKILL.md) -removes that task's folder. +a finding that is still open. + +Write each run's kept proof to +`${XDG_STATE_HOME:-$HOME/.local/state}/verify-proof////`: + +- `` is the repository's name from its origin remote, or else the main + checkout's folder name. It is never a worktree's folder name. +- `` is the branch name with each `/` replaced by `-`. +- `` is the short commit SHA and the time, such as `8fe6922-20261109T1412`. + +Give the run folder's absolute path in your report. Delete the earlier run folders +this run supersedes, except those holding captures for a finding that is still open. +The task folder lasts until the work lands or is abandoned; then +[Repo Cleanup](../repo-cleanup/SKILL.md) finds it from the repo and branch and +removes it. + +Proof from a run tied to no task branch or PR, such as a reproduction, an audit, or a +check of `main`, goes in the session scratch directory and lasts only as long as the +session. Say so in your report. ## Choose what to prove diff --git a/skills/verify/references/ios.md b/skills/verify/references/ios.md index 7db9315..b5ec5dc 100644 --- a/skills/verify/references/ios.md +++ b/skills/verify/references/ios.md @@ -33,6 +33,19 @@ change executable tests when the active task includes implementation, harness repair, or reusable verification setup. Keep test files, test plans, fixtures, and CI configuration in the product repo. +## Build output + +Xcode keys its default DerivedData folder by workspace path, so each worktree and +each disposable checkout gets its own folder, and that folder outlives the checkout. + +- A worktree's normal DerivedData belongs to its owner, who runs its builds one at + a time. +- A run that must overlap another in the same worktree, and every build of a + disposable checkout such as a red-first base, passes `-derivedDataPath` inside + its [run scratch](../SKILL.md#keep-proof-not-runs), so deleting the run scratch + deletes that build. +- Every test run passes `-resultBundlePath` inside its run scratch. + ## Prepare and run native UI tests Discover the project's UI test target, scheme, test plan, wrapper command, and @@ -53,7 +66,7 @@ configurations, selection filters, disabled tests, skips, expected failures, and retries. Reconcile the tests actually executed with the selected assertions under Verify's main procedure. Record the runner's exit status. Export the screenshots, attachments, and log excerpts a verdict cites from the result bundle into -[kept proof](../SKILL.md#keep-proof-not-runs); the bundle itself is run scratch. +[kept proof](../SKILL.md#keep-proof-not-runs). Pair public UI actions with explicit outcome assertions. Prefer accessibility identifiers and meaningful labels. Wait for observable states with bounded From 6474d9e47b4b8e4a92b27a15064958b5e76e5abb Mon Sep 17 00:00:00 2001 From: Sree Raman <1271305+sreejithraman@users.noreply.github.com> Date: Mon, 9 Nov 2026 15:32:02 -0500 Subject: [PATCH 05/10] Name proof folders losslessly and keep shared-checkout builds in run scratch Co-Authored-By: Claude Opus 5.5 --- SOURCES.md | 14 +++++---- skills/repo-cleanup/SKILL.md | 6 ++-- skills/simulator-lifecycle/SKILL.md | 17 ++++++----- skills/verify/SKILL.md | 47 ++++++++++++++++------------- skills/verify/references/ios.md | 14 +++++---- 5 files changed, 56 insertions(+), 42 deletions(-) diff --git a/SOURCES.md b/SOURCES.md index 6504b1e..833d91d 100644 --- a/SOURCES.md +++ b/SOURCES.md @@ -743,11 +743,13 @@ suites preserve required integration gates, reconcile every selected test and attempt, and require matching runtime evidence for pre-existing failure claims. Terminal and service checks use process or PTY driving, bounded completion, public protocols, and fresh persisted-output reads. Separates deleted run scratch from -small kept proof in per-run folders under a per-task folder in the XDG state -directory that lasts until the work lands or is abandoned; proof from runs tied -to no task stays in session scratch. Only a worktree's own builds stay in the -build system and are named by SHA plus hash; the iOS reference sends overlapping -runs, disposable-checkout builds and result bundles into run scratch. Keeps bounded reproduction attempts, +small kept proof in unique per-run folders under a per-task folder in the XDG +state directory, keyed by percent-encoded repo and branch names, that lasts until +the work lands or is abandoned; proof from runs tied to no task stays in session +scratch. Only a worktree's known sole builder keeps builds in the build system; +the iOS reference sends every other run's builds, disposable-checkout builds and +result bundles into run scratch. Build identity is the commit plus the hash of the +product actually installed or tested. Keeps bounded reproduction attempts, outcome counts, authorization, isolation, redaction, run-owned cleanup, and separate defect-reproduction reporting. Authenticated workflows reuse designated test accounts and standing scope, @@ -772,7 +774,7 @@ evidence limits. Greetings and attribution instructions are omitted. Accepts merge completion handoffs from `merge`. Cleanup includes verified task-owned development processes, simulator/emulator installs, disposable test -data, Verify's kept proof, the Xcode DerivedData of removed worktrees, and +data, Verify's kept proof, the Xcode DerivedData of removed or missing worktrees, and temporary devices created solely for the task. Reused devices are preserved and shut down only when the task booted them and no consumer remains. diff --git a/skills/repo-cleanup/SKILL.md b/skills/repo-cleanup/SKILL.md index 72463ce..2de2445 100644 --- a/skills/repo-cleanup/SKILL.md +++ b/skills/repo-cleanup/SKILL.md @@ -63,8 +63,10 @@ Clean up only resources whose owner and disposal reason are established. A merge When you remove a worktree, also remove its Xcode DerivedData folders. These are the folders in Xcode's DerivedData location, `~/Library/Developer/Xcode/DerivedData` by default, whose `info.plist` has a `WorkspacePath` inside the removed - worktree: it starts with the worktree's absolute path plus `/`. Leave every - other DerivedData folder, including folders without that key. + worktree: it starts with the worktree's absolute path plus `/`. During + housekeeping, also remove each DerivedData folder whose `WorkspacePath` no + longer exists on disk. It is a regenerable cache, whoever removed the worktree. + Leave every other DerivedData folder, including folders without that key. Before deleting any branch, recheck its tip and worktree use. For merged work, the tip must still equal the source head verified at merge time or be reachable diff --git a/skills/simulator-lifecycle/SKILL.md b/skills/simulator-lifecycle/SKILL.md index 6de7794..3cfda83 100644 --- a/skills/simulator-lifecycle/SKILL.md +++ b/skills/simulator-lifecycle/SKILL.md @@ -19,15 +19,18 @@ Apply the [run ownership guard](references/workflow.md#choose-the-route-before-a before following reuse, release or cancellation advice: a shared requester may belong to a sibling run. -Check the machine that runs the device once, before you acquire or boot it. For a -remote device host, run the check through that host's access. Read free space with -`df -h "$HOME"` and the 1-minute load average with `uptime`, and compare the load -with the CPU count (`sysctl -n hw.logicalcpu` or `nproc`). Less than 10% free space, -or a load above twice the CPU count, is critical. Then hold the device work, continue -independent work, and recheck when that runs out. If it is still critical, report -both numbers as the blocker. Free space only through +Check the machine that runs the device once, before you acquire or boot it. Read +free space with `df -h "$HOME"` and the 1-minute load average with `uptime`, and +compare the load with the CPU count (`sysctl -n hw.logicalcpu` or `nproc`). Less than +10% free space, or a load above twice the CPU count, is critical. Then hold the device +work, continue independent work, and recheck when that runs out. If it is still +critical, report both numbers as the blocker. Free space only through [Repo Cleanup](../repo-cleanup/SKILL.md)'s ownership checks. +On a remote device host, single-quote the commands so `$HOME` expands there, such as +`ssh 'df -h "$HOME"; uptime; sysctl -n hw.logicalcpu'`. If the host offers no +shell, report the check as not run and continue under the host's own controls. + In T3, acquisition and interactive control must follow its documented route to the same SimLock lease; an ordinary panel session is not proof of that lease. Before acquiring, read [run and handoff conventions](references/workflow.md) for diff --git a/skills/verify/SKILL.md b/skills/verify/SKILL.md index 7d2e5fd..b4cb65f 100644 --- a/skills/verify/SKILL.md +++ b/skills/verify/SKILL.md @@ -29,10 +29,11 @@ A run leaves two kinds of files. Keep them in separate places from the start. **Run scratch** is anything you could produce again: plans, helper and rerun scripts, per-step snapshots, result bundles, intermediate reruns, and builds no later run reuses. Put it in a temporary directory of its own outside the repo, and delete that -directory when the run ends, pass or fail. Only the worktree's own builds stay where -the build system puts them, for its later runs to reuse; [iOS build output](references/ios.md#build-output) -says where Xcode writes. Record a build by its build identity instead of copying it or -its inputs, such as source trees and Pods. +directory when the run ends, pass or fail. Only a worktree's sole builder leaves its +builds where the build system puts them, for its later runs to reuse; +[iOS build output](references/ios.md#build-output) says which runs that covers. Record +a build by its build identity instead of copying it or its inputs, such as source +trees and Pods. **Kept proof** is what a reader needs to trust the verdicts: @@ -40,28 +41,32 @@ its inputs, such as source trees and Pods. - the captures behind each verdict, visual for a visual claim: screenshots, recordings, transcripts, or responses; - the log excerpts a verdict or finding cites; -- build identity: commit SHA plus artifact hash. +- build identity: the commit SHA and the hash of the product actually installed or + tested, so a build crossed with another run's shows. For repeated attempts, keep the outcome counts, plus captures only for failures behind a finding that is still open. Write each run's kept proof to -`${XDG_STATE_HOME:-$HOME/.local/state}/verify-proof////`: - -- `` is the repository's name from its origin remote, or else the main - checkout's folder name. It is never a worktree's folder name. -- `` is the branch name with each `/` replaced by `-`. -- `` is the short commit SHA and the time, such as `8fe6922-20261109T1412`. - -Give the run folder's absolute path in your report. Delete the earlier run folders -this run supersedes, except those holding captures for a finding that is still open. -The task folder lasts until the work lands or is abandoned; then -[Repo Cleanup](../repo-cleanup/SKILL.md) finds it from the repo and branch and -removes it. +`${XDG_STATE_HOME:-$HOME/.local/state}/verify-proof////`. Encode +`` and `` without loss: replace `%` with `%25` first, then `/` with `%2F`. + +- `` is the origin remote's `host/owner/name`, such as + `github.com%2Facme%2Fseatcommons`. With no origin, it is the main checkout's + absolute path. +- `` is the exact branch name. +- `` is the UTC time to the second, the short commit SHA, and a random suffix. + Create it with `mktemp -d` and a template ending in `XXXXXX`, such as + `$HOME/.local/state/verify-proof/github.com%2Facme%2Fseatcommons/feat%2Fseat-map/20261109T141203Z-75e0d1d-Q3x9Lp/`. + +Give the run folder's absolute path in your report. The task folder and every run +folder in it last until the work lands or is abandoned; then +[Repo Cleanup](../repo-cleanup/SKILL.md) finds the task folder from the repo and +branch and removes it. Proof from a run tied to no task branch or PR, such as a reproduction, an audit, or a -check of `main`, goes in the session scratch directory and lasts only as long as the -session. Say so in your report. +check of `main`, goes in the session scratch directory, or in a temporary directory +when the host has none. It lasts only as long as the session. Say so in your report. ## Choose what to prove @@ -176,8 +181,8 @@ Remove secrets and private data from evidence. When a claim says a behavior changed or a bug is fixed, reproduce the old result before you trust the new one. Run the same check, with the same environment and fixtures, against the base revision, in a disposable checkout if the change is already in place, -and keep both results. Run the doctor there too. Red counts only when the old side runs -and shows the old behavior. A setup error isn't red. +and keep both results in the same run folder. Run the doctor there too. Red counts only +when the old side runs and shows the old behavior. A setup error isn't red. A check that passes on both sides proves nothing: change it until it tells them apart, or mark the claim `untested`. If you can't run the old side, revert the change in a disposable diff --git a/skills/verify/references/ios.md b/skills/verify/references/ios.md index b5ec5dc..425c3c0 100644 --- a/skills/verify/references/ios.md +++ b/skills/verify/references/ios.md @@ -38,12 +38,14 @@ and CI configuration in the product repo. Xcode keys its default DerivedData folder by workspace path, so each worktree and each disposable checkout gets its own folder, and that folder outlives the checkout. -- A worktree's normal DerivedData belongs to its owner, who runs its builds one at - a time. -- A run that must overlap another in the same worktree, and every build of a - disposable checkout such as a red-first base, passes `-derivedDataPath` inside - its [run scratch](../SKILL.md#keep-proof-not-runs), so deleting the run scratch - deletes that build. +- Use the worktree's normal DerivedData only when you know you are its sole + builder: you own the worktree, run its builds yourself, and no delegated or + background run is active in it. +- Every other run passes `-derivedDataPath` inside its + [run scratch](../SKILL.md#keep-proof-not-runs), so deleting the run scratch + deletes that build. That covers every delegated or background run, any run + unsure it is alone, and every build of a disposable checkout such as a red-first + base. - Every test run passes `-resultBundlePath` inside its run scratch. ## Prepare and run native UI tests From 245e4ecbad224b37e6e4a1e48a385082b6d29156 Mon Sep 17 00:00:00 2001 From: Sree Raman <1271305+sreejithraman@users.noreply.github.com> Date: Mon, 9 Nov 2026 15:48:57 -0500 Subject: [PATCH 06/10] Key kept proof by a task.json manifest and bounded folder names Co-Authored-By: Claude Opus 5.5 --- SOURCES.md | 25 +++++++++------ skills/repo-cleanup/SKILL.md | 16 ++++++---- skills/verify/SKILL.md | 54 +++++++++++++++++++++++---------- skills/verify/references/ios.md | 12 ++++---- 4 files changed, 70 insertions(+), 37 deletions(-) diff --git a/SOURCES.md b/SOURCES.md index 833d91d..47a45aa 100644 --- a/SOURCES.md +++ b/SOURCES.md @@ -742,15 +742,18 @@ automated and needs assertion coverage beyond a successful command. Targeted suites preserve required integration gates, reconcile every selected test and attempt, and require matching runtime evidence for pre-existing failure claims. Terminal and service checks use process or PTY driving, bounded completion, public -protocols, and fresh persisted-output reads. Separates deleted run scratch from -small kept proof in unique per-run folders under a per-task folder in the XDG -state directory, keyed by percent-encoded repo and branch names, that lasts until -the work lands or is abandoned; proof from runs tied to no task stays in session -scratch. Only a worktree's known sole builder keeps builds in the build system; -the iOS reference sends every other run's builds, disposable-checkout builds and -result bundles into run scratch. Build identity is the commit plus the hash of the -product actually installed or tested. Keeps bounded reproduction attempts, -outcome counts, authorization, isolation, redaction, run-owned cleanup, +protocols, and fresh persisted-output reads. Separates run scratch, made with +`mktemp -d` under `$TMPDIR` and deleted, from small kept proof in unique `mktemp` +per-run folders under a flat per-task folder in the XDG state directory. The task +folder is named by a branch slug and a hash of the origin URL (or main checkout +path) and branch, holds a `task.json` manifest of those inputs, and lasts until the +work lands or is abandoned; proof from runs tied to no task stays in session +scratch. Only the sole agent in a checkout, including a child in its own isolated +worktree, keeps builds in the build system; the iOS reference sends every other +run's builds, disposable-checkout builds and result bundles into run scratch. +Build identity is the commit plus the hash of the product installed or tested. +Keeps bounded reproduction attempts, outcome counts, authorization, isolation, +redaction, run-owned cleanup, and separate defect-reproduction reporting. Authenticated workflows reuse designated test accounts and standing scope, delegate application sign-in and command/API credential use to `agent-login`, @@ -776,6 +779,10 @@ Accepts merge completion handoffs from `merge`. Cleanup includes verified task-owned development processes, simulator/emulator installs, disposable test data, Verify's kept proof, the Xcode DerivedData of removed or missing worktrees, and temporary devices created solely for the task. +It finds Verify's kept-proof task folders by scanning their `task.json` manifests, +removes one when its PR is merged or closed, its branch is gone locally and on the +remote with no open PR, or its checkout is gone and it has no origin, and leaves and +reports one without a readable manifest. Reused devices are preserved and shut down only when the task booted them and no consumer remains. Cleanup reconstructs process, device, and install ownership from available diff --git a/skills/repo-cleanup/SKILL.md b/skills/repo-cleanup/SKILL.md index 2de2445..df3ffe4 100644 --- a/skills/repo-cleanup/SKILL.md +++ b/skills/repo-cleanup/SKILL.md @@ -10,10 +10,10 @@ Clean up only resources whose owner and disposal reason are established. A merge 1. **Inventory.** Resolve the repository, worktrees, default and task branches, relevant pull requests, and candidate resources. Include review surfaces, development apps and their servers/watchers, simulator/emulator devices and - installs, slot claims, runtime files, build folders, the task's kept-proof - folder, found from the repo and branch by Verify's - [naming](../verify/SKILL.md#keep-proof-not-runs), and local or remote refs as - applicable. Follow [development resource discovery](references/development-resources.md#identify-resources) + installs, slot claims, runtime files, build folders, Verify's kept-proof task + folders, found by reading each `task.json` under its + [kept-proof root](../verify/SKILL.md#keep-proof-not-runs), and local or remote + refs as applicable. Follow [development resource discovery](references/development-resources.md#identify-resources) for apps, processes, simulator/emulator devices, and installs. Refresh remote refs before judging branch tips. Prefer project cleanup commands over hand-written deletion. For each candidate, @@ -45,8 +45,12 @@ Clean up only resources whose owner and disposal reason are established. A merge and simulator/emulator installs and devices, follow [development resource cleanup](references/development-resources.md#clean-up). Measure and remove exact task-owned build folders, keeping retained app data. - Remove only the finished or abandoned task's own kept-proof folder, and leave - the root and other tasks' folders. + Remove a kept-proof task folder only when its `task.json` names work that + landed or was abandoned: the branch's PR is merged or closed, the branch is + gone locally and on the remote with no open PR, or the user explicitly + abandoned that work. Also remove one whose `checkout` path is gone and whose + `origin` is null. Leave a folder whose `task.json` is missing or unreadable, + and report it. Leave the root and every other folder. Remove a shared build cache only after approval, when no build is active and no other worktree can use it. diff --git a/skills/verify/SKILL.md b/skills/verify/SKILL.md index b4cb65f..8864535 100644 --- a/skills/verify/SKILL.md +++ b/skills/verify/SKILL.md @@ -28,9 +28,10 @@ A run leaves two kinds of files. Keep them in separate places from the start. **Run scratch** is anything you could produce again: plans, helper and rerun scripts, per-step snapshots, result bundles, intermediate reruns, and builds no later run -reuses. Put it in a temporary directory of its own outside the repo, and delete that -directory when the run ends, pass or fail. Only a worktree's sole builder leaves its -builds where the build system puts them, for its later runs to reuse; +reuses. Create its directory with `mktemp -d`, which puts it under `$TMPDIR`, so the +OS reclaims what a cancelled run leaves. Delete that directory when the run ends, pass +or fail. Only the sole builder in a checkout leaves its builds where the build system +puts them, for its later runs to reuse; [iOS build output](references/ios.md#build-output) says which runs that covers. Record a build by its build identity instead of copying it or its inputs, such as source trees and Pods. @@ -41,28 +42,49 @@ trees and Pods. - the captures behind each verdict, visual for a visual claim: screenshots, recordings, transcripts, or responses; - the log excerpts a verdict or finding cites; -- build identity: the commit SHA and the hash of the product actually installed or - tested, so a build crossed with another run's shows. +- build identity: the commit SHA and the hash of the product installed or tested. For repeated attempts, keep the outcome counts, plus captures only for failures behind a finding that is still open. Write each run's kept proof to -`${XDG_STATE_HOME:-$HOME/.local/state}/verify-proof////`. Encode -`` and `` without loss: replace `%` with `%25` first, then `/` with `%2F`. +`${XDG_STATE_HOME:-$HOME/.local/state}/verify-proof/-//`. The +`-` folder is the task folder. -- `` is the origin remote's `host/owner/name`, such as - `github.com%2Facme%2Fseatcommons`. With no origin, it is the main checkout's - absolute path. -- `` is the exact branch name. -- `` is the UTC time to the second, the short commit SHA, and a random suffix. - Create it with `mktemp -d` and a template ending in `XXXXXX`, such as - `$HOME/.local/state/verify-proof/github.com%2Facme%2Fseatcommons/feat%2Fseat-map/20261109T141203Z-75e0d1d-Q3x9Lp/`. +- `` is the branch name lowercased, with each run of characters other than + `a-z` and `0-9` replaced by `-`, cut to 40 characters. +- `` is the first 12 hex characters of a SHA-256 over the exact + `git remote get-url origin` output, a newline, and the exact branch name. With no + origin, use the main checkout's absolute path in place of the URL. The main + checkout is the parent of `git rev-parse --path-format=absolute --git-common-dir`. + + ```sh + printf '%s\n%s' "$origin" "$branch" | shasum -a 256 | cut -c1-12 + ``` + +If the task folder doesn't exist yet, create it with `mkdir -p` and write its +`task.json` with exactly these fields: `origin`, the exact origin URL or `null`; +`checkout`, the main checkout's absolute path; `branch`, the exact branch name; and +`created`, the UTC time. A sample: + +```json +{"origin": "git@github.com:Acme/SeatCommons.git", "checkout": "/Users/me/src/SeatCommons", "branch": "feat/Seat-Map", "created": "2026-11-09T14:12:03Z"} +``` + +Create each run folder with `mktemp -d` and a template with no trailing slash, where +`$task` is the task folder's absolute path: + +```sh +mktemp -d "$task/$(date -u +%Y%m%dT%H%M%SZ)-$(git rev-parse --short HEAD)-XXXXXX" +``` + +A sample result: +`$HOME/.local/state/verify-proof/feat-seat-map-68d90e4a806f/20261109T141203Z-75e0d1d-Q3x9Lp`. Give the run folder's absolute path in your report. The task folder and every run folder in it last until the work lands or is abandoned; then -[Repo Cleanup](../repo-cleanup/SKILL.md) finds the task folder from the repo and -branch and removes it. +[Repo Cleanup](../repo-cleanup/SKILL.md) finds the task folder by its `task.json` and +removes it. Proof from a run tied to no task branch or PR, such as a reproduction, an audit, or a check of `main`, goes in the session scratch directory, or in a temporary directory diff --git a/skills/verify/references/ios.md b/skills/verify/references/ios.md index 425c3c0..8ad4a9f 100644 --- a/skills/verify/references/ios.md +++ b/skills/verify/references/ios.md @@ -38,14 +38,14 @@ and CI configuration in the product repo. Xcode keys its default DerivedData folder by workspace path, so each worktree and each disposable checkout gets its own folder, and that folder outlives the checkout. -- Use the worktree's normal DerivedData only when you know you are its sole - builder: you own the worktree, run its builds yourself, and no delegated or - background run is active in it. +- Use the checkout's normal DerivedData only when you are its sole builder: the + only agent running in that checkout. A delegated child in its own isolated + worktree qualifies. A child sharing its parent's checkout doesn't. - Every other run passes `-derivedDataPath` inside its [run scratch](../SKILL.md#keep-proof-not-runs), so deleting the run scratch - deletes that build. That covers every delegated or background run, any run - unsure it is alone, and every build of a disposable checkout such as a red-first - base. + deletes that build. That covers every run that shares its checkout with another + agent, any run unsure it is alone, and every build of a disposable checkout such + as a red-first base. - Every test run passes `-resultBundlePath` inside its run scratch. ## Prepare and run native UI tests From c7bc35df257881a42836bdc4e35fa995f00bec19 Mon Sep 17 00:00:00 2001 From: Sree Raman <1271305+sreejithraman@users.noreply.github.com> Date: Mon, 9 Nov 2026 16:06:01 -0500 Subject: [PATCH 07/10] Tie kept-proof removal to branch eligibility and write manifests atomically Co-Authored-By: Claude Opus 5.5 --- SOURCES.md | 25 +++++++++------- skills/repo-cleanup/SKILL.md | 19 +++++++----- skills/verify/SKILL.md | 58 +++++++++++++++++------------------- 3 files changed, 55 insertions(+), 47 deletions(-) diff --git a/SOURCES.md b/SOURCES.md index 47a45aa..4bf8d16 100644 --- a/SOURCES.md +++ b/SOURCES.md @@ -745,12 +745,15 @@ Terminal and service checks use process or PTY driving, bounded completion, publ protocols, and fresh persisted-output reads. Separates run scratch, made with `mktemp -d` under `$TMPDIR` and deleted, from small kept proof in unique `mktemp` per-run folders under a flat per-task folder in the XDG state directory. The task -folder is named by a branch slug and a hash of the origin URL (or main checkout -path) and branch, holds a `task.json` manifest of those inputs, and lasts until the -work lands or is abandoned; proof from runs tied to no task stays in session -scratch. Only the sole agent in a checkout, including a child in its own isolated -worktree, keeps builds in the build system; the iOS reference sends every other -run's builds, disposable-checkout builds and result bundles into run scratch. +folder is named by a branch slug and a hash of the origin URL without userinfo (or +the common Git directory) and branch, and lasts until the work lands or is +abandoned. Before each run folder, Verify checks its `task.json` manifest (`origin`, +`git_dir`, `branch`, `created`), writes a missing one atomically, and sends the run's +proof to session scratch when the manifest conflicts. Proof from runs tied to no +task, including a detached HEAD, stays in session scratch. Only the sole agent in a +checkout, including a child in its own isolated worktree, keeps builds in the build +system; the iOS reference sends every other run's builds, disposable-checkout builds +and result bundles into run scratch. Build identity is the commit plus the hash of the product installed or tested. Keeps bounded reproduction attempts, outcome counts, authorization, isolation, redaction, run-owned cleanup, @@ -779,10 +782,12 @@ Accepts merge completion handoffs from `merge`. Cleanup includes verified task-owned development processes, simulator/emulator installs, disposable test data, Verify's kept proof, the Xcode DerivedData of removed or missing worktrees, and temporary devices created solely for the task. -It finds Verify's kept-proof task folders by scanning their `task.json` manifests, -removes one when its PR is merged or closed, its branch is gone locally and on the -remote with no open PR, or its checkout is gone and it has no origin, and leaves and -reports one without a readable manifest. +It finds Verify's kept-proof task folders by scanning their `task.json` manifests. +From the manifest's own repo, it removes one whose branch work it finds complete or +explicitly abandoned, or whose branch is gone locally and from a successful remote +query with no open PR on the origin repo or its upstream. It also removes one with +no origin whose common Git directory is gone. It keeps and reports one without a +readable manifest or whose check fails or can't run, and skips folders for other repos. Reused devices are preserved and shut down only when the task booted them and no consumer remains. Cleanup reconstructs process, device, and install ownership from available diff --git a/skills/repo-cleanup/SKILL.md b/skills/repo-cleanup/SKILL.md index df3ffe4..c53fa50 100644 --- a/skills/repo-cleanup/SKILL.md +++ b/skills/repo-cleanup/SKILL.md @@ -27,7 +27,8 @@ Clean up only resources whose owner and disposal reason are established. A merge affected worktrees. A merged pull request establishes completion only for its merge-time source head; a branch tip reachable from its intended base is also complete. An explicit request to abandon work establishes abandonment for its identified - commits and task-owned staged, unstaged, or untracked changes. Preserve + commits and task-owned staged, unstaged, or untracked changes; a closed, + unmerged PR leaves its work open. Preserve unrelated changes, ignored user data, and anything whose ownership is uncertain. For housekeeping, verify completion or abandonment separately for each branch or task. Preserve unique commits unless the user explicitly abandoned @@ -45,12 +46,16 @@ Clean up only resources whose owner and disposal reason are established. A merge and simulator/emulator installs and devices, follow [development resource cleanup](references/development-resources.md#clean-up). Measure and remove exact task-owned build folders, keeping retained app data. - Remove a kept-proof task folder only when its `task.json` names work that - landed or was abandoned: the branch's PR is merged or closed, the branch is - gone locally and on the remote with no open PR, or the user explicitly - abandoned that work. Also remove one whose `checkout` path is gone and whose - `origin` is null. Leave a folder whose `task.json` is missing or unreadable, - and report it. Leave the root and every other folder. + Remove a kept-proof task folder when its `task.json` names a branch whose work + this cleanup found complete or explicitly abandoned under step 2. Also remove + it when a successful remote query and the local refs both lack that branch, and + no PR from it is open on the origin repo or its upstream. Judge these only from + the repo the `task.json` names: the current repo's origin or `git_dir`, + computed as [Verify](../verify/SKILL.md#keep-proof-not-runs) does, matches it. + Remove a folder whose `origin` is null and whose `git_dir` no longer exists. + Keep and report a folder whose `task.json` is missing or unreadable, or whose + check fails or can't run, such as offline or after a `gh` error. Skip folders + whose `task.json` names another repo. Leave the root and every other folder. Remove a shared build cache only after approval, when no build is active and no other worktree can use it. diff --git a/skills/verify/SKILL.md b/skills/verify/SKILL.md index 8864535..81e9d8a 100644 --- a/skills/verify/SKILL.md +++ b/skills/verify/SKILL.md @@ -47,48 +47,46 @@ trees and Pods. For repeated attempts, keep the outcome counts, plus captures only for failures behind a finding that is still open. -Write each run's kept proof to -`${XDG_STATE_HOME:-$HOME/.local/state}/verify-proof/-//`. The -`-` folder is the task folder. - -- `` is the branch name lowercased, with each run of characters other than - `a-z` and `0-9` replaced by `-`, cut to 40 characters. -- `` is the first 12 hex characters of a SHA-256 over the exact - `git remote get-url origin` output, a newline, and the exact branch name. With no - origin, use the main checkout's absolute path in place of the URL. The main - checkout is the parent of `git rev-parse --path-format=absolute --git-common-dir`. - - ```sh - printf '%s\n%s' "$origin" "$branch" | shasum -a 256 | cut -c1-12 - ``` - -If the task folder doesn't exist yet, create it with `mkdir -p` and write its -`task.json` with exactly these fields: `origin`, the exact origin URL or `null`; -`checkout`, the main checkout's absolute path; `branch`, the exact branch name; and -`created`, the UTC time. A sample: +Write each run's kept proof to a new run folder inside its task folder, under the +kept-proof root `${XDG_STATE_HOME:-$HOME/.local/state}/verify-proof/`: -```json -{"origin": "git@github.com:Acme/SeatCommons.git", "checkout": "/Users/me/src/SeatCommons", "branch": "feat/Seat-Map", "created": "2026-11-09T14:12:03Z"} +```sh +branch=$(git symbolic-ref --quiet --short HEAD) # empty if detached: use session scratch +origin=$(git remote get-url origin 2>/dev/null | sed -E 's#^([^:/]+://)[^/]*@#\1#') +git_dir=$(git rev-parse --path-format=absolute --git-common-dir) +slug=$(printf '%s' "$branch" | LC_ALL=C tr 'A-Z' 'a-z' | LC_ALL=C tr -cs 'a-z0-9' '-' | cut -c1-40) +hash=$(printf '%s\n%s' "${origin:-$git_dir}" "$branch" | shasum -a 256 | cut -c1-12) +task="${XDG_STATE_HOME:-$HOME/.local/state}/verify-proof/$slug-$hash" +mkdir -p "$task" +# Check or write "$task/task.json" here, before every run folder. +mktemp -d "$task/$(date -u +%Y%m%dT%H%M%SZ)-$(git rev-parse --short HEAD)-XXXXXX" ``` -Create each run folder with `mktemp -d` and a template with no trailing slash, where -`$task` is the task folder's absolute path: +The `sed` strips any `user:token@` from the origin, so no credential is hashed or +stored. `git_dir` is unique to the repo and shared by its worktrees. -```sh -mktemp -d "$task/$(date -u +%Y%m%dT%H%M%SZ)-$(git rev-parse --short HEAD)-XXXXXX" +Before each run folder, make sure `$task/task.json` is readable and names this run's +`branch`, plus its `origin`, or its `git_dir` when `origin` is null. If the file is +missing, write it with exactly `origin` (or `null`), `git_dir`, `branch`, and +`created`, the UTC time: write a temp file in the task folder, then `mv` it into +place. If it is unreadable or names another identity, leave it, report it, and put +this run's proof in session scratch. A sample manifest and run folder: + +```json +{"origin": "git@github.com:Acme/SeatCommons.git", "git_dir": "/Users/me/src/SeatCommons/.git", "branch": "feat/Seat-Map", "created": "2026-11-09T14:12:03Z"} ``` -A sample result: -`$HOME/.local/state/verify-proof/feat-seat-map-68d90e4a806f/20261109T141203Z-75e0d1d-Q3x9Lp`. +`$HOME/.local/state/verify-proof/feat-seat-map-68d90e4a806f/20261109T141203Z-75e0d1d-Q3x9Lp` Give the run folder's absolute path in your report. The task folder and every run folder in it last until the work lands or is abandoned; then [Repo Cleanup](../repo-cleanup/SKILL.md) finds the task folder by its `task.json` and removes it. -Proof from a run tied to no task branch or PR, such as a reproduction, an audit, or a -check of `main`, goes in the session scratch directory, or in a temporary directory -when the host has none. It lasts only as long as the session. Say so in your report. +Proof from a run tied to no task branch or PR, such as a reproduction, an audit, a +check of `main`, or a detached HEAD, goes in the session scratch directory, or in a +temporary directory when the host has none. It lasts only as long as the session. Say +so in your report. ## Choose what to prove From df505d3810cac98c8a5574a0ca5910a047965fee Mon Sep 17 00:00:00 2001 From: Sree Raman <1271305+sreejithraman@users.noreply.github.com> Date: Mon, 9 Nov 2026 16:14:55 -0500 Subject: [PATCH 08/10] Key kept proof by clone and keep it while a worktree holds the branch Co-Authored-By: Claude Opus 5.5 --- SOURCES.md | 15 ++++++++------- skills/repo-cleanup/SKILL.md | 18 ++++++++++-------- skills/verify/SKILL.md | 11 ++++++----- 3 files changed, 24 insertions(+), 20 deletions(-) diff --git a/SOURCES.md b/SOURCES.md index 4bf8d16..c211d87 100644 --- a/SOURCES.md +++ b/SOURCES.md @@ -745,8 +745,8 @@ Terminal and service checks use process or PTY driving, bounded completion, publ protocols, and fresh persisted-output reads. Separates run scratch, made with `mktemp -d` under `$TMPDIR` and deleted, from small kept proof in unique `mktemp` per-run folders under a flat per-task folder in the XDG state directory. The task -folder is named by a branch slug and a hash of the origin URL without userinfo (or -the common Git directory) and branch, and lasts until the work lands or is +folder is named by a branch slug and a hash of the clone's common Git directory and +branch, records the origin without userinfo, and lasts until the work lands or is abandoned. Before each run folder, Verify checks its `task.json` manifest (`origin`, `git_dir`, `branch`, `created`), writes a missing one atomically, and sends the run's proof to session scratch when the manifest conflicts. Proof from runs tied to no @@ -783,11 +783,12 @@ task-owned development processes, simulator/emulator installs, disposable test data, Verify's kept proof, the Xcode DerivedData of removed or missing worktrees, and temporary devices created solely for the task. It finds Verify's kept-proof task folders by scanning their `task.json` manifests. -From the manifest's own repo, it removes one whose branch work it finds complete or -explicitly abandoned, or whose branch is gone locally and from a successful remote -query with no open PR on the origin repo or its upstream. It also removes one with -no origin whose common Git directory is gone. It keeps and reports one without a -readable manifest or whose check fails or can't run, and skips folders for other repos. +From the manifest's own clone, it keeps one while a worktree holds its branch, and +otherwise removes one whose PR merged at a head containing the branch tip, whose +work was explicitly abandoned, or whose branch is gone locally and from a successful +remote query with no open PR on the origin repo or its upstream. It also removes one +whose common Git directory is gone. It keeps and reports one without a readable +manifest or whose check fails or can't run, and skips folders of other clones. Reused devices are preserved and shut down only when the task booted them and no consumer remains. Cleanup reconstructs process, device, and install ownership from available diff --git a/skills/repo-cleanup/SKILL.md b/skills/repo-cleanup/SKILL.md index c53fa50..b2f048d 100644 --- a/skills/repo-cleanup/SKILL.md +++ b/skills/repo-cleanup/SKILL.md @@ -46,16 +46,18 @@ Clean up only resources whose owner and disposal reason are established. A merge and simulator/emulator installs and devices, follow [development resource cleanup](references/development-resources.md#clean-up). Measure and remove exact task-owned build folders, keeping retained app data. - Remove a kept-proof task folder when its `task.json` names a branch whose work - this cleanup found complete or explicitly abandoned under step 2. Also remove - it when a successful remote query and the local refs both lack that branch, and - no PR from it is open on the origin repo or its upstream. Judge these only from - the repo the `task.json` names: the current repo's origin or `git_dir`, - computed as [Verify](../verify/SKILL.md#keep-proof-not-runs) does, matches it. - Remove a folder whose `origin` is null and whose `git_dir` no longer exists. + Judge a kept-proof task folder only from the clone its `task.json` names: the + current repo's `git_dir`, computed as [Verify](../verify/SKILL.md#keep-proof-not-runs) + does, equals the manifest's. Keep it while any worktree holds its branch. + Otherwise remove it when its PR merged at the verified merge-time head and the + branch tip equals or is contained in that head, or when the user explicitly + abandoned that work. Also remove it when a successful remote query and the local + refs both lack that branch, and no PR from it is open on the origin repo or its + upstream. Remove a folder whose `git_dir` no longer exists: its clone is gone. Keep and report a folder whose `task.json` is missing or unreadable, or whose check fails or can't run, such as offline or after a `gh` error. Skip folders - whose `task.json` names another repo. Leave the root and every other folder. + whose `git_dir` belongs to another existing clone. Leave the root and every + other folder. Remove a shared build cache only after approval, when no build is active and no other worktree can use it. diff --git a/skills/verify/SKILL.md b/skills/verify/SKILL.md index 81e9d8a..1b4b412 100644 --- a/skills/verify/SKILL.md +++ b/skills/verify/SKILL.md @@ -55,18 +55,19 @@ branch=$(git symbolic-ref --quiet --short HEAD) # empty if detached: use sessio origin=$(git remote get-url origin 2>/dev/null | sed -E 's#^([^:/]+://)[^/]*@#\1#') git_dir=$(git rev-parse --path-format=absolute --git-common-dir) slug=$(printf '%s' "$branch" | LC_ALL=C tr 'A-Z' 'a-z' | LC_ALL=C tr -cs 'a-z0-9' '-' | cut -c1-40) -hash=$(printf '%s\n%s' "${origin:-$git_dir}" "$branch" | shasum -a 256 | cut -c1-12) +hash=$(printf '%s\n%s' "$git_dir" "$branch" | shasum -a 256 | cut -c1-12) task="${XDG_STATE_HOME:-$HOME/.local/state}/verify-proof/$slug-$hash" mkdir -p "$task" # Check or write "$task/task.json" here, before every run folder. mktemp -d "$task/$(date -u +%Y%m%dT%H%M%SZ)-$(git rev-parse --short HEAD)-XXXXXX" ``` -The `sed` strips any `user:token@` from the origin, so no credential is hashed or -stored. `git_dir` is unique to the repo and shared by its worktrees. +The `sed` strips any `user:token@` from the origin, so no credential is stored. +`git_dir` is unique to each clone and shared by its worktrees, so separate clones of +one remote keep separate task folders. Before each run folder, make sure `$task/task.json` is readable and names this run's -`branch`, plus its `origin`, or its `git_dir` when `origin` is null. If the file is +`branch` and `git_dir`. If the file is missing, write it with exactly `origin` (or `null`), `git_dir`, `branch`, and `created`, the UTC time: write a temp file in the task folder, then `mv` it into place. If it is unreadable or names another identity, leave it, report it, and put @@ -76,7 +77,7 @@ this run's proof in session scratch. A sample manifest and run folder: {"origin": "git@github.com:Acme/SeatCommons.git", "git_dir": "/Users/me/src/SeatCommons/.git", "branch": "feat/Seat-Map", "created": "2026-11-09T14:12:03Z"} ``` -`$HOME/.local/state/verify-proof/feat-seat-map-68d90e4a806f/20261109T141203Z-75e0d1d-Q3x9Lp` +`$HOME/.local/state/verify-proof/feat-seat-map-a9e97ffc830e/20261109T141203Z-75e0d1d-Q3x9Lp` Give the run folder's absolute path in your report. The task folder and every run folder in it last until the work lands or is abandoned; then From 6c8f0af10b5eb6c003aba8a1540de03367e2bf7f Mon Sep 17 00:00:00 2001 From: Sree Raman <1271305+sreejithraman@users.noreply.github.com> Date: Mon, 9 Nov 2026 16:22:46 -0500 Subject: [PATCH 09/10] Keep verify proof in the worktree's private git dir Proof now lives and dies with its worktree, so it needs no naming, manifest, or cleanup rules. Co-Authored-By: Claude Opus 5.5 --- SOURCES.md | 28 +++++++-------------- skills/implement/SKILL.md | 8 +++--- skills/repo-cleanup/SKILL.md | 23 +++-------------- skills/verify/SKILL.md | 49 ++++++++++-------------------------- 4 files changed, 30 insertions(+), 78 deletions(-) diff --git a/SOURCES.md b/SOURCES.md index c211d87..785bbcc 100644 --- a/SOURCES.md +++ b/SOURCES.md @@ -744,16 +744,13 @@ attempt, and require matching runtime evidence for pre-existing failure claims. Terminal and service checks use process or PTY driving, bounded completion, public protocols, and fresh persisted-output reads. Separates run scratch, made with `mktemp -d` under `$TMPDIR` and deleted, from small kept proof in unique `mktemp` -per-run folders under a flat per-task folder in the XDG state directory. The task -folder is named by a branch slug and a hash of the clone's common Git directory and -branch, records the origin without userinfo, and lasts until the work lands or is -abandoned. Before each run folder, Verify checks its `task.json` manifest (`origin`, -`git_dir`, `branch`, `created`), writes a missing one atomically, and sends the run's -proof to session scratch when the manifest conflicts. Proof from runs tied to no -task, including a detached HEAD, stays in session scratch. Only the sole agent in a -checkout, including a child in its own isolated worktree, keeps builds in the build -system; the iOS reference sends every other run's builds, disposable-checkout builds -and result bundles into run scratch. +per-run folders. A task branch in a linked worktree keeps its proof under that +worktree's private Git directory (`--git-path verify-proof`), so Git never commits +it and worktree removal deletes it. Every other run, including the main checkout, a +detached HEAD, an audit, or a reproduction, keeps proof in session scratch for the +session only. Only the sole agent in a checkout, including a child in its own +isolated worktree, keeps builds in the build system; the iOS reference sends every +other run's builds, disposable-checkout builds and result bundles into run scratch. Build identity is the commit plus the hash of the product installed or tested. Keeps bounded reproduction attempts, outcome counts, authorization, isolation, redaction, run-owned cleanup, @@ -780,15 +777,8 @@ evidence limits. Greetings and attribution instructions are omitted. Accepts merge completion handoffs from `merge`. Cleanup includes verified task-owned development processes, simulator/emulator installs, disposable test -data, Verify's kept proof, the Xcode DerivedData of removed or missing worktrees, and -temporary devices created solely for the task. -It finds Verify's kept-proof task folders by scanning their `task.json` manifests. -From the manifest's own clone, it keeps one while a worktree holds its branch, and -otherwise removes one whose PR merged at a head containing the branch tip, whose -work was explicitly abandoned, or whose branch is gone locally and from a successful -remote query with no open PR on the origin repo or its upstream. It also removes one -whose common Git directory is gone. It keeps and reports one without a readable -manifest or whose check fails or can't run, and skips folders of other clones. +data, the Xcode DerivedData of removed or missing worktrees, and temporary devices +created solely for the task. Reused devices are preserved and shut down only when the task booted them and no consumer remains. Cleanup reconstructs process, device, and install ownership from available diff --git a/skills/implement/SKILL.md b/skills/implement/SKILL.md index f3e20dc..1247570 100644 --- a/skills/implement/SKILL.md +++ b/skills/implement/SKILL.md @@ -88,10 +88,10 @@ through Merge. Name the branch or assumption provisional work rests on. It can build and prove, and is reviewed only when the caller asks for review or a PR. Provisional work never merges and never crosses into destructive or outward-facing actions on your own initiative. The user's explicit scrap of this -outcome allows only its scoped cleanup through Repo Cleanup: its branch, PR, -worktree, and kept verification proof; work built on it still gets its own -choice. Land becomes Try, but a requested PR state, draft or review-ready, can -still be reached. Publish a provisional PR with the **Provisional** section from PR's +outcome allows only its scoped cleanup through Repo Cleanup: its branch, PR, and +worktree; work built on it still gets its own choice. Land becomes Try, but a +requested PR state, draft or review-ready, can still be reached. Publish a +provisional PR with the **Provisional** section from PR's [body guide](../pr/references/pr-body.md); that section is where its status lives, and you remove it only after its condition is met and affected proof is refreshed. If its base changes, restack and recheck it. If its base is scrapped, diff --git a/skills/repo-cleanup/SKILL.md b/skills/repo-cleanup/SKILL.md index b2f048d..a65971b 100644 --- a/skills/repo-cleanup/SKILL.md +++ b/skills/repo-cleanup/SKILL.md @@ -10,10 +10,8 @@ Clean up only resources whose owner and disposal reason are established. A merge 1. **Inventory.** Resolve the repository, worktrees, default and task branches, relevant pull requests, and candidate resources. Include review surfaces, development apps and their servers/watchers, simulator/emulator devices and - installs, slot claims, runtime files, build folders, Verify's kept-proof task - folders, found by reading each `task.json` under its - [kept-proof root](../verify/SKILL.md#keep-proof-not-runs), and local or remote - refs as applicable. Follow [development resource discovery](references/development-resources.md#identify-resources) + installs, slot claims, runtime files, build folders, and local or remote refs + as applicable. Follow [development resource discovery](references/development-resources.md#identify-resources) for apps, processes, simulator/emulator devices, and installs. Refresh remote refs before judging branch tips. Prefer project cleanup commands over hand-written deletion. For each candidate, @@ -27,8 +25,7 @@ Clean up only resources whose owner and disposal reason are established. A merge affected worktrees. A merged pull request establishes completion only for its merge-time source head; a branch tip reachable from its intended base is also complete. An explicit request to abandon work establishes abandonment for its identified - commits and task-owned staged, unstaged, or untracked changes; a closed, - unmerged PR leaves its work open. Preserve + commits and task-owned staged, unstaged, or untracked changes. Preserve unrelated changes, ignored user data, and anything whose ownership is uncertain. For housekeeping, verify completion or abandonment separately for each branch or task. Preserve unique commits unless the user explicitly abandoned @@ -46,18 +43,6 @@ Clean up only resources whose owner and disposal reason are established. A merge and simulator/emulator installs and devices, follow [development resource cleanup](references/development-resources.md#clean-up). Measure and remove exact task-owned build folders, keeping retained app data. - Judge a kept-proof task folder only from the clone its `task.json` names: the - current repo's `git_dir`, computed as [Verify](../verify/SKILL.md#keep-proof-not-runs) - does, equals the manifest's. Keep it while any worktree holds its branch. - Otherwise remove it when its PR merged at the verified merge-time head and the - branch tip equals or is contained in that head, or when the user explicitly - abandoned that work. Also remove it when a successful remote query and the local - refs both lack that branch, and no PR from it is open on the origin repo or its - upstream. Remove a folder whose `git_dir` no longer exists: its clone is gone. - Keep and report a folder whose `task.json` is missing or unreadable, or whose - check fails or can't run, such as offline or after a `gh` error. Skip folders - whose `git_dir` belongs to another existing clone. Leave the root and every - other folder. Remove a shared build cache only after approval, when no build is active and no other worktree can use it. @@ -115,4 +100,4 @@ Clean up only resources whose owner and disposal reason are established. A merge and recovery details such as recorded branch heads or reflogs. State partial cleanup plainly. -An explicit cleanup request or a handoff from [merge](../merge/SKILL.md) after an authorized merge covers disposal of verified task-owned temporary resources, including development processes, simulator/emulator installs, disposable test data, kept verification proof, and temporary devices created for the task, in that scope. It does not authorize unrelated or uncertain targets. +An explicit cleanup request or a handoff from [merge](../merge/SKILL.md) after an authorized merge covers disposal of verified task-owned temporary resources, including development processes, simulator/emulator installs, disposable test data, and temporary devices created for the task, in that scope. It does not authorize unrelated or uncertain targets. diff --git a/skills/verify/SKILL.md b/skills/verify/SKILL.md index 1b4b412..da10262 100644 --- a/skills/verify/SKILL.md +++ b/skills/verify/SKILL.md @@ -47,47 +47,24 @@ trees and Pods. For repeated attempts, keep the outcome counts, plus captures only for failures behind a finding that is still open. -Write each run's kept proof to a new run folder inside its task folder, under the -kept-proof root `${XDG_STATE_HOME:-$HOME/.local/state}/verify-proof/`: +Write each run's kept proof to a new run folder, and give its absolute path in your +report. When the run proves a task branch checked out in a linked worktree, put the +folder in that worktree's private Git directory: ```sh -branch=$(git symbolic-ref --quiet --short HEAD) # empty if detached: use session scratch -origin=$(git remote get-url origin 2>/dev/null | sed -E 's#^([^:/]+://)[^/]*@#\1#') -git_dir=$(git rev-parse --path-format=absolute --git-common-dir) -slug=$(printf '%s' "$branch" | LC_ALL=C tr 'A-Z' 'a-z' | LC_ALL=C tr -cs 'a-z0-9' '-' | cut -c1-40) -hash=$(printf '%s\n%s' "$git_dir" "$branch" | shasum -a 256 | cut -c1-12) -task="${XDG_STATE_HOME:-$HOME/.local/state}/verify-proof/$slug-$hash" -mkdir -p "$task" -# Check or write "$task/task.json" here, before every run folder. -mktemp -d "$task/$(date -u +%Y%m%dT%H%M%SZ)-$(git rev-parse --short HEAD)-XXXXXX" +proof=$(git rev-parse --path-format=absolute --git-path verify-proof) +mkdir -p "$proof" && mktemp -d "$proof/$(date -u +%Y%m%dT%H%M%SZ)-$(git rev-parse --short HEAD)-XXXXXX" ``` -The `sed` strips any `user:token@` from the origin, so no credential is stored. -`git_dir` is unique to each clone and shared by its worktrees, so separate clones of -one remote keep separate task folders. +Git never commits that folder, and removing or pruning the worktree deletes it, so the +proof lasts exactly as long as the task's worktree. A checkout is a linked worktree on +a branch when `git rev-parse --path-format=absolute --git-dir --git-common-dir` prints +two different paths and `git symbolic-ref -q HEAD` succeeds. -Before each run folder, make sure `$task/task.json` is readable and names this run's -`branch` and `git_dir`. If the file is -missing, write it with exactly `origin` (or `null`), `git_dir`, `branch`, and -`created`, the UTC time: write a temp file in the task folder, then `mv` it into -place. If it is unreadable or names another identity, leave it, report it, and put -this run's proof in session scratch. A sample manifest and run folder: - -```json -{"origin": "git@github.com:Acme/SeatCommons.git", "git_dir": "/Users/me/src/SeatCommons/.git", "branch": "feat/Seat-Map", "created": "2026-11-09T14:12:03Z"} -``` - -`$HOME/.local/state/verify-proof/feat-seat-map-a9e97ffc830e/20261109T141203Z-75e0d1d-Q3x9Lp` - -Give the run folder's absolute path in your report. The task folder and every run -folder in it last until the work lands or is abandoned; then -[Repo Cleanup](../repo-cleanup/SKILL.md) finds the task folder by its `task.json` and -removes it. - -Proof from a run tied to no task branch or PR, such as a reproduction, an audit, a -check of `main`, or a detached HEAD, goes in the session scratch directory, or in a -temporary directory when the host has none. It lasts only as long as the session. Say -so in your report. +Put every other run's folder in the session scratch directory, or in a temporary +directory when the host has none. That covers the main checkout, a detached HEAD, a +run outside a repo, an audit, and a reproduction. That proof lasts only as long as the +session. Say so in your report. ## Choose what to prove From cddd0d973747c4eae6d643a5cb1716c740ba66cb Mon Sep 17 00:00:00 2001 From: Sree Raman <1271305+sreejithraman@users.noreply.github.com> Date: Mon, 9 Nov 2026 16:32:39 -0500 Subject: [PATCH 10/10] Let the worktree test alone place kept proof Co-Authored-By: Claude Opus 5.5 --- SOURCES.md | 15 +++++---------- skills/verify/SKILL.md | 21 ++++++++------------- skills/verify/references/ios.md | 13 ++++++------- 3 files changed, 19 insertions(+), 30 deletions(-) diff --git a/SOURCES.md b/SOURCES.md index 785bbcc..6aae717 100644 --- a/SOURCES.md +++ b/SOURCES.md @@ -742,16 +742,11 @@ automated and needs assertion coverage beyond a successful command. Targeted suites preserve required integration gates, reconcile every selected test and attempt, and require matching runtime evidence for pre-existing failure claims. Terminal and service checks use process or PTY driving, bounded completion, public -protocols, and fresh persisted-output reads. Separates run scratch, made with -`mktemp -d` under `$TMPDIR` and deleted, from small kept proof in unique `mktemp` -per-run folders. A task branch in a linked worktree keeps its proof under that -worktree's private Git directory (`--git-path verify-proof`), so Git never commits -it and worktree removal deletes it. Every other run, including the main checkout, a -detached HEAD, an audit, or a reproduction, keeps proof in session scratch for the -session only. Only the sole agent in a checkout, including a child in its own -isolated worktree, keeps builds in the build system; the iOS reference sends every -other run's builds, disposable-checkout builds and result bundles into run scratch. -Build identity is the commit plus the hash of the product installed or tested. +protocols, and fresh persisted-output reads. Separates deleted run scratch from +small kept proof. A linked worktree on a branch keeps that proof in its private Git +directory, which worktree removal deletes; other runs keep it in session scratch for +the session. The iOS reference keeps builds in the build system only for a +checkout's sole agent and sends other builds and result bundles to run scratch. Keeps bounded reproduction attempts, outcome counts, authorization, isolation, redaction, run-owned cleanup, and separate defect-reproduction reporting. diff --git a/skills/verify/SKILL.md b/skills/verify/SKILL.md index da10262..9a4f920 100644 --- a/skills/verify/SKILL.md +++ b/skills/verify/SKILL.md @@ -47,24 +47,19 @@ trees and Pods. For repeated attempts, keep the outcome counts, plus captures only for failures behind a finding that is still open. -Write each run's kept proof to a new run folder, and give its absolute path in your -report. When the run proves a task branch checked out in a linked worktree, put the -folder in that worktree's private Git directory: +Write each run's kept proof to a new run folder. In a linked worktree on a branch, +where `git rev-parse --path-format=absolute --git-dir --git-common-dir` prints two +different paths and `git symbolic-ref -q HEAD` succeeds, put the folder in that +worktree's private Git directory: ```sh proof=$(git rev-parse --path-format=absolute --git-path verify-proof) mkdir -p "$proof" && mktemp -d "$proof/$(date -u +%Y%m%dT%H%M%SZ)-$(git rev-parse --short HEAD)-XXXXXX" ``` -Git never commits that folder, and removing or pruning the worktree deletes it, so the -proof lasts exactly as long as the task's worktree. A checkout is a linked worktree on -a branch when `git rev-parse --path-format=absolute --git-dir --git-common-dir` prints -two different paths and `git symbolic-ref -q HEAD` succeeds. - -Put every other run's folder in the session scratch directory, or in a temporary -directory when the host has none. That covers the main checkout, a detached HEAD, a -run outside a repo, an audit, and a reproduction. That proof lasts only as long as the -session. Say so in your report. +Git never commits that folder, and removing or pruning the worktree deletes it. +Otherwise put the folder in the session scratch directory, or in a temporary directory +when the host has none, and say in your report that it lasts only for the session. ## Choose what to prove @@ -251,7 +246,7 @@ their disposable data, and delete the run scratch. Leave reused services and sou fixtures running. Then open the kept proof to confirm it survived. Give each workflow and entry point its actions, expected and observed results, and -the kept proof's path. Give every assertion one verdict: +the kept proof's absolute path. Give every assertion one verdict: - `passed`: the observed result matched. - `failed`: the observed result differed. diff --git a/skills/verify/references/ios.md b/skills/verify/references/ios.md index 8ad4a9f..c6e1032 100644 --- a/skills/verify/references/ios.md +++ b/skills/verify/references/ios.md @@ -39,13 +39,12 @@ Xcode keys its default DerivedData folder by workspace path, so each worktree an each disposable checkout gets its own folder, and that folder outlives the checkout. - Use the checkout's normal DerivedData only when you are its sole builder: the - only agent running in that checkout. A delegated child in its own isolated - worktree qualifies. A child sharing its parent's checkout doesn't. -- Every other run passes `-derivedDataPath` inside its - [run scratch](../SKILL.md#keep-proof-not-runs), so deleting the run scratch - deletes that build. That covers every run that shares its checkout with another - agent, any run unsure it is alone, and every build of a disposable checkout such - as a red-first base. + only agent running in that checkout, such as a delegated child in its own + isolated worktree. +- Every other run, including any run unsure it is alone and every build of a + disposable checkout such as a red-first base, passes `-derivedDataPath` inside + its [run scratch](../SKILL.md#keep-proof-not-runs), so deleting the run scratch + deletes that build. - Every test run passes `-resultBundlePath` inside its run scratch. ## Prepare and run native UI tests