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

package/docs/atelier-sync.md

@@ -0,0 +1,171 @@
+# Atelier Sync: Deliverable Zero
+
+Atelier Sync is the collaborator-facing name for the resident repository
+supervisor. Deliverable Zero is deliberately headless: it proves the Git,
+filesystem, state-machine, recovery, and user-authority boundaries before a
+tray shell or installer is allowed to make the product feel finished.
+
+This is repository mechanics, not MNSTRY runtime authority. A Git commit
+changes the enrolled repository. It does not mutate MNSTRY identity, consent,
+visibility, provisioning, commerce, sessions, audit, or any other managed
+runtime object.
+
+## Authority contract
+
+- Enrollment names exactly one repository. Atelier never scans a home folder.
+- One resolved absolute system Git executable, version, and executable digest
+  owns Git semantics for the enrollment. Every inherited `GIT_*` variable is
+  stripped from supervised Git calls before Atelier adds its small fixed
+  safety environment. Custom SSH transport belongs in the user's SSH config;
+  credentials continue through ordinary Git credential helpers. Git `2.40.0`
+  or newer is required so global and system attribute provenance is observable.
+- Every cycle observes the full repository. There is no watcher correctness
+  dependency in Deliverable Zero.
+- Fetch and fast-forward-only reconciliation are mechanical operations.
+- Commit creation is a two-phase, user-confirmed operation. Planning records
+  the head, branch, complete status digest, exact file paths, commit message,
+  reviewed blob/mode manifest, diff summary, and exact optional upstream push
+  identity. The push identity digest covers the single resolved, normalized,
+  credential-free execution destination; persisted display evidence likewise
+  strips authentication material, query strings, and fragments. Multiple push
+  URLs and `url.*.insteadOf`/`pushInsteadOf` rewrites are refused as ambiguous.
+  Every authoritative field is bound into the operation id.
+  Execution requires that exact id and refuses if the plan, repository,
+  staged bytes/modes, written tree, commit parent/message, or publish target
+  changed. A publish plan is refused while any earlier local commit remains
+  unpublished, and publication names the exact verified commit object rather
+  than a movable `HEAD` ref. Plans expire after 24 hours, are consumed by a
+  definitive execution attempt, and are held under resident file/count
+  ceilings. Expired, malformed, or oversized retained plan files are removed
+  under the repository lock before those ceilings are enforced; redirected
+  plan state remains a hard refusal.
+- A commit plan cannot absorb pre-existing staged work. It stages only literal,
+  explicitly reviewed paths.
+- Configured Atelier boundary policy is checked against the staged change set
+  before commit creation using the enrolled Git executable. When that policy
+  declares private-domain ownership, actor verification is blocking even in
+  legacy-warning mode. The Sync path disables the boundary command's optional
+  network `gh api user` fallback and fails closed when local actor evidence is
+  insufficient. Commit history is provenance, not current-user identity, and
+  is not accepted as actor evidence on this path. Policies without a declared private-domain owner do not invent
+  an actor requirement. Ordinary Git hooks still run; the resulting commit tree,
+  single parent, and message must equal the reviewed authority or the local
+  commit is rolled back and publication is refused.
+- Push is present only when the reviewed plan requested it, the branch had no
+  prior unpublished commits, and HEAD still names the exact verified commit.
+  Atelier re-resolves the single push URL immediately before publication and
+  pushes the exact commit object directly to that reviewed destination. Push is
+  never forced, never follows tags, and never recursively publishes submodule
+  refs. When fetch and push resolve to the same credential-free identity,
+  Atelier refreshes the exact remote-tracking branch and re-observes before it
+  reports `committed-and-published`. A distinct configured push URL is honored,
+  but remains an explicit attention state because it cannot prove the fetch
+  upstream synchronized. A failed push or post-push tracking refresh preserves
+  the local commit, creates one stable attention state, and returns a non-zero
+  command exit.
+- Semantic conflict resolution, merge commits, rebase, reset, force push,
+  browser apply, broad path scans, telemetry, and hidden upload are absent.
+
+## Repository completeness
+
+`atelier sync status` emits a supervisor envelope whose `state.observation`
+contains the current `atelier-repository-observation@v1` document. That
+observation cannot report `complete: true` when any of these are unresolved:
+
+- lexically identifiable provider-managed, UNC/network, WSL-cross-boundary, or
+  unclassified external filesystem roots (mapped-drive classification remains
+  an operating-system integration concern for the signed beta);
+- an unsupported Git engine or bare repository;
+- sparse checkout, partial clone, or shallow repository state;
+- tracked paths carrying `assume-unchanged` or `skip-worktree` index flags;
+- missing or unhealthy submodules;
+- required Git LFS content without a working LFS integration, including LFS
+  semantics declared by tracked or untracked worktree attributes, repository
+  info attributes, and default global or system attributes;
+- an unclassified custom clean, smudge, or process filter;
+- a configured `core.hooksPath` whose executable behavior is outside the
+  reviewed repository contract;
+- a remote URL whose authentication shape cannot be classified;
+- multiple push destinations or any configured Git URL rewrite rule;
+- any required Git evidence read that fails, times out, exceeds its budget, or
+  cannot be parsed.
+- a change set above the 4,096-entry resident observation ceiling; or
+- a `core.attributesFile` outside the repository-owned/tracked attributes
+  boundary whose filter semantics have not been classified.
+
+HTTPS through Git Credential Manager, SSH through the user's existing SSH
+configuration, and local test remotes are classified explicitly. Atelier does
+not collect or store provider credentials.
+
+## Local operation state
+
+Ignored `.atelier-local/runtime/` contains:
+
+- `enrollment.json` — exact repository and Git engine;
+- `state.json` — a bounded projection of healthy, attention, or paused state;
+- `control.json` — user pause/freeze state;
+- `plans/` — expiring, consumed reviewed commit plans under count/byte ceilings;
+- `operations.ndjson` — sequence- and hash-chained resident trace with explicit
+  hash-bound checkpoints before its byte or record ceiling, with a fresh
+  digest-linked generation after a torn or corrupt chain; and
+- an atomic per-repository operation lock.
+
+Every directory component is containment-checked and every state leaf is
+opened without following redirects where the platform supports it, with leaf
+type and identity checks on every platform. Stale-lock recovery uses an
+exclusive recovery claim, ages out an abandoned recovery claim after the owner
+grace interval, identity-checks the lock directory before and after quarantine,
+and quarantines only the claimed stale directory; it never recursively deletes
+a newly acquired lock. A live PID without durable process identity cannot wedge
+the repository forever: its owner record becomes recoverable after the 24-hour
+maximum operation age. Enrollment takes the same lock as every other
+authoritative state mutation.
+
+Deleting this directory removes convenience and diagnostics. It cannot change
+repository meaning. Git plus readable files remain authoritative.
+
+## Engineering commands
+
+```bash
+atelier sync enroll --repo /absolute/path/to/repository
+atelier sync status --repo /absolute/path/to/repository
+atelier sync reconcile --repo /absolute/path/to/repository
+atelier sync run --repo /absolute/path/to/repository --once
+
+atelier sync plan \
+  --repo /absolute/path/to/repository \
+  --path docs/decision.md \
+  --message "docs: record decision" \
+  --publish
+
+# Repeat the exact operation id printed by plan:
+atelier sync commit \
+  --repo /absolute/path/to/repository \
+  --operation operation-... \
+  --confirm operation-...
+```
+
+`status`, `audit`, `reconcile`, `run --once`, and `commit` return a non-zero
+process exit when their result is not healthy, so automation cannot treat a
+paused state, attention state, or failed publication as success merely because
+JSON was emitted.
+
+The future native shell may label the final two commands **Commit & sync**.
+It must not bypass either phase.
+
+The repeated operation id is a visible user-intent confirmation gate, not an
+authorization secret. Local software able to read and modify the repository is
+inside the same operating-system trust domain; the control prevents implicit
+or stale execution, not a hostile process with the user's filesystem access.
+
+## Evidence boundary
+
+Deliverable Zero proves the headless supervisor contract on Linux and macOS,
+with Windows CI covering the portable observation, state, and direct-process
+contract. POSIX executable-wrapper substitution is explicitly skipped on
+Windows; native Windows wrapper-injection proof, signed installation,
+background launch at user login, Windows Home/Pro device behavior, macOS
+notarization, and a nontechnical-user workflow belong to the signed
+collaborator beta. Repositories without an initial commit are not supported by
+this deliverable. A Git executable upgrade changes enrolled identity and
+requires re-enrollment.

