Skip to content

Commit 142272d

Browse files
committed
πŸ€– Say that the second root execution is optional (#260)
The module contract opened by claiming `xmd prompt` owns two root document executions, and its flow diagram ended by running the second one unconditionally β€” one line after the line listing stdout, an `--output` file, a run, or both as the four ways the bytes are delivered. A reader following the diagram would conclude that a default invocation runs the Plan it just printed. Every invocation executes the packaged prompt command document. A second root is executed only under `--run`. The diagram now shows the four deliveries as the alternatives they are, and the paragraph after it puts the complete scope boundary where it belongs: before that optional second execution, so whatever result follows has already let go of the conversation that wrote it. The same claim opened the prompt profile's header and the Tier PR introduction, and three nearby comments still had execution as the thing that follows approval rather than one of the things that might. Corrected to the approved bytes, or to the run that may follow. Prose only: no runtime behaviour, no tests and no evidence changed. Claude-Session: https://claude.ai/code/session_015HcqB9kJM9KFnMNToAuZF6
1 parent 0a927b4 commit 142272d

4 files changed

Lines changed: 32 additions & 21 deletions

File tree

β€Žpackages/cli/src/cli.tsβ€Ž

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1936,8 +1936,8 @@ function* dispatch(
19361936
yield* exit(1);
19371937
break;
19381938
}
1939-
// Once, here, and handed to both consumers below. Authorship and the
1940-
// execution that follows it are one invocation, so they answer to one
1939+
// Once, here, and handed to both consumers below. Authorship and the run
1940+
// that may follow it are one invocation, so they answer to one
19411941
// `--default-agent`, one `DEFAULT_AGENT_NAME` and one permission mode.
19421942
const promptStack = yield* settleAgentStack(
19431943
{

β€Žpackages/cli/src/prompt-profile.tsβ€Ž

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -3,12 +3,12 @@
33
* runs under, and the only thing that ever runs under it
44
* (specs/prompt-command-spec.md).
55
*
6-
* `xmd prompt` owns two root document executions with a complete scope boundary
7-
* between them. This module is the first one. It supplies that document's
8-
* inputs, a constrained Agent provider, Elicitation, the fixed first-party
9-
* components and the host-declared draft validator, and it exposes no custom
10-
* root and no repository component search: the document it runs is the one the
11-
* CLI ships.
6+
* `xmd prompt` executes this root on every invocation, and a second one β€” the
7+
* Plan it returns β€” only under `--run`, behind a complete scope boundary. This
8+
* module is the one that always happens. It supplies that document's inputs, a
9+
* constrained Agent provider, Elicitation, the fixed first-party components and
10+
* the host-declared draft checker, and it exposes no custom root and no
11+
* repository component search: the document it runs is the one the CLI ships.
1212
*
1313
* The Agent ceiling is assembled here rather than read from the command line,
1414
* because it is not the caller's to choose. Writing a Plan is a conversation

β€Žpackages/cli/src/prompt.tsβ€Ž

Lines changed: 18 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -2,26 +2,35 @@
22
* `xmd prompt` β€” the trusted host around the prompt command document
33
* (specs/prompt-command-spec.md).
44
*
5-
* The command owns two root document executions with a complete scope boundary
6-
* between them:
5+
* Every invocation executes one root document β€” the packaged prompt command
6+
* document β€” and a second one only when `--run` asks for it:
77
*
88
* ```text
99
* fixed command preflight
1010
* -> build the run-profile syntax catalog
1111
* -> execute the exact packaged prompt command document
1212
* -> await that execution and provider teardown
1313
* -> validate the returned source again
14-
* -> deliver the exact bytes: stdout, an --output file, a --run, or both
15-
* -> execute retainedSource("<prompt>", source) through the ordinary run path
14+
* -> deliver those exact bytes, in exactly one of four ways:
15+
* (default) write the source to stdout
16+
* --output exclusively create the file
17+
* --run execute retainedSource("<prompt>", source)
18+
* through the ordinary run path
19+
* --output --run create the file, then execute it
1620
* ```
1721
*
22+
* The complete scope boundary sits before that optional second execution: the
23+
* command document and everything it built are gone before a Plan is admitted,
24+
* so whichever result follows, it follows an invocation that has already let go
25+
* of the conversation that wrote it.
26+
*
1827
* What a person is asked, how many drafts may be repaired, how many may be
1928
* reviewed and what happens when nobody approves anything are not here. They are
2029
* in `src/documents/prompt-command.md`, written in the open, where they can be
2130
* read and argued with. This module is what a policy cannot be trusted to do for
2231
* itself: settle the command line, build the ceiling the assistant runs under,
2332
* answer honestly about a draft, and hold the boundary between text an agent
24-
* wrote and a program this host runs.
33+
* wrote and a Plan this host will hand over or run.
2534
*
2635
* Two kinds of failure are told apart throughout, because they have different
2736
* remedies. A *draft* failure is something the agent wrote, so the prompt
@@ -110,7 +119,7 @@ export interface PromptCommand {
110119
/**
111120
* The Agent configuration this invocation settled, before the command ran.
112121
*
113-
* Settled by the caller rather than here, because the execution that follows
122+
* Settled by the caller rather than here, because the run that may follow
114123
* approval is configured from the same answer: two resolutions of one command
115124
* line is two chances to read `DEFAULT_AGENT_NAME` differently.
116125
*/
@@ -193,8 +202,9 @@ export function* runPrompt(command: PromptCommand, deps: PromptDependencies): Op
193202

194203
// Every supplied individual option's shape, as the first draft that bound it
195204
// declared it. Frozen while the Plan is being written and carried into the
196-
// final gate, so the bytes that run are checked against the command line that
197-
// was written rather than against whichever draft happened to be last.
205+
// final gate, so the bytes that are delivered are checked against the command
206+
// line that was written rather than against whichever draft happened to be
207+
// last.
198208
const frozen = new Map<string, OptionSignature>();
199209

200210
// The command document lives and dies inside that call's scope. Leaving it

β€Žspecs/executable-mdx-spec.mdβ€Ž

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -10043,11 +10043,12 @@ One checked-in Markdown suite runs the real command against a fixture directory.
1004310043

1004410044
### Tier PR β€” The `xmd prompt` command
1004510045

10046-
Two root executions with a scope boundary between them: the packaged prompt
10047-
command document, which owns the visible generation, repair, review and failure
10048-
policy, and β€” only under `--run` β€” the Plan it returned, which runs as any
10049-
supplied root does. Without `--run` the approved Plan is the result: stdout by
10050-
default, or an exclusively created `--output` file. Defined in
10046+
One root execution on every invocation β€” the packaged prompt command document,
10047+
which owns the visible generation, repair, review and failure policy β€” and a
10048+
second only under `--run`: the Plan it returned, which runs as any supplied root
10049+
does, behind a complete scope boundary. Without `--run` the approved Plan is the
10050+
result rather than a second execution: stdout by default, or an exclusively
10051+
created `--output` file. Defined in
1005110052
[`xmd prompt`](./prompt-command-spec.md), whose acceptance table this points at
1005210053
rather than restating. The ACPX runtime is a scriptable fake, the review provider
1005310054
is a scripted `Elicitation` handler, and the contextual working directory is a

0 commit comments

Comments
Β (0)