@mnstry/atelier 0.2.0-alpha.12 → 0.2.0-alpha.14

package/docs/template-profile.md

@@ -0,0 +1,164 @@
+# Portable template profiles
+
+Status: Next-release package API. Import validators from
+`@mnstry/atelier/templates` and canonical project binding from
+`@mnstry/atelier/template-bindings`. The versioned schema is exported at
+`@mnstry/atelier/contracts/atelier-template-profile.v1.schema.json`.
+These APIs do not establish installed product-host acceptance.
+
+A template profile names semantic roles, surface roles, supported carriers,
+compatibility and limits. An adopter binds those roles to its own source. The
+profile carries no project content, renderer, runtime handler or permission.
+
+## Four independent grammars
+
+- Semantic roles describe resource, relation, facet, asset, collection, sequence,
+  occurrence, offer and action-descriptor structure. Profiles choose a subset.
+- Surface roles describe composition: Shell, region, collection, card, detail,
+  graph, filter, offer, status, refusal and receipt views. They reference semantic
+  role identifiers, not executable components.
+- Runtime meaning is an optional opaque `RuntimeProfileRef`. A host must supply
+  the exact profile for runtime participation; ordinary local authoring needs
+  no runtime connection. The profile never creates an operation or receipt.
+- Governance and release identities are typed digest-bound references. A
+  `TemplateRef` is not interchangeable with a source, policy, authority decision,
+  project binding, projection or release reference.
+
+## Validation stages
+
+| Entry point | Checks | Does not prove |
+| --- | --- | --- |
+| `validateTemplateDefinition(profile)` | Closed grammar, bounded data, unique roles, surface references and supported extension behavior | Adoption, content or host availability |
+| `validateTemplateBinding(profile, binding, records)` | Exact template, role cardinality, required roles, resolved source digests | Source ownership or content truth |
+| `validateTemplateRelease(profile, binding, release, records)` | Exact binding, projection/source/policy/decision/payload references, required carriers | Publication acceptance, rights or distribution |
+| `validateTemplateHost(profile, host)` | Exact version/pack/runtime requirements, primitives and optional decision observations | Host authentication, actual renderer behavior or operation permission |
+
+Every result includes `authority: structural-only`, `executionAuthority: false`
+and `publicationAuthority: false`. No result authorizes a write, network request,
+installation or publication. The implementation does not mutate inputs.
+
+Reference inventories contain `{ ref, document }` entries. All entries are
+bounded plain JSON; duplicate `(kind, id, version)` identities refuse even if
+their digests differ. References must resolve to exact supplied bytes. No URL
+fetching, path loading, provider call or dynamic extension code occurs.
+
+`templateReference(kind, id, version, document)` hashes the existing Atelier
+canonical JSON serialization of:
+
+```json
+{ "schema": "atelier-template-digest@v1", "kind": "SourceRef", "id": "sample", "version": "v1", "document": {} }
+```
+
+The digest is `sha256:` plus lowercase hexadecimal. Kind, identifier and version
+belong to the digest domain. Template, binding and release versions use SemVer;
+other source-owned versions remain opaque strings. Pack versions retain their
+existing `vN` contract. None of these digests is a signature or an authenticated
+authority decision. This new domain does not reinterpret older artifact digests.
+
+## Extensions and evolution
+
+This is a separate versioned artifact; the closed extension-pack v1 schema is
+unchanged. Profiles may link optional namespaced schema/payload references.
+Their bytes must resolve at binding/release validation, but their meanings stay
+opaque and inert. This version registers no required extension handlers and
+refuses every required extension. Do not place required behavior in optional
+annotations to evade admission.
+
+Exact compatible Atelier versions and pack digests are explicit. There is no
+automatic version coercion, range admission, migration or upgrade apply in this
+module. A new contract version and the existing owner-controlled upgrade path
+must govern changes. Keep prior source and profile artifacts for recovery.
+
+The schema follows the contract epoch's optional `contractVersion` and `ext`
+conventions. Its `ext` containers are reserved and permit no properties in this
+revision. Optional extension data must use the explicit digest-bound namespaced
+`extensions` list; required behavior cannot be smuggled through an ignored bag.
+
+## Optional advisory decisions
+
+`optionalDecisions` declares named tasks using `atelier-decision-request@v1`.
+Each is explicitly optional; the schema refuses a required provider and provides
+no vendor selector. `validateTemplateDecision` consumes the existing request and
+result validators, checks the task binding, and retains proposal-only semantics.
+It does not decide whether the answer is true or should influence the graph.
+
+A host may report `absent`, `disabled`, `unqualified` or `available`. Available
+requires an exact `CapabilityRef`; it remains an untrusted structural observation
+until the host's existing capability and authority checks qualify it. Absence
+leaves local reading and authoring usable. Every diagnostic retains a
+deterministic/manual fallback and `invocationAuthorized: false`.
+
+No decision SDK, credential, network access, provider selection or automatic
+substitution is required. Actual consent, disclosure, execution, budgets,
+revocation and qualification remain with the existing host/capability owners.
+This module adds neither a capability registry nor a second decision ontology.
+
+## Synthetic proof and remaining integration
+
+```sh
+node --test test/template-profile.test.mjs
+```
+
+The invented reading-shelf fixture exercises structural positive cases and
+refusals. It is not a real publication, owner approval, visual baseline or
+conformance certificate. Software/definition licensing never supplies content
+rights or paid-service entitlement.
+
+## Canonical project binding
+
+`@mnstry/atelier/template-bindings` exports `createTemplateProjectView(project,
+requestJson)`. Supply an existing loaded Atelier project and bounded JSON text
+with `profile`, `projectRef`, `roleNodeIds`, `target` and optional `theme`.
+For example, `roleNodeIds: { items: ['library:paper', 'library:thread'] }` binds
+the synthetic shelf's role to existing source identities. The adapter calls the
+canonical graph builder with its fresh file cache; each SourceRef binds the
+exact Markdown byte digest used by that census, not metadata alone.
+
+The initial adapter supports classified active Markdown sources bound as
+Resource, with CollectionView/StatusView presentation. CollectionView is a view
+of selected resources, not proof of a semantic Collection. An unused optional
+Collection role reports unsupported without closing local Resource authoring;
+binding it or requiring it refuses until an explicit canonical mapping exists.
+Unknown targets,
+missing or withheld selected sources, audience/repository-boundary widening,
+unsupported views, missing required roles and runtime-profile requirements
+refuse. Draft/archived sources do not appear. Local archival is not a governed
+withdrawal receipt, and old exported copies are not remotely erased.
+
+Presentation models, escaping, themes and static HTML come from the existing
+presentation package. Web and document preview are the same read-only bytes;
+no inert control pretends to be an implemented action. The adapter writes no
+source, projection, lock or release and performs no provider call. Optional
+decisions report absent with the deterministic/manual fallback.
+
+`textPreview` provides the same selected titles, summaries, self-description
+and status as plain text without CSS, script or media. It is a local low-bandwidth
+preview, not an email/chat adapter, portable document package or publication.
+
+```sh
+node --test test/template-profile.test.mjs test/template-journey.test.mjs
+```
+
+The journey test uses disposable synthetic repositories, the actual local
+maintenance engine and production `createSourceApply`, not an alternate source
+writer. A simulated person's edit is held, applied to canonical source,
+rebuilt and rendered; the old binding refuses against the new source, duplicate
+apply is idempotent and an unrelated resource remains byte-identical. The test
+does not open the desktop application, accept a release or prove accessibility
+with assistive technology. On platforms without production atomic exchange,
+the apply journey explicitly skips and must not count as platform acceptance.
+
+`npm run consumer:smoke` installs the exact tarball offline and exercises the
+template APIs by package name. Its synthetic journey binds canonical source,
+checks provider absence and audience refusal, applies an edit through the
+installed source-apply owner, rejects the stale binding, and checks idempotence
+and preservation of an unrelated source. Atomic exchange is required for the
+write portion; other platforms retain the read-only checks.
+
+The built-in [template adoption participant](template-upgrades.md) connects local
+profile adoption, exact locks, retained history and read-only projections to the
+existing upgrade transaction engine. External packs, runtime extensions and
+automatic restoration remain unsupported.
+
+Remaining integration includes interactive host wiring, all-carrier conformance,
+actual host/accessibility/visual proof, and receiving-owner acceptance.

