[RFC]: A handover contract for product discovery done outside AI-DLC

Nobody has claimed this yet.

## Summary

Establish a handover contract for discovery done outside AI-DLC. Currently, teams may use whatever preferred tooling (eg: Amazon Quick, Codex, etc) to conduct their product discovery workflows. AI-DLC has been designed around CLI-based coding agents, and this may not be the starting point for all product or non-technical teams in their product discovery phase. Given they may have separate tools/workflows, a team that finished discovery elsewhere will end up re-answering AI-DLC's intake from scratch.

We propose instead they hand a package to intent capture, which fast-tracks them to the appropriate stage, while populating the right artefacts and ensuring the existing information gets leveraged across the entire workflow.

## Motivation

Teams do ideation in the tools closest to their stakeholders. We see examples of handover contracts from the Ideation Discovery phase from PR-526, but also from the following repos:
- @clairmit's https://github.com/subcontext/agentic-product-discovery emits `apd.yaml`, a versioned YAML file it describes as the initial input to AI-DLC Ideation and Inception.
- Rachna's https://github.com/aws-samples/sample-ai-plc, a markdown prompt pack, produces a Discovery Document and portable prototype specs. Handover is copying files by hand, with no contract or conformance check.

Each built an end point aimed at AI-DLC, and AI-DLC defines no start point to receive it. Field feedback asks for the same: standardised output from any implementation of ideation.

The cost today: `core/aidlc-common/stages/ideation/intent-capture.md` asks one multi-select intake question and four clarifying questions, plus follow-ups. A team arriving with finished discovery answers them all again, their settled answers reduced to loose prose the intake cannot tell from a hunch. The contract deletes that duplication and the tool lock-in with it: settled answers arrive pre-filled, confirmed at the gate instead of re-typed.

PR #526 shipped the outbound half: on commit, `core/aidlc-common/stages/ideation/discovery-decision.md` appends a handoff contract to the decision pack (the business case behind the commit, pivot or park decision). The inbound half is missing, and the two should be the same shape.

## Detailed Proposal

### Goals

One contract, both directions: AI-DLC's discovery commit emits it, any tool can produce it, and intake pre-fills only what its contents cover.

### Non-goals

No new engine machinery, gates or state. No transport layer, the package arrives however the team moves files. External tools keep their internals. Amazon Quick or any named product integration is out of scope for this request. Extending beyond discovery-to-inception, so other handovers into AI-DLC share this shape, is a direction for later, not this RFC.

### What the package contains

It builds on the four parts the shipped handoff contract already carries. A suggested structure:

- **Provenance** - who produced it, when, from what tool, contract version.
- **Settled** - answers and supported assumptions as requirements, with evidence.
- **Exclusions** - what was ruled out and why.
- **Open items** - unknowns, each with a recommendation or "ask the person".
- **Starting points** - artifacts worth carrying, a prototype or spec, by path.

Every entry carries the shipped contract's five fields: value, status, confidence, who confirmed it and when, source. A minimal example:

```markdown
# Discovery handover package

## Provenance
agentic-product-discovery, 2026-07-10, contract version 1.

## Settled
Field engineers re-key inspection results twice per visit.
Settled, high confidence, confirmed at workshop sign-off,
source site-visits.md.

## Exclusions
No offline-first app in release one. Source pilot-notes.md.

## Open items
Launch order. Recommendation: pilot region first. Low
confidence, ask the person.

## Starting points
prototype/inspection-form/ (a mock-up ten users tested)
```

### How intake consumes it

No new mechanism. Intent capture already reads supplied materials, labels every derived answer with its source, and keeps it unconfirmed until the person confirms at the stage's gate (`intent-capture.md` Steps 4 to 7). The package becomes a first-class input to that step. Settled entries pre-fill the clarifying questions they answer. Open items land in `open-questions-record.md`, recommendations intact. Exclusions become boundaries in the intent statement. Starting points register in `source-inventory.md`. Everything waits unconfirmed at the existing gate. No new gates.

