[Bug]: summary-confirmation guard is unsatisfiable on zero-Unit per-unit stages — summaryQuestionFiles scans only construction/<unit>/<stage>/, ignoring the stage-level path the engine itself resolves (refactor, infra, security-patch)

[leeyoseph-dev]

Description

On a zero-Unit run (a scope where Units Generation is SKIP), a per-unit stage that declares summary_confirmation: required can never be completed. The engine writes the stage's artifacts — including its <stage>-questions.md — to the stage-level path, but the summary-confirmation guard looks for that questions file only under per-unit paths. The file exists, the human answered it, the receipt was minted; the guard still refuses with "its question flow has no <stage>-questions.md file".

The zero-Unit escape hatch already exists in the codebase (usesStageLevelPerUnitArtifacts) and is applied by the artifact resolver — it is simply not applied to the questions-file scanner.

Mechanism

Everything below is on a277af218f0d (current main).

1. The writer resolves the zero-Unit path. resolveArtifactInstances (core/tools/aidlc-artifact-resolution.ts:219-251): for a per-unit stage, when usesStageLevelPerUnitArtifacts(scope, stateContent) is true it returns a single instance at join(record, owner.phase, owner.slug, filename) — i.e. <record>/construction/<stage>/…, with no Unit segment. code-generation.md documents this shape explicitly ("with no synthetic Unit segment").

usesStageLevelPerUnitArtifacts (core/tools/aidlc-lib.ts:21910-21915) is exactly the zero-Unit predicate:

export function usesStageLevelPerUnitArtifacts(scope, stateContent): boolean {
  return effectivePlanAction("units-generation", scope, stateContent) !== "EXECUTE";
}

2. The reader does not. summaryQuestionFiles (core/tools/aidlc-lib.ts:6971-6997) branches only on isPerUnitStage(stage) (:113-115, i.e. for_each: unit-of-work):

function summaryQuestionFiles(projectDir, stage): SummaryQuestionFile[] {
  const rec = recordDir(projectDir);
  if (rec === null) return [];
  if (!isPerUnitStage(stage)) {
    return questionFilesInDir(join(rec, stage.phase, stage.slug), null);   // stage-level
  }
  const constructionDir = join(rec, "construction");
  ...
  for (const unit of readdirSync(constructionDir).sort()) {
    files.push(...questionFilesInDir(join(constructionDir, unit, stage.slug), unit));
  }
  ...
}

It takes no scope/stateContent parameter, so it cannot consult usesStageLevelPerUnitArtifacts at all. On a zero-Unit run the artifacts sit at construction/<stage>/, which is itself a child of construction/ — so readdirSync returns the stage slug as a pseudo-unit and the scanner probes construction/<stage>/<stage>/, which never exists.

3. The guard refuses before the escape hatch is ever consulted. In checkSummaryConfirmationEvidence (core/tools/aidlc-lib.ts:7023):

• :7049 — let questions = summaryQuestionFiles(projectDir, stage); → []
• :7056-7066 — questions.length === 0 and summary_confirmation === "required" → returns {ok:false, message: "Refusing to complete \"<stage>\": its question flow has no <stage>-questions.md file. …"}
• :7067-7079 — the only call to usesStageLevelPerUnitArtifacts in this function, reached only after the refusal above, and it guards a different concern (the bolt-DAG unit-coverage check).

4. Writer/reader asymmetry. summaryQuestionEvidence (core/tools/aidlc-log.ts:160-200) accepts any *-questions.md inside the active record via --questions-file, validates its [Answer]: line, hashes it, and mints SUMMARY_CONFIRMATION_RECORDED with Questions File / Questions SHA-256. So the receipt is recorded successfully, pointing at the stage-level path, and only the verifier is unable to find it.

5. Three blocking call sites, all with options.unit === undefined (there is no unit in a zero-Unit run):

Site	Command	Message prefix
core/tools/aidlc-log.ts:1702	aidlc-log.ts review --stage <s> --reviewer <a> --iteration 1	Cannot start review for "<s>": …
core/tools/aidlc-state.ts:3348-3368 (verifySummaryConfirmationPrecondition)	aidlc-state.ts gate-start <s>	Refusing to complete "<s>": …
core/tools/aidlc-orchestrate.ts (report)	aidlc-orchestrate.ts report --stage <s> --result …	Refusing to complete "<s>": …

