Skip to content

DEV_LOG.md

Latest commit

 

History

History
23 lines (18 loc) · 4.69 KB

DEV_LOG.md

File metadata and controls

23 lines (18 loc) · 4.69 KB
Raw

Development log

Engineering narrative for the oidm-knowledge repository: decisions, blockers, and what was done when. Reader-facing changes go in CHANGELOG.md.

2026-09-20

  • Planning interview with the project lead settled the charter: canonical public documentation, OKF 0.2 bundle in knowledge/, migrate rather than mirror, three-layer organization, facts and goals only, organizations not individuals, Quartz-or-similar site from day one. Full decision table in knowledge/plans/2026-09-20-knowledgebase-build-plan.md.
  • Research: OKF 0.2 is the Google Cloud spec; only type is required; 0.2 added generated, verified, status, sources, stale_after. Chose scaccogatto/okf-skills (0.2-native, validator and visualizer included) over the v0.1 skill linked from okf.md. Installed under .agents/skills/ with symlinks in .claude/skills/.
  • Research: site generator comparison recommended Quartz 5, runner-up Astro Starlight. Three Quartz config points still to verify against live docs.
  • Cloned 17 source repositories read-only into the home directory beside existing checkouts. Ran seven read-only inventory agents (Sonnet and Haiku) covering every source, the Gamma deck, and the openimagingdata.org site. Reports kept in the session scratchpad; substance carried into the plan's source map.
  • Notable findings: imaging-problem-list dev is 258 commits ahead of main and holds 89 docs; FHIR mapping is documented but unimplemented; current anatomic location data lives in findingmodel/notebooks/data/anatomic_locations_noembed.json (2,926 records) alongside the older 2,890-node anatomiclocations.org set; RSNA/RadLex issue #3 tracks merging that set into RadLex; the next-gen-2026 branch of ACR-RSNA-CDEs already uses OKF frontmatter with a house checker, which this repo inherits.
  • Repo initialized with CC-BY-4.0 LICENSE and .gitignore. Plan written. Awaiting approval before Phase 0 completes and synthesis begins.

2026-09-21

  • Project lead asked that the plan cover the entire work edge, not default branches. Ran four branch-level inventories (imaging-problem-list, findingmodel, findingmodels, and the application repos). Added a "work edge" section and branch-specific source rows to the plan. Confirmed from the project lead that the findingmodels taxonomy branch is the immediate content direction and will likely replace many Gamuts-derived models (1,933 of 2,382).
  • Ported the next-gen-2026 checker to tools/check_bundle.py: controlled type vocabulary, trust-signal shape, status values, stale dates, index coverage including subdirectories, link resolution, email and denylist sweep. Diagram rules dropped. Runs with uv run (inline pyyaml dependency). The OKF conformance validator passes on the bundle so far.
  • Quartz spike running in the scratchpad to confirm content path, absolute link resolution, and a frontmatter badge component before the site is set up.
  • Site: Quartz 5.0.0 pinned at commit 97a2d05 is cloned at build time by site/build.sh rather than vendored. Config in site/quartz.config.yaml, a hand-written okf-meta-plugin renders OKF frontmatter as badges and a sources list, and .github/workflows/site.yml deploys to GitHub Pages. Quartz 5 resolves either bundle-absolute or relative links, not both, so tools/prepare_site_content.py stages a link-normalized copy of the bundle in a temporary directory outside the repo (Quartz skips gitignored paths) and the site builds from that. Directory indexes now use ./file.md entries.
  • Phase 1 synthesis: overview, deck extract, references, repository map, and history landed from four Opus agents; glossary in progress. Agents report source conflicts to a collected list for the roadmap phase. Phases 2 to 4 launched in parallel.
  • Phases 2 to 5 complete: six Opus agents wrote the semantic foundation, data structures, applications, and roadmap; each appended source conflicts to a collected file that became roadmap/open-questions.md (90 entries plus 21 upstream defects to file as issues). Project lead decisions applied: the taxonomies are the "MGB exam-oriented sub-taxonomies"; the next-generation vocabulary document is published as draft; the use case catalog is published with its committee credit.
  • Integration: ledger (118 rows) and log merged from agent scratch files; naming made consistent; a dead URL and an exam count corrected; both validators report 115 concepts, 0 errors, 0 warnings; the site rebuilds. Remaining Phase 6 work is the project lead's verification pass, then the first release entry and the follow-up issues (source-repo link-back PRs, upstream defect reports, manuscripts).
  • Added the project lead's stated goals verbatim to the plan so that documents citing the planning interview have a written source (open question 82).