Chapter 4: The Command Surface¶

A Thin Layer Over the Tools You Already Drive¶

1. Why the Repository Needs a Command Surface¶

The repository from the last chapter can hold the rules and still not run them. A rule that lives in a document is read by whoever chooses to read it, and enforced when someone remembers. Engineering work is defined by repetition, and every repeated operation has two halves: the mechanical execution of the change, and the enforcement of the rules that govern it.

Specialised tools handle the mechanics well — version control, the cluster, the cloud — and none of them knows your rules. A gate must pass before anything ships. A release needs a clean tree. Three components ship in an order. A person must approve. None of that lives in the tool. It lives in memory, becomes a checklist, then a habit, then the single point of failure on the day the person who knows the sequence is away.

A command surface is how that policy gets an execution path. It is not a bag of shortcuts, and it is not a place to reimplement a vendor. It is a software system in its own right, and it should be held to the standards the rest of the estate is held to: clear boundaries, one source of truth, small parts, and tests that fail when the thing they guard breaks.

Structured that way, the surface is where the three structures stop being advice. The workflow structure becomes a gate that runs; the engineering structure becomes a boundary the verb enforces; the prompt structure becomes the policy the surface refuses to break. A person, an agent and a pipeline run the same sequence, and none of them has to remember it.

The outcome is the one every Orchestrator is after. When policy lives in the interface, the effective way to work becomes the efficient way to work: the engineer stops spending attention on flags and ordering, and the surface stops letting a step be skipped. That is speed without giving up governance.

What follows is about designing that layer — telling a command that carries policy from one that duplicates a tool, keeping the surface small and learnable, and putting each part where it can be checked.

The rule this chapter defends: use what exists, curate what you use, and build only what nothing else can do.

🎯 What You'll Learn¶

The purpose of the command surface — how a structured interface bridges raw execution engines and the policy they cannot carry
The gap test — the five questions that decide whether a command deserves to exist as code, or should be left to the vendor command
The structure of a learnable surface — how discovery, authority and refusal keep a command surface honest and machine-readable
The commands worth knowing — the version control and workflow verbs that carry discipline

The Words This Chapter Uses¶

Seven words do most of the work, and each means one thing:

Term	What it means here	What it is not
estate	everything one person operates: the repositories, services and hosts — the whole surface	not the gates, not the tooling, not one repository
command surface	the text interface — noun, verb, arguments — that a person and a machine share	not the client, not a log
view	whatever renders the surface's state: a dashboard, a console, a terminal — the view of the book's rule / mechanism / view	never the owner of behaviour
verb	one operation, declared in the registry	not a wrapper; not a vendor command
wrapper	a verb that stands for a vendor invocation — policy or effectiveness	not a reimplementation
registry	the one table that declares every verb	not help, not a completion list
refusal	a designed non-action: a named reason and exit 2	not a failure (exit 1)

After its first use, surface means command surface and nothing else. The rendering side is always the view — so a sentence that says "the surface shows" is wrong, and "the view shows" is right.

One footnote. The estate's CLI also has a client noun, meaning an application registered with the identity provider. It has nothing to do with a view — which is why this chapter does not use the word.

The Two Surfaces, One Question¶

The terminal is the view you already have, and it shows state badly: state scrolls away, a week of runs is not a slope, and a command answers the question you asked rather than the one you should have asked. The view's contribution is legibility — a verdict as one row, a trend as a line, the action beside the state that made it matter.

None of that requires the view to own behaviour. A view is a client of the command surface, not a peer of it — in the client–server sense: a peer negotiates, a client calls. And only the command surface is shared by a person and a machine: the line a person types is the line an agent composes, and its output is the text an agent reads back.

The failure mode is a view built for its own sake: a page per verb, a button that reimplements the operation behind it, a status colour computed by the screen. Each is a second implementation of something one call away — correct when written, wrong within a quarter, invisible, because a screen cannot disagree with itself.

✅ What to Check¶

Name three things you do that no vendor command covers. If you cannot, you do not need a command surface yet.
Name one command you have that is just a shorter git verb. That is the first thing to delete.

2. The Gap Test¶

