fusion-cli 1.1.0__py3-none-any.whl

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

@@ -0,0 +1,13 @@
+# tag — bulk metadata, honestly reported
+
+1. Parse the field and value; `--scope`-like constraints (a folder, a
+   type) narrow the set. Value "auto" means you infer per document from
+   its content — say so in the report.
+2. Edit each document's frontmatter, preserving every existing key and
+   the body untouched. `updated:` does NOT bump (metadata, not content).
+3. Report a table: file · field · old → new.
+4. One ledger entry for the batch:
+   `fusion log classified "<scope> — <field>: <value> (<N> documents)"
+   --bucket <root> --as <you>` then `fusion index <root>` (summaries
+   unchanged, but titles/auroras may have moved in the index) and
+   `fusion check <root>`.

fusion/_skills/fusion-librarian/scripts/link-repair.py

@@ -0,0 +1,371 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.11"
+# dependencies = [
+#   "PyYAML>=6.0",
+# ]
+# ///
+"""fusion-librarian link repair — scan proposes, the human approves, apply
+signs off.
+
+Productizes the pattern run by hand during the 2026-07-10 delivery: 67
+broken relative links repaired across two passes on a real bucket
+(docs/dogfood/frictions.md row 7). `scan` never writes — it walks
+library/ and activities/, finds relative links whose target does not
+exist from the doc's own directory, and proposes a repair by basename
+match against sources/ + the doc zones: a UNIQUE basename match is
+`exact`; a unique match only after lowercase/hyphen-insensitive
+normalization is `fuzzy` — never silently folded into an exact batch;
+two or more candidates is `unrepairable` (never guess between them).
+
+`apply` rewrites ONLY the pairs the human hands back in an approved
+proposals file, validating every pair (doc inside library/ or
+activities/, target exists, no path escapes the bucket) BEFORE writing
+any of them — the intake gate's validate-before-damage discipline. It
+writes no ledger entry: the gear's protocol (references/cross-reference.md)
+has the operator sign one `noted` for the pass and re-run `fusion
+index`/`fusion check`.
+
+Usage:
+    uv run link-repair.py scan --bucket <bucket-root> > proposals.json
+    uv run link-repair.py apply --bucket <bucket-root> --proposals <file.json>
+"""
+import argparse
+import json
+import os
+import re
+import sys
+from datetime import datetime
+from pathlib import Path
+
+import yaml
+
+TODAY = datetime.now().strftime("%Y-%m-%d")
+
+# Documents that can carry broken links worth repairing — never output/
+# (deliverables are frozen) and never a zone outside the doc format.
+DOC_ZONES = ("library", "activities")
+
+# Where a repair candidate may be found: the doc zones themselves (a link
+# that drifted to a sibling that moved) plus sources/ (the assets/X ->
+# sources/... pattern proven live).
+SEARCH_ZONES = ("sources", "library", "activities")
+
+# Registers with a single writer elsewhere — never a link-repair target
+# or a document to scan for links.
+SKIP_NAMES = {"MANIFEST.md", "INDEX.md"}
+
+# `](target)` — target's first char excludes ')' and '#' so bare anchor
+# links ([x](#heading)) never match; http(s)/mailto are filtered after,
+# by scheme, since they share the same bracket-paren shape.
+LINK_RE = re.compile(r"\]\(([^)#][^)]*)\)")
+_SCHEME_RE = re.compile(r"^[a-zA-Z][a-zA-Z0-9+.-]*:")
+
+# Code is not prose: fenced blocks and inline code spans never carry a
+# real relative link, so they're blanked out before extraction — the
+# same fix as cli/src/fusion/document.py's `_blank_code` (twin
+# implementation, kept independent so this skill stays self-contained).
+_FENCE_OPEN_RE = re.compile(r"^(\s*)(`{3,}|~{3,})")
+_INLINE_CODE_RE = re.compile(r"(`+)((?:(?!\1)[^\n])*?)\1")
+
+
+def _blank_code(body: str) -> str:
+    """Blank fenced blocks (opener to closer inclusive, unterminated
+    fences swallow to EOF) and single-line inline code spans, replacing
+    each with equal-length whitespace so link extraction never reads
+    code as prose. Inline spans use a run of N backticks as delimiter
+    (CommonMark's literal-backtick idiom, e.g.
+    `` `` `code with ` backtick` `` ``), closing only on the next run of
+    the SAME length, so a shorter backtick run inside the span is just
+    content, not a terminator."""
+    lines = body.split("\n")
+    out = []
+    i = 0
+    n = len(lines)
+    while i < n:
+        opener = _FENCE_OPEN_RE.match(lines[i])
+        if not opener:
+            out.append(lines[i])
+            i += 1
+            continue
+        fence_char, fence_len = opener.group(2)[0], len(opener.group(2))
+        closer_re = re.compile(
+            r"^\s*" + re.escape(fence_char) + "{" + str(fence_len) + ",}\\s*$"
+        )
+        out.append(" " * len(lines[i]))
+        i += 1
+        while i < n:
+            out.append(" " * len(lines[i]))
+            closed = bool(closer_re.match(lines[i]))
+            i += 1
+            if closed:
+                break
+    blanked = "\n".join(out)
+    return _INLINE_CODE_RE.sub(lambda m: " " * len(m.group(0)), blanked)
+
+
+class RepairError(Exception):
+    """Strict-writer refusal — named loudly, never silently skipped."""
+
+
+# ── discovery ────────────────────────────────────────────────────────────
+
+def _iter_files(zone_dir: Path):
+    for p in sorted(zone_dir.rglob("*")):
+        if not p.is_file() or p.name in SKIP_NAMES:
+            continue
+        rel = p.relative_to(zone_dir)
+        if any(part.startswith(".") for part in rel.parts):
+            continue
+        yield p
+
+
+def _iter_docs(root: Path):
+    """Every .md in library/ and activities/, skipping dot-dirs and the
+    generated INDEX.md — hand-editing a register is never on the table."""
+    for zone in DOC_ZONES:
+        zone_dir = root / zone
+        if not zone_dir.is_dir():
+            continue
+        for p in _iter_files(zone_dir):
+            if p.suffix.lower() == ".md":
+                yield p
+
+
+def _normalize(name: str) -> str:
+    """Lowercase, hyphen-insensitive basename key: case differences and
+    hyphen placement collapse to the same key (amua-map.png and
+    a-mua-map.png both key to 'amuamap.png') — a fuzzy match, extension
+    still required so unrelated files never collide."""
+    stem = Path(name).stem.lower().replace("-", "")
+    ext = Path(name).suffix.lower()
+    return f"{stem}{ext}"
+
+
+def _index_candidates(root: Path):
+    """basename -> [bucket-relative paths] and normalized-basename ->
+    [...] over sources/ + the doc zones — the search space link-repair
+    is allowed to propose targets from."""
+    exact: dict[str, list[Path]] = {}
+    normalized: dict[str, list[Path]] = {}
+    for zone in SEARCH_ZONES:
+        zone_dir = root / zone
+        if not zone_dir.is_dir():
+            continue
+        for p in _iter_files(zone_dir):
+            rel = p.relative_to(root)
+            exact.setdefault(p.name, []).append(rel)
+            normalized.setdefault(_normalize(p.name), []).append(rel)
+    return exact, normalized
+
+
+def _extract_links(text: str):
+    """Yield (raw_target, path_part, anchor) for every candidate relative
+    link — http(s)/mailto skipped by scheme, anchor-only already excluded
+    by LINK_RE's negative first-char class, and fenced/inline code
+    blanked first so code is never read as prose."""
+    for m in LINK_RE.finditer(_blank_code(text)):
+        target = m.group(1)
+        if _SCHEME_RE.match(target):
+            continue
+        path_part, _, anchor = target.partition("#")
+        if not path_part:
+            continue
+        yield target, path_part, anchor
+
+
+# ── scan ─────────────────────────────────────────────────────────────────
+
+def scan(root: Path) -> dict:
+    root = Path(root)
+    exact_idx, normalized_idx = _index_candidates(root)
+    proposals, unrepairable = [], []
+
+    for doc in _iter_docs(root):
+        doc_rel = doc.relative_to(root).as_posix()
+        text = doc.read_text(encoding="utf-8", errors="replace")
+        for raw_target, path_part, anchor in _extract_links(text):
+            if (doc.parent / path_part).exists():
+                continue  # not broken
+
+            basename = Path(path_part).name
+            candidates = exact_idx.get(basename, [])
+            confidence = None
+            chosen = None
+            if len(candidates) == 1:
+                confidence, chosen = "exact", candidates[0]
+            else:
+                norm_candidates = normalized_idx.get(_normalize(basename), [])
+                if len(norm_candidates) == 1:
+                    confidence, chosen = "fuzzy", norm_candidates[0]
+
+            if chosen is None:
+                unrepairable.append({"doc": doc_rel, "link": raw_target})
+                continue
+
+            new_path = os.path.relpath(root / chosen, start=doc.parent)
+            target = new_path.replace(os.sep, "/") + (f"#{anchor}" if anchor else "")
+            proposals.append({
+                "doc": doc_rel, "link": raw_target,
+                "target": target, "confidence": confidence,
+            })
+
+    return {"proposals": proposals, "unrepairable": unrepairable}
+
+
+def _print_table(result: dict) -> None:
+    exact = [p for p in result["proposals"] if p["confidence"] == "exact"]
+    fuzzy = [p for p in result["proposals"] if p["confidence"] == "fuzzy"]
+
+    def _rows(items):
+        for p in items:
+            print(f"  {p['doc']}: {p['link']} -> {p['target']}", file=sys.stderr)
+
+    print(f"EXACT ({len(exact)}) — safe to apply as-is", file=sys.stderr)
+    _rows(exact)
+    print(f"\nFUZZY ({len(fuzzy)}) — normalized match only, "
+          "confirm per group before applying", file=sys.stderr)
+    _rows(fuzzy)
+    print(f"\nUNREPAIRABLE ({len(result['unrepairable'])}) — "
+          "ambiguous or no candidate, never guessed", file=sys.stderr)
+    for u in result["unrepairable"]:
+        print(f"  {u['doc']}: {u['link']}", file=sys.stderr)
+
+
+# ── apply ────────────────────────────────────────────────────────────────
+
+def _split_frontmatter(text: str, doc_rel: str):
+    if not text.startswith("---\n"):
+        raise RepairError(f"no frontmatter block: {doc_rel}")
+    try:
+        end = text.index("\n---", 4)
+    except ValueError:
+        raise RepairError(f"unterminated frontmatter block: {doc_rel}") from None
+    fm = yaml.safe_load(text[4:end])
+    if not isinstance(fm, dict):
+        raise RepairError(f"frontmatter is not a mapping: {doc_rel}")
+    return fm, text[end + 4:]
+
+
+def _bump_updated(text: str, doc_rel: str) -> str:
+    fm, rest = _split_frontmatter(text, doc_rel)
+    fm["updated"] = TODAY
+    front = yaml.safe_dump(fm, sort_keys=False, allow_unicode=True,
+                           width=2**31 - 1)
+    return f"---\n{front}---{rest}"
+
+
+def apply_proposals(root: Path, proposals: list) -> int:
+    """Rewrite ONLY the given (doc, link) -> target pairs. Validates every
+    pair — doc under library/ or activities/, doc not a single-writer
+    register (SKIP_NAMES), doc exists, the literal `](link)` text is
+    present, target resolves inside the bucket and exists on disk, AND the
+    doc's frontmatter parses — BEFORE writing any file
+    (validate-all-before-damage, the intake gate's rule applied here). The
+    frontmatter check runs in phase 1 specifically so a later doc's
+    malformed frontmatter can never be discovered mid-write, after an
+    earlier doc in the same batch was already rewritten: phase 2's own
+    _bump_updated call stays as a safety net, but by construction it can
+    no longer raise."""
+    root = Path(root).resolve()
+    zone_roots = {zone: (root / zone).resolve() for zone in DOC_ZONES}
+
+    # ── phase 1: validate every pair, read but never write ───────────────
+    plan: dict[Path, list[tuple[str, str]]] = {}
+    doc_texts: dict[Path, str] = {}
+    frontmatter_checked: set[Path] = set()
+    for i, p in enumerate(proposals):
+        doc_rel = p["doc"]
+        link = p["link"]
+        target = p["target"]
+        doc_path = (root / doc_rel).resolve()
+        if doc_path.name in SKIP_NAMES:
+            raise RepairError(
+                f"proposals[{i}]: refuses a single-writer register, "
+                f"never a repair target (skip: {doc_rel!r})")
+        if not any(doc_path.is_relative_to(z) for z in zone_roots.values()):
+            raise RepairError(
+                f"proposals[{i}]: doc outside library/ or activities/: "
+                f"{doc_rel!r}")
+        if not doc_path.is_file():
+            raise RepairError(f"proposals[{i}]: doc does not exist: {doc_rel!r}")
+
+        target_path_part, _, _ = target.partition("#")
+        target_abs = (doc_path.parent / target_path_part).resolve()
+        if not target_abs.is_relative_to(root):
+            raise RepairError(
+                f"proposals[{i}]: target escapes the bucket: {target!r}")
+        if not target_abs.is_file():
+            raise RepairError(
+                f"proposals[{i}]: target does not exist: {target!r} "
+                f"(doc {doc_rel!r})")
+
+        text = doc_texts.setdefault(doc_path, doc_path.read_text(encoding="utf-8"))
+        if f"]({link})" not in text:
+            raise RepairError(
+                f"proposals[{i}]: link text not found verbatim in "
+                f"{doc_rel!r}: {link!r}")
+
+        if doc_path not in frontmatter_checked:
+            # Raises RepairError (unparseable/missing frontmatter) before
+            # any document in this batch has been written — the same
+            # parse _bump_updated would otherwise only attempt in phase 2,
+            # by which point earlier docs could already be on disk.
+            _split_frontmatter(text, doc_rel)
+            frontmatter_checked.add(doc_path)
+
+        plan.setdefault(doc_path, []).append((link, target))
+
+    # ── phase 2: execute — every pair already validated ───────────────────
+    changed = 0
+    for doc_path, edits in plan.items():
+        rel = doc_path.relative_to(root).as_posix()
+        text = doc_texts[doc_path]
+        new_text = text
+        for link, target in edits:
+            new_text = new_text.replace(f"]({link})", f"]({target})")
+        if new_text != text:
+            new_text = _bump_updated(new_text, rel)
+            doc_path.write_text(new_text, encoding="utf-8", newline="\n")
+            changed += 1
+    return changed
+
+
+# ── CLI ──────────────────────────────────────────────────────────────────
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(
+        description="fusion-librarian link-repair: scan / apply")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    p = sub.add_parser("scan", help="propose repairs for broken relative "
+                       "links in library/ and activities/")
+    p.add_argument("--bucket", required=True)
+
+    p = sub.add_parser("apply", help="apply an approved subset of a "
+                       "scan's proposals")
+    p.add_argument("--bucket", required=True)
+    p.add_argument("--proposals", required=True,
+                   help="JSON file: {\"proposals\": [...]} or a bare list")
+
+    args = ap.parse_args(argv)
+    root = Path(args.bucket).expanduser()
+
+    try:
+        if args.cmd == "scan":
+            result = scan(root)
+            _print_table(result)
+            print(json.dumps(result, indent=2, ensure_ascii=False))
+        else:
+            payload = json.loads(Path(args.proposals).read_text(encoding="utf-8"))
+            proposals = payload["proposals"] if isinstance(payload, dict) else payload
+            changed = apply_proposals(root, proposals)
+            print(json.dumps({"changed": changed}, indent=2, ensure_ascii=False))
+    except RepairError as exc:
+        print(f"link-repair: {exc}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

fusion/_skills/fusion-planner/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: fusion-planner
+description: "The Fusion planner — the horizon keeper. The human drives activities; the planner structures them. Three gears: create-activity (a new activity folder with a stateful plan document — works for plans, campaigns, programs, agendas alike), horizon (review what's live: stalled activities, expiring commitments, what fusion today will show tomorrow), close (finish an activity: status done, archived, out of the way). Use for 'new project/activity/campaign', 'plan this', 'what's on my plate', 'review my activities', 'what's stalled', 'agenda', 'close/finish this activity'. For placing knowledge use fusion-librarian; for deliverables 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-planner — the horizon
+
+Activities are live work: folders under `activities/`, stateful documents,
+honest statuses. The planner keeps the horizon true — what `fusion today`
+composes tomorrow morning is this skill's report card.
+
+Read `references/fusion-conventions.md` once per session; read the
+bucket's `BUCKET.md ## Conventions` before acting. 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
+
+| Signal | Gear | Load |
+|---|---|---|
+| new activity / plan / campaign / program / agenda | create-activity | references/create-activity.md |
+| what's live / stalled / on my plate / review activities (default) | horizon | references/horizon.md |
+| close / finish / wrap up an activity | close | references/close.md |
+
+The default is **horizon** — read-mostly: it reports freely and writes
+only on a yes. close moves files; reached by inference, it stops and
+confirms.
+
+## The activity shape
+
+```
+activities/<slug>/
+├── plan.md          # the stateful heart: status, dates, aurora
+└── …                # notes, briefs — documents, same rules
+```
+
+`plan.md` frontmatter: the three required fields, plus `status:`
+(`active` | `done` | `dormant`) and `due:` (ISO date) when a real deadline
+exists. Aurora speaks for attention: `commitments` when promised,
+`focus` when it is the deep work, `collab` when shared, `explore` when
+tentative. Expandability is the shape, not machinery: a campaign is an
+activity whose plan has phases; an agenda is an activity whose plan is
+dated items.
+
+## Ledger discipline
+
+| Act | Verb |
+|---|---|
+| new activity | `created` |
+| status change (active ⇄ dormant, honest corrections) | `noted` with the change in the note |
+| close | `archived` |
+
+Always `--bucket <root> --as <you>`, then `fusion index <root>` and
+`fusion check <root>` green.
+
+## Never
+
+- Never let a dead activity keep `status: active` — the horizon lies.
+- Never set `due:` the human didn't state or clearly imply.
+- Never hand-edit the registers.

fusion/_skills/fusion-planner/references/close.md

@@ -0,0 +1,12 @@
+# close — done, kept, out of the way
+
+1. Confirm the target activity and that the human means finished (or a
+   Delegation covers routine closes). State the plan in one sentence.
+2. Edit `plan.md` (and any sibling documents): `status: done`,
+   `aurora: archive`. Add a final Log line summarizing the outcome.
+3. Move the whole folder to `activities/archive/<slug>/`.
+4. `fusion log archived "activities/<slug>/ → activities/archive/<slug>/"
+   --bucket <root> --as <you>` · `fusion index <root>` ·
+   `fusion check <root>` green — path and aurora agree or W3 objects.
+5. If deliverables shipped from this activity, remind the human where
+   they live in `output/` (the analyst's ledger entries say).

fusion/_skills/fusion-planner/references/create-activity.md

@@ -0,0 +1,38 @@
+# create-activity — structure the human's intent
+
+1. Get the essentials from the conversation: name (→ slug), what done
+   looks like, deadline (if promised), who else is involved. Ask only
+   what the human hasn't said.
+2. Choose aurora: promised-with-deadline → `commitments`; the current
+   deep work → `focus`; shared → `collab`; tentative → `explore`. Say
+   which and why in one line.
+3. Create `activities/<slug>/plan.md`:
+
+   ```markdown
+   ---
+   title: <name>
+   type: plan
+   aurora: <chosen>
+   status: active
+   created: <today>
+   due: <date, only if real>
+   ---
+
+   ## Summary
+
+   <what this activity is and what done looks like, 2–3 lines>
+
+   ---
+
+   ## Steps
+
+   - [ ] <the first concrete steps, from the conversation>
+
+   ## Log
+
+   - <today> — created.
+   ```
+
+4. `fusion log created "activities/<slug>/plan.md" --bucket <root>
+   --as <you>` · `fusion index <root>` · `fusion check <root>` green.
+   Then show the human what `fusion today` now includes.

fusion/_skills/fusion-planner/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-planner/references/horizon.md

@@ -0,0 +1,20 @@
+# horizon — keep today honest
+
+Read-mostly; proposes, changes nothing without a yes.
+
+1. `fusion agenda` — dated items and undated actives across buckets;
+   `fusion today` — the attention view; `fusion status <root> --since
+   last-reflection` for the recent pulse of this bucket.
+2. Read `activities/INDEX.md` + each active plan's summary. For each
+   active activity judge: moving (recent ledger touches), **stalled**
+   (active but untouched — W5's territory), **expiring** (due within a
+   week), **done-in-fact** (finished but never closed).
+3. Report the horizon in four short lists with paths and dates. No
+   invented urgency: expiring means a real `due:`, stalled means real
+   silence.
+4. Propose the honest corrections: dormant flips, closes, due-date fixes.
+   On yes: edit the frontmatter, `fusion log noted "activities/<slug> —
+   status: active → dormant" --bucket <root> --as <you>` per flip
+   (several flips confirmed in one pass may share one `noted` line
+   naming them all) · `fusion index <root>` · `fusion check <root>`.
+   Closes go through the close gear.