@mnstry/atelier 0.2.0-alpha.1 → 0.2.0-alpha.11

package/docs/release-engineering.md

@@ -10,23 +10,114 @@ a location, never the matched content.
 ### release:audit
 
 `npm run release:audit` (`scripts/check-release-tarball.mjs`) audits the exact
-tarball `npm pack` would publish:
+tarball `npm pack` would publish. `npm run release:candidate` packs once and
+passes the same archive and expected SHA-256 through this audit and both
+consumer smokes:
 
 - Package metadata: name, license, exposed CLI bins, and a mandatory `files`
   allowlist in `package.json`.
 - Tarball allowlist: every packed path must match a known-good pattern; any
-  unexpected file fails the audit.
+  unexpected file fails the audit. The extracted archive inventory must match
+  the `npm pack --json` inventory exactly.
 - Content scan: every packed file is scanned against committed structural
   patterns (absolute user paths, machine-local temp paths, agent-local state
   paths, key material, secret-like assignments) and against the maintainer-held
   denylist described below.
+- Egress scan: the canonical egress control receives the exact `npm pack`
+  inventory and inspects every packed executable or markup file, including a
+  test-shaped path if one is ever admitted to the artifact. Packed test-fixture
+  suppression markers are refused; reviewed local-computed markers are counted.
 - 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).
 
+`release:candidate` additionally requires a clean tree, records the candidate
+commit and tarball digest, and refuses a version already bound to a different
+tagged commit. It is a release-evidence command, not a publication command.
+When `ATELIER_RELEASE_OUTPUT_DIR` is set, it atomically retains the verified
+tarball, npm-pack metadata, and a machine-readable receipt. The trusted
+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
@@ -43,6 +134,27 @@ Git-tracked tree, not just the tarball:
 Exit codes match `release:audit`: `0` clean, `1` findings, `2` configuration or
 usage error.
 
+### disclosure check
+
+`atelier disclosure check` is the portable consumer-facing content gate. It
+scans every tracked text file by default or the exact staged index with
+`--staged`, never follows tracked symlinks, and reports labels plus locations
+without echoing matched content. `--untrusted` suppresses finding details.
+
+The command loads private patterns from `ATELIER_DENYLIST_JSON`, an explicit
+`--denylist` path, or ignored
+`.atelier-local/disclosure-denylist.json`. A repository-local denylist is
+refused if it is tracked or not covered by `.gitignore`. Missing private
+patterns are a configuration failure unless `--structural-only` explicitly
+acknowledges the reduced verdict. Public text-only packaging can also use
+`--fail-on-binary`; Atelier's own tarball audit separately refuses packed
+binary files.
+
+The public Atelier repository keeps the stronger `repo:check` identity and
+commit-message controls. The portable command exists so consumer repositories
+can enforce the same public/private content boundary without inheriting
+MNSTRY-specific commit identities.
+
 ### Commit-identity gate
 
 Part of `repo:check --commits`. Commit authors must match a hardcoded
@@ -65,18 +177,58 @@ changelog and the migration registry honest about breaking changes:
 - Every registered migration record is re-validated against the migration
   record contract.
 
+### public-api:compat
+
+`npm run public-api:compat` compares every package subpath and named JavaScript
+export published by `v0.2.0-alpha.4` with the current package. Removing one
+fails closed. It also rejects modified source that retains the already-tagged
+baseline version, independently of the release-candidate check. The baseline
+records and verifies its tag commit and the public npm artifact identity; the
+published archive was independently checked to contain all 20 subpaths and 212
+named exports. This is runtime JavaScript shape continuity, not a promise about
+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
 
 `npm run consumer:smoke` (`scripts/consumer-smoke.mjs`) packs the real tarball,
 installs it offline into a throwaway consumer project with lifecycle scripts
