Document Types

• :PROPERTIES: :ID: — org-roam tracks documents by ID, not by path. Every document needs one; generate with uuidgen. Paths can change; IDs do not. Every UUID — both the :ID: property and every [[id:UUID]] link — is uppercase hex. The codegen enforces this for new documents (doc_generate.py uppercases the freshly minted ID, the templates carry uppercase concept-link UUIDs, and --parent-id / --predecessor-id are uppercased defensively); any hand-edited or copy-pasted UUID must follow the same rule. The Sprint 18 story Lock down uppercase UUID invariant records the rationale and the audit trail.
• #+filetags: — the standard org-mode keyword for applying tags to a whole file. #+tags: in standard org-mode declares the allowed tag vocabulary for a file, which is a different concern and not what we want here.
• #+todo: — declares the TODO state vocabulary used by the document. Stateful documents use TODO keywords on their * Status headline; the folder structure carries no state information.
• No #+links: keyword — links live in the document body as id: links (see Linking between documents below). Org-roam picks them up automatically.

#+todo: DISCOVERED BACKLOG STARTED BLOCKED | DONE ABANDONED

Active states are left of the bar; terminal states are right.

• DISCOVERED — found in passing while executing another task; not yet triaged.
• BACKLOG — triaged, scheduled, not started.
• STARTED — an agent is actively working on it. Org auto-stamps the transition via LOGBOOK.
• BLOCKED — paused waiting on something. The reason lives in #+blocked_on (one of review, ci, local_build, external).
• DONE — terminal success. Org auto-stamps CLOSED: on the headline.
• ABANDONED — terminal failure. The reason lives in the Status ** Notes or similar block; audit flags abandoned tasks without one.

Every stateful document has a * Status section formatted as a table. The state lives in the State row (greppable), and the row order is fixed: State / Parent <type> / Now / Waiting on / Next / Last touched. Versions are top-level so the Parent row is dropped.

* Status
,
,| Field        | Value                              |
,|--------------+------------------------------------|
,| State        | STARTED                            |
,| Parent story | Currencies end-to-end |
,| Now          | Implementing the XML serialiser.   |
,| Waiting on   | Nothing.                           |
,| Next         | Add round-trip tests.              |
,| Last touched | 2026-05-21                         |

The Status section sits after the document's "what is this?" section (* Goal for tasks/stories, * Mission for sprints, * Identity for versions) so the reader knows what the doc is before reading its state. Operational detail of in-flight work goes in Now / Waiting on / Next / Last touched and is updated on every agent or orchestrator action.

• Shallower trees. The folder structure mirrors composition only (version → sprint → story → task), no state subdivisions.
• Native org-mode tooling. Org-agenda, the org-mode mode line, and TODO cycling (C-c C-t) all work out of the box on the state of the * Status heading.
• Atomic transitions. Changing state is one edit; the diff is small.
• State-by-grep. grep -lR "^| State.*STARTED" finds every in-flight document in seconds.

• Standard org-mode tag syntax: :tag1:tag2:tag3: — colons on both sides of each tag, no spaces inside.
• All lowercase. Multi-word tags use snake_case.
• At least one tag is required. Two to four is typical. More than six is usually a sign the document needs to be split.

A document's tags should cover the dimensions below where applicable. Tags are flat (no hierarchy), but readers should be able to infer the dimension from the tag itself.

• Component — which area of the codebase: trading, sql, qt, cli, http, compute, shell, codegen, modeling, …
• Domain topic — what the content is about: fx_forward, pricing, reporting, observability, ci, build, release, security, ux, …
• Activity — what kind of work: refactor, new_feature, bug_fix, documentation, migration, cleanup, testing, …
• Status modifier (optional) — blocked, needs_review, urgent, stale.

• A task to add an FX Forward import test: :trading:fx_forward:testing:new_feature:
• A recipe for running the build: :cmake:build:recipe:
• A knowledge doc on the codegen architecture: :codegen:architecture:knowledge:
• A sprint focused on Qt UI work: :qt:ux:sprint:

Every stateful document carries one tag for each of its ancestors in the composition tree (immediate parent first). This duplicates the #+links relationship in a grep-friendly form: #+links drives the org-roam graph, the ancestor tags drive the shell.

• A task tags with its story's slug, and its sprint's slug, and its version's slug.
• A story tags with its sprint's slug, and its version's slug.
• A sprint tags with its version's slug.

Examples (filetags only, content tags omitted):

• A task in versions/v0/sprint_03/login_and_sessions/ → :login_and_sessions:sprint_03:v0:.
• A story in versions/v0/sprint_03/ → :sprint_03:v0:.
• A sprint in versions/v0/ → :v0:.

Single-step lateral queries:

# every task / story / file in sprint_03
grep -lR ":sprint_03:" doc/agile/versions/

# every story in story currencies_end_to_end (which is one, but you
# can grep for siblings on the same theme by switching the tag)
grep -lR ":currencies_end_to_end:" doc/agile/versions/

# every file in version v0
grep -lR ":v0:" doc/agile/versions/

The generator at projects/ores.codegen/generate_doc.sh derives the ancestor slugs from the --parent-dir path (following the versions/<version>/<sprint>/<story>/ layout) and adds them all to #+filetags automatically, on top of any --tags the user supplies.

Stories carry a #+category: frontmatter field (not a tag) that classifies their intent. Categories are used to slice velocity metrics: feature throughput, housekeeping load, and enabler investment are tracked separately so the team can see whether sprint time is going to the right places.

Rules:

• Every story must carry exactly one category.
• When a story spans multiple categories, assign the dominant intent. A story that mostly refactors but incidentally adds an endpoint is still housekeeping.
• Sprints should aim for ≥ 50% feature stories by count. A sprint skewed toward housekeeping or enabler should be noted in the health review focus signal.

• The audit job (System 3*) lists every tag in use and flags singletons (tags used exactly once) for review — they are usually typos or one-offs that should fold into an existing tag.
• The canonical Tag inventory (doc/meta/tag_inventory.org) lists every valid tag grouped by dimension; compass lint validates against it.
• Audit also verifies the parent-tag invariant: every task must carry exactly one story slug as a tag; every story must carry exactly one sprint slug; every sprint must carry exactly one version slug.