gemba-cli 0.1.0__py3-none-any.whl

gemba/assets/skills/gemba-worktree/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: gemba-worktree
+description: Check out the repositories of a task as git worktrees inside its harness, list them and remove them. Use whenever, inside a harness, the user asks to check out, attach, add or open a repository of the task, to start a repository from another branch, to list or show the worktrees, their branches or what is not pushed, or to detach, drop or remove a worktree, whatever the workstream.
+---
+
+# Work on repositories in worktrees
+
+A worktree is a checkout of another repository under `worktrees/` of the harness, on
+one local branch of the run that gemba names after the task. The `gemba worktree`
+commands create, move, list and remove the worktrees and their branches; every git
+command against the repository a worktree comes from is theirs. Your part is to choose
+the repositories and the base branch, run the commands, relay what they print, and do
+the work of the task inside the worktrees.
+
+Every organization-specific value (the repositories folder, the workstreams and their
+rules) lives in `gemba.yaml`, at the tasks repo root. Run
+`gemba config show --workstream <id>`, with the `workstream` of `harness.yaml`, on every
+run and rely on nothing else you know or remember about repositories, branches or
+workstreams. It prints the config resolved, from anywhere inside the harness:
+`repos_dir` at the top level, and in the entry of the workstream, under
+`processes.worktree`, the block of every verb, such as `processes.worktree.add`, with
+the block shared by every workstream already joined to the workstream's. Wherever this
+skill says to read a block, read its `context` as background and follow every entry of
+its `rules` in order; when two rules contradict, follow the later one.
+
+## Prerequisite
+
+The `gemba` command must be on the PATH. It is installed once from PyPI with
+`uv tool install gemba-cli` and checked with `gemba --version`. If `gemba` is not
+found, stop and tell the user to install it with that command. Every verb runs inside a
+harness, from its root or any folder below it. Never run `git worktree` or
+`git branch`, and never run any git command in the repository a worktree comes from.
+
+## Add
+
+1. **Find the repositories the task needs** in `task.md` and in the notes of the run.
+   Name each one by its folder name under the `repos_dir` that `gemba config show`
+   prints, such as `nakatomi-web`. When a name is not clear from them, ask the user; never
+   browse `repos_dir` or any folder above the harness to guess it.
+2. **Read the `worktree.add` block**, `processes.worktree.add` of the document. Read
+   `context` as background and follow every entry of `rules`: they say which branch each
+   repository starts from.
+3. **Choose the base.** Without `--from`, the worktree starts at the default branch of
+   `origin`. Pass `--from <branch>` when the rules, the task or the user name another
+   branch of `origin`. Only a branch is a base: never pass a tag or a commit.
+4. **Run the command** once per repository:
+
+   ```bash
+   gemba worktree add <repo> [--from <branch>]
+   ```
+
+5. **Relay** what it printed: the worktree path, `branch:`, `from:` and `created`, or
+   `already attached, worktree unchanged` when the repository is already checked out in
+   this harness. When it refuses, relay every line, the repositories it names as found
+   at the root of `repos_dir` included, and ask the user how to go on; never work
+   around a refusal.
+
+## Branches
+
+- The branch of a worktree is local: gemba names it after the run, it exists only on
+  this machine and it is never pushed under its own name.
+- It starts with no upstream. Inside the worktree, commit, fetch and pull freely; a
+  pull needs the upstream that the first push sets.
+- A push reaches the remote, so it needs an `external-action` note whose frontmatter
+  reads `approved: true` and that names the branch of the remote. The push always names
+  its target, `git push -u origin HEAD:<the branch the note names>`; the first one sets
+  the upstream, which `gemba worktree list` then shows. Never run `git push` alone or
+  `git push origin HEAD`.
+- To start again from another base, run `gemba worktree add <repo> --from <branch>` on
+  the repository already attached: it moves the branch of the run to that base and
+  keeps its name. It is not a rebase: it refuses while anything is uncommitted or on no
+  remote branch, and even after a push it discards the local tree. To carry your
+  commits onto another base instead, rebase inside the worktree with
+  `git rebase --onto origin/<new base> origin/<old base>`.
+
+## List
+
+Read the `worktree.list` block, `processes.worktree.list` of the document, and run:
+
+```bash
+gemba worktree list
+```
+
+For each worktree it prints its path, `branch:`, `upstream:` (`none` until a push sets
+it), `uncommitted:`, the number of paths not committed, and `unpushed:`, the number of
+commits on no remote branch. Every value is read from git when it runs. Relay them; a
+folder listed as `not a worktree` was not created by gemba, so tell the user. With no
+worktree it prints `no worktrees`.
+
+## Remove
+
+1. **Read the `worktree.remove` block**, `processes.worktree.remove` of the document.
+   Read `context` as background and follow every entry of `rules` before showing the
+   state.
+2. **Show the state** by running the command without `--yes`:
+
+   ```bash
+   gemba worktree remove <repo>
+   ```
+
+   It prints the block `list` prints for that worktree, then
+   `not removed: pass --yes to delete the worktree`, and deletes nothing.
+3. **Ask the user.** Show them the state, ask whether to remove the worktree and its
+   local branch, and remind them to close any editor window open on that folder first.
+   A yes in the conversation is enough: the worktree and its branch are local.
+4. **Remove only after a yes**, by running the same command with `--yes`:
+
+   ```bash
+   gemba worktree remove <repo> --yes
+   ```
+
+   When the user says no, stop. Relay `removed`: the worktree and its local branch are
+   gone, and the remote is what it was.
+
+## When work is pending
+
+`gemba worktree add --from` prints `worktree not moved:` and `gemba worktree remove`
+prints `worktree not removed:` while the worktree holds uncommitted paths or commits on
+no remote branch. Relay every line and say how each is saved: uncommitted paths by a
+commit inside the worktree; commits on no remote branch by a push through an approved
+`external-action` note. Never commit, push or delete anything to make the command pass.
+
+**Never force first.** `--force` discards work. Never pass it on the first run of
+`add --from` or `remove`, even when the user asks to force it: run the command without
+it, relay what it reports as pending, and pass `--force` only after the user confirms,
+in the conversation, that everything in that list is to be discarded. The same holds
+for `add --force` without `--from`, which deletes and recreates a branch of the run
+left without a worktree, discarding its commits.
+
+## Rules
+
+- The commands own the worktrees and the branches of the run. Never run `git worktree`
+  or `git branch`, and never run git in the repository a worktree comes from.
+- Nothing reaches the remote without an `external-action` note whose frontmatter reads
+  `approved: true`.
+- When `gemba.yaml` changes, follow the new content. This skill never needs an edit when
+  a workstream, a rule or the repositories folder is added, changed or removed.

