@awebai/oats 0.29.3 → 0.30.0

package/docs/design/2026-09-13-knowledge-implementation.md

@@ -1,127 +0,0 @@
-# Knowledge implementation plan
-
-Status: implementation authorized by the human on 2026-09-13, including main
-pushes and framework/OKF releases. Execute bounded batches with adversarial
-review after approximately every two new commits, including fix commits.
-The [location contract](2026-09-13-knowledge-location-contract.md) and its
-[reference-theory boundary](../../agents/oats-expert/soul/knowledge/decisions/provider-neutral-knowledge-and-harvest.md)
-remain the architectural context. This document resolves implementation choices
-under that authorization; it does not impose OKF policy on other integrations.
-
-## First delivery
-
-- Canonical reference theory and injection/skill authoring guidance.
-- An optional, installed-artifact-usable `knowledge-theory-expert`.
-- Default OKF with working Git and ordinary directory custody. Omnigraph is an
-  authoring example, not a dependency or a required first implementation.
-- Explicit external base/node ownership and initial reads; independent,
-  automatically requested per-source harvest; preserved evidence before
-  retirement; Git deliveries always PRs; no Git dependency for directory mode.
-- Explicit migration with preservation and cutover, never silently discarding
-  an old soul bundle or treating a missing base as empty knowledge.
-
-## Follow-on phase — after this implementation is complete
-
-The human additionally requested a dedicated OATS knowledge Git repository and
-an expertise-oriented soul reorganization. The [accepted follow-on plan](../../agents/oats-expert/soul/knowledge/decisions/expert-souls-and-knowledge-rebuild.md)
-records the intended overall/kernel/Desktop/market/onboarding roles, the ban on
-engineer-role souls, strict audit of existing knowledge and pending notes,
-rejection of obsolete OAS material and code duplication, and safe cutover.
-This is a curated rebuild, not a bulk migration. The human subsequently allowed
-the separate repository shell to be provisioned under temporary personal
-ownership pending organization transfer. Do not migrate the corpus, rename
-live souls, or remove source knowledge before implementation verification.
-
-## Implementation choices
-
-1. **Capability-owned configuration.** Initially accept one absolute
-   `bindings-file` setting, avoiding ambiguous relative-setting provenance.
-   Paths inside it resolve from that file's directory. The document contains
-   version, durable state directory, named Git/directory bases and cadence.
-2. **Capability-owned soul declarations.** Use `soul/okf.json` rather than
-   teaching the kernel an OKF-specific nested YAML schema. It declares stable
-   owner identity, `owns` and `reads`. Accepted bases carry matching identity
-   and node ownership metadata. No knowledge content resides in the soul.
-3. **One link namespace per OKF base.** Nodes are owned, nonoverlapping
-   subdirectories. Reads are selective, index-first and non-mutating. Every
-   configured base is discoverable; `reads` is not an ACL.
-4. **Durable per-source input.** Keep copied evidence, note hashes, bounded
-   record content, frozen destinations and processing receipts outside source
-   homes/worktrees and accepted bases. Separate capture, delivered judgment,
-   and accepted/reader-visible state. No automatic evidence garbage collection
-   in the first implementation.
-5. **Directory custody is real.** Independent workers must not require a fake
-   Git repository. Add only the generic non-Git execution support actually
-   needed; preserve work-mode, trust and retirement safety.
-6. **Delivery.** Git workers edit their own accepted-baseline checkout and
-   produce a verified PR receipt. Directory workers stage changes and publish
-   with baseline checks, coordination and crash-recoverable receipts. Never
-   downgrade Git failures into direct writes. Initial directory coordination
-   is single-host/cooperative, not a distributed-lock claim.
-7. **Automation.** Reuse generic scheduler command jobs for per-source work;
-   retain pending work after its source is gone. Source registration is
-   automatic; host timer installation is an explicit setup action. Retire
-   captures/enqueues, not synchronously waits for model judgment or GitHub.
-8. **Optional authoring distribution in this repository.** Ship a dedicated
-   `oats.knowledge-theory` package under `oats-package/`, using an enumerated
-   self-contained capability subtree. This keeps release scope to the two
-   authorized repositories and avoids pretending an edit to the bundled
-   `oats.authoring` changes its separately released catalog package. The new
-   package supplies the expert and authoring skill/reference closure, has no
-   knowledge-layer binding or mandatory injection, and does not depend on OKF.
-   **Release channel: Git, not npm.** The npm kernel ships public docs and the
-   CLI but excludes `oats-package/` entirely: npm omits symlinks and therefore
-   cannot carry the canonical source `CLAUDE.md -> AGENTS.md`. Do not ship a
-   partial copy, synthesize source aliases on acquisition, weaken the source
-   rule, or change generic installed-artifact integrity semantics. Acquire with
-   `oats install git:github.com/awebai/oats@v0.23.0`, then explicitly target
-   `oats.knowledge-theory` with `oats use ... --soul <author-soul>`. The default
-   Git package path selects the self-contained subtree and exact-locks its
-   commit. A catalog pin can follow only after that immutable tag exists.
-9. **Minimal generic fixes.** Hooks must receive the running kernel's absolute
-   CLI path; scheduled dispatch must not inherit another instance's identity;
-   final record capture must distinguish completion from a skipped/held pass.
-   Do not add a knowledge registry or compulsory reference doctrine to core.
-
-## Source and delivery discipline
-
-The standalone OKF repository's enumerated runtime subtree is
-`oats-package/capabilities/oats-okf/`. Its published `v1.6.1` is the starting
-baseline; stale unenumerated duplicates are not implementation targets. The
-framework's bundled copy is synchronized only at integration, with parity tests.
-Existing release tags are immutable.
-
-Implementation helpers edit explicitly assigned files and do not commit,
-push, change branches or release. The maintainer integrates small commits and
-runs exact-range adversarial review every two commits, closing blocking
-findings before dependent work advances. Reviews cover product boundary,
-correctness, security and release/merge readiness, not just test results.
-
-## Verification and release gates
-
-- Standalone tests exercise its actual exported payload, not stale root copies.
-- Framework tests include generic non-Git execution, hook/dispatch identity,
-  capture-completeness and alternative-provider isolation.
-- Real temporary Git repositories test embedded/dedicated Git knowledge; real
-  directories outside Git test directory custody, concurrent updates and crash
-  recovery. Failed/uncertain publication stays recoverable.
-- Source deletion and name reuse cannot lose or misattribute pending evidence.
-- Installed-artifact acquire/lock/trust/activate/scaffold/retire probes validate
-  the complete expert curriculum and OKF's real compatibility floor. The kernel
-  tarball must exclude the optional Git package while retaining public docs.
-  Its installed CLI acquires the exact complete theory Git fixture via direct
-  and catalog sources, verifies the tracked alias survives unchanged, removes
-  the fixture checkout, and tests local reference closure and alternative-theory
-  isolation. Generated instance aliases remain ordinary kernel behavior.
-- A fresh selected-runtime instance must answer from delivered knowledge without
-  the source home/transcript. Scaffolding alone is not this learning gate.
-- Run strict knowledge validation, all affected tests, full framework gates,
-  tarball smoke, and a final cross-repository adversarial review before release.
-
-Version targets are provisional: framework 0.23.0 for generic support, OKF 2.0.0
-for breaking external-knowledge custody, optional theory package 1.0.0, then a
-framework patch for catalog/payload updates if required. The prerequisite
-0.23.0 keeps bundled OKF and its catalog pin at 1.6.1; standalone OKF 2.0.0
-follows rather than creating a prerequisite release cycle. Publish dependency
-sources before advancing catalog pins; follow actual current release scripts,
-not historical instructions contradicted by the implemented release lane.

