@clossys/launcher 0.3.1 → 0.5.0

package/README.md

@@ -48,26 +48,99 @@ listed is no longer composed (its source disappeared), so launcher removes
 its composed output and host discovery links — and only that. It never
 touches a skill it did not itself write.
 
+The recorded digest is how launcher tells whether it still owns a composed
+skill. Before rewriting or retiring one, it compares the file on disk
+(`.agents/skills/clossys-<package>/SKILL.md`, and any real-directory copy
+at a host discovery path) with the digest it recorded when it last wrote
+that file:
+
+| On disk | Rewrite (skill still composed) | Retire (skill no longer composed) |
+| --- | --- | --- |
+| Matches the recorded digest | Rewritten | Removed, with its discovery links |
+| Edited since launcher wrote it | Left as is and reported | Left as is, with its discovery links, and reported |
+| Missing | Recreated | Retirement completes (discovery links removed) |
+| No recorded digest (first run, or an older install) | Adopted if it already equals what launcher would write; otherwise left as is and reported | Not touched: launcher only retires a skill its manifest records |
+
+A `SKILL.md` that exists but cannot be read (a permissions error, or a
+directory in its place) is treated like an edited one: left as is and
+reported. A retiring skill directory that holds files other than `SKILL.md`
+is also left as is and reported; a macOS `.DS_Store` file is ignored for
+this check. Each skill left as is appears in the health report as a
+`skill preserved` line naming the file or directory that failed the check,
+and in the report JSON under
+`skillComposition.preserved`; it marks the report degraded, and it is
+reported again on every run until resolved. Launcher recreates a missing
+composed skill because `.agents/skills` is launcher-generated output, so
+recreating it loses nothing a client wrote. That is also how to take
+launcher's version of a skill you edited: move your copy aside, delete the
+directory the `skill preserved` line names (usually
+`.agents/skills/clossys-<package>/`), and run launcher again. To keep your
+edit instead, leave the file as it is.
+
 ## Health report and staleness
 
 After create, resume, or appoint — and on every resume — the command prints
 a read-only health report. It scans all four dependency buckets
 (`dependencies`, `devDependencies`, `optionalDependencies`,
-`peerDependencies`) for the Advisor pin and for extra `@clossys/*` names.
-When the live registry version is known, each pin is graded against it: a
-pin older than live is a `stale pin` finding and marks the report
-**degraded**. The report is also degraded when Advisor is missing, dual-pinned,
-or present in any bucket other than `devDependencies`, and when apply skipped
-one or more inventoried roster targets (missing sibling clone, origin mismatch,
-and similar — the same `skill roster skipped` lines in the report). Per-package
+`peerDependencies`) for the two hub engine pins, `@clossys/advisor` and
+`@clossys/integrator` (an `advisor pin` and an `integrator pin` line), and
+for extra `@clossys/*` names.
+When an engine's live registry version is known, each of its pins is graded
+against it: a pin older than live is a `stale pin` finding, named by package,
+and marks the report **degraded**. The report is also degraded when either
+engine is missing, dual-pinned, or present in any bucket other than
+`devDependencies`, when a composed skill in the hub was left as is because a
+client edited it (the `skill preserved` lines above), when the hub's stored
+inventory fails its contract, and when the hub's lockfile does not resolve the
+engine pins yet (an `install needed (engine-pins-changed-install-needed)` line;
+see "Engine pins and the lockfile" below). Per-package
 skill sources missing from the catalogue are noted but do not by themselves mark