package/docs/blocks/claims.md

@@ -1,18 +1,29 @@
 This package makes three promises. None of them asks for your trust — each
 one names the command that proves it.
 
-**Nothing leaves your machine, with one exception you can see.** There is no
-telemetry, no update check, no crash reporting, and no send path anywhere in
-the package. The exception: when no actor is configured, `boundary check` and
-`doctor` fall back to the `gh` CLI to resolve your GitHub login, which is an
-authenticated request to GitHub made with your own credentials. Set
-`MNSTRY_ATELIER_ACTOR` and that path is never taken. The only network client
-refuses non-loopback URLs, the served pages carry a policy that authorizes no
-external origin, and a fail-closed gate scans the executable and markup files
-under `src/`, `bin/`, `scripts/`, and `examples/` for egress primitives. Two
-limits worth stating plainly: the gate does not read the `.json` and `.md`
-files under `templates/` and `skills/`, and it does not model
-`child_process`, which is why the `gh` fallback above does not trip it:
+**There is no silent egress; every network path is named.** There is no
+telemetry, update check, crash reporting, managed-runtime upload, or model
+provider path in the package. The exceptions are explicit: `boundary check`
+may invoke `gh api user` after no declared actor matches an explicit `--actor`,
+`MNSTRY_ATELIER_ACTOR`, `GITHUB_ACTOR`, or a configured Git email; repository
+identity checks may invoke `gh api repos/...` to resolve a canonical GitHub
+identity. Those authenticated requests use your own `gh` credentials. A
+recognized explicit actor prevents the boundary actor fallback; recorded
+repository identities let identity checks keep working when the provider is
+unavailable. Explicitly enrolled Atelier Sync may also run bounded Git fetches
+for observation/reconciliation and one non-force push only when the exact
+reviewed commit plan requested and confirmed it, no earlier local commit is
+waiting to be published, and HEAD still names the verified commit object. Sync
+never uses the network actor fallback, follows tags, or recursively publishes
+submodule refs. The package's HTTP client
+refuses non-loopback URLs, the served pages authorize no external origin, and
+release audit scans every executable or markup file in the exact `npm pack`
+inventory for egress primitives. The standalone gate also scans executable and
+markup files under `src/`, `bin/`, `scripts/`, `templates/`, `examples/`, and
+`skills/`. Two limits worth stating plainly: the egress control does not
+interpret data-only `.json` or `.md` files, and it does not model
+`child_process`; the reviewed `gh` and enrolled Git paths above are documented
+subprocess exceptions rather than scanner detections:
 
 ```bash
 npm run egress:check

package/docs/blocks/will-not-do.md

@@ -1,7 +1,13 @@
 - It does not write to a MNSTRY runtime database.
-- It does not import, provision, publish, or send anything.
-- Except for the documented `gh` actor-resolution fallback, it initiates no
-  external network requests.
+- It does not import, provision, publish, or send project content to a MNSTRY
+  managed runtime.
+- Conformance remains offline. Network access is limited to the documented
+  `gh` actor-resolution fallback and explicitly enrolled Atelier Sync Git
+  operations: bounded fetch for observation/reconciliation, and non-force push
+  only when the exact reviewed commit plan requested and confirmed it, no
+  earlier local commit remains unpublished, and HEAD still names the verified
+  commit object; Sync does not use network actor fallback, follow tags, or
+  recursively publish submodule refs.
 - It does not execute model-assisted analysis or any model provider.
 - It does not include client project content.
 

package/docs/design.md

@@ -12,12 +12,16 @@ proves it — because a design document that cannot be checked is marketing.
 
 ## 1. A repository with an ontology
 
-A small structured header turns a file into a node: front matter on
+A small structured header turns a file into a governed node: front matter on
 Markdown, or a `.kg.json` sidecar beside any other format — JSON, YAML,
 CSV, media, anything — which the kit enrolls without ever parsing the
 foreign format. The header declares identity (`kg.id`), type, status,
 audience, and relations to other nodes.
 
+Markdown without a `kg` block is still counted by the canonical graph engine,
+but only as private `unclassified` material with a diagnostic. Once a `kg`
+block is present, partial or malformed declarations are blocking errors.
+
 The graph builder compiles the repository into a knowledge graph,
 deterministically: same tree in, same graph out, and `--check` mode fails
 when a generated graph has drifted from its sources. There is no import
@@ -92,14 +96,16 @@ atelier lock check --project ./atelier.project.json
 The same governed workspace projects two ways.
 
 For humans: a generated review surface, served by a sidecar that binds to
-loopback only. The served pages carry a policy that authorizes no external
-origin, and the only network client in the package refuses non-loopback
-URLs.
+loopback only. It requires a generated publication manifest and serves only
+enrolled safe static files after realpath validation. The served pages carry a
+policy that authorizes no external origin, and the only network client in the
+package refuses non-loopback URLs.
 
 For agents: session-bound context and capability envelopes that hand an
 agent harness a governed view of the workspace — what exists, what it may
-look at, what it may propose. Proposals are recorded as metadata; there
-are no browser apply endpoints and no write authority to grant. Context
+look at, what it may propose. Proposals are recorded as typed copy-only
+metadata; capability declarations expose no apply endpoint, source write,
+execution, or Git authority. Context
 without authority. Neutral Claude and Codex skill wrappers ship in the
 package, so a harness can do readiness review work against the workspace
 without a single line of custom glue.

package/docs/install.md

@@ -30,19 +30,19 @@ The registry is the distribution channel of record, as `docs/continuity.md`
 commits:
 
 ```bash
