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

package/contracts/atelier-upgrade-plan.v3.schema.json

@@ -0,0 +1,532 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://mnstry.ai/schemas/atelier/atelier-upgrade-plan.v3.schema.json",
+  "$comment": "contract revision 3.0.0",
+  "title": "mnstry.atelier-upgrade-plan@v3",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema",
+    "digest",
+    "operation",
+    "workspace",
+    "repositoryId",
+    "configPath",
+    "baseHead",
+    "baseTree",
+    "branch",
+    "createdAt",
+    "expiresAt",
+    "policy",
+    "policyDigest",
+    "executorDigest",
+    "gitDigest",
+    "gitConfigDigest",
+    "hooksDigest",
+    "hooksPath",
+    "readSet",
+    "migration",
+    "writes",
+    "releaseEvidence",
+    "dependencyInstallation",
+    "mode",
+    "recoveryCoverage",
+    "message",
+    "gitAuxDigest",
+    "participant"
+  ],
+  "properties": {
+    "schema": {
+      "const": "mnstry.atelier-upgrade-plan@v3"
+    },
+    "digest": {
+      "type": "string",
+      "pattern": "^sha256:[a-f0-9]{64}$"
+    },
+    "operation": {
+      "const": "prepare-local-candidate"
+    },
+    "workspace": {
+      "type": "string",
+      "minLength": 1
+    },
+    "repositoryId": {
+      "type": "string",
+      "pattern": "^sha256:[a-f0-9]{64}$"
+    },
+    "configPath": {
+      "type": "string",
+      "minLength": 1
+    },
+    "baseHead": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{40,64}$"
+    },
+    "baseTree": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{40,64}$"
+    },
+    "branch": {
+      "type": "string",
+      "minLength": 1
+    },
+    "createdAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "expiresAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "policy": {
+      "$schema": "https://json-schema.org/draft/2020-12/schema",
+      "$id": "https://mnstry.ai/schemas/atelier/atelier-adoption-policy.v2.schema.json",
+      "$comment": "contract revision 2.0.0",
+      "title": "mnstry.atelier-adoption-policy@v2",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "schema",
+        "enabled",
+        "mode",
+        "maxAgeSeconds",
+        "recoveryCoverage",
+        "allowedEffects",
+        "participant"
+      ],
+      "properties": {
+        "schema": {
+          "const": "mnstry.atelier-adoption-policy@v2"
+        },
+        "enabled": {
+          "type": "boolean"
+        },
+        "mode": {
+          "const": "manual-exact-plan"
+        },
+        "maxAgeSeconds": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 86400
+        },
+        "recoveryCoverage": {
+          "const": "local-only"
+        },
+        "allowedEffects": {
+          "const": [
+            "template-adoption",
+            "lock-and-projections",
+            "git-commit"
+          ]
+        },
+        "participant": {
+          "const": "local-template-profile@1"
+        },
+        "ext": {
+          "type": "object",
+          "maxProperties": 0,
+          "description": "Reserved extension container; no extension behavior is supported by this contract."
+        },
+        "contractVersion": {
+          "type": "string",
+          "pattern": "^2\\.[0-9]+\\.[0-9]+$"
+        }
+      }
+    },
+    "policyDigest": {
+      "type": "string",
+      "pattern": "^sha256:[a-f0-9]{64}$"
+    },
+    "executorDigest": {
+      "type": "string",
+      "pattern": "^sha256:[a-f0-9]{64}$"
+    },
+    "gitDigest": {
+      "type": "string",
+      "pattern": "^sha256:[a-f0-9]{64}$"
+    },
+    "gitConfigDigest": {
+      "type": "string",
+      "pattern": "^sha256:[a-f0-9]{64}$"
+    },
+    "hooksDigest": {
+      "type": "string",
+      "pattern": "^sha256:[a-f0-9]{64}$"
+    },
+    "hooksPath": {
+      "type": "string",
+      "minLength": 1
+    },
+    "readSet": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "path",
+          "state"
+        ],
+        "properties": {
+          "path": {
+            "type": "string",
+            "minLength": 1
+          },
+          "state": {
+            "anyOf": [
+              {
+                "type": "null"
+              },
+              {
+                "type": "object",
+                "additionalProperties": false,
+                "required": [
+                  "digest",
+                  "mode"
+                ],
+                "properties": {
+                  "digest": {
+                    "type": "string",
+                    "pattern": "^sha256:[a-f0-9]{64}$"
+                  },
+                  "mode": {
+                    "enum": [
+                      "100644",
+                      "100755"
+                    ]
+                  },
+                  "ext": {
+                    "type": "object",
+                    "maxProperties": 0,
+                    "description": "Reserved extension container; no extension behavior is supported by this contract."
+                  }
+                }
+              }
+            ]
+          },
+          "ext": {
+            "type": "object",
+            "maxProperties": 0,
+            "description": "Reserved extension container; no extension behavior is supported by this contract."
+          }
+        }
+      }
+    },
+    "migration": {
+      "$schema": "https://json-schema.org/draft/2020-12/schema",
+      "$id": "https://mnstry.ai/schemas/atelier/atelier-migration.v3.schema.json",
+      "$comment": "contract revision 3.0.0",
+      "title": "mnstry.atelier-migration@v3",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "schema",
+        "id",
+        "executorDigest",
+        "readScope",
+        "allowedWrites",
+        "sideEffects",
+        "postChecks"
+      ],
+      "properties": {
+        "schema": {
+          "const": "mnstry.atelier-migration@v3"
+        },
+        "id": {
+          "const": "local-template-profile@1"
+        },
+        "executorDigest": {
+          "type": "string",
+          "pattern": "^sha256:[a-f0-9]{64}$"
+        },
+        "readScope": {
+          "const": "whole-enrolled-repository"
+        },
+        "allowedWrites": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "sideEffects": {
+          "const": [
+            "git-index",
+            "git-commit"
+          ]
+        },
+        "postChecks": {
+          "const": [
+            "exact-inventory",
+            "lock-schema",
+            "exact-index",
+            "commit-parent-tree-message",
+            "template-adoption",
+            "template-current-source"
+          ]
+        },
+        "ext": {
+          "type": "object",
+          "maxProperties": 0,
+          "description": "Reserved extension container; no extension behavior is supported by this contract."
+        },
+        "contractVersion": {
+          "type": "string",
+          "pattern": "^3\\.[0-9]+\\.[0-9]+$"
+        }
+      }
+    },
+    "writes": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "path",
+          "owner",
+          "action",
+          "before",
+          "after",
+          "content"
+        ],
+        "properties": {
+          "path": {
+            "type": "string",
+            "minLength": 1
+          },
+          "owner": {
+            "enum": [
+              "lock",
+              "generated",
+              "template",
+              "template-history"
+            ]
+          },
+          "action": {
+            "enum": [
+              "create",
+              "update"
+            ]
+          },
+          "before": {
+            "anyOf": [
+              {
+                "type": "null"
+              },
+              {
+                "type": "object",
+                "additionalProperties": false,
+                "required": [
+                  "digest",
+                  "mode"
+                ],
+                "properties": {
+                  "digest": {
+                    "type": "string",
+                    "pattern": "^sha256:[a-f0-9]{64}$"
+                  },
+                  "mode": {
+                    "enum": [
+                      "100644",
+                      "100755"
+                    ]
+                  },
+                  "ext": {
+                    "type": "object",
+                    "maxProperties": 0,
+                    "description": "Reserved extension container; no extension behavior is supported by this contract."
+                  }
+                }
+              }
+            ]
+          },
+          "after": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "digest",
+              "mode"
+            ],
+            "properties": {
+              "digest": {
+                "type": "string",
+                "pattern": "^sha256:[a-f0-9]{64}$"
+              },
+              "mode": {
+                "const": "100644"
+              },
+              "ext": {
+                "type": "object",
+                "maxProperties": 0,
+                "description": "Reserved extension container; no extension behavior is supported by this contract."
+              }
+            }
+          },
+          "content": {
+            "type": "string",
+            "maxLength": 16777216
+          },
+          "ext": {
+            "type": "object",
+            "maxProperties": 0,
+            "description": "Reserved extension container; no extension behavior is supported by this contract."
+          }
+        }
+      }
+    },
+    "releaseEvidence": {
+      "type": "null"
+    },
+    "dependencyInstallation": {
+      "const": "excluded"
+    },
+    "mode": {
+      "const": "manual-exact-plan"
+    },
+    "recoveryCoverage": {
+      "const": "local-only"
+    },
+    "message": {
+      "type": "string",
+      "minLength": 1
+    },
+    "gitAuxDigest": {
+      "type": "string",
+      "pattern": "^sha256:[a-f0-9]{64}$"
+    },
+    "participant": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "profileFile",
+        "selectionFile",
+        "profileDigest",
+        "selectionDigest",
+        "templateRef",
+        "bindingRef",
+        "previousAdoptionDigest",
+        "adoptionDigest"
+      ],
+      "properties": {
+        "id": {
+          "const": "local-template-profile@1"
+        },
+        "profileFile": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 512
+        },
+        "selectionFile": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 512
+        },
+        "profileDigest": {
+          "type": "string",
+          "pattern": "^sha256:[a-f0-9]{64}$"
+        },
+        "selectionDigest": {
+          "type": "string",
+          "pattern": "^sha256:[a-f0-9]{64}$"
+        },
+        "templateRef": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "kind",
+            "id",
+            "version",
+            "digest"
+          ],
+          "properties": {
+            "kind": {
+              "const": "TemplateRef"
+            },
+            "id": {
+              "type": "string",
+              "pattern": "^[a-z][a-z0-9]*(?:[.:-][a-z0-9]+)*$",
+              "maxLength": 128
+            },
+            "version": {
+              "type": "string",
+              "pattern": "^(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)(?:-[a-z0-9]+(?:[.-][a-z0-9]+)*)?$",
+              "maxLength": 64
+            },
+            "digest": {
+              "type": "string",
+              "pattern": "^sha256:[a-f0-9]{64}$"
+            },
+            "ext": {
+              "type": "object",
+              "maxProperties": 0,
+              "description": "Reserved extension container; no extension behavior is supported by this contract."
+            }
+          }
+        },
+        "bindingRef": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "kind",
+            "id",
+            "version",
+            "digest"
+          ],
+          "properties": {
+            "kind": {
+              "const": "BindingRef"
+            },
+            "id": {
+              "type": "string",
+              "pattern": "^[a-z][a-z0-9]*(?:[.:-][a-z0-9]+)*$",
+              "maxLength": 128
+            },
+            "version": {
+              "type": "string",
+              "pattern": "^(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)(?:-[a-z0-9]+(?:[.-][a-z0-9]+)*)?$",
+              "maxLength": 64
+            },
+            "digest": {
+              "type": "string",
+              "pattern": "^sha256:[a-f0-9]{64}$"
+            },
+            "ext": {
+              "type": "object",
+              "maxProperties": 0,
+              "description": "Reserved extension container; no extension behavior is supported by this contract."
+            }
+          }
+        },
+        "previousAdoptionDigest": {
+          "anyOf": [
+            {
+              "type": "null"
+            },
+            {
+              "type": "string",
+              "pattern": "^sha256:[a-f0-9]{64}$"
+            }
+          ]
+        },
+        "adoptionDigest": {
+          "type": "string",
+          "pattern": "^sha256:[a-f0-9]{64}$"
+        },
+        "ext": {
+          "type": "object",
+          "maxProperties": 0,
+          "description": "Reserved extension container; no extension behavior is supported by this contract."
+        }
+      }
+    },
+    "ext": {
+      "type": "object",
+      "maxProperties": 0,
+      "description": "Reserved extension container; no extension behavior is supported by this contract."
+    },
+    "contractVersion": {
+      "type": "string",
+      "pattern": "^3\\.[0-9]+\\.[0-9]+$"
+    }
+  }
+}

