@mnstry/atelier 0.2.0-alpha.1 → 0.2.0-alpha.10

package/docs/decisions.md

@@ -0,0 +1,167 @@
+# Typed decision proposals
+
+The optional `@mnstry/atelier/decisions` API validates finite questions and
+their proposed answers. It performs no provider calls, credential lookup,
+source mutation, or acceptance. A consuming host supplies the provider and
+independently checks authorization before disclosure or use.
+
+For a development pilot, pin the reviewed source commit or its verified
+tarball. Check that the installed package exports `./decisions`; an older
+published alpha may not contain this API. A source merge does not publish a
+new registry version.
+
+This API is suitable for a small, explicit choice, an ordered score, or a
+Boolean probability. It does not extract missing evidence or generate prose.
+The fixtures describe an invented reading room; their answers and usage are
+synthetic examples, not model evaluation results.
+
+```js
+import {
+  decisionRequestDigest,
+  validateDecisionRequest,
+  validateDecisionResult,
+} from '@mnstry/atelier/decisions'
+
+const requestCheck = validateDecisionRequest(request)
+if (!requestCheck.ok) throw new Error('Invalid decision request')
+const digest = decisionRequestDigest(request)
+
+// The host obtains a result under its own provider and disclosure policy.
+const resultCheck = validateDecisionResult(request, result)
+if (!resultCheck.ok) throw new Error('Invalid decision result')
+```
+
+The adjacent TypeScript declarations export `DecisionRequest`,
+`DecisionQuestion`, `DecisionResult`, `DecisionAnswer`, `DecisionScope`,
+`DecisionUsage`, and `DecisionValidation`, including the individual question
+and answer variants. Runtime validation remains required for external data.
+
+For hosts that need only question and answer validation, use
+`validateDecisionAnswers(questions, answers)`. It checks bounded plain JSON,
+question structure, exact answer keys and types, probability distributions,
+and score expectations. It accepts no state, computes no hash, performs no
+provider execution, and writes nothing. The host supplies its own transient
+request binding and enforces its privacy policy.
+
+```js
+import { validateDecisionAnswers } from '@mnstry/atelier/decisions'
+
+const answerCheck = validateDecisionAnswers(questions, answers)
+if (!answerCheck.ok) throw new Error('Invalid decision answers')
+```
+
+This separate API checks evidence reference syntax, uniqueness and bounds,
+but cannot establish membership in a source snapshot that it has not received.
+The request and result validators still enforce that membership. A successful
+answer check establishes neither authorization nor semantic correctness.
+
+## Requests
+
+`atelier-decision-request@v1` records a request ID, task, rubric version,
+host-reported scope, state, evidence references, and questions. The
+`scope.workspaceId` and `scope.authorizationRef` fields bind the assessment to
+the host's reported snapshot. They do not authenticate a caller, prove
+consent, or grant access. The host must revalidate current permissions and
+revocation before sending data or acting on a cached result.
+
+Each question includes instructions and at least one `evidenceIds` entry
+referring to the request's evidence. Evidence identities are unique; their
+`sourceRef` strings are opaque references preserved for the host. Validation
+does not fetch them or prove that the state faithfully represents a source.
+
+| Question | Criteria | Answer |
+| --- | --- | --- |
+| `choice` | A map of 2–64 option IDs to descriptions | A selected option, complete probability map, and provider confidence statistic |
+| `score` | An ordered list of 2–10 descriptions | A zero-index weighted expectation, complete probability list, and provider confidence statistic |
+| `boolean` | Explicit `true` and `false` descriptions | A probability between zero and one |
+
+Identifiers are 1–128 ASCII characters, beginning with a letter or digit and
+continuing with letters, digits, `.`, `_`, `:`, or `-`. The names `__proto__`,
+`constructor`, and `prototype` are refused as object keys and identifiers.
+State and descriptions support Unicode; validation does not normalize text.
+
+Requests are limited to 64 questions, 256 evidence entries, 32,000 state
+characters, 4,000 instruction characters per question, 2,000 characters per
+criterion, and 2,048 characters per source reference. String limits count
+Unicode code points. Empty state is allowed so the host can record an
+insufficient-evidence abstention; instructions and descriptions must contain
+non-whitespace text.
+
+## Results and integrity
+
+`atelier-decision-result@v1` copies the request ID, task, rubric version and
+scope, and carries `requestDigest`, provider ID, concrete model name,
+elapsed milliseconds, and usage. Token counts are nonnegative safe integers;
+`usage: null` records unavailable usage without treating it as zero.
+
+`authority` is always `proposal-only`. `mode` is `shadow` or `advisory`;
+neither value grants execution authority. An `assessed` result contains
+exactly the requested answer keys and types. An `abstained` result contains
+an empty answer map and one explicit reason: `insufficient-evidence`,
+`ambiguous`, `no-match`, `budget-exhausted`, `provider-unavailable`, `timeout`,
+`invalid-response`, or `unauthorized`.
+
+The validator checks that distributions sum to one within `1e-6`, a chosen
+option has maximum probability, and a score equals its zero-index weighted
+expectation within `1e-6`. Tied maximum choices are valid. Boolean answers
+have no confidence field. Confidence is a provider statistic, not measured
+semantic correctness; a structurally valid high-confidence answer can still
+be wrong. The host owns evaluation data, calibrated thresholds, escalation,
+and fallback behavior. The host must also compare the recorded model with
+its requested concrete model pin; the request contract does not prescribe a
+provider or model.
+
+`decisionRequestDigest` returns lowercase SHA-256 over canonical JSON with
+object keys recursively sorted in JavaScript string order. Array order and
+exact Unicode content are retained. It includes the full request, scope,
+evidence, rubric, and optional extensions. Reordering object insertion does
+not change the digest; changing any represented value does. This is local
+integrity evidence, not a signature or proof of provenance. Invalid requests
+throw a generic `TypeError`; validators return `{ ok, errors }` without
+echoing source text, unknown field names, or provider response content.
+
+Content hashes can themselves be sensitive. A host whose policy forbids
+hashing a passage must use its own transient request binding instead of this
+digest-bearing envelope. It can reuse the question and answer types without
+calling `decisionRequestDigest` or retaining a full request. The public
+contract does not override the host's privacy policy.
+
+## Closed fields and extensions
+
+The standalone JSON Schemas are
+`atelier-decision-request.v1.schema.json` and
+`atelier-decision-result.v1.schema.json`. They validate static shape. Use the
+JavaScript validator as well for request binding, evidence relationships,
+distribution semantics, and bounded in-process JSON.
+
+As with other Atelier contracts, the roots allow optional
+`contractVersion: "1.0.0"`, and closed objects allow an optional object-valued
+`ext`. Unknown first-class fields are refused. Namespaced extension members
+are inert metadata: consumers must ignore unrecognized members and must
+never derive authority from them. Dynamic question, choice and answer maps
+contain only their declared entries; they have no reserved metadata entry.
+
+Both requests and results, including extensions, are limited to 16,777,216
+canonical JSON bytes, 100,000 values, and 32 levels of nesting below the root.
+Cycles, symbols, sparse arrays, accessors, non-finite numbers, undefined
+values and custom prototypes are refused. Plain objects with a null
+prototype are accepted. No input is mutated.
+
+## Host integration
+
+1. Build bounded questions from already authorized evidence. Preserve all
+   source passages and coverage independently of a proposed prioritization.
+2. Validate the request, then check the host's current consent, destination,
+   concrete model pin, input limit, evaluation budget and timeout policy.
+3. Call a provider through the host adapter. Keep credentials, private
+   criteria, raw responses and provider execution outside the public kit.
+4. Normalize and validate the result against the exact request. Retain full
+   distributions and unknown usage; represent failures as explicit
+   abstentions without accepting partial answer sets.
+5. Compare shadow results with an independently labeled evaluation set.
+   Enable an advisory consumer only after task-specific acceptance. Keep the
+   host's existing behavior as the fallback and recheck authorization on
+   cache access.
+
+This module does not change the existing analysis adapter's default-disabled
+execution policy or accept a model proposal as an authored fact.

