beadhive 0.1.0__py3-none-any.whl

beadhive/__init__.py

@@ -0,0 +1 @@
+"""ws — workspace beads CLI (per-repo rigs + workspace hydration)."""

beadhive/adopt.py

@@ -0,0 +1,143 @@
+"""`ws plan adopt` — seed a plan FRAME from promoted intake report(s).
+
+The planning-plane ADOPT path (epic, bead). It is the
+planner-side consumer of the triage promote disposition: a report handed
+to the planner carries ``intake:promoted`` (``state.is_promoted``), and ``adopt`` fleshes it into
+the opening FRAME of a molecule spec — the epic seed a planner then decomposes into issues and
+files via ``ws plan file``. It is source-agnostic: any channel (report / github / import) that
+was promoted is adoptable.
+
+Two provenance facets carry through to the filed epic (see ``ws/state.py``):
+
+  * **System-of-record** — the NATIVE ``source_system`` + ``external_ref`` pair (e.g. github /
+    ``gh-9``) survives onto the epic so a GitHub-sourced request stays traceable. ``source_system``
+    is settable only at bead birth, so an adopted epic that carries it is born via ``bd import``
+    (``plan._create_epic``); ``bd create``/``update`` expose no flag for it.
+  * **Originating link** — on ``ws plan file`` each origin report is linked as CHILD-OF the epic
+    (report depends-on epic, ``parent-child``). The epic OWNS the report, never the reverse — so
+    the report is NEVER a blocker of the epic (it can't wrongly gate the molecule on an open
+    report) and it rides the epic to completion. A ``blocks`` edge is not usable here: bd forbids
+    blocking dependencies between an epic and a task, so ``parent-child`` is the sanctioned link.
+
+This module is Typer-free and bd-free — pure spec shaping over already-read bead JSON. ``plan.py``
+owns the CLI verb plus every bd read/write (the ``plan.run`` test seam), so the two planes share
+one subprocess seam and the shaping logic stays trivially unit-testable.
+"""
+
+from __future__ import annotations
+
+from . import state
+
+# Native system-of-record provenance fields carried from an origin report onto the filed epic.
+PROVENANCE_FIELDS = ("source_system", "external_ref")
+
+
+class AdoptError(Exception):
+    """Frame seeding failed (e.g. no beads to adopt). Typer-free; the CLI maps it to exit 1."""
+
+
+# ---- frame seeding (pure; over bead JSON already read by the caller) ---------
+
+
+def _seed_title(beads: list[dict]) -> str:
+    """The seed epic title: ``Adopt: <first report title>`` (+ a count when several are folded)."""
+    first = str(beads[0].get("title") or beads[0].get("id") or "untitled").strip()
+    extra = len(beads) - 1
+    suffix = f" (+{extra} more)" if extra > 0 else ""
+    return f"Adopt: {first}{suffix}"
+
+
+def _seed_description(beads: list[dict]) -> str:
+    """Seed the epic description from the report text(s) so the planner opens with the full ask."""
+    lines = ["Adopted from promoted intake report(s):", ""]
+    for bead in beads:
+        bid = str(bead.get("id") or "?")
+        title = str(bead.get("title") or "").strip()
+        lines.append(f"- {bid}: {title}".rstrip())
+        body = str(bead.get("description") or "").strip()
+        if body:
+            lines.append(f"  {body}")
+    return "\n".join(lines)
+
+
+def _provenance(beads: list[dict]) -> tuple[str, str]:
+    """The system-of-record provenance to carry onto the epic: the ``(source_system, external_ref)``
+    of the FIRST report that carries either (a GitHub-sourced report keeps its ``gh-<n>`` trace).
+    ``('', '')`` when no report carries native provenance (a born-native cross-rig report)."""
+    for bead in beads:
+        source_system = str(bead.get("source_system") or "").strip()
+        external_ref = str(bead.get("external_ref") or "").strip()
+        if source_system or external_ref:
+            return source_system, external_ref
+    return "", ""
+
+
+def frame_from_beads(beads: list[dict]) -> dict:
+    """Build the seed molecule FRAME (epic seed + empty ``issues``) from promoted report bead(s).
+
+    The epic records the originating report id(s) under ``adopts`` and any native provenance under
+    ``source_system`` / ``external_ref``; ``ws plan file`` reads these to link + carry them. Issues
+    are left empty for the planner to decompose. Typer-free; raises ``AdoptError`` on empty input.
+    """
+    if not beads:
+        raise AdoptError("no intake beads to adopt")
+    epic: dict = {
+        "title": _seed_title(beads),
+        "description": _seed_description(beads),
+        "adopts": [str(b.get("id")) for b in beads if b.get("id")],
+    }
+    source_system, external_ref = _provenance(beads)
+    if source_system:
+        epic["source_system"] = source_system
+    if external_ref:
+        epic["external_ref"] = external_ref
+    return {"epic": epic, "issues": []}
+
+
+# ---- file-time helpers (read by plan.file_molecule; pure) --------------------
+
+
+def adopts_of(epic: dict) -> list[str]:
+    """The originating report id(s) an adopted epic links back to (``[]`` when not adopted)."""
+    return [str(x) for x in (epic.get("adopts") or []) if str(x).strip()]
+
+
+def provenance_of(epic: dict) -> tuple[str, str]:
+    """The ``(source_system, external_ref)`` provenance declared on an epic (``''`` when unset)."""
+    return (
+        str(epic.get("source_system") or "").strip(),
+        str(epic.get("external_ref") or "").strip(),
+    )
+
+
+def epic_import_record(epic: dict, labels: list[str]) -> dict:
+    """A ``bd import`` JSONL record that BIRTHS the epic carrying native provenance.
+
+    ``source_system`` can only be set when a bead is created, so a provenance-carrying epic is
+    imported rather than ``bd create``-d. Carries title/type + description/design + the identity
+    triplet labels + the native ``source_system`` / ``external_ref`` pair.
+    """
+    record: dict = {"title": str(epic.get("title") or ""), "issue_type": "epic"}
+    for key in ("description", "design"):
+        val = str(epic.get(key) or "").strip()
+        if val:
+            record[key] = val
+    source_system, external_ref = provenance_of(epic)
+    if source_system:
+        record["source_system"] = source_system
+    if external_ref:
+        record["external_ref"] = external_ref
+    if labels:
+        record["labels"] = list(labels)
+    return record
+
+
+# ---- read-side: distinguish an origin report from a work sibling -------------
+
+
+def is_origin_report(labels) -> bool:
+    """True for an ADOPTED origin report linked under an epic — a promoted intake bead
+    (``intake:promoted``) or one carrying an ``origin:`` channel label. Used to keep origin reports
+    OUT of the molecule's work-sibling set (they carry no acceptance and demand no kickoff gate)
+    while still surfacing them in ``ws plan show``."""
+    return state.is_promoted(labels) or state.origin_of(labels) is not None