package/docs/architecture.md

@@ -0,0 +1,89 @@
+# Responsibilities, workflows and runtime bindings
+
+Atelier is a repository substrate for people, agents and tools. Its portable
+contracts, governance, graph and local runtime support eight responsibilities.
+
+| Responsibility | Work it owns | Existing entry points |
+| --- | --- | --- |
+| Inquiry | Investigate uncertainty and assess evidence | Discovery and Research Harnesses; `inquiry` |
+| Knowledge Stewardship | Curate, govern, connect and operationalize knowledge | `harness knowledge`, `ingest`, intake, graph and context; [evidence navigation](evidence-navigation.md), composed by Discovery and Research |
+| Practical Judgment | Discern fitting action, cultivate practice and learn from consequences | `learn`, practical cases, decision adapters, `practice` |
+| Creation and Delivery | Design, implement, verify and deliver changes | `harness build` |
+| Capability Stewardship | Qualify, package, adopt, exercise and evolve reusable abilities | `capability`, Skill Steward and `skills` |
+| Reflection | Form revisable assessments of the person, work, interaction and system | Witness role; qualified assessments and reflective acts |
+| Interaction | Listen, communicate, pace, challenge and repair | Companion policy and controller over one host authority |
+| Coordination | Connect work, owners, dependencies, delivery, recovery and outcomes | Collaboration, Build and typed Coordination projections |
+
+These names describe responsibilities. A **harness** composes responsibilities
+into work. A **role** describes participation. A **capability** specifies a
+supported outcome; a **resource** realizes it. A **method** is an optional way of
+working. A **record** retains domain meaning. A **host** executes through its
+actual bindings. A role does not acquire a new store or permission merely by
+being named. Coaching is one reflective method. Phronesis remains the foundation
+of Practical Judgment, including purposes, particulars, taste and exceptions.
+
+Skill Steward is a specialized role within Capability Stewardship. Its existing
+catalog and bindings remain authoritative for managed skills. Knowledge
+Stewardship owns knowledge inclusion and applicability. Neither owns another
+repository's adoption decision. Fabric can implement Coordination; the local
+contracts do not require a Fabric service or account.
+
+Creation and Delivery also owns the kit's user-facing failure contract: one
+diagnostic shape, a registry of stable codes, and one exit-code convention for
+every command. Other responsibilities raise typed diagnostics through that
+contract rather than defining their own formats. The contract is proposed in
+issue #90 and is not yet implemented. Until it lands, existing typed codes and
+refusal classes remain authoritative.
+
+`atelier architecture catalog` returns the validated catalog. `architecture
+entry "Skill Steward"` resolves a name. Historical names remain aliases: Discovery
+Engine resolves to Discovery Harness; Skills Harness resolves to Capability
+Harness. Existing persisted CLI/schema/API identifiers are retained.
+
+## Authoring must name its consumers
+
+The additive `atelier-behavior-binding@v1` contract links exact authored
+definition references to field pointers and named, versioned consumers. Each
+field is classified as deterministic **enforcement**, interpreted **guidance**,
+**presentation**, or descriptive **rationale**. Required unsupported behavior
+prevents resolution; optional gaps remain visible in diagnostics.
+
+Pass `{binding, consumers}` to `atelier architecture resolve` or
+`resolveBehaviorBinding` from `@mnstry/atelier/architecture`. Consumer declarations
+bind identity, profile, revision and supported classifications. This is contract
+resolution, not evidence that the declaration is truthful or that a host has
+loaded the definition. The output explicitly leaves adoption unestablished.
+
+Qualification must connect authored bytes, resolved binding, exact adopted and
+consumed revision, executed operation, durable readback and rendered state.
+Preview and production use the same relevant rules with explicitly different
+adapters. A changed authored file must not silently change existing adoptions.
+Host authentication, release resolution, operation authorization and storage stay
+with their owners. An unsupported host supplies diagnostics, not an invented
+fallback interpretation.
+
+## Contract ownership and current coverage
+
+| Meaning | Authoritative mechanism | Consumer proof required |
+| --- | --- | --- |
+| Research evidence and assessment | Inquiry ledger and assessment profiles | Exact handoff, source-family handling and withdrawal |
+| Source custody | Intake store; bounded ingestion processor receipts | Source bytes, output integrity, freshness and locators |
+| Knowledge applicability | Knowledge review and activation records | Current dependencies, local-source checks and retrieval |
+| Accepted learning | Learning decisions and per-harness activation | Scope/exception preservation and withdrawal |
+| Managed capabilities | Exact release, adoption state and binding inventory | Installation, host loading and exercise remain separate |
+| Scoped agent instructions | Instruction adoption adapter | Exact plan, destination readback and consumer context receipt |
+| Build and coordination | Candidate, attempt, gate and handoff records | Native gate evidence and receiving acceptance |
+| Personal Trackables | The selected host's domain writer | Definition adoption, occurrences, evidence and qualified views |
+| Conversation and reflection | Selected host conversation/effect authority | Delivery, interruption, correction and scope controls |
+
+The portable Trackables reducer/local store, Reflection qualification, Interaction
+controller and Coordination views supply reference implementations. Production
+host adoption is not established by this catalog. A catalog entry is not an executable runtime or an additional
+semantic registry. Host adapters must map these contracts to existing domain
+operations rather than create competing writers.
+
+See [Practical Judgment](practical-judgment.md), [research starter](research-starter.md)
+and [integration decisions](integration-contract-decisions.md).
+
+See [Trackables](trackables.md), [Interaction and Reflection](interaction-and-reflection.md)
+and [Coordination](coordination.md) for supported profiles, native bindings and limits.

