@awebai/oats 0.22.19 → 0.23.1

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

@@ -0,0 +1,127 @@
+# 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

@@ -0,0 +1,340 @@
+# 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/okf-mirror-provenance.md

@@ -0,0 +1,105 @@
+# Internal: finalizing the OKF mirror's source provenance
+
+The standalone `oats.okf` distribution is authoritative. The framework's
+`capabilities/oats-okf/` and `scripts/okf-source-inventory.json` are generated
+mirrors, not authoring surfaces. This procedure does not publish the source,
+accept a PR, update the catalog, commit, fetch, or change branches.
+
+## Development versus publication
+
+- `node scripts/check-okf-mirror.mjs --generate --source <standalone-repository>`
+  captures current exported working bytes, including dirty/untracked files.
+  It always records `release.status: pending`, null final refs and
+  `published: false`, even when HEAD happens to have a published tag.
+- `node scripts/check-okf-mirror.mjs --verify` uses only the checked-in inventory
+  and mirror. No Git, clone, credentials or network is needed for either a
+  pending or finalized inventory. It checks exact file sets (including empty
+  directories), file bytes, portable Git executable modes, literal symlink
+  targets, wrapper hashes, and consistent release metadata.
+- `--verify-source --source <standalone-repository>` verifies pending snapshots
+  against their exact recorded working state, including branch/dirty metadata.
+  For published inventories it rechecks the immutable commit, payload, origin
+  tag object and peeled commit, ignoring the recorded local branch name. The
+  checkout must still be clean at the recorded accepted commit; renamed
+  branches and detached HEAD are supported. This published-source check needs
+  origin access. It does not depend on cached remote-tracking refs.
+
+Offline verification is an integrity check of a reviewed checked-in inventory,
+not independent proof that a remote still advertises a tag. The explicit source
+check supplies that evidence. No boolean flag is a publication attestation.
+
+## Post-publication command
+
+Only after source review/merge and actual publication of `v2.0.0`:
+
+1. Obtain the **accepted full merged commit ID** from the source review/release
+   record. Do not substitute a mutable branch name, abbreviated hash, or whatever
+   HEAD happens to resolve to. The legacy inventory field `finalMergedCommit`
+   records this caller-supplied acceptance; Git cannot prove human PR approval.
+2. Have a clean standalone checkout at that commit, with the published tag
+   available locally and `origin` pointing to `awebai/oats-okf`. Fetch/check out
+   deliberately through the parent release procedure; the checker never does it.
+3. From the framework checkout, run:
+
+   ```bash
+   node scripts/check-okf-mirror.mjs --finalize \
+     --source .agents/knowledge-rework/repos/okf \
+     --final-tag v2.0.0 \
+     --final-commit "${OKF_V2_ACCEPTED_COMMIT:?set the reviewed full merged source commit ID}" &&
+   node scripts/check-okf-mirror.mjs --verify-source \
+     --source .agents/knowledge-rework/repos/okf &&
+   node --test test/okf-mirror-parity.test.mjs
+   ```
+
+   The relative source path above is the existing ignored work-view convention;
+   substitute an explicitly resolved standalone repository path in other work
+   views. The command must not be run while source acceptance is still changing.
+
+4. Review the resulting payload/inventory diff, run the remaining release gates,
+   then advance the catalog through the parent integration process. Finalization
+   itself never touches the catalog.
+
+`--finalize` requires both `--final-tag` and a full SHA-1/SHA-256 `--final-commit`.
+It replaces only the mirrored capability and inventory, just like `--generate`,
+but stamps `release.status: published` only after all checks succeed:
+
+- The version tag is exactly `v<distribution version>`; HEAD is the explicitly
+  accepted commit and Git reports a clean source tree. Masked index entries
+  (`assume-unchanged`/`skip-worktree`) are not accepted.
+- Actual exported files and wrappers match raw objects at that commit, not just
+  Git status or filtered checkout content. Ignored exported extras, untracked
+  empty directories, CRLF/filter changes, hidden byte changes, mode drift with
+  `core.filemode=false`, and literal symlink-target differences fail closed.
+  Git replacement objects are disabled. Published inventories also record and
+  hash wrapper file modes; materialization preserves those modes and bytes.
+- Exactly one effective origin fetch URL identifies the official source. The
+  usual official GitHub HTTPS/SSH spellings are equivalent. URL rewrites to an
+  unrelated repository are rejected. The remote query uses canonical public
+  HTTPS with source-local Git configuration disabled, so local upload-pack/SSH
+  overrides cannot fabricate its response. Prompts/helpers are disabled and
+  Git commands have a bounded timeout.
+- The local tag resolves to the accepted commit. A fresh `ls-remote` query must
+  advertise the same tag object and the same peeled commit (or direct commit
+  for a lightweight tag). Both annotated and lightweight tags are supported.
+  Missing/unreachable origin, unpublished tags or mismatched refs fail closed.
+- The source is checked again after staging the copy, before replacing the
+  mirror or inventory. Failed acceptance checks leave both untouched. Ordinary
+  filesystem failures during replacement are not a multi-file transaction.
+
+The published record retains `source.head`, clean-state metadata, the branch
+observed at generation (informational during immutable verification), the
+accepted final tag/commit, `remote: origin`, and the exact `tagObject`. Thus
+changing an annotated tag object without changing its commit still invalidates
+`--verify-source`. Remote checks attest what was advertised when queried; they
+cannot prevent an upstream tag from being moved later. Do not move released
+tags, and re-run source verification at the release gate.
+
+## Isolated regression coverage
+
+`test/okf-mirror-parity.test.mjs` uses temporary source repositories and local bare
+origins only, including tag creation/deletion/movement solely inside fixtures.
+The JavaScript `finalizeOkfMirror`/`verifyOkfSource` APIs accept an explicit
+`repository` expectation for these fixtures and record their real source
+identity; the CLI cannot override the official repository. No tests publish to
+GitHub. Checked-in mirror tests accept consistent pending **or** published
+provenance, so finalizing the source does not require weakening those tests.