spine-cli 0.1.0__py3-none-any.whl

spine/__init__.py

@@ -0,0 +1,3 @@
+"""spine-cli: harness-agnostic process spine."""
+
+__version__ = "0.1.0"

spine/artifacts.py

@@ -0,0 +1,257 @@
+from __future__ import annotations
+
+import os
+import subprocess
+from datetime import datetime, timezone
+from pathlib import Path
+
+from spine.model import EXEC_ROOT, SPEC_ROOT, dump_front, load_contract, parse_front
+
+
+def _now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def identity() -> str:
+    env = os.environ.get("SPINE_USER") or os.environ.get("GIT_AUTHOR_NAME")
+    if env:
+        return env
+    try:
+        proc = subprocess.run(
+            ["git", "config", "--get", "user.name"],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        name = (proc.stdout or "").strip()
+        if proc.returncode == 0 and name:
+            return name
+    except OSError:
+        pass
+    return os.environ.get("USER") or "unknown"
+
+
+def _slug(title: str) -> str:
+    s = "".join(ch.lower() if ch.isalnum() else "-" for ch in title).strip("-")
+    while "--" in s:
+        s = s.replace("--", "-")
+    return s or "item"
+
+
+def _next_number(folder: Path) -> int:
+    n = 0
+    if not folder.exists():
+        return 1
+    for p in folder.glob("*.md"):
+        head = p.name.split("-", 1)[0]
+        if head.isdigit():
+            n = max(n, int(head))
+    return n + 1
+
+
+def new_ticket(root: Path, title: str, typ: str = "grilling") -> Path:
+    folder = root / SPEC_ROOT / "tickets"
+    folder.mkdir(parents=True, exist_ok=True)
+    num = _next_number(folder)
+    path = folder / f"{num:02d}-{_slug(title)}.md"
+    body = f"## Question\n\n{title}\n"
+    text = dump_front(
+        {"Type": typ, "Status": "open", "Blocked by": "", "Owner": "", "Claimed-at": ""},
+        body,
+        title=title,
+    )
+    path.write_text(text, encoding="utf-8")
+    return path
+
+
+def new_work_item(root: Path, title: str, profile: str = "software") -> Path:
+    folder = root / SPEC_ROOT / "work-items"
+    folder.mkdir(parents=True, exist_ok=True)
+    num = _next_number(folder)
+    path = folder / f"{num:02d}-{_slug(title)}.md"
+    body = f"## Intent\n\n{title}\n"
+    text = dump_front(
+        {
+            "Type": "work-item",
+            "Profile": profile,
+            "Status": "ready",
+            "Owner": "",
+            "Claimed-at": "",
+            "Links": "",
+            "Deliverable": "",
+        },
+        body,
+        title=title,
+    )
+    path.write_text(text, encoding="utf-8")
+    return path
+
+
+def resolve_artifact(root: Path, spec: str) -> Path:
+    p = Path(spec)
+    if p.is_absolute() and p.exists():
+        return p
+    cand = root / spec
+    if cand.exists():
+        return cand
+    for folder in ("work-items", "tickets"):
+        d = root / SPEC_ROOT / folder
+        if d.exists():
+            for f in d.glob("*.md"):
+                if spec in f.name or spec in f.stem:
+                    return f
+    raise FileNotFoundError(spec)
+
+
+def read_meta(path: Path) -> tuple[dict[str, str], str]:
+    return parse_front(path.read_text(encoding="utf-8"))
+
+
+def write_meta(path: Path, meta: dict[str, str], body: str) -> None:
+    title = meta.get("Title") or path.stem
+    path.write_text(dump_front(meta, body, title=title), encoding="utf-8")
+
+
+def _deliverable_exists(root: Path, meta: dict[str, str]) -> bool:
+    dest = (meta.get("Deliverable") or "").strip()
+    if not dest:
+        return False
+    p = Path(dest)
+    return (root / dest).exists() or p.exists()
+
+
+def _has_proof(root: Path, kind: str, stem: str) -> bool:
+    folder = root / EXEC_ROOT / kind
+    if not folder.is_dir():
+        return False
+    return any(p.is_file() and (stem in p.name or p.stem == stem) for p in folder.iterdir())
+
+
+def set_status(root: Path, spec: str, nxt: str) -> Path:
+    contract = load_contract(root)
+    path = resolve_artifact(root, spec)
+    meta, body = read_meta(path)
+    cur = meta.get("Status", "")
+    if nxt not in contract.statuses:
+        raise ValueError(f"unknown status {nxt}")
+    profile = (meta.get("Profile") or "software").lower()
+    software = profile == "software"
+    if cur == "doing" and nxt == "done" and not software:
+        if not _deliverable_exists(root, meta):
+            raise ValueError("non-software doing → done needs an existing Deliverable path")
+    elif not contract.allowed(cur, nxt):
+        raise ValueError(f"illegal transition {cur} → {nxt}")
+    if software and cur == "checking" and nxt == "reviewing":
+        if not _has_proof(root, "evals", path.stem):
+            raise ValueError("software checking → reviewing needs proof under .spine/evals/")
+    if nxt == "done" and software:
+        required = contract.software_required()
+        if cur not in {"reviewing"} and "reviewing" in required:
+            raise ValueError("software profile requires reviewing before done")
+        if not _has_proof(root, "reviews", path.stem):
+            raise ValueError("software reviewing → done needs proof under .spine/reviews/")
+    meta["Status"] = nxt
+    write_meta(path, meta, body)
+    return path
+
+
+def claim(root: Path, spec: str) -> Path:
+    path = resolve_artifact(root, spec)
+    meta, body = read_meta(path)
+    owner = meta.get("Owner") or ""
+    claimed_at = meta.get("Claimed-at") or ""
+    if owner and claimed_at and not _stale(claimed_at, root=root):
+        raise ValueError(f"already claimed by {owner} at {claimed_at}")
+    meta["Owner"] = identity()
+    meta["Claimed-at"] = _now().isoformat()
+    if meta.get("Status") == "open":
+        meta["Status"] = "claimed"
+    write_meta(path, meta, body)
+    runtime = root / EXEC_ROOT / "claims" / f"{path.stem}.claim"
+    runtime.parent.mkdir(parents=True, exist_ok=True)
+    runtime.write_text(f"{meta['Owner']}\n{meta['Claimed-at']}\n", encoding="utf-8")
+    return path
+
+
+def release(root: Path, spec: str) -> Path:
+    path = resolve_artifact(root, spec)
+    meta, body = read_meta(path)
+    meta["Owner"] = ""
+    meta["Claimed-at"] = ""
+    if meta.get("Status") == "claimed":
+        meta["Status"] = "open"
+    write_meta(path, meta, body)
+    runtime = root / EXEC_ROOT / "claims" / f"{path.stem}.claim"
+    if runtime.exists():
+        runtime.unlink()
+    return path
+
+
+def _stale(iso: str, hours: int | None = None, root: Path | None = None) -> bool:
+    hours = hours or load_contract(root).stale_hours
+    try:
+        then = datetime.fromisoformat(iso)
+    except ValueError:
+        return True
+    if then.tzinfo is None:
+        then = then.replace(tzinfo=timezone.utc)
+    return (_now() - then).total_seconds() > hours * 3600
+
+
+def is_stale(meta: dict[str, str], root: Path | None = None) -> bool:
+    at = meta.get("Claimed-at") or ""
+    if not at:
+        return False
+    return _stale(at, root=root)
+
+
+def link(root: Path, a: str, b: str) -> None:
+    pa, pb = resolve_artifact(root, a), resolve_artifact(root, b)
+    for path, other in ((pa, pb), (pb, pa)):
+        meta, body = read_meta(path)
+        links = [x.strip() for x in (meta.get("Links") or "").split(",") if x.strip()]
+        rel = str(other.relative_to(root))
+        if rel not in links:
+            links.append(rel)
+        meta["Links"] = ", ".join(links)
+        write_meta(path, meta, body)
+
+
+def _ticket_blocked(meta: dict[str, str]) -> bool:
+    return bool((meta.get("Blocked by") or "").strip())
+
+
+def board(root: Path) -> str:
+    contract = load_contract(root)
+    lines = ["# spine status", ""]
+    wi = root / SPEC_ROOT / "work-items"
+    tk = root / SPEC_ROOT / "tickets"
+    if wi.exists():
+        lines.append("## Work items")
+        for p in sorted(wi.glob("*.md")):
+            meta, _ = read_meta(p)
+            software = (meta.get("Profile") or "software").lower() == "software"
+            gates = contract.next_gates(meta.get("Status", ""), software=software)
+            gate = ",".join(gates) if gates else "-"
+            lines.append(
+                f"- {p.name}: {meta.get('Status','?')} next={gate} owner={meta.get('Owner','') or '-'}"
+            )
+        lines.append("")
+    frontier: list[str] = []
+    if tk.exists():
+        lines.append("## Tickets")
+        for p in sorted(tk.glob("*.md")):
+            meta, _ = read_meta(p)
+            status = meta.get("Status", "?")
+            blocked = meta.get("Blocked by", "") or "-"
+            lines.append(f"- {p.name}: {status} blocked={blocked}")
+            if status == "open" and not _ticket_blocked(meta) and not (meta.get("Owner") or "").strip():
+                frontier.append(p.name)
+        lines.append("")
+        lines.append("## Frontier")
+        if frontier:
+            for name in frontier:
+                lines.append(f"- {name}")
+        else:
+            lines.append("- (empty)")
+    return "\n".join(lines) + "\n"

spine/cli.py

@@ -0,0 +1,108 @@
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from spine import __version__
+from spine.artifacts import board, claim, link, new_ticket, new_work_item, release, set_status
+from spine.doctor import doctor
+from spine.evolve import evolve, install_wires, set_pack
+from spine.initcmd import init_target
+
+
+def _root() -> Path:
+    return Path.cwd()
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="spine", description="Harness-agnostic process spine")
+    parser.add_argument("--version", action="version", version=f"spine {__version__}")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    p_init = sub.add_parser("init", help="scaffold a target")
+    p_init.add_argument("--refresh", action="store_true")
+
+    sub.add_parser("status", help="board")
+
+    p_new = sub.add_parser("new", help="mint a work item and/or map ticket")
+    p_new.add_argument("kind", nargs="?", choices=["ticket", "work-item"])
+    p_new.add_argument("--title", required=True)
+    p_new.add_argument("--type", default="grilling")
+    p_new.add_argument("--profile", default="software")
+    p_new.add_argument("--ticket", action="store_true")
+    p_new.add_argument("--work-item", dest="work_item_flag", action="store_true")
+
+    p_claim = sub.add_parser("claim")
+    p_claim.add_argument("target")
+    p_rel = sub.add_parser("release")
+    p_rel.add_argument("target")
+
+    p_ss = sub.add_parser("set-status")
+    p_ss.add_argument("target")
+    p_ss.add_argument("status")
+
+    p_link = sub.add_parser("link")
+    p_link.add_argument("a")
+    p_link.add_argument("b")
+
+    p_doc = sub.add_parser("doctor")
+    p_doc.add_argument("--report-only", action="store_true")
+
+    p_wire = sub.add_parser("wire", help="install or record skills.sh craft packs")
+    p_wire.add_argument("--install", action="store_true", help="npx skills add default pack")
+    p_wire.add_argument("--pack", default="mattpocock/skills")
+
+    sub.add_parser("evolve", help="refresh binder from wheel; update skills.sh installs")
+
+    args = parser.parse_args(argv)
+    root = _root()
+
+    try:
+        if args.cmd == "init":
+            for line in init_target(root, refresh=args.refresh):
+                print(line)
+        elif args.cmd == "status":
+            print(board(root), end="")
+        elif args.cmd == "new":
+            want_ticket = args.kind == "ticket" or args.ticket
+            want_wi = args.kind == "work-item" or args.work_item_flag
+            if not want_ticket and not want_wi:
+                raise ValueError("new needs ticket and/or work-item")
+            if want_ticket:
+                print(new_ticket(root, args.title, args.type))
+            if want_wi:
+                print(new_work_item(root, args.title, args.profile))
+        elif args.cmd == "claim":
+            print(claim(root, args.target))
+        elif args.cmd == "release":
+            print(release(root, args.target))
+        elif args.cmd == "set-status":
+            print(set_status(root, args.target, args.status))
+        elif args.cmd == "link":
+            link(root, args.a, args.b)
+            print("linked")
+        elif args.cmd == "doctor":
+            for line in doctor(root, apply=not args.report_only):
+                print(line)
+        elif args.cmd == "wire":
+            set_pack(root, args.pack)
+            if args.install:
+                for line in install_wires(root, extra_pack=args.pack):
+                    print(line)
+            else:
+                print(f"default_pack={args.pack} (pass --install to run npx skills add)")
+        elif args.cmd == "evolve":
+            for line in evolve(root):
+                print(line)
+        else:
+            parser.error("unknown command")
+            return 2
+    except (ValueError, FileNotFoundError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

spine/data/binder/build/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: build
+description: Implement a software work item in doing. Use when the item is claimed and status is doing.
+---
+
+# build
+
+```
+spine claim docs/spine/work-items/NN-slug.md
+spine set-status docs/spine/work-items/NN-slug.md doing
+```
+
+Agents own content. CLI owns metadata. Install craft: `npx skills add mattpocock/skills -s implement -s tdd -s codebase-design -y`.
+
+## Gate
+doing (agent-drivable). Next: checking.

spine/data/binder/doctor/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: doctor
+description: Recover mechanical drift in a spine target. Use at session start and when files look wrong.
+---
+
+# doctor
+
+```
+spine doctor
+spine evolve
+```
+
+Doctor auto-fixes stale claims, CLI-owned links, and rollups. It reports unknown statuses, missing spec files, gitignore drift. Never rewrite content sections by hand to fake a fix.
+
+## Gate
+Recovery loop. Not a harness hook.

spine/data/binder/eval/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: eval
+description: Check a software work item against acceptance. Use when status is checking.
+---
+
+# eval
+
+Write proof under `.spine/evals/`. Then:
+
+```
+spine set-status docs/spine/work-items/NN-slug.md reviewing
+```
+
+Craft: `npx skills add mattpocock/skills -s qa -y`.
+
+## Gate
+checking (agent-drivable). Software profile requires this before done.

spine/data/binder/new/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: new
+description: Capture a map ticket or work item via the spine CLI. Use when something new must be recorded in the target.
+---
+
+# new
+
+Mint artifacts with the CLI. Do not hand-edit status, owner, claim, links, or numbers.
+
+```
+spine new ticket --title "..." --type grilling
+spine new work-item --title "..." --profile software
+```
+
+Craft skills for interviewing live on skills.sh. Default wire: `mattpocock/skills` `grill-me` / `wayfinder` (`npx skills add mattpocock/skills -s grill-me -s wayfinder -y`). See `docs/spine/wires.yaml`.
+
+## Gate
+creating-work-item is HITL. Tickets start `open`. Work items start `ready`.

spine/data/binder/next/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: next
+description: Pick the next spine action from the map frontier and work-item board.
+---
+
+# next
+
+Run `spine doctor` then `spine status`. Take the first open unblocked unclaimed ticket, or the work item whose status is the next gate.
+
+```
+spine doctor
+spine status
+```
+
+Craft router (optional): `npx skills add mattpocock/skills -s ask-matt -s implement -y`.
+
+## Gate
+Respect HITL: do not `set-status` to `reviewing` verdicts or mint work items without a human if the contract marks them HITL.

spine/data/binder/review/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: review
+description: Review a software work item. Use when status is reviewing.
+---
+
+# review
+
+HITL verdict. Proof under `.spine/reviews/`. Pass:
+
+```
+spine set-status docs/spine/work-items/NN-slug.md done
+```
+
+Bounce:
+
+```
+spine set-status docs/spine/work-items/NN-slug.md changes-requested
+```
+
+Craft: `npx skills add mattpocock/skills -s code-review -y`.
+
+## Gate
+reviewing (HITL). Software profile requires this before done.

spine/data/binder/wayfind/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: wayfind
+description: Plan with a spine map and tickets. Use when the way to a destination is foggy or multi-session.
+---
+
+# wayfind
+
+Planning lives on the map, not on the work item. Load `docs/spine/maps/`, work frontier tickets under `docs/spine/tickets/`. Claim a ticket with the CLI before work.
+
+```
+spine status
+spine new ticket --title "..." --type research
+spine claim tickets/NN-slug.md
+```
+
+Do not vendor Wayfinder. Install craft from skills.sh: `npx skills add mattpocock/skills -s wayfinder -s grilling -s domain-modeling -y`.
+
+## Gate
+No work-item status for planning. Create a work item at `ready` only when the way is clear.

spine/data/contract.yaml

@@ -0,0 +1,31 @@
+version: 1
+statuses:
+  - ready
+  - doing
+  - checking
+  - reviewing
+  - done
+  - changes-requested
+transitions:
+  ready: [doing]
+  doing: [checking]
+  checking: [reviewing]
+  reviewing: [done, changes-requested]
+  changes-requested: [doing]
+  done: []
+hitl:
+  - creating-work-item
+  - reviewing
+agent_drivable:
+  - doing
+  - checking
+profiles:
+  software:
+    required_before_done:
+      - checking
+      - reviewing
+  default:
+    allow_doing_to_done: true
+claim:
+  stale_hours: 4
+  owner_env: SPINE_USER

spine/data/wires.yaml

@@ -0,0 +1,26 @@
+# Binder concern → skills.sh craft skills. Not vendored; installed via `npx skills`.
+source: skills.sh
+default_pack: mattpocock/skills
+concerns:
+  wayfind:
+    pack: mattpocock/skills
+    skills: [wayfinder, grilling, domain-modeling]
+  new:
+    pack: mattpocock/skills
+    skills: [grill-me, wayfinder]
+  next:
+    pack: mattpocock/skills
+    skills: [ask-matt, implement]
+  doctor:
+    pack: null
+    skills: []
+    cli: [spine doctor]
+  build:
+    pack: mattpocock/skills
+    skills: [implement, tdd, codebase-design]
+  eval:
+    pack: mattpocock/skills
+    skills: [qa]
+  review:
+    pack: mattpocock/skills
+    skills: [code-review]

spine/doctor.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from spine.artifacts import is_stale, read_meta, release, write_meta
+from spine.model import EXEC_ROOT, SPEC_DIRS, SPEC_ROOT, load_contract, packaged_contract
+
+
+def doctor(root: Path, *, apply: bool = True) -> list[str]:
+    msgs: list[str] = []
+    contract = load_contract(root)
+    packaged = packaged_contract()
+    if contract.version != packaged.version:
+        msgs.append(
+            f"REPORT contract version {contract.version} in target vs packaged {packaged.version}"
+        )
+
+    for name in SPEC_DIRS:
+        p = root / SPEC_ROOT / name
+        if not p.is_dir():
+            msgs.append(f"REPORT missing spec dir {p.relative_to(root)}")
+
+    for rel in (
+        SPEC_ROOT / "README.md",
+        SPEC_ROOT / "contract.yaml",
+        SPEC_ROOT / "wires.yaml",
+        SPEC_ROOT / "maps" / "map.md",
+    ):
+        if not (root / rel).exists():
+            msgs.append(f"REPORT missing spec file {rel}")
+
+    gi = root / ".gitignore"
+    if not gi.exists() or ".spine/" not in gi.read_text(encoding="utf-8"):
+        msgs.append("REPORT gitignore missing .spine/")
+
+    folders = []
+    for name in ("work-items", "tickets"):
+        d = root / SPEC_ROOT / name
+        if d.is_dir():
+            folders.append(d)
+
+    for folder in folders:
+        for path in folder.glob("*.md"):
+            meta, body = read_meta(path)
+            status = meta.get("Status", "")
+            if status and status not in contract.statuses and status not in {"open", "claimed", "resolved"}:
+                msgs.append(f"REPORT unknown status {status} in {path.name}")
+            if is_stale(meta, root=root):
+                msgs.append(f"STALE claim on {path.name}")
+                if apply:
+                    release(root, str(path.relative_to(root)))
+                    msgs.append(f"FIX released stale claim {path.name}")
+            links = [x.strip() for x in (meta.get("Links") or "").split(",") if x.strip()]
+            kept = []
+            changed = False
+            for rel in links:
+                if (root / rel).exists():
+                    kept.append(rel)
+                else:
+                    msgs.append(f"BROKEN link {path.name} → {rel}")
+                    changed = True
+            if changed and apply:
+                meta["Links"] = ", ".join(kept)
+                write_meta(path, meta, body)
+                msgs.append(f"FIX links on {path.name}")
+
+    out = root / EXEC_ROOT / "doctor" / "last.txt"
+    out.parent.mkdir(parents=True, exist_ok=True)
+    out.write_text("\n".join(msgs) + ("\n" if msgs else "ok\n"), encoding="utf-8")
+    if not msgs:
+        msgs.append("ok")
+    return msgs

spine/evolve.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+import shutil
+import subprocess
+from pathlib import Path
+
+import yaml
+
+from spine.initcmd import init_target
+from spine.resources import read_data
+
+
+def _npx() -> str | None:
+    return shutil.which("npx")
+
+
+def load_wires(root: Path) -> dict:
+    path = root / "docs/spine/wires.yaml"
+    text = path.read_text(encoding="utf-8") if path.exists() else read_data("wires.yaml")
+    return yaml.safe_load(text) or {}
+
+
+def install_cmd(pack: str, skills: list[str], npx: str = "npx") -> list[str]:
+    cmd = [npx, "--yes", "skills", "add", pack, "-y"]
+    seen: set[str] = set()
+    for name in skills:
+        if name and name not in seen:
+            seen.add(name)
+            cmd.extend(["-s", name])
+    return cmd
+
+
+def skills_for_pack(wires: dict, pack: str) -> list[str]:
+    names: list[str] = []
+    for spec in (wires.get("concerns") or {}).values():
+        if not isinstance(spec, dict):
+            continue
+        if spec.get("pack") != pack:
+            continue
+        names.extend(spec.get("skills") or [])
+    return names
+
+
+def install_wires(root: Path, *, extra_pack: str | None = None) -> list[str]:
+    notes: list[str] = []
+    npx = _npx()
+    wires = load_wires(root)
+    pack = extra_pack or wires.get("default_pack") or "mattpocock/skills"
+    skills = skills_for_pack(wires, pack)
+    if not npx:
+        notes.append(
+            "npx not found; skip craft install. Binder skills are already copied. "
+            f"Run: {' '.join(install_cmd(pack, skills))}"
+        )
+        return notes
+    cmd = install_cmd(pack, skills, npx)
+    proc = subprocess.run(cmd, cwd=root, capture_output=True, text=True)
+    notes.append(f"$ {' '.join(cmd)} exit={proc.returncode}")
+    if proc.stdout:
+        notes.append(proc.stdout[-2000:])
+    if proc.returncode != 0 and proc.stderr:
+        notes.append(proc.stderr[-1000:])
+    return notes
+
+
+def evolve(root: Path) -> list[str]:
+    notes = init_target(root, refresh=True)
+    npx = _npx()
+    if npx:
+        proc = subprocess.run([npx, "--yes", "skills", "update"], cwd=root, capture_output=True, text=True)
+        notes.append(f"skills update exit={proc.returncode}")
+        if proc.stdout:
+            notes.append(proc.stdout[-1500:])
+    else:
+        notes.append("npx not found; refreshed binder from wheel only")
+    return notes
+
+
+def set_pack(root: Path, pack: str) -> None:
+    path = root / "docs/spine/wires.yaml"
+    text = path.read_text(encoding="utf-8") if path.exists() else read_data("wires.yaml")
+    lines = []
+    replaced = False
+    for line in text.splitlines():
+        if line.startswith("default_pack:"):
+            lines.append(f"default_pack: {pack}")
+            replaced = True
+        else:
+            lines.append(line)
+    if not replaced:
+        lines.insert(0, f"default_pack: {pack}")
+    path.write_text("\n".join(lines) + "\n", encoding="utf-8")

spine/initcmd.py

@@ -0,0 +1,111 @@
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+
+from spine.model import EXEC_DIRS, EXEC_ROOT, HARNESS_SKILL_ROOTS, SPEC_DIRS, SPEC_ROOT
+from spine.resources import data_root, read_data
+
+README = """# spine artifacts
+
+Checked-in **spec tier** (this tree):
+
+- `maps/` — planning maps (index only)
+- `tickets/` — map tickets (`NN-slug.md`)
+- `work-items/` — execution work items
+- `decisions/` — durable decisions
+- `wires.yaml` — binder concern → skills.sh craft skills
+
+Gitignored **execution tier** lives in `.spine/` (`evals`, `reviews`, `handoffs`, `doctor`, `claims`).
+
+Install craft skills with the open skills CLI (skills.sh), not by copying bodies into this repo:
+
+```
+npx skills add mattpocock/skills -y
+```
+
+Or `spine wire --install` to install the default wires.
+"""
+
+GITIGNORE_BLOCK = """
+# spine execution tier
+.spine/
+"""
+
+MAP = """# Map
+
+## Destination
+
+## Notes
+
+## Decisions so far
+
+## Not yet specified
+
+## Out of scope
+"""
+
+
+def _copy_tree(src: Path, dest: Path) -> None:
+    dest.mkdir(parents=True, exist_ok=True)
+    for item in src.iterdir():
+        target = dest / item.name
+        if item.is_dir():
+            _copy_tree(item, target)
+        else:
+            shutil.copy2(item, target)
+
+
+def init_target(root: Path, *, refresh: bool = False) -> list[str]:
+    notes: list[str] = []
+    for name in SPEC_DIRS:
+        p = root / SPEC_ROOT / name
+        p.mkdir(parents=True, exist_ok=True)
+        notes.append(f"ensure {p.relative_to(root)}")
+    for name in EXEC_DIRS:
+        p = root / EXEC_ROOT / name
+        p.mkdir(parents=True, exist_ok=True)
+        notes.append(f"ensure {p.relative_to(root)}")
+
+    readme = root / SPEC_ROOT / "README.md"
+    if refresh or not readme.exists():
+        readme.write_text(README, encoding="utf-8")
+        notes.append("wrote docs/spine/README.md")
+
+    wires = root / SPEC_ROOT / "wires.yaml"
+    if refresh or not wires.exists():
+        wires.write_text(read_data("wires.yaml"), encoding="utf-8")
+        notes.append("wrote docs/spine/wires.yaml")
+
+    contract = root / SPEC_ROOT / "contract.yaml"
+    if refresh or not contract.exists():
+        contract.write_text(read_data("contract.yaml"), encoding="utf-8")
+        notes.append("wrote docs/spine/contract.yaml")
+
+    mapp = root / SPEC_ROOT / "maps" / "map.md"
+    if not mapp.exists():
+        mapp.write_text(MAP, encoding="utf-8")
+        notes.append("wrote docs/spine/maps/map.md")
+
+    gi = root / ".gitignore"
+    existing = gi.read_text(encoding="utf-8") if gi.exists() else ""
+    if ".spine/" not in existing:
+        gi.write_text(
+            existing.rstrip() + "\n" + GITIGNORE_BLOCK if existing else GITIGNORE_BLOCK.lstrip("\n"),
+            encoding="utf-8",
+        )
+        notes.append("updated .gitignore")
+
+    binder_src = data_root() / "binder"
+    for harness in HARNESS_SKILL_ROOTS:
+        dest = root / harness
+        dest.mkdir(parents=True, exist_ok=True)
+        if refresh or not any(dest.glob("*/SKILL.md")):
+            _copy_tree(binder_src, dest)
+            notes.append(f"copied binder → {harness}")
+        else:
+            for skill_dir in binder_src.iterdir():
+                target = dest / skill_dir.name
+                _copy_tree(skill_dir, target)
+            notes.append(f"refreshed binder → {harness}")
+    return notes

spine/model.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+import yaml
+
+from spine.resources import read_data
+
+SPEC_ROOT = Path("docs/spine")
+EXEC_ROOT = Path(".spine")
+SPEC_DIRS = ("maps", "tickets", "work-items", "decisions")
+EXEC_DIRS = ("evals", "reviews", "handoffs", "doctor", "claims")
+HARNESS_SKILL_ROOTS = (
+    Path(".agents/skills"),
+    Path(".claude/skills"),
+    Path(".cursor/skills"),
+)
+TICKET_STATUSES = {"open", "claimed", "resolved"}
+
+
+@dataclass(frozen=True)
+class Contract:
+    raw: dict
+    source: str = "packaged"
+
+    @property
+    def version(self) -> int:
+        return int(self.raw["version"])
+
+    @property
+    def statuses(self) -> list[str]:
+        return list(self.raw["statuses"])
+
+    @property
+    def transitions(self) -> dict[str, list[str]]:
+        return {k: list(v) for k, v in self.raw["transitions"].items()}
+
+    @property
+    def stale_hours(self) -> int:
+        return int(self.raw["claim"]["stale_hours"])
+
+    def allowed(self, current: str, nxt: str) -> bool:
+        return nxt in self.transitions.get(current, [])
+
+    def software_required(self) -> list[str]:
+        return list(self.raw["profiles"]["software"]["required_before_done"])
+
+    def next_gates(self, current: str, *, software: bool = True) -> list[str]:
+        nxt = list(self.transitions.get(current, []))
+        if current == "doing" and not software:
+            if "done" not in nxt:
+                nxt.append("done")
+        return nxt
+
+
+def packaged_contract() -> Contract:
+    return Contract(yaml.safe_load(read_data("contract.yaml")), source="packaged")
+
+
+def load_contract(root: Path | None = None) -> Contract:
+    if root is not None:
+        path = root / SPEC_ROOT / "contract.yaml"
+        if path.exists():
+            return Contract(yaml.safe_load(path.read_text(encoding="utf-8")), source=str(path))
+    return packaged_contract()
+
+
+def parse_front(text: str) -> tuple[dict[str, str], str]:
+    """Parse simple `Key: value` header until blank line."""
+    lines = text.splitlines()
+    meta: dict[str, str] = {}
+    i = 0
+    if lines and lines[0].startswith("# "):
+        meta["Title"] = lines[0][2:].strip()
+        i = 1
+        if i < len(lines) and lines[i] == "":
+            i += 1
+    while i < len(lines) and lines[i] != "" and ":" in lines[i] and not lines[i].startswith("#"):
+        k, _, v = lines[i].partition(":")
+        meta[k.strip()] = v.strip()
+        i += 1
+    body = "\n".join(lines[i:]).lstrip("\n")
+    return meta, body
+
+
+def dump_front(meta: dict[str, str], body: str, title: str | None = None) -> str:
+    title = title or meta.get("Title", "untitled")
+    keys = [k for k in meta if k != "Title"]
+    header = [f"# {title}", ""]
+    for k in keys:
+        header.append(f"{k}: {meta[k]}")
+    return "\n".join(header) + "\n\n" + body.lstrip("\n")

spine/resources.py

@@ -0,0 +1,14 @@
+"""Load packaged data files."""
+
+from __future__ import annotations
+
+from importlib.resources import files
+from pathlib import Path
+
+
+def data_root() -> Path:
+    return Path(str(files("spine") / "data"))
+
+
+def read_data(*parts: str) -> str:
+    return (data_root().joinpath(*parts)).read_text(encoding="utf-8")

spine_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,161 @@
+Metadata-Version: 2.5
+Name: spine-cli
+Version: 0.1.0
+Summary: Harness-agnostic process spine CLI
+Author: ASabale
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: pyyaml>=6
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# spine — v1 spec
+
+Public, harness-agnostic process spine. Planning and execution survive sessions as files in a **target**. This spec plus [CONTEXT.md](CONTEXT.md) is enough to implement the toolkit. It does not implement it.
+
+License: **MIT**. Product, GitHub slug, docs, and CLI command: **spine**. PyPI distribution: **spine-cli**. Intended GitHub home: https://github.com/ASabale/spine (not created by this spec). Do not publish as Generic Workflows.
+
+## Job
+
+Durable process across sessions: a **map** plus **tickets** for planning; a **work item** for execution (status, owner, claim, links, next gate). Repo files in the target are the source of truth. No harness API is required for correctness. Optional adapters later; never required.
+
+## Stranger install
+
+Python **3.11+**. Console script `spine` via `[project.scripts]`. Wheel ships the **contract** and binder `SKILL.md` as package data (`importlib.resources`). Init copies skills onto harness discovery roots; a wheel copy is invisible until then.
+
+```text
+uvx --from spine-cli spine init
+```
+
+or `uv tool install spine-cli` then `spine init`. Idempotent: missing artifacts only; refresh offered. Then `spine doctor` once. No plugin marketplace. No clone of the spine source repo. GitHub home is documentation, not an install dependency.
+
+## Two-tier paths
+
+**Spec tier** (checked in):
+
+```text
+docs/spine/README.md
+docs/spine/maps/
+docs/spine/tickets/
+docs/spine/work-items/
+docs/spine/decisions/
+```
+
+**Execution tier** (gitignored; init writes `.gitignore` for `.spine/`):
+
+```text
+.spine/evals/
+.spine/reviews/
+.spine/handoffs/
+.spine/doctor/
+.spine/claims/
+```
+
+Do not use `docs/workflow/` or `.workflow/`. Folder names match the glossary. `docs/spine/README.md` names the tree for a first-time agent.
+
+## Planning (Wayfinder as files)
+
+No GitHub Issues required. One map file per map. Sections: Destination, Notes, Decisions so far, Not yet specified (fog), Out of scope. The map is an **index**: gist plus link; it does not restate a ticket’s answer.
+
+Child tickets: `NN-<slug>.md`, title is the name. Fields: `Type:` (research, prototype, grilling, task), `Status:` (open, claimed, resolved), `Blocked by: NN`. Answers under `## Answer`. Research write-ups are separate files, linked, not pasted. Frontier: open, unblocked, unclaimed tickets. Claim on tickets is a field the **CLI** owns.
+
+Planning never lives on the work item. Chart the map, cut tickets, work the frontier. When the way is clear, HITL **creates** a work item at `ready`.
+
+## Work-item machine (contract)
+
+Happy path: `ready → doing → checking → reviewing → done`.
+
+Bounce: `reviewing → changes-requested → doing`.
+
+Legal transitions:
+
+- `ready → doing`
+- `doing → checking`
+- `checking → reviewing`
+- `reviewing → done`
+- `reviewing → changes-requested`
+- `changes-requested → doing`
+
+HITL: creating a work item; `reviewing`. Agent-drivable: `doing`, `checking`. No `grilling` / `prd` / `planning` status on a work item. Next session reads the current status as the next gate.
+
+Skills and the CLI **reference** this contract; they never restate it.
+
+## Software profile
+
+Same contract. Software work items must pass `checking` (eval against acceptance) and `reviewing` (human or reviewer-agent verdict) before `done`. Proof artifacts live in `.spine/{evals,reviews}/`. Non-software items may `doing → done` under human judgment with a named deliverable existing. No PRD/blueprint stages on the work item.
+
+## CLI
+
+Humans and agents use the same CLI. It is the only writer of machine-driving metadata (status, owner, claim, links, numbers).
+
+Verbs: `init`, `status`, `new`, `claim`, `release`, `set-status`, `link`, `doctor`.
+
+- `init` — scaffold a target.
+- `status` — board (work items + next gate).
+- `new` — mint a work item and/or a map ticket (flags, not a second verb).
+- `claim` / `release` — solo-first lock.
+- `set-status` — only legal transitions.
+- `link` — CLI-owned bidirectional links.
+- `doctor` — mechanical drift.
+
+No harness-specific subcommands. No plugin install.
+
+## Claim policy
+
+`Owner` + `Claimed-at` owned by the CLI. Stale after **4 hours**. `spine claim` fails if a non-stale claim exists. `spine release` and stale doctor-fix clear it. No auth system. Username is `user.name` or `SPINE_USER`.
+
+## Doctor
+
+CLI command, not a harness hook.
+
+**Auto-fix:** stale claims past the policy window; broken bidirectional links the CLI owns; rollups the CLI owns.
+
+**Report-only:** unknown statuses after a contract bump; missing spec-tier files; gitignore drift.
+
+Never auto-edit content sections. Harness session-start is adapter fog, not required v1.
+
+## Binder
+
+v1 concerns (thin `SKILL.md` each): `new` (capture), `wayfind`, `next` (frontier + work-item board), `doctor`, plus software pointers `build`, `eval`, `review`. Do not vendor grilling, TDD, or Wayfinder bodies. Drop graph, tour, and a `dev-*` palette.
+
+Shape: YAML frontmatter + short body — when to use, CLI invocations by pointer, `## Gate` names that exist in the contract (not copied statuses). One skill text. Init writes copies onto harness roots (at least `.agents/skills` for Cursor/Codex/oh-my-pi; `.claude/skills` for Claude Code). No Devin `hooks.v1.json`.
+
+## Out of scope (v1)
+
+- Harness plugins or hooks as required.
+- Code graph (CRG / Graphify).
+- Shipping a full craft-skill catalog.
+- Importing a 16-status idea→done machine.
+- Creating the GitHub repository as part of implementing this spec (home is named; create is a later act).
+
+## Deferred (not decided here)
+
+- Contract versioning and artifact migration.
+- Optional per-harness adapters.
+- A docs-only type profile besides software.
+- How already-wayfinding folders relate to a spine-inited target.
+- Whether init scaffolds CONTEXT.md / ADR conventions.
+- Work-item templates (PRD, blueprint).
+- User-level vs project-level install besides `uvx` + init.
+
+## Auto-evolve, recover, and skill wires (v1 addendum)
+
+Operator instruction 2026-09-18: the toolkit is auto-evolvable, self-recoverable, harness/agent/platform-agnostic. Craft skills are **not** vendored. Discover them on **skills.sh**. Install and update via the open skills CLI (`npx skills …`). Default recommended pack: **mattpocock/skills**. Users may wire any pack.
+
+**Wires file** (spec tier): `docs/spine/wires.yaml` maps binder concerns to skills.sh slugs (`owner/repo` + skill name). Init writes a default mapping to Matt Pocock skills; `spine wire` edits it; `spine evolve` refreshes binder copies from the wheel and runs `npx skills update` when the CLI is available.
+
+Default wires (concern → skills.sh skills, not vendored bodies):
+
+- `wayfind` → `mattpocock/skills` `wayfinder`, `grilling`, `domain-modeling`
+- `new` → `mattpocock/skills` `grill-me` (and map capture via `wayfinder`)
+- `next` → `mattpocock/skills` `ask-matt`, `implement`
+- `doctor` → binder `doctor` plus `spine doctor`
+- `build` → `mattpocock/skills` `implement`, `tdd`, `codebase-design`
+- `eval` → `mattpocock/skills` `qa`
+- `review` → `mattpocock/skills` `code-review`
+
+**Self-recover:** `spine doctor` is the recovery loop. `spine evolve` is the refresh loop. Init stays idempotent.
+
+**Extra CLI verbs (addendum):** `wire`, `evolve`. Same CLI owns metadata; `npx skills` owns craft-skill files on harness roots.

spine_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,22 @@
+spine/__init__.py,sha256=FiHwvf8cW_Pex07RxXH14uu26BBuV7-Z0_rOoiY7tN4,72
+spine/artifacts.py,sha256=nhvP7DqE8RzAlRnwf4zKYsMhjtU14ViVHvLB6twaVQw,8615
+spine/cli.py,sha256=BQIAq5IPq8GzEWgs_czHbE63rOfhLpAmgeQufK9dtZk,3968
+spine/doctor.py,sha256=Cb0lTkWyvuLIvT90ltCYaFfgCdZLHyw70d7faUnapGE,2703
+spine/evolve.py,sha256=twimtefe9rTOGSHHeTb3WHqTwTIWULgRtPD0YvCG4tc,2899
+spine/initcmd.py,sha256=YgPzGw0sIBshKmbSxveRomR2AyOydrZdANgstXy5w_Q,3349
+spine/model.py,sha256=IOPg-fIIHw10Jeci-xb_Z-VR4K8cf1DRv1vowhmP2zg,2857
+spine/resources.py,sha256=ATXyoG15Spgdx4R3BaMEpr1dG_FDKffNkXs5nREZ1nw,312
+spine/data/contract.yaml,sha256=Qrfa6y_HzoR4Fqh8AzUslX4GOydXIs5bc3JuULqM1Yw,506
+spine/data/wires.yaml,sha256=uBEFlhQ2E_zQZol8MwdX1GuSmG907OGt5FYU17SXozQ,640
+spine/data/binder/build/SKILL.md,sha256=0ea7XX8AXbKHDe17OiRv8_cb1xuZ3UPFad3MnZixYdg,425
+spine/data/binder/doctor/SKILL.md,sha256=hUADmmwei1LNdOD_ynNvdXY0-kYtoB1v7lEEqFHuzH0,398
+spine/data/binder/eval/SKILL.md,sha256=6WV1i4KZFX4XrbLWHp4p1zxYHCC74iiE7DdBqaX5Wl8,360
+spine/data/binder/new/SKILL.md,sha256=DEv2mRQkCKwdM1RbjNvOc2HfVRyMwOHrLy2llnFtdf0,632
+spine/data/binder/next/SKILL.md,sha256=cvqpIJnTc1cu6YkbzlTOL6uUM4pj5i4hKqFdFn_-TjI,507
+spine/data/binder/review/SKILL.md,sha256=3UJQ7UmR339sbk6VNN5-oKUWshjwrn6L46ETlKlQb90,438
+spine/data/binder/wayfind/SKILL.md,sha256=DDLh7f_gQFsKPhfhhGhZcshoPJXAso1QPdSZjN2tHqw,649
+spine_cli-0.1.0.dist-info/METADATA,sha256=ZV6w3oDmFJXzfOQCkBZgSAort8KG3_UZj7dFKJ2_C_k,7621
+spine_cli-0.1.0.dist-info/WHEEL,sha256=THafob7ofN-NsuMN7Mg4qZyHaQI7KkD-QlcQatYhXPo,87
+spine_cli-0.1.0.dist-info/entry_points.txt,sha256=es1BIsv-j7vuYVLoXKCkqIjpjsp0eybIuGSjVpSJC8k,41
+spine_cli-0.1.0.dist-info/licenses/LICENSE,sha256=7jKasL10pUuPMwky6QZ7MSba7qPk3KE-1eIg4Kp3S0s,1062
+spine_cli-0.1.0.dist-info/RECORD,,

spine_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.3
+Root-Is-Purelib: true
+Tag: py3-none-any

spine_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+spine = spine.cli:main

spine_cli-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ASabale
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTY OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.