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

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.

package/docs/local-review.md

@@ -0,0 +1,84 @@
+# Local source review
+
+The optional review workspace helps a reader inspect claims, ask a question or
+propose a correction, and retain that contribution. It records **locally asserted
+identity**. A typed name is not an authenticated approver. Acceptance does not
+edit source, publish content, grant access or admit a runtime.
+
+Start with `atelier init --template external-project --target NEW_DIRECTORY`.
+Use a destination whose ancestors are real directories, not symlinks. The
+starter refuses existing destinations and does not initialize Git or install
+hooks. Initialize its adapter and synthetic source as separate repositories when
+ready. An established repository can replace the synthetic source through
+`--repo-path source=PATH`; this changes location, never read authority.
+
+From the adapter, run `atelier graph`, then `atelier project`, followed by:
+
+```sh
+atelier review packs
+atelier review run sample.readiness:contract-gate --answers answers.example.json
+atelier dev --review
+```
+
+Open `/review` on the loopback address printed by the foreground sidecar. Enter
+repository `source` and path `README.md`, copy an exact passage, type a question
+or correction, and choose **Save response**. Save is confirmed only after the
+ledger acknowledges the write. On contention, stale content or service failure,
+the wording remains in the form and the page does not claim success. Retry an
+unchanged contribution after restoring service. A changed draft is a new request.
+Unsaved browser drafts are not durable across tab closure.
+
+To resume, save a reading position using the exact passage. Close the page,
+reopen it, enter the same asserted name and choose the recorded **Resume** button.
+The response history remains visible. A position is restored only against the
+same document digest. After a source edit, earlier responses retain their exact
+wording, anchor and original digest; explicitly select a passage in the new
+revision and contribute a new response. Reading and scrolling never imply agreement.
+
+Enter the returned run ID to review individual subject/predicate/object claims.
+Each shows its ID, mapped answer fields, source-reference resolution, source
+identity and a bounded excerpt. References in this first cut resolve exact graph
+node IDs. Free text, URLs and other reference schemes remain unresolved; they
+are never silently treated as source evidence. A linked source establishes
+which bytes were read, not whether they logically support the proposed claim.
+Read the document and record your judgment. Missing mapped sources or required
+answers prevent acceptance. Rejection and revision remain available against
+current evidence, so missing evidence can be discussed honestly.
+
+Accept/reject/revise requires a reason, request ID and expected version. Every
+contribution is immutable. Subsequent versions link through the same claim/run
+identity and target version; proposed successor wording is retained without
+rewriting the original claim. A later rejection supersedes an earlier acceptance
+for current handoff. An identical retry returns the prior record. Another
+reader's intervening contribution refuses a stale version; reopen the run before
+making a new decision. Previous history remains visible rather than being
+collapsed into a single latest-state approval.
+
+**Inspect owner handoff**, or `atelier review handoff REQUEST_ID`, displays the
+proposed relationship, rationale, affected IDs and required evidence digest.
+The source owner decides the concrete edit in its own workflow. Source changes
+remain unapplied and promotion remains unestablished. No owner-application receipt
+or publication authorization is fabricated. Changed source/configuration,
+policy, pack or evaluator inputs make current handoff ineligible.
+
+The legacy readiness score and `ready`-shaped packet fields retain their existing
+contract meanings: input completion and draft preparation. They are not evidence
+confidence, independent rule execution, human acceptance or runtime readiness.
+New claims omit the former arbitrary numeric confidence. Bound snapshots store
+protocol content, normalized answers, pack identity, declared source byte digests,
+policy identity, and the shipped source/schema evaluator inventory. Dependency
+bytes and upstream publisher authentication need separate installation proof.
+Historic v1 runs without snapshots remain available through the existing readiness
+commands, but cannot be accepted as current evidence through this review surface.
+
+The existing sidecar supplies loopback host/origin checks, session nonce checks
+and private-file protection. `--review` is opt-in. The new ledgers live separately
+from legacy proposals under `.atelier-local/review/`. Each record occupies its own
+immutable event aggregate, so existing compaction retains the complete audit
+history. Per-target versions are checked while holding the ledger write lock.
+Local files and locally asserted identities are not protection from an operator
+who controls that same account and its filesystem.
+
+Synthetic installed and browser checks establish software behavior. An unfamiliar
+reader's useful question or correction, assistance required, and actual adopter
+acceptance still need a human observation; automated tests cannot supply it.