package/docs/template-upgrades.md

@@ -0,0 +1,114 @@
+# Local template adoption
+
+The built-in `local-template-profile@1` participant prepares an inert template
+profile, graph selection and read-only projection in the existing exact-plan
+upgrade engine. It uses the same exclusive writer, exact preimages, saved bytes,
+append-only private journal, backups, commit hooks and commit verification.
+It is not a plugin registry or a second transaction engine.
+
+## Prepare and inspect
+
+Use an isolated linked worktree with one managed root repository. Commit the
+profile and selection JSON inputs before preparing. Both paths must be literal,
+distinct, root-relative regular non-executable files outside managed output.
+The selection has exactly `projectRef`, `roleNodeIds`, `target`, and optional
+`theme`. Source selection and disclosure are enforced by the existing canonical
+graph, projection policy and template composition adapter.
+
+Explicit enrollment uses `atelier.adoption-policy.json`:
+
+```json
+{
+  "schema": "mnstry.atelier-adoption-policy@v2",
+  "enabled": true,
+  "participant": "local-template-profile@1",
+  "mode": "manual-exact-plan",
+  "maxAgeSeconds": 86400,
+  "recoveryCoverage": "local-only",
+  "allowedEffects": ["template-adoption", "lock-and-projections", "git-commit"]
+}
+```
+
+The API is exported through the existing `@mnstry/atelier/upgrade` subpath:
+
+```js
+import { prepareTemplateUpgrade, explainSavedUpgrade, applySavedUpgrade }
+  from '@mnstry/atelier/upgrade'
+
+const prepared = prepareTemplateUpgrade({
+  project,
+  profileFile: 'next-profile.json',
+  selectionFile: 'next-selection.json',
+})
+const explanation = explainSavedUpgrade({ project, planFile: prepared.savedPlan })
+// Inspect the exact changes and obtain the owner's selection before applying.
+// A digest identifies bytes; it does not authenticate a human decision.
+const result = applySavedUpgrade({
+  project,
+  planFile: prepared.savedPlan,
+  confirm: prepared.plan.digest,
+})
+```
+
+There is no new CLI command family. The existing saved-plan apply, explain,
+status and recovery entry points understand the new v3 plan. Existing v2 plans
+remain supported and still refuse execution when their pinned executor changes.
+Policies are never silently converted.
+
+## Installed state
+
+The engine owns only these template paths:
+
+- `atelier-template/profile.json` and `selection.json`: Exact inert input bytes.
+- `atelier-template/adoption.json`: Validated installed state with typed refs,
+  raw input digests and the four managed-content digests/modes.
+- `atelier-template/history/<digest>.json`: Exact immutable prior adoption
+  manifest on subsequent adoption.
+- `atelier-output/template.html` and `template-binding.json`: Read-only
+  rendering and its validated source binding.
+
+The existing lock and normal four graph/projection/readiness files are refreshed
+through their original builders. The v1 lock keeps unrelated fields, provenance,
+migration history, historical success metadata, and the complete workspace
+template lineage in `lock.template`. Only package and generated information
+are refreshed. The separate adoption document owns the profile's typed identity,
+version, and digest. A profile adoption never replaces the workspace template
+identity or version. The adoption document does not hash itself recursively.
+
+First adoption refuses orphan reserved state. Later adoption verifies every
+managed preimage and the complete prior-manifest chain. Committed local changes
+to managed files refuse rather than being overwritten. Source documents and
+ordinary local configuration are never template write targets.
+
+Repeating the same valid inputs is another explicit adoption, not an implicit
+no-op: it appends a new adoption manifest linked to the previous one. Identical
+profile, selection and projection bytes are not rewritten. Existing history is
+verified and retained. Empty reserved root/history directories are harmless;
+unknown reserved child directories are refused, including empty ones.
+
+Before mutation the engine recomputes the template output using current canonical
+source and compares it to the saved bytes. After writes it verifies the installed
+profile, selection, binding and rendering against that same source. A partial or
+failed operation never reports completed adoption.
+
+## Limits and recovery
+
+External packs, runtime profiles, extension handlers, local overlays, custom
+callbacks, package installation, network retrieval, source migrations and
+automatic consent remain unsupported. This first participant does not claim
+full template migration or all-carrier conformance.
+
+The exact-plan POSIX, clean-worktree, path, Git, hook, expiry, bounded-inventory
+and local-evidence controls still apply. Only regular create/update writes are
+supported; no deletion, rename, executable mode change or arbitrary scaffolding
+is added. An accepted attempt consumes its plan, including an interrupted attempt.
+
+Use the existing operation status and recovery dry-run API. Recovery describes
+verified backups and conflicts; it never restores files, resets history, clears
+a lease, resumes a consumed plan or supplies new consent automatically. A later
+restoration needs a separately reviewed operation. Corrupted or missing evidence
+cannot become success.
+
+A completed transaction means a local candidate commit only. Independent review,
+CI, merge, publisher authentication, package release, recipient adoption,
+runtime activation and human acceptance remain separate.

