git-paoding 0.1.0__py3-none-any.whl

git_paoding/__init__.py

@@ -0,0 +1,32 @@
+"""Public package interface for git-paoding."""
+
+from git_paoding.api import (
+    add_slice,
+    archive,
+    assign,
+    assign_batch,
+    get_full_status,
+    get_status,
+    init_session,
+    publish,
+    remove_slice,
+    rename_slice,
+    set_focus,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    "add_slice",
+    "archive",
+    "assign",
+    "assign_batch",
+    "get_full_status",
+    "get_status",
+    "init_session",
+    "publish",
+    "remove_slice",
+    "rename_slice",
+    "set_focus",
+]

git_paoding/_agent_plugins/__init__.py

@@ -0,0 +1 @@
+"""Packaged agent integrations for git-paoding."""

git_paoding/_agent_plugins/git-paoding/.claude-plugin/plugin.json

@@ -0,0 +1,12 @@
+{
+  "name": "git-paoding",
+  "version": "0.1.0",
+  "description": "Teach Claude Code to partition a canonical change into semantic Draft PR review projections.",
+  "author": {
+    "name": "NagisaVon"
+  },
+  "homepage": "https://github.com/NagisaVon/git-paoding",
+  "repository": "https://github.com/NagisaVon/git-paoding",
+  "license": "MIT",
+  "keywords": ["git", "github", "code-review", "pull-requests"]
+}

git_paoding/_agent_plugins/git-paoding/.codex-plugin/plugin.json

@@ -0,0 +1,22 @@
+{
+  "name": "git-paoding",
+  "version": "0.1.0",
+  "description": "Teach Codex to partition a canonical change into semantic Draft PR review projections.",
+  "author": {
+    "name": "NagisaVon"
+  },
+  "homepage": "https://github.com/NagisaVon/git-paoding",
+  "repository": "https://github.com/NagisaVon/git-paoding",
+  "license": "MIT",
+  "keywords": ["git", "github", "code-review", "pull-requests"],
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "git-paoding",
+    "shortDescription": "Create semantic review projections from one canonical change.",
+    "longDescription": "Guide Codex through git-paoding's inspect, assign, publish, refresh, and archive workflow while keeping one authoritative integration branch.",
+    "developerName": "NagisaVon",
+    "category": "Productivity",
+    "capabilities": [],
+    "defaultPrompt": "Use git-paoding to prepare semantic Draft PR review projections for the committed change on my current branch. Inspect first and do not publish until I authorize remote changes."
+  }
+}

git_paoding/_agent_plugins/git-paoding/skills/git-paoding/SKILL.md