The fast-track is the same move PR #526 already uses on commit: where the package covers what a stage would have produced, the run records that stage as skipped with the package named as the reason (the engine's existing skip-with-reason verb), so the person lands at the first stage with genuinely open work.

Why core and not a plugin: the consuming step is intent capture, first in every workflow, and the emitting step is discovery decision, both in core. A contract outside core would mean AI-DLC's own commit path emits a shape core does not recognise.

### What does conformance mean?

Here are a couple of suggestions of the approaches:

- **A documented markdown convention.** One docs page, one template whose H2 headings become the required-sections sensor contract for free (the mechanism that already checks `core/tools/data/templates/decision-pack.md`), at most one advisory sensor. No schema, no linter. Light to maintain, weaker guarantees for producers.
- **A versioned schema with a validator**, the route @clairmit took with `apd.yaml` (a version field, a JSON Schema, a lint script reporting what will be asked versus pre-filled). Easier for producers, but a schema and linter are an ongoing maintenance commitment and a new kind of artifact here.

My lean: start with the convention, let a schema earn its way in if producers ask. But you own the maintenance cost. Which fits the framework's direction?

### Testing evidence

Before any PR I would drive and record: a bare intake run and a package-fed run of the same initiative, counting questions asked in each, so the saving is measured not asserted. Two conformance examples, one from agentic-product-discovery outputs, one from a sample-ai-plc run. And a round trip: commit in AI-DLC's own discovery, feed the emitted contract to a fresh intake.

### Acceptance

I will strive to prepare a PR draft as a reference implementation and test, but the capability has been prior validated from the aforementioned PR and repos. I request scope agreement on this RFC before any PR. If the direction is wrong, no code should be committed.

## Alternatives Considered

- **Do nothing.** External work enters as supplied materials through the intake. That works, but settled answers lose their status on entry, and nothing tells an external tool what to produce, so every producer invents its own end point.
- **Adopt `apd.yaml` as-is.** Real prior art, and we based parts of this design on it. But it is shaped around one tool's outputs, its stage map hardcodes AI-DLC stage names that go stale on rename, and adopting it imports a JSON Schema and a Ruby linter into this repo.
- **An importer per tool.** Rejected on maintenance cost. Every new tool would mean new code here. One contract puts a small, one-time cost on each producer instead.

## Drawbacks

- A public contract is a maintenance commitment. Once external tools produce it, changes need versioning and care. A producer on version 1 meeting an installation expecting version 2 needs a defined outcome, even if that is "treated as plain materials".
- Packages can overstate evidence. A file saying confirmed and high confidence proves nothing, so intake keeps every package-derived answer unconfirmed until a person confirms it at the gate, as it treats materials today.
- Context cost: one more template and docs page in core. Under the convention option that is the entire footprint.

## Additional Context

This builds on PR #526 and lands after it - the materials-first intake and emitted handoff contract both ship there.

Beyond the conformance choice, four open questions for you: when is a package complete enough to accept, and how does intake tell incomplete from intentionally sparse? How do open unknowns keep their owner, recommendation and confidence? What evidence travels inside the package and what stays a link when the receiver cannot reach the producer's paths? And how does a producer learn which contract versions an installation accepts?

Shoutout to @clairmit's agentic-product-discovery, which proved the pre-fill model and shaped the five entry fields. aws-samples/sample-ai-plc showed a portable markdown spec another tool can build from, and its starting-state detection (look at what exists, skip completed work) is what this contract asks intake to do.

Start by reading core/aidlc-common/stages/ideation/intent-capture.md and discovery-decision.md, then compare the emitted contract from PR #526 with core/tools/data/templates/decision-pack.md. Resolve the conformance and completeness questions before proposing an implementation. Done means the RFC has agreed scope and a reference package, with bare, package-fed, conformance, and round-trip runs recorded.

Written by the indexing model from the issue text.