Seven steps. One of them refuses, even in a dry run.

The spine

Every effectful command is an instance of the same seven steps. Two of them behave in opposite ways under --dry-run: Refuse runs, Consent does not. Merge them into one guard phase, the obvious simplification, and cwp push prod --dry-run stops refusing. It prints a plan for a write it would never permit.

Pick a command, then set the conditions. The refusal fires under a dry run; only consent, apply and assert stand down.

{
  "effects": [
    { "kind": "transfer", "path": "wp-content/themes/site",
      "writes": "remote", "source": "wp-content/themes/site" },
    { "kind": "transfer", "path": "wp-content/plugins/site",
      "writes": "remote", "source": "wp-content/plugins/site" },
    { "kind": "unknown",
      "reason": "provider cannot predict deletions without a remote listing" }
  ]
}

Ten steps, in the order they run

The spine above is the shape. This is a whole run, including the parts you did not ask for. Two of them are cwp checking itself: after the work, the run compares what it did against what its plan said, and reports when the two disagree.

Every line answers the same question: why here and not somewhere else.

1. 01survey

   Reads the environment and writes nothing. It runs under --dry-run too: a dry run prints what it found, not a guess.

2. 02refuse

   The guards. They run before the consent and before the write: a refused run has no side effects and needs no tidy-up.

   A refusal stops here, and cwp writes it into the environment's log.

3. 03consent

   You are asked, with the plan's own words: the pages that would be overwritten, the classes that would go.

   --dry-run stops here. cwp prints the plan. The refusals have already run, and cwp has neither asked nor written anything.

4. 04restore point

   After you agree: a run you declined backs nothing up. Before the write: there is a way back.

5. 05tree snapshot

   The same idea for your repository: a dangling commit the run names. A pull that overwrote local work has a way back.

6. 06apply

   The work, one declared step at a time. A step the plan calls fatal stops the run; the rest warn and it carries on.

7. 07check

   The run against its own plan: anything written that was not declared, and anything declared that was not done.

8. 08assert

   Post-conditions about the world. A pull that imported a database asserts that the mail guard intercepts outgoing mail.

9. 09record

   What happened, into the environment's log, where cwp log reads it back weeks later.

10. 10commit

    After the post-conditions held. A commit of a state that failed its own checks would make the failure permanent.

The plan is what the guards read

A plan is not a preview of the run. Each entry says where it writes, whether a failure there stops everything, what committed file it can be reproduced from, and whether it destroys anything. The first of those decides whether a protected environment refuses and whether cwp takes a restore point.

So a write nobody declared is a write outside both. It has happened: a composite declared that it wrote nowhere while its parts wrote to production, and nothing refused it or backed it up. The run now compares itself against its plan at the one place every subprocess passes through, and names the commands when they disagree.

One command, six operations, one refusal

cwp pull is not six runs in a row. Six operations in sequence would ask six times and take six restore points, and a failure at the fourth would leave an environment matching no commit at all.

The composite carries every sub-plan's effects into its own, so the ladder sees the whole run.

Two seams

Everything host-specific sits behind one interface and everything builder-specific behind another. No operation knows which of them it is talking to: cwp push against a Cloudron app, a plain VPS over SSH and a container on your own machine is the same code.

What differs is what each host can promise. The guard ladder reads that promise rather than assuming it. A host that cannot take a restore point refuses the write instead of skipping the step.

Why verification happens per effect

Apply is a fold: cwp verifies each effect as it lands, not in a phase afterwards. Moving that verification out is the obvious simplification, and it is worse than doing nothing. A push that fails cannot be repaired by running it again.

Three transfers. The second one fails its digest.

The layers

Five directories with one rule between them, and the rule is the half people get backwards: the layering test forbids upward imports only. Sibling imports are composition: pull uses scrub, doctor uses its check modules. A rule against those invents a shared/ directory within a month.

The shapes that are not this one

Naming the exceptions keeps the spine from eroding into an escape hatch. All three are first-class types, not opt-outs.

Conduits

cwp wp, cwp shell, cwp tail. They announce their target, hand over, and forward the exit code. stdio is inherited, so the output you came for never enters the journal. Capturing it would break wp shell and strip WP-CLI's colour. No --json, and unguarded by design: cwp cannot classify WP-CLI subcommands, and a reflexive --force on wp plugin list is worse than no guard at all.

Surveys

cwp doctor, status, projects. Survey → Report, and the result is a list of findings. Nothing to refuse, nothing to consent to, nothing to apply.

init, outside all three

Its survey target is an answer nobody has given yet: it asks for the app, then probes it. Interleaving Survey and Plan is the pipeline with its guarantee removed, so init keeps its own shape. Conversational input first, then a pure scaffold planner that returns created, skipped and repaired before it writes anything.