package/docs/design.md

@@ -0,0 +1,167 @@
+# The design
+
+The Atelier makes a repository mean something. Files declare what they are,
+who they are for, and how they relate — and machinery enforces it.
+
+**Git is the database. The ontology is the schema. The validators are the
+constraints. The runtime is local.**
+
+This page states the design in five movements. Each one is a general
+primitive, grounded in a shipped mechanism, ending with the command that
+proves it — because a design document that cannot be checked is marketing.
+
+## 1. A repository with an ontology
+
+A small structured header turns a file into a governed node: front matter on
+Markdown, or a `.kg.json` sidecar beside any other format — JSON, YAML,
+CSV, media, anything — which the kit enrolls without ever parsing the
+foreign format. The header declares identity (`kg.id`), type, status,
+audience, and relations to other nodes.
+
+Markdown without a `kg` block is still counted by the canonical graph engine,
+but only as private `unclassified` material with a diagnostic. Once a `kg`
+block is present, partial or malformed declarations are blocking errors.
+
+The graph builder compiles the repository into a knowledge graph,
+deterministically: same tree in, same graph out, and `--check` mode fails
+when a generated graph has drifted from its sources. There is no import
+step, no database, and no export lock-in. The repository is the store. Git
+is the history, the review process, and the read boundary you already
+trust — an audience label guides projection, but repository access is what
+actually hides a file.
+
+```bash
+atelier graph --project ./atelier.project.json
+atelier graph --check --project ./atelier.project.json
+```
+
+## 2. Rules that refuse
+
+The ontology is not documentation. It is the enforcement mechanism.
+
+The JSON Schema contracts under `contracts/` define the vocabulary —
+exports, project configuration, boundary policy, sidecars, locks,
+migrations, readiness, attestation — and fail-closed validators enforce
+it. The load-bearing
+separation is `audience` versus `visibility`: audience is local readership
+(`public`, `team`, `operator`, `staff`, `private`, `sensitive`), visibility
+is runtime authority (`private`, `shared`, `platform`, `public`), and the
+validators reject every crossing — a local audience word in a visibility
+field, a `visibility` key on a source node, and above all a public export
+that resolves any source reference to a non-public source. That last check
+is fixture-pinned and mutation-tested: deleting its enforcement makes tests
+fail, not documentation drift.
+
+The contracts sit under a stability epoch. Every change is checked against
+the baseline tag's validators, schema widening outside namespaced `ext`
+containers is refused by a schema-vs-schema differ, and a breaking change
+requires a new contract version with a recorded migration. Twelve bundled
+claim-first readiness protocols check a workspace against published
+criteria and produce proposed claims — never runtime mutations.
+
+```bash
+atelier dry-run ./atelier-export.json
+atelier contract check
+npm run contract:compat
+```
+
+## 3. Collaboration as governed disclosure
+
+Repositories have roles. A private-domain repo holds one person's source
+material; a shared-project repo holds what a team may read. The boundary
+guard enforces the difference and fails closed: private or sensitive
+source placed in a shared repo blocks, protected local files staged for
+commit block, and private-domain material appearing in shared work without
+a recorded disclosure blocks.
+
+Crossing the boundary is an event with a record: `atelier promote` writes a
+`git.promote` disclosure event, reviewable like any other commit.
+Disclosure is a commit, not an accident.
+
+Change to the machinery itself is governed the same way. The workspace
+lockfile records exactly which package version, contracts, extension
+packs, and migrations a workspace runs; upgrades are branch-based,
+review-first, refuse dirty repos, and never silently overwrite authored
+content.
+
+```bash
+atelier boundary check --project ./atelier.project.json
+atelier boundary check --staged --project ./atelier.project.json
+atelier promote --source-repo <private-repo> --target-repo <shared-repo> --kg-id <node>
+atelier lock check --project ./atelier.project.json
+```
+
+## 4. A local runtime for humans and for agents
+
+The same governed workspace projects two ways.
+
+For humans: a generated review surface, served by a sidecar that binds to
+loopback only. It requires a generated publication manifest and serves only
+enrolled safe static files after realpath validation. The served pages carry a
+policy that authorizes no external origin, and the only network client in the
+package refuses non-loopback URLs.
+
+For agents: session-bound context and capability envelopes that hand an
+agent harness a governed view of the workspace — what exists, what it may
+look at, what it may propose. Proposals are recorded as typed copy-only
+metadata; capability declarations expose no apply endpoint, source write,
+execution, or Git authority. Context
+without authority. Neutral Claude and Codex skill wrappers ship in the
+package, so a harness can do readiness review work against the workspace
+without a single line of custom glue.
+
+This is a deliberately narrow answer to a broad question. It does not make
+an agent safe around private material in general; it makes one surface
+checkable: within the Atelier sidecar, a harness receives session-bound
+context and can record proposals, and there is no apply endpoint and no
+write authority to grant. A bounded view, with writing made impossible —
+a testable control, not a trust exercise.
+
+```bash
+atelier dev --project ./atelier.project.json
+atelier context flow --project ./atelier.project.json
+```
+
+## 5. A platform for your own tool
+
+The Atelier is designed to be built on, under your name, including
+commercially.
+
+A distribution wraps the CLI under its own command, contributes a
+validated extension pack — branded protocols, terms, templates — and
+themes the projection, while the root contracts, guards, and conformance
+stay canonical underneath. The repository carries a complete fictional
+reference distribution (`examples/loomworks-studio`) small enough to read
+in one sitting: a wrapper bin, a pack, a themed workspace.
+
+Apache-2.0 makes commercial use a right, not a favor. The trademark policy
+keeps the name ours and the code yours: every distribution carries
+"powered by MNSTRY Atelier" attribution, and the check is a command, not a
+request. The contribution terms are inbound-equals-outbound with a DCO
+sign-off and no CLA — nobody, including MNSTRY, holds rights over a
+contribution that the contributor does not also hold. Outside pull
+requests are not open yet; `CONTRIBUTING.md` states the posture and the
+terms that will govern them when they open.
+
+```bash
+atelier distribution check --target ./my-distribution
+atelier extension-pack validate --project ./atelier.project.json
+```
+
+## The first application
+
+Methodology authoring is the Atelier's first application, not its ceiling.
+MNSTRY built this to carry its own most demanding case: private
+transformational work, where a leaked document is not a bug but a
+betrayal. That case set the bar — fail-closed boundaries, no telemetry, no
+send path, agents without authority, disclosure as a recorded event.
+
+That case shaped the defaults. Other bodies of work — a research corpus, a
+client practice, an editorial pipeline, anything that must outlive the
+tools that touch it — reuse the mechanics, and each defines and validates
+its own ontology, protocols, and boundary policies.
+
+The claims behind this page are stated precisely, with their known limits,
+in the README's "Claims you can check" — each with the command that proves
+it. `docs/continuity.md` records the distribution commitments, including
+the perpetual Apache-2.0 grant on every tagged release you receive.