@@ -0,0 +1,206 @@
+---
+name: git-paoding
+description:
+  Prepare and publish semantic review slices for a large committed change while
+  keeping one canonical integration branch. Use when an author wants focused
+  Draft GitHub PRs for comprehension without creating a development branch
+  stack.
+---
+
+<!-- cspell:words paoding buildability PAODING -->
+
+# git-paoding
+
+Use `git-paoding` to partition the current `Base -> Final` diff into human-sized
+semantic review slices. Keep one canonical integrated implementation state
+throughout.
+
+## Preserve the mental model
+
+- Edit, test, lint, and commit only on the canonical integration branch.
+- Treat a slice as a review unit, never as a development phase, historical
+  commit range, buildable unit, or merge target.
+- Never check out, edit, rebase, or restack generated `paoding/...` branches.
+  They are disposable projections derived from the canonical state and local
+  slice metadata.
+- Let `publish` manage generated refs and stable PR identities. Do not manually
+  force-push projections or close and recreate a slice PR merely to refresh it.
+- Never merge a slice PR. It is a Draft PR marked **DO NOT MERGE — review
+  projection only**.
+- Keep authoritative CI, approval, branch protection, and merge on the
+  integration PR.
+- Do not require slice-level CI or independent buildability. Cross-slice
+  dependencies are valid.
+- New PR bodies contain no narrative template. Preserve human-written PR
+  narrative outside machine-managed regions byte-for-byte.
+
+The operating rule is: **run `git-paoding publish` and do what it says**.
+Publication is idempotent and self-checking; there is no separate refresh
+ritual.
+
+## Plan for review without bookkeeping every edit
+
+When review concerns are already apparent, use them as provisional,
+low-frequency structure guidance:
+
+- Prefer one primary review concern per new module or test file when that is a
+  natural boundary.
+- Separate meaningfully different test concerns when ordinary readable
+  organization permits.
+- Avoid one large contiguous insertion that mixes unrelated concerns when a
+  natural separation already exists.
+
+This is optional guidance, not a correctness precondition. Do not create
+artificial files, blank lines, awkward abstractions, or inferior architecture
+merely to manufacture atom boundaries. Do not require active slices or
+attribution calls during the normal edit-test-lint-fix loop. Provisional
+concerns may change.
+
+If nobody planned slice boundaries early, continue normally. Attribution is lazy
+and recoverable: `status` will report unassigned or ambiguous atoms at the
+review checkpoint, and those atoms can be classified then. Forgotten bookkeeping
+never makes publication irrecoverable.
+
+## Prepare the session
+
+Work from the branch containing the complete committed change. Confirm the CLI
+and `gh` 2.45.0 or newer are available, `gh` is authenticated, and the canonical
+branch is available on the Git remote. Do not push a branch without the change
+owner's authorization.
+
+```bash
+git-paoding --version
+gh --version
+gh auth status
+git-paoding init --base origin/main --slice-prefix ABC-123
+git-paoding slice add storage --title "Storage boundary"
+git-paoding slice add tests --title "Storage behavior tests"
+```
+
+Omit `--slice-prefix` to use `slice`. The prefix changes only slice PR titles;
+it does not change stable slice IDs or generated refs. The integration PR title
+is exactly the canonical branch name.
+
+The base is pinned to a commit at initialization. Choose the real integration
+target; do not silently change it later.
+
+## Classify and publish
+
+### 1. Inspect
+
+```bash
+git-paoding status --json
+```
+
+Interpret exit code `2` as action needed, not an operational failure. Read
+the versioned JSON atom list. Use atom IDs for precise selection; paths,
+directories, globs, and Final-coordinate ranges select broader atom sets.
+
+Line ranges use Final coordinates: `path:20-45` means lines 20 through 45 in the
+file at the canonical branch tip. A partial range selects the whole atom; ranges
+do not split atoms.
+
+Previews are short. Run `git-paoding status --full` for complete changed-hunk
+previews. If surrounding context is still needed, read the current file at
+`final_start` through `final_start + final_len - 1` before assigning; do not
+guess from the preview. For a deletion or other atom with no Final lines,
+inspect the relevant Base-side change instead.
+
+### 2. Assign
+
+Prepare `paoding-assignments.json` using the frozen batch contract:
+
+```json
+{
+  "contract_version": 0,
+  "assignments": {
+    "storage": ["src/storage.py"],
+    "tests": ["tests/test_storage.py"]
+  },
+  "force": false
+}
+```
+
+Then run:
+
+```bash
+git-paoding assign --batch paoding-assignments.json
+```
+
+The batch plan is ordinary local input, not git-paoding session metadata. Keep
+it untracked, place it outside the working tree, or manage it according to the
+repository's own policy; do not commit it accidentally.
+
+For an interactive assignment, pass the slice followed by one or more
+selectors:
+
+```bash
+git-paoding assign storage src/storage.py
+git-paoding assign tests tests/test_storage.py
+```
+
+Review the assignment echo: it must list every moved or skipped atom with a
+preview. Path and range selectors should claim only unassigned atoms by default.
+Reassignment through a broad selector requires the explicit `--force` option;
+an exact atom ID may take its atom directly. For batch repartitioning, set the
+JSON `force` field instead of combining `--force` with `--batch`. If a selector
+matches nothing or an atom ID became stale after a new commit, rerun
+`status --json` rather than guessing.
+
+### 3. Publish
+
+```bash
+git-paoding publish
+```
+
+Respond to the result by exit code:
+
+- `0`: clean success; report the integration PR and slice PRs.
+- `2`: attribution needs attention; no remote effects occurred. Return to
+  inspect and assign.
+- `1`: operational error, such as missing session, unavailable or
+  unauthenticated `gh`, or a push/PR failure. Fix the stated cause before
+  retrying.
+
+Do not loop indefinitely. Retry after a concrete local correction; ask the
+author when the fix needs new credentials, a branch push, a changed base, or
+another external mutation.
+
+## Focus review feedback
+
+For a task targeted at an existing slice, focus may act as a prior for genuinely
+new atoms:
+
+```bash
+git-paoding focus storage
+git-paoding status --json
+git-paoding focus --clear
+```
+
+Focus must not overwrite confidently matched existing ownership. Clear it when
+the targeted task ends so unrelated later work does not default to that slice.
+
+## Recovery
+
+- New, unassigned, ambiguous, or updated atoms after canonical edits are
+  expected. Rerun `status`, inspect only what needs attention, assign it, and
+  publish again.
+- Renames and heavy rewrites may return as unassigned or ambiguous. That is safe
+  degradation, not corruption.
+- If local session metadata is lost, do not edit generated refs or PR bodies to
+  reconstruct it. Reinitialize with the original pinned base and recreate the
+  same stable slice IDs.
+- Expect all atom attribution to return as unassigned after reinitialization. A
+  clean publish can adopt existing open slice PRs through their machine markers.
+- If a slice becomes empty, publication may leave its existing Draft PR open and
+  mark it empty; do not invent changes merely to keep the projection nonempty.
+
+After GitHub reports the integration PR as merged, run:
+
+```bash
+git-paoding archive
+```
+
+`archive` closes slice PRs, retains their URLs and discussion history, and
+cleans generated refs; it never merges them. It refuses to run while the
+integration PR is still open or merely closed.