-npm install --save-dev @mnstry/atelier@0.2.0-alpha.4
+npm install --save-dev @mnstry/atelier@0.2.0-alpha.6
 ```
 
 Installing from the matching Git tag resolves to the same reviewed commit:
 
 ```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.6"
 ```
 
 Or over SSH:
 
 ```bash
-npm install --save-dev "git+ssh://git@github.com/MNSTRY/atelier.git#v0.2.0-alpha.4"
+npm install --save-dev "git+ssh://git@github.com/MNSTRY/atelier.git#v0.2.0-alpha.6"
 ```
 
 Keep the `@mnstry/` scope — see the command-form note above for why the
@@ -57,6 +57,24 @@ The workspace `atelier.lock.json` should record the resolved version or Git
 SHA from the install. Treat the tag or version as the friendly handle and the
 SHA as the review authority.
 
+### Adapter runners must bind package identity
+
+An early downstream adapter exposed a subtle failure mode worth making a
+general rule: a wrapper that scans arbitrary sibling checkouts and accepts the
+first matching binary can validate against an archived tree while appearing
+current. Adapter and distribution runners must therefore:
+
+1. declare one exact `@mnstry/atelier` version in their package manifest;
+2. prefer the installed `node_modules/@mnstry/atelier` package over incidental
+   sibling checkouts;
+3. accept an explicit local checkout only when its package name and version
+   match the declared dependency;
+4. run `atelier --version` and `atelier lock check` as part of adapter proof;
+5. fail closed when the declared version, resolved package, and lock disagree.
+
+This rule binds which Atelier implementation ran. It does not make generated
+output authoritative or grant runtime mutation.
+
 Use one private domain repository per user:
 
 ```text