-disabled, and imports the public API to validate a sample export. It proves the
-tarball is installable and functional exactly as a consumer receives it.
+disabled and without copying the publisher's `overrides`, checks the installed
+dependency tree, imports every declared JavaScript export, parses every
+declared JSON export, and validates a sample export through both API and CLI.
+It proves the tarball is installable and functional exactly as a bare consumer
+receives it from disk. The offline smoke deliberately warms the locked registry
+dependency closure first; it does not prove that a not-yet-published version
+resolves from a cold or live registry.
+
+### assurance:mutation-smoke
+
+`npm run assurance:mutation-smoke` runs local, synthetic negative controls for
+the boundary, graph, packed and direct egress, sidecar, and distribution
+families. Every fixture introduces one named failure and must be refused by the
+terminal CLI or release command where one exists. This is part of
+`prepublishOnly`; a control that stops detecting its failure mode blocks the
+release even if positive-path tests remain green.
 
 ### Egress-marker inventory
 
@@ -105,7 +257,7 @@ maintainer-reviewed before entering the list.
 Four jobs run on pushes to `main` and on pull requests, and all four are
 required status checks:
 
-- `test`: syntax check (`node --check`, not a type system), the full test suite, contract checks, `egress:check`, and
+- `test`: syntax check (`node --check`, not a type system), the full test suite (including isolated consumer disclosure-command proofs), contract checks, `egress:check`, `assurance:mutation-smoke`, and
   `migrations:check`. This job sets `ATELIER_ALLOW_MISSING_DENYLIST=1` scoped
   to the job only — denylist assertions belong to the secret lane.
 - `consumer-smoke`: warms the npm cache with `npm ci` (the offline tarball
@@ -127,11 +279,14 @@ the only safe block.
 
 To clear a fork pull request, a maintainer verifies the head SHA and dispatches
 the `fork-sweep` workflow with the pull-request number and that SHA. The
-workflow runs the trusted scanner from `main` against the fork's tree checked
-out as data — it never installs or executes anything from the untrusted tree —
-re-verifies that the head SHA has not moved, and posts a `secret-sweep` check
-run on the SHA. The newest check run with that name supersedes the earlier
-failure for branch protection.
+workflow pins the trusted scanner checkout to the protected default branch and
+runs it against the fork checked out as data — it never installs or executes
+anything from the untrusted tree. It requires an open PR whose base repository
+and branch are the protected default, pins the base and head SHAs from GitHub,
+scans the complete bounded base-to-head object range while waiving only
+repository-specific commit identity, re-verifies that the head SHA has not
+moved, and posts a `secret-sweep` check run on the SHA. The newest check run
+with that name supersedes the earlier failure for branch protection.
 
 `release:audit` never runs against untrusted code (`npm pack` executes
 lifecycle scripts); it re-runs on the push build of the merge commit. No
@@ -145,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/repo-boundary-guard.md

@@ -170,12 +170,22 @@ machine for weeks.
 - `pre-push` runs `atelier boundary push-check` — git writes the ref updates to
   the hook's stdin, and only that range is judged. A brand-new branch is diffed
   against the empty tree, so nothing slips through unscanned.
-- `atelier boundary audit` scans the whole tree and **reports without blocking**,
-  listing both matches and declared exceptions with their reasons.
+- `atelier boundary audit` scans the current working tree by default and
+  **reports without blocking**, listing matches, incomplete-read diagnostics,
+  and declared exceptions with their reasons. Use `--head` for a committed
+  snapshot. The output names its source so a dirty tree cannot be mistaken for
+  `HEAD` evidence.
 
 If the guard cannot work out which repo it is running in, it fails closed. A
 guard that silently judges nothing is worse than one that stops you.
 
+Path scopes are segment-aware globs: `*` does not cross `/`, `**` does, and
+patterns are matched against normalized repository-relative paths. Explicitly
+declaring `contentRules: []` is invalid; omit the field to receive defaults.
+Git diff output and binary reads have per-file and aggregate budgets. A failed,
+truncated, oversized, or unparsable evidence read produces a blocking
+completeness diagnostic rather than a partial clean verdict.
+
 ### Declaring an exception
 
 Exceptions live in the boundary policy, not in the guard script. A repo-specific

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.