Skip to content

Make xmd plan produce approved XMD source only #724

Description

@taras

Story

As a command-line user, I want xmd plan to produce one reviewed XMD program
artifact and never execute it, so I can choose explicitly when and where that
program runs.

Common paths

Write the exact approved source to stdout:

xmd plan "Prepare the release program."

Compose planning and execution explicitly through standard input:

xmd plan "Prepare the release program." | xmd run -

Or preserve the artifact first and run the saved file later:

xmd plan "Prepare the release program." --output release.md && xmd run release.md

--output remains an exclusive file sink: it creates the requested path only
after approval and never replaces an existing file. Without it, stdout contains
only the exact approved program bytes.

One command responsibility

xmd plan maps one instruction string to reviewed and approved XMD source. It
uses the same packaged <Plan> workflow as an ordinary document and does not
start a second root after authorship.

The packaged plan-command document remains a thin adapter: it supplies the
command surface to <Plan>, captures the resulting text, and returns those
exact bytes. The host awaits authorship and teardown, performs the existing
final caller-owned checks, and sends the artifact to exactly one destination.
No approved program effect runs on any success or failure path.

Command grammar

Remove --run completely; it has no alias. --run, --run=true,
--run=false, repeated occurrences, and any placement of that spelling receive
one actionable migration refusal before a catalog, Agent, session, review,
output file, journal, or document execution exists:

xmd plan --run was removed because xmd plan only produces approved source.
Run the program explicitly:
  xmd plan "..." | xmd run -
  xmd plan "..." --output release.md && xmd run release.md

Retain only arguments that configure planning or artifact disposition:

  • the one instruction argument;
  • --include for the syntax catalog;
  • --agent-provider and --default-agent for authorship;
  • --session for the planning conversation;
  • --timeout for the whole planning invocation;
  • --output for the exclusive artifact sink; and
  • ordinary --help and --version behavior.

Remove options that configured the approved program's former execution:

  • generated root-property arguments: --props, --props-*, and --no-props-*;
  • --journal / -j;
  • --raw;
  • --verbose / -V;
  • --timeout-exec and --timeout-fetch;
  • --approve-all, --approve-reads, and --deny-all;
  • --secret-detection and --no-secret-detection.

Each removed spelling refuses as an xmd plan option before authorship. The
corresponding xmd run options remain unchanged. Planning-specific progress and
diagnostic trace work belongs to #676 rather than preserving execution flags
under a new interpretation.

Update command help to say that xmd plan creates, reviews, and writes approved
XMD source. Help never promises to run it and shows both explicit compositions.

Exact artifact behavior

  • Default stdout and --output receive the same byte-identical source and
    digest supplied by #722.
  • Status, review UI, and later planning-progress output do not contaminate
    stdout; interactive presentation uses its existing non-stdout channels.
  • Stop, exhaustion, failure, cancellation, or final refusal writes no artifact
    and starts no program.
  • The output file is created exclusively only after approval and teardown.
  • A command continuation or planning session cannot cause the approved program
    to execute implicitly.

Acceptance ownership

This story exclusively owns these Quest cases:

  • CLI Plan: exact approved bytes reach stdout or the exclusive output file;
    a negative-control program effect never occurs.
  • Removed option: every --run spelling reports the migration above and
    never aliases or executes.

The successful stdin pipeline belongs to #723; this story owns the Plan
producer and the diagnostic that points to it.

Documentation and focused evidence

Rewrite specs/plan-command-spec.md around the single source-artifact outcome.
Update the command/component inventory and command lifecycle in
architecture.md and specs/executable-mdx-spec.md. Update CLI help, README,
and the homepage delivered by PR #719 so they show the public model explicitly:

Plan produces a program.
Evaluate evaluates a program in the current XMD execution.
Run executes a program from the host/CLI.
Composition decides whether and when a planned program runs.

The homepage includes both <Plan> followed by <Evaluate> and xmd plan | xmd run -; PR #719 remains historical and unchanged.

Focused feedback evidence:

deno task test \
  packages/cli/tests/plan-cli.test.ts \
  packages/cli/tests/plan-command-document.test.ts \
  packages/cli/tests/plan-component.test.ts \
  packages/cli/tests/syntax-cli.test.ts \
  packages/cli/tests/packaged-document.test.ts

The CLI suite covers every retained and removed option class, exact stdout and
exclusive output, all no-artifact failures, and negative-control non-execution.
After a feedback commit, run deno task test --changed. Delivery proves the npm
binary with scripts/tests/cli-npm-bin.test.ts, the compiled command with
scripts/tests/plan-component-compiled.test.ts after deno task build, and the
required CI checks.

Dependencies

  • #722 supplies the exact text-producing <Plan> artifact.
  • #723 makes the prescribed pipe migration executable before --run is
    removed.

Out of scope

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