SuperBizAgent-java/openspec/changes/archive/2026-07-08-executor-composer-final-answer/decisions.md

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/design-notes/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:

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.