Add prose write run option

[rawwerks]

Summary

• Add prose write --out <path> so shell users can ask the authoring path to write generated source into an explicit repository-relative target.
• Add --apply for write-only authoring and --run for write-then-run authoring.
• Keep plain prose write "..." unchanged: source-package-only, no filesystem writes.
• Treat --run as a host-adapter macro: the CLI invokes authoring with apply permission, then starts an ordinary prose run <generated-root> only if authoring succeeds.
• Keep std/ops/prose-author non-operational for follow-up execution through post_apply_action: host-will-run-root; it must not run, simulate, publish receipts, or perform optional memory/giving-back side effects.
• For Codex SDK runs, default explicit write/apply authoring to workspace-write when no sandbox mode is configured, while preserving explicit caller sandbox settings.
• Add parser, forwarding, contract, and router tests, including the Cloudflare vulnerability-detection example that motivated the change.

Use Case / Run Evidence

The motivating workflow was:

prose write "a vulnerability detection system that uses lessons from https://blog.cloudflare.com/cyber-frontier-models/"

That produced a useful source package in terminal output, but the user then had to copy/paste it into files before running it. The desired shell workflow is:

prose write --out src/vulnerability-detection --run "a vulnerability detection system that uses lessons from https://blog.cloudflare.com/cyber-frontier-models/"

The branch was tested against that exact example in tmux with the real Codex harness. The live proof wrote the requested package under src/vulnerability-detection in scratch, using the repo copy of skills/open-prose and a process-local Node 22 path.

Important result: the live proof is not yet a green end-to-end demo. The authoring phase recovered from intermediate validation-command failures and wrote valid files, but the Codex harness still exited nonzero (exit=2), so the host-adapter follow-up prose run <generated-root> did not start. Earlier attempts also exposed local-environment issues: the ambient Bun node shim and the globally installed open-prose skill (0.13.1) can change the live proof behavior. Those artifacts are intentionally uncommitted.

Design Boundary

The split is:

• CLI parser/forwarder: owns deterministic shell flags, path validation, and supported host-adapter macros.
• std/ops/prose-author: owns the authoring contract, lint/repair loop, and filesystem-write permission semantics.
• OpenProse skill/docs: own command routing language and host capability rules.
• Ordinary prose run / VM semantics own execution of the generated root.

prose write --run is not pushed into prose-author. The CLI is one host adapter that supports the macro by forwarding two top-level operations. Hosts that cannot do that must reject prose write --run before authoring and must not pass the macro into prose-author.

The chaining/pattern material reinforces this boundary: runtime chaining belongs to VM/Forme/ProseScript execution, not source authoring. That points the future --test-iterations work toward a bounded host macro as well: write/apply, ordinary prose test, repair authoring pass, repeat.

Review Follow-ups

Addressed from independent review and design discussion:

• Added an abort check between the write harness call and the follow-up run so a cancelled command does not launch the second step.
• Rejected dotted non-.prose.md output targets like src/foo.txt instead of silently treating them as folders.
• Documented that --out path checks are CLI validation plus an authoring-contract boundary, not a hard filesystem sandbox.
• Documented that --run implies apply permission.
• Replaced operational run_after_write: host-managed prompt semantics with non-operational post_apply_action: host-will-run-root.
• Added tests that pin unsupported in-session routers to reject the macro before authoring.
• Added a side-effect guardrail after tmux evidence showed authoring could otherwise attempt optional memory/mycelium note writes.

Examples

Package-only, unchanged:

prose write "draft a release readiness responsibility"

Write files but do not run:

prose write --out src/release-readiness --apply "draft a release readiness responsibility"

Write files and immediately run the generated root:

prose write --out src/release-readiness --run "draft a release readiness responsibility"

Testing

Passed locally on 757379a:

pnpm --filter @openprose/prose-cli test -- tests/prose/prose-author-contract.test.ts tests/skills/open-prose.test.ts tests/prose/command-model.test.ts tests/cli/cli.test.ts
pnpm --filter @openprose/prose-cli build
pnpm --filter @openprose/prose-cli typecheck
git diff --check

Safe-push security review approved the branch diff and pushed feature/prose-write-run.

GitHub Actions are green on commit 757379a: Node 20/22 checks, release tarball smoke, npm package smoke, CodeQL, dependency audit, plugin manifest validation, codex/claude SDK smoke, and the OpenProse smoke matrix all pass.

Known issue observed during broader local preflight:

pnpm --filter @openprose/prose-cli test

failed locally in tests/prose/crash-window-replay.test.ts with a timeout. The branch does not modify that test or the serve/crash-window replay path; this remains a disclosed residual outside this feature.

Residual Risk / Follow-ups

• The generated vulnerability-detection example and run artifacts are intentionally uncommitted.
• The exact Cloudflare tmux proof is not green yet because recovered authoring validation-command failures still produce a nonzero harness exit, preventing the follow-up run. This PR remains draft while we decide whether that belongs in PR Add prose write run option #90 or a follow-up harness-hardening PR.
• The sister --test-iterations branch has started in .scratch/worktrees/prose-write-test-iterations-v2 and should reuse this host-adapter boundary.

[irl-dan]

Add --apply for write-only authoring and --run for write-then-run authoring.

--apply is a confusing term in this setting

I prefer --run is default off if not specified and on if specified (alt --run=false, --run=true)

---

This feels like a big architectural leap/decision:

Update the prose-author contract and OpenProse routing docs so --run is host-managed: the authoring step writes files, then the CLI invokes prose run .

The problem with this is that now prose write --run "..." does not work if you're working inside a session.

My expectation would be that prose write --run works inside the session as well as on the outside.

I think one of the tenets we should specify somewhere (if not) that has been an internal guide for me is that prose x should work inside a session, and the CLI is more of a convenience wrapper, rather than a control-flow decider.

Open to more discussion/pushback if I'm missing something here. But if we had CLI-level logic, I'd want a sharper delineation, rather than burying it in a single command option (which looks like all the other options).

[rawwerks]

Update after another implementation/audit pass:

• Pushed 757379a on feature/prose-write-run; PR Add prose write run option #90 is mergeable clean and all GitHub checks are green.
• Addressed the review follow-ups in this branch: abort check between author/run, stricter --out validation, README wording for the target-path boundary, host-adapter wording for --run, and a no-optional-side-effects guardrail for forwarded write authoring.
• Independent audit found no blocking PR Add prose write run option #90 issue. The exact Cloudflare live proof still exposes a separate Codex harness status problem: authoring can recover from an intermediate failed validation command and write valid files, but the harness exits nonzero, so the CLI correctly does not start the follow-up prose run. I am leaving that documented as residual rather than making --run proceed after nonzero authoring.
• I am preparing the sister --test-iterations PR stacked on this branch so the two designs can learn from each other without mixing the features.

[rawwerks]

Applied the low-risk polish from the surrogate review in 5ff2401:

• writeEnabledEnv now respects only the forwarded env instead of also peeking at ambient process.env, with a regression test for filtered env behavior.
• Added command-model coverage for prose write --out <path> ... without --apply/--run, pinning the current source-package-only prompt shape.

Focused tests, typecheck, build, and git diff --check passed locally. GitHub checks are green on the new head.