bugpilot 0.1.0__py3-none-any.whl

bugpilot/core/branch_policy.py

@@ -0,0 +1,223 @@
+"""Which branch an agent works and commits on: the developer's choice.
+
+BugPilot never runs ``git branch``, ``git checkout``, ``git switch``,
+``git add``, ``git commit`` or ``git push`` itself. What it controls is what
+the task tells the agent, and that used to be one rule for everyone: create or
+switch to ``feature/<work-item>-<slug>`` before editing. A hand-written bug
+gets a new ``local_<timestamp>`` id on every run, so every run named a new
+branch; and a developer already working on a branch of their own was moved off
+it.
+
+Three policies, recorded per work item with the hint and the Fix Mode:
+
+- ``current`` (the default): work on the branch that is checked out. Never
+  create or switch one — except that on ``main``/``master`` or a detached HEAD
+  the agent stops and asks before creating the suggested branch.
+- ``per-issue``: one branch for the work item, created once and reused — the
+  name is recorded the first time and every later preparation names the same
+  one.
+- ``ask``: before editing, the agent asks whether to stay on the current
+  branch or create or switch to the suggested one.
+
+The lifecycle rule under all three: preparing the same work item again — Run,
+Rebuild Context, a retry, a new attempt — never calls for a new branch. Only
+the policy decides when a branch is created or switched.
+
+Whatever the policy, ``main`` and ``master`` are protected: nothing is edited,
+committed or pushed on them, and a commit is never made on a detached HEAD. No
+policy and no setting can relax that.
+
+Every sentence about branches in a task, a guardrail, the delivery checks and
+a retry prompt comes from this module.
+"""
+
+from __future__ import annotations
+
+import re
+
+from .identity import is_local_work_item_id
+
+BRANCH_POLICY_CURRENT = "current"
+BRANCH_POLICY_PER_ISSUE = "per-issue"
+BRANCH_POLICY_ASK = "ask"
+
+BRANCH_POLICIES: tuple[str, ...] = (BRANCH_POLICY_CURRENT, BRANCH_POLICY_PER_ISSUE, BRANCH_POLICY_ASK)
+DEFAULT_BRANCH_POLICY = BRANCH_POLICY_CURRENT
+
+# Never written to, under any policy. Not configurable.
+PROTECTED_BRANCHES: tuple[str, ...] = ("main", "master")
+
+# What a recorded branch name may look like: a plain ref, nothing to escape.
+_BRANCH_NAME_RE = re.compile(r"[A-Za-z0-9][A-Za-z0-9._/-]{0,199}")
+
+_POLICY_NAMES = {
+    BRANCH_POLICY_CURRENT: "use the current branch",
+    BRANCH_POLICY_PER_ISSUE: "one branch per work item",
+    BRANCH_POLICY_ASK: "ask the developer",
+}
+
+# The lifecycle rule, said in every task.
+_NO_NEW_BRANCH_FOR_REPREPARING = (
+    "- Preparing this work item again — Run, Rebuild Context, a retry, a new attempt — "
+    "does not call for a new branch."
+)
+
+
+def check_branch_policy(value: str | None) -> str | None:
+    """``value`` if it is a policy, ``None`` if absent; anything else is refused."""
+    if value is None:
+        return None
+    policy = value.strip().lower()
+    if policy not in BRANCH_POLICIES:
+        raise ValueError(
+            f"Unknown branch policy {value!r}. Use one of: {', '.join(BRANCH_POLICIES)}."
+        )
+    return policy
+
+
+def resolve_branch_policy(requested: str | None, recorded: str | None) -> str:
+    """The policy in force: the request's, else what the work item recorded, else the default.
+
+    A recorded value that is not a policy (an issue.json edited by hand, or
+    written by a later version) is ignored rather than fatal: the default is safe.
+    """
+    if requested is not None:
+        return check_branch_policy(requested) or DEFAULT_BRANCH_POLICY
+    if recorded in BRANCH_POLICIES:
+        return recorded  # type: ignore[return-value]
+    return DEFAULT_BRANCH_POLICY
+
+
+def usable_branch_name(value: object) -> str | None:
+    """A recorded branch name, if it is one a task may quote; else ``None``.
+
+    The record is read back into ``task.md`` inside backticks, so a name that is
+    not a plain ref (a hand-edited ``issue.json``) is dropped and derived again
+    rather than quoted.
+    """
+    if not isinstance(value, str):
+        return None
+    name = value.strip()
+    return name if _BRANCH_NAME_RE.fullmatch(name) and ".." not in name else None
+
+
+def records_branch_name(policy: str) -> bool:
+    """Whether the work item's branch is recorded, so later preparations reuse it.
+
+    ``current`` names a branch only as a suggestion for main/master, so it is
+    derived afresh; the other two may have the agent create one, and that one
+    is the branch every later preparation must name.
+    """
+    return policy != BRANCH_POLICY_CURRENT
+
+
+def _existing_branch_clause(issue_key: str) -> str:
+    """For a Jira work item: a branch already made for its key counts as its branch."""
+    if is_local_work_item_id(issue_key):
+        return ""
+    return f", or another existing branch whose name contains `{issue_key}`"
+
+
+def branch_instructions(policy: str, branch: str, issue_key: str = "") -> str:
+    """``task.md``'s Branch Instructions section, heading included."""
+    lines = [f"- Branch policy: {_POLICY_NAMES[policy]}."]
+    if policy == BRANCH_POLICY_PER_ISSUE:
+        lines += [
+            f"- Branch name: `{branch}`",
+            "- Check the current branch before editing.",
+            "- Never work directly on main/master.",
+            f"- Create or switch to `{branch}` before editing files — from a detached HEAD too. "
+            f"If it already exists{_existing_branch_clause(issue_key)}, switch to it rather than creating another.",
+            f"{_NO_NEW_BRANCH_FOR_REPREPARING} Reuse this one.",
+        ]
+    elif policy == BRANCH_POLICY_ASK:
+        lines += [
+            f"- Suggested branch name: `{branch}`",
+            "- Check the current branch before editing.",
+            "- Never work directly on main/master.",
+            "- Before editing, tell the developer the current branch and the suggested branch "
+            f"`{branch}`, and ask whether to stay on the current branch or to create or switch to "
+            "the suggested one; then do as they answer.",
+            "- If the current branch is `main` or `master`, or HEAD is detached, staying is not an "
+            f"option: ask only whether to create or switch to `{branch}`.",
+            _NO_NEW_BRANCH_FOR_REPREPARING,
+        ]
+    else:
+        lines += [
+            "- Check the current branch before editing.",
+            "- Work on the branch that is currently checked out. Do not create or switch branches.",
+            "- Edit only on the current branch.",
+            "- Never work directly on main/master.",
+            _NO_NEW_BRANCH_FOR_REPREPARING,
+            "- If the current branch is `main` or `master`, or HEAD is detached, stop before editing "
+            f'and ask the developer: "You are on a protected branch / detached HEAD. Create `{branch}` '
+            'and continue?" Create and switch to it only if they explicitly agree.',
+        ]
+    return "## Branch Instructions\n\n" + "\n".join(lines) + "\n\n"
+
+
+def retry_branch_section(policy: str, branch: str | None = None) -> str:
+    """A retry prompt's Branch section: the same policy, and no new branch."""
+    if policy == BRANCH_POLICY_PER_ISSUE:
+        where = f"the work item's branch, `{branch}`" if branch else "the work item's branch"
+    elif policy == BRANCH_POLICY_ASK:
+        where = "the branch the developer chose for the first attempt"
+    else:
+        where = "the current branch"
+    return (
+        "## Branch\n\n"
+        f"- Branch policy: {_POLICY_NAMES[policy]}, as in the first attempt.\n"
+        f"- Continue on {where}. A retry does not call for a new branch.\n"
+        "- Never work directly on main/master.\n\n"
+    )
+
+
+def branch_editing_guardrail(policy: str, branch: str | None = None) -> str:
+    """The editing guardrail's branch line."""
+    if policy == BRANCH_POLICY_PER_ISSUE:
+        named = f", `{branch}`" if branch else " named above"
+        return f"- Edit only on the work item's branch{named}; never on main/master.\n"
+    if policy == BRANCH_POLICY_ASK:
+        return "- Edit only on the branch the developer chose; never on main/master.\n"
+    return (
+        "- Edit only on the current branch, never on main/master. Do not create or switch branches "
+        "unless the developer explicitly approves it from main/master or a detached HEAD.\n"
+    )
+
+
+def delivery_branch_checks(policy: str, issue_key: str, branch: str | None) -> str:
+    """The branch checks before staging, after "not main/master" and "not detached"."""
+    if policy == BRANCH_POLICY_PER_ISSUE:
+        if branch:
+            return (
+                f"- Verify the current branch is the work item's branch: `{branch}`"
+                f"{_existing_branch_clause(issue_key)}.\n"
+                f"- If needed, ask whether to create or switch to `{branch}` before editing or delivery.\n"
+            )
+        # No name to hold the branch to: the old checks, which still say the
+        # branch is this work item's.
+        return (
+            "- Verify the current branch starts with `feature/` or another accepted feature prefix.\n"
+            f"- Verify the current branch includes `{issue_key}`.\n"
+        )
+    if policy == BRANCH_POLICY_ASK:
+        return (
+            "- Verify the current branch is the one the developer chose before editing. If they chose "
+            f"to stay on their branch, it does not have to start with `feature/` or include `{issue_key}`.\n"
+        )
+    return (
+        "- Commit on the current branch. It does not have to start with `feature/` "
+        f"or include `{issue_key}`.\n"
+    )
+
+
+def delivery_branch_stop(policy: str, issue_key: str, branch: str | None = None) -> str:
+    """The commit offer's last branch rule, if the policy has one."""
+    if policy != BRANCH_POLICY_PER_ISSUE:
+        return ""
+    if branch:
+        return (
+            f"If the current branch is not `{branch}`{_existing_branch_clause(issue_key)}, "
+            "stop and ask the developer before committing.\n\n"
+        )
+    return f"If {issue_key} is not in the current branch name, stop and ask the developer before committing.\n\n"

