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

package/docs/knowledge-workspace.md

@@ -0,0 +1,264 @@
+# Knowledge workspaces and guided coauthoring
+
+The experimental knowledge workspace connects five reusable dashboards to the
+same source-bound private drafts used by people and agents. Human planning sets
+the task, assisted drafting works from evidence, and human review determines
+what may enter the canonical plan or become an action.
+
+Start with one consequential question, a permitted source, and a reviewer.
+Expand when a demonstrated task needs more knowledge. Graph size is not the
+success measure.
+
+## Open a workspace
+
+```sh
+atelier init --template knowledge-workspace --target my-workspace
+cd my-workspace
+git init
+atelier knowledge check
+atelier graph
+atelier build
+atelier dev --knowledge
+```
+
+Open `/knowledge` at the printed loopback address. This uses the existing
+foreground sidecar and its manifest, host, origin, and nonce controls. Stop it
+with Ctrl-C; restart the same command to resume saved sessions. `--port=0`
+chooses a free port. It installs no background or operating-system service.
+The template is an invented equipment library. Replace its purpose, roles,
+sources, concepts, relations, and questions before operational use.
+
+An existing enrolled project needs a valid `knowledge-plan.json` beside its
+project configuration. Use the schema and guide in
+[knowledge setup](knowledge-setup.md). Rebuild the projection when its source
+changes. The knowledge panels read the current enrolled graph on request; the
+ordinary projection remains the last explicitly built projection.
+
+The sidecar enables these routes only with `--knowledge`. Its new reads are
+`/api/knowledge/dashboard`, `context`, `sessions`, and `read`; mutations are
+`start`, `event`, and `recover`. The empty same-origin `session` POST obtains
+its nonce. There is no remote collaboration, account, canonical apply, model
+provider, or outbound network path. All people who use this local process have
+the local operator's source access. It is not a multi-user access-control layer.
+
+## Supported interfaces
+
+The workspace is experimental. Two of its outputs are versioned contracts that
+hosts, desktop adapters and agents can bind to:
+
+- the context packet from `atelier knowledge context`
+  (`schema: atelier-knowledge-context@v1`);
+- the evaluation report from `atelier knowledge evaluate`
+  (`schema: atelier-knowledge-evaluation@v1`).
+
+Everything else is experimental and may change without a version bump:
+
+- `atelier knowledge check` and `session list` print unversioned JSON;
+- the dashboard and session records carry `experimental-v1` schemas;
+- the browser surfaces and their `/api/knowledge/*` routes, served by
+  `atelier dev --knowledge` and `atelier server --knowledge`, are experimental;
+- the `knowledgeProject` option of `createAtelierSidecarServer` in
+  `@mnstry/atelier/server` is experimental too, not a supported binding.
+
+This release has no library API for the workspace. The workspace modules
+`src/knowledge/plan.mjs`, `context.mjs`, `workspace.mjs` and `sessions.mjs` are
+not exported, and importing them directly is unsupported.
+`@mnstry/atelier/knowledge` exports these functions, which are separate from the
+workspace:
+
+- `inspectKnowledge`
+- `prepareIntakeContribution` and `prepareKnowledgeImport`
+- `knowledgeGraphProposal`
+- `reconcileKnowledge`
+- `prepareIngestionContribution`, `localKnowledgeContext` and
+  `localKnowledgeGraphProposal`
+
+A workspace library export will be added when a host needs one, reviewed together
+with that host's use of it.
+
+Maintainers check a packed candidate with `npm run knowledge:consumer-proof`, with
+`ATELIER_CANDIDATE_TARBALL` set to the tarball.
+
+- **Install.** The script reads the tarball once, installs exactly those
+  hashed bytes into a clean temporary consumer, and runs the installed CLI with
+  the current Node and an empty temporary home. The proof's own Git steps read no
+  global or system Git configuration. The CLI's Git calls get an empty global
+  configuration but may still read the host's system configuration. The install runs offline, from the locked dependency closure
+  already in the npm cache. With a cold cache it refuses before installing
+  anything. Set `ATELIER_KNOWLEDGE_CONSUMER_BOOTSTRAP=1` to allow one declared
+  registry fetch of that closure first; the receipt records whether it ran. The
+  receipt lists the installed dependency tree (`name@version`) and any problems
+  `npm ls` reports. Every entry must lie within the locked closure.
+- **What it checks:**
+  - context for an answerable question selects its caveat source (no answer is
+    generated or judged);
+  - an unsupported question abstains with no sources, candidates or omissions;
+  - evaluation;
+  - a recorded answer stays an unsaved draft until it is saved; the saved
+    private draft and its receipt read back from a new process;
+  - a retried start returns the same session;
+  - an owner correction: the edited source is reported stale, and earlier
+    sessions report changed sources.
+- **The receipt** is bound to the tarball's SHA-256. Any earlier receipt is
+  removed before the inputs are checked. Refusals before the temporary consumer
+  exists (missing tarball, digest mismatch, cold cache, bootstrap or lockfile
+  failure) exit non-zero and leave no receipt. After that, a step failure or an
+  unexpected stop writes `passed: false`. Known local roots in failure text
+  (the temporary folders, the tarball's folder, this repository and the home
+  folder) are replaced with placeholders; other paths may remain.
+
+A passing receipt shows that these documented CLI paths work for that tarball.
+It does not measure answer quality or cost.
+
+## Five connected views
+
+| Workspace | What is visible | Coauthored result | Next proof |
+| --- | --- | --- | --- |
+| Onboard | Purpose, steward, reviewer, source-use policies, and context budget | Useful work, roles, source boundaries, and success criteria | One permitted source can support a consequential question |
+| Model | Definitions, identity rules, directed relationships, and question coverage | A minimal concept or relationship proposal with examples and counterexamples | Source-backed questions distinguish the intended meanings |
+| Deepen | Unused concepts, unknown tags, missing edges, missing evidence, and changed pins | A source-cited correction, contradiction, or unmodeled finding | A reviewer checks exact passages, qualifications, and proposed changes |
+| Apply | Complete bounded sources, provenance, qualifications, and declared relationships | An answer or abstention, uncertainties, proposed action, and validation needs | The owner reviews the answer and decides the next real action |
+| Learn | Equal-budget retrieval comparison and explicitly unmeasured outcomes | Observed outcome, quality, assistance, correction effort, time, and usage notes | Useful work on unseen questions compared with direct source search |
+
+The dashboard recommends a next step from current structural diagnostics. It
+never automatically completes an onboarding stage, promotes an assertion, or
+calls an ontology useful because its checks pass. Both task-specific judgment
+and actual adopter acceptance remain visible work.
+
+The direct-search comparison uses metadata lexical matching. Graph context adds
+one hop of declared relationships. It is not a semantic answer evaluator or a
+full-text-search benchmark. The graph may spend *more* context on necessary
+qualifications; improvement means better work at appropriate total cost.
+
+## Coauthoring and recovery
+
+Select a question and a flow, enter your locally asserted name or role, and
+start. Each session retains its prompts, selected evidence, plan digest, and
+workspace snapshot. The prompts cover generic knowledge-work practices; the
+consumer owns its domain vocabulary and source decisions.
+
+1. Write an answer. **Record my answer** retains its exact wording in session
+   history. It is still a draft.
+2. **Save private draft** persists the field and reads back the matching receipt.
+   **Continue** then advances. A machine `propose` event opens a confirmation
+   step: confirm the revised wording or keep the original before saving.
+3. Pause or close after a confirmed save. The session list resumes history from
+   the local ledger. A `saving` state offers reconciliation; a failed write
+   exposes the existing store's one explicit retry. Exhausted retries need
+   operator inspection; the UI does not remove another writer's lock.
+4. A failed request retains the exact request ID for retry and keeps the text
+   in the tab. Editing pauses so the retry cannot silently change its wording.
+   Restore `atelier dev --knowledge`, retry, or reload the session to inspect
+   what was actually recorded. Retry controls survive reload and export.
+   **End retry and inspect history** stops the tab's retry attempt and preserves
+   its request in exported snapshots; it does not cancel or delete server
+   history. If recorded wording differs from the text in your tab, the current
+   recorded wording and retained answers appear beside it before another intent.
+   A failed history inspection remains visible. Reload does not silently erase
+   unsaved text. Discarding tab text is explicit.
+5. Export a private snapshot for owner review. It includes saved wording,
+   receipts, bound source evidence, unsaved text, and a pending request when
+   present. Review its audience before sharing. Browser download behavior is
+   browser-owned; export does not transmit it to a collaborator.
+
+Unsaved tab text is not durable across tab closure or browser failure. The UI
+warns on navigation while dirty; recording an answer or exporting a snapshot is
+the recovery path. No browser local storage accumulates source material.
+
+The source plan and records are never edited by this surface. A source owner
+uses the exported proposal in its own ordinary edit/review workflow, reviews
+an exact diff, applies the admitted change, reruns `knowledge check` and
+`knowledge evaluate`, and starts a session bound to the resulting sources.
+Never update evidence pins merely to make a failing case pass. A changed
+source or project makes old sessions historical; the original prompts,
+evidence, and wording remain readable, including when the current plan fails
+validation. Correction creates a new session; saved-answer undo is not offered.
+
+Descriptors are immutable, digest-checked files under ignored
+`.atelier-local/knowledge/sessions/`. Accepted intents and draft receipts use the
+existing coauthor ledger under `.atelier-local/coauthor/`. These are private
+proposal artifacts, not a second canonical ontology database. Sessions require
+a Git workspace with ignored, untracked local state. Descriptor and draft files
+use owner-only modes on POSIX hosts. On Windows, access follows the host's
+filesystem permissions; this surface does not install an access-control list.
+Same-account filesystem control is not an authentication boundary.
+An interrupted start is resumable only when its bound sources still match and
+the retained start protocol, ledger, completion marker, and value files support
+that interpretation. A completed start publishes an immutable marker before any
+guided answer. Missing history with a completion marker or retained values is
+never recreated as an empty session. A missing ledger or an incomplete legacy
+descriptor requires inspection. A damaged descriptor does not hide other
+sessions. Preserve damaged files for inspection; the surface never deletes them
+to make history pass.
+
+Each operation checks the current workspace and reports whether its bound
+sources still match. External source editors do not share an atomic transaction
+with the draft ledger: a change during an operation may leave a retained draft
+whose response reports changed sources. These drafts never authorize canonical
+writes or effects. Review and rebind before using them after source changes.
+
+## People and agents share the same flow
+
+`atelier knowledge dashboard` prints the five views as JSON. Obtain its current
+`snapshot` and an actual question ID. Session commands read one JSON object
+from stdin, at most 1 MiB; `list` needs no input:
+
+```sh
+atelier knowledge session list
+atelier knowledge session start < start-request.json
+atelier knowledge session read < session-request.json
+atelier knowledge session event < event-request.json
+atelier knowledge session recover < session-request.json
+```
+
+Start takes `requestId` (a fresh UUID, retained for exact retry), `flow`
+(`onboard`, `model`, `deepen`, `apply`, or `learn`), `questionId`, `snapshot`,
+and `author`. Read/recover take only `sessionId`. Event takes `sessionId` and
+an `event` with a unique `id`, current `expectedRevision`, and reducer `type`.
+An `answer` or `propose` also carries `text`. All other event behavior follows
+[coauthor sessions](coauthor-session.md). Clients cannot submit receipts or
+failure events. Stale versions never silently overwrite an intervening answer.
+
+Ask one useful question at a time. Record the person's exact answer. For
+agent-written revisions, send `propose`, show original and proposed wording,
+and wait for explicit confirmation before `confirm`. The API records intents;
+it cannot authenticate that a human supplied one. Do not infer confirmation,
+source-owner acceptance, or action authority from a saved draft.
+UUID letters, including exact session IDs, are normalized to lowercase. Reusing
+a start request ID with a different author, flow, question, or snapshot is refused. UTF-8 BOM plans are
+supported: the workspace binds raw plan bytes, while the coauthor receipt binds
+decoded text using the same definition as its source reader.
+
+Keep requests in ignored local files rather than interpolating authored text
+into shell commands. The CLI supports `--project` and `--plan` for an explicit
+consumer location; browser sessions use that project's `knowledge-plan.json`.
+A coauthor plan must be a visible, unredirected file inside its workspace.
+The workspace directory itself may be reached through an alias or symbolic link;
+plan segments inside it must not be symbolic links.
+Resumed sessions check their own recorded plan, including sessions started with
+`--plan`. Unavailable source checks are reported separately from changed sources.
+
+## Evaluation and scale
+
+Context contains complete source text, not silently shortened qualifications.
+The exact byte budget covers the context JSON, while estimated tokens are only
+`ceil(bytes / 4)`. Source selection and dashboard retrieval make zero provider
+calls. Workspace scans and evaluation across every planned question still have
+local computation cost; context limits are not a whole-corpus scan deadline.
+
+Descriptors are bounded to 1 MiB, session listings to the 200 newest local
+descriptor files, and coauthor history to its existing ledger ceilings. Listings
+include a total and truncation flag; invalid or unfinished entries are individual
+unavailable rows. Use **Open an exact session ID** or the CLI to inspect an older
+session beyond the listing limit; use CLI `recover` for an older incomplete start.
+Each listing verifies one shared ledger snapshot and replays the selected session
+chains. It does not cache state across requests. No history is silently deleted
+or compacted. This first reference is for bounded local workspaces, with
+text-based observations. It provides no numeric outcome aggregation, automatic source ingestion, semantic
+inference, collaborative presence, or canonical editing UI.
+
+Qualification should include an unfamiliar person and agent completing an
+unseen useful question: time to first supported answer, correct abstention,
+source support, confusion or assistance, corrections, actual token usage,
+provider cost, and the observed outcome. Automated browser proof demonstrates
+software behavior, not those human results.

