cc-os/docs/adr/0020-os-adr-plugin-built-implementation-time-resolutions-of-the-design-s-open-questions.md

id	date	status	supersedes	superseded-by	affected-paths	affected-components	migration_confidence	migration_source
0020	2026-07-03	Accepted					medium	docs/memory-system/03-architecture-decisions.md### ADR-020 — os-adr plugin built; implementation-time resolutions of the design's open questions

0020 — os-adr plugin built; implementation-time resolutions of the design's open questions

Context

The os-adr plugin (OpenSpec change add-os-adr-plugin, built from docs/adr-system/04-plugin-requirements.md + 05-plugin-prd.md) was implemented. Its design deliberately left two questions open — the migration pilot's low-confidence flag-rate threshold, and whether ADR frontmatter needs a Graphify tag/edge convention for retrieval layer 3 — and the pilot forced several heuristic refinements within the design's declared mechanical/LLM boundary.

Decision

(1) Pilot gate threshold: 25% low-confidence flags, recorded in Adr::MigrationReport::FLAG_RATE_THRESHOLD and printed in every migration report. Final pilot rates (sandboxed copies of the three surveyed projects): viking-warrior-training-log 0%, delta-refinery 0%, llf-schema 8.3% — gate passed. (2) No Graphify tag/edge convention for ADRs: retrieval layer 3 expands the query file paths one hop through graphify-out/graph.json node source_file attributes and matches the expanded set against affected-paths frontmatter; ADRs never need to exist as graph nodes. Verified against the real llf-schema graph. (3) Heuristic-boundary refinements from the pilot: heading-synonym fallback mappings (Why/Rationale/Problem/Background→Context, Impact/Implications/Trade-offs→Consequences) are mechanical copies but cap the file at migration_confidence: medium; status synonyms SETTLED/Confirmed→Accepted, OPEN→Proposed map mechanically; bold-label paragraphs (**Context.** …) and bulleted labels (- **Status:** …) parse as sections; multi-decision files without mechanically splittable unit headings classify unrecognized (report-only) rather than converting as one blob.

• Rationale: The threshold was set empirically at pilot time per the PRD ("do not ship on an unmeasured guess"); 25% sits well above the observed worst case (8.3%) while still failing a genuinely broken heuristic run (pre-tightening iterations hit 100% on delta-refinery and llf-schema). Query-path graph expansion keeps ADRs plain markdown with zero indexing obligations — retrieval reuses the existing project graph instead of imposing a new convention on it (and sidesteps the open ADR-014 facet-edge question entirely). Capping synonym-mapped files at medium keeps the mechanical-vs-judgment boundary honest: the copy is mechanical, the mapping is a judgment call, so it stays flagged.

Consequences

The os-adr plugin was built and its two open design questions were resolved at implementation time: a 25% low-confidence migration flag-rate gate was set (validated against pilot data with a worst observed rate of 8.3%), and no Graphify tag/edge convention was created for ADRs since retrieval instead expands query file paths one hop through the existing project graph. Several heuristic refinements (heading/status synonym mappings, bold-label parsing) were capped at medium confidence to keep judgment calls flagged, and multi-decision files without splittable headings are classified unrecognized rather than auto-converted; the cc-os retrofit was later promoted ahead of pilot-project migrations.

Alternatives rejected

• Indexing ADRs as Graphify nodes with a tag/edge convention: adds an extraction pass and a freshness obligation for no retrieval gain at current corpus sizes; revisit only if one-hop query expansion proves too shallow.
  • Treating heading synonyms as high-confidence mechanical fills: hides an interpretive mapping from the flag mechanism.
  • Auto-splitting multi-Status files that lack unit headings: the split points would themselves be guesses; unrecognized + manual handling is the non-destructive answer.
• Cross-references: docs/adr-system/04-plugin-requirements.md (locked requirements), 05-plugin-prd.md (phases), 06-eval-scenarios.md (held-out eval sketches — the eval itself stays deferred), ADR-013 (build-first/migrate-incrementally precedent), ADR-018 (three-place plugin registration, followed during install), ADR-019 (plugin conventions).