Skip to content

livery.workshop._issue_tasks

livery.workshop._issue_tasks

The issue family: the shared work pool and its lifecycle.

issue.create, issue.list, and issue.search are the pool's reads and the one write that files work. The top-level start lives here too, since most work starts from an issue: it picks an issue up (assign within the workspace's limit, branch from a fetched base, open the work in a linked worktree by default), files one from a quoted title, or starts a plain branch that belongs to no issue. issue.stop is start's inverse for an issue: unassign, clean up the local state, and leave the remote branch as the pool's copy. issue.close closes the issue itself, removes the branch it was worked on unless an open pull request comes from that branch, and records where the work got to.

One destruction rule holds everywhere: work that exists nowhere else is never destroyed without --discard, and the refusal's prose names the situation it found.

Functions:

Name Description
assignee_limit

The workspace's assignee limit; policy, not a forge fact.

parse_ref

token as (number, "") or (0, title).

branch_name

<kind>/<number>-<slug>: the number carries identity.

worktree_home

Where this repository's issue worktrees live under the runner's home.

worktree_path

Where the issue's worktree lives: under the runner's home.

issue_default

List the open issues (the bare fm issue).

issue_list

The open issues: number, title, who is on them.

issue_show

One issue in full: title, state, who is on it, the body, and its thread.

issue_search

The open issues whose title or body contains text.

issue_create

File a new issue; start with a title files and starts.

issue_update

Rewrite an issue's title, body, or both.

issue_comment

Add to an issue's thread, leaving its body alone.

start

Start work: an issue by number, a title that files one, or a plain branch.

fetch_base

Fetch origin's heads and the state store in one round trip; print its lines.

start_here

Start branch in this checkout from origin/<base>, or re-enter it.

issue_stop

Stop working on an issue: unassign, clean up the local state.

issue_close

Close the issue itself, and remove the branch it was worked on.

issue_reopen

Reopen a closed issue and put yourself on it, as start does.

Attributes:

Name Type Description
issue

issue module-attribute

issue = group('issue', help='Issues: the shared work pool')

assignee_limit

assignee_limit(root: Path) -> int

The workspace's assignee limit; policy, not a forge fact.

[issues] assignees in the root workshop.toml, default 1 so a free GitLab needs nothing. Enforced by the workshop on every forge, including ones whose native limit is higher; whether the forge itself can honour it is configure's check.

Source code in packages/workshop/src/livery/workshop/_issue_tasks.py
def assignee_limit(root: Path) -> int:
    """The workspace's assignee limit; policy, not a forge fact.

    ``[issues] assignees`` in the root ``workshop.toml``, default 1 so
    a free GitLab needs nothing. Enforced by the workshop on every
    forge, including ones whose native limit is higher; whether the
    forge itself can honour it is ``configure``'s check.
    """
    contract = root / "workshop.toml"
    if not contract.is_file():
        return 1
    data = load_contract(contract)
    return int(data.get("issues", {}).get("assignees", 1))

parse_ref

parse_ref(token: str) -> tuple[int, str]

token as (number, "") or (0, title).

A token livery.workshop._submit.parse_number reads as a number, # or not, is one; anything else is a title to file first. The # matters here: read as a title, #123 would file a junk issue named with the hash.

Source code in packages/workshop/src/livery/workshop/_issue_tasks.py
def parse_ref(token: str) -> tuple[int, str]:
    """*token* as ``(number, "")`` or ``(0, title)``.

    A token [livery.workshop._submit.parse_number][] reads as a
    number, ``#`` or not, is one; anything else is a title to file
    first. The ``#`` matters here: read as a title, ``#123`` would
    file a junk issue named with the hash.
    """
    number = parse_number(token)
    if number is None:
        return 0, token
    return number, ""

branch_name

branch_name(kind: str, number: int, title: str) -> str

<kind>/<number>-<slug>: the number carries identity.

Source code in packages/workshop/src/livery/workshop/_issue_tasks.py
def branch_name(kind: str, number: int, title: str) -> str:
    """``<kind>/<number>-<slug>``: the number carries identity."""
    return f"{kind}/{number}-{_slug(title)}"

worktree_home

worktree_home(root: Path) -> Path

Where this repository's issue worktrees live under the runner's home.

The folder is named after the repository's main checkout, which git reports from any of its worktrees, so work started inside a worktree lands beside the rest. A directory that is no checkout is named by itself.

