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

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.6
+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.6"
+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.6"
+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.

package/docs/integration-and-review-plan.md

@@ -0,0 +1,409 @@
+# External-project integration and human review implementation plan
+
+Status: local implementation candidate. See the feature guides for implemented behavior; final source-bound review, release and human acceptance remain separate gates.
+Baseline: `58895eafbd980ae131d8c5f2d1882ac34f5c08b9`, tree `72f06c2aa8183f93dc2b49066a5c4e55d1c2f336`.
+
+<!-- mnstry-review-request: atelier-integration-plan-r1 gate: plan-readiness -->
+<!-- mnstry-review-workflow: atelier-integration-plan-fable-low-r3 gate: plan-readiness stage: planning -->
+
+## Outcome and authority
+
+A domain owner can connect an established repository through a bounded adapter,
+run its declared method, inspect proposed claims and their evidence, retain
+individual review decisions, and resume without losing authorship or historical
+meaning. Canon stays in the domain repository. The root supplies generic
+contracts, validators, local review behavior, templates, and synthetic proof.
+
+Implementation is authorized as local pre-production work. This plan introduces
+no publication, remote deployment, collaborator enrollment, remote access,
+automatic canonical writes, or member/tenant activation. Approval of a proposal
+does not authorize publication, runtime admission, or consent changes. Existing
+consumer reading and meeting workflows do not depend on this full programme.
+
+All fixtures must be independently invented. Do not copy private correspondence,
+domain names, vocabulary, methods, information architecture, or operational
+details into this repository. Review packets and implementation branches must
+respect the same boundary.
+
+## Baseline findings and evidence
+
+1. `src/project/config.mjs` resolves repository paths in this order: CLI
+   `--repo-path`, ignored local overlay, tracked relative path, sibling discovery.
+   Discovery checks the declared remote when supplied. Command resolution also
+   ensures local state, so describe its possible filesystem writes accurately.
+2. `src/commands/extension-pack.mjs` has a separate option allowlist that rejects
+   `--repo-path` before `commandProject()` executes. Reproduction on Node 22.18.0:
+   `node bin/atelier.mjs extension-pack list --repo-path=sample=.`.
+3. `src/upgrade/upgrade.mjs:packageSource()` captures HEAD only when the installed
+   package directory is itself the Git top-level. Repository metadata without
+   that checkout becomes `private_github` with a null SHA. The lock schema already
+   permits `gitSha`; repository metadata alone cannot prove installation type.
+4. `src/collaboration/proposals.mjs`, `src/collaboration/event-ledger.mjs`, and
+   `src/server/local-sidecar.mjs` provide review records, concurrency machinery,
+   and proposal pages. Readiness proposals currently carry claims as JSON.
+5. `src/readiness-protocols/runtime.mjs:evaluateProtocolAnswers()` measures
+   required-answer presence. `claimsForProtocolRun()` assigns 0.7 or 0.2 based on
+   whether any answer is present, and references a run rather than specific
+   supporting source evidence. Neither is calibrated evidence confidence.
+6. `atelier-claim@v1` fixes `status: proposed` and `promoted: false`.
+   `atelier-readiness-run@v1` identifies a protocol but does not itself establish
+   a complete source/pack/evaluator snapshot for historical reproduction.
+7. Existing distribution/private-domain/shared-project templates, normative
+   audience guidance, extension pack versions/digests and migration declarations
+   provide foundations. They do not constitute a demonstrated end-to-end
+   external-project review experience.
+
+These are bounded source observations, not an exhaustive implementation review.
+Other branches are not assumed landed. Refresh main and reconcile owner changes
+before each implementation stage.
+
+## Design decisions for the first implementation
+
+- Reuse the proposal ledger and local sidecar; do not create a second review
+  database or weaken their current authentication, origin, CSRF, path, private
+  file, or concurrency controls. Validate reusable fit before adding UI.
+- Preserve immutable v1 claim records. Add a separate versioned review-decision
+  contract and derived views. Authoritative new semantics belong in a real
+  contract, not in an unvalidated `ext` member that old consumers ignore.
+- Acceptance prepares an explicit change proposal for the source owner. The
+  source owner applies it through its own workflow. No automatic apply action.
+- Initially make portable bundles inspection-only. Imported review decisions
+  remain attributed historical assertions, never current local approval.
+- Preserve local-only defaults. Export is an explicit local operation, not sync
+  or upload. A later encrypted bundle must identify its recipient and selected
+  disclosure scope without exposing private content in logs.
+- Preserve established CLI aliases and exit codes unless a documented,
+  versioned change is unavoidable. No new runtime dependency is assumed.
+- External-project is an architecture pattern, not an instruction to use
+  `repos[].kind: external`: that kind is unmanaged and supplies no read boundary.
+  The adapter must explicitly declare the actual read authority and allowed refs.
+
+## Work packages and dependency order
+
+### W0 — Baseline, ownership, contracts, and plan disposition
+
+Own an isolated root worktree; keep the ordinary checkout and other writers
+untouched. Record base SHA/tree, clean status, current branch work and any
+overlapping unlanded changes. Resolve overlap through evidence and the source
+owner before editing the same boundary. Never import sibling private data.
+
+Disposition every plan finding as accepted, rejected with evidence, or deferred
+with a bounded reason. Blocking design findings precede dependent implementation.
+Prepare a contract compatibility decision for each new schema and public API.
+Do not silently widen existing v1 contracts or rewrite historical runs.
+
+For every proposed artifact, record reuse, compatible extension, or a separate
+versioned contract with its reason. Inventory existing JCS, attestation,
+support-preview/disclosure, export and migration facilities before adding new
+machinery. Shared hashing or validation does not imply shared artifact semantics.
+Resolve claim-decision aggregate identity, required concurrency version,
+idempotency and full-history retention before implementing the review endpoint.
+Legacy proposal readers must never encounter new event types in their proposal
+aggregates; prove compatibility against the actual pre-change reader.
+
+### W1 — Shared project options and transparent resolution
+
+Files: `src/project/config.mjs`, `src/cli/`, all project-aware command entry
+points in `src/commands/`, command help, project/config tests.
+
+Inventory commands first: classify project-aware versus standalone commands,
+direct-module versus wrapper entry, accepted aliases, environment inputs, and
+side effects. Introduce a shared option definition/parser for project location
+and repo overrides. Unknown command-specific options still fail; a shared
+parser must not accept every argument everywhere. Keep both `--flag=value` and
+`--flag value`, repeated named overrides, missing values, and malformed entries
+explicit. Choose and document duplicate override behavior from current callers.
+
+Document precedence and provide resolution diagnostics showing logical repo,
+resolution source, and declared identity without leaking machine paths in
+portable output. Preserve required-repo failure and all boundary validation.
+Test each command family against a moved two-repository fixture, both through
+the published CLI and an invented wrapper. Include missing/malformed values,
+unresolved required repos, identity mismatch, and unchanged read scope.
+
+### W2 — Installed-package provenance
+
+Files: `src/upgrade/upgrade.mjs`, lock tests, consumer/distribution smoke,
+`docs/install.md`, `docs/upgrade.md`; schema change only if the compatibility
+decision requires it.
+
+Distinguish installed package source from consumer-project source. For a Git
+checkout use its own commit plus dirty-state qualification. For an npm Git
+dependency inspect supported install-lock metadata and match the exact package
+instance, including nested installs and workspace/symlink resolution; never
+borrow the consumer repo HEAD or trust a URL/ref as an immutable commit.
+Registry/tarball installs record available integrity/provenance without inventing
+a Git SHA. Define metadata precedence and refuse conflicting provenance.
+
+Distinguish a declared install origin, observed installed-byte identity, and
+verified source binding. Lock metadata alone is a declaration. An installed-tree
+digest can detect change against a trusted earlier inventory, but cannot prove
+that the declared commit produced those bytes. Define the inventory, links,
+excluded generated files and trust anchor before claiming exact source. A clean
+checkout establishes its tracked commit only; separately account for untracked,
+ignored or generated files that may affect execution. An exact-source check
+must refuse an unverified binding even when a locally recorded digest matches.
+
+Keep historical locks readable. Report legacy/unresolved provenance explicitly;
+an exact-source-required check must fail for unresolved or dirty source. A
+missing Git SHA must not imply private Git origin. Never write credential-bearing
+remote URLs into locks or logs. Test local Git dependency installation with Git
+metadata stripped, tagged/branch inputs, registry-shaped and tarball fixtures,
+multiple package instances, symlinks, dirty checkout and contradictory metadata.
+Use local synthetic repositories and package archives; no registry/network test
+is required to prove these cases.
+Include a declared Git revision with modified installed bytes, and verify that
+neither the declaration nor a newly computed digest reports verified origin.
+
+### W3 — Official external-project starter and audience guidance
+
+Files: `templates/`, `src/commands/setup.mjs` or existing setup owner,
+`docs/install.md`, `docs/distributions.md`, `docs/blocks/audience-visibility.md`,
+template and consumer smoke tests.
+
+Compose existing templates into an invented two-repository example with project
+config, bounded source contract, strict policy, namespaced pack, synthetic
+protocol/answers, local-state exclusions, and documented validation commands.
+No proprietary domain shape may be used as the fixture scaffold. Configuration
+must state which repository owns facts, proposed changes, run state and outputs.
+
+Reference and compose existing CI, consumer-smoke and distribution-smoke paths
+for graph, pack, boundary, readiness and lock proof; add only missing coverage
+under the current execution policy. Documentation does not dispatch CI.
+Setup refuses overwrite and unsafe destination paths. Inspect and test
+reference traversal, symlinks and path escape using existing defensive controls.
+Make source audience, review acceptance, publication eligibility and runtime
+visibility separate in the starter and review copy. A public source is not a
+publication consent or runtime access grant.
+
+### W4 — Evidence-bound runs and honest evaluation
+
+Files: `src/readiness-protocols/runtime.mjs`, affected contracts, validators,
+readiness CLI/renderers and tests.
+
+Separate input completeness, executable rule checks, unresolved evidence,
+human judgment and runtime readiness. Preserve the legacy score as documented
+input completeness; do not silently change the meaning of old results. New
+claims omit unsupported confidence or explicitly identify the method and its
+limits. No calibrated confidence claim without a defined evaluation dataset.
+Apply these distinctions to rendered labels, examples and screenshots as well
+as stored fields. A completed answer form must never appear to establish
+evidence strength, human acceptance or runtime readiness.
+Inventory the run, journey, packet and summary surfaces together. Preserve
+legacy field/status meanings where contracts require them, and explain them in
+the view rather than silently changing existing status literals.
+
+Bind each new run to exact relevant source revisions/content digests, bounded
+reference set, answers digest, protocol digest/version, pack digest/version,
+evaluator identity and applicable policy digest. Reuse `src/attestation/jcs.mjs`
+for canonical JSON and specify the byte/hash envelope. Evidence digests must identify the content
+actually read; a clean repository HEAD alone is insufficient for dirty sources.
+Do not create a timing gap between inspected bytes and recorded identity.
+
+Show field-level evidence links for mapped claims, missing evidence and unresolved
+references. Separate source-backed assertions from an operator's recorded answer.
+Historical v1 runs remain readable but are labeled provenance-incomplete. New
+source/protocol/policy changes invalidate current eligibility for affected reviews
+without changing old records. Test changed source, dirty source, changed pack,
+policy change, absent evidence, migration and deterministic replay under pinned
+inputs; timestamps/run IDs need not match for semantic replay.
+The current run ID hashes project name, protocol ID, normalized answers and
+time; it does not bind protocol content, source bytes, pack or policy. It may
+identify a historical run but cannot replace evidence binding or justify moving
+current decision eligibility ahead of this prerequisite. Revalidate the bound
+evidence inside the decision mutation, not solely when rendering its form.
+
+### W5 — Structured claim decisions and owner handoff
+
+Files: `src/collaboration/`, proposal rendering modules located from sidecar
+imports, `src/server/local-sidecar.mjs`, new review contract and tests.
+
+Render subject/predicate/object with readable labels, original IDs, evidence
+excerpts/links within the read boundary, limitations, conflict indicators,
+source/run identity, and current decision eligibility. Accept, reject and revise
+operate per claim with reviewer attribution, rationale and an exact expected
+revision. Required optimistic concurrency checks must apply at the mutation
+boundary, not just the UI. Explicitly describe local asserted identity versus
+authenticated reviewer identity; typed names alone do not prove human approval.
+Record and render an explicit local-asserted identity kind. Require a client
+decision ID and expected aggregate version; an identical retry returns the
+existing decision, while reuse of the ID with different content fails.
+
+The rendered acceptance check must let a reader identify the proposed change,
+its rationale, supporting evidence, uncertainty or conflicts, intended effect
+of acceptance, and the person or source workflow authorized to apply it.
+An identifier or an accept button alone does not satisfy this check.
+
+Revision creates a linked successor rather than overwriting the original claim.
+Decisions are separate append-only records with verifiable links to claim and
+evidence identity. Retries are idempotent. A change during review refuses stale
+acceptance. Crash recovery reconstructs views from the ledger without silently
+losing or duplicating decisions. Bulk review is not part of the first slice.
+New decisions use distinct aggregates and a versioned contract, sharing proven
+persistence primitives without inserting unsupported events into legacy proposal
+aggregates. Define retention that preserves every decision: current generic
+compaction keeps only selected events, so a latest-state checkpoint alone is
+not a complete decision audit history. Test compaction beyond count/time limits,
+replay, and the old proposal reader against the resulting store.
+
+An accepted decision creates a reviewable owner handoff showing intended source
+edits, affected IDs and required source revision. It grants no canonical write,
+publication or runtime capability. Promotion status is shown only from a
+separate source-owner receipt; absent receipt means not established.
+Evaluate `git-promote-event@v1` for actual cross-repository disclosure events.
+It does not by itself prove that an accepted semantic edit was applied; any
+owner-application receipt must bind the decision, intended edit and resulting
+source revision, with authority appropriate to that workflow.
+
+Tests: claim-level mixed decisions, stale views, concurrent requests, retries,
+crash/restart, missing evidence, source movement, hostile display text, unauthorized
+review, unchanged canonical bytes, and accepted-without-promotion behavior.
+
+### W6 — Reusable document response and resume slice
+
+Dependencies: W4/W5 review identity and persistence contracts, but ship a bounded
+local slice independently of pack migration and portable bundles.
+
+Use one invented document to prove a reader can open a passage, leave a question
+or correction, see save state, close, reopen and find the same response and
+reading position. Bind response to document identity, exact revision and stable
+anchor; retain the original wording and distinguish generated summaries.
+Changed document revisions retain prior responses and require explicit
+reassociation. Aggregate unresolved responses and explicitly recorded decisions
+into a discussion view. Reading/scrolling/no response never means agreement.
+
+The root owns generic passage references, response records and UI primitives;
+consumer repositories own content, reading order, prompts and delivery/access.
+Do not convert packet responses into semantic claims automatically. Verify
+keyboard operation, visible focus, save failure/retry and two-view conflicts.
+Use the established loopback local-service contract for browser proof. No
+physical device, remote collaborator access or onboarding is implied.
+
+Qualify save/resume as one required sequence: contribute a response, observe
+durable save acknowledgement, close, reopen, and recover both original wording
+and reading position. Exercise failed save/retry and changed document revision
+in that sequence; a pending or failed write must never display as saved.
+Include the existing ledger's 423 lock-contention response and retry path.
+Presence/seen records with no responses must still render as unanswered.
+
+Evaluate first use with an unfamiliar reader and an invented document: can
+they make one useful question or correction without prior installation,
+ontology or agent-skill instruction? Record the assistance required and any
+point where they cannot proceed. Technical setup completion is a separate
+result; actual adopter usefulness still needs its own human acceptance record.
+
+### W7 — Extension-pack lifecycle
+
+Files: extension loader, pack/protocol contracts, migration checks, fixtures and
+new lifecycle documentation.
+
+Define substrate compatibility ranges, pack content identity, deprecation and
+replacement terms, protocol version changes and migration modes. Reject an
+unsupported combination before new execution. Preserve old term meaning and
+source/run records; never silently reinterpret them with the newest pack.
+Migration is dry-run first with a report and explicit owner application. Do not
+execute arbitrary extension code or install dependencies as part of loading.
+Historical inspection uses pinned content or marks missing historic dependencies.
+Reuse existing pack digest/lock validation and the upgrade migration registry.
+A required compatibility range cannot be added silently to the closed v1 pack
+contract; record a compatible representation or explicit new-version migration.
+
+Specify the legacy-pack policy: readable and inspectable does not automatically
+mean admitted for new exact-reproducibility execution. Include a compatibility
+matrix for old/current root, old/current pack, historical/new run and migration
+availability. Test refusal, deprecation reporting, replay and rollback.
+
+### W8 — Private run-state policy and portable inspection bundles
+
+Document state classes first: tracked contracts/configuration; ignored local
+answers, runs and decisions; regenerable views/caches; ephemeral sessions/nonces;
+secrets/grants that are never transferable. Git checkout portability is distinct
+from active review portability. Backups are explicit owner-managed actions.
+
+Specify the inspection-bundle manifest after the W0 reuse decision, including
+selected members, sizes/digests, format version, source/pack identities, disclosure
+classification and verification result. Evaluate existing export and support-preview contracts. Reuse their
+primitives where suitable; a runtime export and a private historical inspection
+bundle have different authority and must not be forced into one schema merely
+because both carry provenance. Reuse the existing disclosure scanner and preview
+controls, and the attestation verification path where an applicable trusted
+signature exists. A valid signature still requires signer authorization and
+does not import current approval. Signing is not encryption.
+Export only selected bounded artifacts after an inspectable disclosure preview
+and required disclosure check. Fail closed when the check is unavailable; do not
+label an unchecked export safe. Omit auth/session/grant material and absolute
+machine paths. No silent synchronization or upload.
+
+Import first validates bounded sizes/counts, member digests, paths, duplicates,
+links, versions and content rendering, then exposes an isolated inspection view.
+It cannot overwrite active local state, install packs, execute content or import
+approval authority. Keep foreign decisions visibly attributed and unverified
+unless their actual signature/trust policy is verified.
+
+Encrypted export is a distinct substage: select a maintained local encryption
+mechanism with an explicit recipient/key custody contract, dependency rationale
+and failure tests. Do not invent encryption or claim hashes authenticate a
+sender. Complete manifest/inspection behavior first; encryption and external
+sharing stay unavailable until that mechanism is explicitly selected and proved.
+Test disclosure failures, tampering, truncated archives, unknown versions,
+oversized content, traversal/symlink refusal, duplicate members and inert import.
+
+### W9 — Installed workflow, release evidence and consumer handoff
+
+Test the exact packed artifact in a fresh synthetic two-repository workspace:
+setup -> resolution -> bounded graph/pack checks -> readiness -> claim review ->
+owner handoff -> close/reopen. Repeat under different local folder structures,
+then an explicit pack upgrade. Include the document response slice, source
+immutability, stale-decision refusal and inspection-only bundle behavior.
+
+Use Node 22.18.0. Run focused regression suites, syntax, complete discoverable
+tests, contract and public API compatibility, migrations, disclosure and exact
+tarball/consumer checks. Verify test discovery includes new nested tests; either
+place tests under current discovery or reconcile the separate discovery work.
+Use the maintained private disclosure lane, never substitute structural-only
+results. Existing global failures are reported separately with exact evidence.
+
+An implementation review binds the final candidate and changed contracts. Valid
+review findings are dispositioned and fixed before closeout; a plan review is
+not implementation proof. Refresh main and prove required checks before landing.
+Publishing a package, deployment, consumer activation and human acceptance remain
+separate gates requiring their own authority and evidence.
+
+## Proposed delivery cuts and acceptance gates
+
+1. Reliability: W0-W3. External adapter setup works from the installed artifact
+   on two layouts; every documented project-aware invocation accepts the shared
+   options; source identity is exact or visibly unresolved. No canonical writes.
+2. Human review: W4-W6. A domain owner can understand each claim, inspect evidence,
+   record a decision, retain an attributed response and resume. Stale acceptance
+   fails; original source and historical claims remain unchanged.
+3. Lifecycle: W7-W8 plus W9. Upgrade preserves historical meaning; selected state
+   travels only through validated inspection bundles. Imported evidence never
+   becomes approval. Encryption is qualified separately before availability.
+
+Each cut has focused local proof, exact source identity, review disposition,
+rollback and a clear remaining-gates statement. Consumer human acceptance is
+obtained separately; synthetic/browser proof cannot substitute for it.
+
+## Rollback and recovery
+
+Pin the prior package and packs; retain original documents and append-only
+responses/decisions. Disable optional new views/exports without deleting state.
+Old versions must reject unknown authoritative records or ignore them only when
+that cannot grant authority. Demonstrate rollback with historical data before
+shipping migrations. Import never writes into the active state directory.
+
+## Reviewer challenge and open decisions
+
+Prefer static inspection and existing defensive tests. Challenge dependency
+order, contract evolution, exact provenance, stale acceptance, local reviewer
+identity, disclosure, import authority, legacy compatibility and scope growth.
+Return evidence, files, severity, confidence, impact, remediation order and
+testable acceptance changes. Do not execute new live abuse paths or edit source.
+
+The review must distinguish plan completeness from implementation correctness.
+Known decisions: owner-applied canon and inspection-only imports are first-cut
+defaults; authenticated multi-user approval, cross-computer continuation of active
+authority, concrete encryption/key custody, remote onboarding and any calibrated
+diagnostic scoring require explicit later design decisions. Their absence does
+not block the independent reliability and local review cuts.

