awslabs / awslabs/aidlc-workflows
[Bug]: Session resumption after context clear can skip approval gates by misreading COMPLETED status
- Dominant language
- TypeScript
- Stars
- 4.6k
- Forks
- 827
- Avg merge
- 1d 21h
- Merged PRs (30d)
- 165
Description
## Description
When a Claude session is cleared mid-workflow (cache expiry, going to lunch, deliberate fresh start) and a new session resumes by reading `aidlc-state.md`, the new instance can incorrectly proceed past a human approval gate if the stage status is `COMPLETED` but approval has not yet occurred.
## Steps to Reproduce
1. Run AIDLC through a generation stage (e.g., Requirements Analysis) until the artifact is produced
2. At this point, `aidlc-state.md` shows `Requirements Analysis | COMPLETED` — the generation step is done, but the user has not yet approved
3. Clear the session context (cache expires, take a break, start a fresh Claude session)
4. Resume by asking the new session for the current status
5. The new session reads `aidlc-state.md`, sees `COMPLETED`, and proceeds to the next stage (e.g., Workflow Planning) without waiting for approval
## Expected Behavior
A resumed session should recognize that `COMPLETED` on a generation stage means the artifact exists but not that approval was given. It should halt at the approval gate and report: "Requirements Analysis artifact has been generated — awaiting your approval before proceeding."
## Actual Behavior
The resumed session treats `COMPLETED` as fully done (including approved) and proceeds to the next stage. In the observed case, `execution-plan.md` was generated before `requirements.md` had been approved. The state file and audit log had to be manually corrected afterward.
From the session's own audit log entry after the error was caught:
> "Resumed session. Incorrectly read aidlc-state.md as showing Requirements Analysis COMPLETED and proceeded to Workflow Planning without verifying against the audit trail. Audit trail correctly showed 'awaiting user approval before proceeding to Workflow Planning' — requirements were never formally approved."
## Root Cause
`COMPLETED` is used to mean two different things:
- The artifact generation step finished
- The user approved the artifact
A fresh-context instance reading the state file has no way to distinguish between these two states from the single `COMPLETED` value.
## Suggested Fix
Introduce distinct status values so generation-complete and approval-complete are unambiguous to any reader with zero prior context:
- `GENERATED` or `AWAITING_APPROVAL` — artifact exists, user has not yet approved
- `COMPLETED` — artifact approved; stage fully closed
Alternatively, make human approval an explicit row in the Stage Progress table so the gate is visible as its own incomplete step rather than an annotation on a `COMPLETED` row.
This matters most for natural context resets (cache TTL, breaks, deliberate fresh starts) — not just formal handoffs. The state file should be written defensively for a zero-context reader at all times.
Contributor guide
Research direction
Start by tracing how a resumed session reads aidlc-state.md and compare that interpretation with the audit log entry. Review the Requirements Analysis, requirements.md, and execution-plan.md examples to map generation completion against approval. Done means a zero-context reader can distinguish an unapproved generated artifact from an approved stage and cannot proceed past the approval gate.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- developer-experience, tooling
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100