ostler 0.1.0__py3-none-any.whl

ostler/__init__.py

@@ -0,0 +1,3 @@
+"""ostler — define, validate, search and mutate a repository's markdown knowledge graph (OKF)."""
+
+__version__ = "1.0.0"

ostler/backlog.py

@@ -0,0 +1,73 @@
+"""`ostler backlog` — the intake list as managed markdown (``docs/backlog.md``).
+
+Bullets are ``- [<id>] <text>`` optionally grouped under ``## <section>`` headings. Replaces the
+former bespoke append/prune scripts.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from .crud import Result
+from .model import Graph
+
+_ITEM = re.compile(r"^\s*[-*]\s+\[(?P<id>[^\]]+)\]\s*(?P<text>.*)$")
+
+
+def _path(graph: Graph) -> Path:
+    return graph.root / "docs" / "backlog.md"
+
+
+def items(graph: Graph) -> list[tuple[str, str]]:
+    """(id, text) pairs across all sections, in file order."""
+    p = _path(graph)
+    if not p.exists():
+        return []
+    out: list[tuple[str, str]] = []
+    for line in p.read_text(encoding="utf-8").splitlines():
+        m = _ITEM.match(line)
+        if m:
+            out.append((m.group("id").strip(), m.group("text").strip()))
+    return out
+
+
+def add(graph: Graph, item_id: str, text: str, section: str = "") -> Result:
+    p = _path(graph)
+    existing = {i for i, _ in items(graph)}
+    if item_id in existing:
+        return Result(False, f"backlog item '{item_id}' already exists")
+    lines = p.read_text(encoding="utf-8").splitlines() if p.exists() else ["# Backlog", ""]
+    bullet = f"- [{item_id}] {text}".rstrip()
+    if section:
+        heading = f"## {section}"
+        if heading in lines:
+            idx = lines.index(heading)
+            insert_at = idx + 1
+            while insert_at < len(lines) and not lines[insert_at].startswith("## "):
+                insert_at += 1
+            lines.insert(insert_at, bullet)
+        else:
+            lines += ["", heading, bullet]
+    else:
+        lines.append(bullet)
+    p.parent.mkdir(parents=True, exist_ok=True)
+    p.write_text("\n".join(lines) + "\n", encoding="utf-8")
+    return Result(True, f"filed backlog item '{item_id}'", [p])
+
+
+def prune(graph: Graph, item_id: str) -> Result:
+    p = _path(graph)
+    if not p.exists():
+        return Result(False, "no backlog.md")
+    kept, removed = [], False
+    for line in p.read_text(encoding="utf-8").splitlines():
+        m = _ITEM.match(line)
+        if m and m.group("id").strip() == item_id:
+            removed = True
+            continue
+        kept.append(line)
+    if not removed:
+        return Result(False, f"no backlog item '{item_id}'")
+    p.write_text("\n".join(kept) + "\n", encoding="utf-8")
+    return Result(True, f"pruned backlog item '{item_id}'", [p])

ostler/cli.py

@@ -0,0 +1,307 @@
+"""ostler command-line entry point."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from . import (
+    __version__,
+    backlog as backlog_mod,
+    crud,
+    doctor,
+    edit,
+    freeze as freeze_mod,
+    query as query_mod,
+    registry,
+    select,
+    todo as todo_mod,
+    trace,
+)
+from .model import load
+
+_TYPES = tuple(t.name for t in registry.REGISTRY) + ("seed", "gap")
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="ostler", description="Tend your documentation graph.")
+    p.add_argument("--version", action="version", version=f"ostler {__version__}")
+    p.add_argument("-C", "--chdir", metavar="DIR", help="operate as if run from DIR")
+    sub = p.add_subparsers(dest="command", required=True)
+
+    d = sub.add_parser("doctor", help="referential-integrity check")
+    d.add_argument("--epic", help="restrict checks to one epic (name or folder)")
+    d.add_argument("--json", action="store_true", help="emit the structured report as JSON")
+    d.add_argument("--no-schema", action="store_true", help="skip JSON Schema validation")
+
+    t = sub.add_parser("trace", help="walk the graph from a node")
+    t.add_argument("token", help="seed id, story slug, gap id, surface or doc path")
+
+    # ---- retrieval --------------------------------------------------------
+    ls = sub.add_parser("list", help="list Concepts of a type")
+    ls.add_argument("--type", required=True, choices=_TYPES, dest="etype")
+    ls.add_argument("--epic")
+    ls.add_argument("--status")
+    ls.add_argument("--json", action="store_true")
+
+    se = sub.add_parser("search", help="full-text search over Concepts")
+    se.add_argument("q")
+    se.add_argument("--type", choices=_TYPES, dest="etype")
+    se.add_argument("--owner")
+    se.add_argument("--tag")
+    se.add_argument("--json", action="store_true")
+
+    qy = sub.add_parser("query", help="reverse-index queries")
+    qy.add_argument("name", choices=query_mod.QUERIES)
+    qy.add_argument("arg")
+    qy.add_argument("--json", action="store_true")
+
+    ne = sub.add_parser("next-epic", help="the next epic with unfinished work")
+    ne.add_argument("--json", action="store_true")
+    ns = sub.add_parser("next-story", help="the next runnable story in an epic")
+    ns.add_argument("epic")
+    ns.add_argument("--json", action="store_true")
+
+    # ---- CRUD -------------------------------------------------------------
+    cr = sub.add_parser("create", help="create an epic/story/feature (allocates an id)")
+    crs = cr.add_subparsers(dest="what", required=True)
+    cre = crs.add_parser("epic")
+    cre.add_argument("name")
+    cre.add_argument("--title", required=True)
+    cre.add_argument("--prefix")
+    cre.add_argument("--json", action="store_true")
+    crt = crs.add_parser("story")
+    crt.add_argument("epic")
+    crt.add_argument("slug")
+    crt.add_argument("--title", required=True)
+    crt.add_argument("--covers", default="")
+    crt.add_argument("--depends", default="")
+    crt.add_argument("--prefix")
+    crt.add_argument("--json", action="store_true")
+    crf = crs.add_parser("feature")
+    crf.add_argument("slug")
+    crf.add_argument("--title", required=True)
+    crf.add_argument("--area", default="")
+    crf.add_argument("--route", default="")
+    crf.add_argument("--prefix")
+    crf.add_argument("--json", action="store_true")
+
+    dl = sub.add_parser("delete", help="delete an epic/story/feature")
+    dls = dl.add_subparsers(dest="what", required=True)
+    dls.add_parser("epic").add_argument("name")
+    dls.add_parser("story").add_argument("slug")
+    dls.add_parser("feature").add_argument("slug")
+
+    sd = sub.add_parser("seed", help="add/remove a seed in an epic")
+    sds = sd.add_subparsers(dest="op", required=True)
+    sda = sds.add_parser("add")
+    sda.add_argument("epic")
+    sda.add_argument("id")
+    sda.add_argument("--status", default=registry.DEFAULT_SEED_STATUS)
+    sda.add_argument("--summary", default="")
+    sda.add_argument("--surface", default="")
+    sda.add_argument("--legacy-surface", default="", dest="legacy_surface")
+    sda.add_argument("--backing", default="")
+    sda.add_argument("--prerequisites", default="")
+    sda.add_argument("--source-bullet", default="", dest="source_bullet")
+    sdr = sds.add_parser("remove")
+    sdr.add_argument("epic")
+    sdr.add_argument("id")
+
+    ss = sub.add_parser("set-status", help="set a story's status")
+    ss.add_argument("slug")
+    ss.add_argument("status")
+
+    bl = sub.add_parser("backlog", help="manage docs/backlog.md")
+    bls = bl.add_subparsers(dest="op", required=True)
+    bla = bls.add_parser("add")
+    bla.add_argument("id")
+    bla.add_argument("text")
+    bla.add_argument("--section", default="")
+    bls.add_parser("prune").add_argument("id")
+    bls.add_parser("list").add_argument("--json", action="store_true")
+
+    td = sub.add_parser("todo", help="manage the epics queue (docs/epics/index.md)")
+    tds = td.add_subparsers(dest="op", required=True)
+    tda = tds.add_parser("add")
+    tda.add_argument("name")
+    tda.add_argument("--front", action="store_true")
+    tds.add_parser("prune").add_argument("name")
+    tds.add_parser("reorder").add_argument("names", nargs="+")
+    tds.add_parser("list").add_argument("--json", action="store_true")
+
+    # ---- edit / freeze ----------------------------------------------------
+    write_parent = argparse.ArgumentParser(add_help=False)
+    write_parent.add_argument("--write", action="store_true", default=argparse.SUPPRESS,
+                              help="apply changes (default: dry-run)")
+    e = sub.add_parser("edit", parents=[write_parent],
+                       help="structured edits (dry-run unless --write)")
+    esub = e.add_subparsers(dest="op", required=True)
+    so = esub.add_parser("set-owner", parents=[write_parent])
+    so.add_argument("gap")
+    so.add_argument("story")
+    rl = esub.add_parser("relink", parents=[write_parent])
+    rl.add_argument("old_path")
+    rl.add_argument("new_path")
+    rn = esub.add_parser("rename", parents=[write_parent])
+    rn.add_argument("old_slug")
+    rn.add_argument("new_slug")
+
+    fz = sub.add_parser("freeze", help="pin an approved story/seed as immutable ground truth")
+    fz.add_argument("ident")
+    fz.add_argument("--by", default="")
+    fz.add_argument("--note", default="")
+    uf = sub.add_parser("unfreeze", help="lift the freeze on a story/seed")
+    uf.add_argument("ident")
+    return p
+
+
+# ---------------------------------------------------------------------------
+def _emit(rows, as_json: bool) -> int:
+    if as_json:
+        print(json.dumps(rows, indent=2))
+    elif isinstance(rows, list):
+        for r in rows:
+            print(json.dumps(r) if isinstance(r, dict) else r)
+        if not rows:
+            print("(none)")
+    else:
+        print(json.dumps(rows, indent=2) if rows else "(none)")
+    return 0
+
+
+def _result(res, as_json: bool = False) -> int:
+    if as_json:
+        print(json.dumps({"ok": res.ok, "id": res.entity_id, "message": res.message}))
+    else:
+        print(res.message)
+    return 0 if res.ok else 1
+
+
+def _cmd_doctor(graph, args) -> int:
+    report = doctor.run(graph, epic_filter=args.epic, check_schema=not args.no_schema)
+    if args.json:
+        print(json.dumps(report.as_dict(), indent=2))
+        return 1 if report.errors else 0
+    print(f"org: {report.org}   profile: {report.profile}")
+    for facts in report.epics:
+        orphans = facts["orphanActiveSeeds"]
+        print(f"  epic {facts['dir']}: {facts['storyCount']} stories, "
+              f"{facts['activeSeedCount']} active seeds ({facts['coveredActiveSeeds']} covered)"
+              + (f"  orphans: {', '.join(orphans)}" if orphans else ""))
+    if report.findings:
+        print()
+        for fnd in sorted(report.findings, key=lambda x: (x.severity != "error", x.code)):
+            mark = "✗" if fnd.severity == "error" else "⚠"
+            scope = f"[{fnd.epic}] " if fnd.epic else ""
+            print(f"  {mark} {fnd.code}: {scope}{fnd.message}")
+    print(f"\n{report.errors} error(s), {report.warnings} warning(s)")
+    return 1 if report.errors else 0
+
+
+def _cmd_edit(graph, args) -> int:
+    if args.op == "set-owner":
+        plan = edit.set_owner(graph, args.gap, args.story)
+    elif args.op == "relink":
+        plan = edit.relink(graph, args.old_path, args.new_path)
+    else:
+        plan = edit.rename(graph, args.old_slug, args.new_slug)
+    print(plan.render())
+    if plan.error:
+        return 1
+    if getattr(args, "write", False):
+        plan.apply()
+        print(f"\napplied: {len(plan.changes)} file(s) changed, {len(plan.moves)} move(s)")
+    elif plan.changes or plan.moves:
+        print("\n(dry-run — pass --write to apply)")
+    return 0
+
+
+def _split(csv: str) -> list[str]:
+    return [p.strip() for p in csv.split(",") if p.strip()]
+
+
+def main(argv: list[str] | None = None) -> int:  # noqa: C901 — flat command dispatch
+    args = _build_parser().parse_args(argv)
+    cwd = Path(args.chdir) if args.chdir else None
+    graph = load(cwd)
+    c = args.command
+
+    if c == "doctor":
+        return _cmd_doctor(graph, args)
+    if c == "trace":
+        lines, found = trace.run(graph, args.token)
+        print("\n".join(lines))
+        return 0 if found else 1
+    if c == "list":
+        return _emit(query_mod.list_entities(graph, args.etype, args.epic, args.status), args.json)
+    if c == "search":
+        return _emit(query_mod.search(graph, args.q, args.etype, args.owner, args.tag), args.json)
+    if c == "query":
+        return _emit(query_mod.query(graph, args.name, args.arg), args.json)
+    if c == "next-epic":
+        return _emit(select.next_epic(graph), args.json)
+    if c == "next-story":
+        return _emit(select.next_story(graph, args.epic), args.json)
+    if c == "create":
+        if args.what == "epic":
+            res = crud.create_epic(graph, args.name, args.title, args.prefix)
+        elif args.what == "story":
+            res = crud.create_story(graph, args.epic, args.slug, args.title,
+                                    _split(args.covers), _split(args.depends), args.prefix)
+        else:
+            res = crud.create_feature(graph, args.slug, args.title, args.area, args.route, args.prefix)
+        return _result(res, getattr(args, "json", False))
+    if c == "delete":
+        if args.what == "epic":
+            return _result(crud.delete_epic(graph, args.name))
+        if args.what == "story":
+            return _result(crud.delete_story(graph, args.slug))
+        return _result(crud.delete_feature(graph, args.slug))
+    if c == "seed":
+        if args.op == "add":
+            meta = {"surface": args.surface, "legacySurface": args.legacy_surface,
+                    "backing": args.backing, "prerequisites": args.prerequisites,
+                    "sourceBullet": args.source_bullet}
+            return _result(crud.add_seed(graph, args.epic, args.id, args.status, args.summary, meta))
+        return _result(crud.remove_seed(graph, args.epic, args.id))
+    if c == "set-status":
+        return _result(crud.set_status(graph, args.slug, args.status))
+    if c == "backlog":
+        if args.op == "add":
+            return _result(backlog_mod.add(graph, args.id, args.text, args.section))
+        if args.op == "prune":
+            return _result(backlog_mod.prune(graph, args.id))
+        return _emit([{"id": i, "text": t} for i, t in backlog_mod.items(graph)], args.json)
+    if c == "todo":
+        if args.op == "add":
+            return _result(todo_mod.add(graph, args.name, front=args.front))
+        if args.op == "prune":
+            return _result(todo_mod.prune(graph, args.name))
+        if args.op == "reorder":
+            return _result(todo_mod.reorder(graph, args.names))
+        return _emit(todo_mod.list_epics(graph), args.json)
+    if c == "edit":
+        return _cmd_edit(graph, args)
+    if c == "freeze":
+        plan = freeze_mod.freeze(graph, args.ident, by=args.by, note=args.note)
+        print(plan.render())
+        if plan.error:
+            return 1
+        plan.apply()
+        print(f"frozen — recorded in {(graph.root / '.agents' / 'ids.json').as_posix()}")
+        return 0
+    if c == "unfreeze":
+        plan = freeze_mod.unfreeze(graph, args.ident)
+        print(plan.render())
+        if plan.error:
+            return 1
+        plan.apply()
+        return 0
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

