claude-dev-env 2.3.0 → 2.5.0

package/skills/fresh-branch/scripts/test_create_fresh_branch.py

@@ -146,6 +146,21 @@ def build_repo_with_origin(workspace_path: Path) -> Path:
     return clone_path
 
 
+def read_branch_config(
+    repository_path: Path,
+    branch_name: str,
+    config_leaf: str,
+) -> str:
+    completed = subprocess.run(
+        ["git", "config", "--get", f"branch.{branch_name}.{config_leaf}"],
+        cwd=str(repository_path),
+        check=False,
+        capture_output=True,
+        text=True,
+    )
+    return completed.stdout.strip()
+
+
 def read_head_branch(repository_path: Path) -> str:
     completed = run_git(["rev-parse", "--abbrev-ref", "HEAD"], repository_path)
     return completed.stdout.strip()
@@ -156,6 +171,14 @@ def read_head_commit(repository_path: Path) -> str:
     return completed.stdout.strip()
 
 
+def read_remote_main_commit(repository_path: Path) -> str:
+    completed = run_git(
+        ["ls-remote", REMOTE_NAME, f"refs/heads/{MAIN_BRANCH_NAME}"],
+        repository_path,
+    )
+    return completed.stdout.split()[0]
+
+
 class TestResolveAgentSlug:
     def should_prefer_flag_over_environment(
         self,
@@ -512,6 +535,81 @@ class TestCreateFreshBranchIntegration:
         assert read_head_commit(worktree_path) != local_main_commit
 
 
+class TestWorktreeBranchTracking:
+    def should_leave_new_branch_without_an_upstream(
+        self,
+        tmp_path: Path,
+        monkeypatch: pytest.MonkeyPatch,
+    ) -> None:
+        module = load_create_fresh_branch_module()
+        repository_path = build_repo_with_origin(tmp_path / "repo")
+        agent_scratch_parent = tmp_path / "agent-scratch"
+        monkeypatch.setattr(module.sys, "platform", "linux")
+        monkeypatch.setattr(
+            module.tempfile,
+            "gettempdir",
+            lambda: str(agent_scratch_parent),
+        )
+        success_payload = module.create_fresh_branch(
+            branch_name="fix/no-upstream",
+            repo_path=repository_path,
+            agent_slug="claude",
+            base_ref=DEFAULT_BASE_REF,
+        )
+        worktree_path = Path(success_payload[PAYLOAD_KEY_WORKTREE_PATH])
+        assert read_head_branch(worktree_path) == "fix/no-upstream"
+        assert read_branch_config(repository_path, "fix/no-upstream", "merge") == ""
+        assert read_branch_config(repository_path, "fix/no-upstream", "remote") == ""
+
+    def should_not_aim_a_bare_push_at_main_under_push_default_upstream(
+        self,
+        tmp_path: Path,
+        monkeypatch: pytest.MonkeyPatch,
+    ) -> None:
+        module = load_create_fresh_branch_module()
+        repository_path = build_repo_with_origin(tmp_path / "repo")
+        empty_hooks_path = tmp_path / "repo" / "empty-hooks"
+        run_git(
+            ["config", "push.default", "upstream"],
+            repository_path,
+            empty_hooks_path=empty_hooks_path,
+        )
+        agent_scratch_parent = tmp_path / "agent-scratch"
+        monkeypatch.setattr(module.sys, "platform", "linux")
+        monkeypatch.setattr(
+            module.tempfile,
+            "gettempdir",
+            lambda: str(agent_scratch_parent),
+        )
+        success_payload = module.create_fresh_branch(
+            branch_name="feature/silent-push",
+            repo_path=repository_path,
+            agent_slug="claude",
+            base_ref=DEFAULT_BASE_REF,
+        )
+        worktree_path = Path(success_payload[PAYLOAD_KEY_WORKTREE_PATH])
+        (worktree_path / SEED_FILE_NAME).write_text("drive-by\n", encoding="utf-8")
+        run_git(["add", SEED_FILE_NAME], worktree_path, empty_hooks_path=empty_hooks_path)
+        run_git(
+            ["commit", "-m", "work on the feature branch"],
+            worktree_path,
+            empty_hooks_path=empty_hooks_path,
+        )
+        origin_main_before = read_remote_main_commit(repository_path)
+        push_attempt = subprocess.run(
+            ["git", "-c", f"core.hooksPath={empty_hooks_path}", "push"],
+            cwd=str(worktree_path),
+            check=False,
+            capture_output=True,
+            text=True,
+        )
+        assert push_attempt.returncode != 0, (
+            "bare push should be refused, but it succeeded:\n"
+            f"{push_attempt.stdout}{push_attempt.stderr}"
+        )
+        assert read_remote_main_commit(repository_path) == origin_main_before
+
+
 class TestMainCli:
     def should_print_success_json_and_exit_zero(
         self,

package/skills/fresh-branch/scripts/test_fresh_branch_git_commands.py

@@ -0,0 +1,310 @@
+"""Behavioral tests for fresh_branch_git_commands using real temporary git repos."""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+SCRIPTS_DIRECTORY = Path(__file__).resolve().parent
+if str(SCRIPTS_DIRECTORY) not in sys.path:
+    sys.path.insert(0, str(SCRIPTS_DIRECTORY))
+
+from fresh_branch_git_commands import (
+    assert_git_accepts_branch_name,
+    build_worktree_add_arguments,
+    create_worktree_branch,
+    fetch_base_ref,
+    is_ref_present,
+    read_failure_text,
+    resolve_base_commit,
+    resolve_repo_root,
+    run_git,
+    split_remote_ref,
+)
+
+GIT_USER_NAME = "fresh-branch-test"
+GIT_USER_EMAIL = "fresh-branch-test@example.com"
+MAIN_BRANCH_NAME = "main"
+SEED_FILE_NAME = "README.md"
+SEED_FILE_CONTENTS = "seed\n"
+
+
+def build_repo(workspace_path: Path) -> Path:
+    workspace_path.mkdir(parents=True, exist_ok=True)
+    empty_hooks_path = workspace_path / "empty-hooks"
+    empty_hooks_path.mkdir()
+    hooks_argument = ["-c", f"core.hooksPath={empty_hooks_path}"]
+    subprocess.run(
+        ["git", *hooks_argument, "init", "-b", MAIN_BRANCH_NAME, str(workspace_path)],
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+    for each_pair in (
+        ("user.name", GIT_USER_NAME),
+        ("user.email", GIT_USER_EMAIL),
+        ("commit.gpgsign", "false"),
+    ):
+        subprocess.run(
+            ["git", *hooks_argument, "config", *each_pair],
+            cwd=str(workspace_path),
+            check=True,
+            capture_output=True,
+            text=True,
+        )
+    (workspace_path / SEED_FILE_NAME).write_text(SEED_FILE_CONTENTS, encoding="utf-8")
+    subprocess.run(
+        ["git", *hooks_argument, "add", SEED_FILE_NAME],
+        cwd=str(workspace_path),
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+    subprocess.run(
+        ["git", *hooks_argument, "commit", "-m", "initial commit"],
+        cwd=str(workspace_path),
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+    return workspace_path
+
+
+def build_clone_with_origin(workspace_path: Path) -> tuple[Path, Path]:
+    seed_path = build_repo(workspace_path / "seed")
+    empty_hooks_path = seed_path / "empty-hooks"
+    hooks_argument = ["-c", f"core.hooksPath={empty_hooks_path}"]
+    bare_origin = workspace_path / "origin.git"
+    subprocess.run(
+        ["git", *hooks_argument, "clone", "--bare", str(seed_path), str(bare_origin)],
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+    clone_path = workspace_path / "clone"
+    subprocess.run(
+        ["git", *hooks_argument, "clone", str(bare_origin), str(clone_path)],
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+    for each_pair in (
+        ("user.name", GIT_USER_NAME),
+        ("user.email", GIT_USER_EMAIL),
+        ("commit.gpgsign", "false"),
+    ):
+        subprocess.run(
+            ["git", *hooks_argument, "config", *each_pair],
+            cwd=str(clone_path),
+            check=True,
+            capture_output=True,
+            text=True,
+        )
+    return clone_path, bare_origin
+
+
+def advance_origin_main(workspace_path: Path, bare_origin: Path) -> str:
+    pusher_path = workspace_path / "pusher"
+    empty_hooks_path = workspace_path / "seed" / "empty-hooks"
+    hooks_argument = ["-c", f"core.hooksPath={empty_hooks_path}"]
+    subprocess.run(
+        ["git", *hooks_argument, "clone", str(bare_origin), str(pusher_path)],
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+    for each_pair in (
+        ("user.name", GIT_USER_NAME),
+        ("user.email", GIT_USER_EMAIL),
+        ("commit.gpgsign", "false"),
+    ):
+        subprocess.run(
+            ["git", *hooks_argument, "config", *each_pair],
+            cwd=str(pusher_path),
+            check=True,
+            capture_output=True,
+            text=True,
+        )
+    (pusher_path / SEED_FILE_NAME).write_text("advanced\n", encoding="utf-8")
+    subprocess.run(
+        ["git", *hooks_argument, "commit", "-am", "advance main"],
+        cwd=str(pusher_path),
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+    subprocess.run(
+        ["git", *hooks_argument, "push", "origin", MAIN_BRANCH_NAME],
+        cwd=str(pusher_path),
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+    completed = subprocess.run(
+        ["git", "rev-parse", "HEAD"],
+        cwd=str(pusher_path),
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+    return completed.stdout.strip()
+
+
+def read_branch_config(
+    repository_path: Path,
+    branch_name: str,
+    config_leaf: str,
+) -> str:
+    completed = subprocess.run(
+        ["git", "config", "--get", f"branch.{branch_name}.{config_leaf}"],
+        cwd=str(repository_path),
+        check=False,
+        capture_output=True,
+        text=True,
+    )
+    return completed.stdout.strip()
+
+
+class TestBuildWorktreeAddArguments:
+    def test_pass_no_track_so_the_new_branch_gets_no_upstream(self) -> None:
+        all_arguments = build_worktree_add_arguments(
+            "fix/x",
+            Path("/tmp/agent/fix/x"),
+            "origin/main",
+        )
+        assert "--no-track" in all_arguments
+
+    def test_order_arguments_the_way_git_worktree_add_expects(self) -> None:
+        all_arguments = build_worktree_add_arguments(
+            "fix/x",
+            Path("/tmp/agent/fix/x"),
+            "origin/main",
+        )
+        assert all_arguments[:4] == ["worktree", "add", "-b", "fix/x"]
+        assert all_arguments[-1] == "origin/main"
+        assert all_arguments[-2] == str(Path("/tmp/agent/fix/x"))
+
+
+class TestSplitRemoteRef:
+    def test_split_an_origin_ref(self) -> None:
+        assert split_remote_ref("origin/main") == ("origin", "main")
+
+    def test_split_a_non_origin_remote_ref(self) -> None:
+        assert split_remote_ref("upstream/dev") == ("upstream", "dev")
+
+    def test_default_a_bare_name_to_origin(self) -> None:
+        assert split_remote_ref("main") == ("origin", "main")
+
+    def test_keep_slashes_inside_the_branch_name(self) -> None:
+        assert split_remote_ref("origin/fix/nested") == ("origin", "fix/nested")
+
+
+class TestAssertGitAcceptsBranchName:
+    def test_accept_a_conventional_branch_name(self) -> None:
+        assert assert_git_accepts_branch_name("fix/example-one") is None
+
+    def test_reject_a_name_git_refuses(self) -> None:
+        with pytest.raises(ValueError, match="relative path"):
+            assert_git_accepts_branch_name("fix..example")
+
+
+class TestResolveRepoRoot:
+    def test_return_the_toplevel_for_a_nested_path(self, tmp_path: Path) -> None:
+        repository_path = build_repo(tmp_path / "repo")
+        nested_path = repository_path / "nested"
+        nested_path.mkdir()
+        assert resolve_repo_root(nested_path).resolve() == repository_path.resolve()
+
+    def test_raise_outside_a_repository(self, tmp_path: Path) -> None:
+        plain_directory = tmp_path / "plain"
+        plain_directory.mkdir()
+        with pytest.raises(RuntimeError, match="git repository"):
+            resolve_repo_root(plain_directory)
+
+
+class TestIsRefPresent:
+    def test_find_a_local_branch(self, tmp_path: Path) -> None:
+        repository_path = build_repo(tmp_path / "repo")
+        assert is_ref_present(repository_path, MAIN_BRANCH_NAME) is True
+
+    def test_not_find_an_absent_ref(self, tmp_path: Path) -> None:
+        repository_path = build_repo(tmp_path / "repo")
+        assert is_ref_present(repository_path, "origin/nowhere") is False
+
+
+class TestReadFailureText:
+    def test_prefer_stderr(self, tmp_path: Path) -> None:
+        repository_path = build_repo(tmp_path / "repo")
+        completed = run_git(["rev-parse", "does-not-exist"], repository_path)
+        assert completed.returncode != 0
+        assert "does-not-exist" in read_failure_text(completed)
+
+
+class TestFetchBaseRef:
+    def test_bring_the_remote_tip_into_the_clone(self, tmp_path: Path) -> None:
+        clone_path, bare_origin = build_clone_with_origin(tmp_path / "workspace")
+        advanced_commit = advance_origin_main(tmp_path / "workspace", bare_origin)
+        fetch_base_ref(clone_path, "origin/main")
+        assert is_ref_present(clone_path, "origin/main") is True
+        assert resolve_base_commit(clone_path, "origin/main") == advanced_commit
+
+    def test_raise_for_a_remote_branch_that_does_not_exist(
+        self,
+        tmp_path: Path,
+    ) -> None:
+        clone_path, _bare_origin = build_clone_with_origin(tmp_path / "workspace")
+        with pytest.raises(RuntimeError, match="git fetch failed"):
+            fetch_base_ref(clone_path, "origin/nowhere")
+
+
+class TestResolveBaseCommit:
+    def test_return_the_sha_at_the_ref(self, tmp_path: Path) -> None:
+        repository_path = build_repo(tmp_path / "repo")
+        head_commit = run_git(["rev-parse", "HEAD"], repository_path).stdout.strip()
+        assert resolve_base_commit(repository_path, MAIN_BRANCH_NAME) == head_commit
+
+    def test_raise_for_an_unresolvable_ref(self, tmp_path: Path) -> None:
+        repository_path = build_repo(tmp_path / "repo")
+        with pytest.raises(RuntimeError, match="could not resolve base commit"):
+            resolve_base_commit(repository_path, "refs/heads/nowhere")
+
+
+class TestCreateWorktreeBranch:
+    def test_create_the_branch_at_the_base_ref_with_no_upstream(
+        self,
+        tmp_path: Path,
+    ) -> None:
+        clone_path, _bare_origin = build_clone_with_origin(tmp_path / "workspace")
+        origin_tip = resolve_base_commit(clone_path, "origin/main")
+        worktree_path = tmp_path / "worktrees" / "fix" / "created"
+        create_worktree_branch(
+            clone_path,
+            branch_name="fix/created",
+            worktree_path=worktree_path,
+            base_ref="origin/main",
+        )
+        assert worktree_path.is_dir()
+        assert resolve_base_commit(worktree_path, "HEAD") == origin_tip
+        assert read_branch_config(clone_path, "fix/created", "merge") == ""
+        assert read_branch_config(clone_path, "fix/created", "remote") == ""
+
+    def test_raise_when_the_branch_already_exists(self, tmp_path: Path) -> None:
+        clone_path, _bare_origin = build_clone_with_origin(tmp_path / "workspace")
+        first_path = tmp_path / "worktrees" / "dup-one"
+        second_path = tmp_path / "worktrees" / "dup-two"
+        create_worktree_branch(
+            clone_path,
+            branch_name="fix/dup",
+            worktree_path=first_path,
+            base_ref="origin/main",
+        )
+        with pytest.raises(RuntimeError, match="worktree add failed"):
+            create_worktree_branch(
+                clone_path,
+                branch_name="fix/dup",
+                worktree_path=second_path,
+                base_ref="origin/main",
+            )

package/skills/issue-tracker/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: issue-tracker
+description: >-
+  File, update, and close GitHub work as one epic with native sub-issues.
+  Dedup open and closed issues first. Edit status only inside marker sections.
+  Refresh the epic checklist so it matches its children. Triggers: issue tracker,
+  file an issue, track this issue, open an epic, update the epic, close the issue,
+  refresh the epic checklist, attach a sub-issue.
+argument-hint: "[issue action - file | update | close | refresh-epic | full handoff]"
+---
+
+# Issue tracker
+
+**User wants an issue action done. Here is how those actions work.**
+
+**dedup -> do the work -> markers only -> numbers + URLs**
+
+Run every step the ask needs in one go (file, label, attach, refresh, and so on). The `issue-tracker` agent is the primary handler for one action per turn; this skill is the session path when the agent is unavailable or the ask spans several steps.
+
+Prefer the **same warm** `issue-tracker` agent for follow-ups on the same issue or a related issue on the same epic. Spawn a new agent only for an unrelated work-stream or when the warm agent is gone.
+
+## Voice
+
+Use the `plain-brief` output style (`output-styles/plain-brief.md`). End with the issue number(s) and URL(s) the caller must keep.
+
+## Gotchas
+
+Append a bullet when an action fails in a new way.
+
+- Use REST `.id`, not display `#N`, to attach a sub-issue - [operation-matrix](reference/operation-matrix.md).
+- `gh` attach: `-F sub_issue_id=<n>` (typed int), never `-f`.
+- Status goes in markers, not comments - comments are cross-links only.
+- Dedup open **and** closed; closed twin -> reopen vs file new, never silent refile.
+- Edit only between markers - free-form epic edits break the children checklist.
+- Auto-close is PR-body-first: a related-only UI link does not close the issue on merge.
+
+## The model
+
+One **epic** issue owns a work-stream. Each unit of work is a native GitHub **sub-issue** under it. The epic checklist and every status block live inside marker pairs. Skeletons and refresh steps: [reference/epic-and-sub-issue-model.md](reference/epic-and-sub-issue-model.md).
+
+## Labels
+
+- Parent: `epic`.
+- Sub-issue: `type: roadblock`, `type: task`, `type: bug`, or `type: enhancement`.
+
+Create a missing label, then apply it. Label create is in the operation matrix.
+
+## Markers
+
+- Status (any issue): `<!-- issue-tracker:status -->` … `<!-- /issue-tracker:status -->`
+- Children checklist (epic only): `<!-- issue-tracker:children -->` … `<!-- /issue-tracker:children -->`
+
+Update path: read body -> replace only the text between the target pair -> write the full body back.
+
+## Dedup
+
+Search open and closed issues on the target repo before create. Open twin -> update in place. Closed twin -> ask reopen vs file new.
+
+## Tools
+
+Prefer GitHub MCP. Fall back to `gh` on the same REST endpoints. Full map and `.id` rule: [reference/operation-matrix.md](reference/operation-matrix.md).
+
+## Handoff input
+
+Optional issue-candidate JSON from orchestrator or closeout. Full schema and consume path: [reference/handoff-schema.md](reference/handoff-schema.md).
+
+## Close the sub-issue through the PR (required when a fix ships)
+
+GitHub closes the sub-issue when someone **merges** a pull request into the **default branch** and that PR carries a closing keyword for the issue.
+
+**Required on the PR that merges into the default branch:** put `Closes #N` in the PR body for each finished sub-issue. One keyword per issue: write `Closes #12` and `Closes #13`, not `Closes #12, #13` (only the first number closes in the comma form).
+
+**Preferred on commits:** also put `Closes #N` in the first commit message when the fix starts. Commit alone is backup; the PR body is the contract.
+
+**Stacked / intermediate PRs** that do not merge into the default branch: use a plain `#N` reference in the body so the issue links without a false close promise. Put `Closes #N` only on the PR that actually lands on the default branch.
+
+**Not enough:** a Development "related" link with no closing keyword. **Not enough:** closing the PR without merging.
+
+**Who owns `#N`:** the agent or session writing the PR must use the correct sub-issue number. Nothing in this package verifies the number matches the fix.
+
+## Return shape
+
+Reply with every affected issue number and URL - no narration after that payload.
+
+## File index
+
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | Hub: how issue actions work, gotchas, model, markers, dedup, PR auto-close, return shape |
+| `reference/operation-matrix.md` | MCP + `gh` per action; sub-issue `.id` rule |
+| `reference/epic-and-sub-issue-model.md` | Epic model, markers, body skeleton, checklist refresh |
+| `reference/handoff-schema.md` | Issue-candidate JSON and consume flow |

package/skills/issue-tracker/reference/epic-and-sub-issue-model.md

@@ -0,0 +1,55 @@
+# Epic and sub-issue model
+
+One **epic** issue holds a whole work-stream. Each unit of work under it is a native GitHub **sub-issue**. The epic carries the `epic` label; each sub-issue carries a `type:` label. The epic body mirrors its children as a checklist, and every issue — epic and sub-issue alike — carries a status section. Both sections live between marker comments so a body edit can replace one section and leave the rest untouched.
+
+## The two marker pairs
+
+- `<!-- issue-tracker:status -->` … `<!-- /issue-tracker:status -->` — on every issue. Holds the current status line.
+- `<!-- issue-tracker:children -->` … `<!-- /issue-tracker:children -->` — on the epic only. Holds the checklist of sub-issues.
+
+An edit reads the whole body, swaps only the text between one marker pair, and writes the whole body back. Text outside the markers stays byte-for-byte the same.
+
+## Epic body skeleton
+
+```markdown
+## Epic — <work-stream label>
+
+<One sentence naming the work-stream and its goal.>
+
+<!-- issue-tracker:status -->
+Status: in progress — 1 of 3 children closed.
+<!-- /issue-tracker:status -->
+
+<!-- issue-tracker:children -->
+- [x] owner/repo#12 — parser rejects an empty path
+- [ ] owner/repo#13 — attach reads the display number
+- [ ] owner/repo#14 — label create skips an existing label
+<!-- /issue-tracker:children -->
+```
+
+## Sub-issue body skeleton
+
+```markdown
+## <sub-issue title>
+
+<One sentence: what the work is.>
+
+<!-- issue-tracker:status -->
+Status: open.
+<!-- /issue-tracker:status -->
+
+## Detail
+
+<The evidence, where, impact, and proposed fix — self-contained.>
+```
+
+## Refresh the epic checklist
+
+After you create a sub-issue or close one, refresh the epic's `children` section so it matches the children:
+
+1. Read the epic body.
+2. Add a `- [ ] owner/repo#<N> — <title>` line for a newly created sub-issue, or flip a line to `- [x]` for a closed one.
+3. Update the epic's status line to name the closed count against the total.
+4. Write the whole body back with the issue-update op, replacing only the two marker sections you touched.
+
+A created or closed sub-issue always triggers this refresh, so the epic checklist stays in step with the sub-issues at every step.

package/skills/issue-tracker/reference/handoff-schema.md

@@ -0,0 +1,64 @@
+# Handoff schema
+
+An orchestrator or the closeout skill hands the tracker one **issue-candidate** JSON record per obstacle. The tracker consumes each record through the full path and returns the issue number and URL.
+
+## The record
+
+```json
+{
+  "kind": "roadblock | task | bug | enhancement",
+  "title": "<short imperative title>",
+  "epic": "<work-stream label the sub-issue belongs under>",
+  "summary": "<one sentence a reader with zero session context acts on>",
+  "evidence": "<verbatim line captured this session — error text, command, or log line>",
+  "where": "<file, hook, gate, or tool the evidence names — path relative to the repo root>",
+  "impact": "<what the obstacle cost: work blocked, count of times hit, workaround forced>",
+  "proposed_fix": "<the specific change — name the failure mode and the condition>",
+  "blocking": true
+}
+```
+
+## Field meanings
+
+| Field | Meaning |
+|-------|---------|
+| `kind` | The sub-issue's `type:` label stem. `roadblock`, `task`, `bug`, or `enhancement`. |
+| `title` | The sub-issue title. Short and imperative. |
+| `epic` | The work-stream the sub-issue belongs under. The tracker finds or creates the matching epic. |
+| `summary` | The one-sentence body opener. Self-contained — a reader with no session context acts on it. |
+| `evidence` | A verbatim line captured this session, placed in a fenced block in the body. |
+| `where` | The file, hook, gate, or tool the evidence names. A repo-relative path, no volatile temp path. |
+| `impact` | What the obstacle cost. |
+| `proposed_fix` | The specific change. |
+| `blocking` | `true` routes the sub-issue to `type: roadblock`, overriding `kind`. `false` keeps the `kind` label. |
+
+`kind` maps to the `type:` label. `blocking: true` takes precedence and routes the sub-issue to `type: roadblock`.
+
+## Filled example
+
+```json
+{
+  "kind": "bug",
+  "title": "Inline-collection gate fires in exempt test files",
+  "epic": "hook exemptions for test files",
+  "summary": "The code_rules_enforcer inline-collection check blocks a valid list literal in a test file, where test files are exempt from the magic-value gate.",
+  "evidence": "BLOCKED: [MAGIC_VALUE] Inline list literal [200, 404, 500] in a function body -- extract to a named constant in config/.",
+  "where": "packages/claude-dev-env/hooks/blocking/code_rules_enforcer.py",
+  "impact": "Hit 3 times in one session on three test files; each forced a workaround move to a module constant.",
+  "proposed_fix": "Extend the magic-value test-file exemption to cover the inline-collection check, so list and set literals in test bodies pass.",
+  "blocking": false
+}
+```
+
+## Consume flow
+
+For each record, in order:
+
+1. **Dedup** — search open and closed issues on the target repository for a twin.
+2. **Find or create the epic** — match the `epic` label; open a parent with the `epic` label when none matches.
+3. **Create the sub-issue** — body from `summary`, `evidence`, `where`, `impact`, `proposed_fix`.
+4. **Labels** — apply the `type:` label from `kind`, or `type: roadblock` when `blocking` is `true`. Create the label when the repository lacks it.
+5. **Attach the native sub-issue** — read the child's REST database `.id` and attach it under the epic.
+6. **Refresh the epic checklist** — add the child's `- [ ] owner/repo#<N>` line and update the epic status.
+
+The return is the sub-issue number and URL (and the epic number and URL when the epic was created this call).

package/skills/issue-tracker/reference/operation-matrix.md

@@ -0,0 +1,41 @@
+# Operation matrix
+
+Each issue op maps to a GitHub MCP tool and a `gh` fallback that reaches the same REST endpoint. Prefer the MCP tool; fall back to `gh` when the MCP server is unreachable. The REST endpoint column names the authoritative contract both surfaces call, so a session with neither surface can still drive the raw API.
+
+The MCP tool names below match the connected GitHub MCP server's issue toolset. When a server exposes a tool under a different name, pick the tool by what the row describes, and the REST endpoint tells you what it must call.
+
+| Operation | GitHub MCP tool | REST endpoint | `gh` fallback |
+|-----------|-----------------|---------------|---------------|
+| Search open + closed | `mcp__github__search_issues` | `GET /search/issues?q=<terms>+repo:{owner}/{repo}` | `gh issue list --search "<terms>" --state all` |
+| Create epic / sub-issue | `mcp__github__issue_write` (create) | `POST /repos/{owner}/{repo}/issues` | `gh issue create --title "<t>" --body-file <path> --label <label>` |
+| Read issue body | `mcp__github__issue_read` | `GET /repos/{owner}/{repo}/issues/{number}` | `gh issue view <number> --json body` |
+| Update body / labels | `mcp__github__issue_write` (update) | `PATCH /repos/{owner}/{repo}/issues/{number}` | `gh issue edit <number> --body-file <path> --add-label <label>` |
+| Attach native sub-issue | `mcp__github__sub_issue_write` | `POST /repos/{owner}/{repo}/issues/{number}/sub_issues` | `gh api repos/{owner}/{repo}/issues/{number}/sub_issues -F sub_issue_id=<int>` |
+| Add cross-reference comment | `mcp__github__add_issue_comment` | `POST /repos/{owner}/{repo}/issues/{number}/comments` | `gh issue comment <number> --body-file <path>` |
+| Create label | `mcp__github__` label-create tool | `POST /repos/{owner}/{repo}/labels` | `gh label create <name> --color <hex> --description "<text>"` |
+
+## The sub-issue `.id` rule (read this before every attach)
+
+The sub-issues endpoint identifies the child by its REST **database `.id`** — a large integer such as `2138472019` — not by its display number (`#42`). The two are different values. Passing the display number attaches nothing.
+
+Read the child's `.id` from the create op's response, or fetch it:
+
+```
+gh api repos/{owner}/{repo}/issues/{number} --jq .id
+```
+
+`gh issue view <number> --json id` returns the GraphQL node id, a base64 string — the wrong value for this endpoint. Use `gh api ... --jq .id` for the REST database id.
+
+The gh attach uses `-F` (typed field), which sends the id as a JSON integer. `-f` sends a string, and the endpoint rejects a string sub-issue id.
+
+```
+gh api repos/{owner}/{repo}/issues/{parent}/sub_issues -F sub_issue_id=2138472019
+```
+
+## Body content through `--body-file`
+
+Every `gh issue create`, `gh issue edit`, and `gh issue comment` passes body content with `--body-file <path>`, never `--body "<text>"`. A `--body` string mangles backticks on GitHub — they land as literal `\``. Write the body to a temp file and point `--body-file` at it.
+
+## Paginated reads
+
+`gh issue list` needs no pagination flags. For a `gh api` read of a paginated list endpoint (an issue's comments, a repository's issues), pass `--paginate --slurp` and pipe to external `jq` — `gh`'s built-in `--jq` runs per page and gives wrong cross-page results.