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>
5.2 KiB
5.2 KiB
| type | tldr | status | decided_on | decided_by | affects | confidence | quality | last_updated | freshness_window_days | retention |
|---|---|---|---|---|---|---|---|---|---|---|
| decision | 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. | accepted | 2026-11-11 | Michał Kopeć | .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 | 0.7 | 0.8 | 2026-11-11 | 365 | 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
- 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. - The channel is a separate git repo per trust group, with
CHANNEL.md,members.yaml(KB name → owner emails) andmail/<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 intotmp/share/<channel>/, and creating the repo stays manual. - Messages carry an envelope:
type: share,kind(document/retraction), a stableshare_id(<kb>/<slug>),version,from,to(names or*),sent_by,sent_on,untrusted: true. - Send packs a self-contained copy.
<private>spans and## Notesare 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. Onlyoutputs/documents/,outputs/answers/andwiki/pages can be sent;raw/archive/needs an extra yes. Lint's secret patterns block the send. A dry run shows theABOUT.mdsensitivity section, and the user confirms every send. - Receive never touches
wiki/. Documents go toraw/inbox/, withsubmitted_byset to the git author who added the message, sockb-retract's owner check works unchanged. A newer version points at the earlier one withsupersedes_source, and ingest treats it as supersession. A retraction becomes oneraw/retractions/request per held version. - 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. - What was handled is a ledger, not derived from files. The plan was to
derive "already taken" from
raw/inbox/andraw/archive/, butckb-retractdeletes the archived file, so a retracted document would be offered again. Thereceived:list in theshare:block ofckb.yamlrecords 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.mcpadd_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.yamlgrows 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: sharefiles, ashare: N waitingline at session start, eval cases (a channel needs a git remote, which the eval fixtures don't provide yet), and a PowerShell check.