claude-dev-env 8.40.0 → 8.41.0

package/rules/git-workflow.md

@@ -1,121 +0,0 @@
-# Git workflow
-
-User-level rule: applies to **every** git repo that uses GitHub with `gh`. Small or non-primary repos follow the same rule unless the user says otherwise in the session.
-
-## Workflow decision tree
-
-**When to use stacked PRs:** Feature B depends on Feature A's implementation
-
-**When to extract shared infrastructure first:** Multiple features need same utilities/helpers
-
-**Extract Shared Infrastructure Pattern:**
-1. Create infrastructure PR with only shared code
-2. Get reviewed and MERGE infrastructure first
-3. Launch parallel feature PRs that use merged infrastructure
-
-## Pull request submission rules
-
-**Open every pull request ready for review.** Pass `--draft` only when the owner asks
-for a draft.
-
-**A release bot's PR body is machine input. Leave it alone.** Release automation reads
-back the body of its own merged pull request to decide it owns that merge. Rewriting the
-body, or trimming its header or footer, makes the bot treat the merge as somebody else's
-work: it cuts no tag, the publish job skips, and it opens one more release pull request on
-the next run. The merge stays in the repository. No tag is cut and the package never publishes.
-
-Spot one by its head branch, which starts `release-please--branches--`, or by a body that
-opens with the bot's own marker line. The description rules in this file, the
-`pstack:poteto-agent` writing brief, and the house wording style all step aside for it. The
-failure signature in the release job log reads
-`could not parse pull request body as a release PR`.
-
-`pstack:poteto-agent` writes a title and body from the diff when you want one.
-Publish the title and body file through
-`~/.agents/skills/pull-request/scripts/pull_request.py`. That path is under the
-agents home, not the repository. A worktree holds no `.agents/` copy.
-
-Resolve the active managed root (`CLAUDE_CONFIG_DIR` when set, `~/.claude`
-otherwise), then run `<managed-root>/scripts/durable_post_lint.py` before any
-pull request, issue, or GitHub MCP post. The linter checks the action-specific
-title, body, and volatile-path rules before credential lookup or network
-access.
-
-Use `.agents/skills/pull-request/scripts/recover_legacy_author.py
-<exact-state-file> --confirm-inactive` only for one explicitly selected legacy
-author record. Do not infer a record from age alone. Keep every other record
-untouched.
-
-## Confirm the required checks fired, and let CI run them
-
-The gate runs once, and it runs on CI. Push the branch and read its verdict.
-[`ci-owns-the-gate.md`](ci-owns-the-gate.md) holds the reasoning and the shape
-a local run takes when one is warranted.
-
-Read the branch ruleset for the required check contexts before you push a
-branch, or any level of a stack: `gh api repos/<owner>/<repo>/rules/branches/<trunk>`.
-Read it to learn which checks must report. After the push, confirm each of those
-contexts appears on that level's head. A required check that never fired is
-invisible debt at every level, and it surfaces only after the whole stack is
-pushed, when the repair costs a second pass over every branch.
-
-A red required check blocks the branch, whoever owns the failing line. The
-staged policy lint grades a change against the file's prior text, so a finding
-that survives is one the change introduced or made worse. Fix that line in the
-next push or report the branch blocked. A finding the change did not introduce
-is a gate-scoping defect: report it against the lint and leave the file's shape
-alone. Restructuring a file to satisfy a mis-scoped check trades one finding for
-a set of new ones. Read the gate's own report rather than a narrower substitute. A
-single-file mypy call cannot see sibling modules and reports false import
-errors, so it neither clears nor convicts a change.
-
-A checks listing that reports nothing on the branch is a finding, not a neutral
-state. Find out whether the workflow's event filters exclude the branch, or whether
-the check simply never ran, before you treat that branch as clean.
-
-## Each stack level stands on its own
-
-A symbol belongs at the level that first **uses** it, not the level that first
-mentions it. A bottom pull request that declares the imports its descendants will
-need fails the linter on unused imports. A test helper that calls a function three
-levels above it fails on an undefined name. Both defects stay invisible while you
-read the finished tip, and both are obvious the moment you check one level alone.
-
-Prove each level before you push it: import the modules that level changes, and run
-the required linter against that level's own base. To repair a level, rebuild its
-import header as the union of what that level references, let the linter's
-autofix strip the rest, and move a premature helper up to the level that defines
-what it calls.
-
-## A force-push that moves content obliges a description refresh
-
-Force-with-lease protects the ref. It protects nobody's understanding of what the
-branch now holds. When a rewrite moves content between levels of a stack, or
-otherwise changes what a branch contains, refresh that pull request's description
-before you ask anyone to read or merge it.
-
-## Never commit working documents or images
-
-**Keep these files out of the repository:**
-
-| Pattern | Reason |
-|---------|--------|
-| `docs/plans/*.md` | Working documents for planning, not repo content |
-| `*.plan.md` | Temporary planning files |
-| `SESSION_STATE.md` | Local session state |
-| `*.png *.jpg *.jpeg *.gif *.webp *.avif *.svg *.ico` | Images go to external storage, not GitHub |
-
-An image a PR needs as visual evidence is not an exception to that row. Upload it to the repository's durable `artifacts` release with `python3 ~/.claude/scripts/gh_artifact_upload.py <file> <owner/repo>` and embed the permanent URL in the PR comment. The image lives on GitHub without entering the repository tree.
-
-## Responding to review feedback
-
-**When this applies:** GitHub PR review feedback on a branch you are fixing.
-
-1. Fetch every reviewer comment before making any fix.
-2. Create a checklist in the session's task tool with one item per comment.
-3. Fix systematically, marking each todo complete.
-4. Reply to each comment inline.
-
-Repair only the reported findings.
-
-Every `gh` post in this workflow uses `--body-file` per `gh-cli-conventions.md` and keeps volatile scratch paths out per `durable-post-artifacts.md`. Stage session edits per `re-stage-before-commit.md` before each commit.