package/docs/exact-upgrades.md

@@ -0,0 +1,159 @@
+# Local exact-plan upgrades
+
+The explicit `atelier upgrade plan/apply/status/recover` commands prepare a
+local candidate from an already installed Atelier executor. They preserve an
+adopter's source branch and configuration, show the exact changes, and retain
+local evidence of what was selected and what Git actually committed.
+
+Execution in this first slice requires Linux or macOS with working directory
+fsync. Other hosts, including native Windows, refuse before transaction state
+creation; existing Atelier commands remain available. The platform refusal is
+tested separately from the POSIX execution scenarios.
+
+This first slice supports **one configuration repository in a linked Git
+worktree**, with its project config and workspace at the root. Its single
+managed repo must point to `.`. It refreshes the lock, graph, HTML projection,
+manifest and readiness output. Generated paths must be distinct paths within
+`atelier-output/`. Distribution branding is retained. External packs, local
+overlays, private readiness runs, submodules, sparse checkouts, attribute/filter
+transformations and runtime/alignment participants are refused. These limits
+are explicit eligibility checks, not assurances about unsupported setups.
+
+There is no package installation, network discovery, hook replacement, runtime
+activation, or automatic policy mode. Existing legacy `upgrade --apply` remains
+a separate workflow; it does not acquire these transaction guarantees.
+
+## Enroll and prepare
+
+Create a dedicated candidate worktree using your usual Git workflow, then add
+and commit `atelier.adoption-policy.json` there:
+
+```json
+{
+  "schema": "mnstry.atelier-adoption-policy@v1",
+  "enabled": true,
+  "mode": "manual-exact-plan",
+  "maxAgeSeconds": 86400,
+  "recoveryCoverage": "local-only",
+  "allowedEffects": ["lock-and-projections", "git-commit"]
+}
+```
+
+Ignore `.atelier-local/` and keep every file beneath it untracked. Start with a
+clean index and worktree. From the candidate worktree:
+
+```sh
+atelier upgrade plan --save --project ./atelier.project.json
+```
+
+The result names a private saved plan and its `sha256:` confirmation digest.
+Inspect its `writes`: concrete paths, ownership, old/new byte digests and modes,
+and the proposed bytes in base64. `readSet` inventories the entire enrolled
+repository except Git administration and private local state. The plan also
+binds the repository identity, HEAD, branch, policy, Git executable,
+configuration, Git auxiliary ignore/attribute files, hook directory and files, executor and imported dependency bytes,
+and a fixed expiry. Default lifetime is 24 hours; policy may shorten it.
+The Git fingerprint covers the transaction's selected executable. Legacy
+builders also invoke Git from `PATH`; use the same executable there when
+setting `ATELIER_GIT_PATH`. Cross-host output ordering is not guaranteed.
+Executor checkout metadata may affect generated lock provenance; the saved
+plan binds the resulting bytes rather than promising identical regeneration.
+
+Inherited `GIT_*` overrides such as an IDE's `GIT_ASKPASS` are refused (apart
+from the documented prompt, pager and optional-lock controls). Prepare from
+an environment without those overrides. Repository, global and system Git
+attribute files must be absent or empty for this slice.
+
+Generation uses an isolated private preparation directory and the existing
+builders. Only five registered output paths can be written, and a complete
+before/after inventory checks that boundary. The executor then saves those
+bytes; application does not recalculate or silently replace the selected plan.
+This is a bounded trusted executor, not a sandbox for arbitrary migration code.
+The generated readiness JSON retains absolute local graph and projection paths,
+which may include the account name. Inspect those committed bytes before sharing
+the candidate branch; generating a candidate does not authorize publication.
+
+## Apply the reviewed bytes
+
+Use `atelier upgrade explain --plan SAVED_PLAN_PATH --format markdown` to read
+the verified plan's effects, expiry and consent limits. The default JSON format
+contains the same report. Explanation is read-only and never grants approval.
+See [guided upgrades](guided-upgrades.md) for the owner-agent workflow.
+
+Use the returned path and digest literally:
+
+```sh
+atelier upgrade apply --plan SAVED_PLAN_PATH --confirm sha256:REVIEWED_DIGEST --project ./atelier.project.json
+```
+
+The digest selects content; it is not an authenticated human signature. Host
+permissions must establish any stronger authority. The command takes an
+exclusive local writer lease, checks current bindings before mutation and at
+safe boundaries, records original bytes and write intents, writes only expected
+preimages, stages only the frozen paths, and runs the existing commit hooks.
+No commit uses `--no-verify`. Hook execution is existing adopter code with its
+normal host privileges, not a new sandbox or a promise of no hook side effects.
+Relevant hook changes invalidate the plan; files or executables that hooks
+consult outside their directory are not transitively fingerprinted.
+Git commit has a 30-second execution budget. A timeout is conservatively
+`recovery-required`, since a hook may already have acted; this budget is not
+a guarantee that all hook descendants terminate within 30 seconds.
+
+A successful Git exit is insufficient: the commit's parent, tree and message,
+staged blobs, branch and worktree must match. A refused commit retains its index
+and worktree as `commit-refused`. Unexpected changes become `recovery-required`.
+Neither case causes an automatic retry, reset, hook bypass or success claim.
+Every accepted attempt consumes the plan, including an interrupted attempt.
+
+## Status and recovery evidence
+
+```sh
+atelier upgrade status --operation OPERATION_ID --project ./atelier.project.json
+atelier upgrade recover --operation OPERATION_ID --dry-run --project ./atelier.project.json
+```
+
+The operation ID is the hexadecimal part of the plan digest. Events live in
+`.atelier-local/upgrades/operations/OPERATION_ID/events/`, with original bytes in
+`backups/`. Events are exclusive, fsynced publications with sequence numbers,
+previous-event digests and verified rereads. Missing, truncated or altered events
+refuse success. This is local integrity evidence; a host owner who can replace
+all records can rewrite a chain. It is not externally authenticated provenance.
+
+Only a verified terminal receipt asserts completion. The v1 lock retains prior
+migration history, template lineage and successful-upgrade metadata. Its success
+fields deliberately lag the new receipt; the command never writes the hash of
+an uncreated commit into that commit. No automatic metadata refresh is shipped.
+
+An interruption after Git commits but before the terminal event remains
+`recovery-required`, even when the commit exists. Recovery dry-run reports
+current HEAD/index evidence, safely restorable bytes and conflicts. Subsequent
+user edits and any moved HEAD prevent automatic restoration. This release offers
+**no recovery mutation**: restoring files or reverting a commit requires a
+separately reviewed operation with current authority. It never resets history.
+
+A crash may leave the writer lease in place. Inspect its owner and verify that
+process has stopped before separately handling the stale lease; elapsed time
+alone never releases it. Status and recovery inspection remain available.
+A crash during preparation can also leave a `prepare-*` scratch directory
+under `.atelier-local/upgrades/`. Further preparation and application refuse
+with a stale-preparation diagnostic. Verify the writer has stopped and inspect
+the directory before separately removing only that abandoned scratch directory.
+The command does not delete it automatically or remove plans, receipts or backups.
+
+Evidence has no automatic deletion. Inventory limits (4,096 files, 64 MiB) and a
+32 MiB retained-state admission threshold and 8 MiB saved-plan limit bound this small-workspace slice.
+Exhaustion refuses another operation; export and verify evidence before any
+separate retention maintenance. Ignored state is not backed up or inherited by
+another clone. Enrollment explicitly acknowledges local-only recovery.
+
+## Provenance and acceptance boundaries
+
+The plan pins installed executor and dependency bytes. It does not authenticate
+an upstream publisher or verify a newly downloaded release. Release discovery,
+authenticated artifact intake, dependency installation, multi-repository
+transactions and standing automatic consent remain separate future work.
+
+A completed transaction means a prepared local candidate commit. It does not
+mean a merged upstream change, CI acceptance, adoption in another workspace,
+published package or activated service. Use the adopter's normal review and
+landing process to accept the candidate.

