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

package/README.md

@@ -31,10 +31,50 @@ that must stay legible, internally connected, privacy-aware, and usable across
 many interfaces. Methodology authoring is one application of the system, not
 its definition or ceiling.
 
+See the [responsibility architecture](docs/architecture.md) for Inquiry, Knowledge
+Stewardship, Practical Judgment, Creation and Delivery, Capability Stewardship,
+Reflection, Interaction and Coordination. Start a provider-neutral research
+workflow with the [research starter](docs/research-starter.md).
+Use [portable template profiles](docs/template-profile.md) to bind semantic and
+surface roles to canonical sources, with optional advisory decisions and
+separate host and release validation.
+
+Follow the [Knowledge Health workshop](docs/knowledge-health/quickstart.md) to
+inspect its finding, retain a contribution, and follow the owning correction
+and evidence refresh. Use the exact version and host qualified for that release.
+
+The Knowledge Health kit starts subprocesses, which the egress scanner does not
+model. `src/knowledge-health/example.mjs` and `src/knowledge-health/workshop.mjs`
+run `git init` in the new disposable directory they create.
+`src/knowledge/participatory/installed-workshop.mjs` imports the subprocess API
+and calls nothing through it; its setup uses that workshop's `git init`.
+`src/knowledge-health/proof/installed-check.mjs` runs the installed `atelier`
+bin and `git init` in a consumer directory.
+`src/knowledge-health/proof/common.mjs` runs `npm` and Node for the maintainer
+rehearsal script `src/knowledge-health/proof/rehearse.mjs`, which calls
+`npm view`, `npm install` and `npm pack` against `https://registry.npmjs.org`.
+No Atelier command or package export runs that script; it uses the network only
+when a maintainer starts it by hand.
+
 ## From files to a working system
 
+Start with a question that changes useful work. The
+[knowledge setup workflow](docs/knowledge-setup.md) supplies an editable ontology
+plan, a fictional starter, and CLI checks that connect concepts to questions.
+`atelier knowledge context` selects complete, source-linked evidence within a
+byte budget; `atelier knowledge evaluate` compares lexical and graph retrieval
+without provider calls. A passing check is structural evidence; useful answers
+and efficient token usage still need measurement in real work.
+
 For local-harness authoring, see [durable coauthor sessions](docs/coauthor-session.md)
 and [skill stewardship and managed installation](docs/skill-steward.md).
+The next-release [capability stewardship foundation](docs/capability-stewardship.md)
+adds portable packages, repository-owned adoption and version-bound evidence
+alongside existing skills and tools.
+[Learning from feedback](docs/learning.md) connects private observations to
+reviewed lessons and explicitly activated harness context, with a local CLI.
+[Progressive local ingestion](docs/ingestion.md) preserves selected sources and
+provides bounded text, CSV and JSON evidence search before interpretation.
 [Immutable intake and guide contracts](docs/intake-and-guides.md) extend existing
 processing and hosted-tool adapters without adding remote execution or publication
 authority. These alpha capabilities require explicit consumer integration.
