Open questions
The complement to discoveries.md: discoveries record what has been found; this records what is open. It is the SSOT for the library’s authored architectural questions — the deliberately-deferred decisions, documented honestly rather than re-litigated each session. (CLAUDE.md points here and stays agent-operational; it no longer carries these.)
When a session has a strong case for resolving one, the move is: (a) write the case down, (b) execute the resulting refactor as a single discrete pass that updates every reference across the library, (c) update this file.
Authored architectural questions
Taxonomy axes
Current pattern categories (productivity, temporal, resource-lifecycle, compliance, messaging, workflow, healthcare) mix conceptual axes — healthcare is domain-scoped while the others are concept-scoped; compliance mixes pure-compliance-infrastructure atoms with atoms that happen to be regulated. The right axial split will be forced by content as the catalog grows past the size where preemptive cuts are reasonable; restructuring earlier would relocate the same confusion under different labels. The workflow/ sub-question — whether one atom justifies the category — is resolved (2026-06-04): the category now holds two grounded atoms, Approval Step (the fixed-state pole — states fixed by the atom) and Workflow / State Machine (atom #9, the general-declared pole — states declared by the deployment), so it stands on present catalog evidence rather than on a planned atom. The broader axial split question across all categories is independently open. See the Open question on the current axes paragraph in the Taxonomy section of the-spec-layer.md, and roadmap.md §”Open taxonomy question” for the parallel ROADMAP framing.
Status (2026-06-08): RESOLVED — executed. The usage-derived taxonomy (atoms/TAXONOMY.md) landed: atoms are stored flat (atoms/<name>.md), cross-cutting classification (regulated / security / standards) is derived from the composition graph as overlays, and domain is the one intrinsic, EOS-gated axis. This dissolves the mixed-axes problem — there is no longer one folder per atom to mis-assign. See the 2026-06-08 entry in discoveries.md.
Regulation as folder vs. attribute
The former compliance/ folder conflated two things: atoms whose primary domain is compliance infrastructure (Actor Identity, Retention Window, Tamper Evidence — these have no meaningful non-regulated use case), and atoms that belong to other domains but carry a heavy regulated surface (Soft Delete is resource-lifecycle by nature; Medication Order and Clinical Observation are healthcare; Legal Hold could reasonably be resource-lifecycle or temporal). As the library grows, “regulation” may belong as a frontmatter attribute — regulated: true, or a standards: [GDPR, HIPAA, FRCP] field — rather than a folder that atoms are placed in by consequence rather than by domain. The practical implication: the compliance/ folder may eventually narrow to pure compliance infrastructure primitives, while regulated atoms in other domains carry their regulatory surface as metadata. This restructuring will cause significant tree churn and cross-reference updates across every regulated atom’s Composition notes; it should be executed as a single discrete refactor pass once the content forces the decision, not incrementally. Deferred until the catalog is large enough to make the right cut obvious.
Status (2026-06-08): RESOLVED — executed. regulated / standards / security are now derived from the composition graph (never a folder, never a stored attribute); the move landed flat storage plus generated browse-by-overlay views. The live sub-questions carry forward in atoms/TAXONOMY.md: uncomposed atoms, and the regulated-overlay stewardship obligation that is intrinsic to compliance-infrastructure atoms even when derived classification says otherwise (e.g. selective-disclosure, which the generated view should lint for the overlay sections separately from classification).
Substrate-composing overlay and reverse-leverage view (added 2026-06-12)
A composition that names another composition in its ## Composes (a “super” / substrate composition) is a structural fact derivable straight from the composition graph — does Composes reference ≥1 composition? — exactly like the regulated / security overlays the usage-derived taxonomy already derives. Today it is legible only by reading each spec (a 2026-06-12 hand count: 14 of 24 grounded compositions are substrate-composing; 13 build on Audit Trail, Data Subject Rights Fulfillment is two layers deep, Privileged Access Provisioning composes two compositions at once). It should be a derived overlay in tools/taxonomy/, never a hand-applied tag — a hand-maintained one would drift like a count snapshot. Inverting the same edge yields the reverse-leverage view — “Audit Trail: composed by 13” — which surfaces the reuse leverage a flat pattern count hides (and guards the count against being misread as independent-concept breadth). Open — to generate; trivial once the taxonomy generator gains a composition→composition edge pass.
Guided-process state → phase → action mapping
For the human-facing guided process (the double-diamond entry model — create/select/extract at the vision / composition / atom levels, seeded rough, refined by diverge→converge), the irreducible thing to define is the mapping from an artifact’s state — MUSE completeness state, pressure-testing round, conformance status, ## Composes graph position — to its diamond phase and the prescribed next diverge/converge action. The state substrate already exists; the mapping does not. It is the prerequisite the guided tooling would project from (the tooling derives “where am I / what’s next” from artifact state rather than asking the human to declare it). Open — to define.
Readability ↔ completeness — dialing in the accessibility balance
The library’s load-bearing premise is the bridge principle (the-spec-layer.md §Bridges): the canonical text must be readable by every audience at once, humans included. In practice the corpus still skews toward terse, expert shorthand in places — formal coverage: Inv 4 pending rather than formal coverage of Invariant 4 pending; colon-packed status markers and abbreviations a fluent author parses instantly but that cost every other reader a beat on every access. Self-explanatory phrasing is strictly better there: same meaning, no glossary, no parse, for a few more words the library already commits to paying (verbosity is the architecture of the bridge). The accessibility machinery exists — three reading tiers, the Tier-1-clean Summary, the no-undefined-acronym Pass 1 check — but it governs new prose; it has never been driven back through the accumulated terse surface.
Why this is open, not a TODO. Readability sweeps have been attempted before and failed to stick — a one-pass “make it readable” edit fights the same completeness pressure that produced the terseness, and the next dense pattern reintroduces it. This is one of Daniel Jackson’s standing complaints about software specification: rigor and accessibility get treated as a trade rather than a both. The library’s defensible sequencing has been complete before accessible — a spec cannot be made readable before it is correct and complete, so completeness was bought first, deliberately, accepting terse surface as interim debt. That sequencing was right; the balance is now dial-able.
The open question: what readability discipline actually holds — a standing authoring rule (self-explanatory over shorthand, enforced like the acronym check), a derived linter (flag colon-packed / abbreviated status markers and undefined shorthand), or a readability arm on the scheduled rescan — rather than a one-off sweep that decays. Until that is decided: prefer the fuller self-explanatory form when authoring or touching a line (the 2026-06-10 C12/C3 status correction adopted grounded — formal coverage of Invariant 4 pending on exactly this basis), and do not relaunch a corpus-wide readability sweep on the old failed model. Open — to define the discipline that sticks.
Status-line grammar and the roadmap status mirror (added 2026-06-11)
Two coupled problems surfaced by the 2026-06-11 root-doc scan. First, there is no canonical status grammar. The corpus carries at least six shapes: `grounded` with a parenthetical, a Tier-1 gloss inside the backticks (Soft Delete), grounded on Final Critique N with and without an em-dash date, qualifier statuses (grounded — formal coverage of Invariant 4 pending), and — in two compositions (Session-Gated Authorization, External Onboarding) — Status carried as a top-of-file **Status:** line instead of the ## Status section spec-format.md requires, a canonical-shape deviation by that document’s own rule. Second, roadmap.md mirrors ~50 status cells by hand with no defined semantics and no mechanical check — the 2026-06-11 scan found six rows stale (qualifiers missing on C3/C12; markers and dates behind on C4, C13, C14, C16, Attributed Permissions Admin) plus a duplicated row and a constituent-list mismatch, all while the linter scanned clean the same day. The linter today is pre-alpha, proof-of-concept grade: six high-precision checks, wired to no gate, and the status-mirror class is unwritable against six grammars.
The dependency chain to close it: (1) pin one status grammar in spec-format.md (one marker form, one date semantic — the latest complete round, per pressure-testing.md §Status line format — and ## Status as the only placement); (2) migrate the corpus’s Status lines to it in one discrete pass; (3) add the status-mirror linter check (pattern Status line ⇔ roadmap row) plus a table-duplicate check — both ~20 lines once the grammar exists; (4) wire the linter to an enforcement point — done 2026-06-11: the lint gate runs in continuous integration (.github/workflows/lint.yml), so the checks from step 3 enforce on arrival. Steps 1–2 are a real review pass with touch implications; until they land, roadmap rows are corrected opportunistically (the 2026-06-11 note in the roadmap marks the verified-vs-unverified boundary). Sub-item (added 2026-06-11, guided-tool design review F3): the token taxonomy is as unpinned as the grammar was — unresolved vs partially resolved has no stated boundary anywhere (pressure-testing.md §Status line format points at “the taxonomy above,” which defines none); pin the boundary alongside step (1). The guided tool meanwhile carries its own local mapping (unacknowledged findings → unresolved; resolved-or-carried → partially resolved). Open — steps 1–3 remain; sequencing decided, execution unscheduled.
Canonical vs. internal-staging legibility (added 2026-06-14)
The non-canonical material — the working-ideas/ staging docs (call-prep, the falsifiability metric, the prior-art/positioning note, the outbound-contract-ports registry, the strange-pattern forecast) — is distinguished from canon only de facto: it lives under working-ideas/, most files carry a > Status: internal staging, not canonical blockquote, and (unlike the canonical docs) they lack Jekyll front-matter and a roadmap row, so they are already nav-excluded from the published site. But the canonical/staging tier is derivable, not uniformly labeled — a reader, or an AI agent, landing mid-document cannot always tell at a glance whether a sharply-written staging sketch is canon. That is a drift/misread risk: a staging argument cited as settled canon is exactly the failure the no-snapshot discipline guards against elsewhere, and it grows as the working-ideas set does.
Why this is open, not a TODO. The de-facto convention mostly works, and the right fix is a labeling/rule hardening, not a relocation — moving files would churn the cross-references that now point into working-ideas/ for no gain. So the decision is which hardening: (1) a working-ideas/README that tags the whole folder at once; (2) a required, uniformly-worded staging blockquote on every non-canonical doc; (3) machine-readable front-matter (nav_exclude: true, or a status: staging field) so tooling and the published site filter automatically; (4) the rule written into AGENTS.md / contributing.md — non-canonical lives under working-ideas/ and carries the tag; canonical lives at root / atoms / compositions with front-matter and a roadmap row. Cheapest high-leverage combo is (1)+(4); (3) is the upgrade if an agent ever mis-cites. (Surfaced 2026-06-14 while staging the boundary/positioning notes; logged rather than acted on so it is captured, not lost.)
Trigger to resolve: when the working-ideas set outgrows easy familiarity, or the first time a staging doc is cited as canon (human or AI) — whichever comes first. Open — to decide the hardening, then execute as one pass that tags every non-canonical doc and writes the rule down.
Generated index (planned, not built)
Open questions are also scattered through the artifacts as markers: *(forthcoming)* links, atoms/compositions marked unresolved / partially resolved, open CORNERS items, and the sub-question sections in proposals (e.g. atoms/TAXONOMY.md). Those are derivable — a future generator should project them into an index appended here rather than anyone hand-maintaining the list. Same discipline as the taxonomy itself: name the irreducible (the authored architectural questions above), derive the rest.