A command surface grows by accident: someone needs a shortcut, adds a verb, and the surface becomes a second vocabulary with no owner. The gap test is how a surface stays small enough to trust.

#	Question	If yes	If no
1	Does a vendor command already do it?	continue to 2 — not an automatic no	candidate
2	Does it span more than one repository, tool or vendor?	candidate — no vendor owns the whole	continue
3	Does it carry policy the vendor cannot know — gates, staged-only, review, approval?	candidate — the policy is yours	continue
4	Does it operate on an estate object with no command of its own?	candidate — nothing else can	continue
5	Is it frequent, long to type, and easy to get wrong — with a short equivalent?	candidate — effectiveness is a reason	documentation, not a verb

The counter-test, restated. A verb that is one vendor call needs two of three: high frequency, a long or error-prone invocation, and a short unambiguous equivalent. Miss one and it is a line in the curated list — write that line, not the verb.

Prefer an argument to a verb. orch log N=3 is one verb with an argument, not orch log3, orch log5, orch log10 — and the surface grows in verbs, which is the expensive axis.

And the test is whether you would miss it. If the long form is typed weekly and you still look up the flags, the wrapper has earned its row. If you would not notice it gone, it is a line in the curated list. Nothing keeps a wrapper alive but use.

Four Reasons a Verb Exists¶

Reason	What it means	Example
It carries policy the vendor cannot know	the operation is a vendor verb plus a rule you own	`orch commit` runs the repository's staged gate, then commits only the staged index, with a message built from the diff
It spans more than one tool or repository	no vendor owns the whole operation	`orch sync` fetches and rebases in one step; `orch repo clone-all` clones every repository the caller can reach
It operates on an estate object with no CLI	the Law, the Map, runners, clients, workflows	`orch runner status`, `orch law check`, `orch client list`
It is more effective than the raw command	high frequency, long invocation, one short equivalent	`orch log N=3` instead of `git log --oneline --graph -n 3` typed forty times a week

The fourth reason is the one teams feel first and defend last, so it needs a standard rather than a preference: frequency × recall cost × error cost. A command typed daily with four flags whose order you have to remember is a candidate. A command typed monthly is not, however long it is.

And a wrapper must teach the command it wraps: its help prints the vendor invocation it stands for, so a reader can use the raw command when the wrapper is unavailable, and so the wrapper cannot quietly diverge into a reimplementation.

The Test, Applied¶

Candidate	Passes on	Verdict
`orch commit`	policy: the staged gate, staged-only, a message from the diff	build
`orch repo clone-all`	spans repositories, reads the manifest	build
`orch runner status`	estate object: runners	build
`orch log N=3`	effectiveness: the raw form is `git log --oneline --graph -n 3`, typed daily	build — if the frequency is real
a one-off `git log` with a flag you use twice a year	nothing	do not build; curate the flags instead
a "status" that re-renders `git status`	nothing	delete it

The three that pass are the whole reason the surface exists. The two that fail are the reason it stays small.

✅ What to Check¶

Take your five most-used commands. Run each through the four questions. How many survive?
Find one command that is a wrapper with no policy. What would break if you deleted it?

3. The Structure¶

One Grammar¶

Every command in the surface has the same shape:

<namespace or nothing> <verb> [KEY=VALUE …] [--flags]
orch   repo    clone  REPO=portal
orch   status
gh   pr      create --fill

The grammar is not decoration. A stable grammar means a person can guess, a machine can compose, and help can be generated from one table.

The Registry¶

One table declares every verb. Seven columns, one row per verb:

noun | verb | state | needs_repo | script | mode | help

Column	Why it exists
noun	the object, or `-` for a top-level verb
verb	the operation, one per row
state	shipped or planned — so a planned verb is visibly not a capability
needs_repo	whether the caller's repository is resolved first
script	the one implementation
mode	how arguments are passed
help	the sentence help renders

Everything downstream reads this table: dispatch, help, completion, the view's action inventory, and the conformance gate. That is the chapter's first structural claim — one table, many renderings — and the reason §6's checkpoints exist.

Three Properties of an Instrument¶