git_paoding/agent_install.py

@@ -0,0 +1,113 @@
+"""Install the packaged git-paoding skill for supported coding agents."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from importlib.resources import files
+from pathlib import Path, PurePosixPath
+from typing import Any, Literal
+
+AgentTarget = Literal["codex", "claude"]
+InstallScope = Literal["user", "project"]
+
+
+class AgentInstallError(ValueError):
+    """Raised when an agent skill installation is invalid or unsafe."""
+
+
+@dataclass(frozen=True)
+class AgentInstallResult:
+    """Result of installing one packaged agent skill."""
+
+    target: AgentTarget
+    scope: InstallScope
+    destination: Path
+    changed: bool
+
+
+def _packaged_skill() -> Any:
+    root = files("git_paoding._agent_plugins")
+    skill = root.joinpath("git-paoding").joinpath("skills").joinpath("git-paoding")
+    if not skill.is_dir():
+        raise AgentInstallError("the installed package does not contain the git-paoding skill")
+    return skill
+
+
+def _resource_snapshot(resource: Any, prefix: PurePosixPath = PurePosixPath()) -> dict[str, bytes]:
+    snapshot: dict[str, bytes] = {}
+    for child in resource.iterdir():
+        relative = prefix / child.name
+        if child.is_dir():
+            snapshot.update(_resource_snapshot(child, relative))
+        elif child.is_file():
+            snapshot[relative.as_posix()] = child.read_bytes()
+    return snapshot
+
+
+def _directory_snapshot(directory: Path) -> dict[str, bytes]:
+    return {
+        path.relative_to(directory).as_posix(): path.read_bytes()
+        for path in directory.rglob("*")
+        if path.is_file()
+    }
+
+
+def _destination(
+    target: AgentTarget,
+    scope: InstallScope,
+    *,
+    project_root: Path,
+    home: Path,
+) -> Path:
+    if target == "codex":
+        base = (
+            home / ".agents" / "skills" if scope == "user" else project_root / ".agents" / "skills"
+        )
+    elif target == "claude":
+        base = (
+            home / ".claude" / "skills" if scope == "user" else project_root / ".claude" / "skills"
+        )
+    else:  # pragma: no cover - protected by public type and Click validation
+        raise AgentInstallError(f"unsupported agent target: {target}")
+    return base / "git-paoding"
+
+
+def install_agent_skill(
+    target: AgentTarget,
+    scope: InstallScope,
+    *,
+    project_root: Path | None = None,
+    home: Path | None = None,
+    force: bool = False,
+) -> AgentInstallResult:
+    """Install the packaged skill into one agent's user or project skill root."""
+
+    resolved_project = (project_root or Path.cwd()).resolve()
+    resolved_home = (home or Path.home()).resolve()
+    destination = _destination(
+        target,
+        scope,
+        project_root=resolved_project,
+        home=resolved_home,
+    )
+    source_snapshot = _resource_snapshot(_packaged_skill())
+    if not source_snapshot or "SKILL.md" not in source_snapshot:
+        raise AgentInstallError("the packaged git-paoding skill is incomplete")
+
+    if destination.exists():
+        if not destination.is_dir():
+            raise AgentInstallError(f"skill destination is not a directory: {destination}")
+        if _directory_snapshot(destination) == source_snapshot:
+            return AgentInstallResult(target, scope, destination, changed=False)
+        if not force:
+            raise AgentInstallError(
+                f"skill destination already exists with different contents: {destination}; "
+                "pass --force to overwrite packaged files"
+            )
+
+    for relative, content in source_snapshot.items():
+        output = destination / relative
+        output.parent.mkdir(parents=True, exist_ok=True)
+        output.write_bytes(content)
+
+    return AgentInstallResult(target, scope, destination, changed=True)