Review cannot start, the gate cannot open, and completion is refused — so there is no ordering of the sanctioned steps that gets through.

Affected scopes

Derived from the compiled stage-graph.json + scope-grid.json. Per-unit stages (for_each: unit-of-work) that declare summary_confirmation: required: functional-design, nfr-requirements, nfr-design, infrastructure-design. (code-generation declares no summary_confirmation, so it returns early at aidlc-lib.ts:7045 and is unaffected.)

Shipped scopes with units-generation: SKIP and at least one of those four EXECUTE:

Scope	Affected stage(s)
refactor	functional-design
infra	nfr-requirements, nfr-design, infrastructure-design
security-patch	nfr-requirements

3 of the 11 shipped scopes, plus any composed scope with the same shape. poc, bugfix and express are zero-Unit too but skip all four stages, so they do not hit this.

Steps to Reproduce

# 1. Install the Claude Code distribution into an empty git repo
mkdir demo && cd demo && git init
cp -r /path/to/aidlc-workflows/dist/claude/.claude/ .claude/
cp -r /path/to/aidlc-workflows/dist/claude/aidlc/   aidlc/

# 2. Create a refactor-scope intent (units-generation SKIP, functional-design EXECUTE)
bun .claude/tools/aidlc-utility.ts intent-create \
  --scope refactor --label "demo" --arguments "tidy up a small module"

# 3. Run through to functional-design. Because Units Generation was skipped, the
#    engine resolves this stage's artifacts to the stage-level path, so the
#    questions file is written to:
#      aidlc/spaces/default/intents/<record>/construction/functional-design/functional-design-questions.md

# 4. Answer the questions and record the consolidated-summary checkpoint.
#    This SUCCEEDS — the receipt binds to the stage-level path above:
bun .claude/tools/aidlc-log.ts decision \
  --stage functional-design --checkpoint summary-confirmation \
  --questions-file aidlc/spaces/default/intents/<record>/construction/functional-design/functional-design-questions.md \
  --decision "Does this all look correct before I generate the artifact?" \
  --options "Looks correct,Request changes" --details "Looks correct"

# 5. Generate the artifacts, then try any of the three sanctioned next steps:
bun .claude/tools/aidlc-log.ts review --stage functional-design \
  --reviewer aidlc-architecture-reviewer-agent --iteration 1
bun .claude/tools/aidlc-state.ts gate-start functional-design

Expected Behavior

summaryQuestionFiles finds the questions file the engine itself told the stage to write. On a zero-Unit run the guard should verify the single stage-level questions file at <record>/<phase>/<stage>/<stage>-questions.md — the same path resolveArtifactInstances returns — and the freshness/hash/artifact-ordering checks should proceed against it normally.

Actual Behavior

Step 5 fails, repeatedly and identically, regardless of what the questions file contains:

Cannot start review for "functional-design": its question flow has no
functional-design-questions.md file. Create and answer the stage questions, then
record the consolidated summary checkpoint before generating artifacts.

Refusing to complete "functional-design": its question flow has no
functional-design-questions.md file. Create and answer the stage questions, then
record the consolidated summary checkpoint before generating artifacts.

…while <record>/construction/functional-design/functional-design-questions.md exists, carries exactly one [Answer]: Looks correct under ## Consolidated Summary Confirmation, and is named verbatim in the SUMMARY_CONFIRMATION_RECORDED row the engine itself wrote minutes earlier:

## Summary Confirmation Recorded
**Event**: SUMMARY_CONFIRMATION_RECORDED
**Stage**: functional-design
**Details**: Looks correct
**Checkpoint**: Consolidated Summary Confirmation
**Questions File**: aidlc/spaces/default/intents/<record>/construction/functional-design/functional-design-questions.md
**Questions SHA-256**: 58bc5409…
**Hash Scope**: confirmed-content-v1

The message's own remedy ("create and answer the stage questions, then record the consolidated summary checkpoint") is not actionable — all three of those steps had already succeeded.

What we observed (separate from the code reading above): on a real zero-Unit run we recorded five of these refusals across aidlc-log review and aidlc-state gate-start. The only thing that got us past it was AIDLC_SKIP_SUMMARY_CONFIRMATION_GUARD=1 (aidlc-lib.ts:6917-6919), which is a blunt instrument: it also disables the receipt-freshness check, the questions-file hash binding, and the post-confirmation artifact-write check for the rest of the workflow. Jumping past the stage is worse — it marks the stage [S] (skipped) in aidlc-state.md, which misrepresents what happened.