-degraded. Exit stays 0 on resume
+degraded. Each inventoried repository other than the hub gets a `sibling` line
+(and an entry in `skillComposition.siblings`) saying what the run found for it:
+a checkout beside the hub, one not cloned yet, another account's repository,
+the Foundry supplier tree, a folder that is not a git checkout, a checkout git
+refuses to read (dubious ownership), or a checkout whose git origin does not
+match. The line names that repository by its position in the stored
+inventory's `repositories` array (`repositories[<i>] in the stored
+inventory`), never by its id (#1179), because the whole health report is also
+JSON-dumped into the apply message's `health:` line. For a checkout beside the
+hub or one not cloned yet, the line says a hub run writes nothing there, and
+that once the repository is staffed in an approved plan, `@clossys-advisor`
+and the voices of the roles staffed there arrive with that plan's setup pull
+request. A sibling line never marks the report
+degraded, and a sibling's working tree, output an earlier release wrote into it,
+or its old pins do not change the hub run's result. Exit stays 0 on resume
 (the report is advisory); adopt prints the same report and an unparseable
 pin-versus-live comparison is noted as indeterminate rather than stale.
 `checkInventoryEntries()` additionally validates hub inventory ids read-only,
 marking ids whose repository no longer resolves (skipped with a note when
 `gh` is unavailable).
 
+### Engine pins and the lockfile
+
+For engine pins, resume and appoint change only the hub's `package.json`, never its lockfile,
+and install nothing. A run that changes an engine pin says exactly what it
+changed (`engine pins changed in package.json: @clossys/advisor 0.2.6 -> 0.5.0;
+@clossys/integrator added at 0.8.2`, and `health.enginePins` in the JSON) and
+gives one next step: run the hub's package manager install (`npm install`,
+`pnpm install`, `yarn install` or `bun install`, by the lockfile present), then
+commit `package.json` together with its lockfile. Until then a frozen install
+(`npm ci`, `pnpm install --frozen-lockfile`, `yarn install --immutable`) refuses
+the hub when a pin's version changed or an engine was added; when a pin only
+moved between dependency buckets, or a range became the exact version already
+locked, whether it refuses depends on the package manager (pnpm's frozen
+install does), so such a change is reported the same way. While a lockfile is present that does not resolve the pins yet, the
+report is degraded with an `engine-pins-changed-install-needed` finding
+(`health.installNeeded`): an npm lockfile (`npm-shrinkwrap.json`, which npm
+prefers when both exist, else `package-lock.json`) is read on every run, and
+each engine pinned to a plain version must resolve to that same version in it,
+compared as versions (a `v0.6.0` pin matches a locked `0.6.0`); any other lockfile is not read, so
+it counts as unresolved for the engines the run changed. Resume and appoint
+only raise a pin: one older than live, or not a plain version, becomes the live version,
+and one newer than live is kept. Resume rewrites `package.json` as
+2-space-indented JSON with a final LF, only when a pin changes, and never
+changes its `name`.
+
 
 ## Install
 
@@ -101,31 +174,41 @@ npm install --save-dev --save-exact @clossys/launcher@0.2.0
 ## Talking to the team
 
 First contact is `npx @clossys/launcher` (empty directory or the checkout you
-appoint as the hub). After apply, the launcher composes the same
-`@clossys-<package>` voices into the hub and into every inventoried repository
-checkout that already sits beside the hub (`.agents/skills/clossys-<package>/`
-plus host discovery links). Composition is per checkout, not machine-wide, and
-is not a catalogue dump into `package.json`.
+appoint as the hub). After apply, the launcher composes the
+`@clossys-<package>` voices into the hub (`.agents/skills/clossys-<package>/`
+plus host discovery links). A launcher run writes no skills, skills manifest,
+discovery links, `AGENTS.md` or `CLAUDE.md` into an inventoried product
+repository, and changes nothing in its checkout beside the hub
+(`--clone-missing`, below, only clones a missing one). Once a product
+repository is staffed in an approved plan, it receives those files with that
+plan's setup pull request; an inventoried repository that is not staffed does
+not receive them. Composition is per checkout, not machine-wide, and is not a
+catalogue dump into `package.json`.
 
 Voices are how you talk in a coding agent; they are not engagement engines. The
 `@clossys/advisor` npm package is the engine that grades evidence;
 `@clossys-advisor` in chat is its hiring and compatibility voice. Use
-`@clossys-advisor` and `@clossys-<package>` in the hub or in any inventoried
-product repository. Each voice can talk even when that npm package is not pinned
-in that repo. When composing into a checkout, the launcher reads each skill body
-from that checkout's installed `@clossys/<package>/skill/SKILL.md` when present,
-then from the packed catalogue or a sibling monorepo source. Launcher health
+`@clossys-advisor` and `@clossys-<package>` in the hub, where the whole team
+is composed. A product repository staffed in an approved plan gets
+`@clossys-advisor` and the voices of the roles staffed there, once that plan's
+setup pull request has merged; a role not staffed there is expected to be
+absent. Each voice can talk even when
+that npm package is not pinned in that repo. When composing into the hub, the
+launcher reads each skill body from the hub's installed
+`@clossys/<package>/skill/SKILL.md` when present, then from the packed catalogue
+or a sibling monorepo source. Launcher health
 notes missing catalogue sources but apply continues.
 
 Run `npx @clossys/launcher` again from the hub for a health report and to
-refresh composed voices on sibling inventoried clones. By default it does
+refresh the voices composed in the hub. By default it does
 not `gh repo clone` missing inventory entries -- that is not how you talk to
 the team. `launcher --clone-missing` is the one explicit, approved
 exception (#1179): on resume only, it clones every inventoried repository
 not yet sitting beside the hub, using `cloneMissingInventoryRepositories()`,
 and only those -- an id skipped for any other reason (wrong account, the
 Foundry supplier tree, a mismatched git origin) is left exactly as skipped,
-never attempted.
+never attempted. Cloning is not composing: a repository cloned this way
+receives its team only once it is staffed in an approved plan, like any other.
 
 ## How to run it
 
@@ -139,9 +222,9 @@ silent fallback.
 
 | Current directory | What happens |
 | --- | --- |
-| Empty | Creates `{owner}/workspace` from the in-package skeleton (package name `@owner/workspace`), or clones that hub if it already exists. |
-| Already a hub (generated marker; packed template `skeleton/clossys/.state/workspace.json`) | Resumes. No new repository. `--inventory` here is refused with a pointer to the appointed hub's own `clossys/.state/inventory.json`. A legacy `.clossys/` hub state is migrated automatically; see "Layout" above. |
-| Any other GitHub repository you control | Appoints it as the account hub. Keeps existing product files. Refuses when the working tree has uncommitted changes (`git status --porcelain` non-empty) — the refusal names the offending remote host when the origin is not on github.com. Refuses when `CLOSSYS_OWNER` names a different account than the repository's github.com origin owner. Writes the hub marker. Pins live `@clossys/advisor` in `devDependencies`, relocating and upgrading any pin left in another bucket. A dedicated `{owner}/workspace` checkout is named `@owner/workspace`; a product repository keeps its package name. Always reads the public Advisor version (needed to pin live and to grade resume health). Refuses if the generated hub inventory is missing or empty (packed template `skeleton/clossys/.state/inventory.json`; that generated path does not ship) unless `--inventory <path>` supplies a populated document — or, when the on-disk inventory is already populated and `--inventory` is also supplied, merges the two by repository id (on-disk order first, new ids appended, first occurrence of an id wins). Does not rewrite the lockfile or dump the catalogue. Prints a read-only health report. |
+| Empty | Creates `{owner}/workspace` from the in-package skeleton (package name `@owner/workspace`, pinning live `@clossys/advisor` and `@clossys/integrator` exactly in `devDependencies`), or, when that repository already exists, clones it and classifies its hub marker like a local run: a current marker resumes; a legacy `.clossys/` marker alone is migrated to `clossys/.state/`; both markers are refused before Launcher writes into the clone; with no marker, the clone is appointed as the hub (refused when its working tree has uncommitted changes; existing `README.md`, `AGENTS.md` and `CLAUDE.md` are kept, and a skeleton `package.json` is written only when the clone has none) and the apply message says "appointed". That appoint needs no inventory, but refuses when the clone carries an inventory that fails its contract or a `package.json` that is not a JSON object; every such refusal leaves the clone unchanged. |
+| Already a hub (generated marker; packed template `skeleton/clossys/.state/workspace.json`) | Resumes. No new repository. `--repositories` writes the repositories the founder chose again into `clossys/.state/inventory.json` before skills are composed (see "Choosing the hub's repositories" below). `--inventory` here is refused, and the refusal points at choosing the repositories again on Advisor's repository card and running `launcher --repositories`, instead of at hand-editing the file. A legacy `.clossys/` hub state is migrated automatically; see "Layout" above. For each hub engine whose live version the registry returned, pins that version exactly in `devDependencies` of the hub's existing `package.json`: a frozen older pin is bumped, a pin newer than live is kept, a missing Integrator pin is added, and a pin in another bucket is moved; other `@clossys/*` entries are left as they are, and the file is rewritten only when a pin changes. The report then names each change and the install to run next (see "Engine pins and the lockfile" above). |
+| Any other GitHub repository you control | Appoints it as the account hub. Keeps existing product files. Refuses when the working tree has uncommitted changes (`git status --porcelain` non-empty) — the refusal names the offending remote host when the origin is not on github.com. Refuses when `CLOSSYS_OWNER` names a different account than the repository's github.com origin owner. Writes the hub marker. Pins live `@clossys/advisor` and `@clossys/integrator`, each exactly, in `devDependencies`, relocating any pin left in another bucket, raising an older one (a pin newer than live is kept), and leaving other `@clossys/*` entries as they are; the report names each change and the install to run next. An existing `package.json` `name` is kept; a `{owner}/workspace` checkout whose manifest has no name is named `@owner/workspace`. Refuses, before writing anything, an existing `package.json` that is not a JSON object (unparseable, an array, or a primitive). Always reads the public Advisor and Integrator versions (needed to pin live, and to pin and grade health on resume); refuses as indeterminate when the registry returns either one unreadable. Refuses if the generated hub inventory is missing or empty (packed template `skeleton/clossys/.state/inventory.json`; that generated path does not ship), and the refusal points the founder at choosing the hub's repositories on Advisor's repository card and passing them to `--repositories`, which writes the inventory (see "Choosing the hub's repositories" below). `--inventory <path>` still supplies a populated document instead — and, when the on-disk inventory is already populated and `--inventory` is also supplied, merges the two by repository identity (on-disk order first, new repositories appended, the first occurrence of a repository kept, and every kept entry kept whole, its `packages` included). Does not rewrite the lockfile or dump the catalogue. Prints a read-only health report. |
 
 It does not have to be a brand-new exclusive repository, and it does not
 have to already match a Foundry layout. Informal "workspace-looking" trees
@@ -158,10 +241,91 @@ yes in chat is permission for that one step only; it is not a lasting
 grant and it does not write git unless a file is saved later. The same
 command resumes later.
 
+## Choosing the hub's repositories
+
+A founder never writes the inventory by hand (#1179). Advisor's repository
+card (`@clossys/advisor`'s `repositoryChoiceCard()`, or its
+`advisor-repository-card` bin before the hub exists) offers the
+repositories the agent listed from GitHub for the founder's sign-in; the
+founder chooses; and the agent passes the chosen ids to Launcher:
+
+```bash
+launcher --repositories example-owner/example-app,example-owner/example-site
+```
+
+`--repositories` takes one argument of comma-separated repository ids (an
+id never contains a comma). It works when appointing a repository as the
+hub and on an existing hub checkout; in an empty directory it is refused,
+because there is no hub to write into yet. Launcher writes the chosen ids to
+`clossys/.state/inventory.json` (a generated hub path, not shipped in this package)
+-- the one inventory location it reads on
+every later run -- and, on resume, writes it before the health report is
+built, so the same run lists the repositories just chosen as `sibling` lines.
+
+- The ids, and the document built from them, are checked against
+  `docs/contracts/repository-inventory.json` (in the public repository;
+  that exact path does not ship in this package, but this package's build
+  packs and ships its own copy of the contract) through the same shared
+  contract checker every read of the inventory uses, and the document is
+  checked again by that reader before it is written. What Launcher writes is
+  what Launcher reads back.
+- A malformed choice -- an empty id, an id that is not a bare name or
+  `owner/name`, or two ids naming the same repository -- is refused by
+  position (`repositories[1].id ...`), never echoed, and nothing is written.
+- Launcher decides "is this the same repository" one way everywhere: a
+  bare id names a repository of the hub's own owner, and letter case is
+  ignored, so `app`, `App` and `<owner>/app` are one repository. Owners are
+  compared the same way. A stored inventory, or a choice, that lists one
+  repository twice this way is refused, naming the two positions; it is
+  never merged. The hub itself is recognised by its origin's `owner/name`
+  (or, without a github.com origin, the repository its marker records),
+  never by its folder path, so an inventory that names the hub in another
+  letter case never lists it as its own sibling.
+- An inventory that already lists exactly the chosen repositories, in any
+  order or letter case, or with a bare id for the hub's own owner, is left
+  as it is.
+- An inventory that lists a different set is never merged into or
+  overwritten silently: the run is refused, stating how many repositories
+  each side has and which positions would be added and removed --
+  `--repositories[<i>]` for an added id's position in the `--repositories`
+  argument, `repositories[<i>] in the stored inventory` for a removed id's
+  position in the file -- never the ids themselves, because both the stored
+  inventory file and `--repositories` are input an agent may relay
+  verbatim, and a repository id is exactly the kind of short string a
+  hostile inventory entry could shape as prompt-injection text. Run again
+  with `--replace-inventory` to approve the replacement; a repository that
+  stays keeps its existing entry, `packages` included. An agent acting on
+  the refusal looks each reported position up in its own copy of the
+  stored inventory file or its own `--repositories` argument to learn which
+  repository it names, and tells the founder that name -- never the
+  position string itself, and never text read back out of the inventory
+  file or the argument without that lookup. That replacement run's own
+  success line reports the same removed positions again, distinctly
+  labeled `repositories[<i>] in the replaced inventory`: by the time that
+  line prints, `clossys/.state/inventory.json` is already the new file, so
+  reusing "in the stored inventory" there would point a reader at the
+  wrong document. The positions still index into the file as it stood
+  before this run -- the same one the refusal step already named -- so an
+  agent that already looked a position up there does not need to look it
+  up again. The same position-only rule, and the same "in the stored
+  inventory" wording, applies to every other message this command prints
+  that names a repository from the file currently on disk -- each
+  `sibling (...)` line and `launcher --clone-missing`'s output. (Since
+  #1511 the `skill roster written` health-report line names only the
+  hub's own id, never a stored-inventory position, so it is no longer on
+  this list.)
+- An inventory that fails its contract is likewise replaced only with
+  `--replace-inventory`.
+- `--repositories` and `--inventory` each supply the whole inventory, so
+  they are refused together, and `--replace-inventory` without
+  `--repositories` is refused.
+
 ## CLI
 
 ```bash
 launcher
+launcher --repositories example-owner/example-app,example-owner/example-site
+launcher --repositories example-owner/example-app --replace-inventory
 launcher --inventory path/to/inventory.json
 launcher --clone-missing
 launcher --help
@@ -169,6 +333,12 @@ launcher-check --help
 launcher-check --input observation.json
 launcher-doctor
 launcher-apply-plan --plan plan.json --brief brief.json --repo ./product-checkout
+launcher-apply-plan plan
+launcher-apply-plan materialize --repo ./site-checkout
+launcher-apply-plan verify --repo ./site-checkout
+launcher-apply-plan status --repo ./site-checkout
+launcher-apply-plan body --repo "<id>" --task-record 12
+launcher-apply-plan snapshot --request package-request.json
 ```
 
 Exit codes preserve the ternary:
@@ -176,8 +346,10 @@ Exit codes preserve the ternary:
 | Exit | State | Meaning |
 | --- | --- | --- |
 | `0` | `satisfied` | Created, resumed, or appointed the hub. The message includes a read-only health report. |
-| `1` | `violated` | Known refusal: not GitHub, not empty, missing appoint inventory, the supplier tree, uncommitted changes in the appoint tree, or a `CLOSSYS_OWNER` that disagrees with the origin owner. |
-| `2` | `indeterminate` | Missing `gh`, unreadable registry pin, or an owner that could not be inferred. |
+| `1` | `violated` | Known refusal: not GitHub, not empty, missing appoint inventory, a malformed `--repositories` choice or one that differs from the stored inventory without `--replace-inventory`, the supplier tree, uncommitted changes in the appoint tree, or a `CLOSSYS_OWNER` that disagrees with the origin owner. |
+| `2` | `indeterminate` | Missing `gh`, an Advisor or Integrator registry version that could not be read when creating or appointing, or an owner that could not be inferred. |
+
+`launcher-apply-plan` has its own exit codes, described in [Applying an approved plan](#applying-an-approved-plan) and [Taking the registry snapshot](#taking-the-registry-snapshot).
 
 `launcher-check` grades a captured observation JSON through `planWorkspace` and does not create a hub. Same ternary: 0 is a create/resume/adopt plan, 1 is a known refusal, 2 could not run or could not decide. Appoint grades as a plan only when the observation already records a populated inventory; `--inventory` is a live CLI flag, not a check-cli input.
 
@@ -185,41 +357,54 @@ Exit codes preserve the ternary:
 
 | Export | Description |
 | --- | --- |
-| `planWorkspace()` | Decides create, resume, or adopt from a cwd observation. Optional `{ inventoryPath }` is the only way to appoint without a populated on-disk inventory. |
-| `applyWorkspacePlan()` | Copies the in-package skeleton or hub marker through a host port and returns a `WorkspaceApplyResult` with health. Composes the same skill voices (with the shared conversation contract injected) on the hub and on inventoried sibling checkouts beside it; refreshes stale hub guidance and the generated `clossys/` README on every path, including resume; migrates a legacy `.clossys/` hub state automatically. Optional `{ skillCatalogueRoot, launcherPackageRoot, contractPath, liveLauncherVersion }` selects where skill and contract bodies are read and grades skill-manifest staleness. |
-| `observeWorkspace()` | Reads `gh`, git remotes, cwd, inventory classification, hub-state migration status, and the public Advisor version. |
-| `readInventoryRepositories()` | Reads repository ids from a `schemaVersion: 1` inventory document. |
+| `planWorkspace()` | Decides create, resume, or adopt from a cwd observation. Optional `PlanWorkspaceOptions`: `{ repositories, replaceInventory }` (`--repositories` / `--replace-inventory`; appoint or resume) or `{ inventoryPath }` (`--inventory`; appoint only) are the ways to appoint without a populated on-disk inventory. A plan carrying `repositories` holds the resulting `ChosenInventory`: the exact document to write, or `unchanged`. An appoint plan that merges `--inventory` into a populated stored inventory carries `mergedInventoryRepositories`, the merged entries, each kept whole, and `mergedInventoryDocument`, the exact merged document those entries render to, which apply writes. |
+| `applyWorkspacePlan()` | Copies the in-package skeleton or hub marker through a host port and returns a `WorkspaceApplyResult` with health. Composes the skill voices (with the shared conversation contract injected) on the hub only, writes nothing into an inventoried checkout beside it, and reports each inventoried repository other than the hub under `skillComposition.siblings`; refreshes stale hub guidance and the generated `clossys/` README on every path, including resume; migrates a legacy `.clossys/` hub state automatically. Optional `{ skillCatalogueRoot, launcherPackageRoot, contractPath, liveLauncherVersion }` selects where skill and contract bodies are read and grades skill-manifest staleness. |
+| `observeWorkspace()` | Reads `gh`, git remotes, cwd, inventory classification, hub-state migration status, and the public Advisor and Integrator versions (`npm view <package> version`). |
+| `readInventoryRepositories()` | Reads repository ids from an inventory file, as bytes, routed through `validateInventoryDocument()` (a missing file reads as no ids; anything present but invalid throws, naming the offending field by position -- never silently accepted or silently emptied). An optional fourth argument, the hub's owner, makes a bare id and `<owner>/<id>` one repository. |
 | `readLiveLauncherVersion()` | Reads the public `@clossys/launcher` registry version, used only to grade catalogue-sourced skill staleness. |
 | `launcherPackageRootFromModule()` | Resolves this package's root from `import.meta.url` so apply can find the packed skill catalogue and contract. |
 | `parseGitHubRemote()` | Parses a github.com remote and rejects any other host. |
 | `isHubDocument()` | Type guard for the generated hub marker (packed template: `skeleton/clossys/.state/workspace.json`). |
-| `inspectInventory()` | Classifies inventory JSON as missing, empty, or populated. |
-| `reportHubHealth()` | Read-only pin, inventory, migration, and skills-manifest report. Does not install or uninstall. |
+| `inspectInventory()` | Classifies an inventory document -- pass the file's bytes, and the hub's owner when known -- as missing, empty, populated, or invalid (malformed or schema-mismatched -- never silently folded into empty; see `validateInventoryDocument()`). |
+| `validateInventoryDocument()` | Strictly validates an inventory document -- a file's exact bytes, or text built in memory -- against `docs/contracts/repository-inventory.json` (in the public repository; that exact path does not ship in this package, but this package's build packs and ships its own copy of the contract; `schemaVersion: 1`, a `repositories` array of `{ id, packages? }` entries -- `id` a bare repository name or `owner/name` in the same format Launcher's own sibling/clone resolution requires, case-insensitively unique; `packages`, when present, shaped exactly as `@clossys/integrator`'s `InventoryPackageEntry`, no other key). It is read as strict JSON (a syntax error is reported by position only; a key repeated in any object, bytes that are not valid UTF-8, a leading byte order mark, or a lone surrogate, escaped or raw, is refused) and checked by the same shared contract checker, packed from `@clossys/advisor`, that checks the plan and the brief. With `InventoryReadOptions` `{ hubOwner }`, a bare id and `<hubOwner>/<id>` are also one repository, and a document listing both is refused. Returns `{ valid: true, ids }` or `{ valid: false, reason }`, where `reason` names every field at fault by position and never quotes a value. Every read and write of an inventory document -- `--inventory`, `--repositories`, the on-disk `clossys/.state/inventory.json` (a hub path, not shipped in this package) on every run, and `readInventoryRepositories()` -- passes the file's exact bytes, read with `WorkspaceHost.readBytes()`, never text decoded first, so invalid bytes cannot be silently replaced before the check; an inventory Launcher copies (`--inventory`, or a legacy `.clossys/` inventory it migrates) is written back byte for byte; a document that merely resembles an inventory (for example a governance record whose entries also carry `role`, `visibility`, `status`, `notes`) is refused, never adopted or silently read as though it validated (#1334). |
+| `reportHubHealth()` | Read-only pin, inventory, migration, and skills-manifest report: `advisorPin` and `integratorPin`, each engine graded against its own live version (the live Integrator version is the last, optional argument). Does not install or uninstall. |
 | `formatHubHealth()` | Human lines plus a `health:` JSON line for the same report. |
 | `hasAdvisorPin()` | True when a manifest already pins Advisor in any dependency bucket. |
 | `checkInventoryEntries()` | Read-only inventory id validation through `gh repo view` (batched; skips with a note when `gh` is unavailable). |
-| `DEFAULT_REPOSITORY_NAME` | Default new-hub repository name (`workspace`). Used only when creating, never when appointing. |
+| `DEFAULT_REPOSITORY_NAME` | Default hub repository name (`workspace`): the repository an empty-directory run creates, or clones when it already exists. |
 | `CLOSSYS_DIR_REL` | Relative path of the one visible per-repository Clossys folder (`clossys`). |
 | `STATE_DIR_REL` | Relative path of the machine-state folder (`clossys/.state`). |
 | `WORKSPACE_MARKER_REL` | Relative path of the hub marker. |
 | `WORKSPACE_INVENTORY_REL` | Relative path of the hub inventory. |
 | `CLOSSYS_README_REL` | Relative path of the generated index README at the root of `clossys/`. |
 | `LEGACY_STATE_DIR_REL` / `LEGACY_WORKSPACE_MARKER_REL` / `LEGACY_WORKSPACE_INVENTORY_REL` | Pre-#1171 `.clossys/` paths, kept only so resume can detect and migrate them. |
-| `CommandResult` / `CwdObservation` / `DependencyBucket` / `HubDocument` / `HubHealthReport` / `HubMigrationState` / `InventoryObservation` / `InventoryValidationEntry` / `InventoryValidationReport` / `PinFinding` / `PinGrade` / `SkillManifestDocument` / `SkillManifestEntry` / `SkillsManifestSummary` / `ApplyWorkspaceOptions` / `WorkspaceApplyResult` / `WorkspaceDecision` / `WorkspaceHost` / `WorkspaceObservation` / `WorkspacePlan` / `WorkspaceRefusal` / `WorkspaceState` | Typed host, observation, plan, health, and outcome contracts. |
-| `cloneMissingInventoryRepositories()` | Explicit, approved action (#1179): clones every inventoried repository `resolveSisterCloneTargets` skipped for "not beside the hub", and only those. Returns a `CloneMissingOutcome[]`. |
+| `CommandResult` / `ChosenInventory` / `CwdObservation` / `DependencyBucket` / `EngineInstallFinding` / `EnginePinChange` / `HubDocument` / `HubEnginePin` / `HubHealthReport` / `HubMigrationState` / `InventoryObservation` / `InventoryValidationEntry` / `InventoryValidationReport` / `InventoryReadOptions` / `PinFinding` / `PinGrade` / `PlanWorkspaceOptions` / `SkillManifestDocument` / `SkillManifestEntry` / `SkillsManifestSummary` / `ApplyWorkspaceOptions` / `WorkspaceApplyResult` / `WorkspaceDecision` / `WorkspaceHost` / `WorkspaceObservation` / `WorkspacePlan` / `WorkspaceRefusal` / `WorkspaceState` | Typed host, observation, plan, health, and outcome contracts. A `WorkspaceHost` reads and writes text and, for inventory files, exact bytes (`readBytes()` / `writeBytes()`). |
+| `cloneMissingInventoryRepositories()` | Explicit, approved action (#1179): clones every inventoried repository of the hub's account that is not cloned beside the hub, and only those; a checkout already beside the hub is left out of the outcomes, and every other inventoried repository is reported as `skipped-other-reason`, never attempted. Returns a `CloneMissingOutcome[]`. |
 | `runDoctorChecks()` | Read-only prerequisite checks in fix-in-this-order sequence: git, `gh`, signed in, Node.js, npm, then the advisory coding-agent step. Returns a `DoctorReport`. |
 | `renderDoctorReport()` | Renders a `DoctorReport` one step at a time, the way `launcher-doctor` prints it. |
 | `checkCloudSessionBootstrap()` | Read-only: the three product-repository-layout.json cloud-session-bootstrap checks against a directory. Returns a `CloudBootstrapReport`. |
-| `reportInventoryDrift()` | Compares a declared external inventory against the launcher-written one; reports external-only, launcher-only, and agreeing repository ids. Returns an `InventoryDriftReport`. |
+| `reportInventoryDrift()` | Compares a declared external inventory against the launcher-written one; reports external-only, launcher-only, and agreeing repositories as a count plus each one's position, never its id (`externalInventory[<i>]` into the declared external document, `repositories[<j>]` into the hub's own stored inventory) -- both are document content, and this whole report is JSON-dumped into the apply message's `health:` line on every resume of a hub that declares `externalInventory`. Both files are read as bytes by the strict reader. An optional fifth argument, the hub's owner, compares ids as every other Launcher comparison does (a bare id is that owner's; case is ignored). The hub's own inventory is read with `validateInventoryDocument()`: a missing one lists nothing, and one that is present but invalid makes the report `indeterminate`, never a comparison against an empty list. Returns an `InventoryDriftReport`. |
 | `detectLinkedHosts()` | Read-only: which of `claude-code`, `cursor`, `codex` can currently discover skills in a directory. |
 | `serializeHostRecord()` / `parseHostRecord()` | Round-trip `clossys/.state/hosts.json` (`HOSTS_REL`). |
 | `parsePreferences()` | Reads `clossys/preferences.json`'s budget stance; defaults to `"balanced"` on absence or malformed input. |
 | `readHostModelProfile()` | Reads a packed `model-profiles/<host>.json`; returns `undefined`, never throws, on a missing or malformed file. |
 | `resolveModelForTier()` | Resolves a tier and budget preference to one model name for a host, reporting `belowFloor` rather than silently substituting a weaker tier's model. |
-| `validateAdvisorPlan()` / `validateEngagementBrief()` | Shape validation against the #1175 "Plan file contract" for `clossys/advisor/plan.json` and `clossys/brief.json`. |
-| `isPlanApproved()` | True only when a plan's most recent decision (by timestamp) has `chosen === "approved"`. |
-| `applyEngagementBrief()` | Writes `clossys/brief.json` into a repository directory once both the plan and the brief validate; refuses and writes nothing otherwise. |
-| `CloneMissingOutcome` / `DoctorCheckHost` / `DoctorReport` / `DoctorStepId` / `DoctorStepResult` / `CloudBootstrapCheck` / `CloudBootstrapReport` / `ExternalInventoryDeclaration` / `InventoryDriftReport` / `DiscoveredHost` / `HostRecord` / `BudgetPreference` / `HostModelProfile` / `HostTierMapping` / `ModelResolution` / `PreferencesDocument` / `ReasoningTier` / `SupportedHost` / `AdvisorPlan` / `ApplyBriefResult` / `BlockerKind` / `EngagementBrief` / `EngagementBriefRole` / `PlanBlocker` / `PlanDecision` / `ValidationResult` | Typed contracts for the sections above. |
+| `validateAdvisorPlan()` / `validateEngagementBrief()` | Validation of `clossys/advisor/plan.json` and `clossys/brief.json` (with its `context` snapshot) against the shared plan and brief contracts Advisor also validates against, including the contracts' code rules (R1-R11 for a plan, B1-B2 for a brief). Unknown fields are refused; the reason names every field at fault. |
+| `approvedSubject()` | What an approval binds: the `subjectDigest` of the plan's latest decision (by timestamp) when that decision has `chosen === "approved"`, else `null`. `null` when the approval has no `subjectDigest`, when decisions at the latest time disagree or name different subjects, when any decision time does not parse, or when the plan does not validate. Anything that applies a plan must use this; the one stated exception is the legacy brief-only path (`applyEngagementBrief()` and `launcher-apply-plan`), which predates the binding and uses `isPlanApproved()`. |
+| `isPlanApproved()` | True only when a plan's most recent decision (by timestamp) has `chosen === "approved"`. False when decisions at that latest time disagree, or when any decision time does not parse. It binds no bytes: it ignores `subjectDigest`, so it is also true for an approval that names no change. |
+| `applyEngagementBrief()` | Writes `clossys/brief.json` into a repository directory once the plan validates and is approved and the brief validates; refuses and writes nothing otherwise. Reports the plan's canonical digest. |
+| `planDigest()` / `canonicalJson()` / `canonicalDigest()` / `PLAN_DIGEST_EXCLUDED_FIELDS` | The canonical plan digest: `sha256:` over the RFC 8785 canonical JSON of the plan without `asOf` and `decisions`. Identical to Advisor's for every plan. `canonicalDigest()` is the shared step: `sha256:` over the canonical JSON of any value, which the plan, change-set and bundle digests all use. |
+| `planApplyBundle()` | The pure apply planner: from a validated plan, the hub brief, observations of each staffed repository's default branch (including the exact bytes of its installed-state ledger and its composed-skill manifest), the change sets the hub holds, the composed skill text, the producer version and the hub's Advisor and Integrator pins, computes one change set per staffed repository (a setup set for a repository in the setup phase, an apply set otherwise) and returns a report-mode bundle. Trusts a repository's ledger only through held change sets, or skips the repository with the trust rule as its reason (`ledger-unreadable`, `identity`, `renamed`, `ledger-chain`, `ledger-foreign-row`); computes each owned path and key by compare-and-swap against the trusted ledger (add, keep, update, or a refusal: `unowned-existing`, `client-edited`, `deleted`), reported under V8; composes the Advisor voice with the staffed roles' voices; skips a repository, `indeterminate` and outside the bundle digest, when a setup set cannot be computed safely (`package-manager-unsupported`, `starter-pin-absent`, `starter-pin-unsupported`, `release-age-text-absent`, `starter-request-invalid`), when an apply set would change the Starter pin its request names (`starter-request-stale`), one whose Controller profile needs root entries added when the observation omits the profile text (`root-entry-edit-unbuilt`), one whose owned package the lockfile no longer resolves to the recorded version and integrity (`integrity-mismatch`, violated), one whose ledger holds only some of a setup template's files (`template-rows-partial`), and one whose lockfile or ledger path has a case variant among the observed files (`case-variant-path`). Two or more observed files at the same path, compared case-insensitively, have no single base digest between them, so that path is never kept, updated or adopted. Refuses, by throwing before computing anything, a staffed role that is not a lowercase id token (`role-not-an-id`) and a planItem that is not its repository id, a colon and its package name (`plan-item-not-derived`). Reads no file, network, process or clock; the same inputs give the same bytes. Throws, naming positions and never values, on inputs it cannot plan from. |
+| `AGENTS_GUIDE_PATH` / `AGENTS_GUIDE_TEXT` / `CLOSSYS_SKILL_PATTERNS` / `verifyAgentsGuide()` | The Launcher-owned guide, the `AGENTS.md` file inside `clossys/`: its path, its one constant text, the three `clossys-*` skill path patterns the text carves out, and a check that is true only for exactly those bytes. The text holds no plan text, repository name or client detail, and no marker sits inside it. |
+| `trustInstalledLedger()` / `reconcileWholeFile()` | Whether a repository's ledger bytes may be trusted: exactly canonical and valid (`ledger-unreadable`), for the observed node id (`identity`) and id, compared exactly -- a difference in letter case alone is still refused (`renamed`) -- every generation a held, valid change set whose digest recomputes and that agrees with its history entry (`ledger-chain`), and every row a write of the set it names (`ledger-foreign-row`); a refusal carries the rule only. `reconcileWholeFile()` is the compare-and-swap table for one whole file, with the generation-0 adoption pass allowed only in a setup set; `clossys/.state/skills.json` is adopted through that pass only when its base already holds the exact bytes the set would write, never merely because a skills manifest was read. Pure. Types: `LedgerTrust`, `LedgerTrustRule`, `WholeFileState`, `WholeFileOutcome`. |
+| `projectEngagementBrief()` / `serializeEngagementBrief()` / `PUBLIC_PROBLEM_PLACEHOLDER` | One repository's brief: the hub brief with `staffedHere` set to that repository's roles in plan order, and `problem` replaced by the brief contract's fixed placeholder unless the repository is private, members in the brief contract's order at every depth; and the exact bytes written for it (two-space JSON and a final newline). |
+| `changeSetDigest()` / `changeSetDigestSubject()` / `CHANGE_SET_DIGEST_EXCLUDED_FIELDS` / `DERIVED_FILE_DIGEST_FIELDS` | The change-set digest: `canonicalDigest()` of the change set without `changeSetDigest`, `branch`, `bundle`, `pullRequest`, `inverse`, `tooling` and `texts`, with each derived file reduced to `path`, `mode`, `derived`, `item` and `invariants`. |
+| `bundleDigest()` | The bundle digest an approval binds: `canonicalDigest()` of the plan digest and, sorted by id, the id and change-set digest of each repository that has a change set. Nothing else. |
+| `validateRepositoryChangeSet()` / `validateApplyBundle()` | Validation of a change set and a bundle against the shared change-set and bundle contracts, including their code rules (C1-C16 for a change set: references, allow-list and case-insensitive path rules, the ledger, the digest, only the ledger and lockfile derived, canonical order, each item's writes matching it -- discovery links, the skills manifest, the pointer files and the setup templates included -- a pin-starter in devDependencies and at most once, phase, a complete setup set, the release-age exemption's surface and scope, the root entries a Controller profile needs, no skill written through a symbolic link, every refusal at a path or key its item binds, every whole file changed only as its act's write kind allows (none deletes), and each planItem derived from the repository id and package name; A1-A7 for a bundle: unique ids, the digest, verdicts that are the worst of their checks, the authorization-mismatch and authorization-absent checks, no state or binding in a report bundle, and in a planned bundle a state only where all nine checks passed and a binding exactly where V3 passed). Unknown fields are refused; no reason echoes a value. |
+| `wouldViolateRootEntries()` / `isRootEntryName()` | Whether the root names some paths introduce (each path's first segment) would fail a Controller repository profile's closed root vocabulary: `satisfied` when the profile has no vocabulary Controller checks (schema version 1 or 2, or an empty `rootEntries`) or declares every name allowed or required; `violated`, with the undeclared and the prohibited names, sorted; `indeterminate` (`root-vocabulary-unknown`) for anything Controller could not read as a root vocabulary. Reads only `schemaVersion` and `rootEntries`, by the rules Controller's README states; pure. `isRootEntryName()` is Controller's rule for one direct-child name. |
+| `validateInstalledLedger()` / `readInstalledLedger()` / `ledgerSuccession()` / `serializeInstalledLedger()` / `renderInstalledLedger()` | The installed-state ledger (`clossys/.state/installed.json`): validation against the shared ledger contract and its code rules L1-L10 (history, each generation's approval binding, rows naming history, owned paths and link modes, keys matching packages, no act twice, canonical order, root entries in one Controller profile among fixed names, id-token roles in skill paths, and derived planItems); the contract's succession rules for a pull request's head ledger against its base's, each given as its exact bytes, a `Uint8Array` (both must be exactly canonical; then unchanged, or one next generation keeping the base's history, and an admitted generation installing exactly what the setup deferred and changing nothing else, except that an apply set may add the one guide row, for the `AGENTS.md` file inside `clossys/`, with the guide's digest), reporting whether a next generation was proved `admitted` or only claims an approval (`approval-claimed`); the exact bytes of a valid ledger; a strict read of a ledger from its bytes, also a `Uint8Array` (null unless it is a `Uint8Array`, valid and exactly canonical -- decoded with the same strict, BOM- and invalid-UTF-8-refusing reader the plan and brief contracts use, never a caller's own decode); and the bytes of the next generation a change set writes over the previous ledger, under the contract's RENDER section (each deferred row takes its identity from the plan's package acts, `LedgerPackageIdentity`), refusing a set computed from another generation or for another repository, and an apply set that would adopt a file. A valid ledger is well formed, not trusted: see `trustInstalledLedger()`. |
+| `storeChangeSet()` / `storeApplyBundle()` / `readStoredChangeSet()` / `readStoredApplyBundle()` / `CHANGE_SET_STORE_REL` / `BUNDLE_STORE_REL` | The hub's content-addressed stores under `clossys/.state/apply/change-sets/` and `clossys/.state/apply/bundles/`, one file per digest named by its 64 hex digits: a write validates first and does nothing when the file already holds the same bytes; a change set is append-only and different bytes under its name are refused, while a bundle's digest excludes its authorization, clock and verdicts, so storing a bundle under a digest that already names a file atomically replaces that one file with the newest computation (superseded computations are not recorded); a read is strict, validated, and returns the document only when its recomputed digest matches its name, else null. A digest argument that is not `sha256:` and 64 lowercase hex digits is refused before any path is built. A stored file's recomputed digest proves its integrity, not its provenance: anyone who can write the hub directory can add a set that verifies. Every store directory segment down to `change-sets/` or `bundles/` must be a real directory; a symbolic link anywhere in that chain is refused rather than followed, and a filesystem error other than a missing directory or file is rethrown naming only the operation and its error code, never a path. |
+| `CloneMissingOutcome` / `DoctorCheckHost` / `DoctorReport` / `DoctorStepId` / `DoctorStepResult` / `CloudBootstrapCheck` / `CloudBootstrapReport` / `ExternalInventoryDeclaration` / `InventoryDriftReport` / `DiscoveredHost` / `HostRecord` / `BudgetPreference` / `HostModelProfile` / `HostTierMapping` / `ModelResolution` / `PreferencesDocument` / `ReasoningTier` / `SupportedHost` / `AdvisorPlan` / `ApplyBriefResult` / `BlockerKind` / `EngagementBrief` / `EngagementBriefRole` / `EngagementContext` / `EngagementContextField` / `EngagementContextFieldId` / `GoalDirection` / `PlanBlocker` / `PlanDecision` / `PlanKit` / `PlanPackageAct` / `PlanStaffing` / `ValidationResult` / `PlanApplyBundleInputs` / `PlanApplyBundleResult` / `RepositoryObservation` / `SkippedRepositoryObservation` / `BundleDigestEntry` / `ApplyBundle` / `ApplyBundleRepository` / `ApplyCheck` / `ApplyCheckId` / `ChangeSetDeferral` / `ChangeSetItem` / `ChangeSetPhase` / `ChangeSetRefusal` / `CheckVerdict` / `ContentDigest` / `DependencyPlacement` / `DerivedFileChange` / `FileChange` / `KeyChange` / `LedgerInvariant` / `LockfileName` / `PackageInvariant` / `PackageManagerKind` / `PinnedPackage` / `RefusalReason` / `ReleaseAgeSurfaceKind` / `RepositoryChangeSet` / `RepositoryVisibility` / `WholeFileChange` / `ApprovalBinding` / `DiscoveryRoot` / `ExemptionSurfaceKind` / `WriteRecordSource` / `InstalledLedger` / `LedgerSuccession` / `LedgerViolation` / `RepositoryProfileObservation` / `RootEntryDeclaration` / `RootEntriesVerdict` | Typed contracts for the sections above. |
 
 ## Doctor
 
@@ -247,7 +432,67 @@ session needs: a resolvable `package.json` plus `package-lock.json` pair,
 an `AGENTS.md` that mentions `clossys/`, and a hub marker at the same
 relative path as the packed template `skeleton/clossys/.state/workspace.json`.
 It never runs `npm ci` itself and never mutates anything; it only reports
-which of the three is missing.
+which of the three is missing. A launcher run in the hub writes nothing
+into a product repository, so until the repository is staffed in an approved
+plan and that plan's setup pull request merges, an unsatisfied
+`agents-pointer` check is the expected state; its note says so.
+
+### Setup templates
+
+`renderSetupTemplate()` and the renderers beside it are pure functions that
+return the exact bytes of the files a setup change writes. Nothing writes those
+bytes yet; a later step plans them into a change set. The renderers behind it
+are exported too: `renderStarterRequest()`, `renderAdoptionDecisionWorkflow()`,
+`renderProductCiWorkflow()`, `renderAdoptionEvidenceWorkflow()`,
+`renderSnapshotCollector()`, `renderPathScopeWorkflow()` and
+`renderPathScopeScript()`, the standalone script the path-scope workflow embeds.
+A `TemplateResult` is either `{ ok: true, files }`, a list of `TemplateFile`
+entries (`path` and `bytes`), or `{ ok: false, refusal }` with a
+`TemplateRefusal`; the package manager is a `SetupPackageManager` and the Starter
+pin a `StarterPinInput`.
+
+There are four acts, each with a fixed file list that `renderSetupTemplate()`
+returns in this order:
+
+- `add-caller-workflow` takes `{ packageManager }` and returns
+  `.github/workflows/clossys-adoption-evidence.yml`,
+  `.github/workflows/clossys-adoption-decision.yml` and
+  `.github/scripts/clossys-collect-adoption-snapshot.mjs`.
+- `write-starter-request` takes a `StarterRequestInput` and returns
+  `.starter/request.json`.
+- `add-ci-template` takes no input and returns `.github/workflows/clossys-ci.yml`.
+- `add-path-scope-job` takes no input and returns
+  `.github/workflows/clossys-path-scope.yml`.
+
+The request is in the admission phase and names the Starter as both its own
+engine and its target, and it names both evidence paths, the assessment file
+and the target-input file. It carries no advisor and no hub. The Starter pin must be an exact version in `>=0.2.0 <0.4.0`
+(`STARTER_PIN_RANGE`); any other pin is refused as `starter-pin-unsupported`,
+and a package manager other than npm or pnpm, Yarn included, is refused as
+`package-manager-unsupported`. A refusal names a position such as
+`starter.version` and never quotes the value it refused.
+
+The decision workflow starts only on `workflow_run` completion of the evidence
+workflow, and its job carries no condition, so it starts for every conclusion.
+It checks out the protected pull request base, runs one fixed frozen install
+(`npm ci --ignore-scripts` or `pnpm install --frozen-lockfile --ignore-scripts`),
+and runs the installed Starter's `admit` command over a sparse checkout of the
+`workflow_run` head that holds only `/clossys/.state/installed.json`. The
+trusted decision job never reads or trusts the snapshot artifact the evidence
+workflow uploads, because a pull request controls that workflow. The collector
+script is still written because the contract's file set for the caller
+workflows names it.
+
+The path-scope job applies to pull requests whose head branch starts with
+`clossys/apply-`, and fails when a changed path is outside the paths Clossys may
+own (`OWNED_PATH_PATTERNS`) or, apart from the ledger, `package.json` and the
+lockfiles, is not named by the pull request's own ledger. It runs in the pull
+request's own context, so it catches an agent's mistakes, not a hostile author;
+the admission job runs from the protected base.
+
+A change to any of these workflows, or to `.starter/request.json`, is proved
+only by the first pull request after it merges, because the decision runs from
+the base: a one-merge lag.
 
 ## Inventory: adopting an existing source
 
@@ -277,8 +522,8 @@ presence of `.agents/skills` itself, since Codex reads repository skills
 from that path directly and needs no separate discovery link (verified
 against developers.openai.com/codex/skills, 2026-09-22). The snapshot is
 written to `clossys/.state/hosts.json` (`HOSTS_REL`, via
-`serializeHostRecord()` / `parseHostRecord()`) for the hub and for every
-sibling clone launcher composes skills into -- so a consumer such as
+`serializeHostRecord()` / `parseHostRecord()`) for the hub, the one checkout
+a launcher run composes skills into -- so a consumer such as
 Advisor's next-action phrasing can name the client's actual tool instead
 of guessing.
 
@@ -302,21 +547,1039 @@ tier cannot be met.
 `launcher-apply-plan --plan <plan.json> --brief <brief.json> --repo <dir>`
 writes `clossys/brief.json` into a staffed repository once the plan is
 approved (#1178). `validateAdvisorPlan()` and `validateEngagementBrief()`
-check both files against the exact shapes recorded on issue #1175's "Plan
-file contract"; `isPlanApproved()` reads a plan's most recent decision (by
-timestamp, not array position) and requires it to be `"approved"` --
-absence of any decision is never treated as approval.
-`applyEngagementBrief()` refuses, and writes nothing, unless both checks
-pass, then writes the brief byte-identically -- it never re-authors its
-prose. This package does not compute a brief's content (that is
-`@clossys/advisor`'s `EngagementBrief`, landing in #1193) and does not
-decide whether a plan should be approved (that is Advisor's job); it only
-validates the two landed shapes and writes the one file. Multi-repository
-orchestration -- branch creation, exact package installs, adding Starter's
-caller workflow, and opening one pull request per repository -- is
-deferred: the landed contract does not yet specify how a plan's approved
-roles map to inventory repository ids or to install/remove/relocate work
-items.
+check both files against the shared contracts in this repository's
+`docs/contracts/` -- `advisor-plan.json`, `engagement-brief.json`, and
+`engagement-context.json` for the brief's `context` snapshot (#1475). This
+package's build packs those files, with a copy of the one contract checker
+`@clossys/advisor` uses, so Launcher and Advisor accept exactly the same
+plans and briefs while Launcher keeps no runtime dependency on Advisor.
+Every object is closed: a field the contracts do not declare is refused,
+and a known context value must be one of that field's fixed choice ids,
+because the brief is committed in every staffed repository. A string or
+key containing a lone surrogate is refused, so every plan that validates has
+a digest. Every plan time must be a real calendar date or date-time in
+ISO 8601 form, a date-time with `Z` or a `±hh:mm` offset, checked
+field by field (so `2026-02-30` or `T24:30` is refused). A brief's
+`problem`, `role`, `why` and `metric` must contain a non-whitespace
+character, and an item of `inputsFrom`, `outputsTo`, `sequence` or
+`deliverables` must not be empty. A refusal names each declared field at
+fault and never echoes its value, and never names a key the contracts do
+not declare: such a field is reported at the object that holds it, by its
+1-based position there (`plan.mandate has a field the contract does not
+declare (key 4 of this object), and unknown fields are refused`), counted
+in the order the file wrote the keys when `launcher-apply-plan` reads it; a
+value a caller passes to a validator directly is counted in JavaScript's
+own key order, which lists array-index keys such as `"7"` first.
+`launcher-apply-plan` reads both files as strict JSON: bytes that are not
+valid UTF-8, a leading byte order mark, or an object that repeats a key at
+any depth exit `2`, with a repeated key reported by its position in its
+object and, below the top level, that object's position, never by name,
+and a syntax error by position only, never quoting the file's text, so the
+value validated is exactly the one a reader of the file sees. A position is
+a 0-based index into the decoded text in UTF-16 code units (JavaScript's
+string index): the byte offset for ASCII text, with a character outside
+the Basic Multilingual Plane counting as two.
+A plan may say which roles work in which repository (`staffing`, by
+repository inventory id), which kits were recommended (`kits`), which exact
+package acts are authorized (`packages`, each one exact version and one
+`sha512-` integrity value) and where those versions were resolved from
+(`resolution`) (#1178). Once the schema passes, the contract's code rules
+run: no repository is staffed twice (ids compare case-insensitively),
+every staffed role is one of the mandate's roles and every mandate role is
+staffed somewhere unless it is a hub-only role, every
+package act names a staffed repository spelled exactly the same, no
+`planItem` repeats, no package appears twice in one repository,
+`resolution` is present exactly when `packages` is, no kit id repeats, no
+role repeats within one staffing entry, no role is named twice in
+`mandate.roles`, a repository has at most one `pin-starter` act, always
+placed in `devDependencies`, no hub-only role is staffed, and every
+`planItem` is exactly its act's `repository`, a colon and its `name`, in the
+same letter case (R12). The hub-only
+roles, Advisor and Integrator, are read from the plan contract's
+`definitions.hubOnlyRoles`, the same data Advisor reads. The rules read only a document's own fields,
+as the schema does, so an inherited one is ignored. A brief's optional `staffedHere`
+must name only the brief's own roles, each once. This package implements
+those rules separately from Advisor, and both are tested against the same
+corpus, `docs/contracts/advisor-plan-rules.fixture.json` (in the public
+repository, not shipped in this package).
+`approvedSubject()` says what an approval binds: the `subjectDigest` of the
+plan's most recent decision (by timestamp, not array position) when it is
+`"approved"`. It validates the plan itself first and returns null for one
+that does not validate. An approval with no `subjectDigest` binds nothing,
+and so does no decision at all, a decision time that does not parse, or a tie at
+the latest instant between decisions that disagree or name different
+subjects. It says what was approved, not that it matches: a caller must
+recompute the digest of the change it holds and compare.
+`isPlanApproved()` reads the same most recent decision and is true when it
+is `"approved"`, with the same rules for ties and unreadable times, but it
+binds no bytes: it ignores `subjectDigest`, so it is also true for an
+approval that names no change. Anything that applies a plan must use
+`approvedSubject()` instead.
+`applyEngagementBrief()` and `launcher-apply-plan` are the brief-only path,
+which predates that binding and is kept as it was, not extended: they
+require `isPlanApproved()` and accept an approval with or without a
+`subjectDigest`, checking no binding.
+`applyEngagementBrief()` refuses, and writes nothing, unless all three
+checks pass and the plan's digest is computed; only then does it write the brief byte-identically -- it never re-authors
+its prose -- and reports `planDigest()` of the plan it applied, which the
+CLI prints as `plan digest sha256:...`. That digest is defined once, in
+`docs/contracts/advisor-plan-digest.md` (in the public repository, not shipped in this package);
+this package and Advisor each
+implement it and are tested against the same fixture corpus. On this
+brief-only path, this package does not compute the brief's content -- it
+writes the brief it is given, which `@clossys/advisor`'s
+`toEngagementBrief()` builds, and applies no per-repository projection --
+and it does not decide whether a plan should be approved (that is
+Advisor's job); it only validates the two shapes and writes the one file.
+The apply planner below is different: it projects each repository's brief
+from the hub brief itself.
+
+Launcher's packed skill carries the agent procedure that puts a stored change
+set into a staffed repository, under "Apply an approved plan" (#1762). The
+agent verifies, files the task-record issue, prints the pull request body with
+`launcher-apply-plan body`, commits and pushes only the set's `clossys/apply-`
+branch, opens the pull request, reads `launcher-apply-plan status`, and reports.
+Launcher never pushes, opens a pull request, files an issue or merges, and the
+procedure forbids merging and enabling auto-merge. `check-package-skills` pins
+each of those rules in the packed skill text.
+
+### Release-age exemption
+
+`editReleaseAgeExemption()` computes the edit that lists the publishing
+scope's `<scope>/*` entry as exempt from a package manager's release-age
+delay (#1178). It is pure: it does no I/O. It takes a surface
+(`pnpm-workspace` or `yarnrc`), the surface file's text or `null`, and, for
+pnpm, the `.npmrc` text or `null`. It returns `edited` with the exact new
+text, `unchanged` when the scope entry is already listed, or a refusal
+(`ReleaseAgeEdit`, with `ReleaseAgeEditInput` and
+`ReleaseAgeEditRefusalReason`).
+
+The entry goes under `minimumReleaseAgeExclude` (pnpm, single-quoted) or
+`npmPreapprovedPackages` (Yarn, double-quoted). A missing file becomes the
+key alone, a top-level block sequence of scalars gets one new entry after
+its last item, and a file without the key gets the key appended. Other
+bytes, including comments and the final newline, are kept. The function
+reads only the shapes it recognises: `release-age-surface-unparseable` covers
+a flow sequence, an anchor, an alias, a tag, a comment inside the list,
+several documents, a tab, a carriage return or byte order mark, a repeated
+key, and a value that is not a block sequence of scalars.
+
+For pnpm the `.npmrc` is read under a fixed grammar and refused otherwise.
+Every line must be blank, a comment (first non-space character `#` or `;`),
+or a plain `key=value` assignment, optionally spaced around the `=`, whose key
+is only ASCII letters, digits and `@ : _ . / -`. An `.npmrc` containing any
+line outside those shapes (a quoted or bracketed key, a comment or escape
+inside the key, a tab, a section header, a key with no `=`) is refused as
+`release-age-surface-unparseable`, because npm's ini reader could read such a
+line as the exclusion setting. A plain key that is `userconfig`,
+`globalconfig` or `prefix` (in any case, with `-` and `_` ignored) is refused
+the same way, because it points npm at another config file or prefix
+directory whose own exclusion list the editor cannot read. A plain key that is
+`minimum-release-age-exclude` in any case, with `-` and `_` ignored (so the
+camel-case spelling too), is refused as `release-age-surface-conflict`.
+Refusing is the default: an unrelated `.npmrc` line the grammar does not list
+also refuses the whole file, and the caller resolves the file by hand.
+
+`verifyReleaseAgeExemption()` takes the surface, the text before, the text
+after, and, for pnpm, the `.npmrc` text. It reports a `ReleaseAgeVerdict`, `{ verified: true, value }`
+(its input is a `ReleaseAgeVerifyInput`), only when the two texts differ by that one added entry, read again with the
+same rules; `value` is the `<scope>/*` string the installed-state ledger's
+`entries` row holds. It returns `{ verified: false }` for an unchanged file
+(`before` equal to `after`) and for any `.npmrc` that is a conflict or outside
+the grammar above, so a wiring unit must not verify after an `unchanged` or
+`refused` result. It says nothing about whether a given pnpm or Yarn
+version honours the key; that is proved separately with pinned tools.
+
+### Computing each repository's change
+
+`planApplyBundle()` computes, for each repository a plan staffs, the change
+set one pull request would make there, and a bundle that holds them (#1178).
+It is pure: it takes the plan, the hub brief (`clossys/advisor/brief.json`),
+what the caller observed on each repository's default branch (including the
+exact bytes of its installed-state ledger and its composed-skill manifest),
+the change sets the hub holds, the composed skill text for each role and for
+Advisor, this package's version and the hub's Advisor and Integrator pins,
+and it reads nothing itself. The shapes are the shared contracts
+`docs/contracts/repository-change-set.json` and `apply-bundle.json`, packed
+into this package, and every set and the bundle are validated against them,
+code rules included, before they are returned. The digests are defined in
+`docs/contracts/apply-change-set-digest.md`, with a corpus computed
+independently of this package (both in the public repository, not shipped
+in this package).
+
+- Each set describes the repository's brief, projected from the hub brief with
+  `staffedHere` set to its roles and, unless the repository is private, the
+  brief contract's fixed placeholder in place of the client's problem. It
+  composes the Advisor voice together with each staffed role's voice (D33;
+  `staffedHere` still lists the staffed roles only), and holds each of those
+  skills, a discovery link to it under
+  `.claude/skills` and `.cursor/skills` (none under a root the default
+  branch has as a symbolic link), and `clossys/.state/skills.json` listing
+  the skills it writes. It carries every package act the plan names for
+  that repository, the hub's exact Integrator pin, and names the
+  installed-state ledger as a derived file. No act the plan authorizes is
+  dropped and no other act is added. An act the default branch already
+  satisfies exactly is kept with `satisfiedInBase: true` and writes nothing.
+- Each set also writes the Launcher's guide, an `AGENTS.md` file inside
+  `clossys/`, which covers `clossys/` and the `clossys-*` skills (`agents-guide` item, write-record
+  source `agents-guide`, bound by code rule C9 to that one path). Its bytes are
+  the constant `AGENTS_GUIDE_TEXT`, the same for every repository: it says that
+  `clossys/` and the `clossys-*` skills (`.agents/skills/clossys-*`,
+  `.claude/skills/clossys-*`, `.cursor/skills/clossys-*`) are Launcher-owned
+  and are not edited, renamed or duplicated, and that the repository's own
+  skill policy carves that namespace out. Ownership is the ledger row's digest
+  of the whole file, like any other whole file, with no marker inside it: an
+  existing guide file the ledger does not record is refused as
+  `unowned-existing`, and only a setup set adopts one whose bytes are already
+  exactly the guide. A repository set up before the guide existed has neither
+  a ledger row nor a file there, so an apply set adds the guide. The planner
+  adds it only where the trusted ledger has no row for it and nothing, file or
+  directory, is at its path in any letter case. Admission accepts that one
+  add and no other only where the setup set wrote no guide and the base tree
+  at the set's base commit holds nothing at its path in any letter case. The
+  ledger's succession rule S3 reads the two ledgers, not the tree: it accepts
+  the one new row only where the base ledger has none at that path, with mode
+  `100644` and the digest of `AGENTS_GUIDE_TEXT` as its `after`.
+  `verify` compares the head's bytes with the set's digest
+  and with `verifyAgentsGuide()`; any difference is `diverged`, and `status`
+  reports it as `agents-guide-mismatch`, printing only that token and the pull
+  request number, never file text. The repository's own root `AGENTS.md` and
+  `CLAUDE.md` are not touched. A follow-up will append one fixed pointer line
+  to the root `AGENTS.md`, only when it is absent, and never rewrite the
+  file.
+- A skill under a symbolic link on the default branch (`.agents`,
+  `.agents/skills` or the role's own skill directory) is refused as
+  `skills-root-is-link`: the planner never writes through a link.
+- A repository in the `setup` phase gets a setup set, which the change-set
+  contract requires to carry exactly one item for each of four setup
+  templates (`caller-workflow`, `starter-request`, `ci-template` and
+  `path-scope-job`), the plan's one Starter pin, and, for pnpm, one
+  release-age exemption. The template bytes come only from
+  `renderSetupTemplate()`; the template patterns join `pathAllowList` before
+  any template file is written, and the Starter request takes the package
+  manager, the repository id and the plan's pin and nothing else. A template
+  file the base does not have is created; one it has is adopted only when its
+  bytes are exactly the set's own, and is `unowned-existing` otherwise.
+  Adoption follows the same compare-and-swap table as any whole file, and is
+  the one place the generation-0 adoption pass runs: a composed skill is
+  adopted only when the base's skills manifest records the digest of its
+  bytes. The plan's `pin-starter` act is the set's Starter pin. Every
+  `install` act goes to `deferred` with the reason `after-setup`: it gets no
+  item, no key and no lockfile invariant, and is written by the apply set
+  that follows.
+- For pnpm, a setup set carries one `exempt-release-age` item, with the fixed
+  item id `release-age`, for the pnpm workspace file. Its text comes only from
+  `editReleaseAgeExemption()`, over the exact text of `pnpm-workspace.yaml`
+  and of `.npmrc` that the observation carries. An edit is a whole-file write
+  whose `before` is the digest the base has (or null, when the file is
+  created); an entry the file already lists gives the item and no file; a
+  file the editor will not read, or one whose `.npmrc` sets the same list,
+  gives a path refusal with the editor's reason
+  (`release-age-surface-unparseable`, `release-age-surface-conflict`) and a V6
+  `indeterminate` check with the same rule. A directory at the file's path is
+  refused as unparseable. An apply set carries the same item, with no file,
+  when its trusted ledger records that entry, so that it matches the setup
+  set item for item. npm has no exemption key, so an npm set has no item.
+- A repository is skipped, `indeterminate` and outside the bundle digest,
+  with a reason of its own, wherever a setup set cannot be computed safely:
+  `package-manager-unsupported` (neither npm nor pnpm), `starter-pin-absent`
+  (the plan names no single Starter pin there), `starter-pin-unsupported`
+  (a pin outside the templates' range, `STARTER_PIN_RANGE`),
+  `starter-request-invalid` (a request the renderer refuses, such as a
+  repository id that is not `owner/name`), and `release-age-text-absent` (a
+  pnpm repository whose workspace file or `.npmrc` is there and whose exact
+  text the observation does not carry). An apply set whose Starter pin would
+  write a key is skipped as `starter-request-stale`, because the request a
+  setup set wrote would then name another pin and an apply set does not
+  rewrite it. The planner throws if the text an observation carries is not
+  the file its `files` digest.
+- The planner reads the repository's installed-state ledger at the base
+  and trusts it only through change sets the hub holds (see
+  `trustInstalledLedger()` above): every generation must be a held set whose
+  digest recomputes and that agrees with its history entry, and every row a
+  write of the set it names. A ledger that fails skips the repository,
+  `indeterminate`, with the trust rule as its reason (`ledger-unreadable`,
+  `identity`, `renamed`, `ledger-chain` or `ledger-foreign-row`), outside the
+  bundle digest. No ledger is generation 0. The set's `ledger.generation`
+  comes from the trusted ledger.
+- Each file the set writes whole is computed by compare-and-swap against
+  the trusted ledger's row at its path: with no row, an absent path is added
+  and a present one is refused as `unowned-existing`; with a row, a base that
+  still holds the row's bytes is kept (`before` equal to `after`) or updated,
+  a base with other bytes is refused as `client-edited`, and an absent one as
+  `deleted`, never folded into an update; other paths still proceed. Taking
+  over a present file with no row (the generation-0 adoption pass) is
+  allowed only in a setup set, never in an apply set. A `package.json` key
+  follows the same table against the ledger's key row; a key whose row, base
+  value and desired version agree while the lockfile does not resolve that
+  version and integrity skips the repository as `integrity-mismatch`,
+  `violated`, and is never repaired. The lockfile and the ledger are derived
+  files, checked by their invariants, and are not refused this way.
+- In an apply set, each setup template whose files all have ledger rows is
+  carried as a no-op item, one keep entry per file (or `client-edited` /
+  `deleted`); a template with only some of its files in the ledger skips the
+  repository as `template-rows-partial`. A set edits the Controller repository
+  profile: when the observation carries
+  its text and the edit is stable, a `declare-root-entry` item adds each root
+  name the set introduces and the vocabulary lacks, as an allowed extension,
+  changing nothing else in the profile (`editJsonPointer`, the same editor
+  materialize uses for `package.json` keys). When that text is absent, the
+  repository is skipped as `root-entry-edit-unbuilt`. A profile it cannot read
+  (`root-vocabulary-unknown`), or one that prohibits a root name the set
+  introduces (`root-entry-prohibited`), gets the item refused instead; a
+  profile that already declares every name, or checks no root vocabulary,
+  gets no item.
+- A trusted row the desired state no longer names (a role no longer
+  staffed, a package act the plan no longer names there) is left in place,
+  and the set reports V8 `indeterminate` with rule `removal-unbuilt`: removal
+  sets are not built.
+- The change-set digest leaves out what is computed from it or from what it
+  covers -- the digest itself, the branch, the bundle digest, the pull
+  request text and the inverse set -- and `tooling`, which records the
+  machine, and `texts`, which holds whole-file bytes for materialize only.
+  It also leaves out a derived file's `before` and `after`, for two
+  different reasons: the ledger's bytes cite the digest, and a lockfile's
+  bytes depend on the package manager's version, so both are checked by
+  their invariants, which stay covered. Only those two files may be
+  derived. So a moved base, a different Launcher version, a visibility
+  change, a staffing change, different package bytes or a different ledger
+  generation is a new set, and recomputing any excluded value is not.
+- Every array whose order carries no meaning is written in one canonical
+  order, and the contract refuses any other order, so observing the same
+  repository twice, in any order, gives the same bytes and the same digest.
+  The contract's code rules also tie each kind of item the planner computes
+  to exactly what it writes; the acts nothing computes yet are declared but
+  not yet tied to their files.
+- The bundle digest covers only the plan digest and each computed
+  repository's id and change-set digest, so an approval can bind it and a
+  repository can recompute it from digests alone.
+- The planner's bundle `mode` is `report`, and it records no repository
+  state and no binding. The bundle contract also defines a `planned` mode,
+  where a repository that passed all nine pre-apply checks and is bound by an
+  approval is `planned`, with that binding; the `plan` command writes one
+  only when the hub's committed plan carries an approval that names a bundle
+  the hub holds (see the plan command below). The planner reports its
+  own dry-materialization check (V6), which covers the file
+  layout only: the part of V6 that regenerates the lockfile and checks its
+  invariants is not run by the planner, so a set that changes a lockfile carries V6
+  `indeterminate` with rule `lockfile-not-run`, and V6 is `satisfied` only
+  for a set with no lockfile change; the `plan` command replaces that entry
+  by running the rest of V6, and V9, in a temporary tree (see the plan
+  command below). A release-age path refusal adds V6
+  `indeterminate` with its reason as the rule. Compare-and-swap outcomes are reported under V8:
+  `unowned-existing`, `client-edited`, `deleted` and `removal-unbuilt` each
+  give V8 `indeterminate`, and a set with none of them gives V8 `satisfied`. Two V3 checks
+  need no observation: when the authorization names a different plan
+  digest than the plan's, every computed repository gets a violated V3
+  check (`authorization-plan-mismatch`), and when the plan has package acts
+  and no authorization is given, every computed repository gets a violated
+  V3 check (`authorization-absent`). Each repository's verdict is the worst
+  of its checks.
+
+What a setup set guarantees: it validates against the contract, every write
+is a compare-and-swap against the base, a file is adopted only by byte proof,
+template bytes come from the renderer alone, the Starter pin is one the
+templates support, and materialization and verification both prove that the
+release-age file is the base's bytes plus exactly the one scope entry. What it
+does not handle: root entries in a setup set (the apply set that follows is
+refused by admission because its items differ), lockfile regeneration and the
+provenance check (V9), which the `plan` command runs on a temporary tree, and
+a later change of the pin.
+
+Nothing here writes to a product repository, creates a branch or opens a
+pull request; the only files this part of the package writes are the hub's
+change-set and bundle stores (see the ledger section below). Reading the
+repositories, branch creation, exact package installs,
+adding Starter's caller workflow, and opening one pull request per staffed
+repository -- including the setup pull request that brings a staffed
+repository `@clossys-advisor` and the voices of the roles staffed there --
+are not built yet, so until it ships no Launcher command puts those voices
+into a product repository.
+
+### Observing a repository
+
+`observeRepository({ id, clone, hubOwner?, ports })` turns one local clone
+into the `RepositoryObservation` that `planApplyBundle()` takes, or into a
+skipped observation `{ id, skipped, verdict }` with a reason id. The input is
+an `ObserveRepositoryInput`: a bare `id` is qualified by `hubOwner`, and the
+`RepositoryObservationPorts` supply the two values a clone cannot hold
+(`nodeId` and `visibility`) and, optionally, `originId`, which maps an origin
+URL to `owner/name`.
+
+```ts
+const observed = await observeRepository({
+  id: "acme/site",
+  clone: "/work/site",
+  ports: { nodeId, visibility },
+});
+if ("skipped" in observed) console.log(observed.skipped, observed.verdict);
+```
+
+- The rule: only this repository's own object database and refs are read,
+  through git plumbing, never the working tree and never an alternate object
+  store, `commondir` or submodule repository; anything unusual is refused,
+  not interpreted. What the object database holds is trusted to match its
+  ids: an observation is the committed head as the clone's object database
+  stores it. Every field is read from git objects at the default-branch
+  head; a file's digest is that of its bytes read as UTF-8 text, as
+  materialization computes it (a symbolic link's digest is the digest of its
+  target). Nothing is written to the clone: the remote tip is read with
+  `git ls-remote` run outside the clone, and the default branch comes from
+  the remote's `HEAD`.
+- The committed tree is listed first, and a submodule is refused
+  (`submodule-present`), before any command that reads the working tree runs;
+  `git status` never considers a submodule, because git would open the
+  submodule's own repository and read its configuration.
+- A clone is refused, not observed, when its directory is missing
+  (`clone-missing`, `indeterminate`); when its `origin` is another repository;
+  when its tree is dirty or has untracked files not ignored, or a tracked file is marked
+  skip-worktree or assume-unchanged; when its local head differs from the
+  remote tip; when it reads objects from another store
+  (`objects/info/alternates`); when its git directory holds a split index's
+  shared file (`sharedindex.*`), which git rewrites on every index read, so
+  observing it would write to the clone (`clone-config-unsafe`); or when `.git/config` holds a key outside a
+  short fixed list (`violated`). The config is read as data, so a filter,
+  hook path, pager, `fsmonitor` or alias entry is refused rather than run.
+- The default origin parser names only an exact `https://github.com/` or
+  `ssh` GitHub URL, and only those two transports fetch; an `originId` you
+  supply is the only way a local path is fetched. git is run from an absolute
+  path found among the absolute, non-empty `PATH` entries, never by a search
+  of the clone's own directory.
+- `files` lists whatever the head holds at a path the apply flow may write: a
+  file, a symbolic link, or, for a directory, each file under it, so a
+  directory where a link belongs reads as occupied. Root entries that differ
+  from `clossys`, `.agents`, `.claude` or `.cursor` only by letter case,
+  Unicode form or a trailing dot, and two spellings of `.github` or
+  `.starter`, are refused (`case-variant-owned-path`); a `consumerCi` workflow
+  is a regular file spelled `.github/workflows/`. A regular `.npmrc` is listed
+  as well, though the flow never writes it, because a pnpm setup reads it.
+- `pnpmWorkspaceText` and `npmrcText` are the exact UTF-8 text of
+  `pnpm-workspace.yaml` and `.npmrc` at the head, or null when the file is
+  absent or is not UTF-8; the planner reads a release-age exemption only from
+  them, and throws when one is not the file `files` digests.
+- `nodeId` and `visibility` come through the injected ports; a port that
+  throws or returns a malformed value is `indeterminate`.
+- `phase` is `apply` only when the base has a valid installed-state ledger,
+  every setup-template path is a regular file at the head, and
+  `manifestEntries` pins `@clossys/starter` at an exact `0.2.x` version, the
+  range the setup templates support (the templates' own predicate; `0.1.9`
+  and `0.4.0` read as `setup`), for which its lockfile has a row of that name
+  and version, not an alias (an `npm:` alias,
+  or another package under its name, is refused as `lockfile-unreadable`; the
+  host and integrity are the planner's to check); otherwise it is `setup`.
+- git runs without hooks, `fsmonitor` or a pager, and every tree, blob and
+  output read has a size bound. git inside the clone reads no configuration
+  but the vetted `.git/config` and fixed `-c` overrides: the system and
+  global configuration are switched off, and `GIT_CONFIG_COUNT` and its
+  key and value variables, `GIT_CONFIG_PARAMETERS`, `GIT_CONFIG_SYSTEM` and
+  `GIT_ATTR_SOURCE` are removed. `git ls-remote`, which runs outside the
+  clone, keeps the operator's global and system git config files (credential
+  helpers, proxy) and is given `GIT_CONFIG_COUNT`, `GIT_CONFIG_KEY_n` and
+  `GIT_CONFIG_VALUE_n`, so an origin that needs credentials supplied through
+  them is observed; a fixed `-c` override and `GIT_ALLOW_PROTOCOL` still win
+  over them. `GIT_CONFIG_PARAMETERS` (git's internal encoding of `-c`, not an
+  interface) and `GIT_CONFIG_SYSTEM` are not forwarded to it, so an origin that
+  needs either is skipped as `remote-tip-unreadable`. git's own `GIT_TEST_*`
+  switches (`GIT_TEST_SPLIT_INDEX` among them) reach no git command.
+
+| Verdict | Skip reasons |
+| --- | --- |
+| `violated` | `invalid-id`, `clone-config-unsafe`, `origin-mismatch`, `not-on-default-branch`, `remote-tip-mismatch`, `working-tree-dirty`, `package-manager-conflict` |
+| `indeterminate` | `clone-missing`, `clone-unreadable`, `id-owner-unknown`, `remote-tip-unreadable`, `node-id-unavailable`, `visibility-unavailable`, `tree-too-large`, `submodule-present`, `manifest-unreadable`, `lockfile-ambiguous`, `package-manager-unknown`, `lockfile-unreadable`, `release-age-surface-invalid`, `agents-link-unreportable`, `observation-too-large`, `case-variant-owned-path`, `ledger-unreadable`, `profile-ambiguous` |
+
+What it does not decide: it reports what the committed head holds, not
+whether applying is safe. The checks (configuration, head, index, status)
+and the reads run one after another and are not repeated; the clone is not
+locked. A process that changes the clone between a check and a read is not
+detected, and cannot be detected by checking again, since any later check
+has the same gap, and a process that can write the clone's `.git` can
+already plant a hook or filter that the operator's own git would run. What
+the observation reports is unaffected: every byte comes from an object at the
+remote tip's commit, which a later commit, checkout or edit in the clone does
+not change, so an observation states what that commit held, not that the
+clone stayed clean after it was checked. Object contents, and links inside
+`.git/objects`, are trusted to match their ids. Ignored files at owned paths
+read as absent (`base-mismatch` catches them); a symbolic link at `.github`,
+`.starter` or `clossys` is unreported here and refused by materialization
+(`symlink-ancestor`); conversion attributes (`eol`, `ident`, LFS) end in
+`base-mismatch`; lossy UTF-8 digests can collide, as in materialization; a
+clone clean only through a custom global `core.excludesFile`, or one that
+needs `safe.directory`, is refused, which fails closed. Ownership and trust
+are the planner's judgement, and so is whether the pinned Starter version implements the
+request beyond that template range.
+It is not a check of Windows short names or other alias spellings beyond case
+and Unicode-normalization folding, and which root names a particular set
+creates is the planner's contract check; the observation reports over
+`clossys`, `.agents`, `.claude` and `.cursor`, and, for a repository in its
+setup phase, `.github`, `.starter` and, for a pnpm repository whose workspace
+file the exemption edit will create, `pnpm-workspace.yaml`.
+
+### The installed-state ledger
+
+Every change set names `clossys/.state/installed.json` as a derived file:
+the ledger of what the apply flow wrote in that repository, one generation
+per merged change set (#1178). Its shape, its code rules, the bytes a
+change set's generation renders to, and the succession rules are the
+shared contract `docs/contracts/installed-ledger.json`, with a corpus
+computed independently of this package (both in the public repository, not
+shipped in this package). This package validates a ledger against it
+(`validateInstalledLedger()`), compares a pull request's ledger with its
+base's from their exact bytes (`ledgerSuccession()`), and gives a valid ledger its exact bytes
+(`serializeInstalledLedger()`), reads one strictly from its bytes, a `Uint8Array`,
+(`readInstalledLedger()`), renders the next generation a change set writes
+(`renderInstalledLedger()`), and decides whether a ledger may be trusted
+against the change sets the hub holds (`trustInstalledLedger()`). Nothing
+here reads a ledger from a repository: the caller hands its bytes in.
+
+- Each generation records the change set that wrote it and its binding:
+  `approved`, with the digest of the bundle the founder approved (which
+  may be an earlier run's bundle than the one the set was computed in), or
+  `admitted`, for the apply set that follows an approved setup set under
+  one approval, naming that setup set. An admitted generation must come
+  right after its setup generation, from the same plan and the same
+  approved bundle.
+- No string in a valid ledger is plan or brief text: a `planItem` is exactly
+  the repository id, a colon and the package name, a role appears only as a
+  lowercase id token in a skill path, and a root entry is one of the fixed
+  names the flow's own paths can introduce.
+- A valid ledger is a claim, not evidence. `trustInstalledLedger()` trusts
+  it only when every generation is a change set the hub holds, valid and
+  self-verifying, agreeing with its history entry, and every row is a write
+  of the set it names; one row it cannot account for refuses the whole
+  repository, because rendering the next generation would carry that row
+  forward.
+- `renderInstalledLedger()` gives the bytes of the generation a change set
+  writes over the previous ledger, and refuses a set computed from another
+  generation or for another repository, and an apply set that keeps a file
+  the previous ledger has no row for: an apply generation leaves the
+  ledger's files unchanged.
+- The hub keeps every change set and bundle it computes under
+  `clossys/.state/apply/change-sets/` and `clossys/.state/apply/bundles/`,
+  one file per digest (`storeChangeSet()`, `storeApplyBundle()`). A stored
+  change set is never replaced; a stored bundle is replaced atomically, and
+  only when the same `bundleDigest` is stored again, which covers the plan
+  digest and the change-set digests only, so only the authorization, verdict,
+  clock and mode fields can differ. A rerun replaces a stored bundle of the
+  same digest, planned or not, with one exception: a report-mode bundle never
+  replaces a stored planned one that verifies (`store-failed`), so an
+  approval-bound record is not downgraded by a run that lost the approval. A
+  stored file that does not verify is replaced. A read returns a file only
+  when its recomputed digest matches its name.
+- The succession rules compare what two ledgers claim, not the files: an
+  admitted generation must install exactly the packages its setup deferred
+  and change no other row (an apply set may also add the one guide row, for
+  the `AGENTS.md` file inside `clossys/`, with the guide's digest), but whether the pull request's
+  tree matches its ledger is a separate check.
+- For a reader without the hub, an `approved` head generation is an
+  unauthenticated claim, never an admission or a pass: a pull request
+  could relabel an admitted generation `approved` to escape the admission
+  rules. `ledgerSuccession()` therefore reports such a head as
+  `approval-claimed`, and `admitted` only for an admitted generation that
+  every rule proved. A caller that decides without the hub refuses an
+  `approval-claimed` head on an apply pull request, or treats the pull
+  request as one that needs the client's own review.
+- Each ledger is read from its bytes and must be exactly the bytes the
+  contract renders for it: a repeated key, a byte order mark or any other
+  spelling is refused (`bytes`), never read as an unchanged ledger.
+
+### Planning and the approval sheet
+
+`launcher-apply-plan plan` runs in the hub and takes no option beyond `--help`.
+It computes the apply bundle for the plan file in the hub's working tree, reports whether
+that exact file is the one committed at `HEAD` (the sheet's `Plan committed:` line), and prints the
+approval sheet a client reads before approving it (RFC section 12.7). It
+reads the hub only: `clossys/advisor/plan.json` and `brief.json`, the composed
+skill of each staffed role and of the Advisor voice, the stored change sets,
+the inventory (a staffed repository the inventory does not list is skipped as
+`not-in-inventory`), the exact `@clossys/advisor` and `@clossys/integrator`
+versions in `package.json` with their integrity from the lockfile (a range, or
+a version the lockfile does not hold, is refused), and the execution
+authorization committed in `clossys/advisor/assessment-input.json`, read as
+the blob at `HEAD` and never from the working tree. No blob, or no
+`engagement.executionAuthorization`, is no authorization; one that is not an
+object, or lacks a string `planDigest` or `expiresAt`, is refused. Each staffed
+repository is observed from its clone, a sibling of the hub, by
+`observeRepository()`, and `planApplyBundle()` does the rest. No option carries
+an approval or a binding. The result is a `planned` bundle only when the plan
+is the committed one and the hub's committed plan, read as a git object at an
+attached `HEAD`, carries an approving decision for this plan digest whose
+subject is a bundle the hub stores and verifies. Then each repository's V3 is
+decided by the admission check (`decideSetBinding()`, over the installed-state
+ledger at the set's base commit), and only a bound repository gets a binding:
+V3 `violated` (exit 1) or `indeterminate` (exit 2) with its fixed rule token
+gives none, and a repository whose V3 the bundle already marks violated is
+not admitted and spawns no readiness run. A repository with a binding and
+V1 to V9 all satisfied is `planned`; V1, V2, V4, V5 and V7 are recorded
+satisfied, V9 satisfied only for a set with no derived lockfile (a set that
+changes one keeps the dry tree's V9, and is not `planned` without it). An apply
+set names the bundle that will be recorded in the ledger, and admission needs
+that bundle stored, so the first run after a setup set merges stores it with
+V3 `indeterminate` (`apply-bundle-unrecorded`) and the next run admits it. The
+digests and the change sets are the same as in report mode. So is the sheet,
+apart from its `Mode:` line and, under `Checks not satisfied`, the V3 row of a
+repository the hub refuses (and the V9 row of a set that changes a lockfile, when
+the dry tree ran no provenance check), which only planned mode adds.
+
+It then stores the change sets and the bundle under `clossys/.state/apply/`,
+the only place it writes, and prints the sheet. Over unchanged inputs and an
+unchanged clock the sets, their digests and the bundle digest are the same on
+every run; the V6 and V9 checks stored with them come from the package manager,
+the registry and the Integrator, and the digest does not cover them. A rerun
+after the clock, the committed authorization or the result of a check changed
+keeps the same bundle digest, which covers the plan digest and the change-set
+digests only, and stores the newest computation under it: the one bundle file
+is replaced atomically, and the sheet is printed as before. Change sets stay
+append-only. Earlier computations under a digest are not recorded.
+
+```text
+Approve subjectDigest: sha256:<the bundle digest>
+
+| Repository | Kind | Item | Change | Digest |
+| --- | --- | --- | --- | --- |
+| example-owner/site | pin-starter | example-owner/site:@clossys/starter | @clossys/starter@0.2.0 | 3d2b4f88280d |
+| example-owner/site | compose-skills | skills | 10 paths | 3d2b4f88280d |
+```
+
+The sheet is ids and digests only: the bundle and plan digests, the mode, the
+authorization, one row for each item of each change set (`Change` is
+`name@version` for a package act, else a path count; `Digest` is the first 12
+hex digits of the set's digest), and then each deferred, refused or skipped
+entry by id or path and reason token. It carries no brief or plan prose, no
+stored text, no key value and no file contents. `renderApprovalSheet()` in
+this package builds it as a pure function of the bundle and its change sets,
+and refuses, by a fixed token that names no value, a set or bundle that does
+not validate, sets that are not exactly the bundle's, and any printed value
+that fails a strict pattern or holds `<`, `>`, a backtick, `|`, a carriage
+return or a line feed. Every refusal of the command is likewise a fixed token,
+printed as `launcher-apply-plan plan: <token>; nothing was stored`, except
+`store-failed` and an unexpected failure, which end without that clause because
+some of the sets may already be stored.
+
+Exit `0` when every repository is `satisfied`; `1` when any is `violated`;
+`2` when an input could not be read, the planner refused, or a repository is
+`indeterminate`. A bundle that was computed is stored and printed whatever the
+exit. A Starter pin or a package install changes a lockfile, whose
+regeneration (V6) the planner does not run, so the command dry-materializes
+each such repository before it prints the sheet. It reads the clone at the
+set's base commit through git's object database (`ls-tree` and `cat-file`; no
+checkout, worktree, index or ref is written), writes that tree and the set's
+changes into a directory of its own under the operating system's temporary
+directory, regenerates the lockfile there with the runner `materialize` uses
+(V6), and, only when that passes, runs the hub's provenance check (V9) on the
+same tree. The directory is removed before the command returns, whatever
+happened. A submodule, a link that could reach outside the tree, a link or file
+whose name a filesystem that folds case or normalization would read as a parent
+directory of another entry, a `..` or `.git` path segment or a tree over the
+size cap gives V6 `indeterminate` and launches nothing. A base file whose bytes
+differ from what the set names as its `before` gives V6 `violated`
+(`base-mismatch`), and set text whose bytes differ from its digest gives V6
+`indeterminate` (`change-set-invalid`). A failure of the dry tree gives V6
+`indeterminate` with rule `dry-tree-failed` for that repository only, and V9 is
+then `indeterminate` with rule `lockfile-not-regenerated`. Only V6 and V9 change: the sets, their
+digests and the bundle digest do not. A repository that has a refused path or
+key, or another check that is not satisfied, is not dry-materialized. No rule
+carries tool output, a path or an id. The tool version of pnpm and Yarn is not
+supplied, so a repository that uses one stays `indeterminate`. Supersede is
+not part of this command.
+
+### Materializing and verifying a change set
+
+`launcher-apply-plan materialize --repo <id>` writes a stored repository
+change set into that repository's local clone on the branch the set names,
+including the installed-state ledger. `launcher-apply-plan verify --repo <id>`
+re-reads the clone and reports whether the working tree still matches the
+set. Both commands are step 3 in
+[`docs/rfcs/apply-approved-plan.md`](../../docs/rfcs/apply-approved-plan.md)
+(section 11); a successful verify corresponds to the `materialized` row in
+section 4.4 of that RFC.
+
+### What authorizes a write
+
+`materialize` and `verify` decide, from the hub alone, on whose authority a
+change set is written, and record exactly that in the ledger; no flag, option
+or default supplies it. The decision reads the plan committed at the hub's
+current branch head (an uncommitted edit to `clossys/advisor/plan.json` is
+ignored, and a detached head refuses), the latest approving decision's
+subject digest, the stored bundle with that digest, and the stored change
+sets.
+
+- **Approved.** The set is a member of that bundle, by repository id and
+  change-set digest, and its plan digest equals the plan's. The ledger
+  records `approved` with the bundle's digest.
+- **Admitted.** An apply set that is not a member is admitted, with no second
+  approval, only when all of the following hold: it has the same plan digest
+  and the approving decision is still the latest; its package acts equal the
+  setup set's by plan item, it defers nothing, has the same `producer`, and
+  every whole-file entry is a no-op except the Launcher guide's add (the
+  `agents-guide` item and its file, before null and after the guide's digest,
+  only where the setup set wrote no guide and the base tree at the set's base
+  commit holds nothing at its path in any letter case); and the base's
+  trusted ledger ends with
+  that setup set, bound `approved` to the same subject, with every byte the
+  setup set wrote present in the base by content, so a squash or rebase merge
+  is admitted. The setup set must itself be a member of the approved bundle,
+  and the ledger the set would write must pass the succession rules as an
+  admitted generation.
+- **Otherwise** the step reports `indeterminate` with reason
+  `awaiting-approval` and a fixed detail token, and writes nothing.
+
+The hub's head must be its branch's upstream. `readHubAuthority()` resolves
+`HEAD` once to a commit id, requires the attached branch's configured upstream
+to resolve to that same commit (local refs only, nothing is fetched), and reads
+the plan from that commit id. `HEAD`, its commit and its upstream are read by
+one `git rev-parse`, and the upstream must be a remote-tracking ref (under
+`refs/remotes/`). A branch with no upstream, an upstream that is a local
+branch, or one ahead of or behind it, is `indeterminate` with detail
+`hub-not-upstream`.
+
+A set with package acts also needs a current execution authorization: the
+hub's own `node_modules/.bin/advisor-execution-readiness` (never `npx`) runs
+against the committed `clossys/advisor/assessment-input.json` at the current
+instant, and the authorization must name the plan digest, the repository and
+every package act. The assessment is read at the commit id the plan was read
+from: a hub whose `HEAD` has since moved, detached, or stopped matching its
+upstream is `indeterminate` with detail `hub-head-moved`. A set with no package
+acts skips this step, so its hub head is read once, when the plan is read, and
+not checked a second time. The authorization's permitted packages must also
+equal the plan's packages, by name, version and integrity (each compared as one
+unit, so an empty name cannot stand in for another entry) with each distinct
+package listed once; an extra, a missing or a repeated
+entry is `violated` with detail `packages-not-exact`. Readiness's own answer is
+kept: not current is `violated`; unreadable, absent or failing to run is `indeterminate`. `materialize` checks
+before its first write, and `verify` checks again, so a withdrawn approval or
+an expired authorization fails `verify`.
+
+`readHubAuthority()` reads the committed approval, `planPackagesFor()` gives
+the plan's package identities for one repository, and `decideSetBinding()`
+returns the binding or an `AdmissionRefusal` (exit code, reason and a fixed
+detail token). `HubAuthority` is what `readHubAuthority()` returns: the plan,
+its digest, the approved subject, and `head`, the commit id the plan was read
+from. A `ReadinessRunner` replaces the process launch of the readiness executable, for
+tests.
+
+This proves that the bytes are those the committed decision names, or that the
+one-approval rule admits. It does not prove who committed the decision; the
+hub repository's branch protection governs that.
+
+### Rendering the pull request
+
+`renderPullRequest({ set, binding, taskRecord, supersedes? })` returns the title and body of
+the pull request for one stored change set, and `bodySha256`, which is
+`sha256:` and the hex SHA-256 of the body's UTF-8 bytes. It is a pure function
+of its inputs (`RenderPullRequestInput`: the set, the binding, the task record and the optional superseded numbers): it reads no file, runs no command and opens nothing. The
+title is exactly `set.pullRequest.title`, which must be `Clossys: apply plan `
+and the first 12 hex digits of the set's own digest.
+
+The body is LF only and ends in one LF. Its first line is the marker
+`<!-- clossys-change-set: sha256:<64 hex> -->`, and no other line is a marker.
+It then names the repository id, the phase, and the change-set, plan and bundle
+digests; the binding you pass (`approved` with its subject digest, or `admitted`
+with its subject digest and setup change set); one line per item, in the set's
+own order, with `name@version` for `install` and `pin-starter`; each deferred or
+refused entry by item id and reason code only; and a `## Task record` section
+that links `#<n>`. With `supersedes`, a list of distinct positive safe integers
+that are not the task record, it also writes a `## Supersedes` section before
+the task record, one `- #<n>` line for each number, ascending; without it, or
+with an empty list, the body is byte for byte what it was. It carries ids, act names, versions and digests only, never
+brief or plan prose, file contents, key values or paths.
+
+`readChangeSetMarker(body)` returns the digest only when exactly one line of the
+body is exactly the marker and the marker appears nowhere else, and `null`
+otherwise.
+
+It returns a `PullRequestText`, or a `PullRequestRefusal` whose
+`PullRequestRefusalReason` is a fixed token that names no id, digest or input
+text, for a set that fails `validateRepositoryChangeSet` or
+whose digest does not recompute, a malformed binding, an `admitted` binding on
+a setup set, a task record that is not a positive safe integer, a `supersedes` list that is
+not distinct positive safe integers other than the task record
+(`supersedes-invalid`), and any value it
+cannot prove safe to write (each must match its own strict pattern and hold no
+`<`, `>`, backtick, `|`, carriage return or line feed).
+
+It does not decide the binding: it shows what you pass, so pass the result of
+`decideSetBinding()`. It does not check that the task-record issue exists, and
+it cannot stop a pull request's body being edited after it is opened; keeping
+`bodySha256` and the marker is what lets a later step notice that.
+
+### Recording the body
+
+`launcher-apply-plan body --repo <id> --task-record <n> [--supersedes <n>]...`
+prints the body of the pull request for the repository's stored change set, and
+nothing else, then records the `bodySha256` of exactly the bytes it printed as
+the set's `pullRequest.bodySha256`. Open the pull request from that output.
+
+```bash
+launcher-apply-plan body --repo "<id>" --task-record 12 --supersedes 9
+```
+
+`<id>` is the repository's id, `owner/name`. It is quoted in the examples because
+an unquoted `<id>` pasted into a shell is read as a redirection; replace the
+whole quoted word with the id.
+
+The approval the body shows is what the hub decides at the time of the run, as
+`materialize` decides it, from the plan committed at the hub's HEAD: it is never
+an option or an argument, and a hub whose approval was withdrawn refuses with
+the same reason `materialize` gives, printing no body. If the hub stored a
+planned bundle for the set, that bundle must record exactly the same approval,
+or the run is refused as `binding-mismatch`. Each `--supersedes` is the number
+of the pull request of an older change set of the repository, once each and not
+the task record, and needs another change set of that repository in the hub's
+store (`supersedes-unfounded` otherwise). Every number is digits only.
+
+A set is bound to one body. Running `body` again with the same arguments prints
+the same body and changes nothing; a run that would produce another body is
+refused as `body-bound` and prints nothing, so the hash recorded for the set
+belongs to one body only; whether the pull request that was opened still carries
+that body is what `status` checks afterwards. Recording the hash replaces the one
+stored file of the set atomically, refuses a symbolic link, and changes nothing
+else in the set: its digest, its file name and every other member stay as they
+were.
+
+There is no command that undoes a binding, and no `--dry-run`. A `--task-record`
+or `--supersedes` number mistyped on a first run binds the set to that body, and
+every later run with other numbers is refused as `body-bound`; nothing in this
+package unbinds it. Check the numbers before running `body`.
+
+Hand the output to the pull request as a file, and open the pull request with
+`--body-file`, not with `--body "$(launcher-apply-plan body ...)"`: shell command
+substitution drops the final line feed, and the recorded hash covers it.
+
+Exit `0` prints the body and only the body. Exit `1` is a refusal and exit `2`
+is indeterminate or a usage error; each prints nothing on standard output and
+one line on standard error, `launcher-apply-plan body: refused (<reason>)`,
+`launcher-apply-plan body: indeterminate (<reason>)` or, for a usage error,
+`launcher-apply-plan body: usage: <the usage line>`, a fixed reason or the usage
+line and never an argument, a path or any tool output.
+
+### Observing the pull request
+
+`launcher-apply-plan status --repo <id>` reports what the pull request for the
+repository's stored change set is doing. It runs after the agent has pushed the
+branch and opened the pull request from the text `renderPullRequest()` returned,
+and it changes nothing: it asks GitHub three read-only questions (who is
+asking, which pull requests are open, and where the default branch is) with
+`gh api --method GET`, reads only commits that are already in the local clone
+through git, and never fetches a pull request's head, checks anything out or
+writes a file, an index or any ref but one. It needs a full clone: a partial
+(promisor) clone, such as a blobless or treeless one, is refused up front as
+`partial-clone`, before any object is read, because git would fetch what such a
+clone lacks. All its git calls also run with lazy fetch off, and each has a
+30 second limit, including those of the preconditions it shares with `verify`
+except the base-commit reads made by the hub admission, which have no limit. A
+read of a base blob inside `verify`'s own checks (a base lockfile, for one) that
+fails or times out is taken as an absent file, so `status` can answer `diverged`
+where `indeterminate` is the truer answer. The limit reaches those shared
+reads through the environment variable `CLOSSYS_LAUNCHER_GIT_TIMEOUT_MS`, which
+`status` sets for the duration of its own checks, one `status` call at a time in
+a process; set in a shell, the same variable also limits the git calls of
+`verify` and `materialize`, which set none. The one
+ref it writes is the one `verify` writes: the fetch of the default branch into
+its remote-tracking ref (`refs/remotes/origin/<default branch>`), which also
+leaves `FETCH_HEAD` and any new objects of that branch in the clone. It runs the
+hub's readiness executable as `verify` does.
+
+```bash
+launcher-apply-plan status --repo ./site-checkout
+```
+
+It prints one line, `launcher-apply-plan status: <state>`, then a fixed reason
+in parentheses and `#<n>` for each pull request it is about, and nothing else:
+never a body, a title, a login, a branch, a path or any tool output.
+
+| State | Exit | Meaning |
+| --- | --- | --- |
+| `proposed` | `0` | An open pull request carries this set's marker, was opened by the person running this, from and into the set's own repository, on the set's branch and title, its body hashes to the `bodySha256` that `body` recorded, and its head commit passes every check `verify` makes, including the ledger's exact bytes. |
+| `applied` | `0` | The default branch's tip is in the clone and holds every `after` and every key the set writes, however it got there, with no open pull request needed. |
+| `planned` | `2` | Neither. |
+| `diverged` | `1` | The pull request that carries this set's marker does not match it: a different base branch, branch or title, a body whose hash is not the recorded `bodySha256` (`body-mismatch`), a head that is not in the clone, or a head that fails a `verify` check. |
+| `superseded` | `2` | An older change set this hub stored for the repository has an open pull request. It outranks `proposed`, so it is also the state when this set's own pull request is open beside the older one. |
+| `indeterminate` | `2` | Something could not be read or trusted, with one of the reasons below. |
+
+When more than one applies, the first of `indeterminate`, `diverged`,
+`superseded`, `proposed`, `applied` and `planned` wins. A pull request whose
+body names the marker counts only when its author is the person running this
+and its head and base are both the set's repository; any other is
+`foreign-marker`. A body that has a carriage return, a marker that is not the
+whole of its first line, or a marker `readChangeSetMarker()` cannot read is
+`marker-malformed`. Any open pull request whose body names the marker word, from
+anyone, therefore makes `status` `indeterminate` (`foreign-marker`) until it is
+closed: closing the stray pull request is the remedy.
+
+Every reason `indeterminate` can carry:
+
+- The set and the clone: `change-set-absent`, `change-set-invalid`,
+  `repository-invalid`, `missing-clone` and `partial-clone` (a blobless,
+  treeless or other partial clone; use a full clone).
+- GitHub: `port-failed`, `port-malformed` and `too-many-open`. Only the first
+  page of 100 open pull requests is read, so a listing of 100 or more cannot be
+  shown to be whole and is refused.
+- The markers: `foreign-marker`, `marker-malformed`, `unknown-digest` (a digest
+  this hub never stored) and `duplicate-digest`.
+- The body: `body-unbound`, when the set has no `bodySha256` because `body` never
+  ran for it. Such a set is never `proposed` and never `diverged`; run `body`,
+  which records the hash, and open the pull request from its output.
+- Git, over commits already in the clone: `tip-not-local` (the default branch's
+  tip is not in the clone), `tip-unreadable` (the tip's tree could not be read),
+  `object-unreadable` (a corrupt, missing or unreachable object of the pull
+  request's head, or a git call that timed out on it) and `status-failed` (any
+  other failure, including a git call that timed out, a git that cannot run or
+  an unexpected error; nothing is guessed from it).
+- The clone, the hub and the admission, which `verify` needs and which are
+  judged before the pull request's own fields: a refusal there, of either exit
+  code of `verify` (for example `remote-tip-mismatch`, when the local default
+  branch is not the remote's), is `indeterminate` here, because it is about the
+  clone and not about the pull request. `verify`'s own reasons for an
+  unreadable tree, such as `status-unreadable`, `symlink-ancestor` and
+  `lockfile-format-unsupported`, appear the same way.
+
+`proposed` does not check the head's ancestry to the base commit, and nothing in
+this unit does: it checks the head's tree and the paths that differ from the
+base, as `verify` does, so a head built on a newer default branch that reverts
+it can look the same. A reviewer reading the pull request's own diff on GitHub
+is what would notice.
+
+`status` does notice a body edited after it was opened. It hashes the body of
+this set's own pull request, as GitHub returned it, with no trimming and no
+change to line endings or the final line feed, and `proposed` needs
+`sha256:` and the hex SHA-256 of its UTF-8 bytes to equal the set's
+`bodySha256`. An appended line, a missing final line feed, a trailing space or
+a character that is not well-formed UTF-16 is `diverged` (`body-mismatch`). The
+body is checked after the base branch, branch and title and before the head, so
+the first of those that differs is the reason given. An older set's pull request
+is never hashed, and neither hash nor body is printed.
+
+`verify` now reads a path the set removes with a `lstat` alone. A file that is
+still there but that `verify` cannot read used to raise (exit 2, the usage
+line); it now reports `removal-present` (exit 1), which is the truth about a
+path that should be gone.
+
+## Taking the registry snapshot
+
+`launcher-apply-plan snapshot --request <file> [--out <file>]` takes the
+registry snapshot a plan's exact packages are resolved from (#1178). It is
+the only step of applying a plan that reads the package registry. It records what the
+registry said; it decides nothing from it. Deciding is
+`advisor-resolve-packages`'s job, in `@clossys/advisor`.
+
+- **Request.** `<file>` holds the report `advisor-package-request` prints,
+  `{ "state": "satisfied", "names": [...], "findings": [] }`, or just
+  `{ "names": [...] }`, read as strict JSON (invalid UTF-8, a byte order
+  mark or a repeated key is refused). Every name must be a scoped package
+  name in the publishing scope this package was built with, and appear once.
+  A request with another field, another state or any finding is refused
+  before anything is fetched.
+- **Fetch.** For each name, in name order and one at a time, a `GET` of
+  the package's full registry document at `{registry}/{name}`, with the slash
+  in the name percent-encoded (`@scope%2Fname`), the same encoding
+  `@clossys/integrator` uses. The registry is the one in this repository's
+  `package-scope.json`, packed into this package at build time.
+- **Transport.** Node's own `fetch`. The only headers this step sets are
+  `accept: application/json` and `accept-encoding: identity`, and never an
+  `Authorization` header; Node's fetch adds its own default, non-credential
+  headers. The step does not run the npm CLI, and reads no
+  `.npmrc` and no token from the environment. If Node is started with an
+  environment proxy (`NODE_USE_ENV_PROXY`), requests go through that proxy.
+  No registry credential is ever sent; a username and password written in
+  the proxy URL itself are sent only to that proxy, as Node's fetch does. A redirect is refused, never followed.
+  `accept-encoding: identity` asks for the body uncompressed, so when the
+  server honours it the size cap and `responseSha256` apply to the exact
+  bytes received. A response body is
+  read as a stream and abandoned as soon as it passes 10 MiB; a declared
+  length over that is refused before any of the body is read. If a server
+  compresses the body anyway, Node's `fetch` decodes it and the 10 MiB cap
+  counts the decoded bytes, so the read is still bounded. Each request, body
+  included, is abandoned after 30 seconds.
+- **Answers.** A `200` is projected into the snapshot. A `404` is recorded
+  as `status: "not-found"`. Anything else stops the step at that package:
+  a transport error, a timeout, a redirect, any other status, an oversize
+  body, or a `200` body that is not strict JSON or is not that package's
+  registry document. Nothing further is fetched, no snapshot is written, and
+  the exit code is `2`. An earlier snapshot at the output path is left
+  untouched, and must not be used: exit `2` means this run recorded nothing.
+- **Projection.** Only what the registry snapshot contract declares is
+  kept: the version the `latest` dist-tag names, or `null`, and, when the
+  document lists that version, that one version's integrity value and tarball
+  URL exactly as served, whether it is deprecated, when it was published, and
+  whether it lists attestations. Every other version, dist-tag and field is
+  ignored. The document must name the requested package, and the version's
+  own entry must carry the version number `latest` names; otherwise nothing
+  is written. `responseSha256` is the SHA-256 of the response body's bytes
+  as received; if a server compressed the body despite
+  `accept-encoding: identity`, it is the SHA-256 of the decoded body.
+- **Output.** The snapshot is written only after the exact text to be
+  written has been read back strictly and has passed
+  `docs/contracts/registry-snapshot.json`
+  (in the public repository, not shipped in this package; its content is
+  packed at build time), schema and code rules N1-N3 both. It goes to
+  `--out`, by default `clossys/.state/apply/registry-snapshot.json` under the
+  current directory, which should be the hub. It is two-space JSON with a
+  final newline, with packages sorted by name, so the same registry answers
+  give the same bytes apart from `fetchedAt`. `fetchedBy` is this package's
+  own name and version. The write is atomic: a temporary file in the same
+  directory is written, flushed to disk and renamed over the target, so a
+  reader sees the old file or the whole new one.
+
+A message names a package by its position in the request, `names[<n>]`,
+never by its name, and never quotes a response or the request: a name is
+request text, so the caller looks position `<n>` up in the request file it
+wrote. Exit codes: `0` means the snapshot was written, or that `--help` printed
+the usage;
+`2` means nothing was written, whether because of a usage error, an
+unreadable or refused request, or a registry answer this step cannot record.
+A snapshot is a record of what the registry answered, not evidence of where
+a package came from; that is shown by verifying the package's provenance,
+which this step does not do.
+
+## Checking provenance (V9)
+
+`checkSetProvenance({ tree, hubRoot, items }, ports?)`
+returns, for one change set, its V9 `ApplyCheck` entries
+(`Promise<readonly ApplyCheck[]>`). `plan` runs it on its temporary tree,
+after the lockfile step passes; `materialize` and `verify` do not yet run it.
+
+- **Engine.** It runs the hub's own `node_modules/.bin/integrator-provenance-check --cwd <tree>`
+  (`PROVENANCE_CHECK_BIN`), never through `npx` and never looked up on `PATH`. If
+  that bin is missing, or its real path is not inside the hub's installed
+  `@clossys/integrator`, the result is indeterminate (`engine-missing-bin`).
+  The child gets an environment built from a fixed list of variables, so no
+  parent credential, proxy or CA-trust variable reaches it, and its time and
+  output are capped (`PROVENANCE_CHECK_TIMEOUT_MS`, `PROVENANCE_CHECK_MAX_BUFFER`).
+  The JSON report is parsed strictly; exit `2`, unreadable output, or output
+  that contradicts the exit code is indeterminate.
+- **What gates.** Every `install` and `pin-starter` item except one whose
+  `satisfiedInBase` is exactly `true`. Each must be `verified` at exactly its version. One
+  missing from the report is indeterminate; a verified version other than the
+  act's is violated (`version-mismatch`). Other `@clossys/*` packages in the
+  report never gate, so an unrelated violated legacy pin passes.
+- **No exception.** An unverified package is never satisfied. One the bin
+  reports `violated` stays violated (`provenance-unverified`), and one it
+  cannot decide stays indeterminate. The first-publication exception the
+  design allows for (D20) is deliberately not implemented: a registry
+  snapshot records only the one version `latest` names, so it cannot show
+  that a version is a package's first publication, and Integrator reports a
+  failed attestation the same way as a missing one. Any exception built on
+  that would also pass a package with earlier releases whose latest release
+  fails verification. Until the snapshot contract records evidence of a first
+  publication, an unattested first publication blocks the apply (fail
+  closed).
+- **Verdict.** Indeterminate outranks violated: when any indeterminate rule
+  applies, only indeterminate entries are returned. A set with nothing to gate
+  returns one satisfied entry with no rule, without running the engine.
+- **Soundness boundary.** A pass means every version the set installs or
+  updates is verified by the hub's pinned Integrator at check time, with no
+  exception. It does not cover transitive dependencies or a later republish.
+  The bin check accepts any regular file inside the installed
+  `@clossys/integrator` package and does not compare the installed version
+  with the hub's pin; the hub's `node_modules` is trusted.
+
+`registrySnapshotDigest(snapshot)` returns a registry snapshot's contract digest
+(`sha256:` and 64 lowercase hexadecimal digits) from the snapshot's contents,
+independent of fetch time and of the order of packages and versions; it throws a
+`TypeError` for a snapshot that does not validate. The provenance check does not
+read a snapshot; the digest is for the plan binding a later change wires in.
+
+Types: `ProvenanceGateInput`, `ProvenanceGatePorts`.
 
 ## Why this is not Advisor, Starter, Builder, installer, creator, or a connector
 
@@ -351,9 +1614,10 @@ intact.
 
 ## Requirements
 
-Node.js 20+, ESM, GitHub `gh`, and no runtime dependencies. Creating a new
-hub needs permission to create a private repository under the inferred
-owner. Appointing uses the current checkout and does not create a second
+Node.js 20+, ESM, GitHub `gh`, and no runtime dependencies. The registry
+snapshot step needs HTTPS access to the public registry, and no credential.
+Creating a new hub needs permission to create a private repository under the
+inferred owner. Appointing uses the current checkout and does not create a second
 repository.
 
 ## Licence
@@ -363,3 +1627,52 @@ MIT.
 ## Changelog
 
 Release notes for every version are in the [changelog](https://github.com/clossys/foundry/blob/main/docs/changelogs/launcher.md), kept in the public repository rather than in the installed package.
+
+
+### Apply branch provenance
+
+`launcher-apply-plan plan --agent codex` selects an agent namespace for the
+computed apply branches. The supported choices are `codex`, `claude`, and
+`cursor`. The choice is covered by each change-set digest and the bundle
+approval subject; use the same choice when recomputing an approved bundle.
+Omitting `--agent` preserves legacy `clossys/apply-<digest12>` branches and
+stored change sets. Materialize and apply use the stored branch binding.
+Explicit provenance also renders setup path-scope checks for legacy and
+supported agent apply branches, refusing malformed or unsupported apply
+namespaces. Existing legacy template bytes remain unchanged.
+
+### Opt in to existing root dependency declarations
+
+Existing declarations are refused by default. To adopt or update an existing
+first-party root `package.json` declaration, select the existing bucket and
+explicitly consent before approving setup. `createExistingDeclarationAdoptions`
+derives proof rows from a complete `RepositoryObservation`, a validated resolved
+`AdvisorPlan`, selected package names and the literal
+`"adopt-existing-declaration"`. Pass these rows under the repository id in
+`PlanApplyBundleInputs.existingDeclarationAdoptions`, or save that mapping as
+JSON and pass `launcher-apply-plan plan --adopt-existing <consent.json>`.
+This option supplies scope, never an approval. The approval sheet displays prior
+literal declaration, prior resolved version/integrity, desired public identity
+and observed base. The set and bundle digests cover the consent and desired
+registry snapshot digest. Omission retains all legacy behavior.
+
+This bounded path requires Starter **0.3.x**. Starter 0.2.x remains supported for
+legacy setup, but cannot accept this proof. Only a single declaration in the
+existing root dependency bucket is eligible; cross-bucket relocation, duplicate
+placements, aliases and file/git/tarball declarations refuse. Prior literals may
+be exact, caret or tilde versions with all three numeric components. Align
+unsupported placements in an ordinary reviewed manifest/native-lock change
+before taking a fresh setup observation. Nested application manifests are outside
+this capability.
+
+Setup renders the approved rows into its canonical ledger with the setup digest.
+The protected merged setup is the trust anchor; a newly claimed approved head
+still fails required admission. The next apply retains the proof unchanged and
+emits a real compare-and-swap, even when prior and desired versions are equal.
+Launcher independently checks immutable source keys and root lock identities.
+Starter reads protected base and pull-request head manifest/lock files as data,
+checks prior and desired identities and forbids collateral manifest changes.
+Head code is never executed by this admission check. These checks prove declared
+resolution metadata; installed-byte execution evidence remains a separate proof.
+
+Existing-declaration consent supports stable exact, caret and tilde root declarations in their existing dependency bucket. The prior resolved version must satisfy that declaration. Cross-bucket moves, aliases, file references and prereleases are refused. Proof rows remain immutable; this capability covers initial setup and its first admitted apply. It grants no installed-byte or later-generation lifecycle evidence.