@mnstry/atelier 0.2.0-alpha.13 → 0.2.0-alpha.15

package/src/upgrade/upgrade.mjs

@@ -15,6 +15,7 @@ import {
   writeJson,
 } from '../project/config.mjs'
 import { packageRootFrom } from '../project/package-root.mjs'
+import { canonicalDiffArgs, gitOutputResult, parseDiffSections } from '../boundary/content-rules.mjs'
 import {
   BOUNDARY_POLICY_SCHEMA,
   checkBoundaryPolicy,
@@ -22,12 +23,15 @@ import {
   loadBoundaryPolicy,
 } from '../boundary/policy.mjs'
 import { bundledMnstryReadinessPackV1 } from '../readiness-protocols/bundled-pack.mjs'
+import { bundledReadinessEnabled } from '../readiness-protocols/bundled-selection.mjs'
 import { loadExtensionPacks } from '../extension-packs/loader.mjs'
 import { inspectPackageProvenance, legacyPackageSource } from './provenance.mjs'
 import { prepareUpgrade, applySavedUpgrade, upgradeOperationStatus, recoverUpgradeDryRun, explainSavedUpgrade } from './transaction.mjs'
 import { renderUpgradeExplanation } from './explanation.mjs'
+import { planConsumerClosure, runClosurePlanCommand } from './closure.mjs'
 export { prepareUpgrade, applySavedUpgrade, upgradeOperationStatus, recoverUpgradeDryRun, explainSavedUpgrade }
 export { prepareTemplateUpgrade } from './transaction.mjs'
+export { planConsumerClosure }
 
 export const ATELIER_LOCK_SCHEMA = 'mnstry.atelier-lock@v1'
 export const ATELIER_MIGRATION_SCHEMA = 'mnstry.atelier-migration@v1'
@@ -62,6 +66,20 @@ const normalize = (value) => String(value ?? '').replaceAll('\\', '/').replace(/
 const asArray = (value) => (Array.isArray(value) ? value : [])
 const isObject = (value) => value && typeof value === 'object' && !Array.isArray(value)
 
+function bundledSelectionLockErrors(includeBundled, lock) {
+  if (!lock) return []
+  const recorded = asArray(lock.extensionPacks).some((entry) => entry?.id === bundledMnstryReadinessPackV1.id)
+  if (recorded === includeBundled) return []
+  // The original alpha.0 writer predates bundled pack pins. Preserve its
+  // existing default upgrade path; later empty inventories can be opt-outs.
+  const legacyUnpinned = lock.package?.version === '0.1.0-alpha.0'
+    && (!Object.hasOwn(lock, 'extensionPacks') || (Array.isArray(lock.extensionPacks) && lock.extensionPacks.length === 0))
+  if (includeBundled && legacyUnpinned) return []
+  return [includeBundled
+    ? 'bundled readiness pack is selected but is not recorded in the lock; explicitly write the lock after reviewing pack selection'
+    : 'bundled readiness pack is disabled but remains recorded in the lock; explicitly write the lock after reviewing pack selection']
+}
+
 function sha256(value) {
   return crypto.createHash('sha256').update(typeof value === 'string' ? value : JSON.stringify(value)).digest('hex')
 }
@@ -114,6 +132,7 @@ function loadPolicyForLock(project) {
 }
 
 export function buildAtelierLock({ project, templateId = 'existing-workspace', appliedMigrations = [], packs = [] } = {}) {
+  const includeBundled = bundledReadinessEnabled(project)
   const policy = loadPolicyForLock(project)
   return {
     schema: ATELIER_LOCK_SCHEMA,
@@ -149,11 +168,11 @@ export function buildAtelierLock({ project, templateId = 'existing-workspace', a
     // the manifest bytes plus every referenced protocol file's bytes, so any
     // on-disk edit to the manifest or a protocol is visible byte-for-byte.
     extensionPacks: [
-      {
+      ...(includeBundled ? [{
         id: bundledMnstryReadinessPackV1.id,
         version: bundledMnstryReadinessPackV1.version,
         digest: `sha256:${sha256(bundledMnstryReadinessPackV1)}`,
-      },
+      }] : []),
       ...packs.map((pack) => ({ id: pack.id, version: pack.version, digest: pack.digest })),
     ],
     boundaryPolicy: {
@@ -271,7 +290,7 @@ export const BASE_MIGRATIONS = [
     class: 'template_scaffold',
     title: 'Add missing upgrade documentation scaffold',
     description: 'Add upgrade guidance only when the target file is absent.',
-    files: ['docs/upgrade.md'],
+    files: ['docs/guides/upgrade.md'],
     safety: 'additive',
     reviewMarkerRequired: false,
     explicitConfirmationRequired: false,
@@ -411,18 +430,24 @@ function stagedSemanticFindings(project) {
   const findings = []
   for (const repo of project.repos ?? []) {
     if (!isGitRepo(repo.path)) continue
-    const result = spawnSync('git', ['-C', repo.path, 'diff', '--cached', '--unified=0', '--', '*.md', '*.kg.json'], { encoding: 'utf8' })
-    if (result.status !== 0 || !result.stdout.trim()) continue
-    const diff = result.stdout
-    const changedSemantic = diff
-      .split('\n')
-      .some((line) => /^[+-](?![+-])/.test(line) && SEMANTIC_FIELD_RE.test(line))
-    if (changedSemantic && !REVIEW_MARKER_RE.test(diff)) findings.push(`${repo.name}: staged semantic field change needs Atelier-Boundary-Review marker`)
+    // The boundary guard's pinned diff and parser; only a marker added in this
+    // change approves it, never a removed line or a file name.
+    const result = gitOutputResult(repo.path, [...canonicalDiffArgs(['--cached'], ['--text']), '--', '*.md', '*.kg.json'])
+    if (!result.ok) {
+      findings.push(`${repo.name}: staged semantic fields could not be read (${result.code})`)
+      continue
+    }
+    const sections = parseDiffSections(result.stdout, { detail: true })
+    const changedSemantic = sections.some((section) => section.incomplete
+      || section.hunks.some((hunk) => [...hunk.added, ...hunk.removed].some((line) => SEMANTIC_FIELD_RE.test(line))))
+    const approved = sections.some((section) => section.hunks.some((hunk) => hunk.added.some((line) => REVIEW_MARKER_RE.test(line))))
+    if (changedSemantic && !approved) findings.push(`${repo.name}: staged semantic field change needs Atelier-Boundary-Review marker`)
   }
   return findings
 }
 
 export function planUpgrade({ project, migrations = BASE_MIGRATIONS, allowDirtyGenerated = false, confirmBreaking = [] } = {}) {
+  const includeBundled = bundledReadinessEnabled(project)
   const state = currentState(project)
   const registryErrors = validateMigrationRegistry(migrations)
   const planned = selectedMigrations({ lock: state.lock, migrations })
@@ -430,7 +455,7 @@ export function planUpgrade({ project, migrations = BASE_MIGRATIONS, allowDirtyG
   const warnings = []
   const requiredConfirmations = []
 
-  blockers.push(...registryErrors)
+  blockers.push(...registryErrors, ...bundledSelectionLockErrors(includeBundled, state.lock))
   if (!state.loadedPolicy.ok) blockers.push(...state.loadedPolicy.errors)
   if (state.boundaryReport && !state.boundaryReport.ok) blockers.push(...state.boundaryReport.errors.map((item) => item.message))
   blockers.push(...weakeningFindings({ lock: state.lock, currentPolicy: state.loadedPolicy.policy }))
@@ -606,6 +631,7 @@ export function applyUpgrade({ project, branch, allowDirtyGenerated = false, con
 }
 
 export function checkAtelierLock(project) {
+  const includeBundled = bundledReadinessEnabled(project)
   const { lock, lockPath } = loadAtelierLock(project)
   const errors = []
   if (!lock) errors.push(`lockfile not found: ${lockPath}`)
@@ -626,6 +652,7 @@ export function checkAtelierLock(project) {
       errors.push(item.packId ? `extension pack ${item.packId}: ${item.message}` : `extension packs: ${item.message}`)
     }
     const lockPacks = asArray(lock.extensionPacks)
+    errors.push(...bundledSelectionLockErrors(includeBundled, lock))
     for (const pack of packReport.packs) {
       const entry = lockPacks.find((item) => item?.id === pack.id)
       if (!entry) {
@@ -683,6 +710,10 @@ export function runLockCommand(argv = process.argv.slice(2)) {
 
 export function runUpgradeCommand(argv = process.argv.slice(2)) {
   const args = parseArgs(argv)
+  // `closure` plans against an explicit npm root, which need not be an Atelier
+  // workspace. It runs before the project is resolved, writes nothing, and lets
+  // its typed refusal reach the command wrapper unchanged.
+  if (args._[0] === 'closure') return runClosurePlanCommand(args, argv)
   const project = commandProject({ argv, writeLocalState: args._[0] !== 'explain' })
   if (['plan', 'apply', 'status', 'recover', 'explain'].includes(args._[0])) {
     try {

package/templates/distribution-workspace/README.md

@@ -15,7 +15,7 @@ Every distribution package must carry the exact line below in its README:
 powered by MNSTRY Atelier
 
 `atelier distribution check` blocks on this line. See `TRADEMARKS.md`
-("Required attribution") and `docs/attestation.md` in the Atelier package for
+("Required attribution") and `docs/reference/attestation.md` in the Atelier package for
 the policy and signing details.
 
 ## Projection branding
@@ -81,6 +81,6 @@ atelier lock write --project ./atelier.project.json
 
 ## Learn more
 
-- `docs/distributions.md` in the Atelier package — the full distribution guide.
+- `docs/guides/distributions.md` in the Atelier package — the full distribution guide.
 - `examples/loomworks-studio/` in the Atelier repository — a complete
   reference distribution with a branded wrapper binary and extension pack.

package/templates/external-project-workspace/atelier.project.json

@@ -26,6 +26,9 @@
   ],
   "ext": {
     "mnstry.atelier": {
+      "readiness": {
+        "includeBundled": false
+      },
       "extensionPacks": [
         {
           "id": "sample.readiness",

package/templates/external-project-workspace/pack-lifecycle.json

@@ -11,7 +11,9 @@
         "0.2.0-alpha.10",
         "0.2.0-alpha.11",
         "0.2.0-alpha.12",
-        "0.2.0-alpha.13"
+        "0.2.0-alpha.13",
+        "0.2.0-alpha.14",
+          "0.2.0-alpha.15"
       ],
       "status": "active"
     }

package/templates/knowledge-workspace/README.md

@@ -35,10 +35,10 @@ Its byte budget includes the JSON envelope; token estimates are approximate.
 The tool makes no model calls. Measure actual tokens and resulting work with
 your own agent or host before claiming savings.
 
-The package guide `docs/knowledge-setup.md` explains adoption, limitations, and
+The package guide `docs/start/knowledge-setup.md` explains adoption, limitations, and
 how to measure unseen questions, human correction, and appropriate later reuse.
 
 Open `/knowledge` at the printed address for Onboard, Model, Deepen, Apply,
 and Learn dashboards. Coauthor answers stay in private local history and can
 resume through `atelier knowledge session`. Review exported drafts before
-applying any source change. See the package guide `docs/knowledge-workspace.md`.
+applying any source change. See the package guide `docs/guides/knowledge-workspace.md`.

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

@@ -1,409 +0,0 @@
-# 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

@@ -1,44 +0,0 @@
-# Integration contract decisions
-
-## Responsibility architecture
-
-The [responsibility architecture](architecture.md) is the canonical naming and
-composition model. Keep existing source/API identifiers as compatibility
-surfaces. Responsibilities, roles, methods, resources, records and hosts have
-distinct kinds and typed relationships. This decision adopts the architecture
-direction; it does not declare every consumer implemented or qualified.
-
-Use additive contracts for architecture bindings, practical cases, native ADR
-snapshots and instruction adoption. Existing learning, intake, knowledge and
-capability stores retain their domain ownership. Native ADR identity and
-approvals remain with the repository that issued them. An imported decision
-never becomes a new local approval automatically.
-
-Preview and runtime must map authored fields to the same relevant domain rules.
-Unsupported required behavior is a visible resolution failure. Installation,
-actual loading, operation execution, durable readback and behavior assessment
-remain separate evidence. Reconsider this architecture if a proposed workflow
-requires a competing domain writer or an unrelated mandatory stage.
-
-<!-- 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 ([inspection-bundle.mjs](../src/collaboration/inspection-bundle.mjs); [prepareInspectionBundle](../src/collaboration/inspection-bundle.mjs#L37-L105)) | No active-state overwrite, execution, secret transfer or approval import ([prohibitedKeys](../src/collaboration/inspection-bundle.mjs#L16-L36), [inspectBundle](../src/collaboration/inspection-bundle.mjs#L106-L197), [read and write paths](../src/collaboration/inspection-bundle.mjs#L198-L223)). |
-| Pack compatibility | New versioned lifecycle declaration ([lifecycle.mjs](../src/extension-packs/lifecycle.mjs); [inspectPackLifecycle](../src/extension-packs/lifecycle.mjs#L14-L121)) | Legacy packs remain inspectable; closed v1 contracts are not silently widened ([legacy packs inspectable; closed declaration and entries](../src/extension-packs/lifecycle.mjs#L14-L121), [rootVersion](../src/extension-packs/lifecycle.mjs#L7-L12)). |
-
-<!-- Whole-file citations here rely on decision-practice definition revision three, which drafts on added as well as modified or removed lines. Uncited: Package provenance, Evidence snapshot, Claim decision and Document response await symbol-level citation support in the decision-practice consumer. -->
-
-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.