Skip to content

Commit 869a001

Browse files
committed
🐛 State the whole Plan requirement in every turn that asks for one (#260)
A repair or a revision was told to "keep" the draft's title. That is the wrong instruction for a replacement: a draft whose title is missing, in the wrong place, or does not describe the Plan has nothing worth keeping, and an instruction to keep it asks the coding agent to carry the defect forward. Each Plan-producing turn — the first draft, each repair, each revision — now states the complete requirement on its own: optional frontmatter and then one descriptive level-one heading as the first body content, the Prompt's complete sequence as readable steps, every requested outcome, a meaningful order, and each component beside the prose describing what it does. Replacements are told to write the title the Plan needs rather than the one the last draft had. None of that reaches `<CheckDraft>`, `validateDocument()` or TypeScript. It is what the workflow asks for and what a person reviews, which is where a judgement about whether a title describes a Plan belongs. The prose under "Continue from your decision" claimed a final invalid draft left only one choice. It leaves two: ask the coding agent what went wrong, or stop. The governing documents still described the earlier command. They were swept deliberately rather than by replacing words: the opening example is a titled Plan, the flow shows the four destinations, and the failure table, timeout paragraph, acceptance rows, terminology rows, construct inventory, executable-MDX identity section, ACP lifecycle paragraph and root-props admission paragraph no longer say that an approved Plan always runs, that `--save` is the output option, that stopping is called abort, that admission is followed unconditionally by execution, or that every success writes a journal. The evidence follows the same rule. The approved introduction is pinned whole, punctuation included, rather than sampled; the requirement block is asserted against the actual initial, repair and revision turns and counted three times in the shipped source; and the run-only preflight table covers every spelling, including `-V` and `--secret-detection`. The test-local `validateCandidate` is `checkDraft`, so a terminology sweep finds no survivor of the old name. Claude-Session: https://claude.ai/code/session_015HcqB9kJM9KFnMNToAuZF6
1 parent 7f2a10f commit 869a001

10 files changed

Lines changed: 252 additions & 93 deletions

‎architecture.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -34,9 +34,9 @@ Existing documents and code get aligned to this section retroactively.
3434
| pinned commit | the commit obtained by resolving a base once; it remains the workflow run's starting repository state even as the run creates descendant commits |
3535
| document target | an addressable static heading in a root document's own Markdown flow, named by the canonical path of heading labels that reaches it; selecting one executes the preamble, each ancestor's own content, and that heading's complete subtree |
3636
| Prompt | a person's original request, in ordinary natural language. `xmd prompt` takes exactly one |
37-
| Plan | the executable program produced from a Prompt: an Executable Markdown document combining readable prose that expresses the Prompt's intent with the components that carry it out, each placed beside the prose describing what it does. A Plan is what `xmd prompt` approves, optionally saves and runs; it is not a synonym for a workflow, a policy document or any executable Markdown file |
38-
| prompt command document | the one exact checked-in first-party Markdown value root `xmd prompt` executes to convert a Prompt into a Plan. It implements that conversion and its review workflow — the request wording, the draft and repair loops, the check branches, human review, revision, approval, abort and exhaustion — and returns the exact approved Plan source. It is not itself a Plan. Internal: no command-line option selects another one, and no repository component search can answer for it |
39-
| prompt profile | the trusted-host assembly used only for the prompt command document: its fixed inputs, a constrained Agent provider, Elicitation, the fixed first-party components and the host-declared draft validator. It uses no repository component search and exposes no custom root, and the ceiling it establishes is not readable from the command line. Its working directory is one host-owned directory dedicated to the logical prompt session, keyed by the digest of that name, created empty and required to be empty on the way in. An explicitly named session's directory is durable, because continuation derives the same session identity from it; an invocation-unique default session's is scope-owned, claimed before it is created, and exactly one cleanup is attempted after profile teardown and before admission on every ending — the leaf removed non-recursively when it is still the empty directory that was handed over, and left as found with the command failing terminally when it has gained content or vanished. Where those directories live is a host dependency no caller or document selects |
37+
| Plan | the executable program produced from a Prompt: an Executable Markdown document combining readable prose that expresses the Prompt's intent with the components that carry it out, each placed beside the prose describing what it does. It begins with one descriptive level-one heading. A Plan is what `xmd prompt` approves and then delivers: printed to stdout by default, written to an `--output` file, and run only under `--run`. It is not a synonym for a workflow, a policy document or any executable Markdown file |
38+
| prompt command document | the one exact checked-in first-party Markdown value root `xmd prompt` executes to convert a Prompt into a Plan. It implements that conversion and its review workflow — the Prompt wording, the draft and repair loops, the `<CheckDraft>` branches, human review, revision, approval, stopping, exhaustion and the final explanation turn — and returns the exact approved Plan source. Every Plan-producing turn in it states the complete Plan requirements for itself, so a replacement may add or correct a title rather than only carry one forward. It is not itself a Plan. Internal: no command-line option selects another one, and no repository component search can answer for it |
39+
| prompt profile | the trusted-host assembly used only for the prompt command document: its fixed inputs, a constrained Agent provider, Elicitation, the fixed first-party components and the host-declared `<CheckDraft>`. It uses no repository component search and exposes no custom root, and the ceiling it establishes is not readable from the command line. Its working directory is one host-owned directory dedicated to the logical prompt session, keyed by the digest of that name, created empty and required to be empty on the way in. An explicitly named session's directory is durable, because continuation derives the same session identity from it; an invocation-unique default session's is scope-owned, claimed before it is created, and exactly one cleanup is attempted after profile teardown and before admission on every ending — the leaf removed non-recursively when it is still the empty directory that was handed over, and left as found with the command failing terminally when it has gained content or vanished. Where those directories live is a host dependency no caller or document selects |
4040
| expansion | one logical evaluation of an authored executable element within a document execution |
4141
| expansion ID | a deterministic identifier for one logical expansion; restoring or retrying that expansion preserves the ID, while a distinct evaluation requested by the document receives another |
4242
| Git capability | the contextual interface through which workflow infrastructure queries the Git repository associated with the current working directory |
@@ -3545,7 +3545,7 @@ Status is measured against main.
35453545
| --- | --- | --- |
35463546
| `xmd syntax` | describes every structural construct and every selected component the production `run` profile would let a document write in the contextual working directory, as deterministic Markdown or as version-1 JSON, from one catalog. Inspection only: it registers the run profile's declarations in a bounded scope and reads the filesystem for which files exist and, for a selected Markdown component, that file's frontmatter. It runs no body, imports no repository TypeScript module, installs no provider, mints no authority and writes no journal. An include it cannot enumerate — a selection-relevant symbolic link to a directory beneath it included — fails the whole request rather than printing a healthy subset | built on the #632 stack |
35473547
| document validation | validates one supplied root projection and the recursive Markdown source closure normal component selection discovers, returning deterministic version-1 document diagnostics and `valid`, `invalid` or `not-statically-checkable` invocation outcomes without evaluating document code or installing operational host behavior | built on the #654 stack |
3548-
| `xmd prompt` | turns one Prompt into a Plan and runs it, by executing two root documents with a complete scope boundary between them. First the packaged prompt command document, under the internal `<prompt-command>` identity, inside the prompt profile: one enclosing Session, a host ceiling of one host-owned directory dedicated to that logical session — keyed by the digest of the name, never the name, created empty and required to be empty before the provider exists or a session is materialized, refused rather than cleaned when it is not, durable when the caller named the session and handed back non-recursively after teardown when it did not — with no additional directories, no MCP servers, no native tools and a private strict denial no permission flag widens, no Files, command, service or network capability for that document, no repository component search, and one host-declared `<CheckDraft>` whose closed assessment answers `valid: false` for a defect the draft authored and raises for a defect the command line authored. Its instructions require every Plan to begin with one descriptive level-one title and to keep the Prompt's outcomes as readable steps with each component beside the step it performs, through repairs and revisions alike; that is an authorship and human-review requirement, and `<CheckDraft>` never enforces it. A tenth draft that still has problems may be stopped or explained: the explanation is one more ordinary turn in the same Session carrying only the final diagnostics, is inert text, reopens no draft limit, and ends the command. The host's instruction layer states only that an answer belongs to the message that asked for it, so which shape a turn wants stays in the document. Authorship sits outside durability: it runs on an invocation-owned in-memory stream that is never journaled, persisted, reused or replayed. Then, only after that execution and every provider, Prompt task and Elicitation resource inside it has torn down, the host validates the returned Plan again, resolves props for exactly those bytes, and then delivers the approved Plan where the caller asked: to stdout byte for byte by default, to an exclusively created `--output` path, and — only under `--run` — through the ordinary supplied-source path under the `<prompt>` identity, one ordinary document with its own Agent provider, its own journal and ordinary run output, result and failure behavior. A journal exists only when `--run` begins, and the flags that configure only a run are refused in preflight without it | built on the #659 stack |
3548+
| `xmd prompt` | turns one Prompt into a Plan and delivers it, by executing one root document — and, only under `--run`, a second — with a complete scope boundary between them. First the packaged prompt command document, under the internal `<prompt-command>` identity, inside the prompt profile: one enclosing Session, a host ceiling of one host-owned directory dedicated to that logical session — keyed by the digest of the name, never the name, created empty and required to be empty before the provider exists or a session is materialized, refused rather than cleaned when it is not, durable when the caller named the session and handed back non-recursively after teardown when it did not — with no additional directories, no MCP servers, no native tools and a private strict denial no permission flag widens, no Files, command, service or network capability for that document, no repository component search, and one host-declared `<CheckDraft>` whose closed assessment answers `valid: false` for a defect the draft authored and raises for a defect the command line authored. Its instructions require every Plan to begin with one descriptive level-one title and to keep the Prompt's outcomes as readable steps with each component beside the step it performs, through repairs and revisions alike; that is an authorship and human-review requirement, and `<CheckDraft>` never enforces it. A tenth draft that still has problems may be stopped or explained: the explanation is one more ordinary turn in the same Session carrying only the final diagnostics, is inert text, reopens no draft limit, and ends the command. The host's instruction layer states only that an answer belongs to the message that asked for it, so which shape a turn wants stays in the document. Authorship sits outside durability: it runs on an invocation-owned in-memory stream that is never journaled, persisted, reused or replayed. Then, only after that execution and every provider, Prompt task and Elicitation resource inside it has torn down, the host validates the returned Plan again, resolves props for exactly those bytes, and then delivers the approved Plan where the caller asked: to stdout byte for byte by default, to an exclusively created `--output` path, and — only under `--run` — through the ordinary supplied-source path under the `<prompt>` identity, one ordinary document with its own Agent provider, its own journal and ordinary run output, result and failure behavior. A journal exists only when `--run` begins, and the flags that configure only a run are refused in preflight without it | built on the #659 stack |
35493549
| `<PrintErrors>` / `printErrors(fn)` | prints failures | built on main |
35503550
| `<Fail message>` | stops authored work with the sentence its author wrote, raised where it is written. An ordinary overridable core default — never structural, never reserved, so a repository `Fail.md` is chosen ahead of it — with a closed schema of one required non-empty `message` and **self-closing only**: a paired spelling never enters its body, and `as` is refused by the body itself because there is nothing to bind. Every refusal reports the invocation and happens before the authored message, so a document that never reached its decision is never reported as having made one. A valid invocation is the ordinary failure of a function component: an `Error` carrying the exact authored message, positioned at the opening tag, rendering nothing and binding nothing. It carries no `printErrors()` declaration, which is what leaves recovery to an authored `<PrintErrors>` region under ordinary text-root modes; a value body's `throw` is not replaced there, so the authored failure settles the body ahead of missing-`<Return>` settlement. No authority, context, provider, resource, module state or durable operation of its own: replay of a completed root restores the recorded outcome without re-expanding the body | built on the #659 stack |
35513551
| `<Let as="name">` | binds one name in the current environment from exactly one source: the content it renders, or the exact value `value` names, bound by reference and never through the JSON boundary component props cross — the scanner resolves no JSON for that one prop, and expansion projects none. Which source it has is read from what the author wrote, before either one runs, so a construct naming both expands no child and evaluates no expression. It opens no scope, owns no resource, adds no middleware boundary and writes no journal record — replay reconstructs both sources through ordinary expansion | built on the #527 stack |

‎packages/cli/src/documents/prompt-command.md‎

Lines changed: 40 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -40,11 +40,17 @@ Create one complete XMD Plan from this Prompt:
4040

4141
{props.request}
4242

43-
Begin the Plan with one level-one Markdown title that describes it.
43+
Every Plan is complete on its own:
4444

45-
Write the Plan as a sequence of readable steps. Follow each step with the XMD
46-
component that carries it out. The prose is part of the program and appears when
47-
the Plan runs, so its source and its execution tell the same story.
45+
- optional frontmatter, and then one descriptive level-one Markdown heading as
46+
the first body content;
47+
- the Prompt's complete sequence, written as readable steps;
48+
- every outcome the Prompt asked for;
49+
- those steps in an order that makes sense; and
50+
- each XMD component beside the prose describing the action it performs.
51+
52+
The prose is part of the program and appears when the Plan runs, so its source
53+
and its execution tell the same story.
4854

4955
For the Prompt "ask me for my age and write it to a file", the shape is:
5056

@@ -96,9 +102,20 @@ That Plan has problems. These are the exact ones:
96102
<Json value={check.diagnostics} as="problems" />
97103
<CodeBlock value={problems} language="json" />
98104

99-
Send one complete replacement Plan that resolves every problem above. Keep its
100-
level-one title, keep the Prompt's sequence of readable steps in a meaningful
101-
order, and keep each XMD component beside the step it performs.
105+
Send one complete replacement Plan that resolves every problem above.
106+
107+
Every Plan is complete on its own:
108+
109+
- optional frontmatter, and then one descriptive level-one Markdown heading as
110+
the first body content;
111+
- the Prompt's complete sequence, written as readable steps;
112+
- every outcome the Prompt asked for;
113+
- those steps in an order that makes sense; and
114+
- each XMD component beside the prose describing the action it performs.
115+
116+
Write the title the Plan needs rather than the one the last draft had: add it if
117+
it was missing, move it if it was not the first body content, and replace it if
118+
it did not describe the Plan.
102119

103120
Reply with the Plan source and nothing else. No enclosing code fence, no
104121
explanation before or after it.
@@ -167,8 +184,8 @@ problems:
167184

168185
Approve keeps this exact draft and leaves the review. Request changes sends your
169186
feedback to the coding agent and starts a new draft. Stop ends here. On a tenth
170-
draft that still has problems there is nothing left to revise into, so the
171-
remaining choice is to ask the coding agent what went wrong.
187+
draft that still has problems there is nothing left to revise into, so the two
188+
remaining choices are to ask the coding agent what went wrong, or to stop.
172189

173190
<If condition={review.decision === "Approve"}>
174191
<Let as="approved" value={draft} />
@@ -205,9 +222,20 @@ You read that Plan and asked for this to change:
205222

206223
{review.feedback}
207224

208-
Send one complete replacement Plan. Keep its level-one title, keep the Prompt's
209-
sequence of readable steps in a meaningful order, and keep each XMD component
210-
beside the step it performs.
225+
Send one complete replacement Plan.
226+
227+
Every Plan is complete on its own:
228+
229+
- optional frontmatter, and then one descriptive level-one Markdown heading as
230+
the first body content;
231+
- the Prompt's complete sequence, written as readable steps;
232+
- every outcome the Prompt asked for;
233+
- those steps in an order that makes sense; and
234+
- each XMD component beside the prose describing the action it performs.
235+
236+
Write the title the Plan needs rather than the one the last draft had: add it if
237+
it was missing, move it if it was not the first body content, and replace it if
238+
it did not describe the Plan.
211239

212240
Reply with the Plan source and nothing else. No enclosing code fence, no
213241
explanation before or after it.

0 commit comments

Comments
 (0)