Skip to content

TR-1208 Decisions keep who decided, when and where; answers cite them - #10

Merged
ashish-bagri merged 2 commits into
mainfrom
factory/TR-1208
Nov 17, 2026
Merged

ashish-bagri merged 2 commits into
mainfrom
factory/TR-1208

Conversation

@ashish-bagri

Copy link
Copy Markdown
Member

Ticket: TR-1208 (M2, software-second-brain). The release is TR-1221 (Ashish), not part of this PR.

What changed

  • POST /v1/documents takes kind: "decision". Metadata fields, names exactly as the tares side (TR-1210..1212) will send them: decided_by (list of names, required), decided_at (YYYY-MM-DD or RFC 3339, required), changed_by, changed_at, pr, where (repo_folder | factory_project | by_hand), repo, project, added_by. Bad values are a 400 in the existing style. Other kinds are unchanged.
  • Migration 0011_decision_kind.sql widens the documents.kind CHECK to allow decision. No new column: the metadata stays in the existing metadata JSON.
  • The model sees [1] Title (decision, decided by Ashish Bagri on 3 August 2026) in front of each decision passage (fast, sources and deep modes), and the system prompts say to name who decided and when. Missing or empty values are left out, never "None".
  • Citations carry metadata for decisions (omitted for other kinds and when nothing usable is stored). GET /v1/documents/{id} returns it.
  • kind filter on GET /v1/search and /v1/ask, applied in SQL before the cut to k; in deep mode the request's filter overrides the search tool's own kind.
  • GET /v1/documents?kind=decision&source=&limit=&cursor=: read key, tenant scoped, newest decided first, keyset cursor (next_cursor, null on the last page), limit 1..200 (default 50).
  • docs/usage.md: a Decisions section with the field table, an example and the listing.

Checks (run on this branch, in the rust:1.95 image against the local pg17)

  • cargo test --all-targets --no-fail-fast: lib 344 passed, 0 failed, 2 ignored; every target passed except cli_search (3 passed, 2 failed) and one cli_repo pool timeout that passed on rerun (13 passed).
  • cli_search failures: no_hits_is_a_note_on_stderr_and_still_success and plain_output_is_path_lines_score_symbols_and_three_snippet_lines. The stderr gets onnxruntime cpuid_info warning: Unknown CPU vendor from the aarch64 docker VM, ahead of any lore output; the diff in src/cli/search.rs is two lines of kind plumbing. I did not run a clean main to prove it, so CI on x86 is the check.
  • cargo test --lib --test decisions: 344 + 13 passed, 0 failed.
  • cargo clippy --all-targets -- -D warnings: finished, no warnings. cargo fmt --check: rc 0.
  • Broke it once: with metadata: hit.decision.clone() in src/answer/fast.rs replaced by metadata: None, decision_citation_has_who_and_when_in_the_prompt_and_on_the_citation failed (citation metadata Null); with the prompt label replaced by the plain kind it failed at the prompt assertion. Both restored, test passes again.

The decision citation test is decision_citation_has_who_and_when_in_the_prompt_and_on_the_citation in tests/decisions.rs.

Notes for the reviewer

  • Required fields: decided_by and decided_at only (git always gives an author and a date; by-hand names the decider). Limits: 50 names, 256 bytes a name, 2048 bytes for pr.
  • The Linear description lacks added_by; the working doc has it, so it is included.
  • Kiran reviews indexer and search changes (via the orchestrator).
  • Merge: Ashish merges lore PRs by hand on GitHub after his yes.

…rry them

kind=decision documents take decided_by, decided_at, changed_by, changed_at, pr,
where, repo, project and added_by in metadata (decided_by and decided_at required).
Fast, sources and deep answers show the decider and date in front of each decision
passage and put the metadata on the citation. search and ask take a kind filter,
and GET /v1/documents lists documents by kind, paged by a keyset cursor.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@ashish-bagri

Copy link
Copy Markdown
Member Author

factory/review: changes requested (round 1, head 88bb21a)

Verdict: changes. One finding blocks: the deep-mode kind check (F1). It is a one-line fix plus one test. The rest of this PR is solid. Every mutation I tried was caught, and paging one row at a time gives exactly the single-page list.

