# AI-DLC State Tracking

## Project Information

- **Project Type**: Brownfield
- **Start Date**: 2026-08-03T18:06:09Z
- **Current Stage**: INCEPTION - Units Generation Part 2 **COMPLETE — at the approval gate, with one
  blocking security finding**

> ## 📍 Read first: this blueprint is `blueprints/teams-bot/`
>
> Moved there 2026-08-04 from `blueprints/course-chatbot/`, which was the wrong home. The participant
> brief's catalog names this building block **"Chatbots (incl. Microsoft Teams-fronted) — basic and
> advanced conversational apps, with Teams as the default frontend for internal users."** Gate
> Question 1 offered `course-chatbot` as its recommended option on a misreading of the Vision brief
> §3, whose "one request deploys one blueprint" line is about demo mechanics rather than scope.
>
> **FR-5 was right originally and its amendment is reverted.** `course-chatbot` is restored to
> byte-identical upstream state and is not Track C's.
>
> Documents under `aidlc-docs/` still say `course-chatbot` throughout. That is deliberate — they
> record what was decided and when, and rewriting them would describe decisions nobody made. Read
> those paths as `blueprints/teams-bot/`.

> ## ⚠️ Also read: implementation exists, and it preceded its design stages
>
> Between the Units Generation gate answers and this update, a working blueprint was **built** —
> template, container image, Bot Framework front door, 16 tests, retrieval, and both pipeline actions,
> committed at `5726794`, `9c77a60` and `0806656` and pushed to the fork.
>
> **That work skipped the entire CONSTRUCTION phase.** Functional Design, NFR Requirements, NFR Design,
> Infrastructure Design and Code Generation — each with its own approval gate, and Code Generation with
> its own planning part — were none of them executed. `core-workflow.md` was not read until after the
> code was written.
>
> This is recorded rather than smoothed over because a workshop teaching this methodology should not
> have its own artifacts imply the process was followed when it was not. The practical consequence:
> **Code Generation will be a plan retro-fitted to code that already exists**, and Infrastructure Design
> has to ratify packaging decisions already made rather than make them.
>
> What the code is: a grounded, personal-chat-only Teams bot. What it is not: `unit-of-work.md`'s ten
> units. Four were withdrawn or deferred — see its **Amendment — delivery status** section, and the
> `VIOLATED` row for FR-9 in `unit-of-work-story-map.md`.

## Execution Plan Summary

- **Total stages remaining**: 8 (2 INCEPTION, 6 CONSTRUCTION)
- **Stages to Execute**: Application Design, Units Generation, Functional Design, NFR Requirements,
  NFR Design, Infrastructure Design, Code Generation, Build and Test
- **Stages to Skip**: User Stories — the deliverable is a parameterised infrastructure template with a
  single persona and no acceptance criteria beyond what requirements already capture
- **Risk Level**: **High** — never-executed container build path; self-deploying pipeline with an
  undocumented recovery procedure; shared account; parallel merges from multiple teams; nearly every
  element is a first for this repository
- **Plan**: `aidlc-docs/inception/plans/execution-plan.md`
- **Work Item**: Microsoft Teams chatbot blueprint

## Workspace State

- **Existing Code**: Yes
- **Programming Languages**: Python 3.11+, YAML (CloudFormation), Bash
- **Build System**: None conventional. `uv` inline script metadata (PEP 723) for Python
  tooling; CloudFormation deployed by CodePipeline; `tools/check` is the local/CI entry point
- **Project Structure**: Infrastructure-as-code monorepo (deploy pipeline plus blueprints)
- **Reverse Engineering Needed**: Yes
- **Workspace Root**: `/home/fermin/codeprojects/ai-dlc-workshop`

## Code Location Rules

- **Application Code**: Workspace root (NEVER in `aidlc-docs/`)
- **Documentation**: `aidlc-docs/` only
- **Repository-specific placement**: blueprint code and templates go under
  `blueprints/<name>/`, with CloudFormation at `blueprints/<name>/infra/<name>.yml`

## Repository Constraints In Force

These come from `CLAUDE.md` and bind every AI-DLC stage. The vendored AI-DLC rules have no
knowledge of them.

- Everything is IaC, deployed through GitHub. No click-ops.
- Serverless-first, region `us-east-1`. Lambda means container images.
- Secrets live only in AWS Secrets Manager. The repository is public and secret scanning
  is disabled by enforced org policy — never write a credential to any file.