bugpilot/core/cleanup.py

@@ -0,0 +1,58 @@
+"""Safe cleanup helpers for generated bugpilot artifacts."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .identity import validate_work_item_id
+from .safe_paths import owned_path, remove_owned_path
+
+
+@dataclass
+class CleanResult:
+    issue_key: str
+    deleted_paths: list[str] = field(default_factory=list)
+    preserved_paths: list[str] = field(default_factory=list)
+    missing_paths: list[str] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+
+
+def validate_issue_key(issue_key: str) -> None:
+    """Deprecated alias for :func:`identity.validate_work_item_id`.
+
+    Kept so existing callers keep working; new code should call
+    ``validate_work_item_id`` directly.
+    """
+    validate_work_item_id(issue_key)
+
+
+def clean_issue_artifacts(repo_root: Path, issue_key: str, include_memory: bool = False) -> CleanResult:
+    """Delete one work item's generated artifacts, and its memory entry if asked.
+
+    Every path is checked before anything is deleted (``safe_paths.owned_path``):
+    a link or junction at ``.ai``, ``.ai/<id>``, ``.ai_memory`` or below raises
+    :class:`~bugpilot.core.safe_paths.UnsafePathError` and nothing is removed —
+    not the folder, not the memory entry. Both ``clean`` and ``bug --fresh``
+    come through here.
+    """
+    validate_issue_key(issue_key)
+    result = CleanResult(issue_key=issue_key)
+
+    workflow_dir = owned_path(repo_root, (".ai", issue_key))
+    memory_file = owned_path(repo_root, (".ai_memory", "bugs", f"{issue_key}.md")) if include_memory else None
+
+    if remove_owned_path(workflow_dir):
+        result.deleted_paths.append(f".ai/{issue_key}/")
+    else:
+        result.missing_paths.append(f".ai/{issue_key}/")
+
+    if memory_file is not None:
+        if remove_owned_path(memory_file):
+            result.deleted_paths.append(f".ai_memory/bugs/{issue_key}.md")
+        else:
+            result.missing_paths.append(f".ai_memory/bugs/{issue_key}.md")
+    else:
+        result.preserved_paths.append(f".ai_memory/bugs/{issue_key}.md")
+
+    return result

bugpilot/core/code_files.py

@@ -0,0 +1,99 @@
+"""Which files code search looks at, and which of them are documentation.
+
+One list, because there were three and they disagreed. `search.INCLUDE_GLOBS`
+built ripgrep's `-g` flags, `search._is_included_path` re-stated the same
+suffixes inline to filter rg's output, and `keywords._CODE_EXT` decided whether
+`widget.cpp` in a bug report looked like a file name. The third had drifted:
+it recognised `.ts`, `.go`, `.java`, `.c`, `.hxx` and `.qml`, and the first two
+did not — so a bug naming `reader.ts` produced a keyword for a file the search
+would never open. Nine extensions were recognised and unsearchable.
+
+The split between implementation and documentation is here for the same reason
+the extensions are: `search.py` ranks with it and `context.py` selects with it,
+and a second opinion about whether `.md` is documentation is a bug waiting to
+happen.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+#: Implementation: source, headers, UI definitions, build files.
+#:
+#: Extensions rather than languages, because that is what both consumers have.
+#: Adding one here makes it searchable, filterable and recognisable as a file
+#: name in a bug report, in one edit.
+CODE_SUFFIXES: frozenset[str] = frozenset(
+    {
+        # C and C++
+        "c", "cc", "cpp", "cxx", "h", "hpp", "hxx",
+        # Qt
+        "ui", "qrc", "qml",
+        # build
+        "cmake",
+        # everything else bugpilot has been pointed at
+        "py", "ts", "js", "java", "cs", "go", "rs",
+    }
+)
+
+#: Files with no useful suffix that are still implementation.
+CODE_FILENAMES: frozenset[str] = frozenset({"CMakeLists.txt"})
+
+#: Prose. Searched — a design document naming the subsystem is a real lead — but
+#: never allowed to displace implementation, which is what §33.2 is about.
+#:
+#: `txt` is deliberately absent. §33.2's requirement was to align the *code*
+#: extensions the extractor already recognised; the documentation formats were
+#: an addition of mine, and generic `.txt` turned out to be the wrong one. It is
+#: the most common extension for things that are not prose at all —
+#: `requirements.txt`, licence text, generated file lists, test fixtures, data
+#: dumps — so searching it buys noise and scan time rather than leads. It was
+#: also the cause of `CMakeLists.txt` classifying as documentation.
+#:
+#: `CMakeLists.txt` stays searchable through `CODE_FILENAMES`, which is where it
+#: belongs: it is a build file, not a document.
+DOC_SUFFIXES: frozenset[str] = frozenset({"md", "rst", "adoc"})
+
+
+def search_globs() -> list[str]:
+    """The `-g` patterns ripgrep is given, implementation and documentation."""
+    suffixes = sorted(CODE_SUFFIXES | DOC_SUFFIXES)
+    return [f"*.{suffix}" for suffix in suffixes] + sorted(CODE_FILENAMES)
+
+
+def _suffix(path: str) -> str:
+    return Path(path).suffix.lower().lstrip(".")
+
+
+def is_searchable(path: str) -> bool:
+    """Whether a path rg returned is one this search is interested in.
+
+    rg is already told the globs; this filters its output too, because a glob
+    and a returned path can disagree — a symlink, an odd separator, a file whose
+    name matches a pattern by accident.
+    """
+    return Path(path).name in CODE_FILENAMES or _suffix(path) in (CODE_SUFFIXES | DOC_SUFFIXES)
+
+
+def is_documentation(path: str) -> bool:
+    """Prose rather than implementation. Never both.
+
+    Mostly by extension: a `.md` under `src/` is still prose, and a path-based
+    guess ("does it live in docs/") was wrong for README.md, which sits at the
+    root of every repository bugpilot has been pointed at.
+
+    The named-file check is the exception, and it is the whole reason this is
+    not a one-line suffix test. `CMakeLists.txt` ends in `.txt`, so a pure
+    suffix rule called it documentation *and* implementation at once. Ranking
+    read the second answer and was right; the artifact label and the corpus
+    metric read the first and were wrong — which would have quietly inflated
+    "documentation in top 5" on exactly the CMake-heavy repositories §33 is
+    aimed at.
+    """
+    if Path(path).name in CODE_FILENAMES:
+        return False
+    return _suffix(path) in DOC_SUFFIXES
+
+
+def is_implementation(path: str) -> bool:
+    return Path(path).name in CODE_FILENAMES or _suffix(path) in CODE_SUFFIXES