Findings

  • F1 (P2, blocks), src/answer/deep.rs:242.
    • The problem: deep mode never validates req.kind. docs/usage.md:315 says another name is a 400 in every mode, but a deep ask with kind: ["bogus"] returns 200 OK.
    • What happens instead: the bad kind goes through scoped_to_kinds into every search call, and each call returns a tool error. So the request takes a deep slot and LLM rounds, and answers with no search at all.
    • The fix: call search::validate_kinds on req.kind at the top of deep::answer, or once in http/ask.rs for every mode. Add a deep-mode case next to the fast-mode bogus-kind test.
  • F2 (P3), src/store.rs list_documents:
    • sort_micros is computed in a subquery over the whole tenant and then sorted.
    • With kind=decision, the (tenant_id, kind) index keeps it to decisions. The unfiltered listing sorts every document on each page.
    • Fine for now. If it grows, consider a stored sort column.
  • F3 (P3), src/mcp.rs:294 and :421:
    • MCP search and get_document still show only the kind, not who decided and when.
    • The definition of done doesn't require it, so this could be a follow-up.
  • F4 (P3), src/decision.rs:125:
    • human_date shows decided_at as written, but the listing sorts on the instant. So 2026-08-03T01:00:00+02:00 shows as 3 August but sorts as 2 August, 23:00Z.
    • A far-future date also stays at the top of the list.
    • Worth a line in usage.md.

What I verified

All runs were on 88bb21a, in rust:1.95-trixie against a fresh pgvector pg17 container.

  • cargo fmt --check: clean.
  • cargo clippy --all-targets -- -D warnings: rc 0.
  • cargo test --all-targets --no-fail-fast: 737 passed, 2 failed, 4 ignored. The 2 failures are the known arm64 failures in cli_search (onnxruntime prints a cpuid warning on stderr), not this diff. lib: 344 passed. decisions: 13 passed.

Mutations. Each one was caught by a failing test, then restored.

Mutation Caught by
decided_at no longer required lib the_minimum_is_decided_by_and_decided_at
keyset < changed to <= listing_decisions_pages_in_a_stable_order_without_gaps_or_overlap
deep scoped_to_kinds override dropped the_request_kind_filter_overrides_the_kind_of_a_search_call
decision_metadata nulled in search 5 tests in decisions
sources bullet label dropped sources_mode_shows_who_decided_and_when
both decision sort branches disabled the listing-order test

Probes. I added these for the review and then removed them.

  • Five decisions with mixed dates (a plain date, a Z time, an offset time, a tie) plus two notes, paged with limit=1: identical to the single-page list (7 rows).
  • The deep bogus-kind ask: 200 OK. That is F1.

Your three questions

  1. Required fields: decided_by and decided_at match the definition of done. The cost is that a decision with no known decider can't be stored, which I think is fine.
  2. Cursor SQL: correct, per the probe above. pg_input_is_valid needs PG16+, and PG17 is pinned in docs, deploy and CI. Dates that chrono accepts and Postgres rejects fall back to updated_at.
  3. Deep-mode override: overriding the model's kind rather than intersecting with it is the safe choice, and the docs say so. The only problem there is F1.

Not verified

  • CI on x86.
  • The cli_search failures rerun on a clean main under arm64.
  • The listing's speed on a large tenant.
  • A live LLM run. The answer modes were checked through the stubbed tests.

A second model challenged this review. Its prompt-injection-via-names point was rejected: the passage text and the title already reach the prompt unescaped from the same ingest key, so names open no new channel.

ashish-crew-reviewer

…e the decided_at sort in usage

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@ashish-bagri

Copy link
Copy Markdown
Member Author

factory/review: pass (round 2, head 8696a53)

Verdict: pass. F1 and F4 are fixed. F2 and F3 stay open as P3 follow-ups and don't block.

  • F1 fixed.
    • deep::answer now calls search::validate_kinds at src/answer/deep.rs:164, before deep_guard.admit. A bad kind is a 400 that names it, and takes no slot and no model round.
    • The new test deep_ask_refuses_an_unknown_kind_before_it_asks_the_model covers it.
    • I deleted the line: that test failed (decisions 13 passed, 1 failed). Restored.
  • F4 fixed. usage.md explains the instant-vs-written date and far-future dates.

What I verified

All runs were on 8696a53, in rust:1.95-trixie against a fresh pgvector pg17 container.

  • cargo fmt --check: clean.
  • cargo clippy --all-targets -- -D warnings: rc 0.
  • cargo test --lib --test ask --test decisions --test deep: 344 + 10 + 14 + 23 passed, 0 failed.

Not verified

  • The full suite: not rerun. Only 3 files changed since round 1, which had 737 passed (2 known arm64 failures in cli_search).
  • CI on x86.

Merging is by hand: lore needs a GitHub approval.

ashish-crew-reviewer

@ashish-bagri
ashish-bagri merged commit 4e1bf65 into main Nov 17, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant