diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 4fe86c1..7f49129 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -14,20 +14,29 @@ jobs: - name: Checkout repository uses: actions/checkout@v4 - - name: Run research modes suite - run: bash tests/test_research_modes.sh + - name: Run workflow contract suite + run: bash tests/test_workflow_static.sh - name: Run execution scope suite run: bash tests/test_execution_scope.sh - - name: Run publication compatibility suite - run: bash tests/test_publication_compatibility.sh + - name: Run isolated execution workspace suite + run: bash tests/test_execution_workspace.sh - - name: Run AGY preflight suite - run: bash tests/test_agy_preflight.sh + - name: Run research workspace suite + run: bash tests/test_research_workspace.sh - - name: Check Codex adapter syntax - run: bash -n scripts/run-codex-json.sh + - name: Run research acceptance suite + run: bash tests/test_research_acceptance.sh + + - name: Run failed launch fallback suite + run: bash tests/test_worker_failure.sh + + - name: Run repository consistency suite + run: bash tests/test_repository_consistency.sh + + - name: Check retained helper syntax + run: bash -n scripts/check-execution-scope.sh scripts/execution-workspace.sh scripts/make-research-workspace.sh scripts/cleanup-research-workspace.sh macos-bash: name: macOS Bash contract suite @@ -36,20 +45,29 @@ jobs: - name: Checkout repository uses: actions/checkout@v4 - - name: Run research modes suite - run: bash tests/test_research_modes.sh + - name: Run workflow contract suite + run: bash tests/test_workflow_static.sh - name: Run execution scope suite run: bash tests/test_execution_scope.sh - - name: Run publication compatibility suite - run: bash tests/test_publication_compatibility.sh + - name: Run isolated execution workspace suite + run: bash tests/test_execution_workspace.sh + + - name: Run research workspace suite + run: bash tests/test_research_workspace.sh - - name: Run AGY preflight suite - run: bash tests/test_agy_preflight.sh + - name: Run research acceptance suite + run: bash tests/test_research_acceptance.sh - - name: Check Codex adapter syntax - run: bash -n scripts/run-codex-json.sh + - name: Run failed launch fallback suite + run: bash tests/test_worker_failure.sh + + - name: Run repository consistency suite + run: bash tests/test_repository_consistency.sh + + - name: Check retained helper syntax + run: bash -n scripts/check-execution-scope.sh scripts/execution-workspace.sh scripts/make-research-workspace.sh scripts/cleanup-research-workspace.sh windows-powershell: name: Windows PowerShell contract suite @@ -61,17 +79,23 @@ jobs: - name: Checkout repository uses: actions/checkout@v4 - - name: Run research helpers suite - run: pwsh -File tests/test_research_helpers.ps1 + - name: Run workflow contract suite + run: pwsh -File tests/test_workflow_static.ps1 - name: Run execution scope suite run: pwsh -File tests/test_execution_scope.ps1 - - name: Run publication compatibility suite - run: pwsh -File tests/test_publication_compatibility.ps1 + - name: Run isolated execution workspace suite + run: pwsh -File tests/test_execution_workspace.ps1 + + - name: Run research workspace suite + run: pwsh -File tests/test_research_workspace.ps1 + + - name: Run research acceptance suite + run: pwsh -File tests/test_research_acceptance.ps1 - - name: Run AGY preflight suite - run: pwsh -File tests/test_agy_preflight.ps1 + - name: Run failed launch fallback suite + run: pwsh -File tests/test_worker_failure.ps1 - - name: Run Codex adapter suite - run: pwsh -File tests/test_codex_adapter.ps1 + - name: Run repository consistency suite + run: pwsh -File tests/test_repository_consistency.ps1 diff --git a/.scratch/offload-review-remediation/README.md b/.scratch/offload-review-remediation/README.md deleted file mode 100644 index 94e925b..0000000 --- a/.scratch/offload-review-remediation/README.md +++ /dev/null @@ -1,127 +0,0 @@ -# Offload review remediation tickets - -Drafted 2026-09-03 from the [whole-skill review](evidence/review.md) of revision `cfc9f4e`. All 14 tickets are now published as GitHub issues, covering all 13 confirmed findings. No implementation has started. GitHub is the active issue tracker. - -## GitHub issues - -| Local ticket | Published issue | -| --- | --- | -| 01 | [#3: Execute every PowerShell model-routing test group](https://github.com/anthonyandrei/offload/issues/3) | -| 02 | [#4: Make documented PowerShell research handoffs return usable values](https://github.com/anthonyandrei/offload/issues/4) | -| 03 | [#5: Check committed and working-tree edits against a fixed baseline](https://github.com/anthonyandrei/offload/issues/5) | -| 04 | [#6: Add a verified lifecycle for isolated execution worktrees](https://github.com/anthonyandrei/offload/issues/6) | -| 05 | [#7: Run execution stages through isolated workspaces and retire shared-tree dispatch](https://github.com/anthonyandrei/offload/issues/7) | -| 06 | [#8: Review one complete change artifact against the execution baseline](https://github.com/anthonyandrei/offload/issues/8) | -| 07 | [#9: Require one valid reviewer verdict for every requested criterion](https://github.com/anthonyandrei/offload/issues/9) | -| 08 | [#10: Require audit coverage for every claim and citation pair](https://github.com/anthonyandrei/offload/issues/10) | -| 09 | [#11: Prevent orphaned workers when PowerShell output setup fails](https://github.com/anthonyandrei/offload/issues/11) | -| 10 | [#12: Keep PowerShell cleanup inside the marked workspace](https://github.com/anthonyandrei/offload/issues/12) | -| 11 | [#13: Make routing provenance examples match both validators](https://github.com/anthonyandrei/offload/issues/13) | -| 12 | [#14: Give every worker attempt distinct evidence paths](https://github.com/anthonyandrei/offload/issues/14) | -| 13 | [#15: Continue synthesis from verified successful research angles](https://github.com/anthonyandrei/offload/issues/15) | -| 14 | [#16: Preserve routing history and explain pruned evidence after success](https://github.com/anthonyandrei/offload/issues/16) | - -## Breakdown - -| Ticket and deliverable | Priority | Blocked by | Findings | -| --- | --- | --- | --- | -| [01. Execute every PowerShell model-routing test group](issues/01-execute-model-routing-tests.md) | P2 | None | F-09 | -| [02. Make documented PowerShell research handoffs return usable values](issues/02-capture-powershell-research-output.md) | P1 | None | F-01 | -| [03. Check committed and working-tree edits against a fixed baseline](issues/03-verify-baseline-relative-scope.md) | P1 | None | F-03, F-06 | -| [04. Add a verified lifecycle for isolated execution worktrees](issues/04-add-isolated-execution-workspaces.md) | P1 | 03 | F-02 | -| [05. Run execution stages through isolated workspaces and retire shared-tree dispatch](issues/05-migrate-execution-to-isolated-workers.md) | P1 | 03, 04 | F-02, F-03 | -| [06. Review one complete change artifact against the execution baseline](issues/06-review-complete-change-artifacts.md) | P1 | 05 | F-04 | -| [07. Require one valid reviewer verdict for every requested criterion](issues/07-require-complete-reviewer-verdicts.md) | P1 | 06 | F-05 | -| [08. Require audit coverage for every claim and citation pair](issues/08-require-complete-citation-audits.md) | P1 | None | F-05 | -| [09. Prevent orphaned workers when PowerShell output setup fails](issues/09-close-launcher-failure-lifetime.md) | P2 | 01 | F-07 | -| [10. Keep PowerShell cleanup inside the marked workspace](issues/10-avoid-following-cleanup-links.md) | P2 | None | F-08 | -| [11. Make routing provenance examples match both validators](issues/11-align-routing-provenance-examples.md) | P2 | None | F-11 | -| [12. Give every worker attempt distinct evidence paths](issues/12-preserve-per-attempt-artifacts.md) | P2 | None | F-13 | -| [13. Continue synthesis from verified successful research angles](issues/13-merge-only-verified-research-attempts.md) | P2 | 02, 12 | F-12 | -| [14. Preserve routing history and explain pruned evidence after success](issues/14-retain-routing-history-after-cleanup.md) | P2 | 10, 11, 12 | F-10 | - -Each ticket contains its own problem, deliverable, atomic acceptance checklist, file pointers, and verification steps. Numbering is a valid topological publication order, not a requirement to finish every earlier number first. - -## Publication design - -Use isolated Git worktrees for writing workers. Tickets 03 and 04 add baseline verification and workspace helpers beside the current behavior. Ticket 05 migrates gate authors and implementers, then removes the old no-baseline and shared-tree paths. Tickets 06 and 07 complete the diff-review path. This avoids one oversized execution rewrite. - -Keep success-time pruning of raw research artifacts, but retain routing history and a small evidence disposition manifest. Ticket 14 records which referenced files were present, retained, missing, or pruned, with content hashes where inspection is safe. The report will no longer imply that a deleted path still provides inspectable evidence. - -Split F-05 into execution criterion coverage and web citation coverage. They require different input identities and acceptance checks. Combine F-03 with F-06 because both fix the same paired scope helpers and their failure contract. - -No separate general refactor is required. Ticket 01 repairs dormant tests; it is not a blanket blocker for unrelated helpers. - -Published at the user's request. Blockers in the issue bodies link to actual GitHub issue numbers. Existing issues were left unchanged. - -## Dependency graph - -```mermaid -flowchart LR - T03["03 Baseline scope"] --> T04["04 Execution workspaces"] - T03 --> T05["05 Execution migration"] - T04 --> T05 - T05 --> T06["06 Complete review artifact"] - T06 --> T07["07 Criterion coverage"] - T01["01 Execute tests"] --> T09["09 Launcher lifetime"] - T02["02 PowerShell capture"] --> T13["13 Verified research merge"] - T12["12 Attempt artifacts"] --> T13 - T10["10 Link-safe cleanup"] --> T14["14 Retain history"] - T11["11 Provenance shape"] --> T14 - T12 --> T14 - T08["08 Citation coverage"] -``` - -## Scheduling - -Unblocked issues corresponding to tickets 01, 02, 03, 08, 10, 11, and 12 carry ready-for-agent. Every issue also carries bug and review-remediation. - -Start with 02 and 03 for the broken research and execution paths, and 01 to restore confidence in the routing test suite. Ticket 08 can proceed independently. Continue the execution chain through 07 before relying on automated diff-gate acceptance. - -Dependencies express behavior prerequisites. File ownership still limits parallel dispatch. Several tickets edit `modes/web-research.md`, `SKILL.md`, and shared test files. Serialize those edits or use isolated branches with deliberate integration. Ticket 12 also overlaps execution-mode edits in 05 through 07. - -Do not use the currently broken shared-tree offload execution workflow to implement this plan. Use direct orchestration or independently verified isolated checkouts until ticket 05 is complete. An unblocked source-edit ticket can still be delayed by a concrete regression exposed by ticket 01. - -## Shared constraints - -- Work in the source repository. Leave `C:/Users/antho/.codex/skills/_offload` unchanged until a separately requested installation/update step. -- Preserve the Gemini model policy, role routing, one-retry ceiling, and immediate quota handoff. -- Preserve shell parity. Bash remains compatible with 3.2+ and its existing dependencies. Native Windows requires PowerShell 7, Git, and AGY, with no Bash, Python, or jq dependency. -- Keep `SKILL.md` as a router under 500 lines; put detailed contracts and workflow instructions in their proper files. -- Treat plan mode and worktrees as workflow controls, not enforceable OS write barriers. -- Prefer fake workers and disposable repositories for regression checks. A live paid worker run or broad model comparison is unnecessary for these fixes. -- Before destructive fixture cleanup, resolve and verify absolute paths within the intended disposable root. Never reset or clean the user's checkout to simplify a test. -- Record the actual shells/platforms exercised. The review ran PowerShell 7 and Git Bash on Windows; native Linux, macOS, and Bash 3.2 were not exercised. -- Each ticket must demonstrate its stated behavior, including the negative case that exposed the defect. Do not substitute a text search for a runtime verification requirement. -- Parent tracker items must remain unchanged if these tickets are later published. - -## Finding coverage - -| Finding | Tickets | -| --- | --- | -| F-01 | [02](issues/02-capture-powershell-research-output.md) | -| F-02 | [04](issues/04-add-isolated-execution-workspaces.md), [05](issues/05-migrate-execution-to-isolated-workers.md) | -| F-03 | [03](issues/03-verify-baseline-relative-scope.md), [05](issues/05-migrate-execution-to-isolated-workers.md) | -| F-04 | [06](issues/06-review-complete-change-artifacts.md) | -| F-05 | [07](issues/07-require-complete-reviewer-verdicts.md), [08](issues/08-require-complete-citation-audits.md) | -| F-06 | [03](issues/03-verify-baseline-relative-scope.md) | -| F-07 | [09](issues/09-close-launcher-failure-lifetime.md) | -| F-08 | [10](issues/10-avoid-following-cleanup-links.md) | -| F-09 | [01](issues/01-execute-model-routing-tests.md) | -| F-10 | [14](issues/14-retain-routing-history-after-cleanup.md) | -| F-11 | [11](issues/11-align-routing-provenance-examples.md) | -| F-12 | [13](issues/13-merge-only-verified-research-attempts.md) | -| F-13 | [12](issues/12-preserve-per-attempt-artifacts.md) | - -The review also suggested a minor description edit to align the trigger wording with distinct work lanes. It is a nonblocking editorial follow-up, outside these confirmed-defect tickets. Rejected and unverified claims from the audit are excluded. - -## Evidence and validation - -The `evidence/` directory contains a copy of the full audit, its verification decisions, reproduction logs, and the list of dormant test groups. Original temporary paths inside the copied report describe the audit run. Use the copies here for durable ticket context. - -Reproduction scripts are not copied as executable instructions. New regression fixtures must be disposable and must not reuse the original audit workspace. - -`tickets.json` records ticket IDs, dependencies, priorities, findings, and acceptance criteria for mechanical checks. The accompanying `validation.json` records this draft's coverage and dependency validation. - - -Publication details are recorded in [github-issues.json](github-issues.json). [github-publication.json](github-publication.json) confirms all 14 remote bodies, open states, blocker links, and readiness labels were read back and verified. diff --git a/.scratch/offload-review-remediation/evidence/bash-status-repro.log b/.scratch/offload-review-remediation/evidence/bash-status-repro.log deleted file mode 100644 index decbfee..0000000 --- a/.scratch/offload-review-remediation/evidence/bash-status-repro.log +++ /dev/null @@ -1,2 +0,0 @@ -simulated git status failure -scope_check_exit_on_git_status_failure=0 diff --git a/.scratch/offload-review-remediation/evidence/repro-helpers.log b/.scratch/offload-review-remediation/evidence/repro-helpers.log deleted file mode 100644 index 0de47b6..0000000 --- a/.scratch/offload-review-remediation/evidence/repro-helpers.log +++ /dev/null @@ -1,19 +0,0 @@ -outside_workspace_readonly_before=True -ParentContainsErrorRecordException: D:\dreiOS\Projects\offload\scripts\cleanup-research-workspace.ps1:128 -Line | - 128 | [System.IO.Directory]::Delete($entry, $true) - | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - | Exception calling "Delete" with "2" argument(s): "Access to the path 'nested-link' is denied." -junction_cleanup_exit=1 -outside_workspace_file_exists=True -outside_workspace_readonly_after=False -ParentContainsErrorRecordException: D:\dreiOS\Projects\offload\scripts\run-agy-json.ps1:414 -Line | - 414 | $errFs = [System.IO.File]::Create($resolvedErrorPath) - | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - | Exception calling "Create" with "1" argument(s): "The process cannot access the file - | 'C:\Users\antho\AppData\Local\Temp\offload-audit-d919ed4019894033906315ba97d92b66\helper-repros\same.log' - | because it is being used by another process." -same_output_error_launcher_exit=1 -worker_finished_at_launcher_exit=False -worker_finished_after_launcher_exit=True diff --git a/.scratch/offload-review-remediation/evidence/repro-research.log b/.scratch/offload-review-remediation/evidence/repro-research.log deleted file mode 100644 index fe1185a..0000000 --- a/.scratch/offload-review-remediation/evidence/repro-research.log +++ /dev/null @@ -1,8 +0,0 @@ -empty_citation_audit_schema_valid=True -empty_criteria_schema_valid=True -web_powershell_blocks=3 parse_errors=0 -ERROR: structured_output property missing in file: C:\Users\antho\AppData\Local\Temp\offload-audit-d919ed4019894033906315ba97d92b66\merge-repro\researcher-3.json -merge_two_good_one_failed_exit=2 -Error: routing missing required schema_version -documented_attempt_routing_exit=1 -container_routing_exit=0 diff --git a/.scratch/offload-review-remediation/evidence/repro.log b/.scratch/offload-review-remediation/evidence/repro.log deleted file mode 100644 index 363e31f..0000000 --- a/.scratch/offload-review-remediation/evidence/repro.log +++ /dev/null @@ -1,13 +0,0 @@ -b.txt -parallel_worker_A_exit=1 -a.txt -parallel_worker_B_exit=1 -committed_frozen_change_exit=0 -plain_diff_line_count=0 -actual_changes=M a.txt; ?? new.txt -[{"finding":"must reach synthesizer"}] -direct_extractor_capture_is_null=True -native_extractor_capture_is_null=False -cleanup_exit=0 -routing_outcomes_retained=False -cleanup_workspace=C:\Users\antho\AppData\Local\Temp\offload-research-1efd6d8ee4cd44ec84e557f101930ecb diff --git a/.scratch/offload-review-remediation/evidence/review.md b/.scratch/offload-review-remediation/evidence/review.md deleted file mode 100644 index 74f8636..0000000 --- a/.scratch/offload-review-remediation/evidence/review.md +++ /dev/null @@ -1,225 +0,0 @@ -# Whole-skill review - -Reviewed 2026-09-03 against `cfc9f4e` in `D:/dreiOS/Projects/offload`. - -The modular router and central model policy are worth keeping. The skill's main weakness is the connection between its instructions and its helpers. Ordinary parallel execution fails scope checks, PowerShell research handoffs lose their output, and several verification paths accept incomplete evidence. I would fix these before relying on unattended runs. - -This is a review, with no source changes. Thirteen confirmed findings follow. P1 means fix before relying on the affected workflow. P2 means a concrete correctness or verification gap that should follow. All findings have high confidence. The review used lint-skills and writing-for-agents for instructions, plus direct code inspection and disposable reproductions for runtime behavior. - -## Coverage - -The audited unit is the user-owned source repository, classified as owned-local. The installed skill is a tracked copy; it was used to launch isolated workers and was not edited. Usage counts and the user's global skill registry were outside this repository review. No skills-ledger.md was present. - -| Unit | Status | Findings | -|---|---|---| -| SKILL.md, 205 lines | Clear mode routing; routing-record contract mismatch | F-11 | -| modes/execution.md | Verification and concurrency defects | F-02, F-03, F-04, F-05 | -| modes/repo-research.md | Broken PowerShell setup and record retention | F-01, F-10 | -| modes/web-research.md | Handoff, acceptance, partial-result, and retry defects | F-01, F-05, F-11, F-12, F-13 | -| Model policy and policy validation | No additional confirmed defect in the supported default routes | None | -| Launcher pair | PowerShell child lifetime defect | F-07 | -| Execution scope helper pair | Shared-tree accounting, committed edits, Bash failure handling | F-02, F-03, F-06 | -| Workspace creation and extraction helpers | PowerShell output contract mismatch | F-01 | -| Provenance helpers | Documented input disagrees with validator | F-11 | -| Cleanup helper pair | Routing history loss; PowerShell junction traversal | F-08, F-10 | -| Tests | Fifty PowerShell test groups do not execute | F-09 | -| README, context, specs, ADRs | Read for intent and consistency; no separate additional finding | None | - -## Confirmed findings - -### F-01 · P1 · PowerShell research commands cannot capture helper output - -Location: [make-research-workspace.ps1:170](D:/dreiOS/Projects/offload/scripts/make-research-workspace.ps1:170), [extract-structured-output.ps1:77](D:/dreiOS/Projects/offload/scripts/extract-structured-output.ps1:77), [repo-research.md:40](D:/dreiOS/Projects/offload/modes/repo-research.md:40), [web-research.md:211](D:/dreiOS/Projects/offload/modes/web-research.md:211). - -Both helpers write through `[Console]::Out`. The documented `& script.ps1` invocation captures PowerShell pipeline output, so the workspace expression calls `.Trim()` on null. The synthesis expression silently assigns null and loses researcher evidence. I encountered the workspace failure while starting this review. A separate extraction reproduction printed valid JSON to the console while the assigned variable remained null. Calling the helper as a native `pwsh -File` process captured the same output successfully. - -Fix the helpers to emit pipeline values, or consistently invoke them through a native subprocess. Test the exact documented assignment expressions, including nonempty merged findings. - -Lever: false capability claim. Kind: structural. Provenance: orchestrator, reproduced. - -### F-02 · P1 · Parallel implementers fail each other's ownership checks - -Location: [execution.md:136](D:/dreiOS/Projects/offload/modes/execution.md:136), [execution.md:178](D:/dreiOS/Projects/offload/modes/execution.md:178), [check-execution-scope.ps1:145](D:/dreiOS/Projects/offload/scripts/check-execution-scope.ps1:145), [check-execution-scope.sh:122](D:/dreiOS/Projects/offload/scripts/check-execution-scope.sh:122). - -The workflow dispatches independent workers into the same working tree, then checks each worker against its own owned paths. Both helpers read the entire current working tree. With worker A changing only a.txt and worker B changing only b.txt, A's check reports b.txt and B's check reports a.txt. Both exit 1 even though ownership was respected. - -Give each worker an isolated worktree and verify before integration, or redesign the batch workflow with explicit attribution. Passing the union of all owned files loses the promised per-worker ownership guarantee. - -Lever: false capability claim. Kind: structural. Provenance: orchestrator+checked, reproduced. - -### F-03 · P1 · Committed changes bypass ownership and frozen-path protection - -Location: [check-execution-scope.ps1:145](D:/dreiOS/Projects/offload/scripts/check-execution-scope.ps1:145), [check-execution-scope.sh:138](D:/dreiOS/Projects/offload/scripts/check-execution-scope.sh:138), [execution.md:132](D:/dreiOS/Projects/offload/modes/execution.md:132). - -Both scope helpers inspect `git status` without a recorded baseline revision. After a worker modifies a frozen gate and commits it, status is clean and the scope check exits 0. Freezing gates with a commit does not prevent this. The workflow also needs to verify gate-author changes before treating the resulting tree as the untouched baseline. - -Record an immutable baseline before each writing stage. Account for committed, staged, unstaged, and new files, and verify frozen contents against that baseline. A prompt telling workers not to commit would not replace this check. - -Lever: false capability claim. Kind: structural. Provenance: orchestrator+checked, reproduced. - -### F-04 · P1 · Diff review omits staged changes and new files - -Location: [execution.md:216](D:/dreiOS/Projects/offload/modes/execution.md:216), [execution.md:232](D:/dreiOS/Projects/offload/modes/execution.md:232), [execution.md:242](D:/dreiOS/Projects/offload/modes/execution.md:242). - -Reviewers run bare `git diff`, and the orchestrator matches quotes against the same command. It excludes staged changes and untracked files. In the reproduction, one staged edit and one new file produced zero diff lines. A larger change can therefore pass checks on its unstaged portion while other changed content never reaches the reviewer. - -Build one complete review artifact against the recorded baseline, explicitly including new files. Give that same artifact to the reviewer and quote verifier. - -Lever: false capability claim. Kind: structural. Provenance: orchestrator+checked, reproduced. - -### F-05 · P1 · Empty review and audit results satisfy acceptance rules - -Location: [execution.md:210](D:/dreiOS/Projects/offload/modes/execution.md:210), [execution.md:246](D:/dreiOS/Projects/offload/modes/execution.md:246), [web-research.md:292](D:/dreiOS/Projects/offload/modes/web-research.md:292), [web-research.md:306](D:/dreiOS/Projects/offload/modes/web-research.md:306). - -The reviewer schema accepts `{"criteria":[]}`. The auditor schema accepts `{"citation_audits":[],"final_status":"pass"}`. Both passed PowerShell's JSON Schema validation against the literal schemas in the documents. Execution accepts when all returned quotes match, without requiring every requested criterion. Web research accepts the auditor's pass status without matching audits to the claim ledger. - -Assign criterion IDs and require exactly one verdict per requested ID. Match audit entries to every required claim/citation pair, reject missing or duplicate entries, and check that individual verdicts agree with the overall status. Adding only minItems would still allow partial coverage. - -Lever: false capability claim. Kind: structural. Provenance: orchestrator, schema reproduction and instruction inspection. - -### F-06 · P2 · Bash scope verification reports success when git status fails - -Location: [check-execution-scope.sh:138](D:/dreiOS/Projects/offload/scripts/check-execution-scope.sh:138). - -The process substitution feeding the touched-path loop does not propagate a failed `git status` exit. A controlled mock returning exit 73 for that command caused the helper to print the error and then return 0. PowerShell already checks the child exit status. - -Capture status output with an explicitly checked exit code before parsing its NUL-delimited records. Add a failure-path test. - -Lever: false capability claim. Kind: structural. Provenance: orchestrator+checked, reproduced with a mock, not a damaged repository. - -### F-07 · P2 · PowerShell launcher leaves a worker running after output setup fails - -Location: [run-agy-json.ps1:408](D:/dreiOS/Projects/offload/scripts/run-agy-json.ps1:408). - -The launcher starts AGY before opening its output and error streams. Stream creation happens outside the cleanup block. When both paths point to the same file, the second open throws and the launcher exits, while the child keeps running. A disposable fake worker wrote its completion marker after the launcher had already failed. - -Validate output paths and open both streams before launch. Ensure every post-launch failure terminates or explicitly hands off the child and disposes resources. Cover locked or invalid destinations as well as identical paths. - -Lever: false capability claim. Kind: structural. Provenance: orchestrator+checked, reproduced. - -### F-08 · P2 · PowerShell cleanup traverses nested junctions outside the workspace - -Location: [cleanup-research-workspace.ps1:122](D:/dreiOS/Projects/offload/scripts/cleanup-research-workspace.ps1:122). - -The helper checks whether each top-level entry is a reparse point, then recursively enumerates all files below ordinary directories to clear read-only attributes. That enumeration follows nested junctions. In a disposable reproduction, repo/nested-link pointed to a sibling directory outside the cleanup workspace. Cleanup changed the sibling file from read-only to normal, then failed to delete the junction. The file remained; external deletion was not observed. - -Walk directories without following reparse points at any depth. Remove links themselves and change attributes only on files whose traversal remains inside the workspace. - -Lever: false capability claim. Kind: structural. Provenance: orchestrator+checked, reproduced entirely under the audit's temporary directory. - -### F-09 · P2 · Fifty PowerShell model-routing test groups never execute - -Location: [test_model_routing.ps1:366](D:/dreiOS/Projects/offload/tests/test_model_routing.ps1:366). - -Fifty groups are bare `{ ... }` expressions, which create and print ScriptBlock objects. They do not run the contained assertions. The suite exits 0 after reporting 147 assertions from the executed portions, while later coverage for invalid policies, invocation forms, escalation, and exit contracts is skipped. - -Invoke those blocks or remove their outer braces. Check that a deliberate assertion failure inside a representative group makes the suite fail. The AST-derived list of all 50 groups is saved beside this report. - -Lever: false capability claim. Kind: structural. Provenance: orchestrator, observed suite output and AST inspection. - -### F-10 · P2 · Successful cleanup deletes required routing history - -Location: [cleanup-research-workspace.ps1:111](D:/dreiOS/Projects/offload/scripts/cleanup-research-workspace.ps1:111), [cleanup-research-workspace.sh:130](D:/dreiOS/Projects/offload/scripts/cleanup-research-workspace.sh:130), [SKILL.md:120](D:/dreiOS/Projects/offload/SKILL.md:120). - -The root contract requires routing-outcomes.json in the scratch workspace, but success cleanup retains only final.md, provenance.json, and the marker. A reproduction confirmed routing-outcomes.json was deleted. Web provenance embeds routing only optionally; repository research has no mandatory archival step. - -Preserve routing-outcomes.json, or require a verified archival merge before cleanup. Preserve enough evidence to interpret retained attempt paths. Removing raw scratch files on success is an accepted design choice; losing the required history is the defect. - -Lever: duplication, conflicting contracts. Kind: structural. Provenance: orchestrator+checked, reproduced. - -### F-11 · P2 · Documented routing provenance has the wrong JSON shape - -Location: [SKILL.md:143](D:/dreiOS/Projects/offload/SKILL.md:143), [web-research.md:325](D:/dreiOS/Projects/offload/modes/web-research.md:325), [collect-provenance.ps1:214](D:/dreiOS/Projects/offload/scripts/collect-provenance.ps1:214). - -The instructions attach the individual attempt record as a worker's routing object. Both validators expect a container with schema_version and attempts. The documented shape failed with "routing missing required schema_version"; wrapping the same record in `{"schema_version":1,"attempts":[...]}` succeeded. - -Choose one shape and show a complete example used by both shell tests. Prefer a worker-level container that retains both attempts. - -Lever: duplication, conflicting contracts. Kind: structural. Provenance: orchestrator+checked, reproduced. - -### F-12 · P2 · Failed researcher files block the documented partial-success path - -Location: [web-research.md:197](D:/dreiOS/Projects/offload/modes/web-research.md:197), [web-research.md:210](D:/dreiOS/Projects/offload/modes/web-research.md:210), [web-research.md:316](D:/dreiOS/Projects/offload/modes/web-research.md:316). - -Synthesis may continue after a researcher exhausts retries if two independent angles remain. The preparation snippets instead glob every researcher-*.json, including failed results. Two valid result files plus one ERROR envelope made extraction exit 2. - -Build the merge input from verified successful attempts, explicitly exclude failed and superseded artifacts, then check the surviving evidence-angle count. Keep failed files for diagnostics. - -Lever: false capability claim. Kind: structural. Provenance: orchestrator+checked, reproduced. - -### F-13 · P2 · Retry examples overwrite the artifacts referenced by attempt history - -Location: [web-research.md:200](D:/dreiOS/Projects/offload/modes/web-research.md:200), [web-research.md:279](D:/dreiOS/Projects/offload/modes/web-research.md:279), [web-research.md:307](D:/dreiOS/Projects/offload/modes/web-research.md:307), [run-agy-json.ps1:413](D:/dreiOS/Projects/offload/scripts/run-agy-json.ps1:413). - -The one-revision loop reuses synthesizer.json and auditor.json. Both launchers truncate existing destinations. Repeating the documented dispatch replaces attempt 1's output, so an earlier routing record can point to attempt 2's evidence. - -Keep worker identity stable while making artifact paths attempt-specific, such as synthesizer.attempt-1.json and synthesizer.attempt-2.json. Record those paths and explicitly select the accepted attempt for downstream stages. - -Lever: information hierarchy, incomplete lifecycle instructions. Kind: structural. Provenance: orchestrator+checked, direct code and workflow inspection. - -## Instruction quality - -The 205-line root router meets the progressive-disclosure goal. The mode boundaries, bounded research assignments, retry ceiling, and distinction between operational and quality failures are useful. Keep the explicit statements that plan mode is only a behavioral hint and add-dir is not confinement. - -The description ends with a workflow summary and allows research fan-out across "angles or files". The body and context contract make distinct work lanes the threshold and keep focused reviews local. Tighten the description to those trigger boundaries and remove the process summary. This is minor compared with the runtime findings. - -The best next investment is a small set of executable workflow checks that run the documented shell handoffs. More repeated prose about verification will not catch F-01 or F-09. Keep policy definitions central and link to complete record examples so future changes do not recreate F-10 and F-11. - -## Verification performed - -All nine existing test entry points exited 0. Five ran in PowerShell 7. Four ran under Git Bash on Windows. - -| Entry point | Observed result | -|---|---| -| tests/test_research_helpers.ps1 | Exit 0, 130 assertions | -| tests/test_execution_scope.ps1 | Exit 0, 103 assertions | -| tests/test_model_routing.ps1 | Exit 0, 147 executed assertions, 50 uninvoked groups | -| tests/test_workflow_static.ps1 | Exit 0, 72 assertions | -| tests/test_routing_provenance.ps1 | Exit 0, 40 assertions | -| tests/test_agy_helpers.sh | Exit 0 | -| tests/test_execution_scope.sh | Exit 0 | -| tests/test_research_modes.sh | Exit 0 | -| tests/test_model_routing.sh | Exit 0 | - -Native Linux, macOS, and Bash 3.2 were not exercised. This was not a live web-research run or a quality comparison between models. - -Additional disposable reproductions checked shared-tree scope, committed frozen changes, staged/new diff omissions, pipeline capture, Git failure propagation, schema acceptance, cleanup retention, provenance shape, partial-result merging, junction traversal, and child lifetime after launcher failure. - -Evidence is in repro.log, bash-status-repro.log, repro-research.log, repro-helpers.log, and uninvoked-test-blocks.json beside this report. Reproduction scripts are also retained. Do not rerun them indiscriminately against existing fixture directories. - -## Offload run - -Three isolated AGY researchers used gemini-3.8-flash-high, one attempt each. The longest lane took about 6 minutes 56 seconds. I inspected all 18 returned claims against live source and adjusted severity myself. No lower-priority finding was accepted solely through sampling. - -| Worker | Lane | Provenance | Result | -|---|---|---|---| -| execution | Execution safety | orchestrator+checked | Three findings accepted; gate-author concern narrowed into F-03; two claims not adopted | -| helpers | Shell helpers and parity | orchestrator+checked | Three findings accepted; two lower-impact observations retained below; one dangling-link claim unverified | -| research | Evidence and provenance | orchestrator+checked | Four findings accepted; syntax claim refuted; scalar-splat edge case excluded from supported workflow findings | - -All scoped snapshot files still matched the source after the workers finished. Returned SUCCESS statuses were not treated as verification. - -Rejected or limited claims: - -- The alleged trailing backslash in the PowerShell auditor command is absent. The source uses backticks, and its code block parses. -- Scalar string splatting does expand to characters, but the claimed single-result synthesis path does not meet the workflow's requirement for two surviving independent angles. F-01 is the actual supported-path failure. -- A retry does not necessarily require throwing away the previous attempt's work. The lack of a prescribed rollback alone is not a confirmed defect. -- The absence of a final implementer commit is not independently a bug. A workflow may intentionally leave verified changes for its caller. -- Gate-author scope checking needs attention, but the worker overstated a standalone failure. The clean-tree requirement catches ordinary uncommitted stray changes; baseline and committed-change protection are covered by F-03. -- The helper worker's proposed index.lock reproduction was not used as proof. F-06 was demonstrated with a controlled failing git-status mock. -- Whitespace-only AGY_BIN falls back in PowerShell according to source inspection, while Bash rejects it. This is a lower-impact configuration inconsistency, not promoted to the main findings. -- Bash provenance routing validation lacks the dedicated counterpart of the PowerShell routing-provenance suite. This is a coverage observation, not proof of another runtime defect. -- The dangling-link claim remains unverified. Automatic approval review blocked the follow-up disposable test with "blocked by policy" and no further reason. It is excluded from confirmed findings. - -Raw worker results, process timings, per-claim decisions, and source-attributed token usage are retained beside the report in routing-outcomes.json and verification.json. No retries were needed to finish the review locally. - -## Recommended fix order - -1. Repair PowerShell handoffs and activate the dormant test groups. -2. Define isolated execution and immutable baselines, then generate complete review artifacts. -3. Enforce criterion and citation coverage before accepting results. -4. Fix launcher failure cleanup, nested junction handling, and Bash failure propagation. -5. Align provenance shapes, attempt filenames, successful-input selection, and retention. - -The source repository remains unchanged. - diff --git a/.scratch/offload-review-remediation/evidence/uninvoked-test-blocks.json b/.scratch/offload-review-remediation/evidence/uninvoked-test-blocks.json deleted file mode 100644 index bbf31c0..0000000 --- a/.scratch/offload-review-remediation/evidence/uninvoked-test-blocks.json +++ /dev/null @@ -1,202 +0,0 @@ -[ - { - "start": 366, - "end": 385 - }, - { - "start": 394, - "end": 416 - }, - { - "start": 419, - "end": 438 - }, - { - "start": 441, - "end": 458 - }, - { - "start": 465, - "end": 484 - }, - { - "start": 487, - "end": 508 - }, - { - "start": 511, - "end": 529 - }, - { - "start": 536, - "end": 551 - }, - { - "start": 554, - "end": 569 - }, - { - "start": 572, - "end": 587 - }, - { - "start": 590, - "end": 605 - }, - { - "start": 608, - "end": 622 - }, - { - "start": 625, - "end": 639 - }, - { - "start": 646, - "end": 659 - }, - { - "start": 662, - "end": 676 - }, - { - "start": 679, - "end": 693 - }, - { - "start": 696, - "end": 709 - }, - { - "start": 712, - "end": 727 - }, - { - "start": 730, - "end": 744 - }, - { - "start": 747, - "end": 762 - }, - { - "start": 765, - "end": 779 - }, - { - "start": 782, - "end": 798 - }, - { - "start": 801, - "end": 816 - }, - { - "start": 823, - "end": 838 - }, - { - "start": 841, - "end": 855 - }, - { - "start": 862, - "end": 877 - }, - { - "start": 880, - "end": 895 - }, - { - "start": 898, - "end": 913 - }, - { - "start": 916, - "end": 931 - }, - { - "start": 934, - "end": 949 - }, - { - "start": 952, - "end": 967 - }, - { - "start": 970, - "end": 985 - }, - { - "start": 988, - "end": 1005 - }, - { - "start": 1008, - "end": 1023 - }, - { - "start": 1026, - "end": 1041 - }, - { - "start": 1044, - "end": 1082 - }, - { - "start": 1085, - "end": 1123 - }, - { - "start": 1126, - "end": 1166 - }, - { - "start": 1171, - "end": 1250 - }, - { - "start": 1257, - "end": 1282 - }, - { - "start": 1285, - "end": 1299 - }, - { - "start": 1302, - "end": 1315 - }, - { - "start": 1318, - "end": 1330 - }, - { - "start": 1333, - "end": 1347 - }, - { - "start": 1350, - "end": 1364 - }, - { - "start": 1367, - "end": 1378 - }, - { - "start": 1381, - "end": 1391 - }, - { - "start": 1394, - "end": 1404 - }, - { - "start": 1407, - "end": 1437 - }, - { - "start": 1440, - "end": 1455 - } -] diff --git a/.scratch/offload-review-remediation/evidence/verification.json b/.scratch/offload-review-remediation/evidence/verification.json deleted file mode 100644 index f44bb74..0000000 --- a/.scratch/offload-review-remediation/evidence/verification.json +++ /dev/null @@ -1,129 +0,0 @@ -{ - "reviewed_commit": "cfc9f4e", - "verification_method": "Every worker claim inspected against live source. Runtime reproductions for accepted failure modes where practical. No claims accepted from worker status alone.", - "workers": [ - { - "worker_id": "execution", - "finding_decisions": [ - { - "index": 1, - "status": "accepted", - "finding": "F-02" - }, - { - "index": 2, - "status": "accepted", - "finding": "F-03" - }, - { - "index": 3, - "status": "not_adopted", - "reason": "Retry rollback is not inherently required; retaining partial work can be correct." - }, - { - "index": 4, - "status": "accepted", - "finding": "F-04" - }, - { - "index": 5, - "status": "narrowed", - "finding": "F-03", - "reason": "Ordinary uncommitted stray changes conflict with clean-tree precondition; immutable baseline and gate-author checks still needed." - }, - { - "index": 6, - "status": "not_adopted", - "reason": "No requirement that orchestrator commit final changes; lack of commit is not independently a defect." - } - ] - }, - { - "worker_id": "helpers", - "finding_decisions": [ - { - "index": 1, - "status": "accepted", - "finding": "F-06", - "reason": "Reproduced with controlled failing git-status mock; suggested index.lock command not relied on." - }, - { - "index": 2, - "status": "unverified", - "reason": "Follow-up disposable dangling-junction test was rejected by automatic approval policy. No confirmed failure included." - }, - { - "index": 3, - "status": "accepted", - "finding": "F-08", - "reason": "Reproduced external readonly attribute mutation; did not observe external file deletion." - }, - { - "index": 4, - "status": "accepted", - "finding": "F-07", - "reason": "Reproduced child completion after output-open failure using fake worker." - }, - { - "index": 5, - "status": "lower_impact_observation", - "reason": "Source confirms whitespace override falls back; not promoted to main defect list." - }, - { - "index": 6, - "status": "coverage_observation", - "reason": "No dedicated Bash routing-provenance tests found; not itself proof of another runtime defect." - } - ] - }, - { - "worker_id": "research", - "finding_decisions": [ - { - "index": 1, - "status": "refuted", - "reason": "Actual auditor command uses backticks and parses without errors." - }, - { - "index": 2, - "status": "not_adopted", - "reason": "Scalar splat behavior reproduced, but one surviving evidence angle does not meet supported synthesis preconditions." - }, - { - "index": 3, - "status": "accepted_narrowed", - "finding": "F-10", - "reason": "Required routing history deletion confirmed; raw scratch deletion on success is intentional." - }, - { - "index": 4, - "status": "accepted", - "finding": "F-12" - }, - { - "index": 5, - "status": "accepted", - "finding": "F-11" - }, - { - "index": 6, - "status": "accepted", - "finding": "F-13" - } - ] - } - ], - "orchestrator_findings": [ - "F-01", - "F-05", - "F-09" - ], - "final_findings_count": 13, - "tests": { - "entry_points": 9, - "all_exit_zero": true, - "powershell_assertions_reported": 492, - "uninvoked_powershell_blocks": 50 - }, - "source_edits": false -} diff --git a/.scratch/offload-review-remediation/github-issues.json b/.scratch/offload-review-remediation/github-issues.json deleted file mode 100644 index 2f7e03e..0000000 --- a/.scratch/offload-review-remediation/github-issues.json +++ /dev/null @@ -1,86 +0,0 @@ -[ - { - "id": "01", - "number": 3, - "url": "https://github.com/anthonyandrei/offload/issues/3", - "title": "Execute every PowerShell model-routing test group" - }, - { - "id": "02", - "number": 4, - "url": "https://github.com/anthonyandrei/offload/issues/4", - "title": "Make documented PowerShell research handoffs return usable values" - }, - { - "id": "03", - "number": 5, - "url": "https://github.com/anthonyandrei/offload/issues/5", - "title": "Check committed and working-tree edits against a fixed baseline" - }, - { - "id": "04", - "number": 6, - "url": "https://github.com/anthonyandrei/offload/issues/6", - "title": "Add a verified lifecycle for isolated execution worktrees" - }, - { - "id": "05", - "number": 7, - "url": "https://github.com/anthonyandrei/offload/issues/7", - "title": "Run execution stages through isolated workspaces and retire shared-tree dispatch" - }, - { - "id": "06", - "number": 8, - "url": "https://github.com/anthonyandrei/offload/issues/8", - "title": "Review one complete change artifact against the execution baseline" - }, - { - "id": "07", - "number": 9, - "url": "https://github.com/anthonyandrei/offload/issues/9", - "title": "Require one valid reviewer verdict for every requested criterion" - }, - { - "id": "08", - "number": 10, - "url": "https://github.com/anthonyandrei/offload/issues/10", - "title": "Require audit coverage for every claim and citation pair" - }, - { - "id": "09", - "number": 11, - "url": "https://github.com/anthonyandrei/offload/issues/11", - "title": "Prevent orphaned workers when PowerShell output setup fails" - }, - { - "id": "10", - "number": 12, - "url": "https://github.com/anthonyandrei/offload/issues/12", - "title": "Keep PowerShell cleanup inside the marked workspace" - }, - { - "id": "11", - "number": 13, - "url": "https://github.com/anthonyandrei/offload/issues/13", - "title": "Make routing provenance examples match both validators" - }, - { - "id": "12", - "number": 14, - "url": "https://github.com/anthonyandrei/offload/issues/14", - "title": "Give every worker attempt distinct evidence paths" - }, - { - "id": "13", - "number": 15, - "url": "https://github.com/anthonyandrei/offload/issues/15", - "title": "Continue synthesis from verified successful research angles" - }, - { - "id": "14", - "number": 16, - "url": "https://github.com/anthonyandrei/offload/issues/16", - "title": "Preserve routing history and explain pruned evidence after success" - } -] diff --git a/.scratch/offload-review-remediation/github-publication.json b/.scratch/offload-review-remediation/github-publication.json deleted file mode 100644 index fa23c39..0000000 --- a/.scratch/offload-review-remediation/github-publication.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "status": "verified", - "repository": "anthonyandrei/offload", - "issues": 14, - "ready": 7, - "verified_at": "2026-09-03T04:29:34.3766379+08:00" -} diff --git a/.scratch/offload-review-remediation/github/01-body.md b/.scratch/offload-review-remediation/github/01-body.md deleted file mode 100644 index 33dce98..0000000 --- a/.scratch/offload-review-remediation/github/01-body.md +++ /dev/null @@ -1,52 +0,0 @@ - - -Blocked by: None - -Priority: P2. Review findings: F-09. Remediation ticket 01 of 14. - -Reviewed 2026-09-03 against [cfc9f4e](https://github.com/anthonyandrei/offload/commit/cfc9f4edc219b199c5c243c95f91fa2c463d137d). - -## Problem - -Fifty bare script blocks in tests/test_model_routing.ps1 create ScriptBlock objects without running their assertions. The existing green result covers only the invoked portions. - -## Deliverable - -Invoke the dormant groups and make their failures propagate to the test command. Keep the existing test intent and isolate each fixture as needed. - -## Acceptance criteria - -- [ ] Every one of the 50 groups listed in the Source evidence section below executes rather than printing its source. -- [ ] A deliberate assertion failure in a representative formerly dormant group makes a disposable copy of the suite exit nonzero. -- [ ] The ordinary suite exits zero after the exercised behavior is verified. Any newly exposed production defect is documented as a blocker instead of weakening or skipping its assertion. -- [ ] Test output distinguishes executed assertions from script text; the existing invoked assertions still run. - -## Source evidence - -- [tests/test_model_routing.ps1:366](https://github.com/anthonyandrei/offload/blob/cfc9f4edc219b199c5c243c95f91fa2c463d137d/tests/test_model_routing.ps1#L366) - -The audit identified these 50 uninvoked script-block line ranges in the linked test file at the reviewed revision: 366-385, 394-416, 419-438, 441-458, 465-484, 487-508, 511-529, 536-551, 554-569, 572-587, 590-605, 608-622, 625-639, 646-659, 662-676, 679-693, 696-709, 712-727, 730-744, 747-762, 765-779, 782-798, 801-816, 823-838, 841-855, 862-877, 880-895, 898-913, 916-931, 934-949, 952-967, 970-985, 988-1005, 1008-1023, 1026-1041, 1044-1082, 1085-1123, 1126-1166, 1171-1250, 1257-1282, 1285-1299, 1302-1315, 1318-1330, 1333-1347, 1350-1364, 1367-1378, 1381-1391, 1394-1404, 1407-1437, 1440-1455. - -## Implementation pointers - -- [tests/test_model_routing.ps1](https://github.com/anthonyandrei/offload/blob/cfc9f4edc219b199c5c243c95f91fa2c463d137d/tests/test_model_routing.ps1) - -New helper or test filenames under listed directories are implementation choices. - -## Verification - -Run pwsh -NoProfile -File tests/test_model_routing.ps1, plus the deliberate-failure check in a disposable copy. No live AGY call is needed. - -## Scope and constraints - -This ticket repairs test execution. Do not change model defaults, retry limits, or production behavior merely to turn the suite green. - -- Work in the source repository. Do not update installed skill copies as part of this issue. -- Preserve the Gemini model policy, role routing, maximum two attempts, and immediate quota handoff. -- Preserve Bash 3.2+ compatibility and native PowerShell 7 support. Add no Windows requirement for Bash, Python, or jq. -- Keep the root SKILL.md router below 500 lines; place detailed workflow contracts in the mode documents or supporting files. -- Use fake workers and disposable repositories for regressions. Verify resolved cleanup paths stay inside the test root. -- Shared-file edits still require serialized integration even when issues have no dependency edge. -- Do not use the existing shared-tree offload execution workflow for these fixes until its migration is complete. Use direct orchestration or independently verified isolated checkouts. - -The original review exercised PowerShell 7 and Git Bash on Windows. Native Linux, macOS, and Bash 3.2 were not exercised. Record the platforms used for this issue rather than claiming untested parity. diff --git a/.scratch/offload-review-remediation/github/02-body.md b/.scratch/offload-review-remediation/github/02-body.md deleted file mode 100644 index cf38184..0000000 --- a/.scratch/offload-review-remediation/github/02-body.md +++ /dev/null @@ -1,57 +0,0 @@ - - -Blocked by: None - -Priority: P1. Review findings: F-01. Remediation ticket 02 of 14. - -Reviewed 2026-09-03 against [cfc9f4e](https://github.com/anthonyandrei/offload/commit/cfc9f4edc219b199c5c243c95f91fa2c463d137d). - -## Problem - -The workspace and extraction helpers write to Console.Out, while the mode examples capture the PowerShell pipeline. Workspace.Trim() fails on null, and merged researcher evidence can silently become null. - -## Deliverable - -Make the helpers emit their result through the PowerShell pipeline and keep diagnostics on the error channel. Test the exact documented in-process assignments and native pwsh -File invocation. - -## Acceptance criteria - -- [ ] The documented workspace assignment returns one nonempty existing workspace path and .Trim() succeeds. -- [ ] The documented extraction assignment for two valid researcher envelopes returns nonempty JSON containing both findings. -- [ ] Both direct & invocation and native pwsh -File invocation return the same semantic payload without diagnostic text mixed into JSON. -- [ ] Invalid input still fails with the intended exit/error contract, and the mode examples match the tested commands. - -## Source evidence - -- [scripts/make-research-workspace.ps1:170](https://github.com/anthonyandrei/offload/blob/cfc9f4edc219b199c5c243c95f91fa2c463d137d/scripts/make-research-workspace.ps1#L170) -- [scripts/extract-structured-output.ps1:77](https://github.com/anthonyandrei/offload/blob/cfc9f4edc219b199c5c243c95f91fa2c463d137d/scripts/extract-structured-output.ps1#L77) -- [modes/repo-research.md:40](https://github.com/anthonyandrei/offload/blob/cfc9f4edc219b199c5c243c95f91fa2c463d137d/modes/repo-research.md#L40) -- [modes/web-research.md:211](https://github.com/anthonyandrei/offload/blob/cfc9f4edc219b199c5c243c95f91fa2c463d137d/modes/web-research.md#L211) - -## Implementation pointers - -- [scripts/make-research-workspace.ps1](https://github.com/anthonyandrei/offload/blob/cfc9f4edc219b199c5c243c95f91fa2c463d137d/scripts/make-research-workspace.ps1) -- [scripts/extract-structured-output.ps1](https://github.com/anthonyandrei/offload/blob/cfc9f4edc219b199c5c243c95f91fa2c463d137d/scripts/extract-structured-output.ps1) -- [modes/repo-research.md](https://github.com/anthonyandrei/offload/blob/cfc9f4edc219b199c5c243c95f91fa2c463d137d/modes/repo-research.md) -- [modes/web-research.md](https://github.com/anthonyandrei/offload/blob/cfc9f4edc219b199c5c243c95f91fa2c463d137d/modes/web-research.md) -- [tests/test_research_helpers.ps1](https://github.com/anthonyandrei/offload/blob/cfc9f4edc219b199c5c243c95f91fa2c463d137d/tests/test_research_helpers.ps1) - -New helper or test filenames under listed directories are implementation choices. - -## Verification - -Add workflow-shaped cases to tests/test_research_helpers.ps1 using disposable workspaces and fixture envelopes, then run that suite. - -## Scope and constraints - -Keep the Windows workflow native to PowerShell 7. Do not add Bash, jq, or Python dependencies. - -- Work in the source repository. Do not update installed skill copies as part of this issue. -- Preserve the Gemini model policy, role routing, maximum two attempts, and immediate quota handoff. -- Preserve Bash 3.2+ compatibility and native PowerShell 7 support. Add no Windows requirement for Bash, Python, or jq. -- Keep the root SKILL.md router below 500 lines; place detailed workflow contracts in the mode documents or supporting files. -- Use fake workers and disposable repositories for regressions. Verify resolved cleanup paths stay inside the test root. -- Shared-file edits still require serialized integration even when issues have no dependency edge. -- Do not use the existing shared-tree offload execution workflow for these fixes until its migration is complete. Use direct orchestration or independently verified isolated checkouts. - -The original review exercised PowerShell 7 and Git Bash on Windows. Native Linux, macOS, and Bash 3.2 were not exercised. Record the platforms used for this issue rather than claiming untested parity. diff --git a/.scratch/offload-review-remediation/github/03-body.md b/.scratch/offload-review-remediation/github/03-body.md deleted file mode 100644 index cafc59e..0000000 --- a/.scratch/offload-review-remediation/github/03-body.md +++ /dev/null @@ -1,56 +0,0 @@ - - -Blocked by: None - -Priority: P1. Review findings: F-03, F-06. Remediation ticket 03 of 14. - -Reviewed 2026-09-03 against [cfc9f4e](https://github.com/anthonyandrei/offload/commit/cfc9f4edc219b199c5c243c95f91fa2c463d137d). - -## Problem - -The scope helpers trust git status. A worker can commit a frozen or unowned edit and pass with a clean status. Bash also returns success when the git status command in process substitution fails. - -## Deliverable - -Expand the paired helper contract with an explicit immutable baseline revision. Compute the complete final delta against that revision and compare frozen contents with the baseline. Preserve the old call form only until #7 migrates callers. - -## Acceptance criteria - -- [ ] A committed unowned edit and a committed frozen edit both produce nonzero results even when git status is clean. -- [ ] Owned-only committed, staged, unstaged, and new-file changes pass; unowned or frozen changes in each applicable state fail. -- [ ] Renames and deletions check all affected paths, with existing path normalization and NUL-safe filename handling preserved. -- [ ] Missing or invalid supplied baselines fail; the helper never silently substitutes current HEAD for a supplied baseline. -- [ ] A mocked git status failure with exit 73, and failures of any other Git query used for verification, produce nonzero helper results. -- [ ] Both shell families expose equivalent baseline semantics and diagnostics. - -## Source evidence - -- [scripts/check-execution-scope.ps1:145](https://github.com/anthonyandrei/offload/blob/cfc9f4edc219b199c5c243c95f91fa2c463d137d/scripts/check-execution-scope.ps1#L145) -- [scripts/check-execution-scope.sh:138](https://github.com/anthonyandrei/offload/blob/cfc9f4edc219b199c5c243c95f91fa2c463d137d/scripts/check-execution-scope.sh#L138) - -## Implementation pointers - -- [scripts/check-execution-scope.ps1](https://github.com/anthonyandrei/offload/blob/cfc9f4edc219b199c5c243c95f91fa2c463d137d/scripts/check-execution-scope.ps1) -- [scripts/check-execution-scope.sh](https://github.com/anthonyandrei/offload/blob/cfc9f4edc219b199c5c243c95f91fa2c463d137d/scripts/check-execution-scope.sh) -- [tests/test_execution_scope.ps1](https://github.com/anthonyandrei/offload/blob/cfc9f4edc219b199c5c243c95f91fa2c463d137d/tests/test_execution_scope.ps1) -- [tests/test_execution_scope.sh](https://github.com/anthonyandrei/offload/blob/cfc9f4edc219b199c5c243c95f91fa2c463d137d/tests/test_execution_scope.sh) - -New helper or test filenames under listed directories are implementation choices. - -## Verification - -Extend and run both execution-scope suites with temporary Git repositories and controlled Git failure mocks. Check final content relative to the captured baseline, not a worker-reported revision. - -## Scope and constraints - -This is the expand stage. Temporary compatibility is not sufficient to close F-03; #7 must require the baseline in every execution workflow. Worktrees and baseline checks are not an OS write sandbox. - -- Work in the source repository. Do not update installed skill copies as part of this issue. -- Preserve the Gemini model policy, role routing, maximum two attempts, and immediate quota handoff. -- Preserve Bash 3.2+ compatibility and native PowerShell 7 support. Add no Windows requirement for Bash, Python, or jq. -- Keep the root SKILL.md router below 500 lines; place detailed workflow contracts in the mode documents or supporting files. -- Use fake workers and disposable repositories for regressions. Verify resolved cleanup paths stay inside the test root. -- Shared-file edits still require serialized integration even when issues have no dependency edge. -- Do not use the existing shared-tree offload execution workflow for these fixes until its migration is complete. Use direct orchestration or independently verified isolated checkouts. - -The original review exercised PowerShell 7 and Git Bash on Windows. Native Linux, macOS, and Bash 3.2 were not exercised. Record the platforms used for this issue rather than claiming untested parity. diff --git a/.scratch/offload-review-remediation/github/04-body.md b/.scratch/offload-review-remediation/github/04-body.md deleted file mode 100644 index fe8d317..0000000 --- a/.scratch/offload-review-remediation/github/04-body.md +++ /dev/null @@ -1,55 +0,0 @@ - - -Blocked by: #5 - -Priority: P1. Review findings: F-02. Remediation ticket 04 of 14. - -Reviewed 2026-09-03 against [cfc9f4e](https://github.com/anthonyandrei/offload/commit/cfc9f4edc219b199c5c243c95f91fa2c463d137d). - -## Problem - -Per-worker ownership cannot be checked reliably while multiple writers share one working tree. The execution workflow needs a small, tested mechanism for creating isolated candidates and importing only their verified changes. - -## Deliverable - -Add paired shell-native execution-workspace helpers with a narrow create, verify/export, integrate, and cleanup contract. Store an orchestrator-owned manifest outside the worker checkout with task identity, absolute paths, baseline revision, and owned/frozen paths. Keep this beside the current workflow until #7. - -## Acceptance criteria - -- [ ] Two workers starting from the same baseline can independently edit a.txt and b.txt, and each scope check passes against only its own candidate. -- [ ] An unowned or frozen change in either candidate blocks export/integration, including when the worker has committed it. -- [ ] Export captures committed and uncommitted final changes and records a content digest; integration consumes only that verified artifact. -- [ ] Integration into a disposable integration checkout preflights the whole change, detects conflicts, and retains candidates on failure without partially publishing changes to the caller checkout. -- [ ] Creation and cleanup only operate on manifest-owned paths; no existing caller checkout or unrelated worktree is reset, cleaned, or removed. -- [ ] The paired helpers pass equivalent disposable-repository cases and add no Windows dependency beyond PowerShell 7 and Git. - -## Source evidence - -- [modes/execution.md:136](https://github.com/anthonyandrei/offload/blob/cfc9f4edc219b199c5c243c95f91fa2c463d137d/modes/execution.md#L136) -- [modes/execution.md:178](https://github.com/anthonyandrei/offload/blob/cfc9f4edc219b199c5c243c95f91fa2c463d137d/modes/execution.md#L178) - -## Implementation pointers - -- [scripts/](https://github.com/anthonyandrei/offload/tree/cfc9f4edc219b199c5c243c95f91fa2c463d137d/scripts/) -- [tests/](https://github.com/anthonyandrei/offload/tree/cfc9f4edc219b199c5c243c95f91fa2c463d137d/tests/) -- [docs/adr/](https://github.com/anthonyandrei/offload/tree/cfc9f4edc219b199c5c243c95f91fa2c463d137d/docs/adr/) - -New helper or test filenames under listed directories are implementation choices. - -## Verification - -Add focused lifecycle suites for both shells using fake workers. Exercise two sibling tasks, a scope violation, an integration conflict, and cleanup ownership guards. - -## Scope and constraints - -This is an additive workspace capability. Keep its interface small enough for #7 to use directly. Do not build a general scheduler or change the model policy. Record the worktree decision in a short ADR. - -- Work in the source repository. Do not update installed skill copies as part of this issue. -- Preserve the Gemini model policy, role routing, maximum two attempts, and immediate quota handoff. -- Preserve Bash 3.2+ compatibility and native PowerShell 7 support. Add no Windows requirement for Bash, Python, or jq. -- Keep the root SKILL.md router below 500 lines; place detailed workflow contracts in the mode documents or supporting files. -- Use fake workers and disposable repositories for regressions. Verify resolved cleanup paths stay inside the test root. -- Shared-file edits still require serialized integration even when issues have no dependency edge. -- Do not use the existing shared-tree offload execution workflow for these fixes until its migration is complete. Use direct orchestration or independently verified isolated checkouts. - -The original review exercised PowerShell 7 and Git Bash on Windows. Native Linux, macOS, and Bash 3.2 were not exercised. Record the platforms used for this issue rather than claiming untested parity. diff --git a/.scratch/offload-review-remediation/github/05-body.md b/.scratch/offload-review-remediation/github/05-body.md deleted file mode 100644 index a0d94db..0000000 --- a/.scratch/offload-review-remediation/github/05-body.md +++ /dev/null @@ -1,66 +0,0 @@ - - -Blocked by: #5, #6 - -Priority: P1. Review findings: F-02, F-03. Remediation ticket 05 of 14. - -Reviewed 2026-09-03 against [cfc9f4e](https://github.com/anthonyandrei/offload/commit/cfc9f4edc219b199c5c243c95f91fa2c463d137d). - -## Problem - -Adding baseline and workspace helpers does not fix the existing instructions. Gate authors still write before an untouched baseline is established, and implementers still share the caller's tree. - -## Deliverable - -Migrate gate-author and implementer dispatch to #6's lifecycle. Verify gate authors against the original baseline before importing approved tests into an integration checkout. Freeze that gate baseline before creating implementer worktrees. Retire no-baseline scope calls and shared-tree writing examples. - -## Acceptance criteria - -- [ ] The documented Bash and PowerShell machine-gated flow completes with two disjoint fake implementers and imports both verified changes without sibling scope failures. -- [ ] A gate author that commits an unowned source edit is rejected before its output can become the implementation baseline. -- [ ] Implementers receive the approved frozen gates and an externally recorded baseline; committed gate edits are rejected. -- [ ] Overlapping assignments run serially from the newly accepted baseline, and all accepted deltas undergo scope and gate verification before publication to the caller. -- [ ] Retries retain the original verification baseline for that writing stage; a failed attempt never becomes an implicitly trusted baseline. -- [ ] Quota handoff records still-running candidates and artifacts immediately without waiting for sibling completion; normal cleanup waits for workers to stop. -- [ ] All execution-mode examples supply a baseline and isolated working directory, and the scope helpers reject omitted baselines after migration. -- [ ] A final combined gate check runs before publishing the integrated result; conflicts or failed gates leave the caller's existing work intact. - -## Source evidence - -- [modes/execution.md:90](https://github.com/anthonyandrei/offload/blob/cfc9f4edc219b199c5c243c95f91fa2c463d137d/modes/execution.md#L90) -- [modes/execution.md:132](https://github.com/anthonyandrei/offload/blob/cfc9f4edc219b199c5c243c95f91fa2c463d137d/modes/execution.md#L132) -- [modes/execution.md:136](https://github.com/anthonyandrei/offload/blob/cfc9f4edc219b199c5c243c95f91fa2c463d137d/modes/execution.md#L136) -- [modes/execution.md:178](https://github.com/anthonyandrei/offload/blob/cfc9f4edc219b199c5c243c95f91fa2c463d137d/modes/execution.md#L178) - -## Implementation pointers - -- [modes/execution.md](https://github.com/anthonyandrei/offload/blob/cfc9f4edc219b199c5c243c95f91fa2c463d137d/modes/execution.md) -- [SKILL.md](https://github.com/anthonyandrei/offload/blob/cfc9f4edc219b199c5c243c95f91fa2c463d137d/SKILL.md) -- [README.md](https://github.com/anthonyandrei/offload/blob/cfc9f4edc219b199c5c243c95f91fa2c463d137d/README.md) -- [AGENTS.md](https://github.com/anthonyandrei/offload/blob/cfc9f4edc219b199c5c243c95f91fa2c463d137d/AGENTS.md) -- [CLAUDE.md](https://github.com/anthonyandrei/offload/blob/cfc9f4edc219b199c5c243c95f91fa2c463d137d/CLAUDE.md) -- [CONTEXT.md](https://github.com/anthonyandrei/offload/blob/cfc9f4edc219b199c5c243c95f91fa2c463d137d/CONTEXT.md) -- [scripts/check-execution-scope.ps1](https://github.com/anthonyandrei/offload/blob/cfc9f4edc219b199c5c243c95f91fa2c463d137d/scripts/check-execution-scope.ps1) -- [scripts/check-execution-scope.sh](https://github.com/anthonyandrei/offload/blob/cfc9f4edc219b199c5c243c95f91fa2c463d137d/scripts/check-execution-scope.sh) -- [tests/test_workflow_static.ps1](https://github.com/anthonyandrei/offload/blob/cfc9f4edc219b199c5c243c95f91fa2c463d137d/tests/test_workflow_static.ps1) -- [tests/](https://github.com/anthonyandrei/offload/tree/cfc9f4edc219b199c5c243c95f91fa2c463d137d/tests/) - -New helper or test filenames under listed directories are implementation choices. - -## Verification - -Run executable workflow cases with fake AGY workers for both shell families, the scope suites, and relevant static checks. Inspect current architecture pointers for agreement with the migrated mode. - -## Scope and constraints - -This ticket is the migrate and contract stage for one execution mode. Use the helpers from #6 rather than adding another orchestration framework. Diff-review completeness and acceptance remain #8, #9. - -- Work in the source repository. Do not update installed skill copies as part of this issue. -- Preserve the Gemini model policy, role routing, maximum two attempts, and immediate quota handoff. -- Preserve Bash 3.2+ compatibility and native PowerShell 7 support. Add no Windows requirement for Bash, Python, or jq. -- Keep the root SKILL.md router below 500 lines; place detailed workflow contracts in the mode documents or supporting files. -- Use fake workers and disposable repositories for regressions. Verify resolved cleanup paths stay inside the test root. -- Shared-file edits still require serialized integration even when issues have no dependency edge. -- Do not use the existing shared-tree offload execution workflow for these fixes until its migration is complete. Use direct orchestration or independently verified isolated checkouts. - -The original review exercised PowerShell 7 and Git Bash on Windows. Native Linux, macOS, and Bash 3.2 were not exercised. Record the platforms used for this issue rather than claiming untested parity. diff --git a/.scratch/offload-review-remediation/github/06-body.md b/.scratch/offload-review-remediation/github/06-body.md deleted file mode 100644 index 64cad97..0000000 --- a/.scratch/offload-review-remediation/github/06-body.md +++ /dev/null @@ -1,55 +0,0 @@ - - -Blocked by: #7 - -Priority: P1. Review findings: F-04. Remediation ticket 06 of 14. - -Reviewed 2026-09-03 against [cfc9f4e](https://github.com/anthonyandrei/offload/commit/cfc9f4edc219b199c5c243c95f91fa2c463d137d). - -## Problem - -Bare git diff omits staged changes and new files. Reviewers and quote matching can agree on an incomplete diff and still miss part of a task. - -## Deliverable - -Produce one immutable review artifact from each verified candidate and its recorded baseline, then pass the identical artifact to the reviewer and quote verifier. Reuse the delta export from #6 where possible. - -## Acceptance criteria - -- [ ] A fixture containing a committed edit, staged edit, unstaged edit, and new file exposes every final change to review. -- [ ] Deletion and rename information is present, and binary changes are explicitly identified for direct review instead of silently omitted. -- [ ] The reviewer prompt reads the recorded artifact rather than running an independent bare git diff. -- [ ] Quote verification uses the exact artifact bytes or their verified digest; modifying the candidate after artifact creation cannot silently change the evidence being accepted. -- [ ] Git or artifact-generation failures prevent review acceptance, and both shells produce equivalent review coverage. - -## Source evidence - -- [modes/execution.md:216](https://github.com/anthonyandrei/offload/blob/cfc9f4edc219b199c5c243c95f91fa2c463d137d/modes/execution.md#L216) -- [modes/execution.md:232](https://github.com/anthonyandrei/offload/blob/cfc9f4edc219b199c5c243c95f91fa2c463d137d/modes/execution.md#L232) -- [modes/execution.md:242](https://github.com/anthonyandrei/offload/blob/cfc9f4edc219b199c5c243c95f91fa2c463d137d/modes/execution.md#L242) - -## Implementation pointers - -- [modes/execution.md](https://github.com/anthonyandrei/offload/blob/cfc9f4edc219b199c5c243c95f91fa2c463d137d/modes/execution.md) -- [scripts/](https://github.com/anthonyandrei/offload/tree/cfc9f4edc219b199c5c243c95f91fa2c463d137d/scripts/) -- [tests/](https://github.com/anthonyandrei/offload/tree/cfc9f4edc219b199c5c243c95f91fa2c463d137d/tests/) - -New helper or test filenames under listed directories are implementation choices. - -## Verification - -Add focused artifact-generation tests and execute the documented reviewer handoff with a fake reviewer. Compare the artifact's path/content coverage with the baseline delta. - -## Scope and constraints - -This ticket guarantees complete evidence. #9 adds exhaustive criterion coverage; do not treat successful quote lookup alone as sufficient acceptance. - -- Work in the source repository. Do not update installed skill copies as part of this issue. -- Preserve the Gemini model policy, role routing, maximum two attempts, and immediate quota handoff. -- Preserve Bash 3.2+ compatibility and native PowerShell 7 support. Add no Windows requirement for Bash, Python, or jq. -- Keep the root SKILL.md router below 500 lines; place detailed workflow contracts in the mode documents or supporting files. -- Use fake workers and disposable repositories for regressions. Verify resolved cleanup paths stay inside the test root. -- Shared-file edits still require serialized integration even when issues have no dependency edge. -- Do not use the existing shared-tree offload execution workflow for these fixes until its migration is complete. Use direct orchestration or independently verified isolated checkouts. - -The original review exercised PowerShell 7 and Git Bash on Windows. Native Linux, macOS, and Bash 3.2 were not exercised. Record the platforms used for this issue rather than claiming untested parity. diff --git a/.scratch/offload-review-remediation/github/07-body.md b/.scratch/offload-review-remediation/github/07-body.md deleted file mode 100644 index 6ecb948..0000000 --- a/.scratch/offload-review-remediation/github/07-body.md +++ /dev/null @@ -1,54 +0,0 @@ - - -Blocked by: #8 - -Priority: P1. Review findings: F-05. Remediation ticket 07 of 14. - -Reviewed 2026-09-03 against [cfc9f4e](https://github.com/anthonyandrei/offload/commit/cfc9f4edc219b199c5c243c95f91fa2c463d137d). - -## Problem - -The reviewer schema accepts an empty criteria array, and the workflow accepts when all returned quotes match. Empty or partial responses can therefore pass without addressing the task. - -## Deliverable - -Assign stable IDs to requested criteria and add a mechanical coverage check in both shell workflows before accepting any reviewer response. - -## Acceptance criteria - -- [ ] Empty output is rejected when criteria were requested. -- [ ] Missing, duplicate, and unknown criterion IDs are rejected, even when every returned quote exists in the artifact. -- [ ] Each requested criterion has exactly one verdict; fail or hedge prevents automated acceptance. -- [ ] Every pass has a literal matching evidence line from #8's artifact, with matching performed on data rather than interpolated shell code. -- [ ] A complete all-pass response with valid evidence is accepted, and malformed or incomplete responses route to direct orchestrator review. - -## Source evidence - -- [modes/execution.md:210](https://github.com/anthonyandrei/offload/blob/cfc9f4edc219b199c5c243c95f91fa2c463d137d/modes/execution.md#L210) -- [modes/execution.md:246](https://github.com/anthonyandrei/offload/blob/cfc9f4edc219b199c5c243c95f91fa2c463d137d/modes/execution.md#L246) - -## Implementation pointers - -- [modes/execution.md](https://github.com/anthonyandrei/offload/blob/cfc9f4edc219b199c5c243c95f91fa2c463d137d/modes/execution.md) -- [scripts/](https://github.com/anthonyandrei/offload/tree/cfc9f4edc219b199c5c243c95f91fa2c463d137d/scripts/) -- [tests/](https://github.com/anthonyandrei/offload/tree/cfc9f4edc219b199c5c243c95f91fa2c463d137d/tests/) - -New helper or test filenames under listed directories are implementation choices. - -## Verification - -Use fixed criterion sets and fake reviewer envelopes for empty, partial, duplicate, unknown, failed, hedged, forged-quote, and complete outputs. Exercise both documented shell flows. - -## Scope and constraints - -A minimum array length alone does not establish coverage. Preserve the existing direct-review fallback and bounded retry policy. - -- Work in the source repository. Do not update installed skill copies as part of this issue. -- Preserve the Gemini model policy, role routing, maximum two attempts, and immediate quota handoff. -- Preserve Bash 3.2+ compatibility and native PowerShell 7 support. Add no Windows requirement for Bash, Python, or jq. -- Keep the root SKILL.md router below 500 lines; place detailed workflow contracts in the mode documents or supporting files. -- Use fake workers and disposable repositories for regressions. Verify resolved cleanup paths stay inside the test root. -- Shared-file edits still require serialized integration even when issues have no dependency edge. -- Do not use the existing shared-tree offload execution workflow for these fixes until its migration is complete. Use direct orchestration or independently verified isolated checkouts. - -The original review exercised PowerShell 7 and Git Bash on Windows. Native Linux, macOS, and Bash 3.2 were not exercised. Record the platforms used for this issue rather than claiming untested parity. diff --git a/.scratch/offload-review-remediation/github/08-body.md b/.scratch/offload-review-remediation/github/08-body.md deleted file mode 100644 index c67f2a4..0000000 --- a/.scratch/offload-review-remediation/github/08-body.md +++ /dev/null @@ -1,56 +0,0 @@ - - -Blocked by: None - -Priority: P1. Review findings: F-05. Remediation ticket 08 of 14. - -Reviewed 2026-09-03 against [cfc9f4e](https://github.com/anthonyandrei/offload/commit/cfc9f4edc219b199c5c243c95f91fa2c463d137d). - -## Problem - -The auditor schema accepts an empty citation_audits array with final_status pass. The workflow does not compare returned audits with the synthesis claim ledger. - -## Deliverable - -Derive the required claim_id and URL pairs from the ledger and validate exact audit coverage and verdict consistency before accepting the synthesis. - -## Acceptance criteria - -- [ ] A nonempty required pair set rejects empty or partial citation_audits even when final_status is pass. -- [ ] Duplicate and unknown claim/citation pairs are rejected; two citations for one claim require separate coverage. -- [ ] Every required pair has one supported verdict before automated acceptance, and failed or unresolved entries cannot coexist with an accepted overall pass. -- [ ] A ledger with no auditable pairs follows an explicit documented branch and cannot bypass citations required by the research assignment. -- [ ] Complete valid coverage passes in both shell workflows; invalid responses follow the existing bounded revision or orchestrator fallback path. - -## Source evidence - -- [modes/web-research.md:292](https://github.com/anthonyandrei/offload/blob/cfc9f4edc219b199c5c243c95f91fa2c463d137d/modes/web-research.md#L292) -- [modes/web-research.md:306](https://github.com/anthonyandrei/offload/blob/cfc9f4edc219b199c5c243c95f91fa2c463d137d/modes/web-research.md#L306) - -## Implementation pointers - -- [modes/web-research.md](https://github.com/anthonyandrei/offload/blob/cfc9f4edc219b199c5c243c95f91fa2c463d137d/modes/web-research.md) -- [scripts/](https://github.com/anthonyandrei/offload/tree/cfc9f4edc219b199c5c243c95f91fa2c463d137d/scripts/) -- [tests/test_research_modes.sh](https://github.com/anthonyandrei/offload/blob/cfc9f4edc219b199c5c243c95f91fa2c463d137d/tests/test_research_modes.sh) -- [tests/test_workflow_static.ps1](https://github.com/anthonyandrei/offload/blob/cfc9f4edc219b199c5c243c95f91fa2c463d137d/tests/test_workflow_static.ps1) -- [tests/](https://github.com/anthonyandrei/offload/tree/cfc9f4edc219b199c5c243c95f91fa2c463d137d/tests/) - -New helper or test filenames under listed directories are implementation choices. - -## Verification - -Run fixture-based audit acceptance tests for empty, partial, duplicate, unknown, contradictory, and complete results. Use synthetic ledger data and no live browsing. - -## Scope and constraints - -Do not change what constitutes a trustworthy source in this ticket. This fix checks coverage and internal consistency of the required audit. - -- Work in the source repository. Do not update installed skill copies as part of this issue. -- Preserve the Gemini model policy, role routing, maximum two attempts, and immediate quota handoff. -- Preserve Bash 3.2+ compatibility and native PowerShell 7 support. Add no Windows requirement for Bash, Python, or jq. -- Keep the root SKILL.md router below 500 lines; place detailed workflow contracts in the mode documents or supporting files. -- Use fake workers and disposable repositories for regressions. Verify resolved cleanup paths stay inside the test root. -- Shared-file edits still require serialized integration even when issues have no dependency edge. -- Do not use the existing shared-tree offload execution workflow for these fixes until its migration is complete. Use direct orchestration or independently verified isolated checkouts. - -The original review exercised PowerShell 7 and Git Bash on Windows. Native Linux, macOS, and Bash 3.2 were not exercised. Record the platforms used for this issue rather than claiming untested parity. diff --git a/.scratch/offload-review-remediation/github/09-body.md b/.scratch/offload-review-remediation/github/09-body.md deleted file mode 100644 index 90ff2d8..0000000 --- a/.scratch/offload-review-remediation/github/09-body.md +++ /dev/null @@ -1,53 +0,0 @@ - - -Blocked by: #3 - -Priority: P2. Review findings: F-07. Remediation ticket 09 of 14. - -Reviewed 2026-09-03 against [cfc9f4e](https://github.com/anthonyandrei/offload/commit/cfc9f4edc219b199c5c243c95f91fa2c463d137d). - -## Problem - -The PowerShell launcher starts AGY before opening output streams. If stream creation fails, the child escapes cleanup and continues running after the launcher exits. - -## Deliverable - -Validate destinations and open owned resources before starting the child. Put every post-start operation under a cleanup path that terminates and waits for the child on launcher failure and disposes streams. - -## Acceptance criteria - -- [ ] Identical output/error paths fail before a fake worker starts. -- [ ] Locked or invalid output destinations fail without starting a worker. -- [ ] A controlled exception after launch causes the child to stop before the launcher returns; no completion marker appears afterward. -- [ ] Streams are disposed on success, launch failure, and post-launch failure, so the output files can be reopened. -- [ ] Successful launch output, error capture, process metadata, exit codes, and explicit quota handoff behavior remain consistent with their existing contracts. - -## Source evidence - -- [scripts/run-agy-json.ps1:408](https://github.com/anthonyandrei/offload/blob/cfc9f4edc219b199c5c243c95f91fa2c463d137d/scripts/run-agy-json.ps1#L408) -- [scripts/run-agy-json.ps1:413](https://github.com/anthonyandrei/offload/blob/cfc9f4edc219b199c5c243c95f91fa2c463d137d/scripts/run-agy-json.ps1#L413) - -## Implementation pointers - -- [scripts/run-agy-json.ps1](https://github.com/anthonyandrei/offload/blob/cfc9f4edc219b199c5c243c95f91fa2c463d137d/scripts/run-agy-json.ps1) -- [tests/test_model_routing.ps1](https://github.com/anthonyandrei/offload/blob/cfc9f4edc219b199c5c243c95f91fa2c463d137d/tests/test_model_routing.ps1) - -New helper or test filenames under listed directories are implementation choices. - -## Verification - -Use the now-executed PowerShell suite and disposable fake workers that write delayed markers. Do not consume live AGY quota. - -## Scope and constraints - -The blocker establishes that routing test groups actually execute. If new cases belong in a separate focused suite, keep that suite explicitly invoked. - -- Work in the source repository. Do not update installed skill copies as part of this issue. -- Preserve the Gemini model policy, role routing, maximum two attempts, and immediate quota handoff. -- Preserve Bash 3.2+ compatibility and native PowerShell 7 support. Add no Windows requirement for Bash, Python, or jq. -- Keep the root SKILL.md router below 500 lines; place detailed workflow contracts in the mode documents or supporting files. -- Use fake workers and disposable repositories for regressions. Verify resolved cleanup paths stay inside the test root. -- Shared-file edits still require serialized integration even when issues have no dependency edge. -- Do not use the existing shared-tree offload execution workflow for these fixes until its migration is complete. Use direct orchestration or independently verified isolated checkouts. - -The original review exercised PowerShell 7 and Git Bash on Windows. Native Linux, macOS, and Bash 3.2 were not exercised. Record the platforms used for this issue rather than claiming untested parity. diff --git a/.scratch/offload-review-remediation/github/10-body.md b/.scratch/offload-review-remediation/github/10-body.md deleted file mode 100644 index 43bf41e..0000000 --- a/.scratch/offload-review-remediation/github/10-body.md +++ /dev/null @@ -1,52 +0,0 @@ - - -Blocked by: None - -Priority: P2. Review findings: F-08. Remediation ticket 10 of 14. - -Reviewed 2026-09-03 against [cfc9f4e](https://github.com/anthonyandrei/offload/commit/cfc9f4edc219b199c5c243c95f91fa2c463d137d). - -## Problem - -Cleanup checks top-level links but recursively enumerates files under ordinary directories. A nested junction lets attribute changes reach a sibling directory outside the workspace. - -## Deliverable - -Traverse entries without following reparse points at any depth. Remove the link itself, and only clear file attributes within the verified workspace traversal. - -## Acceptance criteria - -- [ ] A nested junction to a controlled sibling fixture is removed without changing the target's file content, existence, or read-only attributes. -- [ ] Ordinary read-only workspace files are removed on success, and retained report/provenance files remain intact. -- [ ] Top-level and nested links use the same no-follow rule. -- [ ] Marker validation, Git-root rejection, and other protected-path checks still fail safely. -- [ ] Tests resolve and verify every destructive fixture path inside a dedicated temporary test root before cleanup; no external or user-owned directory is used. - -## Source evidence - -- [scripts/cleanup-research-workspace.ps1:122](https://github.com/anthonyandrei/offload/blob/cfc9f4edc219b199c5c243c95f91fa2c463d137d/scripts/cleanup-research-workspace.ps1#L122) - -## Implementation pointers - -- [scripts/cleanup-research-workspace.ps1](https://github.com/anthonyandrei/offload/blob/cfc9f4edc219b199c5c243c95f91fa2c463d137d/scripts/cleanup-research-workspace.ps1) -- [tests/test_research_helpers.ps1](https://github.com/anthonyandrei/offload/blob/cfc9f4edc219b199c5c243c95f91fa2c463d137d/tests/test_research_helpers.ps1) - -New helper or test filenames under listed directories are implementation choices. - -## Verification - -Add and run controlled junction fixtures in tests/test_research_helpers.ps1 on Windows. Use existing-target links for the confirmed reproduction; record platform limitations rather than inventing unsupported coverage. - -## Scope and constraints - -The separate dangling-link allegation was not verified in the audit and is not a required reproduction. Preserve failure retention behavior. - -- Work in the source repository. Do not update installed skill copies as part of this issue. -- Preserve the Gemini model policy, role routing, maximum two attempts, and immediate quota handoff. -- Preserve Bash 3.2+ compatibility and native PowerShell 7 support. Add no Windows requirement for Bash, Python, or jq. -- Keep the root SKILL.md router below 500 lines; place detailed workflow contracts in the mode documents or supporting files. -- Use fake workers and disposable repositories for regressions. Verify resolved cleanup paths stay inside the test root. -- Shared-file edits still require serialized integration even when issues have no dependency edge. -- Do not use the existing shared-tree offload execution workflow for these fixes until its migration is complete. Use direct orchestration or independently verified isolated checkouts. - -The original review exercised PowerShell 7 and Git Bash on Windows. Native Linux, macOS, and Bash 3.2 were not exercised. Record the platforms used for this issue rather than claiming untested parity. diff --git a/.scratch/offload-review-remediation/github/11-body.md b/.scratch/offload-review-remediation/github/11-body.md deleted file mode 100644 index 54a02d5..0000000 --- a/.scratch/offload-review-remediation/github/11-body.md +++ /dev/null @@ -1,57 +0,0 @@ - - -Blocked by: None - -Priority: P2. Review findings: F-11. Remediation ticket 11 of 14. - -Reviewed 2026-09-03 against [cfc9f4e](https://github.com/anthonyandrei/offload/commit/cfc9f4edc219b199c5c243c95f91fa2c463d137d). - -## Problem - -The instructions attach an individual attempt as worker.routing, but both provenance validators require a schema_version and attempts container. - -## Deliverable - -Use the existing validator contract, worker.routing = {schema_version: 1, attempts: [...]}. Add a complete reusable fixture and reference it from the shared instructions and web mode. - -## Acceptance criteria - -- [ ] The exact documented worker object passes both provenance helpers and preserves all recorded attempt fields. -- [ ] A two-attempt example retains both attempts under one stable worker identity. -- [ ] The previously documented bare-attempt shape is rejected by both test paths. -- [ ] The fixture is the source of the complete example or is mechanically checked against it, so documentation and validation cannot drift silently. -- [ ] The root router remains under 500 lines and links to detail instead of duplicating the full record schema. - -## Source evidence - -- [SKILL.md:143](https://github.com/anthonyandrei/offload/blob/cfc9f4edc219b199c5c243c95f91fa2c463d137d/SKILL.md#L143) -- [modes/web-research.md:325](https://github.com/anthonyandrei/offload/blob/cfc9f4edc219b199c5c243c95f91fa2c463d137d/modes/web-research.md#L325) -- [scripts/collect-provenance.ps1:214](https://github.com/anthonyandrei/offload/blob/cfc9f4edc219b199c5c243c95f91fa2c463d137d/scripts/collect-provenance.ps1#L214) - -## Implementation pointers - -- [SKILL.md](https://github.com/anthonyandrei/offload/blob/cfc9f4edc219b199c5c243c95f91fa2c463d137d/SKILL.md) -- [modes/web-research.md](https://github.com/anthonyandrei/offload/blob/cfc9f4edc219b199c5c243c95f91fa2c463d137d/modes/web-research.md) -- [tests/test_routing_provenance.ps1](https://github.com/anthonyandrei/offload/blob/cfc9f4edc219b199c5c243c95f91fa2c463d137d/tests/test_routing_provenance.ps1) -- [tests/test_research_modes.sh](https://github.com/anthonyandrei/offload/blob/cfc9f4edc219b199c5c243c95f91fa2c463d137d/tests/test_research_modes.sh) -- [tests/](https://github.com/anthonyandrei/offload/tree/cfc9f4edc219b199c5c243c95f91fa2c463d137d/tests/) - -New helper or test filenames under listed directories are implementation choices. - -## Verification - -Run the PowerShell routing-provenance suite and a Bash case using the same fixture through collect-provenance.sh. Compare parsed results. - -## Scope and constraints - -Keep the existing schema version and model policy. This ticket does not make optional embedding mandatory; retention is #16. - -- Work in the source repository. Do not update installed skill copies as part of this issue. -- Preserve the Gemini model policy, role routing, maximum two attempts, and immediate quota handoff. -- Preserve Bash 3.2+ compatibility and native PowerShell 7 support. Add no Windows requirement for Bash, Python, or jq. -- Keep the root SKILL.md router below 500 lines; place detailed workflow contracts in the mode documents or supporting files. -- Use fake workers and disposable repositories for regressions. Verify resolved cleanup paths stay inside the test root. -- Shared-file edits still require serialized integration even when issues have no dependency edge. -- Do not use the existing shared-tree offload execution workflow for these fixes until its migration is complete. Use direct orchestration or independently verified isolated checkouts. - -The original review exercised PowerShell 7 and Git Bash on Windows. Native Linux, macOS, and Bash 3.2 were not exercised. Record the platforms used for this issue rather than claiming untested parity. diff --git a/.scratch/offload-review-remediation/github/12-body.md b/.scratch/offload-review-remediation/github/12-body.md deleted file mode 100644 index 20e3685..0000000 --- a/.scratch/offload-review-remediation/github/12-body.md +++ /dev/null @@ -1,57 +0,0 @@ - - -Blocked by: None - -Priority: P2. Review findings: F-13. Remediation ticket 12 of 14. - -Reviewed 2026-09-03 against [cfc9f4e](https://github.com/anthonyandrei/offload/commit/cfc9f4edc219b199c5c243c95f91fa2c463d137d). - -## Problem - -Retry and revision examples reuse synthesizer.json and auditor.json. The launchers truncate those destinations, so attempt 1's routing record can point to attempt 2's output. - -## Deliverable - -Keep worker_id stable and use attempt-specific output, error, and process-artifact paths throughout dispatch/retry examples. Record an explicit accepted attempt for downstream stages. - -## Acceptance criteria - -- [ ] Initial and retry dispatch for the same worker use distinct artifact paths containing their attempt numbers. -- [ ] A fake second dispatch leaves the first output/error artifacts byte-for-byte intact. -- [ ] Both attempt records point to their own artifacts and retain the same worker_id. -- [ ] Downstream synthesis, audit, and report examples consume the explicitly selected attempt rather than whichever file was most recently overwritten. -- [ ] All three modes follow the convention, and maximum two attempts plus existing retry classification remain unchanged. - -## Source evidence - -- [modes/web-research.md:200](https://github.com/anthonyandrei/offload/blob/cfc9f4edc219b199c5c243c95f91fa2c463d137d/modes/web-research.md#L200) -- [modes/web-research.md:279](https://github.com/anthonyandrei/offload/blob/cfc9f4edc219b199c5c243c95f91fa2c463d137d/modes/web-research.md#L279) -- [modes/web-research.md:307](https://github.com/anthonyandrei/offload/blob/cfc9f4edc219b199c5c243c95f91fa2c463d137d/modes/web-research.md#L307) - -## Implementation pointers - -- [SKILL.md](https://github.com/anthonyandrei/offload/blob/cfc9f4edc219b199c5c243c95f91fa2c463d137d/SKILL.md) -- [modes/execution.md](https://github.com/anthonyandrei/offload/blob/cfc9f4edc219b199c5c243c95f91fa2c463d137d/modes/execution.md) -- [modes/repo-research.md](https://github.com/anthonyandrei/offload/blob/cfc9f4edc219b199c5c243c95f91fa2c463d137d/modes/repo-research.md) -- [modes/web-research.md](https://github.com/anthonyandrei/offload/blob/cfc9f4edc219b199c5c243c95f91fa2c463d137d/modes/web-research.md) -- [tests/](https://github.com/anthonyandrei/offload/tree/cfc9f4edc219b199c5c243c95f91fa2c463d137d/tests/) - -New helper or test filenames under listed directories are implementation choices. - -## Verification - -Execute two fake attempts using each shell's documented naming convention, compare first-attempt hashes, and validate the resulting routing record. No launcher auto-renaming is required. - -## Scope and constraints - -This ticket changes orchestration filenames, not model selection or retry count. Coordinate edits to execution.md with #7, #8, #9 instead of applying concurrent edits to that file. - -- Work in the source repository. Do not update installed skill copies as part of this issue. -- Preserve the Gemini model policy, role routing, maximum two attempts, and immediate quota handoff. -- Preserve Bash 3.2+ compatibility and native PowerShell 7 support. Add no Windows requirement for Bash, Python, or jq. -- Keep the root SKILL.md router below 500 lines; place detailed workflow contracts in the mode documents or supporting files. -- Use fake workers and disposable repositories for regressions. Verify resolved cleanup paths stay inside the test root. -- Shared-file edits still require serialized integration even when issues have no dependency edge. -- Do not use the existing shared-tree offload execution workflow for these fixes until its migration is complete. Use direct orchestration or independently verified isolated checkouts. - -The original review exercised PowerShell 7 and Git Bash on Windows. Native Linux, macOS, and Bash 3.2 were not exercised. Record the platforms used for this issue rather than claiming untested parity. diff --git a/.scratch/offload-review-remediation/github/13-body.md b/.scratch/offload-review-remediation/github/13-body.md deleted file mode 100644 index f590387..0000000 --- a/.scratch/offload-review-remediation/github/13-body.md +++ /dev/null @@ -1,56 +0,0 @@ - - -Blocked by: #4, #14 - -Priority: P2. Review findings: F-12. Remediation ticket 13 of 14. - -Reviewed 2026-09-03 against [cfc9f4e](https://github.com/anthonyandrei/offload/commit/cfc9f4edc219b199c5c243c95f91fa2c463d137d). - -## Problem - -The synthesis snippets glob every researcher JSON file. A failed envelope stops extraction even when two successful independent angles satisfy the documented partial-success policy. - -## Deliverable - -Build the extraction input list from the verified selected attempts, then check independent surviving research angles before synthesis. Retain failed and superseded files as diagnostics. - -## Acceptance criteria - -- [ ] Two verified successful independent angles plus one exhausted ERROR worker produce merged evidence from the two successful angles. -- [ ] A failed attempt followed by a verified retry contributes only the retry's findings. -- [ ] Completed but unverified results never enter synthesis. -- [ ] Two successful attempts for the same assignment do not count as two independent angles. -- [ ] Fewer than two surviving independent angles takes the documented fallback instead of dispatching synthesis. -- [ ] Both Bash and PowerShell snippets pass explicit selected file arrays and avoid globs that include failed or superseded envelopes. - -## Source evidence - -- [modes/web-research.md:197](https://github.com/anthonyandrei/offload/blob/cfc9f4edc219b199c5c243c95f91fa2c463d137d/modes/web-research.md#L197) -- [modes/web-research.md:210](https://github.com/anthonyandrei/offload/blob/cfc9f4edc219b199c5c243c95f91fa2c463d137d/modes/web-research.md#L210) -- [modes/web-research.md:316](https://github.com/anthonyandrei/offload/blob/cfc9f4edc219b199c5c243c95f91fa2c463d137d/modes/web-research.md#L316) - -## Implementation pointers - -- [modes/web-research.md](https://github.com/anthonyandrei/offload/blob/cfc9f4edc219b199c5c243c95f91fa2c463d137d/modes/web-research.md) -- [tests/test_research_helpers.ps1](https://github.com/anthonyandrei/offload/blob/cfc9f4edc219b199c5c243c95f91fa2c463d137d/tests/test_research_helpers.ps1) -- [tests/test_research_modes.sh](https://github.com/anthonyandrei/offload/blob/cfc9f4edc219b199c5c243c95f91fa2c463d137d/tests/test_research_modes.sh) - -New helper or test filenames under listed directories are implementation choices. - -## Verification - -Run fake researcher fixtures through the actual extraction helper in each shell, including a successful PowerShell pipeline capture from #4. - -## Scope and constraints - -Keep the existing independent-angle threshold and recovery policy. Do not silently drop failing files from provenance. - -- Work in the source repository. Do not update installed skill copies as part of this issue. -- Preserve the Gemini model policy, role routing, maximum two attempts, and immediate quota handoff. -- Preserve Bash 3.2+ compatibility and native PowerShell 7 support. Add no Windows requirement for Bash, Python, or jq. -- Keep the root SKILL.md router below 500 lines; place detailed workflow contracts in the mode documents or supporting files. -- Use fake workers and disposable repositories for regressions. Verify resolved cleanup paths stay inside the test root. -- Shared-file edits still require serialized integration even when issues have no dependency edge. -- Do not use the existing shared-tree offload execution workflow for these fixes until its migration is complete. Use direct orchestration or independently verified isolated checkouts. - -The original review exercised PowerShell 7 and Git Bash on Windows. Native Linux, macOS, and Bash 3.2 were not exercised. Record the platforms used for this issue rather than claiming untested parity. diff --git a/.scratch/offload-review-remediation/github/14-body.md b/.scratch/offload-review-remediation/github/14-body.md deleted file mode 100644 index cd44f88..0000000 --- a/.scratch/offload-review-remediation/github/14-body.md +++ /dev/null @@ -1,61 +0,0 @@ - - -Blocked by: #12, #13, #14 - -Priority: P2. Review findings: F-10. Remediation ticket 14 of 14. - -Reviewed 2026-09-03 against [cfc9f4e](https://github.com/anthonyandrei/offload/commit/cfc9f4edc219b199c5c243c95f91fa2c463d137d). - -## Problem - -Success cleanup deletes routing-outcomes.json despite the shared requirement to maintain it. Optional web provenance embedding does not protect repository-research runs or explain deleted evidence paths. - -## Deliverable - -Preserve routing-outcomes.json on success. Before deleting raw artifacts, write and retain an evidence disposition manifest with each referenced relative path, existence before cleanup, content hash for existing regular files, and retained or pruned status. Keep raw-file pruning as the default success policy. - -## Acceptance criteria - -- [ ] Success cleanup preserves final.md, provenance.json when present, the workspace marker, routing-outcomes.json, and the evidence disposition manifest. -- [ ] Both attempts and their verification verdicts remain readable after cleanup in repository and web research fixtures. -- [ ] Every evidence path in the retained routing record has a disposition entry; missing inputs are explicitly marked missing instead of reported as pruned or verified. -- [ ] Evidence paths cannot authorize reads, hashing, attribute changes, or deletion outside the workspace or through a reparse point; external/link paths receive an explicit uninspected entry. -- [ ] An invalid routing record or failure to write the disposition manifest stops success cleanup before raw artifacts are removed. -- [ ] Failure/interruption retention remains unchanged, and repeating successful cleanup preserves the original manifest information rather than reclassifying pruned files as missing. -- [ ] Both shell families produce the same retention and disposition behavior. - -## Source evidence - -- [scripts/cleanup-research-workspace.ps1:111](https://github.com/anthonyandrei/offload/blob/cfc9f4edc219b199c5c243c95f91fa2c463d137d/scripts/cleanup-research-workspace.ps1#L111) -- [scripts/cleanup-research-workspace.sh:130](https://github.com/anthonyandrei/offload/blob/cfc9f4edc219b199c5c243c95f91fa2c463d137d/scripts/cleanup-research-workspace.sh#L130) -- [SKILL.md:120](https://github.com/anthonyandrei/offload/blob/cfc9f4edc219b199c5c243c95f91fa2c463d137d/SKILL.md#L120) - -## Implementation pointers - -- [scripts/cleanup-research-workspace.ps1](https://github.com/anthonyandrei/offload/blob/cfc9f4edc219b199c5c243c95f91fa2c463d137d/scripts/cleanup-research-workspace.ps1) -- [scripts/cleanup-research-workspace.sh](https://github.com/anthonyandrei/offload/blob/cfc9f4edc219b199c5c243c95f91fa2c463d137d/scripts/cleanup-research-workspace.sh) -- [SKILL.md](https://github.com/anthonyandrei/offload/blob/cfc9f4edc219b199c5c243c95f91fa2c463d137d/SKILL.md) -- [modes/repo-research.md](https://github.com/anthonyandrei/offload/blob/cfc9f4edc219b199c5c243c95f91fa2c463d137d/modes/repo-research.md) -- [modes/web-research.md](https://github.com/anthonyandrei/offload/blob/cfc9f4edc219b199c5c243c95f91fa2c463d137d/modes/web-research.md) -- [tests/test_research_helpers.ps1](https://github.com/anthonyandrei/offload/blob/cfc9f4edc219b199c5c243c95f91fa2c463d137d/tests/test_research_helpers.ps1) -- [tests/test_research_modes.sh](https://github.com/anthonyandrei/offload/blob/cfc9f4edc219b199c5c243c95f91fa2c463d137d/tests/test_research_modes.sh) - -New helper or test filenames under listed directories are implementation choices. - -## Verification - -Run paired cleanup fixtures containing successful and failed attempts, absent optional provenance, missing evidence, and an out-of-workspace evidence reference. Verify surviving records and disposal metadata after success and after a repeated cleanup. - -## Scope and constraints - -Use a separate disposition manifest so the routing schema need not change. It records provenance of cleanup, not a claim that pruned content remains available. Do not retain complete repository snapshots by default. - -- Work in the source repository. Do not update installed skill copies as part of this issue. -- Preserve the Gemini model policy, role routing, maximum two attempts, and immediate quota handoff. -- Preserve Bash 3.2+ compatibility and native PowerShell 7 support. Add no Windows requirement for Bash, Python, or jq. -- Keep the root SKILL.md router below 500 lines; place detailed workflow contracts in the mode documents or supporting files. -- Use fake workers and disposable repositories for regressions. Verify resolved cleanup paths stay inside the test root. -- Shared-file edits still require serialized integration even when issues have no dependency edge. -- Do not use the existing shared-tree offload execution workflow for these fixes until its migration is complete. Use direct orchestration or independently verified isolated checkouts. - -The original review exercised PowerShell 7 and Git Bash on Windows. Native Linux, macOS, and Bash 3.2 were not exercised. Record the platforms used for this issue rather than claiming untested parity. diff --git a/.scratch/offload-review-remediation/issues/01-execute-model-routing-tests.md b/.scratch/offload-review-remediation/issues/01-execute-model-routing-tests.md deleted file mode 100644 index 01f75f0..0000000 --- a/.scratch/offload-review-remediation/issues/01-execute-model-routing-tests.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -id: offload-review-01 -status: published -priority: P2 -labels: [bug, review-remediation, ready-for-agent] -findings: [F-09] -blocked_by: [] ---- - -# 01. Execute every PowerShell model-routing test group - -Blocked by: None - -Source: [whole-skill audit](../evidence/review.md), F-09. Reviewed at `cfc9f4e` on 2026-09-03. Published as [#3](https://github.com/anthonyandrei/offload/issues/3). GitHub is the active issue tracker. - -## Problem - -Fifty bare script blocks in tests/test_model_routing.ps1 create ScriptBlock objects without running their assertions. The existing green result covers only the invoked portions. - -## Deliverable - -Invoke the dormant groups and make their failures propagate to the test command. Keep the existing test intent and isolate each fixture as needed. - -## Acceptance criteria - -- [ ] Every one of the 50 groups listed in the audit's uninvoked-test-blocks.json executes rather than printing its source. -- [ ] A deliberate assertion failure in a representative formerly dormant group makes a disposable copy of the suite exit nonzero. -- [ ] The ordinary suite exits zero after the exercised behavior is verified. Any newly exposed production defect is documented as a blocker instead of weakening or skipping its assertion. -- [ ] Test output distinguishes executed assertions from script text; the existing invoked assertions still run. - -## Implementation pointers - -- [tests/test_model_routing.ps1](../../../tests/test_model_routing.ps1) - -Evidence locations at the reviewed revision: `tests/test_model_routing.ps1:366`. New helper or test filenames under listed directories are implementation choices. - -## Verification - -Run pwsh -NoProfile -File tests/test_model_routing.ps1, plus the deliberate-failure check in a disposable copy. No live AGY call is needed. - -## Scope and constraints - -This ticket repairs test execution. Do not change model defaults, retry limits, or production behavior merely to turn the suite green. - -Apply the [shared constraints and scheduling notes](../README.md). Do not modify the installed skill copy as part of this ticket. - diff --git a/.scratch/offload-review-remediation/issues/02-capture-powershell-research-output.md b/.scratch/offload-review-remediation/issues/02-capture-powershell-research-output.md deleted file mode 100644 index 680e3c3..0000000 --- a/.scratch/offload-review-remediation/issues/02-capture-powershell-research-output.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -id: offload-review-02 -status: published -priority: P1 -labels: [bug, review-remediation, ready-for-agent] -findings: [F-01] -blocked_by: [] ---- - -# 02. Make documented PowerShell research handoffs return usable values - -Blocked by: None - -Source: [whole-skill audit](../evidence/review.md), F-01. Reviewed at `cfc9f4e` on 2026-09-03. Published as [#4](https://github.com/anthonyandrei/offload/issues/4). GitHub is the active issue tracker. - -## Problem - -The workspace and extraction helpers write to Console.Out, while the mode examples capture the PowerShell pipeline. Workspace.Trim() fails on null, and merged researcher evidence can silently become null. - -## Deliverable - -Make the helpers emit their result through the PowerShell pipeline and keep diagnostics on the error channel. Test the exact documented in-process assignments and native pwsh -File invocation. - -## Acceptance criteria - -- [ ] The documented workspace assignment returns one nonempty existing workspace path and .Trim() succeeds. -- [ ] The documented extraction assignment for two valid researcher envelopes returns nonempty JSON containing both findings. -- [ ] Both direct & invocation and native pwsh -File invocation return the same semantic payload without diagnostic text mixed into JSON. -- [ ] Invalid input still fails with the intended exit/error contract, and the mode examples match the tested commands. - -## Implementation pointers - -- [scripts/make-research-workspace.ps1](../../../scripts/make-research-workspace.ps1) -- [scripts/extract-structured-output.ps1](../../../scripts/extract-structured-output.ps1) -- [modes/repo-research.md](../../../modes/repo-research.md) -- [modes/web-research.md](../../../modes/web-research.md) -- [tests/test_research_helpers.ps1](../../../tests/test_research_helpers.ps1) - -Evidence locations at the reviewed revision: `scripts/make-research-workspace.ps1:170`, `scripts/extract-structured-output.ps1:77`, `modes/repo-research.md:40`, `modes/web-research.md:211`. New helper or test filenames under listed directories are implementation choices. - -## Verification - -Add workflow-shaped cases to tests/test_research_helpers.ps1 using disposable workspaces and fixture envelopes, then run that suite. - -## Scope and constraints - -Keep the Windows workflow native to PowerShell 7. Do not add Bash, jq, or Python dependencies. - -Apply the [shared constraints and scheduling notes](../README.md). Do not modify the installed skill copy as part of this ticket. - diff --git a/.scratch/offload-review-remediation/issues/03-verify-baseline-relative-scope.md b/.scratch/offload-review-remediation/issues/03-verify-baseline-relative-scope.md deleted file mode 100644 index 64d5907..0000000 --- a/.scratch/offload-review-remediation/issues/03-verify-baseline-relative-scope.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -id: offload-review-03 -status: published -priority: P1 -labels: [bug, review-remediation, ready-for-agent] -findings: [F-03, F-06] -blocked_by: [] ---- - -# 03. Check committed and working-tree edits against a fixed baseline - -Blocked by: None - -Source: [whole-skill audit](../evidence/review.md), F-03, F-06. Reviewed at `cfc9f4e` on 2026-09-03. Published as [#5](https://github.com/anthonyandrei/offload/issues/5). GitHub is the active issue tracker. - -## Problem - -The scope helpers trust git status. A worker can commit a frozen or unowned edit and pass with a clean status. Bash also returns success when the git status command in process substitution fails. - -## Deliverable - -Expand the paired helper contract with an explicit immutable baseline revision. Compute the complete final delta against that revision and compare frozen contents with the baseline. Preserve the old call form only until ticket 05 migrates callers. - -## Acceptance criteria - -- [ ] A committed unowned edit and a committed frozen edit both produce nonzero results even when git status is clean. -- [ ] Owned-only committed, staged, unstaged, and new-file changes pass; unowned or frozen changes in each applicable state fail. -- [ ] Renames and deletions check all affected paths, with existing path normalization and NUL-safe filename handling preserved. -- [ ] Missing or invalid supplied baselines fail; the helper never silently substitutes current HEAD for a supplied baseline. -- [ ] A mocked git status failure with exit 73, and failures of any other Git query used for verification, produce nonzero helper results. -- [ ] Both shell families expose equivalent baseline semantics and diagnostics. - -## Implementation pointers - -- [scripts/check-execution-scope.ps1](../../../scripts/check-execution-scope.ps1) -- [scripts/check-execution-scope.sh](../../../scripts/check-execution-scope.sh) -- [tests/test_execution_scope.ps1](../../../tests/test_execution_scope.ps1) -- [tests/test_execution_scope.sh](../../../tests/test_execution_scope.sh) - -Evidence locations at the reviewed revision: `scripts/check-execution-scope.ps1:145`, `scripts/check-execution-scope.sh:138`. New helper or test filenames under listed directories are implementation choices. - -## Verification - -Extend and run both execution-scope suites with temporary Git repositories and controlled Git failure mocks. Check final content relative to the captured baseline, not a worker-reported revision. - -## Scope and constraints - -This is the expand stage. Temporary compatibility is not sufficient to close F-03; ticket 05 must require the baseline in every execution workflow. Worktrees and baseline checks are not an OS write sandbox. - -Apply the [shared constraints and scheduling notes](../README.md). Do not modify the installed skill copy as part of this ticket. - diff --git a/.scratch/offload-review-remediation/issues/04-add-isolated-execution-workspaces.md b/.scratch/offload-review-remediation/issues/04-add-isolated-execution-workspaces.md deleted file mode 100644 index 3e11ee8..0000000 --- a/.scratch/offload-review-remediation/issues/04-add-isolated-execution-workspaces.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -id: offload-review-04 -status: published -priority: P1 -labels: [bug, review-remediation] -findings: [F-02] -blocked_by: [offload-review-03] ---- - -# 04. Add a verified lifecycle for isolated execution worktrees - -Blocked by: [03](./03-verify-baseline-relative-scope.md) - -Source: [whole-skill audit](../evidence/review.md), F-02. Reviewed at `cfc9f4e` on 2026-09-03. Published as [#6](https://github.com/anthonyandrei/offload/issues/6). GitHub is the active issue tracker. - -## Problem - -Per-worker ownership cannot be checked reliably while multiple writers share one working tree. The execution workflow needs a small, tested mechanism for creating isolated candidates and importing only their verified changes. - -## Deliverable - -Add paired shell-native execution-workspace helpers with a narrow create, verify/export, integrate, and cleanup contract. Store an orchestrator-owned manifest outside the worker checkout with task identity, absolute paths, baseline revision, and owned/frozen paths. Keep this beside the current workflow until ticket 05. - -## Acceptance criteria - -- [ ] Two workers starting from the same baseline can independently edit a.txt and b.txt, and each scope check passes against only its own candidate. -- [ ] An unowned or frozen change in either candidate blocks export/integration, including when the worker has committed it. -- [ ] Export captures committed and uncommitted final changes and records a content digest; integration consumes only that verified artifact. -- [ ] Integration into a disposable integration checkout preflights the whole change, detects conflicts, and retains candidates on failure without partially publishing changes to the caller checkout. -- [ ] Creation and cleanup only operate on manifest-owned paths; no existing caller checkout or unrelated worktree is reset, cleaned, or removed. -- [ ] The paired helpers pass equivalent disposable-repository cases and add no Windows dependency beyond PowerShell 7 and Git. - -## Implementation pointers - -- [scripts/](../../../scripts/) -- [tests/](../../../tests/) -- [docs/adr/](../../../docs/adr/) - -Evidence locations at the reviewed revision: `modes/execution.md:136`, `modes/execution.md:178`. New helper or test filenames under listed directories are implementation choices. - -## Verification - -Add focused lifecycle suites for both shells using fake workers. Exercise two sibling tasks, a scope violation, an integration conflict, and cleanup ownership guards. - -## Scope and constraints - -This is an additive workspace capability. Keep its interface small enough for ticket 05 to use directly. Do not build a general scheduler or change the model policy. Record the worktree decision in a short ADR. - -Apply the [shared constraints and scheduling notes](../README.md). Do not modify the installed skill copy as part of this ticket. - diff --git a/.scratch/offload-review-remediation/issues/05-migrate-execution-to-isolated-workers.md b/.scratch/offload-review-remediation/issues/05-migrate-execution-to-isolated-workers.md deleted file mode 100644 index 3185e7a..0000000 --- a/.scratch/offload-review-remediation/issues/05-migrate-execution-to-isolated-workers.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -id: offload-review-05 -status: published -priority: P1 -labels: [bug, review-remediation] -findings: [F-02, F-03] -blocked_by: [offload-review-03, offload-review-04] ---- - -# 05. Run execution stages through isolated workspaces and retire shared-tree dispatch - -Blocked by: [03](./03-verify-baseline-relative-scope.md), [04](./04-add-isolated-execution-workspaces.md) - -Source: [whole-skill audit](../evidence/review.md), F-02, F-03. Reviewed at `cfc9f4e` on 2026-09-03. Published as [#7](https://github.com/anthonyandrei/offload/issues/7). GitHub is the active issue tracker. - -## Problem - -Adding baseline and workspace helpers does not fix the existing instructions. Gate authors still write before an untouched baseline is established, and implementers still share the caller's tree. - -## Deliverable - -Migrate gate-author and implementer dispatch to ticket 04's lifecycle. Verify gate authors against the original baseline before importing approved tests into an integration checkout. Freeze that gate baseline before creating implementer worktrees. Retire no-baseline scope calls and shared-tree writing examples. - -## Acceptance criteria - -- [ ] The documented Bash and PowerShell machine-gated flow completes with two disjoint fake implementers and imports both verified changes without sibling scope failures. -- [ ] A gate author that commits an unowned source edit is rejected before its output can become the implementation baseline. -- [ ] Implementers receive the approved frozen gates and an externally recorded baseline; committed gate edits are rejected. -- [ ] Overlapping assignments run serially from the newly accepted baseline, and all accepted deltas undergo scope and gate verification before publication to the caller. -- [ ] Retries retain the original verification baseline for that writing stage; a failed attempt never becomes an implicitly trusted baseline. -- [ ] Quota handoff records still-running candidates and artifacts immediately without waiting for sibling completion; normal cleanup waits for workers to stop. -- [ ] All execution-mode examples supply a baseline and isolated working directory, and the scope helpers reject omitted baselines after migration. -- [ ] A final combined gate check runs before publishing the integrated result; conflicts or failed gates leave the caller's existing work intact. - -## Implementation pointers - -- [modes/execution.md](../../../modes/execution.md) -- [SKILL.md](../../../SKILL.md) -- [README.md](../../../README.md) -- [AGENTS.md](../../../AGENTS.md) -- [CLAUDE.md](../../../CLAUDE.md) -- [CONTEXT.md](../../../CONTEXT.md) -- [scripts/check-execution-scope.ps1](../../../scripts/check-execution-scope.ps1) -- [scripts/check-execution-scope.sh](../../../scripts/check-execution-scope.sh) -- [tests/test_workflow_static.ps1](../../../tests/test_workflow_static.ps1) -- [tests/](../../../tests/) - -Evidence locations at the reviewed revision: `modes/execution.md:90`, `modes/execution.md:132`, `modes/execution.md:136`, `modes/execution.md:178`. New helper or test filenames under listed directories are implementation choices. - -## Verification - -Run executable workflow cases with fake AGY workers for both shell families, the scope suites, and relevant static checks. Inspect current architecture pointers for agreement with the migrated mode. - -## Scope and constraints - -This ticket is the migrate and contract stage for one execution mode. Use the helpers from ticket 04 rather than adding another orchestration framework. Diff-review completeness and acceptance remain tickets 06 and 07. - -Apply the [shared constraints and scheduling notes](../README.md). Do not modify the installed skill copy as part of this ticket. - diff --git a/.scratch/offload-review-remediation/issues/06-review-complete-change-artifacts.md b/.scratch/offload-review-remediation/issues/06-review-complete-change-artifacts.md deleted file mode 100644 index 2d58d33..0000000 --- a/.scratch/offload-review-remediation/issues/06-review-complete-change-artifacts.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -id: offload-review-06 -status: published -priority: P1 -labels: [bug, review-remediation] -findings: [F-04] -blocked_by: [offload-review-05] ---- - -# 06. Review one complete change artifact against the execution baseline - -Blocked by: [05](./05-migrate-execution-to-isolated-workers.md) - -Source: [whole-skill audit](../evidence/review.md), F-04. Reviewed at `cfc9f4e` on 2026-09-03. Published as [#8](https://github.com/anthonyandrei/offload/issues/8). GitHub is the active issue tracker. - -## Problem - -Bare git diff omits staged changes and new files. Reviewers and quote matching can agree on an incomplete diff and still miss part of a task. - -## Deliverable - -Produce one immutable review artifact from each verified candidate and its recorded baseline, then pass the identical artifact to the reviewer and quote verifier. Reuse the delta export from ticket 04 where possible. - -## Acceptance criteria - -- [ ] A fixture containing a committed edit, staged edit, unstaged edit, and new file exposes every final change to review. -- [ ] Deletion and rename information is present, and binary changes are explicitly identified for direct review instead of silently omitted. -- [ ] The reviewer prompt reads the recorded artifact rather than running an independent bare git diff. -- [ ] Quote verification uses the exact artifact bytes or their verified digest; modifying the candidate after artifact creation cannot silently change the evidence being accepted. -- [ ] Git or artifact-generation failures prevent review acceptance, and both shells produce equivalent review coverage. - -## Implementation pointers - -- [modes/execution.md](../../../modes/execution.md) -- [scripts/](../../../scripts/) -- [tests/](../../../tests/) - -Evidence locations at the reviewed revision: `modes/execution.md:216`, `modes/execution.md:232`, `modes/execution.md:242`. New helper or test filenames under listed directories are implementation choices. - -## Verification - -Add focused artifact-generation tests and execute the documented reviewer handoff with a fake reviewer. Compare the artifact's path/content coverage with the baseline delta. - -## Scope and constraints - -This ticket guarantees complete evidence. Ticket 07 adds exhaustive criterion coverage; do not treat successful quote lookup alone as sufficient acceptance. - -Apply the [shared constraints and scheduling notes](../README.md). Do not modify the installed skill copy as part of this ticket. - diff --git a/.scratch/offload-review-remediation/issues/07-require-complete-reviewer-verdicts.md b/.scratch/offload-review-remediation/issues/07-require-complete-reviewer-verdicts.md deleted file mode 100644 index c4f756c..0000000 --- a/.scratch/offload-review-remediation/issues/07-require-complete-reviewer-verdicts.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -id: offload-review-07 -status: published -priority: P1 -labels: [bug, review-remediation] -findings: [F-05] -blocked_by: [offload-review-06] ---- - -# 07. Require one valid reviewer verdict for every requested criterion - -Blocked by: [06](./06-review-complete-change-artifacts.md) - -Source: [whole-skill audit](../evidence/review.md), F-05. Reviewed at `cfc9f4e` on 2026-09-03. Published as [#9](https://github.com/anthonyandrei/offload/issues/9). GitHub is the active issue tracker. - -## Problem - -The reviewer schema accepts an empty criteria array, and the workflow accepts when all returned quotes match. Empty or partial responses can therefore pass without addressing the task. - -## Deliverable - -Assign stable IDs to requested criteria and add a mechanical coverage check in both shell workflows before accepting any reviewer response. - -## Acceptance criteria - -- [ ] Empty output is rejected when criteria were requested. -- [ ] Missing, duplicate, and unknown criterion IDs are rejected, even when every returned quote exists in the artifact. -- [ ] Each requested criterion has exactly one verdict; fail or hedge prevents automated acceptance. -- [ ] Every pass has a literal matching evidence line from ticket 06's artifact, with matching performed on data rather than interpolated shell code. -- [ ] A complete all-pass response with valid evidence is accepted, and malformed or incomplete responses route to direct orchestrator review. - -## Implementation pointers - -- [modes/execution.md](../../../modes/execution.md) -- [scripts/](../../../scripts/) -- [tests/](../../../tests/) - -Evidence locations at the reviewed revision: `modes/execution.md:210`, `modes/execution.md:246`. New helper or test filenames under listed directories are implementation choices. - -## Verification - -Use fixed criterion sets and fake reviewer envelopes for empty, partial, duplicate, unknown, failed, hedged, forged-quote, and complete outputs. Exercise both documented shell flows. - -## Scope and constraints - -A minimum array length alone does not establish coverage. Preserve the existing direct-review fallback and bounded retry policy. - -Apply the [shared constraints and scheduling notes](../README.md). Do not modify the installed skill copy as part of this ticket. - diff --git a/.scratch/offload-review-remediation/issues/08-require-complete-citation-audits.md b/.scratch/offload-review-remediation/issues/08-require-complete-citation-audits.md deleted file mode 100644 index 29a5b2a..0000000 --- a/.scratch/offload-review-remediation/issues/08-require-complete-citation-audits.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -id: offload-review-08 -status: published -priority: P1 -labels: [bug, review-remediation, ready-for-agent] -findings: [F-05] -blocked_by: [] ---- - -# 08. Require audit coverage for every claim and citation pair - -Blocked by: None - -Source: [whole-skill audit](../evidence/review.md), F-05. Reviewed at `cfc9f4e` on 2026-09-03. Published as [#10](https://github.com/anthonyandrei/offload/issues/10). GitHub is the active issue tracker. - -## Problem - -The auditor schema accepts an empty citation_audits array with final_status pass. The workflow does not compare returned audits with the synthesis claim ledger. - -## Deliverable - -Derive the required claim_id and URL pairs from the ledger and validate exact audit coverage and verdict consistency before accepting the synthesis. - -## Acceptance criteria - -- [ ] A nonempty required pair set rejects empty or partial citation_audits even when final_status is pass. -- [ ] Duplicate and unknown claim/citation pairs are rejected; two citations for one claim require separate coverage. -- [ ] Every required pair has one supported verdict before automated acceptance, and failed or unresolved entries cannot coexist with an accepted overall pass. -- [ ] A ledger with no auditable pairs follows an explicit documented branch and cannot bypass citations required by the research assignment. -- [ ] Complete valid coverage passes in both shell workflows; invalid responses follow the existing bounded revision or orchestrator fallback path. - -## Implementation pointers - -- [modes/web-research.md](../../../modes/web-research.md) -- [scripts/](../../../scripts/) -- [tests/test_research_modes.sh](../../../tests/test_research_modes.sh) -- [tests/test_workflow_static.ps1](../../../tests/test_workflow_static.ps1) -- [tests/](../../../tests/) - -Evidence locations at the reviewed revision: `modes/web-research.md:292`, `modes/web-research.md:306`. New helper or test filenames under listed directories are implementation choices. - -## Verification - -Run fixture-based audit acceptance tests for empty, partial, duplicate, unknown, contradictory, and complete results. Use synthetic ledger data and no live browsing. - -## Scope and constraints - -Do not change what constitutes a trustworthy source in this ticket. This fix checks coverage and internal consistency of the required audit. - -Apply the [shared constraints and scheduling notes](../README.md). Do not modify the installed skill copy as part of this ticket. - diff --git a/.scratch/offload-review-remediation/issues/09-close-launcher-failure-lifetime.md b/.scratch/offload-review-remediation/issues/09-close-launcher-failure-lifetime.md deleted file mode 100644 index c7e6604..0000000 --- a/.scratch/offload-review-remediation/issues/09-close-launcher-failure-lifetime.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -id: offload-review-09 -status: published -priority: P2 -labels: [bug, review-remediation] -findings: [F-07] -blocked_by: [offload-review-01] ---- - -# 09. Prevent orphaned workers when PowerShell output setup fails - -Blocked by: [01](./01-execute-model-routing-tests.md) - -Source: [whole-skill audit](../evidence/review.md), F-07. Reviewed at `cfc9f4e` on 2026-09-03. Published as [#11](https://github.com/anthonyandrei/offload/issues/11). GitHub is the active issue tracker. - -## Problem - -The PowerShell launcher starts AGY before opening output streams. If stream creation fails, the child escapes cleanup and continues running after the launcher exits. - -## Deliverable - -Validate destinations and open owned resources before starting the child. Put every post-start operation under a cleanup path that terminates and waits for the child on launcher failure and disposes streams. - -## Acceptance criteria - -- [ ] Identical output/error paths fail before a fake worker starts. -- [ ] Locked or invalid output destinations fail without starting a worker. -- [ ] A controlled exception after launch causes the child to stop before the launcher returns; no completion marker appears afterward. -- [ ] Streams are disposed on success, launch failure, and post-launch failure, so the output files can be reopened. -- [ ] Successful launch output, error capture, process metadata, exit codes, and explicit quota handoff behavior remain consistent with their existing contracts. - -## Implementation pointers - -- [scripts/run-agy-json.ps1](../../../scripts/run-agy-json.ps1) -- [tests/test_model_routing.ps1](../../../tests/test_model_routing.ps1) - -Evidence locations at the reviewed revision: `scripts/run-agy-json.ps1:408`, `scripts/run-agy-json.ps1:413`. New helper or test filenames under listed directories are implementation choices. - -## Verification - -Use the now-executed PowerShell suite and disposable fake workers that write delayed markers. Do not consume live AGY quota. - -## Scope and constraints - -The blocker establishes that routing test groups actually execute. If new cases belong in a separate focused suite, keep that suite explicitly invoked. - -Apply the [shared constraints and scheduling notes](../README.md). Do not modify the installed skill copy as part of this ticket. - diff --git a/.scratch/offload-review-remediation/issues/10-avoid-following-cleanup-links.md b/.scratch/offload-review-remediation/issues/10-avoid-following-cleanup-links.md deleted file mode 100644 index 10141e3..0000000 --- a/.scratch/offload-review-remediation/issues/10-avoid-following-cleanup-links.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -id: offload-review-10 -status: published -priority: P2 -labels: [bug, review-remediation, ready-for-agent] -findings: [F-08] -blocked_by: [] ---- - -# 10. Keep PowerShell cleanup inside the marked workspace - -Blocked by: None - -Source: [whole-skill audit](../evidence/review.md), F-08. Reviewed at `cfc9f4e` on 2026-09-03. Published as [#12](https://github.com/anthonyandrei/offload/issues/12). GitHub is the active issue tracker. - -## Problem - -Cleanup checks top-level links but recursively enumerates files under ordinary directories. A nested junction lets attribute changes reach a sibling directory outside the workspace. - -## Deliverable - -Traverse entries without following reparse points at any depth. Remove the link itself, and only clear file attributes within the verified workspace traversal. - -## Acceptance criteria - -- [ ] A nested junction to a controlled sibling fixture is removed without changing the target's file content, existence, or read-only attributes. -- [ ] Ordinary read-only workspace files are removed on success, and retained report/provenance files remain intact. -- [ ] Top-level and nested links use the same no-follow rule. -- [ ] Marker validation, Git-root rejection, and other protected-path checks still fail safely. -- [ ] Tests resolve and verify every destructive fixture path inside a dedicated temporary test root before cleanup; no external or user-owned directory is used. - -## Implementation pointers - -- [scripts/cleanup-research-workspace.ps1](../../../scripts/cleanup-research-workspace.ps1) -- [tests/test_research_helpers.ps1](../../../tests/test_research_helpers.ps1) - -Evidence locations at the reviewed revision: `scripts/cleanup-research-workspace.ps1:122`. New helper or test filenames under listed directories are implementation choices. - -## Verification - -Add and run controlled junction fixtures in tests/test_research_helpers.ps1 on Windows. Use existing-target links for the confirmed reproduction; record platform limitations rather than inventing unsupported coverage. - -## Scope and constraints - -The separate dangling-link allegation was not verified in the audit and is not a required reproduction. Preserve failure retention behavior. - -Apply the [shared constraints and scheduling notes](../README.md). Do not modify the installed skill copy as part of this ticket. - diff --git a/.scratch/offload-review-remediation/issues/11-align-routing-provenance-examples.md b/.scratch/offload-review-remediation/issues/11-align-routing-provenance-examples.md deleted file mode 100644 index 620c824..0000000 --- a/.scratch/offload-review-remediation/issues/11-align-routing-provenance-examples.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -id: offload-review-11 -status: published -priority: P2 -labels: [bug, review-remediation, ready-for-agent] -findings: [F-11] -blocked_by: [] ---- - -# 11. Make routing provenance examples match both validators - -Blocked by: None - -Source: [whole-skill audit](../evidence/review.md), F-11. Reviewed at `cfc9f4e` on 2026-09-03. Published as [#13](https://github.com/anthonyandrei/offload/issues/13). GitHub is the active issue tracker. - -## Problem - -The instructions attach an individual attempt as worker.routing, but both provenance validators require a schema_version and attempts container. - -## Deliverable - -Use the existing validator contract, worker.routing = {schema_version: 1, attempts: [...]}. Add a complete reusable fixture and reference it from the shared instructions and web mode. - -## Acceptance criteria - -- [ ] The exact documented worker object passes both provenance helpers and preserves all recorded attempt fields. -- [ ] A two-attempt example retains both attempts under one stable worker identity. -- [ ] The previously documented bare-attempt shape is rejected by both test paths. -- [ ] The fixture is the source of the complete example or is mechanically checked against it, so documentation and validation cannot drift silently. -- [ ] The root router remains under 500 lines and links to detail instead of duplicating the full record schema. - -## Implementation pointers - -- [SKILL.md](../../../SKILL.md) -- [modes/web-research.md](../../../modes/web-research.md) -- [tests/test_routing_provenance.ps1](../../../tests/test_routing_provenance.ps1) -- [tests/test_research_modes.sh](../../../tests/test_research_modes.sh) -- [tests/](../../../tests/) - -Evidence locations at the reviewed revision: `SKILL.md:143`, `modes/web-research.md:325`, `scripts/collect-provenance.ps1:214`. New helper or test filenames under listed directories are implementation choices. - -## Verification - -Run the PowerShell routing-provenance suite and a Bash case using the same fixture through collect-provenance.sh. Compare parsed results. - -## Scope and constraints - -Keep the existing schema version and model policy. This ticket does not make optional embedding mandatory; retention is ticket 14. - -Apply the [shared constraints and scheduling notes](../README.md). Do not modify the installed skill copy as part of this ticket. - diff --git a/.scratch/offload-review-remediation/issues/12-preserve-per-attempt-artifacts.md b/.scratch/offload-review-remediation/issues/12-preserve-per-attempt-artifacts.md deleted file mode 100644 index 52d7319..0000000 --- a/.scratch/offload-review-remediation/issues/12-preserve-per-attempt-artifacts.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -id: offload-review-12 -status: published -priority: P2 -labels: [bug, review-remediation, ready-for-agent] -findings: [F-13] -blocked_by: [] ---- - -# 12. Give every worker attempt distinct evidence paths - -Blocked by: None - -Source: [whole-skill audit](../evidence/review.md), F-13. Reviewed at `cfc9f4e` on 2026-09-03. Published as [#14](https://github.com/anthonyandrei/offload/issues/14). GitHub is the active issue tracker. - -## Problem - -Retry and revision examples reuse synthesizer.json and auditor.json. The launchers truncate those destinations, so attempt 1's routing record can point to attempt 2's output. - -## Deliverable - -Keep worker_id stable and use attempt-specific output, error, and process-artifact paths throughout dispatch/retry examples. Record an explicit accepted attempt for downstream stages. - -## Acceptance criteria - -- [ ] Initial and retry dispatch for the same worker use distinct artifact paths containing their attempt numbers. -- [ ] A fake second dispatch leaves the first output/error artifacts byte-for-byte intact. -- [ ] Both attempt records point to their own artifacts and retain the same worker_id. -- [ ] Downstream synthesis, audit, and report examples consume the explicitly selected attempt rather than whichever file was most recently overwritten. -- [ ] All three modes follow the convention, and maximum two attempts plus existing retry classification remain unchanged. - -## Implementation pointers - -- [SKILL.md](../../../SKILL.md) -- [modes/execution.md](../../../modes/execution.md) -- [modes/repo-research.md](../../../modes/repo-research.md) -- [modes/web-research.md](../../../modes/web-research.md) -- [tests/](../../../tests/) - -Evidence locations at the reviewed revision: `modes/web-research.md:200`, `modes/web-research.md:279`, `modes/web-research.md:307`. New helper or test filenames under listed directories are implementation choices. - -## Verification - -Execute two fake attempts using each shell's documented naming convention, compare first-attempt hashes, and validate the resulting routing record. No launcher auto-renaming is required. - -## Scope and constraints - -This ticket changes orchestration filenames, not model selection or retry count. Coordinate edits to execution.md with tickets 05 through 07 instead of applying concurrent edits to that file. - -Apply the [shared constraints and scheduling notes](../README.md). Do not modify the installed skill copy as part of this ticket. - diff --git a/.scratch/offload-review-remediation/issues/13-merge-only-verified-research-attempts.md b/.scratch/offload-review-remediation/issues/13-merge-only-verified-research-attempts.md deleted file mode 100644 index 7271f90..0000000 --- a/.scratch/offload-review-remediation/issues/13-merge-only-verified-research-attempts.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -id: offload-review-13 -status: published -priority: P2 -labels: [bug, review-remediation] -findings: [F-12] -blocked_by: [offload-review-02, offload-review-12] ---- - -# 13. Continue synthesis from verified successful research angles - -Blocked by: [02](./02-capture-powershell-research-output.md), [12](./12-preserve-per-attempt-artifacts.md) - -Source: [whole-skill audit](../evidence/review.md), F-12. Reviewed at `cfc9f4e` on 2026-09-03. Published as [#15](https://github.com/anthonyandrei/offload/issues/15). GitHub is the active issue tracker. - -## Problem - -The synthesis snippets glob every researcher JSON file. A failed envelope stops extraction even when two successful independent angles satisfy the documented partial-success policy. - -## Deliverable - -Build the extraction input list from the verified selected attempts, then check independent surviving research angles before synthesis. Retain failed and superseded files as diagnostics. - -## Acceptance criteria - -- [ ] Two verified successful independent angles plus one exhausted ERROR worker produce merged evidence from the two successful angles. -- [ ] A failed attempt followed by a verified retry contributes only the retry's findings. -- [ ] Completed but unverified results never enter synthesis. -- [ ] Two successful attempts for the same assignment do not count as two independent angles. -- [ ] Fewer than two surviving independent angles takes the documented fallback instead of dispatching synthesis. -- [ ] Both Bash and PowerShell snippets pass explicit selected file arrays and avoid globs that include failed or superseded envelopes. - -## Implementation pointers - -- [modes/web-research.md](../../../modes/web-research.md) -- [tests/test_research_helpers.ps1](../../../tests/test_research_helpers.ps1) -- [tests/test_research_modes.sh](../../../tests/test_research_modes.sh) - -Evidence locations at the reviewed revision: `modes/web-research.md:197`, `modes/web-research.md:210`, `modes/web-research.md:316`. New helper or test filenames under listed directories are implementation choices. - -## Verification - -Run fake researcher fixtures through the actual extraction helper in each shell, including a successful PowerShell pipeline capture from ticket 02. - -## Scope and constraints - -Keep the existing independent-angle threshold and recovery policy. Do not silently drop failing files from provenance. - -Apply the [shared constraints and scheduling notes](../README.md). Do not modify the installed skill copy as part of this ticket. - diff --git a/.scratch/offload-review-remediation/issues/14-retain-routing-history-after-cleanup.md b/.scratch/offload-review-remediation/issues/14-retain-routing-history-after-cleanup.md deleted file mode 100644 index 540c7c8..0000000 --- a/.scratch/offload-review-remediation/issues/14-retain-routing-history-after-cleanup.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -id: offload-review-14 -status: published -priority: P2 -labels: [bug, review-remediation] -findings: [F-10] -blocked_by: [offload-review-10, offload-review-11, offload-review-12] ---- - -# 14. Preserve routing history and explain pruned evidence after success - -Blocked by: [10](./10-avoid-following-cleanup-links.md), [11](./11-align-routing-provenance-examples.md), [12](./12-preserve-per-attempt-artifacts.md) - -Source: [whole-skill audit](../evidence/review.md), F-10. Reviewed at `cfc9f4e` on 2026-09-03. Published as [#16](https://github.com/anthonyandrei/offload/issues/16). GitHub is the active issue tracker. - -## Problem - -Success cleanup deletes routing-outcomes.json despite the shared requirement to maintain it. Optional web provenance embedding does not protect repository-research runs or explain deleted evidence paths. - -## Deliverable - -Preserve routing-outcomes.json on success. Before deleting raw artifacts, write and retain an evidence disposition manifest with each referenced relative path, existence before cleanup, content hash for existing regular files, and retained or pruned status. Keep raw-file pruning as the default success policy. - -## Acceptance criteria - -- [ ] Success cleanup preserves final.md, provenance.json when present, the workspace marker, routing-outcomes.json, and the evidence disposition manifest. -- [ ] Both attempts and their verification verdicts remain readable after cleanup in repository and web research fixtures. -- [ ] Every evidence path in the retained routing record has a disposition entry; missing inputs are explicitly marked missing instead of reported as pruned or verified. -- [ ] Evidence paths cannot authorize reads, hashing, attribute changes, or deletion outside the workspace or through a reparse point; external/link paths receive an explicit uninspected entry. -- [ ] An invalid routing record or failure to write the disposition manifest stops success cleanup before raw artifacts are removed. -- [ ] Failure/interruption retention remains unchanged, and repeating successful cleanup preserves the original manifest information rather than reclassifying pruned files as missing. -- [ ] Both shell families produce the same retention and disposition behavior. - -## Implementation pointers - -- [scripts/cleanup-research-workspace.ps1](../../../scripts/cleanup-research-workspace.ps1) -- [scripts/cleanup-research-workspace.sh](../../../scripts/cleanup-research-workspace.sh) -- [SKILL.md](../../../SKILL.md) -- [modes/repo-research.md](../../../modes/repo-research.md) -- [modes/web-research.md](../../../modes/web-research.md) -- [tests/test_research_helpers.ps1](../../../tests/test_research_helpers.ps1) -- [tests/test_research_modes.sh](../../../tests/test_research_modes.sh) - -Evidence locations at the reviewed revision: `scripts/cleanup-research-workspace.ps1:111`, `scripts/cleanup-research-workspace.sh:130`, `SKILL.md:120`. New helper or test filenames under listed directories are implementation choices. - -## Verification - -Run paired cleanup fixtures containing successful and failed attempts, absent optional provenance, missing evidence, and an out-of-workspace evidence reference. Verify surviving records and disposal metadata after success and after a repeated cleanup. - -## Scope and constraints - -Use a separate disposition manifest so the routing schema need not change. It records provenance of cleanup, not a claim that pruned content remains available. Do not retain complete repository snapshots by default. - -Apply the [shared constraints and scheduling notes](../README.md). Do not modify the installed skill copy as part of this ticket. - diff --git a/.scratch/offload-review-remediation/publish-issues.ps1 b/.scratch/offload-review-remediation/publish-issues.ps1 deleted file mode 100644 index 8dea946..0000000 --- a/.scratch/offload-review-remediation/publish-issues.ps1 +++ /dev/null @@ -1,151 +0,0 @@ -$ErrorActionPreference = 'Stop' -Set-StrictMode -Version 3.0 -$repo = 'anthonyandrei/offload' -$root = $PSScriptRoot -$manifest = Get-Content -LiteralPath (Join-Path $root 'tickets.json') -Raw | ConvertFrom-Json -$revision = 'cfc9f4edc219b199c5c243c95f91fa2c463d137d' -$baseUrl = "https://github.com/$repo" -$publicationDir = Join-Path $root 'github' -New-Item -ItemType Directory -Path $publicationDir -Force | Out-Null - -function Invoke-GhChecked { - param([string[]]$GhArgs) - $result = & gh @GhArgs - if ($LASTEXITCODE -ne 0) { throw "gh failed with exit $LASTEXITCODE for $($GhArgs[0])" } - return $result -} - -$existingLabels = @(Invoke-GhChecked @('label','list','--repo',$repo,'--limit','100','--json','name') | ConvertFrom-Json) -foreach ($definition in @( - @{ name = 'ready-for-agent'; color = '0E8A16'; description = 'No outstanding prerequisite issues; scoped and ready for implementation' }, - @{ name = 'review-remediation'; color = '5319E7'; description = 'Confirmed findings from the 2026-09-03 whole-skill review' } -)) { - if ($definition.name -notin @($existingLabels.name)) { - Invoke-GhChecked @('label','create',$definition.name,'--repo',$repo,'--color',$definition.color,'--description',$definition.description) | Out-Null - } -} - -$existing = @(Invoke-GhChecked @('issue','list','--repo',$repo,'--state','all','--limit','200','--json','number,title,body,url,labels') | ConvertFrom-Json) -$published = [ordered]@{} -foreach ($ticket in $manifest.tickets) { - $marker = "" - $matches = @($existing | Where-Object { $_.body.Contains($marker) }) - if ($matches.Count -gt 1) { throw "Duplicate publication markers for ticket $($ticket.id)" } - if ($matches.Count -eq 1) { - $published[$ticket.id] = [ordered]@{ id = $ticket.id; number = $matches[0].number; url = $matches[0].url; title = $ticket.title } - } -} - -function Resolve-TicketReferences { - param([string]$Text) - $Text = $Text.Replace("the audit's uninvoked-test-blocks.json", 'the Source evidence section below') - $Text = [regex]::Replace($Text, '(?i)\btickets (\d{2}) (and|through) (\d{2})\b', { - param($match) - $first = $match.Groups[1].Value - $last = $match.Groups[3].Value - if ($published.Contains($first) -and $published.Contains($last)) { - $ids = if ($match.Groups[2].Value -eq 'through') { @([int]$first..[int]$last | ForEach-Object { '{0:D2}' -f $_ }) } else { @($first, $last) } - return (@($ids | ForEach-Object { "#$($published[$_].number)" }) -join ', ') - } - return $match.Value - }) - return [regex]::Replace($Text, '(?i)\bticket (\d{2})\b', { - param($match) - $id = $match.Groups[1].Value - if ($published.Contains($id)) { return "#$($published[$id].number)" } - return "remediation ticket $id" - }) -} - -function New-IssueBody { - param($Ticket) - $lines = [System.Collections.Generic.List[string]]::new() - $lines.Add("") - $lines.Add('') - $blockers = @($Ticket.blocked | ForEach-Object { - if (-not $published.Contains($_)) { throw "Missing published blocker $_" } - "#$($published[$_].number)" - }) - $lines.Add($(if ($blockers.Count) { 'Blocked by: ' + ($blockers -join ', ') } else { 'Blocked by: None' })) - $lines.Add('') - $lines.Add("Priority: $($Ticket.priority). Review findings: $($Ticket.findings -join ', '). Remediation ticket $($Ticket.id) of 14.") - $lines.Add('') - $lines.Add("Reviewed 2026-09-03 against [$($revision.Substring(0,7))]($baseUrl/commit/$revision).") - foreach ($section in @( - @{ heading = 'Problem'; content = $Ticket.problem }, - @{ heading = 'Deliverable'; content = $Ticket.deliverable } - )) { - $lines.Add(''); $lines.Add("## $($section.heading)"); $lines.Add('') - $lines.Add((Resolve-TicketReferences $section.content)) - } - $lines.Add(''); $lines.Add('## Acceptance criteria'); $lines.Add('') - foreach ($criterion in $Ticket.accept) { $lines.Add('- [ ] ' + (Resolve-TicketReferences $criterion)) } - $lines.Add(''); $lines.Add('## Source evidence'); $lines.Add('') - foreach ($reference in $Ticket.refs) { - $parts = $reference -split ':' - $lines.Add("- [$reference]($baseUrl/blob/$revision/$($parts[0])#L$($parts[1]))") - } - if ($Ticket.id -eq '01') { - $groups = Get-Content -LiteralPath (Join-Path $root 'evidence/uninvoked-test-blocks.json') -Raw | ConvertFrom-Json - $ranges = @($groups | ForEach-Object { "$($_.start)-$($_.end)" }) -join ', ' - $lines.Add('') - $lines.Add("The audit identified these 50 uninvoked script-block line ranges in the linked test file at the reviewed revision: $ranges.") - } - $lines.Add(''); $lines.Add('## Implementation pointers'); $lines.Add('') - foreach ($file in $Ticket.files) { - $kind = if ($file.EndsWith('/')) { 'tree' } else { 'blob' } - $lines.Add("- [$file]($baseUrl/$kind/$revision/$file)") - } - $lines.Add(''); $lines.Add('New helper or test filenames under listed directories are implementation choices.') - $lines.Add(''); $lines.Add('## Verification'); $lines.Add('') - $lines.Add((Resolve-TicketReferences $Ticket.verify)) - $lines.Add(''); $lines.Add('## Scope and constraints'); $lines.Add('') - $lines.Add((Resolve-TicketReferences $Ticket.limits)) - $lines.Add('') - $lines.Add('- Work in the source repository. Do not update installed skill copies as part of this issue.') - $lines.Add('- Preserve the Gemini model policy, role routing, maximum two attempts, and immediate quota handoff.') - $lines.Add('- Preserve Bash 3.2+ compatibility and native PowerShell 7 support. Add no Windows requirement for Bash, Python, or jq.') - $lines.Add('- Keep the root SKILL.md router below 500 lines; place detailed workflow contracts in the mode documents or supporting files.') - $lines.Add('- Use fake workers and disposable repositories for regressions. Verify resolved cleanup paths stay inside the test root.') - $lines.Add('- Shared-file edits still require serialized integration even when issues have no dependency edge.') - $lines.Add('- Do not use the existing shared-tree offload execution workflow for these fixes until its migration is complete. Use direct orchestration or independently verified isolated checkouts.') - $lines.Add('') - $lines.Add('The original review exercised PowerShell 7 and Git Bash on Windows. Native Linux, macOS, and Bash 3.2 were not exercised. Record the platforms used for this issue rather than claiming untested parity.') - return ($lines -join "`n") + "`n" -} - -foreach ($ticket in $manifest.tickets) { - if ($published.Contains($ticket.id)) { continue } - $bodyPath = Join-Path $publicationDir "$($ticket.id)-body.md" - New-IssueBody $ticket | Set-Content -LiteralPath $bodyPath -Encoding utf8 -NoNewline - $labels = if ($ticket.blocked.Count -eq 0) { 'bug,review-remediation,ready-for-agent' } else { 'bug,review-remediation' } - $url = [string](Invoke-GhChecked @('issue','create','--repo',$repo,'--title',"[$($ticket.priority)] $($ticket.title)",'--body-file',$bodyPath,'--label',$labels)) - $url = $url.Trim() - if ($url -notmatch '/issues/(\d+)$') { throw "Could not parse created issue URL: $url" } - $published[$ticket.id] = [ordered]@{ id = $ticket.id; number = [int]$Matches[1]; url = $url; title = $ticket.title } - @($published.Values) | ConvertTo-Json -Depth 8 | Set-Content -LiteralPath (Join-Path $root 'github-issues.json') -Encoding utf8 - Write-Output "$($ticket.id): $url" -} - -# Resolve references to later tickets after all issue numbers exist. -foreach ($ticket in $manifest.tickets) { - $bodyPath = Join-Path $publicationDir "$($ticket.id)-body.md" - $body = New-IssueBody $ticket - $oldBody = Get-Content -LiteralPath $bodyPath -Raw - if ($body -cne $oldBody) { - $body | Set-Content -LiteralPath $bodyPath -Encoding utf8 -NoNewline - Invoke-GhChecked @('issue','edit',[string]$published[$ticket.id].number,'--repo',$repo,'--body-file',$bodyPath) | Out-Null - } -} - -$remote = @(Invoke-GhChecked @('issue','list','--repo',$repo,'--state','all','--label','review-remediation','--limit','100','--json','number,title,body,url,labels,state') | ConvertFrom-Json) -foreach ($ticket in $manifest.tickets) { - $actual = @($remote | Where-Object { $_.number -eq $published[$ticket.id].number }) - if ($actual.Count -ne 1 -or $actual[0].state -ne 'OPEN') { throw "Missing open issue $($ticket.id)" } - $expectedBody = New-IssueBody $ticket - if ($actual[0].body.TrimEnd() -cne $expectedBody.TrimEnd()) { throw "Remote body mismatch for $($ticket.id)" } - $ready = 'ready-for-agent' -in @($actual[0].labels.name) - if ($ready -ne ($ticket.blocked.Count -eq 0)) { throw "Incorrect ready label for $($ticket.id)" } -} -[ordered]@{ status = 'verified'; repository = $repo; issues = $published.Count; ready = @($manifest.tickets | Where-Object { $_.blocked.Count -eq 0 }).Count; verified_at = (Get-Date).ToString('o') } | ConvertTo-Json | Set-Content -LiteralPath (Join-Path $root 'github-publication.json') -Encoding utf8 -Write-Output 'Verified all 14 remote issue bodies, open states, dependencies, and readiness labels.' diff --git a/.scratch/offload-review-remediation/tickets.json b/.scratch/offload-review-remediation/tickets.json deleted file mode 100644 index 4884b61..0000000 --- a/.scratch/offload-review-remediation/tickets.json +++ /dev/null @@ -1,505 +0,0 @@ -{ - "schema_version": 1, - "status": "published", - "source_revision": "cfc9f4e", - "date": "2026-09-03", - "tickets": [ - { - "id": "01", - "slug": "execute-model-routing-tests", - "title": "Execute every PowerShell model-routing test group", - "priority": "P2", - "findings": [ - "F-09" - ], - "blocked": [], - "problem": "Fifty bare script blocks in tests/test_model_routing.ps1 create ScriptBlock objects without running their assertions. The existing green result covers only the invoked portions.", - "files": [ - "tests/test_model_routing.ps1" - ], - "refs": [ - "tests/test_model_routing.ps1:366" - ], - "deliverable": "Invoke the dormant groups and make their failures propagate to the test command. Keep the existing test intent and isolate each fixture as needed.", - "accept": [ - "Every one of the 50 groups listed in the audit's uninvoked-test-blocks.json executes rather than printing its source.", - "A deliberate assertion failure in a representative formerly dormant group makes a disposable copy of the suite exit nonzero.", - "The ordinary suite exits zero after the exercised behavior is verified. Any newly exposed production defect is documented as a blocker instead of weakening or skipping its assertion.", - "Test output distinguishes executed assertions from script text; the existing invoked assertions still run." - ], - "verify": "Run pwsh -NoProfile -File tests/test_model_routing.ps1, plus the deliberate-failure check in a disposable copy. No live AGY call is needed.", - "limits": "This ticket repairs test execution. Do not change model defaults, retry limits, or production behavior merely to turn the suite green.", - "github_url": "https://github.com/anthonyandrei/offload/issues/3", - "github_number": 3 - }, - { - "id": "02", - "slug": "capture-powershell-research-output", - "title": "Make documented PowerShell research handoffs return usable values", - "priority": "P1", - "findings": [ - "F-01" - ], - "blocked": [], - "problem": "The workspace and extraction helpers write to Console.Out, while the mode examples capture the PowerShell pipeline. Workspace.Trim() fails on null, and merged researcher evidence can silently become null.", - "files": [ - "scripts/make-research-workspace.ps1", - "scripts/extract-structured-output.ps1", - "modes/repo-research.md", - "modes/web-research.md", - "tests/test_research_helpers.ps1" - ], - "refs": [ - "scripts/make-research-workspace.ps1:170", - "scripts/extract-structured-output.ps1:77", - "modes/repo-research.md:40", - "modes/web-research.md:211" - ], - "deliverable": "Make the helpers emit their result through the PowerShell pipeline and keep diagnostics on the error channel. Test the exact documented in-process assignments and native pwsh -File invocation.", - "accept": [ - "The documented workspace assignment returns one nonempty existing workspace path and .Trim() succeeds.", - "The documented extraction assignment for two valid researcher envelopes returns nonempty JSON containing both findings.", - "Both direct & invocation and native pwsh -File invocation return the same semantic payload without diagnostic text mixed into JSON.", - "Invalid input still fails with the intended exit/error contract, and the mode examples match the tested commands." - ], - "verify": "Add workflow-shaped cases to tests/test_research_helpers.ps1 using disposable workspaces and fixture envelopes, then run that suite.", - "limits": "Keep the Windows workflow native to PowerShell 7. Do not add Bash, jq, or Python dependencies.", - "github_url": "https://github.com/anthonyandrei/offload/issues/4", - "github_number": 4 - }, - { - "id": "03", - "slug": "verify-baseline-relative-scope", - "title": "Check committed and working-tree edits against a fixed baseline", - "priority": "P1", - "findings": [ - "F-03", - "F-06" - ], - "blocked": [], - "problem": "The scope helpers trust git status. A worker can commit a frozen or unowned edit and pass with a clean status. Bash also returns success when the git status command in process substitution fails.", - "files": [ - "scripts/check-execution-scope.ps1", - "scripts/check-execution-scope.sh", - "tests/test_execution_scope.ps1", - "tests/test_execution_scope.sh" - ], - "refs": [ - "scripts/check-execution-scope.ps1:145", - "scripts/check-execution-scope.sh:138" - ], - "deliverable": "Expand the paired helper contract with an explicit immutable baseline revision. Compute the complete final delta against that revision and compare frozen contents with the baseline. Preserve the old call form only until ticket 05 migrates callers.", - "accept": [ - "A committed unowned edit and a committed frozen edit both produce nonzero results even when git status is clean.", - "Owned-only committed, staged, unstaged, and new-file changes pass; unowned or frozen changes in each applicable state fail.", - "Renames and deletions check all affected paths, with existing path normalization and NUL-safe filename handling preserved.", - "Missing or invalid supplied baselines fail; the helper never silently substitutes current HEAD for a supplied baseline.", - "A mocked git status failure with exit 73, and failures of any other Git query used for verification, produce nonzero helper results.", - "Both shell families expose equivalent baseline semantics and diagnostics." - ], - "verify": "Extend and run both execution-scope suites with temporary Git repositories and controlled Git failure mocks. Check final content relative to the captured baseline, not a worker-reported revision.", - "limits": "This is the expand stage. Temporary compatibility is not sufficient to close F-03; ticket 05 must require the baseline in every execution workflow. Worktrees and baseline checks are not an OS write sandbox.", - "github_url": "https://github.com/anthonyandrei/offload/issues/5", - "github_number": 5 - }, - { - "id": "04", - "slug": "add-isolated-execution-workspaces", - "title": "Add a verified lifecycle for isolated execution worktrees", - "priority": "P1", - "findings": [ - "F-02" - ], - "blocked": [ - "03" - ], - "problem": "Per-worker ownership cannot be checked reliably while multiple writers share one working tree. The execution workflow needs a small, tested mechanism for creating isolated candidates and importing only their verified changes.", - "files": [ - "scripts/", - "tests/", - "docs/adr/" - ], - "refs": [ - "modes/execution.md:136", - "modes/execution.md:178" - ], - "deliverable": "Add paired shell-native execution-workspace helpers with a narrow create, verify/export, integrate, and cleanup contract. Store an orchestrator-owned manifest outside the worker checkout with task identity, absolute paths, baseline revision, and owned/frozen paths. Keep this beside the current workflow until ticket 05.", - "accept": [ - "Two workers starting from the same baseline can independently edit a.txt and b.txt, and each scope check passes against only its own candidate.", - "An unowned or frozen change in either candidate blocks export/integration, including when the worker has committed it.", - "Export captures committed and uncommitted final changes and records a content digest; integration consumes only that verified artifact.", - "Integration into a disposable integration checkout preflights the whole change, detects conflicts, and retains candidates on failure without partially publishing changes to the caller checkout.", - "Creation and cleanup only operate on manifest-owned paths; no existing caller checkout or unrelated worktree is reset, cleaned, or removed.", - "The paired helpers pass equivalent disposable-repository cases and add no Windows dependency beyond PowerShell 7 and Git." - ], - "verify": "Add focused lifecycle suites for both shells using fake workers. Exercise two sibling tasks, a scope violation, an integration conflict, and cleanup ownership guards.", - "limits": "This is an additive workspace capability. Keep its interface small enough for ticket 05 to use directly. Do not build a general scheduler or change the model policy. Record the worktree decision in a short ADR.", - "github_url": "https://github.com/anthonyandrei/offload/issues/6", - "github_number": 6 - }, - { - "id": "05", - "slug": "migrate-execution-to-isolated-workers", - "title": "Run execution stages through isolated workspaces and retire shared-tree dispatch", - "priority": "P1", - "findings": [ - "F-02", - "F-03" - ], - "blocked": [ - "03", - "04" - ], - "problem": "Adding baseline and workspace helpers does not fix the existing instructions. Gate authors still write before an untouched baseline is established, and implementers still share the caller's tree.", - "files": [ - "modes/execution.md", - "SKILL.md", - "README.md", - "AGENTS.md", - "CLAUDE.md", - "CONTEXT.md", - "scripts/check-execution-scope.ps1", - "scripts/check-execution-scope.sh", - "tests/test_workflow_static.ps1", - "tests/" - ], - "refs": [ - "modes/execution.md:90", - "modes/execution.md:132", - "modes/execution.md:136", - "modes/execution.md:178" - ], - "deliverable": "Migrate gate-author and implementer dispatch to ticket 04's lifecycle. Verify gate authors against the original baseline before importing approved tests into an integration checkout. Freeze that gate baseline before creating implementer worktrees. Retire no-baseline scope calls and shared-tree writing examples.", - "accept": [ - "The documented Bash and PowerShell machine-gated flow completes with two disjoint fake implementers and imports both verified changes without sibling scope failures.", - "A gate author that commits an unowned source edit is rejected before its output can become the implementation baseline.", - "Implementers receive the approved frozen gates and an externally recorded baseline; committed gate edits are rejected.", - "Overlapping assignments run serially from the newly accepted baseline, and all accepted deltas undergo scope and gate verification before publication to the caller.", - "Retries retain the original verification baseline for that writing stage; a failed attempt never becomes an implicitly trusted baseline.", - "Quota handoff records still-running candidates and artifacts immediately without waiting for sibling completion; normal cleanup waits for workers to stop.", - "All execution-mode examples supply a baseline and isolated working directory, and the scope helpers reject omitted baselines after migration.", - "A final combined gate check runs before publishing the integrated result; conflicts or failed gates leave the caller's existing work intact." - ], - "verify": "Run executable workflow cases with fake AGY workers for both shell families, the scope suites, and relevant static checks. Inspect current architecture pointers for agreement with the migrated mode.", - "limits": "This ticket is the migrate and contract stage for one execution mode. Use the helpers from ticket 04 rather than adding another orchestration framework. Diff-review completeness and acceptance remain tickets 06 and 07.", - "github_url": "https://github.com/anthonyandrei/offload/issues/7", - "github_number": 7 - }, - { - "id": "06", - "slug": "review-complete-change-artifacts", - "title": "Review one complete change artifact against the execution baseline", - "priority": "P1", - "findings": [ - "F-04" - ], - "blocked": [ - "05" - ], - "problem": "Bare git diff omits staged changes and new files. Reviewers and quote matching can agree on an incomplete diff and still miss part of a task.", - "files": [ - "modes/execution.md", - "scripts/", - "tests/" - ], - "refs": [ - "modes/execution.md:216", - "modes/execution.md:232", - "modes/execution.md:242" - ], - "deliverable": "Produce one immutable review artifact from each verified candidate and its recorded baseline, then pass the identical artifact to the reviewer and quote verifier. Reuse the delta export from ticket 04 where possible.", - "accept": [ - "A fixture containing a committed edit, staged edit, unstaged edit, and new file exposes every final change to review.", - "Deletion and rename information is present, and binary changes are explicitly identified for direct review instead of silently omitted.", - "The reviewer prompt reads the recorded artifact rather than running an independent bare git diff.", - "Quote verification uses the exact artifact bytes or their verified digest; modifying the candidate after artifact creation cannot silently change the evidence being accepted.", - "Git or artifact-generation failures prevent review acceptance, and both shells produce equivalent review coverage." - ], - "verify": "Add focused artifact-generation tests and execute the documented reviewer handoff with a fake reviewer. Compare the artifact's path/content coverage with the baseline delta.", - "limits": "This ticket guarantees complete evidence. Ticket 07 adds exhaustive criterion coverage; do not treat successful quote lookup alone as sufficient acceptance.", - "github_url": "https://github.com/anthonyandrei/offload/issues/8", - "github_number": 8 - }, - { - "id": "07", - "slug": "require-complete-reviewer-verdicts", - "title": "Require one valid reviewer verdict for every requested criterion", - "priority": "P1", - "findings": [ - "F-05" - ], - "blocked": [ - "06" - ], - "problem": "The reviewer schema accepts an empty criteria array, and the workflow accepts when all returned quotes match. Empty or partial responses can therefore pass without addressing the task.", - "files": [ - "modes/execution.md", - "scripts/", - "tests/" - ], - "refs": [ - "modes/execution.md:210", - "modes/execution.md:246" - ], - "deliverable": "Assign stable IDs to requested criteria and add a mechanical coverage check in both shell workflows before accepting any reviewer response.", - "accept": [ - "Empty output is rejected when criteria were requested.", - "Missing, duplicate, and unknown criterion IDs are rejected, even when every returned quote exists in the artifact.", - "Each requested criterion has exactly one verdict; fail or hedge prevents automated acceptance.", - "Every pass has a literal matching evidence line from ticket 06's artifact, with matching performed on data rather than interpolated shell code.", - "A complete all-pass response with valid evidence is accepted, and malformed or incomplete responses route to direct orchestrator review." - ], - "verify": "Use fixed criterion sets and fake reviewer envelopes for empty, partial, duplicate, unknown, failed, hedged, forged-quote, and complete outputs. Exercise both documented shell flows.", - "limits": "A minimum array length alone does not establish coverage. Preserve the existing direct-review fallback and bounded retry policy.", - "github_url": "https://github.com/anthonyandrei/offload/issues/9", - "github_number": 9 - }, - { - "id": "08", - "slug": "require-complete-citation-audits", - "title": "Require audit coverage for every claim and citation pair", - "priority": "P1", - "findings": [ - "F-05" - ], - "blocked": [], - "problem": "The auditor schema accepts an empty citation_audits array with final_status pass. The workflow does not compare returned audits with the synthesis claim ledger.", - "files": [ - "modes/web-research.md", - "scripts/", - "tests/test_research_modes.sh", - "tests/test_workflow_static.ps1", - "tests/" - ], - "refs": [ - "modes/web-research.md:292", - "modes/web-research.md:306" - ], - "deliverable": "Derive the required claim_id and URL pairs from the ledger and validate exact audit coverage and verdict consistency before accepting the synthesis.", - "accept": [ - "A nonempty required pair set rejects empty or partial citation_audits even when final_status is pass.", - "Duplicate and unknown claim/citation pairs are rejected; two citations for one claim require separate coverage.", - "Every required pair has one supported verdict before automated acceptance, and failed or unresolved entries cannot coexist with an accepted overall pass.", - "A ledger with no auditable pairs follows an explicit documented branch and cannot bypass citations required by the research assignment.", - "Complete valid coverage passes in both shell workflows; invalid responses follow the existing bounded revision or orchestrator fallback path." - ], - "verify": "Run fixture-based audit acceptance tests for empty, partial, duplicate, unknown, contradictory, and complete results. Use synthetic ledger data and no live browsing.", - "limits": "Do not change what constitutes a trustworthy source in this ticket. This fix checks coverage and internal consistency of the required audit.", - "github_url": "https://github.com/anthonyandrei/offload/issues/10", - "github_number": 10 - }, - { - "id": "09", - "slug": "close-launcher-failure-lifetime", - "title": "Prevent orphaned workers when PowerShell output setup fails", - "priority": "P2", - "findings": [ - "F-07" - ], - "blocked": [ - "01" - ], - "problem": "The PowerShell launcher starts AGY before opening output streams. If stream creation fails, the child escapes cleanup and continues running after the launcher exits.", - "files": [ - "scripts/run-agy-json.ps1", - "tests/test_model_routing.ps1" - ], - "refs": [ - "scripts/run-agy-json.ps1:408", - "scripts/run-agy-json.ps1:413" - ], - "deliverable": "Validate destinations and open owned resources before starting the child. Put every post-start operation under a cleanup path that terminates and waits for the child on launcher failure and disposes streams.", - "accept": [ - "Identical output/error paths fail before a fake worker starts.", - "Locked or invalid output destinations fail without starting a worker.", - "A controlled exception after launch causes the child to stop before the launcher returns; no completion marker appears afterward.", - "Streams are disposed on success, launch failure, and post-launch failure, so the output files can be reopened.", - "Successful launch output, error capture, process metadata, exit codes, and explicit quota handoff behavior remain consistent with their existing contracts." - ], - "verify": "Use the now-executed PowerShell suite and disposable fake workers that write delayed markers. Do not consume live AGY quota.", - "limits": "The blocker establishes that routing test groups actually execute. If new cases belong in a separate focused suite, keep that suite explicitly invoked.", - "github_url": "https://github.com/anthonyandrei/offload/issues/11", - "github_number": 11 - }, - { - "id": "10", - "slug": "avoid-following-cleanup-links", - "title": "Keep PowerShell cleanup inside the marked workspace", - "priority": "P2", - "findings": [ - "F-08" - ], - "blocked": [], - "problem": "Cleanup checks top-level links but recursively enumerates files under ordinary directories. A nested junction lets attribute changes reach a sibling directory outside the workspace.", - "files": [ - "scripts/cleanup-research-workspace.ps1", - "tests/test_research_helpers.ps1" - ], - "refs": [ - "scripts/cleanup-research-workspace.ps1:122" - ], - "deliverable": "Traverse entries without following reparse points at any depth. Remove the link itself, and only clear file attributes within the verified workspace traversal.", - "accept": [ - "A nested junction to a controlled sibling fixture is removed without changing the target's file content, existence, or read-only attributes.", - "Ordinary read-only workspace files are removed on success, and retained report/provenance files remain intact.", - "Top-level and nested links use the same no-follow rule.", - "Marker validation, Git-root rejection, and other protected-path checks still fail safely.", - "Tests resolve and verify every destructive fixture path inside a dedicated temporary test root before cleanup; no external or user-owned directory is used." - ], - "verify": "Add and run controlled junction fixtures in tests/test_research_helpers.ps1 on Windows. Use existing-target links for the confirmed reproduction; record platform limitations rather than inventing unsupported coverage.", - "limits": "The separate dangling-link allegation was not verified in the audit and is not a required reproduction. Preserve failure retention behavior.", - "github_url": "https://github.com/anthonyandrei/offload/issues/12", - "github_number": 12 - }, - { - "id": "11", - "slug": "align-routing-provenance-examples", - "title": "Make routing provenance examples match both validators", - "priority": "P2", - "findings": [ - "F-11" - ], - "blocked": [], - "problem": "The instructions attach an individual attempt as worker.routing, but both provenance validators require a schema_version and attempts container.", - "files": [ - "SKILL.md", - "modes/web-research.md", - "tests/test_routing_provenance.ps1", - "tests/test_research_modes.sh", - "tests/" - ], - "refs": [ - "SKILL.md:143", - "modes/web-research.md:325", - "scripts/collect-provenance.ps1:214" - ], - "deliverable": "Use the existing validator contract, worker.routing = {schema_version: 1, attempts: [...]}. Add a complete reusable fixture and reference it from the shared instructions and web mode.", - "accept": [ - "The exact documented worker object passes both provenance helpers and preserves all recorded attempt fields.", - "A two-attempt example retains both attempts under one stable worker identity.", - "The previously documented bare-attempt shape is rejected by both test paths.", - "The fixture is the source of the complete example or is mechanically checked against it, so documentation and validation cannot drift silently.", - "The root router remains under 500 lines and links to detail instead of duplicating the full record schema." - ], - "verify": "Run the PowerShell routing-provenance suite and a Bash case using the same fixture through collect-provenance.sh. Compare parsed results.", - "limits": "Keep the existing schema version and model policy. This ticket does not make optional embedding mandatory; retention is ticket 14.", - "github_url": "https://github.com/anthonyandrei/offload/issues/13", - "github_number": 13 - }, - { - "id": "12", - "slug": "preserve-per-attempt-artifacts", - "title": "Give every worker attempt distinct evidence paths", - "priority": "P2", - "findings": [ - "F-13" - ], - "blocked": [], - "problem": "Retry and revision examples reuse synthesizer.json and auditor.json. The launchers truncate those destinations, so attempt 1's routing record can point to attempt 2's output.", - "files": [ - "SKILL.md", - "modes/execution.md", - "modes/repo-research.md", - "modes/web-research.md", - "tests/" - ], - "refs": [ - "modes/web-research.md:200", - "modes/web-research.md:279", - "modes/web-research.md:307" - ], - "deliverable": "Keep worker_id stable and use attempt-specific output, error, and process-artifact paths throughout dispatch/retry examples. Record an explicit accepted attempt for downstream stages.", - "accept": [ - "Initial and retry dispatch for the same worker use distinct artifact paths containing their attempt numbers.", - "A fake second dispatch leaves the first output/error artifacts byte-for-byte intact.", - "Both attempt records point to their own artifacts and retain the same worker_id.", - "Downstream synthesis, audit, and report examples consume the explicitly selected attempt rather than whichever file was most recently overwritten.", - "All three modes follow the convention, and maximum two attempts plus existing retry classification remain unchanged." - ], - "verify": "Execute two fake attempts using each shell's documented naming convention, compare first-attempt hashes, and validate the resulting routing record. No launcher auto-renaming is required.", - "limits": "This ticket changes orchestration filenames, not model selection or retry count. Coordinate edits to execution.md with tickets 05 through 07 instead of applying concurrent edits to that file.", - "github_url": "https://github.com/anthonyandrei/offload/issues/14", - "github_number": 14 - }, - { - "id": "13", - "slug": "merge-only-verified-research-attempts", - "title": "Continue synthesis from verified successful research angles", - "priority": "P2", - "findings": [ - "F-12" - ], - "blocked": [ - "02", - "12" - ], - "problem": "The synthesis snippets glob every researcher JSON file. A failed envelope stops extraction even when two successful independent angles satisfy the documented partial-success policy.", - "files": [ - "modes/web-research.md", - "tests/test_research_helpers.ps1", - "tests/test_research_modes.sh" - ], - "refs": [ - "modes/web-research.md:197", - "modes/web-research.md:210", - "modes/web-research.md:316" - ], - "deliverable": "Build the extraction input list from the verified selected attempts, then check independent surviving research angles before synthesis. Retain failed and superseded files as diagnostics.", - "accept": [ - "Two verified successful independent angles plus one exhausted ERROR worker produce merged evidence from the two successful angles.", - "A failed attempt followed by a verified retry contributes only the retry's findings.", - "Completed but unverified results never enter synthesis.", - "Two successful attempts for the same assignment do not count as two independent angles.", - "Fewer than two surviving independent angles takes the documented fallback instead of dispatching synthesis.", - "Both Bash and PowerShell snippets pass explicit selected file arrays and avoid globs that include failed or superseded envelopes." - ], - "verify": "Run fake researcher fixtures through the actual extraction helper in each shell, including a successful PowerShell pipeline capture from ticket 02.", - "limits": "Keep the existing independent-angle threshold and recovery policy. Do not silently drop failing files from provenance.", - "github_url": "https://github.com/anthonyandrei/offload/issues/15", - "github_number": 15 - }, - { - "id": "14", - "slug": "retain-routing-history-after-cleanup", - "title": "Preserve routing history and explain pruned evidence after success", - "priority": "P2", - "findings": [ - "F-10" - ], - "blocked": [ - "10", - "11", - "12" - ], - "problem": "Success cleanup deletes routing-outcomes.json despite the shared requirement to maintain it. Optional web provenance embedding does not protect repository-research runs or explain deleted evidence paths.", - "files": [ - "scripts/cleanup-research-workspace.ps1", - "scripts/cleanup-research-workspace.sh", - "SKILL.md", - "modes/repo-research.md", - "modes/web-research.md", - "tests/test_research_helpers.ps1", - "tests/test_research_modes.sh" - ], - "refs": [ - "scripts/cleanup-research-workspace.ps1:111", - "scripts/cleanup-research-workspace.sh:130", - "SKILL.md:120" - ], - "deliverable": "Preserve routing-outcomes.json on success. Before deleting raw artifacts, write and retain an evidence disposition manifest with each referenced relative path, existence before cleanup, content hash for existing regular files, and retained or pruned status. Keep raw-file pruning as the default success policy.", - "accept": [ - "Success cleanup preserves final.md, provenance.json when present, the workspace marker, routing-outcomes.json, and the evidence disposition manifest.", - "Both attempts and their verification verdicts remain readable after cleanup in repository and web research fixtures.", - "Every evidence path in the retained routing record has a disposition entry; missing inputs are explicitly marked missing instead of reported as pruned or verified.", - "Evidence paths cannot authorize reads, hashing, attribute changes, or deletion outside the workspace or through a reparse point; external/link paths receive an explicit uninspected entry.", - "An invalid routing record or failure to write the disposition manifest stops success cleanup before raw artifacts are removed.", - "Failure/interruption retention remains unchanged, and repeating successful cleanup preserves the original manifest information rather than reclassifying pruned files as missing.", - "Both shell families produce the same retention and disposition behavior." - ], - "verify": "Run paired cleanup fixtures containing successful and failed attempts, absent optional provenance, missing evidence, and an out-of-workspace evidence reference. Verify surviving records and disposal metadata after success and after a repeated cleanup.", - "limits": "Use a separate disposition manifest so the routing schema need not change. It records provenance of cleanup, not a claim that pruned content remains available. Do not retain complete repository snapshots by default.", - "github_url": "https://github.com/anthonyandrei/offload/issues/16", - "github_number": 16 - } - ] -} diff --git a/.scratch/offload-review-remediation/validation.json b/.scratch/offload-review-remediation/validation.json deleted file mode 100644 index acdd10c..0000000 --- a/.scratch/offload-review-remediation/validation.json +++ /dev/null @@ -1,37 +0,0 @@ -{ - "schema_version": 1, - "status": "passed", - "checked_at": "2026-09-03T04:23:04.9722708+08:00", - "source_revision": "cfc9f4edc219b199c5c243c95f91fa2c463d137d", - "tickets": 14, - "acceptance_criteria": 76, - "dependency_order": "topological", - "findings_covered": [ - "F-01", - "F-02", - "F-03", - "F-04", - "F-05", - "F-06", - "F-07", - "F-08", - "F-09", - "F-10", - "F-11", - "F-12", - "F-13" - ], - "dependency_ready": [ - "01", - "02", - "03", - "08", - "10", - "11", - "12" - ], - "local_links_checked": 128, - "evidence_copies_hash_verified": 7, - "errors": [], - "scope": "Draft structure, source pointers, finding coverage, graph order, local links, and evidence copies only. No implementation tests were run." -} diff --git a/.scratch/offload-verification-hardening/spec.md b/.scratch/offload-verification-hardening/spec.md deleted file mode 100644 index c27bf6f..0000000 --- a/.scratch/offload-verification-hardening/spec.md +++ /dev/null @@ -1,363 +0,0 @@ ---- -status: ready-for-agent -labels: - - ready-for-agent -date: 2026-09-04 ---- - -# Offload verification and launcher hardening - -Status: ready for implementation. - -Publication: local scratch specification. This repository has no configured issue-tracker workflow, and this task did -not authorize publishing an external issue. - -## Problem - -The accepted review identified three correctness gaps in the current offload workflow: - -1. The PowerShell launcher can start `agy` with a child process working directory different from the caller's current - workspace. Relative paths in a worker prompt can therefore resolve against the launcher repository instead of the - isolated research workspace. -2. `cleanup-research-workspace` treats the top-level `routing-outcomes.json.attempts` array as if it could contain at most - two entries total. A valid run with several workers can contain one or two attempts per worker and is rejected. The - current uniqueness check also treats the attempt number as globally unique instead of unique per worker. -3. A worker process can exit successfully while returning missing, empty, malformed, or unverified work. The workflow - needs to keep process completion, artifact validity, and verification status separate. - -The live compatibility probe against the installed `agy` 1.1.25 also clarified the plan-mode contract. The plan arm and -no-mode arm exposed the same 57 tools and `always-proceed` permission mode. Plan mode added a plan system command and -the tested direct write to the scratch path was rejected, while the no-mode arm wrote its sentinel. This is useful -version-specific evidence, but it does not prove that plan mode is a complete write boundary: other tools and command -paths remain available, and `--add-dir` grants access without confining writes. - -## Intended result - -Make the workflow's actual safety and acceptance boundaries explicit and mechanically enforceable: - -- read workers continue to receive `--mode plan`, but documentation treats it as a behavioral hint; -- research workers remain isolated from the live repository and execution workers remain protected by scope and gate - checks; -- PowerShell launches `agy` in the caller-declared workspace; -- routing history supports any number of logical workers while enforcing at most two attempts per worker; -- successful process exit never bypasses structured-output, artifact, scope, or review gates; -- gate commands that cannot run are reported as `unrunnable` and do not trigger a model retry; -- browser or headless claims carry a checkable reality anchor; -- published provenance and reports redact credential-shaped values; -- a maintainer-only compatibility probe records future `agy` plan-mode behavior without becoming a live-model CI gate. - -## User stories - -1. As an orchestrator, I want every research worker's relative paths to resolve inside its assigned workspace, so that - a worker cannot accidentally inspect or modify the launcher repository because of a process-directory mismatch. -2. As a maintainer, I want the Bash and PowerShell launchers to have the same workspace-directory contract, so that a - workflow behaves consistently on both supported platforms. -3. As an orchestrator, I want plan mode's observed behavior and its limits documented accurately, so that I can use it - as a useful worker hint without treating it as a security boundary. -4. As an orchestrator, I want a worker's process state recorded separately from its verification state, so that exit 0 - cannot be reported as verified success by itself. -5. As an orchestrator, I want malformed, empty, or incomplete structured output rejected at the existing extraction and - selection seams, so that downstream stages receive only substantive worker results. -6. As an orchestrator, I want a gate that exits 126 or 127 classified as `unrunnable`, so that missing or unusable gate - tooling is reported clearly and does not waste the worker's retry budget. -7. As an orchestrator, I want routing history to retain all workers and their attempts, so that parallel runs remain - auditable without rejecting valid histories. -8. As an orchestrator, I want accepted attempts to point to one verified artifact for the same logical worker, so that a - retry cannot silently replace or shadow the evidence selected for downstream work. -9. As a user reviewing browser or headless work, I want claims tied to a saved screenshot, DOM, network, console, or - equivalent artifact, so that the report distinguishes observed state from worker assertion. -10. As a user receiving provenance or a final report, I want credential-shaped values redacted at the publication - boundary, so that diagnostic output does not expose secrets while raw scratch evidence remains available under the - existing cleanup policy. -11. As a maintainer, I want deterministic tests for these contracts, so that normal verification does not depend on a - live Gemini call or on the current behavior of an external CLI. -12. As a maintainer, I want a repeatable live compatibility probe for `agy` version changes, so that plan-mode claims are - refreshed from evidence instead of copied forward indefinitely. - -## Scope - -The implementation covers the shared launcher contract, research-workspace cleanup, worker-result acceptance, report -redaction, headless evidence anchors, and their documentation and tests. It preserves the existing model policy, -two-attempt ceiling, quota handoff, isolated research workspaces, frozen execution paths, and review-artifact checks. - -The primary files and seams are: - -- `scripts/run-agy-json.ps1` and `scripts/run-agy-json.sh`; -- `scripts/cleanup-research-workspace.ps1` and `scripts/cleanup-research-workspace.sh`; -- `scripts/extract-structured-output.ps1` and `scripts/extract-structured-output.sh`; -- `scripts/select-research-outputs.ps1` and `scripts/select-research-outputs.sh`; -- `scripts/collect-provenance.ps1` and `scripts/collect-provenance.sh`; -- the existing PowerShell and Bash acceptance suites and routing fixtures; -- `SKILL.md`, `README.md`, `modes/repo-research.md`, `modes/web-research.md`, and the routing specification that - currently documents the attempt record. - -Use the highest existing public seam for each behavior. Do not add a private helper solely to make an internal unit -test pass when the launcher, extractor, selector, cleanup command, or provenance command already exposes the behavior. - -## Functional requirements - -### 1. PowerShell child working directory - -`run-agy-json.ps1` MUST set `System.Diagnostics.ProcessStartInfo.WorkingDirectory` before starting `agy`. - -- The value MUST be the caller's current filesystem location at the time the launcher is invoked. -- The launcher MUST resolve the location through the PowerShell provider and reject non-filesystem locations with a clear - configuration error before starting `agy`. -- The launcher MUST NOT silently use `$PSScriptRoot`, the repository root, or the process's inherited .NET directory. -- Existing output and error path handling, model-policy resolution, argument validation, delimiter behavior, timeout, - and exit-code propagation MUST remain unchanged. -- No new caller-facing `--cwd` option is required for this change. A future explicit alternate-directory option is out - of scope. - -The Bash launcher already inherits the invoking shell's directory. Add a parity test rather than changing its behavior -unless the test demonstrates a separate defect. - -### 2. Plan-mode documentation and safety contract - -Keep `--mode plan` in read-role invocations and examples. Update wording in all maintained documentation and static tests -so that it states: - -- plan mode is a version-sensitive behavioral hint; -- the accepted probe observed additional plan behavior and blocked the tested direct write outside the permitted artifact - area on `agy` 1.1.25; -- the exposed tools and command paths mean plan mode MUST NOT be the sole containment or safety mechanism; -- `--add-dir` grants access but does not confine writes; -- filesystem isolation, scoped snapshots, execution-scope checks, frozen paths, and mechanical gates remain the actual - safety and verification controls. - -Documentation MUST NOT claim either that plan mode guarantees no writes or that the current probe proves plan mode is -useless. It should describe the observed behavior and the boundary of the evidence. - -### 3. Routing-outcomes attempt identity - -Preserve the existing top-level shape: - -```json -{ - "schema_version": 1, - "attempts": [] -} -``` - -Change validation in both cleanup helpers and all associated documentation/fixtures as follows: - -- `attempts` MAY contain records for any number of logical workers. -- Each record MUST have a stable `worker_id` and integer `attempt` equal to 1 or 2. -- The pair `(worker_id, attempt)` MUST be unique within the record. -- Each `worker_id` MUST have no more than two records. -- Attempt 2 MUST remain a retry of the same logical `worker_id`; changing process, model, or prompt does not create a - new worker. -- An attempt record MUST retain the existing routing, state, failure, verification, evidence, and usage fields. -- A per-worker `accepted_attempt` MUST identify an existing attempt for that same worker whose verification passed and - whose selected artifact exists. -- Optional nested routing histories in `provenance.json` MUST follow the same per-worker invariant. - -The cleanup helpers MUST reject a worker with three attempts, a missing or invalid attempt number, a duplicate -`(worker_id, attempt)` pair, or an accepted attempt that does not resolve to a verified artifact. They MUST accept, for -example, attempt 1 for workers A, B, and C plus attempt 2 for worker B. - -The helpers MUST continue to preserve valid routing evidence and produce the existing disposition manifest. No migration -of old records is needed because a record with at most two total attempts remains valid under the new rules. - -### 4. Worker-result acceptance - -The workflow MUST distinguish these states: - -1. process completed; -2. output envelope parsed; -3. structured output passed the mode's schema and substantive-field checks; -4. evidence, scope, gate, review, or citation checks passed; -5. one attempt was explicitly accepted for downstream use. - -An exit code of 0, a top-level worker status, or a nonempty prose `response` alone MUST NOT establish state 3, 4, or 5. - -At the existing extractor and selector seams: - -- reject missing, invalid, scalar, or otherwise unparsable structured output; -- require the mode-specific success status and the nonempty fields named by that mode's assignment schema; -- require evidence paths or equivalent result references where the mode contract calls for them; -- preserve explicit accepted-attempt selection and never select by wildcard, newest filename, or process completion time; -- keep worker prose out of downstream structured prompts unless it is explicitly part of the validated schema. - -For execution work, acceptance continues to require the relevant gate plus execution-scope and frozen-path checks. For -research work, acceptance continues to require the relevant artifact and orchestrator verification rules. The change is -to make these requirements authoritative in the acceptance path and reports, not to replace them with a new universal -content schema. - -### 5. Unrunnable gates - -Extend the shared failure vocabulary with `unrunnable`. - -- When a configured gate process exits 126 or 127, normalize the gate result to `unrunnable`. -- Record `verification: not_performed` when the gate could not run; retain the command, exit code, and diagnostic path - as evidence. -- Do not treat this as a worker quality failure and do not spend a model retry on it. -- Return an actionable error naming the missing, non-executable, or unavailable gate command. -- Preserve existing handling for worker crashes, timeouts, tool failures, quota exhaustion, and quality failures. -- Update validators, fixtures, reports, and documentation that enumerate `failure_class` values. - -If a worker process itself exits 126 or 127, classify it as `unrunnable` only when the launcher can establish that the -configured worker command was not runnable. Otherwise retain the existing operational or unknown classification rather -than guessing. - -### 6. Reality anchors for headless and browser claims - -For an assignment that makes a browser, GUI, rendering, or other externally observable headless claim, the accepted -result MUST include at least one reality anchor. A reality anchor is a saved artifact such as a screenshot, DOM snapshot, -network capture, console log, rendered file, or equivalent machine-checkable output. - -The anchor contract MUST include: - -- an explicit type; -- a path or artifact identifier; -- the claim or acceptance criterion it supports; -- existence and regular-file checks; -- containment within the assigned scratch/evidence area or an explicitly owned output path. - -The report MUST mark a claim without a valid anchor as unverified or failed according to the mode's existing halt rules. -Non-browser assignments are not required to manufacture a reality anchor. - -### 7. Publication-boundary redaction - -Before writing `provenance.json`, `final.md`, or a user-facing handoff/report, sanitize worker-derived strings and copied -diagnostics. Raw worker artifacts remain governed by the existing success/partial cleanup policy and are not rewritten by -the redaction pass. - -The redaction pass MUST cover credential-shaped values including authorization and bearer headers, cookies, private-key -blocks, password/secret/token/API-key assignments, and credential-bearing query parameters. It MUST preserve ordinary -public URLs, file paths, hashes, counts, and non-secret field names. Replacements MUST be stable markers such as -`[REDACTED]`, never a partial secret. - -The pass MUST be tested with both positive secret-shaped fixtures and negative fixtures for normal URLs, hashes, and -fields such as `token_count`. - -Credential forwarding rules remain unchanged: workers do not receive cookies, session tokens, browser profiles, or -environment credentials implicitly. - -### 8. Maintainer-only compatibility probe - -Add a shell-parity probe for future `agy` compatibility checks. It MUST run in a disposable workspace and use the same -fixed prompt, role, model policy, and output schema for two arms: - -- `agy --mode plan`; -- the same invocation without `--mode plan`. - -The probe MUST capture, for each arm: - -- `agy --version`; -- process exit code and structured-output parse result; -- initialization permission mode, available-tool summary, and expanded command summary when exposed; -- the result of an intentional sentinel write to the disposable workspace; -- output/error artifact paths and any reported duration or usage. - -The probe MUST report observations and warnings, not convert one version's behavior into a permanent safety guarantee. -It MUST fail the compatibility review if it cannot establish which arm ran or whether the sentinel check was performed. -It MUST NOT run as part of the normal deterministic test suite or silently alter the repository. - -## Documentation decisions - -Update the maintained contract wherever it currently describes the affected behavior: - -- `SKILL.md`: plan-mode limits, per-worker attempt identity, result acceptance, and `unrunnable` handling; -- `modes/repo-research.md` and `modes/web-research.md`: isolation, accepted evidence, reality anchors where applicable, - and publication redaction; -- `README.md`: user-facing explanation and deterministic test commands; -- `docs/specs/0003-gemini-model-routing.md`: the corrected attempt-record invariant and failure vocabulary; -- static documentation tests and canonical routing fixtures. - -Keep the current role/model policy and the historical nature of the 3.7 comparison clear. Do not introduce a second -source of truth for routing or retry rules. - -## Test strategy - -Use fake `agy` and temporary workspaces for deterministic tests. Test through the public scripts, not by mocking private -PowerShell or shell functions. - -### Launcher tests - -- Invoke `run-agy-json.ps1` from a temporary directory containing spaces. -- Have the fake worker emit its observed current directory and assert it equals the temporary directory. -- Assert the existing model injection, delimiter, output/error paths, exit-code propagation, and caller-flag rejection - tests still pass. -- Run the equivalent Bash inheritance test. - -### Routing and cleanup tests - -- Accept three workers with one attempt each. -- Accept workers A, B, and C at attempt 1 plus worker B at attempt 2. -- Reject three attempts for one worker. -- Reject duplicate `(worker_id, attempt)` pairs while allowing the same attempt number on different workers. -- Reject an invalid attempt number and an accepted attempt whose verification or artifact is invalid. -- Preserve and hash retained evidence in the disposition manifest. -- Exercise both PowerShell and Bash cleanup helpers against equivalent fixtures. - -### Acceptance and failure tests - -- Reject exit 0 with missing structured output. -- Reject valid JSON with missing or empty mode-required fields. -- Accept a fully structured result only after its applicable evidence/gate/scope/review checks pass. -- Verify explicit accepted-attempt selection after a retry. -- Normalize gate exit 126 and 127 to `unrunnable`, preserve diagnostics, and assert no retry is scheduled. -- Preserve existing operational, quality, timeout, quota, and partial-result behavior. - -### Reality and redaction tests - -- Accept a browser/headless claim with a valid in-scope anchor. -- Reject or mark unverified a claim with a missing, out-of-scope, or nonexistent anchor. -- Redact representative authorization, cookie, token, secret, private-key, and credential-query values. -- Confirm normal public URLs, hashes, counts, and non-secret names remain intact. - -### Documentation and compatibility tests - -- Update static checks so no maintained document calls plan mode a complete write barrier or the sole safety control. -- Validate the compatibility-probe output shape with a checked-in fixture or fake runner. -- Keep the live compatibility probe out of deterministic CI and document the command used by maintainers. - -The existing suites remain required, including `tests/test_research_helpers.ps1`, `tests/test_workflow_static.ps1`, -`tests/test_research_modes.sh`, and the execution-scope tests for both shell families. - -## Implementation order - -1. Update the shared contract and routing fixture expectations, including the per-worker attempt identity and - `unrunnable` vocabulary. -2. Fix the PowerShell launcher working directory and add cross-platform launcher regression tests. -3. Fix both cleanup helpers and add multi-worker routing fixtures. -4. Tighten structured-result acceptance and gate classification at the extractor/selector and existing execution-gate - seams. -5. Add reality-anchor validation and publication-boundary redaction, with focused fixtures. -6. Update documentation and static tests. -7. Add the maintainer-only live compatibility probe and document when to run it. -8. Run the full deterministic suite, then run the compatibility probe only when the installed `agy` behavior or supported - version requires a refresh. - -## Completion criteria - -The work is complete when: - -- a PowerShell worker observes the caller's filesystem directory as its child working directory; -- Bash and PowerShell tests cover the same launcher contract; -- multi-worker routing histories clean successfully while more than two attempts for one worker fail closed; -- accepted attempts are explicit, per-worker, verified, and artifact-backed; -- exit 0 cannot bypass structured-output or mode-specific verification; -- gate exits 126 and 127 produce `unrunnable` without model retry; -- required headless claims have in-scope reality anchors; -- published provenance and reports contain no fixture secrets while raw scratch evidence follows existing retention rules; -- documentation accurately describes the observed plan-mode behavior and continues to require filesystem isolation; -- deterministic tests pass without a live model call; -- the compatibility probe can produce a complete two-arm observation when run by a maintainer. - -## Out of scope - -- Removing `--mode plan` from read workers or claiming that it guarantees no writes. -- Running research workers against the live repository or relying on `--add-dir` as containment. -- Replacing isolated workspaces with in-place read agents, symlinked mutable environments, or blanket `git add -A`. -- Retrying from failed commits, placing red tests on the main branch, or weakening frozen-path and execution-scope - checks. -- Introducing a default STORM-style workflow, background Telegram/daemon integration, streaming dashboards, or unrelated - chat/provider integrations. -- Changing the Gemini model policy, quota policy, maximum retry ceiling, or historical 3.7 comparison beyond the - documentation needed for this contract. -- Making the live compatibility probe a required CI step or a production safety gate. -- Publishing to an external issue tracker, copying private source material from the comparison repository, or importing - implementation details that are not supported by this repository's own contracts and tests. -- Broad cleanup, refactoring, or redesign outside the files and seams listed in this specification. diff --git a/.scratch/offload-web-research/spec.md b/.scratch/offload-web-research/spec.md deleted file mode 100644 index 07fdbe5..0000000 --- a/.scratch/offload-web-research/spec.md +++ /dev/null @@ -1,388 +0,0 @@ -# Offload research modes - -Status: ready for agent - -Publication: local scratch spec. This repository has no project-specific issue-tracker workflow, -and this task did not authorize publishing an external issue. - -## Problem - -`offload` currently puts implementation work and bounded repository audits in one 420-line -`SKILL.md`. It has no workflow for cited online research. Its current safety model also treats -`agy --mode plan` as a write barrier, but direct probes showed that plan-mode workers can write. -That claim appears in the skill, README, and project instructions. - -The private Asa project by Achibukz has a useful research shape: parallel evidence gathering, -synthesis, and an independent audit. Copying Asa into this public MIT repository would expose -private work and create a licensing problem. Installing Asa as a dependency would also make a -private package part of `offload`'s public setup. - -## Solution - -Keep `offload` as one Skillshare-tracked skill. Turn its root `SKILL.md` into a short router and -move each workflow into a mode document. Reimplement the research shape in original language and -small shell helpers. Do not copy Asa source, prompts, tests, or documentation. - -Add a `web-research` mode that dispatches researchers, a synthesizer, and an independent auditor. -Every worker runs in a disposable directory. Mixed repository and online research receives only a -temporary copy of paths the orchestrator declares. The live repository is never exposed to a -research worker. - -Credit the idea in public documentation with this wording: - -> Offload's online-research workflow is adapted from Asa by Achibukz, used with permission. - -Do not publish the private repository URL, branch name, commit, screenshots, or copied text. - -## User stories - -1. As an offload user, I want one skill invocation for execution and research, so that I do not - have to learn separate skills. -2. As an offload user, I want the router to infer the mode from my request, so that the common path - needs no extra syntax. -3. As an offload user, I want to override the inferred mode, so that I can correct an ambiguous - route. -4. As an offload user, I want small factual lookups to stay with the orchestrator, so that a simple - answer does not fan out into a full run. -5. As an offload user, I want online research to require multiple evidence angles, a real - comparison, or a citation audit, so that offloading pays for its overhead. -6. As an offload user, I want a standard research profile, so that ordinary research gets broad - evidence without an oversized run. -7. As an offload user, I want a deep profile when I request it or when a named risk trigger fires, - so that difficult decisions get more scrutiny. -8. As an offload user, I want the report to name an automatic deep trigger, so that I know why the - run expanded. -9. As an offload user, I want every final citation opened and checked by an independent auditor, - so that a plausible URL is not treated as support. -10. As an offload user, I want claims tied to their citations, source quality, conflicts, and - uncertainty, so that I can judge the answer rather than trust a worker count. -11. As an offload user, I want primary and independent sources to outweigh repeated secondary - coverage, so that five workers repeating one source do not look like five confirmations. -12. As an offload user, I want unsupported incidental claims removed, so that the final answer does - not preserve noise for completeness. -13. As an offload user, I want unresolved claims kept only when they affect the decision and marked - clearly, so that uncertainty remains visible where it matters. -14. As an offload user, I want a failed mandatory stage to return a partial result instead of a firm - synthesis, so that incomplete research cannot masquerade as a finished answer. -15. As a repository owner, I want research workers isolated from the live working tree, so that a - worker write cannot change my files. -16. As a repository owner, I want mixed repository and web research to copy only declared paths, - so that unrelated private material is not sent to workers. -17. As an offload user, I want public sources used by default and private online sources used only - after explicit authorization, so that credentials and signed-in data are not passed silently. -18. As an offload user, I want compact provenance retained without successful worker transcripts, - so that I can audit the result without keeping a bloated run history. -19. As an offload user, I want raw artifacts retained when a run fails, so that the failure can be - diagnosed. -20. As an offload user, I want research to finish before implementation begins, so that workers - implement from an audited result instead of changing the target while evidence is still being - gathered. -21. As an existing offload user, I want execution and repository research behavior preserved, so - that adding web research does not break established workflows. -22. As an installer, I want Skillshare to install the router, modes, and helpers together, so that - no plugin or private dependency is required. -23. As an implementer, I want deterministic tests around routing, isolation, failure handling, and - provenance, so that most behavior can be checked without spending model calls. -24. As a maintainer, I want one live comparison of the proposed model split, so that the role - assignments rest on observed research output rather than a coding benchmark. - -## Invocation and routing - -Generic research does not automatically invoke `offload`. Invoke it when the user asks to offload, -or offer it once when a request has enough fan-out to benefit. For web research, that means at -least two independent evidence angles, a real comparison, or a citation audit. Keep a single -factual lookup local. A declined offer remains declined for the session. - -Once invoked, the router uses this order: - -1. Honor an explicit mode override. -2. If a requested mutation depends on new external evidence, route to `web-research` first and - `execution` second. -3. Route a direct file or code mutation with no research prerequisite to `execution`. -4. Route a read-only question answerable from declared local files to `repo-research`. -5. Route a read-only question that needs current or external evidence to `web-research`. -6. Route a question that needs local and external evidence to `web-research` with a scoped - repository snapshot. - -The root skill owns only shared preconditions, this routing decision, mode loading, and the final -cross-mode report contract. It must not duplicate mode procedures. - -## Repository layout - -The implementation stays inside the existing repository and keeps the package as one skill. - -| Path | Responsibility | -|---|---| -| `SKILL.md` | Short trigger and router document, under 500 lines | -| `modes/execution.md` | Existing scout, gate-author, implementer, and diff-review workflow | -| `modes/repo-research.md` | Existing bounded local research and audit workflow | -| `modes/web-research.md` | Standard and deep online research workflow | -| `scripts/make-research-workspace.sh` | Create a disposable run directory and optional scoped repository copy | -| `scripts/collect-provenance.sh` | Build and validate the compact run record from stage artifacts | -| `scripts/cleanup-research-workspace.sh` | Remove successful raw artifacts while retaining final output and provenance | -| `tests/` | High-level shell tests with a fake `agy`, fixtures, and the live smoke procedure | -| `README.md` | Human-facing use, installation, limits, safety correction, and attribution | -| `AGENTS.md` | Maintainer-facing architecture and current worker guarantees | - -Do not add a monolithic workflow runner. The orchestrator retains decomposition, source judgment, -deep-trigger judgment, synthesis acceptance, and failure decisions. Shell helpers handle only -temporary directories, copying declared paths, artifact cleanup, schema checks, and provenance -assembly. - -Skillshare already tracks the whole repository. Installation must keep using the tracked skill. -The manual installation option must copy the whole skill directory, not only `SKILL.md`. - -## Mode contracts - -### Execution - -Move the current writing workflow into `modes/execution.md` without changing its accepted behavior: - -- Scout tentative file ownership. -- Choose one machine or diff gate per writing task. -- Red-check and read machine gates before freezing them. -- Dispatch implementers only from a clean Git working tree. -- Check touched paths, frozen paths, and the selected gate. -- Retry a failed implementer once, then stop that task. - -Correct the worker-safety claim throughout the repository. `--mode plan` is a behavioral hint, not -a write barrier. Scouts and reviewers must run from disposable directories or against disposable -repository copies when a write would otherwise reach live files. Never say that `--add-dir` or -plan mode confines a worker. - -### Repository research - -Move the current bounded local investigation into `modes/repo-research.md`. Preserve its required -assignment fields: - -- One bounded question. -- Declared file or directory scope. -- Concrete evidence expectations. -- A rule against modifying files or dispatching nested workers. - -Replace plan-mode safety with filesystem isolation. Copy the declared scope into a disposable -workspace, run the worker there, and verify findings against the live repository with read-only -orchestrator commands. Existing priority correction, direct checking of high-priority findings, -sampling of lower-priority findings, and unsupported-claim labeling remain in place. - -### Web research - -The standard profile dispatches two or three researchers in parallel, then one synthesizer, then -one auditor. Assign each researcher a distinct evidence angle. Overlap is allowed only when it -tests a conflict or the independence of a source. - -The deep profile uses no more than five researchers in total. It starts from standard-profile -findings and adds only the angles needed to resolve the trigger. Do not rerun the standard work. -Deep activates when the user asks for it or when one of these conditions appears: - -- Material source conflict. -- A costly or hard-to-reverse decision. -- Citation-sensitive output. -- Substantial counterevidence. - -Record the trigger in the report and provenance. If no trigger appears, use standard. - -Researchers use `gemini-3.7-flash-high`. The synthesizer and auditor use -`gemini-3.1-pro-high`. Keep the split only if the live smoke comparison supports it. Otherwise use -`gemini-3.7-flash-high` for every role and record that decision in the test result and docs. - -Every worker gets a 20-minute timeout. A timed-out mandatory stage is incomplete even if other -workers returned useful material. - -## Evidence and claim rules - -Researchers return claims, not essays. Each finding must identify its evidence angle, the claim, -supporting source URLs, source type, publication or update date when available, conflicts, and -uncertainty. Prefer primary sources. Treat sources that repeat the same upstream report as one -line of evidence. - -The synthesizer builds a claim ledger from researcher outputs. It may combine claims only when the -citations support the same proposition. It removes unsupported incidental claims. It retains an -unresolved claim only when it could change the answer or decision, and labels the gap. - -The auditor is independent. It receives the proposed synthesis and claim ledger, not the -synthesizer's private reasoning. It opens every citation intended for the final answer and checks: - -- The URL resolves to the named source. -- The source supports the nearby claim, either directly or with a stated inference. -- The source date is suitable for a time-sensitive claim. -- The source is primary, secondary, or a repeated derivative. -- Conflicting evidence and material uncertainty remain visible. - -The final report calls supported claims `audited`, never `verified`. Repository research may keep -its existing verification vocabulary because the orchestrator can reproduce local evidence. - -If the auditor rejects a citation, the synthesizer may remove or narrow the claim and return it for -one audit pass. Do not create an open-ended revision loop. If the second audit still fails, omit an -incidental claim or retain a decision-relevant claim as unresolved. - -## Worker isolation - -Every research run creates a unique temporary directory outside the live repository. Launch all -researchers, the synthesizer, and the auditor with that directory as their working directory. - -For mixed repository and web research: - -1. The orchestrator declares the smallest required paths. -2. The workspace helper copies only those paths into a snapshot under the temporary directory. -3. Workers receive the snapshot path, never the live repository path. -4. The orchestrator verifies local claims against the live repository using read-only commands. -5. Cleanup removes the copied repository material after a successful run. - -Workers use public web sources by default. Private or authenticated sources require the user's -explicit authorization for that run. Never forward cookies, tokens, browser profiles, environment -credentials, or session data implicitly. - -## Stage outputs - -Keep schemas in the web-research mode or a disclosed schema resource. Do not embed large JSON -schemas in the root router. - -The researcher result contains: - -- Stable run and angle identifiers. -- Completion status and failure reason. -- The bounded question and evidence angle. -- Findings with claim text, source records, conflicts, and uncertainty. -- Search gaps and counterevidence. - -The synthesizer result contains: - -- A claim ledger with decision relevance. -- A proposed answer with claim-level citation references. -- Conflicts, inferences, unresolved claims, and omitted unsupported claims. -- The profile used and any deep trigger. - -The auditor result contains: - -- One entry for every citation in the proposed final answer. -- Resolve status, support verdict, source classification, independence notes, and date fitness. -- A final status of `pass`, `revise`, or `incomplete`. -- Exact claims that must be removed, narrowed, or marked unresolved. - -The compact provenance JSON contains: - -- Run identifier, request summary, selected mode, profile, and deep trigger. -- Start time, end time, duration, and scratch path. -- Every worker's role, model, status, duration, and artifact name. -- Declared repository snapshot paths, if any. -- Final citation URLs and audit verdicts. -- Final run status and incomplete-stage reasons. - -On success, retain only the final Markdown result and provenance JSON in the scratch directory. -Remove raw worker responses and the repository snapshot. On failure or incomplete status, retain -raw stage artifacts and the snapshot for diagnosis. Do not write research artifacts into the -repository or a global history unless the user asks. - -## Failure behavior - -Researcher failure may receive one retry with the concrete failure. A missing researcher does not -block synthesis when the remaining evidence still covers at least two independent angles, but the -report must name the missing angle. - -Synthesis and audit are mandatory. A crash, timeout, unparsable result, or unresolved audit failure -in either stage changes the run to `partial`. A partial run may return audited claims collected so -far, but it must withhold a firm synthesis or recommendation. State which stage failed and keep the -raw artifacts. - -Do not convert worker disagreement into a vote. Resolve conflicts by source quality, -independence, directness, and recency. If those checks do not settle the conflict, keep it -unresolved. - -## Research plus implementation - -Treat research and mutation as separate phases: - -1. Finish the research workflow and its audit. -2. Reduce the result to the final answer, claim ledger, and compact provenance. -3. Use that compact result as an input to `execution`. -4. Apply the existing Git, ownership, frozen-path, and gate checks to implementation. - -Do not pass raw research transcripts to implementers. Do not start implementation from a partial -research result unless the user explicitly accepts the named gaps. - -## Documentation decisions - -Write `SKILL.md`, mode files, schemas, prompts, and `AGENTS.md` for agents using the -`writing-for-agents` rules. Keep shared instructions in the router and branch-specific detail in -the selected mode. The root skill must remain under 500 lines. - -Write maintained human-facing documentation in Anthony's voice using `write-like-me`. Apply -`unslop` to all prose. Update README examples and findings so they do not claim plan mode prevents -writes. Add the agreed Asa attribution without a private link. - -## Test strategy - -Test through the highest public seam: invoke the router and helpers as an orchestrator would. Use a -fake `agy` executable that records arguments and returns fixture JSON. Do not add internal mocking -hooks solely for tests. - -### Deterministic acceptance tests - -1. An explicit override selects the named mode. -2. A local-only bounded question selects repository research. -3. A current or external question selects web research. -4. A mixed local and external question selects web research and copies only declared repository - paths. -5. A direct mutation selects execution. -6. A mutation that depends on external evidence completes research and audit before execution. -7. A single factual lookup does not trigger an offload offer. -8. Standard web research dispatches two or three researchers, one synthesizer, and one auditor in - the required order. -9. Deep research never exceeds five researchers and does not repeat completed standard angles. -10. Each named deep trigger selects deep and appears in provenance. -11. Workers run from a disposable directory and receive no live repository path. -12. A scoped snapshot contains declared paths and excludes undeclared paths. -13. Successful cleanup keeps only the final result and provenance. -14. Failed cleanup retains raw artifacts and the snapshot. -15. Provenance contains every required field and rejects a missing mandatory field. -16. A failed or timed-out synthesizer produces a partial result with no firm recommendation. -17. A failed or timed-out auditor produces a partial result with no firm recommendation. -18. The auditor receives every citation used by the proposed final answer. -19. An unsupported incidental claim disappears from the final result. -20. A decision-relevant unsupported claim remains only as unresolved. -21. Existing execution and repository research fixtures still pass after the files move. -22. Repository text contains no claim that plan mode or `--add-dir` prevents writes. -23. `SKILL.md` remains below 500 lines and every mode pointer resolves. -24. Manual installation instructions copy the whole directory. - -### Live smoke comparison - -Run one fixed standard-profile web question twice. Use the proposed split for one run and -`gemini-3.7-flash-high` for every role in the other. Record runtime, completed stages, citation -resolution, supported claim count, conflict handling, and uncertainty handling. - -Keep the Pro synthesizer and auditor only if the split completes all mandatory stages, does not -regress citation support, and improves synthesis or audit judgment enough to justify its runtime. -This is a recorded maintainer judgment, not a permanent benchmark claim. If the split does not -clear that bar, change the mode and docs to Flash for all roles before release. - -## Completion criteria - -Implementation is complete when: - -- The router and all three mode documents exist and their responsibilities do not overlap. -- Execution and repository research preserve their prior accepted behavior. -- Web research implements standard, deep, synthesis, audit, isolation, and failure contracts. -- No live repository path reaches a research worker. -- No document claims plan mode is a write barrier. -- Deterministic tests pass with the fake `agy`. -- The live smoke comparison is recorded and the shipped model assignment matches its result. -- README and AGENTS match actual behavior and installation. -- Public documentation includes the agreed attribution and no private repository details. -- The final diff contains no copied Asa source, prompts, tests, or documentation. - -## Out of scope - -- Publishing, vendoring, installing, or linking the private Asa repository. -- Making Asa a runtime dependency. -- Packaging `offload` as a Codex plugin. -- Subagent activity visibility, live dashboards, streaming traces, or chat integrations. -- A general autonomous research daemon or monolithic workflow engine. -- Unbounded research with no question or evidence angles. -- Automatic access to authenticated or private online sources. -- Credential, cookie, or browser-session forwarding. -- Claims that an audited result is true with certainty. -- Permanent storage of successful raw worker transcripts. -- Replacing the orchestrator's judgment with worker votes or a numeric confidence average. -- Changing unrelated execution behavior, hooks, or repository structure. diff --git a/AGENTS.md b/AGENTS.md index c541c0f..947696c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,34 +1,18 @@ # offload -Agent-agnostic skill that delegates plan execution and research to headless `agy` workers. +Offload is an agent-agnostic, outcome-based delegation skill. The active contract is [SKILL.md](SKILL.md); [CONTEXT.md](CONTEXT.md) and ADR 0012 are the durable project sources of truth. -## Key decisions and architecture +## Current boundaries -Dispatch control: `dispatch-worker.sh` and `dispatch-worker.ps1` are orchestrator-owned admission interfaces. They record bounded assignment parentage and budgets, create worktrees, and start workers. Worker-context calls to dispatch, launch, or execution-workspace lifecycle helpers fail closed and are recorded; worker follow-up requests remain data until the orchestrator admits them. +- Keep provider, model, reasoning, and command details runtime-dynamic. Do not add copied catalogs, exact model identifiers, role matrices, or integration interfaces to the workflow. +- Keep launch admission simple. A real launch is the usability check; unknown account, entitlement, billing, quota, capacity, or benchmark information must not block it. +- Keep implementation changes isolated until the orchestrator reviews the actual diff and relevant checks. +- Keep research bounded, source-backed, and explicit about inference and uncertainty. +- Retain only generic helpers that directly enforce scope, isolation, bounded snapshots, or safe cleanup. -- **Orchestrator-agnostic, adapter-backed workers**: Any agent capable of reading `SKILL.md` and running shell commands can orchestrate, including Claude Code, Codex CLI, and similar agents. Worker execution runs through the adapter contract, with `agy` as the reference adapter. The self-guard stops a dispatched worker that loads this skill, and the dispatcher plus worker-context guards enforce that workflow boundary. Every assignment instructs workers not to dispatch nested workers, but the skill cannot enforce that prohibition if a worker ignores it. -- **Modular mode architecture**: Root `SKILL.md` is a lightweight router under 500 lines owning shared preconditions, mode inference, explicit overrides, mode loading, and the shared report contract. Workflows are isolated into dedicated mode documents: `modes/execution.md` (code and file mutations), `modes/repo-research.md` (bounded local investigations and audits), and `modes/web-research.md` (online research, synthesis, and citation auditing). -- **Routing hierarchy**: Once invoked, the router resolves mode in this order: - 1. Honor explicit mode override. - 2. Route research-backed mutations to `web-research` first and `execution` second. - 3. Route direct file or code mutations to `execution`. - 4. Route local read-only questions to `repo-research`. - 5. Route external read-only questions to `web-research`. - 6. Route mixed local and external questions to `web-research` with a scoped snapshot. - Single factual lookups stay local with the orchestrator. -- **Shell-native helper families with platform parity**: Offload maintains two shell-native helper families: Bash 3.2+ for POSIX shells and PowerShell 7+ for PowerShell orchestrators. Orchestrators select the helper family for their current shell. Native workflows on Windows require only PowerShell 7+, Git, and `agy` without WSL, Git Bash, Python, or `jq`. Platform parity ensures equivalent workflow behavior, workspace isolation, provenance artifacts, and safety checks across supported shells. -- **Worker roles, preferences, and modes**: - - Worker routing is governed centrally by `model-policy.json` and a vendor adapter. The policy stores each role's internal preference, independent effort, and required capabilities. The adapter provides the live catalog and translates the selected model into worker arguments. - - Selection is deterministic after filtering for availability, quota, effort, capabilities, and static security constraints. Family hints are descriptive only. -- **Model routing policy and recovery accounting**: - - Preflight model availability check against the resolved `agy` installation before first dispatch. - - Launchers take `--role ` and optional `--route default|quality-retry`, resolving models dynamically and rejecting caller `--model` or `--effort` arguments. - - Stable assignment identity across attempts with a strict ceiling of at most one retry (maximum two attempts per worker). - - Operational failures (crashes, timeouts, unparsable output) trigger at most one retry of the pinned selection (`--route default`). Quality failures (gate failures, scope violations, audit rejections) retry the pinned selection or require an explicit fallback or handoff when the pin is unavailable. - - Explicit quota exhaustion triggers immediate handoff of unfinished work to the calling orchestrator without blocking on sibling workers. - - The orchestrator records all attempts and verification verdicts in `routing-outcomes.json` in the scratch workspace. Web research provenance optionally records routing attempt records in `provenance.json`. -- **Corrected worker guarantees**: `--mode plan` is a version-sensitive behavioral hint, not a write barrier. The accepted `agy 1.1.25` probe blocked the tested direct write outside the permitted artifact area, but plan mode is not a sole safety control. `--add-dir` grants access without confining writes. Security and containment rely on filesystem isolation (disposable workspaces with scoped file snapshots for research) and mechanical verification (clean git working trees, execution scope checks, frozen path diffs, and test gates for execution). -- **Verification over claims**: Worker JSON status (`SUCCESS`/`ERROR`) is not trusted alone. Implementers are verified via mechanical execution scope checks (`check-execution-scope.sh` or `check-execution-scope.ps1`), frozen paths, and gate commands. Reviewers are verified against the recorded artifact digest and verbatim quote matching. Research findings are verified against the live repository with read-only orchestrator commands after scope validation, with direct checks on high-priority claims and sampling on lower-priority claims. -- **Preconditions**: Writing workflows require a clean git repository. Research workflows operate in isolated disposable workspaces. -- **Proactive offer contract**: For implementation splits of 3+ gated tasks or multi-angle audit fan-outs, the orchestrator offers offloading once per session; a negative response settles the decision for that session. Offload uses a host-independent, model-readable proactive offer contract in context files (`AGENTS.md` or `CLAUDE.md`) rather than vendor-specific lifecycle hooks. -- **Installation**: Tracked public repo (`github.com/anthonyandrei/offload`), installed via `skillshare install anthonyandrei/offload --track` as `_offload`. Manual installation copies the entire skill directory. +## Editing and verification + +- Preserve unrelated user changes in a dirty checkout. +- Use the native shell helper for the platform being changed. +- Run the contract tests for the affected platform and the full suite when practical. +- Treat superseded ADRs as historical context. Do not add active links to removed files. diff --git a/CONTEXT.md b/CONTEXT.md index 1f9e204..cd4c56c 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -1,80 +1,42 @@ # Offload context -Offload delegates bounded work through compatible worker adapters while the calling agent remains responsible for scope, verification, and reporting. The repository includes a reference adapter, but selection is provider-neutral. +Offload is a lean, agent-agnostic workflow for delegating bounded implementation and research work. The orchestrator chooses how to execute the workflow from the tools and evidence available at runtime. See [ADR 0012](docs/adr/0012-keep-offload-outcome-based-and-runtime-dynamic.md). -## Publication boundary +## Core contract -Published source skills remain vendor-neutral. `grill-with-docs` owns its -interview and documentation workflow and can run without offload. Offload is -an optional delegation layer, while adapters own vendor launch syntax, model -catalogs, capability probes, and output parsing. Consumers depend on stable -capabilities, model preferences, separate reasoning effort, and normalized -results, not vendor names or exact model IDs. +- Treat workers as fallible collaborators, not authoritative executors or hostile processes. +- Discover available worker CLIs, models, and current command syntax at runtime when useful. +- Choose whether and where to delegate using the task, current benchmark references, cost, and orchestrator judgment. +- Do not make delegation depend on quota, entitlement, billing, benchmark, or other speculative pre-checks. A real launch settles whether a chosen worker is usable. +- Review every worker-authored implementation and run relevant verification before acceptance. +- Ground research in credible sources, audit citations, and distinguish sourced findings from inference, uncertainty, disagreement, and stale evidence. +- Return unfinished work to the orchestrator automatically when a worker fails. +- Isolate delegated work appropriately and remove temporary workspaces after accepted integration. -Capability support does not enforce security. The orchestrator remains -responsible for isolation, ownership, cleanup, execution scope checks, and -acceptance gates. The source repository is authoritative; generated and -installed copies are release outputs. See -`docs/contracts/publication-compatibility.md` and ADR 0007. +These are procedural assurances, not a promise that worker output is infallible. ## Language **Orchestrator**: -The calling agent that plans assignments, dispatches workers, and verifies their results. -_Avoid_: Controller, parent agent +The calling agent that decides whether and how to delegate, reviews worker output, and owns the final result. **Worker**: -A process launched through a compatible adapter and assigned one bounded role. Its process environment is marked as worker context, so the dispatch, launcher, and execution-workspace lifecycle interfaces reject nested assignment, process, or worktree creation. -_Avoid_: Subagent, child agent +A fallible collaborator assigned one bounded piece of work. Its output is never accepted solely because the worker reports success. -**Compatible worker adapter**: -An adapter that implements the worker contract and has verified support for the assignment's required capabilities. An installed agent CLI alone does not establish compatibility. -_Avoid_: Any installed CLI, universal worker support +**Runtime discovery**: +The orchestrator's inspection of currently available CLIs, models, capabilities, and command help. Offload does not store vendor command syntax or normalize provider catalogs. -**Worker selection**: -The orchestrator's choice of a configured, compatible worker provider before making an offload offer. Selection checks authenticated access, current entitlement, and usage limits against the assignment, verification, and one retry, accounting for workers sharing quota. Rank eligible workers by task capability and expected quality, with remaining capacity as the tie-breaker. Unknown usage excludes automatic selection but permits explicit user selection with disclosed uncertainty and otherwise established access. An explicit user provider choice takes precedence, subject to eligibility checks. The offer names the selected worker and explains the choice. The protocol-2 selector and capacity ledger implement this behavior. See ADR 0009. -_Avoid_: Always offer one provider, implicit provider switch +**Decision reference**: +Current external evidence, such as a relevant benchmark, that grounds routing judgment without determining it. Missing, stale, or mismatched benchmark data never blocks delegation. -**Dispatch ledger**: -The orchestrator-owned `offload-dispatch-state-v1` record for admitted assignments. It records parentage, depth, child IDs, budgets, owned and frozen paths, lifecycle state, artifacts, and rejected nested-dispatch events. -_Avoid_: Worker tree, implicit scheduler state +**Implementation assurance**: +The requirement that the orchestrator reviews worker-authored changes and performs verification relevant to the assignment before accepting them. -**Helper family**: -A shell-native set of scripts that implements the same offload operations and command contracts for one supported shell. -_Avoid_: Port, rewrite +**Research assurance**: +The requirement that the orchestrator checks source quality, claim support, and citations before accepting a research synthesis. -**Platform parity**: -Equivalent workflow behavior, safety checks, artifacts, and failure signals across supported helper families. -_Avoid_: Identical implementation +**Orchestrator fallback**: +The automatic return of unfinished work to the orchestrator after worker failure. Offload does not retry through a routing engine or silently switch providers. -**Native workflow**: -An offload workflow that runs in a supported host shell without WSL, Git Bash, or another compatibility layer. -_Avoid_: Cross-platform workflow - -**Launcher delimiter**: -The literal `--` argument that separates launcher options from worker arguments. PowerShell callers write `'--'` so the command parser passes the delimiter to the helper. Arguments after it retain their order and individual values. -_Avoid_: Optional separator, inferred worker boundary - -**Execution scope check**: -The mechanical comparison of repository changes against a worker's owned and frozen paths. -_Avoid_: Diff check, ownership check - -**Proactive offer contract**: -The host-independent rule that defines when an orchestrator offers offloading, how often it asks, and how it handles the answer. -_Avoid_: Hook, Claude hook - -**Model routing**: -The policy and adapter process that selects an available model and independent reasoning effort for an offload worker assignment. It uses a role preference, task capabilities, live availability, static security rules, and quota state. -_Avoid_: Mode routing, unrestricted model selection - -**Role default**: -The internal preference, reasoning effort, and required capabilities assigned to an offload role. The adapter resolves those requirements to a current model. -_Avoid_: Best model, permanent model assignment - -**Model policy**: -The shared source of permitted model assignments and routing constraints, read and validated by both shell-native helper families for every offload mode. -_Avoid_: Per-mode model list, launcher default - -**Model promotion**: -A change to an offload role default justified by repeated local runs on representative tasks with the same inputs and verification gates. ADR 0005 records a one-time exception for the initial 3.8 Flash baseline migration, which requires an integration smoke test. -_Avoid_: Version upgrade, benchmark ranking +**Workspace isolation**: +Separation appropriate to the risk of the delegated work, such as a disposable worktree for implementation or a disposable project copy for research. The workflow specifies the outcome, not shell-specific commands. diff --git a/README.md b/README.md index 7cefd58..177319d 100644 --- a/README.md +++ b/README.md @@ -1,425 +1,47 @@ -# offload +# Offload -`offload` is an agent-agnostic skill that delegates bounded plan execution and research tasks to headless workers through a configured vendor adapter. The calling agent remains responsible for isolation, verification, cleanup, and reporting; the worker handles the assigned task. The repository includes a reference adapter, but selection and admission use a provider-neutral contract. +Offload is a small, agent-agnostic delegation contract. It lets an orchestrator hand a bounded implementation or research assignment to a worker while keeping responsibility for review, unfinished work, and the final report. -Whatever CLI coding agent loads this skill serves as the orchestrator: Claude Code, Codex CLI, or any agent that can read instructions and run shell commands. The configured adapter launches the worker, not the orchestrator. The orchestrator never accepts worker claims at face value. It verifies work mechanically through test gates, execution scope checks, verbatim quote matching, independent citation auditing, and direct repository checks. +## Contract -Offload's online-research workflow is adapted from Asa by Achibukz, used with permission. Do not publish a private repository URL, branch, commit, screenshots, or copied text. +The orchestrator: -## What it supports +- uses Offload only for an explicit request, a named worker provider, an accepted offer, or a host-approved proactive offer; +- describes the assignment, paths or questions, acceptance criteria, deliverables, and authority boundary; +- discovers current worker tools, model choices, and reasoning options at runtime; +- makes a task-based choice using capabilities, availability, cost, judgment, and advisory benchmark evidence; +- treats a real launch as the usability check. Unknown account, entitlement, billing, quota, capacity, or benchmark information does not block launch; +- keeps the worker bounded and forbids nested delegation; +- reviews the actual result and relevant verification before accepting it; +- finishes unfinished work itself or reports the precise blocker. -- Execution workers in isolated Git worktrees, with owned and frozen paths checked after each run. -- Research workers in disposable snapshots that keep the live repository untouched. -- Shell-native helpers for Bash 3.2+ and PowerShell 7+. -- Vendor-neutral adapters for AGY, Claude Code, and Codex CLI, all using the same assignment and normalized-result contract. -- Shared model routing through `model-policy.json`, with bounded retries and immediate handoff when the worker quota is exhausted. +The workflow does not carry provider commands, copied help, exact model identifiers, a universal catalog, a role matrix, or a hidden selection protocol. A named provider choice is honored. A failed launch returns the unfinished assignment to the orchestrator without a silent switch or automatic second attempt. -Start with the root [`SKILL.md`](SKILL.md) for the workflow contract. The README gives the public overview; the mode documents contain the shell-specific procedures. +## Implementation assignments -## Publication boundary +Implementation runs in a disposable isolated worktree or project copy. The orchestrator checks the final diff for scope and intent, runs the relevant project checks, and accepts or integrates the result only when the acceptance criteria pass. The disposable workspace is removed after recovery or acceptance. -Published source skills use the vendor-neutral contract in -[`docs/contracts/publication-compatibility.md`](docs/contracts/publication-compatibility.md). -`grill-with-docs` owns its interview and documentation workflow and can run -without offload. Offload is an explicit optional delegation layer. Adapters own -vendor command syntax, model catalogs, capability probes, and output parsing. +## Research assignments -Published consumers use stable capabilities and internal model preferences, with -reasoning effort kept separate. They do not depend on vendor names, family -labels, or exact model IDs. The compatibility checker rejects unavailable -adapters and vendor-specific references. Capability support does not enforce -security; the orchestrator still owns isolation, execution scope checks, cleanup, -and acceptance gates. +Research starts with bounded questions and evidence responsibilities. The worker uses credible sources, and the orchestrator checks that every material citation resolves and supports its claim. Inference, uncertainty, disagreement, missing evidence, and stale evidence stay visible in the final synthesis. -## Worker safety and containment +## Proactive offers -- **`--mode plan` is a version-sensitive behavioral hint, not a write barrier.** The accepted `agy 1.1.25` probe blocked the tested direct write outside the permitted artifact area, but plan mode is not a sole safety control. Never rely on it alone to protect live repository files. -- **`--add-dir` grants directory access without confining writes.** A worker can edit files outside its assignment if pointed at a live repository tree. -- **Filesystem isolation.** Research workflows run inside disposable workspaces outside the live repository. Workers receive only scoped snapshots of declared files, keeping live repository files untouched. -- **Mechanical verification.** Execution workflows require a clean git working tree, execution scope checks (`check-execution-scope.sh` or `check-execution-scope.ps1`), frozen path checks, and automated test gates. -- **Prohibition on nested dispatch.** Assignments instruct workers not to dispatch nested workers. -- **Vendor-neutral worker adapters.** [`docs/worker-adapter-contract.md`](docs/worker-adapter-contract.md) defines the assignment, lifecycle, capability/model discovery, ownership, and normalized-result boundary. The included launcher is a reference adapter; verification and cleanup remain with the orchestrator. -- **Orchestrator-owned dispatch.** `dispatch-worker.sh` or `dispatch-worker.ps1` is the only workflow entry point that admits an assignment, creates its worktree, and starts its worker process. The dispatcher sets `OFFLOAD_WORKER_CONTEXT=1` for the worker. Worker-context calls to the dispatcher, launcher, or execution-workspace lifecycle helpers fail closed and record a `nested_dispatch_rejected` event. -- **Structured follow-up requests.** A worker may return a request for more work in `structured_output`, but that request is data for the orchestrator to review. It never starts a process automatically. -- **Bounded assignment ledger.** The dispatcher records assignment ID, parent ID, depth, child IDs, role, owned and frozen paths, lifecycle timestamps, output and error paths, worktree manifest, and timeout/resource budget in an `offload-dispatch-state-v1` ledger. Root limits for depth, child width, timeout, and total resource units are immutable for descendants; admission rejects attempts that would exceed them. -- **Defense in depth.** Vendor sandbox behavior, including `agy --mode plan`, is a useful additional boundary but is not treated as enforcement. The workflow verifies the worker context, assignment ledger, worktree lifecycle, frozen paths, execution scope, and test gates mechanically. +The host may offer Offload for implementation with at least three independently gated assignments when the repository is clean, or for a read-only audit or research task with at least two independent evidence tracks. The user must consent before dispatch. A refusal settles the offer for the session. -## Supported environments +## Repository layout -| Host path | Required runtime | Required tools | CI system | -|---|---|---|---| -| Native Windows | PowerShell 7+ | Git and a configured adapter | `windows-latest` | -| Linux with Bash | Bash 3.2+ | Git, `jq`, Python 3, and a configured adapter | `ubuntu-latest` | -| macOS with Bash | Bash 3.2+ | Git, `jq`, Python 3, and a configured adapter | `macos-latest` | -| Linux or macOS with PowerShell | PowerShell 7+ | Git and a configured adapter | Supported by contract, not a required CI job | - -### Helper family selection - -Orchestrators select helper scripts based on their current shell (`.sh` for Bash, `.ps1` for PowerShell), never by host operating system detection or universal launchers. Native Windows orchestrators require only PowerShell 7 (`pwsh`), Git, and the configured adapter. Windows workflows do not require Bash, WSL, Git Bash, Python, or `jq`. - -### Worker adapters - -The repository ships three adapters. Each one probes the installed worker, -launches it with the selection made by the orchestrator, and returns the shared -normalized result format. - -| Adapter | Entry points | Contract | -|---|---|---| -| AGY | `scripts/run-agy-json.ps1`, `scripts/run-agy-json.sh` | Reference adapter for `agy` workers | -| Claude Code | `scripts/run-claude-json.ps1`, `scripts/run-claude-json.sh` | [`docs/specs/0004-claude-adapter.md`](docs/specs/0004-claude-adapter.md) | -| Codex CLI | `scripts/run-codex-json.ps1`, `scripts/run-codex-json.sh` | [`docs/codex-adapter.md`](docs/codex-adapter.md) | - -All adapters implement [`docs/adapter-contract.md`](docs/adapter-contract.md). -Set `AGY_BIN` or `CLAUDE_BIN` when the corresponding executable is not on -`PATH`. Unsupported or unmarked sandboxes fail closed; an adapter does not turn -the caller checkout into a sandbox. - -## Requirements - -- A CLI coding agent that can read skills and run shell commands (Claude Code, Codex CLI, or similar). -- The configured adapter, available on `PATH` or at the path accepted by the launcher. The included reference adapter can use `agy`, but no provider is assumed by the public contract. -- For execution workflows: a git repository with a clean working tree (`git status --porcelain` is empty). Research workflows run in disposable workspaces. +- [SKILL.md](SKILL.md) is the active delegation contract. +- [CONTEXT.md](CONTEXT.md) and [ADR 0012](docs/adr/0012-keep-offload-outcome-based-and-runtime-dynamic.md) define the current vocabulary and decisions. +- [Benchmark references](docs/research/2026-09-07-benchmark-references-for-runtime-routing.md) are advisory evidence for runtime choices. +- [Execution scope](scripts/check-execution-scope.sh) and [execution workspace](scripts/execution-workspace.sh) helpers retain generic implementation safety. +- [Research workspace](scripts/make-research-workspace.sh) and [research cleanup](scripts/cleanup-research-workspace.sh) helpers retain bounded disposable snapshots. +- The tests under [tests](tests) check the contract, isolation, scope, cleanup, failure fallback, and repository consistency. ## Installation -### Option A: skillshare - -```bash -skillshare install anthonyandrei/offload --track -skillshare sync -``` - -The `--track` flag keeps git history so `skillshare update offload` can pull updates. Skillshare places tracked repositories under an underscore prefix, so the skill installs at `_offload/` and is invoked as `_offload`. - -### Option B: copy the entire skill directory - -Copy the whole skill directory into your agent's skills folder: - -#### Bash -```bash -cp -R /path/to/offload ~/.claude/skills/offload -``` - -#### PowerShell -```powershell -Copy-Item -Recurse -Path \path\to\offload -Destination $HOME\.claude\skills\offload -``` - -Because `offload` contains mode documents in `modes/` and helper scripts in `scripts/`, you must copy the entire directory rather than a single file. - -## Router and mode selection - -Root `SKILL.md` is a lightweight router that resolves how a task runs. It routes tasks into three mode documents: - -1. **Explicit mode override.** Honor explicit user requests specifying `execution`, `repo-research`, or `web-research`. -2. **Research-backed mutations.** When a code change depends on external research, route to `modes/web-research.md` first to gather evidence and audit citations. Pass the audited summary to `modes/execution.md` for implementation. -3. **Direct mutations.** Route code or file changes directly to `modes/execution.md`. -4. **Local read-only questions.** Route questions answerable from local repository files to `modes/repo-research.md`. -5. **External read-only questions.** Route questions requiring current web facts or external documentation to `modes/web-research.md`. -6. **Mixed local and external questions.** Route questions needing both local files and web evidence to `modes/web-research.md` with a declared repository snapshot. - -Single factual lookups stay local with the orchestrator and are not offloaded. - -## Worker roles - -| Role | Mode | Preference | Job | -|---|---|---|---| -| scout | Execution | fast | Discovers repository-relative file paths touched by provisional tasks. | -| gate-author | Execution | balanced | Authors executable test files from acceptance criteria. | -| implementer | Execution | balanced | Modifies owned code files to satisfy gates. | -| reviewer | Execution | deep | Evaluates diffs adversarially against criteria for diff-gated tasks. | -| researcher | Research | balanced | Collects structured findings for assigned evidence angles or bounded local scopes. | -| synthesizer | Web research | deep | Builds claim ledgers, resolves conflicts, and drafts answers. | -| auditor | Web research | deep | Independently verifies citation URLs and claims against live sources. | - -Worker routing is governed by repository-root `model-policy.json` and [`docs/adapter-contract.md`](docs/adapter-contract.md). Launchers accept `--role ` and select a current eligible catalog entry. Callers must not supply `--model` or `--effort` flags. - -A historical live smoke comparison against Gemini 3.7 retained Flash for every role. The proposed Pro split did not complete its mandatory synthesis stage, while the all-Flash control completed synthesis and citation audit with four supported claims. The recorded comparison is in [`tests/live-smoke-comparison.md`](tests/live-smoke-comparison.md). - -## Workflows - -### Execution workflow (`modes/execution.md`) - -Used for code and file modifications across independent gated tasks. - -1. **Split and scout.** Break work into provisional tasks. Dispatch parallel scouts under `--mode plan` via `dispatch-worker`, which wraps `run-agy-json`, with a JSON schema to identify touched files. If tasks overlap on files, serialize them. -2. **Assign gates.** Every task receives exactly one gate: - - **Machine gate.** An automated test command exiting 0 on success. A gate-author worker writes the test. The orchestrator runs a red check against the untouched tree to verify failure, reads the test code to confirm intent, and commits the test to freeze it. - - **Diff gate.** Plain-text criteria for tasks without test commands (such as documentation or configuration changes) receive stable IDs. A reviewer worker evaluates the immutable review artifact and returns exactly one verdict per ID. The orchestrator accepts only complete all-pass coverage whose evidence lines match the same artifact. -3. **Dispatch implementers.** Dispatch implementers in parallel from a clean git tree with explicit owned files, frozen paths, gate commands, and bounded budgets via `dispatch-worker`. The dispatcher wraps `execution-workspace` and `run-agy-json`; workers never call those lifecycle or launch interfaces directly. -4. **Mechanical verification.** - - Execution scope check: verify touched paths against assigned owned and frozen paths using `check-execution-scope`: - #### Bash - ```bash - "$OFFLOAD_ROOT/scripts/check-execution-scope.sh" --owned src/render.py --frozen tests/test_render.py - ``` - #### PowerShell - ```powershell - & "$OffloadRoot/scripts/check-execution-scope.ps1" --owned src/render.py --frozen tests/test_render.py - ``` - - Gate command: run the machine test command or run `check-review-verdict` against the reviewer JSON, stable criteria file, and recorded artifact after checking its digest. - -### Repository research workflow (`modes/repo-research.md`) - -Used for bounded local codebase investigations, audits, and invariant checks without mutating files. - -1. **Assignment specification.** Every assignment declares four items: - - One bounded question. - - Allowed scope of files or directories. - - Evidence expectations (file paths with line numbers or reproducible commands). - - Explicit non-mutation rule. -2. **Filesystem isolation.** Create a disposable workspace with `make-research-workspace.sh` or `make-research-workspace.ps1`. The helper copies only declared scope paths into a snapshot directory (`/repo/`). Run the worker pointed at the snapshot directory via `run-agy-json`. -3. **Verification protocol.** Run read-only orchestrator checks against the live repository: - - Reject citations outside declared scope. - - Check all high-priority findings directly in live files (`orchestrator+checked`). - - Sample medium- and low-priority findings (`orchestrator+sampled`). - - Mark unsupported claims as unverified (`agy+unverified`). -4. **Cleanup.** Run `cleanup-research-workspace.sh` or `cleanup-research-workspace.ps1` with `--status success`. - -### Web research workflow (`modes/web-research.md`) - -Used for technical investigations, documentation lookups, and multi-angle research against online sources. - -1. **Stage 1: Dispatch researchers.** Split the question into independent evidence angles. Dispatch parallel researchers returning structured JSON claims with source URLs, publication dates, and source types via `run-agy-json`. -2. **Stage 2: Synthesize claim ledger.** Extract findings with `extract-structured-output`. A synthesizer worker merges findings into a structured claim ledger, discards unsupported incidental claims, preserves decision-relevant uncertainty, and drafts a proposed answer. -3. **Stage 3: Independent citation audit.** An independent auditor opens each URL cited in the proposed answer to verify resolution, direct claim support, date fitness, and primary versus derivative classification. -4. **Audit revision loop.** If the auditor requests revisions, the synthesizer runs one revision pass to narrow or remove rejected claims, followed by a final audit. -5. **Provenance and cleanup.** Validate and build `provenance.json` with `collect-provenance`, write `/final.md`, and clean the workspace with `cleanup-research-workspace`. - -## Research profiles and automatic deep triggers - -Web research operates under two profiles: - -- **Standard profile.** Dispatches 2 or 3 parallel researchers across distinct angles, followed by 1 synthesizer and 1 auditor. Use for general technical questions, documentation lookups, and library comparisons. -- **Deep profile.** Dispatches up to 5 researchers in total. Deep research starts from standard findings and adds only supplementary angles to resolve specific uncertainty or conflicts, without re-running standard angles. - -Deep profile activates on explicit user request or automatically when one of four triggers occurs: - -1. **Material source conflict.** High-trust primary sources directly contradict one another. -2. **Costly or hard-to-reverse decision.** Architectural choices, infrastructure migrations, or licensing commitments. -3. **Citation-sensitive output.** Formal specifications, security advisories, or compliance requirements. -4. **Substantial counterevidence.** Initial findings challenge core architectural assumptions. - -The active profile and trigger are recorded in the report and in `provenance.json`. - -## Workspace isolation and scoped snapshots - -Research workers never run directly against live repository files. - -The workspace helper creates a unique temporary directory outside the repository: - -#### Bash -```bash -WORKSPACE=$(./scripts/make-research-workspace.sh --source-repo "$PWD" --path src/auth --path config.json) -``` - -#### PowerShell -```powershell -$Workspace = (& ./scripts/make-research-workspace.ps1 --source-repo (Get-Location).Path --path src/auth --path config.json).Trim() -``` - -The script copies only declared paths into `/repo/` and creates the `.offload-research-workspace` marker. Worker prompts and `--add-dir` arguments point to the snapshot directory. The live repository remains untouched. - -## Source policy - -- **Public sources default.** Research workers query public web sources by default. -- **Explicit authorization for private sources.** Accessing private, internal, or authenticated repositories and APIs requires explicit user authorization for that specific run. Never forward cookies, session tokens, browser profiles, or environment credentials implicitly. - -## Failure handling and recovery - -Follow the shared recovery rules in `SKILL.md`: - -- **Stable worker IDs and retry ceiling.** Each assignment retains a stable identifier across attempts. Attempt 1 is initial dispatch; attempt 2 is the only permitted retry (maximum two attempts per task). -- **Quality versus operational failures.** Failing a machine gate, scope check, or citation audit is a quality failure; operational failures include crashes, timeouts (20m), and unparsable output. Operational failures retry with `--route default` using the recorded selection. Quality failures retry with `--route quality-retry` using the recorded pin; if it is unavailable, record an explicit fallback or handoff instead of switching silently. -- **Immediate quota handoff.** If adapter-reported quota is exhausted, stop dispatching immediately and hand all unfinished work back to the calling orchestrator while preserving completed artifacts. -- **Outcome tracking.** Every attempt and verification verdict is recorded in `routing-outcomes.json` in the scratch workspace. Web research provenance optionally records routing attempt data in `provenance.json`. -- **Implementer failures.** If an implementer fails its gate or violates execution scope, retry once with the error output. If the retry fails, halt that task. -- **Researcher failures.** If a researcher crashes or times out, retry once. If the retry fails, synthesis proceeds as long as at least two independent evidence angles remain. The final report explicitly names any omitted angle. -- **Synthesis and audit failures.** Synthesis and citation audit are mandatory stages. If either stage crashes, times out, or fails to resolve citations after its retry budget, the run transitions to `partial` status. -- **Partial result contract.** A `partial` run returns verified claims and raw findings collected before the failure. It strictly withholds firm conclusions or recommendations, states the failed stage, and preserves all raw artifacts for debugging. - -## Compact provenance and report contract - -### Provenance tracking and workspace cleanup - -At the end of a research run, `collect-provenance` validates and generates `provenance.json`: - -#### Bash -```bash -./scripts/collect-provenance.sh \ - --run-id "run-01" \ - --request-summary "Evaluate database migration options" \ - --selected-mode "web-research" \ - --profile "standard" \ - --start-time "2026-08-31T10:00:00Z" \ - --end-time "2026-08-31T10:04:30Z" \ - --duration-seconds 270 \ - --scratch-path "$WORKSPACE" \ - --workers "$WORKERS_JSON" \ - --final-citations "$CITATIONS_JSON" \ - --audit-verdicts "$AUDITS_JSON" \ - --final-status "success" \ - --incomplete-stage-reasons "[]" \ - --output "$WORKSPACE/provenance.json" -``` - -#### PowerShell -```powershell -& ./scripts/collect-provenance.ps1 ` - --run-id "run-01" ` - --request-summary "Evaluate database migration options" ` - --selected-mode "web-research" ` - --profile "standard" ` - --start-time "2026-08-31T10:00:00Z" ` - --end-time "2026-08-31T10:04:30Z" ` - --duration-seconds 270 ` - --scratch-path "$Workspace" ` - --workers $WorkersJson ` - --final-citations $CitationsJson ` - --audit-verdicts $AuditsJson ` - --final-status "success" ` - --incomplete-stage-reasons "[]" ` - --output "$Workspace/provenance.json" -``` - -After generating provenance, `cleanup-research-workspace` cleans the temporary workspace: - -#### Bash -```bash -./scripts/cleanup-research-workspace.sh --workspace "$WORKSPACE" --status success -``` - -#### PowerShell -```powershell -& ./scripts/cleanup-research-workspace.ps1 --workspace "$Workspace" --status success -``` - -- On `success`, the helper removes intermediate worker files and snapshot directories while preserving `final.md`, `provenance.json` when present, `routing-outcomes.json`, the workspace marker, and `evidence-disposition.json`. The disposition manifest records each routing evidence path, its pre-cleanup existence, a SHA-256 hash for existing regular files, and whether it was retained, pruned, missing, or left uninspected for safety. -- On `partial` or failure, the helper retains all raw artifacts and logs. - -### Crash recovery and resource ownership - -The adapters maintain a durable, orchestrator-owned resource ledger outside worker checkouts. Pass the same ledger, assignment ID, and parent ID to workspace and worker helpers when coordinating a run: - -```bash -LEDGER="$SCRATCH/offload-resource-ledger.json" -WORKSPACE=$(./scripts/make-research-workspace.sh --ledger "$LEDGER" --assignment-id "$ASSIGNMENT" --parent-id "$PWD" --source-repo "$PWD" --path src/auth) -./scripts/run-agy-json.sh --role researcher --ledger "$LEDGER" --assignment-id "$ASSIGNMENT" --parent-id "$PWD" --output "$WORKSPACE/worker.json" --error "$WORKSPACE/worker.err" -- --prompt '...' -./scripts/cleanup-research-workspace.sh --workspace "$WORKSPACE" --status success --ledger "$LEDGER" --resource-id "research-workspace:$ASSIGNMENT" -``` - -If the orchestrator crashes, reconcile the ledger on its next run. Reconciliation terminates recorded worker processes before cleaning their resources and discovers AGY-native Git worktrees that were never registered as `unknown`. It never deletes dirty, unmerged, unowned, ambiguous, or otherwise unprovable resources. - -### Shared report format - -All modes format results into a consistent summary: - -```markdown -## Offload run: N workers, - -| worker | gate / lane | provenance | result | files / findings | -|--------|-------------|------------|--------|------------------| -| parser | pytest tests/test_parser.py | agy+red+read | ✓ 12/12 | as assigned (scout) | -| render | pytest tests/test_render.py | orchestrator (fallback) | ✓ 8/8 | ⚠ +1 stray | -| docs | diff | agy+grep | △ judged | as assigned (scout) | -| auth-audit | audit (isolated) | orchestrator+checked (high) + orchestrator+sampled (med/low) | complete | 3 findings (2 verified, 1 unverified) | - -### Claimed by worker, not verified -- "also improved error messages" -- "Legacy endpoints may be affected" -``` - -### Provenance values - -- `orchestrator`: Step performed directly by orchestrator. -- `agy+red+read`: Gate written by worker, checked with red run and inspection. -- `agy+grep`: Recorded artifact reviewed by worker, verbatim quote and digest verified by the orchestrator. -- `agy→orchestrator`: Reviewer escalated, diff inspected by orchestrator. -- `orchestrator+checked`: Evidence directly verified in live repository. -- `orchestrator+sampled`: Sample of medium or low priority citations verified. -- `agy+unverified`: Finding lacking verifiable evidence. -- `orchestrator (fallback)`: Worker failed, completed by orchestrator. - -### Result classifications - -- **Proven**: Verified by automated test exit code or mechanical check. -- **Judged**: Evaluated against written criteria by diff reviewer or orchestrator. -- **Verified**: Confirmed by direct orchestrator check or codebase sampling. -- **Audited**: Verified by independent citation auditor against live sources. -- **Claimed**: Asserted in worker output without verification; explicitly marked unverified. - -## Proactive offer contract - -Offload uses a portable, model-readable proactive-offer contract instead of vendor-specific hooks. Orchestrators offer offload unprompted when tasks meet qualified scale thresholds, ask for confirmation before dispatching, and respect user preference for the remainder of the session. - -### Worked context example - -Place this instruction block in your agent's project context file (`AGENTS.md`, `CLAUDE.md`, or custom instructions): - -```markdown -## Offload delegation - -- Use Offload when the user asks to offload, run work through a specific vendor adapter, or accepts a compatible-worker offer. -- Offer a selected compatible worker once, before starting, when implementation splits into three or more independently gated tasks in a clean Git repository, or when a read-only audit or external research requires multiple distinct work lanes. Count research lanes by distinct questions or evidence responsibilities, not browser tabs. -- Keep narrow factual answers, explanations, single-source lookups, and focused code reviews local. -- Ask before dispatching. -- Ask once per session. If the user declines, continue locally without offering another worker in that session. -- When Offload applies, let its skill instructions choose the appropriate workflow mode. -``` - -### Optional host adapters - -Host automation or hooks that implement the proactive-offer contract must satisfy four requirements: - -1. **Trigger conditions**: Trigger only when the proactive-offer conditions hold (3+ independently gated implementation tasks in a clean git repository, or multi-lane research/audit). -2. **Session state**: Keep once-per-session state and never ask repeatedly after a refusal. -3. **User consent**: Ask the user before dispatching workers. -4. **Fail open**: Fail open so a broken adapter never blocks the host agent's normal workflow. - -## Deterministic test suite - -Run the automated acceptance suite to verify contracts across supported helper families: - -#### Bash -```bash -bash tests/test_research_modes.sh -bash tests/test_execution_scope.sh -bash tests/test_worker_adapter_contract.sh -bash tests/test_agy_preflight.sh -``` - -#### PowerShell -```powershell -pwsh -File tests/test_research_helpers.ps1 -pwsh -File tests/test_execution_scope.ps1 -pwsh -File tests/test_worker_adapter_contract.ps1 -pwsh -File tests/test_codex_adapter.ps1 -pwsh -File tests/test_agy_preflight.ps1 -``` - -The Codex worker boundary is documented in docs/codex-adapter.md. It discovers -the installed CLI structured-output support and selects models from the -host-provided CODEX_MODEL_CATALOG. It fails closed when either capability is -unavailable. - -## Findings about agy - -- **Catalog preflight is bounded and read-only.** The AGY adapters bound both model discovery and the headless usage probe; timeout, malformed, missing, stale, and unsupported observations remain unknown. -- **Group-level usage is not protocol capacity.** The current `agy /usage` response exposes fractions and reset times, but no protocol `remaining_units` or `reserved_units`, so the adapter does not infer unlimited or available capacity. -- **The installed CLI does not prove full eligibility.** AGY 1.1.27 does not expose a supported non-secret account identifier, per-model entitlement, billing route, or per-model reservation capacity through the inspected headless surface. Automatic selection therefore fails closed. See [ADR 0010](docs/adr/0010-agy-preflight-discovery.md). -- **Use `dispatch-worker.sh` or `dispatch-worker.ps1` for execution assignments.** They own assignment admission, worktree creation, result and error paths, and the bounded launch. The dispatcher wraps the lower-level `run-agy-json` helper, which rejects the unsupported `agy --output` flag. -- **Use structured output extractors (`extract-structured-output.sh` or `extract-structured-output.ps1`) between research stages.** They forward only validated `structured_output`, keeping verbose worker prose out of later prompts. -- **Model routing is governed by `model-policy.json` and the adapter contract.** Launchers select a live eligible model using the role preference, effort, required capabilities, quota, and static security rules. The adapter receives the exact selection and translates it for its vendor. Reasoning effort stays separate from model identity, and callers must not pass `--model` or `--effort`. -- **`--mode plan` is a version-sensitive behavioral hint, not a write barrier.** The accepted probe on `agy 1.1.25` blocked the tested direct write outside the permitted artifact area, but this observation is not a guarantee. `--add-dir` grants access without confining writes. Security relies on filesystem isolation and mechanical verification. - -Run the maintainer-only compatibility probe when the installed `agy` behavior needs a refresh (never as a deterministic CI gate): - -```text -pwsh -NoProfile -File scripts/probe-agy-compatibility.ps1 --workspace --output -``` - -Published provenance and reports are redacted at the publication boundary. Browser/headless claims must carry an in-scope reality anchor. Process completion and exit 0 do not by themselves establish an accepted result; gates that cannot run use the `unrunnable` classification. +Install the complete repository directory as a skill. The repository is the source of truth for the contract and its generic safety helpers. -## License +## Verification -MIT. See `LICENSE`. +The contract suite runs natively in Bash and PowerShell. It checks the active documentation, helper behavior, disposable workspace safety, bounded research snapshots, failed-launch fallback, and references to removed workflow machinery. diff --git a/SKILL.md b/SKILL.md index be0fa09..8ff693b 100644 --- a/SKILL.md +++ b/SKILL.md @@ -1,267 +1,61 @@ --- name: offload -description: Use when the user wants execution or research handed to another CLI agent instead of running it here. Triggers include "offload this", "run this on a worker", or after answering yes to the offload offer. Also offer unprompted when implementation splits into three or more independently gated tasks in a clean git repository, or when a read-only audit or online research fans out across multiple angles or files. Dispatches parallel headless workers through an adapter, gates their output, and reports what was proven versus claimed. +description: Use when the user explicitly asks to offload work to another worker, names a worker provider, or accepts an offload offer. Offer proactively for large, independently gated implementation or research work when the host instructions permit it. --- # offload -If you are a dispatched worker, stop here. Return worker results to your orchestrator. Workers do not dispatch nested workers. Any agent that can read instructions and run shell commands can orchestrate, including Claude Code, Codex CLI, and similar agents. Assignments prohibit nested worker dispatch, and the workflow enforces that boundary with an orchestrator-owned dispatcher and worker-context guards. +Offload is an optional delegation workflow. The calling agent remains the orchestrator: it owns the assignment, reviews the result, finishes unfinished work, and gives the final report. -## What this skill does +Use this skill when the user explicitly asks to offload or run work on another worker, names a worker provider, or accepts a proactive offer. Keep narrow factual answers, explanations, single-source lookups, and focused code reviews local. A worker must not dispatch another worker. -`offload` delegates execution and research tasks to headless workers through a configured adapter. A reference adapter is included, but the workflow contract does not depend on a vendor or exact model ID. You remain the orchestrator. You decompose tasks, set acceptance criteria or bounded questions, and verify evidence and gates. Workers handle exploration, test authoring, code implementation, diff review, and research evidence collection. +## Before delegation -You never accept worker claims at face value. You verify output through mechanical checks, test execution, diff inspections, or secondary reviews. +- Describe one bounded assignment. Include the objective, in-scope paths or questions, acceptance criteria, deliverables, and the boundary of the worker's authority. +- If the user named a provider, honor that choice. Otherwise inspect the worker tools currently available to the host. When the choice matters, use each tool's current native help or model-listing facility rather than relying on copied instructions. +- Choose the worker, model, and reasoning effort from the task, required capabilities, current availability, cost, relevant benchmark references, and judgment. The benchmark note is advisory evidence, not a routing table. +- Unknown entitlement, billing, quota, capacity, or benchmark information never blocks an attempted launch. The real launch is the definitive usability check. +- Start one worker per bounded assignment by default. Split work only when the pieces are genuinely independent and each has its own acceptance criteria. -## Publication boundary +Do not encode provider command syntax, copied help text, exact model identifiers, a universal catalog, or a role matrix in this workflow. Those details belong to the worker tool and the current runtime. -Published source skills use the vendor-neutral contract in -[`docs/contracts/publication-compatibility.md`](docs/contracts/publication-compatibility.md). -`grill-with-docs` owns its interview and documentation workflow and can run -without offload. Offload is an explicit optional delegation layer. Adapters own -vendor command syntax, model catalogs, capability probes, and output parsing. +## Implementation work -Published consumers use capabilities, internal model preferences, separate -reasoning effort, and normalized results. They do not depend on vendor names, -family labels, or exact model IDs. The compatibility checker rejects -unavailable adapters and vendor-specific references. Capability support does not -enforce security. The orchestrator still owns isolation, execution scope -checks, cleanup, and acceptance gates. +- Place implementation work in an appropriately isolated disposable worktree or project copy. The worker must not write directly to the orchestrator's live checkout before review. +- Give the worker its assignment and acceptance criteria. Do not give it authority to widen its paths, change the assignment, dispatch nested workers, or alter orchestrator state. +- After launch, inspect the actual files and diff. Check scope, intent, and the relevant project checks. A success message from the worker is evidence to inspect, not an acceptance decision. +- Accept or integrate changes only when the criteria and relevant verification pass. Reject out-of-scope or unverified changes, then finish the assignment yourself or report the remaining blocker. +- Remove the disposable workspace after accepted integration. If partial output must be preserved, name it in the report and clean it when the orchestrator has recovered what it needs. -## Preconditions and helper selection +## Research work -Select the helper family matching your current host shell: +- Define bounded questions and evidence responsibilities. Use separate disposable snapshots when repository context or concurrent work makes isolation useful. +- Prefer credible primary sources and claim-level support. Reject broken citations or claims not supported by their cited sources. Mark inference, uncertainty, disagreement, missing evidence, and stale evidence plainly. +- A worker's research synthesis is not accepted solely because it contains citations or reports success. The orchestrator reviews the sources and the claims they support. +- Do not require a universal result envelope or provider-specific research record. Keep only the evidence needed to support the final answer. -- **POSIX shells (Bash 3.2+)**: Use `.sh` scripts in `scripts/`. Requires Git, `jq`, Python 3, and the configured adapter's own executable. -- **PowerShell (PowerShell 7+)**: Use `.ps1` scripts in `scripts/`. Native Windows orchestrators require PowerShell 7 (`pwsh`), Git, and the configured adapter. Windows workflows do not require Bash, WSL, Git Bash, Python, or `jq`. +## Launch failure and fallback -Check these requirements before dispatching workers: +- A failed launch or failed run returns the unfinished assignment and any usable partial output to the orchestrator automatically. +- Do not hide a failed launch with an Offload-managed second automatic attempt or a silent provider switch. The orchestrator may make a new, explicit decision after reporting what failed. +- The orchestrator completes the remaining work when it can do so safely. Otherwise it reports a resumable partial result, the failure, and the precise blocker. -1. **Offer before dispatch.** When reaching this skill unprompted, offer the choice to the user first following the proactive offer contract. Describe the planned dispatch and ask for confirmation. Ask once per session. A negative response settles the decision for the rest of the session. -2. **Local factual lookups.** Keep a single factual lookup local with the orchestrator; do not offer or route it to offload. -3. **Adapter availability.** Verify the configured adapter is invokable and can return a protocol-2 catalog. The adapter must prove authenticated access, current entitlement, billing route, and usage capacity for the selected account and model. An installed CLI or static catalog entry is not enough. -4. **Git working tree.** Writing workflows (`modes/execution.md`) require a clean git repository (`git rev-parse --is-inside-work-tree` and empty `git status --porcelain`). Research workflows (`modes/repo-research.md`, `modes/web-research.md`) operate in isolated disposable workspaces. -5. **Preflight model availability check.** Before dispatching the first worker in a run: - - Read repository-root `model-policy.json` (resolved relative to helper scripts, never the caller's working directory). - - Ask the configured adapters for live catalogs, then filter by verified access, entitlement, billing route, fresh usage, required capabilities, and supported effort. - - Estimate assignment, verification, and one retry unit, including active shared reservations. If no eligible worker exists or availability cannot be established, block dispatch and return the affected work to the caller. Do not silently switch providers or fall back to an unverified default. - - An explicit provider is checked first and is never replaced silently. Unknown usage is allowed only for an explicit provider after the other checks pass, and the selection records the uncertainty. - - Avoid repeating catalog discovery for every worker in the same run unless the adapter reports that availability changed. -6. **Policy installation, updates, and revert.** - - `model-policy.json` is located at repository root alongside helper scripts. Installation must copy the entire skill directory (including `model-policy.json`). - - The policy enforces `schema_version: 2`, a non-empty `policy_revision`, `max_effort: "high"`, `max_retries_per_worker: 1`, `quota_action: "handoff"`, and exactly seven role mappings: `scout`, `gate-author`, `implementer`, `reviewer`, `researcher`, `synthesizer`, and `auditor`. - - Each role declares an internal preference (`fast`, `balanced`, or `deep`), an independent effort (`low`, `medium`, or `high`), and required capabilities. It does not publish vendor names or exact model IDs. - - To update policy: edit `model-policy.json` in the skill root and update `policy_revision`. To revert: restore the prior revision. Launchers validate the entire policy on every invocation. Missing or invalid policy fails closed before launching workers. - - There is no policy-level model escalation target. Quality retries use the pinned selection when one exists. A missing pin requires an explicit fallback or handoff record. +## Proactive offer -## Routing +Host instructions may offer Offload without an explicit request only when all of the following are true: -Once invoked, select a mode using this order: +- implementation has at least three independently gated assignments and the Git repository is clean, or +- a read-only audit or research task has at least two distinct evidence tracks. -1. **Explicit mode override.** Honor an explicit user request specifying a mode (`execution`, `repo-research`, or `web-research`). -2. **Research-backed mutation.** When a requested mutation depends on external research, route to `modes/web-research.md` first for evidence gathering and audit, then route to `modes/execution.md` for implementation. -3. **Direct mutation.** Route a direct file or code change with no external research prerequisite to `modes/execution.md`. -4. **Local read-only question.** Route a read-only question answerable from declared local files to `modes/repo-research.md`. -5. **External read-only question.** Route a read-only question requiring current or external evidence to `modes/web-research.md`. -6. **Mixed local and external question.** Route a question needing both local and external evidence to `modes/web-research.md` with a declared repository snapshot. +Ask for consent before dispatching. A refusal settles the offer for the rest of the session. Do not offer it for narrow work. The host keeps the final result and remains responsible for verification. -## Modes +## Final report -Load the matching mode document for the selected route and shell-specific commands: +State the bounded assignment, worker choice when relevant, actual result, files or sources inspected, verification performed, remaining uncertainty, and any failure or fallback. Say whether disposable workspaces were removed. Do not claim a worker ran until its launch succeeded. -- [`modes/execution.md`](modes/execution.md): Dispatches scouts, gate-authors, implementers, and diff reviewers for code and file modifications. -- [`modes/repo-research.md`](modes/repo-research.md): Dispatches bounded local code investigations and audits in isolated workspaces with direct evidence verification. -- [`modes/web-research.md`](modes/web-research.md): Dispatches multi-angle online researchers, synthesis, and citation auditing in isolated workspaces. +## Repository references -## Shared model routing and launcher contract - -Offload routes all workers through the repository-root `model-policy.json` and the adapter contract in [`docs/adapter-contract.md`](docs/adapter-contract.md). The launcher selects an eligible current catalog entry. The adapter translates that exact selection into vendor-specific arguments. Callers must never pass `--model` or `--effort` after `--`. - -### Launcher invocation - -Execution workers must use `scripts/dispatch-worker.sh` or `scripts/dispatch-worker.ps1`, which calls this lower-level launcher after admission. The direct forms below are for the isolated research stages described in the research mode documents. - -- **POSIX shells**: `"$OFFLOAD_ROOT/scripts/run-agy-json.sh" --role [--route ] --adapter --provider --output --error --lifecycle --assignment-id --attempt <1|2> --mode --verification-baseline --resource-ledger -- ` -- **PowerShell**: `& "$OffloadRoot/scripts/run-agy-json.ps1" --role [--route ] --adapter --provider --output --error --lifecycle --assignment-id --attempt <1|2> --mode --verification-baseline --resource-ledger '--' ` - -In PowerShell command expressions, always quote the delimiter (`'--'`). - -### Roles and preferences - -| Role | Preference | Effort | Primary mode | -|---|---|---|---| -| `scout` | fast | low | Execution | -| `gate-author` | balanced | high | Execution | -| `implementer` | balanced | high | Execution | -| `reviewer` | deep | high | Execution | -| `researcher` | balanced | high | Repo research / Web research | -| `synthesizer` | deep | high | Web research | -| `auditor` | deep | high | Web research | - -### Routes - -- `--route default` (default): Selects the best eligible catalog entry for the role's preference, effort, and capabilities. -- `--route quality-retry`: Requires a pin from the prior attempt and reuses that exact adapter, vendor, model ID, and effort. If the pin is missing or unavailable, the launcher records an explicit fallback or handoff condition and does not switch silently. - -## Worker adapter contract - -The vendor-neutral boundary for one bounded worker assignment is defined in -[`docs/worker-adapter-contract.md`](docs/worker-adapter-contract.md). The -orchestrator owns assignment constraints, verification, publication, and -cleanup decisions. An adapter owns vendor command syntax, output parsing, -capability discovery, and model catalog handling, then returns the normalized -result described by that contract. Validate adapter results with -`scripts/check-worker-adapter.ps1` or `scripts/check-worker-adapter.sh` before -running the existing execution scope check and gates. - -## Shared recovery, retry accounting, and failure handling - -### Worker lifecycle contract - -Both native launchers write the same lifecycle artifact for every dispatched worker. The state machine is: - -`created -> started -> running -> completed|failed|canceled|quota-handoff -> retained -> cleaned` - -`started` includes the child process ID. The launcher waits for the child to exit, records its exit code, and only then records `retained` and `cleaned`. Timeout uses `failed` with `failure_class: "timeout"`; cancellation uses `canceled`; explicit quota diagnostics use `quota-handoff`. Output, error, lifecycle, and resource-ledger paths remain available as diagnosis evidence for every non-success terminal state. - -The launcher accepts `--timeout-seconds` and a testable `--cancel-file`. A timeout or cancellation terminates the worker, waits for exit, flushes both streams, and finalizes the lifecycle artifact before returning. A zero-exit worker advances to `completed` only when its output is a successful JSON envelope with `structured_output`; malformed output is recorded as `failed` with `failure_class: "malformed_output"`. - -`--resource-ledger` records the stable assignment, pinned model, effort, verification baseline, and attempt artifacts. Attempt 2 must use the same assignment and pinned model/effort as attempt 1. Attempt 3 is rejected before dispatch. Resume and retry consumers must read the ledger and select an explicit accepted attempt; they must not infer the latest artifact by wildcard. - -### Stable worker IDs and retry ceiling - -- A worker represents one logical assignment, not a single process run. -- Assign each logical assignment a stable `worker_id` across attempts. -- **Attempt 1** is the initial dispatch. -- **Attempt 2** is its only permitted retry. Maximum two attempts total per assignment. -- Changing process IDs, models, conversations, or prompt instructions does not reset the retry count. - -### Attempt artifact paths - -- Give every worker process its own output and error paths. Include the stable `worker_id` and attempt number in both paths, such as `.attempt1.json` and `.attempt1.err`. -- Build the paths before each launcher call. Attempt 2 must use new paths, never the attempt 1 paths, so the launcher cannot truncate earlier evidence. -- Add every process artifact path to that attempt's `evidence_paths` entry in `routing-outcomes.json`. -- After verification, record one explicit `accepted_attempt` for each logical worker beside that worker's `routing` container, and point its selected output field at that attempt's artifact. Downstream stages read only the accepted attempt paths. They must not use a wildcard or a filename that can refer to the latest retry by accident. - -### Failure classification and recovery rules - -1. **Verified success**: Output passes mechanical gates and verification checks. Accept result; no retry. -2. **Quality failure**: The worker completed with a parsable response (exit code 0), but the output fails verification (e.g. machine gate failure normalized to `quality` via `execute-gate.sh` or `execute-gate.ps1`, execution scope violation, reviewer quote mismatch, unsupported synthesis claim, or audit rejection). - - If retry budget remains and mode permits correction: retry once (attempt 2) with concrete verification feedback. Use `--route quality-retry` with the recorded pin; if the pin is unavailable, record an explicit fallback or handoff instead of selecting a replacement silently. - - If attempt 2 fails or the mode requires immediate fallback: stop retrying and follow that mode's halt, partial-result, or orchestrator fallback path. -3. **Unrunnable failure**: Gate execution exited 126 or 127, normalized to `failure_class: "unrunnable"` with `verification: not_performed`. Preserve the command, exit code, and diagnostic evidence in `routing-outcomes.json`. Exits 126 and 127 are not quality retries; do not schedule or spend a model retry. -4. **Operational failure**: Process crash (nonzero exit code), timeout (20 minutes with no output), unparsable JSON, or tool failure. - - Follow mode's recovery rule with at most one same-model retry (`--route default`) where permitted. Never escalate models for operational failures. -5. **Unknown failure**: Record uncertainty and follow the operational-failure path. Do not assume a quality failure or quota issue. -6. **Quota exhaustion**: Explicit quota exhaustion reported by the adapter or worker diagnostics. Trigger immediate quota handoff. - -### Immediate quota handoff - -When explicit quota exhaustion is detected: -- Stop dispatching new workers immediately. -- Return unfinished work to the calling orchestrator without waiting for running siblings. -- Do not retry automatically, wait for reset, switch models, or activate paid credits. -- Preserve completed artifacts. -- Report status of all assignments: verified, unverified, failed, pending (never dispatched), and still running (with process/job references and output paths). The calling orchestrator takes ownership. - -## Run outcome records (`routing-outcomes.json`) - -The orchestrator maintains `routing-outcomes.json` in each run's scratch workspace. It records process and verification history per attempt: - -- Top-level fields: `schema_version` (integer 1) and `attempts` (array). -- Each attempt object records: - - `worker_id`: Stable assignment identifier. - - `role`: One of the 7 policy roles. - - `mode`: `execution`, `repo-research`, or `web-research`. - - `attempt`: Integer 1 or 2. - - `policy_revision`: Policy revision string. - - `route`: `"default"` or `"quality-retry"`. - - `adapter`: Adapter name and `adapter_revision`. - - `vendor`: Adapter-reported vendor family. - - `model_id`: Exact selected model ID. `model` may repeat it for compatibility with older records. - - `family_hint`: Descriptive adapter metadata. It never grants permissions or promises cross-vendor quality. - - `preference`: Internal policy preference (`fast`, `balanced`, or `deep`). - - `effort`: Selected reasoning effort (`low`, `medium`, or `high`), kept separate from model identity. - - `catalog_revision`: Adapter catalog or probe revision used for selection. - - `selection_reason`: Deterministic filtering and ranking reason. - - `preflight_reasons`: Exact sanitized diagnostics from the selection record. Copy them unchanged into every attempt. - - `usage_uncertain`: Boolean indicating that explicit provider or pin policy admitted unknown usage. - - `reason`: Initial dispatch or observed failure and recovery decision authorizing attempt 2. - - `started_at`: ISO 8601 UTC timestamp. - - `ended_at`: ISO 8601 UTC timestamp (null while running). - - `duration_seconds`: Observed elapsed time (null while running). - - `exit_code`: Worker process exit code (null while running). - - `state`: `"running"`, `"completed"`, `"failed"`, or `"interrupted"`. - - `failure_class`: `"none"`, `"quality"`, `"timeout"`, `"tool_error"`, `"malformed_output"`, `"quota"`, `"unrunnable"`, or `"unknown"`. - - `verification`: `"pending"`, `"passed"`, `"failed"`, or `"not_performed"`. - - `evidence_paths`: Array of output, error, gate, review, or audit artifact paths. - - `usage`: Source-attributed reported usage object with explicit units, or null when unavailable. - -Pending assignments that never dispatched are listed in the final handoff report, not as attempt records. In web research runs, routing history for a worker may optionally be attached as a `routing` container (`{schema_version: 1, attempts: [...]}`) in each worker entry within `provenance.json`. See [`modes/web-research.md`](modes/web-research.md#provenance-and-cleanup) and canonical fixture [`tests/fixtures/routing-worker.json`](tests/fixtures/routing-worker.json) for the complete worker record example. - -## Shared report contract - -Use this standard report format across all modes: - -```markdown -## Offload run — N workers, - -| worker | gate / lane | provenance | result | files / findings | -|--------|-------------|------------|--------|------------------| -| parser | pytest tests/test_parser.py | agy+red+read | ✓ 12/12 | as assigned (scout) | -| render | pytest tests/test_render.py | orchestrator (fallback) | ✓ 8/8 | ⚠ +1 stray | -| docs | diff | agy+grep | △ judged | as assigned (scout) | -| auth-audit | audit (isolated) | orchestrator+checked (high) + orchestrator+sampled (med/low) | complete | 3 findings (2 verified, 1 unverified) | - -### render — ownership violation -owned: src/render.py -also edited: src/util.py - - -### docs — reviewer verdict -pass: 3/3 criteria, all quotes matched verbatim. No escalation. - -### auth-audit — findings & verification sample -- [HIGH] [orchestrator+checked] Route `/api/v1/reset` lacks session check (src/auth/routes.py:L45-L52) — confirmed. -- [MED] [orchestrator+sampled] Token expiry default is 30d (src/config.py:L18) — confirmed by sample. -- [LOW] [agy+unverified] "Legacy endpoints may be affected" — unverified (no location cited). -Sample recorded: 1/1 high checked, 1/2 med/low sampled. - -### Claimed by worker, not verified -- "also improved error messages" -- "Legacy endpoints may be affected" -``` - -### Provenance values - -- `orchestrator`: Step performed directly by the orchestrator. -- `agy+red+read`: Gate written by gate-author, validated by red check and read. -- `agy+grep`: Recorded artifact reviewed by worker, verbatim quote and digest verified by the orchestrator. -- `agy→orchestrator`: Reviewer escalated or hedged, diff inspected by orchestrator. -- `orchestrator+checked`: Evidence location or command directly verified in repository. -- `orchestrator+sampled`: Sample of medium- or low-priority citations verified. -- `agy+unverified`: Finding or claim lacking verifiable evidence. -- `orchestrator (fallback)`: Worker failed or timed out, completed by orchestrator. - -### Result classifications - -- **Proven**: Verified by an automated command exit code or mechanical check. -- **Judged**: Evaluated against written criteria by a diff reviewer or orchestrator. -- **Verified**: Confirmed by direct orchestrator check (`orchestrator+checked`) or sampling (`orchestrator+sampled`) against repository files. -- **Audited**: Verified by an independent citation auditor worker against live sources. -- **Claimed**: Asserted by worker output without independent verification; labeled explicitly as unverified. - -## Limits and worker safety - -- **`--mode plan` is a version-sensitive behavioral hint, not a write barrier.** The accepted compatibility probe on `agy 1.1.25` found the tested direct write outside the permitted artifact area blocked, but exposed tools and command paths remained available. This observation is not a guarantee and plan mode is not the sole containment or safety mechanism. -- **`--add-dir` grants directory access without confining writes.** A worker can edit files outside its assignment if pointed at the live tree. -- **Filesystem isolation.** Research modes run in disposable workspaces with scoped file snapshots. Live repository files are never exposed directly to research workers. -- **Execution safety.** Execution mode requires a clean git baseline, mechanical execution scope checks (`check-execution-scope.sh` or `check-execution-scope.ps1`), frozen path diffs, and test gates. -- **Orchestrator-owned dispatch.** Use `scripts/dispatch-worker.sh` or `scripts/dispatch-worker.ps1` for every execution assignment. It is the only workflow interface that creates an assignment record, execution worktree, and worker process. The dispatcher sets `OFFLOAD_WORKER_CONTEXT=1`; worker-context calls to the dispatcher, `run-agy-json`, or `execution-workspace` fail with exit 126. -- **Structured follow-up requests.** Workers may return a structured request for more work. The orchestrator records and evaluates that data explicitly. No worker response can automatically create a child assignment. -- **Assignment ledger.** Every admitted assignment records its ID, parent ID, depth, child IDs, role, owned and frozen paths, lifecycle state and timestamps, output/error paths, worktree manifest, and timeout/resource budget. The root fixes maximum depth, child width, per-assignment timeout, and total resource units. Admission rejects a request before worktree or process creation when it would exceed any limit. -- **Vendor boundary versus workflow verification.** `agy --mode plan` and any vendor sandbox are defense in depth. The workflow does not treat prompts or sandbox hints as its sole control; it verifies caller context, ledger admission, worktree lifecycle, scope, frozen paths, and gates. -- **Bounded scope requirement.** Open-ended research without a bounded question, declared scope, and evidence expectations is out of scope. -- **Worker timeout.** Every dispatched worker has a bounded dispatcher timeout and forwards the normal AGY output deadline (`--print-timeout 20m`). - -Result acceptance is separate from process completion: a parsed envelope, substantive structured output, evidence/scope/gate checks, and (where applicable) review or citation checks must all pass before an explicit `accepted_attempt` is recorded. Exit code 0 alone does not establish verified success. Gate exits 126 or 127 are `unrunnable`, retain their command and diagnostic evidence, use `verification: not_performed`, and do not consume a model retry. +- [CONTEXT.md](CONTEXT.md) defines the project's terms and durable contract. +- [ADR 0012](docs/adr/0012-keep-offload-outcome-based-and-runtime-dynamic.md) records why the workflow stays outcome-based and runtime-dynamic. +- [Benchmark references](docs/research/2026-09-07-benchmark-references-for-runtime-routing.md) records optional decision evidence. +- The generic [execution scope checker](scripts/check-execution-scope.sh) and [execution workspace helper](scripts/execution-workspace.sh) enforce the retained implementation safety outcomes. diff --git a/docs/adapter-contract.md b/docs/adapter-contract.md deleted file mode 100644 index 65b80cb..0000000 --- a/docs/adapter-contract.md +++ /dev/null @@ -1,107 +0,0 @@ -# Worker adapter catalog contract - -Status: accepted. Catalog protocol version 2. - -The launcher owns policy, selection, retry identity, capacity admission, and -filesystem scope. An adapter owns vendor syntax, authenticated discovery, and -the live catalog. The public workflow names a worker role, an internal -preference (`fast`, `balanced`, or `deep`), a reasoning effort, and required -capabilities. It does not name a vendor or exact model ID unless the user -explicitly chooses one. - -## Operations - -The launcher invokes an adapter with one of these operations: - -```text -adapter --operation catalog --request REQUEST.json -adapter --operation launch --request SELECTION.json --output OUTPUT --error ERROR -- WORKER_ARGS... -``` - -`REQUEST.json` contains the role, preference, effort, required capabilities, -policy revision, route, and protocol version. The catalog operation writes one -JSON object to stdout. A catalog must report the adapter revision, vendor, -catalog revision, model entries, and a normalized preflight record for each -candidate: - -```json -{ - "protocol_version": 2, - "adapter": "configured-adapter", - "adapter_revision": "adapter-2", - "vendor": "provider-name", - "catalog_revision": "provider-current", - "models": [{ - "id": "provider-exact-model-id", - "supported_efforts": ["low", "high"], - "capabilities": ["structured-output"], - "scores": {"fast": 1, "balanced": 2, "deep": 3}, - "preflight": { - "access": {"state": "verified", "reason": "authenticated", "account_ref": "nonsecret-account-ref"}, - "entitlement": {"state": "active", "reason": "subscription", "billing_route": "included"}, - "usage": { - "state": "known", - "observed_at": "2026-09-05T00:00:00Z", - "source": "provider-usage", - "scopes": [{"scope_id": "account-window", "remaining_units": 8, "reserved_units": 0, "reset_at": "2026-09-05T01:00:00Z"}] - } - } - }] -} -``` - -Discovery probes must enforce a real process deadline and terminate the full -probe process tree before returning. The Bash AGY adapter uses GNU `timeout` -with a completion marker when available. Its fallback requires `setsid` or -`pgrep` for process-tree cleanup and fails closed when neither is available. -Provider exit codes, including 124 and 137, are not treated as timeout proof. - -Access, entitlement, billing, and usage observations must be current, scoped, -and explainable. Missing, malformed, stale, unsupported, or optimistic -observations never become available capacity. The selector requires known -fresh usage for automatic selection. An explicit provider may proceed with -unknown usage only after access, capability, entitlement, and billing checks -pass, with the uncertainty recorded in the selection. - -When a candidate is rejected, the selector emits a sanitized diagnostic that -preserves whether the provider confirmed a failure or verification was -unavailable or unsupported. An eligible selection carries `preflight_reasons` -and `usage_uncertain` so handoff and retry paths retain the same decision -context. Adapter fields such as `available` or `quota_available` cannot turn -an unknown observation into verified access or capacity. - -Selection accepts only these normalized billing routes: `included`, -`subscription`, `test-subscription`, `probe-subscription`, `free`, `trial`, -`community`, and `enterprise`. Denied, rejected, forbidden, paid-fallback, -empty, unknown, or any other route remains ineligible. Eligible selection -records contain only the allowlisted preflight fields, with account references -and provider-controlled reasons redacted before they are written or handed -off. - -The selector rejects expired entitlements, paid-fallback routes, explicit -ineligibility, and candidates that cannot cover the assignment, verification, -and one allowed retry. It ranks eligible candidates by the role preference and -capabilities first, remaining capacity second, and stable provider/model -identity last. Family labels and installed CLIs do not establish quality or -access. - -The selection record includes the normalized preflight evidence, a capacity -estimate, and reservation scopes. The launcher reserves those scopes before a -managed launch, then records completion, cancellation, failure, or recovery. -Competing admissions use an atomic ledger. Reservation and usage evidence -must not contain credentials, tokens, or private account data. - -## Pinning and retries - -The launcher writes the complete selection record when `--selection-output` is -supplied. The orchestrator copies it into every `routing-outcomes.json` attempt -together with the attempt number and verification result. A retry or resume -supplies the same record with `--pin`. The launcher checks the pinned adapter, -provider, account or billing route, exact model ID, effort, and current -eligibility. A missing pinned model fails explicitly and requires a recorded -fallback or handoff. No retry silently changes provider, model, effort, or -billing route. At most one retry is allowed for an assignment. - -Adapters keep discovery, quota, cancellation, wait, and exit-code details -behind this protocol. They must not widen the permissions, tools, path scope, -or resource ownership granted by the orchestrator. diff --git a/docs/adr/0001-maintain-shell-native-helper-families.md b/docs/adr/0001-maintain-shell-native-helper-families.md index 03687b6..391d872 100644 --- a/docs/adr/0001-maintain-shell-native-helper-families.md +++ b/docs/adr/0001-maintain-shell-native-helper-families.md @@ -1,5 +1,5 @@ --- -status: accepted +status: superseded by ADR 0012 --- # Maintain shell-native helper families diff --git a/docs/adr/0005-bound-model-routing-to-gemini-and-explicit-rules.md b/docs/adr/0005-bound-model-routing-to-gemini-and-explicit-rules.md index 0cf2ee5..a719bfd 100644 --- a/docs/adr/0005-bound-model-routing-to-gemini-and-explicit-rules.md +++ b/docs/adr/0005-bound-model-routing-to-gemini-and-explicit-rules.md @@ -1,5 +1,5 @@ --- -status: accepted +status: superseded by ADR 0012 --- # Bound model routing to Gemini and explicit rules diff --git a/docs/adr/0007-cross-library-publication-boundaries.md b/docs/adr/0007-cross-library-publication-boundaries.md index 4768d99..198fee7 100644 --- a/docs/adr/0007-cross-library-publication-boundaries.md +++ b/docs/adr/0007-cross-library-publication-boundaries.md @@ -1,5 +1,5 @@ --- -status: accepted +status: superseded by ADR 0012 --- # Keep published skills vendor-neutral diff --git a/docs/adr/0008-runtime-model-selection-through-adapters.md b/docs/adr/0008-runtime-model-selection-through-adapters.md index bb55eb1..a743449 100644 --- a/docs/adr/0008-runtime-model-selection-through-adapters.md +++ b/docs/adr/0008-runtime-model-selection-through-adapters.md @@ -1,6 +1,6 @@ # ADR 0008: Select models at runtime through worker adapters -- Status: accepted +- Status: superseded by [ADR 0012](0012-keep-offload-outcome-based-and-runtime-dynamic.md) - Date: 2026-09-04 - Supersedes: [ADR 0005](0005-bound-model-routing-to-gemini-and-explicit-rules.md) diff --git a/docs/adr/0009-select-compatible-workers-before-offering-offload.md b/docs/adr/0009-select-compatible-workers-before-offering-offload.md index b25db19..a507dd0 100644 --- a/docs/adr/0009-select-compatible-workers-before-offering-offload.md +++ b/docs/adr/0009-select-compatible-workers-before-offering-offload.md @@ -1,6 +1,6 @@ # ADR 0009: Select compatible workers before offering offload -- Status: accepted, implementation pending +- Status: superseded by [ADR 0011](0011-launch-first-admission-and-orchestrator-fallback.md) - Date: 2026-09-05 - Extends: ADR 0003 and ADR 0008 diff --git a/docs/adr/0010-agy-preflight-discovery.md b/docs/adr/0010-agy-preflight-discovery.md index 7da18ea..c419c1b 100644 --- a/docs/adr/0010-agy-preflight-discovery.md +++ b/docs/adr/0010-agy-preflight-discovery.md @@ -1,6 +1,6 @@ # ADR 0010: Fail closed when AGY preflight cannot prove eligibility -- Status: accepted +- Status: superseded by [ADR 0011](0011-launch-first-admission-and-orchestrator-fallback.md) - Date: 2026-09-06 - Extends: ADR 0008 and ADR 0009 - Issue: [#42](https://github.com/anthonyandrei/offload/issues/42) diff --git a/docs/adr/0011-launch-first-admission-and-orchestrator-fallback.md b/docs/adr/0011-launch-first-admission-and-orchestrator-fallback.md new file mode 100644 index 0000000..e4b99b7 --- /dev/null +++ b/docs/adr/0011-launch-first-admission-and-orchestrator-fallback.md @@ -0,0 +1,36 @@ +# ADR 0011: Use launch-first admission and orchestrator fallback + +- Status: superseded by [ADR 0012](0012-keep-offload-outcome-based-and-runtime-dynamic.md) +- Date: 2026-09-07 +- Supersedes: [ADR 0009](0009-select-compatible-workers-before-offering-offload.md) and [ADR 0010](0010-agy-preflight-discovery.md) +- Extends: [ADR 0008](0008-runtime-model-selection-through-adapters.md) + +## Context + +Offload grew from an AGY orchestrator into a provider-neutral framework. Its admission path also grew into an attempt to prove account entitlement, billing route, and enough quota for an assignment, verification, and retry before launching a worker. Providers do not consistently expose that evidence. The AGY adapter therefore returned unknown values that the selector treated as blockers, making ordinary AGY dispatch impossible even when a real launch could have succeeded. + +Workers are fallible collaborators. The orchestrator must verify their work, but routine delegation does not need a workflow engine that predicts every provider failure before attempting a launch. The user also prefers hands-off recovery over a mid-run prompt asking whether to try another vendor. + +## Decision + +Provider discovery and run admission are separate operations. A manual or cached setup check may discover installed adapters, models, and provider-reported capabilities. Each run uses the provider named by the user or a configured default. It does not scan and rank every vendor by live usage before dispatch. + +Run admission checks that the chosen adapter and model exist and that any required capability the provider can report is present. Missing or unsupported access, entitlement, billing, or usage data is not a blocker. A fresh, explicit provider denial, unavailable model, prohibited billing route, or exhausted quota may block launch. Otherwise, the launch itself is the definitive access and capacity check. + +Adapters own catalog discovery, launch translation, and result normalization. They do not have to prove account or billing facts that the provider does not expose. Offload never switches providers silently. + +When a worker fails, unfinished work returns to the orchestrator automatically. The orchestrator preserves usable partial output, completes the remaining work when it can do so safely, and reports the worker failure in the final result. It does not interrupt the run to offer another vendor. If safe completion is impossible, it returns a resumable partial result and explains the blocker. + +Routine work defaults to one worker per bounded assignment with orchestrator verification. Separate scouts, gate authors, reviewers, citation auditors, or retries require a task-specific reason. Publication, integration, and acceptance gates still fail closed. Reports must not claim that a worker is running until launch has succeeded, and disposable workspace claims describe scoped project copies rather than operating-system containment. + +## Consequences + +- AGY and other providers can run when their CLI and model exist even if they cannot expose pre-launch quota or billing details. +- Known provider failures remain actionable, while unavailable telemetry no longer prevents useful work. +- The orchestrator may spend more of its own tokens after a worker failure, in exchange for fewer user interruptions and more reliable task completion. +- Capacity ledgers and speculative entitlement checks are no longer required for ordinary admission. Existing implementations that enforce them must be simplified to match this decision. +- Historical ADRs 0009 and 0010 remain available as the record of the stricter policy and why it was replaced. + +## Implementation status + +At acceptance, the selectors, adapter contract, skill instructions, and user documentation still implement or describe the superseded preflight policy. This ADR records the accepted replacement; aligning those files is separate implementation work. diff --git a/docs/adr/0012-keep-offload-outcome-based-and-runtime-dynamic.md b/docs/adr/0012-keep-offload-outcome-based-and-runtime-dynamic.md new file mode 100644 index 0000000..5150496 --- /dev/null +++ b/docs/adr/0012-keep-offload-outcome-based-and-runtime-dynamic.md @@ -0,0 +1,48 @@ +# ADR 0012: Keep offload outcome-based and runtime-dynamic + +- Status: accepted +- Date: 2026-09-07 +- Supersedes: [ADR 0001](0001-maintain-shell-native-helper-families.md), [ADR 0005](0005-bound-model-routing-to-gemini-and-explicit-rules.md), [ADR 0007](0007-cross-library-publication-boundaries.md), [ADR 0008](0008-runtime-model-selection-through-adapters.md), and [ADR 0011](0011-launch-first-admission-and-orchestrator-fallback.md) + +## Context + +Offload began as a way to orchestrate AGY workers, then expanded into an agent-agnostic orchestration framework. The expansion introduced adapter contracts, normalized catalogs, model policies, provider admission checks, routing records, retries, parallel shell command families, and prescribed command sequences. + +That machinery attempted to make every orchestrator reason and route identically. It also depended on provider facts that were unavailable or unknowable before launch. In practice, admission could reject a usable worker because entitlement, billing, or quota remained unknown. + +The durable value of offload is narrower. It should preserve the quality and safety obligations around delegation while allowing the runtime model to decide how to satisfy them from its current tools and evidence. + +## Decision + +Offload is an outcome-based workflow, not a vendor orchestration framework or step-by-step command guide. + +The skill records no vendor command syntax, copied help text, model matrix, adapter interface, normalized model catalog, quota protocol, routing algorithm, provider-specific retry policy, or persistent worker-performance ledger. The orchestrator discovers installed worker tools, current models, capabilities, and command syntax at runtime when that information is useful. It may inspect native help and model-listing facilities directly. + +The orchestrator chooses whether to delegate and selects the vendor, model, and reasoning effort using the assignment, current availability, cost, relevant benchmark references, and its own judgment. Benchmark references are advisory evidence. They do not prove availability, entitlement, remaining usage, subscription cost, or performance in the actual worker harness. Missing, stale, unavailable, or mismatched benchmark evidence never blocks delegation. + +A real launch is the definitive usability check. Offload does not attempt to prove usable capacity in advance. It does not silently switch providers or run an offload-level retry engine. When a worker fails, unfinished work returns to the orchestrator automatically. + +Offload standardizes only the assurances surrounding delegation: + +- A worker receives one bounded assignment in an appropriately isolated workspace. +- The orchestrator treats the worker as a fallible collaborator. +- Worker-authored implementation is reviewed and subjected to relevant verification before acceptance. +- Research is grounded in credible sources, citations are checked, and inference is identified. +- The orchestrator completes or safely reports unfinished work after worker failure. +- Temporary workspaces are removed after accepted integration. +- The final report states what was delegated, what was verified, and what remains uncertain. + +These are procedural assurances. They do not claim that worker output or orchestrator review is infallible. + +## Consequences + +- Different orchestrators may make different routing and execution decisions while satisfying the same acceptance obligations. +- Provider CLI and model changes do not require an offload release merely to update stored commands or catalogs. +- External benchmarks ground judgment without becoming mandatory runtime dependencies. +- AGY remains a valid worker option without being a special architectural boundary. +- Runtime model quality and judgment affect outcomes more than prescriptive workflow mechanics. +- The existing command-heavy skill, adapters, routing policy, ledgers, and duplicated helper families do not implement this decision and require a separate simplification change. + +## Decision references + +The initial advisory shortlist is recorded in [the benchmark research note](../research/2026-09-07-benchmark-references-for-runtime-routing.md). It may evolve independently because references support judgment rather than define protocol behavior. diff --git a/docs/codex-adapter.md b/docs/codex-adapter.md deleted file mode 100644 index 5c07559..0000000 --- a/docs/codex-adapter.md +++ /dev/null @@ -1,123 +0,0 @@ -# Codex adapter - -The Codex adapter is a vendor-neutral worker boundary for hosts that provide the -Codex CLI. It conforms to the worker adapter contract (`docs/adapter-contract.md`) -and has PowerShell and Bash entry points: - -```text -scripts/run-codex-json.ps1 --operation catalog --request -scripts/run-codex-json.ps1 --operation launch --request --output --error -- - -bash scripts/run-codex-json.sh --operation catalog --request -bash scripts/run-codex-json.sh --operation launch --request --output --error -- -``` - -The Bash entry point requires Bash 3.2 or newer and `jq`; the PowerShell entry -point requires PowerShell 7 or newer. - -## Operations - -### Catalog discovery - -`--operation catalog --request ` probes the installed Codex CLI for -the structured execution flags used by the adapter: `--json`, `--output-schema`, -and `--output-last-message`. It also reads the host-provided `CODEX_MODEL_CATALOG` -(or `OFFLOAD_ADAPTER_CATALOG`) environment variable. The variable may contain a -JSON document or a path to one: - -```json -{ - "revision": "host-catalog-1", - "models": [ - { - "id": "host-selected-model", - "preference": "balanced", - "efforts": ["low", "medium", "high"] - } - ] -} -``` - -The adapter emits a protocol version 2 catalog document to standard output: - -```json -{ - "protocol_version": 2, - "adapter": "codex", - "adapter_revision": "codex-2", - "vendor": "codex", - "catalog_revision": "host-catalog-1", - "models": [ - { - "id": "host-selected-model", - "family_hint": "unknown", - "available": true, - "quota_available": true, - "supported_efforts": ["low", "medium", "high"], - "capabilities": ["structured-output"], - "scores": { "fast": 2, "balanced": 1, "deep": 2 }, - "preflight": { - "access": { "state": "verified", "account_ref": "account-ref" }, - "entitlement": { "state": "active", "billing_route": "subscription" }, - "usage": { - "state": "known", - "source": "codex-usage", - "observed_at": "2026-09-05T00:00:00Z", - "scopes": [ - { "scope_id": "account-window", "remaining_units": 12, "reserved_units": 0 } - ] - } - } - } - ] -} -``` - -The catalog is supplied by the host; the adapter does not hardcode vendor model -IDs. Access, entitlement, billing, and usage are independent preflight facts. -Missing or stale facts remain unknown and cannot be selected as compatible. If -the CLI flags or catalog are unavailable, the adapter fails closed and exits -nonzero. - -### Worker launch - -`--operation launch --request --output --error -- ` -launches Codex with the exact model selected by the orchestrator. The adapter -parses worker arguments following the `--` delimiter (such as `--prompt`, `--cd`, -`--cancel-file`, and `--timeout-seconds`), preserving argument and path -boundaries when values contain spaces. - -The adapter owns the native Codex invocation syntax, supplying fixed -constraints: - -- `exec --json --ephemeral` -- `--cd ` -- `--sandbox workspace-write` -- `--ask-for-approval never` -- `--output-schema ` -- `--output-last-message ` -- `--model ` -- `-- ` - -The adapter captures process standard output and standard error, writing the -normalized result to the designated output path: - -```json -{ - "status": "success", - "structured_output": { ... }, - "model_id": "host-selected-model" -} -``` - -## Security and responsibility boundary - -The orchestrator owns assignment constraints, execution-scope verification, -final acceptance gates, resource ledgers, and cleanup. The adapter does not run -adapter-owned scope checks or acceptance gates, nor does it maintain a competing -private ledger schema. - -Cancellation (signal or cancel file) terminates the process and exits with code -130. Timeout terminates the process and exits with code 124. Quota exhaustion -exits with code 75 for caller handoff. Malformed output exits with code 1, -preserving the raw output for diagnosis. diff --git a/docs/contracts/publication-compatibility.md b/docs/contracts/publication-compatibility.md deleted file mode 100644 index 9a93b6c..0000000 --- a/docs/contracts/publication-compatibility.md +++ /dev/null @@ -1,143 +0,0 @@ -# Publication compatibility contract - -This contract keeps a published source skill independent from worker vendors. -It applies to `grill-with-docs` and to any other skill that may use offload. - -## Ownership boundary - -`grill-with-docs` owns the interview workflow and the documentation workflow. It -must run with no offload, AGY, Codex, Claude, or vendor-model installation. Its -published instructions may describe an optional offload integration, but they -must not require that integration to run the interview. - -`offload` owns optional worker delegation, the orchestrator lifecycle, artifact -verification, and the execution scope check. An adapter owns one vendor's -launch syntax, output parsing, model catalog, capability probe, cancellation, -and resource identity details. The adapter receives the assignment's static -constraints. It cannot widen tool permissions, path scope, worktree scope, or -cleanup obligations. - -Capability support is not security enforcement. An adapter can report that a -worker supports structured output or cancellation. The orchestrator still -enforces filesystem isolation, frozen paths, execution scope checks, cleanup -ownership, and acceptance gates. A vendor's permission feature is never a -substitute for those checks. - -## Stable consumer contract - -Published skills depend on these stable concepts: - -- `orchestrator`, `worker`, and `adapter` roles. -- Assignment requirements and static security constraints. -- Internal model preferences: `fast`, `balanced`, and `deep`. -- Reasoning effort as a separate setting. -- Adapter-reported capabilities and a normalized result. -- Artifact, process, worktree, and resource ownership records. - -They must not depend on a vendor name, a vendor family label, an exact model -ID, or a vendor-specific feature. Exact model IDs and family hints may appear -in adapter-owned runtime records. They are metadata, not a cross-library -contract or a quality guarantee. - -## Manifest and catalog versions - -A published skill carries `publication.json` beside `SKILL.md`: - -```json -{ - "schema_version": 1, - "publication_contract_version": 1, - "skill": "grill-with-docs", - "contract": "vendor-neutral", - "imports": [], - "optional_adapters": [ - { "name": "offload", "min_version": "1.0.0" } - ], - "required_capabilities": [], - "vendor_features": [] -} -``` - -`imports` are required adapters. The compatibility check fails when an import -is absent or older than `min_version`. `optional_adapters` may be absent. A -missing optional adapter produces a warning and does not stop the source skill -from running. `required_capabilities` names a capability supplied by a named -adapter. `vendor_features` must stay empty in a published source skill. - -An adapter catalog records the available adapter contract and its capabilities: - -```json -{ - "schema_version": 1, - "adapter_contract_version": 1, - "adapters": [ - { - "name": "offload", - "version": "1.2.0", - "capabilities": ["worker-delegation", "structured-results"], - "vendor_features": ["adapter-owned-feature"] - } - ] -} -``` - -The contract version changes for incompatible manifest, adapter, helper-family, -or normalized-result changes. A minor version adds optional fields or -capabilities without changing existing meaning. A patch version fixes behavior -without changing the contract. Consumers pin the contract major and set a -minimum adapter version. Adapters may release vendor model changes within that -adapter version line. The orchestrator records the selected adapter, model -metadata, catalog revision, and every attempt for retry and resume. - -## Helper-family compatibility - -The Bash and PowerShell helper families implement equivalent observable -contracts. Each family must preserve argument order, structured-result capture, -output and error separation, ownership records, cleanup rules, and failure -classification. Their implementations may differ. - -There is no universal launcher. Select the helper family from the host shell. -Vendor command syntax stays in the adapter package. A published source skill -may link to the helper-family contract, but it must not copy a vendor command or -assume that one shell is installed. - -Run the compatibility check against a published skill and the adapter catalog: - -```bash -scripts/check-publication-compatibility.sh \ - --skill-root /path/to/published-skill \ - --catalog /path/to/adapter-catalog.json -``` - -```powershell -& scripts/check-publication-compatibility.ps1 ` - --skill-root C:\path\to\published-skill ` - --catalog C:\path\to\adapter-catalog.json -``` - -The check fails for a missing required adapter, an incompatible version, a -missing capability, a vendor feature declaration, or a vendor-specific name in -published Markdown. CI runs both helper-family checks. The check does not prove -that a worker is safe. Runtime verification remains the orchestrator's job. - -## Release and migration guidance - -The source repository is the source of truth. Edit the source skill, -`publication.json`, adapter contract, and helper-family documents there. Do not -edit generated release archives, installed skill copies, or copied adapter -catalogs directly. Regenerate or reinstall them, then run the compatibility -checks and the full contract suite before publishing. - -Release an adapter when its vendor command syntax, model catalog, or capability -probe changes. Release the source skill only when its interview or -documentation workflow changes. A vendor model release therefore updates one -adapter and its catalog record. It does not require a pull request to every -consumer skill. - -Existing AGY-only consumers migrate by removing vendor model IDs and command -examples from their source skill, adding `publication.json`, and declaring the -offload adapter as optional unless delegation is required for the workflow. -Replace vendor-specific settings with a model preference, separate effort, -required capabilities, and the normalized result fields. Keep the old AGY -adapter installed during the migration, run the compatibility checker, and -move any vendor-specific routing or security text into the adapter package. diff --git a/docs/research/2026-09-03-model-routing.md b/docs/research/2026-09-03-model-routing.md deleted file mode 100644 index 812099f..0000000 --- a/docs/research/2026-09-03-model-routing.md +++ /dev/null @@ -1,55 +0,0 @@ -# Gemini model routing research - -Date: 2026-09-03. Run: `offload-model-routing-20260903`. Status: **partial**. - -The final citation audit requested another narrowing and reported one unresolved URL. The permitted revision cycle is exhausted. This note retains supported findings and local observations; it does not recommend role assignments. Raw artifacts remain in the research workspace recorded in the accompanying provenance file. - -## Settled design decisions - -[ADR 0005](../adr/0005-bound-model-routing-to-gemini-and-explicit-rules.md) records the accepted policy: Gemini only, verified success before elapsed time and quota use, role defaults with explicit escalation, repeated local comparisons before promotion, and separate recovery for quality failures, timeouts, tool errors, and exhausted quota. These are user decisions, not research findings. Gemini 3.8 Flash is the requested migration baseline; dispatch defaults have not changed. - -## Direct local observations - -The orchestrator ran `agy models` on this host. It listed Gemini 3.8, 3.7, and 3.6 Flash with low, medium, and high effort, plus Gemini 3.1 Pro with low and high effort. Model availability establishes that a candidate can be selected, not that it suits a role. - -Current mode documents assign 3.7 Flash low to scouts and 3.7 Flash high to the other worker roles. They repeat literal model IDs; the launcher forwards the caller's selection. - -Six applicable invocations in this research run completed using `gemini-3.8-flash-high`. Two synthesis drafts needed correction by citation auditors. These are compatibility observations, not a controlled comparison or an estimate of task success. - -The existing [live smoke comparison](../../tests/live-smoke-comparison.md) stopped one Pro synthesis after 4 minutes 27 seconds without output. Flash completed synthesis and audit. That single comparison does not establish permanent role superiority or a general Pro timeout rate. - -## Findings supported by the final AGY audit - -- **Audited; also opened by the orchestrator.** AGY documentation displays separate Gemini and Claude/GPT usage groups, each with five-hour and weekly limits. It does not establish relative quota consumption across Gemini models. [AGY models](https://www.antigravity.google/docs/models/) -- **Audited by AGY.** The searched vendor evaluation methodology describes benchmark setups such as mini-swe and OSWorld. It supplies no measurements for this repository's offload roles. This is a finding about the searched document, not a claim that no relevant evidence exists elsewhere. [Gemini 3.8 Flash evaluation methodology](https://deepmind.google/models/evals-methodology/gemini-3-8-flash) -- **Audited by AGY.** The searched AGY models and plans pages supply no comparative offload-role latency, tool success rates, or per-model quota consumption measurements. [AGY models](https://www.antigravity.google/docs/models/), [AGY plans](https://www.antigravity.google/docs/plans/) - -## Rejected or unresolved - -The final auditor only partially supported the claim connecting specific effort levels to latency and timeouts, and marked its model-card URL unresolved. The claim is omitted. Earlier drafts also transferred Gemini API capabilities to AGY and proposed Pro escalation without local evidence. Those claims are not accepted. - -The research does not establish winning role assignments, useful escalation targets, comparative quota costs, or reliable automatic recovery from quota exhaustion. API capabilities and prices do not establish AGY behavior or allowance consumption. - -## Offload run, seven invocations - -All invocations used `gemini-3.8-flash-high` in plan mode in a disposable workspace. Workers received public research questions and the observed catalog, with no live repository snapshot. Exact run duration, citations, audit verdicts, and artifact paths are recorded in [provenance](2026-09-03-model-routing.provenance.json). - -| Worker | Lane | Provenance | Result | Findings | -| --- | --- | --- | --- | --- | -| researcher-gemini | Gemini capabilities | AGY findings, then citation audit | Completed | Candidate evidence and limits | -| researcher-operations | AGY availability and usage | AGY findings, then citation audit | Completed | Catalog and quota documentation | -| researcher-alternatives | Non-Gemini alternatives | Orchestrator cancellation | Cancelled | Scope removed after Gemini-only decision; no findings used | -| synthesizer | Initial claim ledger | AGY | Completed; revision required | Unsupported transfers removed later | -| auditor | Initial citation audit | Independent AGY invocation | Revise | Rejected capability and escalation assumptions | -| synthesizer-revised | One permitted revision | AGY | Completed | Four narrowed claims | -| auditor-final | Final citation audit | Independent AGY invocation | Revise | Three claims supported; one omitted | - -The final audit's unresolved citation makes the run partial under the offload web-research contract. All mandatory stages ran. No further revision workers were dispatched. Any implementation that depends on the research requires review and acceptance of these gaps under that contract. - -## Orchestrator follow-up on DeepSWE - -On 2026-09-03, Anthony asked whether DeepSWE already supports migrating to 3.8 Flash. A focused primary-source lookup found Google's launch post reporting stronger software engineering performance and favorable DeepSWE performance relative to larger frontier models at lower cost. The same post says 3.8 can spend more tokens and tool calls on complex tasks, especially at higher effort, and points compute-constrained users toward lower effort or 3.7 Flash. Stronger benchmark performance therefore does not establish lower token consumption than 3.7 or lower AGY quota use. [Google's Gemini 3.8 launch post](https://blog.google/innovation-and-ai/models-and-research/gemini-models/3-8-flash-and-3-8-flash-cyber/) - -The orchestrator retrieved this text through web search; direct page opening failed. This follow-up was not part of the AGY audit and does not change that run's partial status. - -Accepted adjustment: use the published evidence to justify the requested 3.8 baseline migration, check integration with a small smoke test, and reserve repeated comparative evaluations for subsequent changes to effort or model assignments by role. Anthony approved this specific exception to the local-promotion requirement after reviewing the evidence limits. ADR 0005 records it. The original research run remains partial. diff --git a/docs/research/2026-09-03-model-routing.provenance.json b/docs/research/2026-09-03-model-routing.provenance.json deleted file mode 100644 index f8d2ef6..0000000 --- a/docs/research/2026-09-03-model-routing.provenance.json +++ /dev/null @@ -1,280 +0,0 @@ -{ - "run_id": "offload-model-routing-20260903", - "request_summary": "Research Gemini model routing for offload and document accepted design decisions.", - "selected_mode": "web-research", - "profile": "standard", - "deep_trigger": null, - "start_time": "09/02/2026 18:24:28", - "end_time": "2026-09-02T18:39:32.3990747\u002B00:00", - "duration_seconds": 29704.4, - "scratch_path": "C:\\Users\\antho\\AppData\\Local\\Temp\\offload-research-8c3cec7a038f43d0acc7d39879ef25c5", - "workers": [ - { - "output": "C:\\Users\\antho\\AppData\\Local\\Temp\\offload-research-8c3cec7a038f43d0acc7d39879ef25c5\\researcher-gemini.json", - "model": "gemini-3.8-flash-high", - "status": "completed", - "id": "researcher-gemini", - "role": "researcher" - }, - { - "output": "C:\\Users\\antho\\AppData\\Local\\Temp\\offload-research-8c3cec7a038f43d0acc7d39879ef25c5\\researcher-operations.json", - "model": "gemini-3.8-flash-high", - "status": "completed", - "id": "researcher-operations", - "role": "researcher" - }, - { - "id": "researcher-alternatives", - "model": "gemini-3.8-flash-high", - "status": "cancelled", - "output": "C:\\Users\\antho\\AppData\\Local\\Temp\\offload-research-8c3cec7a038f43d0acc7d39879ef25c5\\researcher-alternatives.json", - "reason": "User narrowed scope to Gemini only; no output used", - "role": "researcher" - }, - { - "output": "C:\\Users\\antho\\AppData\\Local\\Temp\\offload-research-8c3cec7a038f43d0acc7d39879ef25c5\\synthesizer.json", - "model": "gemini-3.8-flash-high", - "status": "completed_revision_required", - "id": "synthesizer", - "role": "synthesizer" - }, - { - "output": "C:\\Users\\antho\\AppData\\Local\\Temp\\offload-research-8c3cec7a038f43d0acc7d39879ef25c5\\auditor.json", - "model": "gemini-3.8-flash-high", - "status": "revise", - "id": "auditor", - "role": "auditor" - }, - { - "output": "C:\\Users\\antho\\AppData\\Local\\Temp\\offload-research-8c3cec7a038f43d0acc7d39879ef25c5\\synthesizer-revised.json", - "model": "gemini-3.8-flash-high", - "status": "completed", - "id": "synthesizer-revised", - "role": "synthesizer" - }, - { - "output": "C:\\Users\\antho\\AppData\\Local\\Temp\\offload-research-8c3cec7a038f43d0acc7d39879ef25c5\\auditor-final.json", - "model": "gemini-3.8-flash-high", - "status": "revise", - "id": "auditor-final", - "role": "auditor" - } - ], - "repository_snapshot_paths": [], - "final_citations": [ - "https://www.antigravity.google/docs/models/", - "https://deepmind.google/models/evals-methodology/gemini-3-8-flash", - "https://www.antigravity.google/docs/plans/" - ], - "audit_verdicts": [ - { - "verdict": { - "citation_audits": [ - { - "citation_url": "https://ai.google.dev/gemini-api/docs/models/gemini-3.8-flash", - "claim_id": "claim-gemini-3-8-flash-effort-latency", - "date_fitness": "September 2026 / Current (page updated 2026-09-02 UTC). Matches Gemini 3.8 release date.", - "independence_notes": "Primary vendor API reference documentation from Google AI for Developers.", - "notes": "Verifies thinking effort levels (low, medium, high), but does not document latency, timeouts, or increased token consumption on this page.", - "resolves": true, - "source_classification": "primary", - "support_verdict": "partially_supports" - }, - { - "citation_url": "https://deepmind.google/models/model-cards/gemini-3-8-flash/", - "claim_id": "claim-gemini-3-8-flash-effort-latency", - "date_fitness": "September 2026 / Current (Published September 2026). Matches model release.", - "independence_notes": "Primary vendor model card published by Google DeepMind.", - "notes": "Directly supports configurable effort levels and explicitly notes under Known Limitations that higher effort levels may cause slowness, timeout issues, or increased token consumption.", - "resolves": true, - "source_classification": "primary", - "support_verdict": "supports" - }, - { - "citation_url": "https://ai.google.dev/gemini-api/docs/models/gemini-3.8-flash", - "claim_id": "claim-gemini-3-8-flash-capabilities", - "date_fitness": "September 2026 / Current (page updated 2026-09-02 UTC).", - "independence_notes": "Primary vendor API reference documentation from Google AI for Developers.", - "notes": "Verifies the 1,048,576 token input limit and native API support for caching, code execution, function calling, search grounding, and URL context. Note: transferring these API features to AGY offload runtime is unverified.", - "resolves": true, - "source_classification": "primary", - "support_verdict": "supports" - }, - { - "citation_url": "https://deepmind.google/models/model-cards/gemini-3-8-flash/", - "claim_id": "claim-gemini-3-8-flash-capabilities", - "date_fitness": "September 2026 / Current (Published September 2026).", - "independence_notes": "Primary vendor model card published by Google DeepMind.", - "notes": "Verifies 1M input context window and agentic coding workflows, but detailed tool endpoints (URL context, search grounding, context caching) are specified in the API documentation.", - "resolves": true, - "source_classification": "primary", - "support_verdict": "partially_supports" - }, - { - "citation_url": "https://deepmind.google/models/model-cards/gemini-3-8-flash/", - "claim_id": "claim-vendor-eval-gap", - "date_fitness": "September 2026 / Current (Published September 2026).", - "independence_notes": "Primary vendor model card published by Google DeepMind.", - "notes": "Reports evaluations on synthetic benchmarks (DeepSWE, OSWorld) and lists AGY only as a distribution channel, demonstrating the absence of AGY offload runtime benchmarks in the model card.", - "resolves": true, - "source_classification": "primary", - "support_verdict": "partially_supports" - }, - { - "citation_url": "https://deepmind.google/models/evals-methodology/gemini-3-8-flash", - "claim_id": "claim-vendor-eval-gap", - "date_fitness": "September 2026 / Current (September 2026 technical report).", - "independence_notes": "Primary vendor technical evaluation methodology document published by Google DeepMind.", - "notes": "Confirms evaluations used synthetic/isolated test harnesses (mini-swe agent harness, Terminus 2, OSWorld docker with pyautogui); confirms absence of AGY offload runtime evaluations in searched methodology.", - "resolves": true, - "source_classification": "primary", - "support_verdict": "supports" - }, - { - "citation_url": "https://ai.google.dev/gemini-api/docs/models/gemini-3.8-flash", - "claim_id": "claim-vendor-eval-gap", - "date_fitness": "September 2026 / Current (page updated 2026-09-02 UTC).", - "independence_notes": "Primary vendor API reference documentation from Google AI for Developers.", - "notes": "Defines developer API specifications and contains no empirical AGY offload subagent task success or role latency metrics.", - "resolves": true, - "source_classification": "primary", - "support_verdict": "partially_supports" - }, - { - "citation_url": "https://www.antigravity.google/docs/models/", - "claim_id": "claim-agy-gemini-quota-pooling", - "date_fitness": "Antigravity 2.0 (v2.11.0) / Current live site.", - "independence_notes": "Primary vendor product documentation for Google Antigravity.", - "notes": "Explicitly documents separate usage tracking sections for \u0027Gemini Models\u0027 vs \u0027Claude and GPT models\u0027, each monitoring rolling \u0027Weekly Limit Remaining\u0027 and \u0027Five Hour Limit Remaining\u0027.", - "resolves": true, - "source_classification": "primary", - "support_verdict": "supports" - }, - { - "citation_url": "https://www.antigravity.google/docs/plans/", - "claim_id": "claim-agy-gemini-quota-pooling", - "date_fitness": "Antigravity 2.0 (v2.11.0) / Current live site.", - "independence_notes": "Primary vendor plan and rate limit documentation for Google Antigravity.", - "notes": "Verifies baseline Gemini access across all tiers, five-hour rolling quota refreshes, and weekly rate limits, though specific UI pool separation is detailed in the models page.", - "resolves": true, - "source_classification": "primary", - "support_verdict": "partially_supports" - }, - { - "citation_url": "https://www.antigravity.google/docs/cli/commands/usage/", - "claim_id": "claim-agy-gemini-quota-pooling", - "date_fitness": "Antigravity CLI v1.1.23 / Current live site.", - "independence_notes": "Primary vendor CLI command documentation for Google Antigravity.", - "notes": "Confirms \u0060/usage\u0060 (alias \u0060/quota\u0060) triggers a fresh check of model quotas on disk and from backend services, verifying CLI tracking of model allocations.", - "resolves": true, - "source_classification": "primary", - "support_verdict": "partially_supports" - }, - { - "citation_url": "https://www.antigravity.google/docs/models/", - "claim_id": "claim-agy-runtime-empirics-gap", - "date_fitness": "Antigravity 2.0 (v2.11.0) / Current live site.", - "independence_notes": "Primary vendor product documentation for Google Antigravity.", - "notes": "Supports absence: documents model catalog and configurable thinking levels but contains no empirical turn latency distributions, tool success metrics, or rate limit recovery behavior.", - "resolves": true, - "source_classification": "primary", - "support_verdict": "supports" - }, - { - "citation_url": "https://www.antigravity.google/docs/plans/", - "claim_id": "claim-agy-runtime-empirics-gap", - "date_fitness": "Antigravity 2.0 (v2.11.0) / Current live site.", - "independence_notes": "Primary vendor documentation for Google Antigravity.", - "notes": "Verifies that rate limits correlate dynamically with prompt/work complexity and are uncommitted to fixed latency SLAs or empirical recovery curves, requiring local empirical validation.", - "resolves": true, - "source_classification": "primary", - "support_verdict": "supports" - } - ], - "claims_to_narrow": [ - "claim-vendor-eval-gap: Narrow the absence claim regarding untested runtime fitness specifically to the vendor evaluation sources searched (DeepMind model card, evals methodology report, and Gemini API docs).", - "claim-agy-runtime-empirics-gap: Narrow the absence claim regarding turn latency distributions and recovery behavior specifically to the official Google Antigravity documentation searched (antigravity.google/docs/models/, plans/, and CLI usage docs).", - "claim-gemini-3-8-flash-capabilities: Narrow the inference to clarify that native Gemini API tools (URL context, search grounding, context caching) describe API-level features and do not automatically transfer as proven AGY runtime capabilities without local empirical testing." - ], - "claims_to_remove": [ - "The assertion in the candidate routing table rationale that the Web Researcher role operates \u0027using native search grounding\u0027 in the AGY runtime, which represents an unsupported transfer of Gemini API features to AGY.", - "Any evidentiary claim or routing assumption asserting that Gemini 3.1 Pro is inherently stronger, superior, or a proven escalation rescue for offload roles (such as Synthesizer, Gate-Author, Implementer, or Reviewer) in AGY workflows without empirical proof." - ], - "claims_unresolved": [ - "Empirical turn latency distributions and success rates for gemini-3.8-flash across low, medium, and high effort levels when invoked via standalone agy offload processes.", - "Whether automated escalation to gemini-3.1-pro or higher thinking effort levels resolves failed verification gates in AGY workflows without inducing timeout failures or quota exhaustion.", - "The exact tool execution mechanism by which AGY offload CLI processes perform web retrieval and workspace indexing compared to native Gemini API tooling." - ], - "final_status": "revise" - }, - "worker": "auditor" - }, - { - "verdict": { - "citation_audits": [ - { - "citation_url": "https://deepmind.google/models/model-cards/gemini-3-8-flash/", - "claim_id": "claim-gemini-3-8-flash-effort-latency", - "date_fitness": "Current (published September 2026, corresponding to model release).", - "independence_notes": "Primary first-party vendor documentation from Google DeepMind.", - "notes": "The vendor model card confirms customizable effort levels and notes under Known Limitations that the model may use more tokens to maximize performance especially at higher effort levels, alongside occasional slowness or timeout issues. However, the model card does not specify \u0027low, medium, and high\u0027 effort levels (which appear in AGY UI documentation instead), nor does it explicitly state that higher effort levels directly trigger execution slowness and timeouts.", - "resolves": false, - "source_classification": "primary", - "support_verdict": "partially_supports" - }, - { - "citation_url": "https://www.antigravity.google/docs/models/", - "claim_id": "claim-agy-gemini-quota-pooling", - "date_fitness": "Current (Antigravity 2.0 v2.11.0 documentation, September 2026).", - "independence_notes": "Primary first-party platform documentation from Google Antigravity.", - "notes": "The models documentation UI explicitly displays distinct usage tracking panels for \u0027Gemini Models\u0027 and \u0027Claude and GPT models\u0027, each showing independent rolling \u0027Five Hour Limit Remaining\u0027 and \u0027Weekly Limit Remaining\u0027 meters.", - "resolves": true, - "source_classification": "primary", - "support_verdict": "supports" - }, - { - "citation_url": "https://deepmind.google/models/evals-methodology/gemini-3-8-flash", - "claim_id": "claim-vendor-eval-gap", - "date_fitness": "Current (September 2026 evaluation methodology specification).", - "independence_notes": "Primary first-party vendor evaluation methodology from Google DeepMind.", - "notes": "The vendor evaluation methodology details synthetic benchmark environments (including mini-swe agent harness for DeepSWE v1.1 and OSWorld 2.0 docker for computer use) and contains no benchmarks, latency profiles, or runtime task success measurements for AGY offload subagent workflows.", - "resolves": true, - "source_classification": "primary", - "support_verdict": "supports" - }, - { - "citation_url": "https://www.antigravity.google/docs/models/", - "claim_id": "claim-agy-runtime-empirics-gap", - "date_fitness": "Current (Antigravity 2.0 v2.11.0 documentation, September 2026).", - "independence_notes": "Primary first-party platform documentation from Google Antigravity.", - "notes": "The models documentation covers the reasoning model catalog, effort levels in the model selector, and quota limit indicators, but does not provide comparative role latency distributions, empirical tool success rates, or comparative quota consumption figures across models or effort levels.", - "resolves": true, - "source_classification": "primary", - "support_verdict": "supports" - }, - { - "citation_url": "https://www.antigravity.google/docs/plans/", - "claim_id": "claim-agy-runtime-empirics-gap", - "date_fitness": "Current (Antigravity 2.0 v2.11.0 documentation, September 2026).", - "independence_notes": "Primary first-party platform documentation from Google Antigravity.", - "notes": "The plans documentation specifies tier entitlements, baseline quota refresh cycles, credit overages, and rate limit structure, but does not supply comparative role latency distributions, empirical tool success rates, or comparative quota consumption data across models or effort levels.", - "resolves": true, - "source_classification": "primary", - "support_verdict": "supports" - } - ], - "claims_to_narrow": [ - "claim-gemini-3-8-flash-effort-latency" - ], - "claims_to_remove": [], - "claims_unresolved": [], - "final_status": "revise" - }, - "worker": "auditor-final" - } - ], - "final_status": "partial", - "incomplete_stage_reasons": [ - "Final mandatory citation audit returned revise and marked one model-card citation unresolved. Omitted that claim; no further revision allowed. Comparative role assignments remain unestablished." - ] -} diff --git a/docs/research/2026-09-07-benchmark-references-for-runtime-routing.md b/docs/research/2026-09-07-benchmark-references-for-runtime-routing.md new file mode 100644 index 0000000..c98010b --- /dev/null +++ b/docs/research/2026-09-07-benchmark-references-for-runtime-routing.md @@ -0,0 +1,27 @@ +# Benchmark references for runtime routing + +- Date: 2026-09-07 +- Status: accepted as advisory evidence + +## Conclusion + +Benchmark references can ground an orchestrator's choice of vendor, model, and reasoning effort without becoming a routing matrix or admission dependency. The orchestrator should consult a relevant source when the choice materially affects expected cost or quality, prefer evidence for the exact model and effort, account for harness differences, and proceed by judgment when evidence is absent. + +Initial task-to-reference guidance: + +- **Coding and implementation:** [DeepSWE](https://deepswe.datacurve.ai/) reports software-engineering success, effort, token use, steps, and benchmark cost under a common mini-swe-agent harness. Its results are advisory because the harness differs from native worker CLIs. +- **General non-coding work:** [LiveBench](https://livebench.ai/) provides objective, category-level evaluation for reasoning, data analysis, language, and instruction following, with public [evaluation code and data](https://github.com/LiveBench/LiveBench). Use the relevant category rather than its overall score. +- **Multi-step web research:** [FutureSearch Deep Research Bench](https://drb.futuresearch.ai/) compares research configurations using accuracy, cost, and estimated runtime. Its [paper](https://arxiv.org/abs/2506.06287) documents the benchmark and research harness. +- **Citation-heavy research reports:** [DeepResearch Bench](https://deepresearch-bench.github.io/) evaluates report quality and citation support through RACE and FACT. Its [repository](https://github.com/Ayanami0730/deep_research_bench) publishes tasks, reports, and evaluation code. Scores apply to complete research systems and should not be transferred automatically to their base models. +- **Optional cost and speed context:** [Artificial Analysis](https://artificialanalysis.ai/models) provides broad cross-vendor quality, price, speed, and latency information with a documented [data API](https://artificialanalysis.ai/data-api). It remains optional because its composite methodology and API access introduce their own constraints. + +Human-preference leaderboards such as Arena can serve as subjective tie-breakers, but preference is not a substitute for correctness. Tool-use benchmarks such as BFCL are useful only when function calling is central to the assignment. + +## Boundaries + +- Benchmark evidence ranks only plausible candidates; it does not establish that a CLI exists or can launch. +- Benchmark prices estimate API execution, not subscription quota or marginal CLI cost. +- Whole-agent research benchmarks measure the search stack, prompts, and harness as well as the underlying model. +- Missing exact model or effort data stays missing. Family resemblance is weak evidence, not a synthetic score. +- No benchmark lookup, parser, cache, freshness gate, or API is required for delegation. +- The orchestrator's review of the actual result outranks the worker's benchmark reputation. diff --git a/docs/specs/0001-platform-agnostic-workflows.md b/docs/specs/0001-platform-agnostic-workflows.md deleted file mode 100644 index 636e6a0..0000000 --- a/docs/specs/0001-platform-agnostic-workflows.md +++ /dev/null @@ -1,374 +0,0 @@ -# Platform-agnostic offload workflows - -Status: ready for implementation - -Issue: [#1, Add native Windows / PowerShell support for research workflows](https://github.com/anthonyandrei/offload/issues/1) - -Related decisions: - -- [ADR 0001: Maintain shell-native helper families](../adr/0001-maintain-shell-native-helper-families.md) -- [ADR 0002: Centralize execution scope checks](../adr/0002-centralize-execution-scope-checks.md) -- [ADR 0003: Use a portable proactive-offer contract](../adr/0003-use-a-portable-proactive-offer-contract.md) -- [ADR 0004: Mark workspaces before cleanup](../adr/0004-mark-workspaces-before-cleanup.md) - -## Problem - -Offload describes itself as agent-agnostic, but its commands assume a POSIX shell. Native Windows orchestrators cannot run the documented workflows without WSL or Git Bash. The research helpers require Bash, and parts of the execution workflow require POSIX tools such as `awk`, `sort`, and `comm`. The optional proactive-offer hook also depends on a Claude Code lifecycle event and JSON format. - -The result is a mismatch between the project's stated boundary and its executable path. An orchestrator can run `agy.exe` on Windows but cannot follow Offload's isolation, output capture, provenance, cleanup, or execution verification procedures as written. - -## Solution - -Maintain two shell-native helper families with the same observable contracts: - -- Bash 3.2 or newer for POSIX-shell orchestrators. -- PowerShell 7 or newer for PowerShell orchestrators. - -All execution, repository-research, and web-research instructions must provide a native path for both families. Native Windows must require only PowerShell 7, Git, and `agy`. It must not require Bash, WSL, Git Bash, Python, or `jq`. - -Replace the Claude Code hook with a model-readable proactive-offer contract. Include the current global `AGENTS.md` offload rules as the worked example. Host-specific automation may implement the contract, but no vendor hook belongs to the supported core. - -## User stories - -1. As a Windows orchestrator user, I want to run execution workflows in PowerShell, so that I do not need WSL or Git Bash. -2. As a Windows orchestrator user, I want to run repository research in PowerShell, so that scoped snapshots and live-repository verification remain reproducible. -3. As a Windows orchestrator user, I want to run web research in PowerShell, so that worker output, synthesis, citation audit, provenance, and cleanup use the documented workflow. -4. As a Bash orchestrator user, I want existing helper commands to keep working, so that Windows support does not break current installations. -5. As an orchestrator user, I want `AGY_BIN` to override automatic discovery, so that I can select a specific worker executable. -6. As an orchestrator user, I want an invalid explicit `AGY_BIN` to fail immediately, so that Offload does not run a different executable than the one I selected. -7. As a research user, I want snapshot creation to reject paths that escape the source repository or traverse links, so that workers receive only the declared scope. -8. As a research user, I want cleanup to reject directories that Offload did not create, so that a bad argument cannot erase unrelated files. -9. As an execution user, I want one command to detect unowned changes and modified frozen paths, so that worker scope is checked the same way in every shell. -10. As an agent user, I want portable context instructions for proactive offers, so that my agent can suggest Offload without a vendor-specific hook. -11. As an adapter author, I want a small proactive-offer contract, so that I can implement host automation without copying Claude Code behavior by accident. -12. As a maintainer, I want CI to run the helper contracts on Windows, macOS, and Linux, so that supported platforms cannot drift unnoticed. -13. As a maintainer, I want tests to invoke helper scripts as real processes, so that they verify user-visible behavior rather than implementation details. -14. As a user diagnosing a failed research run, I want partial and failed cleanup to retain raw artifacts, so that the failure remains inspectable. - -## Supported environments - -| Host path | Required runtime | Required tools | CI system | -|---|---|---|---| -| Native Windows | PowerShell 7+ | Git and `agy` | `windows-latest` | -| Linux with Bash | Bash 3.2+ | Git, `agy`, `jq`, and Python 3 | `ubuntu-latest` | -| macOS with Bash | Bash 3.2+ | Git, `agy`, `jq`, and Python 3 | `macos-latest` | -| Linux or macOS with PowerShell | PowerShell 7+ | Git and `agy` | Supported by contract, not a required CI job | - -The documentation selects a helper family from the current shell. It must not use operating-system detection or a universal launcher. - -## Helper families - -The PowerShell family adds these scripts: - -- `scripts/make-research-workspace.ps1` -- `scripts/run-agy-json.ps1` -- `scripts/extract-structured-output.ps1` -- `scripts/collect-provenance.ps1` -- `scripts/cleanup-research-workspace.ps1` -- `scripts/check-execution-scope.ps1` - -The Bash family retains its five current research helpers and adds: - -- `scripts/check-execution-scope.sh` - -The existing Bash research helpers may change where this specification adds a shared contract, such as workspace markers and cleanup checks. Existing accepted arguments must remain valid. - -### Shared command rules - -Both families must follow these rules: - -- Use the existing GNU-style long argument names, including repeated arguments and the `--` delimiter used by `run-agy-json`. -- Write machine-readable or path output to stdout. -- Write warnings, usage text, and diagnostics to stderr. -- Return zero on success and nonzero on validation, safety, parsing, or child-process failure. -- Preserve paths containing spaces and non-ASCII characters. -- Do not depend on the current working directory when resolving a script sibling or caller-supplied absolute path. -- Do not require identical diagnostic wording or identical validation error codes across helper families. -- Do require `run-agy-json` to return the exit code produced by `agy`. - -Tests must compare behavior and artifacts. They must not compare script source or internal function names. - -## Helper contracts - -### Research workspace creation - -`make-research-workspace.sh` and `make-research-workspace.ps1` accept: - -- Optional `--source-repo `. -- Zero or more `--path ` arguments. - -On success, each helper must: - -- Create a unique directory under the host temporary directory. -- Write `.offload-research-workspace` at the workspace root with the exact content `offload-research-workspace-v1` followed by a newline. -- Print only the absolute workspace path to stdout. -- If a source repository is supplied, copy each existing declared path to `repo/`. -- Warn and continue when a declared path does not exist. -- Preserve file contents and relative directory structure. - -Each helper must reject a declared path when it: - -- Is absolute or rooted. -- Resolves outside the source repository. -- Contains a parent traversal component. -- Is or contains a symbolic link, junction, or other reparse point. - -On any rejection or copy failure, the helper must remove the workspace it created and return nonzero. - -### Worker launch and output capture - -`run-agy-json.sh` and `run-agy-json.ps1` accept: - -- Required `--output `. -- Required `--error `. -- Required `--` delimiter followed by one or more `agy` arguments. - -PowerShell command expressions must quote the delimiter as `'--'`. Bare `--` is consumed by PowerShell before the script receives its arguments. The literal delimiter remains required by both helpers. See [the issue #2 fix plan](0002-powershell-launcher-delimiter.md) for the accepted command-parser regression coverage. - -Both helpers must: - -- Reject `--output` and `--output=` inside the forwarded `agy` arguments. -- Create parent directories for output and error files. -- Write `agy` stdout only to the output file. -- Write `agy` stderr only to the error file. -- Forward all worker arguments without reordering or splitting values that contain spaces. -- Return the worker exit code. - -The PowerShell helper resolves `agy` in this order: - -1. Non-empty `AGY_BIN`. -2. `Get-Command agy`. -3. `%USERPROFILE%\.local\bin\agy.exe`. - -If `AGY_BIN` is non-empty but does not resolve to an invokable file or command, the helper must fail without trying later sources. The final discovery error must name the sources it checked. - -The Bash helper keeps the equivalent existing order of `AGY_BIN`, `command -v agy`, and `$HOME/.local/bin/agy`. An invalid explicit `AGY_BIN` must also fail without fallback. - -### Structured-output extraction - -`extract-structured-output.sh` and `extract-structured-output.ps1` accept an optional `--array` followed by one or more JSON result files. - -Without `--array`, the helper emits each input file's `structured_output` as compact JSON. With `--array`, it emits one compact JSON array containing each input file's `structured_output` in argument order. - -The helper must fail when an input file is missing, contains invalid JSON, has a non-object top level, or lacks `structured_output`. It must never emit the top-level worker `response` field as part of extracted output. - -### Provenance collection - -`collect-provenance.sh` and `collect-provenance.ps1` retain the current build and validation interfaces and produce the same JSON shape. - -Both helpers must: - -- Accept JSON arrays either as inline JSON or as a path to a JSON file where the current Bash helper allows both. -- Preserve `deep_trigger` as `null` when absent or empty. -- Parse `duration_seconds` as a non-negative number. -- Validate the current allowed values for mode, profile, and final status. -- Require every current provenance field. -- Write UTF-8 JSON with a trailing newline. -- Avoid adding platform-specific fields or path normalization to the schema. - -The PowerShell implementation must use PowerShell and .NET JSON support. It must not call Python or `jq`. - -### Research workspace cleanup - -`cleanup-research-workspace.sh` and `cleanup-research-workspace.ps1` accept required `--workspace ` and `--status ` arguments. - -Before deleting content, both helpers must resolve the target to an absolute path and reject: - -- A missing or non-directory target. -- A filesystem root. -- The current user's home directory. -- The process current directory. -- A Git worktree root. -- A directory without `.offload-research-workspace` containing the exact version marker. - -For `success`, cleanup preserves only `final.md`, `provenance.json`, and the workspace marker. It removes all other children without following links out of the workspace. - -For `partial` and `failed`, cleanup validates the target and marker but preserves all contents. - -### Execution scope check - -`check-execution-scope.sh` and `check-execution-scope.ps1` run inside a Git worktree and accept: - -- One or more repeated `--owned ` arguments. -- Zero or more repeated `--frozen ` arguments. - -The helpers must use Git plumbing or machine-readable Git output rather than parsing human-formatted status columns. They must account for: - -- Modified tracked files. -- Deleted tracked files. -- Both paths involved in renames or copies. -- Untracked files that are not ignored. -- Paths containing spaces and non-ASCII characters. - -Path comparison follows Git's repository-relative path representation. A touched path passes ownership only when it exactly matches an owned file or is contained by an owned directory. A frozen path fails when that file or any path under that directory changed. - -The helper prints each unowned or frozen-path violation to stdout and returns nonzero when violations exist. It prints nothing and returns zero when the execution scope is valid. It must not modify the repository or create comparison files in the worktree. - -## Workflow documentation changes - -### Root router - -Update `SKILL.md` to: - -- Define helper selection by current shell. -- State the native Windows requirements. -- Remove POSIX-only `agy` discovery language. -- Keep the router below 500 lines. -- Keep the proactive-offer trigger and consent rules host-independent. -- Point to the mode documents for shell-specific commands. - -### Execution mode - -Update `modes/execution.md` to: - -- Provide adjacent Bash and PowerShell worker launch examples. -- Route worker calls through the matching `run-agy-json` helper. -- Replace inline `awk`, `sort`, and `comm` ownership logic with the matching `check-execution-scope` helper. -- Provide native frozen-path and gate commands for each shell where the command differs. -- Preserve worker roles, models, retry rules, gate semantics, and verification provenance. - -### Repository research mode - -Update `modes/repo-research.md` to: - -- Provide Bash and PowerShell workspace creation and worker launch examples. -- Use the matching `make-research-workspace` and `run-agy-json` helpers. -- Keep workers inside the disposable snapshot. -- Preserve the existing verification protocol against the live repository. - -### Web research mode - -Update `modes/web-research.md` to: - -- Provide Bash and PowerShell commands for workspace creation, all worker stages, structured-output extraction, provenance generation, and cleanup. -- Use `ConvertFrom-Json` and `ConvertTo-Json` or the PowerShell extractor where Bash currently uses inline `jq`. -- Preserve worker schemas, profiles, deep triggers, retry limits, partial-result behavior, and citation-audit rules. - -### README - -Update `README.md` to: - -- Add the support matrix and helper-selection rule. -- Provide installation and invocation examples for Bash and PowerShell. -- Replace POSIX-only examples in all workflows with adjacent Bash and PowerShell examples or links to the mode documents. -- Remove the Claude Code hook setup and `jq` hook requirement. -- Add the proactive-offer contract and the worked context-file example below. - -The worked example must preserve these rules from the current global `AGENTS.md`, with wording adjusted only to make the snippet self-contained: - -- Use Offload when the user asks for AGY, Gemini workers, or accepts an offer. -- Offer once before starting when implementation has at least three independently gated tasks in a clean Git repository. -- Offer once when a read-only audit or external research task requires multiple distinct work lanes. -- Count research lanes by distinct questions or evidence responsibilities, not browser tabs. -- Keep narrow factual answers, explanations, single-source lookups, and focused reviews local. -- Ask before dispatching. -- After a refusal, continue locally and do not offer again during that session. -- Let the Offload skill choose the workflow after invocation. - -Document an optional adapter contract with four requirements: - -1. Trigger only when the proactive-offer conditions hold. -2. Keep once-per-session state. -3. Ask the user before dispatching workers. -4. Fail open so a broken adapter never blocks the host's normal workflow. - -Delete `hooks/offload-ask.sh` and remove references to the `hooks/` implementation. Do not replace it with a PowerShell hook. - -### Project context - -Update `AGENTS.md` after implementation so its architecture summary uses the terms in `CONTEXT.md`, names both helper families, replaces `comm` with the execution scope check, and replaces the Claude-only hook decision with the proactive-offer contract. - -## Test strategy - -Tests must invoke scripts through their public command-line interfaces. Do not add mocks inside helper implementations. - -### Bash acceptance suite - -Extend the current Bash tests and add focused files where needed. The suite must cover: - -- Existing router and mode structure checks. -- Presence of both helper families in documentation. -- Bash syntax validation and executable bits. -- Worker launch argument forwarding and output separation using a fake `agy`. -- Explicit `AGY_BIN` precedence and invalid-value failure. -- Structured-output extraction in scalar and array modes. -- Missing, malformed, and unstructured JSON rejection. -- Scoped workspace copying, missing-path warnings, traversal rejection, and link rejection. -- Workspace marker creation. -- Provenance build and validation behavior. -- Success cleanup retention. -- Partial and failed cleanup retention. -- Refusal to clean an unmarked or unsafe directory. -- Execution scope success and violations in a temporary Git repository. -- Modified, deleted, renamed, copied, untracked, ignored, spaced, and non-ASCII path cases. - -### PowerShell acceptance suite - -Add a PowerShell suite that covers the same observable cases. It must use temporary directories and a fake `agy` command. It must run without Bash, Python, `jq`, Pester, or other downloaded test dependencies. - -The suite may use a small local assertion harness written in PowerShell. A failing assertion must return a nonzero process exit code. - -### Documentation contract checks - -Tests must fail when: - -- A mode mentions only one helper family for a required operation. -- Active documentation still requires the Claude Code hook. -- Active documentation still uses `comm` for execution verification. -- Native Windows instructions invoke Bash, Python, or `jq`. -- `SKILL.md` reaches 500 lines. -- README installation stops copying the entire skill directory. - -### CI - -Add one GitHub Actions workflow with these jobs: - -- Ubuntu Bash contract suite on `ubuntu-latest`. -- macOS Bash contract suite on `macos-latest`. -- Windows PowerShell contract suite on `windows-latest` using `pwsh`. - -Jobs must not install or call the real `agy` service. They must use local fake commands and require no credentials. - -## Implementation order - -1. Add failing contract tests for PowerShell files, workspace markers, cleanup refusal, and execution scope checks. -2. Add the PowerShell research helpers and make their tests pass. -3. Add both execution scope helpers and make their Git fixture tests pass. -4. Update the Bash workspace and cleanup helpers for the marker contract. -5. Update all mode documents and the root router. -6. Replace the vendor hook documentation with the proactive-offer contract and delete the hook implementation. -7. Update README and project context. -8. Add the three CI jobs and run every local suite available on the development host. - -Each step must preserve unrelated working-tree changes. The implementation must not normalize file modes or line endings as a side effect. - -## Acceptance criteria - -The implementation is complete when all of these statements are true: - -1. A native Windows orchestrator can follow execution, repository-research, and web-research workflows using PowerShell 7 without WSL or Git Bash. -2. Native Windows helpers do not call Bash, Python, or `jq`. -3. Bash and PowerShell helpers preserve equivalent structured output, workspace isolation, provenance, cleanup, and execution-scope behavior. -4. `AGY_BIN` works in both families and remains authoritative when set. -5. PowerShell discovery can invoke an ordinary Windows `agy` command or `%USERPROFILE%\.local\bin\agy.exe`. -6. Cleanup refuses unmarked and unsafe directories. -7. Execution verification catches unowned changes and frozen-path changes without `comm`. -8. README and every mode document state the supported shell path and contain no required vendor-specific hook. -9. The proactive-offer example preserves the accepted global `AGENTS.md` behavior. -10. Ubuntu, macOS, and Windows CI jobs pass without credentials or a real `agy` service. -11. Existing Bash acceptance behavior continues to pass. -12. `SKILL.md` remains below 500 lines. - -## Out of scope - -- Windows PowerShell 5.1. -- A universal launcher that detects the host operating system. -- A shared Python, Node.js, or compiled helper implementation. -- Maintained hooks for Claude Code, Codex, or another vendor. -- Automatic editing of a user's global context files. -- Script signing, execution-policy changes, or package installation. -- Changes to worker roles, models, schemas, retry counts, research profiles, or report classifications. -- Changes to the `agy` CLI. -- Exact diagnostic wording across Bash and PowerShell. -- Live `agy` calls in CI. -- Redesigning the execution workflow beyond portable launch and scope verification. diff --git a/docs/specs/0002-powershell-launcher-delimiter.md b/docs/specs/0002-powershell-launcher-delimiter.md deleted file mode 100644 index 4f405a3..0000000 --- a/docs/specs/0002-powershell-launcher-delimiter.md +++ /dev/null @@ -1,79 +0,0 @@ -# PowerShell launcher delimiter fix - -Status: implemented and verified - -Date: 2026-09-03 - -Issue: [#2, PowerShell launcher passthrough invocation](https://github.com/anthonyandrei/offload/issues/2) - -Related contract: [Platform-agnostic offload workflows](0001-platform-agnostic-workflows.md#worker-launch-and-output-capture) - -## Problem and evidence - -The documented PowerShell call to `run-agy-json.ps1` uses bare `--`. PowerShell consumes that token before the helper receives its arguments. The helper then rejects `-p` as an unknown launcher option. - -A local reproduction on PowerShell 7.6.4 used a child `pwsh -Command` process to execute the documented call expression. Bare `--` produced exit code 2 and `unknown launcher option: -p`. Quoted `'--'` passed argument validation and reached executable resolution. An intentionally invalid `AGY_BIN` prevented worker launch in both probes. This confirmed parsing behavior, but did not verify end-to-end argument forwarding. - -Eight launcher examples contain the faulty syntax: four in `modes/execution.md`, one in `modes/repo-research.md`, and three in `modes/web-research.md`. - -The existing PowerShell test runner supplies arguments through `ProcessStartInfo.ArgumentList` to `pwsh -File`. That path bypasses parsing of a PowerShell call expression. Its fake worker also joins arguments into one string, so the space-preservation assertion cannot distinguish one argument from multiple arguments with the same joined text. - -## Accepted decisions - -1. Quoted `'--'` is the supported delimiter spelling in PowerShell command expressions. Keep the helper's requirement for a literal delimiter and its rejection of worker flags supplied without one. -2. A regression test that executes the actual call expression through `pwsh -Command` satisfies the interactive parsing requirement. Preserve the existing `-File` coverage. Verify argument boundaries using a JSON array captured by a fake worker. - -Both decisions were explicitly accepted by the user. They clarify the existing helper contract and require no new architectural dependency or ADR. - -## User stories - -1. As a PowerShell orchestrator, I want the documented worker command to run after substituting its placeholders, so that I can follow any offload workflow without discovering a quoting workaround. -2. As a caller, I want prompts and paths containing spaces to reach the worker intact, so that my assignment retains its intended values. -3. As a maintainer, I want tests to exercise the documented command syntax and detect split arguments, so that a passing suite provides evidence for the actual invocation path. -4. As a caller, I want a missing delimiter to fail before launching a worker, so that malformed launcher arguments do not run an unintended assignment. - -## Implementation plan - -### Correct the public instructions - -- Change the delimiter to `'--'` in all eight PowerShell launcher examples across the three mode documents. -- Update `Show-Usage` in `scripts/run-agy-json.ps1` to show the quoted delimiter. Add a short explanation of PowerShell consuming the bare token where it helps callers use the helper. -- Keep the clarification already recorded in specification 0001 and the launcher delimiter definition in `CONTEXT.md`. -- Preserve the required delimiter, forwarded `--output` rejection, and Bash invocation syntax. - -### Strengthen the existing PowerShell acceptance suite - -Work in `tests/test_research_helpers.ps1`. Keep the public process runner and the existing `Invoke-Helper` path for `pwsh -File`. - -- Make the fake worker record its received arguments as a JSON array. Replace joined-string matching with argument-count and ordinal, element-by-element comparisons. Do not flatten either array for comparison. -- Add a child process that runs a PowerShell command expression through `pwsh -NoProfile -NonInteractive -Command`. The expression must call the real helper with the call operator, quoted `'--'`, and worker arguments beginning with `-p`. Passing the whole expression through `ProcessStartInfo.ArgumentList` is acceptable because PowerShell still parses that expression. -- Supply temporary paths and fixture values safely, for example through the child's environment. Do not interpolate unescaped paths or prompts into executable command text. Use a fake worker selected by `AGY_BIN`; no real worker or network access is needed. -- Include output and error paths containing spaces, a prompt containing spaces, and a forwarded path value containing spaces. Compare the full ordered worker argument array. The launcher delimiter and launcher output/error options must not appear in that array. -- Verify worker stdout and stderr land in their respective files, and that the child process reports the helper's exit code. Explicitly propagate `$LASTEXITCODE` from the command expression, including for a nonzero fake-worker exit. -- Add negative command-expression cases for bare `--` and an omitted delimiter. Both must return nonzero and leave the fake worker unlaunched. Use fresh capture paths or a launch marker for each case so previous artifacts cannot satisfy this assertion. Do not require exact diagnostic wording. - -### Verify and review - -Run `pwsh -NoProfile -File tests/test_research_helpers.ps1`. The existing Windows CI job already runs this suite; no new test dependency or CI job is required. - -Review all PowerShell launcher examples and the usage text for the quoted delimiter. Confirm that Bash examples retain their existing syntax. Run the existing research-modes suite where Bash is available, or rely on the existing Ubuntu and macOS CI jobs for that check. Inspect the final diff for scope and whitespace errors. - -## Acceptance criteria - -1. Every PowerShell launcher example and the PowerShell usage message shows `'--'`. -2. A documented-style call expression parsed by PowerShell launches the fake worker successfully. -3. The captured JSON array matches the expected worker arguments exactly, including order, count, and values containing spaces. -4. Output/error paths containing spaces work, stdout and stderr remain separated, and worker exit codes propagate. -5. Bare and omitted delimiters fail before worker launch. -6. Existing `-File` tests remain and use argument-boundary assertions for forwarding. Existing launcher rejection and discovery checks continue to pass. -7. The PowerShell acceptance suite passes without credentials, a real `agy` service, or downloaded test dependencies. Existing CI remains green. - -The quoted call already passes launcher parsing before this fix. Its new regression coverage may therefore pass immediately; it protects the accepted invocation contract. The documentation correction resolves the reported failure. Do not change parser behavior merely to force a red-to-green test transition. - -## Out of scope - -Automatic delimiter inference, accepting the bare delimiter form as valid, launcher API redesign, executable discovery changes, Bash helper changes, new dependencies, and expanded platform or PowerShell-version matrices are outside this fix. - -## Completion state - -Implementation is complete. The eight PowerShell examples, launcher usage text, and regression coverage were updated. The PowerShell acceptance suite passes; the Bash suite could not run in this Windows environment because Bash/WSL is unavailable. diff --git a/docs/specs/0003-gemini-model-routing.md b/docs/specs/0003-gemini-model-routing.md deleted file mode 100644 index 193ef37..0000000 --- a/docs/specs/0003-gemini-model-routing.md +++ /dev/null @@ -1,213 +0,0 @@ ---- -status: ready-for-agent -labels: - - ready-for-agent -date: 2026-09-03 ---- - -# Gemini model routing - -This specification implements the decisions in [ADR 0005](../adr/0005-bound-model-routing-to-gemini-and-explicit-rules.md). It is ready for implementation. No launcher or workflow behavior changed during specification work. - -Related material: - -- [Domain terms](../../CONTEXT.md) -- [Model research and evidence limits](../research/2026-09-03-model-routing.md) -- [Shell platform contract](0001-platform-agnostic-workflows.md) -- [PowerShell delimiter contract](0002-powershell-launcher-delimiter.md) - -## Problem and intended result - -Offload assigns Gemini 3.7 Flash through model IDs repeated in workflow instructions. Its launchers forward the caller's model arguments without enforcing a shared routing policy. Changing a role's model therefore requires coordinated edits, and callers can select models outside the intended limits. - -Move the baseline to Gemini 3.8 Flash and make one shared policy authoritative for every worker role in every mode. Both shell families must resolve and validate selections before launching AGY. Keep routing explainable through role defaults and explicit quality escalation rules. - -The objective is verified task success first, followed by elapsed time and quota consumption. The initial defaults are an approved baseline, not a claim that they are optimal for every task. Record enough evidence to evaluate later changes. - -## User stories - -1. As an offload user, I want Gemini workers for delegated work, so that delegation uses the usage allowance I prefer. -2. As an offload user, I want reasoning effort capped at high, so that neither normal work nor recovery exceeds my chosen limit. -3. As an orchestrator, I want a default model for each worker role, so that the same assignment follows the same routing rule across modes. -4. As an orchestrator, I want the approved 3.8 Flash baseline, so that new work no longer depends on the older default. -5. As a maintainer, I want one model policy shared across platforms, so that changing a role does not leave conflicting workflow instructions. -6. As an orchestrator, I want invalid routing requests rejected before dispatch, so that missing settings cannot silently select an unintended model. -7. As an orchestrator, I want model escalation only after a verified quality failure and with supporting evidence, so that a larger model name does not substitute for demonstrated suitability. -8. As an offload user, I want at most one retry for each assignment, so that repeated failures cannot create an open-ended run. -9. As an orchestrator, I want timeouts and tool failures distinguished from quality failures, so that recovery addresses the failure that occurred. -10. As an offload user, I want unfinished work returned immediately when Gemini quota runs out, so that I can decide how to continue. -11. As an orchestrator, I want completed work and verification requirements preserved during handoff, so that recovery does not lose useful results or accept unchecked changes. -12. As a maintainer, I want verified outcomes, elapsed time, and available usage evidence recorded per attempt, so that later model choices can be compared fairly. -13. As a maintainer, I want the migration checked through the actual launchers and a small live smoke test, so that the new baseline is usable without a full comparison against 3.7. -14. As a caller, I want existing prompt forwarding, output capture, isolation, and verification to keep working, so that model routing does not change the assignment's meaning or safeguards. - -## Accepted routing policy - -The first policy revision assigns these defaults: - -| Role | Default model | Effort | -| --- | --- | --- | -| scout | `gemini-3.8-flash-low` | low | -| gate-author | `gemini-3.8-flash-high` | high | -| implementer | `gemini-3.8-flash-high` | high | -| reviewer | `gemini-3.8-flash-high` | high | -| researcher | `gemini-3.8-flash-high` | high | -| synthesizer | `gemini-3.8-flash-high` | high | -| auditor | `gemini-3.8-flash-high` | high | - -The researcher role has the same default in repository and web research. Mode selection, web research profiles, worker permissions, and assignment scope remain separate from model selection. - -Only Gemini models are eligible. Permitted effort levels are low, medium, and high, with high as the ceiling. The first revision has no configured escalation targets. Existing evidence does not justify assigning Pro or medium effort to a default role, or selecting an automatic escalation target. - -Future promotions require repeated representative offload runs using the same inputs and verification gates. Compare verified success before considering time or usage. Published benchmarks identify candidates; they do not establish local superiority. A future promotion proposal must define its cases and repeat count before evaluation, then attach the results and limitations to the policy change. - -The initial 3.7-to-3.8 migration is the accepted exception. It needs the integration checks below, not a full comparative benchmark. Neither published coding results nor the migration smoke test establishes lower AGY quota consumption. - -## Implementation decisions - -### Shared policy - -Add one repository-root `model-policy.json`. Resolve it relative to the installed helper location, never the caller's current directory. Include it in installation and manual-copy instructions. No environment override, per-mode policy file, or caller-supplied policy path is needed. - -The policy has these fields: - -| Field | Contract | -| --- | --- | -| `schema_version` | Integer `1`; reject unsupported versions. | -| `policy_revision` | Nonempty revision identifier, initially `2026-09-03.1`; change it whenever routing behavior changes. | -| `max_effort` | `high` for this release. | -| `max_retries_per_worker` | Integer `1`. | -| `quota_action` | `handoff`. | -| `roles` | Object containing exactly the seven roles above. | -| `roles..default_model` | Complete AGY model ID, including its effort suffix. | -| `roles..quality_escalation` | Initially `null` for every role. A configured entry contains `model` and `evidence_path`. | - -The model ID is the source of effort information. Do not store a second editable effort value for each selection. Validate the Gemini prefix and a terminal `low`, `medium`, or `high` effort suffix. Reject empty IDs, non-Gemini IDs, unknown effort suffixes, and selections above the ceiling. Actual availability also requires the AGY preflight below. - -A non-null escalation entry must name a different eligible model and a nonempty repository-relative path to an existing evaluation document inside the skill directory. The document must identify the role, baseline, candidate, comparison method, results, and promotion decision. Helpers validate the entry and path; the maintainer reviewing a promotion validates the quality of its evidence. A file's existence does not prove superiority. - -Both shell families validate the whole policy before dispatch, including unused roles and escalation entries. Missing or malformed JSON, missing roles, invalid types or values, and unsupported schema versions fail closed. Use existing POSIX dependencies and PowerShell's native JSON support. Add no Windows dependency on Bash, jq, or Python. - -### Launcher contract - -Extend `scripts/run-agy-json.sh` and `scripts/run-agy-json.ps1` with two options before the required delimiter: - -- `--role ` is required and selects a policy role. -- `--route ` is optional, defaults to `default`, and accepts `default` or `quality-retry`. - -The default route resolves `default_model`. The quality-retry route resolves that role's configured escalation model. If no target exists, reject the quality-retry request before AGY starts. Never infer a Pro target or silently replace the requested route with the default. An allowed same-model retry explicitly uses the default route. - -The launcher injects exactly one `--model` selection from the policy. Reject caller-supplied `--model` and `--effort` options after the delimiter, including equals forms. Current AGY help exposes those long options without short aliases. Preserve ordinary prompt text containing those strings. Option validation must distinguish an option from the value of an AGY prompt or other value-taking option. Do not search prompt substrings or flatten argument arrays. - -Missing or duplicate routing options, unknown roles or routes, invalid policy, and attempted model overrides return an argument/configuration error before launching a worker. Use exit code 2 and an actionable stderr diagnostic. The missing-role diagnostic should direct old callers to supply a role and remove their model flag. - -Preserve executable resolution through `AGY_BIN`, PATH, and the existing user-local fallback. An invalid explicit `AGY_BIN` still fails without trying another binary. Preserve stdout/stderr file capture, exact worker exit codes, prompt and path argument boundaries, and forwarded `--output` rejection. PowerShell command expressions must continue to use quoted `'--'` as specified in specification 0002. - -Do not add an independent `--effort` argument. The selected AGY model ID already encodes effort. Do not introduce a custom model override or bypass option. - -The launcher enforces the selection boundary. It does not judge task quality, authorize a retry, or persist a global retry counter. Those responsibilities remain with the orchestrator following the shared rules. Direct AGY invocation can bypass a helper, so this is a workflow contract rather than process containment. - -### Workflow integration and preflight - -Update the root router, all three mode documents, README, and AGENTS.md to use the shared policy. Active dispatch examples supply roles and omit literal model IDs. Give the root router one shared routing and recovery section; mode documents refer to it and retain their existing mode-specific steps. Keep the root skill below 500 lines. - -Before the first worker in a run, the orchestrator reads the policy and checks the selected defaults against the available Gemini IDs reported by the resolved AGY installation. If a required model is absent or availability cannot be established, report the blocked dispatch and return the affected work. Do not silently downgrade to 3.7, use AGY's default, or pick a similarly named model. Check an escalation model before using it too. Avoid repeating catalog discovery for every worker in the same run unless AGY reports that availability changed. - -Replace every active 3.7 default, including command examples and current role summaries. Preserve historical research, smoke results, and completed specifications as records of what ran. Link current model summaries to the policy instead of maintaining another editable routing table. This specification and the accepted ADR record the initial revision. - -Maintain the existing 20-minute worker timeout, clean-repository precondition for writing workflows, disposable research workspaces, execution scope checks, frozen paths, gates, review quote validation, and citation auditing. Model selection does not weaken any of them. - -## Recovery and retry accounting - -A worker means one logical assignment, not one process invocation. Track a stable worker ID across attempts. Attempt 1 is the initial call; attempt 2 is its only possible retry. A new process name, model, conversation, or revision prompt does not reset the count. A genuinely separate assignment has its own ID. - -Only a completed response rejected by the applicable verification process counts as a quality failure. Examples include failing implementation gates, invalid review evidence, and unsupported synthesis claims. A reported worker `SUCCESS` or exit code zero does not establish verified success. A crash, timeout, or response that cannot be parsed is an operational failure rather than evidence that a different model would do better. - -| Observed result | Required action | -| --- | --- | -| Verified success | Accept according to the mode's existing verification contract. No retry. | -| Quality failure, retry remains, and the mode permits correction | Retry once with concrete verification feedback. Use `quality-retry` only when that role has an evidence-backed target; otherwise use the default model. | -| Quality failure after the retry, or the mode requires immediate fallback | Stop retrying. Follow that mode's halt, partial-result, or orchestrator fallback path. | -| Timeout, process/tool error, or unusable response | Follow the mode's existing recovery rule, with at most one same-model retry where it permits one. No model escalation. | -| Unknown failure | Record uncertainty and follow the operational-failure path. Do not infer a quality problem or quota exhaustion. | -| Explicit Gemini quota exhaustion | Stop scheduling workers and immediately hand unfinished work back to the calling orchestrator. No automatic retry, wait for reset, model switch, or paid-credit activation. | - -Quota classification requires explicit AGY quota evidence from structured output or a diagnostic. A generic timeout, HTTP throttling message, or tool failure alone is insufficient. Classify quota before the other recovery rules when the evidence is present. - -The one-retry ceiling does not grant a retry in stages that currently fall back or return partial immediately. Preserve these mode distinctions: - -- Execution keeps its scout and gate-author fallback, implementer gate/scope retry (consuming normalized `scripts/execute-gate.sh` / `scripts/execute-gate.ps1` outcomes where gate exit 126 or 127 is `unrunnable` without quality retry), and direct orchestrator review fallback. -- Repository research keeps its bounded same-model operational retry and subsequent orchestrator fallback. -- Web research keeps its minimum-angle requirement and partial-result behavior for failed mandatory synthesis or audit stages. Its allowed synthesis revision uses the synthesizer's second attempt; the final audit uses the auditor's second attempt. Earlier retries consume those same budgets. Exhaustion returns a partial result rather than creating a new assignment to repeat the stage. - -An escalation consumes attempt 2. No third invocation is permitted for the same logical assignment, even when the second failure has a different cause. - -On quota handoff, preserve completed artifacts and list verified, unverified, failed, pending, and still-running assignments. Include process or job references and output paths for workers already running. Do not wait for sibling workers to finish before reporting the handoff or schedule replacement workers. The calling orchestrator takes ownership of any running work. Outputs recovered later still need the original verification. Keep the existing worker timeout bound and incomplete-work cleanup rules. - -## Outcome records and reporting - -Maintain a `routing-outcomes.json` artifact in each run's existing scratch workspace. The orchestrator owns it and updates it after dispatch and verification. Machine gate executions route through the shared shell-native gate execution helper (`scripts/execute-gate.sh` or `scripts/execute-gate.ps1`), preserving the command, exit code, and diagnostic evidence in `evidence_paths`. This is a bounded run record, not a new service or persistent scheduler. Use a top-level `schema_version` of 1 and an `attempts` array. - -Each attempt records: - -| Field | Contract | -| --- | --- | -| `worker_id`, `role`, `mode` | Stable assignment identity and existing mode name. | -| `attempt` | Integer 1 or 2. | -| `policy_revision`, `route`, `model`, `effort` | Resolved selection; derive effort from the model ID. | -| `reason` | Initial default or the observed failure and recovery decision that authorized attempt 2. | -| `started_at`, `ended_at`, `duration_seconds` | UTC timestamps and observed elapsed time; ending values are null while running. | -| `exit_code` | Actual process exit code, or null when unavailable. | -| `state` | `running`, `completed`, `failed`, or `interrupted`. This is process state, not a quality verdict. | -| `failure_class` | `none`, `quality`, `timeout`, `tool_error`, `quota`, `unrunnable`, or `unknown`. A gate exit 126/127 is `unrunnable` and does not consume a retry. | -| `verification` | `pending`, `passed`, `failed`, or `not_performed`, using the applicable mode's checks. | -| `evidence_paths` | Output, error, gate, review, or audit artifact references that support the outcome. | -| `usage` | Null when unavailable; otherwise source-attributed reported measurements with explicit units. | - -Pending assignments that never dispatched belong in the final handoff/report, not in fabricated attempt records. Failed dispatches still belong in the report with their configuration or availability diagnostics. - -The retry ceiling is per logical worker: `(worker_id, attempt)` pairs are unique, each worker has at most two attempts, and attempt 2 reuses the same stable `worker_id`. An explicit `accepted_attempt` must resolve to that same worker's existing verified artifact; a newer or wildcard artifact is never selected implicitly. - -Record tokens, elapsed time, quota counters, or other usage measurements only when actually observed. Token counts and wall time are not interchangeable with AGY quota consumption. Missing usage stays null. Do not copy secrets or entire prompts into the routing record. - -The final report links the run record and summarizes selected models, verification results, retries, and any handoff. Preserve the distinction between proven, judged, verified, audited, and worker-claimed results. In web research, add the corresponding attempt record as an optional `routing` object in each provenance worker entry. Extend both provenance validators to validate present routing objects while accepting historical entries without them. Do not replace the existing provenance schema or manufacture missing historical measurements. - -## Verification and acceptance criteria - -Use the existing public launcher tests with a fake AGY selected through `AGY_BIN`. Exercise shell processes and captured argument arrays rather than mocking JSON readers or internal policy-resolution functions. For invalid-policy cases, copy the helper family and policy into a disposable fixture directory, then alter the fixture policy. No production-only test override is needed. - -Required automated coverage: - -1. Every role resolves to the exact initial model on Bash and PowerShell. Researcher behavior is identical across research modes. -2. The launcher forwards exactly one policy-selected model and preserves all other supported arguments, including prompts and paths with spaces. Prompt values containing model-option text remain intact. -3. Missing, malformed, or unsupported policies, invalid role maps, non-Gemini IDs, effort violations, unknown roles/routes, duplicate routing arguments, and caller model/effort overrides fail before the fake worker starts. -4. A null escalation target rejects a quality-retry request. A fixture policy with a valid evidence-backed target dispatches that target. Missing or escaping evidence paths and identical default/target models fail validation. -5. Existing executable-resolution, output capture, stderr capture, nonzero exit, required delimiter, and forwarded-output rejection tests keep passing. PowerShell retains both `-File` and actual command-expression coverage with quoted `'--'`. -6. Outcome/provenance validation accepts valid routing records and legacy workers without routing data, while rejecting invalid attempt numbers, role/effort values, and negative durations. Pending ending values and unavailable usage remain valid. -7. Static workflow checks require role-based dispatch and shared recovery references in every mode. They reject active 3.7 dispatch defaults and preserve the router size limit without treating historical results as current policy. - -Review the documented recovery paths against these cases: implementation quality failure then failed retry; timeout then quality failure on attempt 2; reviewer fallback; synthesis revision followed by final audit; an exhausted synthesis/audit retry budget; and quota exhaustion while another worker is running. For each, verify the described invocation count, selection, artifact handling, and final status. These are orchestration-instruction checks, not claims that the launcher can enforce an agent's reasoning. - -Run the existing Bash research-mode and execution-scope suites on Ubuntu and macOS, and the PowerShell research-helper and execution-scope suites on Windows. Keep the existing CI jobs and test frameworks. Wire added coverage into those suites rather than introducing a separate runtime or CI platform. - -After automated checks pass, perform a small live smoke check through the real launcher: - -- A low-effort scout discovers known files in a disposable fixture. -- A high-effort implementer makes a tiny owned-file change in a clean disposable Git repository, then passes its scope check and deterministic gate. -- A high-effort researcher reads a scoped fixture and returns structured findings that the orchestrator checks against it. - -These checks cover the two selected model IDs and both plan and accept-edits invocation paths. Fake-worker tests cover every role and both shells. Use the existing worker timeout and recovery budget, record live attempts and outcomes, and report the platform used. Do not use the production repository as the mutation fixture. A failed or quota-blocked smoke check leaves migration verification incomplete; it does not authorize a fallback model or a claim of successful migration. - -Completion requires the shared policy, both launchers, active workflow instructions, outcome recording, provenance compatibility, passing platform contract tests, and successful live smoke evidence. The implementation report must identify anything that could not be verified. No comparative claim about optimal effort, Pro suitability, or quota savings follows from passing these checks. - -## Out of scope - -- Implementation work during this specification task. -- Non-Gemini workers or reasoning effort above high. -- Automatic selection based on free-form task classification, learned routing, or per-request experimentation. -- Initial medium-effort or Pro defaults, or unevaluated escalation targets. -- A full 3.7-versus-3.8 benchmark, exhaustive role benchmark suite, or fixed repeat count for future promotions. -- Automatic quota waiting, paid-credit activation, quota-driven model switching, or account management. -- A new orchestration engine, persistent retry scheduler, telemetry dashboard, or quota estimator. -- Changes to mode inference, research profiles, permission models, isolation, verification standards, or the worker timeout. -- Rewriting historical evidence to use current model names, deploying an installed skill update, or publishing a release. diff --git a/docs/specs/0004-claude-adapter.md b/docs/specs/0004-claude-adapter.md deleted file mode 100644 index f90ca66..0000000 --- a/docs/specs/0004-claude-adapter.md +++ /dev/null @@ -1,92 +0,0 @@ -# Claude adapter contract - -The Claude adapter is a vendor-neutral worker boundary for hosts that provide the -Claude Code CLI (`claude`). It conforms to the worker adapter contract -(`docs/adapter-contract.md`) and has PowerShell and Bash entry points: - -```text -scripts/run-claude-json.ps1 --operation catalog --request -scripts/run-claude-json.ps1 --operation launch --request --output --error -- - -bash scripts/run-claude-json.sh --operation catalog --request -bash scripts/run-claude-json.sh --operation launch --request --output --error -- -``` - -The orchestrator owns assignment constraints, execution-scope verification, -final acceptance gates, resource ledgers, and lifecycle management. The adapter -owns Claude Code command syntax and response normalization. - -## Operations - -### Catalog discovery - -`--operation catalog --request ` verifies that the Claude CLI is -available and advertises structured output support via `claude --help`. It reads -model metadata from `CLAUDE_MODEL_CATALOG` or `OFFLOAD_ADAPTER_CATALOG` (or -host-provided model list) and outputs a protocol version 1 catalog JSON document -to standard output: - -```json -{ - "protocol_version": 1, - "adapter": "claude", - "adapter_revision": "claude-1", - "vendor": "anthropic", - "catalog_revision": "catalog-revision-id", - "models": [ - { - "id": "claude-3-5-sonnet-20241022", - "family_hint": "sonnet", - "available": true, - "quota_available": true, - "supported_efforts": ["low", "medium", "high"], - "capabilities": ["structured-output"], - "scores": { "fast": 2, "balanced": 1, "deep": 2 } - } - ] -} -``` - -If the CLI or catalog is unavailable, the adapter fails closed and exits -nonzero. - -### Worker launch - -`--operation launch --request --output --error -- ` -launches Claude Code with the exact model selected by the orchestrator. The -adapter parses worker arguments following the `--` delimiter (such as -`--prompt`, `--cd`, `--cancel-file`, `--timeout-seconds`, `--allowedTools`, and -`--disallowedTools`), preserving argument and path boundaries when values -contain spaces. - -The adapter enforces isolated execution: -- The working directory must contain an `.offload-execution-workspace` or - `.offload-research-workspace` marker. Unmarked workspaces fail closed. -- Nested dispatch tools `Task` and `Agent` are automatically added to - `--disallowedTools`. -- `--permission-mode` defaults to `acceptEdits`; `bypassPermissions` is rejected. -- Structured JSON output is requested via `-p --output-format json`. - -The normalized output written to `` follows the launcher result -contract: - -```json -{ - "status": "success", - "response": "ok", - "session_id": "s1", - "structured_output": { ... }, - "model_id": "claude-3-5-sonnet-20241022" -} -``` - -## Security and responsibility boundary - -The orchestrator owns assignment verification, execution scope checks, final -gates, and resource ledgers. The adapter does not run adapter-owned scope checks -or acceptance gates, nor does it generate competing private ledger schemas. - -Cancellation (signal or cancel file) terminates the process and exits with code -130. Timeout terminates the process and exits with code 124. Quota exhaustion -exits with code 75 for caller handoff. Malformed output exits with code 1, -preserving the raw output for diagnosis. diff --git a/docs/worker-adapter-contract.md b/docs/worker-adapter-contract.md deleted file mode 100644 index c3883f3..0000000 --- a/docs/worker-adapter-contract.md +++ /dev/null @@ -1,128 +0,0 @@ -# Worker adapter contract - -This document defines the boundary between the `orchestrator` and a vendor -`adapter`. An adapter runs one bounded `worker` assignment. It does not decide -the assignment, verify the result, or own cleanup outside the resources it -reports. - -The contract is versioned independently from a vendor command line. Vendor -syntax, output parsing, process handles, capability catalogs, and model -catalogs stay inside the adapter. The orchestrator only consumes the records -defined here and runs the `execution scope check` and other existing gates. - -## Assignment - -The orchestrator gives the adapter an immutable JSON assignment: - -```json -{ - "contract_version": 1, - "assignment_id": "task-17", - "request": { "prompt": "..." }, - "constraints": { - "tools": ["read", "write"], - "permissions": ["repo.read", "repo.write"], - "owned_paths": ["src"], - "frozen_paths": ["tests"], - "worktree": { "id": "worktree-17", "path": "..." }, - "artifact_root": "...", - "cleanup_resource_ids": ["process:17", "worktree:17"] - } -} -``` - -`assignment_id` must be stable across retries. `owned_paths` and -`frozen_paths` are repository-relative paths. The adapter may use fewer tools, -permissions, or paths than the assignment grants, but it cannot widen them. -The worktree and artifact root are exact identities. A result that reports a -different worktree, artifact root, or cleanup resource is rejected. - -The adapter must treat `constraints` as read-only input. It must not turn a -missing permission into an allowed permission, reinterpret a path as a parent -directory, or transfer cleanup to the orchestrator for an unreported resource. - -## Adapter operations - -Every adapter exposes these operations, whether as functions, a command -protocol, or a host-language object: - -| Operation | Required behavior | -| --- | --- | -| `discover-capabilities` | Return the adapter's available tools and permissions, without changing the assignment. | -| `discover-models` | Return model identifiers and capabilities known by this vendor. The adapter owns catalog syntax and authentication. | -| `launch` | Start exactly one worker for the assignment and return a process/job identity plus the worktree and artifact-root identities. | -| `wait` | Wait for completion up to the requested timeout and return a lifecycle state. | -| `cancel` | Request cancellation for the reported process/job identity and return its final lifecycle state. | -| `exit-status` | Return the process exit code or signal, including a still-running state when no exit exists. | -| `capture-result` | Parse the worker output into the normalized result below. Raw vendor output never crosses this boundary. | -| `ownership` | Return the process/job, worktree, and artifact resources the adapter created and can identify. | - -`launch` may not widen the static assignment. `wait`, `cancel`, and -`exit-status` may only address the identity returned by `launch`. The adapter -reports ownership; the orchestrator decides whether cleanup is safe. This -prevents an adapter from deleting a resource outside its ownership record. - -## Normalized result - -`capture-result` returns this shape: - -```json -{ - "contract_version": 1, - "assignment_id": "task-17", - "status": "succeeded", - "artifacts": [ - { "path": "...", "kind": "worker-output", "sha256": "...", "verified": false } - ], - "resources": [ - { "type": "process", "id": "process:17" }, - { "type": "worktree", "id": "worktree:17", "path": "..." } - ], - "ownership": { "resource_ids": ["process:17", "worktree:17"] }, - "constraint_snapshot": { - "tools": ["read"], - "permissions": ["repo.read"], - "owned_paths": ["src"], - "frozen_paths": ["tests"], - "worktree": { "id": "worktree-17", "path": "..." }, - "artifact_root": "...", - "cleanup_resource_ids": ["process:17", "worktree:17"] - }, - "model_selection": { - "provider": "vendor-name", - "model_id": "vendor-model-id", - "selection_reason": "matched required capability" - }, - "exit": { "code": 0, "signal": null }, - "publication": { "status": "unpublished" } -} -``` - -`status` is one of `succeeded`, `failed`, `cancelled`, or `malformed`. -`malformed` describes a worker response that the adapter could classify. An -unparseable adapter result is a contract failure instead. - -The adapter must keep every artifact below `artifact_root`, report every -resource in `ownership.resource_ids`, and set `verified` to `false`. -`publication.status` must be `unpublished`. Verification, publication, and -the final `accepted_attempt` belong to the orchestrator after the -`execution scope check` and gate commands pass. - -The normalized result always carries model-selection metadata. The -`provider`, model identifier, and selection reason are opaque to the -orchestrator. The orchestrator may compare them with its own policy, but it -does not parse vendor model catalogs. - -## Reference adapter - -The repository includes a reference adapter and vendor-neutral launcher path. -On PowerShell it uses [`scripts/run-agy-json.ps1`](../scripts/run-agy-json.ps1); -on POSIX hosts it uses [`scripts/run-agy-json.sh`](../scripts/run-agy-json.sh). -The filenames preserve compatibility with existing installations, but the -launcher accepts a configured adapter and the catalog protocol is provider -neutral. Each adapter keeps its command syntax and catalog parsing behind the -adapter boundary, then emits the same assignment and normalized-result -records. - -`grill-with-docs` and other host skills should depend only on this contract. -They must not contain adapter names, vendor commands, or vendor model names. diff --git a/model-policy.json b/model-policy.json deleted file mode 100644 index 3b5ad18..0000000 --- a/model-policy.json +++ /dev/null @@ -1,51 +0,0 @@ -{ - "schema_version": 2, - "policy_revision": "2026-09-04.1", - "max_effort": "high", - "max_retries_per_worker": 1, - "quota_action": "handoff", - "capacity_estimation": { - "version": 1, - "assignment_units": 1, - "verification_units": 1, - "retry_units": 1, - "usage_freshness_seconds": 300 - }, - "roles": { - "scout": { - "preference": "fast", - "effort": "low", - "required_capabilities": [] - }, - "gate-author": { - "preference": "balanced", - "effort": "high", - "required_capabilities": [] - }, - "implementer": { - "preference": "balanced", - "effort": "high", - "required_capabilities": [] - }, - "reviewer": { - "preference": "deep", - "effort": "high", - "required_capabilities": [] - }, - "researcher": { - "preference": "balanced", - "effort": "high", - "required_capabilities": [] - }, - "synthesizer": { - "preference": "deep", - "effort": "high", - "required_capabilities": [] - }, - "auditor": { - "preference": "deep", - "effort": "high", - "required_capabilities": [] - } - } -} diff --git a/modes/execution.md b/modes/execution.md deleted file mode 100644 index 5a2f196..0000000 --- a/modes/execution.md +++ /dev/null @@ -1,471 +0,0 @@ -# Execution mode - -Dispatches configured workers to implement file and code changes across independent gated tasks through isolated workspaces. - -## Preconditions and helper selection - -Select the helper family matching your current host shell: - -- **POSIX shells (Bash 3.2+)**: Use `scripts/dispatch-worker.sh`, `scripts/run-agy-json.sh`, `scripts/check-execution-scope.sh`, `scripts/execute-gate.sh`, and `scripts/execution-workspace.sh`. Requires Git, `jq`, Python 3, and the configured adapter's executable. -- **PowerShell (PowerShell 7+)**: Use `scripts/dispatch-worker.ps1`, `scripts/run-agy-json.ps1`, `scripts/check-execution-scope.ps1`, `scripts/execute-gate.ps1`, and `scripts/execution-workspace.ps1`. Native Windows orchestrators require only PowerShell 7 (`pwsh`), Git, and the configured adapter. Windows workflows do not require Bash, WSL, Git Bash, Python, or `jq`. - -Check these before dispatching writing tasks: - -1. **The configured adapter is available.** Verify it through `run-agy-json` and require a protocol-2 catalog with verified access and capacity. -2. **Target is a git repository.** Run `git rev-parse --is-inside-work-tree`. -3. **Working tree is clean.** Run `git status --porcelain`. A clean tree is required to track edits, isolate changes, and roll back failed tasks. -4. **Record baseline revision.** Record the caller repository baseline before creating workspaces: - - Bash: `BASELINE=$(git rev-parse HEAD)` - - PowerShell: `$Baseline = (git rev-parse HEAD).Trim()` -5. **Model policy and preflight check.** Complete the shared preflight model availability check described in [`SKILL.md`](../SKILL.md) before dispatching the first worker. All workers route through `model-policy.json`. -6. **Workspace isolation principle.** Writing workers are never dispatched directly into the caller's main checkout (``). All candidate mutations occur in isolated candidate worktrees created at the recorded baseline revision via `execution-workspace create`. -7. **Orchestrator-owned admission.** Route every worker launch through `dispatch-worker` with a dispatch ledger and explicit `--max-depth`, `--max-width`, `--max-timeout-seconds`, and `--max-resource-units` on the root assignment. The dispatcher creates the worktree and invokes the launcher. A worker's structured request for more work remains data until the orchestrator deliberately admits it as a new bounded assignment. - -Every execution dispatch supplies the shared lifecycle metadata to `run-agy-json`: `--assignment-id`, `--attempt`, `--mode execution`, `--verification-baseline`, `--resource-ledger`, and a distinct `--lifecycle` path. The launcher records the common state machine, waits for the worker to exit before cleanup, and records the exit result. Timeout and cancellation terminate the worker before cleanup; quota exhaustion hands off unfinished work immediately. Retries and resume read the resource ledger and preserve the pinned assignment, model, effort, verification baseline, and attempt limit. - -## Roles and models - -Workers are admitted by role using `dispatch-worker` with `--role ` and a bounded budget. The dispatcher invokes `run-agy-json`, which resolves models dynamically from `model-policy.json`. Do not pass `--model` or `--effort` directly. Refer to [`SKILL.md`](../SKILL.md) for the shared model routing, preflight, and recovery contract. - -The command examples below show adapter arguments passed after the dispatcher's `--` delimiter. In a real run, put the state path, assignment identity, parent identity when applicable, source revision, owned and frozen paths, output and error paths, workspace path, budget, and root limits on the `dispatch-worker` invocation. Do not invoke `run-agy-json` directly for an execution assignment. - -The examples use one assignment per ledger. For a parallel wave, share the ledger and set its root child-width and total resource limits to cover the whole wave. - -| Role | Wave | Preference | Effort | Mode | Job | -|---|---|---|---|---|---| -| scout | 1 | fast | low | `plan` | Report repository-relative file paths a task touches. | -| gate-author | 2 | balanced | high | `accept-edits` | Author an executable test file from acceptance criteria. | -| implementer | 3 | balanced | high | `accept-edits` | Implement the task within owned files in candidate workspace. | -| reviewer | 4 | deep | high | `plan` | Evaluate the recorded review artifact against criteria for diff-gated tasks. | - -`--mode plan` is a version-sensitive behavioral hint, not a write barrier. On `agy 1.1.25`, the compatibility probe blocked the tested direct write outside the permitted artifact area, but this is not a guarantee. `--add-dir` grants access without confining writes. Protection relies on isolated candidate worktrees, mechanical execution scope checks with explicit baselines, frozen path checks, and test gates. - -Acceptance is distinct from process completion: exit 0, a top-level success status, or prose is insufficient. Require a parsed envelope, valid substantive structured output, execution-scope and gate evidence, and an explicit accepted attempt. A gate exit 126 or 127 is classified as `unrunnable` with `verification: not_performed`; preserve the command, exit code, and diagnostic evidence, and do not schedule a quality retry. - -Worker processes run through the vendor-neutral adapter boundary in -[`docs/worker-adapter-contract.md`](../docs/worker-adapter-contract.md). -Validate its normalized result with `scripts/check-worker-adapter.sh` or -`scripts/check-worker-adapter.ps1`, using the helper matching the host, before -accepting artifacts. The adapter reports process, worktree, and artifact -ownership. The orchestrator alone decides whether verification, publication, -or cleanup is allowed. - -## Step 1: Split and scout - -### Provisional split - -Break work into provisional tasks with a slug and a concise description of goals. - -### Choose gates - -Assign each task exactly one gate: - -- **Machine gate.** An executable test command executed through `execute-gate.sh` or `execute-gate.ps1`. A gate-author creates the test in Step 2; you run a red check and read the test before freezing it. The shared gate helper normalizes exit 0 to passed (`failure_class: none`), exit 126/127 to unrunnable (`verification: not_performed`, no quality retry), and other nonzero exits to quality failure (`verification: failed`). Record whether the task is behavior-preserving (waives the red check failure requirement). -- **Diff gate.** Plain-text criteria for tasks without automated tests (documentation, configuration, refactoring). A reviewer worker evaluates the diff against these criteria in Step 5. - -### Scout - -For provisional writing tasks, dispatch scouts in parallel through `dispatch-worker` with `--role scout`. Scouts run in an isolated worktree at the recorded baseline: - -#### Bash -```bash -OFFLOAD_ROOT="" -DISPATCH_STATE="/offload/dispatch.json" -SCOUT_WORKSPACE="/offload/scout" -SCOUT_SCHEMA='{"type":"object","properties":{"files":{"type":"array","items":{"type":"string"}}},"required":["files"]}' -"$OFFLOAD_ROOT/scripts/dispatch-worker.sh" \ - --state "$DISPATCH_STATE" \ - --assignment-id "scout-" \ - --role scout \ - --source-repo "" \ - --baseline "$BASELINE" \ - --owned "README.md" \ - --workspace-dir "$SCOUT_WORKSPACE" \ - --max-depth 0 \ - --max-width 1 \ - --max-timeout-seconds 1200 \ - --max-resource-units 1 \ - --timeout-seconds 1200 \ - --resource-units 1 \ - --output "/offload/.attempt1.scout.json" \ - --error "/offload/.attempt1.scout.err" \ - -- \ - -p ". List every repo-relative file path this task would need to read or change. Do not edit anything. Do not dispatch nested workers." \ - --output-format json \ - --mode plan \ - --json-schema "$SCOUT_SCHEMA" \ - --add-dir "$SCOUT_WORKSPACE" \ - --print-timeout 20m -``` - -#### PowerShell -```powershell -$OffloadRoot = "" -$DispatchState = "/offload/dispatch.json" -$ScoutWorkspace = "/offload/scout" -$ScoutSchema = '{"type":"object","properties":{"files":{"type":"array","items":{"type":"string"}}},"required":["files"]}' -& "$OffloadRoot/scripts/dispatch-worker.ps1" ` - --state $DispatchState ` - --assignment-id "scout-" ` - --role scout ` - --source-repo "" ` - --baseline $Baseline ` - --owned "README.md" ` - --workspace-dir $ScoutWorkspace ` - --max-depth 0 ` - --max-width 1 ` - --max-timeout-seconds 1200 ` - --max-resource-units 1 ` - --timeout-seconds 1200 ` - --resource-units 1 ` - --output "/offload/.attempt1.scout.json" ` - --error "/offload/.attempt1.scout.err" ` - '--' ` - -p ". List every repo-relative file path this task would need to read or change. Do not edit anything. Do not dispatch nested workers." ` - --output-format json ` - --mode plan ` - --json-schema $ScoutSchema ` - --add-dir $ScoutWorkspace ` - --print-timeout 20m -``` - -Read `structured_output` from the JSON response to extract the file list. - -### Finalize split - -Reconcile scout findings: - -- If two writing tasks touch overlapping files, serialize them rather than running in parallel. -- If a scout returned unexpected paths, adjust task boundaries before proceeding. -- Write final acceptance criteria for each task and assign each one a unique, stable `criterion_id` (for example, `C1`, `C2`). Save the resulting array as a JSON file in the run scratch directory so the reviewer and verifier consume the same set. - -## Step 2: Author gates - -Machine-gated tasks only. Skip for diff-gated tasks. - -For each machine-gated task, create an isolated candidate worktree at the recorded `$BASELINE`, owning only the gate file and freezing source files. Then dispatch one gate-author per machine-gated task in parallel using `--role gate-author`: - -#### Bash -```bash -GATE_WORKSPACE="/offload/gate-" -"$OFFLOAD_ROOT/scripts/dispatch-worker.sh" \ - --state "/offload/dispatch.json" \ - --assignment-id "gate-" \ - --source-repo "" \ - --baseline "$BASELINE" \ - --owned "" \ - --frozen "" \ - --frozen "" \ - --workspace-dir "$GATE_WORKSPACE" \ - --max-depth 0 \ - --max-width 1 \ - --max-timeout-seconds 1200 \ - --max-resource-units 1 \ - --timeout-seconds 1200 \ - --resource-units 1 \ - --role gate-author \ - --output "/offload/.attempt1.gate.json" \ - --error "/offload/.attempt1.gate.err" \ - -- \ - -p ". Write this test at . Do not touch any other file. Do not dispatch nested workers." \ - --output-format json \ - --add-dir "$GATE_WORKSPACE" \ - --mode accept-edits \ - --print-timeout 20m -``` - -#### PowerShell -```powershell -$GateWorkspace = "/offload/gate-" -& "$OffloadRoot/scripts/dispatch-worker.ps1" ` - --state "/offload/dispatch.json" ` - --assignment-id "gate-" ` - --source-repo "" ` - --baseline $Baseline ` - --owned "" ` - --frozen "" ` - --frozen "" ` - --workspace-dir $GateWorkspace ` - --max-depth 0 ` - --max-width 1 ` - --max-timeout-seconds 1200 ` - --max-resource-units 1 ` - --timeout-seconds 1200 ` - --resource-units 1 ` - --role gate-author ` - --output "/offload/.attempt1.gate.json" ` - --error "/offload/.attempt1.gate.err" ` - '--' ` - -p ". Write this test at . Do not touch any other file. Do not dispatch nested workers." ` - --output-format json ` - --add-dir $GateWorkspace ` - --mode accept-edits ` - --print-timeout 20m -``` - -Verify each created gate: - -1. **Scope verification and patch export.** Run `execution-workspace verify-export --manifest "/offload/gate-.manifest.json"`. The helper executes `check-execution-scope` against `--baseline "$BASELINE" --owned "" --frozen ""`. If the gate-author modified unowned source files or violated scope, it is rejected immediately before its output can become an implementation baseline. -2. **File existence.** Confirm the test file exists at `` in the candidate workspace (`[ -f "$GATE_WORKSPACE/" ]` in Bash or `Test-Path "$GateWorkspace/"` in PowerShell). -3. **Red check.** Run the gate command against the untouched baseline revision in the candidate workspace (`` in Bash or `& ` in PowerShell). Require a non-zero exit code, unless the task is marked behavior-preserving where 0 is expected. -4. **Read the test.** Read the test source to confirm assertions match the requirements. -5. **Integrate and freeze.** Integrate verified gate patch into the repository integration baseline: - - Bash: - ```bash - "$OFFLOAD_ROOT/scripts/execution-workspace.sh" integrate \ - --manifest "/offload/gate-.manifest.json" - git commit -m "offload: freeze gates" - GATE_BASELINE=$(git rev-parse HEAD) - ``` - - PowerShell: - ```powershell - & "$OffloadRoot/scripts/execution-workspace.ps1" integrate ` - --manifest "/offload/gate-.manifest.json" - git commit -m "offload: freeze gates" - $GateBaseline = (git rev-parse HEAD).Trim() - ``` - -## Step 3: Dispatch implementers - -For each task, create an isolated candidate worktree from the approved `$GATE_BASELINE` (or initial `$BASELINE` for diff-gated tasks). Assign owned paths and designate approved gates as frozen paths. Dispatch implementers in parallel using `--role implementer`: - -#### Bash -```bash -TASK_WORKSPACE="/offload/" -"$OFFLOAD_ROOT/scripts/dispatch-worker.sh" \ - --state "/offload/dispatch.json" \ - --assignment-id "" \ - --source-repo "" \ - --baseline "$GATE_BASELINE" \ - --owned "" \ - --owned "" \ - --frozen "" \ - --workspace-dir "$TASK_WORKSPACE" \ - --max-depth 0 \ - --max-width 1 \ - --max-timeout-seconds 1200 \ - --max-resource-units 1 \ - --timeout-seconds 1200 \ - --resource-units 1 \ - --role implementer \ - --output "/offload/.attempt1.json" \ - --error "/offload/.attempt1.err" \ - -- \ - -p ". Owned files: . Frozen paths: . Gate command: . Do not touch any other file. Do not dispatch nested workers." \ - --output-format json \ - --add-dir "$TASK_WORKSPACE" \ - --mode accept-edits \ - --print-timeout 20m -``` - -#### PowerShell -```powershell -$TaskWorkspace = "/offload/" -& "$OffloadRoot/scripts/dispatch-worker.ps1" ` - --state "/offload/dispatch.json" ` - --assignment-id "" ` - --source-repo "" ` - --baseline $GateBaseline ` - --owned "" ` - --owned "" ` - --frozen "" ` - --workspace-dir $TaskWorkspace ` - --max-depth 0 ` - --max-width 1 ` - --max-timeout-seconds 1200 ` - --max-resource-units 1 ` - --timeout-seconds 1200 ` - --resource-units 1 ` - --role implementer ` - --output "/offload/.attempt1.json" ` - --error "/offload/.attempt1.err" ` - '--' ` - -p ". Owned files: . Frozen paths: . Gate command: . Do not touch any other file. Do not dispatch nested workers." ` - --output-format json ` - --add-dir $TaskWorkspace ` - --mode accept-edits ` - --print-timeout 20m -``` - -The prompt must specify owned files, frozen paths (including approved frozen gates), the gate command, and prohibitions against touching unassigned files or dispatching nested workers. - -When an attempt fails verification, keep its evidence paths in the outcome record and redispatch the same `worker_id` with attempt 2 paths. Set `ATTEMPT=2` in Bash or `$Attempt = 2` in PowerShell, then use `/offload/.attempt2.json` (or `.attempt2..json` for the role-suffixed scout, gate-author, and reviewer artifacts) for `--output`, with the matching `.err` path for `--error`. Record the verified attempt as `accepted_attempt` in the orchestrator's run state and use only that attempt's patch or review output for integration. - -## Step 4: Collect - -Read worker JSON responses and record outcomes in `routing-outcomes.json`: - -- `status: SUCCESS`: Worker completed execution. Proceed to verification in Step 5. -- Non-zero exit code or unparsable output: Worker crashed or encountered an operational failure. Record the attempt and follow Step 6. -- Timeout (no output written before 20m timeout): Operational failure. Record the timeout and follow Step 6. -- **Immediate quota handoff**: If explicit adapter-reported quota exhaustion is detected on any worker, record still-running candidates and all existing artifacts in `routing-outcomes.json` immediately without waiting for sibling completion, and hand off unfinished work directly to the calling orchestrator. - -## Step 5: Verify and integrate - -Verify every worker reporting `SUCCESS`: - -1. **Mechanical execution scope check and patch export.** - Run `execution-workspace verify-export --manifest "/offload/.manifest.json"` before dispatching a reviewer. - - #### Bash - ```bash - if ! REVIEW_ARTIFACT="$("$OFFLOAD_ROOT/scripts/execution-workspace.sh" verify-export --manifest "")"; then - echo "review artifact export failed" >&2 - exit 1 - fi - ``` - - #### PowerShell - ```powershell - $ReviewArtifact = & "$OffloadRoot/scripts/execution-workspace.ps1" ` - verify-export ` - --manifest "" - if ($LASTEXITCODE -ne 0) { - throw "review artifact export failed" - } - ``` - - `verify-export` stages all candidate changes, including committed, staged, unstaged, deleted, renamed, untracked, and binary changes. It executes `check-execution-scope` against the recorded baseline and owned/frozen paths, then writes one binary-capable patch outside the candidate and records its `patch_file`, `patch_digest`, and `touched_paths` in the manifest. Any scope, Git, artifact, or digest failure rejects the review. - - Direct manual invocation of `check-execution-scope` always requires `--baseline`: - #### Bash - ```bash - "$OFFLOAD_ROOT/scripts/check-execution-scope.sh" \ - --baseline "$GATE_BASELINE" \ - --owned "" \ - --owned "" \ - --frozen "" \ - --frozen "" - ``` - - #### PowerShell - ```powershell - & "$OffloadRoot/scripts/check-execution-scope.ps1" ` - --baseline $GateBaseline ` - --owned "" ` - --owned "" ` - --frozen "" ` - --frozen "" - ``` - - Any violation printed by the helper represents an unowned modification or a frozen path violation. The helper exits nonzero when violations exist. Report violations regardless of gate results. - -2. **Candidate gate execution.** - - Machine gate: Run the frozen gate command in the candidate workspace through the shell-native gate execution helper (`execute-gate.sh` or `execute-gate.ps1`), which captures diagnostic stdout/stderr to an artifact file and normalizes gate exit codes: - - #### Bash - ```bash - GATE_REPORT="$("$OFFLOAD_ROOT/scripts/execute-gate.sh" --command "" --workspace "$TASK_WORKSPACE")" - ``` - - #### PowerShell - ```powershell - $GateReport = & "$OffloadRoot/scripts/execute-gate.ps1" --command "" --workspace $TaskWorkspace | ConvertFrom-Json - ``` - - Consume the normalized classification from the gate execution helper rather than requiring the process to exit 0 directly: - - `verification_status: "passed"` (`failure_class: "none"`, exit 0): The gate passed cleanly. - - `failure_class: "unrunnable"` (`verification_status: "not_performed"`, `allow_retry: false`, exit 126 or 127): The gate command could not be executed (command not found or permission denied). Retain the command, exit code, and `diagnostic_artifact_path` evidence in `routing-outcomes.json`. Exits 126 and 127 are not quality retries; do not schedule a quality retry. - - `failure_class: "quality"` (`verification_status: "failed"`, `allow_retry: true`, other non-zero exit codes): The test assertions failed. Record the diagnostic artifact path and schedule a quality retry if attempt budget remains. - - Diff gate: Dispatch an adversarial reviewer worker to inspect the recorded artifact using `--role reviewer`: - - #### Bash - ```bash - REVIEW_SCHEMA='{"type":"object","properties":{"criteria":{"type":"array","items":{"type":"object","properties":{"criterion_id":{"type":"string"},"verdict":{"type":"string","enum":["pass","fail","hedge"]},"quote":{"type":"string"}},"required":["criterion_id","verdict","quote"]}}},"required":["criteria"]}' - REVIEW_WORKSPACE="/offload/-reviewer" - "$OFFLOAD_ROOT/scripts/dispatch-worker.sh" \ - --state "/offload/dispatch.json" \ - --assignment-id "-reviewer" \ - --role reviewer \ - --source-repo "" \ - --baseline "$GATE_BASELINE" \ - --owned "README.md" \ - --workspace-dir "$REVIEW_WORKSPACE" \ - --max-depth 0 \ - --max-width 1 \ - --max-timeout-seconds 1200 \ - --max-resource-units 1 \ - --timeout-seconds 1200 \ - --resource-units 1 \ - --output "/offload/.attempt1.review.json" \ - --error "/offload/.attempt1.review.err" \ - -- \ - -p "Read the recorded review artifact at . Verify its bytes against before reviewing. Do not inspect the candidate checkout or generate another diff. Return exactly one verdict object for every criterion in , copying each criterion_id exactly. Decide pass, fail, or hedge if unsure. Look for reasons the criterion FAILS before accepting pass. For every pass, quote one complete line verbatim from the artifact that proves it. Criteria: " \ - --output-format json \ - --mode plan \ - --json-schema "$REVIEW_SCHEMA" \ - --add-dir "" \ - --add-dir "" \ - --print-timeout 20m - ``` - - #### PowerShell - ```powershell - $ReviewSchema = '{"type":"object","properties":{"criteria":{"type":"array","items":{"type":"object","properties":{"criterion_id":{"type":"string"},"verdict":{"type":"string","enum":["pass","fail","hedge"]},"quote":{"type":"string"}},"required":["criterion_id","verdict","quote"]}}},"required":["criteria"]}' - $ReviewWorkspace = "/offload/-reviewer" - & "$OffloadRoot/scripts/dispatch-worker.ps1" ` - --state "/offload/dispatch.json" ` - --assignment-id "-reviewer" ` - --role reviewer ` - --source-repo "" ` - --baseline $GateBaseline ` - --owned "README.md" ` - --workspace-dir $ReviewWorkspace ` - --max-depth 0 ` - --max-width 1 ` - --max-timeout-seconds 1200 ` - --max-resource-units 1 ` - --timeout-seconds 1200 ` - --resource-units 1 ` - --output "/offload/.attempt1.review.json" ` - --error "/offload/.attempt1.review.err" ` - '--' ` - -p "Read the recorded review artifact at . Verify its bytes against before reviewing. Do not inspect the candidate checkout or generate another diff. Return exactly one verdict object for every criterion in , copying each criterion_id exactly. Decide pass, fail, or hedge if unsure. Look for reasons the criterion FAILS before accepting pass. For every pass, quote one complete line verbatim from the artifact that proves it. Criteria: " ` - --output-format json ` - --mode plan ` - - --json-schema $ReviewSchema ` - --add-dir "" ` - --add-dir "" ` - --print-timeout 20m - ``` - - Read `structured_output` from the JSON response to extract criteria verdicts and quotes. - - First recheck the recorded digest. Then run the data-only coverage and evidence verifier with the criteria file, reviewer JSON, and the same artifact: - - Bash digest: `test "sha256:$(sha256sum "" | awk '{print tolower($1)}')" = ""` - - PowerShell digest: `$actualDigest = "sha256:$((Get-FileHash -Algorithm SHA256 -LiteralPath "").Hash.ToLowerInvariant())"; if ($actualDigest -ne "") { throw "review artifact digest mismatch" }` - - Bash verifier: `"$OFFLOAD_ROOT/scripts/check-review-verdict.sh" --criteria "" --review "" --artifact ""` - - PowerShell verifier: `& "$OffloadRoot/scripts/check-review-verdict.ps1" --criteria "" --review "" --artifact ""` - - The verifier performs exact criterion coverage and literal line matching from parsed data. Exit 0 accepts the reviewer result (`agy+grep`). Exit 1 means every criterion was covered but a fail or hedge requires direct orchestrator review. Exit 2 means malformed or incomplete coverage, duplicate or unknown IDs, a forged quote, or another verification error. For exit 1 or 2, inspect the recorded artifact directly (`agy→orchestrator`). - -3. **Integration of verified tasks.** - - Disjoint tasks: Apply verified candidate patches sequentially via `execution-workspace integrate --manifest ""`. The helper tests integration in a disposable scratch worktree before applying to the target. - - Overlapping tasks: Run overlapping tasks serially. When Task 1 integrates, its resulting commit becomes the new baseline `$STAGE_BASELINE` for Task 2. Task 2's candidate worktree is created from this newly accepted baseline. Every accepted delta undergoes scope and gate verification before publication to the caller. - -4. **Final combined gate check.** - After all verified tasks are integrated into the integration target, execute all gate commands across all completed tasks together through the shared gate execution helper (`execute-gate.sh` or `execute-gate.ps1`). - Every gate must normalize to `verification_status: "passed"` (`failure_class: "none"`). If any combined gate normalizes to quality failure or unrunnable, or if conflicts arise, the caller's working tree remains intact (the integrated changes are aborted and not published). Only publish when all combined gates pass cleanly. - -## Step 6: Retry, recovery, and cleanup - -Follow the shared recovery, retry accounting, and failure handling rules in [`SKILL.md`](../SKILL.md): - -- **Stable worker IDs and retry ceiling.** Assign a stable `worker_id` to each logical task. Attempt 1 is initial dispatch; attempt 2 is its only possible retry. Maximum two attempts total per task. -- **Outcome tracking.** Record each attempt and verification outcome in `routing-outcomes.json`. -- **Baseline retention on retry.** Retries must retain the original verification baseline for that writing stage (e.g. `$GATE_BASELINE`). A failed attempt never becomes an implicitly trusted baseline. Create a fresh candidate worktree at the original baseline for attempt 2. -- **Implementer quality failure.** If an execution scope check violation occurs or a machine gate normalizes to `failure_class: "quality"` (non-zero exit code other than 126/127), this constitutes a quality failure. If a retry remains (attempt 2), redispatch once with the specific failure output and diagnostic evidence using the pinned selection. If the pinned model is unavailable, record the explicit fallback or handoff and do not switch silently. If attempt 2 fails, halt that task. -- **Unrunnable gate execution.** If a gate command exits 126 or 127, it normalizes to `failure_class: "unrunnable"` with `verification_status: "not_performed"` and `allow_retry: false`. Gate exits 126 and 127 are not quality retries; preserve the command, exit code, and diagnostic evidence in `routing-outcomes.json` without spending or scheduling a quality retry. -- **Scout or gate-author operational failure.** If a scout or gate-author crashes, times out, or produces unparsable output, retry once using `--route default`. If the retry fails, complete that step directly as the orchestrator (`orchestrator (fallback)`). -- **Reviewer failure.** If reviewer output is unparsable or fails digest or quote verification, inspect the recorded artifact directly as the orchestrator (`agy→orchestrator`). -- **Quota exhaustion.** Explicit adapter-reported quota exhaustion triggers immediate quota handoff per [`SKILL.md`](../SKILL.md). Do not retry or switch models. Record still-running candidates immediately without waiting for siblings, preserve completed artifacts, and return unfinished work to the calling orchestrator. -- **Workspace cleanup.** After workers have terminated, clean up candidate worktrees: - - Bash: `"$OFFLOAD_ROOT/scripts/execution-workspace.sh" cleanup --manifest "" --status success|failed|retain` - - PowerShell: `& "$OffloadRoot/scripts/execution-workspace.ps1" cleanup --manifest "" --status success|failed|retain` - Wait for active worker processes to terminate before calling cleanup. Pass `--status retain` if preserving a candidate workspace for orchestrator inspection. - -- **Ownership ledger and crash recovery.** Candidate worktrees, research workspaces, and worker processes are recorded in an orchestrator-owned ledger outside their resource paths. Register a resource before or immediately after creation, update it as the lifecycle changes (`active`, `failed`, `timed_out`, `cancelled`, `quota_handoff`, `cleanup_pending`, or `completed`), and run reconciliation at the start of a later run: - - Bash: `"$OFFLOAD_ROOT/scripts/resource-ledger.sh" reconcile --ledger "" --source-repo ""` - - PowerShell: `& "$OffloadRoot/scripts/resource-ledger.ps1" reconcile --ledger "" --source-repo ""` - Cleanup terminates and waits for an owned worker process before touching its resources. It removes only records whose owner marker, parent relationship, and Git/worktree safety checks pass. Dirty, unmerged, unknown, ambiguous, or otherwise unprovable resources remain on disk and in the ledger for review. Never place the ledger inside a worker checkout. diff --git a/modes/repo-research.md b/modes/repo-research.md deleted file mode 100644 index fda1c2c..0000000 --- a/modes/repo-research.md +++ /dev/null @@ -1,122 +0,0 @@ -# Repository research mode - -Conducts bounded local repository investigations, audits, and invariant checks using isolated workspaces and read-only orchestrator verification. - -## Preconditions and helper selection - -Select the helper family matching your current host shell: - -- **POSIX shells (Bash 3.2+)**: Use `scripts/make-research-workspace.sh`, `scripts/run-agy-json.sh`, and `scripts/cleanup-research-workspace.sh`. Requires Git, `jq`, Python 3, and the configured adapter's executable. -- **PowerShell (PowerShell 7+)**: Use `scripts/make-research-workspace.ps1`, `scripts/run-agy-json.ps1`, and `scripts/cleanup-research-workspace.ps1`. Native Windows orchestrators require only PowerShell 7 (`pwsh`), Git, and the configured adapter. Windows workflows do not require Bash, WSL, Git Bash, Python, or `jq`. - -Complete the shared preflight model availability check described in [`SKILL.md`](../SKILL.md) before dispatching workers. Researchers route through the role preference, effort, and required capabilities in `model-policy.json`; the adapter selects the current model. Do not pass `--model` or `--effort` directly. - -Every research dispatch supplies the shared lifecycle metadata to `run-agy-json`: `--assignment-id`, `--attempt`, `--mode repo-research`, `--verification-baseline`, `--resource-ledger`, and a distinct `--lifecycle` path. The launcher records worker exit results and retains diagnosis artifacts for failed, canceled, timed-out, malformed, or quota-handoff runs. Resume and retry must use the ledger's pinned identity, model, effort, verification baseline, and attempt limit. - -## Assignment requirements - -Every repository research assignment must define four fields: - -1. **One bounded question.** A specific inquiry answerable from code (for example, "Which API endpoints omit session authentication?"). -2. **Allowed scope.** Explicit list of files, directories, or modules the worker is permitted to inspect. -3. **Evidence expectations.** Concrete citations required for each finding (file paths with line numbers or ranges, and reproducible commands). -4. **Explicit non-mutation rule.** A clear instruction: investigate only, make no file modifications or creations, and dispatch no nested workers. - -Open-ended research without a bounded question, defined scope, and evidence expectations is out of scope. - -## Filesystem isolation and workspace creation - -Do not point workers directly at the live repository. `--mode plan` is a version-sensitive behavioral hint, not a write barrier; the `agy 1.1.25` probe is an observation, not a guarantee. Similarly, `--add-dir` grants directory access without confining worker writes. Filesystem isolation and disposable workspaces are the containment boundary. - -Isolate every research run in a disposable workspace: - -#### Bash -```bash -OFFLOAD_ROOT="" -WORKSPACE=$("$OFFLOAD_ROOT/scripts/make-research-workspace.sh" --source-repo "$PWD" --path "" --path "") -``` - -#### PowerShell -```powershell -$OffloadRoot = "" -$Workspace = (& "$OffloadRoot/scripts/make-research-workspace.ps1" --source-repo (Get-Location).Path --path "" --path "").Trim() -``` - -The workspace helper creates a unique temporary directory, writes the `.offload-research-workspace` marker, and copies only declared scope paths into `/repo/`. Launch the worker with its working directory set to the workspace and `--add-dir` pointing at `/repo`. The live repository remains untouched by worker processes. - -## Worker dispatch - -Dispatch researchers in parallel using role `researcher` with a structured schema and the matching launcher helper. The launcher asks the adapter to select a current eligible model: - -#### Bash -```bash -RESEARCH_SCHEMA='{"type":"object","properties":{"lane_id":{"type":"string"},"lane_kind":{"type":"string","enum":["research","audit"]},"question":{"type":"string"},"overall_status":{"type":"string","enum":["complete","inconclusive","blocked"]},"uncertainty":{"type":"string"},"findings":{"type":"array","items":{"type":"object","properties":{"finding":{"type":"string"},"priority":{"type":"string","enum":["high","medium","low"]},"status":{"type":"string","enum":["confirmed","refuted","inconclusive"]},"evidence_locations":{"type":"array","items":{"type":"string"}},"evidence_commands":{"type":"array","items":{"type":"string"}}},"required":["finding","priority","status","evidence_locations"]}}},"required":["lane_id","lane_kind","question","overall_status","uncertainty","findings"]}' - -"$OFFLOAD_ROOT/scripts/run-agy-json.sh" \ - --role researcher \ - --output "$WORKSPACE/.attempt1.research.json" \ - --error "$WORKSPACE/.attempt1.research.err" \ - -- \ - -p "Lane ID: . Lane kind: . Question: . Allowed scope: . Evidence expectations: . Non-mutation rule: investigate only, do not create or edit files, do not dispatch nested workers." \ - --output-format json \ - --mode plan \ - --json-schema "$RESEARCH_SCHEMA" \ - --add-dir "$WORKSPACE/repo" \ - --print-timeout 20m -``` - -#### PowerShell -```powershell -$ResearchSchema = '{"type":"object","properties":{"lane_id":{"type":"string"},"lane_kind":{"type":"string","enum":["research","audit"]},"question":{"type":"string"},"overall_status":{"type":"string","enum":["complete","inconclusive","blocked"]},"uncertainty":{"type":"string"},"findings":{"type":"array","items":{"type":"object","properties":{"finding":{"type":"string"},"priority":{"type":"string","enum":["high","medium","low"]},"status":{"type":"string","enum":["confirmed","refuted","inconclusive"]},"evidence_locations":{"type":"array","items":{"type":"string"}},"evidence_commands":{"type":"array","items":{"type":"string"}}},"required":["finding","priority","status","evidence_locations"]}}},"required":["lane_id","lane_kind","question","overall_status","uncertainty","findings"]}' - -& "$OffloadRoot/scripts/run-agy-json.ps1" ` - --role researcher ` - --output "$Workspace/.attempt1.research.json" ` - --error "$Workspace/.attempt1.research.err" ` - '--' ` - -p "Lane ID: . Lane kind: . Question: . Allowed scope: . Evidence expectations: . Non-mutation rule: investigate only, do not create or edit files, do not dispatch nested workers." ` - --output-format json ` - --mode plan ` - --json-schema $ResearchSchema ` - --add-dir "$Workspace/repo" ` - --print-timeout 20m -``` - -Read `structured_output` from the JSON response to extract validated findings. - -If a lane needs its one permitted retry, keep the same `lane_id` and use new paths. Set `ATTEMPT=2` in Bash or `$Attempt = 2` in PowerShell, then dispatch to `.attempt2.research.json` and `.attempt2.research.err`. Record both paths in the corresponding attempt's `evidence_paths`, and set an explicit `accepted_attempt` after verification. Any report or later consumer must read only the selected attempt, never a wildcard that could include both attempts. - -## Verification protocol - -Never accept a worker's research findings on trust alone. Run this verification protocol against the live repository using read-only orchestrator commands: - -1. **Scope validation.** Confirm all cited `evidence_locations` and `evidence_commands` stay inside the declared scope. Treat out-of-scope citations as invalid. -2. **Priority assessment.** Independently evaluate finding severity. Correct worker-assigned priority when needed so critical findings cannot bypass thorough review. -3. **Direct check of high-priority findings.** Inspect the exact cited file paths and line ranges in the live repository. Before running any `evidence_command`, inspect it to ensure it is read-only, non-interactive, and safe. Confirm the evidence directly proves the finding. Record provenance as `orchestrator+checked`. -4. **Sampling lower-priority findings.** Spot-check a representative sample of medium- and low-priority findings against the live codebase. Record provenance as `orchestrator+sampled`. -5. **Mark unsupported claims as unverified.** If a finding lacks concrete evidence, cites out-of-scope files, references unsafe commands, or fails manual checking, classify it as `UNVERIFIED` (provenance `agy+unverified`). -6. **Record sample counts and provenance.** Note priority adjustments, the exact sample verified, and individual finding provenance in the final report. - -## Retry, recovery, and fallback - -Follow the shared recovery, retry accounting, and failure handling rules in [`SKILL.md`](../SKILL.md): - -- **Stable worker IDs and retry ceiling.** Assign a stable `worker_id` to each investigation lane. Attempt 1 is initial dispatch; attempt 2 is its only permitted retry. Maximum two attempts total per assignment. -- **Outcome tracking.** Record each attempt and verification outcome in `routing-outcomes.json`. -- **Operational failure.** If a worker crashes, times out, or produces unparsable output, redispatch once using `--route default`. No model escalation for operational failure. -- **Orchestrator fallback.** If the second attempt fails or findings remain inconclusive, complete the investigation directly as the orchestrator (`orchestrator (fallback)`). -- **Quota exhaustion.** Explicit adapter-reported quota exhaustion triggers immediate quota handoff per [`SKILL.md`](../SKILL.md). Do not retry or switch models. Preserve completed artifacts and return unfinished work to the calling orchestrator. - -## Cleanup - -After verification completes, clean the temporary workspace and snapshot directory using the matching cleanup helper. On success, it retains `final.md`, `provenance.json` when present, `routing-outcomes.json`, the workspace marker, and an `evidence-disposition.json` manifest. The manifest records every evidence path from the routing record, its pre-cleanup existence, a SHA-256 hash for existing regular files, and whether the path was retained, pruned, missing, or left uninspected for safety. Raw worker artifacts remain the default success-pruning policy. A partial or failed run retains all artifacts. - -#### Bash -```bash -"$OFFLOAD_ROOT/scripts/cleanup-research-workspace.sh" --workspace "$WORKSPACE" --status success -``` - -#### PowerShell -```powershell -& "$OffloadRoot/scripts/cleanup-research-workspace.ps1" --workspace "$Workspace" --status success -``` diff --git a/modes/web-research.md b/modes/web-research.md deleted file mode 100644 index ea61e04..0000000 --- a/modes/web-research.md +++ /dev/null @@ -1,549 +0,0 @@ -# Web research mode - -Conducts cited online investigations and multi-angle technical research by dispatching parallel headless workers through the configured adapter, synthesizing findings into a structured claim ledger, and validating every final citation with an independent auditor. - -## Preconditions and sources - -1. **Public-source default.** Research workers query public online sources by default. -2. **Explicit authorization for private sources.** Accessing private, internal, or authenticated sources requires explicit authorization from the user for that specific run. Never forward cookies, session tokens, browser profiles, or environment credentials implicitly. -3. **Helper family and environment requirements.** Select the helper family matching your host shell: - - **POSIX shells (Bash 3.2+)**: Use `.sh` scripts in `scripts/`. Requires Git, `jq`, Python 3, and the configured adapter's executable. - - **PowerShell (PowerShell 7+)**: Use `.ps1` scripts in `scripts/`. Native Windows orchestrators require only PowerShell 7 (`pwsh`), Git, and the configured adapter. Windows workflows do not require Bash, WSL, Git Bash, Python, or `jq`. -4. **Configured adapter availability.** Workers are launched using the matching `run-agy-json` helper, which handles adapter selection and output capture. -5. **Filesystem isolation.** Every research run operates in a disposable workspace outside the live repository. -6. **Model policy and preflight check.** Complete the shared preflight model availability check described in [`SKILL.md`](../SKILL.md) before dispatching workers. All roles route through the role preference, effort, and required capabilities in `model-policy.json`; the adapter selects a current eligible model. Do not pass `--model` or `--effort` directly. - -Every web-research dispatch supplies the shared lifecycle metadata to `run-agy-json`: `--assignment-id`, `--attempt`, `--mode web-research`, `--verification-baseline`, `--resource-ledger`, and a distinct `--lifecycle` path. The launcher waits for worker exit before cleanup, preserves diagnosis evidence for non-successful runs, and hands off quota-exhausted work without waiting for sibling workers. Resume and retry must use the ledger's pinned identity, model, effort, verification baseline, and attempt limit. - -## Worker isolation and mixed repositories - -`--mode plan` is a version-sensitive behavioral hint, not a write barrier. The accepted `agy 1.1.25` probe blocked the tested direct write outside the permitted artifact area, but exposed tools and commands mean this is not a guarantee. Similarly, `--add-dir` grants directory access without confining worker writes. Safety and containment rely on strict filesystem isolation: - -1. **Create workspace.** Initialize a temporary directory outside the live codebase using the matching workspace helper: - - #### Bash - ```bash - OFFLOAD_ROOT="" - WORKSPACE=$("$OFFLOAD_ROOT/scripts/make-research-workspace.sh" --source-repo "$PWD" --path "") - ``` - - #### PowerShell - ```powershell - $OffloadRoot = "" - $Workspace = (& "$OffloadRoot/scripts/make-research-workspace.ps1" --source-repo (Get-Location).Path --path "").Trim() - ``` - -2. **Mixed repository handoff.** When research requires context from local files, declare the exact minimal paths required. The workspace helper writes the `.offload-research-workspace` marker and copies only those declared paths into `/repo/`. -3. **No live repository paths.** Never pass the live repository path in worker prompts or `--add-dir` arguments. Point `--add-dir` at the snapshot directory (`/repo`) when local context is needed. -4. **Local evidence verification.** The orchestrator independently checks all local codebase citations against the live repository using read-only commands. - -## Profiles and triggers - -Choose between two research profiles based on task complexity: - -### Standard profile - -Dispatches two or three researchers in parallel across distinct evidence angles, followed by one synthesizer, followed by one auditor. Use standard profile for general technical questions, documentation lookups, and library comparisons. - -### Deep profile - -Dispatches up to five researchers in total. Deep research starts from standard-profile findings and adds only the supplementary angles required to resolve specific uncertainty or conflicts. Do not rerun standard angles. - -Deep profile activates upon explicit user request or when one of these named triggers is encountered: - -- **Material source conflict**: High-trust primary sources directly contradict one another. -- **Costly or hard-to-reverse decision**: Architectural choices, infrastructure migrations, or licensing commitments. -- **Citation-sensitive output**: Formal specifications, security advisories, or compliance requirements. -- **Substantial counterevidence**: Initial findings challenge core architectural assumptions. - -Record the specific deep trigger in the final report and in `provenance.json`. If no trigger applies, use standard profile. - -## Worker roles and models - -Workers are dispatched by role using `run-agy-json` with `--role `. The launcher resolves models dynamically from `model-policy.json`. Do not pass `--model` or `--effort` directly. Refer to [`SKILL.md`](../SKILL.md) for the shared model routing, preflight, and recovery contract. - -| Role | Stage | Preference | Effort | Alternative model | Mode | Job | -|---|---|---|---|---|---|---| -| researcher | 1 | balanced | high | adapter catalog | `plan` | Gathers structured claims and citations for an assigned evidence angle. | -| synthesizer | 2 | deep | high | adapter catalog | `plan` | Builds claim ledger, resolves agreements/conflicts, and drafts synthesis. | -| auditor | 3 | deep | high | adapter catalog | `plan` | Independently verifies every citation in the proposed final answer. | - -A historical live smoke comparison against Gemini 3.7 retained Flash for every role. The proposed Pro synthesizer and auditor split did not complete its mandatory synthesis stage, while the all-Flash control completed synthesis and citation audit with four supported claims. See [`tests/live-smoke-comparison.md`](../tests/live-smoke-comparison.md) for the recorded judgment. - -All workers run with a 20-minute timeout (`--print-timeout 20m`). - -## Stage 1: Dispatch researchers - -Divide the investigation into distinct evidence angles. Overlap between angles is permitted only to test conflicting claims or verify source independence. Example angles: -- Angle A: Official documentation, specifications, and vendor release notes. -- Angle B: Independent benchmarks, real-world case studies, and performance reports. -- Angle C: Known failure modes, security advisories, and counter-arguments. - -### Researcher JSON schema - -```json -{ - "type": "object", - "properties": { - "run_id": {"type": "string"}, - "angle_id": {"type": "string"}, - "status": {"type": "string", "enum": ["success", "failed", "inconclusive"]}, - "failure_reason": {"type": "string"}, - "question": {"type": "string"}, - "evidence_angle": {"type": "string"}, - "findings": { - "type": "array", - "items": { - "type": "object", - "properties": { - "claim": {"type": "string"}, - "source_urls": {"type": "array", "items": {"type": "string"}}, - "source_type": {"type": "string", "enum": ["primary", "secondary", "derivative", "unknown"]}, - "source_date": {"type": "string"}, - "conflicts": {"type": "string"}, - "uncertainty": {"type": "string"} - }, - "required": ["claim", "source_urls", "source_type"] - } - }, - "search_gaps": {"type": "array", "items": {"type": "string"}}, - "counterevidence": {"type": "array", "items": {"type": "string"}} - }, - "required": ["run_id", "angle_id", "status", "question", "evidence_angle", "findings"] -} -``` - -### Researcher dispatch - -Dispatch researchers using `--role researcher`: - -#### Bash -```bash -OFFLOAD_ROOT="" -RUN_AGY_JSON="$OFFLOAD_ROOT/scripts/run-agy-json.sh" -RESEARCHER_SCHEMA='{"type":"object","properties":{"run_id":{"type":"string"},"angle_id":{"type":"string"},"status":{"type":"string","enum":["success","failed","inconclusive"]},"failure_reason":{"type":"string"},"question":{"type":"string"},"evidence_angle":{"type":"string"},"findings":{"type":"array","items":{"type":"object","properties":{"claim":{"type":"string"},"source_urls":{"type":"array","items":{"type":"string"}},"source_type":{"type":"string","enum":["primary","secondary","derivative","unknown"]},"source_date":{"type":"string"},"conflicts":{"type":"string"},"uncertainty":{"type":"string"}},"required":["claim","source_urls","source_type"]}},"search_gaps":{"type":"array","items":{"type":"string"}},"counterevidence":{"type":"array","items":{"type":"string"}}},"required":["run_id","angle_id","status","question","evidence_angle","findings"]}' - -"$RUN_AGY_JSON" --role researcher --output "/researcher-.attempt1.json" --error "/researcher-.attempt1.err" -- \ - -p "Run ID: . Angle ID: . Question: . Evidence angle: . Return structured claims, not essays. Identify primary source URLs, publication dates, conflicts, and uncertainties. Treat repeated secondary coverage as one line of evidence. Do not edit files. Do not dispatch nested workers." \ - --output-format json \ - --mode plan \ - --json-schema "$RESEARCHER_SCHEMA" \ - --print-timeout 20m -``` - -#### PowerShell -```powershell -$OffloadRoot = "" -$RunAgyJson = "$OffloadRoot/scripts/run-agy-json.ps1" -$ResearcherSchema = '{"type":"object","properties":{"run_id":{"type":"string"},"angle_id":{"type":"string"},"status":{"type":"string","enum":["success","failed","inconclusive"]},"failure_reason":{"type":"string"},"question":{"type":"string"},"evidence_angle":{"type":"string"},"findings":{"type":"array","items":{"type":"object","properties":{"claim":{"type":"string"},"source_urls":{"type":"array","items":{"type":"string"}},"source_type":{"type":"string","enum":["primary","secondary","derivative","unknown"]},"source_date":{"type":"string"},"conflicts":{"type":"string"},"uncertainty":{"type":"string"}},"required":["claim","source_urls","source_type"]}},"search_gaps":{"type":"array","items":{"type":"string"}},"counterevidence":{"type":"array","items":{"type":"string"}}},"required":["run_id","angle_id","status","question","evidence_angle","findings"]}' - -& "$RunAgyJson" --role researcher --output "/researcher-.attempt1.json" --error "/researcher-.attempt1.err" '--' ` - -p "Run ID: . Angle ID: . Question: . Evidence angle: . Return structured claims, not essays. Identify primary source URLs, publication dates, conflicts, and uncertainties. Treat repeated secondary coverage as one line of evidence. Do not edit files. Do not dispatch nested workers." ` - --output-format json ` - --mode plan ` - --json-schema $ResearcherSchema ` - --print-timeout 20m -``` - -Read `structured_output` from each researcher JSON response to extract validated findings for synthesis. Do not forward the top-level `response`, usage metadata, or the full JSON envelope. - -If a researcher needs its one retry, preserve the same worker ID and dispatch to `/researcher-.attempt2.json` and `/researcher-.attempt2.err`. Record both attempts, set the worker's explicit `accepted_attempt`, and point its selected `output` field at that artifact after verification. Only selected researcher outputs may feed synthesis. - -## Stage 2: Synthesize claim ledger - -The synthesizer merges findings across the verified selected researcher outputs and constructs a claim ledger. - -### Synthesis rules - -1. **Claim ledger.** Map each finding to a discrete claim ID with citations, decision relevance, and status. -2. **Combine propositions.** Combine claims only when cited sources support the exact same proposition. -3. **Remove unsupported incidental claims.** Discard low-relevance claims that lack primary or verifiable support. -4. **Preserve decision-relevant uncertainty.** Retain unresolved or conflicting claims that affect the core question, clearly labeling the evidence gap. -5. **No voting.** Do not resolve disagreements by counting worker instances. Weigh primary and independent sources over derivative summaries. - -### Synthesizer JSON schema - -```json -{ - "type": "object", - "properties": { - "claim_ledger": { - "type": "array", - "items": { - "type": "object", - "properties": { - "claim_id": {"type": "string"}, - "claim": {"type": "string"}, - "citations": {"type": "array", "items": {"type": "string"}}, - "decision_relevance": {"type": "string", "enum": ["critical", "supporting", "incidental"]}, - "status": {"type": "string", "enum": ["supported", "conflicted", "unresolved"]}, - "inferences": {"type": "string"} - }, - "required": ["claim_id", "claim", "citations", "decision_relevance", "status"] - } - }, - "proposed_answer": {"type": "string"}, - "omitted_unsupported_claims": {"type": "array", "items": {"type": "string"}}, - "unresolved_claims": {"type": "array", "items": {"type": "string"}}, - "profile_used": {"type": "string", "enum": ["standard", "deep"]}, - "deep_trigger": {"type": "string"} - }, - "required": ["claim_ledger", "proposed_answer", "profile_used"] -} -``` - -### Synthesizer dispatch - -Before dispatching, select the inputs from the verified worker records. `WORKER_RECORDS` is an explicit JSON file containing the worker records after routing and verification. The selector follows each researcher's `accepted_attempt`, checks that the matching versioned routing attempt completed with `verification_status: "passed"`, checks the selected artifact's successful researcher envelope, and returns the surviving paths and distinct `angle_id` values. It does not delete or hide omitted artifacts; failed and superseded attempts remain available in the routing record and workspace for diagnostics. - -If fewer than two independent angles survive, take the documented partial-result fallback and do not dispatch a synthesizer. When the threshold is met, pass the returned paths as an explicit array to the extractor: - -#### Bash selection gate -```bash -RESEARCH_SELECTION_JSON="$("$OFFLOAD_ROOT/scripts/select-research-outputs.sh" \ - --workers "$WORKER_RECORDS" \ - --base-dir "")" -SURVIVING_ANGLE_COUNT="$(jq -r '.independent_angle_count' <<<"$RESEARCH_SELECTION_JSON")" -if [ "$SURVIVING_ANGLE_COUNT" -lt 2 ]; then - printf 'Fewer than two verified independent research angles survived; use partial fallback.\n' >&2 -else - ACCEPTED_RESEARCH_OUTPUTS=() - while IFS= read -r selected_file; do - ACCEPTED_RESEARCH_OUTPUTS+=("$selected_file") - done < <(jq -r '.selected_files[]' <<<"$RESEARCH_SELECTION_JSON" | tr -d '\r') -fi -``` - -#### PowerShell selection gate -```powershell -$ResearchSelectionJson = & "$OffloadRoot/scripts/select-research-outputs.ps1" ` - --workers $WorkerRecords ` - --base-dir "" -$ResearchSelection = $ResearchSelectionJson | ConvertFrom-Json -$SurvivingAngleCount = [int]$ResearchSelection.independent_angle_count -if ($SurvivingAngleCount -lt 2) { - [Console]::Error.WriteLine('Fewer than two verified independent research angles survived; use partial fallback.') -} else { - $AcceptedResearcherFiles = @($ResearchSelection.selected_files) -} -``` - -When the selection gate reaches the synthesis branch, dispatch the synthesizer using `--role synthesizer`: - -#### Bash -```bash -MERGED_RESEARCH_FINDINGS="$("$OFFLOAD_ROOT/scripts/extract-structured-output.sh" --array "${ACCEPTED_RESEARCH_OUTPUTS[@]}")" -SYNTH_SCHEMA='{"type":"object","properties":{"claim_ledger":{"type":"array","items":{"type":"object","properties":{"claim_id":{"type":"string"},"claim":{"type":"string"},"citations":{"type":"array","items":{"type":"string"}},"decision_relevance":{"type":"string","enum":["critical","supporting","incidental"]},"status":{"type":"string","enum":["supported","conflicted","unresolved"]},"inferences":{"type":"string"}},"required":["claim_id","claim","citations","decision_relevance","status"]}},"proposed_answer":{"type":"string"},"omitted_unsupported_claims":{"type":"array","items":{"type":"string"}},"unresolved_claims":{"type":"array","items":{"type":"string"}},"profile_used":{"type":"string","enum":["standard","deep"]},"deep_trigger":{"type":"string"}},"required":["claim_ledger","proposed_answer","profile_used"]}' - -"$RUN_AGY_JSON" --role synthesizer --output "/synthesizer.attempt1.json" --error "/synthesizer.attempt1.err" -- \ - -p "Question: . Profile: . Deep trigger: . Researcher findings: $MERGED_RESEARCH_FINDINGS. Build a claim ledger. Discard unsupported incidental claims. Keep decision-relevant gaps as unresolved. Draft a proposed answer referencing claim IDs. Do not edit files. Do not dispatch nested workers." \ - --output-format json \ - --mode plan \ - --json-schema "$SYNTH_SCHEMA" \ - --print-timeout 20m -``` - -#### PowerShell -```powershell -$MergedResearchFindings = & "$OffloadRoot/scripts/extract-structured-output.ps1" --array $AcceptedResearcherFiles -$SynthSchema = '{"type":"object","properties":{"claim_ledger":{"type":"array","items":{"type":"object","properties":{"claim_id":{"type":"string"},"claim":{"type":"string"},"citations":{"type":"array","items":{"type":"string"}},"decision_relevance":{"type":"string","enum":["critical","supporting","incidental"]},"status":{"type":"string","enum":["supported","conflicted","unresolved"]},"inferences":{"type":"string"}},"required":["claim_id","claim","citations","decision_relevance","status"]}},"proposed_answer":{"type":"string"},"omitted_unsupported_claims":{"type":"array","items":{"type":"string"}},"unresolved_claims":{"type":"array","items":{"type":"string"}},"profile_used":{"type":"string","enum":["standard","deep"]},"deep_trigger":{"type":"string"}},"required":["claim_ledger","proposed_answer","profile_used"]}' - -& "$RunAgyJson" --role synthesizer --output "/synthesizer.attempt1.json" --error "/synthesizer.attempt1.err" '--' ` - -p "Question: . Profile: . Deep trigger: . Researcher findings: $MergedResearchFindings. Build a claim ledger. Discard unsupported incidental claims. Keep decision-relevant gaps as unresolved. Draft a proposed answer referencing claim IDs. Do not edit files. Do not dispatch nested workers." ` - --output-format json ` - --mode plan ` - --json-schema $SynthSchema ` - --print-timeout 20m -``` - -Read `structured_output` from the synthesizer JSON response to extract `proposed_answer` and `claim_ledger` for the citation audit. Do not forward the synthesizer's top-level `response`. - -If the audit requires a synthesizer revision, redispatch the same synthesizer worker with `--output "/synthesizer.attempt2.json"` and `--error "/synthesizer.attempt2.err"`. Set its `accepted_attempt` only after the revised output passes the final audit. - -## Stage 3: Independent citation audit - -The auditor is independent. It receives the proposed answer and claim ledger (not the synthesizer's chain-of-thought). - -### Citation audit rules - -The auditor opens each URL cited in the proposed answer and checks: -1. **Resolution.** The URL resolves to the expected source page. -2. **Support.** The source directly supports the associated claim, or supports it via a stated logical inference. -3. **Date fitness.** The publication or update date is appropriate for time-sensitive claims. -4. **Classification.** The source is categorized as primary, secondary, or derivative. -5. **Visibility.** Material conflicts and uncertainties remain visible in the answer. - -### Auditor JSON schema - -```json -{ - "type": "object", - "properties": { - "citation_audits": { - "type": "array", - "items": { - "type": "object", - "properties": { - "citation_url": {"type": "string"}, - "claim_id": {"type": "string"}, - "resolves": {"type": "boolean"}, - "support_verdict": {"type": "string", "enum": ["supports", "partially_supports", "refutes", "unsupported"]}, - "source_classification": {"type": "string", "enum": ["primary", "secondary", "derivative", "unknown"]}, - "independence_notes": {"type": "string"}, - "date_fitness": {"type": "string"}, - "notes": {"type": "string"} - }, - "required": ["citation_url", "claim_id", "resolves", "support_verdict", "source_classification"] - } - }, - "final_status": {"type": "string", "enum": ["pass", "revise", "incomplete"]}, - "claims_to_remove": {"type": "array", "items": {"type": "string"}}, - "claims_to_narrow": {"type": "array", "items": {"type": "string"}}, - "claims_unresolved": {"type": "array", "items": {"type": "string"}} - }, - "required": ["citation_audits", "final_status"] -} -``` - -### Auditor dispatch - -Dispatch the auditor using `--role auditor`: - -#### Bash -```bash -ACCEPTED_SYNTHESIZER_OUTPUT="/synthesizer.attempt.json" -PROPOSED_ANSWER="$(jq -r '.structured_output.proposed_answer' "$ACCEPTED_SYNTHESIZER_OUTPUT")" -CLAIM_LEDGER="$(jq -c '.structured_output.claim_ledger' "$ACCEPTED_SYNTHESIZER_OUTPUT")" -AUDITOR_SCHEMA='{"type":"object","properties":{"citation_audits":{"type":"array","items":{"type":"object","properties":{"citation_url":{"type":"string"},"claim_id":{"type":"string"},"resolves":{"type":"boolean"},"support_verdict":{"type":"string","enum":["supports","partially_supports","refutes","unsupported"]},"source_classification":{"type":"string","enum":["primary","secondary","derivative","unknown"]},"independence_notes":{"type":"string"},"date_fitness":{"type":"string"},"notes":{"type":"string"}},"required":["citation_url","claim_id","resolves","support_verdict","source_classification"]}},"final_status":{"type":"string","enum":["pass","revise","incomplete"]},"claims_to_remove":{"type":"array","items":{"type":"string"}},"claims_to_narrow":{"type":"array","items":{"type":"string"}},"claims_unresolved":{"type":"array","items":{"type":"string"}}},"required":["citation_audits","final_status"]}' - -"$RUN_AGY_JSON" --role auditor --output "/auditor.attempt1.json" --error "/auditor.attempt1.err" -- \ - -p "Audit every citation in the proposed synthesis against live sources. Proposed answer: $PROPOSED_ANSWER. Claim ledger: $CLAIM_LEDGER. Verify each citation URL, check whether it directly supports the claim, classify primary vs derivative, and evaluate date fitness. Do not edit files. Do not dispatch nested workers." \ - --output-format json \ - --mode plan \ - --json-schema "$AUDITOR_SCHEMA" \ - --print-timeout 20m -``` - -#### PowerShell -```powershell -$AcceptedSynthesizerOutput = "/synthesizer.attempt.json" -$SynthJson = Get-Content $AcceptedSynthesizerOutput -Raw | ConvertFrom-Json -$ProposedAnswer = $SynthJson.structured_output.proposed_answer -$ClaimLedger = $SynthJson.structured_output.claim_ledger | ConvertTo-Json -Compress -Depth 10 -$AuditorSchema = '{"type":"object","properties":{"citation_audits":{"type":"array","items":{"type":"object","properties":{"citation_url":{"type":"string"},"claim_id":{"type":"string"},"resolves":{"type":"boolean"},"support_verdict":{"type":"string","enum":["supports","partially_supports","refutes","unsupported"]},"source_classification":{"type":"string","enum":["primary","secondary","derivative","unknown"]},"independence_notes":{"type":"string"},"date_fitness":{"type":"string"},"notes":{"type":"string"}},"required":["citation_url","claim_id","resolves","support_verdict","source_classification"]}},"final_status":{"type":"string","enum":["pass","revise","incomplete"]},"claims_to_remove":{"type":"array","items":{"type":"string"}},"claims_to_narrow":{"type":"array","items":{"type":"string"}},"claims_unresolved":{"type":"array","items":{"type":"string"}}},"required":["citation_audits","final_status"]}' - -& "$RunAgyJson" --role auditor --output "/auditor.attempt1.json" --error "/auditor.attempt1.err" '--' ` - -p "Audit every citation in the proposed synthesis against live sources. Proposed answer: $ProposedAnswer. Claim ledger: $ClaimLedger. Verify each citation URL, check whether it directly supports the claim, classify primary vs derivative, and evaluate date fitness. Do not edit files. Do not dispatch nested workers." ` - --output-format json ` - --mode plan ` - --json-schema $AuditorSchema ` - --print-timeout 20m -``` - -Read `structured_output` from the auditor JSON response to extract `citation_audits` and `final_status`. - -If the auditor needs its one retry for the final audit, use `--output "/auditor.attempt2.json"` and `--error "/auditor.attempt2.err"` with the same auditor worker ID. Record that attempt separately, set the auditor's `accepted_attempt` after the final audit passes, and use its explicitly selected artifact for audit validation and the final report. - -### Audit verification and acceptance rules - -Before accepting the synthesis, mechanically validate audit coverage and verdict consistency: - -#### Bash -```bash -ACCEPTED_AUDITOR_OUTPUT="/auditor.attempt.json" -"$OFFLOAD_ROOT/scripts/check-citation-audit.sh" \ - --ledger "$ACCEPTED_SYNTHESIZER_OUTPUT" \ - --auditor "$ACCEPTED_AUDITOR_OUTPUT" -AUDIT_STATUS=$? -``` - -#### PowerShell -```powershell -$AcceptedAuditorOutput = "/auditor.attempt.json" -& "$OffloadRoot/scripts/check-citation-audit.ps1" ` - --ledger $AcceptedSynthesizerOutput ` - --auditor $AcceptedAuditorOutput -$AuditStatus = $LASTEXITCODE -``` - -Audit validation enforces mechanical acceptance contracts across both shells: -1. **Required claim/citation pair coverage**: Every citation URL listed under each claim in the claim ledger forms a required `(claim_id, citation_url)` pair. Two citations for one claim require separate audit coverage. -2. **Exact coverage**: A nonempty required pair set rejects empty or partial `citation_audits` even when `final_status` is `pass`. Duplicate and unknown claim/citation pairs are rejected. -3. **Verdict consistency for automated acceptance**: Before automated acceptance (`exit 0`), every required pair must have `resolves: true` and `support_verdict: "supports"`. Failed entries (`resolves: false`, non-supporting verdicts `partially_supports`, `refutes`, `unsupported`) or unresolved entries (`claims_to_remove`, `claims_to_narrow`, `claims_unresolved`) cannot coexist with an accepted overall `pass`. -4. **Ledger with no auditable pairs**: By default, research assignments require citations. A ledger with no auditable pairs cannot bypass citations required by the research assignment; automated acceptance is rejected. If an explicit documented assignment branch permits citation-free findings, `--allow-empty` must be explicitly specified and requires empty `citation_audits`. -5. **Workflow branching**: - - `exit 0` (`pass`): Valid complete coverage with supported verdicts. The synthesis is accepted. Label supported claims as `audited` in the final report. - - `exit 1` (`revise`): Valid complete coverage where the auditor requested revision. The synthesizer may perform **one** revision pass to narrow or remove rejected claims (consuming the synthesizer's second attempt, attempt 2). The revised output undergoes one final audit (consuming the auditor's second attempt, attempt 2). - - `exit 2` (`invalid`): Malformed response, partial coverage, duplicate/unknown pairs, contradictory verdicts, or zero pairs when citations required. Triggers one bounded retry of the failing worker using `--route default` (if attempt 1) or falls back to direct orchestrator review or `partial` status. - -Do not enter open-ended revision loops. If the second audit fails or exhausts the retry budget, omit incidental unsupported claims or mark decision-relevant claims as unresolved and transition the run to `partial` status. - -## Failure handling and partial results - -Follow the shared recovery, retry accounting, and failure handling rules in [`SKILL.md`](../SKILL.md): - -- **Stable worker IDs and retry ceiling.** Assign a stable `worker_id` to each assignment (researcher angle, synthesizer, auditor). Attempt 1 is initial dispatch; attempt 2 is its only permitted retry. Maximum two attempts total per assignment. -- **Outcome tracking.** Record each attempt and verification outcome in `routing-outcomes.json`. -- **Researcher failure.** If a researcher crashes, times out, or produces unparsable output, retry once with the error details using `--route default`. The selection gate admits only the verified accepted attempt for each assignment. If a retry fails, synthesis proceeds as long as at least two distinct `angle_id` values remain; otherwise use the partial-result fallback. The final report explicitly names any omitted angle. -- **Synthesis or audit failure.** Synthesis and citation audit are mandatory stages. The allowed synthesizer revision pass consumes the synthesizer's second attempt. The subsequent audit consumes the auditor's second attempt. If either stage crashes, times out, returns unparsable JSON, or fails to resolve citations after exhausting its 2-attempt budget, the run transitions to `partial` status. -- **Partial result contract.** A `partial` run returns audited claims and raw findings collected up to the point of failure, but strictly withholds a firm synthesis or recommendation. State the failed stage explicitly and retain all raw artifacts for debugging. -- **Quota exhaustion.** Explicit adapter-reported quota exhaustion triggers immediate quota handoff per [`SKILL.md`](../SKILL.md). Do not retry or switch models. Preserve completed artifacts and return unfinished work to the calling orchestrator. - -## Provenance and cleanup - -Browser, GUI, rendering, and other externally observable headless claims require a reality anchor: an explicit artifact type and path or artifact identifier, plus the claim or acceptance criterion it supports. Accept screenshots, DOM snapshots, network captures, console logs, rendered files, or equivalent regular files inside the disposable workspace or owned output; missing or out-of-scope anchors are unverified. Before publishing provenance, `final.md`, or a handoff/report, recursively redact credential-shaped values with stable `[REDACTED]` markers; leave raw scratch evidence unchanged. - -At the conclusion of the research run: - -1. **Assemble provenance.** Validate and generate `provenance.json` using the matching provenance helper. Each entry in the `workers` array may optionally include a `routing` container (`{schema_version: 1, attempts: [...]}`) retaining all attempts for that worker from `routing-outcomes.json` (canonical fixture: [`tests/fixtures/routing-worker.json`](../tests/fixtures/routing-worker.json)): - - ```json - { - "id": "researcher-web-1", - "role": "researcher", - "status": "completed", - "output": "workspace/researcher-web-1.attempt2.json", - "accepted_attempt": 2, - "routing": { - "schema_version": 1, - "attempts": [ - { - "worker_id": "researcher-web-1", - "role": "researcher", - "mode": "web-research", - "attempt": 1, - "policy_revision": "2026-09-04.1", - "route": "default", - "adapter": "agy", - "adapter_revision": "adapter-revision", - "vendor": "vendor-family", - "model_id": "exact-model-id", - "model": "exact-model-id", - "family_hint": "family-hint", - "preference": "balanced", - "effort": "high", - "catalog_revision": "catalog-revision", - "selection_reason": "Eligible catalog candidate ranked highest for the role preference", - "reason": "Initial default dispatch", - "started_at": "2026-09-03T00:00:00Z", - "ended_at": "2026-09-03T00:01:30Z", - "duration_seconds": 90.0, - "exit_code": 1, - "state": "failed", - "failure_class": "quality", - "verification_status": "failed", - "evidence_paths": [ - "workspace/researcher-web-1.attempt1.json", - "workspace/researcher-web-1.attempt1.err" - ], - "usage": { - "prompt_tokens": 1000, - "candidates_tokens": 250, - "unit": "tokens" - } - }, - { - "worker_id": "researcher-web-1", - "role": "researcher", - "mode": "web-research", - "attempt": 2, - "policy_revision": "2026-09-04.1", - "route": "default", - "adapter": "agy", - "adapter_revision": "adapter-revision", - "vendor": "vendor-family", - "model_id": "exact-model-id", - "model": "exact-model-id", - "family_hint": "family-hint", - "preference": "balanced", - "effort": "high", - "catalog_revision": "catalog-revision", - "selection_reason": "Pinned selection retained after a retry", - "reason": "Retry authorized after quality gate failure on attempt 1", - "started_at": "2026-09-03T00:02:00Z", - "ended_at": "2026-09-03T00:03:30Z", - "duration_seconds": 90.0, - "exit_code": 0, - "state": "completed", - "failure_class": "none", - "verification_status": "passed", - "evidence_paths": [ - "workspace/researcher-web-1.attempt2.json", - "workspace/researcher-web-1.attempt2.err" - ], - "usage": { - "prompt_tokens": 1200, - "candidates_tokens": 300, - "unit": "tokens" - } - } - ] - } - } - ``` - - - #### Bash - ```bash - "$OFFLOAD_ROOT/scripts/collect-provenance.sh" \ - --run-id "" \ - --request-summary "" \ - --selected-mode "web-research" \ - --profile "" \ - --deep-trigger "" \ - --start-time "" \ - --end-time "" \ - --duration-seconds "" \ - --scratch-path "" \ - --workers '' \ - --final-citations '' \ - --audit-verdicts '' \ - --final-status "" \ - --incomplete-stage-reasons '' \ - --output "/provenance.json" - ``` - - #### PowerShell - ```powershell - & "$OffloadRoot/scripts/collect-provenance.ps1" ` - --run-id "" ` - --request-summary "" ` - --selected-mode "web-research" ` - --profile "" ` - --deep-trigger "" ` - --start-time "" ` - --end-time "" ` - --duration-seconds "" ` - --scratch-path "" ` - --workers '' ` - --final-citations '' ` - --audit-verdicts '' ` - --final-status "" ` - --incomplete-stage-reasons '' ` - --output "/provenance.json" - ``` - -2. **Save final result.** Write `/final.md` from the explicitly accepted synthesizer and auditor artifacts (and the selected researcher outputs they consumed), or from the retained partial findings. Never glob raw worker JSON when assembling the report. -3. **Run cleanup helper.** Execute the matching cleanup helper: - - #### Bash - ```bash - "$OFFLOAD_ROOT/scripts/cleanup-research-workspace.sh" --workspace "" --status "" - ``` - - #### PowerShell - ```powershell - & "$OffloadRoot/scripts/cleanup-research-workspace.ps1" --workspace "" --status "" - ``` - - - On `success`, the helper retains `final.md`, `provenance.json` when present, `routing-outcomes.json`, the workspace marker, and `evidence-disposition.json`. The disposition manifest records every evidence path from the routing record, its pre-cleanup existence, a SHA-256 hash for existing regular files, and a `retained`, `pruned`, `missing`, or safety-driven `uninspected` disposition. Raw intermediate worker JSON files and the temporary repository snapshot are still pruned by default. - - On `partial` or failed status, the helper preserves all raw artifacts, worker logs, and repository snapshots for debugging. - -## Research-then-implementation handoff - -When research precedes code implementation (`modes/execution.md`): - -1. Complete the full research workflow, synthesis, and citation audit. -2. Distill the verified research into a compact specification, audited claim ledger, and `provenance.json`. -3. Hand only the compact specification to `modes/execution.md`. Never feed raw multi-turn research transcripts to implementation workers. -4. If research concludes with a `partial` status, do not begin execution unless the user explicitly reviews and accepts the identified gaps. diff --git a/scripts/agy-adapter.ps1 b/scripts/agy-adapter.ps1 deleted file mode 100644 index 14fba42..0000000 --- a/scripts/agy-adapter.ps1 +++ /dev/null @@ -1,286 +0,0 @@ -#!/usr/bin/env pwsh -# Reference worker adapter. Vendor-specific AGY syntax lives here, not in the launcher. - -$ErrorActionPreference = 'Stop' -Set-StrictMode -Version 3.0 - -function Fail([string]$message, [int]$exitCode = 2) { - [Console]::Error.WriteLine("ERROR: $message") - exit $exitCode -} - -function Resolve-Program([string]$path) { - if ([string]::IsNullOrWhiteSpace($path)) { Fail 'AGY_BIN is empty' } - if ($path.EndsWith('.ps1', [System.StringComparison]::OrdinalIgnoreCase)) { - return @{ File = (Get-Command pwsh -ErrorAction Stop).Source; Prefix = @('-NoProfile', '-NonInteractive', '-File', $path) } - } - return @{ File = $path; Prefix = @() } -} - -function Invoke-Captured([string]$file, [string[]]$arguments, [string]$stdoutPath, [string]$stderrPath, [int]$timeoutMilliseconds = 0) { - $psi = [System.Diagnostics.ProcessStartInfo]::new() - $psi.FileName = $file - $psi.UseShellExecute = $false - $psi.RedirectStandardOutput = $true - $psi.RedirectStandardError = $true - foreach ($argument in $arguments) { [void]$psi.ArgumentList.Add($argument) } - $process = [System.Diagnostics.Process]::new() - $process.StartInfo = $psi - try { - if (-not $process.Start()) { Fail "failed to start adapter command: $file" 127 } - $stdoutTask = $process.StandardOutput.ReadToEndAsync() - $stderrTask = $process.StandardError.ReadToEndAsync() - $timedOut = $false - if ($timeoutMilliseconds -gt 0) { - if (-not $process.WaitForExit($timeoutMilliseconds)) { - $timedOut = $true - try { $process.Kill($true) } catch { } - $process.WaitForExit() - } - } else { - $process.WaitForExit() - } - [System.IO.File]::WriteAllText($stdoutPath, $stdoutTask.Result, [System.Text.Encoding]::UTF8) - [System.IO.File]::WriteAllText($stderrPath, $stderrTask.Result, [System.Text.Encoding]::UTF8) - return [pscustomobject]@{ Code = $process.ExitCode; TimedOut = $timedOut } - } finally { - $process.Dispose() - } -} - -function Get-FamilyHint([string]$modelId) { - if ($modelId -match '^gemini-[^-]+-(?flash|pro)-') { return $Matches.family } - if ($modelId -match '^claude-[^-]+-(?opus|sonnet|haiku)') { return $Matches.family } - if ($modelId -match '^gpt-oss-') { return 'oss' } - return 'unknown' -} - -function Get-PreferenceScore([string]$family, [string]$preference) { - $scores = @{ - fast = @{ flash = 1; haiku = 2; oss = 2; sonnet = 3; pro = 4; opus = 5; unknown = 100 } - balanced = @{ sonnet = 1; flash = 2; oss = 3; pro = 3; haiku = 4; opus = 5; unknown = 100 } - deep = @{ opus = 1; pro = 2; sonnet = 3; oss = 4; flash = 5; haiku = 6; unknown = 100 } - } - if ($scores.ContainsKey($preference) -and $scores[$preference].ContainsKey($family)) { return $scores[$preference][$family] } - return 100 -} - -function Get-UsageGroupForModel([string]$modelId) { - if ($modelId -match '^gemini-') { return 'gemini' } - if ($modelId -match '^(claude-|gpt-)') { return 'claude-and-gpt' } - return '' -} - -function Get-UsageGroup([string]$name) { - $normalized = ([string]$name).ToLowerInvariant() - if ($normalized -match 'gemini') { return 'gemini' } - if ($normalized -match 'claude' -and $normalized -match 'gpt') { return 'claude-and-gpt' } - return '' -} - -function Get-NormalizedResetTime($value) { - if ($null -eq $value -or [string]::IsNullOrWhiteSpace([string]$value)) { return '' } - $parsed = [DateTimeOffset]::MinValue - if (-not [DateTimeOffset]::TryParse([string]$value, [Globalization.CultureInfo]::InvariantCulture, [Globalization.DateTimeStyles]::AssumeUniversal, [ref]$parsed)) { return '' } - return $parsed.ToUniversalTime().ToString("yyyy-MM-dd'T'HH:mm:ss'Z'") -} - -function Get-UsageSnapshot([string]$raw) { - $snapshot = [ordered]@{ - observed_at = '' - reason = 'AGY usage probe did not expose supported group-level usage' - groups = @{} - } - $document = $null - try { $document = ConvertFrom-Json -InputObject $raw -Depth 30 -ErrorAction Stop } - catch { - $snapshot.reason = 'AGY usage probe returned malformed JSON' - return [pscustomobject]$snapshot - } - $status = if ($document.PSObject.Properties['status']) { [string]$document.status } else { '' } - if ($status -notin @('SUCCESS', 'success')) { - $snapshot.reason = 'AGY usage probe returned a non-success status' - return [pscustomobject]$snapshot - } - - $groups = @() - $command = if ($document.PSObject.Properties['command']) { $document.command } else { $null } - if ($null -ne $command -and $command.PSObject.Properties['data'] -and $null -ne $command.data -and $command.data.PSObject.Properties['groups']) { - $groups = @($command.data.groups) - } elseif ($null -ne $command -and $command.PSObject.Properties['groups']) { - $groups = @($command.groups) - } elseif ($document.PSObject.Properties['groups']) { - $groups = @($document.groups) - } - $recognizedGroups = 0 - foreach ($group in $groups) { - if ($null -eq $group) { continue } - $groupName = if ($group.PSObject.Properties['id']) { [string]$group.id } elseif ($group.PSObject.Properties['name']) { [string]$group.name } else { '' } - $groupKey = Get-UsageGroup $groupName - if ([string]::IsNullOrWhiteSpace($groupKey)) { continue } - $recognizedGroups++ - $scopes = [System.Collections.Generic.List[object]]::new() - if (-not $group.PSObject.Properties['buckets']) { continue } - foreach ($bucket in @($group.buckets)) { - if ($null -eq $bucket -or -not $bucket.PSObject.Properties['id'] -or -not $bucket.PSObject.Properties['window'] -or -not $bucket.PSObject.Properties['remaining_fraction'] -or -not $bucket.PSObject.Properties['reset_time']) { continue } - $bucketId = [string]$bucket.id - $window = [string]$bucket.window - $remaining = 0.0 - if ([string]::IsNullOrWhiteSpace($bucketId) -or [string]::IsNullOrWhiteSpace($window) -or -not [double]::TryParse([string]$bucket.remaining_fraction, [Globalization.NumberStyles]::Float, [Globalization.CultureInfo]::InvariantCulture, [ref]$remaining) -or $remaining -lt 0 -or $remaining -gt 1) { continue } - $resetAt = Get-NormalizedResetTime $bucket.reset_time - if ([string]::IsNullOrWhiteSpace($resetAt)) { continue } - $scopes.Add([ordered]@{ - scope_id = $bucketId - window = $window - remaining_units = $remaining - reserved_units = 0 - reset_at = $resetAt - }) - } - if ($scopes.Count -gt 0) { $snapshot.groups[$groupKey] = @($scopes) } - } - if ($snapshot.groups.Count -eq 0) { - if ($recognizedGroups -gt 0) { $snapshot.reason = 'AGY usage probe returned no valid group-level usage bucket' } - return [pscustomobject]$snapshot - } - $snapshot.observed_at = [DateTime]::UtcNow.ToString("yyyy-MM-dd'T'HH:mm:ss'Z'") - $snapshot.reason = '' - return [pscustomobject]$snapshot -} - -function Get-Preflight($usageSnapshot, [string]$usageGroup) { - $usageReason = [string]$usageSnapshot.reason - $observedAt = [string]$usageSnapshot.observed_at - if (-not [string]::IsNullOrWhiteSpace($usageGroup) -and $usageSnapshot.groups.Contains($usageGroup) -and @($usageSnapshot.groups[$usageGroup]).Count -gt 0) { - $usageReason = 'AGY usage exposes group-level fractions without protocol capacity units or reservation data' - } elseif ([string]::IsNullOrWhiteSpace($usageReason)) { - $usageReason = if ([string]::IsNullOrWhiteSpace($usageGroup)) { 'AGY model ID is not mapped to a supported usage group' } else { "AGY usage probe returned no valid usage bucket for model group '$usageGroup'" } - } - return [ordered]@{ - access = [ordered]@{ state = 'unknown'; reason = 'AGY headless discovery does not expose a non-secret account identifier'; account_ref = '' } - entitlement = [ordered]@{ state = 'unknown'; reason = 'AGY headless discovery does not expose model entitlement'; billing_route = 'unknown' } - usage = [ordered]@{ state = 'unknown'; reason = $usageReason; source = 'agy-usage'; observed_at = $observedAt; scopes = @() } - } -} - -function Convert-ModelListToCatalog([string]$raw, $usageSnapshot) { - $models = @( - foreach ($line in ($raw -split "`r?`n")) { - if ($line -notmatch '^\s*(?\S+)\s+(?