ckb/.agents/modules/share/README.md
Michał Kopeć b6b592d5d7 Template 2.0.2: share and capture hardening, Crux without Sources
Fixes F6, F12-F16 from the 2.0.0 script review:
- share: plain file/mailbox names and mailbox-bound share_id/version, or
  the message is ignored (no ckb.yaml injection, no writes outside
  raw/inbox/); ledger rejects whitespace/control characters; every
  commit on a message must be by an owner; duplicate members.yaml
  entries unown a mailbox; only verified retractions hide mail; branch,
  url and name validated before git; received copy always untrusted;
  <private> stripped from title/tldr and unclosed tags; no send without
  the secret scan
- capture: frontmatter values quoted unless plainly safe; one-line title
- lint check 13: chat-attributed Crux needs no Sources

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 14:38:18 +01:00

100 lines
4 KiB
Markdown

# `share` module
*Read this in: **English** | [Polski](README.pl.md)*
Opt-in. Install with "install the share module"; remove with "uninstall the
share module". Nothing in here is active until installed.
## What it does
It sends a document from one KB to another through a **channel**, which is a
separate git repo that both KBs can push to. The receiving KB takes the
document into `raw/inbox/` and ingests it as usual, so nothing unreviewed
reaches its wiki.
| Skill | Does |
|---|---|
| `ckb-share` | Joins a channel, sends a document (packed into a self-contained copy, secret-scanned, confirmed), lists and takes incoming mail, shows what was sent, and retracts a sent document. |
Say "share the kickoff summary with beta", or "check shared mail", then
"Ingest".
## The channel
```
<channel-repo>/
├── CHANNEL.md # what the channel is for (human)
├── members.yaml # kb name → owners (git emails allowed to write its mailbox)
└── mail/
├── alpha/ # written only by KB "alpha"; files never edited or deleted
└── beta/
```
- **One channel per trust group**, such as one client. Git has no per-folder
permissions, so everyone in the channel can read every mailbox.
- **One writer per mailbox.** No merge conflicts are possible.
- **Append-only.** A new version or a retraction is a new file.
- Create the repo by hand on your git host (empty is fine). The first
`join` seeds `CHANNEL.md` and `members.yaml`.
## A message
```markdown
---
type: share
kind: document # document | retraction
share_id: alpha/kickoff-summary
version: 2
from: alpha
to: [beta] # or ["*"] for the whole channel
sent_by: Ann Smith <ann@example.com>
sent_on: 2026-11-14
title: Kickoff summary
origin: outputs/documents/2026-11-11_kickoff-summary.md
supersedes_version: 1
untrusted: true
---
```
When sending, private spans (`<private>…</private>`) and `## Notes` are left
out. Links into the sender's wiki become text, and `## Sources` / `## Crux`
paths are marked with the sender's name, so the receiver's lint treats them
as not checkable rather than broken.
When receiving, the file goes into `raw/inbox/` with `share_channel`,
`share_ref` (path@commit), `received_on`, `submitted_by` and, for a newer
version, `supersedes_source`.
## Safety
- **Nothing leaves without a yes.** Every send is shown first, as a dry run
with the `ABOUT.md` sensitivity section, and a possible secret blocks it
outright.
- **The sender is checked.** On receive, every git author who added or
changed a message must be an owner of its mailbox in `members.yaml`, and a
mailbox listed twice there counts as unowned. Otherwise the message is
marked unverified and not taken unless you insist. Only a verified
retraction can withdraw a message you haven't taken yet. A message whose
`from`, `share_id` or version doesn't match its mailbox, or whose file name
isn't a plain name, is ignored with a warning.
- **`members.yaml` is trusted as written.** Any member who can push can edit
it, including to add themselves as an owner. A git host with protected
paths or a pre-receive hook is what enforces mailbox ownership; use one for
a channel whose members you don't fully trust.
- **Received mail is untrusted data**, never instructions to the agent. The
received copy always carries `untrusted: true`, and the sender's own
`untrusted` and review fields are dropped.
- **Unsharing doesn't unpublish.** A retraction makes receivers unwind the
document through `ckb-retract`, but the original stays in the channel's git
history.
- **No stored credentials.** Channels use your own git access. Clones live in
`tmp/share/`, which is gitignored.
## What's recorded where
| What | Where |
|---|---|
| Channels, this KB's mailbox name, incoming ledger | `share:` block of `ckb.yaml` (committed, owned by the script) |
| Channel clones, send previews | `tmp/share/` (gitignored) |
| Received documents | `raw/inbox/` → `raw/archive/` after ingest |
| Received retractions | `raw/retractions/`, for `ckb-retract` |