Clarify event-driven coordination and stable-candidate review; bump staged-implementation to 0.2.0-alpha.2

2026-09-20 14:08:50 +02:00
parent 71b0061d3f
commit 382f6a09c9
7 changed files with 11 additions and 5 deletions
@@ -1,6 +1,6 @@
 {
  "name": "staged-implementation",
-  "version": "0.2.0-alpha.1",
+  "version": "0.2.0-alpha.2",
  "description": "Experimental coordinated staged implementation with planner, coordinator, bounded orchestrator, implementer, and validator roles.",
  "author": {
    "name": "Local developer"
@@ -10,7 +10,7 @@ Staged Implementation bundles five skills with two execution entry points:

 Use this plugin when a feature or fix is too large or contract-heavy to handle as one open-ended coding pass.

-**Experimental preview — `0.2.0-alpha.1`.** Stable `0.1.5` is preserved on `master`. This branch changes Orchestrator's boundary; old whole-checklist launch prompts must explicitly select Coordinator rather than silently losing scope. No installation, migration execution, measured savings or unattended-runtime qualification is implied by the files or structural validators. Qualify the [pilot](skills/coordinator/references/pilot-validation.md) before consequential coordinated execution. Do not mix stable and preview role instructions in one run.
+**Experimental preview — `0.2.0-alpha.2`.** Stable `0.1.5` is preserved on `master`. This branch changes Orchestrator's boundary; old whole-checklist launch prompts must explicitly select Coordinator rather than silently losing scope. No installation, migration execution, measured savings or unattended-runtime qualification is implied by the files or structural validators. Qualify the [pilot](skills/coordinator/references/pilot-validation.md) before consequential coordinated execution. Do not mix stable and preview role instructions in one run.

 ## Plugin Structure

@@ -28,7 +28,7 @@ Start with one active orchestrator assignment at a time. Coordinator + orchestra
 1. Select the next eligible chunk or validation gate from written dependencies and actual accepted state. Do not treat a committed candidate as accepted without its acceptance evidence. Do not use held work as a dependency. Verify uncommitted accepted inputs explicitly when permitted by policy. If grouping is useful, enumerate the approved chunk IDs and order; preserve every acceptance/rollback boundary.
 2. Assign the bounded work using the shared execution contract. Save or reference the assignment in existing prompt/handoff locations; no separate dispatch journal. Give a fresh orchestrator scoped context without full parent-history inheritance when supported, explicit authorized model/effort if needed, and the correct experimental skill path/version. It writes the detailed implementer prompt after verifying scoped readiness. Do not send it the entire historical run narrative.
 3. Record the assignment/worker mapping and ownership before it may mutate shared resources. Delegate chunk review, acceptance and scoped commits under existing user authority. Reserve the candidate/index/integration target for that orchestrator; neither coordinator nor another worker may edit or stage there concurrently. Coordinator-owned scheduling records must be separate from the candidate's validated inputs, or updated only after its hold is released.
-4. Wait for completion or material events using supported notifications/interruptible waits. Preserve user updates and justified liveness checks. Do not send routine acknowledgement prompts, poll continuously, or absorb raw logs merely to remain busy. Route relevant user instructions and pauses promptly; do not let the orchestrator dispatch beyond its assignment.
+4. Wait for completion or material events using supported notifications/interruptible waits. Do not send routine acknowledgement prompts, poll continuously, or absorb raw logs merely to remain busy. Check liveness when expected progress, tool failure or other evidence warrants it; a wait timeout alone is insufficient. Prefer available status information before prompting. Required user updates use information already received, with uncertainty stated honestly; do not initiate inspections or descendant status requests solely to refresh a progress message. Follow the shared contract's communication boundary while preserving timely intervention, pause routing and required safety/resource checks. Do not let the orchestrator dispatch beyond its assignment.
 5. Check the returned acceptance record and actual repository state under **Completion Verification**. Route concrete omissions or discrepancies back to the same orchestrator when continuity is useful. Do not start a new full review for every clerical correction. New contract or cross-chunk risk can require a scoped independent challenge; no required review may be skipped.
 6. Transfer outstanding resources/holds, retire the complete worker subtree and verify capacity for the next assignment. Closing a parent does not prove its children/processes stopped. Preserve held source, failed evidence and future gate/rollback consumers. Reconcile eligible cleanup and allocations before further work.
 7. Update the one current run handoff and affected checklist/readiness entries. Dispatch the next fresh orchestrator, or stop at the authorized boundary. No new user approval is needed for routine steps already authorized.
@@ -21,6 +21,8 @@ The orchestrator reads the actual candidate and contracts, writes/reuses the sco

 Fixable in-scope review/test failures keep acceptance held while the same assignment performs correction and revalidation. They do not automatically become a blocked return or trigger fresh orchestrator setup. Return a block when missing authority, contract, dependency or environment prevents safe progress; preserve the candidate and findings rather than retrying equivalent failed attempts.

+Keep communication event-driven within existing authority. The bounded orchestrator handles ordinary investigation, in-scope corrections and revalidation without routine progress messages or acknowledgement requests to Coordinator. Promptly report completion, blockers requiring coordination, authority requests and material findings affecting the wider run; preserve other findings and failures in durable evidence and the final return. Required user-facing updates do not create a requirement to poll descendants or relay periodic status through each level. Use known state and state uncertainty honestly; higher-priority update instructions, agreed checkpoints, urgent reporting and pause handling remain binding.
+
 Keep the candidate and relevant harness/configuration/build stable during validation. Same-chunk repairs may reuse workers, but writes resume only after the validation hold is released. Replacement requires verified cessation of prior writes, candidate verification and ownership transfer. No additional review layer is mandated by the existence of a coordinator.

 The active orchestrator alone stages/commits its accepted scope under its commit policy, after inspecting the exact staged diff and verifying accepted candidate identity. Coordinate any integration target exclusively. Commit permission is not merge/deploy/push permission. If integration changes the accepted source or relevant inputs, re-establish review/evidence applicability before integration acceptance. A valid isolated-worktree commit does not by itself prove the target branch is integrated.
@@ -14,6 +14,8 @@ Before consequential unattended work, qualify a small disposable fixture project
 6. **Integration discrepancy:** change a fixture input after validation or return an inconsistent candidate/commit identity. Verify completion is held for reconciliation. Test uncommitted accepted work under `do-not-commit` without forcing a commit or allowing unsafe subsequent overlap.
 7. **Resources:** simulate low-space/admission outcomes without filling the disk. Check allocation accounting across layers, persistence verification before edits, retained future consumers and bounded cleanup authority. Retirement must not delete held work or imply a process/resource release.

+During ordinary execution and the correction cycle, observe whether user updates trigger status-only polling chains or parents duplicate active workers' investigations. Check that required updates use known state, ordinary repairs stay with the orchestrator, and material blockers/pauses still propagate promptly. Record deviations in the existing trial evidence; no separate report or rigid message quota is needed.
+
 Hold unattended qualification on any unresolved authority, candidate, recovery or capacity failure. Propose direct/manual execution only as an explicit alternative, not an automatic fallback. Additional nested reviews require available capacity; do not drop a required review or change models to fit.

 ## Real-Work Trial
@@ -211,7 +211,9 @@ 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.
+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, blocker reporting and required safety/resource checks remain required. Apply the shared execution contract's communication boundary: routine in-scope corrections stay here, and user updates do not trigger descendant polling.
+
+While a worker owns an active implementation or validation pass, do not continuously inspect its changing work or duplicate its assigned investigation. Intervene for concrete risk, blockers, ownership conflicts or an agreed checkpoint; perform acceptance review against the stable returned candidate. This does not restrict required independent review or investigation of affected callers and shared behavior.

 When spawning an implementer sub-agent: