@appchy/jarvis 0.1.37 → 0.1.39

package/harness/harness/ids.py

@@ -0,0 +1,140 @@
+"""The ledger id vocabulary — ONE definition of what a durable-rule id looks like,
+so the letter is a repo setting rather than a constant baked into eight regexes.
+
+A repo picks its own prefix: `D-nn`, `G-nn`, `ADR-nn`. The harness is otherwise
+identical, and a fork that differs only in a letter is a fork that drifts — so the
+letter lives here and nowhere else. `jarvis work where <id>` resolves whichever a repo
+uses, because ids are permanent and only their HOME moves.
+
+Everything downstream builds its pattern from `LEDGER` instead of writing `G-\\d+`
+inline. Adding a second recognised prefix later (a merged repo, a migration window)
+is a change to this list, not a sweep.
+"""
+import re
+
+#: The prefix this repo's durable rules carry. One token, no trailing dash.
+#: Overridden per-repo by `ids.prefix` in `.claude/work.config.json`; the value
+#: here is the shipped default, used when no config is present.
+LEDGER = "D"
+
+#: Prefixes a citation may legally use. The first is canonical — `id_new` and
+#: every scaffold write this one. Extras are recognised but never generated,
+#: which is how a migration window stays readable without going silent.
+RECOGNISED = (LEDGER,)
+
+#: Whether the DASH is optional when reading — `D12` as well as `D-12`.
+#: OFF by default, and that default is a bug fix. A short prefix collides with
+#: ordinary data the moment the dash is optional: a repo whose prefix is `P` had
+#: every `priority: P0` in its task frontmatter read as a citation to a rule `P-0`
+#: that does not exist, and `align` reported it as a dangling citation in seven
+#: files. Turn it on only where an interface really does publish undashed ids.
+UNDASHED = False
+
+
+def configure(prefix: str, recognised: tuple = (), undashed: bool = False) -> None:
+    """Rebind the vocabulary from config, once, before anything parses.
+
+    Every pattern below is rebuilt rather than reassigned piecemeal, because a
+    module that captured `ID` at import time would keep the default and report a
+    repo's entire ledger as dangling — the failure mode is a wall of false
+    warnings, which is how a lint stops being read.
+    """
+    global LEDGER, RECOGNISED, UNDASHED, ID, ID_EXACT
+    LEDGER = prefix.rstrip("-")
+    RECOGNISED = tuple(dict.fromkeys((LEDGER, *(r.rstrip("-") for r in recognised))))
+    UNDASHED = undashed
+    ID = re.compile(_id_pattern())
+    ID_EXACT = re.compile(rf"^(?:{'|'.join(RECOGNISED)})-(?!0+\Z)\d+\Z")
+
+
+def _id_pattern() -> str:
+    """The dash is REQUIRED unless a repo opts into `UNDASHED`. Writes always emit
+    the dashed canonical form either way.
+
+    **Number zero is not an id.** Ledger numbering starts at 1 in every repo, so
+    `<PREFIX>-0` can only be a typo or — the case that found this — prose ABOUT an
+    id-shaped token. A handoff log recording the undashed-prefix bug had to write
+    the words "`priority: P0` was read as a citation to `P-0`", and `align` then
+    reported `P-0` as a dangling citation in the very note explaining that it
+    isn't one. Excluding it here rather than in the citation check keeps one
+    definition of what an id is: `where P-0` now says it is not an id, instead of
+    hunting for a home that cannot exist.
+    """
+    dash = "-?" if UNDASHED else "-"
+    return rf"\b(?:{'|'.join(RECOGNISED)}){dash}(?!0+\b)\d+\b"
+
+
+#: An id anywhere in a line of prose.
+ID = re.compile(_id_pattern())
+
+#: An id anchored for exact-match validation — no surrounding text allowed.
+#:
+#: `\Z` rather than `$`, which in Python matches before a trailing newline: `"D-12\n"`
+#: passed as an exact id and reached a gate that then wrote the newline into a
+#: heading. And zero is excluded here for the reason `_id_pattern` excludes it, so the
+#: two answers to "is this an id" cannot disagree.
+ID_EXACT = re.compile(rf"^(?:{'|'.join(RECOGNISED)})-(?!0+\Z)\d+\Z")
+
+
+def pattern(group: bool = True) -> str:
+    """The bare id regex as a string, for embedding in a larger pattern.
+
+    `group=True` captures the id; callers that only need to anchor a heading pass
+    False so their own groups keep their numbering.
+    """
+    # The alternation is grouped, or with two recognised prefixes this reads as
+    # "prefix A, or prefix B followed by -nn" — and a bare `D` in any heading gets
+    # indexed as a rule id. `_id_pattern` has always grouped it; this had not.
+    alt = "|".join(RECOGNISED)
+    return rf"((?:{alt})-\d+)" if group else rf"(?:(?:{alt})-\d+)"
+
+
+def heading(level: int = 3) -> re.Pattern:
+    """`### D-nn — title` — a definition site. Level 2 is a system's `## D-nn`."""
+    return re.compile(rf"^{'#' * level}\s+{pattern()}\b", re.MULTILINE)
+
+
+def titled_heading(level: int = 3) -> re.Pattern:
+    """`### D-nn — title`, capturing (id, title). An entry with no title is not a
+    definition — `align` reports it rather than indexing a blank."""
+    return re.compile(rf"^{'#' * level}\s+{pattern()}\s*[—-]\s*(.+)$", re.MULTILINE)
+
+
+def index_entry() -> re.Pattern:
+    """`- **D-nn** — title` or `- D-nn — title`, the Index line shapes.
+
+    The bold is optional because it is typography, not structure: one repo writes
+    the id bare and another writes it bold, and an Index the parser cannot read
+    reports every entry as missing.
+    """
+    return re.compile(rf"^-\s+\*{{0,2}}{pattern()}\*{{0,2}}\s*[—-]\s*(.+)$", re.MULTILINE)
+
+
+def sort_key(id_: str) -> int:
+    """Numeric order, prefix- and dash-agnostic, so 9 sorts before 10 rather than
+    lexicographically.
+
+    The digits AFTER the last dash, never every digit in the string. A prefix need
+    only be alphanumeric, so `ADR2` is legal, and stripping non-digits turned
+    `ADR2-14` into 214 — which then fed "the highest id anywhere" and had `normalise`
+    fabricating `ADR2-214`.
+    """
+    tail = id_.rsplit("-", 1)[-1] if "-" in id_ else id_
+    digits = re.sub(r"\D", "", tail)
+    return int(digits) if digits else 0
+
+
+def normalise(id_: str) -> str:
+    """Undashed or lower-case in, dashed canonical out. The one place that form
+    is made.
+
+    **The prefix it was written with survives.** `RECOGNISED` exists precisely so a
+    repo can read a second prefix through a migration, and rewriting every one of them
+    to `LEDGER` collapsed the two id spaces into one: `normalise("ADR-7")` returned
+    `"D-7"`, so `where ADR-7` printed D-7's rule and a citation to either resolved to
+    the other. Only the FORM is canonicalised here — the dash and the case — never
+    which ledger an id belongs to.
+    """
+    head = id_.rsplit("-", 1)[0] if "-" in id_ else re.sub(r"\d+$", "", id_)
+    known = {r.lower(): r for r in RECOGNISED}
+    return f"{known.get(head.strip().lower(), LEDGER)}-{sort_key(id_)}"

