# Decisions

## Context Collection

- `devflow/index.md` confirms `executor-v2-output-contract`, `executor-gatekeeper-hook`, and `executor-verifier-claim-checks` are archived.
- `openspec/changes` has no active changes before this phase.
- `openspec/specs/chat-verifier-agent/spec.md` is the existing capability that owns verifier routing and audit behavior.
- No existing `chat-composer-agent` capability exists, so this change introduces it.

## Question Pool

| Question | Type | Resolution |
|---|---|---|
| Should Composer be a new capability or folded into `chat-verifier-agent`? | evidence-driven | New `chat-composer-agent` capability plus modified `chat-verifier-agent` routing. Composer is a distinct expression layer, while ChatService routing remains part of the verifier chain. |
| Can Composer call tools or inspect raw tool output? | evidence-driven | No. The issue and prior design require Composer to receive only Verifier-allowed material. |
| Should Gatekeeper, Verifier, or Planner change in this phase? | evidence-driven | No. Stage four is limited to Composer final-answer generation and routing. |
| What is the interface impact level? | evidence-driven | L2 internal contract change: ChatService internal final-answer semantics change, but no external API or database schema changes. |

## Key Decisions

- Composer is implemented as `chat_composer` or an equivalent model call after Verifier.
- Composer input is assembled by ChatService, not by the model.
- `claim_checks` are authoritative for filtering allowed material.
- REJECT input always has `allowed_hypotheses=[]`.
- Composer malformed output falls back to fixed safe templates.
- Fallback must never use Executor `user_facing_answer` or raw Executor JSON.
- Composer audit is persisted under `verifier_evaluation.composer_output`.

## Cross-Artifact Alignment

| Source | Alignment |
|---|---|
| Issue objective | Stage four in `mvp/issues/executor-structured-output-v2.md` requires Composer output final answer from Verifier-allowed material. Covered by proposal, design, specs, and tasks. |
| Proposal -> design | Proposal says Composer owns final expression; design defines input filtering, output parsing, fallback, and audit. |
| Design -> specs | Design decisions are reflected in `chat-composer-agent` requirements and modified `chat-verifier-agent` routing requirements. |
| Specs -> tasks | Each required behavior has implementation and test tasks, including malformed fallback and no raw output leakage. |

## Commit Gate Notes

- Interface impact: L2 internal.
- No unresolved user-interview question identified.
- No database migration required.
- No OpenSpec/devflow conflict found.

## Apply Notes

- Implemented `chat_composer` as a post-Verifier expression Agent in `ChatService`.
- `ChatService` now builds Composer input from `VerifierDecision` plus parsed Executor structured output, not from raw Executor answer text.
- PASS, LOW_CONFID, and REJECT final-answer paths now use Composer output or a deterministic safe fallback.
- Verifier-missing or Verifier-malformed paths use fixed fallback directly because there is no trustworthy Verifier decision for Composer.
- Composer audit is persisted under `verifier_evaluation.composer_output` without adding a database table.

## Test Drift And Fixes

- Initial test compilation failed because `ChatServiceSequentialAgentTest.java` had a UTF-8 BOM at the file start. Removed the BOM.
- Existing sequential-flow tests still expected the old three-Agent call sequence and temporary V2 renderer behavior. Updated them to include `chat_composer` when a valid Verifier decision exists.
- Tests that exercise fixed fallback now force malformed Composer output so they verify no raw JSON or Executor final answer leakage.
- LOW_CONFID tests were updated to allow indirect support to appear as a possible direction rather than requiring it to disappear from all final-answer text.

## Verification

Passed:

```powershell
mvn "-Dtest=ChatServiceSequentialAgentTest" test
mvn "-Dtest=ExecutorGatekeeperServiceTest,VerifierInputHookTest,ChatServiceSequentialAgentTest" test
cmd /c openspec validate executor-composer-final-answer
cmd /c openspec validate --specs
```

Known existing warnings:

- Maven reports duplicate `spring-boot-starter-test` dependency in `pom.xml`.
- Existing Lombok `@Builder` default warnings remain.