# Domain Scenario Loop - Repo Adapter

## Purpose

This repository now supports two outer-loop capture modes:
- `run-case` for one concrete domain question;
- `run-scenario` for a linked multi-step domain chain that should reuse one assistant session.
- `run-pack` for a whole domain question pool grouped into several scenarios.
- `run-pack-loop` for an autonomous analyst/coder loop over a whole domain pack.

`run-scenario` is the preferred capture mode for domains where the user's next question depends on the previous result set.
`run-pack` is the preferred capture mode when the user brings a full domain pool that should be kept in one aggregate backlog.

## Runtime contract

The scenario runner does not introduce a new product runtime.

It reuses:
- `POST /api/assistant/message`
- `GET /api/assistant/session/:session_id`
- current backend LLM/profile configuration
- current address/deep routing inside the product

## Artifact contract

Scenario artifacts live under:

`artifacts/domain_runs/<scenario_id>/`

Top-level artifacts:
- `scenario_brief.md`
- `scenario_manifest.json`
- `scenario_state.json`
- `scenario_summary.md`
- `scenario_output.md`
- `final_status.md`

Per-step artifacts:
- `steps/<step_id>/output.md`
- `steps/<step_id>/debug.json`
- `steps/<step_id>/turn.json`
- `steps/<step_id>/session.json`
- `steps/<step_id>/assistant_response.json`
- `steps/<step_id>/step_state.json`

Pack artifacts live under:

`artifacts/domain_runs/<pack_id>/`

- `pack_manifest.json`
- `pack_state.json`
- `pack_summary.md`
- `final_status.md`
- `scenarios/<scenario_id>/...`

## Placeholder contract

Scenario questions can reference earlier step outputs with placeholders such as:

- `{{step_01_inventory.entries[0].item}}`
- `{{semantic_memory.active_result_set_id}}`

This keeps carryover explicit and machine-readable.

## Status contract

Scenario capture uses four operational statuses:
- `accepted`
- `partial`
- `blocked`
- `needs_exact_capability`

`partial` means the scenario executed, but one or more steps still need route hardening, evidence hardening, or presentation hardening.
`needs_exact_capability` means the scenario is valid for the project, but the current contour still lacks the exact route or capability needed to answer it.

In autonomous pack-loop mode, `partial` and `needs_exact_capability` are non-terminal by default. The loop should continue domain enablement work until one of these happens:
- analyst quality reaches the configured acceptance gate, normally `>= 80`;
- the analyst marks `requires_user_decision = true` because the next step would otherwise require guessing a missing required observation, making an architecture-risky change, accepting a hacky/brittle workaround, or choosing a business-critical tradeoff without enough evidence;
- the runtime is truly blocked;
- the loop reaches `max_iterations`.