git-paoding 0.1.0__tar.gz

git_paoding-0.1.0/PKG-INFO

@@ -0,0 +1,351 @@
+Metadata-Version: 2.3
+Name: git-paoding
+Version: 0.1.0
+Summary: Semantic review slicing for large agent-generated changes
+Requires-Dist: click>=8.1
+Requires-Dist: pydantic>=2
+Requires-Dist: hypothesis>=6 ; extra == 'dev'
+Requires-Dist: mypy>=1.15 ; extra == 'dev'
+Requires-Dist: pre-commit>=4 ; extra == 'dev'
+Requires-Dist: pytest>=8 ; extra == 'dev'
+Requires-Dist: pytest-cov>=6 ; extra == 'dev'
+Requires-Dist: ruff>=0.11 ; extra == 'dev'
+Requires-Python: >=3.11
+Provides-Extra: dev
+Description-Content-Type: text/markdown
+
+# git-paoding
+
+<!-- cspell:words paoding pipx PAODING -->
+
+Agent writes globally. Humans review locally.
+
+`git-paoding` lets a coding agent keep one coherent implementation on one
+canonical integration branch while presenting the final change as several small,
+semantic Draft GitHub pull requests. Those slice PRs are review projections:
+they help people understand one concern at a time, but they are not development
+branches or merge targets.
+
+The canonical integration PR remains authoritative. It contains the complete
+change, runs CI, receives final approval, and merges. Review feedback goes back
+into the canonical branch; a later `git-paoding publish` refreshes the
+projections without creating a branch stack to restack.
+
+The name comes from 庖丁解牛 (_Chef Ding carves the ox_): cutting along the
+natural joints.
+
+
+## Install the CLI and agent workflow
+
+`git-paoding` is designed for coding agents rather than as a human-operated UI.
+A complete installation has two parts:
+
+1. The Python package provides the deterministic `git-paoding` executable.
+2. The agent skill or plugin teaches Codex or Claude Code when and how to use it.
+
+Installing only the Python package does not make an agent discover the workflow.
+Install the CLI and one agent integration together.
+
+### Give this page to an agent
+
+You can send an agent this repository URL and the following request:
+
+```text
+Install git-paoding by following the repository README. Install the Python CLI
+and the integration for the agent you are running as, verify both, and then
+explain the workflow. Do not initialize a session, push, publish, or change any
+repository until I give you a specific review-slicing task.
+```
+
+### 1. Install the CLI
+
+`git-paoding` requires Python 3.11 or newer, Git, and
+[GitHub CLI](https://cli.github.com/) 2.45.0 or newer. GitHub operations reuse
+the account and credentials configured by `gh`; authenticate before initializing
+a session:
+
+```bash
+gh auth login
+gh auth status
+```
+
+Install the released package with one of these methods. `uv tool` or `pipx` is
+recommended because it keeps the agent-facing command isolated:
+
+```bash
+uv tool install git-paoding
+pipx install git-paoding
+python -m pip install git-paoding
+```
+
+Choose one installation method, not all three. Confirm the explicit command and
+Git's external-subcommand form resolve to the same release:
+
+```bash
+git-paoding --version
+git paoding --version
+```
+
+If the first PyPI release is not available yet, install the current GitHub
+version directly:
+
+```bash
+uv tool install "git+https://github.com/NagisaVon/git-paoding.git"
+```
+
+To install from a source checkout instead:
+
+```bash
+git clone https://github.com/NagisaVon/git-paoding.git
+cd git-paoding
+uv sync --extra dev --locked
+uv run git-paoding --help
+```
+
+### 2. Install the agent integration
+
+Choose one of the following installation methods for each agent. The bundled
+standalone skill and the marketplace plugin provide the same instructions, so
+installing both for the same agent is unnecessary.
+
+#### Option A: install the bundled standalone skill
+
+The Python distribution carries the same `SKILL.md` used by both plugins. The
+following commands copy that bundled skill into the official personal skill
+directory and work without a plugin UI:
+
+For Codex:
+
+```bash
+git-paoding agent install --target codex --scope user
+```
+
+For Claude Code:
+
+```bash
+git-paoding agent install --target claude --scope user
+```
+
+To install both, repeat `--target` in one command:
+
+```bash
+git-paoding agent install --target codex --target claude --scope user
+```
+
+Use `--scope project` to install into the current repository instead of the
+current user's global skill directory. Re-run with `--force` after upgrading if
+the installed skill was modified locally. Codex installs to
+`.agents/skills/git-paoding`; Claude Code installs to
+`.claude/skills/git-paoding` (under the home directory for user scope).
+
+Verify the skill appears in Codex with `/skills`. In Claude Code, run `/skills`
+or invoke `/git-paoding` directly. Restart the agent only if a newly created
+top-level skill directory is not detected in the current session.
+
+#### Option B: install through the plugin marketplace
+
+This repository is also a marketplace for a skill-only `git-paoding` plugin.
+The Codex and Claude Code manifests share one packaged skill, so their behavior
+does not drift.
+
+For Codex, add the GitHub marketplace:
+
+```bash
+codex plugin marketplace add NagisaVon/git-paoding
+codex plugin add git-paoding@git-paoding
+```
+
+The same plugin then appears in the Plugins Directory in the ChatGPT desktop
+app. Invoke its skill as `$git-paoding`.
+
+For Claude Code, the complete installation is available from the CLI:
+
+```bash
+claude plugin marketplace add NagisaVon/git-paoding
+claude plugin install git-paoding@git-paoding --scope user
+```
+
+Run `/reload-plugins` if Claude Code asks for it, then invoke the plugin skill as
+`/git-paoding:git-paoding`.
+
+### 3. Ask the agent to prepare review slices
+
+For Codex:
+
+```text
+$git-paoding Prepare semantic review slices for the complete committed change
+on my current branch, using origin/main as the base. Inspect and propose the
+slice assignments first. Do not push or publish until I approve the plan.
+```
+
+For the Claude Code plugin:
+
+```text
+/git-paoding:git-paoding Prepare semantic review slices for the complete
+committed change on my current branch, using origin/main as the base. Inspect
+and propose the slice assignments first. Do not push or publish until I approve
+the plan.
+```
+
+## Run a review-slicing session
+
+After installation, Codex and Claude Code follow the same operational workflow
+below. Their invocation syntax differs (`$git-paoding` in Codex and
+`/git-paoding:git-paoding` for the Claude Code plugin), but both use the same
+`git-paoding` CLI and repository state.
+
+Start from the branch that contains the complete, committed implementation. The
+base is pinned when the session is initialized; moving `origin/main` later does
+not silently move that pin.
+
+```bash
+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"
+git-paoding status --json
+```
+
+`status` is local and read-only. Exit code `2` is expected while it reports
+unassigned or ambiguous atoms. Its JSON includes each atom's ID, path, Base and
+Final ranges, owner, state, and short preview. Use `git-paoding status --full`
+when complete changed-hunk previews are useful.
+
+`--slice-prefix` is optional and defaults to `slice`. It changes only generated
+slice PR titles, such as `[ABC-123] Storage boundary`; slice IDs and generated
+refs remain stable. The integration PR title is the canonical branch name.
+
+Assign interactively by an atom ID, path, directory, glob, or Final-coordinate
+line range. Broad selectors preserve already-owned atoms unless `--force` is
+passed; explicit atom IDs may reassign their exact atom without it. Every
+selected atom is echoed as assigned or skipped:
+
+```bash
+git-paoding assign storage src/storage.py
+git-paoding assign tests tests/test_storage.py
+git-paoding status --json
+```
+
+When no action is needed, publish the review projections:
+
+```bash
+git-paoding publish
+```
+
+`publish` is idempotent. It reconciles first and stops with exit code `2` and no
+remote effects if attribution still needs attention. A clean publish pushes
+generated projection refs, creates or refreshes stable Draft slice PRs, and
+creates or updates the Draft integration PR and its slice index. Operational
+failures use exit code `1`; success uses `0`.
+
+Keep the canonical branch available on the selected Git remote before
+publishing. If it has not been pushed, obtain the change owner's approval before
+doing so:
+
+```bash
+git push -u origin HEAD
+```
+
+### Three-step agent flow
+
+The intended agent loop is:
+
+```bash
+git-paoding status --json
+git-paoding assign --batch paoding-assignments.json
+git-paoding publish
+```
+
+The batch request uses the frozen versioned contract:
+
+```json
+{
+  "contract_version": 0,
+  "assignments": {
+    "storage": ["src/storage.py"],
+    "tests": ["tests/test_storage.py"]
+  },
+  "force": false
+}
+```
+
+Batch assignment is all-or-nothing: an unknown slice, invalid selector, or
+cross-slice conflict rejects the entire request. Set the JSON `force` field to
+`true` when a batch is intentionally repartitioning already-owned atoms; do not
+combine the interactive `--force` option with `--batch`. The batch plan is an
+ordinary local input file rather than session metadata; keep it untracked or
+manage it according to the repository's own policy.
+
+For targeted review feedback, focus may provide a default owner for genuinely
+new atoms without overwriting confidently matched ownership:
+
+```bash
+git-paoding focus storage
+git-paoding status --json
+git-paoding focus --clear
+```
+
+## What reviewers should know
+
+A slice PR is a view onto one semantic part of the final integrated change.
+Different slices may touch different regions of the same file, and one slice may
+rely on code shown by another. A slice is not required to build or test by
+itself.
+
+Every slice PR is Draft and carries a
+**DO NOT MERGE — review projection only** warning because:
+
+- Its generated base and head refs are disposable projections.
+- It is not the branch where implementation work happens.
+- Its review is for comprehension, not authoritative approval.
+- Only the integration PR represents the complete change and real merge target.
+
+Use normal GitHub review features on a slice PR: read its narrative, inspect
+Files changed, and leave inline comments. After feedback, update the canonical
+branch and refresh the same slice PR. GitHub may mark comments
+outdated when their lines change; the discussion history and stable PR identity
+remain useful.
+
+## Suppress CI for slice PRs
+
+Slice projections are review units, not integration units. In consumer
+repositories, filter the `pull_request` workflow to real target branches so
+generated `paoding/.../base` refs do not start authoritative CI. For a
+repository that merges into `main`:
+
+```yaml
+name: CI
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+```
+
+GitHub evaluates the `pull_request.branches` filter against the PR's base
+branch. Keep the normal CI and branch-protection requirements on the integration
+PR.
+
+## Safety and recovery
+
+- Work only on the canonical integration branch. Never check out or edit
+  generated `paoding/...` branches.
+- Never merge a slice PR. Close/archive it after the integration PR merges.
+- Do not expect a slice projection to build, test, or pass CI independently.
+- Unassigned or ambiguous atoms are normal recovery states, not metadata
+  corruption. Rerun `status`, classify what remains, and publish again.
+- Slice metadata lives in the repository's common Git directory and is not
+  committed. Do not delete it as a routine reset.
+- If session metadata is lost, recreate the session and the same stable slice
+  IDs. Attribution returns as unassigned, while existing open slice PRs can be
+  adopted by their machine markers on the next clean publish.
+- New PR bodies contain only their machine-managed region; the tool does not
+  seed a narrative template. Human narrative added outside those delimiters is
+  preserved byte-for-byte on refresh.
+
+After GitHub reports the integration PR as merged, archive the generated review
+surface without merging any slice PR:
+
+```bash
+git-paoding archive
+```

git_paoding-0.1.0/README.md

@@ -0,0 +1,335 @@
+# git-paoding
+
+<!-- cspell:words paoding pipx PAODING -->
+
+Agent writes globally. Humans review locally.
+
+`git-paoding` lets a coding agent keep one coherent implementation on one
+canonical integration branch while presenting the final change as several small,
+semantic Draft GitHub pull requests. Those slice PRs are review projections:
+they help people understand one concern at a time, but they are not development
+branches or merge targets.
+
+The canonical integration PR remains authoritative. It contains the complete
+change, runs CI, receives final approval, and merges. Review feedback goes back
+into the canonical branch; a later `git-paoding publish` refreshes the
+projections without creating a branch stack to restack.
+
+The name comes from 庖丁解牛 (_Chef Ding carves the ox_): cutting along the
+natural joints.
+
+
+## Install the CLI and agent workflow
+
+`git-paoding` is designed for coding agents rather than as a human-operated UI.
+A complete installation has two parts:
+
+1. The Python package provides the deterministic `git-paoding` executable.
+2. The agent skill or plugin teaches Codex or Claude Code when and how to use it.
+
+Installing only the Python package does not make an agent discover the workflow.
+Install the CLI and one agent integration together.
+
+### Give this page to an agent
+
+You can send an agent this repository URL and the following request:
+
+```text
+Install git-paoding by following the repository README. Install the Python CLI
+and the integration for the agent you are running as, verify both, and then
+explain the workflow. Do not initialize a session, push, publish, or change any
+repository until I give you a specific review-slicing task.
+```
+
+### 1. Install the CLI
+
+`git-paoding` requires Python 3.11 or newer, Git, and
+[GitHub CLI](https://cli.github.com/) 2.45.0 or newer. GitHub operations reuse
+the account and credentials configured by `gh`; authenticate before initializing
+a session:
+
+```bash
+gh auth login
+gh auth status
+```
+
+Install the released package with one of these methods. `uv tool` or `pipx` is
+recommended because it keeps the agent-facing command isolated:
+
+```bash
+uv tool install git-paoding
+pipx install git-paoding
+python -m pip install git-paoding
+```
+
+Choose one installation method, not all three. Confirm the explicit command and
+Git's external-subcommand form resolve to the same release:
+
+```bash
+git-paoding --version
+git paoding --version
+```
+
+If the first PyPI release is not available yet, install the current GitHub
+version directly:
+
+```bash
+uv tool install "git+https://github.com/NagisaVon/git-paoding.git"
+```
+
+To install from a source checkout instead:
+
+```bash
+git clone https://github.com/NagisaVon/git-paoding.git
+cd git-paoding
+uv sync --extra dev --locked
+uv run git-paoding --help
+```
+
+### 2. Install the agent integration
+
+Choose one of the following installation methods for each agent. The bundled
+standalone skill and the marketplace plugin provide the same instructions, so
+installing both for the same agent is unnecessary.
+
+#### Option A: install the bundled standalone skill
+
+The Python distribution carries the same `SKILL.md` used by both plugins. The
+following commands copy that bundled skill into the official personal skill
+directory and work without a plugin UI:
+
+For Codex:
+
+```bash
+git-paoding agent install --target codex --scope user
+```
+
+For Claude Code:
+
+```bash
+git-paoding agent install --target claude --scope user
+```
+
+To install both, repeat `--target` in one command:
+
+```bash
+git-paoding agent install --target codex --target claude --scope user
+```
+
+Use `--scope project` to install into the current repository instead of the
+current user's global skill directory. Re-run with `--force` after upgrading if
+the installed skill was modified locally. Codex installs to
+`.agents/skills/git-paoding`; Claude Code installs to
+`.claude/skills/git-paoding` (under the home directory for user scope).
+
+Verify the skill appears in Codex with `/skills`. In Claude Code, run `/skills`
+or invoke `/git-paoding` directly. Restart the agent only if a newly created
+top-level skill directory is not detected in the current session.
+
+#### Option B: install through the plugin marketplace
+
+This repository is also a marketplace for a skill-only `git-paoding` plugin.
+The Codex and Claude Code manifests share one packaged skill, so their behavior
+does not drift.
+
+For Codex, add the GitHub marketplace:
+
+```bash
+codex plugin marketplace add NagisaVon/git-paoding
+codex plugin add git-paoding@git-paoding
+```
+
+The same plugin then appears in the Plugins Directory in the ChatGPT desktop
+app. Invoke its skill as `$git-paoding`.
+
+For Claude Code, the complete installation is available from the CLI:
+
+```bash
+claude plugin marketplace add NagisaVon/git-paoding
+claude plugin install git-paoding@git-paoding --scope user
+```
+
+Run `/reload-plugins` if Claude Code asks for it, then invoke the plugin skill as
+`/git-paoding:git-paoding`.
+
+### 3. Ask the agent to prepare review slices
+
+For Codex:
+
+```text
+$git-paoding Prepare semantic review slices for the complete committed change
+on my current branch, using origin/main as the base. Inspect and propose the
+slice assignments first. Do not push or publish until I approve the plan.
+```
+
+For the Claude Code plugin:
+
+```text
+/git-paoding:git-paoding Prepare semantic review slices for the complete
+committed change on my current branch, using origin/main as the base. Inspect
+and propose the slice assignments first. Do not push or publish until I approve
+the plan.
+```
+
+## Run a review-slicing session
+
+After installation, Codex and Claude Code follow the same operational workflow
+below. Their invocation syntax differs (`$git-paoding` in Codex and
+`/git-paoding:git-paoding` for the Claude Code plugin), but both use the same
+`git-paoding` CLI and repository state.
+
+Start from the branch that contains the complete, committed implementation. The
+base is pinned when the session is initialized; moving `origin/main` later does
+not silently move that pin.
+
+```bash
+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"
+git-paoding status --json
+```
+
+`status` is local and read-only. Exit code `2` is expected while it reports
+unassigned or ambiguous atoms. Its JSON includes each atom's ID, path, Base and
+Final ranges, owner, state, and short preview. Use `git-paoding status --full`
+when complete changed-hunk previews are useful.
+
+`--slice-prefix` is optional and defaults to `slice`. It changes only generated
+slice PR titles, such as `[ABC-123] Storage boundary`; slice IDs and generated
+refs remain stable. The integration PR title is the canonical branch name.
+
+Assign interactively by an atom ID, path, directory, glob, or Final-coordinate
+line range. Broad selectors preserve already-owned atoms unless `--force` is
+passed; explicit atom IDs may reassign their exact atom without it. Every
+selected atom is echoed as assigned or skipped:
+
+```bash
+git-paoding assign storage src/storage.py
+git-paoding assign tests tests/test_storage.py
+git-paoding status --json
+```
+
+When no action is needed, publish the review projections:
+
+```bash
+git-paoding publish
+```
+
+`publish` is idempotent. It reconciles first and stops with exit code `2` and no
+remote effects if attribution still needs attention. A clean publish pushes
+generated projection refs, creates or refreshes stable Draft slice PRs, and
+creates or updates the Draft integration PR and its slice index. Operational
+failures use exit code `1`; success uses `0`.
+
+Keep the canonical branch available on the selected Git remote before
+publishing. If it has not been pushed, obtain the change owner's approval before
+doing so:
+
+```bash
+git push -u origin HEAD
+```
+
+### Three-step agent flow
+
+The intended agent loop is:
+
+```bash
+git-paoding status --json
+git-paoding assign --batch paoding-assignments.json
+git-paoding publish
+```
+
+The batch request uses the frozen versioned contract:
+
+```json
+{
+  "contract_version": 0,
+  "assignments": {
+    "storage": ["src/storage.py"],
+    "tests": ["tests/test_storage.py"]
+  },
+  "force": false
+}
+```
+
+Batch assignment is all-or-nothing: an unknown slice, invalid selector, or
+cross-slice conflict rejects the entire request. Set the JSON `force` field to
+`true` when a batch is intentionally repartitioning already-owned atoms; do not
+combine the interactive `--force` option with `--batch`. The batch plan is an
+ordinary local input file rather than session metadata; keep it untracked or
+manage it according to the repository's own policy.
+
+For targeted review feedback, focus may provide a default owner for genuinely
+new atoms without overwriting confidently matched ownership:
+
+```bash
+git-paoding focus storage
+git-paoding status --json
+git-paoding focus --clear
+```
+
+## What reviewers should know
+
+A slice PR is a view onto one semantic part of the final integrated change.
+Different slices may touch different regions of the same file, and one slice may
+rely on code shown by another. A slice is not required to build or test by
+itself.
+
+Every slice PR is Draft and carries a
+**DO NOT MERGE — review projection only** warning because:
+
+- Its generated base and head refs are disposable projections.
+- It is not the branch where implementation work happens.
+- Its review is for comprehension, not authoritative approval.
+- Only the integration PR represents the complete change and real merge target.
+
+Use normal GitHub review features on a slice PR: read its narrative, inspect
+Files changed, and leave inline comments. After feedback, update the canonical
+branch and refresh the same slice PR. GitHub may mark comments
+outdated when their lines change; the discussion history and stable PR identity
+remain useful.
+
+## Suppress CI for slice PRs
+
+Slice projections are review units, not integration units. In consumer
+repositories, filter the `pull_request` workflow to real target branches so
+generated `paoding/.../base` refs do not start authoritative CI. For a
+repository that merges into `main`:
+
+```yaml
+name: CI
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+```
+
+GitHub evaluates the `pull_request.branches` filter against the PR's base
+branch. Keep the normal CI and branch-protection requirements on the integration
+PR.
+
+## Safety and recovery
+
+- Work only on the canonical integration branch. Never check out or edit
+  generated `paoding/...` branches.
+- Never merge a slice PR. Close/archive it after the integration PR merges.
+- Do not expect a slice projection to build, test, or pass CI independently.
+- Unassigned or ambiguous atoms are normal recovery states, not metadata
+  corruption. Rerun `status`, classify what remains, and publish again.
+- Slice metadata lives in the repository's common Git directory and is not
+  committed. Do not delete it as a routine reset.
+- If session metadata is lost, recreate the session and the same stable slice
+  IDs. Attribution returns as unassigned, while existing open slice PRs can be
+  adopted by their machine markers on the next clean publish.
+- New PR bodies contain only their machine-managed region; the tool does not
+  seed a narrative template. Human narrative added outside those delimiters is
+  preserved byte-for-byte on refresh.
+
+After GitHub reports the integration PR as merged, archive the generated review
+surface without merging any slice PR:
+
+```bash
+git-paoding archive
+```