package/docs/trackables.md

@@ -0,0 +1,111 @@
+# Trackables: one definition, one domain writer
+
+A Trackable follows an identifiable subject or pursuit over time. Its adopted
+definition, instance, occurrences, evidence and qualified views retain separate
+meanings. Following a practice, completing a milestone and recording a reflection
+use different profiles. A recorded result does not establish independent ability.
+
+The portable `@mnstry/atelier/trackables` API exports one domain reducer used by
+`previewTrackable` and the private `createTrackableStore` reference adapter.
+Product hosts adapt this reducer through their existing authenticated domain
+writer. They must not copy member state into a Witness-specific store.
+
+## Supported reference profile
+
+| Profile | Occurrence | Evidence | Domain fulfillment |
+| --- | --- | --- | --- |
+| Recurring practice | Local calendar day in an explicit IANA timezone | Completed, partial, skipped, waived, not applicable | Separate from completing an occurrence |
+| Milestone | One opportunity for the adopted definition | Same explicit result states | Explicit open, fulfilled or released disposition |
+| Qualitative series | Unscheduled source event | Attributed text observation | Unscored |
+
+Missing evidence is `unobserved`, never zero or automatic failure. Several
+matching reports of one occurrence count once; conflicting reports remain
+`disputed`. Manual and session records retain separate source identities and
+assistance. A source event cannot be recaptured under another evidence ID for the
+same instance. Different instances and days remain distinct.
+
+This bounded profile supports daily calendars, not arbitrary recurrence,
+quantitative meters, streaks or a universal progress score. It uses the host's
+installed IANA timezone data for new records, previews and current windows.
+Journal replay preserves each recorded occurrence's original local day. Native
+schedulers retain calendar ownership and
+must qualify their mappings, including timezone database version where needed.
+
+`releaseTrackable` validates and hashes a definition. Releasing new bytes does
+not change existing instances. `adopt` requires a later compatible revision and
+an explicit effective instant; it refuses changes that reinterpret recorded
+occurrences. Late reports resolve the definition applicable at occurrence time.
+DST changes preserve local-day identity. A timezone change uses a new definition.
+
+The immutable journal records every command, actor assertion, recording time,
+source time and resulting state digest. New events use `atelier-trackable-event@v2`;
+record events also pin the resolved occurrence, source instant/reference and host
+timezone-data version (`null` if unavailable). Replay checks these against the
+adopted definition, scope, instance and command, without recalculating the stored
+local day. Event-chain and resulting-state digest checks still apply. This is
+local integrity checking, not authentication of the host calendar or recorder.
+Corrections preserve original events and
+invalidate dependent fulfillment evidence. Lifecycle, domain fulfillment,
+evidence quality and attention remain independent. Pausing prevents new capture;
+retirement is terminal. Views describe current corrected knowledge about the
+selected occurrence time, not historical knowledge as it was then understood.
+
+## Local use and ownership
+
+Run `atelier trackable preview|release|execute|snapshot|view|export` with JSON stdin.
+The existing workspace must ignore `.atelier-local/`. Local identity is asserted,
+not authenticated. `scope` selects a private store; operating-system access is
+its trust boundary, so this is not multi-tenant access control. Exports are
+private and require deliberate handling. Withdrawal and correction retain
+history; this adapter does not claim secure erasure or automated retention.
+
+A command has `schema: "atelier-trackable-command@v1"`, `requestId`,
+`expectedRevision`, `operation` and `input`. Operations are `release`,
+`instantiate`, `adopt`, `record`, `correct`, `lifecycle` and `disposition`.
+The exported [schema](../contracts/atelier-trackable.v1.schema.json) and
+[fixtures](../fixtures/atelier-trackable) specify exact fields.
+
+`execute` locks the selected scope, verifies history, applies the shared reducer,
+atomically publishes one event and reads it back. Replaying the same request and
+actor returns the original receipt; changed input under that identity refuses.
+A lost response can therefore be reconciled by retrying the original command.
+Dead process locks use the existing private-state custody mechanism. Journal
+capacity reserves room for correction and retirement; full histories remain
+available for explicit export. No automatic archive or compaction is performed.
+
+Older `atelier-trackable-event@v1` events remain readable and can precede new v2
+events without rewriting history. They lack the original calendar observation,
+so replay still needs compatible timezone data. If replay of a legacy record
+produces a different state digest, snapshot, view and execute refuse.
+`exportHistory()` remains available after verifying the full event chain and
+returns `stateVerified: false` plus `replayError`; these raw events are not a
+verified reconstructed state. Restore the original calendar environment before
+resuming that store. Do not infer a timezone change from this diagnostic alone,
+or rewrite old digests to make them pass. Other replay and integrity failures
+still refuse; a valid reconstruction exports `stateVerified: true`.
+
+## Authoring and host adoption
+
+Definition fields `profile` and `schedule` are enforced by the reducer and
+occurrence resolver. `id` and `revision` pin meaning; `purpose` is rationale;
+`interpretationLimits` are surfaced guidance. The engine revision appears in
+release and view outputs. Host binding must additionally name immutable source
+resolution, authentication, operation authorization, evidence-source validation,
+storage and rendering. Caller-supplied source digests are provenance assertions,
+not proof that a session or instrument reported them.
+
+The reducer's optional `occurrenceResolution` context is for replay of a
+previously verified journal, never user-authored command input. Native writers
+that use it must persist and verify the command, complete resolution and state
+digest together. The local adapter derives it from the new state and never
+accepts a caller override. Existing recorded evidence keeps its occurrence when
+current rules change; new evidence and the current-window view can consequently
+resolve the same instant to a different day. The API does not silently merge or
+reinterpret those occurrences.
+
+Reference tests exercise preview/runtime parity, durable reload, scoped stores,
+correction, duplicate transport/source events, same-day instances, late evidence,
+DST, timezone adoption, simulated timezone-data drift, legacy export-only
+recovery and refusal of inconsistent replay metadata. These establish the portable subset. Authenticated
+member-host adoption, actual UI refresh and broader calendar profiles require
+separate receiving-host evidence.

