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

package/docs/release-engineering.md

@@ -30,6 +30,9 @@ consumer smokes:
 - Version drift: `CHANGELOG.md` must contain a `## <version>` heading and
   `README.md` must mention the version. The expected version and tarball name
   are derived from `package.json`, never hardcoded.
+- Declared exports: every `exports` target in the packed `package.json` must
+  be a file the tarball carries.
+- Obsidian package contents: see [Obsidian package contents](#obsidian-package-contents).
 
 Exit codes: `0` clean, `1` findings, `2` configuration error (for example an
 unavailable denylist without explicit acknowledgment).
@@ -43,6 +46,78 @@ publishing workflow runs `prepublishOnly` explicitly with that output directory,
 re-verifies the retained digest, and publishes the retained tarball path rather
 than repacking the source checkout.
 
+### Obsidian package contents
+
+The Obsidian projection ships as runtime, contracts and documents, and its
+proof tooling does not ship. `release:audit` enforces both halves on the exact
+tarball.
+
+Shipped, and required by the audit:
+
+- The entry points behind the package subpaths `./obsidian` (maintenance
+  runtime, `src/runtime/obsidian/index.mjs`), `./obsidian/contracts`,
+  `./obsidian/materialize`, `./obsidian/publication`, `./obsidian/recovery`,
+  `./obsidian/edits`, `./obsidian/proposals` and `./obsidian/selection`, with
+  `src/commands/obsidian.mjs`, the service entry and the two contribution
+  modules under `src/runtime/obsidian/contributions/`.
+- Every `contracts/atelier-obsidian-<name>.v<n>.schema.json` present in the
+  source tree (lowercase name, versioned). Each must be packed and exported
+  under its own path, and the audit fails if it finds none.
+- `docs/obsidian.md` and `docs/obsidian-contract.md`.
+- `fixtures/obsidian/**`: small synthetic text only. Every packed fixture, in
+  any subtree and spelling under `fixtures/`, is at most 262,144 bytes. The
+  acceptance receipts under `fixtures/obsidian/acceptance/receipts/` are
+  synthetic shape fixtures whose host id matches `host-synthetic-*` and whose
+  operator id is `operator-synthetic`; the schema fixtures under
+  `fixtures/obsidian/contracts/` carry no identity block. Validating one closes
+  nothing.
+
+Never shipped, and refused by name in addition to the path allowlist:
+
+- `scripts/**` (including the `scripts/obsidian/` desktop harness, scale
+  generator and receipt verifier), `test/**`, `experiments/**`, `examples/**`.
+- Any `.artifacts/` directory, where acceptance receipts and their evidence
+  are written.
+- Any `.asar` file.
+- An acceptance receipt outside `fixtures/obsidian/`, one carrying the desktop
+  harness extension (`mnstry.atelier.obsidian.desktop-receipts`), or one whose
+  host or operator id is not the synthetic form above (or, outside the schema
+  fixtures, one with no identity block): that document records a real host,
+  even with the harness block removed.
+- Scale corpora and binary samples. They are generated in temporary storage at
+  test time and are never files of this repository.
+
+The path allowlist was not widened for the Obsidian projection. Every check
+above refuses more than the allowlist alone did.
+
+`test/obsidian-package.test.mjs` is the AP-06 package proof and runs with the
+ordinary test suite. It packs the package, extracts it into a bare consumer
+project, links the locked runtime dependencies from the checkout, and from a
+separate process imports every Obsidian subpath by package name, checks that
+an undeclared internal path stays closed, and runs the production pipeline
+(canonical graph, source snapshot, `prepareView`, `publishView`) over a
+synthetic workspace into a temporary vault that no application has open. A
+document the census did not classify must not reach the vault. It also packs
+a synthetic package containing each refused class and matches each audit
+refusal by message. It does not run `npm install`; `consumer:smoke` does, on
+the same tarball contents, and imports every declared export including these.
+
+Limits of this proof:
+
+- It is package proof only. Gate G18 also requires a separately recorded
+  adopter acceptance, and nothing in this repository produces or implies one.
+- It never starts the app. Behaviour inside a running app is acceptance
+  evidence from `scripts/obsidian/desktop-receipts.mjs` on a desktop host and
+  is not covered by any CI lane. No CI lane has a desktop session.
+- Publication is skipped where no atomic exchange exists. On Windows the
+  publisher refuses with `exchange-unsupported-platform`, so the Windows
+  portability lane runs the pack, import and `prepareView` cases and skips the
+  publish case.
+- The `*ForOracleTests` names exported by the Obsidian modules are mutation
+  controls for the test suite. They ship because the modules that define them
+  ship; they are not a supported API and carry no compatibility promise. They
+  should be excluded when the public API baseline is next regenerated.
+
 ### repo:check
 
 `npm run repo:check` (`scripts/check-repo-disclosure.mjs`) sweeps the whole
@@ -116,8 +191,23 @@ function signatures, types, or behavior.
 ### egress:check
 
 `npm run egress:check` (`atelier egress check`) scans package runtime paths for
-forbidden non-localhost egress. The package claims no network egress in runtime
-paths; this gate is the mechanical check behind that claim.
+forbidden non-localhost HTTP egress primitives. The package claims no silent or
+undocumented runtime egress; this gate is one mechanical check behind that
+claim. It does not interpret data-only Markdown/JSON and does not model
+`child_process`, so the reviewed `gh` identity-resolution subprocesses and the
+explicitly enrolled Atelier Sync Git fetch/non-force-push subprocesses are
+documented exceptions backed by dedicated refusal tests. Sync refuses fetch on
+an incomplete observation, refuses publish while prior local commits are
+unpublished, strips repository/config retargeting environment variables, and
+pushes the exact post-hook-verified commit object without following tags or
+recursively publishing submodule refs. Its boundary check also suppresses the
+optional network actor fallback.
+
+The optional `vault` API is explicitly host-bound: provider storage, metadata
+and identity bindings can perform network I/O when invoked by a consuming host.
+The core does not install SDKs or start a listener. The lexical egress scanner
+does not model SDK method calls; vault behavior requires its own conformance
+suite and independent review. No egress suppression marker is added for it.
 
 ### consumer:smoke
 
@@ -210,6 +300,13 @@ A version bump touches exactly:
 - `CHANGELOG.md` (a `## <version>` heading)
 - the pinned install tags in `README.md`, `docs/install.md`,
   and `docs/upgrade.md`
+- `compatibleRootVersions` in
+  `templates/external-project-workspace/pack-lifecycle.json`, so the shipped
+  starter's pack is qualified for the released root version (the
+  `review packs` consumer smoke and `test/review-portability.test.mjs` fail
+  when it lags)
+- the linked package version recorded in
+  `examples/astro-presentation/package-lock.json`
 
 The release scripts derive the expected version and tarball name from
 `package.json`, so they are not part of the bump surface, and `release:audit`