package/docs/assurance-controls.md

@@ -22,8 +22,8 @@ commit and packed-tarball digest.
 | Source application policy is re-read before every automatic apply | The engine authorizes from disk immediately before each dispatch; manual mode never reaches the apply operation; the service keeps this on every tick; the apply operation reads the installed policy again at its decision and immediately before the write, recomputes its digest and evaluates its selector over the current canonical graph; `policy install` verifies that digest and names the expected one; whether this machine may see the object is asked before anything else, so an absent and a withheld object get one answer | Revocation, manual-mode and apply-unavailable cases in `test/obsidian-maintenance.test.mjs`; policy, refusal-table and late-revocation cases in `test/obsidian-edits.test.mjs`, each with a deliberately broken rule that must fail | A policy is private configuration of one machine; whoever can write that private state can install one |
 | Applying an edit to a source file cannot lose another program's bytes | One operation for a person and for a policy: exact identity, path and digest checks at commit; the write is an atomic exchange, never a check followed by a rename; displaced bytes that are not the base are exchanged back and retained; the old source stays as a backup that is looked at again for late writers; write-ahead record and intent before the exchange; restart recovery decides from digests only, and so does an exchange that reports a failure; generated regions never reach a source: the tail is intact, or removed with the end of the authored text proven, and anything else refuses; every git directory is refused, nested, respelled or relocated; the hold on an edited note lifts only on a read of the note at that moment; no git command that writes | `test/obsidian-edits.test.mjs`: end to end through the real engine, a refusal table with a whole-project byte and `git status` oracle, a real second process writing in three styles and four timings with both outcomes asserted, a crash at every durable step, a disclosure walk, a generated tail cut at every byte offset from both sides and a fuzz over the whole note; every oracle has a mutation control | macOS arm64 on APFS only; refuses where no atomic exchange exists; the source becomes a new file (permission bits kept, hard links refused); a late writer's bytes are retained and surfaced, never merged; a hard link made after the path check is not detected; a fragment of generated text shorter than eight bytes left inside an edited body cannot be told from typing |
 | A structural edit made in a vault becomes one copy-only proposal and never a source change | The proposal adapter routes by whole identity to the existing store of the enrolled repository or refuses typed and writes nothing; it records the operation in private immutable state first, looks in the persisted store for its operation identity before creating, under a private per-repository lock taken over only with proof; it preflights the ledger limits, defers `ledger-full`, refuses `proposal-too-large` and `ledger-corrupt`, bounds batches and retries, and never compacts; a proposal holds codes, offsets and digests and no note text; acceptance is shown and never acted on | `test/obsidian-proposals.test.mjs`: routing table with a whole-project byte and `git status` oracle, identity survival against the real store, a crash at every step, two real processes, generated ledgers at 256 KiB, 16 MiB and 10,000 events and an invalid line, a no-busy-loop count of store reads, a disclosure walk; engine cases in `test/obsidian-maintenance.test.mjs`; every oracle has a mutation control | In manual mode an operation exists only after apply has looked at the edit; a refused or exhausted operation waits for a person; the store directory lives in the repository and must be git-ignored; two workspaces that enrol one repository create one proposal each |