AI-DLC Version

v2

Release / Commit

a277af218f0d (current main at time of filing).

AI-DLC Phase

Construction

Harness

Claude Code

AI Model

Claude Opus 5

Environment

• OS: macOS (Darwin 25.5.0)
• Scope: composed scope with units-generation — SKIP, functional-design — EXECUTE (reproducible on the stock refactor scope)
• Zero-Unit: no unit-of-work.md, no Unit DAG

Possible fix directions

1. Thread the escape hatch into the scanner (smallest change). Give summaryQuestionFiles the stateContent that checkSummaryConfirmationEvidence already holds and short-circuit the per-unit branch:

   if (!isPerUnitStage(stage) ||
       usesStageLevelPerUnitArtifacts(getField(stateContent ?? "", "Scope"), stateContent)) {
     return questionFilesInDir(join(rec, stage.phase, stage.slug), null);
   }

   This mirrors resolveArtifactResolution's branch exactly, so writer and reader agree by construction. Callers already pass stateContent at all three blocking sites (aidlc-log.ts:1703, aidlc-state.ts:3364, and the orchestrate report path).

2. Resolve the questions file through resolveArtifactInstances instead of by directory walk, so there is one code path deciding where a per-unit stage's files live. More invasive, but removes the whole class of drift — [Bug]: traceability sensor can never pass on zero-Unit code-generation (poc/bugfix/refactor/security-patch/express) #1011 is the same class of defect in a different component (aidlc-sensor-traceability.ts extractUnitName deriving a Unit from a path that has none).

3. Whichever route, a regression test at the checkSummaryConfirmationEvidence level covering units-generation: SKIP + a summary_confirmation: required per-unit stage would pin it.

Relationship to existing issues

• unit-major: per-unit summary-confirmation guard deadlocks routing for kind-vacuous units #864 (closed, fixed by fix: kind-vacuous units no longer deadlock per-unit summary-confirmation routing #912) produces the byte-identical error string, but from the options.unit-bearing path for kind-vacuous units. fix: kind-vacuous units no longer deadlock per-unit summary-confirmation routing #912's vacuity filter is present at a277af2 (aidlc-orchestrate.ts:5295, :7151-7155) and does not touch the directory the scanner walks — verified that it does not cover this case.
• [Bug]: traceability sensor can never pass on zero-Unit code-generation (poc/bugfix/refactor/security-patch/express) #1011 is the same zero-Unit-path-derivation class, in the traceability sensor. That one is advisory; this one hard-blocks.
• [Bug]: checkSummaryConfirmationEvidence matches ARTIFACT_* rows by absolute path — a workspace cloned to a different directory deadlocks, and review-freeze blocks the prescribed remedy #863 (fixed by fix: preserve summary write receipts across workspace moves #918) and [Bug]: checkSummaryConfirmationEvidence accepts the reviewer's ## Review append as the post-confirmation artifact write #856 (open) are in the same function but concern the post-receipt artifact-write scan, not the questions-file scan. Orthogonal — a fix here should leave both alone.
• [Feature]: Separate per-unit artifact folders from stage-diary folders under construction/ #862 / PR fix: separate per-unit artifact folders from stage folders under construction/ (#862) #1005 is directly adjacent: the readdirSync(<record>/construction) above is exactly the "enumerate every construction/ child as a unit" pattern that PR calls out. Moving units to construction/units/<unit>/ changes the directory this scanner walks but does not by itself add the zero-Unit branch — so the two want sequencing.

Happy to open a PR for direction 1 with a regression test if that is the preferred shape.

[skalugin]

Independent reproduction — surfaced during a live AI-DLC workshop.

This came up in a hands-on workshop session, not a synthetic repro: Claude Code harness,
stock refactor scope, functional-design stage, framework state v8. The
construction/functional-design/functional-design-questions.md file existed with a single
[Answer]: Looks correct, and SUMMARY_CONFIRMATION_RECORDED named that exact stage-level
path — yet aidlc-log review and aidlc-state gate-start both refused with "its question
flow has no functional-design-questions.md file".