package/docs/review-portability.md

@@ -0,0 +1,55 @@
+# Review state and portable inspection
+
+| State | Ownership and portability |
+| --- | --- |
+| Contracts, adapter configuration and declared packs | Track in the adapter; domain facts stay in their source repository. |
+| Real answers, evidence snapshots, responses and decisions | Ignored owner-local state; backup is an explicit owner action. |
+| Projections and caches | Regenerable, subject to the same content disclosure boundary. |
+| Session state, nonces and presence | Ephemeral; never exported with review records. |
+| Secrets, credentials, grants and signing keys | Nontransferable through the inspection format. |
+
+Moving a Git checkout does not transfer active review authority. This feature
+exports selected historical evidence for inspection; it does not synchronize
+state, upload files, install packs, execute migrations or import current approval.
+There is no encrypted-export option. Encryption, recipient selection and key
+custody require a separate design and qualification. Hashes are not encryption
+and do not authenticate a sender.
+
+Preview a selected run and optionally selected response/position request IDs:
+
+```sh
+atelier review export --runs RUN_ID --responses RESPONSE_ID,POSITION_ID --denylist PRIVATE_POLICY.json
+```
+
+The disclosure policy must contain the `patterns` array used by the existing
+scanner; maintain it privately. The command fails closed if that policy is
+unavailable or rejects selected content. Preview reports selected identities,
+byte counts and digests. Inspect the selected local history and evidence before
+writing the reviewed selection. Then repeat with `--write --out inspection.json`.
+An existing output file is never overwritten. The current selection is validated
+and disclosure-checked again at write time. Exports contain private excerpts and
+asserted names, so an empty policy is appropriate only for an invented fixture.
+
+`atelier review inspect inspection.json` validates the version, closed contracts,
+member count/byte bounds, JCS SHA-256 digests, duplicate identities and historical
+links before displaying inert JSON. It does not resolve a project or write active
+state. Foreign decisions remain visibly unverified historical assertions. The
+format carries no trusted signature: there is no applicable signer authorization
+or attestation to verify. Valid hashes prove internal consistency only.
+
+The `atelier-review.v1.schema.json` contract defines these separate artifacts.
+Evidence and contributions use the existing JCS implementation; the bundle hash
+covers every top-level member except `digest`. A member hash covers its complete
+`value`; `bytes` is the UTF-8 byte count of `JSON.stringify(value)`. Record input
+hashes cover complete submitted input. Maximum bundle size is 4 MiB, with at most
+20 runs and 2,000 selected document contributions. Current capture supports up to
+256 text source nodes and 1 MiB per source; unsupported inputs refuse capture.
+No archive extraction or arbitrary path writing occurs. Symlink input/output
+leaves, absolute machine-path values, credential-bearing URLs and nontransferable
+field names are refused. Generic text still needs the owner's private disclosure
+policy; structural checks do not determine disclosure permission.
+
+To roll back, pin the earlier package and pack/configuration/lock together,
+disable the optional review surface, and retain both ledgers. Legacy proposal
+readers continue using their separate files. Never delete historical records or
+reinterpret them under a replacement pack to make an upgrade appear complete.