Source code in packages/workshop/src/livery/workshop/_issue_tasks.py
def worktree_home(root: Path) -> Path:
    """Where this repository's issue worktrees live under the runner's home.

    The folder is named after the repository's main checkout, which git
    reports from any of its worktrees, so work started inside a
    worktree lands beside the rest. A directory that is no checkout is
    named by itself.
    """
    name = root.name
    if (root / ".git").exists():
        name = git.main_checkout(root).name
    return footman.data_dir() / "worktrees" / name

worktree_path

worktree_path(root: Path, number: int, title: str) -> Path

Where the issue's worktree lives: under the runner's home.

Outside every repository, so repo tooling never walks into a worktree, and under a per-user home so a worktree's venv hardlinks from the same filesystem's cache. The home is the runner's own data directory, asked of footman: a footman plugin owns no home of its own.

Source code in packages/workshop/src/livery/workshop/_issue_tasks.py
def worktree_path(root: Path, number: int, title: str) -> Path:
    """Where the issue's worktree lives: under the runner's home.

    Outside every repository, so repo tooling never walks into a
    worktree, and under a per-user home so a worktree's venv
    hardlinks from the same filesystem's cache. The home is the
    runner's own data directory, asked of footman: a footman plugin
    owns no home of its own.
    """
    return worktree_home(root) / f"{number}-{_slug(title)}"

issue_default

issue_default() -> None

List the open issues (the bare fm issue).

Source code in packages/workshop/src/livery/workshop/_issue_tasks.py
@issue.default
def issue_default() -> None:
    """List the open issues (the bare ``fm issue``)."""
    issue_list()

issue_list

issue_list() -> None

The open issues: number, title, who is on them.

Source code in packages/workshop/src/livery/workshop/_issue_tasks.py
@issue.task(name="list")
def issue_list() -> None:
    """The open issues: number, title, who is on them."""
    root = _workspace()
    rows = _repo(root).issue.list(state="open")
    if not rows:
        print("  no open issues")
        return
    for row in rows:
        holders = f"  ({', '.join(row.assignees)})" if row.assignees else ""
        print(f"  #{row.number}  {row.title}{holders}")

issue_show

issue_show(ref: Annotated[Arg[str], ask(), suggest(_open_numbers, strict=False)] = '') -> None

One issue in full: title, state, who is on it, the body, and its thread.

The body is the work order and the thread its continuation, so both print verbatim. The pull request on the issue's branch is named when one is open, since that is where the work stands. The branch is looked up among the local branches and the remote-tracking refs, so the verb asks no remote of git; a lookup git cannot answer is named in one line, and the body and the thread still print.

Source code in packages/workshop/src/livery/workshop/_issue_tasks.py
@issue.task(name="show")
def issue_show(
    ref: Annotated[Arg[str], ask(), suggest(_open_numbers, strict=False)] = "",
) -> None:
    """One issue in full: title, state, who is on it, the body, and its thread.

    The body is the work order and the thread its continuation, so
    both print verbatim. The pull request on the issue's branch is
    named when one is open, since that is where the work stands. The
    branch is looked up among the local branches and the
    remote-tracking refs, so the verb asks no remote of git; a lookup
    git cannot answer is named in one line, and the body and the
    thread still print.
    """
    root = _workspace()
    number, _ = parse_ref(ref)
    if not number:
        fail(f"issue.show takes an issue number; {ref!r} is not one")
    repo = _repo(root)
    found = repo.issue.get(number)
    if found is None:
        fail(f"no issue #{number} on the forge")
    holders = f"  ({', '.join(found.assignees)})" if found.assignees else ""
    labels = f"  [{', '.join(found.labels)}]" if found.labels else ""
    print(f"  #{found.number}  {found.title}{holders}{labels}")
    print(f"  {found.state}  {found.url}".rstrip())
    try:
        branch = _find_branch(root, number, ask_origin=False)
    except git.GitError as error:
        print(f"  the issue's branch could not be looked up: {error}")
        branch = ""
    pull = repo.pr.find_by_head(branch) if branch else None
    if pull is not None and pull.state == "open":
        print(f"  open PR #{pull.number} on {branch}: {pull.title}")
    if found.body.strip():
        print()
        print(found.body.rstrip("\n"))
    for comment in repo.issue.comments(number):
        when = f" {comment.created_at}" if comment.created_at else ""
        print()
        print(f"  --- {comment.author}{when}")
        print(comment.body.rstrip("\n"))