Property	The question it answers	What fails without it
Discovery	What can this surface do, from here, right now?	the reader learns it from a stale wiki
Authority	What does it treat as true?	two sources of truth: a file and a running system
Refusal	What will it not do, and does it say so?	a guess — the surface acts, and the damage is done

Discovery is the surface describing itself for the code in front of you; authority is the decision about which fact wins; refusal is a designed non-action, with a reason and an exit code.

🎭 Key Insight — the three are one decision seen three ways. A surface whose vocabulary is stored once can generate its discovery; one that knows which fact is authoritative can refuse an input that would need a guess; and one that refuses can be driven by a machine, because a non-zero exit is information rather than a mess.

The exit codes are part of the contract. Zero for success, one for failure, two for a refusal — bad input, refused by name. A person and an agent branch on the same number, which is why a refusal must never be reported as a failure: the two need different responses. And a run that has not finished is not a success; a "still running" state that returns zero is a green nobody measured.

A mutation previews before it writes. A mutating verb prints its resolved plan — the ref, the inputs, the exact thing that would happen — and changes nothing until told to. The preview shows the engine's own resolution, not the view's summary of it.

The Ownership Test¶

One test settles which side owns the behaviour, and it runs in both directions. Call it the deletion test.

Delete the view. If a capability disappears, the view owned behaviour. If only legibility goes — the trend, the glance, the colour — it was a view.

Delete the command surface. If the view still works, it was a peer with its own copy. If everything that mattered stops — gates, dispatch, mutation — the engine was where the work lived.

The Ways a Surface Lies¶

The three properties have seven known failure modes, and the rest of this chapter is designed around them:

#	Mode	Property lost	What it looks like	The check
1	a second source of truth	discovery	the same fact written twice, and the two disagree	delete one; does anything break?
2	duplicated behaviour	discovery	two implementations of one operation, drifting	the deletion test, run in both directions
3	a wrong-direction claim	authority	"not read" reported as a verdict	is every unmeasured state named as unmeasured?
4	substring classification	authority	a name test standing in for an identity test	does the match use an id, or a fragment of a name?
5	a silent skip	refusal	a check reporting success about input it never saw	feed it nothing; does it pass?
6	unparsed input	refusal	accepted now, parsed later, where you cannot test it	is every argument parsed before work starts?
7	under-scope by name	refusal	the name promises more than the body runs	compare the name to the operations it performs

Each is structural: the code is sincere, the review passed, and the output is wrong. The fix is never "be more careful" — it is a change to where the fact lives or what the surface accepts. §6's checkpoints exist because each one happened.

The fourth is worth one case. A bootstrap command decided whether a file was a generated stub by searching its text for a filename. The rules file contained that string — it is the file that says read the rules — so the command classified the rules file as a stub, replaced it with a redirect, and reported success. 143 lines became 17, and nothing objected, because the only check was the one that had just misfired. The guard that came out of it is structural identity: compare the resolved path, never the text, and refuse when the target is the file you are installing.

✅ What to Check¶

Is there one table, and does every rendering read it?
Does a mutating verb print a plan before it acts, and refuse bad input by name with exit 2?
Take the last wrong output you saw from a tool. Which of the three properties failed?

4. The Commands Worth Knowing — Version Control¶

This is the list a reader should learn. Not every flag — the vendor's page has those — but the commands that change the outcome of a normal week.

What you are doing	The command	What it buys you
stage deliberately	`git add -p`	partial staging is how a commit becomes reviewable
read what you are about to commit	`git diff --staged`	the staged index is the change; the working tree is still a discussion
write a message that explains why	`orch commit`	the estate's policy: staged gate first, staged-only commit, message from the diff
see what changed on a branch	`git log --oneline --graph @{u}..`	the shape of the change without the noise
find when a line appeared	`git log -S"<text>" --oneline`	searches the diff, not the message
find the change that broke it	`git bisect run <script>`	a bisect is only fast when the test is scripted
see why a line is here	`git blame -w -C`	`-C` follows moved code — the difference between blame and noise
recover a lost commit	`git reflog`	the last resort that is not a resort at all
rehearse without disturbing the tree	`git worktree add`	a second checkout, no stashing
publish a version	`orch release`	the estate's policy: gate, clean tree, signed tag, push the tag only