I line-verified the mechanism against source and it matches your write-up exactly
(summaryQuestionFiles at aidlc-lib.ts:6971 branching only on isPerUnitStage; the
questions.length === 0 refusal firing before the sole usesStageLevelPerUnitArtifacts
call in checkSummaryConfirmationEvidence, which only gates the bolt-DAG check) — so
nothing to add to the analysis, just a second independent data point that this hard-blocks
real users during live sessions.

AIDLC_SKIP_SUMMARY_CONFIRMATION_GUARD=1 was likewise the only unblock, with the same
downsides you flag. +1 for fix direction 1 (thread stateContent into summaryQuestionFiles
so writer and reader agree by construction); happy to validate a PR against a live
refactor run.

[leeyoseph-dev]

Thanks for the independent line-verification, and for confirming the env-var is the only unblock. One piece of scope information that a single-scope repro does not surface, and that changes the size of the fix.

refactor is not the only affected stock scope. Six of the eleven have the same shape.

The trap is structural: a scope that SKIPs units-generation while EXECUTEing any stage declared for_each: unit-of-work. Exactly five stages carry that declaration at a277af218f0d — functional-design, nfr-requirements, nfr-design, infrastructure-design, code-generation. Any scope that drops unit generation but keeps one of those five arrives with zero Units, the engine resolves the stage-level path, and summaryQuestionFiles still scans the per-unit one.

Each scope file states its own membership in prose, so this is checkable without running anything:

Scope	Explicitly skips units-generation	for_each stages it still runs
bugfix	yes	code-generation
poc	yes	code-generation
express	yes (not in its grid)	code-generation
refactor	yes	functional-design, code-generation
security-patch	yes	nfr-requirements, code-generation
infra	yes	nfr-requirements, nfr-design, infrastructure-design

The remaining five (classic, enterprise, feature, mvp, workshop) do not list units-generation among their skips; I have only positively verified mvp, from a live run whose state file shows units-generation — EXECUTE.

aidlc-infra.md documents the contradiction in its own words: "ideation, user-stories, domain-design, units-generation, and code-generation are skipped … the NFR + infrastructure design stages … are EXECUTE" — and those three NFR/infra stages are precisely the for_each ones.

Two consequences for the fix:

1. infra is the better test case than refactor. It trips the guard on three different stages instead of one, and on the NFR/infrastructure path rather than the code-generation path — so it exercises the resolution mismatch where the two paths diverge most. Direction 1 (thread stateContent into summaryQuestionFiles) is still right precisely because it is scope-independent, but a matrix that only covers refactor would miss whether the NFR stages resolve identically.

2. The walking-skeleton autonomy ladder may be a second casualty. stage-protocol-construction.md states the ladder is not presented for "skeleton-off or zero-Unit execution". A trapped scope is zero-Unit by construction, so it also silently loses the Construction autonomy choice. Worth confirming whether that suppression is intended for zero-Unit generally or is collateral from the same root cause.

One usability note, since you hit this in a live workshop: the single change that would have saved us the most time is not the fix but the refusal text. "its question flow has no <stage>-questions.md file" is false at the moment it is printed — the file exists, and the writer named that exact path a moment earlier. Printing the path actually searched would turn this into a two-minute diagnosis. That holds regardless of which fix direction lands.

For what it is worth, we now avoid all six and use mvp --depth Minimal for small work. Heavier than it should be, but deadlock-free across a full cycle.

[apackeer]

Fixed by #1110, merged to main as 7998589.

summaryQuestionFiles now follows the approved plan's artifact placement: when the effective plan does not EXECUTE units-generation, discovery reads the stage-level path (construction/<stage>/) instead of scanning construction/<unit>/<stage>/. The rule keys on the effective plan rather than a scope list, so it covers every scope that skips Units Generation while executing a for_each: unit-of-work stage, including the six listed in this thread.

Both refusal paths from the reports pass workflow state into the check: aidlc-log review and aidlc-state gate-start. Isolated --single runs keep their own placement by design.

Regression coverage: tests/unit/t332-summary-authorization.test.ts (infra by default, feature with a SKIP override, obsolete Unit folders ignored) and tests/integration/t127-single-stage-invariant.test.ts.

If a build containing 7998589 still refuses, please reopen with the scope, stage, and the exact refusal.