Repository navigation
Description
To express an OST we currently support:
- a set of pages (nodes), each with a type and parent relationship (frontmatter)
- an "OST on a page" with conventions for defining a structure based on markdown content (headings, bullets, inline properties)
In theory these worlds could merge and the concepts for the latter could be supported in the former. That is, a goal page could include headings/lists for sub-goals and/or opportunities inline, just like in an OST structure. This allows for detailed pages where warranted, while not requiring it when there isn't as much detail. A really clear example of this would be to include the mission on a vision page instead of it being separate
Rough idea of how this could work:
- Extract the in-page extraction
- Support that in the readSpace code path - for each node, also look in the markdown for headings/bullets to add to the node list
- The
parentproperty needs a reliable convention for referring to the title extracted from the content of a parent page.
Example:
new_vision.md (vision title is "new_vision" based on the filename)
type: vision
---
Blah blah vision stuff
## [type:: mission] Our mission in 2026
Blah blah mission stuff. Note that mission title is "Our mission in 2026" based on the inline property and title content
make_moneys.md (goal title is "make_moneys")
type: goal
parent: [[new_vision#[type mission] Our mission in 2026]]
---
Blah blah goal stuff
This goal's parent wikilink is a (hopefully valid) reference to the heading in the vision page, recognised as a mission node.
Alternatively, or in addition, we could explore supporting anchor markup.
In vision doc: ## [type:: mission] Our mission in 2026 ^mission
In goal doc: parent: [[new_vision#^mission]]
Type is still needed in this case for parsing. That is, unless we decide that a unique named anchor matching the named OSTNode types is allowed as an alternative expression. This would be not just for linking, but parsing OST-on-a-page-like (aka embedded) content too. This wouldn't work for multiples, like multiple embedded goals on a page, unless we extend the convention to allowing numbered anchors (eg ^goal1) or something. This feels like it's well worth trying. While inline [type:: blah] is ok, I don't love it. We can keep that, but also allow this new approach.
Activity
mindsocket commentedon Feb 26, 2026
@claude work on this issue in a new branch. It is appropriate to overhaul the current divided architecture between "on a page" and "space" parsing, and to adapt and extend the tests accordingly, including new tests for this "hybrid" approach.
Note any decisions and assumptions you make in a comment here.
claude commentedon Feb 26, 2026
Claude finished @mindsocket's task in 24m 12s —— View job •
claude/issue-10-20260226-0439• Create PR ➔Working on Issue #10: Support "embedding" of subitems at any level
src/parse-embedded.ts— shared extraction logicsrc/read-ost-page.tsto use parse-embedded + support hybrid filessrc/read-space.ts— extract embedded nodes from all typed filessrc/validate.ts— fix node index building + handlefile#section/file#^anchorwikilinksWhat was implemented
New
src/parse-embedded.ts— all shared body-parsing logic (headings, typed bullets, YAML blocks, anchor extraction, depth inference) lives here, called by bothreadOstPageandreadSpace.Hybrid pages — any file with a real OST type (e.g.
type: vision) can now contain embedded child nodes in its body:Only headings with explicit
[type:: x]or an OST-type anchor (^mission,^goal1) become embedded nodes; other headings are depth-tracking placeholders.Cross-file parent refs — embedded nodes get compound labels (
filename#title) and generated parent refs use[[filename]]or[[filename#title]]:Anchor support —
^anchornamestored indata.anchor; indexed for[[File#^anchor]]wikilink resolution; anchors named after OST types imply type.ost_on_a_pagein space context — the file is no longer added as a single node; instead its embedded nodes are extracted withcontainer#titlecompound labels. TheincludePageFilesoption is removed.Decisions & Assumptions
includePageFilesoption fromreadSpace—ost_on_a_pagefiles always contribute embedded nodes nowost_on_a_pagemode retains depth-based type inference (backward compatible)anchorToOstType:^goal1→ type "goal"; exact match (^mission) also worksshowanddiagramCLI commands build parent-child trees usingdata.titleas the lookup key, which won't match compoundfilename#sectionparent refs — hybrid embedded nodes will surface as roots rather than children in those views. Can be fixed in a follow-up.|
mindsocket commentedon Feb 26, 2026
Following research on #3 (findings in
docs/torres-alignment-research.md):This issue's embedding work is the key enabler for the sub-entity model discussed in #5. Once heading/section embedding is supported at any level, sub-entities (assumptions, metrics, risks, problem statements) can be expressed as annotated headings within a primary entity page without requiring separate files. The schema defines the type in one place; full-page and embedded expressions both validate against it.
This "full page or embedded heading — both valid" flexibility is worth calling out as a deliberate design principle, to be documented in #18.
mindsocket commentedon Feb 26, 2026
By definition, historically at least, reading a space should look for files other than ost on a page. This allows a directory to evolve from an "on a page" to set of files without having to keep them separate, and avoiding collisions. It doesn't make sense to combine the approaches, and it doesn't make sense to force them to be in different directories. Restore how it worked before, reading a space collects all non-on-a-page files, and page based strictly reads nodes from only the file given.
Switching topics, it sounds like links and titles have been conflated. Titles are defined at the source from filename, header, or bullet. Links, including anchors ensure the correct referenced item is found but those links should resolve to plain titles in the schema. Perhaps some work is needed to better describe the wikilink formatting vs a title specification.
Specifically...
These compund labels might not be valid wiki links. Embedded nodes should simply get a resolved title ("Our mission"), type and parent. Parent links to that (eg vision#^mission) should resolve to the same unique title in the nodes.
Does that make sense @claude
claude commentedon Feb 26, 2026
Claude encountered an error —— View job
Working on corrections to Issue #10 implementation
filename#titlelabels[[file#section]]/[[file#^anchor]]→ plain title lookup)•
claude/issue-10-20260226-0709claude commentedon Feb 26, 2026
Claude encountered an error —— View job
I'll analyze this and get back to you.
fix: restore space/page separation and remove compound node labels
mindsocket commentedon Feb 26, 2026
Pushed corrections to
claude/issue-10-20260226-0439.Changes made
Restored space/page separation (
src/read-space.ts):Reverted to the original logic —
readSpacereads non-ost_on_a_pagefiles as single nodes, one per file. Hybrid files (typed pages with embedded content) are included as regular nodes; their body content is ignored in space mode. TheincludePageFilesoption is retained. No more embedded extraction in space mode.Removed compound labels (
src/parse-embedded.ts,src/read-ost-page.ts):Dropped the
labelPrefixoption fromextractEmbeddedNodes. Embedded nodes now always have plain resolved titles (e.g."The Mission"), and parent refs within a page use plain wikilinks (e.g.[[The Mission]]). The page itself is referenced by its filename sans extension (e.g.[[hybrid-page-valid]]).Updated fixture (
tests/fixtures/valid-ost/hybrid_solution.md):Changed
parent: "[[hybrid_vision#Embedded Goal]]"toparent: "[[hybrid_vision]]"— since embedded nodes are not extracted in space mode, the solution now correctly references the vision file as a whole.Updated tests:
read-space.test.ts: node count 9→7, hybrid section now asserts that no#-labelled nodes appear and that hybrid files are treated as single nodes.validate.test.ts: node count 9→7, removed compound-label test cases.What the wikilink/title distinction now looks like
In page mode (
readOstPageon a hybrid file):hybrid-page-valid.md, titlehybrid-page-validThe Mission, parent[[hybrid-page-valid]]The Goal, parent[[The Mission]]In space mode (
readSpace):hybrid_vision.md→ one node, titlehybrid_visionhybrid_solution.md→ one node, parent[[hybrid_vision]](references by filename key)Cross-file refs to embedded nodes (e.g.
[[vision#^mission]]) are out of scope for the current space validation path and can be addressed as a follow-up if needed.fix: restore space/page separation and remove compound node labels
fix: restore space/page separation and remove compound node labels
fix: restore space/page separation and remove compound node labels