Two Kinds of Wrapper, and the Line Between Them¶

The estate's command surface holds a small set of verbs over git, and they are not the same kind of thing. Two carry policy; six remove a decision you would otherwise get wrong.

Policy wrappers — orch commit and orch release. Commit is git commit plus three rules: the repository's staged gate must pass, only the staged index is committed, and the message is built from the diff. Release is policy too: gate, clean tree, signed tag, push the tag only. Neither rule belongs to git, and git tag cannot know that a tag here means this shipped.

Effectiveness wrappers — orch log, orch status, orch diff-staged, orch last, orch branches, orch unstage. Each stands for a long, frequent, easy-to-misremember invocation, and each prints the raw command it stands for.

The wrapper	What it stands for	Why it earns a row
`orch log N=3`	`git log --oneline --graph -n 3`	typed constantly; four flags to recall
`orch status`	`git status` plus the suggested next action	the most typed command, and the advice is the point
`orch diff-staged`	`git diff --staged`	one mental step removed from the wrong diff
`orch unstage`	`git restore --staged`	the flag nobody remembers

The line between them is evidential, not moral — the two rules in §2 bound this table: an argument beats a verb, and nothing keeps a wrapper alive but use. A policy wrapper exists because the rule cannot live in git. An effectiveness wrapper exists because the invocation is long, frequent and error-prone — and if that stops being true, the wrapper should be deleted rather than defended.

Both kinds keep one promise: the wrapper teaches the command it wraps. Help prints the raw invocation, so the surface is never a dead end: the raw command stays readable and usable on its own.

✅ What to Check¶

Which of the ten do you actually use? The rest are the ones to learn.
For each estate command, name the rules it adds. A wrapper with no rules is a shortcut, and shortcuts do not earn a surface.

5. The Commands Worth Knowing — Workflow¶

Version control records intent. Workflow decides whether it may land — and the commands below are the ones that make that decision legible rather than something you hope about.

What you are doing	The command	What it buys you
open the change with its intent	`gh pr create --fill`	the body is built from the commits — a claim a reviewer can check
know whether it may land	`gh pr checks --watch`	the verdict, live, instead of refreshing a page
read a failed run	`gh run view --log-failed`	the failing step, not the whole log
retry only what failed	`gh run rerun --failed`	no full rebuild to learn one thing
trigger a workflow from the terminal	`gh workflow run`	the same trigger the UI uses, in a script
dispatch with the estate's preflight	`orch workflow run`	parses the workflow before dispatch, so a broken file fails here rather than on the runner
see the estate's declared workflows	`orch workflow list`	the inventory, from the registry, not a wiki

The Habit Behind the List¶

Two of these are habits, not commands.

Read the failing step, not the log. --log-failed exists because most of a log is irrelevant to the failure; reading the wrong part is how a 30-second diagnosis becomes an hour.

Rerun only what failed. A full rerun hides whether the failure was flaky and costs the pipeline again. --failed is the honest retry.

And one boundary: the gate's verdict is the authority, not the pipeline's colour. A workflow that finished is not a workflow that passed; a check that never ran is not a check that passed. That distinction is the subject of §7.

Mechanism and View¶

The runner, the queue and the log viewer are mechanisms and views — adopt them, never rebuild them. What you own is the declaration: which workflows exist, what triggers them, what each one must prove. That declaration lives in the repository and is read by orch workflow list; the pipeline renders it.

✅ What to Check¶

Does your surface tell you whether the change may land, or only that a job finished?
Can you read a failure without opening a browser?

6. The Build Order¶

💰 Cost Check: a verb you build costs a row, an implementation, a test and a help page — and every vendor change it wraps is now your problem too. A command you learn costs an afternoon and keeps paying. The expensive surface is the one that copied a vendor verb: it saves a keystroke and adds a second thing to maintain, and the second thing is the one that drifts.

The order is not theoretical. It is the order this estate's surface had to be rebuilt in after the failures the appendix records, and each stage sits where it does because the alternative produces one of them.

