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

package/docs/release-engineering.md

@@ -10,16 +10,23 @@ 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.
@@ -27,6 +34,15 @@ tarball `npm pack` would publish:
 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.
+
 ### repo:check
 
 `npm run repo:check` (`scripts/check-repo-disclosure.mjs`) sweeps the whole
@@ -43,6 +59,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,6 +102,17 @@ 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
@@ -75,8 +123,22 @@ paths; this gate is the mechanical check behind that claim.
 
 `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 +167,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 +189,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

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/upgrade.md

@@ -5,6 +5,29 @@ 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.5
+
+This release hardens public/private boundary enforcement, local serving,
+collaboration-ledger integrity, disclosure review, and release provenance.
+Documents valid against `0.2.0-alpha.0` remain contract-compatible, but some
+previously tolerated unsafe or ambiguous states now fail closed.
+
+- Projects using `atelier dev` must provide a generated
+  `atelier.manifest.json`; only enrolled, safe, realpath-validated static files
+  are served, and the sidecar accepts loopback traffic only.
+- Empty or malformed content-rule policies, incomplete Git reads, corrupt or
+  oversized collaboration ledgers, and unsafe manifest entries are now
+  blocking errors with typed CLI diagnostics.
+- Run `atelier disclosure check` before sharing tracked or staged content. A
+  private denylist is required by default and must remain outside the public
+  repository.
+- Release candidates are packed once, SHA-256-bound, and the exact audited
+  tarball is the artifact sent through npm trusted publishing.
+
+Re-run the boundary, disclosure, graph, readiness, and lock checks below after
+updating. If `atelier dev` previously served files without a manifest, generate
+and review the manifest before restarting it.
+
 ## Upgrading to 0.2.0-alpha.4
 
 This is a presentation release. There are no contract changes and no runtime
@@ -94,7 +117,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.4
+npm install --save-dev @mnstry/atelier@0.2.0-alpha.5
 npx mnstry-atelier lock write --project ./atelier.project.json
 ```
 
