awslabs / awslabs/aidlc-workflows
[Feature]: Phase-gate sensor: enforce phase-boundary verification file existence and content
- Dominant language
- TypeScript
- Stars
- 4.6k
- Forks
- 827
- Avg merge
- 1d 21h
- Merged PRs (30d)
- 165
Description
### Description
Phase-boundary verification files (`verification/phase-check-.md`) are instructed by stage prose but have no programmatic enforcement. Nothing in the tooling validates their existence or content. The `PHASE_VERIFIED` audit event fires unconditionally at every phase boundary regardless of whether the verification actually ran.
This creates a structural blind spot: a conductor working from the directive's `produces` array (the engine's formal artifact graph) will never be reminded to create these files, because they live at `/verification/`, outside the `///` path convention that `resolveArtifactPath` enforces. The existing `verifyStageArtifacts` guard at approve time only checks produces-declared artifacts.
**Proposed fix — two layers:**
1. **Content-validation sensor** (phase-gate): a new sensor with `matches: "**/verification/phase-check-*.md"` that fires reactively when the file is written, validating it contains a summary verdict (pass/fail) and isn't a stub. Declared on the 3 boundary stages (`approval-handoff, delivery-planning, build-and-test`).
2. **Existence enforcement at approve/advance time**: extend `verifyStageArtifacts` in `aidlc-state.ts` to additionally check that `/verification/phase-check-.md` exists before allowing the 3 phase-boundary stages to complete. This catches the primary failure mode when the agent is skipping the step entirely.
**Secondary fix — naming inconsistency:**
`stage-protocol-governance.md` §13 step 3 says `/verification/[phase-boundary]-verification.md` but the actual stage bodies use `phase-check-.md`. These should be aligned.
### Use Case
During a real workflow run, the conductor skipped Step 11 (Phase Boundary Verification) of `build-and-test` because it worked from the `produces` array rather than reading the full stage body. The phase-check file was never created, but `report --result approved` succeeded and `PHASE_VERIFIED` was emitted to the audit, creating a false record that verification occurred.
This is a systemic gap: any conductor (human or AI) that relies on the engine's formal signals (produces, directives, sensors) will miss these verification steps because they exist only as prose instructions with no downstream consumer.
The fix ensures:
- A conductor cannot approve a phase-boundary stage without producing the verification file (deterministic gate)
- If the file is produced, its content is validated for structural soundness (advisory sensor)
- The audit event PHASE_VERIFIED carries actual meaning rather than being a positional no-op
Related: #401 (traceability sensor infrastructure that this builds on)
### Version
v2 (alpha)
### Area
Other
### Additional Context
Affected stages and their verification files:
| Stage | Phase-check file | In `produces`? |
|-------|-----------------|----------------|
| `approval-handoff` (ideation) | `/verification/phase-check-ideation.md` | No |
| `delivery-planning` (inception) | `/verification/phase-check-inception.md` | No |
| `build-and-test` (construction) | `/verification/phase-check-construction.md` | No |
**Why they can't simply be added to produces:** `resolveArtifactPath` (`aidlc-orchestrate.ts:768`) resolves all produces entries to `///.md`. The verification/ directory is a top-level sibling at `/verification/`, outside that convention. Adding them would require either a path-override mechanism in the resolver or moving the files into the stage directory (losing the consolidated verification view).
**Key code locations:**
- `core/tools/aidlc-state.ts:762` — `verifyStageArtifacts` (the enforcement point to extend)
- `core/tools/aidlc-state.ts:972` — `PHASE_VERIFIED` emitted unconditionally in handleAdvance
- `core/tools/aidlc-state.ts:1177` — `PHASE_VERIFIED` emitted unconditionally in handleCompleteWorkflow
- `core/tools/aidlc-orchestrate.ts:768` — `resolveArtifactPath` (why produces can't cover these)
- `core/aidlc-common/protocols/stage-protocol-governance.md` — the prose-only governance contract
- `core/knowledge/aidlc-shared/verification.md` — the verification methodology doc
Contributor guide
Research direction
Start with verifyStageArtifacts in core/tools/aidlc-state.ts:762 and trace the unconditional PHASE_VERIFIED emissions at lines 972 and 1177. Read resolveArtifactPath in core/tools/aidlc-orchestrate.ts:768 and the stage-protocol-governance.md and verification.md documents to understand the path and naming constraints. Done means the three boundary stages enforce their phase-check files, written files receive content validation, audit events reflect the gate, and the naming inconsistency is aligned.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- tooling
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 65/100