flowchart LR
    R["1 · gap list<br/>what deserves a verb"] --> G["2 · registry<br/>one table"]
    G --> V["3 · verbs<br/>one operation each"]
    V --> H["4 · help<br/>rendered, never written"]
    H --> D["5 · view<br/>calls the verbs"]
    D --> C["6 · guard<br/>conformance gate"]

Step 1 — The Gap List¶

Before a line of code: the operations that pass the gap test, and the ones that will stay documentation. Checkpoint: every candidate has a reason from the four questions, and every refusal names the vendor command it defers to.

Step 2 — The Registry¶

One table, seven columns, a row per verb. Everything downstream reads it.

Checkpoint: every row resolves — a shipped row has an implementation that exists and is executable, no verb is declared twice, a planned row says so. This is a gate, not a review.

Step 3 — The Verbs¶

Each verb is one operation and owns three things: the work, the guard and the intent. The guard belongs inside the operation — a guard in the caller is a guard on one surface; a guard in the operation is a guard on every surface that will ever exist.

Checkpoint: every shipped verb refuses an unknown argument with a named reason and exit 2, and every mutating verb prints its resolved plan without acting. Prove both with a fixture per verb, not with a sample.

Step 4 — Help¶

Help is a rendering of the table, never a document beside it. Arguments, examples and the verb's intent are composed from the registry row and the implementation's own header, so help --all describes the surface that exists.

Checkpoint: help renders every declared verb and nothing undeclared. A missing verb is an undocumented capability; an extra verb is a page for something nobody built. This estate's conformance gate checks both directions — which is how it found two rows it had been skipping.

Step 5 — The Client¶

The view comes fifth because it can only call what exists. Its job is legibility plus a bounded set of actions, each naming the operation it runs.

Checkpoint: every view action resolves to an operation that exists, and deleting the view removes only legibility. Run the deletion test as a gate, not a thought experiment.

Step 6 — The Guard¶

The conformance gate comes last because it judges what exists — and because it must be able to fail. It asserts that every declared verb is implemented, unique, documented and dispatchable, that no retired name survives in the live instructions, and that the advertised and enforced surfaces are the same set.

Checkpoint: the guard fails on a deliberately planted defect, and the failure is recorded.

What Breaks If You Reorder It¶

Move	What breaks	The symptom you see first
Help before the registry	help becomes the definition; every verb edits two places	a documented verb nobody built
View before the verbs	the view becomes the first implementation	a terminal that cannot do what the button does
Guard before the verbs	the gate asserts things about a surface that does not exist	a green run over an empty set
Verbs before the registry	the verb list lives in the dispatcher and in help	a verb no help page mentions
A guard that never judges the view	view actions have no inventory to resolve against	a button whose command was renamed last month

The Checkpoint Habit¶

A checkpoint is not a milestone; it is a measurement that can fail, taken when a step claims to be done. All six share a shape: state a set, compute what the code actually has, compare, refuse on a difference, record the result. That shape is what lets a stage be finished rather than merely written.

✅ What to Check¶

Count your registry rows, then ask the surface how many verbs it has. A difference is step two, unfinished.
Ask one shipped verb to refuse an unknown argument and one to print its plan, and ask the view to name the operation each action resolves to. If any cannot, that step is unfinished.

7. Seeing Widely, Acting Narrowly¶

Why the Two Jobs Split Apart¶

For years the two jobs lived apart. A dashboard read state: charts, colours, a number per panel — and it could not touch anything, so nobody had to think about its authority. A terminal console acted: you typed a command and the system changed, and the only thing between your typo and production was your own attention.

Operator consoles merged the two: one surface that reports and acts, with buttons beside the numbers. That is convenient, and it creates a question the old split never had to ask — when a screen can both show and do, what stops the doing from being as casual as the showing?

The three properties from §3 make the answer unavoidable. Discovery says the console must describe what it can do for the code in front of you; authority says it must decide which fact wins instead of rendering a second one; refusal says it must decline what it cannot resolve. A surface that does those three things honestly can be trusted with a button. One that does not can be trusted with nothing.

So this section is the console's half of §3: what the three properties demand when the rendering side is also the side with hands.