package/docs/extension-pack-lifecycle.md

@@ -0,0 +1,33 @@
+# Pack compatibility for evidence-bound review
+
+The closed v1 pack format remains unchanged. An adapter can declare a separate
+`atelier-pack-lifecycle@v1` file through
+`ext["mnstry.atelier"].extensionPackLifecycle`. Each entry binds the pack ID,
+version and content digest to `compatibleRootVersions`, an explicit finite set
+of approved root versions. This conservative compatibility range does not infer
+SemVer compatibility or silently approve a future root version.
+
+`atelier review packs` reports admission. `--migration-plan` returns a dry-run
+report referencing the existing extension-pack upgrade registry and its checks.
+A declaration can name an available registry `migrationId`; unknown migrations
+fail qualification. Pack loading never executes extension code or installs
+packages. An owner reviews replacement term/protocol meaning, retains prior
+content, updates declarations and locks, and uses the existing upgrade workflow.
+The plan itself writes nothing. A fresh run is required after a change.
+
+| Root/pack state | Historical inspection | New evidence-bound run |
+| --- | --- | --- |
+| Current root explicitly approved; exact active pack | Pinned snapshot | Admitted |
+| Exact deprecated pack, root approved | Pinned snapshot; replacement shown | Admitted with deprecated status |
+| Retired, wrong digest/version or unapproved root | Pinned snapshot | Refused |
+| Legacy pack without lifecycle declaration | Existing readers remain usable | Unqualified; refused |
+| No custom packs | Bundled snapshot | Admitted |
+| Old root predating this feature | Its legacy readers only | No new review protocol supplied by that root |
+
+A snapshot contains the actual protocol and source identity used originally.
+Historical inspection does not load today's replacement as yesterday's method.
+Migration IDs describe reviewed owner operations, not autonomous reinterpretation
+or approval. For rollback restore the previous package, pack declarations and
+lock; retain the evidence and contribution ledgers. Existing legacy readiness
+execution remains compatible and does not acquire exact-review qualification
+merely because it can still read the pack.