package/docs/skill-steward.md

@@ -0,0 +1,156 @@
+# Skill stewardship
+
+Atelier skill stewardship is a local, evidence-gated loop for keeping agent
+skills useful without turning every repeated request into permanent
+instructions. It separates four concerns that are easy to blur together:
+
+```text
+bounded observation -> evidence candidate -> authored and tested change
+                                                   |
+package release -> content-bound sync plan -> repo-scoped managed projection
+```
+
+Git remains the source of record for authored skills. Ignored local state holds
+only enumerated observations, staging directories, and recoverable quarantine.
+The steward has no telemetry, model provider, prompt capture, send path, browser
+apply endpoint, or authority to mutate its source catalog.
+
+## The operating loop
+
+### 1. Observe outcomes, not conversations
+
+An equipped agent can record one outcome after relevant work:
+
+```bash
+atelier skills observe \
+  --workflow weekly.release \
+  --signal repeated-task \
+  --outcome success
+```
+
+The observation accepts only a stable workflow key, one enumerated signal, an
+optional skill name, and an enumerated outcome. It has no fields for prompts,
+transcripts, summaries, source excerpts, names, or client material; callers
+must not encode any of them into the workflow key. Records live under ignored
+`.atelier-local/skill-steward/observations.ndjson`.
+
+Signals are `repeated-task`, `missing-workflow`, `user-correction`,
+`trigger-miss`, `trigger-collision`, `tool-failure`, `stale-guidance`,
+`successful-run`, `unused-skill`, and `superseded-skill`. Outcomes are
+`success`, `failure`, `corrected`, `missing`, and `unknown`.
+
+### 2. Promote only repeated evidence
+
+```bash
+atelier skills candidates --json
+```
+
+The candidate builder is deterministic. It proposes no source edit and uses
+fixed minimums:
+
+| Candidate | Evidence required |
+| --- | --- |
+| Create | Three combined `repeated-task` or `missing-workflow` signals with no named skill |
+| Improve | Two `user-correction` signals, or three combined correction/failure/staleness signals, for a named skill |
+| Reconcile | Two `trigger-collision` signals |
+| Retire | Two `superseded-skill` signals or three `unused-skill` signals for a named skill |
+
+An agent using the shipped `atelier-skill-steward` skill may turn an eligible
+candidate into an authored change, test positive and negative triggers, and
+run the catalog audit. Instruction-only changes that retain the same tools,
+data boundary, and external authority may progress through that automated
+lane. Any new network access, filesystem scope, external message, spending,
+destructive action, credential handling, or audience change pauses for human
+authorization.
+
+### 3. Audit the whole catalog
+
+```bash
+atelier skills audit
+atelier skills audit --root ./skills/codex --peer ./skills/claude --json
+```
+
+The audit validates required YAML frontmatter, lowercase names, directory/name
+agreement, UTF-8 `SKILL.md` text, bounded bundle size, real files and directories,
+bundle-contained relative resources, unfinished placeholders, and byte-level
+parity between agent surfaces. Errors fail the command. Warnings remain
+visible and reviewable.
+
+Catalog audits should run after authored changes and on a regular schedule.
+A scheduled agent task can run the audit and candidate builder, exercise
+eligible instruction-only changes, and leave a tested Git diff for ordinary
+review. Scheduling invokes the same skill and does not widen its permissions or
+lower its evidence thresholds.
+
+A portable recurring-task prompt is:
+
+> Use the `atelier-skill-steward` skill in this repository. Audit the complete
+> skill catalog, inspect evidence-thresholded candidates, and integrate eligible
+> authority-neutral instruction changes with behavioral and repository gates.
+> Reconcile overlaps and retire only evidence-backed vestiges. Do not capture
+> task content, add authority, overwrite drift, or bypass an exact sync plan.
+
+### 4. Update deployed skills from the released root package
+
+A consuming repository can project the released package's `skills/codex`
+catalog into repo-scoped `.agents/skills`:
+
+```bash
+atelier skills sync --json
+atelier skills sync --apply --confirm sha256:<the-reviewed-plan-digest>
+```
+
+The first command is read-only. The second recomputes the current plan and
+requires the exact digest that was reviewed. It refuses:
+
+- a target outside the enrolled workspace;
+- malformed or redirected bundles and lock files;
+- a collision with an unmanaged local skill;
+- local drift from the last managed digest; or
+- any source catalog that fails audit.
+
+Replaced and retired managed bundles move to
+`.atelier-local/skill-steward/quarantine/`; they are never permanently deleted
+by sync. The projection lock at
+`.agents/skills/.atelier-skill-lock.json` binds each installed bundle to its
+content digest and the source package version. This is the update bridge: after
+a newer `@mnstry/atelier` is installed, the same plan/apply sequence brings its
+shipped skills into the current repository without overwriting local ownership.
+
+Installation is explicit per repository; installing the package alone does not
+install a discoverable skill projection. Existing unmanaged bundles, including
+byte-identical bundles, are never adopted implicitly. Missing managed bundles
+count as local drift. Source and target may not overlap. A confirmation is
+bound to the workspace and source location as well as their observed content.
+Location hashes are local identifiers, not anonymization or authentication.
+Interrupted operations leave a lock and recovery state for inspection; do not
+automatically clear them or overwrite a locally edited projection.
+
+## Portable contracts
+
+`contracts/atelier-skill-steward.v1.schema.json` defines four independently
+addressable documents:
+
+- `mnstry.atelier-skill-audit@v1` for catalog findings;
+- `mnstry.atelier-skill-candidates@v1` for thresholded work;
+- `mnstry.atelier-skill-sync-plan@v1` for review and exact confirmation; and
+- `mnstry.atelier-skill-sync-lock@v1` for the managed projection inventory.
+
+Fixtures cover valid and invalid examples, and the registry, compatibility,
+disclosure, packaging, and release gates treat the contract and portable skill
+bundles as public artifacts.
+
+## Automation policy
+
+The safe autonomous lane is deliberately narrower than everything an agent
+could theoretically do:
+
+1. record only enumerated, content-free outcomes during ordinary work;
+2. audit and aggregate on a schedule;
+3. author only evidence-backed, authority-neutral skill changes;
+4. validate behavior, catalog integrity, disclosure, and package gates;
+5. leave public source changes in Git for review; and
+6. update a deployed projection only from a reviewed, exact digest plan.
+
+This makes “self-improving” mean accumulated evidence plus reversible changes,
+not silent memory, prompt harvesting, or unbounded self-modification.