A console that shows you everything and changes nothing is a perfectly good console. A console that can also change things is a different instrument with a different risk, so it needs one rule: show as much as you like; do only what a person asked for.

The Two Jobs Carry Opposite Risks¶

	Showing — reading state	Acting — changing state
What it is	what exists, what passed, what failed, which step, how old the fact is	dispatching a deploy, provisioning, deleting, staging a commit, bypassing a gate
If you widen it	nothing breaks; the worst case is a crowded screen	authority grows, and every action is a decision nobody makes any more, because it already happened
If it is wrong	the reader learns something false and asks a question	the system has changed, and the correction is a second action
The safe direction	generous	narrow, named, confirmed

That asymmetry is the whole section. Showing more is cheap and reversible; acting more is neither.

Three Rules¶

1 · Show everything you can read — and say when you cannot. Three outcomes, never two: pass, fail, not-verified. A missing row is unknown; a verdict about another commit is history; a check that could not read is not-verified; a gate that has not run is not-run. A green colour in place of any of these is the lie this rule forbids.

2 · Act only through a verb that already exists. The view holds no behaviour. Every control resolves to a command, so the guard that command carries applies whoever pressed it. A button that reimplements the operation is a second implementation, and §3's deletion test finds it.

3 · Stop at ambiguity; never pick. If the input can be read two ways, the surface names the candidates and exits non-zero. It does not choose the likeliest, retry with a correction, or map a renamed verb to whatever looks closest. A choice made by the surface is invisible in the invocation and wrong the day the repository changes.

What Requires a Person¶

The console shows	The action that needs a person	Why	Enforced by
state — what exists, in which environment	dispatch — a live deploy or provisioning run	it mutates a provider; the decision is the Orchestrator's	convention — no hook yet
the verdict — pass, fail, not-verified, not-run	staging and committing	the ship boundary is a human signature	staged gate and review
the failing step — job, step, error excerpt	bypassing a gate	a gate is the promise; bypassing it is a silent renegotiation	the gate itself
the age and subject of each fact	choosing between two interpretations	the choice is invisible in the invocation and wrong later	refusal by name, exit 2
the refusal — its reason and exit code	retrying a failed mutation without a new decision	the second attempt is a new decision wearing the first one's clothes	convention — no hook yet

Why This Lives in the Verb¶

A view that can dispatch holds authority. Authority is not a property of a widget; it is the power of the operation behind it. So the rule is enforced where the operation lives:

A mutating verb prints its resolved plan and changes nothing until told to. The plan is the engine's own resolution — the ref, the inputs, the exact operation — and the view shows that plan, not a summary of it. The person confirms a line the engine would actually run.

That is why "the console must not own behaviour" is a live rule rather than a truism: a console can act, and the only thing standing between the button and production is that the button calls a verb that refuses, previews, and records.

The Reader May Be an Agent¶

Every rule above was written for a person at a screen, and each binds tighter when the reader is a machine.

An agent reads the console and acts through it, at a speed no one reviews. If the console shows a colour where it should say not-verified, the agent proceeds on a fact nobody measured. If the console picks between two interpretations, the agent inherits the choice and never sees that a choice was made. If the console can dispatch without a preview, the agent's first attempt is already in production.

That is the background to this section's shape: the console is the agent's eyes and its hands, so the showing side must be honest about what it does not know, and the acting side must be narrow enough that a wrong step is one step, visible and reversible.

The Honest Limit¶

Two of the five boundaries above are enforced by convention rather than by a mechanism: dispatch and retrying without a new decision. The command refuses nothing when an agent runs it; the rule holds because the agent reads the Law and the human reviews the tree.

Stated plainly, because a boundary that is only prose is a future version of under-scope by name: the surface's name promises a control its body does not enforce. The fix is already named in the table — a hook that refuses the action regardless of who is typing.

✅ What to Check¶

List every control in the console and mark each show or act. For every act, name the verb it calls — an act with no verb is a second implementation.
Ask what the console returns when it cannot read. If the answer is a colour rather than unknown or not-verified, rule 1 is not implemented.
Pick an ambiguous input and type it. Does the surface name the candidates and refuse, or does it choose?