@@ -54,7 +94,7 @@ governed projections
 You can see the complete loop in a disposable sample workspace:
 
 ```bash
-npm install --save-dev @mnstry/atelier@0.2.0-alpha.12
+npm install --save-dev @mnstry/atelier@0.2.0-alpha.13
 npx mnstry-atelier init --fixture=sample-workspace --target ./sample
 npx mnstry-atelier graph --project ./sample/atelier.project.json
 npx mnstry-atelier project --project ./sample/atelier.project.json
@@ -248,6 +288,56 @@ uncertainty. `@mnstry/atelier/decisions` validates these records offline.
 The host supplies optional provider execution and retains authorization;
 an assessment carries proposal-only authority.
 
+## Capabilities alongside your existing tools
+
+<!-- atelier:block:capability-stewardship:start -->
+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.
+<!-- atelier:block:capability-stewardship:end -->
+
+See [capability stewardship](docs/capability-stewardship.md) for the operating guide.
+
+## Discovery and research
+
+<!-- atelier:block:inquiry-harnesses:start -->
+Discovery Harness and Research Harness share a local inquiry history. Discovery
+frames questions and competing explanations; Research returns source captures,
+verified assertions, contradictions and new questions. Immutable references keep
+each assessment and decision connected to the exact evidence it used.
+
+The open foundation includes qualitative assessments, explicit elicited odds,
+a simple Bayesian rate model, evidence-family checks, withdrawal tracking and
+reviewable graph proposals. Numerical results remain conditional on the declared
+model and evidence. They grant no execution or publication authority.
+
+Each harness is available as a portable capability package alongside existing
+skills. Skill Steward governs its version and repository adoption. Provider
+execution, hosted collaboration and specialized proprietary methods can use the
+same handoff and evidence contracts through separately authorized adapters.
+
+The architecture catalog calls the workflow Discovery Harness and resolves
+Discovery Engine as its historical alias. The immutable bundled v1 readiness
+pack retains its Discovery Engine title, identifiers and original digest, so
+existing release locks can use the governed upgrade path without a separate repin.
+<!-- atelier:block:inquiry-harnesses:end -->
+
+See [Discovery and Research Harnesses](docs/inquiry-harnesses.md) for the local workflow.
+
 ## Where the Atelier stops
 
 The open package owns repository-side structure and proof. A managed runtime
@@ -288,15 +378,28 @@ 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 local authoring HTTP client
+submodule refs.
+
+The explicitly invoked maintainer rehearsal
+`src/knowledge-health/proof/rehearse.mjs` uses
+`src/knowledge-health/proof/common.mjs` to run `npm view`, `npm install` and
+optional `npm pack` against `https://registry.npmjs.org`. These commands can use
+the public package registry. The rehearsal uses empty consumer npm configuration
+and a disposable install/cache; installation uses `--ignore-scripts`. It is a
+maintainer proof command, not an automatic local authoring or conformance
+operation, and it calls no model provider. Its `npm ls` reads the consumer
+dependency tree. This disclosure does not authorize a registry rehearsal or
+publication.
+
+The local authoring 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:
+`child_process`; the `gh`, enrolled Git and explicit maintainer `npm` paths above
+are documented subprocess exceptions rather than scanner detections:
 
 ```bash
 npm run egress:check
@@ -378,7 +481,7 @@ Node.js 22 (22.18.0 or later) or Node.js 24 (24.13.1 or later) is required.
 Pin the prerelease while the package remains in alpha:
 
 ```bash
