@appchy/jarvis 0.1.36 → 0.1.39

package/harness/harness/model.py

@@ -0,0 +1,364 @@
+import os
+import re
+from datetime import date
+from pathlib import Path
+
+from .tree import BUCKETS, DONE_TIER, PRIORITIES, RESERVED_MD
+from .frontmatter import as_list, parse_frontmatter, read_item, rewrite_file, title_of
+
+
+def current_session_id() -> str:
+    return os.environ.get("CLAUDE_CODE_SESSION_ID", "").strip()
+def record_session(folder: Path, sid=None, label=None) -> bool:
+    """Append a Claude Code session to a task's frontmatter, deduped by session
+    id. Returns True when a new entry was added.
+
+    `sid` defaults to the CURRENT session, which is every caller but one. The
+    exception is a session this one STARTED: the wrap opens the successor and is
+    the only thing that will ever know both ids, and with no way to pass one the
+    link was hand-written into the handoff as prose and inferred by nothing. A
+    board fact belongs on the board.
+
+    `label` is appended to the entry so the two are told apart on sight. It is
+    not a separate field: `sessions:` is a flat list read by several things, and
+    a second shape for one entry would break every one of them to record a word.
+    """
+    sid = sid or current_session_id()
+    if not sid:
+        return False
+    md = folder / "task.md"
+    if not md.is_file():
+        return False
+    text = read_item(md)
+    sessions = as_list(parse_frontmatter(text).get("sessions"))
+    if any(sid in entry for entry in sessions):
+        return False
+    entry = f"{date.today().isoformat()}  {sid}" + (f"  {label}" if label else "")
+
+    # The check that matters happens INSIDE the mutation, against the text being
+    # written rather than the one read a moment earlier — otherwise a write landing
+    # between the two records the same session twice.
+    def mutate(d):
+        if any(sid in existing for existing in as_list(d.get("sessions"))):
+            return
+        d["sessions"] = as_list(d.get("sessions")) + [entry]
+        d["updated"] = date.today().isoformat()
+
+    rewrite_file(md, mutate)
+    return True
+class Task:
+    """A task folder with a task.md inside it. `status` is the bucket name
+    (`queue`/`in-progress`/`complete`) for tasks in a version; `None` for a
+    backlog task (no status until pulled).
+
+    `epic` is the name of the epic holding it, or None for a loose task in a
+    version that has not adopted the epic shape (v20/v24 at the reshape). It is
+    DERIVED from where the folder sits — never a frontmatter field, for the same
+    reason status isn't: two writers for one fact is how they drift apart."""
+
+    def __init__(self, folder: Path, status, version, in_backlog: bool = False,
+                 epic=None):
+        self.folder = folder
+        self.name = folder.name
+        self.status = status
+        self.version = version
+        self.in_backlog = in_backlog
+        self.epic = epic
+        self.md = folder / "task.md"
+        self.fm = parse_frontmatter(self.md.read_text())
+        self.title = title_of(self.md)
+        self.priority = str(self.fm.get("priority", "P2")).strip()
+        self.depends_on = as_list(self.fm.get("depends_on"))
+        self.code = as_list(self.fm.get("code"))
+        self.covers = as_list(self.fm.get("covers"))
+        # `owner:` is canonical; `product:` is the pre-domain spelling still on
+        # disk while the rename lands. One reader, so no consumer has to know.
+        self.owner = str(self.fm.get("owner")
+                         or self.fm.get("product") or "").strip()
+        self.legacy_product = "owner" not in self.fm and "product" in self.fm
+        self.start = (str(self.fm.get("start", "")).strip() or None)
+        self.end = (str(self.fm.get("end", "")).strip() or None)
+        self.sessions = as_list(self.fm.get("sessions"))
+        self.updated = str(self.fm.get("updated", "")).strip()
+        self.completed = str(self.fm.get("completed", "")).strip()
+        self.artifacts = sorted(
+            p.name for p in folder.glob("*.md")
+            if p.name not in ("task.md", "stories.md")
+        )
+
+    def priority_rank(self) -> int:
+        return PRIORITIES.index(self.priority) if self.priority in PRIORITIES else 9
+
+    def display_status(self) -> str:
+        return self.status if self.status else "backlog"
+def _version_order(fm: dict, name: str) -> int:
+    """Derive a version's roadmap sort order: an explicit `order:`
+    frontmatter value wins; else a leading numeric prefix in the name
+    (`0-scene-generator` -> 0, `3-poc-map` -> 3); else 9999 so un-ordered
+    versions sort last rather than breaking the roadmap."""
+    raw = str(fm.get("order", "")).strip()
+    if raw:
+        try:
+            return int(raw)
+        except ValueError:
+            pass
+    m = re.match(r"^(\d+)-", name)
+    if m:
+        return int(m.group(1))
+    return 9999
+def _is_epic_dir(p: Path) -> bool:
+    """Is this subdirectory of a version an epic? It carries `epic.md` while it
+    is being planned, and only its buckets once `release` has removed that —
+    either shape counts, or a released version's own tasks would vanish from
+    every listing. The version's own bucket dirs are excluded by name."""
+    if not p.is_dir() or p.name in BUCKETS:
+        return False
+    return (p / "epic.md").is_file() or any((p / b).is_dir() for b in BUCKETS)
+class Epic:
+    """An `epic.md` folder — the TEMPORARY tier between a version and its tasks:
+    the coherent goal you plan together, holding the tasks that deliver it.
+
+    Two shapes, one class. In a version it owns bucket subdirs
+    (`<v>/<epic>/{queue,in-progress,complete}/<task>/`); in the backlog its tasks
+    sit directly under it (`backlog/<epic>/<task>/`) because a backlog task has
+    no status until it is pulled — the same reason `backlog/` never had buckets.
+
+    An epic is temporary BY DEFINITION: `release` removes `epic.md`, because how
+    the work was planned stops being true the moment it ships. The folder stays
+    as the grouping of what shipped; git holds the plan."""
+
+    def __init__(self, folder: Path, version=None, in_backlog: bool = False):
+        self.folder = folder
+        self.name = folder.name
+        self.md = folder / "epic.md"
+        # After release the plan doc is gone and only the grouping remains, so
+        # everything read from epic.md must tolerate its absence — otherwise
+        # `release` would make its own tasks unreachable, which is a far worse
+        # bug than a missing title.
+        self.planned = self.md.is_file()
+        self.fm = parse_frontmatter(self.md.read_text()) if self.planned else {}
+        self.title = title_of(self.md) if self.planned else folder.name
+        self.version = version
+        self.in_backlog = in_backlog
+        # Read off the PATH rather than passed in, so it cannot be set to something
+        # the tree disagrees with — the folder's home is the only statement of it.
+        self.done_tier = folder.parent.name == DONE_TIER
+        self.covers = as_list(self.fm.get("covers"))
+        # Same vocabulary as a task's `owner:` — a bare `<feature>` or a bare
+        # org-domain. It exists on an epic for one reason: an epic owned by a
+        # DOMAIN has no `AC-nn` layer to qualify against, because a domain hosts
+        # rules rather than criteria. Naming that domain is how such an epic
+        # states its finish line instead of leaving `covers:` to read as an
+        # oversight. An epic owned by a FEATURE has criteria available and is
+        # still expected to name them.
+        self.owner = str(self.fm.get("owner") or "").strip()
+        # The epic this one carries on from, in an earlier cut. An epic name is
+        # globally unique, so work moved into a later version arrives under a new
+        # name and would otherwise read as a fresh goal that happens to resemble an
+        # old one — losing the plan that already settled how to build it.
+        self.continues = str(self.fm.get("continues") or "").strip()
+        self.tasks: dict = {b: [] for b in BUCKETS}
+        self.backlog_tasks: list = []
+        if in_backlog:
+            for p in sorted(folder.iterdir()):
+                if p.is_dir() and (p / "task.md").is_file():
+                    self.backlog_tasks.append(
+                        Task(p, status=None, version=None, in_backlog=True,
+                             epic=self.name)
+                    )
+        else:
+            for b in BUCKETS:
+                bucket = folder / b
+                if not bucket.is_dir():
+                    continue
+                for p in sorted(bucket.iterdir()):
+                    if p.is_dir() and (p / "task.md").is_file():
+                        self.tasks[b].append(
+                            Task(p, status=b, version=version, epic=self.name)
+                        )
+
+    def all_tasks(self) -> list:
+        return self.backlog_tasks + [t for b in BUCKETS for t in self.tasks[b]]
+
+    def is_done(self) -> bool:
+        """Every task in it is complete — and there is at least one.
+
+        An EMPTY epic is deliberately not done: a goal nobody has cut tasks for has
+        not been achieved, it has not been started, and parking it out of sight is
+        the one way this tier could hide work instead of revealing it."""
+        tasks = self.all_tasks()
+        return bool(tasks) and all(t.status == "complete" for t in tasks)
+class Version:
+    """A version folder with version.md — a RELEASE, not a container of ideas:
+    it states the user-visible `outcome:` it delivers, and cannot open while an
+    earlier version is still unreleased.
+
+    Holds EPICS (`<v>/<epic>/`), each with its own buckets. Versions that
+    predate the epic tier hold their tasks in buckets directly, and both shapes
+    are read here — `all_tasks()` returns the union, so every consumer sees one
+    flat list and none of them had to learn the nesting."""
+
+    def __init__(self, folder: Path):
+        self.folder = folder
+        self.name = folder.name
+        self.md = folder / "version.md"
+        self.fm = parse_frontmatter(self.md.read_text())
+        self.title = title_of(self.md)
+        self.order = _version_order(self.fm, self.name)
+        self.outcome = str(self.fm.get("outcome", "")).strip()
+        self.start = (str(self.fm.get("start", "")).strip() or None)
+        self.end = (str(self.fm.get("end", "")).strip() or None)
+        self.target = str(self.fm.get("target", "")).strip()
+        self.released = str(self.fm.get("released", "")).strip()
+        # Loose tasks — the pre-epic shape, still read so grandfathered versions
+        # keep working untouched (v20/v24 hold live work at the reshape).
+        self.tasks: dict = {b: [] for b in BUCKETS}
+        for b in BUCKETS:
+            bucket = folder / b
+            if not bucket.is_dir():
+                continue
+            for p in sorted(bucket.iterdir()):
+                if p.is_dir() and (p / "task.md").is_file():
+                    self.tasks[b].append(
+                        Task(p, status=b, version=self.name)
+                    )
+        # Epics sit at the version's top level while they are MOVING, and drop into
+        # `<v>/complete/` once every task in them is done — so the board shows work in
+        # flight and finished goals stop being something to read past. The tier is
+        # DERIVED and materialized by `_settle_epic_tier`, never hand-set: an epic is
+        # in `complete/` because its tasks put it there, and reopening one moves it
+        # straight back out. Both tiers are read here, so every consumer still sees one
+        # `epics` list and none of them had to learn the nesting.
+        self.epics: list = [
+            Epic(p, version=self.name) for p in sorted(folder.iterdir())
+            if _is_epic_dir(p)
+        ]
+        done_tier = folder / DONE_TIER
+        if done_tier.is_dir():
+            self.epics += [
+                Epic(p, version=self.name) for p in sorted(done_tier.iterdir())
+                if _is_epic_dir(p)
+            ]
+
+    def loose_tasks(self) -> list:
+        return [t for b in BUCKETS for t in self.tasks[b]]
+
+    def all_tasks(self) -> list:
+        return self.loose_tasks() + [t for e in self.epics for t in e.all_tasks()]
+
+    def bucket(self, name: str) -> list:
+        """Every task in one bucket, across the loose tier and every epic."""
+        return self.tasks[name] + [t for e in self.epics for t in e.tasks[name]]
+
+    def status(self) -> str:
+        """`released` if version.md carries a released date; `current` if any
+        task is in-progress; otherwise `planned`."""
+        if self.released:
+            return "released"
+        if any(t.status == "in-progress" for t in self.all_tasks()):
+            return "current"
+        return "planned"
+def scan(root: Path) -> dict:
+    """Return {versions: [Version], backlog: [Task], backlog_epics: [Epic]}.
+
+    `backlog` is EVERY backlog task — loose ones and the ones inside a backlog
+    epic — so the many consumers that walk it are unaffected by the epic tier.
+    `backlog_epics` is there for the few that care about the grouping."""
+    versions = []
+    vdir = root / "versions"
+    if vdir.is_dir():
+        for v in sorted(vdir.iterdir()):
+            if v.is_dir() and (v / "version.md").is_file():
+                versions.append(Version(v))
+    # Roadmap order, not folder-name lexicographic — `order:` wins,
+    # else a `NN-slug` name prefix, else last (`_version_order`).
+    versions.sort(key=lambda v: (v.order, v.name))
+
+    backlog, backlog_epics = [], []
+    bdir = root / "backlog"
+    if bdir.is_dir():
+        # A folder is an EPIC if it holds epic.md, a TASK if it holds task.md.
+        # The marker file is the discriminator, so there is no registry to keep
+        # in step with the tree.
+        for sub in sorted(bdir.iterdir()):
+            if not sub.is_dir():
+                continue
+            if (sub / "epic.md").is_file():
+                epic = Epic(sub, in_backlog=True)
+                backlog_epics.append(epic)
+                backlog += epic.backlog_tasks
+            elif (sub / "task.md").is_file():
+                backlog.append(
+                    Task(sub, status=None, version=None, in_backlog=True)
+                )
+
+    return {"versions": versions, "backlog": backlog,
+            "backlog_epics": backlog_epics}
+def locate(root: Path, name: str):
+    """Find a task by name anywhere. Returns a Task or None."""
+    s = scan(root)
+    for v in s["versions"]:
+        for t in v.all_tasks():
+            if t.name == name:
+                return t
+    for t in s["backlog"]:
+        if t.name == name:
+            return t
+    return None
+def locate_version(root: Path, name: str):
+    """Find a version by name. Looks in `archive/versions/` too, so a released
+    cut stays LOOKUPABLE after it leaves the board — `path` and `where` keep
+    answering, while `scan` (and therefore `list`, the README and every lint)
+    sees only live work. Archived is off the board, not gone."""
+    for base in ("versions", "archive/versions"):
+        folder = root / base / name
+        if (folder / "version.md").is_file():
+            return Version(folder)
+    return None
+def locate_epic(root: Path, name: str):
+    """Find an epic by name anywhere — in a version or in the backlog. Names are
+    globally unique across tasks, epics and versions, so a name alone resolves."""
+    s = scan(root)
+    for v in s["versions"]:
+        for e in v.epics:
+            if e.name == name:
+                return e
+    for e in s["backlog_epics"]:
+        if e.name == name:
+            return e
+    return None
+def epic_home(root: Path, epic: "Epic") -> str:
+    """A human-readable home for an epic — `version '<v>'` or `backlog`."""
+    return "backlog" if epic.in_backlog else f"version '{epic.version}'"
+def locate_feature(root: Path, name: str):
+    """The one place that resolves `<feature>` to its spec FILE — mirrors
+    `locate_version`. `cmd_feature_new` and `_owner_ref_lint` both use it so the
+    existence check can't drift between "scaffold" and "lint" call sites.
+
+    There is no app tier and no folder tier: this repo is ONE product, so a feature
+    name is globally unique and `product/<feature>.md` is its whole address.
+    Returns the .md, not a directory — a feature no longer HAS a directory."""
+    md = root / "product" / f"{name}.md"
+    return md if md.is_file() and md.name not in RESERVED_MD else None
+def scan_features(root: Path) -> list:
+    """Every feature spec, as a list of `.md` paths. The mirror of
+    `scan_systems`, and the one definition of "what counts as a feature file" —
+    three call sites globbed `product/*/feature.md` before the flatten, and a
+    flat glob would sweep up `README.md` if each re-derived the filter."""
+    product = root / "product"
+    if not product.is_dir():
+        return []
+    return [p for p in sorted(product.glob("*.md")) if p.name not in RESERVED_MD]
+def _ordered(buckets: dict) -> list:
+    """in-progress, then blocked, then queue (by priority), then complete.
+
+    Blocked sits SECOND, directly under what is moving — above the queue, not
+    filed away near what is finished. It is the only bucket whose contents are
+    somebody's obligation rather than the harness's, and a board that buries the
+    one list a person has to act on is a board that quietly reinstates the
+    babysitting.
+    """
+    return (buckets["in-progress"]
+            + buckets["blocked"]
+            + sorted(buckets["queue"], key=lambda t: (t.priority_rank(), t.name))
+            + buckets["complete"])

