Skip to content

Commit 0a927b4

Browse files
committed
🐛 Use the approved apostrophe, and refuse --save by name (#260)
The introduction claimed to be the approved wording and was one byte away from it: `coding agent's plan` with an ASCII apostrophe where the contract has U+2019. The regression that was supposed to catch that had copied the same byte, so it pinned the file to itself rather than the file to the contract. Both now carry E2 80 99, and the fixture's comment says why it is the byte and not the sentence that is being held. Two contract passages still described the earlier command. The ACP lifecycle said the profile's scope closes before "the save and the execution"; it closes before final admission and before whichever result was asked for. The command spec said `xmd prompt` executes two root documents; it always executes the command document and executes a second only under `--run`. The terminology sweep reached the comments, messages and test names that the earlier passes left behind: "the save" in the deadline and teardown comments, the harness's `--save`, the profile's two directory failures now saying "nothing was output or run", and the review-decision comments and test names that still called stopping an abort. The unrelated abort in `runDocument` is left alone — it is about a document's own failure, not this command's. `--save` had no real proof it was gone. The case that passed it also passed two mutually exclusive permission flags, so the earlier failure decided the outcome and the assertion would have held whether or not the option still worked. That case no longer carries it, and a focused one does — on a command line that is otherwise entirely valid. Making that case honest exposed something worth fixing. `--save out.md` was refused, but as "unrecognized argument: out.md": the scanner passed the unknown option to a parser that stops at the first option it does not define and drops the rest, so what a caller heard about was the value rather than the flag. Fixed preflight now refuses an option this command does not define, by name, and names `--output` when the option was `--save`. Claude-Session: https://claude.ai/code/session_015HcqB9kJM9KFnMNToAuZF6
1 parent 869a001 commit 0a927b4

12 files changed

Lines changed: 109 additions & 40 deletions

‎packages/cli/src/cli.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2176,7 +2176,7 @@ export function* runXmd(
21762176
const selected = provisional.ok ? provisional.value.config : undefined;
21772177
// The two commands that end in a document execution. `xmd prompt`'s deadline
21782178
// encloses more than a run's — the catalog, the assistant session, every
2179-
// repair, the human review, provider teardown, the save and the execution —
2179+
// repair, the human review, provider teardown, the output file and the run —
21802180
// because all of it is what the caller asked to be bounded.
21812181
const executes =
21822182
!helpRequest.requested &&

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ steps. It combines the original Prompt, which describes those steps, with the XM
1818
components available to carry them out. A coding agent turns both into one
1919
document that explains and executes the sequence.
2020

21-
The result is the XMD version of a coding agent's plan. A conventional Markdown
21+
The result is the XMD version of a coding agent’s plan. A conventional Markdown
2222
plan must be interpreted again before its steps can happen. An XMD Plan already
2323
contains those executable steps, so running it simply executes them.
2424

‎packages/cli/src/prompt-args.ts‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -208,6 +208,25 @@ export function scanPromptArgs(args: readonly string[]): PromptScan {
208208
continue;
209209
}
210210

211+
if (!KNOWN.has(name)) {
212+
// The parser stops at the first option it does not define and drops the
213+
// rest, so an option nobody defines would otherwise be accepted in
214+
// silence — and a caller who asked for something the command never did
215+
// has not been answered. `--save` is named because it is the one
216+
// spelling somebody may remember; it was replaced before release, so
217+
// there is no alias to keep.
218+
return {
219+
...(request === undefined ? {} : { request }),
220+
fixed,
221+
occurrences,
222+
error:
223+
name === "--save"
224+
? `unrecognized option for xmd prompt: --save — the approved Plan goes to stdout, ` +
225+
`and ${OUTPUT_OPTION} writes it to a file`
226+
: `unrecognized option for xmd prompt: ${name}`,
227+
};
228+
}
229+
211230
if (name === RUN_OPTION) {
212231
runs = true;
213232
}

‎packages/cli/src/prompt-profile.ts‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -389,8 +389,8 @@ function* establishDirectory(directory: string): Operation<Result<string>> {
389389
* empty and is handing back empty is removed; anything else is reported and
390390
* nothing is deleted, because a leaf that changed underneath a conversation
391391
* nobody authorized to write there is interference, not a tidying job. The
392-
* failure raises out of the profile's scope, so no final validation, save or
393-
* execution follows it.
392+
* failure raises out of the profile's scope, so no final admission follows it,
393+
* and the approved Plan reaches no stdout, no file and no run.
394394
*
395395
* A directory the conversation never got — establishment refused it, or never
396396
* made it — is a different question, and one already answered: whatever
@@ -410,14 +410,14 @@ function* releaseSessionDirectory(directory: string, claim: DirectoryClaim): Ope
410410
throw new Error(
411411
`${directory} was made for this conversation and is already gone. Something removed ` +
412412
"it while the conversation was still running, which nothing here is allowed to do; " +
413-
"nothing was saved or run",
413+
"nothing was output or run",
414414
);
415415
}
416416
if (code === "ENOTEMPTY" || code === "EEXIST") {
417417
throw new Error(
418418
`${directory} was empty when this conversation started and is not now. It belongs to ` +
419419
"one invocation, so nothing should have written there; its contents were left alone " +
420-
"and nothing was saved or run",
420+
"and nothing was output or run",
421421
);
422422
}
423423
throw error instanceof Error ? error : new Error(String(error));

‎packages/cli/src/prompt.ts‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@
1111
* -> execute the exact packaged prompt command document
1212
* -> await that execution and provider teardown
1313
* -> validate the returned source again
14-
* -> optionally save the exact bytes
14+
* -> deliver the exact bytes: stdout, an --output file, a --run, or both
1515
* -> execute retainedSource("<prompt>", source) through the ordinary run path
1616
* ```
1717
*
@@ -199,8 +199,8 @@ export function* runPrompt(command: PromptCommand, deps: PromptDependencies): Op
199199

200200
// The command document lives and dies inside that call's scope. Leaving it
201201
// closes the Prompt tasks, the provider and the Elicitation provider, so a
202-
// teardown failure raises out here — before the validation, the save and the
203-
// execution that would otherwise already have happened.
202+
// teardown failure raises out here — before the admission, the output file
203+
// and the run that would otherwise already have happened.
204204
let authored: Result<string>;
205205
try {
206206
authored = yield* runPromptCommandDocument({

‎packages/cli/tests/packaged-document.test.ts‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -27,8 +27,10 @@ import { useWorkingDirectory } from "./support/prompt-harness.ts";
2727
* The approved introduction, exactly.
2828
*
2929
* Pinned rather than sampled: this is the passage the product contract settled,
30-
* down to "coding agent's plan", and a paraphrase that still contained the
31-
* chosen sentences would pass a looser check while saying something else.
30+
* down to the typographic apostrophe in "coding agent’s plan". A paraphrase that
31+
* still contained the chosen sentences would pass a looser check while saying
32+
* something else, and an ASCII apostrophe here would quietly redefine the
33+
* approved wording around whatever the file happens to hold.
3234
*/
3335
const INTRODUCTION = [
3436
"# `xmd prompt` turns steps into a program",
@@ -38,7 +40,7 @@ const INTRODUCTION = [
3840
"components available to carry them out. A coding agent turns both into one",
3941
"document that explains and executes the sequence.",
4042
"",
41-
"The result is the XMD version of a coding agent's plan. A conventional Markdown",
43+
"The result is the XMD version of a coding agent’s plan. A conventional Markdown",
4244
"plan must be interpreted again before its steps can happen. An XMD Plan already",
4345
"contains those executable steps, so running it simply executes them.",
4446
"",

‎packages/cli/tests/prompt-args.test.ts‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -269,6 +269,23 @@ describe("Tier PR — xmd prompt fixed grammar", () => {
269269
}
270270
});
271271

272+
it("C1: an option this command does not define is refused, not dropped", function* () {
273+
// The parser stops at the first option it does not define and drops the
274+
// rest, so silence here would mean accepting a command line nobody honoured.
275+
const unknown = scanPromptArgs(["prompt", REQUEST, "--not-a-thing", "value"]);
276+
expect(unknown.error).toBe("unrecognized option for xmd prompt: --not-a-thing");
277+
278+
// `--save` was replaced before release, so there is no alias — and the
279+
// refusal says where the Plan goes now rather than only that the option is
280+
// unknown.
281+
const retired = scanPromptArgs(["prompt", REQUEST, "--save", "out.md"]);
282+
expect(retired.error).toContain("unrecognized option for xmd prompt: --save");
283+
expect(retired.error).toContain("goes to stdout");
284+
expect(retired.error).toContain("--output writes it to a file");
285+
// It is not quietly read as the option that replaced it.
286+
expect(retired.occurrences).toEqual([]);
287+
});
288+
272289
it("C7: a frozen option's shape is what a later candidate may not change", function* () {
273290
const scalar = bindingsFor({ name: { type: "string" } });
274291
const boolean = bindingsFor({ name: { type: "boolean" } });

‎packages/cli/tests/prompt-cli.test.ts‎

Lines changed: 31 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -192,7 +192,7 @@ describe(
192192
// the whole invocation shares now happens.
193193
yield* useWorkingDirectory(function* (dir) {
194194
const { code, stderr } = yield* runCli(
195-
["prompt", REQUEST, "--approve-all", "--deny-all", "--save", "out.md"],
195+
["prompt", REQUEST, "--approve-all", "--deny-all", "--run"],
196196
{ cwd: dir },
197197
).join();
198198

@@ -203,7 +203,30 @@ describe(
203203
// No provider was built: reaching one is what reports an agent as
204204
// unavailable, and this command line never got that far.
205205
expect(stderr).not.toContain("unavailable");
206+
});
207+
});
208+
209+
it("C1: --save is gone, and is refused as the unknown option it is", function* () {
210+
// Nothing was released under the old spelling, so there is no alias and
211+
// nothing to keep compatible with. Proven on a command line that is
212+
// otherwise entirely valid: a case that also carried a second, earlier
213+
// failure would pass whether or not `--save` still worked.
214+
yield* useWorkingDirectory(function* (dir) {
215+
const { code, stdout, stderr } = yield* runCli(["prompt", REQUEST, "--save", "out.md"], {
216+
cwd: dir,
217+
}).join();
218+
219+
expect(code).toBe(1);
220+
expect(stderr).toContain("--save");
221+
// Not accepted, not silently dropped, and not mistaken for `--output`.
206222
expect(yield* exists(join(dir, "out.md"))).toBe(false);
223+
// And nothing downstream of the refusal ran: no catalog was rendered, no
224+
// provider was reached, nobody was asked anything, no approved source
225+
// was printed, and no journal exists.
226+
expect(stdout).toBe("");
227+
expect(stderr).not.toContain("## Built-in components");
228+
expect(stderr).not.toContain("unavailable");
229+
expect(yield* until(readdir(dir))).toEqual([]);
207230
});
208231
});
209232

@@ -333,10 +356,10 @@ describe(
333356
});
334357
});
335358

336-
it("C12: every refusal is nonzero and leaves no save, journal or run", function* () {
359+
it("C12: every refusal is nonzero and leaves no output file, journal or run", function* () {
337360
const journalName = "trace.jsonl";
338361

339-
// Abort at review, through the command document's authored failure.
362+
// Stop at review, through the command document's authored failure.
340363
yield* useWorkingDirectory(function* (dir, profileRoot) {
341364
const harness = createPromptHarness({ profileRoot });
342365
harness.deps.execute = executor(dir, join(dir, journalName));
@@ -517,7 +540,7 @@ describe(
517540
);
518541

519542
expect(code).toBe(0);
520-
// The saved file already existed when the document started.
543+
// The output file already existed when the document started.
521544
expect(seen).toEqual([true]);
522545
// Source only: no diagnostics, no decision, no wrapper.
523546
expect(yield* readTextFile(join(dir, "out.md"))).toBe(GREETER);
@@ -570,12 +593,12 @@ describe(
570593
// The identity the run reports is the deliberate one.
571594
expect(yield* readTextFile(journal)).toContain("<prompt>");
572595
// Relative filesystem operations resolved the contextual cwd, not the
573-
// identity, so the document's own write landed beside the save.
596+
// identity, so the document's own write landed beside the output file.
574597
expect(yield* exists(join(dir, "greeting.txt"))).toBe(true);
575598
expect(yield* exists(join(dir, "out.md"))).toBe(true);
576599
});
577600

578-
// A runtime failure is an ordinary run failure: nonzero, with the save the
601+
// A runtime failure is an ordinary run failure: nonzero, with the file the
579602
// caller asked for still on disk to hand-edit.
580603
yield* useWorkingDirectory(function* (dir, profileRoot) {
581604
const harness = createPromptHarness({ profileRoot });
@@ -622,7 +645,7 @@ describe(
622645
// and the person was asked once, and neither was asked again.
623646
expect(harness.fake.prompts).toHaveLength(1);
624647
expect(harness.reviews).toHaveLength(1);
625-
// The save already happened, and a failing run leaves it to hand-edit.
648+
// The file was already written, and a failing run leaves it to hand-edit.
626649
expect(yield* readTextFile(join(dir, "out.md"))).toBe(FAILING_TEST);
627650
});
628651
});
@@ -692,7 +715,7 @@ describe(
692715
expect(yield* exists(join(dir, "out.md"))).toBe(false);
693716
});
694717

695-
// A teardown failure prevents the final validation, the save and the run,
718+
// A teardown failure prevents the final admission, the output file and the run,
696719
// whatever the command document selected.
697720
yield* useWorkingDirectory(function* (dir, profileRoot) {
698721
const harness = createPromptHarness({ profileRoot });

‎packages/cli/tests/prompt.test.ts‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -446,7 +446,7 @@ describe(
446446
expect(harness.executions).toHaveLength(1);
447447
});
448448

449-
// Abort, a turn that failed, and a cancelled command each hand the
449+
// Stopping, a turn that failed, and a cancelled command each hand the
450450
// directory back the same way a success does.
451451
for (const ending of [
452452
{ name: "stop", drive: (harness: PromptHarness) => harness.script({ decision: "Stop" }) },
@@ -558,7 +558,7 @@ describe(
558558
expect(lines[0]).toContain("was made for this conversation and is already gone");
559559
expect(lines[0]).not.toContain("does not validate");
560560
// The Plan was approved and still reached nothing: no admission that
561-
// could have saved it, no save, no execution and so no journal.
561+
// could have delivered it, no output file, no execution and so no journal.
562562
expect(harness.reviews).toHaveLength(1);
563563
expect(yield* exists(join(dir, "out.md"))).toBe(false);
564564
expect(yield* until(readdir(dir))).toEqual([]);
@@ -569,7 +569,7 @@ describe(
569569
// given empty and did not leave empty is preserved and the command fails:
570570
// something wrote there while the conversation ran, and this host
571571
// authorized nothing to. The draft was approved first, so what is being
572-
// observed is a Plan that would otherwise have been saved and run.
572+
// observed is a Plan that would otherwise have been written and run.
573573
yield* useWorkingDirectory(function* (dir, profileRoot) {
574574
const harness = createPromptHarness({ profileRoot });
575575
harness.fake.script({ reply: VALID });
@@ -602,7 +602,7 @@ describe(
602602
expect(yield* exists(String(workdir))).toBe(true);
603603
expect(yield* readTextFile(String(planted))).toBe("not this command's doing\n");
604604

605-
// And nothing after the failure began: no save, and no execution — so no
605+
// And nothing after the failure began: no output file, and no execution — so no
606606
// journal, which only an execution creates.
607607
expect(yield* exists(join(dir, "out.md"))).toBe(false);
608608
expect(yield* until(readdir(dir))).toEqual([]);
@@ -993,7 +993,7 @@ describe(
993993
});
994994
});
995995

996-
it("C9: arbitrary source cannot close the presentation, and abort is authored", function* () {
996+
it("C9: arbitrary source cannot close the presentation, and stopping is authored", function* () {
997997
yield* useWorkingDirectory(function* (dir, profileRoot) {
998998
// A document that holds a fence of its own, and a run of five backticks.
999999
const fenced = [
@@ -1021,7 +1021,7 @@ describe(
10211021
expect(message).toContain(`\n${fenced}\n\`\`\`\`\`\``);
10221022
});
10231023

