From 69c46f3083479d2d1b7344dcee7557cd49cbb99c Mon Sep 17 00:00:00 2001 From: Dayowe Date: Sat, 19 Sep 2026 19:41:11 +0200 Subject: [PATCH] Refine worker lifecycle and resource safeguards; release staged-implementation 0.1.5 --- .../.codex-plugin/plugin.json | 2 +- plugins/staged-implementation/README.md | 14 +++++ .../skills/implementer/SKILL.md | 6 +- .../skills/orchestrator/SKILL.md | 61 +++++++++---------- .../references/resource-lifecycle.md | 33 ++++++++++ .../skills/planner/SKILL.md | 12 +++- .../skills/validator/SKILL.md | 8 +++ 7 files changed, 101 insertions(+), 35 deletions(-) create mode 100644 plugins/staged-implementation/skills/orchestrator/references/resource-lifecycle.md diff --git a/plugins/staged-implementation/.codex-plugin/plugin.json b/plugins/staged-implementation/.codex-plugin/plugin.json index 5fbc8e5..8dc24d5 100644 --- a/plugins/staged-implementation/.codex-plugin/plugin.json +++ b/plugins/staged-implementation/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "staged-implementation", - "version": "0.1.4", + "version": "0.1.5", "description": "Planner, implementer, validator, and orchestrator skills for staged implementation workflows.", "author": { "name": "Local developer" diff --git a/plugins/staged-implementation/README.md b/plugins/staged-implementation/README.md index eb15ec5..29f07ca 100644 --- a/plugins/staged-implementation/README.md +++ b/plugins/staged-implementation/README.md @@ -105,6 +105,20 @@ The usual flow is: 3. Use `validator` when runtime, UI, API, integration, or regression evidence is needed. 4. Use `orchestrator` when you want Codex to coordinate the loop across chunks. +## Lifecycle and Context Efficiency + +The workflow keeps implementation and validation rigor while avoiding avoidable context churn: + +- Each worker carries stable chunk/assignment IDs, with a recorded mapping to a supported unique task label when available. Same-worker corrections retain the ID; replacement workers increment the attempt. +- An implementer may remain available for same-chunk repairs but cannot write during validation. Replacements acquire write ownership only after prior writes stop and the candidate, findings and resources are verified and transferred. +- Accepted/permanently blocked assignments retire after handoff: stop work and dispatch, close when supported, otherwise establish inactivity. Retained exceptions need a purpose/release condition; safe independent chunks may overlap with explicit ownership and isolation. Idle availability alone does not demonstrate token expense. +- Workers return one compact packet and stop until a concrete follow-up. Avoid acknowledgement chatter; retain justified liveness checks, intervention and blocker reporting. +- The existing durable handoff stays compact while preserving pending gates, dependencies, recovery obligations and authority restrictions directly or through authoritative links. +- Parent review starts from the actual diff, requirements and evidence, inspecting surrounding code, callers and shared behavior as needed without waiting for a discovered defect. +- Read the resource reference for initial persistence verification before edits and before substantial allocations (including large builds in the main checkout), worktree/resource management or cleanup. Reuse applicable instructions and verified setup rather than reloading them for routine steps. + +These are efficiency rules, not acceptance shortcuts. Required independent validation, fresh gates, contract checks and evidence remain mandatory where the task requires them. + ## Notes - The skills are intentionally separate. Keeping the roles separate makes the boundaries clearer and reduces accidental scope widening. diff --git a/plugins/staged-implementation/skills/implementer/SKILL.md b/plugins/staged-implementation/skills/implementer/SKILL.md index ad5c319..6792463 100644 --- a/plugins/staged-implementation/skills/implementer/SKILL.md +++ b/plugins/staged-implementation/skills/implementer/SKILL.md @@ -20,7 +20,7 @@ Expect either: - a saved implementer prompt path, plus repo root when not obvious - or a complete in-chat implementer prompt -The prompt should define scope, non-goals, requirements, invariants, validation, and test posture. If any required contract, symbol, endpoint, data source, output path, or validation target is unclear, stop and ask. Do not guess. +The prompt should define scope, non-goals, requirements, invariants, validation, and test posture. Under orchestration it should also carry a stable `Chunk ID`, `Assignment ID`, and assignment mode (`new-chunk`, `correction`, or `replacement`) so the parent can distinguish same-chunk repair from next-chunk work. If any required contract, symbol, endpoint, data source, output path, or validation target is unclear, stop and ask. Do not guess. ## Workflow @@ -71,6 +71,7 @@ The prompt should define scope, non-goals, requirements, invariants, validation, - Confirm unaffected behavior was preserved when the prompt requires it. 7. Report results. + - Echo the supplied chunk/assignment IDs and assignment mode when present. - Summarize changed files and behavior. - Distinguish fresh validation from verified reused evidence; give concise differences, counts, failures, skipped cases/limits and artifact paths instead of repeating unchanged inventories or full logs. Retain raw evidence and prior candidate provenance; inspect failures/unexpected output. Briefly explain recurring setup failures or repeated checks in this report. Apply process improvements prospectively without repackaging historical evidence. - Hand off owned temporary paths, active processes, retained evidence/recovery needs and disposable candidates to the parent. Do not remove a build/check-out needed by validation or a later gate merely because implementation ended. @@ -82,6 +83,8 @@ The prompt should define scope, non-goals, requirements, invariants, validation, Complete routine steps within the assignment without repeated parent acknowledgements. Promptly report blockers, material findings and ownership conflicts; candidate release, shared-resource acquisition, scope changes and required approvals remain coordination points. Completion does not release resources. For a bounded correction, verify the original assignment/current candidate and apply the delta with required revalidation instead of recreating still-valid artifacts. Preserve required user updates. Correctness obligations take priority over token savings. +After returning a complete result, stop and wait for a concrete follow-up. Do not poll the parent/validator, pre-emptively inspect the next chunk, continue exploratory work, or generate additional summaries/evidence unless assigned. As the same-chunk repair agent, write only after the parent releases the validation hold and assigns the correction. For replacement, relinquish writes and hand off owned operations/resources; the replacement must wait for the parent's verified ownership transfer before editing. Retirement ends assigned work even if the runtime leaves the worker open; it does not release retained resources. + An authorized orchestration run includes routine cleanup of its tracked, disposable temporary resources; the parent passes that bounded scope and any restrictions into the assignment. Clean only exact assigned run-owned resources after parent/consumer release, without a separate user approval within that scope. Verify ownership and path boundaries, preserve required evidence in a verified durable location with updated references, and release owned processes first. Never sweep `/tmp`, follow links into unrelated locations, prune shared caches, remove files predating the run or force-remove uncommitted work. Standalone implementation permission does not grant this orchestration scope. Without applicable authority or with uncertain retention, leave paths recorded and request clarification; retention/no-deletion instructions and pauses remain binding. - Treat questions, observations, and suggestions as analysis-only unless the user explicitly asks for code or patches. @@ -109,6 +112,7 @@ Do not silently broaden the test strategy in a way that changes project structur Keep the final response concise and factual: - ready for review | blocked | incomplete; candidate baseline plus scoped changes/build identity as applicable, not self-acceptance +- chunk/assignment IDs and assignment mode when supplied - changed files and behavior - fresh/reused validation, failures and missing evidence - blockers, ambiguities, or residual risk diff --git a/plugins/staged-implementation/skills/orchestrator/SKILL.md b/plugins/staged-implementation/skills/orchestrator/SKILL.md index d02131f..8ab437c 100644 --- a/plugins/staged-implementation/skills/orchestrator/SKILL.md +++ b/plugins/staged-implementation/skills/orchestrator/SKILL.md @@ -20,6 +20,7 @@ Prefer a task packet containing: - repo root - project instruction docs, if not discoverable from the repo - feature/fix name or slug +- stable chunk IDs and a run-state/handoff path, or permission to create one beside the plan/checklist - plan path - implementation checklist path - prompt map path @@ -50,7 +51,7 @@ Before delegating implementation, run a readiness preflight: 1. Establish current state. - Read project instructions first. - Establish context from the plan, checklist, prompt map, current handoff/review and relevant git/worktree state. On continuation, read changed instructions/contracts and affected scope rather than reloading unchanged history. - - Before delegating edits, establish persistent implementation and evidence locations under **Persistent Workspaces**. On resume, verify the actual candidate files and backing Git metadata before using previous reports or continuing dependent work. + - Before delegating edits, establish persistent implementation and evidence locations under **Resource Lifecycle**. On resume, verify the actual candidate files and backing Git metadata before using previous reports or continuing dependent work. - Before initial implementation delegation, verify the reviewed planning package against its checkpoint and actual working files. If relevant planning changes remain uncommitted, honor an explicit uncommitted disposition or applicable planning-checkpoint authorization; otherwise finish applicable document checks, identify the exact files and proposed commit, and ask before proceeding. Planning-checkpoint permission and accepted-chunk commit permission are separate. Exclude unrelated changes; do not repeat a resolved checkpoint request or turn routine execution-status updates into a new planning checkpoint gate. Record the verified baseline, including relevant uncommitted inputs when explicitly allowed. - Read any existing readiness audit. If no readiness audit exists, create one before writing the first implementer prompt. - Initially classify every chunk as `ready`, `blocked-by-contract-decision`, `blocked-by-dependency`, `blocked-by-environment`, or `needs-small-freeze-before-prompt`. Subsequently verify affected entries/dependencies; broaden when a shared contract changes or applicability is uncertain. @@ -67,12 +68,14 @@ For each authorized ready chunk: 3. Write the implementer prompt. - Produce one surgical prompt for that chunk only. + - Give the pass a stable `Chunk ID`, `Assignment ID` and mode under **Run State and Worker Lifecycle**. - Save official prompts beside the companion plan/checklist unless the user requests another output path. - Re-read the saved prompt before delegating. 4. Delegate implementation. - Spawn a fresh implementer sub-agent when possible. - Give the sub-agent the saved prompt and explicitly tell it to use `$implementer`. + - Use a supported task label mapped to the assignment ID under **Run State and Worker Lifecycle**. - Pass only the context needed for that chunk. - Tell the sub-agent not to commit and to report changed files, validation, blockers, and proposed commit message. @@ -86,7 +89,7 @@ For each authorized ready chunk: 6. Handle review outcome. - If contract ambiguity exists, hold the affected chunk and identify the exact missing decision; apply **Stopping Conditions** before continuing other work. - If implementation violates the prompt or frozen contracts and the docs are clear, write a surgical follow-up prompt. - - Send the follow-up to the same implementer sub-agent when continuity helps; spawn a new implementer if a fresh pass is safer. + - Reuse the designated repair agent when continuity helps; if a fresh pass is safer, follow the replacement ownership-transfer procedure under **Run State and Worker Lifecycle** before permitting edits. - Repeat review/follow-up until accepted, blocked, or stopped by the user. 7. Validate when evidence is required. @@ -102,13 +105,24 @@ For each authorized ready chunk: - Confirm no out-of-scope work remains. - Apply the explicit commit policy. - Use the chunk's proposed commit message when acceptable; otherwise write a one-line commit message with the chunk ID prefix when one exists. + - Retire the chunk's workers under **Run State and Worker Lifecycle**, recording any justified retention exception before further delegation. 9. Continue. - - Update one live handoff and the chunk's current outcome; update checklist/map/readiness entries when their state/dependencies change, without copying the running journal into each artifact. - - Reconcile temporary-resource ownership/retention and perform eligible authorized cleanup under **Temporary Resources and Cleanup** before the next large allocation. + - Update the existing live handoff and the chunk's current outcome; update checklist/map/readiness entries when their state/dependencies change, without copying the running journal into each artifact. + - Reconcile temporary-resource ownership/retention and perform eligible authorized cleanup under **Resource Lifecycle** before the next large allocation. - Choose the next ready chunk. - Stop when all chunks are complete, blocked, or no ready chunk remains. +## Run State and Worker Lifecycle + +Use the existing durable handoff as one compact continuation record, not a second status system. Update it in place with current chunk/assignment IDs, candidate/baseline identity, worker ownership, unresolved findings/blockers, evidence pointers, retained resources, next ready work and one-line accepted outcomes/commit IDs. Preserve outstanding gates, dependencies, recovery/retention obligations and authority restrictions directly or through clear authoritative links, including obligations needed only later. Do not carry accepted-chunk narratives, full logs or superseded findings into later assignments unless a dependency or regression requires them. + +Attribute every worker assignment to a stable chunk and role with a canonical ID such as `::`. Use implementer modes `new-chunk | correction | replacement` and validator modes `validation | revalidation | replacement`. Same-worker corrections/revalidation retain the assignment ID; a fresh replacement increments the attempt. A next-chunk worker uses the new chunk's ID. Where task labels are supported, use the canonical ID only if valid for that tool; otherwise choose a supported unique label (for example, `o_03_implementer_1` for `O-03:implementer:1`). Record the assignment-to-label/worker mapping once in the handoff; check label collisions and do not assume telemetry can decode an unsupported format. + +The implementer may remain available as the same-chunk repair agent during validation, but must not write until the parent releases the validation hold and assigns a correction. Before a replacement edits, establish that the prior worker and its owned operations have stopped writing; verify the actual candidate, transfer relevant findings/resources, retire the superseded assignment and designate the replacement as sole writer. A recorded transfer alone does not establish that writes stopped. An unresolved validation hold still prevents replacement edits. + +At acceptance or permanent block, transfer required responsibilities and retire the workers: stop further assigned work, remove them from dispatch and close them when supported. If closure is unavailable, use supported controls to establish inactivity and record retirement; do not claim interruption closed a worker or released its processes/resources. Preserve held source and evidence. Any retention exception needs a purpose and release condition. Safe independent chunks may overlap with recorded ownership and candidate isolation; do not serialize them merely because another worker remains available. Retained workers receive no unrelated next-chunk work. Idle availability alone is not evidence of token consumption. + ## Readiness Audit Rules The readiness audit exists to resolve blockers before implementation, not during the first failed prompt. @@ -138,6 +152,9 @@ Every implementer prompt must include: ```text Repo root: +Chunk ID: +Assignment ID: +Assignment mode: new-chunk | correction | replacement Read these first: Task: Scope for this pass: @@ -188,6 +205,8 @@ For new implementer and independent-validator assignments, default to fresh scop Dispatch complete bounded assignments so workers can finish already-authorized routine steps without acknowledgement chatter. Coordinate candidate release, shared-resource acquisition, scope changes and required approvals explicitly; a completion notification does not release a workspace. Prefer completion notifications or interruptible waits, with proportionate polling when necessary. Preserve required user updates and immediate blocker/material-finding reports; do not add a permanent monitoring loop or wait so long that intervention is prevented. +Do not routinely send status-only prompts to a worker with a complete assignment. A wait timeout alone does not justify an acknowledgement or context replay; use notifications, independent safe work or an interruptible wait compatible with required user updates. Perform a proportionate liveness check when expected progress, a tool failure or other evidence suggests the worker is stuck; prefer available status information before prompting. Necessary intervention and blocker reporting remain required. + When spawning an implementer sub-agent: - start with a fresh sub-agent for each new chunk by default @@ -200,13 +219,13 @@ When spawning an implementer sub-agent: - pass cleanup scope, retention requirements and disk/allocation restrictions; require workers to report exact owned resource paths and outstanding consumers on handoff - avoid delegating planner/reviewer decisions - wait only when the result is needed for the next critical-path step -- close sub-agents when their chunk is accepted or permanently blocked If sub-agent edits are not inspectable as the actual candidate diff, hold that chunk and report the integration limitation instead of reviewing a summary as if it were a diff. Apply **Stopping Conditions** before continuing other work. When invoking a validator pass: - instruct it to use `$validator` +- give it the same chunk ID and a validator assignment ID/mode with the supported task-label mapping under **Run State and Worker Lifecycle** - provide the exact expected behavior, frozen contracts and candidate identity: baseline revision plus scoped changes (including relevant untracked inputs), and the relevant build/artifact and its source provenance - release implementer writes before validation; prevent overlapping writes to the validated scope, relevant harness/configuration inputs, or replacement of the tested build/target until the pass is released - provide approved credential or environment sources only when needed @@ -224,6 +243,8 @@ Efficiency changes organization and communication, not what must be understood, Keep roles distinct: implementer self-audit; parent actual-diff/integration/contract review; validator independent checks of assigned behavior/risks. Do not automatically add a general reviewer for each correction. Reuse a validator for bounded corrections while context remains valid; a changed mechanism, disputed finding, new risk or explicit gate may require a fresh challenge. All mandated independent reviews remain required. +For parent review, start with the actual scoped diff, frozen requirements and relevant evidence. Inspect surrounding code, callers and shared behavior as needed to assess impact; do not wait for a discovered defect to justify broader reading. Avoid repeatedly rereading unchanged full files or rerunning successful worker checks merely to restate evidence. Run parent-owned checks when required for acceptance, when worker evidence is missing/stale/uncertain, or when an independent check directly reduces a concrete risk. + Reuse reliable verification helpers and a canonical candidate-scoped input record where useful; verify their coverage/applicability rather than rebuilding them per worker. Keep prior candidate provenance intact when inputs change, and keep concurrent candidates separate. Create only the smallest missing helper when justified, not a mandatory evidence framework. Before expensive checks, preflight relevant paths, tool versions, generated prerequisites and file-type/symlink handling. Recheck changed or uncertain setup; preflight does not replace behavioral assertions. Validators independently verify inputs and expected outcomes against the frozen contract, not an unexamined helper or previous verdict. For same-contract corrections, reference the original assignment and current candidate, then send the concrete finding, affected scope, required revalidation and proposed evidence reuse. Do not regenerate valid assignments, matrices, environment audits or evidence packages. A replacement worker needs enough baseline context to interpret the delta. Group coherent findings from the current review when practical, but report urgent safety/contract blockers immediately. Reuse only after verifying relevant source, harness, dependencies, build configuration and environment match, preserving original limits. A commit ID alone is insufficient. Rerun if applicability is uncertain; shared owners/styles may affect many consumers. Required fresh checks cannot be skipped. @@ -234,35 +255,13 @@ Batch compatible independent reads/mechanical checks and inspect every result to Report concise differences, counts, failures, skipped/not-tested obligations, evidence limits and artifact paths; retain raw logs/artifacts and inspect unexpected output. Link any existing canonical input record and detailed results instead of regenerating/reproducing unchanged inventories, hashes or packages. Apply process improvements prospectively; do not reorganize historical evidence merely to match a new convention. Briefly record causes of recurring setup failures or reasons for repeated checks in the existing report, not a new tracking system. Efficiency does not authorize model changes, missed cases, weaker contracts or unsafe rollback. -## Persistent Workspaces +## Resource Lifecycle -Unfinished source must live on persistent storage from the first edit. Verify resolved workspace paths and backing Git/common-directory storage are not temporary, memory-backed or subject to automatic cleanup; a persistent-looking name or `.git` file alone is insufficient. The current checkout may itself be a worktree. Use it for safe sequential work; use isolated worktrees when delegation/concurrency or candidate isolation requires them. Prefer the project's established persistent worktree location. If none is suitable or already authorized, propose one dedicated location and ask once before creation; do not automatically scatter siblings or use `/tmp` as a fallback. Reuse the chosen location and same-chunk workspace; create only needed worktrees. +Unfinished source, backing Git metadata and required evidence must be durable from creation. Before delegating edits, verify the resolved checkout, backing Git/common-directory storage and evidence destinations under the reference's persistence procedure; an existing checkout is not automatically suitable. Reuse that verification only while paths/storage remain demonstrably unchanged. `/tmp` and other disposable locations may hold only reproducible copies. Keep a compact ownership/consumer/release record, preserve evidence and uncommitted work until their retention conditions are satisfied, and never infer cleanup authority from names, age or location. -Nested worktrees are allowed only when their paths are ignored and untracked in the containing repository. Verify both before creation; do not force-add them. Ignore rules prevent ordinary staging, not deletion: protect worktree containers and shared Git metadata from broad cleanup, including `git clean -fdx`, and never remove a containing checkout while nested worktrees or dependent Git metadata remain needed. Record workspace/common-directory paths, owners and consumers in the existing durable handoff. Preserve unfinished/held candidates; release integrated worktrees only after the existing retention and cleanup checks pass. +Read and apply [Resource Lifecycle](./references/resource-lifecycle.md) for that initial persistence verification and before creating/reusing worktrees or disposable build/test copies, large builds (including in the main checkout), dependency/browser installations, archives or other substantial allocations, and cleanup/storage recovery. It defines persistence, coordinated disk-headroom checks, evidence retention and bounded cleanup. Reuse already-read instructions and verified setup where applicable rather than reloading the reference for every routine step. -Reserve `/tmp` and other disposable storage for reproducible resources. A disposable build/test copy requires a complete persistent source candidate, including staged, unstaged, new/untracked files and required local inputs, with provenance linking the copy to it. No unique implementation edits belong there. Write required evidence and recovery artifacts to persistent destinations as produced, rather than waiting for acceptance or pause. A reboot can happen between handoffs. Persistence does not require premature commits or acceptance. On resume, missing/changed source requires recovery and diff verification before continuation; transcripts/Git metadata are recovery aids, not proof of complete recovery. Reconstructed candidates require applicable revalidation before acceptance. - -## Temporary Resources and Cleanup - -Authorization to run orchestration includes routine cleanup of that run's tracked, disposable temporary resources once the checks below pass. State this default in the handoff and worker assignments; do not require separate cleanup approval within its bounds. Explicit retention/no-deletion instructions and higher-priority restrictions override the default. Reading this skill or doing standalone planning/implementation/validation does not authorize orchestration cleanup. Resources accumulated earlier in the same resumed run qualify only after ownership and release conditions are verified and recorded; unknown ownership or files predating the run do not qualify. - -Maintain a compact record in the existing handoff of exact run-created paths, purpose/owner, active or future consumers, and release condition. Register resources when created and transfer responsibility when a worker exits; a closed agent does not make its files disposable. On resume, reconcile that record against actual resources before reusing or removing them. Do not infer ownership from a filename prefix, age or location under `/tmp`. - -Use these disk defaults automatically unless explicit project/run instructions override them; record any override in the existing handoff. Per filesystem, below **5 GiB free** means report low headroom and serialize large allocations; **2 GiB or less free** means a critical disk-space blocker and pause write-heavy work. They are operating defaults, not proof that a particular build fits. - -Before large builds, dependency/browser installations, checkout copies or archives, the parent checks every receiving filesystem and coordinates active/planned allocations there. Admit a start only when measured free space minus their conservative remaining additional peak, including the proposed operation, stays above the critical reserve. Account for starts already authorized to other workers before authorizing another; different directories may share one filesystem. If combined peak is uncertain, serialize and reassess; if even the single operation's headroom cannot be established, hold it. Use existing handoff/assignment notes, not a quota service. Workers must coordinate additional large allocations outside their assigned scope with the parent. Prefer compatible existing environments without sharing mutable candidate inputs or violating isolation. - -Recheck before large allocations and after substantial allocations or cleanup, rather than after every command. Completion releases an allocation assignment, not its retained bytes: remeasure free space and account for remaining consumers before scheduling more work. No continuous monitoring system is required. - -At observed critical space, or any disk-full/quota/inode-exhaustion error regardless of free bytes, stop launching affected writes, safely halt affected owned write-heavy operations and immediately report the blocker. State the filesystem, available capacity/error, held operations, known run-owned resources and eligible cleanup or needed user intervention. Do not retry failed writes, launch a large emergency archive or treat partial outputs as valid evidence. Only already-authorized bounded cleanup may reclaim resources; do not invent deletion authority or override a user pause. Independent read-only work may continue only if safe and authorized; stop the run when storage pressure prevents reliable work globally. Resume affected writes only after rechecking safe headroom and allocation conditions; inspect potentially partial/corrupt outputs, restore candidate identity and rerun affected checks before acceptance. - -At validation release, acceptance, abandonment or pause/handoff, classify resources as still in use, retained evidence/recovery, or disposable. The parent owns disposition across workers and later gates. Preserve required raw evidence, unique failed/unfinished state, uncommitted source and rollback packages until their retention condition is resolved. A failed run need not keep every duplicate dependency tree forever, but do not discard anything needed to substantiate/reproduce findings or satisfy a pending gate. - -Before releasing an evidence-bearing workspace, preserve the required artifacts in the agreed durable location, verify they remain readable/identifiable, and update references. Keep original failure identity; do not leave the only evidence behind a deleted temporary path. Moving bytes to the same filesystem is not space reclamation, and copying entire disposable workspaces or committing bulky generated output is not the default preservation method. - -Use the run's bounded cleanup scope, carried into each assignment. Check each exact path is run-owned and within that scope, with no active process/validator, retained artifact or pending consumer depending on it. Release owned processes/handles before removal, respecting pauses and operational authority. Do not traverse symlinks/mounts into unrelated locations, clear `/tmp` broadly, delete by wildcard/prefix, or prune shared caches, files predating the run, user files or resources belonging to other runs. Worker resources may be cleaned by the parent after a recorded ownership handoff, subject to the same authorization and release checks; resources still owned by another worker remain protected. Use the owning tool's safe lifecycle for managed resources such as Git worktrees, without forced removal of uncommitted work. If ownership, retention or authority is unclear, keep the resource and ask with concrete paths/reasons. - -Perform eligible cleanup at the lifecycle boundaries above, including run completion, rather than waiting for disk pressure. After accepted integration, explicitly resolve redundant candidate/build copies: verify persistent source/evidence preservation, rollback needs and consumer release, then remove eligible copies or record a specific retention reason and release condition. An evidence archive alone does not establish disposability; uncommitted work remains protected. Record removed paths, retained paths with reasons/revisit conditions, and resulting headroom after substantial cleanup. If cleanup is blocked or a pause does not permit it, preserve the inventory for handoff; do not silently forget resources or relax acceptance to recover space. Cleanup beyond the run-owned scope requires separate authority. +The core safety boundary always applies: no broad `/tmp` clearing, wildcard/prefix deletion, shared-cache pruning, symlink traversal into unrelated locations, forced removal of uncommitted work, or destructive cleanup outside the recorded run-owned scope. Disk-full/quota/inode failures stop affected writes until safe headroom and candidate integrity are re-established. ## Review Rules diff --git a/plugins/staged-implementation/skills/orchestrator/references/resource-lifecycle.md b/plugins/staged-implementation/skills/orchestrator/references/resource-lifecycle.md new file mode 100644 index 0000000..e27ed0b --- /dev/null +++ b/plugins/staged-implementation/skills/orchestrator/references/resource-lifecycle.md @@ -0,0 +1,33 @@ +# Orchestrator Resource Lifecycle + +Read this reference for initial persistence verification before delegating edits, and before creating/reusing worktrees or disposable build/test copies, large builds (including in the main checkout), dependency/browser installations, archives or other substantial allocations, and cleanup/storage recovery. Reuse already-read instructions and verified setup while applicable. The core orchestrator skill remains authoritative for acceptance and worker lifecycle. + +## Persistent Workspaces + +Unfinished source must live on persistent storage from the first edit. Verify resolved workspace paths and backing Git/common-directory storage are not temporary, memory-backed or subject to automatic cleanup; a persistent-looking name or `.git` file alone is insufficient. The current checkout may itself be a worktree. Use it for safe sequential work; use isolated worktrees when delegation/concurrency or candidate isolation requires them. Prefer the project's established persistent worktree location. If none is suitable or already authorized, propose one dedicated location and ask once before creation; do not automatically scatter siblings or use `/tmp` as a fallback. Reuse the chosen location and same-chunk workspace; create only needed worktrees. + +Nested worktrees are allowed only when their paths are ignored and untracked in the containing repository. Verify both before creation; do not force-add them. Ignore rules prevent ordinary staging, not deletion: protect worktree containers and shared Git metadata from broad cleanup, including `git clean -fdx`, and never remove a containing checkout while nested worktrees or dependent Git metadata remain needed. Record workspace/common-directory paths, owners and consumers in the existing durable handoff. Preserve unfinished/held candidates; release integrated worktrees only after the retention and cleanup checks below pass. + +Reserve `/tmp` and other disposable storage for reproducible resources. A disposable build/test copy requires a complete persistent source candidate, including staged, unstaged, new/untracked files and required local inputs, with provenance linking the copy to it. No unique implementation edits belong there. Write required evidence and recovery artifacts to persistent destinations as produced, rather than waiting for acceptance or pause. A reboot can happen between handoffs. Persistence does not require premature commits or acceptance. On resume, missing/changed source requires recovery and diff verification before continuation; transcripts/Git metadata are recovery aids, not proof of complete recovery. Reconstructed candidates require applicable revalidation before acceptance. + +## Temporary Resources and Cleanup + +Authorization to run orchestration includes routine cleanup of that run's tracked, disposable temporary resources once the checks below pass. State this default in the handoff and worker assignments; do not require separate cleanup approval within its bounds. Explicit retention/no-deletion instructions and higher-priority restrictions override the default. Reading the skill or doing standalone planning/implementation/validation does not authorize orchestration cleanup. Resources accumulated earlier in the same resumed run qualify only after ownership and release conditions are verified and recorded; unknown ownership or files predating the run do not qualify. + +Maintain a compact record in the existing handoff of exact run-created paths, purpose/owner, active or future consumers, and release condition. Register resources when created and transfer responsibility when a worker exits; a closed agent does not make its files disposable. On resume, reconcile that record against actual resources before reusing or removing them. Do not infer ownership from a filename prefix, age or location under `/tmp`. + +Use these disk defaults automatically unless explicit project/run instructions override them; record any override in the existing handoff. Per filesystem, below **5 GiB free** means report low headroom and serialize large allocations; **2 GiB or less free** means a critical disk-space blocker and pause write-heavy work. They are operating defaults, not proof that a particular build fits. + +Before large builds, dependency/browser installations, checkout copies or archives, the parent checks every receiving filesystem and coordinates active/planned allocations there. Admit a start only when measured free space minus their conservative remaining additional peak, including the proposed operation, stays above the critical reserve. Account for starts already authorized to other workers before authorizing another; different directories may share one filesystem. If combined peak is uncertain, serialize and reassess; if even the single operation's headroom cannot be established, hold it. Use existing handoff/assignment notes, not a quota service. Workers must coordinate additional large allocations outside their assigned scope with the parent. Prefer compatible existing environments without sharing mutable candidate inputs or violating isolation. + +Recheck before large allocations and after substantial allocations or cleanup, rather than after every command. Completion releases an allocation assignment, not its retained bytes: remeasure free space and account for remaining consumers before scheduling more work. No continuous monitoring system is required. + +At observed critical space, or any disk-full/quota/inode-exhaustion error regardless of free bytes, stop launching affected writes, safely halt affected owned write-heavy operations and immediately report the blocker. State the filesystem, available capacity/error, held operations, known run-owned resources and eligible cleanup or needed user intervention. Do not retry failed writes, launch a large emergency archive or treat partial outputs as valid evidence. Only already-authorized bounded cleanup may reclaim resources; do not invent deletion authority or override a user pause. Independent read-only work may continue only if safe and authorized; stop the run when storage pressure prevents reliable work globally. Resume affected writes only after rechecking safe headroom and allocation conditions; inspect potentially partial/corrupt outputs, restore candidate identity and rerun affected checks before acceptance. + +At validation release, acceptance, abandonment or pause/handoff, classify resources as still in use, retained evidence/recovery, or disposable. The parent owns disposition across workers and later gates. Preserve required raw evidence, unique failed/unfinished state, uncommitted source and rollback packages until their retention condition is resolved. A failed run need not keep every duplicate dependency tree forever, but do not discard anything needed to substantiate/reproduce findings or satisfy a pending gate. + +Before releasing an evidence-bearing workspace, preserve the required artifacts in the agreed durable location, verify they remain readable/identifiable, and update references. Keep original failure identity; do not leave the only evidence behind a deleted temporary path. Moving bytes to the same filesystem is not space reclamation, and copying entire disposable workspaces or committing bulky generated output is not the default preservation method. + +Use the run's bounded cleanup scope, carried into each assignment. Check each exact path is run-owned and within that scope, with no active process/validator, retained artifact or pending consumer depending on it. Release owned processes/handles before removal, respecting pauses and operational authority. Do not traverse symlinks/mounts into unrelated locations, clear `/tmp` broadly, delete by wildcard/prefix, or prune shared caches, files predating the run, user files or resources belonging to other runs. Worker resources may be cleaned by the parent after a recorded ownership handoff, subject to the same authorization and release checks; resources still owned by another worker remain protected. Use the owning tool's safe lifecycle for managed resources such as Git worktrees, without forced removal of uncommitted work. If ownership, retention or authority is unclear, keep the resource and ask with concrete paths/reasons. + +Perform eligible cleanup at lifecycle boundaries, including run completion, rather than waiting for disk pressure. After accepted integration, explicitly resolve redundant candidate/build copies: verify persistent source/evidence preservation, rollback needs and consumer release, then remove eligible copies or record a specific retention reason and release condition. An evidence archive alone does not establish disposability; uncommitted work remains protected. Record removed paths, retained paths with reasons/revisit conditions, and resulting headroom after substantial cleanup. If cleanup is blocked or a pause does not permit it, preserve the inventory for handoff; do not silently forget resources or relax acceptance to recover space. Cleanup beyond the run-owned scope requires separate authority. diff --git a/plugins/staged-implementation/skills/planner/SKILL.md b/plugins/staged-implementation/skills/planner/SKILL.md index 838c730..920c952 100644 --- a/plugins/staged-implementation/skills/planner/SKILL.md +++ b/plugins/staged-implementation/skills/planner/SKILL.md @@ -97,7 +97,7 @@ A good chunk: - has explicit non-goals - can be validated without finishing the whole feature - has validation commands that prove the unit, not just an internal helper edit -- is large enough to justify a separate prompt/review cycle +- justifies a separate prompt/review/validation cycle without combining unrelated risk or rollback boundaries Prefer merging adjacent checklist items when they: @@ -114,7 +114,7 @@ Prefer splitting work when: - restart, migration, upgrade, rollback, or safety risk deserves isolated review - one part is still ambiguous while adjacent work is already frozen -Do not create separate prompts just because a second file is touched, a helper is extracted, or a checklist has multiple bullets that share the same risk and validation surface. +Do not create separate prompts just because a second file is touched, a helper is extracted, or a checklist has multiple bullets that share the same risk and validation surface. Avoid micro-chunks whose extra handoffs, fresh contexts and repeated review/validation cost more than the isolation benefit they provide. ## Planning and Evidence Proportionality @@ -226,6 +226,9 @@ Use this prompt structure unless the user explicitly requests a different shape: ```text Repo root: +Chunk ID: +Assignment ID: +Assignment mode: new-chunk | correction | replacement Read these first: Task: Scope for this pass: @@ -282,6 +285,7 @@ Every orchestrator prompt must include: - repo root - feature/fix name or slug +- stable chunk-ID convention and a run-state/handoff path, or permission for the orchestrator to create one beside the plan/checklist - plan path - implementation checklist path - prompt map path @@ -294,6 +298,10 @@ Every orchestrator prompt must include: - persistent implementation/evidence locations, or the location decision required before dependent work starts - stopping conditions +State the intended lifecycle: a same-chunk repair agent may remain available but cannot write during validation. Replacements acquire write ownership only after prior writes stop and candidate/findings/resources are verified and transferred. Accepted/permanently blocked assignments retire after required handoffs, using closure when supported or verified inactivity and removal from dispatch otherwise. Preserve held work and permit safe independent overlap with recorded ownership/isolation; retained-worker exceptions need a purpose and release condition. Use the existing handoff to preserve outstanding gates, dependencies, recovery obligations and authority restrictions, not just the next step. + +Use canonical assignment IDs such as `::`; same-worker corrections/revalidation retain the ID and fresh replacements increment the attempt. If task labels are supported, use the ID only when valid for that tool; otherwise use a supported unique encoding and record its mapping to the assignment/worker in the handoff. Do not require unsupported label syntax or assume telemetry recognizes the encoding. + State in the handoff that authorization to run orchestration includes routine cleanup of that run's tracked, disposable temporary resources after ownership, retention and consumer-release checks pass. No separate cleanup approval question is needed within those bounds. Carry this scope into worker assignments and honor explicit retention/no-deletion instructions and higher-priority restrictions. On resuming the same run, accumulated resources qualify only after their run ownership and release conditions are verified and recorded. Unknown ownership, shared caches, files predating the run, unrelated resources and anything still needed remain excluded. Standalone planning/implementation/validation or commit permission does not grant this orchestration cleanup scope; ask for concrete additional authority only when needed outside it. Never propose blanket clearing of `/tmp`. The commit policy must be explicit and must use one of: diff --git a/plugins/staged-implementation/skills/validator/SKILL.md b/plugins/staged-implementation/skills/validator/SKILL.md index 3d885c2..c58656a 100644 --- a/plugins/staged-implementation/skills/validator/SKILL.md +++ b/plugins/staged-implementation/skills/validator/SKILL.md @@ -20,6 +20,7 @@ The validator reports evidence and risk. The planner/reviewer or orchestrator de Prefer a task packet containing: - repo root +- chunk ID, assignment ID, and assignment mode (`validation`, `revalidation`, or `replacement`) when invoked by an orchestrator - project instruction docs, if not discoverable from the repo - plan/checklist/prompt/review paths or in-chat contract - validation target, such as local app URL, API base URL, device, service, CLI, test suite, or build target @@ -78,11 +79,13 @@ Follow the assigned acceptance level: local implementation, integration, or actu 4. Capture evidence. - Record commands or tools used. - Summarize differences, counts, failures, skipped/not-tested cases, limits and artifact paths; retain full logs and inspect unexpected output. Link applicable canonical input records rather than regenerating/reproducing unchanged inventories. Preserve prior candidate provenance and distinguish newly run checks from verified reused evidence. Briefly explain recurring setup failures or repeated checks in the existing report; apply improvements prospectively without repackaging historical evidence. + - Batch coherent non-urgent findings into one report/follow-up packet instead of streaming acknowledgement-scale updates. Report a safety, contract, candidate-integrity or resource blocker immediately when parent intervention is required. - Capture screenshots only when they support the verdict. - Note relevant console errors, network failures, logs, or API responses. - Do not print secrets, tokens, passwords, or sensitive env values. 5. Report verdict. + - Echo supplied chunk/assignment IDs and assignment mode when present. - Establish candidate identity remains valid before reporting. Entry verification may cover this adjacent boundary when controlled ownership and applicable change checks demonstrate unchanged relevant source/inputs/build; do not automatically repeat full scans. Mutation, interruption that makes continuity uncertain or other identity uncertainty requires renewed verification. If relevant inputs changed, stop affected checks, notify the parent and qualify old evidence; resume only after a stable candidate is established. Prior-agent assurances alone do not establish continuity. - Mark each validation item as pass, fail, blocked, or not tested. - Explain failures with concrete observed behavior. @@ -94,6 +97,8 @@ For a correction/revalidation, verify the original assignment/current candidate Complete assigned routine checks without repeated parent acknowledgements; promptly report blockers/material findings and coordinate candidate release, shared resources, scope changes and approvals. A completion notice does not release a workspace. Preserve required user updates. Correctness and acceptance obligations take priority over token savings. +After returning the verdict, stop and wait for a concrete revalidation assignment. Do not poll the parent/implementer, continue exploratory validation, or repeat successful checks merely because the worker remains available. Same-worker revalidation retains the chunk/assignment IDs; independently determine affected coverage plus required regressions/fresh gates, then stop after reporting. On replacement or retirement, hand off validation holds, owned operations/resources and evidence; the parent coordinates their release. Retirement ends assigned work even if the runtime leaves the worker open. + ## Browser/UI Validation When validating a UI with browser or Playwright tools: @@ -156,6 +161,9 @@ Use this compact structure, omitting empty optional sections. Keep blocking find Verdict: - pass | fail | blocked | partial +Assignment: +- chunk/assignment IDs and mode when supplied + Candidate: - baseline/scoped changes and relevant build identity