ostler/crud.py

@@ -0,0 +1,232 @@
+"""`ostler` mutation — create/delete epics, stories, features; add/remove seeds; set status.
+
+All structural mutation goes through here so id allocation (``ids.py``) and the canonical markdown
+layout (``SPEC.md`` / ``registry.py``) stay correct. Writers apply immediately and return a
+:class:`Result`; the CLI prints its message.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import yaml
+
+from . import ids, markdown, registry
+from .model import Graph
+
+
+@dataclass
+class Result:
+    ok: bool
+    message: str
+    paths: list[Path] = field(default_factory=list)
+    entity_id: str = ""   # the allocated id, for create commands (consumed via --json)
+
+
+# ---------------------------------------------------------------------------
+# markdown section helpers (operate on a MarkdownDoc's body, preserving frontmatter)
+# ---------------------------------------------------------------------------
+def _insert_subsection(doc: markdown.MarkdownDoc, heading: str, block: list[str]) -> None:
+    """Insert a ``### …`` *block* under the ``## heading`` section, creating it if absent."""
+    body_lines = doc.body.split("\n")
+    sec = doc.find_section(heading)
+    if sec is None:
+        out = list(body_lines)
+        while out and out[-1].strip() == "":
+            out.pop()
+        out += ["", f"## {heading}", "", *block]
+        doc.body = "\n".join(out) + "\n"
+    else:
+        at = sec.line_end
+        doc.body = "\n".join(body_lines[:at] + block + body_lines[at:])
+    doc._sections = None
+
+
+def _remove_subsection(doc: markdown.MarkdownDoc, heading: str, sub_title: str) -> bool:
+    sec = doc.find_section(heading)
+    if sec is None:
+        return False
+    for child in sec.children:
+        if child.title.strip() == sub_title:
+            body_lines = doc.body.split("\n")
+            del body_lines[child.line_start:child.line_end]
+            doc.body = "\n".join(body_lines)
+            doc._sections = None
+            return True
+    return False
+
+
+def _dump_frontmatter(fm: dict) -> str:
+    return yaml.safe_dump(fm, sort_keys=False, allow_unicode=True)
+
+
+# ---------------------------------------------------------------------------
+# epics
+# ---------------------------------------------------------------------------
+def create_epic(graph: Graph, name: str, title: str, prefix: str | None = None) -> Result:
+    edir = graph.doc_roots["epics"] / name
+    epic_md = edir / "epic.md"
+    if epic_md.exists():
+        return Result(False, f"epic '{name}' already exists")
+    eid = ids.allocate(graph, prefix)
+    fm = {"type": "epic", "id": eid, "title": title, "status": "planned"}
+    text = f"---\n{_dump_frontmatter(fm)}---\n# Epic: {title}\n\n## Seeds\n\n## Stories\n"
+    edir.mkdir(parents=True, exist_ok=True)
+    epic_md.write_text(text, encoding="utf-8")
+    return Result(True, f"created epic '{name}' ({eid})", [epic_md], entity_id=eid)
+
+
+def delete_epic(graph: Graph, name: str) -> Result:
+    edir = graph.doc_roots["epics"] / name
+    if not (edir / "epic.md").exists():
+        return Result(False, f"no epic '{name}'")
+    import shutil
+    shutil.rmtree(edir)
+    todo = graph.doc_roots["epics"] / "index.md"
+    removed = ""
+    if todo.exists():
+        from . import todo as todo_mod
+        if todo_mod.prune(graph, name).ok:
+            removed = " (removed from epics index)"
+    return Result(True, f"deleted epic '{name}'{removed}", [edir])
+
+
+# ---------------------------------------------------------------------------
+# stories
+# ---------------------------------------------------------------------------
+def _story_block(slug: str, title: str, sid: str,
+                 covers: list[str], depends: list[str]) -> list[str]:
+    return [
+        f"### {slug}",
+        f"- title: {title}",
+        f"- id: {sid}",
+        f"- covers: {', '.join(covers) if covers else '(none)'}",
+        f"- depends on: {', '.join(depends) if depends else '(none)'}",
+        "",
+    ]
+
+
+def create_story(graph: Graph, epic_name: str, slug: str, title: str,
+                 covers: list[str] | None = None, depends: list[str] | None = None,
+                 prefix: str | None = None) -> Result:
+    edir = graph.doc_roots["epics"] / epic_name
+    epic_md = edir / "epic.md"
+    if not epic_md.exists():
+        return Result(False, f"no epic '{epic_name}'")
+    story_md = edir / "stories" / slug / "story.md"
+    if story_md.exists():
+        return Result(False, f"story '{slug}' already exists")
+
+    sid = ids.allocate(graph, prefix)
+    doc = markdown.split(epic_md.read_text(encoding="utf-8"))
+    _insert_subsection(doc, registry.STORIES_HEADING,
+                       _story_block(slug, title, sid, covers or [], depends or []))
+    epic_md.write_text(doc.render(), encoding="utf-8")
+
+    fm = {"type": "story", "slug": slug, "status": "Not started"}
+    body = (f"# Story: {title}\n\n## Context\n\n## Acceptance Criteria\n\n"
+            f"## Implementation Status\n\n- **Status**: Not started\n")
+    story_md.parent.mkdir(parents=True, exist_ok=True)
+    story_md.write_text(f"---\n{_dump_frontmatter(fm)}---\n{body}", encoding="utf-8")
+    return Result(True, f"created story '{slug}' ({sid}) in epic '{epic_name}'",
+                  [epic_md, story_md], entity_id=sid)
+
+
+def delete_story(graph: Graph, slug: str) -> Result:
+    found = graph.find_story(slug)
+    if found is None:
+        return Result(False, f"no story '{slug}'")
+    epic, story = found
+    epic_md = epic.epic_md
+    doc = markdown.split(epic_md.read_text(encoding="utf-8"))
+    _remove_subsection(doc, registry.STORIES_HEADING, slug)
+    epic_md.write_text(doc.render(), encoding="utf-8")
+    if story.story_md and story.story_md.exists():
+        import shutil
+        shutil.rmtree(story.story_md.parent)
+    return Result(True, f"deleted story '{slug}' from epic '{epic.name}'", [epic_md])
+
+
+def set_status(graph: Graph, slug: str, status: str) -> Result:
+    found = graph.find_story(slug)
+    if found is None or found[1].story_md is None:
+        return Result(False, f"no story '{slug}' with a story.md")
+    path = found[1].story_md
+    doc = markdown.split(path.read_text(encoding="utf-8"))
+    fm = doc.frontmatter or {"type": "story", "slug": slug}
+    fm["status"] = status
+    doc.raw_frontmatter = _dump_frontmatter(fm)
+    doc.body = re.sub(r"(\*\*Status\*\*:\s*).*", lambda m: m.group(1) + status,
+                      doc.body, count=1)
+    path.write_text(doc.render(), encoding="utf-8")
+    return Result(True, f"status of '{slug}' → {status}", [path])
+
+
+# ---------------------------------------------------------------------------
+# seeds (live in epic.md `## Seeds`)
+# ---------------------------------------------------------------------------
+def add_seed(graph: Graph, epic_name: str, seed_id: str, status: str = registry.DEFAULT_SEED_STATUS,
+             summary: str = "", meta: dict | None = None) -> Result:
+    edir = graph.doc_roots["epics"] / epic_name
+    epic_md = edir / "epic.md"
+    if not epic_md.exists():
+        return Result(False, f"no epic '{epic_name}'")
+    if status not in registry.SEED_STATUSES:
+        return Result(False, f"invalid status '{status}' (one of {', '.join(registry.SEED_STATUSES)})")
+    doc = markdown.split(epic_md.read_text(encoding="utf-8"))
+    sec = doc.find_section(registry.SEEDS_HEADING)
+    if sec is not None and any(c.title.strip() == seed_id for c in sec.children):
+        return Result(False, f"seed '{seed_id}' already exists in '{epic_name}'")
+    block = [f"### {seed_id}", f"- status: {status}"]
+    for key in ("surface", "legacySurface", "backing", "prerequisites", "sourceBullet"):
+        val = (meta or {}).get(key)
+        if val:
+            block.append(f"- {key}: {val}")
+    block.append("")
+    if summary:
+        block += [summary, ""]
+    _insert_subsection(doc, registry.SEEDS_HEADING, block)
+    epic_md.write_text(doc.render(), encoding="utf-8")
+    return Result(True, f"added seed '{seed_id}' to epic '{epic_name}'", [epic_md])
+
+
+def remove_seed(graph: Graph, epic_name: str, seed_id: str) -> Result:
+    edir = graph.doc_roots["epics"] / epic_name
+    epic_md = edir / "epic.md"
+    if not epic_md.exists():
+        return Result(False, f"no epic '{epic_name}'")
+    doc = markdown.split(epic_md.read_text(encoding="utf-8"))
+    if not _remove_subsection(doc, registry.SEEDS_HEADING, seed_id):
+        return Result(False, f"no seed '{seed_id}' in '{epic_name}'")
+    epic_md.write_text(doc.render(), encoding="utf-8")
+    return Result(True, f"removed seed '{seed_id}' from epic '{epic_name}'", [epic_md])
+
+
+# ---------------------------------------------------------------------------
+# features
+# ---------------------------------------------------------------------------
+def create_feature(graph: Graph, slug: str, title: str, area: str = "",
+                   route: str = "", prefix: str | None = None) -> Result:
+    froot = graph.doc_roots["features"]
+    path = (froot / area / f"{slug}.md") if area else (froot / f"{slug}.md")
+    if path.exists():
+        return Result(False, f"feature '{slug}' already exists")
+    fid = ids.allocate(graph, prefix)
+    fm = {"type": "feature", "id": fid, "slug": slug, "title": title}
+    if area:
+        fm["area"] = area
+    if route:
+        fm["route"] = route
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(f"---\n{_dump_frontmatter(fm)}---\n# {title}\n\n", encoding="utf-8")
+    return Result(True, f"created feature '{slug}' ({fid})", [path], entity_id=fid)
+
+
+def delete_feature(graph: Graph, slug: str) -> Result:
+    for feat in graph.features:
+        if feat.slug == slug:
+            feat.path.unlink()
+            return Result(True, f"deleted feature '{slug}'", [feat.path])
+    return Result(False, f"no feature '{slug}'")