package/docs/design/2026-09-13-knowledge-location-contract.md

@@ -1,340 +0,0 @@
-# Knowledge contracts, integrations, and storage
-
-**Status:** architecture proposal for discussion, 2026-09-13. No implementation
-or configuration schema is approved by this document. Accepted direction is
-recorded in [external knowledge custody](../../agents/oats-expert/soul/knowledge/decisions/external-knowledge-custody.md)
-and [provider-neutral knowledge and harvest](../../agents/oats-expert/soul/knowledge/decisions/provider-neutral-knowledge-and-harvest.md).
-This proposal refines the [knowledge and memory direction](2026-09-13-knowledge-and-memory-direction.md).
-
-## 1. Accepted starting points
-
-**Scope:** OATS publishes an opinionated reference knowledge theory; default
-OKF follows it, but other knowledge capabilities may choose different models.
-The location/harvest design below is for this default-theory workstream and
-capabilities that choose to adopt it, not extra kernel requirements.
-
-- All knowledge leaves the soul, including general expertise.
-- Working instances read knowledge and capture memory; they do not promote
-  into the base. For now this is injection guidance, not an OS sandbox.
-- Harvesting is independent of the source instance's execution/work context.
-- Git-committed knowledge updates are PRs.
-- Access rests on users' existing accounts; for GitHub repositories, their
-  GitHub permissions apply. Assume all workspace/team agents can access the
-  configured bases. No new public/private classification or per-agent ACLs.
-- The first working version must cover Git-backed OKF AND a non-Git knowledge
-  store. Non-Git support is not a later optional extension.
-- The reference knowledge/memory theory is independent of concrete storage
-  tools. An integration using a graph store and its CLI can adopt that theory,
-  or choose a different approach; it owns the resulting runtime behavior.
-- OATS supplies canonical authoring docs for knowledge injections and skills,
-  and a `knowledge-theory-expert` agent to help create knowledge capabilities.
-  The expert and full authoring material are planned deliverables, not yet built.
-- Every capability provides its own complete runtime instructions, skills,
-  memory conventions, harvester and related machinery. The kernel does not
-  automatically inject the reference doctrine into every knowledge capability.
-
-The mechanisms below are proposed. In particular, which non-Git implementation
-ships first is not yet settled: directory-backed OKF is the simplest candidate;
-Omnigraph is a concrete alternative to investigate, not an already verified
-integration or an agreed initial dependency.
-
-## 2. Separate the model, the integration, and custody
-
-### OATS reference knowledge/memory model — the recommended approach
-
-- **Instance memory:** task-local state, observations and captured evidence.
-- **Durable knowledge:** expertise that survives an instance, with explicit
-  ownership, provenance, decisions and supersession.
-- **Capture:** preserve observations while doing the work; do not make the
-  working instance hold the promotion bar.
-- **Harvest:** judge candidates against the common doctrine; promote, merge,
-  supersede or drop; preserve exclusions and one authoritative home per claim.
-- **Consultation:** discover relevant prior knowledge before re-deriving it,
-  using progressive disclosure rather than bulk loading.
-
-These meanings do not require Markdown, YAML frontmatter, `index.md`, local
-files, a Git branch, or a particular command. The promotion bar, expertise
-rather than code-description doctrine, and capture/judgment separation remain
-consistent when an author chooses to implement this theory with another tool.
-They are not mandatory policy for a capability that chooses a different model.
-
-### Canonical authoring material and knowledge-theory-expert
-
-OATS maintains the theory in its repository and supplies canonical documentation
-for turning it into working-agent injections, skills and harvester instructions.
-These references explain the concepts, their rationale, expected behaviors and
-examples. An author can point a coding agent at them without needing a special
-runtime dependency.
-
-OATS should also provide `knowledge-theory-expert`. Its job is to:
-
-- explain the reference model and the reasons for its distinctions;
-- help map it to a chosen tool's actual read/write and storage behavior;
-- help author a complete capability, including injections, skills and harvesting;
-- identify gaps or deliberate departures and suggest relevant behavioral tests.
-
-It assists authors; it does not run every harvest, police every capability,
-serve as a required approval gate, or replace the canonical docs. Its package,
-curriculum and instructions are still to design. No agent has been scaffolded
-or spawned as part of this scoping discussion.
-
-### Knowledge capability — a complete runtime implementation
-
-Each capability supplies the complete behavior selected by the deployment:
-its skills, injections, instance memory and capture protocol, native reader
-and writer tools, harvester and judgment instructions where applicable,
-lifecycle contributions, validation and delivery. It is not only an adapter
-under a mandatory OATS-supplied judge.
-
-For example:
-
-- Default OKF authors use the reference theory and ship concrete OKF injection,
-  craft/harvest skills, harvester, hooks and Git/non-Git delivery behavior.
-- An Omnigraph capability author may use the same docs/expert to create the
-  equivalent package around the native CLI and data model.
-- An author choosing a different memory or learning model provides and
-  documents that capability's own runtime instructions instead.
-
-Canonical theory stays in one maintained place, but adopting it does not
-require a mandatory shared runtime injection or harvester skill. Explicit
-resource reuse through supported packaging is fine; mutable documentation is
-not fetched into agents as a hidden policy update. Capability releases own
-changes to the runtime material they supply.
-
-The kernel keeps generic capability/layer/configuration/lifecycle/operation
-and trust contracts. It neither chooses the theory nor implements a universal
-harvester. Existing framework/work-mode rules still apply to every capability.
-
-### Custody — how a write becomes accepted knowledge
-
-Format and delivery are separate choices. OKF does not imply Git:
-
-| Implementation | Read path | Write/delivery path |
-|---|---|---|
-| Git-backed OKF | Accepted revision of an OKF bundle | Independent checkout, validation, PR; accepted after merge |
-| Directory-backed OKF | Configured OKF directory | Coordinated, validated update with an observable durable result; no Git or PR |
-| CLI-backed graph store | Provider-native discovery/query through its CLI | Provider-native writes and confirmation; no invented Git semantics |
-
-A dedicated knowledge repository can be Git-backed; moving out of the code
-repo does not make it non-Git. A non-Git store must work without `.git`, GitHub,
-a branch, a remote, or a PR receipt.
-
-## 3. Base, node, binding
-
-Sections 3–7 describe the proposed default location/harvest design and offer a
-pattern for authors adopting the reference theory. These nouns and shapes are
-not mandatory schema for every knowledge capability.
-
-### Base
-
-A named body of durable knowledge with a canonical provider-resolved location.
-It is not intrinsically an OKF bundle or a repository.
-
-An OKF base maps to a bundle root. A different provider can map a base to its
-native database/space/collection identifier. Only that provider interprets
-its locator, storage structure, validation and consistency behavior.
-
-General expertise, project decisions and team knowledge all live in bases;
-none live inside souls. A project or workspace may consult several bases.
-The invariant is **one authoritative home per concept**, not one required
-physical storage root for everything relevant to a project.
-
-### Node
-
-A logically soul-owned portion of a base, with exactly one owning soul. A soul
-can own nodes in several bases. Ownership is responsibility and harvest
-routing, not an access-control grant. A provider must make the boundary
-addressable; an OKF directory is one representation, not the universal one.
-
-`project/oats-desktop-expert` and `team/oats-desktop-expert` are distinct node
-references. Matching leaf names never merge them. Owner identity must also
-distinguish same-named souls in different repositories; its exact syntax is open.
-
-### Binding
-
-Workspace/project configuration maps logical references to a selected
-integration's concrete locations. A soul declares what it owns and consults,
-without embedding knowledge, physical paths, remote URLs or credentials.
-
-Illustrative soul declarations, not an approved schema:
-
-```yaml
-# oats-desktop-expert/soul.yaml
-knowledge:
-  owns: [project/oats-desktop-expert]
-  reads: [project/oats-expert]
-```
-
-Here `oats-desktop-expert` consults project direction maintained by `oats-expert`
-and accumulates its own durable Desktop expertise. Binding `project` to an
-embedded OKF bundle, a separate OKF repository, or a non-Git store does not
-change the meaning of those declarations.
-
-Aliases are contextual, not global identities. Resolve them before a read or
-harvest; persisted jobs retain the resolved destination so later configuration
-changes cannot redirect pending work. Changing storage providers is an explicit
-migration, not an alias edit that silently converts or copies knowledge.
-
-## 4. Reference-model implementation contract versus concrete location
-
-Do not make a tool pretend to have files or Git metadata. The following is a
-checklist for our default implementation and other capabilities adopting this
-model. It is not a new universal knowledge-provider API, mandatory theoretical
-conformance test, or kernel requirement.
-
-| Concern | Provider-neutral meaning |
-|---|---|
-| Resolve | Map a logical base/node to an unambiguous provider-owned destination and owner |
-| Discover/consult | Give instances a useful entry point and tools to retrieve relevant accepted knowledge |
-| Prepare harvest | Preserve bounded source evidence and resolved destinations independently of the source home |
-| Apply judgment | Let the harvester maintain knowledge using the provider's native authoring tools |
-| Validate | Check the proposed update against the provider's representation and shared semantic requirements |
-| Deliver | Report a durable proposal, an applied update, a no-change result, or a failure; distinguish these |
-| Refresh/inspect | Explain what readers can see, freshness limitations and pending work without guessing from activity |
-
-The resolved descriptor needs a logical reference, provider identity, opaque
-provider locator, node/owner identity, reader/writer instructions or operation
-references, delivery semantics, and binding provenance. A version or receipt
-is provider-native; a Git commit ID is not a required field for every store.
-
-### OKF location examples
-
-| Placement/custody | Canonical location | Bundle root | Read baseline |
-|---|---|---|---|
-| Embedded Git | `https://github.com/example/project.git` | `knowledge/` | Configured accepted branch |
-| Dedicated Git | `https://github.com/example/project-knowledge.git` | `.` | Configured accepted branch |
-| Non-Git directory | Explicit workspace-relative directory, e.g. `./team-knowledge` | That directory | Provider-confirmed current contents |
-
-Git locators include repository, contained root, accepted ref and PR target/head
-route. Directory locators include a resolved path and direct-update custody.
-A future CLI-backed locator uses the actual identifiers supported by that
-provider; do not invent Omnigraph fields or command flags before investigation.
-
-Configuration belongs to the selected knowledge capability's settings and
-existing targeting, not a new mandatory kernel registry. Multiple bases do not
-require multiple active knowledge layers: `oats.okf` can supply both Git and
-directory custody. An Omnigraph integration could replace it in another
-deployment. Simultaneous different integrations in one instance are not assumed
-here; that would need a separate composition decision.
-
-### Resolution and access rules
-
-1. Bind locations explicitly; do not choose from cwd, source work mode, source
-   feature branch or whichever checkout happens to be writable.
-2. Relative paths resolve from their declaring scope, with containment checks.
-3. Missing required bindings or failed access are visible errors; never create
-   an empty substitute or silently choose another base.
-4. Reads do not scaffold nodes. Creation and ownership changes are explicit writes.
-5. Use the user's existing account/access for the selected system. GitHub governs
-   GitHub access; a local directory uses host filesystem access; another tool
-   uses its native authentication. No new OATS permission system is implied.
-6. All configured workspace/team bases are available to its agents. `reads`
-   selects initial context, not an ACL; `owns` selects responsibility/routing.
-   Access to other repositories does not auto-bind them.
-7. A failed Git delivery cannot fall back to direct writes. Tracked knowledge
-   cannot be relabelled local merely to bypass its PR contract.
-8. Defer public/private classification and disclosure routing. Keep the existing
-   secret/credential and third-party-verbatim promotion exclusions.
-
-## 5. Independent harvest, provider-specific writing
-
-A per-source harvest takes preserved evidence, source/soul identity, bounded
-record provenance, claimed note versions, resolved destinations and a stable
-input identifier. It does not rely on the source staying alive or keeping the
-same worktree/branch. Independent execution does not mean context-free evidence.
-
-The reference-model harvester's reasoning is:
-
-1. Consult existing relevant knowledge through the integration's read tools.
-2. Judge the source candidates under the common doctrine.
-3. Select each candidate's owned destination; maintain or supersede existing
-   knowledge rather than creating duplicate descriptions.
-4. Apply changes with the integration's authoring tools, validate, and report
-   the actual delivery outcome. Advance source processing state only under the
-   agreed durable-result protocol.
-
-Concrete writing differs:
-
-- **Git OKF:** worker-owned destination checkout, starting from the accepted
-  branch; knowledge-only PR whether the bundle is embedded or dedicated.
-- **Non-Git OKF candidate:** worker-owned execution context, coordinated edits
-  to the configured directory, validation and recoverable publication. A plain
-  successful edit command alone is not the whole crash/retry contract.
-- **Omnigraph scenario:** the harvester uses Omnigraph's native CLI to consult
-  and write knowledge; working instances use it to retrieve knowledge. How
-  logical nodes, supersession, receipts and consistency map to that CLI must
-  be verified. No command surface or transaction guarantee is assumed here.
-
-The integration manages authenticating through the user's available access;
-credentials do not travel inside harvest evidence. Source retirement preserves
-inputs before removal or reports incomplete retirement. Results are per
-explicit destination; cross-store changes are not assumed atomic.
-
-Provider-neutral orchestration does not mean every backend supports identical
-transactions or review states. Do not report a proposal as applied, a queued
-write as queryable, or a process launch as successful harvesting.
-
-## 6. Visibility, concurrency and validation
-
-For Git OKF, distinguish PR opened, merged, and visible in a refreshed reader.
-For non-Git, distinguish proposed/staged changes if supported, durable application,
-and reader visibility according to the actual provider. A direct local provider
-can have no pending-review phase; it must not fabricate one.
-
-A provider documents its read consistency and available version/freshness
-signals. If it cannot offer snapshots, acknowledge that instead of inventing a
-Git-like revision. Failed or rejected delivery must remain recoverable after
-the source home is gone. Exact watermark and retention mechanics are open.
-
-Concurrency has separate units: source input claims, node updates and storage
-publication. Git requires accepted-head validation across PRs; non-Git files
-need coordinated/recoverable publication; a service needs its actual concurrency
-contract. Test concurrent harvests, retries, and failure after a partial write.
-
-Validate OKF with the OKF validator, including each base's native link namespace.
-A graph integration validates its own representation and logical ownership;
-it does not run a Markdown validator on a service. Default implementations
-must pass behavioral tests for the reference doctrine, provenance, supersession,
-exclusions, one canonical home and consultation by a fresh instance. Authors
-adopting the theory can reuse these tests; a capability choosing a different
-theory is not rejected merely for differing from that model.
-
-## 7. First working version and remaining decisions
-
-There are two related deliverables:
-
-1. **Reference/authoring:** canonical theory and injection/skill guidance plus
-   the `knowledge-theory-expert` agent. Useful without a running OKF deployment.
-2. **Default implementation:** complete capability-owned runtime behavior,
-   applying that theory to working Git and non-Git storage.
-
-**Required:** working Git-backed OKF AND a working non-Git knowledge store.
-A Git-only release with a non-Git interface stub does not satisfy this scope.
-
-Recommendation for the smallest initial implementation: `oats.okf` with Git and
-plain-directory custody. This exercises both paths without introducing an
-unresearched external dependency. The choice is not yet accepted: confirm
-whether the first non-Git implementation should instead be Omnigraph itself.
-An Omnigraph implementation adopting the reference theory should be possible
-without rewriting the theory; this does not oblige every Omnigraph capability
-to adopt it.
-
-Acceptance scenarios use `oats-expert` and `oats-desktop-expert`:
-
-1. Git OKF works both inside the code repo and in a dedicated knowledge repo;
-   harvest runs independently and opens the appropriate knowledge-only PR.
-2. The non-Git implementation persists real harvested knowledge with no Git
-   repository or GitHub dependency, and reports a verifiable result.
-3. In each implementation, a fresh instance answers from accepted knowledge
-   learned by a retired instance, without its home or transcript.
-4. Both preserve the same promotion doctrine, provenance and exclusions, and
-   handle concurrent updates, failed delivery and safe retirement inputs.
-5. A workspace using the OKF integration can consult multiple configured bases
-   without ambiguous ownership or destination selection.
-
-Before implementation, settle the authoring-material and expert delivery shape,
-non-Git backend, binding/schema and ownership identity, delivery/refresh semantics,
-and source input/retention protocol. The kernel stays provider-neutral; each
-capability supplies its complete runtime knowledge behavior. No mandatory shared
-theory-runtime layer, public/private permission model or multi-provider router
-is a prerequisite.

