The writ lifecycle surface: reconcile, scopes, and the vocabulary settlement #762

The design is settled (2026-08-31). This tracks placing it in the tree: the specification, the plan, the user
documentation, and then the code.

What was ruled

Four lifecycle operations, named once. deploy, reconcile, upgrade, decommission — in both lore
and writ, over different subjects. No program has a status command. writ status is the sole violator
(commands.go:187) and becomes writ reconcile.

The rename is a reversion. writ reconcile existed and was replaced by writ status at phase-8 step 47,
because "'Reconcile' promises mutation the command does not perform" (writ-deploy-family.md:136). That
reason no longer holds: reconcile reports AND repairs. 5.1's "there is no --fix" is the stale part.
Reconcile is git diff for a deployment — what changed since deploy and some number of upgrades — and one
day a merge tool: restore a system from its current state back to its desired state.

Reconcile is a command, not a flag. There is no --reconcile.

Reconcile is valid only after deployment. Before it, not-found — which is what makes the exit code carry
information. This corrects #756, filed against the opposite reading.

The word is scope, not target. A scope is a named execution context: a name, a target root, a
confinement boundary, an elevation posture, and its own graph. 2.4-hermeticity-guarantees.md is the
authority. target keeps its own job: a destination path.

--scope is multi-valued, repeatable, and writ-only. [--scope=<name>]...

Elevation is per scope, automatic, as needed — sudo on Unix, Administrator on Windows. Not soon; the
design is a draft (6.1-privilege-elevation.md).

The builtin scopes

Capitalization is the platform's. LOCALAPPDATA and APPDATA are deliberately not builtins: Local has
no supported relocation and reaches through Home as an ordinary relative path; Roaming is officially
redirectable under domain policy, so a builtin would hardcode a location an AD policy may override.

Reserved names

Builtin scope names are reserved on every platform and defined on some:

The general rule: data is skipped, instructions are refused. Reserving everywhere is what keeps one
repository meaning one thing on every machine.

Custom scopes

One config map, name to root, mined from custom segments and converging with them:

writ:
  scopes:
    Staging: ~/staging/root

The vocabulary rename

The evidence is four lines apart in one file: builder.go:49 "Target is the absolute path to the target
file"; builder.go:57 "TargetName is the target scope".

Work

• 10-command-line-interface.md: the four operations, --scope, reserved names, custom scopes
• 2.4-hermeticity-guarantees.md: scope vocabulary; remove three stale "unconfined" claims
• 5.1-reconciliation.md: reconcile reports AND repairs; the rename and why step 47's reason lapsed
• deploy replaces the record: a deploy opens one lifetime and the fold is bounded to it (ruled 2026-09-22, The four lifecycle operations are defined by what each does to the record: deploy replaces it, upgrade updates it, decommission removes it, reconcile restores it #913; the documents carry it, the code does not)
• upgrade updates the record (The four lifecycle operations are defined by what each does to the record: deploy replaces it, upgrade updates it, decommission removes it, reconcile restores it #913)
• decommission removes the record (The four lifecycle operations are defined by what each does to the record: deploy replaces it, upgrade updates it, decommission removes it, reconcile restores it #913)
• reconcile restores the system to the record, the desired state; its words name system-versus-record drift: absent, changed (The four lifecycle operations are defined by what each does to the record: deploy replaces it, upgrade updates it, decommission removes it, reconcile restores it #913, reconcile's words name system-versus-record drift, the record as the reference: linked, copied, absent, changed; orphan and missing retired #923)
• 4.4-root-path-triad.md: §4 Mode Switch describes types that no longer exist
• 5.3-recovery-site.md: RootReaderWriter test mode no longer exists
• schema/defaults/writ.yaml and schema/devlore-config.json: writ.scopes, open map, in BOTH
• the plan document
• writ status → writ reconcile, package moved with git mv, no alias
• the Target* → Scope* rename
• --scope, multi-valued, replacing the inert --target
• The doubled environment prefix: WRIT_WRIT_VERBOSE works, WRIT_VERBOSE does not

Open design questions

• Does a file deployment depend on package installation? (2026-09-05, DANOBLE-WD11-3.) The deploy graph runs the
  manifest's package subgraph before the file chains, and one failed pkg.install (818) stopped the whole
  scope: no link, no directory, no store was written. A user asking for a working box got nothing because one package
  name was wrong. Options: file chains and package subgraphs are independent siblings that fail independently; or the
  order stays and a package failure is reported but not fatal to the files; or the dependency is real and stays. A
  ruling for this thread.

Related

#761 (System scope roots disagree), #756 (corrected by the not-found ruling), #746 (writ.segments
unwired — the same shape as writ.targets).