package/docs/upgrade.md

@@ -9,6 +9,104 @@ workspace between Atelier package releases. The flow is local-only: it does not
 provision repositories, contact a Git host, mutate the MNSTRY runtime, or write
 through a browser view.
 
+## Upgrading to 0.2.0-alpha.14
+
+`atelier upgrade closure --npm-root ABSOLUTE_NPM_ROOT` plans a check of a staged
+candidate's own dependency closure before an upgrade. It reads the candidate's
+lockfile and manifests only and runs no npm command. Exit code 3 is a completed
+plan and exit code 2 a refusal; the command never exits 0, because a plan is not
+proof of an offline reinstall. It refuses `--__proto__` as an unsupported flag.
+See [Consumer dependency closure plan](#consumer-dependency-closure-plan).
+
+This release also introduces `@mnstry/atelier/ui`, a tenant-neutral control
+grammar for local Atelier tooling and compatible downstream interfaces. Existing
+consumers do not need to change. Consumers that adopt it map the
+`--system-control-*` custom properties to their own theme.
+
+No schema or stored record format changes in this release. The boundary checks
+now judge work they used to miss, so a commit or push that passed on
+0.2.0-alpha.13 can be refused, and a few other results change:
+
+- Reinstall the boundary hooks with `atelier boundary install-hooks`. The new
+  pre-push hook passes the remote Git names, so history held only by another
+  remote is judged on its way to a new one. The push check judges every commit
+  the remote's tracking refs do not hold, each against its parent, binaries
+  included. A push carrying more than 1000 such commits or more than the
+  evidence budget is refused with `content-scan-incomplete`; push it in
+  smaller parts.
+- The pre-commit check reads the index and work tree Git names, so
+  `git commit -a`, `git commit <paths>` and commits from a linked worktree are
+  judged. It blocks with `pre-commit-repo-unresolved` when no single declared
+  repository is being committed, as the push check does.
+- The content scan pins its diff format, so an external diff, a textconv
+  driver, changed prefixes or quoted paths no longer leave a change unscanned.
+  A staged or pushed deletion of a binary file no longer blocks.
+- The semantic-field review takes only an added review marker as approval; a
+  removed marker, or one in a file name, approves nothing. `atelier upgrade`
+  applies the same rule.
+- `extract-structure` refuses `parallel: true` with `NATIVE_WORKERS_UNATTESTED`.
+- Knowledge Health regenerates its rule identity for the two graph files: the
+  `check` each assessment carries names a new `version`, `sourceTree` and
+  `graphBlob`. The rule it applies is unchanged. A workshop contribution
+  started on 0.2.0-alpha.13, completed or not, cannot start Review on this
+  release (`finding changed; refresh before selecting a new draft`); start
+  Review before upgrading, or record a new contribution.
+- `runMaintenanceService` from `@mnstry/atelier/obsidian` refuses a project
+  loader that answers with a promise when no `locateProject` is given
+  (`service-loader-not-synchronous`); on 0.2.0-alpha.13 such a service
+  protected no repository. Pass a synchronous `locateProject`, which answers
+  a project naming its folder, to keep an asynchronous loader (see
+  [Obsidian](obsidian.md)).
+
+A package update supplies no interpretation approval, source-write permission,
+publication authority or runtime activation. Rehearse this exact installed
+version in a disposable workspace before client use.
+
+## Upgrading to 0.2.0-alpha.13
+
+The public [Knowledge Health workshop](knowledge-health/devday/public-default.md)
+uses an invented local workspace. Participants can retain their original words,
+a separate interpretation and a `note`, `perspective-only`, `disagreement` or
+`pause` response. Review is a separate optional session. A selected draft can
+produce one retained copy-only source-owner proposal; retries and reopen read
+back its original receipt instead of appending another proposal. A source owner
+reviews the proposal and edits the declaration with normal repository tools,
+then reads it back and reassesses. The browser host grants no source-apply route.
+
+`atelier knowledge semantic` exposes the existing semantic runner's eleven
+operations through JSON stdin. It retains the runner's refusal codes and saved
+failure details. The [semantic operation contract](semantic-operation.md)
+remains authoritative; this release adds no schema or package export.
+
+Existing source and local history remain owned by their original repositories.
+A package update supplies no interpretation approval, source-write permission,
+Obsidian host qualification, publication authority or runtime activation. Rehearse
+this exact installed version in a disposable workspace before client use.
+
+## Unreleased
+
+The bundled readiness pack retains its original v1 content and digest. Existing
+locks, including the prior alpha.10 release fixture, can prepare and apply both
+ordinary v2 and template v3 exact plans without first rewriting the lock.
+Discovery Harness is the architecture name; the persisted readiness entry still
+uses Discovery Engine. Actual external pack changes still require their own
+adoption procedure and are not accepted by either participant.
+
+The next release adds the responsibility workflows, source-current ingestion,
+Trackables, governed instruction adoption and local template profiles. Template
+adoption uses the existing exact-plan transaction engine with explicit v2 policy
+and v3 plans; existing policies are never converted automatically. See
+[template profiles](template-profile.md) and [template adoption](template-upgrades.md).
+Optional advisory decisions require no provider installation or activation.
+
+New Trackable journals retain resolved calendar occurrences and byte-bound state.
+Legacy v1 journals remain available as chain-verified exports when state replay
+cannot be established. Preserve historical records and use the documented
+[Trackables](trackables.md) host limits before adopting a new profile.
+Regenerate local graph/projection artifacts through the ordinary upgrade process
+and qualify each consuming host independently. A package update supplies no
+publication permission or runtime activation.
+
 ## Upgrading to 0.2.0-alpha.12
 
 This release makes the first open of an Obsidian view automatic and ships
@@ -205,7 +303,7 @@ For registry installs, pin the exact version and record the resolved version
 in the lockfile:
 
 ```bash
-npm install --save-dev @mnstry/atelier@0.2.0-alpha.12
+npm install --save-dev @mnstry/atelier@0.2.0-alpha.14
 npx mnstry-atelier lock write --project ./atelier.project.json
 ```
 
@@ -213,7 +311,7 @@ For Git installs, pin the release tag rather than a branch, so the lock file
 records exactly what was reviewed:
 
 ```bash
-npm install --save-dev "git+https://github.com/MNSTRY/atelier.git#v0.2.0-alpha.12"
+npm install --save-dev "git+https://github.com/MNSTRY/atelier.git#v0.2.0-alpha.14"
 npx mnstry-atelier lock write --project ./atelier.project.json
 ```
 
@@ -292,3 +390,122 @@ For the bounded, manually confirmed single-repository workflow, see
 commands are separate from the legacy flag-based migration workflow above.
 They preserve history and honor existing commit hooks; they do not install a
 new package or activate a runtime.
+
+## Consumer dependency closure plan
+
+`atelier upgrade closure --npm-root ABSOLUTE_NPM_ROOT` plans a check of a staged
+candidate's own dependency closure. A consumer does not inherit a dependency
+publisher's npm `overrides`, so the candidate's own lockfile is what counts.
+
+The command reads these files and no others:
+
+- the candidate's `package.json` and `package-lock.json`;
+- the installed `package.json` of every lockfile copy of the selected package;
+- `package.json` in each directory above the npm root, up to the filesystem
+  root, to refuse a parent that declares workspaces. When the npm root is under
+  your home directory, that includes a `package.json` in the home directory;
+- Atelier's own `package.json`. The CLI reads it on every run for its version;
+  this plan also takes the default package name from it when `--package` is
+  not given.
+
+It does not run npm, use the network, read npm configuration or credentials, or
+write anything. The directory need not be an Atelier workspace, and `--npm-root`
+has no default.
+
+Every run prints exactly one JSON document with `"proof": "not-run"`, including
+a run whose arguments are refused. A completed plan holds:
+
+- the lockfile's SHA-256, version and entry count;
+- entries by source (`npm`, `git`, `local_path`, `link`, `bundled` and
+  `unclassified`, an installed entry with no `resolved`); the counts add up to
+  the entry count;
+- the registry hosts the lockfile names, and separately the URL schemes (`http`,
+  `https`) it uses;
+- the number of registry tarballs an offline proof would need;
+- lockfile entries whose `os`, `cpu` or `libc` excludes this host;
+- the selected package's lockfile copies, and under `manifests` the path, name,
+  version and SHA-256 of each installed manifest that was read;
+- the selected package's exact `overrides` that were checked against every
+  installed copy, the ones with no copy, and the ones left unchecked: a
+  version-selector key, a nested override, a value that is not an exact
+  version, or a package that a link provides (`link-only`, or `linked-copy`
+  when a registry copy is installed beside the link);
+- every refusal, with its code, one `reason`, a message and a next step.
+
+A refused plan holds its refusals and whatever else was established. A refusal
+of the arguments, the npm root or the shape of the lockfile stops the plan
+there, so it holds nothing about the lockfile's entries; any other refusal is
+listed beside the rest of the classification.
+
+Exit code 3 means a completed plan. Exit code 2 means a refusal: the JSON
+document, then `[code] message` with a `Next:` step on standard error. The
+command never exits 0: a plan is not a pass, and this command does not prove an
+offline reinstall.
+
+Overrides are taken from the installed manifest only when it is the package the
+lockfile records: each copy's manifest must declare the selected name and the
+version of its own lockfile entry, and all copies must be at one version with
+the same overrides. Otherwise the plan is refused and no override is reported
+as checked.
+
+Refusals reuse existing codes:
+
+- `usage`: the input is not supported. Reasons: `npm-root-required`,
+  `npm-root-not-absolute`, `npm-root-not-directory`, `npm-root-linked` (the
+  path is a link or passes through one; the refusal prints the directory's
+  `realPath` to pass instead), `argument-unsupported` (an unknown flag, an
+  extra argument, a flag with no value, an empty `--package` or
+  `--registry-host`, or a flag given more than once; an empty value after
+  `--npm-root=` is `npm-root-required`), `manifest-missing`, `lockfile-missing`,
+  `lockfile-invalid` (not a JSON object, or a `packages` entry that is not an
+  object), `lockfile-version` (version 1, or no `packages` map), `workspaces`,
+  `prefix-mismatch` (a parent directory declares workspaces) and
+  `linked-node-modules`.
+- `consumer-closure-incomplete`: an offline reinstall could not be proven for a
+  lockfile entry. Reasons: `missing-integrity`, `git-source`, `other-host`,
+  `outside-project`, `link-target-missing` (a link that names no folder),
+  `zero-copies`, `selected-package-unreadable`, `selected-package-mismatch`
+  (an installed manifest that is not the package its lockfile entry records)
+  and `selected-copies-differ`.
+- `override-not-inherited`: reason `copy-off-pin`. A copy is installed at a
+  version other than the selected package's exact pin. More than one copy, all
+  at the pin, is reported and not refused.
+
+Options:
+
+- `--package NAME` selects the package whose overrides are checked. It defaults
+  to `@mnstry/atelier`.
+- `--registry-host HOST[,HOST]` names the approved registry hosts. A tarball on
+  any other host, or at a URL with no readable host, is then refused. Without
+  it, hosts are reported and `approvedRegistryVerified` is `false`, because the
+  plan does not read npm configuration.
+
+Give each option once, with a value, after the word `closure`. An option with
+an empty value is refused; leave the option out to use its default.
+
+Limits:
+
+- The plan cannot run `npm prefix`, so `prefixVerified` is always `false`.
+  Instead it requires `--npm-root` to be the directory's real path and refuses
+  any parent directory of it that declares workspaces, whether or not that
+  parent's workspaces include the candidate. A path that is a link, or passes
+  through one, is refused, with its `realPath` in the JSON result. On macOS,
+  `/tmp` is a link into `/private` and `$TMPDIR` passes through `/var`, another
+  such link, so a candidate staged there needs its real path (for example
+  `pwd -P` from inside it).
+- Containment of links and local files is checked by path, without following
+  links. The folder a link points to is not opened: an override for a package
+  that a link provides is listed as unchecked, never as checked.
+- Approving a host does not verify the transport. A host is matched by its
+  exact name and port, whatever the scheme; `registrySchemes` counts `http`
+  and `https` separately.
+- The manifest binding compares the name and version the installed manifest
+  declares. It does not verify the installed files against the lockfile's
+  `integrity`.
+- Platform evidence uses this process's `os` and `cpu`; `libc` is unknown
+  unless a caller of `planConsumerClosure` supplies it.
+- A flag with no value placed before the word `closure` (for example
+  `atelier upgrade --package closure`) takes `closure` as its value, so the
+  ordinary upgrade command runs instead of this one.
+- `lockTreeDifferences`, the comparison of two `npm ls` trees, is in the source
+  but is not exported from the package and no command uses it.

package/fixtures/atelier-architecture/binding/invalid/document.json

@@ -0,0 +1,19 @@
+{
+  "schema": "atelier-behavior-binding@v1",
+  "definition": {
+    "ref": "definitions/weekly-note.json",
+    "digest": "sha256:0000000000000000000000000000000000000000000000000000000000000000"
+  },
+  "fields": [
+    {
+      "pointer": "/question",
+      "classification": "implicit",
+      "required": true,
+      "consumer": {
+        "id": "reference-note",
+        "profile": "note-v1",
+        "revision": "1"
+      }
+    }
+  ]
+}