@mnstry/atelier 0.2.0-alpha.5 → 0.2.0-alpha.8

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.

package/docs/install.md

@@ -17,6 +17,10 @@ Git repository access is the hard read boundary for source files. Local
 `kg.audience` labels guide projection and review, but they do not hide files
 from anyone who can read the repository.
 
+For adapters whose source repositories live elsewhere, see
+[project options](project-options.md) for shared CLI overrides, precedence and
+resolution diagnostics. Moving a repository does not change its read authority.
+
 Two command forms ship, and each has a place. Inside an installed
 workspace, use `atelier` — it resolves from `node_modules/.bin`, so npm
 scripts and workspace shells get the real binary. From outside a
@@ -30,19 +34,19 @@ The registry is the distribution channel of record, as `docs/continuity.md`
 commits:
 
 ```bash
-npm install --save-dev @mnstry/atelier@0.2.0-alpha.5
+npm install --save-dev @mnstry/atelier@0.2.0-alpha.8
 ```
 
 Installing from the matching Git tag resolves to the same reviewed commit:
 
 ```bash
-npm install --save-dev "git+https://github.com/MNSTRY/atelier.git#v0.2.0-alpha.5"
+npm install --save-dev "git+https://github.com/MNSTRY/atelier.git#v0.2.0-alpha.8"
 ```
 
 Or over SSH:
 
 ```bash
-npm install --save-dev "git+ssh://git@github.com/MNSTRY/atelier.git#v0.2.0-alpha.5"
+npm install --save-dev "git+ssh://git@github.com/MNSTRY/atelier.git#v0.2.0-alpha.8"
 ```
 
 Keep the `@mnstry/` scope — see the command-form note above for why the
@@ -121,17 +125,60 @@ atelier init --template shared-project --target ./project-alpha --actor tenant-u
 
 `--actor` rewrites the copied boundary policy actor entry and binds it to the
 local Git email when available. Use `--github-login` or `--git-email` to set
-those values explicitly during onboarding. At check time, a declared actor is
-resolved in this order: recognized `--actor`/`MNSTRY_ATELIER_ACTOR`/
-`GITHUB_ACTOR`, configured Git email, then a reviewed `gh api user` fallback.
-An explicit value that is not declared in the policy does not authenticate an
-actor and therefore does not suppress later resolution attempts.
+those values explicitly during onboarding. Initialization does not infer a
+GitHub login from the environment or actor slug; without `--github-login` it
+retains an actor-specific placeholder. At check time, explicit selectors are validated even for shared-only work.
+Unknown `--actor`/`MNSTRY_ATELIER_ACTOR` values or conflicting explicit selectors
+are always errors. Boundary ownership is scoped to configured repository names;
+these names do not authenticate a checkout's identity. Duplicate configured names
+are refused case-insensitively.
+
+Derived attribution is needed only when the project operates a private-domain
+repository with a declared owner. Shared-only checks skip platform, Git-email and
+`gh` lookup entirely. When ownership requires attribution, precedence is:
+
+| Input | Result |
+| --- | --- |
+| `--actor` or `MNSTRY_ATELIER_ACTOR` | Must name one declared actor; wins over derived inputs. |
+| `GITHUB_ACTOR` | Must uniquely match a declared `githubLogin`, case-insensitively. Unmapped/ambiguous values do not fall through. Actor keys and login placeholders are not login mappings. |
+| Configured Git email | Used only without either input above; must map to one actor. Commit history is never used. |
+| Optional `gh api user` | Used only when the inputs above are absent or configured email has no match; must uniquely match a declared login. Sync disables this lookup. |
+
+Unresolved derived attribution and ownership mismatches are errors in strict
+mode and warnings in ordinary `legacy-warning` mode. Sync forces ownership errors
+in both modes. Reports retain the resolution reason and affected repository.
+`allowHistoryActorResolution` is a deprecated, accepted no-op: setting it to true
+never enables history-based attribution. These are attribution hints, not
+authenticated authorization. In particular `GITHUB_ACTOR` describes the supplied
+platform value, not an authenticated human operating a phone or a workflow rerun.
+Shared-host deployment must establish its own trusted identity boundary.
+
+`init` refuses existing scaffold files or an existing project/lock; use `adopt`
+for existing content and `upgrade` for managed changes. Adoption validates the
+proposed or retained project and its selected policy before writing any scaffold
+or local state, preserves existing locks, and
+refuses drift rather than reporting success. Choose and install the intended
+package before adoption. Preview configs resolve `@mnstry/atelier/cli` from the
+workspace through parent `node_modules` directories using Node, without registry
+fallback. This supports the documented subdirectory target and hoisted install.
+Generate `graph` and `project` output before starting the preview. Existing launch
+configs are not rewritten by these template changes. Append server arguments
+following a `--` separator after the configured Node arguments. The host process
+lifecycle still needs qualification before relying on preview restarts.
+
+Upgrade planning and application use the same optional `gh api user` fallback
+as ordinary boundary checks. Supply a valid explicit selector or mapped identity
+to avoid this lookup; Sync disables it.
+
+The generated manifest's `graphPath` is relative to its output directory. Readers
+of older manifests should continue accepting absolute paths; resolve relative
+values against the directory containing `atelier.manifest.json`.
 
 Then update:
 
 - `atelier.project.json` repo paths.
 - `repo-access.v1.json` read boundaries.