package/docs/upgrade.md

@@ -1,10 +1,51 @@
 # Upgrade Guide
 
+For an owner asking their agent to prepare an update, start with
+[guided upgrades](guided-upgrades.md). It separates release selection and staged
+installation from the exact local transaction and the owner's adoption decision.
+
 Use this guide when upgrading a copied private-domain or shared-project starter
 workspace between Atelier package releases. The flow is local-only: it does not
 provision repositories, contact a Git host, mutate the MNSTRY runtime, or write
 through a browser view.
 
+## Upgrading to 0.2.0-alpha.8
+
+This release adds typed advisory decision contracts and an experimental,
+opt-in Obsidian projection. Nothing is published for a project that does not
+enable `ext["mnstry.atelier.obsidian"]`; see [obsidian.md](obsidian.md).
+
+The link resolver that produces `links_to` edges changed in five classes
+(links inside code and front matter, directory links, links that climb above
+the repository root, malformed percent-encoding, and workspace-only wikilink
+and cross-repository edges). Regenerate committed graph artifacts after
+upgrading and review the difference; the classes are listed in the changelog
+and in [obsidian-contract.md](obsidian-contract.md).
+
+## Upgrading to 0.2.0-alpha.7
+
+This release adds optional evidence-bound local review and the external-project
+starter. Existing v1 locks and readers remain compatible. To use bound review,
+explicitly qualify each pack for the new root version, regenerate the graph and
+projection, and create a fresh run. Historical runs retain their original
+snapshot and never acquire renewed approval from an upgrade. See
+[local review](local-review.md) for the complete workflow.
+
+## Upgrading to 0.2.0-alpha.6
+
+This release adds Atelier Sync Deliverable Zero: a headless, local repository
+supervisor with explicit enrollment, complete repository observations,
+fast-forward-only reconciliation, pause/resume control, hash-chained local
+operation traces, and two-phase user-confirmed commit and publication. It does
+not add a desktop shell, semantic conflict resolution, force operations,
+telemetry, or unattended semantic writes.
+
+Consumers that adopt the new runtime should enroll one repository explicitly,
+treat watchers as hints rather than truth, require a fresh complete observation
+before each confirmed mutation, and keep commit and publication as separate
+user decisions. Existing consumers that do not import the runtime subpaths are
+contract-compatible and need only update their pinned dependency.
+
 ## Upgrading to 0.2.0-alpha.5
 
 This release hardens public/private boundary enforcement, local serving,