beadhive/archive.py

@@ -0,0 +1,165 @@
+"""archive.py — list and prune the soft-archive graveyard created by ``ws rig retire``.
+
+``ws rig retire`` moves retired clones into ``archive.dir`` (default
+``$GIT_WORKSPACE/.archived``) under a ``<provider>/<org>/<repo>`` subpath.  This module
+provides the read and reclaim commands:
+
+- ``list_archived(archive_dir)``  → ``list[ArchivedRepo]`` sorted by descending age.
+- ``prune_archived(archive_dir, *, older_than_days, all, dry_run)`` → ``PruneResult``.
+
+Guard: ``prune_archived`` resolves every candidate path and asserts it is strictly inside
+``archive_dir`` before calling ``shutil.rmtree`` — so a misconfigured or symlinked
+``archive.dir`` can never cause collateral damage outside the graveyard.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _dir_size(path: Path) -> int:
+    """Recursively sum the sizes of all files under ``path``."""
+    total = 0
+    try:
+        for root, _dirs, files in os.walk(path):
+            for f in files:
+                try:
+                    total += (Path(root) / f).stat().st_size
+                except OSError:
+                    pass
+    except (OSError, PermissionError):
+        pass
+    return total
+
+
+def _age_days(path: Path) -> float:
+    """Age of ``path`` in fractional days (mtime-based)."""
+    try:
+        mtime = path.stat().st_mtime
+    except OSError:
+        return 0.0
+    return (time.time() - mtime) / 86400.0
+
+
+# ---------------------------------------------------------------------------
+# Data types
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class ArchivedRepo:
+    """One archived clone entry under ``archive_dir``."""
+
+    path: Path
+    """Absolute path of the archived clone (``<archive_dir>/<provider>/<org>/<repo>``)."""
+
+    triplet: str
+    """``<provider>/<org>/<repo>`` — the human-readable identity."""
+
+    age_days: float
+    """Fractional days since the directory was last modified (mtime)."""
+
+    size_bytes: int
+    """Total size of all files under the clone directory."""
+
+
+@dataclass
+class PruneResult:
+    """Outcome of ``prune_archived``."""
+
+    removed: list[str] = field(default_factory=list)
+    """Triplets removed (or would-remove under dry-run)."""
+
+    reclaimed_bytes: int = 0
+    """Total bytes freed (0 on dry-run — nothing was actually removed)."""
+
+    dry_run: bool = False
+
+
+# ---------------------------------------------------------------------------
+# Core logic
+# ---------------------------------------------------------------------------
+
+
+def list_archived(archive_dir: Path) -> list[ArchivedRepo]:
+    """Return all ``<provider>/<org>/<repo>`` entries under ``archive_dir``, sorted by age
+    (oldest first — matches the prune ordering so the output and pruning are consistent).
+
+    Returns an empty list when ``archive_dir`` does not exist.
+    """
+    if not archive_dir.exists():
+        return []
+
+    repos: list[ArchivedRepo] = []
+    for provider_dir in sorted(archive_dir.iterdir()):
+        if not provider_dir.is_dir():
+            continue
+        for org_dir in sorted(provider_dir.iterdir()):
+            if not org_dir.is_dir():
+                continue
+            for repo_dir in sorted(org_dir.iterdir()):
+                if not repo_dir.is_dir():
+                    continue
+                triplet = f"{provider_dir.name}/{org_dir.name}/{repo_dir.name}"
+                repos.append(
+                    ArchivedRepo(
+                        path=repo_dir,
+                        triplet=triplet,
+                        age_days=_age_days(repo_dir),
+                        size_bytes=_dir_size(repo_dir),
+                    )
+                )
+    # Oldest first
+    repos.sort(key=lambda r: r.age_days, reverse=True)
+    return repos
+
+
+def prune_archived(
+    archive_dir: Path,
+    *,
+    older_than_days: float,
+    remove_all: bool = False,
+    dry_run: bool = False,
+) -> PruneResult:
+    """Remove archived repos that are older than ``older_than_days`` days.
+
+    When ``remove_all`` is True, every archived repo is removed regardless of age.
+    When ``dry_run`` is True, nothing is mutated — the result reports what *would* be removed
+    and the total bytes that would be reclaimed.
+
+    Path-escape guard: each candidate path is resolved and checked to be strictly under the
+    resolved ``archive_dir`` before any ``shutil.rmtree`` call.  A repo path that escapes the
+    archive dir is silently skipped (never deleted).
+    """
+    result = PruneResult(dry_run=dry_run)
+    repos = list_archived(archive_dir)
+    resolved_root = archive_dir.resolve()
+
+    for repo in repos:
+        if not remove_all and repo.age_days < older_than_days:
+            continue
+
+        # Path-escape guard: resolve first, then check containment.
+        resolved_path = repo.path.resolve()
+        try:
+            resolved_path.relative_to(resolved_root)
+        except ValueError:
+            # Path escapes archive_dir — skip unconditionally.
+            continue
+
+        size = repo.size_bytes
+        result.removed.append(repo.triplet)
+
+        if not dry_run:
+            shutil.rmtree(resolved_path, ignore_errors=True)
+            result.reclaimed_bytes += size
+
+    return result

beadhive/assets/AGF-hint.md

@@ -0,0 +1,10 @@
+<!-- bh:agf:start (managed by `bh rig init` — edit outside these markers; `-f` refreshes) -->
+## AGF — Agentic Git Flow
+
+This repo is onboarded as a **`bh` rig** and develops via **AGF**: work is tracked in beads
+and driven through `bh`, **not** raw `git` / `bd` / `gh`.
+
+- **Is this repo set up for AGF?** → run `bh rig ready` (add `-v` for the line-item breakdown).
+- **Lifecycle, roles, conventions:** see `.beads/PRIME.md` and `docs/AGF.md`.
+- Drive beads with `bh work`; load the role skill for your seat (coordinator / developer / merger).
+<!-- bh:agf:end -->

beadhive/assets/PRIME.md

@@ -0,0 +1,131 @@
+# Beads + bh work — repo conventions
+
+This repo tracks work with **bd** (beads) and integrates it with git through **`bh`**. Two
+rules before anything else:
+
+- **Drive the lifecycle with `bh work`, not raw `bd` / `git`.** `bh work` takes a bead from
+  assigned → merged and applies this repo's config defaults (identity, commit signing,
+  validation, review gate) for you.
+- **Read beads with the first-class verbs** — `bh work ready|issue|list` (dependency-ordered,
+  byte/JSON-stable output), not raw `bd` queries.
+- **File epics/molecules with `bh plan file`, never hand-create them with `bh bd create`.** The
+  planner compiler builds the full envelope a dispatcher needs to dispatch — the
+  `provider:`/`org:`/`repo:` triplet + dimension labels, the bd swarm, and a per-root kickoff
+  gate — which a hand-rolled `bh bd create` epic lacks.
+- **`bh bd` is a gated last-resort fallback**, off by default (`passthrough.bd_enabled`): it
+  exits non-zero with a steering message until you set `WS_BD_PASS_ENABLED=1` (or `WS_DEBUG=1`).
+  Reach for it only for one-off issue surgery the convention verbs above don't cover.
+- **Raw `git` is only for local work** — the actual change *inside* a worktree. Never use
+  raw `git` / `bd` / `gh` to drive the lifecycle (claim, submit, merge), or you bypass the
+  defaults the tooling sets up for you.
+
+Beads is **issues only** — knowledge/memory lives in the project's own system (no
+`bd remember`).
+
+## Load the skill for your role
+
+Each role skill states its duties and the verbs it uses; all of them build on the shared
+**`work`** skill (the `bh work` verb reference).
+
+| Role | Identity | Alias | Skill | Duty |
+|---|---|---|---|---|
+| Dispatcher | `disp/` | overseer | `dispatcher` | deliver an epic: assign beads to developers, watch gates, re-dispatch (collapsed mode inlines the implementation) |
+| Developer | `dev/` | polecat | `developer` | take one assigned bead to a reviewable state |
+| Reviewer | `rev/` | — | `reviewer` | walk an approved branch, resolve or bounce the review gate |
+| Merger | `merge/` | the Refinery | `merger` | serialize merges to the integration branch, preserve history |
+
+The full seat roster (Control supervisor/director/custodian/controller, Planning planner/analyst,
+Assurance warden) is in the canon `docs/design/roles-rbac-matrix.md`. Gas-Town names are optional,
+non-normative aliases.
+
+## Conventions
+
+- Every issue's home is the `provider:`/`org:`/`repo:` triplet — `bh plan file` injects it when
+  it compiles a molecule; `bh labels validate` checks it. Dependencies are declared in the
+  molecule spec (`deps:`) and filed by `bh plan file`, not hand-added.
+- `bh plan verify <epic>` is the planner's done-gate: it checks a filed molecule against the
+  planning-plane conventions (bd swarm, per-root kickoff gate, triplet + closed-dimension
+  labels) — the same check `bh work start`/`assign`/`claim` run before dispatch.
+- `bh work` reads per-rig defaults from config — load the `work` skill for details.
+
+### Intake + outbound state vocabulary
+
+Cross-rig report state (epic) is modelled with native
+`bd set-state <bead> <dim>=<value>` (event-sourced, with the `<dim>:<value>` label cache),
+**never ad-hoc labels**. The module `beadhive/state.py` is the single owner of the closed
+vocabulary — downstream beads reuse it rather than re-inventing states:
+
+| Dimension | Value | Meaning |
+|---|---|---|
+| `intake` | `untriaged` | untriaged inbound — set when a report lands, **cleared on triage** |
+| `intake` | `accepted` / `rejected` / `rerouted` / `promoted` | the terminal value a triage disposition transitions to (clears `untriaged`) |
+| `outbound` | `pending` | staged outbound candidate — captured with **zero public exposure** |
+| `publish` | `approved` | the contributor filed it upstream (behind the human publish gate) |
+| `origin` | `report` \| `github` \| `import` | the intake **CHANNEL** a bead entered through — a durable, source-agnostic provenance tag (orthogonal to the `intake` *queue* state) |
+
+These are registered as **closed dimensions** (`beadhive/state.py:STATE_DIMENSIONS`, merged in by
+`registry.closed_dimensions`), so intake/outbound/origin beads validate clean under `bh labels
+validate` and an unknown value (e.g. `outbound:bogus`, `origin:carrier-pigeon`) is rejected.
+Queue predicates `state.is_untriaged_intake(labels)` / `state.is_promoted(labels)` /
+`state.is_outbound_candidate(labels)` drive the triage, planner-adopt, and contributor queues;
+`state.channel_of(labels, source_system)` (label-first, else derived from `source_system`) /
+`state.origin_of(labels)` / `state.is_report_origin` resolve the intake channel.
+
+**Provenance convention — THREE orthogonal facets (operator-approved, epic):**
+
+1. **System-of-record** = the **native** `source_system` + `external_ref` pair — bd's "mirrors
+   an external system of record" coupling, settable only at import. Reserved for **external
+   mirrors** (github / legacy import); a born-native report **never** overloads it.
+2. **Intake channel** = the closed `origin` dimension above (set via `bd set-state origin=…`,
+   like `intake`). `bh report` files via **plain `bd create` + `bd set-state origin=report`** —
+   this retired the old `import` + `source_system=report` workaround (follow-up).
+   Imported beads keep their native `source_system`; `state.origin_from_source_system(...)` derives
+   their channel on **read** (a uniform triage queue) **without** re-stamping an `origin` label.
+3. **Reporter identity** = `bd --actor` (unchanged) — **never** a closed label (`reported-by` is
+   open-ended and would fail `bh labels validate`). Do not add a reporter label dimension.
+
+### Fielding intake (triage duty)
+
+Incoming reports must be **fielded, not buried in backlog**. The queue is **source-agnostic**:
+`bh report` (`origin:report`), GitHub-issue import (`github`) and legacy import (`import`) all land
+as `intake:untriaged` and share **one** triage queue. The **intake CHANNEL** is the closed `origin`
+dimension, **not** the native `source_system`: reports carry an explicit `origin:report` label,
+while imported beads derive their channel from `source_system` on read
+(`state.channel_of` / `origin_from_source_system`) — uniform, no double-stamping.
+
+- **See the queue:** `bh work intake` — this rig's untriaged intake (source-agnostic; the resolved
+  `origin` channel rides each row). `--source report|github|import` narrows on that channel (not raw
+  `source_system`). `bd find-duplicates` runs on entry (`bh report`) **and** at triage, surfacing
+  likely dupes so a colliding request never buries the queue.
+- **See the fleet:** `bh hq intake` — the director's fleet-wide inbox (untriaged intake
+  across every rig).
+- **Dispose (type-aware):**
+  - `bh work accept <id> [--type T] [--priority P]` — set type/priority, clear intake → backlog.
+  - `bh work reject <id> --reason "…"` — close with a reporter-visible reason.
+  - `bh work reroute <id> --to <rig>` — re-file a mis-routed report into the right rig; or
+    `--super <seat>` to bounce it to the director (stays in the fleet-wide inbox).
+  - `bh work promote <id>` — hand to the planner (sets `intake:promoted`, the adopt queue key;
+    the planner adopts it into a gated epic molecule).
+
+- **Future follow-up:** cross-rig `bh hq` interchange (`bh plan` / `bh work --rig <id>`) is not
+  wired yet.
+
+### Escalation chain (flat-MVP)
+
+The chain is flat and fire-and-forget at each rung:
+
+1. **Developer** hits a `bh` / `bd` / tool bug → `bh escalate '<what> with <tool>'` — one
+   one-liner to HQ; keep working. Do not route or investigate.
+2. **HQ** queues it as `intake:untriaged` with `origin:escalation`. The director sees it
+   via `bh hq intake` (fleet-wide inbox).
+3. **Director** is the terminal router: `bh work reroute <id> --to <rig>` re-files it
+   into the right rig; `bh work reroute <id> --super <seat>` keeps it in the fleet inbox for a
+   second look; `bh work accept/reject/promote` handle clear-cut cases.
+
+No auto-routing exists yet. The director decides where every escalation lands.
+
+**Dispatcher** fields intake for its own rig: `bh work intake` shows the rig queue;
+`accept / reject / reroute / promote` dispose of each item. Cross-rig or ambiguous items go up
+with `reroute --super`; the director picks them up from `bh hq intake`.
+
+- Run `bd prime` after compaction or in a new session to reload this context.

beadhive/assets/claude-settings.json

@@ -0,0 +1,21 @@
+{
+  "permissions": {
+    "deny": [
+      "Bash(bd remember:*)"
+    ]
+  },
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          { "type": "command", "command": "bd prime --hook-json" }
+        ]
+      }
+    ]
+  },
+  "statusLine": {
+    "type": "command",
+    "command": "ws statusline",
+    "padding": 0
+  }
+}