issue_search(text: Arg[str] = '') -> None

The open issues whose title or body contains text.

Source code in packages/workshop/src/livery/workshop/_issue_tasks.py
@issue.task(name="search")
def issue_search(text: Arg[str] = "") -> None:
    """The open issues whose title or body contains *text*."""
    if not text:
        fail(f"name the text to search for: `{footman.prog()} issue.search watcher`")
    root = _workspace()
    for row in _repo(root).issue.search(text):
        print(f"  #{row.number}  {row.title}")

issue_create

issue_create(title: Arg[str] = '', type: Annotated[str, doc('kind label: feat, fix, chore, docs, refactor')] = 'feat', body: Annotated[str, doc('the issue body, readable by an outsider')] = '') -> None

File a new issue; start with a title files and starts.

The kind label is best-effort: a forge or token that refuses labels costs the label, never the issue. Every filed issue should carry a body an outsider can read; correct one later with issue.update.

Source code in packages/workshop/src/livery/workshop/_issue_tasks.py
@issue.task(name="create")
def issue_create(
    title: Arg[str] = "",
    type: Annotated[str, doc("kind label: feat, fix, chore, docs, refactor")] = "feat",
    body: Annotated[str, doc("the issue body, readable by an outsider")] = "",
) -> None:
    """File a new issue; ``start`` with a title files and starts.

    The kind label is best-effort: a forge or token that refuses
    labels costs the label, never the issue. Every filed issue
    should carry a body an outsider can read; correct one later
    with ``issue.update``.
    """
    if not title:
        fail(f'name the issue: `{footman.prog()} issue.create "fix the flaky watch"`')
    root = _workspace()
    repo = _repo(root)
    if type not in _KINDS:
        fail(f"unknown type {type!r}: one of {', '.join(_KINDS)}")
    try:
        created = repo.issue.create(title, body=body, labels=(f"kind/{type}",))
    except ForgeError:
        created = repo.issue.create(title, body=body)
        print("  Note: the kind label was refused; the issue is filed without it")
    print(f"  filed #{created.number}: {created.title}")
    if created.url:
        print(f"  {created.url}")

issue_update

issue_update(number: Arg[int] = 0, title: Annotated[str, doc('the corrected title (empty keeps it)')] = '', body: Annotated[str, doc('the corrected body (empty keeps it)')] = '') -> None

Rewrite an issue's title, body, or both.

Only the provided fields change; clearing a text to empty is not part of the contract. The issue is read first, so a wrong number refuses by name instead of writing nowhere.

Source code in packages/workshop/src/livery/workshop/_issue_tasks.py
@issue.task(name="update")
def issue_update(
    number: Arg[int] = 0,
    title: Annotated[str, doc("the corrected title (empty keeps it)")] = "",
    body: Annotated[str, doc("the corrected body (empty keeps it)")] = "",
) -> None:
    """Rewrite an issue's title, body, or both.

    Only the provided fields change; clearing a text to empty is not
    part of the contract. The issue is read first, so a wrong number
    refuses by name instead of writing nowhere.
    """
    if not number:
        fail(f"name the issue: `{footman.prog()} issue.update 123 --body=...`")
    if not title and not body:
        fail("nothing to change: pass --title, --body, or both")
    root = _workspace()
    repo = _repo(root)
    found = repo.issue.get(number)
    if found is None:
        fail(f"issue #{number} does not exist in this repository")
    repo.issue.update(number, title=title, body=body)
    changed = ", ".join(
        name for name, value in (("title", title), ("body", body)) if value
    )
    print(f"  #{number}: {changed} updated")

issue_comment

issue_comment(number: Arg[int] = 0, body: Annotated[str, doc("what to add to the issue's thread")] = '') -> None

Add to an issue's thread, leaving its body alone.

The body is the work order and the thread its continuation, so a ruling, a measurement or a change of direction goes here rather than into a rewrite of the body, which would replace the specification a reader opens the issue for. The issue is read first, so a wrong number refuses by name instead of writing nowhere.

