docs: auto-approve tier contract — judgment-based restatement, framework-neutral done/new

[zheng-weihao]

Summary

Restates the auto-approve tier contract by where the judgment lives instead of by side effect, and converges the docs on two smaller truths found during the audit. No hook behavior change — the case list in hooks/auto-approve.sh and SAFE_SUBCOMMANDS in plugin.ts are unchanged; comments, tests and docs now match what the hooks already did.

The four tiers

Tier	Subcommands	Auto-approve?
Framework-verified (read-only / destructive read / idempotent workspace-write)	repos info status context version doctor completion / jot --pop / add switch sync memo goal jot	Yes (bundled)
Framework-neutral — workflow timing	done new	No — neutral: neither bundled nor must-confirm; users who want them prompt-less allowlist them in their own agent settings (snippets included)
Project-level / shared-infrastructure change	config clone	No — always prompt
Irreversible delete/reset — runtime-gated	prune sync --force sync --branch	No — always prompt (already machine-refused from inside any workspace at the runtime layer)

Why done/new move out of the destructive bucket: both are non-destructive and reversible (done is a state flip that setting a goal reactivates; new only creates a guarded, prune-reclaimable directory), but orbit cannot judge when running them is right — that timing is the user's workflow rhythm, and bundling them would be the framework taking a position on it. This also retires the stale "human-initiated regardless of permissions" actor prescription (CONSTRAINTS L49, Anti-Pattern 3, SKILL Safety rule 3): the implementation never distinguished callers, and creating a workspace from inside another one is a live workflow.

jot --pop's bundling gets its honest rationale: the queue is not user data (jot+memo is agent-maintained by design) and pop timing is procedural, not user rhythm.

Also in this pass

• Bare orbit goal never had a read path (TTY opens an editor, non-TTY reads stdin) — USAGE, SKILL and CONSTRAINTS no longer promise the bare read; reads point at orbit context goal.
• SKILL.md: workflow steps 1/2 now respect the injected-block preflight instead of commanding re-fetches; step 7 pops jots only when the startup block reported them (the startup moment is the residue discriminator — same-session jots still aggregate at wrap-up/overflow, per spec-knowledge's capture/aggregate split); the Examples section now shows the assess-before-add chain instead of skipping it; ~18 lines trimmed.
• spec-commands: the execution-location matrix gains the missing orbit config row (runs anywhere in the project).

Test plan

• bats tests/24_auto_approve.bats — 7/7 (destructive-tier loop narrowed to prune/clone/config; new pin: done/new fall through as framework-neutral)
• node --experimental-strip-types --test plugin.test.ts — 17/17
• shellcheck hooks/auto-approve.sh — clean
• Full bats suite green except tests/09_prune.bats, which hangs on this machine with and without these changes (pre-existing, unrelated — verified against a clean tree)