Sprint 20
Table of Contents
This page documents a sprint (Sprint 20) of ORE Studio. It captures the sprint's mission, current status, and the stories that compose it. For the surrounding context — version goals, sprint order, and product identity — see Version 0.
Mission
Commission the ores.refdata entities across all access layers,
finish the codegen tidy-up, and verify the Windows/macOS CI builds
green.
Status
| Field | Value |
|---|---|
| State | DONE |
| Parent version | Version 0 |
| Previous | Sprint 19 |
| Start | 2026-06-06 |
| End (expected) | 2026-06-13 |
| End (actual) | 2026-06-12 |
| Now | Nothing. |
| Waiting on | Nothing. |
| Next | Sprint 21 |
| Release Notes | Sprint 20 Release Notes |
| Last touched | 2026-06-12 |
Stories
For the definitions of the themes see Themes.
Product
Epic: ores.refdata Commissioning
Commission all ores.refdata entities across every access layer: verify Qt UI end-to-end
post-NATS migration (list window, detail window, history, delete, eventing), implement or
verify shell and CLI commands (list, add, remove), document each entity in the user manual,
and file backlog captures for Wt and HTTP gaps. One story per entity. Carried from sprint 19
by file move — IDs and task history intact.
| Story | State | Start | End | Description |
|---|---|---|---|---|
| Commission: currency | BLOCKED | 2026-06-06 | 7/8 tasks done; Qt verification blocked on timestamp unification story (inbox). | |
| Commission: country | BLOCKED | 2026-06-06 | Verify Qt + shell + CLI (existing); manual; Wt/HTTP captures. | |
| Commission: party | BACKLOG | Verify Qt; implement shell + CLI; manual; Wt/HTTP captures. | ||
| Commission: party_type | BACKLOG | Verify Qt; implement shell + CLI; manual; Wt/HTTP captures. | ||
| Commission: party_status | BACKLOG | Verify Qt; implement shell + CLI; manual; Wt/HTTP captures. | ||
| Commission: party_id_scheme | BACKLOG | Verify Qt; implement shell + CLI; manual; Wt/HTTP captures. | ||
| Commission: contact_type | BACKLOG | Verify Qt; implement shell + CLI; manual; Wt/HTTP captures. | ||
| Commission: counterparty | BACKLOG | Verify Qt; implement shell + CLI; manual; Wt/HTTP captures. | ||
| Commission: book | BACKLOG | Verify Qt; implement shell + CLI; manual; Wt/HTTP captures. | ||
| Commission: book_status | BACKLOG | Verify Qt; implement shell + CLI; manual; Wt/HTTP captures. | ||
| Commission: business_unit | BACKLOG | Verify Qt; implement shell + CLI; manual; Wt/HTTP captures. | ||
| Commission: business_centre | BACKLOG | Verify Qt; implement shell + CLI; manual; Wt/HTTP captures. | ||
| Commission: portfolio | BACKLOG | Verify Qt; implement shell + CLI; manual; Wt/HTTP captures. | ||
| Commission: purpose_type | BACKLOG | Verify Qt; implement shell + CLI; manual; Wt/HTTP captures. |
Epic: Provisioning
Provision a complete system from the command line: shell equivalents for the three provisioner wizards plus an org-mode tangled ores-shell script library. Design first, implementation as a follow-up story.
| Story | State | Start | End | Description |
|---|---|---|---|---|
| Provisioners from the shell — analysis and design | DONE | 2026-06-06 | 2026-06-10 | Map the three provisioner wizards to the shell command surface; brainstorm the idiomatic ores-shell interface; decide implementation approach and scope follow-up stories. |
| Implement ores-shell provisioning commands | DONE | 2026-06-06 | 2026-06-06 | Flag parsing + stop-on-error load; plumbing (bundles, workflow, lei, synthetic, parties, account-parties, reports); provision system/tenant/party porcelain. Scoped by the design story. |
| Provisioning script library | DONE | 2026-06-06 | 2026-06-08 | Org-mode script library in ores.shell/scripts/ with emacs tangle CMake target; end-to-end provision_all script; manual chapter. Depends on the commands story. |
Epic: Qt application
User-facing improvements to the Qt desktop application beyond entity commissioning.
| Story | State | Start | End | Description |
|---|---|---|---|---|
| Qt help system from the user manual | DONE | 2026-06-08 | 2026-06-10 | Build the manual into a .qch collection and open it in-app via QHelpEngine; native, offline, searchable help from the existing manual. |
Tooling
Epic: Compass
Developer toolkit consolidation, carried from sprint 19: complete the test pillar.
| Story | State | Start | End | Description |
|---|---|---|---|---|
| Port serve-site.sh to compass | DONE | 2026-06-11 | 2026-06-11 | Add compass site serve; delete serve-site.sh; update recipe and dashboard. |
| Add compass test run | DONE | 2026-06-12 | 2026-06-12 | Run all / composite / single-component tests or Catch2 filters via compass; –build delegates to cmake; .env loaded for direct binary runs. Re-promoted from the inbox. |
Epic: Skills
Make skill discovery obvious and compass usage procedural: define an action-oriented naming convention for skills, inventory compass commands and map them to skills, rename or delete the existing skills that do not conform, and add workflow skills for the common compass rituals. This epic gates the sprint: no other story starts until it is done.
| Story | State | Start | End | Description |
|---|---|---|---|---|
| Action-oriented skill cleanup | DONE | 2026-06-06 | 2026-06-06 | Naming convention; compass command inventory and skill map; rename/delete existing skills; add compass workflow skills. |
| Clean up the compass work lifecycle | DONE | 2026-06-06 | 2026-06-06 | Create vs pick-up split; scaffold tasks; bookkeeping rides the PR (no PR-to-close-a-PR); robust pr merge close-out. |
Epic: Codegen
Codegen tidy-up: finish the org-mode model migration, resolve C++ template drift, and land the safety and CI guardrails so generated code stays trustworthy. Carried from sprint 19.
| Story | State | Start | End | Description |
|---|---|---|---|---|
| Codegen unified model — org-mode migration | DONE | 2026-06-06 | 2026-06-11 | All 32 tasks completed or abandoned; meta-model improved and schema reference authored. |
| Refactor ores.codegen C++ generation | BLOCKED | Carried: audit/resolve template-production drift; 13 open tasks; was blocked on the org migration tail. | ||
| Decommission legacy codegen bash scripts | BACKLOG | Replace direct bash invocations of ores.codegen with compass or the Python codegen; remove the scripts. | ||
| Codegen CI zero-diff invariant | BACKLOG | CI job regenerating all registered components, failing on any diff vs HEAD. | ||
| Codegen model safety guardrails | BACKLOG | Runtime guards for missing component_include/component_core; block dual-template SQL generation. | ||
| Codegen unified model — Phase 1: Qt derivation | BACKLOG | Derive Qt fields from conventions; drop explicit NATS protocol class names from models. | ||
| Codegen unified model — Phase 3: unify temporal templates | BACKLOG | Merge temporal and non-temporal C++ template families into single model-controlled templates. | ||
| Convert codegen mustache templates to literate org | DONE | 2026-06-06 | 2026-06-07 | Each .mustache template tangled from a facet-documenting org doc; three-level literate hierarchy (template ← facet ← group ← overview); zero-diff drift check. |
| Clean up codegen documentation and MASD alignment | DONE | 2026-06-07 | 2026-06-10 | Update MASD doc facet catalogue to link to literate template org files; cross-link template docs into org-roam graph; audit and correct MASD terminology. |
| Remove the #+version field and finish doc-format cleanup | DONE | 2026-06-08 | 2026-06-09 | Finish sprint 18's doc_format_cleanup: strip #+version from all org files, retire doc_version_audit.py, purge version guidance, fix stale v2 codegen references. |
| Create MASD model catalogues and org-mode variability profiles | DONE | 2026-06-09 | 2026-06-10 | Module catalogues for floating entity models; component overviews catalogue modules/sub-components; variability model rewritten to separate activation from configuration (facet_catalogue.org tangle moved to codegen org-model migration story). |
Epic: Compass
Developer toolkit ergonomics: small compass and tooling improvements that keep the LLM-driven workflow frictionless.
| Story | State | Start | End | Description |
|---|---|---|---|---|
| Compass quality of life | DONE | 2026-06-06 | 2026-06-10 | Second QoL round, 15 tasks: SSH_AUTH_SOCK from .env, dashboard services bug, Claude settings auto-authorisation, actionable search, journal log newest-first, capture –commit, search by folder name, task move, recipe how-do boost, inbound-link boost, PR review gate, cross-reference wiring, story tasks subcommand, scoped search, capture promote fix. |
| Suggest the next work item to pick up | DONE | 2026-06-08 | 2026-06-10 | New compass heading command: ranked next-work-item suggestions from the journals, fleet, sprint state, and backlog buckets; optional keyword steering. |
| Migrate Claude memories to org-based memory system | DONE | 2026-06-11 | 2026-06-11 | Audit harness memory files, port keepers to the org system, delete the harness files, update LLM instructions, disable auto-memory in Claude Code settings. |
| compass generate catalogue: auto-generate index org files from tagged content | BACKLOG | compass command to regenerate catalogue/index org files by scanning tagged org files; covers memories, recipes, knowledge, and skills catalogues. | ||
| Fix orphan documents and introduce tag taxonomy | BACKLOG | Fix memory catalogue, shell-provisioning chapter, codegen test fixtures, trading entity orphans; create tag inventory doc; add compass tag validation. |
Infrastructure
| Story | State | Start | End | Description |
|---|---|---|---|---|
| Skip vcpkg for doc-only cmake builds | DONE | 2026-06-12 | 2026-06-12 | ORES_VCPKG_ENABLED switch + linux-doc-only preset; site CI drops sccache, Qt, and vcpkg steps. |
| Verify Windows and macOS CI builds | BACKLOG | Re-run MSVC and macOS builds; verify the rfl C1202 fix; fix or file follow-ups. Slipped in sprints 18 and 19. | ||
| Retune CI for tens of merges an hour | DONE | 2026-06-06 | 2026-06-08 | Path-classified PR jobs behind one pr-gate check; main matrices on staggered 2h/3h/4h schedules with a doc-only skip guard; Claude review replaces Gemini. |
| Fix nightly clang-format CI | DONE | 2026-06-08 | 2026-06-08 | Unpin clang-format-18; apply drift to 181 files; restore bot-PR approach. PR #1187. |
| Fix flaky IAM repository tests | DONE | 2026-06-10 | 2026-06-10 | Eliminate duplicate-key failures caused by UUID v7 timestamp collision in email generation; one-line fix in account_generator.cpp. |
| Improve CDash build visibility | DONE | 2026-06-08 | 2026-06-09 | PR tagging; Site CDash category; drop Experimental from developer-facing CI. |
Site
Epic: Documentation Site
Public-facing documentation site improvements: navigation, UX, and new pages.
| Story | State | Start | End | Description |
|---|---|---|---|---|
| Replace site navbar with a structured menu | DONE | 2026-06-07 | 2026-06-09 | Replace the flat nav bar with a hierarchical dropdown menu; reorganise existing items; expose new pages. Plus a refinement: merge Agile into Developer, reorder for new users. |
| Add Edit on GitHub button to every site page | DONE | 2026-06-11 | 2026-06-11 | Per-page Edit button in the site preamble linking to the GitHub web editor for the source org file. |
| Fix site preview port to env port range | DONE | 2026-06-11 | 2026-06-11 | Move ORES_SITE_PORT from ad-hoc 8000+suffix to base_port+4 within each env's port range. |
| Knowledge graph: LLM document filter and tag export fix | DONE | 2026-06-11 | 2026-06-11 | org-roam-ui to external/ (no patches); tag export from ALLTAGS; :skill: and :llm: filetags on all LLM docs. PR #1257. |
Agile
| Story | State | Start | End | Description |
|---|---|---|---|---|
| Open sprint 20 | DONE | 2026-06-06 | 2026-06-06 | Two-PR transition ceremony: close 19 (carry, release notes), open 20 (pull stories, version bump, vcpkg). |
| Agile dashboard PoC: JavaScript UI over org-mode data | DONE | 2026-06-06 | 2026-06-07 | PoC succeeded: ores.org-js agile board over graphdata.json, deployed with the site. |
| Sprint health review — System 2 analysis | DONE | 2026-06-07 | 2026-06-12 | Periodic health checks; housekeeping tasks added as the sprint progresses. |
| Agile timeline: bucketed summaries of recent activity | DONE | 2026-06-07 | 2026-06-10 | compass timeline command; environment stamping; LLM snapshot skill; board timeline view. |
| Clean up sprint timeline generation | DONE | 2026-06-11 | 2026-06-11 | Skip empty buckets; add sprint_timeline.org catalogue. |
| Codegen Model Dashboard | ABANDONED | 2026-06-11 | 2026-06-12 | Abandoned: d3-force unsuitable for UML at 127 nodes. Re-captured as ores.diagrams + SVG viewer inbox stories. |
Hotfixes
| Story | State | Start | End | Description |
|---|---|---|---|---|
| Hotfix: site navbar missing after edit-on-github change | DONE | 2026-06-11 | 2026-06-11 | #' in backtick alist embeds literal (function ...) form; functionp rejects it; bare symbol fixes it. |
| Hotfix: ores.shell tests fail to link on Windows | DONE | 2026-06-07 | 2026-06-07 | New command_args/command_feedback/script_runner symbols lack ORES_SHELL_EXPORT; Windows test exe cannot link against the DLL. |
| Hotfix: shell bundles gcc build | DONE | 2026-06-06 | 2026-06-06 | linux-gcc-debug-ninja red: four shell command files built std::string from std::vector<std::byte> iterators; converted to ores::nats::as_string_view. PR #1133. |
| Accumulate a tagged face dataset for profile pictures | STARTED | 2026-06-10 | Build the external/facestudio/ seed catalog: move the 60 downloaded AI faces, add manifest/methodology metadata, document the FaceStudio licence, fix the accumulation script (age filter 20–70, 429 handling, multiple images per combination, correct output path), and wire into the seeder. | |
| Hotfix: CI runners run out of disk space | DONE | 2026-06-12 | 2026-06-12 | The canary build exhausts disk on ubuntu-24.04; expand the free-disk-space cleanup step across all workflows and remove sccache from the site build. |
Postponed
Stories planned for this sprint that could not be completed. All folders moved
to sprint_21/ at sprint open (2026-06-12). The epic tables above show the
state each story was in when the sprint closed.
In-progress at sprint close
Stories where work started or partial tasks were completed.
| Story | Tasks done | Reason |
|---|---|---|
| Commission: currency | 7/8 | Qt verification waiting on timestamp unification story |
| Commission: country | 1/6 | Codegen blocker cleared; remaining tasks unstarted |
| Refactor ores.codegen C++ generation | 6/19 | Org-mode migration blocker cleared; 13 drift-application tasks remain |
| Fix orphan documents and introduce tag taxonomy | 1/4 | Memory catalogue fixed; 3 tasks unstarted |
| Accumulate a tagged face dataset for profile pictures | — | Accumulation ongoing within API throttle limits |
Never started
Stories pulled into sprint planning but not touched. No tasks exist; ready to pull into sprint 21.
| Story | Epic |
|---|---|
| Commission: party | ores.refdata Commissioning |
| Commission: party_type | ores.refdata Commissioning |
| Commission: party_status | ores.refdata Commissioning |
| Commission: party_id_scheme | ores.refdata Commissioning |
| Commission: contact_type | ores.refdata Commissioning |
| Commission: counterparty | ores.refdata Commissioning |
| Commission: book | ores.refdata Commissioning |
| Commission: book_status | ores.refdata Commissioning |
| Commission: business_unit | ores.refdata Commissioning |
| Commission: business_centre | ores.refdata Commissioning |
| Commission: portfolio | ores.refdata Commissioning |
| Commission: purpose_type | ores.refdata Commissioning |
| Decommission legacy codegen bash scripts | Codegen |
| Codegen CI zero-diff invariant | Codegen |
| Codegen model safety guardrails | Codegen |
| Codegen unified model — Phase 1: Qt derivation | Codegen |
| Codegen unified model — Phase 3: unify temporal templates | Codegen |
| compass generate catalogue | Compass |
| Verify Windows and macOS CI builds | Infrastructure |
Achievements
Milestones worth capturing as they happen, so the release notes at sprint close have the evidence to hand.
All builds green (2026-06-08)
Every configured build went green simultaneously — all Linux compiler/generator combinations plus the shell and Qt targets — a clean baseline for the provisioning and refdata work in flight.
Captures
Real captures filed during this sprint that have not been pulled into a
story as tasks — listed here purely for visibility into what the sprint
surfaced. Each is an inbox capture (compass capture); triage them at the
health review (promote to a story, move to next, or discard).
| Capture | Tags | Description |
|---|---|---|
| Split the user manual into Qt and Wt manuals | documentation manual wt qt |
Split the single manual into separate Qt and Wt manuals (near-identical), sharing identical content via codegen. |
| Standardise timeline bucket generation as a compass writer | agile timeline compass tooling |
Build the bucket writer (canonical format) under the snapshot-skill task; replaces ad-hoc generation. |
| Accumulate a tagged face dataset for profile pictures | dataset seeder iam ui |
Build a seed catalog of attribute-tagged faces (via facestudio.app), accumulated over time within API throttling, for account profile pictures. |
Timeline
Sprint timeline — index of all snapshot files in doc/agile/versions/v0/sprint_20/timeline/.
Regenerate after new snapshots are taken: compass timeline catalogue.
Health Review
| # | Date | Day | Verdict | Task |
|---|---|---|---|---|
| 1 | 2026-06-07 | day 1 | N/A | Health review 1 — sprint 20 housekeeping |
| 2 | 2026-06-10 | day 4 | AMBER | Health review 2 — sprint 20 mid-sprint analysis |
| 3 | 2026-06-12 | day 6 | N/A | Sprint 20 close-out: audit fixes, story states, backlog migration |
Charts
Charts generated via compass sprint charts. See Sprint health charts for what each chart measures, its purpose, and how to read it.
PRs & Commits per Day
Dual-axis bar chart. PRs (left axis) and commits (right axis) per day. A high commits-to-PR ratio may indicate scope creep.
Daily Line Churn
Lines added (green) and deleted (red) per day. Building work produces mostly additions; refactoring produces a mix. Days with no churn may indicate blockers.
PR Cycle Time
Hours from PR open to merge, one bar per PR. Long bars indicate review bottlenecks. Generated only when PR data is available.
Cumulative Stories Done
Line chart tracking stories marked DONE during the sprint. Steady upward slope is healthy; plateauing signals a stall.
Retrospective
What went well
- Throughput and discipline: 161 PRs in six days, closed on day six within the seven-day box — an improvement on sprint 19's nine-day overrun. Zero open PRs at close, no stale branches.
- The compass ecosystem delivered at scale: 31 workflow skills across
every pillar, the
compass headingnext-item recommender, timeline snapshot generation — all three stories complete and shipped. - The codegen literate migration finished. This commitment carried from sprint 18 through 20 — it is done. All 32+ mustache templates are now literate org sources; MASD knowledge graph fully cross-linked; zero-diff drift check in place.
- Provisioning shipped end-to-end in one sprint: design, CLI implementation, org-mode script library, and a user manual chapter. No half-finished work.
- Sprint audit ran clean at close; health reviews were honest and the HR5 close recommendation was taken without hesitation.
What hurt
- The commissioning mission repeated the sprint 19 pattern — tooling gravity won. 161 PRs shipped and the sprint's stated goal (commission the entity library) was not achieved: two entities out of fourteen were meaningfully touched (currency 7/8 done, country 1/6 done). The retrospective note from sprint 19 — "the tooling excuse is spent" — did not hold.
- Sprint planning included 19 stories that were never touched. These functioned as planning inventory, not sprint commitments. Twelve commission entities and five codegen guardrail stories appeared in the sprint table but never had a start date; their presence made the commissioning mission look underway when it was not.
- The codegen model dashboard was a mis-bet: planned, started, and abandoned in the same sprint when the d3-force JS approach proved unworkable at 127 nodes. The sunk cost was modest but the lesson is to time-box explorations explicitly.
- Windows and macOS CI verification slipped for the third consecutive sprint. The root cause (rfl/MSVC C1202 complexity) is cleared, but a story with no start date never gets started.
What changed
- Sprint closure now has a formal Postponed section that explicitly separates in-progress stories (where effort was invested) from never-started stories. Story states are normalised at close (BLOCKED→BACKLOG with blockers preserved in Now/Waiting on); the sprint audit catches stale states mechanically.
- Sprint 21 must operate under a hard constraint: no new tooling stories unless they directly unblock a commission task in the same sprint. The commissioning mission is the only permissible mission until the entity library is commissioned.
Release Notes
See release_notes.org for the full narrative.