-- `atelier.lock.json` with `atelier lock write` after choosing the exact Atelier package source.
+- `atelier.lock.json`: inspect `atelier lock check`; use the reviewed upgrade path for a changed package or policy rather than silently rewriting the baseline.
 - README placeholders for project names and Git remotes.
 
 Keep project configuration tracked and local overlay state ignored. Track
@@ -165,3 +212,12 @@ smoke-test tools; they are not the default install path.
 
 See `docs/tenant-readiness.md` for the readiness review format and
 `docs/upgrade.md` for the full upgrade flow and boundary review checklist.
+
+## External source adapters and local review
+
+Use `atelier init --template external-project --target NEW_DIRECTORY` for the
+invented adapter/source starter. See [local review](local-review.md) for the
+complete installed workflow, source ownership, asserted identity and save/resume.
+`atelier lock provenance` distinguishes declared install origin, observed package
+bytes and verified clean-checkout binding. It never substitutes the consumer
+repository's HEAD for the installed package.

package/docs/intake-and-guides.md

@@ -0,0 +1,65 @@
+# Immutable intake and guide integration
+
+## Keep source, extraction and meaning separate
+
+`@mnstry/atelier/intake` supplies a bounded local integrity store for existing
+extractors. It does not select or run a processor, install dependencies, import
+an entire corpus, upload data, or accept semantic claims.
+
+Create the store in a Git workspace whose `.atelier-local/` is ignored and
+untracked. Ingest a visible relative source file against an expected SHA-256.
+The store copies verified bytes, checks the source again, and writes an immutable
+provenance record. Identical bytes from different source paths retain separate
+records. Original files are never moved, rewritten or removed.
+
+Begin an attempt using an explicit identifier, verified blob digest, extractor
+identity/version and configuration digest. Retrying the identical attempt is
+idempotent; changing its identity is refused. Complete it with bounded UTF-8
+output and its expected digest. Output is written and checked before completion.
+An interrupted or conflicting output is preserved, never overwritten; inspect
+it and use a new attempt identifier for a changed run. An occupied operation lock
+requires recovery inspection. A completion receipt proves byte integrity only:
+semantic acceptance remains pending. Read completion through the store to verify
+its attempt, output and source blob again.
+
+The current per-file/output ceiling is 16 MiB. Larger media stay in existing
+bounded processing tools; do not split or downsample originals silently. This
+adapter does not promise aggregate disk quota, malware isolation, cross-host
+locking, backup, or a Windows qualification. Consumers retain conversation branch
+structure, missing-asset evidence, and format-specific completeness checks.
+Do not flatten a conversation export merely to satisfy a text-output API.
+Packet authoring can proceed before corpus ingestion.
+
+## Guides and private implementations
+
+`@mnstry/atelier/guides` and the guide schema define portable offers, inert
+remote capability descriptors, local engagement transitions and exact-payload
+consent assessment. Offers identify the guide and capabilities; engagement can
+be accepted, paused, resumed or irrevocably revoked. An updated offer requires
+a newly bound engagement. Deliverable acceptance remains an explicit human step.
+Commercial terms, booking, billing and provider enrollment remain consumer-owned.
+
+Descriptors contain schema digests and a service reference, not executable code,
+private instructions or credentials. Do not place sensitive prose in a local
+skill, blueprint, manifest, bundle or model context and expect it to remain hidden.
+A proprietary implementation must stay behind a separately operated service.
+The local harness can call an authenticated remote MCP tool through its configured
+host; installing this package neither configures MCP nor makes that connection.
+
+Consent binds the canonical JSON payload, exact offer and capability, engagement
+revision and a validity interval. Changing any binding requires new consent.
+Revoked/paused engagements and expired consent are refused by local assessment.
+Even a positive result is only `eligible-for-host-validation`, never execution
+authority. These are unsigned local assertions, not authenticated approvals.
+
+A production host must authenticate guide and author, enforce tenant isolation
+and current entitlements/revocation server-side, validate the real schemas, show
+exact outbound disclosure and cost, acquire current authorization, and verify
+the returned output before proposing a local change. Never send private inputs
+just because a descriptor or saved consent says to. Outputs remain untrusted
+proposals and cannot publish, edit canonical sources or grant permissions.
+
+No remote executor, endpoint, credential store, scheduling, billing, browser
+editor or network behavior is added here. Codex Desktop remains the conversation
+surface; the local packet and durable drafts remain independently usable when
+the hosted service is unavailable.