# 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

- [x] proposal, design, specs and tasks exist.
- [x] strict OpenSpec validation passes.
- [x] all evidence-driven questions are resolved.
- [x] no unresolved interface decision remains.
- [x] `.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.