package/docs/integration-contract-decisions.md

@@ -0,0 +1,22 @@
+# Integration contract decisions
+
+<!-- mnstry-review-workflow: atelier-integration-implementation-r1 gate: implementation-readiness stage: closing -->
+
+These decisions implement the first local integration cut. They do not satisfy
+independent review, publication or human acceptance.
+
+| Artifact | Decision | Compatibility and authority |
+| --- | --- | --- |
+| Package provenance | Separate versioned diagnostic; retain v1 lock fields | Declared origin and observed bytes do not authenticate an upstream publisher. Exact checks require verified binding. |
+| Evidence snapshot | Separate content-addressed record using existing JCS | Existing v1 runs stay readable; missing snapshot means no current decision eligibility. |
+| Claim decision | Separate immutable decision aggregate and contract | Never insert new event types into legacy proposal aggregates. Stable request identity and expected version are mandatory. |
+| Document response | Separate passage-bound record | A question/correction is not a semantic claim or agreement. |
+| Owner handoff | Derived proposed change | No canonical apply or publication authority; cross-repository Git disclosure is a distinct event. |
+| Inspection bundle | Separate inert artifact; reuse disclosure/JCS | No active-state overwrite, execution, secret transfer or approval import. |
+| Pack compatibility | New versioned lifecycle declaration | Legacy packs remain inspectable; closed v1 contracts are not silently widened. |
+
+Reuse existing private-file, ledger, origin/nonce, JSON validation and
+attestation primitives where applicable. Decisions retain complete history;
+latest-state compaction alone is not an audit archive. Local typed identity is
+explicitly asserted, not authenticated. Encryption and transfer of active
+authority require a separate custody design before availability.