8. Build the Workbench¶

The build order is the argument. This is the build: six artefacts, each with the shape that makes it checkable. Keep the shapes; put your own operations in the rows.

Artefacts¶

Artefact	What it is for	Where it lives
gap list	which operations deserve a verb, and which defer to a vendor command	`docs/gaps.md`
verb registry	the only list of what the surface can do	`cli/registry.tsv`, one row per verb
argument contract	what each verb advertises and what it enforces	inside each verb's help, derived from the registry
help renderer	renders the registry — never written by hand	one script, one output
curated list	the vendor commands worth knowing, and what each buys	`docs/commands.md`
conformance guard	proves the surface is whole, and fails on a planted defect	the gate

The registry, as a shape — seven columns, nothing else:

# cli/registry.tsv — the only membership source
noun    verb    state   needs_repo  script  mode    help
-   status  shipped 1   libexec/status.sh   kv  what is staged, and the suggested next action
-   commit  shipped 1   libexec/commit.sh   kv  staged gate, then commit only the staged index
repo    clone-all   shipped 0   libexec/ws-run.sh   kv  clone every repository you can access

The curated list, as a shape — one row per command, and the reason it earns its place:

# docs/commands.md
task            command             what it buys
stage deliberately  git add -p          partial staging is how a commit becomes reviewable
read the change     git diff --staged       the index is the change; the tree is a discussion
find the regression git bisect run <script>     a bisect is only fast when the test is scripted
may this land?      gh pr checks --watch        the verdict, live, instead of a refresh

Decisions¶

Choice	Default	What changes if you choose otherwise
build or curate	curate first; build only what passes the gap test	a surface that is a second vocabulary
one verb per operation	yes	two verbs for one operation produce two behaviours that drift
the registry as the only list	yes	a completion script or a doc that keeps its own list is a second source of truth
help rendered from the registry	yes	hand-written help goes stale on the first added verb
arguments advertised by name, exit 2 for a refusal	yes	a caller cannot tell "fix the input" from "try again"
mutations previewed by default	yes, write only on an explicit flag	a preview that writes is a trap

✅ Checks¶

Every registry row resolves: an implementation exists, is executable and is dispatched.
An unknown argument is refused by name, with a fix line and exit 2.
Help renders every declared verb and nothing undeclared.
Every view action resolves to a verb that exists; deleting the view removes no behaviour.
The guard fails on a planted defect (a row with no implementation, a verb with no test).
Every effectiveness wrapper prints the raw command it stands for.
No two verbs differ only by an argument that could carry the difference.

Sequence¶

Gap list — run every candidate through the four questions. Checkpoint: each refusal names the vendor command it defers to.
Registry — one table, seven columns. Checkpoint: every row resolves.
Verbs — one operation each, refusing unknown arguments by name. Checkpoint: refusal by name, and a plan before any write.
Help — rendered from the table. Checkpoint: help and the table agree in both directions.
Client — one action per operation, holding no behaviour. Checkpoint: the deletion test removes only the surface.
Guard — the conformance gate, with a planted defect. Checkpoint: the guard fails on that defect, and the failure is recorded.

Done When¶

The gap list exists, and every verb on the surface can be traced to one of the four questions.
The registry is the only list of what the surface can do.
A wrong argument is refused by name, with a fix line and exit 2.
Deleting the view leaves every behaviour intact.

9. 🔑 Chapter Summary¶

Use the command surface you already drive; build only the layer that carries your policy.

The vendor tools win their own domains. A surface that reimplements one is a liability.
A verb exists for one of four reasons: it carries policy, it spans tools, it serves an estate object, or it measurably beats typing the raw command. Otherwise it is documentation.
One grammar, three properties — discovery, authority, refusal — and seven known ways to lose them, each with a checkpoint.
Learn the commands that carry discipline: partial staging, the staged diff, a message that explains why, -S and bisect run, --log-failed and --failed. That list is the chapter's practical half.
Build last, and build small: most of what the surface offers should be a vendor command you learned to use well. The verbs you write are the few that carry policy or span tools — and each one costs a row, an implementation, a test and a help page.