package/harness/harness/kickoff.py

@@ -0,0 +1,231 @@
+"""The opening prompt for the NEXT session — derived, not written by hand.
+
+A wrap ends with a prompt that opens the next session on this work. For a long
+time that prompt was authored by whichever session happened to be wrapping, from
+a template in `commands/wrap.md`, and it had one defect that made it useless as
+shipped: **it never invoked the skill.** `SessionStart` tells a fresh session the
+harness is here; nothing in it makes the session LOAD it. So every handed-over
+prompt had the skill's own name typed in front of it by hand before it could be
+used — every session, by the one person the handoff exists to save.
+
+That is exactly the kind of fact a template cannot hold and a derivation can. The
+command comes from `instructions.skill`, the paths come from the tree, the status
+and next step come from the handoff the wrap has just made current, and the
+standards the plan is held against come from `spine.*`. Nothing here is repeated
+prose about any particular repo.
+
+**The prompt is the whole brief the session starts with.** There is no second
+message: `session_start` takes one string, the session takes its turn, and then
+it sits open waiting for a person. So this file is not a nudge — it is the entire
+contract with a session that will begin work unattended, which is why it states
+the order (orient → settle what is open → state the plan → then code) rather than
+assuming a fresh session infers it.
+"""
+from pathlib import Path
+
+from .model import locate
+from .tree import cli, die, find_work_root, rel
+
+#: `graph.mcp`, `session.mcp`, `session.tool`, `spine.*`, `instructions.skill` —
+#: bound by `config.apply` rather than re-read here, for the same reason every
+#: other module reads module attributes: one reader of the config file, and it is
+#: not this.
+GRAPH_MCP = None
+SESSION_MCP = None
+SESSION_TOOL = None
+SPINE = []
+SKILL = None
+
+_RULE = "─" * 72
+
+
+def _handoff_line(text: str, label: str):
+    """The `**Status:**` / `**NEXT:**` line out of a handoff, or None.
+
+    Read from the handoff rather than asked for on the command line, because the
+    wrap has just written them there and a value typed twice is a value that
+    disagrees with itself. The template pins both to the top two lines; this
+    tolerates them anywhere, since a session that moved them still meant them.
+    """
+    for raw in text.splitlines():
+        line = raw.strip()
+        if line.lower().startswith(f"**{label.lower()}:**"):
+            value = line[len(label) + 5:].strip()
+            # An unfilled template placeholder is not a status. Passing
+            # `<one line — where the task is right now.>` into the next session
+            # as fact is worse than passing nothing, which at least sends it to
+            # the handoff to look.
+            if value and not value.startswith("<"):
+                return value
+    return None
+
+
+def _open_questions(task) -> list:
+    """Unanswered questions on the task — the same pairing `autonomy` does.
+
+    Imported through the module rather than duplicated: `asked:` is an
+    append-only transcript where an answer cancels the longest-waiting question,
+    and a second reader of that shape is a second place for it to be read wrong.
+    """
+    from .autonomy import _open_questions as read
+    return read(task)
+
+
+def build_prompt(task, root: Path, next_step=None, watch=None) -> str:
+    """The prompt itself. Everything in it is derived except `watch`, which only
+    the session that just did the work can know."""
+    handoff = task.folder / "handoff.md"
+    text = handoff.read_text() if handoff.is_file() else ""
+    status = _handoff_line(text, "Status")
+    nxt = next_step or _handoff_line(text, "NEXT")
+
+    # **The first line is prose, and the skill comes second — deliberately.**
+    # Two reasons, both learned from using it. A message that OPENS with a slash
+    # command renders as a command invocation and takes over the session view, so
+    # the founder cannot see the conversation at all. And the opening line is what
+    # shows in session history: `Continue <task> — <title>` says which work this
+    # session is, where a bare command says only that a command ran.
+    #
+    # The cost is real and is paid on purpose: off line one it is no longer parsed
+    # as a slash command, so it must read as an INSTRUCTION the session acts on
+    # rather than as an invocation the client performs. That is what the line below
+    # is for, and why it says "before anything else" instead of just naming it.
+    # Do not move it back to the top.
+    lines = [f"Continue `{task.name}` — {task.title}.", ""]
+    # Silent when the repo names no command. The harness cannot derive one any more
+    # — it no longer lives inside the thing that owns slash commands — and a line
+    # telling a session to load something that resolves for nobody is worse than no
+    # line at all, in the one place whose whole job is loading the harness.
+    if SKILL:
+        lines.append(f"Load {SKILL} before anything else — it is the harness "
+                     f"this repo runs on, and everything below is its board.")
+        lines.append("")
+
+    # Paths, not contents. The handoff is the carrier the wrap has just made
+    # current, and a prompt that inlined it would be a second copy going stale
+    # from the moment it was sent — while the session it is sent to can read the
+    # file itself, in the repo it is standing in.
+    if handoff.is_file():
+        lines.append(f"  handoff   {rel(handoff, root)}   ← read this first; it holds "
+                     f"what the last session learned")
+    else:
+        lines.append("  handoff   NONE — this task has no handoff.md, so nothing "
+                     "carried across but the brief")
+    lines.append(f"  brief     {rel(task.md, root)}")
+    epic = task.folder.parents[1] / "epic.md"
+    if epic.is_file():
+        lines.append(f"  epic      {rel(epic, root)}   (§Plan — the calls the epic "
+                     f"already settled)")
+    lines.append("")
+
+    if status:
+        lines.append(f"Status: {status}")
+    if nxt:
+        lines.append(f"Next:   {nxt}")
+    if watch:
+        lines.append(f"Watch out for: {watch}")
+    if status or nxt or watch:
+        lines.append("")
+
+    open_qs = _open_questions(task)
+    if open_qs:
+        lines.append("This task has questions nobody has answered yet. They come "
+                     "before the work:")
+        lines += [f"  - {q}" for q in open_qs]
+        lines.append("")
+
+    lines.append("Before you write any code:")
+    lines.append(f"  1. Orient. Read the files above in that order, then `{cli()} list` "
+                 "for the board around them.")
+    lines.append("  2. Settle what is open. Answer it, or park it — "
+                 f"`{cli()} ask {task.name} --question \"…\"` records a question and "
+                 f"moves on; it never blocks.")
+    if GRAPH_MCP:
+        lines.append(f"  3. Map the blast radius through the `{GRAPH_MCP}` graph "
+                     f"before proposing a non-trivial plan.")
+    else:
+        lines.append("  3. Map the blast radius. No graph engine is configured here, "
+                     "so the sweep is grep-wide — say so in the plan rather than "
+                     "implying a map you did not get.")
+    held = (" and how it holds against " + " · ".join(SPINE)) if SPINE else ""
+    lines.append("  4. State the plan back before writing anything: the shapes, "
+                 "interfaces, types and signature changes it makes" + held + ". "
+                 "Report it, then proceed.")
+    lines.append("")
+    # The founder's call, 2026-08-21, and it is the difference between this and a
+    # status-report prompt: the successor is picking the work UP. Left unsaid, a
+    # session handed a handoff tends to summarise it back and stop.
+    lines.append("Then do the work. You are picking this up, not reporting on it — "
+                 "the plan is the pause, not the deliverable.")
+    return "\n".join(lines)
+
+
+def session_name(task) -> str:
+    """What to call the session this prompt opens.
+
+    The picker, the prompt box and the terminal title all show it, and without
+    one Claude Code derives a name from the FOLDER — identical for every session
+    in a repo, so several runs are told apart only by an id nobody reads.
+
+    A run is numbered by how many have already worked the item, so the first is
+    just the title and the fifth says it is the fifth. The number leads because
+    that is the column a picker never truncates, and the count comes off
+    `sessions:` rather than being carried in the prompt: the wrap has just
+    recorded the run doing the wrapping, so the successor is the next one along
+    and nothing has to remember what number it is.
+    """
+    ordinal = len(task.sessions) + 1
+    return task.title if ordinal == 1 else f"{ordinal} · {task.title}"
+
+
+def cmd_kickoff(args) -> int:
+    root = find_work_root()
+    task = locate(root, args["name"])
+    if not task:
+        die(f"no task named '{args['name']}' found")
+    prompt = build_prompt(task, root, args.get("next"), args.get("watch"))
+
+    # `--prompt-only` is the pipe. Everything else this command prints is
+    # instruction for the CALLER, and a caller that pipes wants none of it.
+    if args.get("prompt-only") == "true":
+        print(prompt)
+        return 0
+
+    repo = root.parent
+    print("KICKOFF PROMPT — pass verbatim as `prompt`, with nothing added:")
+    print(_RULE)
+    print(prompt)
+    print(_RULE)
+
+    if not SESSION_MCP:
+        # Not an error, and said as a mode rather than a lack. A repo with nothing
+        # that can start a session still gets everything above; it is carried
+        # across by a person, which is what the wrap always did.
+        print("no session starter configured (`session.mcp` is null) — hand the "
+              "block above to a person, or name the MCP server that can start a "
+              "session in this repo in .claude/work.config.json.")
+        return 0
+
+    if not SESSION_TOOL:
+        # Unreachable through a loaded config — `session.mcp` without
+        # `session.tool` is refused at load. Held anyway, because the line below
+        # composes a tool name a model is told to call, and one built around a
+        # missing half resolves to nothing while reading like a real instruction.
+        print(f"`session.mcp` names {SESSION_MCP!r} but `session.tool` is unset, so "
+              f"there is no tool to call — hand the block above to a person.")
+        return 0
+    tool = f"mcp__{SESSION_MCP}__{SESSION_TOOL}"
+    print(f"start it:  {tool}")
+    print(f"           prompt = the block above, verbatim")
+    print(f"           cwd    = {repo}")
+    print(f"           name   = {session_name(task)}")
+    # The one check that separates a session from a session id. A start that
+    # reports `outlivesThisConnection: false` ran in-process, as a child of the
+    # caller — so it dies with the very session that started it, while looking
+    # exactly like success: created, stamped, titled, and with zero turns ever
+    # taken. Measured on this machine 2026-08-21, not feared.
+    print(f"then:      the answer must say `outlivesThisConnection: true`. FALSE "
+          f"means the session is a child of this one and dies with it — report "
+          f"that as a failure, not a start.")
+    print(f"           record it: `{cli()} session {task.name} --id <sessionId>`")
+    return 0