@@ -117,7 +158,7 @@ For registry installs, pin the exact version and record the resolved version
 in the lockfile:
 
 ```bash
-npm install --save-dev @mnstry/atelier@0.2.0-alpha.5
+npm install --save-dev @mnstry/atelier@0.2.0-alpha.8
 npx mnstry-atelier lock write --project ./atelier.project.json
 ```
 
@@ -125,7 +166,7 @@ For Git installs, pin the release tag rather than a branch, so the lock file
 records exactly what was reviewed:
 
 ```bash
-npm install --save-dev "git+https://github.com/MNSTRY/atelier.git#v0.2.0-alpha.5"
+npm install --save-dev "git+https://github.com/MNSTRY/atelier.git#v0.2.0-alpha.8"
 npx mnstry-atelier lock write --project ./atelier.project.json
 ```
 
@@ -177,3 +218,30 @@ older workspaces and should not be used in new docs or package scripts.
 When unsure, fail closed: keep source in the private-domain workspace and move
 only a reviewed summary into the shared-project workspace through ordinary Git
 review.
+
+## Exact installed source and review history
+
+`atelier lock provenance --exact-source-required` and
+`atelier lock check --exact-source-required` refuse unverified bindings.
+Supported npm lock metadata is a declaration matched to the exact installation
+slot, including nested instances; a SHA in that declaration is not proof of the
+installed bytes. Linked/unsupported stores remain unresolved when no trustworthy
+instance evidence is available. Tarball/registry integrity is reported when
+available, without inventing a Git origin. Dirty, ignored or untracked executable
+inputs prevent verified checkout qualification. Inventory excludes Git metadata
+and dependency trees; two observed byte inventories must agree and match the commit tree, including when Git index hints conceal changes. A verified clean
+checkout does not authenticate an upstream publisher.
+
+Review snapshots and decisions are separate from historical v1 locks. See
+[pack lifecycle](extension-pack-lifecycle.md) and
+[inspection portability](review-portability.md) before replacing packs or moving
+state. Updating a package or a digest never silently renews old approval.
+
+## Exact local candidate transactions
+
+For the bounded, manually confirmed single-repository workflow, see
+[Local exact-plan upgrades](exact-upgrades.md). The `upgrade plan --save`,
+`upgrade apply --plan ... --confirm ...`, `upgrade status`, and recovery dry-run
+commands are separate from the legacy flag-based migration workflow above.
+They preserve history and honor existing commit hooks; they do not install a
+new package or activate a runtime.