fusion-cli 1.1.0__py3-none-any.whl

fusion/_skills/fusion-intake/scripts/gate.py

@@ -0,0 +1,267 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.11"
+# dependencies = []
+# ///
+"""fusion-intake Stage 1 — the deterministic gate classifier.
+
+Hashes every file in inbox/, compares against the sources/ tree, normalizes
+filenames, scores content similarity, and writes a gate manifest with six
+buckets: exact_dups, near_dups, update_candidates, clean_new, containers,
+inbox_dups. It classifies and reports — it never writes to sources/ or
+library/. Stage 2 (the agent, references/gate.md) assigns the final
+class and asks the human where the locked rule requires it.
+
+Usage:
+    uv run <skill>/scripts/gate.py --bucket <bucket-root> [--out <path>]
+"""
+import argparse
+import hashlib
+import json
+import re
+import subprocess
+import uuid
+from collections import defaultdict
+from dataclasses import dataclass, field
+from pathlib import Path
+
+# Locked lineage thresholds (doc-converter, kept verbatim).
+NEAR_DUP_THRESHOLD = 0.85   # best content sim >= this (and not exact) -> near-dup
+UPDATE_SIM_FLOOR = 0.30     # [floor, near): name match -> update candidate
+SHINGLE_K = 3               # word-shingle size for similarity
+
+SIMILARITY_READ_CAP = 512 * 1024  # bytes of text considered for similarity — enough to catch any real re-export/update
+
+_DATE_PREFIX = re.compile(r"^(?:\d{4}-\d{2}-\d{2}|\d{8})[_-]")
+_SEP_RUN = re.compile(r"[\s_-]+")
+_WORD = re.compile(r"\w+")
+
+SKIP_NAMES = {"MANIFEST.md", "README.md"}
+
+# Containers are delivery vehicles, not originals (skills/fusion-intake
+# scripts/convert.py `unpack`) — the gate reports them and skips all other
+# classification, before hashing (a 144MB zip should not be shingled).
+CONTAINER_EXTS = {".zip", ".athena"}
+
+
+def normalize_filename(name: str) -> str:
+    """Strip a leading date prefix, lowercase, collapse separators to '-',
+    drop the extension."""
+    stem = Path(name).stem
+    stem = _DATE_PREFIX.sub("", stem)
+    stem = stem.lower()
+    stem = _SEP_RUN.sub("-", stem).strip("-")
+    return stem
+
+
+def sha256_of(path: Path) -> str:
+    h = hashlib.sha256()
+    with open(path, "rb") as fh:
+        for chunk in iter(lambda: fh.read(65536), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def extract_text(path: Path) -> str:
+    """Text for similarity scoring. Binary formats decode to noise and
+    effectively compare on filename only — full content comparison is
+    Stage 2's judgment work. Reads at most SIMILARITY_READ_CAP bytes: a
+    144MB delivery must not be fully decoded just to shingle it."""
+    try:
+        with path.open("rb") as fh:
+            data = fh.read(SIMILARITY_READ_CAP)
+        return data.decode("utf-8", errors="ignore")
+    except OSError:
+        return ""
+
+
+@dataclass
+class SourceIndex:
+    by_hash: dict = field(default_factory=lambda: defaultdict(list))
+    by_name: dict = field(default_factory=lambda: defaultdict(list))
+    text_by_path: dict = field(default_factory=dict)
+
+
+def _iter_files(root: Path):
+    for p in sorted(root.rglob("*")):
+        if not p.is_file() or p.name in SKIP_NAMES:
+            continue
+        rel = p.relative_to(root)
+        if any(part.startswith(".") for part in rel.parts):
+            continue
+        yield p
+
+
+def index_sources(sources_dir: Path) -> SourceIndex:
+    idx = SourceIndex()
+    sources_dir = Path(sources_dir)
+    for p in _iter_files(sources_dir):
+        rel = str(p.relative_to(sources_dir))
+        idx.by_hash[sha256_of(p)].append(rel)
+        idx.by_name[normalize_filename(p.name)].append(rel)
+        idx.text_by_path[rel] = extract_text(p)
+    return idx
+
+
+def _shingles(text, k: int = SHINGLE_K) -> set:
+    """Produce word k-shingles from text. Texts below k word tokens yield NO
+    shingles—there is no linguistic evidence at sub-k thresholds by design.
+    Idempotent on an already-shingled set (cheap passthrough) so callers can
+    thread precomputed/cached shingles through the same call sites that
+    otherwise take raw text."""
+    if isinstance(text, set):
+        return text
+    tokens = _WORD.findall(text.lower())
+    if len(tokens) < k:
+        return set()
+    return {" ".join(tokens[i:i + k]) for i in range(len(tokens) - k + 1)}
+
+
+def similarity(a, b) -> float:
+    """Jaccard over word k-shingles: 0.0 disjoint .. 1.0 identical. Texts
+    under SHINGLE_K words always score 0.0—no evidence, not identity. Exact
+    duplicates are sha256's catch upstream, not this function's. Accepts
+    raw text or a precomputed shingle set (idempotent via _shingles) so
+    the gate's cached best-match path can reuse shingles across sources."""
+    sa, sb = _shingles(a), _shingles(b)
+    if not sa or not sb:
+        return 0.0
+    union = len(sa | sb)
+    return len(sa & sb) / union if union else 0.0
+
+
+def git_history(path: Path, cwd: Path, limit: int = 10) -> list:
+    """Prior-version evidence via git log --follow; [] outside a repo or on
+    any failure (liberal reader)."""
+    try:
+        out = subprocess.run(
+            ["git", "log", "--follow", "--date=short",
+             f"-n{limit}", "--format=%ad\t%s", "--", str(path)],
+            cwd=str(cwd), capture_output=True, text=True, timeout=30,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return []
+    if out.returncode != 0:
+        return []
+    history = []
+    for line in out.stdout.splitlines():
+        date, _, subject = line.partition("\t")
+        if date:
+            history.append({"date": date, "subject": subject})
+    return history
+
+
+def _best_match(incoming_shingles: set, idx: SourceIndex, shingle_cache: dict):
+    """Best (path, sim) over ALL sources — catches renamed near-dups.
+    Source shingles are cached on first use (shingle_cache, one dict per
+    run) so a batch with many incoming files never re-shingles the same
+    source text twice."""
+    best_path, best_sim = None, 0.0
+    for path, src_text in idx.text_by_path.items():
+        if path not in shingle_cache:
+            shingle_cache[path] = _shingles(src_text)
+        s = similarity(incoming_shingles, shingle_cache[path])
+        if s >= best_sim:
+            best_path, best_sim = path, s
+    return best_path, best_sim
+
+
+def classify_intake(inbox_dir: Path, sources_dir: Path, idx: SourceIndex) -> dict:
+    result = {"exact_dups": [], "near_dups": [],
+              "update_candidates": [], "clean_new": [], "inbox_dups": [],
+              "containers": []}
+    seen_in_batch: dict = {}
+    shingle_cache: dict = {}   # source path -> shingle set, cached for this run only
+    for f in _iter_files(Path(inbox_dir)):
+        rel = str(f.relative_to(inbox_dir))
+
+        if f.suffix.lower() in CONTAINER_EXTS:
+            result["containers"].append({"incoming": rel, "size": f.stat().st_size})
+            continue
+
+        h = sha256_of(f)
+
+        if h in seen_in_batch:
+            result["inbox_dups"].append({
+                "incoming": rel,
+                "duplicate_of": seen_in_batch[h],
+                "hash": h,
+                "auto_skip": True,
+            })
+            continue
+        seen_in_batch[h] = rel
+
+        if h in idx.by_hash:
+            result["exact_dups"].append({
+                "incoming": rel,
+                "matched_source": idx.by_hash[h][0],
+                "hash": h,
+                "auto_skip": True,
+            })
+            continue
+
+        name_match = normalize_filename(f.name) in idx.by_name
+        incoming_shingles = _shingles(extract_text(f))
+        if incoming_shingles:
+            match_path, sim = _best_match(incoming_shingles, idx, shingle_cache)
+        else:
+            # No word-level evidence (binary/empty) — hash matching already
+            # ran above, and empty shingles can never score above 0.0, so
+            # skip the whole sources scan rather than pay for it.
+            match_path, sim = None, 0.0
+
+        if match_path is not None and sim >= NEAR_DUP_THRESHOLD:
+            result["near_dups"].append({
+                "incoming": rel, "matched_source": match_path,
+                "similarity": round(sim, 4), "auto_skip": False,
+            })
+        elif match_path is not None and sim >= UPDATE_SIM_FLOOR and name_match:
+            result["update_candidates"].append({
+                "incoming": rel, "matched_source": match_path,
+                "similarity": round(sim, 4),
+                "history": git_history(Path("sources") / match_path,
+                                       Path(sources_dir).parent),
+                "auto_skip": False,
+            })
+        elif match_path is not None and sim >= UPDATE_SIM_FLOOR:
+            result["near_dups"].append({
+                "incoming": rel, "matched_source": match_path,
+                "similarity": round(sim, 4), "auto_skip": False,
+            })
+        else:
+            result["clean_new"].append({"incoming": rel})
+    return result
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(
+        description="fusion-intake Stage-1 gate classifier")
+    ap.add_argument("--bucket", required=True, help="bucket root")
+    ap.add_argument("--out", help="manifest path "
+                    "(default: <bucket>/workbench/.intake/gate-<runid>.json)")
+    args = ap.parse_args(argv)
+
+    root = Path(args.bucket).expanduser().resolve()
+    inbox, sources = root / "inbox", root / "sources"
+    if not inbox.is_dir() or not sources.is_dir():
+        print(f"not a bucket (no inbox/ + sources/): {root}")
+        return 1
+
+    idx = index_sources(sources)
+    buckets = classify_intake(inbox, sources, idx)
+    manifest = {
+        "version": 1,
+        "counts": {k: len(v) for k, v in buckets.items()},
+        "buckets": buckets,
+    }
+    out = Path(args.out) if args.out else (
+        root / "workbench" / ".intake" / f"gate-{uuid.uuid4().hex[:12]}.json")
+    out.parent.mkdir(parents=True, exist_ok=True)
+    out.write_text(json.dumps(manifest, indent=2), encoding="utf-8",
+                   newline="\n")
+    print(f"gate: {manifest['counts']} -> {out}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

fusion/_skills/fusion-librarian/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: fusion-librarian
+description: "The Fusion librarian — the accountable owner of a bucket's order. One entry, eight gears: query (natural-language search over the bucket — the default), create (a new conformant document), tag (bulk frontmatter metadata), cross-reference (map what relates to what), promote (workbench → a real zone, validated), archive (out of the way, path + aurora agreeing), restructure (reorganize and sign your reasons), reflect (the reflection ritual: introspect the ledger, propose curation, land what was learned). Use for 'find', 'search', 'where is', 'create a document', 'tag', 'what links to', 'promote', 'archive this', 'reorganize', 'restructure', 'run a reflection'. For files arriving from outside use fusion-intake; for activity planning use fusion-planner; for reports and exports use fusion-analyst. Applies only inside a Fusion bucket — a directory tree with BUCKET.md and LEDGER.md at its root; if there is no such bucket in play, this skill does not apply."
+license: MIT
+compatibility: "Requires the fusion CLI on PATH."
+---
+
+# fusion-librarian — the owner
+
+The agent is the librarian: not a search box, an accountable owner. Clean,
+bold, opinionated structures — and every structural act signed in the
+ledger with its reasons.
+
+Read `references/fusion-conventions.md` once per session. Before any gear:
+read the bucket's `BUCKET.md` — `### Rules` bind how this bucket files
+things; `### Delegations` say what you may do without asking. No
+`BUCKET.md` up the tree and none named? Stop — this is not a Fusion
+bucket, and no Fusion skill applies (`fusion hub` lists the real ones).
+
+## Pick the gear
+
+Explicit intent beats inference. Bare or ambiguous intent defaults to
+**query** — the one gear that changes nothing.
+
+| Signal | Gear | Load |
+|---|---|---|
+| find / search / where is / what do we know about | query (default) | references/query.md |
+| create / new document / write down | create | references/create.md |
+| tag / label / set field across docs | tag | references/tag.md |
+| what links to / related / map connections | cross-reference | references/cross-reference.md |
+| promote / finalize / move out of workbench | promote | references/promote.md |
+| archive / put away (documents — a finished *activity* closes via fusion-planner) | archive | references/archive.md |
+| reorganize / restructure / new taxonomy | restructure | references/restructure.md |
+| reflect / reflection / review the bucket | reflect | references/reflect.md |
+
+Destructive gears — promote, archive, restructure — are never reached by
+near-miss inference: if you arrived at one without the user naming it,
+stop and confirm by name. reflect proposes destructive acts but executes
+them only on a yes (or a standing delegation).
+
+## Ledger discipline (which hat, which verb)
+
+| Gear | Verb logged |
+|---|---|
+| create | `created` |
+| tag | `classified` |
+| promote | `promoted` |
+| archive | `archived` |
+| restructure | `restructured` — always with a `--note` giving the reasons |
+| reflect | `reflected` to sign the cycle; `noted` for each convention change |
+| query | nothing — reading is free |
+| cross-reference | nothing — unless approved link edits are applied, then `noted` |
+
+All writes via `fusion log … --bucket <root> --as <you>`. After any gear
+that adds, moves, or edits documents: `fusion index <root>`, then
+`fusion check <root>` — green before you report done.
+
+## Never
+
+- Never hand-edit `LEDGER.md`, `INDEX.md`, or `MANIFEST.md`.
+- Never touch `sources/` — originals are immutable.
+- Never restructure or archive without either a yes or a written
+  delegation in BUCKET.md.
+- Never leave `fusion check` red behind you.

fusion/_skills/fusion-librarian/references/archive.md

@@ -0,0 +1,21 @@
+# archive — out of the way, never out of reach
+
+Path is the truth, aurora is the signal — both, always, in one move.
+
+1. Confirm the target and the authority: explicit ask, or a standing
+   delegation in BUCKET.md `### Delegations` that covers this case
+   (cite it in the note when you use it).
+2. Move the document to `<its-zone>/archive/<same-folder-structure>/`.
+3. Repair what pointed at it: run `uv run <skill>/scripts/link-repair.py
+   scan --bucket <root>` and apply exact-confidence repairs per the
+   sweep protocol in [cross-reference.md](cross-reference.md) (or a
+   standing delegation); fuzzy always asks.
+4. Edit its frontmatter: `aurora: archive`.
+5. `fusion log archived "<zone>/<old> → <zone>/archive/<new>"
+   [--note "delegation: <rule>"] --bucket <root> --as <you>` ·
+   `fusion index <root>` · `fusion check <root>` — the checker's W3
+   watches exactly this agreement.
+
+Activities are the planner's: closing or archiving one is
+fusion-planner's close gear (it also writes the final Log line in
+plan.md). This gear archives library/ and output/ documents.

fusion/_skills/fusion-librarian/references/create.md

@@ -0,0 +1,14 @@
+# create — a document born conformant
+
+1. Establish title, type, aurora, and destination zone/folder. Infer type
+   and folder from the bucket's existing taxonomy and BUCKET.md Rules;
+   ask only when genuinely ambiguous. Aurora is the human-attention call —
+   propose, and let an explicit instruction override. Before writing,
+   triage `library/INDEX.md` for an existing document on the same
+   subject — extending or reconciling one beats creating a twin; when a
+   candidate exists, propose the edit instead and let the human choose.
+2. Write the document: the three required fields (plus `created:` today,
+   `tags:` when useful), `## Summary` (2–3 lines), `---`, then the body.
+   Filename: lowercase-hyphen slug, ≤60 chars.
+3. `fusion log created "<zone>/<path>" --bucket <root> --as <you>` ·
+   `fusion index <root>` · `fusion check <root>` green.

fusion/_skills/fusion-librarian/references/cross-reference.md

@@ -0,0 +1,45 @@
+# cross-reference — map what relates to what
+
+Read-only. For a target document or topic:
+
+1. Extract its entities (names, projects, products, periods).
+2. Sweep the bucket: direct mentions (grep), shared frontmatter values
+   (type, tags, aurora), thematic kinship (summaries that talk about the
+   same thing).
+3. Report three buckets, every line carrying a path:
+   **Direct references** · **Shared attributes** · **Thematic connections**.
+4. Offer (don't apply) link edits: "these two documents should point at
+   each other" — applying them is a content change the user approves.
+   On a yes: edit, then sign the write —
+   `fusion log noted "<path> — cross-linked to <other>" --bucket <root>
+   --as <you>` — then `fusion index <root>`, `fusion check <root>`.
+
+## Repair sweep — broken links, scan proposes, you approve, apply signs off
+
+`scripts/link-repair.py` productizes the pattern above for the mechanical
+case: a link that used to resolve and no longer does (a document moved, a
+source got re-filed). It never guesses between candidates — the human
+gate stays in the middle.
+
+1. `uv run <skill>/scripts/link-repair.py scan --bucket <root> >
+   proposals.json` — walks `library/` and `activities/`, tests every
+   relative link from the doc's own directory, and for each broken one
+   searches `sources/` and the doc zones by basename. JSON goes to
+   stdout, a human-readable table to stderr: **EXACT** (unique basename
+   match — safe to apply as-is), **FUZZY** (unique only after
+   lowercase/hyphen-insensitive normalization — confirm per group, never
+   silently folded in with the exact ones), **UNREPAIRABLE** (zero or
+   two-or-more candidates — never guessed, hand-fix or leave it).
+2. Show the human the table. Exact and fuzzy are always separated; a
+   fuzzy group is applied only on an explicit yes.
+3. Edit `proposals.json` down to the approved subset (delete the
+   proposals nobody confirmed; `unrepairable` entries are informational,
+   never fed to apply).
+4. `uv run <skill>/scripts/link-repair.py apply --bucket <root>
+   --proposals proposals.json` — rewrites only the approved pairs,
+   bumps (or adds) `updated:` on the documents it touched, prints the
+   count. It writes no ledger entry.
+5. Sign the pass yourself: `fusion log noted "link-repair sweep — <N>
+   links repaired (<E> exact, <F> fuzzy)" --bucket <root> --as <you>` —
+   then `fusion index <root>`, `fusion check <root>` green before you
+   report done.

fusion/_skills/fusion-librarian/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-librarian/references/promote.md

@@ -0,0 +1,24 @@
+# promote — leaving the workbench is a deliberate act
+
+workbench/ has no rules; the zones do. Promotion is the moment the rules
+attach.
+
+Pre-flight (all three, before anything moves):
+1. Explicit invocation confirmed — arrived here by inference? Stop, ask.
+2. Source is in `workbench/`; destination zone/folder named or clearly
+   inferable from the document's nature (`library/` knowledge,
+   `activities/` live work, `output/` deliverables). Ask if unclear.
+3. State the plan in one sentence: "Promoting workbench/<x> to
+   <zone>/<folder>/<slug>.md."
+
+Validate BEFORE moving (strict writer — a failed check stops the
+promotion, nothing moves):
+- frontmatter parses; `title`, `type`, `aurora` present; aurora one of
+  the eight; summary-first body; slug filename ≤60.
+- activities documents: `status` present. output documents: encourage
+  `data_sources`.
+Fix what the user wants fixed, or leave it in the workbench.
+
+Then: move the file (Write new + delete old, or `mv`), then
+`fusion log promoted "workbench/<x> → <zone>/<path>" --bucket <root>
+--as <you>` · `fusion index <root>` · `fusion check <root>` green.

fusion/_skills/fusion-librarian/references/query.md

@@ -0,0 +1,17 @@
+# query — answer from the bucket, cited
+
+Read-only. Changes nothing, logs nothing.
+
+1. Parse the question: entities, concepts, constraints (type, aurora,
+   dates, status).
+2. Triage via `library/INDEX.md` + `activities/INDEX.md` — titles and
+   summary lines first. `fusion status` helps scope what exists.
+3. Grep frontmatter for structured hits (`type:`, `aurora:`, `tags:`),
+   then content for the rest.
+4. Read the most relevant documents — summaries first, bodies only for
+   the finalists (keep it under ~10 full reads).
+5. Answer with a `## Sources` table: document path · what it contributed.
+   Every claim cites a path. If the bucket is silent on part of the
+   question, say what is known and what is missing — never fill gaps
+   from your own general knowledge without labelling it as outside the
+   bucket.

fusion/_skills/fusion-librarian/references/reflect.md

@@ -0,0 +1,47 @@
+# reflect — the metabolism (SPEC §10)
+
+The files remember → you reflect → the human judges → the system learns.
+Run on the bucket's `reflection_cadence`, or when asked.
+
+## 1. Introspect
+
+```bash
+fusion log --since last-reflection --bucket <root>   # what happened
+fusion status <root> --since last-reflection         # counts, auroras…
+fusion check <root>                     # drift: stale INDEX, W1 inbox age…
+```
+
+Read the window's ledger like telemetry: what got converted, promoted,
+touched — and what never did.
+
+## 2. Curate & prune — the proposal list
+
+Propose, with paths and evidence, whichever apply:
+- workbench items older than the window → promote or expire;
+- activities with `status: active` and no ledger touch → `dormant` or
+  archive (W5 already names them);
+- superseded or stale library documents → `archive/`;
+- duplicates to merge, fat documents to split;
+- summaries that no longer match their bodies;
+- taxonomy that stopped serving → a restructure proposal;
+- rules the window taught: "we always filed X under Y — make it a Rule?"
+- delegations earned: acts the human approved repeatedly this window.
+
+## 3. Judge
+
+Present the list. Destructive and archival acts need a yes — EXCEPT where
+`### Delegations` already grants it (cite the delegation, act, and note
+it). Never bundle: the human can take proposal 3 and refuse proposal 4.
+
+## 4. Learn & sign
+
+- Approved rule/delegation changes: edit `BUCKET.md ## Conventions`, one
+  `fusion log noted "BUCKET.md — <the change>" --bucket <root> --as <you>`
+  per change.
+- Execute approved acts via their own gears (archive, restructure…) so
+  each carries its own verb.
+- Sign the cycle LAST:
+  `fusion log reflected "<bucket> — <N> proposals, <M> adopted"
+  --bucket <root> --as <you>`
+- Episodic reports are ephemeral: the proposal list lives in workbench/
+  and can die there; only conventions and ledger entries persist.

fusion/_skills/fusion-librarian/references/restructure.md

@@ -0,0 +1,20 @@
+# restructure — ownership means showing your reasons
+
+The librarian's distinctive power: reorganizing the bucket when the
+taxonomy stopped serving. Also the most destructive gear — so it runs as
+propose → confirm → execute → sign.
+
+1. **Propose.** Read the zone's INDEX + folder shape. Write the plan:
+   every move (`old → new`), every folder created or retired, and the
+   REASON in one paragraph. Check `BUCKET.md ### Rules` — a restructure
+   that contradicts a Rule needs the Rule changed first (that is a
+   reflect-gear conversation).
+2. **Confirm.** The human says yes (or a Delegation explicitly covers
+   it — rare for restructures; cite it).
+3. **Execute.** Move files; update relative links in affected documents
+   (grep for the old paths); keep filenames conformant.
+4. **Sign.** One ledger entry for the operation:
+   `fusion log restructured "<zone>/<scope>" --note "<the reason>"
+   --bucket <root> --as <you>` — the note is not optional here. Then
+   `fusion index <root>` and `fusion check <root>` (W4 watches the links
+   you just moved).