package/docs/learning-harnesses.md

@@ -0,0 +1,238 @@
+# Knowledge development and the learning cycle
+
+Status: implemented locally for the next release. Published alpha.7 does not
+contain these commands. Use `node bin/atelier.mjs harness help` in this source
+checkout, or `atelier harness help` from a package built from this candidate.
+
+Knowledge Harness helps people establish, develop, use and revise what they know.
+Ingestion is one capability within that larger purpose. Sources can also originate
+in authorship, conversation, observation, research or implementation experience.
+The graph is one maintained representation; documents, source collections,
+datasets and decisions remain important in their own right.
+
+People define purpose and acceptance criteria. Agents prepare admitted work.
+Designated owners validate consequential interpretations and delivery. The local
+records cannot authenticate those people or grant permissions on their behalf.
+
+## The capability family
+
+| Capability | Responsibility |
+| --- | --- |
+| Discovery Harness | Frame questions, alternatives and uncertainties |
+| Research Harness | Investigate and return traceable evidence |
+| Knowledge Harness | Develop, evaluate, curate and activate knowledge |
+| Build Harness | Turn an objective into a verified deliverable |
+| Fabric or another coordinator | Coordinate owners, outcomes, dependencies and delivery gates |
+| Skill Steward | Govern capability versions, adoption and improvement |
+
+The shared API is `@mnstry/atelier/harnesses`; domain APIs are
+`@mnstry/atelier/knowledge` and `@mnstry/atelier/build`. The existing
+`@mnstry/atelier/harness` context API and `atelier build` projection alias are
+unchanged. Build workflow commands begin `atelier harness build`.
+
+The shared layer provides immutable references, bounded history storage,
+explicit handoffs, current-input reconciliation and version-bound feedback.
+Knowledge and build retain separate closed schemas and state semantics. Existing
+inquiry records are read through a bridge, never rewritten into a universal record.
+
+## Establish a useful knowledge domain
+
+An establishment record names its repository identity, owner, purpose, scope,
+audience, source policy, acceptance policy, identity rules, vocabulary and the
+questions it must support. Each question has a concrete acceptance criterion.
+Types and relations have definitions; each relation maps explicitly to an
+existing graph predicate. Start with a small representative collection and
+check the question-to-evidence trace before scaling acquisition.
+
+Contribution categories are source, observation, concept, claim, model,
+interpretation and decision rationale. Their domain-specific term comes from the
+declared vocabulary. These categories describe a contribution's role; they are
+not grades of truth. Ontology changes use a new `domain-revision` with migration
+rationale and flag old dependants for reconsideration. This conservative first
+implementation requires reevaluation under the new domain; it does not silently
+remap old types or merge identities.
+
+## Acquire, create, interpret and evaluate
+
+`atelier harness example` prints an invented complete learning cycle. It includes
+simulated owner decisions, CI and delivery reports; none is real execution proof.
+The per-profile ledger examples show every supported record shape.
+
+Preserve existing files with `@mnstry/atelier/intake`. Its `ingest`, `beginAttempt`,
+`completeAttempt` and `readCompletion` operations keep source bytes, extractor
+identity/configuration and output receipts separate. The new
+`prepareIntakeContribution` verifies existing completion and output bytes and
+prepares a source contribution. It invokes no extractor and accepts no meaning.
+
+```js
+import { createIntakeStore, intakeDigest } from '@mnstry/atelier/intake'
+import { prepareIntakeContribution } from '@mnstry/atelier/knowledge'
+import { appendHarness, EMPTY_HARNESS_HEAD } from '@mnstry/atelier/harnesses'
+
+// The caller chooses a Git root with ignored .atelier-local/ and authors domain.
+appendHarness({ workspaceRoot, profile: 'knowledge', record: domain,
+  confirm: EMPTY_HARNESS_HEAD })
+const intake = createIntakeStore({ workspaceRoot })
+const source = intake.ingest({ ref: sourcePath, expectedDigest: intakeDigest(sourceBytes) })
+intake.beginAttempt({ attemptId, blobId: source.blobId,
+  extractorId, extractorVersion, configurationDigest })
+// The separately authorized processor supplies output; the harness does not run it.
+intake.completeAttempt({ attemptId, output, expectedOutputDigest: intakeDigest(output) })
+const proposed = prepareIntakeContribution({ workspaceRoot, records: [domain],
+  attemptId, title: 'Source material', term: declaredType })
+// Author a contribution record around proposed.data, then append with the current head.
+```
+
+Authored contributions retain a rationale for their origin. Captured text binds
+its digest and source locator. Extraction binds the original blob, attempt,
+configuration and output. An exchange retains its complete handoff. Derived
+contributions use exact quoted passages from earlier contributions; scope and
+audience widening refuse. Missing passages, versions, references and vocabulary
+are failures. Source text cannot expand execution authority.
+
+A private container can hold public contributions. When an export includes domain
+context, its audience is at least as restrictive as both the domain and the
+contribution. Sensitive material requires a sensitive receiver. Team, staff and
+operator are separate audiences; combining them requires private containment.
+
+Evaluation records preserve judgment (`supported`, `contested`, `uncertain`,
+`unsupported`), rationale, applicability scope and limitations. Reviews separately
+record accepted, deferred or rejected dispositions. Accepted contributions require
+an evaluation and accepted evidence dependencies. A curated uncertain claim
+remains uncertain. This layer does not calculate an undifferentiated confidence
+score. Bayesian assumptions and computed results remain in the inquiry assessment
+that the research handoff references and preserves.
+
+A new evaluation reopens the contribution's prior acceptance and its downstream
+uses. A replacement review must account for every current evaluation, including
+contradictory judgments. Reacceptance preserves the earlier review and does not
+silently restore old handoffs or activations.
+
+## Connect, activate and revise
+
+Propose identity matches or conceptual links as relation records. Acceptance
+requires current accepted endpoints. No entity merge is automatic. An activation
+names reviewed contributions/relations, purpose, destination and domain questions.
+`knowledgeGraphProposal` emits draft Markdown and unpromoted `atelier-claim@v1`
+edges, with selected evidence dependencies, reviews and limitations retained.
+Accepted relations also receive draft evidence documents containing their rationale,
+review and domain definition; the corresponding edge pins that relation and review.
+The receiver reviews/adopts the exact files through its existing authoring process,
+rebuilds the graph and verifies the meaningful source trace.
+
+Withdraw or revise a contribution without deleting the original. Local descendants
+become reconsideration items. Downstream repositories use current source snapshots
+to discover changed inputs through `reconcileKnowledge` or `buildReadiness`.
+Previously admitted graph files are not rewritten or removed automatically.
+Revisit their source decisions and prepare a new authorized change.
+
+## Handoffs and freshness
+
+`createHarnessHandoff` binds a source repository label, profile, run, history digest,
+subject reference, audience, exact payload, destination and purpose. Knowledge
+exports accepted contributions; inquiry exports accepted current decisions; build
+exports a current accepted candidate with resolved dependencies. An external
+destination remains subject to the host's disclosure and execution rules.
+
+`source.repositoryBinding` is `establishment-record` for knowledge/build, whose
+establishment records declare the repository. Existing inquiry campaigns have no
+repository field, so their handoffs explicitly use `caller-declared`; verification
+reports the same distinction. Neither value authenticates a repository or owner.
+
+`verifyHarnessHandoff` verifies a supplied producer history against those pins.
+The current history must contain the complete exact issued history as a prefix;
+unrelated appends are allowed only while the subject and accepted payload remain
+unchanged and current. A source rewrite, relevant correction, ontology migration,
+gate replacement or candidate replacement invalidates the relevant handoff.
+
+Snapshots are explicit `{repository, profile, records}` objects. Missing or
+ambiguous sources cannot clear freshness. Reconciliation can traverse knowledge,
+inquiry and build dependencies, bounded to 12 dependency hops, 64 supplied snapshots
+and 256 verification calls per operation. Inspected histories and successful
+verification results are cached within that operation. A verification budget
+failure is a named reconsideration reason or readiness blocker, never freshness.
+`verifyHarnessHandoff`, `reconcileKnowledge` and `buildReadiness` report
+`dependencyWork`; their optional `verificationLimit` can lower the ceiling.
+Freshness is relative to the supplied snapshot, not a live remote observation.
+The toolkit cannot detect a withheld update or authenticate the source owner.
+The receiver must obtain snapshots through its existing trusted process.
+
+`prepareKnowledgeImport` verifies a handoff and prepares a contribution with
+semantic acceptance pending. Its full context stays in the contribution. Graph
+activation and outgoing handoffs recheck relevant imported dependencies. An
+unavailable proprietary service does not prevent reading or exporting saved
+records, although current remote-input freshness may remain unresolved.
+
+## Build discipline derived from Fabric
+
+A build objective declares owner, scope, acceptance criteria, required gates,
+artifact dependencies, admitted effects, attempt budget and stopping rule.
+A candidate pins repository identity, commit, tree, artifact digest and reported
+writer custody. `prepareGitCandidate` reads a selected local Git root, requires
+clean source, verifies the artifact twice and prepares its exact candidate data.
+It executes no build or test and does not authenticate the writer declaration.
+
+Record attempt intent before an external command/adapter invocation. Progress can
+be running, uncertain, completed, failed or cancelled. Unsettled or completed
+operations refuse replay; a failed/cancelled attempt can be retried within the
+declared budget. An uncertain attempt requires reconciliation against that same
+attempt. The harness neither dispatches nor cancels the actual process, and a
+caller-reported cancellation cannot establish physical process cleanup.
+
+Gate reports bind the exact candidate and a declared gate with evidence digest,
+locator and verifier identity. Required source, review, CI, runtime, integration
+and delivery gates stay distinct. Transport completion never creates a passed
+gate. Where a gate names an attempt, a pass requires completion on that candidate.
+External CI/review adapters must validate their native receipts before recording
+reports; this local core cannot authenticate arbitrary supplied evidence digests.
+
+An accepted decision requires current passed required gates and settled attempts.
+`buildReadiness` also rechecks explicit dependency snapshots. Its result is
+`readyReported`, with `authenticatedAcceptance:false` and
+`executionAuthorized:false`. A delivery report is a separate record. Replacing
+a candidate, gate or decision leaves older proof visible and marks dependants.
+
+`buildCoordinationProposal` exposes owner, outcome, dependencies, candidate, gates
+and blockers for Fabric or another coordinator. It reads no private Fabric state,
+creates no tasks, sends no messages, and does not claim coordinator acceptance.
+Concrete CI connectors, authenticated receipt verification, distributed worker
+leases and operated scheduling remain adapters, outside this local implementation.
+
+## Storage, skills and boundaries
+
+`atelier harness knowledge|build append --record FILE --confirm DIGEST` appends
+to `.atelier-local/harnesses/PROFILE/RUN/ledger.json`. Use `status` for the head
+and `export` for the complete ledger, including private content. `inspect` checks
+history and references; `validate` checks one record's shape only.
+
+Writes require a Git root, ignored untracked private state, a qualified POSIX
+filesystem, the cooperating-writer lock and the current head. Windows ledger
+writes refuse before creating state; read-only inspection and exchange of
+existing histories remain available. Atomic single-file replacement preserves
+a complete previous or next history after interruption.
+Hard process termination can leave the shared lock for operator reconciliation;
+no automatic lock recovery or multi-repository transaction is added here. Hashes
+do not defend against a writer who can replace the whole history. Audience labels
+are descriptive; repository access remains the actual read boundary.
+
+Limits are 256 records and 8 MiB serialized per ledger, 64 items in bounded record
+arrays, 262,144 characters per contribution, and 1,048,576 characters per handoff
+payload. Existing intake allows larger outputs; a contribution that exceeds these
+bounds needs an explicit continuation plan. No silent compaction occurs.
+
+`atelier-knowledge-harness` and `atelier-build-harness` ship as identical Codex and
+Claude skills and independently sealed reference packages. Adopt through the
+existing capability Steward with observed `atelier-harness-v1` availability and
+explicit local effects. Preserve third-party skills and customizations. The
+packages declare their behavioral evaluation unknown; placement is not host use.
+
+`prepareHarnessFeedback` binds feedback to the skill binding in effect at the
+subject record. The receiver's `capability observe` checks actual current binding.
+Context/provider causes remain in the wrapper and map to unknown in the older
+Steward event vocabulary. Feedback never rewrites, publishes or upgrades a skill.
+
+The contracts, skills, storage, basic calculations, graph proposals and offline
+exchange remain open. Optional operated services can supply specialized extraction,
+managed execution, collaboration, connectors or advanced inference. Credentials,
+cost limits, source access, authenticated receipts and operational permissions
+remain host-owned; local manifests confer none of them.