awslabs / awslabs/aidlc-workflows

[Bug]: Session resumption after context clear can skip approval gates by misreading COMPLETED status

Open
#249 1 comment 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.