bugpilot/core/config.py

@@ -0,0 +1,242 @@
+"""Configuration helpers."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+from .user_config import load_user_config
+
+
+WORKFLOW_STEPS = [
+    "doctor",
+    "fetch",
+    "parse",
+    "keywords",
+    "memory_search",
+    "code_search",
+    "git_context",
+    "context",
+    "prompt",
+    "agent_instructions",
+    "memory_add",
+    "agent_fix",
+    # What `summarize-results` did: the Result Overview was rendered (`pass`) or
+    # could not be (`fail`). A command having run, never a verdict on the fix.
+    # `manual_validation` and `final_review_prompt` were listed here too, and
+    # marked `pass` by printing a checklist and a prompt — read back by
+    # `status` as a validation and a review that never happened. Neither is a
+    # workflow step, so neither is recorded (§37.70).
+    "result_summary",
+    "memory_update",
+    "delivery_check",
+    "commit_plan",
+    "push_plan",
+    "notify",
+    "jira_comment_draft",
+    "jira_comment",
+    "retry_prompt",
+    "manual_result",
+]
+
+
+@dataclass(frozen=True)
+class AppConfig:
+    repo_root: Path
+    jira_base_url: str | None
+    jira_email: str | None
+    jira_token: str | None
+    copilot_command: str
+    claude_command: str
+    claude_args: str
+    copilot_args: str
+
+    @property
+    def has_jira_credentials(self) -> bool:
+        return bool(self.jira_base_url and self.jira_email and self.jira_token)
+
+
+@dataclass(frozen=True)
+class EmailConfig:
+    """SMTP configuration for outbound notification email.
+
+    Credentials are read from the environment only. bugpilot never hardcodes or
+    persists SMTP secrets; use a secrets manager to inject them at runtime.
+    """
+
+    host: str | None
+    port: int
+    username: str | None
+    password: str | None
+    use_ssl: bool
+    use_starttls: bool
+    sender: str | None
+    recipients: tuple[str, ...]
+
+    @property
+    def is_configured(self) -> bool:
+        # Enough to send: a server, a sender, and at least one recipient.
+        return bool(self.host and self.sender and self.recipients)
+
+    @property
+    def uses_auth(self) -> bool:
+        return bool(self.username)
+
+    def missing_fields(self) -> list[str]:
+        missing: list[str] = []
+        if not self.host:
+            missing.append("SMTP_HOST")
+        if not self.sender:
+            missing.append("BUGPILOT_EMAIL_FROM")
+        if not self.recipients:
+            missing.append("BUGPILOT_EMAIL_TO")
+        if self.username and not self.password:
+            missing.append("SMTP_PASSWORD")
+        return missing
+
+
+@dataclass(frozen=True)
+class GraphConfig:
+    """Microsoft Graph (client-credentials) settings for sending mail over HTTPS.
+
+    This is the transport of choice when the tenant disables SMTP client
+    authentication. All values come from the environment; the client secret is
+    never hardcoded, logged, or persisted by bugpilot.
+    """
+
+    tenant_id: str | None
+    client_id: str | None
+    client_secret: str | None
+
+    @property
+    def is_configured(self) -> bool:
+        return bool(self.tenant_id and self.client_id and self.client_secret)
+
+    def missing_fields(self) -> list[str]:
+        missing: list[str] = []
+        if not self.tenant_id:
+            missing.append("GRAPH_TENANT_ID")
+        if not self.client_id:
+            missing.append("GRAPH_CLIENT_ID")
+        if not self.client_secret:
+            missing.append("GRAPH_CLIENT_SECRET")
+        return missing
+
+
+def load_config(repo_root: Path) -> AppConfig:
+    # Precedence for every Jira setting: environment variables first (power
+    # users / CI), then the `bugpilot setup` config file
+    # (~/.bugpilot/config.toml). The site is one of them now — there is no
+    # built-in default, so an unconfigured install reports itself as such
+    # instead of aiming at whichever tenant happened to be hard-coded.
+    user = load_user_config()
+    return AppConfig(
+        repo_root=repo_root,
+        jira_base_url=_clean_env("JIRA_BASE_URL") or user.jira_base_url,
+        jira_email=_clean_env("JIRA_EMAIL") or user.jira_email,
+        jira_token=_clean_env("JIRA_TOKEN") or user.jira_token,
+        copilot_command=os.getenv("BUGPILOT_COPILOT_COMMAND", "copilot"),
+        claude_command=os.getenv("BUGPILOT_CLAUDE_COMMAND", "claude"),
+        # Interactive by default, but auto-accept file edits so the agent is not
+        # blocked on every edit. For a fully unattended run (also skipping shell
+        # prompts for git / bugpilot), set BUGPILOT_CLAUDE_ARGS to include
+        # --dangerously-skip-permissions.
+        claude_args=os.getenv("BUGPILOT_CLAUDE_ARGS", "--permission-mode acceptEdits"),
+        copilot_args=os.getenv("BUGPILOT_COPILOT_ARGS", ""),
+    )
+
+
+def load_email_config() -> EmailConfig:
+    return EmailConfig(
+        host=_clean_env("SMTP_HOST"),
+        port=_env_int("SMTP_PORT", 587),
+        username=_clean_env("SMTP_USERNAME"),
+        password=os.getenv("SMTP_PASSWORD") or None,
+        use_ssl=_env_bool("SMTP_USE_SSL", False),
+        use_starttls=_env_bool("SMTP_USE_STARTTLS", True),
+        sender=_clean_env("BUGPILOT_EMAIL_FROM"),
+        recipients=_parse_recipients(os.getenv("BUGPILOT_EMAIL_TO")),
+    )
+
+
+def load_graph_config() -> GraphConfig:
+    return GraphConfig(
+        tenant_id=_clean_env("GRAPH_TENANT_ID"),
+        client_id=_clean_env("GRAPH_CLIENT_ID"),
+        client_secret=os.getenv("GRAPH_CLIENT_SECRET") or None,
+    )
+
+
+def _clean_env(name: str) -> str | None:
+    value = os.getenv(name)
+    if value is None:
+        return None
+    value = value.strip()
+    return value or None
+
+
+def _env_int(name: str, default: int) -> int:
+    raw = _clean_env(name)
+    if raw is None:
+        return default
+    try:
+        return int(raw)
+    except ValueError:
+        return default
+
+
+def _env_bool(name: str, default: bool) -> bool:
+    raw = _clean_env(name)
+    if raw is None:
+        return default
+    return raw.lower() in {"1", "true", "yes", "on"}
+
+
+def _parse_recipients(raw: str | None) -> tuple[str, ...]:
+    if not raw:
+        return ()
+    parts = [item.strip() for item in raw.replace(";", ",").split(",")]
+    return tuple(item for item in parts if item)
+
+
+def issue_dir(repo_root: Path, issue_key: str) -> Path:
+    """Where a work item's files are read from. Writers use :func:`writable_issue_dir`."""
+    return repo_root / ".ai" / issue_key
+
+
+def writable_issue_dir(repo_root: Path, issue_key: str, *, create: bool = True) -> Path:
+    """``.ai/<issue_key>/``, checked before anything is written into it.
+
+    The id is validated — it becomes a path segment — and every component is
+    checked by ``safe_paths.writable_dir``: a link or junction at ``.ai`` or
+    ``.ai/<id>`` raises ``UnsafePathError`` and nothing is written. With
+    ``create=False`` a missing folder is returned for the caller to report.
+    """
+    from .safe_paths import writable_dir
+
+    _checked_id(issue_key)
+    return writable_dir(repo_root, (".ai", issue_key), create=create)
+
+
+def _checked_id(issue_key: str) -> None:
+    """The id as a path segment: anything but a work item id is an unsafe path."""
+    from .identity import validate_work_item_id
+    from .safe_paths import UnsafePathError
+
+    try:
+        validate_work_item_id(issue_key)
+    except ValueError as exc:
+        raise UnsafePathError(str(exc)) from exc
+
+
+def memory_dir(repo_root: Path) -> Path:
+    return repo_root / ".ai_memory" / "bugs"
+
+
+def writable_memory_file(repo_root: Path, issue_key: str, *, create: bool = True) -> Path:
+    """``.ai_memory/bugs/<issue_key>.md``, checked like :func:`writable_issue_dir`."""
+    from .safe_paths import refuse_link, writable_dir
+
+    _checked_id(issue_key)
+    return refuse_link(writable_dir(repo_root, (".ai_memory", "bugs"), create=create) / f"{issue_key}.md")