[feature] Suppress decisions from codebase itself and log it as markdown file (similar to obsidian) #514

Activity

1. cdeust

   added

   enhancementNew feature or requestNew feature or request

   on Sep 8, 2026
2. cdeust commented on Sep 8, 2026

   

   cdeust

   on Sep 8, 2026

   OwnerAuthor

   More actions

   Code inspection and grounding (2026-09-08, HEAD ca32ba5)

   Read-only inspection of the tree plus live PostgreSQL measurements. Nothing implemented yet; this is the evidence to decide on.

   Owner ruling recorded

   The wiki page id is the single identifier space and the interface for every decision and every piece of established documentation. Source files keep at most an index pointing at the wiki page. In-file decision prose is refused: it bloats the codebase and pushes files over the 300-line cap.

   What in-file decisions cost today (mcp_server/, scripts/, benchmarks/lib/, hooks/)

   Measure	Value
   Python files / lines	685 / 148,652
   Comment + docstring lines	50,158 (34 %)
   Comment blocks of 10+ lines	1,433 blocks, 33,329 lines (66 % of all comment lines)
   Comment blocks of 25+ lines	379 blocks, 17,544 lines; largest 325 lines in pg_schema.py
   # source: lines (required by the craftsmanship gate on every constant)	428
   Comment lines citing an issue or PR number	631
   Files over the 300-line cap	131

   Three rival id spaces already exist

   • docs/adr/: 25 files, two schemes (001-…013-, then ADR-0044…ADR-0055; 014–043 absent, cause unknown).
   • In-code references: 172 ADR- hits in mcp_server/ + scripts/ (some to wiki-style ids such as ADR-2244), plus 25 bare decision <memory-id> references.
   • Wiki adr kind: pages named <n>-<slug>.md under per-domain subdirectories; next_adr_number (infrastructure/wiki_pages_listing.py:86-100) parses the first numeric segment of every page under adr/**, so two pages named after memory ids (adr/4253701-…, adr/305772-…) make the next allocated id 4253702. The id authority is broken today.

   So the "index token in code" half of #514 already exists, in two grammars, and nothing resolves either.

   Retrieval today, measured

   recall_memories (infrastructure/pg_schema.py:1290-1300) builds its tsquery by replacing every non-alphanumeric character with a space, dropping one-character words and OR-joining the rest. PostgreSQL's parser keeps -0042 as a signed-number token in the vector:

   -- query side: 'D-0042' -> words {'d','0042'} -> to_tsquery('0042')
   -- vector side: to_tsvector('english','Decision: see D-0042 for rationale')
   --   = '-0042':4 'd':3 'decis':1 'rational':6 'see':2
   SELECT to_tsvector('english','Decision: see D-0042 for rationale') @@ to_tsquery('english','0042');   -- f
   SELECT similarity('<400-char body mentioning D-0042 once>','D-0042');                                  -- 0.039 (< 0.1 gate, pg_schema.py:1367)
   SELECT to_tsvector('english','see ADR-0046 phase') @@ to_tsquery('english','0046');                   -- f
   SELECT to_tsvector('english','Decision: see D0042 for rationale') @@ to_tsquery('english','d0042');   -- t
   SELECT to_tsvector('english','Decision: see D-0042 for rationale') @@ phraseto_tsquery('english','D-0042'); -- t

   A hyphenated id misses both exact lanes (FTS and trigram) and reaches recall by embedding similarity alone: that is exactly the complaint in this issue, now measured. A hyphen-free id is exactly retrievable today, and the schema already has an exact lane (phraseto_tsquery, used by spreading activation at pg_schema.py:1682). This is a query-construction change on the recall path, not new machinery.

   Other findings on the retrieval side:

   • wiki_adr stores its pointer memory with the id only in source=wiki://…, which is not indexed; only content feeds content_tsv. The id must appear in the memory body.
   • unified_search fuses memories + code symbols only: no wiki lane, no exact-id mode.
   • Exact fetch primitives exist: recall(memory_id=N) and wiki_read(path=…).
   • Provenance grading (core/provenance.py:26-27) already treats a markdown path as a checkable reference (VERIFIED when it exists).
   • The craftsmanship # source: rule is a substring test (scripts/craftsmanship_constants.py:43,74-86): # source: <wiki id> passes today with no existence check. Verifying the page exists belongs in check_craftsmanship.py (the constants module is declared I/O-free).
   • Doc correction: docs/mcp-tools.md says wiki_reindex writes memory pointers; handlers/wiki_reindex.py:130-160 only rebuilds INDEX.md, zero remember calls.

   Prerequisites, in order

   1. Repair next_adr_number: parse a fixed-width numeric head only; quarantine the two memory-id-named pages out of adr/.
   2. Reserve ids 0001–0055 so the 25 docs/adr/ files and the 172 in-code references keep their numbers; document the 014–043 gap as reserved.
   3. Decide id-to-path resolution: adr/ is per-domain and numbered globally, so an id is a glob (adr/**/0046-*.md), not a path. Either flatten adr/ or keep an id→path map in the wiki index. This is the load-bearing decision for "look up the index exactly".
   4. Put the id in the pointer memory's content, and stop stripping hyphens in recall_memories (or standardise on a hyphen-free id, which already works).
   5. Make the craftsmanship gate resolve # source: <wiki id> to an existing page.

   Options under the ruling

   • A. Wiki id in code, prose in docs/: two substrates to keep in sync; contradicts "the wiki is the interface". Not recommended.
   • B. Wiki id and prose both in the wiki (purest reading): docs/adr/ migrates in; unified_search gains a wiki lane and an exact-id mode. Trade-off: decision prose leaves PR diffs.
   • C. B plus a generated read-only mirror in docs/adr/ produced by wiki_reindex: prose stays reviewable in PRs at the cost of one more module.

   Recommendation: B, with C's mirror only if reviewers need decision text in diffs.

   Acceptance signal

   Known-item retrieval, not semantic relevance (LongMemEval/LoCoMo are the wrong instruments): seed N decision pages, query each id bare, measure recall@1 and MRR@10 under benchmarks/reproduce.sh (isolated container), template benchmarks/gate_precision/run_benchmark.py. Before: hyphenated ids hit neither exact lane (measured above). Target: recall@1 = 1.0. Guard the rest with reproduce.sh --no-regression against origin/main.

   Suggested increments

   1. Id authority + quarantine + reservation (small, unblocks everything).
   2. Exact-id recall lane + id in pointer content, with the known-item benchmark.
   3. # source: gate resolves wiki ids.
   4. Migration tooling: extract decision blocks (start with the 379 blocks of 25+ lines) into wiki pages, leave the id in place, measure the line-count drop against the 131 files over the cap.
   5. docs/adr/ migration into the wiki, unified_search wiki lane.
3. cdeust commented on Sep 8, 2026

   

   cdeust

   on Sep 8, 2026

   OwnerAuthor

   More actions

   Decision 2026-09-08: option B retained (wiki id and prose both in the wiki, index in code, exact-id retrieval). The issue body now carries the decision, the five prerequisites, the five increments and the acceptance signal; the inspection comment above is the evidence.
4. cdeust

   closed this as completedin #515on Sep 9, 2026