gemba/cli.py

@@ -0,0 +1,35 @@
+"""Entry point of the `gemba` command: subcommand dispatch and `--version`."""
+
+import argparse
+import sys
+from collections.abc import Sequence
+from importlib.metadata import version
+from typing import NoReturn
+
+from gemba.commands import archive, config, create, harness, init, mark, record, report, skills, worktree
+from gemba.commands import list as list_  # named after the process; the alias keeps list() usable
+from gemba.commands import set as set_  # named after the process; the alias keeps set() usable
+
+COMMANDS = (init, create, list_, skills, config, harness, record, mark, archive, report, set_, worktree)
+
+
+class ArgumentParser(argparse.ArgumentParser):
+    """Argument parser whose usage errors exit with 1, like every other gemba error."""
+
+    def error(self, message: str) -> NoReturn:
+        self.print_usage(sys.stderr)
+        self.exit(1, f"{self.prog}: error: {message}\n")
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = ArgumentParser(prog="gemba", description="Task-based system for working with AI agents.")
+    parser.add_argument("--version", action="version", version=version("gemba-cli"))
+    subparsers = parser.add_subparsers(dest="command", metavar="<command>")
+    for command in COMMANDS:
+        command.register(subparsers)
+
+    args = parser.parse_args(argv)
+    if args.command is None:
+        parser.print_help(sys.stderr)
+        return 1
+    return args.handler(args)

