Story
As an Executable Markdown author, I want an approved <Plan> to expand where I
wrote it, so a document can create and carry out a program without leaving the
current execution. When I need the approved source instead, I capture it with
as and none of that program runs.
Common path
Without as, <Plan> authors, reviews and approves one XMD program, then
expands the exact approved source inline at its invocation site:
Prepare the release program and carry it out here.
<Plan>
1. Read package.json and CHANGELOG.md.
2. Ask an Agent to recommend the next semantic version and explain why.
3. Validate the answer.
4. Ask me to approve it.
5. Write RELEASE.md.
</Plan>
The release program completed, so continue with the result.
The <Plan> content expands once to form the complete Prompt. Drafts stay
inert. After approval, the constrained authorship environment tears down, the
exact approved source is structurally admitted, and that source expands between
the surrounding prose.
An author who wants the approved program without carrying it out captures it:
<Plan as="program">
Prepare the release program.
</Plan>
This binds the exact approved source under program and performs none of the
program's effects. Authorship and review are about the program's contents; they
do not change according to whether the authored document expands or captures
the result.
Current gap
PR #685 completed #660 by adding <Plan> to the ordinary run profile. The
component is currently a value component: it requires as, binds the approved
source as a string, and never expands that program.
xmd plan --run can execute an approved Plan, but it does so only after
authorship ends by starting a second root through the CLI. An embedded <Plan>
has no way to carry out its approved program inside the enclosing execution.
Contract
<Plan> produces approved XMD program source rather than ordinary rendered
text. Authorship always completes under the existing constrained authorship
profile, and the approved bytes have two engine-owned outcomes:
- without
as, canonical execution admits and expands the source inline at the
<Plan> site;
- with
as, canonical execution binds the exact source and does not expand it;
and
- stopped, rejected, exhausted, failed, or cancelled authorship produces no
program expansion and no binding.
The ordinary run profile declares this behavior as trusted host metadata on the
exact packaged <Plan> component. Markdown frontmatter, repository components,
workflow bundles, and component registrations cannot request it. Ordinary value
components continue to require as, including value components that return a
string.
Inline Plan source is an embedded text-root projection, not another document
execution:
- its own frontmatter metadata, imports, and
<Output> selection apply;
- it sees the caller's bindings and current ambient
props; when it declares
root props, that schema validates the current props before its first effect;
- a source declaring root
returns is refused before its first effect because
an inline <Plan> has no destination for a root value; and
- it uses the enclosing execution's current component selection, Workspace,
authority, output flow, failure mode, and cancellation scope.
The inline projection creates no second lifecycle, root result, journal, or
host profile. Its expansion and every effect receive durable identities beneath
the authored <Plan> site. Replay restores the exact approved source without
repeating authorship and resumes an interrupted expansion without repeating a
completed effect.
Security and durability
- No candidate, rejected draft, or captured program executes.
- The authorship profile tears down completely before approved source can
expand or be bound.
- The approved program receives only the authority already present at the
authored execution site; model output grants no authority.
- The trusted executable-source disposition is unavailable to document-authored
components and is captured with the run profile before installation begins.
- Admission retains the exact approved source, and ordinary component selection
records detect an incompatible replay instead of silently selecting a
different implementation.
- Adding
as prevents every effect of the approved program while preserving the
same authorship and review contract.
Acceptance
<Plan> without as expands one approved program exactly where the component
appears: an observable effect between two surrounding markers occurs once,
and no approved source text is emitted in its place.
- The same
<Plan as="program"> binds byte-for-byte approved source while a
negative-control effect in that source does not occur.
- Stopping, rejecting, exhausting, failing, or cancelling authorship leaves the
enclosing document without any approved-program effect or binding.
- Inline source uses representative current-profile syntax, caller bindings,
ambient props, imports, and <Output> behavior without starting another
document lifecycle.
- A declared root-props mismatch and a root
returns declaration each refuse
the inline source before a negative-control effect runs.
- A partial journal resumes inside the approved program without another
authorship turn, review, or completed effect.
- An ordinary string-valued component still refuses an invocation without
as,
and a repository component cannot opt into executable-source disposition.
- Validation,
xmd syntax, the npm package, and the compiled binary describe
and ship the same <Plan> contract.
Evidence
Extend packages/cli/tests/plan-component.test.ts with immediate, captured,
refused, cancelled, and replayed Plan cases. Add focused core coverage for the
trusted disposition, embedded text-root projection, and ordinary value-component
negative control. The tests fail if captured source executes, replay authors
again, a root contract is discarded, or inline expansion starts another root.
Run the exact focused files plus deno task test --changed. Distribution probes
cover the npm and compiled assets when the packaged <Plan> declaration
changes.
Dependencies and related work
Out of scope
- A public Markdown frontmatter field for executable-source returns.
- Deferred full-program expansion through
<Evaluate>.
- An independent nested-document
<Run> component or process isolation.
- Executing an unapproved draft.
- Widening the authorship Agent's tools, filesystem, network, or permission
ceiling.
- Giving ordinary string-returning components executable behavior.
Story
As an Executable Markdown author, I want an approved
<Plan>to expand where Iwrote it, so a document can create and carry out a program without leaving the
current execution. When I need the approved source instead, I capture it with
asand none of that program runs.Common path
Without
as,<Plan>authors, reviews and approves one XMD program, thenexpands the exact approved source inline at its invocation site:
The
<Plan>content expands once to form the complete Prompt. Drafts stayinert. After approval, the constrained authorship environment tears down, the
exact approved source is structurally admitted, and that source expands between
the surrounding prose.
An author who wants the approved program without carrying it out captures it:
This binds the exact approved source under
programand performs none of theprogram's effects. Authorship and review are about the program's contents; they
do not change according to whether the authored document expands or captures
the result.
Current gap
PR #685 completed #660 by adding
<Plan>to the ordinary run profile. Thecomponent is currently a value component: it requires
as, binds the approvedsource as a string, and never expands that program.
xmd plan --runcan execute an approved Plan, but it does so only afterauthorship ends by starting a second root through the CLI. An embedded
<Plan>has no way to carry out its approved program inside the enclosing execution.
Contract
<Plan>produces approved XMD program source rather than ordinary renderedtext. Authorship always completes under the existing constrained authorship
profile, and the approved bytes have two engine-owned outcomes:
as, canonical execution admits and expands the source inline at the<Plan>site;as, canonical execution binds the exact source and does not expand it;and
program expansion and no binding.
The ordinary run profile declares this behavior as trusted host metadata on the
exact packaged
<Plan>component. Markdown frontmatter, repository components,workflow bundles, and component registrations cannot request it. Ordinary value
components continue to require
as, including value components that return astring.
Inline Plan source is an embedded text-root projection, not another document
execution:
<Output>selection apply;props; when it declaresroot props, that schema validates the current props before its first effect;
returnsis refused before its first effect becausean inline
<Plan>has no destination for a root value; andauthority, output flow, failure mode, and cancellation scope.
The inline projection creates no second lifecycle, root result, journal, or
host profile. Its expansion and every effect receive durable identities beneath
the authored
<Plan>site. Replay restores the exact approved source withoutrepeating authorship and resumes an interrupted expansion without repeating a
completed effect.
Security and durability
expand or be bound.
authored execution site; model output grants no authority.
components and is captured with the run profile before installation begins.
records detect an incompatible replay instead of silently selecting a
different implementation.
asprevents every effect of the approved program while preserving thesame authorship and review contract.
Acceptance
<Plan>withoutasexpands one approved program exactly where the componentappears: an observable effect between two surrounding markers occurs once,
and no approved source text is emitted in its place.
<Plan as="program">binds byte-for-byte approved source while anegative-control effect in that source does not occur.
enclosing document without any approved-program effect or binding.
ambient props, imports, and
<Output>behavior without starting anotherdocument lifecycle.
returnsdeclaration each refusethe inline source before a negative-control effect runs.
authorship turn, review, or completed effect.
as,and a repository component cannot opt into executable-source disposition.
xmd syntax, the npm package, and the compiled binary describeand ship the same
<Plan>contract.Evidence
Extend
packages/cli/tests/plan-component.test.tswith immediate, captured,refused, cancelled, and replayed Plan cases. Add focused core coverage for the
trusted disposition, embedded text-root projection, and ordinary value-component
negative control. The tests fail if captured source executes, replay authors
again, a root contract is discarded, or inline expansion starts another root.
Run the exact focused files plus
deno task test --changed. Distribution probescover the npm and compiled assets when the packaged
<Plan>declarationchanges.
Dependencies and related work
<Plan>component #660 and PR Add the <Plan> component to xmd run #685 supply the packaged<Plan>authorship component and exactapproved-source return.
<Evaluate>evaluate complete XMD programs #713 owns deferred inline expansion of captured complete programs through<Evaluate>after this embedded projection exists.xmd plan --runremains the CLI's explicit independent-execution path and abehavior to compare, not the topology for inline expansion.
Out of scope
<Evaluate>.<Run>component or process isolation.ceiling.