package/docs/design/2026-09-14-artifact-retention-contract.md

@@ -1,190 +0,0 @@
-# Retained capability artifacts and captured resolutions
-
-14 September 2026. Portable Souls implementation foundation, task `aweb-abiu`.
-
-Package updates currently replace `.agents/capabilities/installed/<id>`.
-Instance metadata records commands and resource paths into that mutable store.
-Keeping a command string does not keep the implementation that string invokes.
-
-This first patch adds **retention primitives only**, in
-`lib/capability-artifacts.mjs`. It does not change the installer, lock schema,
-instance launch, scheduler or lifecycle dispatch. Existing instances are not
-protected from package updates by this patch. The following integration contract
-must be reviewed before those consumers change.
-
-## Responsibilities
-
-- Acquisition resolves sources and materializes a package's declared resources.
-- Retention publishes a verified capability tree under its exact integrity.
-- Resolution selects one artifact per capability ID and records effective inputs.
-- Approval authorizes the selected executable revision, independently of retention.
-- Dispatch uses the captured resolution, including for retirement and queued work.
-
-No soul, workspace, team or knowledge schema belongs in the storage primitive.
-There is no new resolver or background service. The artifact includes materialized
-runtime dependencies and its existing `.oats-installation.json` provenance.
-
-## Storage API implemented in this patch
-
-```text
-<deployment>/.agents/capabilities/artifacts/
-  .gitignore                         # managed file containing *
-  <capability-id>/
-    sha256-<full digest>/             # one retained capability tree
-```
-
-`retainCapabilityArtifact(scope, sourceDir, capabilityId, lock)` accepts a
-materialized capability and its captured package/capability lock maps. It checks
-the locked integrity and generated provenance before publication and verifies
-the copied tree again before renaming it into place. It returns the capability
-ID, integrity, canonical local directory and `retained` or `kept` status.
-
-`verifyRetainedCapability(scope, capabilityId, lock)` verifies the exact stored
-revision against the captured provenance. It does not consult the scope's current
-lock, source checkout, catalog, network or approval state.
-
-An absent scope, store or revision reports `artifact-not-found`. A present but
-invalid tree/store or a digest/provenance mismatch is a different refusal. Callers
-can therefore distinguish missing inputs from damaged retained state without
-parsing filesystem error messages. A damaged entry is never silently repaired.
-
-`retainedCapabilityDir(scope, capabilityId, integrity)` computes the lexical path
-after checking the ID and full digest. Computing a path is not verification.
-
-Both publication and verification reject broken or escaping symlinks. Absolute
-symlinks back into the original source are rejected too: that source may later
-disappear. Internal relative symlinks retain their spelling. The source directory
-is copied with the package engine's catchable copy routine, not linked or moved.
-File permissions are preserved; this uses the existing artifact digest format,
-which hashes file bytes and symlink targets, not Unix mode bits.
-At the consumer-migration boundary, introduce a versioned digest covering file
-bytes, symlink targets and each regular file's executable flag, normalized from
-the owner-execute bit (`(mode & 0o100) !== 0`). Apply the same digest rule to Git
-and local-path sources. Group/other execute bits depend on the acquiring user's
-umask and are not part of artifact identity. This models execution by the
-deployment operator who owns the materialized files; it is not a guarantee for
-arbitrary other operating-system principals.
-Keep the old format explicitly verifiable for pre-migration evidence; never
-reinterpret an old digest as covering modes. Other mode bits remain outside
-identity. Do not rewrite modes during retention or infer executable entrypoints
-by parsing free-form command/hook strings. This format change is not implemented
-by the current primitive.
-
-An existing revision is verified and reused. A damaged existing tree is an error,
-never an invitation to overwrite it. Publishing another revision leaves the first
-alone. Same-filesystem staging and rename avoid partially published trees; normal
-errors remove staging. Concurrent publication of an already present valid revision
-may reuse it after verification. A process crash can leave dot-prefixed staging
-for later explicit cleanup; it is never a selectable artifact. This is not a
-power-loss durability or hostile-host isolation guarantee.
-
-Retention creates its managed ignore before any payload. It does not change the
-scope's config, current lock, approval flags or authored capability directories.
-Empty store directories/ignore metadata may remain after failure. No artifact
-garbage collection is implemented: conservative retention is intentional.
-
-## Resolution and lock integration proposed next
-
-Use a versioned per-instance resolution record, with a separate identifier from
-runtime/session identity. It needs:
-
-- Exact source soul reference and retained source revision.
-- One selected artifact reference per capability ID, plus package provenance
-  sufficient to verify and, where possible, restore that artifact.
-- Effective non-secret configuration, default/override provenance and binding
-  references, not secrets or a promise to freeze membership and credentials.
-- Every managed helper, command/hook and runtime resource required for later
-  dispatch. Resource references resolve against retained artifact roots.
-
-The following contract decisions incorporate the external expert's review:
-
-- Imported and member-repository souls produce the same record shape: upstream
-  soul identity, exact retained source revision and adopter-local alias. Keep the
-  canonical repository and exported path in the source reference; the local alias
-  is not a global identity.
-- Retain soul source artifacts separately from capability artifacts, under the
-  deployment, keyed by qualified source identity and content digest. Do not encode
-  a soul as a capability helper. A shared leaf module may implement the tree-copy,
-  digest and publication mechanics, with different provenance validation for each
-  kind. Retain all declared source resources needed after preparation, not just
-  `soul.yaml` or a symlink into the author's checkout.
-  Source retention inherits the same typed absence, invalid-shape and integrity
-  refusals, including never silently repairing a damaged retained tree.
-- Store captured resolutions independently of instance homes so queued work can
-  retain a reference after its originating home is removed. Each instance and
-  independent execution references its exact resolution; conservative retention
-  applies to both source trees and resolution records.
-- Record provenance per effective choice: a soul requirement/default, workspace
-  default, import-entry adoption default or explicit operator choice. Preserve the
-  hard constraints as well as the selected values.
-- Record resolved non-secret provider bindings with separate credential references.
-  The default knowledge provider's payload includes store-qualified read nodes and
-  owned-node destinations. The kernel envelope does not require other knowledge
-  providers to implement OKF's owns/reads model.
-- Record the responsible human/private-team key and chosen wider-team references
-  for messaging-enabled instances. These capture the choice, not immutable live
-  membership or permission to read earlier conversations.
-- Existing-instance migration records `reconstructed`, `partial` or `unknown`
-  status with evidence and unresolved inputs. A partial or unknown record cannot
-  pass for a complete captured resolution in CLI or Desktop readiness.
-
-The scope is an explicit deployment directory. A standalone repository or an
-isolated user-data deployment uses the same store and APIs; no workspace Git
-repository or parent-directory discovery is required by retention.
-
-The deployment lock records current choices for new preparation. A captured
-resolution is the authority for its instance or queued work; it must not look up
-an older package row by ID in today's lock and accidentally acquire a new one.
-The wire schema/version is not chosen by this retention patch. Current lock
-objects are inputs for verification, not an implicit new persistent lock format.
-
-Preparation publishes all needed artifacts, then commits the complete resolution
-before launching anything. A failed preparation may leave unreferenced valid
-artifacts; it must not leave a selectable partial resolution. Choosing or approving
-a newer artifact is a separate operation. No artifact's presence grants approval.
-
-Independent queued work retains the resolution it will execute, even after the
-originating instance or source soul has been removed. Recurring schedules must
-state whether they capture a composition or explicitly prepare a new one on a
-future tick; an already queued execution cannot silently advance either way.
-The proposed default is to capture the composition; re-preparation on later ticks
-is an explicit policy. Messaging-disabled jobs do not acquire a private team.
-
-## Consumer migration
-
-This is one coordinated change, not a permanent pair of resolution engines:
-
-1. Add the explicit lock/resolution schema and store migration. Verify the current
-   flat artifacts before retaining them. Do not re-fetch a moving source and
-   claim those bytes reconstruct an overwritten historical revision.
-2. Wire acquisition/preparation to retained artifacts. Ensure selected source
-   revisions are consistent across the transaction; preserve normal trust gates.
-3. Capture references for new instances and independent work. Route generated
-   commands, runtime packages, capability helpers, launch/retire hooks and recovery
-   through the captured resolution, including after source deletion.
-4. Migrate existing instance/queued-work records only where their exact managed
-   inputs can be established. Report unresolved historical inputs explicitly;
-   preserve running sessions and let their owners choose the restart boundary.
-5. Remove mutable-store lookups from captured consumers. Update diagnostics and
-   removal behavior to retain referenced revisions. Add collection only later if
-   actual storage use justifies it.
-
-The compatibility boundary includes `core.mjs` acquisition, restoration, trust,
-discovery, spawn, launch and retirement; package diagnostics and CLI paths; and
-the scheduler/operation callers. Each is a consumer to check, not a reason to
-create another config parser. Before wiring core consumers, extract the shared
-artifact helpers into a narrow leaf module: `core.mjs` must not acquire a circular dependency on the retention module
-that currently consumes its helpers. Keep policy and lifecycle logic out of the
-shared leaf module.
-
-## Evidence and limits
-
-The focused tests use the real package engine to install A, retain it, update to
-B and retain B. Both execute their own test payload after removing the original
-source, flat install and current lock. Further tests cover idempotent retention,
-digest/provenance rejection, no silent repair, contained symlinks, and Git ignores.
-No model harnesses or GUI processes are started.
-
-This proves the storage prerequisite. It does **not** yet prove a running instance
-or queued job dispatches A while new work uses B. That acceptance test belongs to
-the consumer migration, with executable trust and recovery exercised end to end.