gemba/commands/__init__.py

@@ -0,0 +1 @@
+"""One module per process of Gemba, each exposing `register(subparsers)`."""

gemba/commands/archive.py

@@ -0,0 +1,62 @@
+"""`gemba archive`: move tasks that went cold into the archive folder of their workstream."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path, PurePosixPath
+
+from gemba import config, harness, tasks
+
+
+def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    parser = subparsers.add_parser(
+        "archive",
+        help="move tasks into the archive folder of their workstream",
+        description=(
+            f"Move the file of each task, unchanged, into {tasks.TASKS_DIR}/<workstream>/{tasks.ARCHIVE_DIR}/, "
+            "whatever its status. Each ref is handled on its own and gets one line, archived or not archived; "
+            "the exit code is 1 when any ref was refused. A task whose harness folder exists is refused. "
+            "Nothing is committed."
+        ),
+    )
+    parser.add_argument(
+        "refs", nargs="+", metavar="ref", help="ref of a task, such as SUP-1; give several to archive them"
+    )
+    parser.add_argument("--root", type=Path, help="tasks repo root (default: walk up to the nearest gemba.yaml)")
+    parser.set_defaults(handler=run)
+
+
+def run(args: argparse.Namespace) -> int:
+    try:
+        gemba_config = config.load(root=args.root)
+    except config.ConfigError as exc:
+        print(f"gemba archive: {exc}", file=sys.stderr)
+        return 1
+
+    root = gemba_config.root
+    refused = False
+    for ref in args.refs:
+        try:
+            task = tasks.find_by_ref(root, gemba_config.workstreams, ref)
+        except tasks.TaskError as exc:
+            problem = f"cannot be resolved: {exc}"
+        else:
+            if task is None:
+                problem = f"is the ref of no task under {tasks.TASKS_DIR}/, archives included"
+            else:
+                folder = harness.harness_path(root, task.workstream, PurePosixPath(task.path).stem)
+                destination = tasks.archive_destination(task)
+                problem = tasks.archive_problem(
+                    task,
+                    folder.relative_to(root).as_posix() if folder.exists() else None,
+                    (root / destination).exists(),
+                )
+                if problem is None:
+                    (root / destination).parent.mkdir(parents=True, exist_ok=True)
+                    (root / task.path).rename(root / destination)
+                    print(f"archived: {destination}")
+                    continue
+        refused = True
+        print(f"not archived: {ref} {problem}")
+    return 1 if refused else 0

gemba/commands/config.py

@@ -0,0 +1,117 @@
+"""`gemba config check` and `gemba config show`: validate gemba.yaml, then summarize or resolve it."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from gemba import config
+from gemba.commands import selection
+
+
+def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    parser = subparsers.add_parser(
+        "config",
+        help="check the gemba config or show it resolved",
+        description=(
+            f"Read {config.CONFIG_FILENAME}, the config of the tasks repo, without ever writing it: the file is "
+            "edited by hand."
+        ),
+    )
+    parser.set_defaults(handler=lambda _args: usage(parser))
+    verbs = parser.add_subparsers(dest="verb", metavar="<verb>")
+
+    check = verbs.add_parser(
+        "check",
+        help="validate the config and summarize it",
+        description=(
+            f"Validate {config.CONFIG_FILENAME} as every command does before acting. A valid config is summarized "
+            "with its workstreams and prefixes, its default workstream and its agent providers; an invalid one is "
+            "reported with the path of the file and the first problem, and the command exits 1."
+        ),
+    )
+    check.add_argument("--root", type=Path, help="tasks repo root (default: walk up to the nearest gemba.yaml)")
+    check.set_defaults(handler=run_check)
+
+    show = verbs.add_parser(
+        "show",
+        help="print the effective config as one JSON document",
+        description=(
+            f"Validate {config.CONFIG_FILENAME} as check does and print the effective config as one JSON object: "
+            "the top-level keys, the defaults applied and null where nothing is declared, and `workstreams`, in "
+            "catalogue order, each with its prefix, its description, its effective metadata schema and, under "
+            "`processes`, the effective block of every process and verb, the base block followed by the "
+            "workstream's."
+        ),
+    )
+    show.add_argument("--workstream", metavar="ID", help="workstream identifier from gemba.yaml (default: every one)")
+    show.add_argument("--root", type=Path, help="tasks repo root (default: walk up to the nearest gemba.yaml)")
+    show.set_defaults(handler=run_show)
+
+
+def run_check(args: argparse.Namespace) -> int:
+    try:
+        gemba_config = config.load(root=args.root)
+    except config.ConfigError as exc:
+        return fail("check", str(exc))
+
+    workstreams = ", ".join(
+        f"{workstream.id} ({workstream.prefix})" for workstream in gemba_config.workstreams.values()
+    )
+    providers = ", ".join(gemba_config.agent_providers) if gemba_config.agent_providers else "none declared"
+    print(f"{config.CONFIG_FILENAME} is valid")
+    print(f"workstreams: {workstreams}")
+    print(f"default workstream: {gemba_config.default_workstream}")
+    print(f"agent providers: {providers}")
+    return 0
+
+
+def run_show(args: argparse.Namespace) -> int:
+    try:
+        gemba_config = config.load(root=args.root)
+    except config.ConfigError as exc:
+        return fail("show", str(exc))
+
+    if args.workstream is not None and args.workstream not in gemba_config.workstreams:
+        return fail(
+            "show",
+            f"unknown workstream '{args.workstream}' (valid workstreams: {', '.join(gemba_config.workstreams)})",
+        )
+    shown = [args.workstream] if args.workstream is not None else list(gemba_config.workstreams)
+    document = {
+        "organization": gemba_config.organization,
+        "branch_prefix": gemba_config.branch_prefix,
+        "repos_dir": gemba_config.repos_dir,
+        "ide": gemba_config.ide,
+        "agent_providers": None if gemba_config.agent_providers is None else list(gemba_config.agent_providers),
+        "default_workstream": gemba_config.default_workstream,
+        "workstreams": [workstream(gemba_config, workstream_id) for workstream_id in shown],
+    }
+    print(selection.dump(document))
+    return 0
+
+
+def workstream(gemba_config: config.Config, workstream_id: str) -> dict[str, object]:
+    """The entry of one workstream in the document of show."""
+    declared = gemba_config.workstreams[workstream_id]
+    return {
+        "id": declared.id,
+        "prefix": declared.prefix,
+        "description": declared.description,
+        "metadata": [
+            {"name": field.name, "type": field.type, "required": field.required, "description": field.description}
+            for field in gemba_config.effective_schema(workstream_id)
+        ],
+        "processes": gemba_config.effective_processes(workstream_id),
+    }
+
+
+def usage(parser: argparse.ArgumentParser) -> int:
+    parser.print_help(sys.stderr)
+    return 1
+
+
+def fail(verb: str, message: str) -> int:
+    print(f"gemba config {verb}: {message}", file=sys.stderr)
+    return 1