Source code in packages/workshop/src/livery/workshop/_issue_tasks.py
@issue.task(name="comment")
def issue_comment(
    number: Arg[int] = 0,
    body: Annotated[str, doc("what to add to the issue's thread")] = "",
) -> None:
    """Add to an issue's thread, leaving its body alone.

    The body is the work order and the thread its continuation, so a
    ruling, a measurement or a change of direction goes here rather
    than into a rewrite of the body, which would replace the
    specification a reader opens the issue for. The issue is read
    first, so a wrong number refuses by name instead of writing
    nowhere.
    """
    if not number:
        fail(f"name the issue: `{footman.prog()} issue.comment 123 --body=...`")
    if not body:
        fail("nothing to say: pass --body with the text for the thread")
    root = _workspace()
    repo = _repo(root)
    found = repo.issue.get(number)
    if found is None:
        fail(f"issue #{number} does not exist in this repository")
    repo.issue.comment(number, body)
    print(f"  #{number}: added to the thread")

start

start(ref: Annotated[Arg[str], ask(), suggest(_open_numbers, strict=False)] = '', type: Annotated[str, doc('kind override: feat, fix, chore, docs, refactor')] = '', from_: Annotated[str, doc('start on this pushed, unmerged branch instead of main; submit targets it')] = '', body: Annotated[str, doc('the issue body when the title form files one')] = '', wip: Annotated[bool, doc('park the dirty tree as a commit and reuse this checkout')] = False, worktree: Annotated[bool, doc('open the work in a linked worktree')] = True, agent: Annotated[str, doc('hand the work to a coding agent (implies a worktree)')] = '', prompt: Annotated[str, doc("an initial prompt appended to the agent's briefing")] = '', open: Annotated[str, doc('how to open a worktree: shell, code, or none')] = '') -> None

Start work: an issue by number, a title that files one, or a plain branch.