-| Opening a view reports `current` only for the exact, verified, present generation and a qualified app | `open` needs a tick of the proven service after the request, a persisted `current`, an independent read-back of the trusted pointer and every note, and an app at or above the minimum version that lists the vault and answers for it; the vault is added to the app's list through the app while it runs, and in its settings file only while the process table shows no Obsidian, atomically, with a backup, keeping every other key, and leaving nothing behind when a step fails; never inside a folder the app lists as a vault; a call about the vault is routed, from the app's list, to that vault only (its folder or its id) or not made; every other outcome is typed, distinct and exits non-zero; the app and the operating system are reached only through injected seams, and the production ones only behind `--adapter=obsidian-cli` | `test/obsidian-open.test.mjs`: outcome table, read-back, app-floor, busy, read-only, every app state, settings-file refusal and retry cases, each with a deliberately broken rule that must fail; a failure injected at every file-system call of the settings write; call routing against a model of the app's own routing; a spawn guard (a private HOME, on Linux a private XDG_RUNTIME_DIR, and no such child on Windows) and a production-seam import check; the opt-in `test/obsidian-first-open-real-app.test.mjs` against an isolated app | The operating system's URL opener is not exercised by any test (the real-app suite hands URLs to its isolated app directly); `indexing` relies on an undocumented readiness field; the real-app suite has run on macOS only |
-| Operating-system startup is never installed implicitly | `buildStartupAdapter` is pure text generation; Windows refuses typed; the service refuses `--startup` without a consent that covers startup | Builder purity oracle (no filesystem, process or home-directory access; no machine path beyond its inputs) and startup-consent refusal | Generated units have not been qualified against real launchd or systemd hosts |
+| Opening a view reports `current` only for the exact, verified, present generation and a qualified app | `open` needs a tick of the proven service after the request, a persisted `current`, an independent read-back of the trusted pointer and every note, and an app at or above the minimum version that lists the vault and answers for it; the vault is added to the app's list through the app while it runs, and in its settings file only while the process table shows no Obsidian, atomically, with a backup, keeping every other key, and leaving nothing behind when a step fails; never inside a folder the app lists as a vault; a call about the vault is routed, from the app's list, to that vault only (its folder or its id) or not made; every other outcome is typed, distinct and exits non-zero; the app and the operating system are reached only through injected seams, and the production ones only behind the selected adapter: `--adapter=obsidian-cli`, or the one the workspace remembers, which the test runner never uses | `test/obsidian-open.test.mjs`: outcome table, read-back, app-floor, busy, read-only, every app state, settings-file refusal and retry cases, each with a deliberately broken rule that must fail; a failure injected at every file-system call of the settings write; call routing against a model of the app's own routing; a spawn guard (a private HOME, on Linux a private XDG_RUNTIME_DIR, and no such child on Windows) and a production-seam import check; the opt-in `test/obsidian-first-open-real-app.test.mjs` against an isolated app | The operating system's URL opener is not exercised by any test (the real-app suite hands URLs to its isolated app directly); `indexing` relies on an undocumented readiness field; the real-app suite has run on macOS only |
+| Operating-system startup is never installed implicitly | `buildStartupAdapter` is pure text generation; a login item is installed only by `service unit --install`, after a consent that covers startup is recorded; the production service manager refuses under the test runner and for a HOME that is not the account's; Windows refuses typed; the service refuses `--startup` without a consent that covers startup, and under it a refusal exits 0 so it is not restarted in a loop | Builder purity oracle; golden unit texts; manager call sequences against launchctl and systemctl stand-ins; production-manager refusals in a child process; a spawn and file guard on the real LaunchAgents and systemd folders; startup refusal exit codes | The managers have been exercised against stand-ins, not against a live launchd or systemd session |
 | Expected operator failures are actionable without leaking internals | Typed project/JSON diagnostics and the CLI execution wrapper | `test/cli-brand.test.mjs` | Unexpected stacks require the operator to opt in with `ATELIER_DEBUG=1` |
 | Published APIs do not disappear silently | Tag-derived subpath and named-export baseline plus version/tag identity refusal | `public-api:compat`; `test/public-api-compat.test.mjs` | Additive API checks do not decide whether a new version number is appropriate |
 | The published artifact is the artifact tested | `release:candidate` packs once, binds SHA-256, sends that exact archive through allowlist/content audit, bare-consumer install, all-export import, and branded distribution smoke, then the trusted-publishing workflow retains and publishes that same tarball path | `release:audit`, `consumer:smoke`, `distribution:smoke`, `assurance:mutation-smoke`, `publish-workflow.test.mjs` | Passing gates does not publish, deploy, or constitute an external reviewer’s approval |

package/docs/blocks/capability-stewardship.md

@@ -0,0 +1,17 @@
+Atelier's Skill Steward can govern portable capabilities alongside a person's
+existing skills and tools. A capability package describes the useful outcome,
+its procedures, requirements, evaluation evidence and limits. Each repository
+chooses exact release pins, aliases and whether to reference, manage, customize
+or retire it.
+
+The local foundation verifies complete package contents, prepares an exact
+adoption plan, preserves previous bundles, and refuses collisions and local
+drift. Repository host profiles keep placement explicit. Cross-repository status
+shows each adopter's own state; one repository's update never implies another's
+acceptance.
+
+Installation, host discovery and successful exercise are separate evidence.
+Content-free observations can guide improvement, and draft graph records keep
+provenance connected to adoption and outcomes. Publisher authentication, live
+host evaluation and human acceptance require their own evidence. This source
+capability is intended for the next release; alpha.7 does not expose its command.