-npm install --save-dev @mnstry/atelier@0.2.0-alpha.12
+npm install --save-dev @mnstry/atelier@0.2.0-alpha.13
 ```
 
 Then choose the path that matches what you are building:
@@ -397,7 +500,7 @@ Then choose the path that matches what you are building:
 
 ## Status and command reference
 
-Current package: `@mnstry/atelier@0.2.0-alpha.12`.
+Current package: `@mnstry/atelier@0.2.0-alpha.13`.
 
 The alpha package is usable and contract-tested, but its library API may still
 change before a stable release. Pin the exact version in production toolchains.
@@ -461,3 +564,36 @@ the [contract](docs/obsidian-contract.md) and the
 [maintenance service](docs/local-services.md) before relying on it. The
 package subpaths are `@mnstry/atelier/obsidian` and
 `@mnstry/atelier/obsidian/*`.
+
+<!-- atelier:block:learning-harnesses:start -->
+## Knowledge and Build Harnesses
+
+Knowledge Harness supports establishing, developing, evaluating, curating and
+activating a body of knowledge. Ingestion is one entry point alongside original
+writing, observation, research and build results. Contributions retain their
+domain revision, provenance, uncertainty and owner-reported review history.
+
+Build Harness records bounded objectives, exact candidates, artifact dependencies,
+attempts and distinct verification gates. Its coordination proposal can be read
+by Fabric or another adapter. The shared harness contract connects these workflows
+to Discovery, Research and Skill Steward without replacing their domain records.
+
+These are local, provider-neutral source capabilities for the next release.
+Handoffs preserve exact pins, and explicit source snapshots reveal corrections
+that require downstream reconsideration. Graph outputs remain draft proposals.
+Recorded acceptance is not authenticated authority, and local checks do not prove
+research quality or recipient acceptance. Hosted execution remains adapter-owned.
+<!-- atelier:block:learning-harnesses:end -->
+
+Read the [Knowledge and Build Harness guide](docs/learning-harnesses.md) for the complete local learning cycle.
+
+The [research quickstart](docs/research-starter-quickstart.md) explains how to use
+a supplied candidate packet with existing tools and skills. See
+[Trackables](docs/trackables.md), [Interaction and Reflection](docs/interaction-and-reflection.md)
+and [Coordination](docs/coordination.md) for portable runtime profiles and host obligations.
+
+The optional [knowledge workspace](docs/knowledge-workspace.md) connects
+onboarding, ontology modeling, evidence deepening, application, and outcome
+learning with shared private coauthor sessions for people and agents.
+
+The [public workshop profile](docs/knowledge-health/devday/public-default.md) uses the existing Knowledge host to retain ordinary drafts and one copy-only source-owner handoff as a local proposal.

package/contracts/atelier-adoption-policy.v2.schema.json

@@ -0,0 +1,55 @@
+{
+  "$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]+$"
+    }
+  }
+}

package/contracts/atelier-architecture.v1.schema.json

@@ -0,0 +1,258 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://mnstry.ai/schemas/atelier/atelier-architecture.v1.schema.json",
+  "$defs": {
+    "catalog": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "schema": {
+          "const": "atelier-architecture-catalog@v1"
+        },
+        "entries": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "id": {
+                "type": "string",
+                "pattern": "^[a-z][a-z0-9.-]{0,95}$"
+              },
+              "kind": {
+                "enum": [
+                  "responsibility",
+                  "harness",
+                  "role",
+                  "capability",
+                  "resource",
+                  "method",
+                  "record",
+                  "host"
+                ]
+              },
+              "label": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 1024
+              },
+              "aliases": {
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "minLength": 1,
+                  "maxLength": 1024
+                },
+                "maxItems": 12
+              },
+              "purpose": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 1024
+              },
+              "implementation": {
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "minLength": 1,
+                  "maxLength": 1024
+                },
+                "maxItems": 16
+              },
+              "ext": {
+                "type": "object",
+                "maxProperties": 0
+              }
+            },
+            "required": [
+              "id",
+              "kind",
+              "label",
+              "aliases",
+              "purpose",
+              "implementation"
+            ]
+          },
+          "maxItems": 128
+        },
+        "relations": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "from": {
+                "type": "string",
+                "pattern": "^[a-z][a-z0-9.-]{0,95}$"
+              },
+              "type": {
+                "enum": [
+                  "composes",
+                  "participates",
+                  "realizes",
+                  "supports",
+                  "applies",
+                  "handles",
+                  "executes"
+                ]
+              },
+              "to": {
+                "type": "string",
+                "pattern": "^[a-z][a-z0-9.-]{0,95}$"
+              },
+              "ext": {
+                "type": "object",
+                "maxProperties": 0
+              }
+            },
+            "required": [
+              "from",
+              "type",
+              "to"
+            ]
+          },
+          "maxItems": 256
+        },
+        "contractVersion": {
+          "type": "string",
+          "pattern": "^1\\.[0-9]+\\.[0-9]+$"
+        },
+        "ext": {
+          "type": "object",
+          "maxProperties": 0
+        }
+      },
+      "required": [
+        "schema",
+        "entries",
+        "relations"
+      ]
+    },
+    "binding": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "schema": {
+          "const": "atelier-behavior-binding@v1"
+        },
+        "definition": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "ref": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 1024
+            },
+            "digest": {
+              "type": "string",
+              "pattern": "^sha256:[0-9a-f]{64}$"
+            },
+            "ext": {
+              "type": "object",
+              "maxProperties": 0
+            }
+          },
+          "required": [
+            "ref",
+            "digest"
+          ]
+        },
+        "fields": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "pointer": {
+                "type": "string",
+                "pattern": "^(/([^~/]|~[01])*)+$",
+                "maxLength": 1024
+              },
+              "classification": {
+                "enum": [
+                  "enforced",
+                  "guidance",
+                  "presentation",
+                  "rationale"
+                ]
+              },
+              "required": {
+                "type": "boolean"
+              },
+              "consumer": {
+                "anyOf": [
+                  {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "properties": {
+                      "id": {
+                        "type": "string",
+                        "pattern": "^[a-z][a-z0-9.-]{0,95}$"
+                      },
+                      "profile": {
+                        "type": "string",
+                        "pattern": "^[a-z][a-z0-9.-]{0,95}$"
+                      },
+                      "revision": {
+                        "type": "string",
+                        "minLength": 1,
+                        "maxLength": 1024
+                      },
+                      "ext": {
+                        "type": "object",
+                        "maxProperties": 0
+                      }
+                    },
+                    "required": [
+                      "id",
+                      "profile",
+                      "revision"
+                    ]
+                  },
+                  {
+                    "type": "null"
+                  }
+                ]
+              },
+              "ext": {
+                "type": "object",
+                "maxProperties": 0
+              }
+            },
+            "required": [
+              "pointer",
+              "classification",
+              "required",
+              "consumer"
+            ]
+          },
+          "maxItems": 128
+        },
+        "contractVersion": {
+          "type": "string",
+          "pattern": "^1\\.[0-9]+\\.[0-9]+$"
+        },
+        "ext": {
+          "type": "object",
+          "maxProperties": 0
+        }
+      },
+      "required": [
+        "schema",
+        "definition",
+        "fields"
+      ]
+    }
+  },
+  "title": "Atelier architecture catalog and behavior bindings",
+  "$comment": "contract revision 1.0.0",
+  "oneOf": [
+    {
+      "$ref": "#/$defs/catalog"
+    },
+    {
+      "$ref": "#/$defs/binding"
+    }
+  ]
+}

package/contracts/atelier-boundary-delegations.v1.schema.json

@@ -0,0 +1,161 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://mnstry.ai/schemas/atelier/atelier-boundary-delegations.v1.schema.json",
+  "$comment": "contract revision 1.0.0 (contract-stability epoch)",
+  "title": "atelier-boundary-delegations@v1",
+  "description": "Owner-signed delegations of the local boundary actor check, kept beside the boundary policy. A delegation is authority only when its signature verifies against an owner key the host supplies outside operator-writable files, it is current and not revoked by the host, its policy digest and repository root commits match. It covers only the local boundary check and the pre-commit path; it never changes ownership, audiences, paths, content rules, promotion, push-content approval or publication.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema",
+    "delegations"
+  ],
+  "properties": {
+    "schema": {
+      "const": "atelier-boundary-delegations@v1"
+    },
+    "contractVersion": {
+      "type": "string",
+      "pattern": "^1\\.[0-9]+\\.[0-9]+$"
+    },
+    "delegations": {
+      "type": "array",
+      "maxItems": 64,
+      "items": {
+        "$ref": "#/$defs/delegation"
+      }
+    },
+    "ext": {
+      "type": "object",
+      "description": "Reserved extension container. Producers MAY add namespaced members (recommend vendor-prefixed keys). Consumers MUST ignore members they do not recognize. Contents are not validated at v1 and carry no authority over first-class fields."
+    }
+  },
+  "$defs": {
+    "identifier": {
+      "type": "string",
+      "pattern": "^[a-z0-9][a-z0-9._-]{0,63}$"
+    },
+    "actorId": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$"
+    },
+    "repoName": {
+      "type": "string",
+      "pattern": "^[a-z0-9][a-z0-9._-]*$"
+    },
+    "utc": {
+      "type": "string",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,3})?Z$"
+    },
+    "delegation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "schema",
+        "id",
+        "owner",
+        "operator",
+        "repos",
+        "operations",
+        "notBefore",
+        "expiresAt",
+        "policyDigest",
+        "repoRoots",
+        "signature"
+      ],
+      "properties": {
+        "schema": {
+          "const": "atelier-boundary-delegation@v1"
+        },
+        "id": {
+          "$ref": "#/$defs/identifier"
+        },
+        "owner": {
+          "$ref": "#/$defs/actorId"
+        },
+        "operator": {
+          "$ref": "#/$defs/actorId"
+        },
+        "repos": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 64,
+          "uniqueItems": true,
+          "items": {
+            "$ref": "#/$defs/repoName"
+          }
+        },
+        "operations": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "enum": [
+              "boundary-check",
+              "pre-commit"
+            ]
+          }
+        },
+        "notBefore": {
+          "$ref": "#/$defs/utc"
+        },
+        "expiresAt": {
+          "$ref": "#/$defs/utc"
+        },
+        "signature": {
+          "$ref": "#/$defs/signature"
+        },
+        "ext": {
+          "type": "object",
+          "description": "Reserved extension container. Producers MAY add namespaced members (recommend vendor-prefixed keys). Consumers MUST ignore members they do not recognize. Contents are not validated at v1 and carry no authority over first-class fields."
+        },
+        "policyDigest": {
+          "type": "string",
+          "pattern": "^sha256:[0-9a-f]{64}$",
+          "description": "sha256 of the RFC 8785 form of the whole boundary policy (ext removed at every level) and the managed repository names."
+        },
+        "repoRoots": {
+          "type": "object",
+          "propertyNames": {
+            "$ref": "#/$defs/repoName"
+          },
+          "additionalProperties": {
+            "type": "string",
+            "pattern": "^(?:[0-9a-f]{40}|[0-9a-f]{64})$"
+          },
+          "minProperties": 1,
+          "maxProperties": 64,
+          "description": "Each listed repository's first root commit."
+        }
+      }
+    },
+    "signature": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "algorithm",
+        "keyId",
+        "value"
+      ],
+      "properties": {
+        "algorithm": {
+          "const": "ed25519"
+        },
+        "keyId": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128
+        },
+        "value": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 512
+        },
+        "ext": {
+          "type": "object",
+          "description": "Reserved extension container. Producers MAY add namespaced members (recommend vendor-prefixed keys). Consumers MUST ignore members they do not recognize. Contents are not validated at v1 and carry no authority over first-class fields."
+        }
+      }
+    }
+  }
+}