package/docs/guided-upgrades.md

@@ -0,0 +1,99 @@
+# Upgrade with your agent
+
+Ask your agent to prepare an upgrade using the bundled
+`atelier-guided-upgrade` skill. It is available in both packaged skill surfaces.
+For an older installation, the operator first selects and verifies the new
+package. Reading its skill is not permission to install or execute it in your
+working Atelier.
+
+> Prepare an Atelier upgrade in an isolated candidate. Preserve my authored
+> work, local customizations and existing approvals. Identify an exact trusted
+> release, explain its effect here and run the appropriate checks. Show me what
+> is ready and ask before applying changes to my working installation, merging
+> or restarting services. Report unsupported configurations explicitly.
+
+## What the owner reviews
+
+The agent prepares a short explanation with inspectable evidence:
+
+| Item | Required information |
+| --- | --- |
+| Source | Old and selected package identities, source commit when verified, artifact integrity, dependency lock and trust source. |
+| Local impact | Benefit, actual changed paths, preserved customizations, migrations and unsupported participants. |
+| Validation | Exact candidate tested, commands, results, skipped coverage and remaining acceptance checks. |
+| Consent | The specific installation, commit, merge or activation effects requested; prior applicable authority and any new decision. |
+| Recovery | What remains untouched, retained backups and conflicts; whether restoration is manual. |
+| Outcome | Prepared, installed in candidate, committed, merged, running and owner-accepted are distinct states. |
+
+Do not attach private authored content to an upstream issue or public release.
+Even generated readiness output can contain account paths. Retain full evidence
+privately and publish only an explicitly approved summary.
+
+## Exact-plan explanation
+
+After selecting/installing the executor in an eligible candidate, follow
+[exact upgrades](exact-upgrades.md) for enrollment and preparation. Use the
+verified installed binary (these examples assume a root-local npm install):
+
+```sh
+./node_modules/.bin/atelier upgrade plan --save --project ./atelier.project.json
+./node_modules/.bin/atelier upgrade explain --plan SAVED_PLAN_PATH --project ./atelier.project.json
+./node_modules/.bin/atelier upgrade explain --plan SAVED_PLAN_PATH --format markdown --project ./atelier.project.json
+```
+
+Both explanations derive from the same verified saved plan. They expose paths,
+before/after hashes, executor evidence, expiry and consent limits, without
+printing the proposed base64 contents. Inspect the saved bytes separately.
+The command is read-only: it neither records consent nor regenerates output.
+JSON `bindingsCurrent: false` and `blockers` identify observed staleness even
+when explanation succeeds. `bindingsCurrent: true` is not a reservation or a
+complete application admission; apply performs its full checks again.
+
+The owner's decision must bind the displayed plan and effects. An agent records
+the exact words and conversation reference privately with the report digest,
+candidate, target and decision. Use `humanApprovalAuthenticated: false` and
+`recordedBy: agent`; the record is an attestation of the conversation, not a
+cryptographic human signature. Hashes identify content and detect changes. A
+trusted host/harness must enforce any stronger approval boundary. Merely
+writing an approval-looking JSON file grants no authority.
+
+## Existing workspaces outside the first slice
+
+A managed subdirectory, multiple repositories, external packs, overlays or an
+unsupported host require a separate operator procedure. Keep those boundaries;
+changing a graph root to `.` can expose previously excluded material. Never
+remove a guard to make the exact planner accept a workspace.
+
+Use the consuming repository's documented procedure, retaining the old source
+and lock history, an exact dependency pin and a before/after manifest. Label the
+result as an operator-prepared candidate. The exact transaction receipt and its
+guarantees do not apply. If no procedure exists, prepare a migration proposal and
+stop before application. The legacy flag-based apply command is not an automatic
+substitute for the saved-plan workflow.
+
+An isolated snapshot may preserve active local edits for a rehearsal, provided
+its manifest is stable and the original remains untouched. It does not settle
+ownership of those edits or include ignored answer history. Reconcile with the
+active writer before eventual adoption. Test reopening/resuming owned state at
+the actual recipient before claiming owner acceptance.
+
+## Release and pilot checklist
+
+Maintainers retain a release candidate with `ATELIER_RELEASE_OUTPUT_DIR` and
+`npm run prepublishOnly`: one archive is audited and exercised by installed
+consumer and distribution smokes. This proves the candidate artifact, not that
+it was published or that an adopter trusts its publisher. Include the candidate
+commit/tree, artifact digest, release notes, supported runtimes, migration limits
+and original review qualifications in the release handoff.
+
+The publishing workflow rebuilds and verifies its own retained artifact after
+the release commit lands. Its published integrity is the consumer's installation
+reference; do not substitute a different local tarball's digest. Publication
+uses a separately authorized version tag. An alpha version in source is not
+evidence that npm already contains it.
+
+Pilot one explicitly selected workspace: inspect, prepare separately, explain,
+record a real decision, apply the authorized effects, verify and confirm the
+owner can continue their work. Candidate tests alone do not complete that last
+step. Background discovery, unattended installation and automatic recovery are
+not provided by this workflow.