package/harness/harness/peers.py

@@ -0,0 +1,187 @@
+"""Somebody else is on this — and here is whether you can reach them.
+
+**What was already known, and thrown away.** The harness has always recorded who
+else is working. A `.claim` holds an instance id; a board commit holds
+`Work-Session` and `Work-Machine`. What every surface then DID with that knowledge
+was print eight hex characters — `held by a7c5d0cb` — which names a session without
+reaching one. The id was right there and led nowhere, so the only move left was to
+wait for a lease to expire, or take the work and collide.
+
+So one function turns an id into the thing a session can act on: whether that
+instance is on THIS machine, where `ListAgents` lists it and `SendMessage` reaches
+it, or on another, where it cannot be reached from here at all.
+
+**It never sends anything.** Not on a collision, not on a plan change, not ever.
+An agent that messages another agent without the person in the loop is a
+conversation nobody asked for and nobody can take back, so this decides nothing and
+starts nothing: it says who, and whether they are reachable. Acting on that is the
+session's call, and the person's.
+
+**Reach is honest about its edge.** `SendMessage` addresses sessions on this
+machine (and whatever Remote Control has connected). A claim from another host is
+therefore reported as unreachable rather than left looking addressable — a name you
+cannot deliver to is worse than a plain statement that you cannot. Carrying a
+message between machines is a transport a repo brings with it; this harness reports
+the reach it actually has and does not invent one.
+"""
+import json
+import os
+from pathlib import Path
+
+from . import git
+
+#: How much of an instance id is worth showing. Eight hex characters is what every
+#: surface here has always printed and what `ListAgents` matches on sight.
+SHORT = 8
+
+
+def me() -> str:
+    """This session's own instance id — the same one a claim is written with."""
+    return git._session()
+
+
+def here() -> str:
+    """This machine's name, by the same rule a commit trailer uses. One answer, so
+    a claim and a commit can never disagree about which box they came from."""
+    return git.machine()
+
+
+#: Where an agent client publishes the sessions it currently has running. Claude
+#: Code is the only one that publishes anything today; the shape is one JSON file
+#: per process carrying its own session id, its addressable name and its pid.
+#: Overridable so this is testable without a real home directory.
+SESSIONS = "WORK_SESSIONS_DIR"
+DEFAULT_SESSIONS = "~/.claude/sessions"
+
+#: Answers already worked out this run, keyed by the directory they came from. Keyed
+#: rather than a single slot because the tests point this at several directories in
+#: one process, and a cache that ignored where it read from would answer for the
+#: wrong one.
+_RUNNING = {}
+
+
+def running():
+    """Every agent session live on THIS machine as `{session id: name}`, or `None`
+    when nothing here publishes that at all.
+
+    The `None` is the whole point and must not be flattened into an empty dict. No
+    directory means *this client does not say*, which is where Codex and Gemini sit
+    — and a caller that reads "nothing is running" from silence would report every
+    peer as dead on the clients that are least able to argue. An empty dict is a
+    different and much stronger claim: something published a list and this session
+    was not on it.
+
+    A pid is checked rather than trusted. The directory is cleaned up on exit, so in
+    practice it holds only live runs, but a process killed hard leaves its file
+    behind — and a stale entry here would resurrect exactly the ghost this exists to
+    catch. Signal 0 asks the kernel whether the pid is there without touching it.
+
+    **Known limit: a recycled pid reads as alive.** If a session is killed hard AND
+    the operating system later hands its number to some unrelated program, this says
+    running about a session that is gone. It is not closed here, and the alternatives
+    were worse: every artifact that could corroborate the pid — the messaging socket
+    included — is left behind by the same hard kill, so pairing two stale files
+    proves nothing, and reading a process's start time needs a child process this
+    module is deliberately not allowed to spawn. What bounds it instead is where the answer is used: one
+    row on a status screen reading "running" instead of "ended", never a board write,
+    which is the constraint the rule about a client's facts already sets.
+
+    The result is cached per directory for the life of the process. The harness is a
+    short-lived command, so re-globbing and re-signalling once per printed row is
+    repeated work for an answer that cannot change inside one run.
+    """
+    where = Path(os.path.expanduser(os.environ.get(SESSIONS) or DEFAULT_SESSIONS))
+    key = str(where)
+    if key in _RUNNING:
+        return _RUNNING[key]
+    if not where.is_dir():
+        _RUNNING[key] = None
+        return None
+    out = {}
+    for f in sorted(where.glob("*.json")):
+        try:
+            entry = json.loads(f.read_text(encoding="utf-8", errors="replace"))
+        except (json.JSONDecodeError, ValueError, OSError):
+            continue  # a half-written file is not a dead session
+        if not isinstance(entry, dict):
+            continue
+        run, pid = str(entry.get("sessionId", "")), entry.get("pid")
+        if not run:
+            continue
+        try:
+            # Strictly positive: signal 0 to pid 0 asks about the whole process
+            # group and to a negative pid about another one, so either would answer
+            # "alive" about something that is not this session at all.
+            if int(pid) <= 0:
+                continue
+            os.kill(int(pid), 0)
+        except (TypeError, ValueError, ProcessLookupError):
+            continue
+        except PermissionError:
+            pass  # alive and owned by somebody else, which is still alive
+        out[run] = str(entry.get("name", "")).strip()
+    _RUNNING[key] = out
+    return out
+
+
+def describe(instance: str, host: str = "") -> str:
+    """`instance` (and the machine it sits on) as a line that says what to do next.
+
+    Answers that are genuinely different actions: it is you (carry on), it is
+    somebody elsewhere (you cannot reach them from here), or it is somebody on this
+    machine — and that last one splits again on whether they are still running.
+
+    That split is the correction. This used to promise that any id on this machine
+    could be reached, which is a promise about a process nobody had checked was
+    alive. It was believed: a run steering another run guessed at an address, a
+    different session recognised the description of itself, acted on it, and wrote
+    into the brief of work it was not doing. An id whose session has exited is not a
+    peer to negotiate with, it is abandoned work — and those want opposite moves.
+    """
+    who = (instance or "").strip()
+    if not who:
+        return "an unnamed session"
+    short = who[:SHORT]
+    if who == me():
+        return f"{short} — this session"
+    box = (host or "").strip()
+    if box and here() and box != here():
+        return (f"{short} on {box} — another machine, so it cannot be reached from "
+                f"here; the board is the only thing you share")
+    live = running()
+    if live is None:
+        return (f"{short} — this machine: `ListAgents` lists it, `SendMessage` reaches "
+                f"it if the plan needs to change")
+    if who not in live:
+        return (f"{short} — this machine, but that session has ENDED: there is "
+                f"nobody to reach, so this is abandoned rather than held")
+    name = live[who]
+    if not name:
+        return (f"{short} — this machine and still running, though it publishes no "
+                f"name to address it by")
+    return (f"`{name}` ({short}) — this machine and still running: `SendMessage` "
+            f"reaches it if the plan needs to change")
+
+
+def of_claim(claim: dict) -> str:
+    """The same line, from a `.claim` — which carries the machine since this
+    landed, so a hold taken elsewhere reads as elsewhere rather than as local."""
+    return describe(str(claim.get("instance", "")), str(claim.get("machine", "")))
+
+
+def arrivals(rows: list) -> str:
+    """What just landed on the board from somewhere else, as one line.
+
+    Read from the commits a pull brought in, so it answers the question a session
+    actually has when the ground moves under it — *who changed the plan, and can I
+    ask them about it* — rather than announcing that a fetch happened.
+    """
+    others = [r for r in rows if str(r.get("by", "")) != me()]
+    if not others:
+        return ""
+    items = sorted({str(r.get("name", "")) for r in others if r.get("name")})
+    sources = sorted({(str(r.get("by", "")), str(r.get("machine", "")))
+                      for r in others if r.get("by") or r.get("machine")})
+    said = "; ".join(describe(who, host) for who, host in sources) or "another session"
+    shown = ", ".join(items[:4]) + (f" +{len(items) - 4} more" if len(items) > 4 else "")
+    return f"the board moved under you — {shown or 'board edits'} · from {said}"

package/harness/harness/product.py

@@ -0,0 +1,29 @@
+from .tree import die, find_work_root, rel
+from .model import locate_feature
+from .scaffold import _check_kebab, _check_state, _scaffold_feature
+from .generate import _sync
+
+
+def cmd_feature_new(args) -> int:
+    """Scaffold `work/product/<feature>.md`.
+
+    There is no `--app`, and no `app-new`: this repo is ONE product, so a feature
+    sits directly under `product/` and its name is globally unique — which is
+    also why `owner:` is a bare feature name. It is a FILE, not a folder holding
+    one file: the path a spec is cited by must never change again, and a folder
+    that appears the day a sibling arrives is a path that changes on file count
+    (`AC-20`)."""
+    root = find_work_root()
+    name = args["name"]
+    _check_kebab("feature", name)
+    if locate_feature(root, name):
+        die(f"a feature named '{name}' already exists")
+    md = root / "product" / f"{name}.md"
+    if md.exists():
+        die(f"{rel(md, root)} already exists")
+    state = args.get("state") or "idea"
+    _check_state(state)
+    _scaffold_feature(md, state)
+    print(f"created {rel(md, root)}")
+    _sync(root)
+    return 0