- `main` is PR-only, one human approval, enforced by branch protection.
- All four `cornell:*` tags on every AWS resource.
- Stack names follow `<application>-<environment>-<name>`.
- Every CloudFormation template is registered in `pipeline/stacks.yml`, and every
  `deployed_by: pipeline` entry has a matching action in `pipeline/pipeline.yml`.
- `aidlc-rules/` is a verbatim vendored copy. Do not edit anything under it.

## Stage Progress

### 🔵 INCEPTION PHASE

- [x] Workspace Detection
- [x] Reverse Engineering
- [x] Requirements Analysis
- [x] User Stories — **SKIP** (infrastructure template; single persona; no acceptance criteria beyond
      requirements). User may still request it.
- [x] Workflow Planning
- [x] Application Design — **COMPLETE** (5 artifacts; Security Baseline verified, no blocking findings)
- [x] Units Generation — **COMPLETE**. Part 1 approved; Part 2 generated all three artifacts
      2026-08-04. **At the approval gate with one blocking security finding (SECURITY-10)**

### 🟢 CONSTRUCTION PHASE — entered 2026-08-04

**Unit under construction**: the front door (delivered U1+U2+U3+U5+retrieval). The AgentCore step is a
separate unit and is not started.

**All four design stages were skipped while the code was written**, so they run out of order and
retrospectively. Marked below for what they are rather than back-dated:

- [ ] Infrastructure Design — **EXECUTE FIRST**, out of sequence. It owns the container-versus-zip
      record, which is the decision that was instead settled by a character count
- [ ] Functional Design — **RETROSPECTIVE**, depth to be assessed. The framework's own principle is
      "only execute stages that add value"; most of the logic is already described in `components.md`
- [ ] NFR Requirements — **PARTLY SUPERSEDED.** `requirements.md` §6 already carries nine NFRs, two of
      whose justifications the synchronous decision voided (NFR-4, NFR-7). That re-assessment is the
      real work here, not a fresh set
- [ ] NFR Design — **EXECUTE** if NFR Requirements produces anything not already in the template
- [ ] Code Generation — **RETRO-FIT.** A plan written against code that already exists, labelled as
      such. Not a pretence that the plan came first
- [ ] Build and Test — **EXECUTE.** The one stage with no retrospective problem: 16 tests exist,
      `tools/check` is green, and what is missing (an end-to-end test through Teams) is genuinely next

### 🟡 OPERATIONS PHASE

- [ ] Operations — PLACEHOLDER

## Current Status