@@ -103,7 +121,11 @@ atelier init --template shared-project --target ./project-alpha --actor tenant-u
 
 `--actor` rewrites the copied boundary policy actor entry and binds it to the
 local Git email when available. Use `--github-login` or `--git-email` to set
-those values explicitly during onboarding.
+those values explicitly during onboarding. At check time, a declared actor is
+resolved in this order: recognized `--actor`/`MNSTRY_ATELIER_ACTOR`/
+`GITHUB_ACTOR`, configured Git email, then a reviewed `gh api user` fallback.
+An explicit value that is not declared in the policy does not authenticate an
+actor and therefore does not suppress later resolution attempts.
 
 Then update:
 

package/docs/knowledge-graph.md

@@ -7,16 +7,20 @@ projection readiness.
 
 ## Source Rules
 
-- Markdown documents use front matter.
+- Markdown documents may use front matter. A document with no `kg` block is
+  represented as `unclassified`, assigned the fail-closed `private` audience,
+  and reported diagnostically rather than silently treated as governed.
 - Non-Markdown sources use adjacent `.kg.json` sidecars.
-- `kg.id` is required and stable.
-- `kg.audience` is required.
+- Once a Markdown `kg` block exists, `kg.id` and `kg.audience` are required;
+  empty, partial, and malformed declarations are blocking errors.
 - `kg.visibility` is invalid in local source metadata.
 - Declared relations emit semantic edges.
 
 ## Source formats
 
-The graph is sidecar-first: Markdown front matter is the only inline metadata
+The graph has one canonical classification engine in
+`src/graph/knowledge-graph.mjs`; the older `graph.mjs` surface is a compatibility
+adapter over it, not a second classifier. Markdown front matter is the only inline metadata
 format the kit reads, and every other file becomes a first-class node through
 an adjacent `<file>.kg.json` sidecar
 (`contracts/knowledge-source-sidecar.v1.schema.json`). This is how any format

