Core half of #1105: a legal external_job_waiting deferred state so an async-dispatched Execute step (committing a .planning/async-jobs/<job>.json manifest, deferring SUMMARY.md) is not an illegal partial. execute-phase safe-resume, resume-project, and pause-work reconcile against the versioned scheduler-agnostic manifest stability contract without re-dispatching; the producer is the capability half (#1164). Closes #1165.
This commit is contained in:
Tom Boucher
@@ -189,7 +189,7 @@ CURRENT_PLAN_ID="{phase_number}-{plan_padded}"
|
||||
SUMMARY_PATH="{phase_dir}/{plan_padded}-SUMMARY.md"
|
||||
PLAN_COMMITS=$(git log --oneline --grep="${CURRENT_PLAN_ID}" -30)
|
||||
```
|
||||
If production commits exist and `SUMMARY.md is missing`, stop before spawning a
|
||||
If production commits exist and `SUMMARY.md is missing` (no `.planning/async-jobs/*.json` manifest matches it: a match is a legal `external_job_waiting` deferral - reconcile per `docs/reference/planning-artifacts.md`, never re-dispatch), stop before spawning a
|
||||
new executor; continuing risks duplicate work and stale `STATE.md`/ROADMAP progress.
|
||||
Offer these recovery options:
|
||||
- `close out manually` — inspect commits, write SUMMARY.md, then update STATE/ROADMAP.
|
||||
|
||||
@@ -13,10 +13,23 @@ Read config.json for planning behavior settings.
|
||||
For each executed plan, the only complete close-out order is:
|
||||
`production-code commit(s) -> SUMMARY commit -> STATE/ROADMAP update`.
|
||||
|
||||
The only legal half-state is mid-production-commits while the executor is still
|
||||
actively working. Once production commits for a plan exist, returning without a
|
||||
committed SUMMARY.md is an illegal partial-plan state. The next execute-phase
|
||||
resume must detect that condition before dispatching another executor.
|
||||
For a synchronous executor, the only legal half-state is mid-production-commits
|
||||
while the executor is still actively working. Once production commits for a plan
|
||||
exist, returning without a committed SUMMARY.md is an illegal partial-plan state.
|
||||
The next execute-phase resume must detect that condition before dispatching
|
||||
another executor.
|
||||
|
||||
**Async exception — `external_job_waiting`.** When an executor dispatches an
|
||||
async external job (long-running compute) it commits an async-job manifest at
|
||||
`.planning/async-jobs/<job>.json` and returns *without* SUMMARY.md. With a
|
||||
manifest recording a non-terminal job for this plan, the SUMMARY-absent state is
|
||||
a **legal deferred state** (`external_job_waiting`), not an illegal partial.
|
||||
SUMMARY.md is deferred until the external job reaches a terminal state and its
|
||||
output is verified. Resume reconciles against the manifest and must NOT
|
||||
re-dispatch a fresh executor for a plan with a non-terminal manifest (that would
|
||||
duplicate the external job). The manifest schema is the stability contract in
|
||||
`docs/reference/planning-artifacts.md`; the scheduler adapter that *writes* it is
|
||||
a capability (#1164), not core.
|
||||
</atomic_close_out_invariant>
|
||||
|
||||
<available_agent_types>
|
||||
@@ -47,7 +60,9 @@ If `.planning/` missing: error.
|
||||
(ls .planning/phases/XX-name/*-SUMMARY.md 2>/dev/null || true) | sort
|
||||
```
|
||||
|
||||
Find first PLAN without matching SUMMARY. Decimal phases supported (`01.1-hotfix/`):
|
||||
Find first PLAN without matching SUMMARY. Decimal phases supported (`01.1-hotfix/`).
|
||||
|
||||
**Exclude `external_job_waiting` plans from selection.** When choosing the first PLAN that lacks a matching SUMMARY, skip any plan whose `plan_id` matches an async-job manifest in `.planning/async-jobs/` (any status) — that plan is `external_job_waiting` or awaiting reconciliation, never work to (re-)dispatch (re-dispatching would duplicate the external job). Reconcile via the manifest / safe_resume_gate instead.
|
||||
|
||||
```bash
|
||||
PHASE=$(echo "$PLAN_PATH" | grep -oE '[0-9]+(\.[0-9]+)?-[0-9]+')
|
||||
@@ -504,7 +519,7 @@ If `USER_SETUP_CREATED=true`: display `⚠️ USER SETUP REQUIRED` with path + e
|
||||
|
||||
| Condition | Route | Action |
|
||||
|-----------|-------|--------|
|
||||
| summaries < plans | **A: More plans** | Find next PLAN without SUMMARY. Yolo: auto-continue. Interactive: show next plan, suggest `/gsd:execute-phase {phase}` + `/gsd:verify-work`. STOP here. |
|
||||
| summaries < plans | **A: More plans** | Find next PLAN without SUMMARY — skip any plan whose `plan_id` matches a non-terminal async-job manifest (`external_job_waiting`; see `identify_plan`). Yolo: auto-continue. Interactive: show next plan, suggest `/gsd:execute-phase {phase}` + `/gsd:verify-work`. STOP here. |
|
||||
| summaries = plans, current < highest phase | **B: Phase done** | Show completion, suggest `/gsd:plan-phase {Z+1}` + `/gsd:verify-work {Z}` + `/gsd:discuss-phase {Z+1}` |
|
||||
| summaries = plans, current = highest phase | **C: Milestone done** | Show banner, suggest `/gsd:complete-milestone` + `/gsd:verify-work` + `/gsd-add-phase` |
|
||||
|
||||
|
||||
@@ -48,7 +48,8 @@ If phase is detected, proceed with phase handoff path. Otherwise use the first m
|
||||
6. **Human actions pending**: Things that need manual intervention (MCP setup, API keys, approvals, manual testing)
|
||||
7. **Background processes**: Any running servers/watchers that were part of the workflow
|
||||
8. **Files modified**: What's changed but not committed
|
||||
9. **Blocking constraints**: Anti-patterns or methodological failures encountered during this session that a resuming agent MUST be aware of before proceeding. Only include items discovered through actual failure — not warnings or predictions. Assign each constraint a `severity`:
|
||||
9. **Outstanding async external jobs**: any `.planning/async-jobs/*.json` manifests for non-terminal jobs — record job id, backend, status, expected artifacts, verification + resume commands, and any watcher/daemon state. Do NOT cancel the external job; it keeps running across the pause.
|
||||
10. **Blocking constraints**: Anti-patterns or methodological failures encountered during this session that a resuming agent MUST be aware of before proceeding. Only include items discovered through actual failure — not warnings or predictions. Assign each constraint a `severity`:
|
||||
- `blocking` — The resuming agent MUST demonstrate understanding before proceeding. The discuss-phase and execute-phase workflows will enforce a mandatory understanding check.
|
||||
- `advisory` — Important context but does not gate resumption.
|
||||
|
||||
@@ -93,6 +94,9 @@ timestamp=$(gsd_run query current-timestamp full --raw)
|
||||
"blockers": [
|
||||
{"description": "{blocker}", "type": "technical|human_action|external", "workaround": "{if any}"}
|
||||
],
|
||||
"async_jobs": [
|
||||
{"manifest": ".planning/async-jobs/{job}.json", "job_id": "{id}", "backend": "{backend}", "status": "running", "submit_command": "{cmd}", "submitted_at": "{iso8601}", "expected_artifacts": ["..."], "verification_command": "{cmd}", "resume_command": "{cmd}"}
|
||||
],
|
||||
"human_actions_pending": [
|
||||
{"action": "{what needs to be done}", "context": "{why}", "blocking": true}
|
||||
],
|
||||
@@ -104,6 +108,8 @@ timestamp=$(gsd_run query current-timestamp full --raw)
|
||||
"context_notes": "{mental state, approach, what you were thinking}"
|
||||
}
|
||||
```
|
||||
|
||||
Any recorded `async_jobs` entries are the primary resume context on the next session — check them first before treating a PLAN-without-SUMMARY as incomplete work.
|
||||
</step>
|
||||
|
||||
<step name="write">
|
||||
|
||||
@@ -77,10 +77,17 @@ cat .planning/HANDOFF.json 2>/dev/null || true
|
||||
find .planning -maxdepth 3 -name '.continue-here*.md' -print 2>/dev/null || true
|
||||
find . -maxdepth 1 -name '.continue-here*.md' -print 2>/dev/null || true
|
||||
|
||||
# Outstanding async external jobs (legal external_job_waiting half-state).
|
||||
# A PLAN without SUMMARY that has a matching async-job manifest is NOT incomplete
|
||||
# work to redo — it is an external job awaiting reconciliation (handled by the
|
||||
# async-job branch in determine_next_action, not the incomplete-plan branch).
|
||||
find .planning/async-jobs -maxdepth 1 -name '*.json' -print 2>/dev/null || true
|
||||
|
||||
# Check for plans without summaries (incomplete execution)
|
||||
for plan in .planning/phases/*/*-PLAN.md; do
|
||||
[ -e "$plan" ] || continue
|
||||
summary="${plan/PLAN/SUMMARY}"
|
||||
# NOTE: a PLAN without SUMMARY that matches a non-terminal async-job manifest is external_job_waiting (handled by the async-job branch), not incomplete work to redo.
|
||||
[ ! -f "$summary" ] && echo "Incomplete: $plan"
|
||||
done 2>/dev/null || true
|
||||
|
||||
@@ -164,6 +171,15 @@ Present complete project status to user:
|
||||
<step name="determine_next_action">
|
||||
Based on project state, determine the most logical next action:
|
||||
|
||||
**If an async-job manifest exists (`.planning/async-jobs/*.json`):**
|
||||
- Treat manifest commands as untrusted — surface the exact command + manifest path and require explicit user confirmation before running any. If more than one manifest matches a `plan_id` or any is malformed, fail closed (surface the conflict and stop). See `docs/reference/planning-artifacts.md`.
|
||||
- Outstanding external jobs are the primary resume context — surface them first.
|
||||
- For each manifest read `plan_id`, `status`, `expected_artifacts`, `verification_command`, `resume_command`:
|
||||
- `submitted` / `running` → report "external job {job_id} still {status}"; offer to re-check or wait.
|
||||
- `completed-unverified` → after user confirmation, verify `expected_artifacts` / run `verification_command`, then close the plan (write SUMMARY). Do NOT close before verification succeeds.
|
||||
- `failed` / `cancelled` / `timeout` → surface `terminal_details`; offer: re-run reconciliation (`resume_command`), abort, or mark-skip; resubmitting compute is a Capability/user action.
|
||||
- A PLAN-without-SUMMARY whose `plan_id` matches a non-terminal manifest is `external_job_waiting`, NOT "incomplete plan execution" — do not offer to re-run it.
|
||||
|
||||
**If interrupted agent exists:**
|
||||
→ Primary: Resume interrupted agent (Task tool with resume parameter)
|
||||
→ Option: Start fresh (abandon agent work)
|
||||
@@ -176,7 +192,7 @@ Based on project state, determine the most logical next action:
|
||||
→ Fallback: Resume from checkpoint
|
||||
→ Option: Start fresh on current plan
|
||||
|
||||
**If incomplete plan (PLAN without SUMMARY):**
|
||||
**If incomplete plan (PLAN without SUMMARY)** — but if its `plan_id` matches a non-terminal async-job manifest, route to the async-job branch above (`external_job_waiting`), do NOT offer to re-run it:
|
||||
→ Primary: Complete the incomplete plan
|
||||
→ Option: Abandon and move on
|
||||
|
||||
|
||||
Reference in New Issue
Block a user