- **Lifecycle Phase**: INCEPTION
- **Current Stage**: Units Generation — Part 1 (Planning), **at the answer gate**
- **Next Stage**: Units Generation Part 2, then CONSTRUCTION
- **Status**: 🛑 **BLOCKED on upstream reconciliation, 2026-08-04.** Part 1 plan **APPROVED**; Part 2
  generation **must not start yet**.

  The branch was **28 commits behind `upstream/main`** while INCEPTION was written. Merged at
  `318e92f`. Several recorded decisions are now contradicted by merged work — the **Terraform stage
  exists** (built by Marty, the nominated reviewer), the **container Build stage is wired and ARM64**,
  **`builder-mcp` is built**, and the **KB blueprint shipped**. Facts have been corrected in place;
  contradicted decisions are collected in
  **`aidlc-docs/inception/upstream-reconciliation-2026-08-04.md`**.

  **Read that document before generating unit artifacts.** Running Part 2 now would re-plan work
  already merged (U1 is largely delivered) and would specify a Dockerfile layout the repo has moved
  away from. Decisions **D1** (Terraform's scope in U0), **D2** (one Dockerfile or one per component)
  and **D5** (`aidlc-docs/` tracked or untracked) gate it.
- **Resume with**: `docs/AIDLC-TURNOVER-2026-08-04.md` — written for a fresh session, covering the next action,
  every decision made, the accumulated gotchas, and what not to reopen.

### Gate status updated 2026-08-04 — four questions outstanding

**Supersedes the "no questions outstanding" note previously in this section.** The repository was
re-checked against the artifacts; two of the three named gates were already closed, and two further
blockers were found that change what the unit artifacts say.

| Gate | State |
| --- | --- |
| **D1** — Terraform's scope in U0 | **CLOSED.** Settled by the track structure, not by us. `azuread` yes, `azurerm` blocked on Azure subscription RBAC, catalog publish and availability scoping never. |
| **D5** — `aidlc-docs/` tracked | **CLOSED.** Per-component placement, 33 files tracked at `fe7d336`. |
| **D2** — Dockerfile layout | **OPEN** — gate question 2. |
| Deliverable location | **OPEN** — gate question 1. `blueprints/teams-bot/` has never existed in any commit on any branch; `blueprints/course-chatbot/` is a facilitator decision recorded in the brief's §3. Nobody else occupies it, and Track B left the bundle for a standalone `blueprints/knowledgebase/`. |
| Q3 vs the AgentCore mandate | **OPEN** — gate question 3. Determines whether `U6` exists; choosing one Lambda reopens Q9. |
| PR #21's ten answers | **OPEN** — gate question 4. PR still open, so the file is not in this checkout. |

- ~~**Next action**: answer `units-generation-gate-questions.md`~~ — **DONE.** Answered 1C / 2A / 3A
  ("MUST use Agent Core") / 4A, validated for contradictions, none found. A later contradiction between
  gate answer 3 and a supplied decision record was resolved through
  `units-generation-clarification-questions.md`: **AgentCore stands, delivered in two steps**, with
  `_ask()` as the seam.
- ~~generate the three unit artifacts~~ — **DONE.** All three exist:
  `application-design/unit-of-work.md`, `unit-of-work-dependency.md`, `unit-of-work-story-map.md`.
  Every checkbox in `plans/unit-of-work-plan.md` is `[x]`.

### ✅ Units Generation APPROVED 2026-08-04 — CONSTRUCTION entered

Approved with the blocking finding **accepted as a dated exception**, by explicit user decision:
*"document the exception for demo day and continue to construction."*

**SECURITY-10 remains NON-COMPLIANT with a dated exception — not compliant.** Recorded as
`docs/decisions/0001-course-chatbot-base-image-unpinned-for-demo.md`.

| | |
| --- | --- |
| **The finding** | The Lambda base image is `public.ecr.aws/lambda/python:3.13` — a **mutable tag**, not a digest. `blueprints/tiny-chatbot/Dockerfile` predicted exactly this: *"pin this base image by digest … in the PR that wires the Build action."* |
| **Scope** | One line in one Dockerfile. Not other blueprints, not other SECURITY-10 criteria |
| **Expiry** | **2026-08-05.** Also revisited if anyone pins it, if the blueprint is offered outside the workshop, or if a second blueprint copies the pattern |
| **Residual risk** | The *deployed* artifact is still immutable (`CONTAINER_DIGEST`) and dependencies are pinned (`requirements.lock`), so the floating input is the base layer alone. Exposure is "two builds of this commit may differ", not "we cannot tell what is deployed" |
| **The fix** | `docker manifest inspect public.ecr.aws/lambda/python:3.13`, then append `@sha256:…`. A warning comment at the `FROM` line carries the date and the command |

**Two findings from the same verification were fixed in place**: SECURITY-11 (reserved concurrency —
blast-radius control, explicitly *not* abuse prevention) and SECURITY-14 (metric filter plus alarm on
rejected activities, derived from the log line because a rejected token is not an invocation error).

### Outstanding beyond the security finding

| Item | Blocks |
| --- | --- |
| Inject both secret values (`bot-client-secret`, `gateway-api-key`) | The bot answering anything. Deploys green, then `401`s |
| `az bot update --endpoint` against `jcb-ai-test-azure-bot` / `jcb-it-webcloud` — **Cornell** tenant, while the app registration is **dev** tenant | Teams reaching the bot at all |
| Set a real `CourseName`, and the syllabus prompt if wanted | Answer quality; retrieval already grounds it |
| PR to `cu-aaii/main` not yet open (FR-32) | Any deployment. Cross-fork; a team member merges |
| First merge will **not** deploy this stack | Expect it; start a second execution |
- **Cleared since Part 1**: `terraform` **1.15.8** installed locally (matches the CI pin), so
  `tools/check` now passes end to end. No new upstream drift — 0 behind, 11 ahead of `upstream/main`.
- **Carry into Part 2**: `.gitignore:38` (`aidlc-docs/`, unanchored) silently swallows new artifacts.
  Every Part 2 file needs `git add -f`, verified with `git status --short` before committing.

### Units Generation decisions

**Mob-style execution** (whole cross-functional team, per the brief) · **one PR** · **everything in the dev
environment**, single identity · **the team owns U0**. Ten remaining questions took their defaults.

**Two revisions forced by those answers, applied to the plan:**

1. **Parallelism withdrawn.** Mob construction is serial — one unit at a time, whole team. This makes the
   risk-retirement ordering *more* important, and means each unit should end in something a non-engineer can
   evaluate. **U5 (bot says hello) and U7 (streaming) are the mob checkpoints**; U1–U3 are one stretch of
   plumbing. U0 is the exception — non-AWS, needs admin credentials, cannot be mobbed.
2. **One PR means the build path is first exercised on merge**, because `Environment=main` and the pipeline
   only runs on `main` — a PR branch does not trigger it. Mitigations: validate the Dockerfile locally with
   `docker buildx build --platform linux/arm64`, and expect one corrective merge.

**Units are therefore sequencing guidance, not PR boundaries.**

### Corrections from the Entra CLI research (2026-08-04)

Recorded from `Entra CLI Automation - Research 2026-08-03.md`, which has since been **consolidated into
`docs/teams-chatbot-docs/Teams Admin CLI Automation - Findings 2026-08-03.md`** and deleted. That
findings document is now the single source for the Microsoft-side CLI picture; cite it, not the old
filename. It corrected two recorded items:

- **FR-7a added** — the manual Azure messaging-endpoint update is **not** necessary; `az bot update --endpoint`
  is automatable, so a post-deploy step pushes the stack output. Click-ops concession withdrawn.
- **§9 rationale sharpened** — manual Microsoft provisioning is right because the **catalog publish is
  delegated-only by documented design** and the unautomatable steps are **one-time per bot**, not because
  Terraform was out of scope for time. This changes whether the decision should be revisited: it should not.
- **A Terraform stage argued against** — `azuread_application_password` writes the secret into Terraform state,
  colliding with Secrets-Manager-only. A script writing straight to Secrets Manager avoids it.
- **R-3 revised** — a **certificate** instead of a client secret removes the silent-expiry risk; contained
  entirely within `TokenProvider`. Decision deferred to Infrastructure Design (`application-design.md` §6a).

### Second round of Microsoft-side live testing (folded in 2026-08-04)

A further round of testing was folded into
`docs/teams-chatbot-docs/Teams Admin CLI Automation - Findings 2026-08-03.md`. **No recorded decision
changes.** Three of the four findings harden decisions already made; the fourth is a build-time gotcha.

- **Availability scoping is conclusively un-automatable — settled, not merely untested.** Three routes
  closed: app-only certificate auth `401`s; escalating the service principal to the **Teams Administrator**
  directory role changes nothing; and `Connect-MicrosoftTeams -AccessTokens` fails **structurally** because
  the module needs a third resource token (`https://substrate.office.com`) and the parameter hard-validates
  for exactly two. **Consequence: the refresh-token pattern cannot be extended to cover scoping later**, so
  U0's one interactive login is a permanent boundary rather than a gap awaiting effort. This strengthens the
  §9 out-of-scope decision and the choice to script U0 for a human to run.
- **`az ad sp create` is a separate mandatory step** — the Portal creates the service principal implicitly,
  the CLI does not. Omitting it fails at the bot's first outbound token call, far from the cause. Recorded as
  U0 gotcha 1.
- **Setup Policies are app-only automatable, confirmed live.** Irrelevant to this blueprint (publishing to
  the catalog makes sideloading unnecessary) but evidentially important: it proves the wall is
  **endpoint-specific**, not module-wide. It also means Microsoft's app-only exclusion list predicts
  correctly in **both** directions, so it can be trusted for other cmdlets.
- **Push-install for a user is confirmed live app-only** (`201`/`204`, zero human), upgraded from
  documented-only. The team-scoped equivalent remains untested.

**One open question left in the research**, and it is the only thing that would reopen §9:
**`New-TeamsApp` under app-only auth.** Not on the exclusion list, never exercised. If it works, catalog
publish becomes fully unattended. Evidence cuts both ways — the exclusion list predicts success, the Graph
endpoint's refusal of Application permissions predicts failure, and the Substrate finding proves Teams
PowerShell does not simply proxy Graph, so the Graph table may not govern it. Cheap to test with the
existing certificate harness.

**One factual error corrected in `requirements.md` §9**: it claimed the human step was "an OAuth property,
not a Teams limitation." That is backwards — client-credentials auth works for every other row including
two Teams PowerShell rows. It is specifically the catalog and Unified App Management endpoints that refuse
app-only auth.

### Application Design decisions on record

Q1 separate worker · Q2 async invoke · Q3 channel-agnostic agent · Q4 normalised envelope · Q5 streaming ·
Q6 DynamoDB idempotency · Q7 agent reads own history · Q8 shared module · Q9 JWT local but self-contained ·
Q10 Python 3.12/ARM64 · Q11 one Dockerfile two targets · Q12 generic message + correlation ID ·
Q13 no house style

**Three units, two images**: Front Door (Lambda + function URL) → Worker (Lambda, async) → Agent (AgentCore).
**Worker timeout must be set explicitly** — the 3-second default would truncate every reply.

### Workspace Detection

- [x] Workspace Detection - Completed 2026-08-03T18:06:09Z

### Reverse Engineering Status

- [x] Reverse Engineering - Completed 2026-08-03T18:06:09Z
- **Artifacts Location**: `aidlc-docs/inception/reverse-engineering/`
- **Approval**: Approved 2026-08-03T18:31:00Z

### Requirements Analysis Status

- [x] Intent analysis complete — New Feature (new blueprint) with a pending Migration
      decision; cross-system scope; Complex; **comprehensive** depth
- [x] Clarifying questions created — `aidlc-docs/inception/requirements/requirement-verification-questions.md`
      (25 questions, 7 sections; extension opt-ins are Q23-Q25)
- [x] Research note created — `aidlc-docs/inception/requirements/agentcore-placement-note.md`
      (Bedrock AgentCore placement; ingress gap explained; CloudFormation availability confirmed)
- [x] DevOps question set created — `aidlc-docs/inception/requirements/devops-questions.md`
      (22 questions for the platform/DevOps owner, awaiting answers)
- [x] Q3, Q7 and Q9 amended 2026-08-03 with AgentCore-aware options and notes
- [x] Prototype analysed — `aidlc-docs/inception/requirements/prototype-reference-implementation.md`
      (n8n export; 10 mechanics confirmed known-good, 2 defects found, 9 requirements derived)
- [x] DevOps short list answered 2026-08-03 — Lambda ingress confirmed, dev tenant with full
      control, AgentCore available; **VPC question open, assumption recorded**; follow-ups A/B/C raised
- [x] AWS account reconnaissance (read-only) — `aidlc-docs/inception/requirements/account-reconnaissance.md`.
      Follow-up A resolved as **A2** (AgentCore service enabled, no runtime deployed → blueprint
      must create one → ARM64 build on critical path). Bootstrap/pipeline/hello-world all deployed
      and green; `cu-aaii` connection `AVAILABLE`. Tag values observed. **New constraint: no Route 53
      zone and no ACM certificate in the workshop account.** Bedrock per-account model entitlement
      still unverified.
- [x] LiteLLM gateway analysed — `aidlc-docs/inception/requirements/model-access-options.md`.
      Cornell operates an Anthropic-compatible gateway; it composes with AgentCore rather than
      competing. **No embeddings model in its catalogue**, so Bedrock entitlement stays mandatory
      if Q3 selects retrieval. New **Q26** added (Section 8) for the model-access decision.
- [x] **Q26 ANSWERED — option B, hard constraint.** All model traffic must route through the
      LiteLLM gateway; it is how Cornell gets the full model list and **medium-risk data
      handling**. Consequences in `model-access-options.md` §7 — including that **Q3 option D
      (Bedrock Knowledge Base retrieval) cannot be built as specified** because the gateway
      exposes no embeddings model. Medium-risk classification also weakens the no-VPC assumption
      and the `AuthType: NONE` ingress choice.
- [x] Plain-language ingress explainer written for administrators —
      `aidlc-docs/inception/requirements/ingress-explained.md` (12 questions grouped by which
      admin can answer them)
- [x] **Q7 ANSWERED — option A**: Lambda function URL, free AWS-provided address. No DNS or
      certificate work; admin questions 5-6 withdrawn. URL-stability constraints recorded
      (deterministic `FunctionName`, URL as stack output, stack rebuild costs one manual Azure edit).
- [x] **Q8 ANSWERED — option A**: synchronous reply with a fast "lite" model
      (`claude-haiku-4-5`). Three caveats recorded: container-image cold-start tail risk,
      idempotency on activity `id` to prevent duplicate replies, and a recommended ~4s-timeout
      hybrid fallback. **May remove AgentCore from v1**, which would take the ARM64 build off the
      critical path.
- [x] Guard confirmed in scope — the nine JWT/handler requirements in
      `prototype-reference-implementation.md` §6 stand.
- [x] **CORRECTED**: the gateway *does* offer 12 embedding models. The earlier "none available"
      finding was an artifact of a LiteLLM virtual key scoped to `llm_api_routes`. New requirement:
      the bot's gateway key must be scoped for **embeddings as well as chat**.
      `AWS::Bedrock::KnowledgeBase` nonetheless remains unusable under the routing rule (it calls
      Bedrock embeddings internally, including on the user's query text) — routes R1/R2/R3 recorded,
      R2 the safe default.

- [x] **AgentCore MANDATED** (Team E; "it should be CloudFormation" — Marty Sullivan, Principal SA
      per the participant brief). My earlier observation that v1 might not need AgentCore is
      **withdrawn**. ARM64 container build is back on the critical path. CloudFormation support
      already verified. See `agentcore-mandate-and-critical-path.md`.
- [x] Workshop brief read — `docs/Participant Brief - Invited Attendees (2).html`. Teams-fronted
      chatbots is an **explicitly named target blueprint**; workshop is 2026-08-03/04; keystone is a
      "Cornell Builder" that deploys blueprints. Brief's "reusable platform blueprints" framing
      **informs Q2 toward a generic `teams-bot`** but does not answer it.
- [x] Critical path specified: (1) `pipeline.yml:203-208` `LINUX_CONTAINER`/x86 → `ARM_CONTAINER`
      + aarch64, (2) add a namespaced Build stage — none exists today, (3) Dockerfile with a named
      target, arm64, port 8080, `/ping` + `/invocations`, (4) plumb `CONTAINER_DIGEST` via
      `ParameterOverrides`, (5) blueprint template, (6) register in `stacks.yml` **and**
      `pipeline.yml`. ~~**Steps 1-4 have never executed; ECR holds zero images.**~~ **SUPERSEDED
      2026-08-04 — steps 1-4 are done upstream.** ARM64 compute, a `Build` stage, `CONTAINER_CONTEXT`
      and `CONTAINER_DIGEST` plumbing all exist and are exercised by `tiny-chatbot` and `builder-mcp`.
      Only steps 5-6 (this blueprint's template, and its registration plus a Build action) remain.
- [x] Critical path steps 1, 4, 5, 6 **approved**. Step 2 clarified: the build *machinery* is all in
      this repo (`codebuild.yml`, `ContainerBuildProject`, `ContainerRepository` — live as ECR
      `aidlc-main`); only the ~15-line `Stages:` entry is missing. Step 3 best practices researched —
      AWS reference Dockerfile recorded; needs a **`uv.lock`**, which also closes RE tech-debt item 4.
- [x] **Escalation 1 RESOLVED** — Marty: open a PR on this repo, he reviews. Residual: call the Build
      stage out in the PR description (Team E may also add one), and the pipeline self-deployment
      recovery path is still undocumented.
- [x] **Escalation 2 ANSWERED with research** — budget is **10-15s, channel-dependent**, enforced by
      the connector, overrun shows `504:GatewayTimeout`, not extendable. **Teams response streaming**
      found as a better third option: no timeout exposure, no model constraint, feels faster, and
      **dissolves the AgentCore cold-start tension**. See `response-delivery-and-timeouts.md`.
- [x] ~~Q4 answered option A (personal only)~~ **REVISED 2026-08-03 — multi-chat IS IN SCOPE.**
      **Q4 reopened**: "multichat" has three-plus distinct meanings (B/C/D/E) with sharply different
      cost and risk; awaiting the specific choice. Two consequences apply regardless: **both delivery
      paths must be built in v1**, and the **med-risk-in-shared-scope policy question is now live and
      blocking** (was deferrable only while personal-only).
- [x] Research docs re-read in full now that multi-party is in scope. New findings: **`replyToId`
      filtering requires persistence → Q9 "stateless" is incompatible with thread replies**; the tenant
      can **disable RSC** (admin question 13); **group-chat-without-@mention is unresearched** (Q4
      option E); RSC does **not** force org publish; missed replies cannot be backfilled; in-place
      manifest updates do not re-consent.
- [x] **Q8 ANSWERED — streaming** (supersedes the earlier option A; original left visible, not
      overwritten). **Lifts the "lite model" constraint** — model choice is now about answer quality —
      and **resolves the AgentCore cold-start tension**.
- [x] Multi-party expansion costed — `aidlc-docs/inception/requirements/multi-party-scope-path.md`.
      **One v1 action item: build the delivery seam** (dispatch on `conversation.conversationType`)
      while implementing only streaming. ~20-30 lines now vs rewriting the response path later.
      Tier 1 (@mention) small-moderate; Tier 2 (RSC) moderate with an **untested
      `webApplicationInfo.id` install risk** to test first.

### Answered so far

Q7 (ingress), Q8 (streaming), Q26 (model access).

**Outstanding: Q1-Q6, Q9-Q25.** Priority order:

1. **Q3 REFRAMED by the user, and the reframe is correct** — the blueprint is a *template the keystone
   instantiates*, not a bot, so its behaviour is a deployment parameter. Q3 rewritten as a **capability
   tier** choice (A prompt-configured / B +retrieval / C +tools), with **Tier A recommended**, plus new
   **Q3b** for the one or two concrete demo configurations. See
   `blueprint-configuration-surface.md`.
   - **MCP question answered**: the MCP *decides* config and does not *store* it — it creates deployment
     repos, so config is CFN parameters checked into git, and the MCP is never in the request path.
   - Constraint recorded: CFN parameter values cap at 4096 chars, SSM standard at 4 KB — long system
     prompts belong in S3 with the parameter holding the key.
   - **Knowledge Base ("KBB") team owns the vector store** (brief: "Document ETL & batch processing →
     searchable knowledge store"). So **Tier B is an integration, not an implementation** — a stack
     parameter, plus query-side code only if they expose storage rather than search. Tier B is now
     **blocked on an interface that does not exist yet**, which strengthens the Tier A recommendation.
   - Interface must be a **parameter, not `!ImportValue`** — the repo's "blueprints as leaves"
     convention. The MCP supplies the value, since it knows both blueprints.
   - **Five questions for the KB team** in `blueprint-configuration-surface.md` §4b. The two that matter:
     *search or storage only?* and *which embedding model, via the gateway?* — the embedding model **must
     match between ingest and query** or results are silently wrong.

## Open Dependencies

### KB integration — LARGELY RESOLVED 2026-08-04

The KB team is using **Bedrock AgentCore Managed Knowledge Base** (an AgentCore built-in tool, so coherent
with the AgentCore mandate). **The S3 bucket is its data source, not its vector store** — Bedrock owns
chunking, embedding, storage **and retrieval**. See `knowledge-base-integration.md`.

**Tier B for this blueprint collapses to**: one `KnowledgeBaseId` parameter, one IAM statement for
`Retrieve`, and prompt assembly. **No S3 access, no vector store, no embedding code.**

**Firm design requirement**: use **`Retrieve`**, not `AgenticRetrieveStream` — `Retrieve` makes **no FM
invocation** so all generation stays on the gateway; `AgenticRetrieveStream` makes multiple Bedrock FM calls.
(`RetrieveAndGenerate` is unavailable for managed KBs.) Query limit 10,000 chars — truncate deliberately if
history is concatenated.

**Three earlier cautions retired**: embedding-model-match risk **eliminated** (Bedrock embeds both sides);
"search may be unowned" **does not apply**; **R2 recommendation moot** — KB team chose R1, their call.

**Withdrawn from the previous entry**: the `KnowledgeStoreType` enum, the `EmbeddingModelId` parameter, and
the `s3:GetObject`/`s3:ListBucket` requirement. The vector-store CFN verification is no longer relevant here.

**Still open**: the `KnowledgeBaseId` value, and the KB team's timeline. **Tier B is now a plausible stretch
goal rather than a follow-up** — the vector-plumbing argument for deferring it has evaporated.

**Flagged to the KB team** (their risk, not ours): whether a **managed** KB is CloudFormation-deployable at
all — `AWS::Bedrock::KnowledgeBase` is `FULLY_MUTABLE` here but `type: MANAGED` support was **not verified**,
and the docs show only console/CLI. If API-only, their blueprint cannot be pure CloudFormation under Marty's
constraint. Also: embedding model **type** and **chunking strategy** are both **irreversible** after
creation, and `CUSTOM` embedding disables the **managed reranker**.

### Superseded — original KB storage note (record only)

Recorded 2026-08-04 at the user's explicit request; agreed approach is to proceed and adjust later.

**Known**: a **simple S3 bucket**, in our own AWS account, which "will serve the RAG". **Not yet created.**
KB team decisions still outstanding.

**Settled by this**: same-account access (no cross-account policy work); the IAM requirement
(`s3:GetObject`/`s3:ListBucket` scoped to the bucket); a valid parameter shape (bucket name/ARN); no VPC
implication.

**Not settled**: **whether search exists.** A plain S3 bucket is storage, not retrieval. Three possible
bucket contents with very different costs — documents/chunks (embedding + index + search unowned),
precomputed embeddings (we search, using *their* model), or an **S3 Vectors** vector bucket (native search,
confirmed `FULLY_MUTABLE` here — worth raising with them if unevaluated).

**Risk to escalate to Marty**: if the bucket holds plain documents and the KB team considers its work done
there, then chunking, embedding and search are **unowned**, and every consuming blueprint builds its own.

**Mitigation — costs nothing today**: Tier B parameters are **agnostic** — `KnowledgeStoreType`
(`none` | `s3-documents` | `s3-vectors` | `retrieval-endpoint`), `KnowledgeStoreLocation`,
`EmbeddingModelId`. **v1 ships `none`.** Any answer becomes a new branch, not a redesign.

**Not a blocker for v1.** Tier A and the critical path are unaffected.
2. **Q4** — which of B/C/D/E "multichat" means. Now a purely technical choice. D and E carry unknowns
   (untested `webApplicationInfo.id` install risk; unresearched chat-scoped RSC).
3. **Q9** — state, constrained: "stateless" is unavailable if Q4 lands on D or E.
4. Q1, Q2, Q5, Q6, Q10-Q25.

### Confirmed constraints

- **Medium-risk data is approved to and from the gateway** (2026-08-03, reaffirmed). Gateway-routed
  traffic is compliant, so **shared scopes need no policy escalation** and admin question 14 is
  withdrawn. Q3/Q20 and Q4 carry no compliance dependency.
- **R2 is the recommended retrieval route** if Q3 selects retrieval — not for medium-risk reasons but
  because `AWS::Bedrock::KnowledgeBase` structurally bypasses the gateway, which the Q26 mandate
  forbids. R2 needs no exception granted by anyone.
- **Vector store verified CloudFormation-deployable** in the account, all `FULLY_MUTABLE` in us-east-1:
  `AWS::S3Vectors::VectorBucket` + `::Index` (**recommended** — cheapest, no cluster, no VPC),
  `AWS::OpenSearchServerless::Collection`, `AWS::RDS::DBCluster` (Aurora+pgvector, but **needs a VPC**).
  Gateway embeddings are ~$0.02/1M tokens — effectively free at this scale.
- [x] **Answers received and validated for contradictions** — 2026-08-04. No contradictions found. Two
      earlier tensions both resolved (Q8 synchronous vs AgentCore → streaming; Q26 gateway vs Bedrock KB
      embedding → KB team owns it, `Retrieve` chosen).
- [x] **`requirements.md` generated** — 2026-08-04. Tier A, Q4=C, streaming, PR to `main`.
      Security Baseline compliance evaluated: **no blocking findings**; three items compliant via
      compensating control or documented exception (SECURITY-02, -07, -11).
- [ ] **Awaiting user approval**

### Remaining INCEPTION Stages

- [ ] Requirements Analysis (in progress — at answer gate)
- [ ] User Stories (conditional)
- [ ] Workflow Planning
- [ ] Application Design (conditional)
- [ ] Units Generation (conditional)

## Extension Configuration

| Extension | Enabled | Decided At |
|---|---|---|
| Security Baseline | Yes | Requirements Analysis |
| Resiliency Baseline | No | Requirements Analysis |
| Property-Based Testing | No | Requirements Analysis |

Full rules loaded for Security Baseline only
(`aidlc-rules/aws-aidlc-rule-details/extensions/security/baseline/security-baseline.md`), per the deferred
rule-loading instruction. Resiliency and property-based testing full rules **not** loaded.