package/docs/local-services.md

@@ -0,0 +1,101 @@
+# Managed local services
+
+Atelier-backed repositories sometimes need a local authoring, review, or
+preview service that writes repository-owned state. The service may be
+specialized; its lifecycle and data-boundary behavior should not be improvised.
+
+This contract applies to consumer services other than `atelier dev`. It does
+not change the Atelier sidecar's own lifecycle.
+
+## Atelier sidecar reference boundary
+
+The built-in `atelier dev` sidecar is the reference for its request and
+publication boundary, not for the managed lifecycle below. It binds only to a
+literal loopback host and refuses startup without a valid generated
+`atelier.manifest.json`. Static reads are limited to manifest-enrolled,
+supported file types after realpath containment; hidden, state, secret-shaped,
+symlinked, unknown, and unenrolled paths are denied. API reads require a trusted
+loopback host and `Sec-Fetch-Site: same-origin` or `none`; `same-site` and
+cross-site requests are refused. Mutations additionally require an
+allowed method, exact expected origin, and the session nonce. Its collaboration
+records are copy-only proposals, not an apply channel.
+
+## Kit and adapter boundary
+
+The portable Atelier layer owns these invariants:
+
+- bind to loopback only;
+- expose explicit `start`, `status`, and `stop` operations;
+- detach only when the user asked for a service that survives an agent command;
+- identify the running process with both a random runtime identifier and its
+  process ID;
+- refuse to adopt, overwrite, or stop a process whose identity cannot be
+  proven;
+- keep runtime records, logs, drafts, and recovery copies in ignored local
+  storage with owner-only permissions;
+- make writes atomic and keep a failed queued write from poisoning later saves;
+- keep unsaved browser work available when the service disappears;
+- provide an explicit snapshot export and a retry path;
+- use no telemetry, remote dependency, or external send path.
+
+The consuming repository owns its service name, port, executable, state schema,
+content, command names, and user-facing recovery copy. None of those adapter
+details belong in the public Atelier kit.
+
+## Lifecycle contract
+
+### Start
+
+1. Resolve an explicit loopback port and ignored runtime directory.
+2. Probe the service health endpoint.
+3. If a managed instance answers with the recorded runtime identifier and PID,
+   report it as already running.
+4. If anything else owns the port, refuse to take it over.
+5. Generate a fresh runtime identifier, start the child without a shell, write
+   a mode-0600 runtime record, and wait for health to echo both identifiers.
+6. If health never proves ownership, stop only the child just created and
+   report the ignored operational log.
+
+### Status
+
+Status is healthy only when the runtime record, health response, runtime
+identifier, PID, service identity, and loopback address agree. A responding
+port without that proof is occupied, not adopted.
+
+### Stop
+
+Stop only the PID whose health response matches the recorded runtime identifier
+and PID. Refuse on disagreement. After a clean stop, remove only the generated
+runtime record. Never kill by port, process name, or broad pattern.
+
+Managed start survives a terminal or agent command. It does not imply operating
+system startup. Installing an OS-level service is a separate system change and
+requires explicit user authorization.
+
+## Authoring-state contract
+
+- The canonical template may be tracked; the live draft must be ignored unless
+  a reviewed workflow explicitly promotes a sanitized artifact.
+- Live state and runtime metadata use owner-only permissions.
+- Browser autosave is a recovery layer, not a substitute for the canonical
+  local file.
+- A lost server must produce a persistent, actionable message naming the exact
+  restart command, the retained browser state, the snapshot option, and Retry.
+- Conflict responses remain fail-closed. Do not silently overwrite a newer
+  file or reconcile divergent tabs automatically.
+
+## Required evidence
+
+A consumer implementation is not complete until tests prove:
+
+1. start is idempotent and survives the launching command;
+2. status refuses an unowned listener;
+3. stop is bound to runtime identifier and PID;
+4. a stopped server leaves the exact in-browser draft intact;
+5. restart plus Retry persists that draft;
+6. a refused filesystem write does not break later valid saves;
+7. private state and runtime files are ignored and owner-readable only; and
+8. a fresh checkout can discover the commands through its agent instructions.
+
+Use synthetic fixtures for public Atelier tests. Tenant-specific proof remains
+in the tenant repository.

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,18 +102,52 @@ 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.
 
 ### 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 +176,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 +198,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