Run document sections as hierarchical workflow targets

[taras]

Story

As a project maintainer, I want sections of an ordinary README or executable Markdown document to be addressable and runnable, so one readable document can describe common preparation once and expose its sections as repeatable workflows.

README hierarchy already expresses composition. A selected section inherits the preparation written in its ancestor sections, while unrelated sibling sections do not run.

Example

# Project

prepare the project

## Test

run the tests

## Verification

verify the project

xmd targets README.md

README.md#Test
README.md#Verification

xmd run README.md#Verification

The selected execution is equivalent to this projected document:

# Project

prepare the project

## Verification

verify the project

The root preparation and the selected section run. The Test sibling is absent and does not execute.

An unqualified invocation retains today's whole-document behavior:

xmd run README.md

There is no separate --target option. The fragment is part of the document reference and works wherever a root document can be selected:

xmd run README.md#Test
xmd workflow start README.md#Release/Publish

Section execution

A document's root-flow Markdown headings form a hierarchy.

Selecting a section executes:

1. the document preamble;
2. the direct content of each ancestor section along the selected path; and
3. the selected section's complete subtree in document order.

It excludes every sibling subtree along that path.

For example:

# Project

prepare the project

## Release

prepare the release

### Build

build artifacts

### Publish

publish artifacts

README.md#Release runs project preparation, release preparation, Build, and Publish. README.md#Release/Publish runs project preparation, release preparation, and Publish, but not Build.

The projected output retains the headings on the selected path. They remain passive Markdown and keep the emitted result readable and structurally coherent.

A single outermost heading is the document title and is omitted from target fragments. If a document has multiple outermost headings, none is an unambiguous title, so those heading names remain in their paths.

Target discovery and matching

xmd targets <document> lists all statically addressable heading paths. It does not infer whether a section contains effects: a prose-only target is valid and simply expands without producing durable effects.

Only headings authored in the root document's Markdown flow define targets. Headings nested inside component content do not:

## Review

<Prompt>
 ## Instructions
 Check the implementation carefully.
</Prompt>

This document exposes README.md#Review, not README.md#Review/Instructions. Headings produced by components, expressions, or other expansion are not addressable. Target discovery is static and side-effect-free.

The fragment is a hierarchical glob over normalized, statically visible heading text:

• / separates heading levels;
• literals match heading text;
• * matches within one hierarchy level and never crosses /;
• ** matches recursively across zero or more hierarchy levels.

Examples:

README.md#Test
README.md#Release/*
README.md#Ver*
README.md#**/Verification

In the initial contract, every selector must resolve to exactly one section. No match or multiple matches fails immediately and reports the matching or available canonical paths. Duplicate or ambiguous headings are not disambiguated with occurrence numbers; authors give them distinct structural paths.

The resolved exact heading path is canonical. The caller's glob is invocation metadata, not durable identity.

Scope and root contract

Targeting projects the root body before expansion. It does not create an implicit component or a second props model.

The engine:

1. loads and parses the complete root definition;
2. resolves the target without executing the document;
3. projects the ancestor path and selected subtree; and
4. validates and executes the projected body using the existing root component contract.

Consequences:

• root frontmatter and component resolution still define the document;
• root props are available unchanged;
• the root return schema still applies;
• <Return> and <Output> structural rules are checked against the selected projection, not skipped siblings;
• every target in a value root satisfies the same declared return schema; and
• an unqualified run validates and executes the complete body as it does today.

Skipped sibling sections contribute no output, bindings, effects, resources, or component invocations. A target cannot depend on a binding or side effect created by a skipped sibling. Shared preparation belongs in a common ancestor or reusable component.

Shared API and durable identity

Selection is a runtime-neutral root-document capability, not logic implemented only by the CLI.

The shared source and inspection APIs represent an optional target selector, resolve it through the same parser, and expose canonical targets for xmd targets and other hosts. File and inline source behavior must remain one coherent source model; a host does not inspect one definition and execute another.

For a retained workflow, the resolved exact target path extends the versioned workflow definition descriptor:

descriptor version
+ object kind
+ object format
+ immutable object ID
+ repository-relative root document path
+ resolved exact target path

For a Git definition, the immutable object ID is the pinned commit. A repository locator and local checkout path remain replaceable, credential-free retrieval metadata: they do not participate in run identity and the host reauthorizes them before use.

Different targets in the same immutable object and root document are different workflow definitions. Resume uses the recorded descriptor and exact target, reauthorizes whatever retrieval metadata is current, and does not re-resolve the caller's glob against a changed checkout.

Target projection preserves original source positions and deterministic expansion identity within that selected definition. Replay of the same target observes the same projection. Existing run/workflow durability, failure, cancellation, secret filtering, output, and replay contracts otherwise remain unchanged.

Markdown links

A reference such as README.md#Verification remains an ordinary Markdown link when it appears inside a document. Rendering or expanding a link never executes its target.

An XMD-aware host may recognize the reference and offer an explicit Run action. Execution starts only when a caller passes the reference to xmd run, xmd workflow start, or the equivalent shared API.

Future fan-out

A selector that resolves multiple paths fails in this story.

A future feature may fan a multi-match selector out into one independent run or workflow per resolved target. Each execution will have its own run ID, journal, status, Workspace, and lifecycle. This is orchestration above a single document execution: ** retains its standard recursive glob meaning and does not itself mean fan-out.

Acceptance

• xmd run README.md retains whole-document behavior.
• xmd run README.md#Target executes ancestor direct content plus the selected subtree and excludes sibling subtrees.
• Selecting a non-leaf section executes all of its descendants in document order.
• Selected output retains the ancestor and target headings.
• A single outermost title is omitted from canonical fragments; multiple outermost headings remain addressable path segments.
• xmd targets lists canonical references without executing the document.
• Only static root-flow headings are addressable.
• Literal, *, and ** hierarchical matching obey the exact-one rule.
• Zero and multiple matches fail before expansion or effects and report useful canonical paths.
• Skipped siblings cannot emit, bind values, acquire resources, invoke components, or perform effects.
• The selected projection retains the root's props, frontmatter, return, and output contracts.
• The shared execution and inspection APIs, CLI run mode, and workflow start mode use the same target representation and resolution.
• Retained definition identity includes the resolved exact target path, while the original glob remains non-authoritative invocation metadata.
• Resume uses the recorded immutable definition and target.
• Markdown links remain passive.
• Existing unselected execution, error, cancellation, output, secret-filtering, and replay behavior remains covered.
• The executable MDX, CLI, and workflow definition specifications describe the shipped contract in present tense.

Related work

• Reframe the website around repeatable workflows #352 frames Executable.md as turning documentation into repeatable workflows.
• Quest: Resume workflows with their Workspace, repositories, and Agent state #218 owns retained workflow and Workspace architecture.
• Run Markdown workflows in an in-browser playground #410 owns browser-playground execution and can consume the same inspection and target-reference contract.
• Dogfood hierarchical README targets in developer tooling #414 dogfoods this contract in executable.md's own README and developer tooling.