package/rules/re-stage-before-commit.md

@@ -1,14 +0,0 @@
-# Re-Stage Session Edits Before Commit
-
-Stage the files you edited this session right before you commit them. A plain `git commit` records only the staged snapshot; a tracked file this session changed but left unstaged stays behind in the working tree.
-
-No hook denies a commit that would drop tracked session edits. Run `git status` before you commit, then stage what you changed with `git add <paths>` or commit with `git commit -a`.
-
-Staging covers tracked files you edited. Do not commit untracked files unless the user explicitly instructs it. An untracked file in the working tree is outside the change until they say otherwise.
-
-## Staging shapes
-
-- **A pathspec.** `git commit -- <paths>` or `git commit <paths>` commits only the named paths on purpose.
-- **A preceding `git add` or `git stage`.** `git add <paths> && git commit …` stages the files in its own segment before the commit runs.
-
-A `--amend` carries the same risk. An amend records the staged snapshot too, so an unstaged session edit is dropped the same way a plain commit drops it.

package/rules/review-closure-is-a-check.md

@@ -1,54 +0,0 @@
-# Review Closure Is a Check
-
-**When this applies:** Any pull request an agent drives, from the first review comment on it to the merge.
-
-## Rule
-
-A review finding on the head is answered before the pull request merges. The agent driving it replies, pushes the fix, or both. The check named `Review closure` reads that state on every push, on every review event, and on every top-level comment, and reports red while a finding waits.
-
-One command prints the same verdict:
-
-```
-python packages/claude-dev-env/scripts/review_closure.py <owner>/<name> <number>
-```
-
-It prints `CLOSED` and exits 0 when every finding on the head is answered. It prints `OPEN`, one line per waiting finding, and exits 1. It exits 2 when the state could not be read.
-
-## What closes a finding
-
-| The thread | Closed by |
-|---|---|
-| A review comment on code | A push that replaced the code it points at |
-| A review comment on code | A reply from the account driving the pull request |
-| A review comment on code | Resolution, where the comment carries no red circle |
-| A red-circle finding | A reply from the driving account, or a push that replaced the code |
-| A thread the driving account opened | Itself |
-| A blocking `Claude Approvals` row | A push, which moves the head the check reports on |
-| A top-level comment on the pull request | A later top-level comment from the driving account |
-| A bot notice: a review-skipped note, a pointer to an updated summary, a Graphite verdict mirror, a Qodo change summary, a Qodo in-progress placeholder, or a Qodo review that found no issues | Itself |
-
-A review bot rewrites its summary comment on each pass. Its edit leaves an answered summary closed, because each new finding it has arrives as a review thread or a new comment. An edit from a person reopens the comment.
-
-A red circle marks a finding a review states as blocking, so resolution in silence leaves it open. The reply says what changed or why the finding stands, and the reviewer reads it beside the diff.
-
-The driving account is the one that opened the pull request. Where the agent comments under a second login, `--driver-login <login>` names it, repeatably.
-
-A repository whose review bots post notices this package does not know passes each one's marker text with `--notice-marker <text>`, repeatably. A bot comment carrying that text closes itself, like the built-in notices above.
-
-## Where the check runs
-
-`.github/workflows/review-closure.yml` runs it here on a push to a pull request, on a submitted or dismissed review, on a review comment, and on a top-level comment posted or edited on a pull request. Each run reports on the pull request's head commit, so a finding posted after the last push still turns the check red.
-
-A top-level comment arrives as an `issue_comment` event, and a run on that event belongs to the default branch commit. The comment job reads the pull request's head, runs the same command, and posts the verdict on that head through the Checks API as a `Review closure` check run. The token belongs to the GitHub Actions app, so that check run carries the same name and app as the pull request job's own, and the newest one on the head is the one branch rules read.
-
-A private repository that installs this package runs the same command from its own workflow, against the revision of this package that its workflow pins.
-
-A repository that merges through a merge queue also runs the check on `merge_group` and lists `Review closure` as a required check. The queue ref `gh-readonly-queue/<base>/pr-<number>-<sha>` names the pull request number the command takes. A finding posted while an entry waits in the queue then fails the queue build. Without that trigger, the entry merges on the verdict it carried when it joined the queue.
-
-## Sibling rules
-
-| Rule | Role |
-|---|---|
-| [`agent-merges-its-own-green-pull-request.md`](agent-merges-its-own-green-pull-request.md) | The agent that drives a pull request merges it once its gate passes |
-| [`git-workflow.md`](git-workflow.md) | Open ready for review, and confirm each required context fired after the push |
-| [`correction-lens.md`](correction-lens.md) | A correction becomes a control at the highest layer that can hold it |