feat: add workflow progress trail to assistant responses

[XinyuQu]

Summary

Closes #247. Adds a new MANDATORY: Workflow Progress Trail rule to core-workflow.md that requires the AI agent to append a one-line breadcrumb at the end of every assistant response during an active AI-DLC session, derived from aidlc-docs/aidlc-state.md.

The trail surfaces existing state into the chat surface where the user is actually looking — answering "where am I?" and "what's coming up next?" without requiring the user to open aidlc-state.md or execution-plan.md mid-conversation.

Changes

Single file modified: aidlc-rules/aws-aidlc-rules/core-workflow.md (+70 lines, −0).

• Added a new top-level ## MANDATORY: Workflow Progress Trail section, placed alongside existing MANDATORY: blocks (Content Validation, Question File Format, Custom Welcome Message). Defines:
  • Output format: AI-DLC Progress: <stage1> (<status>) -> <stage2> (<status>) -> ...
  • Status values (plain text, no emoji): (done), (in progress), (skipped), (pending), (pending, conditional)
  • Uniform collapse model at three levels (Inception phase, each Construction Unit, Build and Test): each level renders as a single entry when fully done or fully pending; expands when active.
  • Construction unit-count visibility gated on Units Generation status: until Units Generation is terminal, render construction (pending) placeholder rather than fabricating a unit count.
  • Active-next expansion: the first not-fully-done unit always expands (even if all its stages are still pending) so the user sees what's coming up.
  • Skip conditions (no aidlc-state.md yet, or workflow complete).
  • Three worked examples (mid-Construction, mid-Inception, between-Inception-and-Construction).
• Added a "trail emission" step (MANDATORY: Append workflow progress trail per ...) to the execution block of each Inception stage (7) and each Construction stage (5 per-unit + Build and Test = 6). 13 total — one for every stage that ends with a user-visible response.
• Added a Workflow Progress Trail entry to the ## Key Principles list, mirroring the placement of Plan-Level Checkbox Enforcement added in PR fix: update execution-plan.md status on stage completion #69.

No changes to aidlc-state.md schema, execution-plan.md format, the extension framework, or any rule-detail file under aidlc-rules/aws-aidlc-rule-details/.

User experience

Before: During a long AI-DLC workflow, the user has no in-chat indicator of which stage is current, which were skipped, or how many remain. The information lives in aidlc-state.md, audit.md, and execution-plan.md (Mermaid + checklist), but accessing it requires switching context and opening files mid-conversation.

After: Every assistant response in an active AI-DLC session ends with a single line like:

AI-DLC Progress: inception (done) -> Unit 1/3 (done) -> Unit 2/3 (in progress): functional-design (in progress) -> nfr-requirements (pending, conditional) -> nfr-design (pending, conditional) -> infrastructure-design (pending, conditional) -> code-generation (pending) -> Unit 3/3 (pending) -> build-and-test (pending)

The user can see at a glance: Inception is done, Unit 1 is finished, Unit 2 is mid-flight on functional design, Unit 3 hasn't started, and Build and Test is the final step. No file-switching required.

Token cost: ~1 line per assistant turn (~30 tokens). aidlc-state.md is already read as part of session continuity, so no new file-read overhead.

Checklist

• I have reviewed the contributing guidelines
• I have performed a self-review of this change
• Changes have been tested
• Changes are documented

Test Plan

1. markdownlint (full repo, 58 files):

$ npx markdownlint-cli2 "**/*.md"
markdownlint-cli2 v0.22.1 (markdownlint v0.40.0)
Linting: 58 file(s)
Summary: 0 error(s)

2. Reachability check — trail-emission step present in every stage's execution block:

$ grep -c "Append workflow progress trail per" aidlc-rules/aws-aidlc-rules/core-workflow.md
13

(7 Inception + 5 per-unit Construction + 1 Build and Test = 13.)

3. Sandbox test environment — installed the modified rules into an isolated test directory at the path the rule's MANDATORY: Rule Details Loading block resolves for non-Kiro/non-AmazonQ tools (.aidlc-rules/ + .aidlc-rule-details/):

/tmp/aidlc-sandbox/
├── .aidlc-rules/
│   └── core-workflow.md         (modified)
├── .aidlc-rule-details/         (full copy of aws-aidlc-rule-details/)
│   ├── common/  construction/  extensions/  inception/  operations/
└── aidlc-docs/
    └── aidlc-state.md           (synthetic state files)

4. Synthetic state-file scenarios — exercised the rule's rendering logic against four aidlc-state.md shapes covering the full workflow span:

#	Scenario	Expected behavior	Result
1	Brownfield, mid-Construction (Unit 2 of 3 in progress)	Inception collapsed; Unit 1 collapsed; Unit 2 expanded; Unit 3 collapsed	PASS
2	Mid-Inception, Units Generation not yet run	Inception expanded; Construction shown as construction (pending) placeholder (no fake unit count)	PASS
3	Inception just completed, Units Generation produced 3 units, Construction not yet started	Inception collapsed; Unit 1 expanded as active-next; Units 2 and 3 collapsed	PASS
4	Units Generation skipped (single implicit unit), Code Generation in progress	Inception collapsed; Unit 1/1 expanded with current state	PASS

Each scenario produces output that matches one of the three worked examples embedded in the rule, byte-for-byte (verified by diff).

5. Length comparison — full-expand vs. uniform-collapse model on the brownfield mid-Construction scenario:

Model	Trail entries
Full expand (rejected)	23
Uniform collapse	9

The collapse model keeps long workflows scannable while preserving full visibility of the active and active-next phase/unit.

Acknowledgment

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of the project license.