fusion-cli 1.1.0__py3-none-any.whl

fusion/_skills/fusion-intake/references/delivery.md

@@ -0,0 +1,107 @@
+# Delivery intake — batch, for a package of many files
+
+A single dropped file walks the pipeline in SKILL.md one step at a time.
+A **delivery** — a container or folder holding dozens to hundreds of
+files arriving together — walks the same pipeline, but its mechanical
+halves (admit, link) run once each, as a single validated batch, instead
+of one subprocess call per file. This is the protocol proven live on a
+122-file `.athena` package: 122 sequential `admit` calls plus 122 `link`
+calls became one `unpack`, one gate pass, one `batch` call for the admits
+and links, with Stage 2 conversion (the operator's judgment) unchanged in
+the middle.
+
+## The full protocol
+
+1. **Unpack.** `convert.py unpack --bucket <root> --file <container>` —
+   the container is a vehicle, not an original (references/gate.md). It
+   lands beside itself in `inbox/`, keeping folder context, and is
+   discarded. Sign the act `noted`.
+2. **Dedupe (hash sweep).** Before gating hundreds of files one at a
+   time, sweep the unpacked tree for byte-identical duplicates
+   (`sha256_of` on every member) — a delivery often repeats the same
+   attachment across several notes. Keep one copy per distinct hash;
+   report the rest as redundant and remove them from `inbox/`, signed
+   `noted`, same as `inbox_dups` in `references/gate.md`.
+3. **Gate.** `gate.py --bucket <root>` over what remains, then
+   `references/gate.md` for Stage 2 classification. A delivery's files
+   are usually all `new` — but run the topic match anyway; a delivery can
+   still update or conflict with what's already in the library.
+4. **Categories on basename collision.** A delivery's folder structure is
+   real information: when two admitted files would collide on the same
+   `(category, basename)` — the same filename nested under different
+   package folders — file each occurrence under its own per-folder
+   category (`records/2026-q1/report.pdf`,
+   `records/2026-q2/report.pdf`) rather than renaming either file.
+   `batch` enforces the collision check; it never picks a category for
+   you.
+5. **Convert (Stage 2, per file).** Unchanged — this is the operator's
+   judgment, never batched. Notes in particular get **lifted summaries**:
+   when a delivery's package manifest or index already carries a
+   one-line description per note, lift it verbatim into the document's
+   `## Summary` instead of re-deriving one from the body — it's the
+   author's own framing, and it's usually better than a machine-written
+   restatement.
+6. **Batch links from the package manifest.** Once every document for
+   this delivery is written, build ONE op-list from the package's own
+   manifest (see schema below) and run `batch`. If the delivery's admits
+   haven't happened yet either, put them in the same op-list — `batch`
+   validates and runs both halves together.
+7. **Close.** Per document, sign one ledger line: `fusion log converted
+   "sources/<cat>/<file> → <doc>" --bucket <root> --as <you>`. A delivery
+   of 122 files gets 122 `converted` lines — the ledger is a trail of
+   individual acts, batching the mechanics never collapses that trail.
+   Then `fusion index <root>` and `fusion check <root>`, green.
+8. **Archive pass — only when the delivery's own intent says so.** A
+   delivery that is itself an archival drop (its cover note, package
+   manifest, or the human's instruction says these are records being
+   retired, not active work) gets one archive pass at the end: move the
+   closed documents to an `archive/` subfolder inside their zone and set
+   `aurora: archive` on each, per `references/fusion-conventions.md`
+   §Archive. Do not archive by default — most deliveries add active
+   material, not retire it.
+
+## `batch` — schema and semantics
+
+```json
+{"admits": [{"file": "<inbox-rel>", "category": "<cat>"}],
+ "links":  [{"source": "<sources-rel>", "doc": "<zone-rel-doc>"}]}
+```
+
+`admits[].file` is a path relative to `inbox/`; `links[].source` is the
+resulting `sources/`-relative path (`<category>/<basename>`);
+`links[].doc` is zone-relative (`library/...`, `activities/...`, or
+`output/...`) — the document Stage 2 already wrote.
+
+```bash
+uv run <skill>/scripts/convert.py batch --bucket <root> --ops <ops.json> --actor <you>
+```
+
+Prints `{"admitted": n, "linked": m}`.
+
+**Validation before damage, at batch scale.** Two passes, never partial:
+
+1. Every admit and every link is checked structurally BEFORE anything
+   moves: admit files exist in `inbox/` with a supported extension,
+   `(category, basename)` is unique both within the batch and against
+   every row already in `sources/MANIFEST.md` (and against any file
+   already sitting on disk in `sources/` even without a row), the actor
+   is a single token, and each link's `doc` is zone-relative while its
+   `source` either already has a MANIFEST row or is declared by this same
+   batch's admits. One bad op anywhere aborts the whole call — nothing
+   moves, nothing is appended, not even the good ops ahead of it in the
+   list.
+2. All admits then run (reusing `admit()` — still the only writer of
+   `sources/MANIFEST.md`). This half does not roll back.
+3. Before any link is written, every link's `doc` is checked to exist on
+   disk NOW — the operator's Stage 2 conversion must already have
+   produced it. If any doc is missing, the batch aborts naming it and NO
+   link is written, not even the ones whose doc is fine: partial linking
+   would leave some sources correctly cross-referenced and others
+   silently `—`, indistinguishable from "not yet converted."
+4. All links then run (reusing the same MANIFEST-writing path as the
+   `link` subcommand).
+
+Conversion itself (Stage 2 — reading the file, writing the document) is
+never part of a batch: it's the one step in this pipeline that stays the
+operator's judgment, file by file, exactly as `references/convert.md`
+describes.

fusion/_skills/fusion-intake/references/fusion-conventions.md

@@ -0,0 +1,149 @@
+# The Fusion Conventions — operator's card
+
+> Carried byte-identical by all four Fusion skills. SPEC.md in the Fusion
+> repository is normative; this card is the working summary. When they
+> disagree, SPEC.md wins and this card has a bug.
+
+**The contract:** the human judges, the AI operates, the files remember.
+
+**Liberal reader, strict writer.** Never refuse to read a bucket because
+something is missing or unknown. Never write into `library/`, `activities/`,
+`output/`, or a register without satisfying every rule below first.
+
+## The bucket
+
+```
+<bucket>/
+├── BUCKET.md        # identity card + learned conventions
+├── LEDGER.md        # append-only collaboration record
+├── inbox/           # drop zone — things arrive, nothing lives here
+├── sources/         # immutable originals + MANIFEST.md
+├── library/         # settled knowledge — documents
+├── activities/      # live work — documents + status
+├── workbench/       # ephemeral human+AI space — NO format rules
+└── output/          # finished deliverables — documents
+```
+
+- `sources/` is immutable: never modify, rename, or delete a registered file.
+- `workbench/` has no rules; leaving it (promotion) is a deliberate,
+  ledger-logged act.
+- Fusion holds knowledge and work, never media or code — documents point
+  (`resource:`) at big things, they never swallow them.
+- `output/` may also hold non-markdown deliverable files (exports); their
+  names are still lowercase-hyphen slugs with a lowercase extension.
+
+## Before acting — always
+
+1. Read `BUCKET.md`: the identity card, then `## Conventions` — `### Rules`
+   are how this bucket works; `### Delegations` are your standing autonomy
+   grants. They bind you.
+2. Triage through `library/INDEX.md` and `activities/INDEX.md` plus document
+   summaries before opening bodies.
+
+## The document format
+
+Every `.md` in `library/`, `activities/`, `output/` (except INDEX.md):
+
+```markdown
+---
+title: Human-readable name
+type: what-it-is        # open vocabulary, curated per bucket
+aurora: library         # one of the eight — closed set
+---
+
+## Summary
+
+Two or three lines a human or agent reads in two seconds.
+
+---
+
+Full body. Cross-links are plain relative markdown links.
+```
+
+- Required: `title`, `type`, `aurora` — exactly three.
+- Optional: `tags`, `created`/`updated` (ISO dates), `due` (ISO date the
+  thing falls due — `fusion agenda` surfaces it), `source` (path into
+  `sources/`), `resource` (URI or bucket path of the thing this document
+  describes), `status` (`active`|`done`|`dormant`, activities only),
+  `data_sources` (paths list, output only).
+- Body MUST be summary-first: `## Summary`, the lines, a `---` separator,
+  then everything else.
+- Filenames: lowercase, hyphen-separated, `.md`, stem ≤60 chars.
+- Preserve frontmatter keys you don't recognize.
+
+## Aurora — the eight (closed)
+
+| Aurora | Meaning |
+|---|---|
+| `commitments` | Obligations, promises, deadlines |
+| `focus` | Deep work, what deserves full attention |
+| `ops` | Operations, process, the recurring |
+| `collab` | Shared work, other people involved |
+| `life` | Personal, wellbeing, the non-work |
+| `explore` | Curiosity, research, the not-yet-settled |
+| `archive` | Done, kept, out of the way |
+| `library` | Reference, the settled knowledge |
+
+Aurora says what a document means for the human's attention — never invent
+a ninth value.
+
+## Archive
+
+No archive zone: archived items move to an `archive/` subfolder inside their
+zone AND take `aurora: archive`. Path is the truth, aurora is the signal —
+both, always.
+
+## The registers — single writers, no exceptions
+
+| File | Only writer | Your move |
+|---|---|---|
+| `LEDGER.md` | `fusion log` | `fusion log <verb> "<object>" [--note "…"] --as <you>` |
+| `library/INDEX.md`, `activities/INDEX.md` | `fusion index` | run it after any add/move/edit that changes titles or summaries |
+| `sources/MANIFEST.md` | fusion-intake's `scripts/convert.py` | everything enters `sources/` through the intake gate |
+
+Never edit these three files by hand — not with an editor tool, not with
+shell. The ledger verbs (closed set of eleven): `created`, `converted`,
+`classified`, `indexed`, `moved`, `promoted`, `archived`, `restructured`,
+`shipped`, `reflected`, `noted`. Sign with your agent name (`--as claude`,
+or set `FUSION_ACTOR`).
+
+## The CLI crib
+
+| Command | What it does |
+|---|---|
+| `fusion new <path>` | scaffold a conformant bucket |
+| `fusion hub [add\|remove]` | list / register / retire buckets |
+| `fusion log <verb> <object>` | append a signed ledger entry |
+| `fusion index` | regenerate INDEX files (logs `indexed` when changed) |
+| `fusion check [path]` | conformance: errors, warnings, honest exit codes |
+| `fusion status [--since …]` | one bucket at a glance |
+| `fusion today` | the composed morning across all hub buckets |
+| `fusion agenda` | dated + active items across buckets |
+| `fusion setup` | install/refresh the skills into detected agents |
+
+All take `--json`. `--since last-reflection` scopes to the current
+reflection window. **Exit gate for every skill scenario: `fusion check`
+green before you call the work done.**
+
+## When you're blocked
+
+- `fusion` not on PATH: stop and tell the human — the install is
+  `uv tool install ./fusion/cli` from a clone of the Fusion repository.
+  Never imitate the notary by hand: no register writes while the CLI is
+  missing.
+- `fusion check` red and you cannot fix it: stop, show the findings
+  verbatim, leave the bucket as it stands, and sign nothing that claims
+  the work is done. A bucket is a git repo — nothing is unrecoverable.
+- The human rejects a proposal: that is a result, not a failure. Record
+  it if the gear's protocol says to (`noted`), and move on.
+
+## The four accountabilities
+
+| Skill | Owns |
+|---|---|
+| fusion-intake | The gate. Everything that enters, enters through it. |
+| fusion-librarian | The order. Placement, curation, restructuring, reflection. |
+| fusion-planner | The horizon. Activities, agendas, what today looks like. |
+| fusion-analyst | The output. Deliverables that cite their sources. |
+
+One skill, one accountability — the ledger says which hat was worn.

fusion/_skills/fusion-intake/references/gate.md

@@ -0,0 +1,107 @@
+# The intake gate — Stage 2 (judgment)
+
+Stage 1 (`scripts/gate.py`) wrote `workbench/.intake/gate-<runid>.json`
+with six buckets: `exact_dups`, `near_dups`, `update_candidates`,
+`clean_new`, `containers`, `inbox_dups`. This stage assigns each file's
+final class and writes the intake report. It writes NOTHING to
+`sources/` or `library/` — admission and conversion happen only after
+this stage's confirmations.
+
+## Topic matching (do this before classifying)
+
+For every `clean_new` and `update_candidates` entry:
+
+1. Read `library/INDEX.md` (and `activities/INDEX.md` if the content looks
+   like live work) — titles + summary lines are your map.
+2. Grep `library/` for the incoming file's key entities (names, products,
+   periods, metrics).
+3. Read the 1–3 most-related documents' summaries; open bodies only when
+   claims must be compared.
+
+## Per-bucket protocol
+
+**`exact_dups` → duplicate (exact).** Record in the report with the
+matched source. Do not convert, do not prompt — an exact re-drop carries
+no new information.
+
+**`inbox_dups` → the same bytes dropped twice in one batch.** The first
+copy proceeds under its own class; the rest are redundant — report them,
+and clean them out of `inbox/` (delete, signed with a `noted` ledger
+line): `fusion log noted "inbox duplicate deleted: <name> (same bytes
+as <kept>)" --bucket <root> --as <you>` per the standing rule of
+2026-07-10; a bucket's BUCKET.md Conventions may override.
+
+**`clean_new` → new.** Run the topic match. No overlap → class `new`,
+auto-proceed; the gate adds zero friction to genuinely new content.
+Topic overlap without contradiction → still `new`, but note
+"extends <doc>" in the report. Contradiction → reclassify `conflicting`.
+
+**`update_candidates` → updated (confirm) — the identity guard.**
+Read the incoming content and the matched source. Same logical identity
+(a newer version of the SAME document), one candidate, unambiguous →
+class `updated`. Similar-but-not-clearly-same, or multiple candidates →
+ASK the user to confirm identity. Never guess a supersede. On `updated`,
+the report states exactly what a confirmed update will do:
+- admit the new file to `sources/` (renamed if the name collides — the
+  old original is immutable and stays);
+- reconcile the existing library document IN PLACE: same path, content
+  re-converted, `updated:` bumped, `source:` repointed;
+- MANIFEST: new row for the new original, its `library` column pointing
+  at the reconciled document.
+
+**Contradiction detection → conflicting (confirm + resolve).** For
+update candidates and topic-overlapping new files, compare claims:
+figures (same metric, different value), dates (same event, different
+date), conclusions (approved vs rejected). Do NOT flag: facts the
+library is silent on, cosmetic rewording, or a clearly new reporting
+period. On a real conflict, record the claim, both values, both sources —
+and stop. Nothing converts until the human resolves it: accept as
+correction (reconcile), reject (skip) (delete from `inbox/` + `noted`,
+same line as a near-dup skip), or keep both with a note.
+
+**`near_dups` → duplicate (near) (confirm).** Probably a re-export or
+trivial edit. Never auto-skip, never auto-convert: offer skip / treat as
+update / convert as new. A confirmed skip deletes the file from
+`inbox/` and signs it: `fusion log noted "skipped <name>
+(near-duplicate of <source>): <the human's words>" --bucket <root>
+--as <you>` — nothing lives in inbox, not even a rejected guest.
+
+**`containers` → vehicles, not originals.** Report each one (name, size).
+Containers (`.zip`, `.athena`) never enter `sources/` intact — `unpack`
+them beside the container (`inbox/<stem>/` for top-level drops, or a
+nested container's own sub-folder if it lives deeper, keeping that
+context) on the standing rule (or ask first if the container is
+unexpected or its size is surprising), delete the container, sign the
+act `noted`: `fusion log noted "unpacked inbox/<name> →
+inbox/<stem>/ (<n> members; container discarded)" --bucket <root>
+--as <you>`, then gate the extracted contents like any other inbox
+drop.
+
+## The intake report (the prompt surface)
+
+Present one report for the whole run — a table, then a detail block per
+non-`new` row:
+
+```markdown
+## Intake report — <date>
+
+| Incoming | Class | Matches | Action |
+|---|---|---|---|
+| acme-audit.pdf | new | — | converting |
+| q1-report.xlsx | updated | sources/reports/q1-report.xlsx | supersede + reconcile (confirm) |
+| brochure.pdf | duplicate | sources/marketing/brochure.pdf | auto-skipped (exact) |
+| q1-financials.xlsx | conflicting | library/finance/q1.md | hold — revenue 5.0M vs 4.2M |
+```
+
+Detail blocks name the evidence: similarity score, normalized-name match,
+git history lines, the exact conflicting claims. The report is the
+question — ask it, then act only on the answers.
+
+## After confirmation
+
+Proceed per SKILL.md steps 2–4 for approved files only. For an `updated`
+file, `prepare` targets the existing document — pass `--reconcile` plus
+`--dest`/`--slug` set to its current path pieces (without `--reconcile`,
+prepare refuses to touch an existing document) — and the reconciliation
+edits that document in place. Delete gate run files
+(`workbench/.intake/gate-*.json`) at the end of the run.