SuperBizAgent-java/devflow/projects/2026-07-21-single-react-rag-log-projections/decisions.md

Decisions: single-react-rag-log-projections

Discover status

• Checkpoint: Discover
• Capability source: sm-flow with grill-with-docs codebase evidence; no external service integration required.
• Scale: complex, because two tool adapters share a lifecycle boundary and define bounded Agent-facing output semantics.

Evidence-driven findings

1. ToolBoundary currently accepts project(String rawResponse) and already owns Run/ID/authorization/read-only/JSON/budget/lifecycle enforcement.
2. LookupKnowledgeTool emits evidenceBlocks, contextPack, retrievalTrace, rerankTrace, session domains, and message; these are internal retrieval/audit fields and must not be projected.
3. QueryLogsTools emits region, physical log topic, result limit, instance and metrics; the frozen contract requires logical topic/query/lookback scope and source_kind=MOCK instead.
4. Existing ACI records already define the required snake_case fields and immutable collections.
5. The request scope must be passed to the log projector through a typed adapter method rather than inferred from raw output.

User-confirmed direction

• Use the framework-provided tool_call_id only.
• Keep lifecycle status and evidence status separate.
• Implement the stage in phases and complete sm-flow archive plus Git commit before the next stage.
• Adopt the request-aware projector adapter for log scope preservation.

Question pool

Dimension	Question	Mode	Conclusion	Status
Terminology	Are RAG traces and context packs Agent evidence?	evidence-driven	No. They are internal retrieval/audit details and are excluded from projection.	resolved
Boundary	How is log scope preserved when the generic projector has no request?	evidence-driven	Typed adapter carries QueryLogsRequest into a request-aware projector method.	resolved
Provenance	Which log source is implemented now?	evidence-driven	Existing Mock source only; result always records source_kind=MOCK.	resolved
Negative result	What does an empty query mean?	evidence-driven	NO_EVIDENCE for the recorded scope, with no health/problem inference.	resolved
Compatibility	Should legacy tools and public paths be changed now?	evidence-driven	No. Add adapters/projectors only; cutover is later.	resolved

Risks

• Existing mock messages contain hostnames, pod IDs, SQL literals, and stack-like text; sanitization must happen before projection.
• Collection limits and excerpt limits can make the Agent result incomplete; truncated must be explicit.
• The generic boundary API should remain reusable for stage 3C, so request-aware behavior belongs in an adapter or specialized projector interface.

Discover checkpoint

• Proposal created: openspec/changes/single-react-rag-log-projections/proposal.md
• Context and issue evidence recorded.
• No unresolved user-interview question remains for this bounded stage; implementation direction was explicitly accepted in the conversation.

Commit audit

• Capability source: sm-flow and local OpenSpec CLI.
• OpenSpec strict validation: passed for single-react-rag-log-projections.
• Cross-artifact alignment:
  • brief goals/non-goals -> proposal scope: aligned.
  • proposal boundaries and request-aware projector decision -> design: aligned.
  • design projection bounds, redaction, scope and adapter ownership -> spec requirements: aligned.
  • spec scenarios -> tasks for limits, RAG, logs, boundary integration and verification: aligned.
• Interface impact: L2 internal Harness adapter/projector only; no public protocol or legacy runtime cutover.
• Preflight risks accepted: legacy payload drift fails closed; sensitive log fields are redacted; total projection budget is explicit.

Commit gate

• proposal, design, specs and tasks exist.
• strict OpenSpec validation passes.
• all evidence-driven questions are resolved.
• no unresolved interface decision remains.
• .committed marker created for Apply.

Archive result

• Apply tasks complete.
• .archive-ready marker created.
• OpenSpec archived at openspec/changes/archive/2026-07-21-single-react-rag-log-projections.
• Main capability specification added at openspec/specs/rag-log-projections/spec.md.
• Next stage remains 3C MySQL projection; no Agent cutover is implied by this archive.