@@ -102,7 +125,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.4"
+npm install --save-dev "git+https://github.com/MNSTRY/atelier.git#v0.2.0-alpha.5"
 npx mnstry-atelier lock write --project ./atelier.project.json
 ```
 

package/fixtures/projects/sample-workspace/content/source.html.kg.json

@@ -1,5 +1,6 @@
 {
-  "assetFilename": "source.html",
+  "schema": "mnstry.source-sidecar@v1",
+  "asset": "source.html",
   "title": "Sample Source",
   "summary": "Neutral non-Markdown source with durable sidecar identity.",
   "tags": [
@@ -8,6 +9,8 @@
   "kg": {
     "id": "sample-workspace:source-html",
     "type": "source",
+    "domain": "sample",
+    "lifecycle": "source",
     "status": "active",
     "audience": "private",
     "relations": {}

package/fixtures/projects/source-formats-workspace/content/data.json.kg.json

@@ -1,5 +1,6 @@
 {
-  "assetFilename": "data.json",
+  "schema": "mnstry.source-sidecar@v1",
+  "asset": "data.json",
   "title": "Sample dataset",
   "summary": "Neutral JSON dataset described entirely by its sidecar.",
   "tags": [
@@ -8,6 +9,8 @@
   "kg": {
     "id": "source-formats:data-json",
     "type": "source",
+    "domain": "sample",
+    "lifecycle": "source",
     "status": "active",
     "audience": "team",
     "relations": {}

package/fixtures/projects/source-formats-workspace/content/logo.png.kg.json

@@ -1,5 +1,6 @@
 {
-  "assetFilename": "logo.png",
+  "schema": "mnstry.source-sidecar@v1",
+  "asset": "logo.png",
   "title": "Sample binary asset",
   "summary": "Four-byte PNG-magic stub; the graph never reads the asset bytes.",
   "tags": [
@@ -8,6 +9,8 @@
   "kg": {
     "id": "source-formats:logo-png",
     "type": "artifact",
+    "domain": "sample",
+    "lifecycle": "source",
     "status": "active",
     "audience": "sensitive",
     "relations": {}

package/fixtures/projects/source-formats-workspace/content/metrics.csv.kg.json

@@ -1,5 +1,6 @@
 {
-  "assetFilename": "metrics.csv",
+  "schema": "mnstry.source-sidecar@v1",
+  "asset": "metrics.csv",
   "title": "Sample metrics",
   "summary": "Neutral CSV evidence table described by its sidecar.",
   "tags": [
@@ -8,6 +9,8 @@
   "kg": {
     "id": "source-formats:metrics-csv",
     "type": "evidence",
+    "domain": "sample",
+    "lifecycle": "source",
     "status": "active",
     "audience": "operator",
     "relations": {}

package/fixtures/projects/source-formats-workspace/content/pipeline.yaml.kg.json

@@ -1,5 +1,6 @@
 {
-  "assetFilename": "pipeline.yaml",
+  "schema": "mnstry.source-sidecar@v1",
+  "asset": "pipeline.yaml",
   "title": "Sample pipeline",
   "summary": "Neutral YAML file; atelier never parses it, the sidecar speaks for it.",
   "tags": [
@@ -8,6 +9,8 @@
   "kg": {
     "id": "source-formats:pipeline-yaml",
     "type": "source",
+    "domain": "sample",
+    "lifecycle": "source",
     "status": "active",
     "audience": "public",
     "relations": {}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mnstry/atelier",
-  "version": "0.2.0-alpha.4",
+  "version": "0.2.0-alpha.5",
   "private": false,
   "description": "Local toolkit that turns a Git repository into an ontology-governed knowledge graph, enforcement layer, and runtime for people, agents, and tools. No telemetry, service, or account.",
   "keywords": [
@@ -32,8 +32,10 @@
     "./readiness-protocols": "./src/readiness-protocols/bundled-pack.mjs",
     "./server": "./src/server/local-sidecar.mjs",
     "./harness": "./src/harness/context.mjs",
+    "./collaboration": "./src/collaboration/index.mjs",
     "./support": "./src/support/support-bundle.mjs",
     "./egress": "./src/egress/forbidden-egress.mjs",
+    "./disclosure": "./src/disclosure/content-scan.mjs",
     "./boundary": "./src/boundary/policy.mjs",
     "./upgrade": "./src/upgrade/upgrade.mjs",
     "./attestation": "./src/attestation/sign.mjs",
@@ -48,7 +50,7 @@
     "contract": "node src/check-atelier-export-contract.mjs",
     "dry-run": "node src/validate-atelier-export-dry-run.mjs fixtures/atelier-export/sample-studio-offer.v1.json",
     "test": "node --test test/*.test.mjs",
-    "syntax:check": "find bin src -name '*.mjs' -print0 | xargs -0 -n1 node --check",
+    "syntax:check": "node scripts/check-syntax.mjs",
     "graph:test": "node --test test/graph.test.mjs test/graph-knowledge-graph.test.mjs test/graph-determinism.test.mjs test/graph-source-formats.test.mjs",
     "project:test": "node --test test/project.test.mjs test/project-config.test.mjs test/projection-policy.test.mjs test/projection-alignment.test.mjs",
     "server:security:test": "node --test test/server.test.mjs test/server-security.test.mjs test/server-proposals.test.mjs",
@@ -57,19 +59,24 @@
     "egress:check": "node bin/atelier.mjs egress check",
     "readiness:test": "node --test test/readiness.test.mjs test/readiness-summary.test.mjs test/readiness-protocol-contract.test.mjs test/readiness-protocols.test.mjs test/readiness-protocol-runtime.test.mjs",
     "harness:test": "node --test test/harness.test.mjs test/harness-context.test.mjs",
-    "boundary:test": "node --test test/boundary-policy-contract.test.mjs test/boundary-guard.test.mjs",
+    "collaboration:test": "node --test test/collaboration-ledger.test.mjs test/server-proposals.test.mjs",
+    "boundary:test": "node --test test/boundary-policy-contract.test.mjs test/boundary-content-rules.test.mjs test/boundary-guard.test.mjs",
     "upgrade:test": "node --test test/upgrade-contract.test.mjs test/upgrade.test.mjs",
     "release:audit": "node scripts/check-release-tarball.mjs",
+    "release:candidate": "node scripts/release-candidate.mjs",
     "repo:check": "node scripts/check-repo-disclosure.mjs",
     "migrations:check": "node scripts/check-breaking-migrations.mjs",
     "contract:compat": "node scripts/check-contract-compat.mjs",
+    "public-api:compat": "node scripts/check-public-api-compat.mjs",
+    "assurance:mutation-smoke": "node --test test/assurance-mutations.test.mjs",
     "consumer:smoke": "node scripts/consumer-smoke.mjs",
     "distribution:smoke": "node scripts/distribution-smoke.mjs",
-    "prepublishOnly": "npm run release:audit && npm run repo:check && npm run migrations:check && npm run contract:compat && npm run syntax:check && npm test && npm run consumer:smoke && npm run distribution:smoke"
+    "prepublishOnly": "npm run repo:check && npm run migrations:check && npm run contract:compat && npm run public-api:compat && npm run syntax:check && npm test && npm run assurance:mutation-smoke && npm run release:candidate"
   },
   "dependencies": {
     "ajv": "8.20.0",
-    "ajv-formats": "3.0.1"
+    "ajv-formats": "3.0.1",
+    "fast-uri": "3.1.5"
   },
   "devDependencies": {
     "@types/node": "^22.0.0"

package/skills/claude/atelier-local-service/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: atelier-local-service
+description: Build or repair a durable loopback-only authoring, review, or preview service in an Atelier-backed repository when local state must survive agent commands and fail safely.
+---
+
+# Atelier local service
+
+Use this skill for a consumer-owned service that persists repository-backed
+local state. Do not use it to change `atelier dev` itself or to install an
+operating-system service without explicit authorization.
+
+Read `docs/local-services.md` from the installed Atelier package or source
+checkout before changing lifecycle code.
+
+## Boundary first
+
+Separate the portable mechanism from the consumer adapter before editing:
+
+- Atelier invariants: loopback binding, proven ownership, exact stop, ignored
+  mode-0600 state, atomic writes, recoverable browser failure, and tests.
+- Consumer details: service identity, port, commands, paths, schema, content,
+  and user-facing language.
+
+Never promote consumer names, content, structures, examples, or local paths
+into Atelier. Public tests use invented fixtures.
+
+## Workflow
+
+1. Inspect the existing server, process owner, port, persistence file,
+   `.gitignore`, health route, save handler, and tests. Preserve the live draft
+   before restarting anything.
+2. Expose repository-owned `start`, `status`, and `stop` commands. Start may
+   detach only because the user needs continuity beyond the launching command.
+3. Bind to loopback. Pair a random runtime identifier with the PID in both the
+   private runtime record and health response. Refuse unowned listeners.
+4. Keep drafts, runtime metadata, and operational logs ignored and owner-only.
+   Do not commit live authoring state.
+5. Make the UI retain the draft when the service disappears. Show the exact
+   restart command, snapshot export, and Retry path instead of a generic error.
+6. Serialize writes without permanently rejecting the queue after one failed
+   operation. Keep conflicts and invalid state fail-closed.
+7. Prove lifecycle ownership, server-loss recovery, later-save recovery,
+   permissions, ignore coverage, and fresh-checkout discoverability.
+
+Do not claim durability from a passing request alone. Report separately:
+saved file truth, managed-process truth, browser recovery truth, and the
+remaining OS-restart boundary.

package/skills/claude/atelier-public-boundary/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: atelier-public-boundary
+description: Generalize a lesson from a private or tenant implementation into the public Atelier repository without carrying proprietary material across the trust boundary.
+---
+
+# Atelier public boundary
+
+Use this skill whenever a public Atelier change is informed by work in a
+private, client, tenant, or internal repository.
+
+## Extract the invariant, not the source
+
+1. State the reusable failure mode or contract without client vocabulary.
+2. Identify every source-specific name, path, port, field, content structure,
+   example, and operational fact. Keep those in the source repository.
+3. Re-derive the public mechanism against an invented fixture. Neutral wording
+   is not enough if the fixture still reproduces a proprietary structure.
+4. Keep private disclosure patterns in the ignored denylist or CI secret. Do
+   not place them in code, tests, docs, branch names, or commit messages.
+5. Add a regression test for the general control and run an evidence-backed
+   defensive review when a guard changes.
+
+## Required gates
+
+Before staging, run the repository's disclosure check. After staging, scan the
+staged index with the private denylist, then inspect the exact diff and release
+tarball. A structural-only pass is useful on an untrusted fork but is not a
+complete maintainer verdict.
+
+If the private denylist is unavailable, stop short of claiming the public
+boundary is green. Do not replace it with remembered client names.

package/skills/codex/atelier-local-service/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: atelier-local-service
+description: Build or repair a durable loopback-only authoring, review, or preview service in an Atelier-backed repository when local state must survive agent commands and fail safely.
+---
+
+# Atelier local service
+
+Use this skill for a consumer-owned service that persists repository-backed
+local state. Do not use it to change `atelier dev` itself or to install an
+operating-system service without explicit authorization.
+
+Read `docs/local-services.md` from the installed Atelier package or source
+checkout before changing lifecycle code.
+
+## Boundary first
+
+Separate the portable mechanism from the consumer adapter before editing:
+
+- Atelier invariants: loopback binding, proven ownership, exact stop, ignored
+  mode-0600 state, atomic writes, recoverable browser failure, and tests.
+- Consumer details: service identity, port, commands, paths, schema, content,
+  and user-facing language.
+
+Never promote consumer names, content, structures, examples, or local paths
+into Atelier. Public tests use invented fixtures.
+
+## Workflow
+
+1. Inspect the existing server, process owner, port, persistence file,
+   `.gitignore`, health route, save handler, and tests. Preserve the live draft
+   before restarting anything.
+2. Expose repository-owned `start`, `status`, and `stop` commands. Start may
+   detach only because the user needs continuity beyond the launching command.
+3. Bind to loopback. Pair a random runtime identifier with the PID in both the
+   private runtime record and health response. Refuse unowned listeners.
+4. Keep drafts, runtime metadata, and operational logs ignored and owner-only.
+   Do not commit live authoring state.
+5. Make the UI retain the draft when the service disappears. Show the exact
+   restart command, snapshot export, and Retry path instead of a generic error.
+6. Serialize writes without permanently rejecting the queue after one failed
+   operation. Keep conflicts and invalid state fail-closed.
+7. Prove lifecycle ownership, server-loss recovery, later-save recovery,
+   permissions, ignore coverage, and fresh-checkout discoverability.
+
+Do not claim durability from a passing request alone. Report separately:
+saved file truth, managed-process truth, browser recovery truth, and the
+remaining OS-restart boundary.

package/skills/codex/atelier-public-boundary/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: atelier-public-boundary
+description: Generalize a lesson from a private or tenant implementation into the public Atelier repository without carrying proprietary material across the trust boundary.
+---
+
+# Atelier public boundary
+
+Use this skill whenever a public Atelier change is informed by work in a
+private, client, tenant, or internal repository.
+
+## Extract the invariant, not the source
+
+1. State the reusable failure mode or contract without client vocabulary.
+2. Identify every source-specific name, path, port, field, content structure,
+   example, and operational fact. Keep those in the source repository.
+3. Re-derive the public mechanism against an invented fixture. Neutral wording
+   is not enough if the fixture still reproduces a proprietary structure.
+4. Keep private disclosure patterns in the ignored denylist or CI secret. Do
+   not place them in code, tests, docs, branch names, or commit messages.
+5. Add a regression test for the general control and run an evidence-backed
+   defensive review when a guard changes.
+
+## Required gates
+
+Before staging, run the repository's disclosure check. After staging, scan the
+staged index with the private denylist, then inspect the exact diff and release
+tarball. A structural-only pass is useful on an untrusted fork but is not a
+complete maintainer verdict.
+
+If the private denylist is unavailable, stop short of claiming the public
+boundary is green. Do not replace it with remembered client names.