gemba/commands/create.py

@@ -0,0 +1,104 @@
+"""`gemba create`: validate a creation request, allocate the ref and write the task file."""
+
+from __future__ import annotations
+
+import argparse
+import datetime
+import sys
+from pathlib import Path
+
+from gemba import config, metadata, tasks, values
+
+CREATION_STATUSES = ("open", "in-progress", "blocked")
+
+
+def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    parser = subparsers.add_parser(
+        "create",
+        help="create a task file",
+        description="Validate the request against gemba.yaml, allocate the ref and write the task file.",
+    )
+    parser.add_argument("--workstream", required=True, help="workstream identifier from gemba.yaml")
+    parser.add_argument("--slug", required=True, help="lowercase ASCII words joined by single hyphens")
+    parser.add_argument("--date", help="creation date as YYYY-MM-DD (default: today)")
+    parser.add_argument("--status", default="open", help="open (default), in-progress or blocked")
+    parser.add_argument("--description", help="short description written at the top of the body")
+    parser.add_argument(
+        "--set",
+        dest="assignments",
+        action="append",
+        default=[],
+        metavar="KEY=VALUE",
+        help="metadata value, converted by the declared type of its field (null for none); "
+        "repeat a key of a text field to build a list",
+    )
+    parser.add_argument("--root", type=Path, help="tasks repo root (default: walk up to the nearest gemba.yaml)")
+    parser.set_defaults(handler=run)
+
+
+def run(args: argparse.Namespace) -> int:
+    try:
+        gemba_config = config.load(root=args.root)
+    except config.ConfigError as exc:
+        return fail(str(exc))
+
+    errors = []
+    workstream = gemba_config.workstreams.get(args.workstream)
+    if workstream is None:
+        errors.append(
+            f"unknown workstream '{args.workstream}' (valid workstreams: {', '.join(gemba_config.workstreams)})"
+        )
+    if not tasks.is_valid_slug(args.slug):
+        errors.append(f"invalid slug '{args.slug}': use lowercase ASCII letters and digits joined by single hyphens")
+    if args.status == "done":
+        errors.append("status 'done' is not allowed at creation (allowed: open, in-progress, blocked)")
+    elif args.status not in CREATION_STATUSES:
+        errors.append(f"invalid status '{args.status}' (allowed: open, in-progress, blocked)")
+    created, date_error = parse_date(args.date)
+    if date_error:
+        errors.append(date_error)
+    assignments, assignment_errors = metadata.parse_assignments(args.assignments, allow_add=False)
+    errors.extend(assignment_errors)
+
+    task_metadata: dict[str, object] = {}
+    if workstream is not None:
+        schema = gemba_config.effective_schema(workstream.id)
+        assigned = metadata.assign(schema, {}, assignments, f"'{workstream.id}'")
+        errors.extend(assigned.problems)
+        task_metadata = assigned.values
+
+    if errors:
+        return fail("task not created:\n" + "\n".join(f"- {error}" for error in errors))
+    assert workstream is not None and created is not None, "every failed check above appended an error"
+
+    ref = tasks.next_ref(gemba_config.root, workstream.prefix)
+    folder = gemba_config.root / tasks.TASKS_DIR / workstream.id
+    target = folder / tasks.filename(created, ref, args.slug)
+    relative = target.relative_to(gemba_config.root).as_posix()
+    if target.exists():
+        return fail(f"task not created: {relative} already exists")
+
+    for path in (folder, folder / tasks.ARCHIVE_DIR):
+        path.mkdir(parents=True, exist_ok=True)
+        (path / tasks.GITKEEP).touch(exist_ok=True)
+    content = tasks.render(args.status, ref, created, task_metadata, args.description)
+    with target.open("x", encoding="utf-8") as handle:
+        handle.write(content)
+
+    print(relative)
+    print(ref)
+    return 0
+
+
+def parse_date(text: str | None) -> tuple[datetime.date | None, str | None]:
+    if text is None:
+        return datetime.date.today(), None
+    created = values.iso_date(text)
+    if created is None:
+        return None, f"invalid date '{text}': use YYYY-MM-DD"
+    return created, None
+
+
+def fail(message: str) -> int:
+    print(f"gemba create: {message}", file=sys.stderr)
+    return 1