REF is an issue number (a leading # is accepted), a quoted title, which files the issue first, or <kind>/<slug> (docs/ the-plan) for a branch that belongs to no issue: a note, a small fix. An issue is assigned, and assignment is documentation: at the workspace's assignee limit, or when the forge refuses the write, the start proceeds with a warning that others will not see you on the issue. An issue's branch is <kind>/<number>-<slug> and fm submit closes the issue on merge; a plain branch is named as given and closes nothing. Every branch starts from a fetched origin/main, so a stale base is impossible; --from=<branch> starts on a pushed, unmerged parent instead and records the parent with the commit the branch starts from. fm submit targets the parent until it has merged, and fm sync and fm submit move the branch's own commits when the parent moves or merges. A worktree under the runner's home is the default, entered in a shell when a person is at the terminal (--open=code opens the editor instead, --open=none prints the path); --no-worktree reuses this checkout, where a dirty tree refuses naming --wip (park the tree as a commit; squash-only merging evaporates it) as the escape. --agent launches the named agent in the worktree with a minimal briefing; the worktree's own instructions are the real ones. Re-running on started work re-enters it, in whichever tree holds the branch. A local branch no tree holds is re-entered on its own tip, unless its pull request merged and took that tip: the branch is finished work, so it goes and the start begins fresh.

Source code in packages/workshop/src/livery/workshop/_issue_tasks.py
@footman.task(interactive=True)
def start(
    ref: Annotated[Arg[str], ask(), suggest(_open_numbers, strict=False)] = "",
    type: Annotated[str, doc("kind override: feat, fix, chore, docs, refactor")] = "",
    from_: Annotated[
        str,
        doc("start on this pushed, unmerged branch instead of main; submit targets it"),
    ] = "",
    body: Annotated[str, doc("the issue body when the title form files one")] = "",
    wip: Annotated[
        bool, doc("park the dirty tree as a commit and reuse this checkout")
    ] = False,
    worktree: Annotated[bool, doc("open the work in a linked worktree")] = True,
    agent: Annotated[
        str, doc("hand the work to a coding agent (implies a worktree)")
    ] = "",
    prompt: Annotated[
        str, doc("an initial prompt appended to the agent's briefing")
    ] = "",
    open: Annotated[str, doc("how to open a worktree: shell, code, or none")] = "",
) -> None:
    """Start work: an issue by number, a title that files one, or a plain branch.

    REF is an issue number (a leading ``#`` is accepted), a quoted
    title, which files the issue first, or ``<kind>/<slug>`` (``docs/
    the-plan``) for a branch that belongs to no issue: a note, a small
    fix. An issue is assigned, and assignment is documentation: at the
    workspace's assignee limit, or when the forge refuses the write,
    the start proceeds with a warning that others will not see you on
    the issue. An issue's branch is ``<kind>/<number>-<slug>`` and
    ``fm submit`` closes the issue on merge; a plain branch is named
    as given and closes nothing. Every branch starts from a fetched
    ``origin/main``, so a stale base is impossible; ``--from=<branch>``
    starts on a pushed, unmerged parent instead and records the parent
    with the commit the branch starts from. ``fm submit`` targets the
    parent until it has merged, and ``fm sync`` and ``fm submit`` move
    the branch's own commits when the parent moves or merges. A worktree under
    the runner's home is the default, entered in a shell when a
    person is at the terminal (``--open=code`` opens the editor
    instead, ``--open=none`` prints the path); ``--no-worktree``
    reuses this checkout, where a dirty tree refuses naming ``--wip``
    (park the tree as a commit; squash-only merging evaporates it) as
    the escape. ``--agent`` launches the named agent in the worktree
    with a minimal briefing; the worktree's own instructions are the
    real ones. Re-running on started work re-enters it, in whichever
    tree holds the branch. A local branch no tree holds is re-entered
    on its own tip, unless its pull request merged and took that tip:
    the branch is finished work, so it goes and the start begins fresh.
    """
    if not ref:
        fail(
            f"name what to start: an issue number (`{footman.prog()} start 123`),"
            f' a quoted title (`{footman.prog()} start "fix the flaky watch"`), or'
            f" a branch (`{footman.prog()} start docs/the-plan`)"
        )
    root = _workspace()
    repo = _repo(root)
    if agent:
        worktree = True
    if type and type not in _KINDS:
        fail(f"unknown type {type!r}: one of {', '.join(_KINDS)}")
    plain = _PLAIN_BRANCH_RE.match(ref)
    if plain is None and "/" in ref and " " not in ref:
        fail(
            f"{ref!r} is not a branch this verb starts: spell it"
            f" `<kind>/<slug>` with a kind of {', '.join(_KINDS)} and a"
            " lowercase slug (`docs/the-plan`)"
        )
    if plain is not None:
        kind, slug = plain.group(1), plain.group(2)
        branch = ref
        path = worktree_home(root) / f"{kind}-{slug}"
        briefing = f"Work on branch {branch}."
        started = f"{branch} (no issue; submit closes nothing)"
    else:
        work = _issue_for(repo, ref, type=type, body=body)
        _assign(root, repo, work)
        kind = _issue_kind(work.labels, type)
        branch = branch_name(kind, work.number, work.title)
        path = worktree_path(root, work.number, work.title)
        briefing = f"Work on issue #{work.number}: {work.title}\n\n{work.body}"
        started = branch
    fetch_base(root)
    base = "main"
    if from_:
        if from_ == branch:
            fail(f"--from={from_} names the branch being started")
        if not git.remote_head(root, from_):
            fail(
                f"origin has no branch {from_!r} to start on: push the parent"
                f" first (`{footman.prog()} submit` in its worktree), then"
                " start on it"
            )
        base = from_
    if worktree:
        from livery.workshop._sweep import sweep_worktrees

        for line in sweep_worktrees(worktree_home(root).parent, dry_run=False):
            print(f"  {line}")
        held = _started_at(root, branch, path)
        if held is not None:
            print(f"  already started: {branch} at {held}")
            if held == path:
                # A start that failed after the worktree existed (a sync
                # that met no network) left it unsynced; running the
                # start again is the recovery, so it syncs again.
                _provision(path)
            if agent:
                _launch_agent(agent, held, briefing, branch, prompt)
                return
            _open_work(held, open)
            return
        path.parent.mkdir(parents=True, exist_ok=True)
        if _kept(repo, root, branch):
            # The branch outlived its worktree and is not finished work:
            # a worktree on its own tip re-enters it, its commits kept.
            git.run(root, "worktree", "add", str(path), branch)
            print(f"  worktree {path} on {branch}, its own commits kept")
        else:
            git.run(root, "worktree", "add", str(path), "-b", branch, f"origin/{base}")
            print(f"  worktree {path} on {started}")
            _record_parent(root, branch, from_)
        _provision(path)
        if agent:
            _launch_agent(agent, path, briefing, branch, prompt)
            return
        _open_work(path, open)
        return
    if not git.is_clean(root):
        if wip:
            git.commit_all(root, f"chore(wip): parked by start ({branch})")
            print("  parked the working tree (squash-only merging evaporates it)")
        else:
            fail(
                "the working tree has uncommitted changes.\n"
                f"  Park them and reuse this checkout:  {footman.prog()} start --wip"
                f" --no-worktree {ref}\n"
                "  Or work in a linked worktree:       "
                f"{footman.prog()} start {ref}"
            )
    start_here(root, repo, branch, base=base, parent=from_, started=started)

fetch_base

fetch_base(root: Path) -> None

Fetch origin's heads and the state store in one round trip; print its lines.

What a start does before it cuts a branch: the base is origin's and the store's row series are what the branch's first gate reads, the shape a sync's own fetch has.

Raises:

Type Description
Failed

when origin could not be fetched, in git's words.

Source code in packages/workshop/src/livery/workshop/_issue_tasks.py
def fetch_base(root: Path) -> None:
    """Fetch origin's heads and the state store in one round trip; print its lines.

    What a start does before it cuts a branch: the base is origin's
    and the store's row series are what the branch's first gate reads,
    the shape a sync's own fetch has.

    Raises:
        Failed: when origin could not be fetched, in git's words.
    """
    from livery.git import fetch_store
    from livery.workshop._series import mirrored_series
    from livery.workshop._sync import store_lines

    fetched = fetch_store(
        state_store(root), series=mirrored_series(root), branches=True
    )
    if fetched.why:
        fail(f"origin could not be fetched: {fetched.why}")
    for line in store_lines(fetched):
        print(line)

start_here

start_here(root: Path, repo: Repository, branch: str, *, base: str = 'main', parent: str = '', started: str = '') -> None

Start branch in this checkout from origin/<base>, or re-enter it.

The in-place half of start, which the balancer's submit calls too (livery.workshop._balance.submit). A local branch that is not finished work is switched to as it stands; one whose pull request merged goes, and the start begins fresh. origin/<base> is read as the last fetch left it, so fetch_base comes first. The working tree is the caller's to check: a dirty one carries its changes onto the branch. parent records the branch fm submit targets until it merges; started is how the branch is announced, its name when empty.

Source code in packages/workshop/src/livery/workshop/_issue_tasks.py
def start_here(
    root: Path,
    repo: Repository,
    branch: str,
    *,
    base: str = "main",
    parent: str = "",
    started: str = "",
) -> None:
    """Start *branch* in this checkout from ``origin/<base>``, or re-enter it.

    The in-place half of ``start``, which the balancer's submit calls
    too ([livery.workshop._balance.submit][]). A local *branch* that is
    not finished work is switched to as it stands; one whose pull
    request merged goes, and the start begins fresh. ``origin/<base>``
    is read as the last fetch left it, so `fetch_base` comes first.
    The working tree is the caller's to check: a dirty one carries
    its changes onto the branch. *parent* records the branch ``fm
    submit`` targets until it merges; *started* is how the branch is
    announced, its name when empty.
    """
    if _kept(repo, root, branch):
        git.switch(root, branch)
        print(f"  already started: back on {branch}")
        return
    git.run(root, "checkout", "-b", branch, f"origin/{base}")
    print(f"  on {started or branch}")
    _record_parent(root, branch, parent)

issue_stop

issue_stop(ref: Annotated[Arg[str], ask(), suggest(_open_numbers, strict=False)] = '', discard: Annotated[bool, doc('destroy work that exists nowhere else')] = False) -> None

Stop working on an issue: unassign, clean up the local state.

The remote branch is never touched; while the issue is open it stays the pool's copy. Work that exists nowhere else is never destroyed without --discard, and the refusal names what it found: a delta the remote is missing, a remote gone while the issue is open (exceptional), or an issue already closed.

Source code in packages/workshop/src/livery/workshop/_issue_tasks.py
@issue.task(name="stop")
def issue_stop(
    ref: Annotated[Arg[str], ask(), suggest(_open_numbers, strict=False)] = "",
    discard: Annotated[bool, doc("destroy work that exists nowhere else")] = False,
) -> None:
    """Stop working on an issue: unassign, clean up the local state.

    The remote branch is never touched; while the issue is open it
    stays the pool's copy. Work that exists nowhere else is never
    destroyed without ``--discard``, and the refusal names what it
    found: a delta the remote is missing, a remote gone while the
    issue is open (exceptional), or an issue already closed.
    """
    root = _workspace()
    repo = _repo(root)
    number = 0
    if ref:
        number, _title = parse_ref(ref)
        if not number:
            fail("issue.stop takes a number; a title names nothing to stop")
    else:
        match = _BRANCH_RE.match(git.current_branch(root))
        if match is None:
            fail(
                "not on an issue branch: name the issue"
                f" (`{footman.prog()} issue.stop 123`) or run it from the branch."
            )
        number = int(match.group(1))
    branch = _find_branch(root, number)
    if not branch:
        fail(f"no branch for issue #{number} exists locally or on the remote")

    work = repo.issue.get(number)
    state = work.state if work is not None else "unknown"
    remote_exists = branch in git.remote_branches(root, "")
    merged_head = ""
    try:
        landed = merged_pull_request(repo, root, branch)
        merged_head = landed.head_sha if landed is not None else ""
    except ForgeError:
        merged_head = ""
    only_local = (
        only_local_work(root, branch, merged_head=merged_head)
        if git.local_branch_exists(root, branch)
        else ""
    )
    if only_local and not discard:
        if state == "closed":
            fail(
                f"issue #{number} is already closed, but this branch holds"
                f" {only_local} that exists nowhere else. Push it somewhere"
                " it matters, or pass --discard to destroy it."
            )
        if not remote_exists:
            fail(
                f"the remote branch for issue #{number} is gone while the"
                f" issue is still open, and this branch holds {only_local}."
                " That is not a state stop creates; someone removed the"
                " branch. Push the branch back, or pass --discard to"
                " destroy the local work."
            )
        fail(
            f"this branch holds {only_local} that the remote branch does"
            " not. Push first (`git push`), or pass --discard to destroy"
            " the delta; the remote branch stays as the pool's copy."
        )

    if work is not None and state == "open":
        try:
            repo.issue.unassign(number)
            print(f"  unassigned you from #{number}")
        except ForgeError as error:
            print(f"  Note: could not unassign ({error}); continuing")

    removed = _remove_local(root, branch)
    what = " and ".join(removed) if removed else "nothing local to remove"
    print(f"  stopped #{number}: {what}; the remote branch stays")

issue_close

issue_close(ref: Annotated[Arg[str], ask(), suggest(_open_numbers, strict=False)] = '', reason: Annotated[str, doc('why: done, wontfix, duplicate, stale, ...')] = '', message: Annotated[str, doc('free-text detail for the close comment')] = '', keep_branch: Annotated[bool, doc('retain the local and remote branch')] = False, discard: Annotated[bool, doc('destroy work that exists nowhere else')] = False) -> None

Close the issue itself, and remove the branch it was worked on.

An open pull request from the issue's branch keeps the branch and its worktree: deleting the head branch makes the forge close the pull request unmerged, and the branch may carry work for another issue. The close then ends the issue alone and names the pull request, to be merged or closed first. A forge that cannot say whether such a pull request is open keeps them too, and the line names the forge's error. A pull request that already merged means the work landed, the supplied reason no longer applies, and the close becomes cleanup: "issue already resolved". Otherwise the worktree, the local branch, and the remote branch are removed by default, with the removed head sha recorded in the close comment; --keep-branch retains them.

Source code in packages/workshop/src/livery/workshop/_issue_tasks.py
@issue.task(name="close", interactive=True)
def issue_close(
    ref: Annotated[Arg[str], ask(), suggest(_open_numbers, strict=False)] = "",
    reason: Annotated[str, doc("why: done, wontfix, duplicate, stale, ...")] = "",
    message: Annotated[str, doc("free-text detail for the close comment")] = "",
    keep_branch: Annotated[bool, doc("retain the local and remote branch")] = False,
    discard: Annotated[bool, doc("destroy work that exists nowhere else")] = False,
) -> None:
    """Close the issue itself, and remove the branch it was worked on.

    An open pull request from the issue's branch keeps the branch and
    its worktree: deleting the head branch makes the forge close the
    pull request unmerged, and the branch may carry work for another
    issue. The close then ends the issue alone and names the pull
    request, to be merged or closed first. A forge that cannot say
    whether such a pull request is open keeps them too, and the line
    names the forge's error. A pull request that already merged means
    the work landed, the supplied reason no longer applies, and the
    close becomes cleanup: "issue already resolved". Otherwise the
    worktree, the local branch, and the remote branch are removed by
    default, with the removed head sha recorded in the close comment;
    ``--keep-branch`` retains them.
    """
    if not ref:
        fail(
            "name the issue to close:"
            f" `{footman.prog()} issue.close 123 --reason=wontfix`"
        )
    if not reason:
        fail(
            "closing needs a --reason (done, wontfix, duplicate, stale,"
            " ...): the pool reads why the work ended."
        )
    root = _workspace()
    repo = _repo(root)
    number, _title = parse_ref(ref)
    if not number:
        fail("issue.close takes a number; a title names nothing to close")
    work = repo.issue.get(number)
    if work is None:
        fail(f"issue #{number} does not exist in this repository")

    git.fetch(root)
    branch = _find_branch(root, number)
    tip = git.any_head(root, branch) if branch else ""

    held = _held_by_pull_request(repo, root, branch) if branch else ""
    if held:
        print(f"  {held}")
        _close_with_record(repo, number, reason, message, held)
        return

    # The destruction rule runs before anything is removed: a refusal
    # that checks afterwards would be checking a branch that is
    # already gone. The merged pull request is read first: its head
    # decides what the merge took.
    try:
        landed = merged_pull_request(repo, root, branch) if branch else None
    except ForgeError as error:
        fail(
            f"the forge could not say whether {branch}'s pull request merged"
            f" ({error}); nothing was removed and #{number} stays open."
            " Run the close again when the forge answers."
        )
    merged = landed is not None
    only_local = (
        only_local_work(root, branch, merged_head=landed.head_sha if landed else "")
        if branch and git.local_branch_exists(root, branch)
        else ""
    )

    if merged:
        if reason:
            print("  Note: the PR merged, so the supplied reason does not apply")
        if git.local_branch_exists(root, branch):
            if only_local and not discard:
                print(
                    f"  kept {branch}: it holds {only_local}; pass --discard"
                    " to remove it"
                )
            else:
                _remove_local(root, branch)
        if work.state == "open":
            repo.issue.comment(number, "closed: resolved by the merged PR")
            repo.issue.close(number)
        print("  issue already resolved, nothing left to do")
        return

    if only_local and not discard and not keep_branch:
        fail(
            f"the branch for #{number} holds {only_local} that exists"
            " nowhere else, and close removes branches by default. Pass"
            " --keep-branch to retain them, or --discard to destroy the"
            " work with the issue."
        )

    removed_sha = ""
    if branch and not keep_branch:
        # The tip was read before the branch is deleted: the close
        # comment records where the work got to.
        removed_sha = tip
        _remove_local(root, branch)
        if branch in git.remote_branches(root, ""):
            git.run(root, "push", "origin", "--delete", branch)
            print(f"  removed the remote branch {branch}")

    where = f"removed branch {branch} at {removed_sha}" if removed_sha else ""
    _close_with_record(repo, number, reason, message, where)

issue_reopen

issue_reopen(ref: Annotated[Arg[str], ask()] = '') -> None

Reopen a closed issue and put yourself on it, as start does.

For an issue a merge closed before its work was done (a branch that carried a plan or a pinning test under the issue's number). Reopening an open issue is a no-op, and the assignment follows start's rules: the workspace's limit and a refused write warn and go on.

Source code in packages/workshop/src/livery/workshop/_issue_tasks.py
@issue.task(name="reopen")
def issue_reopen(
    ref: Annotated[Arg[str], ask()] = "",
) -> None:
    """Reopen a closed issue and put yourself on it, as start does.

    For an issue a merge closed before its work was done (a branch
    that carried a plan or a pinning test under the issue's number).
    Reopening an open issue is a no-op, and the assignment follows
    start's rules: the workspace's limit and a refused write warn
    and go on.
    """
    if not ref:
        fail(f"name the issue to reopen: `{footman.prog()} issue.reopen 123`")
    root = _workspace()
    repo = _repo(root)
    number, _title = parse_ref(ref)
    if not number:
        fail("issue.reopen takes a number; a title names nothing to reopen")
    work = repo.issue.get(number)
    if work is None:
        fail(f"issue #{number} does not exist in this repository")
    if work.state == "open":
        print(f"  #{number} is already open")
    else:
        repo.issue.reopen(number)
        print(f"  reopened #{number}: {work.title}")
    _assign(root, repo, work)