@awebai/oats 0.39.1 → 0.39.3

package/docs/design/2026-10-01-instance-cloning.md

@@ -0,0 +1,106 @@
+# Instance cloning: the `oats.cloning` package
+
+Status: **DECIDED 2026-10-01** by the maintainer with the steward (the transcript handling revised
+2026-10-02 by the human: "cloning just works"). Shipped as `oats.cloning` 1.0.0
+([awebai/oats-cloning](https://github.com/awebai/oats-cloning)), compatibility `oats >=0.34.0`.
+
+## Context
+[Knowledge theory](../knowledge-theory.md#reusing-working-understanding-context-handoffs-and-cloning)
+accepted cloning in principle and left it open: harvesting preserves individual lessons, not the
+combined working picture of a long-running instance. A clone should carry selected references,
+verified observations and provisional reasoning marked as such, under its own identity, credentials
+and ownership, and copying it promotes nothing to shared knowledge.
+
+## Decision
+1. **A capability, not a kernel change.** Everything cloning needs already exists in the kernel:
+   `oats status` and `instance.json` to find and describe the source, `oats capture`/`oats recall`
+   for its transcript, `oats spawn` with `--relation`/`--relative-to`, the launch flags and `--base`,
+   `--preview` then `--expect-decision`, `oats session upload`/`session start`, and
+   `oats retire --self`. No config key, manifest field, hook variable or lock format changes. The
+   capability has no lifecycle hooks, so it cannot break a composing soul's spawn.
+2. **Three roles.** The *requester* (an instance with the capability, or the operator from the
+   deployment with `--soul oats.cloning/cloner`) runs
+   `oats cloning request <source> --goal … --relation independent|child|sibling|parent`. That spawns
+   a short-lived *cloner* (the package soul `oats.cloning/cloner`, `knowledge: none`), which reads the
+   source (`dossier`), writes a brief and a plan (`/plan-clone`), spawns the *clone* (`spawn`:
+   preview, apply, verify), reports and retires itself. The clone is an ordinary instance of the
+   source's soul; nothing about it is special to the kernel.
+3. **The requester chooses only what is theirs:** the goal, the relation and its anchor (the source
+   by default, never the cloner, which retires), the name, whether the transcript is read, and the
+   work base. `independent` is the kernel's `unrelated` and takes no anchor. The cloner decides what
+   the clone carries, and asks the requester only when a choice is genuinely theirs.
+4. **The clone carries a curated brief, not a copy.** A generated preamble (a provenance block and
+   fixed "you are a clone" text) and the cloner's body under fixed headings: the goal verbatim,
+   what is verified (each with its evidence), decisions and why, working understanding marked
+   provisional, open threads and who owns them, work state, where to look (transcript turn ids are
+   citations), and what was not carried. Inherited material is not new evidence: the clone notes it
+   only after re-verifying it. Its commitments, PRs, threads and children stay with the source
+   unless the brief says they were handed over.
+5. **Read-only on the source, bounded.** `dossier` copies a filtered `instance.json` (never the
+   command, environment, hooks, `capabilityMeta` or any credential locator), `TASK.md`, `STATE.md`,
+   `log.md` and `notes/**/*.md` as regular files contained in the home, with size budgets. It never
+   reads identity material, `.oats*`, attachments or the regenerated `AGENTS.md`. Work state is read
+   with read-only git: branch, HEAD, ahead/behind, commit subjects, changed paths and a diffstat,
+   never diff content; a directory work tree is only listed.
+6. **The transcript is included by default, through a temporary record.** `--transcript exclude`
+   opts out. The cloner captures the source into a private record in its own home
+   (`oats capture --root`, 0700), copies the host's capture ignore list into it (and captures nothing
+   if that list exists but cannot be read), reads it with `oats recall --root`, and deletes it. The
+   host's own record is never written, so a source the host chose not to capture stays uncaptured.
+7. **Security requirements, each tested.**
+   - *Redaction, not refusal.* Before the clone can see anything, `spawn` redacts the whole assembled
+     brief, preamble included, with a fixed set of patterns: PEM private keys, provider tokens and
+     keys, JWTs, Bearer tokens, credentials in URLs, and uppercase assignments such as
+     `API_TOKEN=…` or `PASSWORD: …`. Each match becomes `[redacted:<pattern>]`; the receipt and the
+     answer list `{line, pattern}`, never the value. Where a pattern's boundary is ambiguous it
+     redacts more rather than less. Redaction is pattern-limited: a form no pattern recognises
+     survives it, so the `/plan-clone` exclusions stay the policy and redaction is the seatbelt.
+   - *The brief lives only in the clone's home, mode 0600.* `claude` and `codex` launches pass
+     `TASK.md` as an argument, visible to other local users. So the clone is spawned `--no-launch`
+     with only the preamble and a pointer in its task, the brief is attached with
+     `oats session upload` (0600), `TASK.md` is made 0600, and only then is the session started.
+     `spawn` verifies the modes, the attachment's sha256 and the provenance block byte for byte.
+   - *A fresh messaging identity.* `spawn` never passes identity settings, and after the start checks
+     that the clone's alias is its own instance name and its identity differs from the source's
+     (`E_CLONE_IDENTITY` otherwise; a resident identity tied to the source's is refused before the
+     spawn).
+   - *The plan cannot escalate.* `spawn` enforces that the plan matches the request and the source:
+     the soul, relation, anchor and name; the source's launch settings (yolo and child spawns are never
+     escalated); `oats.okf harvest=off` carried when the source had it, never turned on; a base only
+     for worktree souls.
+8. **Cleanup survives retirement.** Retirement keeps a changed home in recovery storage, so the
+   cloner cannot rely on its home being deleted: once the apply has run, it empties `clone/` except
+   `receipt.json` (which holds no source text), and a later run first removes an earlier run's
+   leftovers. A refusal before the apply deletes the temporary record and keeps the brief and plan
+   for a retry. Known limit: a cloner killed mid-run and then retired from outside leaves its
+   `clone/` (0700) in recovery storage.
+9. **Packaging.** Its own repository and package, `oats.cloning`, mirrored and pinned in this
+   repository like the other official packages, with a member expert soul (`oats-cloning-expert`)
+   beside the package soul. **Not a workspace default:** only the souls that request clones compose
+   it (`oats.cloning: { from: package }`), and it becomes a default later on evidence of use. The
+   workspace pins it as `git:github.com/awebai/oats-cloning@v1.0.0` until every deployment's CLI
+   carries the catalog entry, because a bare version is `E_PACKAGE_MISSING` on a CLI without it.
+
+## Rejected
+- **A raw transcript fork** (resuming or forking the source's harness session). It copies identity
+  statements, home paths, secrets and half-finished reasoning as if settled, is harness-specific,
+  and carries no notion of what is still true. The brief is a curated reading, not a replay.
+- **Copying `notes/` into the clone.** Notes are the source's evidence; copied, they would be
+  harvested a second time as the clone's own.
+- **The brief in `TASK.md`.** World-readable by default and passed on the command line.
+- **A refuse-on-match secret scan.** It stops a clone over one stray token; redaction removes the
+  value and still reports where it was.
+- **An operator consent step per clone** (dropped by the human), and an acknowledgement flag for
+  sources the host does not capture. Both are procedural gates: same-user agents can already read
+  the host record, and the temporary record makes neither necessary.
+- **Shipping inside `oats.framework`** (deployable with a bare pin today). Rejected for a standalone
+  package identity, as the human asked. **A second package inside this repository** was rejected
+  too: a `git:` pin always reads `oats-package/`, so it would carry the costs of both options.
+- **A workspace default** in v1: no evidence yet that every soul needs it.
+
+## Out of scope (v1)
+Cloning across machines or from a retired instance; cloning into a different soul (that is a
+handoff); asking a live source to write its own handoff; carrying work-tree content, uncommitted
+changes, attachments, schedules, joined teams or children; a Desktop "Clone" action; kernel
+provenance fields such as `clonedFrom`; the knowledge harvester skipping inherited material in a
+clone's transcript (the preamble marks it instead).

package/docs/knowledge-theory.md

@@ -230,13 +230,15 @@ Directory bases use their own recoverable publication mechanism. Receipts state
 
 ## Reusing working understanding: context handoffs and cloning
 
-Harvesting preserves individual lessons, not the combined working picture that makes a long-running instance effective; a handoff or clone could carry selected references, verified observations and labeled provisional reasoning, but that is not a knowledge store and copying it promotes nothing. A clone would need its own identity, credentials and ownership, and no protocol for selecting and sharing such context is defined.
+Harvesting preserves individual lessons, not the combined working picture that makes a long-running instance effective. A handoff or clone carries selected references, verified observations and labeled provisional reasoning; that is not a knowledge store, and copying it promotes nothing.
+
+Cloning exists as the official `oats.cloning` package ([souls and instances](souls-and-instances.md#cloning-an-instance)). A clone is a new instance of the source's soul with its own identity, credentials and ownership. What it carries is a curated brief written by a short-lived cloner for the new goal: what was re-verified, with its evidence; decisions and their reasons; working understanding marked provisional; open threads and who owns them; and where to look, with transcript turn ids as citations. The cloner leaves secrets out of the brief, a pattern-based redaction pass catches the common forms that slip through, and the brief is attached to the clone as a 0600 file, never placed in its task text. A clone does not carry the raw transcript, the source's `notes/`, the content of its work tree or its uncommitted changes (a worktree clone starts from the source's committed branch, the soul's default or a requested ref), or its commitments: those stay with the source unless the brief says they were handed over. Inherited material is not new evidence; the clone records it in its own notes only after re-verifying it.
 
 ## Implementation boundaries
 
 The model's settled positions are those above: short- and long-running instances are both legitimate; the default is centralized, per-soul knowledge open to reviewed structural evolution; capabilities own their model and runtime behavior; the doctrine preserves expertise, not code descriptions or task residue; and structural change preserves provenance and running work. These are not CLI flags or configuration schemas.
 
-The default OKF capability implements consultation, capture, independent harvest and maintainer review; it does not provide automatic per-soul provisioning, a co-located profile, automatic speciation, redirects or context cloning. Proving the kernel's flexibility needs a genuinely different organization and learning model, not only Git and directory storage within OKF. Updating this document does not migrate existing deployments.
+The default OKF capability implements consultation, capture, independent harvest and maintainer review; it does not provide automatic per-soul provisioning, a co-located profile, automatic speciation, redirects or context cloning. Context cloning is a separate package, `oats.cloning`, not part of the knowledge capability. Proving the kernel's flexibility needs a genuinely different organization and learning model, not only Git and directory storage within OKF. Updating this document does not migrate existing deployments.
 
 ## Related documentation
 

package/docs/official-catalog.md

@@ -12,8 +12,9 @@ or workspace membership alone does not make a package official.
 | `oats.framework` | `oats-framework/v1.5.0` (this repository) | `oats.core`, `oats.setup`, `oats.knowledge-theory` | `knowledge-theory-expert` |
 | `oats.okf` | `v4.1.1` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
 | `oats.aweb` | `v1.21.1` | `oats.aweb` (messaging) | |
-| `oats.engineering` | `v1.5.0` | `oats.engineering-expert`, `oats.developer`, `oats.code-review` | `code-reviewer` |
+| `oats.engineering` | `v1.8.0` | `oats.engineering-expert`, `oats.developer`, `oats.code-review`, `oats.maintainer` | `code-reviewer` |
 | `oats.authoring` | `v1.0.3` | `oats.authoring` | |
+| `oats.cloning` | `v1.0.1` | `oats.cloning` | `cloner` |
 | `oats.jira` | `v1.0.1` | `oats.jira` (tasks) | |
 | `oats.linear` | `v1.0.1` | `oats.linear` (tasks) | |
 

package/docs/release-notes/v0.39.2.md

@@ -0,0 +1,64 @@
+# OATS 0.39.2
+
+## Added
+
+- **oats.cloning 1.0.1**, a new official package (catalog entry, workspace
+  member and pin, and the bundled mirror): clone an instance for a new goal.
+  `oats cloning request <source>` spawns the package soul
+  `oats.cloning/cloner`, which reads the source and writes a curated,
+  redacted brief, then spawns the clone with it attached and a fresh
+  identity. The clone gets no raw transcript, notes or work content. See
+  [instance cloning](../design/2026-10-01-instance-cloning.md).
+  - The framework's oats-expert, oats-kernel-expert, oats-desktop-expert,
+    integrations-expert, oats-operator-expert and oats-setup-admin souls take
+    it (`oats.cloning: { from: package }`); there is no workspace default.
+  - The workspace pins it as `git:github.com/awebai/oats-cloning@v1.0.1`
+    until every deployment's CLI carries this catalog entry; then the pin
+    becomes the bare `v1.0.1`.
+  - 1.0.1 over 1.0.0 (the first pin on main): secret assignments are
+    redacted in any case and as JSON or YAML keys (`password=…`,
+    `client_secret: …`, `"PASSWORD": "…"`), a quoted value to its real
+    closing quote. The README states what redaction does not catch, and that
+    under `delivery: channel` a Claude Code cloner or clone waits at Claude
+    Code's development-channels confirmation until a human answers it.
+  - Operators: run `oats sync` to lock the package; new spawns of those
+    souls get the capability. Running instances keep what they were spawned
+    with.
+
+## Changed
+
+- **Desktop: terminal text in the White and Solarized themes renders at the
+  stroke weight of a native macOS terminal with font smoothing.** Chromium
+  draws dark text on a light background lighter, so these themes' terminal text
+  looked fainter than the same font in a native terminal. Each theme now sets
+  its own text weight; Dark is unchanged, and bold text stays bold.
+- **oats.engineering 1.8.0** (catalog and workspace pin, and the bundled
+  mirrors; includes 1.6.0 and 1.7.0):
+  - **New capability `oats.maintainer`**: the whole maintainer job, generic.
+    It covers the overview of what's open, launching work, a direction and
+    architecture gate, review and merge at an exact head, release planning
+    and shipping with a verification checklist, cross-review between peer
+    maintainers, keeping the project clean, and a living roadmap,
+    architectural calls and coherence rules kept in the maintainer's
+    knowledge. Skills: `/maintainer-intake`, `/launch-work`,
+    `/direction-gate`, `/pr-review`, `/plan-release`, `/ship-release`,
+    `/cross-review-peer`, `/keep-it-clean`.
+  - **A maintainer is not an expert; no soul holds both roles.** The
+    maintainer launches work without leading it: `/launch-work` delegates it
+    to a live expert whose work it continues, or spawns the best-suited expert
+    with `--relation unrelated` as the effort's lead, never as its own child.
+    The lead coordinates the developers and experts it needs.
+  - **Knowledge and state.** Maintainers and experts consult their knowledge
+    before deciding, and keep their instance state accurate.
+  - **Experts tell a standing maintainer what they start** when a human
+    launches them directly.
+  - **Experts give unrelated work to a new expert** (1.6.0). New work goes to
+    a live expert only when it continues that expert's work or that expert's
+    context helps. Otherwise the expert spawns a new one: as its child when
+    the work is part of its effort, or with `--relation unrelated` when it is
+    independent, reporting to whoever asked.
+  - **Developers prefer this machine's reviewer override** (1.7.0). When
+    picking the reviewer's model, `/run-the-review-loop` reads what the
+    machine will launch (`launch.effective`, including an `oats-local.yaml`
+    `souls.launch` override), not only the soul's default. It keeps the
+    override when that runs on another harness than the developer's.

package/docs/release-notes/v0.39.3.md

@@ -0,0 +1,10 @@
+# OATS 0.39.3
+
+## Fixed
+
+- **Desktop: sidebar instance rows keep their gap when selected or hovered.**
+  Each row is meant to paint its fill 2px short of its top and bottom edges,
+  leaving a 4px gap between neighbouring fills. The hover and selected fills
+  painted over that gap, so a selected row and a hovered row above or below it
+  touched. They now stop short of it, in every theme; row height and the tree
+  connectors are unchanged.

package/docs/souls-and-instances.md

@@ -387,6 +387,30 @@ If the workspace has a messaging capability such as aweb, spawned instances
 can also receive identities and coordinate with each other automatically. The
 tasks capability can provide shared work state while messaging provides conversation.
 
+### Cloning an instance
+
+A clone is a new instance of an existing instance's soul that starts from a
+curated brief of what that instance knows, for a new goal. It is not a copy of
+the source's home. Cloning is the official
+[`oats.cloning`](https://github.com/awebai/oats-cloning) package, not a kernel
+verb; a soul that may request clones composes it
+(`oats.cloning: { from: package }`). An instance with the capability runs:
+
+```bash
+oats cloning request <source> --goal-file goal.md --relation independent|child|sibling|parent \
+  [--relative-to <instance>] [--name <slug>] [--transcript exclude] [--base source|default|<ref>]
+```
+
+From the deployment directory the operator adds `--soul oats.cloning/cloner`.
+The relation is required and is the kernel's spawn relation of the clone to the
+anchor (`--relative-to`, the source by default); `independent` is the kernel's
+`unrelated` and takes no anchor. The request spawns a short-lived
+`oats.cloning/cloner`, which reads the source (its home files, work state and,
+unless excluded, its transcript), writes the brief, spawns the clone with its
+own identity, reports and retires itself. Only instances on this host can be
+cloned. [Reusing working understanding](knowledge-theory.md#reusing-working-understanding-context-handoffs-and-cloning)
+says what a clone carries and what it does not.
+
 ### Retire
 
 Retirement runs active capability retire hooks in reverse spawn order before the home disappears. The aweb

package/package-catalog.json

@@ -28,7 +28,12 @@
     },
     "oats.engineering": {
       "url": "https://github.com/awebai/oats-engineering.git",
-      "ref": "v1.5.0",
+      "ref": "v1.8.0",
+      "path": "oats-package"
+    },
+    "oats.cloning": {
+      "url": "https://github.com/awebai/oats-cloning.git",
+      "ref": "v1.0.1",
       "path": "oats-package"
     },
     "oats.framework": {
@@ -65,6 +70,7 @@
     "oats.okf-maintenance": "oats.okf",
     "oats.engineering-expert": "oats.engineering",
     "oats.developer": "oats.engineering",
-    "oats.code-review": "oats.engineering"
+    "oats.code-review": "oats.engineering",
+    "oats.maintainer": "oats.engineering"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awebai/oats",
-  "version": "0.39.1",
+  "version": "0.39.3",
   "description": "OATS (Open Agent Team Specification) — durable souls, disposable instances, targetable capability packages, and the runtime-neutral oats CLI/kernel.",
   "keywords": [
     "agents",