New opt-in `share` module with skill `ckb-share` and stdlib `share.py` (join/send/unshare/list/receive/status). KBs exchange documents through a git channel with one append-only mailbox per KB; sends are packed self-contained, secret-scanned and confirmed; received documents land in raw/inbox/ (untrusted), retractions in raw/retractions/; the git author must own the mailbox. dedup_inbox.py reports SAME SHARE; ckb-ingest and ckb-retract know share files. Smoke test covers two KBs end to end. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
97 lines
5.2 KiB
Markdown
97 lines
5.2 KiB
Markdown
---
|
|
type: decision
|
|
tldr: KBs exchange documents through an opt-in `share` module — a git channel per trust group with one append-only mailbox per KB; sends are packed self-contained, secret-scanned and confirmed; receives land in raw/inbox/ (untrusted) or raw/retractions/; the git author must own the mailbox; handled messages are recorded in a ledger in ckb.yaml.
|
|
status: accepted
|
|
decided_on: 2026-11-11
|
|
decided_by: Michał Kopeć
|
|
affects: .agents/modules/share/, .agents/skills/ckb-ingest/SKILL.md, .agents/skills/ckb-ingest/scripts/dedup_inbox.py, .agents/skills/ckb-retract/SKILL.md, tests/smoke.sh, README.md, docs/MANUAL.md
|
|
confidence: 0.7
|
|
quality: 0.8
|
|
last_updated: 2026-11-11
|
|
freshness_window_days: 365
|
|
retention: high
|
|
---
|
|
|
|
# D-0018 — A share module: mailboxes in a git channel
|
|
|
|
**Status:** Accepted · **Decided:** 2026-11-11 · **Deciders:** Michał Kopeć
|
|
|
|
## Context
|
|
|
|
One KB often holds something another KB needs: a summary, a decision, an
|
|
answer. Until now the options were `linked/`, which mounts a whole KB and
|
|
needs local filesystem access, and the `mcp` module's `add_to_inbox`, which
|
|
needs the receiver to run a server. A team wanted to prepare a document in
|
|
one KB and drop it where another KB can pick it up, using only git.
|
|
|
|
## Decision
|
|
|
|
1. **An opt-in module** (D-0001 pattern), `share`, with one skill,
|
|
`ckb-share`, and one stdlib script, `share.py`. Most KBs never send
|
|
anything, so the base pays no context for it.
|
|
2. **The channel is a separate git repo per trust group**, with
|
|
`CHANNEL.md`, `members.yaml` (KB name → owner emails) and `mail/<kb>/`.
|
|
Each KB writes only to its own mailbox and never edits or deletes a file
|
|
there, so merge conflicts cannot happen. A new version or a retraction is
|
|
a new file. The channel is cloned into `tmp/share/<channel>/`, and creating
|
|
the repo stays manual.
|
|
3. **Messages carry an envelope**: `type: share`, `kind`
|
|
(`document`/`retraction`), a stable `share_id` (`<kb>/<slug>`), `version`,
|
|
`from`, `to` (names or `*`), `sent_by`, `sent_on`, `untrusted: true`.
|
|
4. **Send packs a self-contained copy.** `<private>` spans and `## Notes` are
|
|
dropped. Local links become text. Sources and Crux paths are marked
|
|
`<kb>:`, so the receiver's lint treats them as not checkable rather than
|
|
broken. Only `outputs/documents/`, `outputs/answers/` and `wiki/` pages
|
|
can be sent; `raw/archive/` needs an extra yes. Lint's secret patterns
|
|
block the send. A dry run shows the `ABOUT.md` sensitivity section, and
|
|
the user confirms every send.
|
|
5. **Receive never touches `wiki/`.** Documents go to `raw/inbox/`, with
|
|
`submitted_by` set to the git author who added the message, so
|
|
`ckb-retract`'s owner check works unchanged. A newer version points at the
|
|
earlier one with `supersedes_source`, and ingest treats it as
|
|
supersession. A retraction becomes one `raw/retractions/` request per
|
|
held version.
|
|
6. **The sender is checked on receive.** The git author who added a message
|
|
must be an owner of its mailbox in `members.yaml`. If not, the message is
|
|
UNVERIFIED and is taken only when the user insists. Git cannot enforce
|
|
per-folder writes; a git host's path protection can, and that is
|
|
documented as optional hardening.
|
|
7. **What was handled is a ledger, not derived from files.** The plan was to
|
|
derive "already taken" from `raw/inbox/` and `raw/archive/`, but
|
|
`ckb-retract` deletes the archived file, so a retracted document would be
|
|
offered again. The `received:` list in the `share:` block of `ckb.yaml`
|
|
records every message taken, declined, filed or seen. The script owns the
|
|
whole block.
|
|
|
|
The plan's open questions were settled on their recommended answers: notes
|
|
are dropped by default (`--keep-notes` to send them); documents, answers and
|
|
wiki pages can be sent, raw sources only with a yes; declines live in
|
|
committed `ckb.yaml`; a routine only reports what is waiting; channels are
|
|
created by hand.
|
|
|
|
## Alternatives considered
|
|
|
|
- **Sync one folder with a submodule or subtree.** Pinned commits, a detached
|
|
HEAD and history mixed into the KB. Rejected for a separate clone in
|
|
`tmp/`.
|
|
- **One shared folder all KBs write to, deleting what they take.** Conflicts
|
|
between writers, and one receiver's delete hides the file from the others.
|
|
- **`linked/` to a shared KB.** Better for knowledge everyone keeps reading.
|
|
Still available, but it doesn't fit handing one document over.
|
|
- **`mcp` `add_to_inbox`.** Needs a running server at the receiver. Still the
|
|
right tool when one exists.
|
|
- **Read receipts written back to the channel.** Deferred: the receiver would
|
|
write outside its own mailbox, or into it, which mixes roles.
|
|
|
|
## Consequences
|
|
|
|
- Sent material stays in the channel's git history. Unsharing makes
|
|
receivers unwind it, but it doesn't unpublish.
|
|
- `ckb.yaml` grows by one line per message received. That is acceptable for
|
|
years of use, and the ledger can be trimmed by hand once its messages are
|
|
gone from the channel.
|
|
- The Hub plan's git push transport (`raw/outbox/` to an inbound branch) can
|
|
adopt this envelope instead of inventing its own.
|
|
- Not done in this release: a lint check for `type: share` files, a
|
|
`share: N waiting` line at session start, eval cases (a channel needs a git
|
|
remote, which the eval fixtures don't provide yet), and a PowerShell check.
|