1024-
// Abort reaches the command document's own `<Fail>`, with the message the
1024+
// Stop reaches the command document's own `<Fail>`, with the message the
10251025
// shipped Markdown wrote. Nothing about it is host policy.
10261026
yield* useWorkingDirectory(function* (dir, profileRoot) {
10271027
const harness = createPromptHarness({ profileRoot });
@@ -1040,7 +1040,7 @@ describe(
10401040
});
10411041

10421042
// Exhaustion is reachable, and it is a different ending. Ten presentations
1043-
// that never validated, the last offering nothing but `abort`, and the
1043+
// that never validated, the last offering nothing but a way out, and the
10441044
// sentence says there was never a Plan to approve rather than that
10451045
// somebody decided to stop.
10461046
yield* useWorkingDirectory(function* (dir, profileRoot) {

‎packages/cli/tests/support/prompt-harness.ts‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -143,7 +143,8 @@ export function createPromptHarness(options: {
143143
* A temporary directory that is also the contextual working directory.
144144
*
145145
* Both, because the two answer different questions: session placement and
146-
* `--save` resolve the contextual one, while a real file has to live somewhere.
146+
* `--output` resolve the contextual one, while a real file has to live
147+
* somewhere.
147148
*/
148149
export function* useWorkingDirectory<T>(
149150
body: (dir: string, profileRoot: string) => Operation<T>,

0 commit comments

Comments
 (0)