Skip to content

Make <Plan> expand inline by default #711

Description

@taras

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions