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.

sprint_20_all_builds_green.png

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

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.

prs_commits.png

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.

line_churn.png

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.

pr_cycle.png

Cumulative Stories Done

Line chart tracking stories marked DONE during the sprint. Steady upward slope is healthy; plateauing signals a stall.

stories_done.png

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 heading next-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.

Emacs 29.1 (Org mode 9.6.6)