feat: bring product discovery into Ideation — an idea-to-decision flow that feeds Inception (2.2.11)

AGENTS.md

@@ -22,7 +22,7 @@ The hand-authored source lives in `core/` (harness-neutral) + `harness/<name>/`
 (per-CLI surfaces); `bun scripts/package.ts` regenerates the `dist/<harness>/`
 trees. The core uses the same building blocks in every harness:
 
-- **Skills** (`skills/aidlc/`) — Orchestrator (`SKILL.md`), stage protocol, and 32 stage files across 5 phases (initialization, ideation, inception, construction, operation)
+- **Skills** (`skills/aidlc/`) — Orchestrator (`SKILL.md`), stage protocol, and 36 stage files across 5 phases (initialization, ideation, inception, construction, operation)
 - **Agents** (`agents/`) — 14 `aidlc-<role>-agent.md` files: 11 domain-expert personas (product, design, delivery, architect, aws-platform, compliance, devsecops, developer, quality, pipeline-deploy, operations), 2 review-only agents (product-lead, architecture-reviewer), and the adaptive-workflows composer (aidlc-composer-agent)
 - **Method/rules** (`memory/`) — Layered config in the space memory layer: `org.md` (framework defaults), `team.md` (affirmed practices), `project.md` (project overrides), and `phases/<phase>.md` for ideation/inception/construction/operation
 - **Sensors** (`sensors/`) — Deterministic verification manifests (advisory): `aidlc-required-sections.md`, `aidlc-upstream-coverage.md`, `aidlc-linter.md`, `aidlc-type-check.md`

CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to this project will be documented in this file.
 
