73 lines
4.3 KiB
Markdown
73 lines
4.3 KiB
Markdown
# 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.
|