🚚 Rename xmd prompt to xmd plan (#670) - #671
Merged
Merged
Conversation
The authorship command is named for its result. `xmd plan "<Prompt>"` takes one Prompt and delivers the Plan it produced, and `xmd --help` describes it as "Create an executable Plan from a Prompt and review it before writing or running it." The rename carries the identities that name the command: the packaged root is `plan-command.md` and runs under `<plan-command>`, the constrained trusted-host assembly is the authorship profile, generated logical sessions are `xmd-plan:<UUID>` under `~/.xmd/plan/sessions`, and the approved Plan runs under `<plan>`. Nothing about authorship policy, authority, property behavior, output mode, failure ordering, cancellation or teardown changes. The packaged Markdown document's only edits are its title, its one explanatory sentence and its four authored `<Fail>` messages. `<Prompt>` remains the ordinary one-turn Agent component: its API, failure policy, `agent_prompt` records and the capitalized Prompt in authored instructions are untouched. The old spelling is not registered, aliased or kept as a tombstone. A token naming no command continues through the existing default-run grammar, and nothing reads, migrates or removes `~/.xmd/prompt`.
…670) The spec's four result-mode rows wrote `xmd plan "<plan>"`, borrowing the final supplied-source identity for the argument the command receives. The command takes the person's Prompt and produces a Plan, so the rows now read `xmd plan "<Prompt>"`. Every other `<plan>` names the identity approved bytes run under and is unchanged. The retired-namespace sentinel sat at a `-retired` sibling of the harness's own root — a path no production code consults, so it proved nothing about `.xmd/prompt`. It now sits at a literal `.xmd/prompt/sessions` beside the `.xmd/plan/sessions` the command is given, both under one temporary tree the case owns and removes whole. The case observes that the conversation really ran under the plan namespace before reading the sibling back, so an empty listing cannot stand in for a command that reached neither tree. No production source, and no part of the packaged Markdown document, changes.
| const provisional = xmd.parse({ args: helpRequest.args }); | ||
| const selected = provisional.ok ? provisional.value.config : undefined; | ||
| // The two commands that end in a document execution. `xmd prompt`'s deadline | ||
| // The two commands that end in a document execution. `xmd plan`'s deadline |
There was a problem hiding this comment.
Redundant comment — restates what the code does.
Suggested change
| // The two commands that end in a document execution. `xmd plan`'s deadline |
PR #671: 🚚 Rename
|
taras
marked this pull request as ready for review
August 31, 2026 00:33
#670) `prompt` names no command, and a first token that names none is a document reference to the default `run` command. So an executable document called `prompt` in the working directory was rendered and executed by `xmd prompt` — exit 0, and a file written — by a caller who wrote what they believed was a command. That is authorship-adjacent execution and a durable effect from the spelling this rename retired. An invocation whose exact first token is `prompt` is now refused at the top of `runXmd()`: before the inline-document scan, before command selection, and before anything reads a path. It fails closed, establishing no catalog, Agent, Session, authorship directory, output, journal or execution: xmd prompt is not a command — use `xmd plan "<Prompt>"` to create a Plan, or `xmd run ./prompt` to run a document named `prompt` The message answers both readings, because the token is ambiguous by construction. `prompt` is still not registered, aliased or listed in help — this is a preflight refusal, not a command. Only the exact first token is recognized, so `xmd run ./prompt`, `xmd run prompt` and `xmd ./prompt` still execute a document legitimately called that; refusing the bare token must not cost the ability to run a file with that name. The earlier claim that falling through to default run satisfied the retired spelling was wrong, and it was written down in the suite commentary, the command spec, the mdx acceptance row and the architecture inventory. All four now describe the fail-closed preflight instead. No production behaviour outside that preflight changes, and the packaged Markdown document is untouched.
| const provisional = xmd.parse({ args: helpRequest.args }); | ||
| const selected = provisional.ok ? provisional.value.config : undefined; | ||
| // The two commands that end in a document execution. `xmd prompt`'s deadline | ||
| // The two commands that end in a document execution. `xmd plan`'s deadline |
There was a problem hiding this comment.
Redundant comment — restates what the code does.
Suggested change
| // The two commands that end in a document execution. `xmd plan`'s deadline |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #670.
Why
The authorship command was named for its input rather than its result. It takes a Prompt — what you describe — and produces a Plan: an executable Markdown document with reader-facing prose beside the components that carry it out.
xmd plansays that.Nothing is published under the old name. The latest release is
v0.9.2, which predates the command entirely, so this is a rename with no compatibility surface — no alias, no deprecation, no tombstone.What changes
Before:
After:
xmd --helpnow lists:and lists no
promptcommand. The four result modes are unchanged: source on stdout by default,--output <path>,--run, or--outputfollowed by--run.How it works
Identity-bearing values only:
xmd promptxmd planprompt-command.mdplan-command.md<prompt-command><plan-command><prompt><plan>xmd-prompt:<UUID>xmd-plan:<UUID>~/.xmd/prompt/sessions~/.xmd/plan/sessionsNo authorship policy, authority, property behavior, output mode, failure ordering, cancellation or teardown behavior changes.
Review guide
Start with: the
packages/cli/src/documents/plan-command.mddiff — it should be exactly six lines.Then review:
plan-args.tsandcli.tsfor command selection and help;authorship-profile.tsfor the renamed ceiling and directory namespace;plan.tsfor the phase graph and<plan>identity.Look carefully at:
<Prompt>is a different concept and had to survive. It is the ordinary one-turn Agent component.installPromptFailurePolicy,agent_promptrecords, the fake'sprompts, therequestprop and the capitalized Prompt in authored text all stay. The residual-terminology classification below is the evidence that nothing genuine was renamed to make a text search come back empty.<plan>is the final supplied-source identity, not the person's input. Fifteen uses name that identity —retainedSource("<plan>", source),PLAN_IDENTITY,(<plan>:5:1)positions, diagnostics, journals. A blind rename would have corrupted them.rungrammar safely absorbed an unregistered token. That was wrong:promptwas read as a document path, soxmd promptbeside a file namedpromptrendered it, exited 0 and wrote a file.runXmd()now refuses the exact first tokenpromptas its very first operation — before eval-flag reading, command selection or any document lookup — andxmd run ./promptstill runs a document by that name.promptis registered nowhere, aliased to nothing and absent from help.What must stay true
xmd prompt→xmd plan(title, one explanatory sentence, four authored<Fail>messages). Headings, props, schemas, both loop bounds,<CheckDraft>placement, review choices,<Return>and every branch are identical.<Prompt>and the Agent API do not change — no file underpackages/core,packages/acporpackages/test-agentappears in either commit.~/.xmd/prompt.prompt, proves it is neither rendered nor run and writes no sentinel, then provesxmd run ./promptstill executes it.How to verify it
At
613a4075: five suites5 passed (46 steps)— the 43 that made #260 acceptable, two rename cases and the retired-token refusal; the adjacent dispatch suites (cli-help,command,inline-cli,syntax-cli)6 passed (53 steps), run because the refusal sits at the top ofrunXmd(); packaged-document1 passed; npm byte-identity1 passed (46s); loaderpass 2under Node and2 passunder Bun;deno task check,lint,buildandgit diff --checkall clean.Because the rename moves a compiled asset and both
deno compile --includesites, the compiled binary was rebuilt and probed from a temporary cwd with a temporaryHOME:It fails at the first Agent turn, not with a missing packaged document — so the embedded asset loaded, expanded under
<plan-command>, opened its Session and reached the turn. The temporary home held.xmd/plan/sessionsand no.xmd/prompt, and the invocation-unique leaf was handed back.Three regressions were confirmed to fail without their subject, since one that passes either way proves nothing: the retired-namespace sentinel fails when
releaseSessionDirectoryis made to remove the sibling recursively; the loader case fails if a conflictingplan-command.mdplanted in the working directory could answer for the packaged one; and both retired-token cases fail with the preflight disabled.Scope
Included
git mvrenames — four source modules, four test suites, one harness, one spec — all detected as renames (77–93% similarity);PromptDiagnostic→DraftDiagnosticwhere the name meant a finding owned by the command rather than an Agent Prompt;architecture.mdand five specs.Intentionally unchanged
<Prompt>, Prompt failure policy andagent_promptdurable vocabulary.plan-command.md's policy, structure, bounds and wording beyond the command name.~/.xmd/prompt, which is left exactly as any existing installation has it.--run=<value>proofs, kept as three cases rather than collapsed during the move.Risks and limitations
~/.xmd/promptbecomes inert. Nothing migrates it. A caller who had used--session <name>gets a fresh directory under the new namespace, so an ACPX session established under the old one will not be continued. Acceptable because nothing is published, but it is a real behavioral consequence rather than a pure rename.test-weights.jsonhas no entry for the renamed suites, so they keep the corpus fallback until the next dispatched measurement.plan-cli.test.tssuite title was chosen to keep itsdescribecall multi-line: shortening it dropped the call under the formatter's column threshold, which reindented ~700 lines and destroyed rename detection. The title is taken verbatim from that file's own module comment; no assertion or contract changed.Scope confirmation
https://claude.ai/code/session_015HcqB9kJM9KFnMNToAuZF6