+## [2.2.11] - 2026-07-08
+
+Adds an opt-in `discovery` scope that runs ideation as an idea-to-decision flow, and extends the existing `intent-capture` stage — for every scope that runs it — to work materials-first. Intent-capture now opens with one intake question for the asks and materials behind an initiative, answers its clarifying questions from them (material-derived answers carry their source, stay `unconfirmed`, and are confirmed or corrected at the stage's approval gate), records any mandate and decide-by date, and produces two new artifacts every scope benefits from: a source inventory and an open questions record. **For existing scopes the change is additive: the clarifying questions are unchanged, no new hard-failure path exists, and a stock run gains one intake question plus the two new artifacts** ("None" is a valid inventory). Under `discovery`, intent-capture is the entry point to four new ideation stages that build an evidenced picture of the current state, express the future state as options, test the riskiest assumptions first, and end in an explicit commit, pivot, or park decision. The scope ships with framework-default artifact templates — the first tier-2 templates to ship. No stock scope gains or loses stages and the six pre-existing delivery-path ideation stage files (1.2-1.7) are untouched, but shared surfaces shift as counts: progress denominators go from `(N/32 overall)` to `(N/36 overall)`, help and status text now reads "32 of 36 stages" for the full scopes, and new state files list the four discovery stages as SKIP rows under stock scopes. Discovery is reachable only by explicit `/aidlc discovery` or `--scope discovery`. **Upgrade:** re-copy your `dist/<harness>/` shell into the project to pick up the extended stage, the new scope, stage files, and templates.
+
+* EXTENDED `intent-capture` (1.1), additively: a materials-first intake question before the questionnaire (asked through the stage's questions file, so the forwarding-loop Stop hook sees the wait), the person's own reading recorded before any agent synthesis, source labels on answers, mandate and decide-by capture, conditional intent-statement sections (Where This Came From, Already Decided, Decide-By Date), and two new produces (`source-inventory`, `open-questions-record`). The clarifying questions and their gate are unchanged.
+* NEW `discovery` scope (8 stages: 3 initialization + intent-capture + 4 discovery ideation stages) ending in a commit / pivot / park decision gate.
+* NEW four ideation stage files, `discovery-current-state` (1.8) through `discovery-decision` (1.11), with evidence-order and riskiest-first-testing mechanics, wired behind intent-capture.
+* The validated vision is wired into delivery, not left to conductor goodwill: on a commit the decision stage appends a structured **handoff contract** to the decision pack (settled entries as pre-answers, exclusions as boundaries, open items with recommendations, promoted starting points, and a map to where the record answers delivery's first questions) and refreshes the intent statement with a **What Discovery Validated** section. `requirements-analysis` and `user-stories` each gain `decision-pack` as an OPTIONAL consume (`required: false`) plus matching prose, and `refined-mockups` gains `design-language-record` and `evidence-record` the same way (the validated design language and people-tested mock-up variants reach the stage whose job is UI design) — for the stock scopes the pack never exists and an absent optional input is dropped silently, so their behavior is unchanged; when it exists, the run-stage directive hands them its path and the upstream-coverage sensor verifies it was referenced. The recovery protocol's ideation block now spans 1.1–1.11 and names the pack as load-bearing resume context.
+* The orchestrator SKILL's never-call-the-state-tools rule gains its missing exception sentence: a stage body may explicitly relay a named workflow-level verb (`jump`, `park`, `scope-change`, `set-status`, `state skip`) — the discovery decision stage instructs exactly these, and the two rules no longer contradict.
+* NEW nine framework-default templates under `tools/data/templates/` — the first shipped tier-2 templates; team overrides still win. `intent-statement` deliberately ships no template, so its conditional sections never become required headings for existing scopes.
+* Stage graph grows 32 to 36 and the scope table gains a discovery column. The welcome banner's scope table also corrects two pre-existing wrong cells against the compiled grid (infra INCEPTION reads PD, RA and security-patch RE reads RE, RA).
+* No keyword routing changes (discovery ships `keywords: []`).
+* RFC reference: issue #517.
 ## [2.2.10] - 2026-07-06
 
 Workspace detection now recognizes git submodules. A workspace whose code lives in uninitialized submodules (empty dirs plus a `.gitmodules` file) previously scanned as Greenfield, so reverse-engineering was auto-skipped and every design stage ran with zero code understanding. The scanner gains a sixth brownfield signal: a parseable `.gitmodules` with at least one submodule path entry classifies the workspace Brownfield. When submodule paths are uninitialized, the scan warns and names the remedy (`git submodule update --init --recursive`) at birth, in the doctor report, and on `detect`. Languages stay as scanned (Unknown is truthful until the submodules are fetched). **Upgrade:** re-copy your `dist/<harness>/` shell into the project.

README.md

@@ -4,11 +4,11 @@
 > **GA Preview — under active development.** AI-DLC Workflows 2.0 is a GA Preview release. Interfaces, stage definitions, the agent roster, and the install model are still evolving, and breaking changes can land between releases. Expect rough edges, pin a known-good version for anything you depend on, and review all generated output before you act on it. See the [roadmap](https://awslabs.github.io/aidlc-workflows/roadmap.html) for what's shipped, in flight, and planned.
 > **For production use, stay on the stable [`main`](https://github.com/awslabs/aidlc-workflows/tree/main) branch.**
 
-A native implementation of the **AI-DLC methodology** (AI-Driven Development Life Cycle) that runs on **many harnesses from one source of truth** — today Claude Code, Kiro IDE, Kiro CLI, and Codex CLI, and any capable harness you port it to. Run a full software-development lifecycle — 11 domain-expert agents working through a 32-stage workflow, and you approve every gate — in whichever harness you use.
+A native implementation of the **AI-DLC methodology** (AI-Driven Development Life Cycle) that runs on **many harnesses from one source of truth** — today Claude Code, Kiro IDE, Kiro CLI, and Codex CLI, and any capable harness you port it to. Run a full software-development lifecycle — 11 domain-expert agents working through a 36-stage workflow, and you approve every gate — in whichever harness you use.
 
 The methodology lives once, in a harness-neutral `core/`; each harness adds a thin surface that decides how it shows up on that harness. So you edit the methodology in one place, and every harness distribution is generated from it — no harness gets special treatment. (See [Repository layout](#repository-layout) for how the pieces fit together.)
 
-![version](https://img.shields.io/badge/version-2.2.10-blue)
+![version](https://img.shields.io/badge/version-2.2.11-blue)
 ![license](https://img.shields.io/badge/license-MIT--0-green)
 ![Kiro IDE](https://img.shields.io/badge/harness-Kiro%20IDE-orange)
 ![Kiro CLI](https://img.shields.io/badge/harness-Kiro%20CLI-orange)
@@ -29,9 +29,9 @@ Ad-hoc AI coding works until the project gets real. Then context drifts between
 
 ## Key Features
 
-- **[5 phases, 32 stages](docs/guide/04-phases-and-stages.md)** — Initialization, Ideation, Inception, Construction, Operation
+- **[5 phases, 36 stages](docs/guide/04-phases-and-stages.md)** — Initialization, Ideation, Inception, Construction, Operation
 - **[11 domain-expert agents](docs/guide/06-agents.md)** — product, design, delivery, architect, aws-platform, compliance, devsecops, developer, quality, pipeline-deploy, operations
-- **[9 adaptive scopes](docs/guide/05-scopes-and-depth.md)** (enterprise through workshop) with auto-detection from freeform intent
+- **[10 adaptive scopes](docs/guide/05-scopes-and-depth.md)** (enterprise through workshop, plus the opt-in discovery) with auto-detection from freeform intent
 - **[3 depth levels](docs/guide/05-scopes-and-depth.md#the-3-depth-levels)** (Minimal/Standard/Comprehensive) — control artifact detail per stage
 - **[3 test strategy levels](docs/guide/05-scopes-and-depth.md#the-3-test-strategy-levels)** (Minimal/Standard/Comprehensive) — independent of depth for flexible test coverage
 - **[CLI utilities](docs/guide/12-cli-commands.md)** — jump to any stage or phase, check status, change scope/depth/test strategy mid-workflow
@@ -240,7 +240,7 @@ aidlc-claude/
 │  ─────────── HAND-AUTHORED SOURCE — edit here ───────────
 ├── core/                       # ONE harness-neutral source of truth
 │   ├── tools/                  #   25 aidlc-*.ts engine tools (+ data/scaffold/ templates)
-│   ├── aidlc-common/           #   stage protocol + 32 stage files + conductor
+│   ├── aidlc-common/           #   stage protocol + 36 stage files + conductor
 │   ├── agents/                 #   11 domain-expert personas
 │   ├── knowledge/ memory/ scopes/ sensors/ hooks/
 │   ├── skills/                 #   3 session skills (session-cost, replay, outcomes-pack)

core/agents/aidlc-composer-agent.md

@@ -15,7 +15,7 @@ modelOverride: opus
 
 # Composer Agent
 
-You are the AI-DLC workflow composer. A scope is a checklist of which of the 32
+You are the AI-DLC workflow composer. A scope is a checklist of which of the 36
 stages run (an EXECUTE/SKIP grid); your job is to propose the checklist that
 actually fits the task in front of you, instead of the keyword guess or the
 static default. The deterministic engine runs whatever grid is approved; you

core/aidlc-common/protocols/stage-protocol-recovery.md

@@ -57,8 +57,9 @@ When resuming, load context appropriate to the current phase and stage type:
 - Workspace Detection loads fresh filesystem scan
 - State Init reads workspace classification from Workspace Detection
 
-**IDEATION stages (1.1–1.7):**
+**IDEATION stages (1.1–1.11):**
 - Load `<record>/ideation/` artifacts completed so far (intent capture, market research, feasibility, scope)
+- For a discovery run (stages 1.8–1.11), the decision pack and evidence record are the load-bearing context — reload them first, along with the assumptions record and the open questions record
 - Load guardrails from `{{HARNESS_DIR}}/rules/`
 
 **INCEPTION — RE (Reverse Engineering) stages:**

core/aidlc-common/protocols/stage-protocol.md

@@ -193,14 +193,14 @@ Then present the structured approval question as defined above.
 ### Part 4: Progress update (mandatory — after user approves)
 After the user selects "Approve", display a progress line before proceeding.
 
-**For enterprise and feature scopes** (all 32 stages active):
+**For enterprise and feature scopes** (the graph holds 36 stages; enterprise and feature execute all 32 delivery-path stages — every stage except the 4 discovery-only ideation stages):
 ```
-Progress: [N]/32 overall | [phase-N]/[phase-total] [Phase] stages complete. Next: [Next Stage Name]
+Progress: [N]/36 overall | [phase-N]/[phase-total] [Phase] stages complete. Next: [Next Stage Name]
 ```
 
 **For all other scopes** (fewer stages in scope), show in-scope progress with overall shown parenthetically:
 ```
-Progress: [X]/[S] in-scope stages complete ([N]/32 overall) | [phase-N]/[phase-total] [Phase]. Next: [Next Stage Name]
+Progress: [X]/[S] in-scope stages complete ([N]/36 overall) | [phase-N]/[phase-total] [Phase]. Next: [Next Stage Name]
 ```
 Where `S` = total stages for the current scope. Reference scope stage counts:
 | Scope | In-scope stages (S) |
@@ -211,11 +211,12 @@ Where `S` = total stages for the current scope. Reference scope stage counts:
 | refactor | ~9 |
 | infra | ~13 |
 | security-patch | ~10 |
+| discovery | 8 (3 initialization + 5 ideation) |
 
-Example (enterprise): "Progress: 13/32 overall | 3/7 IDEATION stages complete. Next: Approval & Handoff"
-Example (bugfix): "Progress: 5/8 in-scope stages complete (7/32 overall) | 2/3 CONSTRUCTION. Next: Build & Test"
+Example (enterprise): "Progress: 13/36 overall | 3/7 IDEATION stages complete. Next: Approval & Handoff"
+Example (bugfix): "Progress: 5/8 in-scope stages complete (7/36 overall) | 2/3 CONSTRUCTION. Next: Build & Test"
 
-Count only stages in the current phase (INITIALIZATION, IDEATION, INCEPTION, CONSTRUCTION, or OPERATION). Include both completed and skipped stages in the numerator.
+Count only stages in the current phase (INITIALIZATION, IDEATION, INCEPTION, CONSTRUCTION, or OPERATION), and only stages the active scope executes — plan SKIP rows are outside both the phase numerator and the phase total. In the numerator, include stages completed and stages runtime-skipped (`[S]`) during the run. The overall counter works the same way against the full graph: completed plus `[S]` over 36, so a finished feature run reads 32/36 (the four discovery SKIP rows are counted by neither side).
 
 ---
 
@@ -401,7 +402,7 @@ Rules:
 - The `[slug]` suffix in `activeForm` is required. A PostToolUse hook parses it to automatically sync the state file (Lifecycle Phase, Current Stage, Active Agent, checkbox `[-]`).
 - The task MUST be `in_progress` for the activeForm spinner to display — `pending` tasks show nothing.
 - Update BEFORE reading the stage file or doing any stage work.
-- This applies to all 32 stages. No exceptions.
+- This applies to all 36 stages. No exceptions.
 - If task IDs are not in context (e.g., after compaction), use `TaskList` to find by subject.
 - For skipped stages, mark completed with skip note: TaskUpdate({ taskId: [ID], status: "completed", description: "[original] — Skipped: [reason]" })
 
@@ -626,19 +627,20 @@ Create exactly the detail needed — no more, no less. Depth adapts to scope and
 ### Scope-to-depth mapping
 | Scope | Default Depth | Typical Stages |
 |-------|--------------|----------------|
-| enterprise | Comprehensive | All 32 |
-| feature | Standard | All 32 |
+| enterprise | Comprehensive | All 32 delivery-path |
+| feature | Standard | All 32 delivery-path |
 | mvp | Standard | ~25 (skip late Operation) |
 | poc | Minimal | ~8 (Ideation + core Inception) |
 | bugfix | Minimal | ~8 (targeted) |
 | refactor | Minimal | ~9 (targeted) |
 | infra | Standard | ~13 (infra-focused) |
 | security-patch | Minimal | ~10 (security-focused) |
+| discovery | Standard | 8 (idea-to-decision) |
 
 ### Depth levels
 - **Minimal** (poc, bugfix, refactor, security-patch): ~2-4 questions per stage, minimal artifacts, brief analysis
-- **Standard** (feature, mvp, infra): ~5-8 questions per stage, full artifacts at moderate detail
-- **Comprehensive** (enterprise): ~8-12+ questions per stage, comprehensive artifacts with deep analysis, all stages execute
+- **Standard** (feature, mvp, infra, discovery): ~5-8 questions per stage, full artifacts at moderate detail
+- **Comprehensive** (enterprise): ~8-12+ questions per stage, comprehensive artifacts with deep analysis, all delivery-path stages execute
 
 The orchestrator determines appropriate depth based on scope selection. Users can override at three points:
 1. Via the `--depth` flag: `/aidlc --scope bugfix --depth comprehensive` or `/aidlc --depth minimal`
@@ -708,7 +710,7 @@ Key terms used throughout AI-DLC documentation:
 |------|-----------|
 | **Phase** | Top-level grouping: INITIALIZATION, IDEATION, INCEPTION, CONSTRUCTION, OPERATION |
 | **Stage** | A discrete step within a phase (e.g., Intent Capture, Requirements Analysis, Code Generation, Observability Setup) |
-| **Scope** | Controls which stages execute and at what depth. Nine built-in scopes, one file per scope under `{{HARNESS_DIR}}/scopes/aidlc-<name>.md`: enterprise, feature, mvp, poc, bugfix, refactor, infra, security-patch, workshop. Custom scopes can be added without editing this file. |
+| **Scope** | Controls which stages execute and at what depth. Ten built-in scopes, one file per scope under `{{HARNESS_DIR}}/scopes/aidlc-<name>.md`: enterprise, feature, mvp, poc, bugfix, refactor, infra, security-patch, workshop, discovery. Custom scopes can be added without editing this file. |
 | **Bolt** | One execution of Construction stages 3.1–3.5 for a Unit (or small group of dependency-linked Units). Stages 3.6 (Build and Test) and 3.7 (CI Pipeline) run **once** after all Bolts complete, not per-Bolt. The first Bolt is the **walking skeleton** — the thinnest end-to-end slice that proves the architecture. |
 | **Walking skeleton** | The first Bolt in Construction — smallest end-to-end slice that exercises every integration point. Always gated and interactive so humans can confirm the shape before the rest of Construction runs. |
 | **Ladder prompt** | The single prompt that fires after the walking-skeleton gate asking the user to choose between "continue autonomously" and "gate every Bolt". The choice is recorded in state (`Construction Autonomy Mode`) and governs the rest of Construction. |
@@ -746,7 +748,7 @@ Before creating any artifact file, validate:
 ### Template overrides
 Before writing artifact `X` (keyed by the output filename stem — artifact `X` writes to `X.md`), resolve its template in this order, override-before-default, first hit wins:
 1. **team template** — `aidlc/spaces/<space>/memory/templates/X.md` (the active space's hand-authored override);
-2. **framework default** — the engine-shipped default `X.md` *if one ships* (none ship at GA, so this normally misses);
+2. **framework default** — the engine-shipped default `X.md` *if one ships* (the framework ships nine defaults, one per discovery artifact; other artifacts miss here);
 3. **else** — no template: follow the stage's existing prose.
 
 If a template resolves (tier 1 or 2), follow its structure: use its `##` headings as the skeleton to fill. A resolved template is used whole-doc (verbatim structure, no section merge). The `required-sections` sensor verifies the output against the SAME resolution order and the SAME file, so the produced shape and the checked shape cannot drift.