ckb/.agents/modules/share
Michał Kopeć aab4b9e5e2 Template 2.0.3: Windows encoding, line endings, BOM, paths, hooks
Fixes F7-F11 from the 2.0.0 script review:
- UTF-8 stdout/stderr in every script; UTF-8 decoding of git/rg/yt-dlp
  output and of hook stdin
- utf-8-sig reads, so BOM files keep their frontmatter
- fingerprints match LF or CRLF checkouts (lint, lint_quick.sh,
  consolidate); prefix match on the full digest; short ones reported
- POSIX paths in lint output; rg --path-separator /
- hook installers default to the running interpreter, quote paths,
  --check reports a missing interpreter, odd settings are an error

New tests/unit/test_windows.py.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 15:32:26 +01:00
..
fragments Template 1.28.0: share module — mailboxes in a git channel (D-0018) 2026-11-11 13:31:51 +01:00
skills/ckb-share Template 2.0.3: Windows encoding, line endings, BOM, paths, hooks 2026-11-11 15:32:26 +01:00
module.yaml Template 1.28.0: share module — mailboxes in a git channel (D-0018) 2026-11-11 13:31:51 +01:00
README.md Template 2.0.2: share and capture hardening, Crux without Sources 2026-11-11 14:38:18 +01:00
README.pl.md Template 2.0.2: share and capture hardening, Crux without Sources 2026-11-11 14:38:18 +01:00

share module

Read this in: English | Polski

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

---
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