claude-dev-env 8.6.0 → 8.7.0

package/rules/agent-merges-its-own-green-pull-request.md

@@ -0,0 +1,54 @@
+# The Agent Merges Its Own Green Pull Request
+
+**When this applies:** Any pull request an agent opened or was asked to drive, once its checks report.
+
+## Rule
+
+The agent that drives a pull request merges it. A pull request that is green, carries no open review thread, and sits at a merge state of `clean` is merged in the same run that brought it there. Waiting for the owner to type "merge" parks finished work on the person the work was done for.
+
+Three things stay with the owner, and nothing else does:
+
+- A pull request the owner asked to hold.
+- A change the owner said they want to read first.
+- A repository whose branch rule requires an approving review the agent cannot give.
+
+Where the branch rule requires zero approvals and one status check, that check is the gate, and the agent merges on its verdict.
+
+Validation is the precondition, and green means every check reported on the exact head commit. A branch rule that requires one status check names the floor a merge needs; a pull request whose other checks are red or still running is held until they report.
+
+## The precondition is mechanical
+
+One command prints the verdict:
+
+```
+python packages/claude-dev-env/scripts/agent_merge_check.py <owner>/<name> <number>
+```
+
+It prints `MERGE` and exits 0 when the pull request is ready. It prints `HOLD` with the reason and exits 1 for a draft, for a head behind or conflicting with the base, for a required check that is not passing, for a check still running or red, and for an open review thread. It exits 2 when the state could not be read.
+
+Each hold reason names its own repair, and each repair belongs to the agent:
+
+| Hold | What the agent does |
+|---|---|
+| Head behind the base | Merge the base branch in and push |
+| Head conflicts with the base | Merge the base branch in, resolve, push |
+| A required check is red | Read the failing check, fix it, push |
+| A check is red or still running | Fix it, or wait for it, then read the verdict again |
+| A review thread is open | Answer it, push the fix, resolve the thread |
+| The pull request is a draft | Mark it ready once the checks pass |
+
+## When a gate elsewhere holds the merge command
+
+A session working inside another repository can sit behind that repository's own pre-merge gate, which reads the checkout the session works in and refuses a merge command whatever repository the pull request belongs to. That session hands the merge to the session that owns this repository's pull requests, by message, naming the pull request. The receiving session reads the verdict above and merges. The hand-off carries the work; it never lands on the owner.
+
+## After the merge
+
+Delete nothing by hand. The repository deletes the head branch on merge.
+
+## Sibling rules
+
+| Rule | Role |
+|---|---|
+| [`git-workflow.md`](git-workflow.md) | Draft first, and confirm each required context fired after the push |
+| [`ci-owns-the-gate.md`](ci-owns-the-gate.md) | The gate runs once, and it runs on CI |
+| [`correction-lens.md`](correction-lens.md) | A correction becomes a control at the highest layer that can hold it |

package/rules/archiving-agent-config.md

@@ -43,6 +43,16 @@ Record a row in the archive manifest for each file: why it went, the `git mv`
 that restores it, and every other edit a restore has to undo. A restore that has
 to be reconstructed from the diff is not recoverable in any useful sense.
 
+## Exempt files
+
+The "Never archived" section of `rules-archived/ARCHIVE-MANIFEST.md` names the
+files this procedure leaves alone. Read that section before a prune moves
+anything. A pass that reaches an exempt file stops there and reports which file
+it was, so the prune's other moves still land.
+
+`rules/correction-lens.md` is on that list today. Editing an exempt file to
+sharpen it is ordinary work.
+
 ## Make the archive stick
 
 Two things do not follow the file on their own.

package/rules/code-standards.md

@@ -27,6 +27,7 @@ BDD is the outer process and TDD is the inner loop: [`bdd.md`](bdd.md) discovers
 
 | Concern | Rule file |
 |---|---|
+| Handling a correction from the user | [`correction-lens.md`](correction-lens.md) |
 | Task tracking / worker completion | [`workers-done-before-complete.md`](workers-done-before-complete.md) |
 | Multi-step task list | skill `task-build` (see agents catalog) |
 

package/rules/correction-lens.md

@@ -0,0 +1,134 @@
+# Correction Lens
+
+**Standing rule. This file is never archived and never removed.** The permanence
+clause at the end of this document states what that binds.
+
+**When this applies:** Every correction the user gives. A "no, do it this way", a
+"stop writing that word", a repeated review comment, a fix the user makes by hand
+after an agent hands work back. Each one is evidence that a control is missing,
+and the correction is handled by building that control.
+
+## Rule
+
+A correction runs through five layers, in this order, and the lesson lands at the
+highest layer that can hold it. The change opens in the same run as the
+correction.
+
+| Priority | Layer | What holds the lesson | The lesson lands as |
+|---|---|---|---|
+| 1 | Codebase | The mistake is impossible by how the code is written | A type, a signature, a data structure, an API shape, a deleted branch |
+| 2 | Static analysis | A program reads the tree and decides | A lint rule, an enforcer check, a paired test, a CI gate |
+| 3 | Review tooling | A reviewer or a review bot reads the criterion | A `CODE_RULES.md` row, a `.cursor/BUGBOT.md` pointer, a Graphite or BugBot rule |
+| 4 | Skill | An agent follows a procedure | A skill under the agents home |
+| 5 | Style guide | Word choice and prose shape | A row in a `rules/*.md` file or a style document |
+
+Layer 1 is the goal every time. A lesson encoded there needs no reader, no run,
+and no agent to remember it. The wrong call has nowhere to live.
+
+## Choosing the layer
+
+Three sentences close every correction:
+
+1. The layer chosen.
+2. Why each higher layer cannot hold this lesson.
+3. The change opened at the chosen layer, by pull request.
+
+A layer holds a lesson when its own test passes:
+
+- **Layer 1 holds it** when a type, a signature, or a data structure can make the
+  wrong call fail to compile, fail to construct, or fail to exist.
+- **Layer 2 holds it** when a program reading the tree can separate right from
+  wrong with no judgment call.
+- **Layer 3 holds it** when a reader needs the criterion in front of them and a
+  program cannot decide it.
+- **Layer 4 holds it** when the lesson is a procedure with steps an agent runs.
+- **Layer 5 holds it** when the lesson is word choice or the shape of prose.
+
+Effort rules out no layer. A layer is ruled out when it lacks the capability to
+hold the lesson, and the sentence that rules it out says which capability is
+missing. "A lint for this would take a day" leaves layer 2 in play.
+
+Two layers often hold one correction. Take both: the shape at layer 1 and the
+check at layer 2 cost one run together and each covers what the other misses.
+
+## A repeated correction moves up a layer
+
+The same correction arriving a second time is the measurement. The layer chosen
+the first time was too low. Move the lesson one layer up and say so in the same
+run.
+
+A review comment that repeats across pull requests reads the same way. Each
+repetition names the layer below the reviewer as the one that needs the control.
+Count the repetitions.
+
+## Where the control lands
+
+A control lands in this package, so every session that loads this environment
+carries it, on any machine, under any model. A control written into one
+project's instructions reaches that project alone, and a control written into a
+chat reply reaches that conversation alone.
+
+Memory holds the decision. The control holds the behavior. A correction that
+produced a memory file and nothing else has been recorded and never encoded, so
+the rule still binds. Open the control.
+
+## Trust grows as the controls catch the common mistakes
+
+Add agents after the controls catch what agents get wrong, and start from a
+workflow small enough to watch. Each repeated correction becomes a stronger
+control, and the number of agents rises behind it.
+[`docs/high-trust-agent-delivery.md`](../docs/high-trust-agent-delivery.md)
+carries the model this comes from, including the layered-controls picture and
+the inner and outer delivery loops.
+
+## Permanence
+
+This file stays in `rules/`. A prune pass, an archive sweep, a consolidation, or
+a rewrite that would move it into `rules-archived/` stops at this line. The
+"Never archived" section of
+[`packages/claude-dev-env/rules-archived/ARCHIVE-MANIFEST.md`](../rules-archived/ARCHIVE-MANIFEST.md)
+names it, and
+[`archiving-agent-config.md`](archiving-agent-config.md) names the same
+exemption from the archiving procedure's side.
+
+An edit that sharpens this rule is welcome. The file stays.
+
+## Excerpt for repository-instruction sessions
+
+Codex reads its repository `AGENTS.md`; this excerpt supplies the standalone
+contract.
+
+```
+Correction handling for this run, from rules/correction-lens.md.
+
+Every correction the user gives becomes a control. Run it through five layers
+and land it at the highest one that can hold it:
+
+1. Codebase. The mistake is impossible by how the code is written: a type, a
+   signature, a data structure, an API shape.
+2. Static analysis. A program reads the tree and decides: a lint rule, an
+   enforcer check, a paired test, a CI gate.
+3. Review tooling. A reviewer or a review bot reads the criterion: a code-rules
+   row, a BUGBOT pointer, a Graphite rule.
+4. Skill. An agent follows a procedure.
+5. Style guide. Word choice and prose shape.
+
+Close the correction with three sentences: the layer chosen, why each higher
+layer cannot hold the lesson, and the change opened at that layer in this run.
+Effort rules out no layer; a missing capability does, and you name which one.
+
+The same correction arriving twice means the layer was too low. Move it up one
+layer and say so.
+
+Land the control in the shared environment package, so every session carries
+it. A memory file records the decision and encodes nothing.
+```
+
+## Sibling rules
+
+| Rule | Role |
+|---|---|
+| [`flag-non-breaking-findings.md`](flag-non-breaking-findings.md) | A gate blocks on a breaking finding and records a smell |
+| [`code-standards.md`](code-standards.md) | The layer map of contract, pointer, enforcer, lint, session rules |
+| [`archiving-agent-config.md`](archiving-agent-config.md) | How a rule leaves service, and which files are exempt |
+| [`falsify-before-green.md`](falsify-before-green.md) | A new layer-2 check counts once it has run red on a named break |

package/rules/flag-non-breaking-findings.md

@@ -97,6 +97,17 @@ loading, so the gate fails. A non-canonical filename and a Git mode other than
 `SEVERITY_BY_RULE_ID` in that module is the whole declaration. Add a check,
 add its row.
 
+`scripts/repository_policy.py` splits the committed-tree checks the same way.
+`SEVERITY_BY_CHECK_ID` in `repository_checks/config/constants.py` carries one
+row per check id, and a check id with no row reads as breaking. The
+`package-inventory` check is the one smell there. A production file whose
+package inventory omits its row still imports and still runs, so the check
+prints its finding with an `advisory:` prefix, records it in the ledger, and
+leaves the tree passing. Every other committed-tree check blocks: a `CLAUDE.md`
+naming a file that does not exist, an env-var row naming a file that never
+reads the variable, a test outside the testpaths allowlist, and a tracked
+secret.
+
 ## Sibling rules
 
 | Rule | Role |

package/rules/no-contrast-framing.md

@@ -0,0 +1,68 @@
+# No Contrast Framing
+
+**When this applies:** Every sentence a person reads. A chat reply, a commit
+message, a pull request title or body, a review comment, an issue, a rule file,
+a document, a plan, a memory file.
+
+## Rule
+
+State what is true. Leave the rejected reading out.
+
+A contrast defines its subject against something the writer already decided
+against, so the reader carries two readings where one would do, and the second
+one is the writer's own discarded draft. The sentence says more and shows less.
+
+Six forms carry the whole ban. Each row names the form the check reports.
+
+| Form | Shape | Write this |
+|---|---|---|
+| `trailing-comma-not` | `a diff regression, not shared infrastructure` | `a diff regression` |
+| `corrective-it-is-not` | `it is not a flake, it is a bug` | `a bug`, then the evidence that shows it |
+| `substitution-rather-than` | `park it rather than fix it` | `park it` |
+| `additive-not-just` | `not just for today` | the point the sentence was building toward |
+| `comparative-ranking` | `being precise matters more than trying to cover them` | `be precise about these three` |
+| `substitution-as-opposed-to` | `a warning as opposed to a failure` | `a warning` |
+
+A comparison of quantities stays. "The function runs more than 30 lines" counts
+lines. The ban covers the comparison that ranks one course of action over
+another the writer is turning down.
+
+Three shapes stay quiet by design. A backticked span or a fenced block carries
+an example, so the check blanks it first. A line opening with `>` quotes
+someone else, whose words are theirs to write. A `, not` clause reports only
+when no bare `not` already sits earlier in the line, so a list of clauses
+reports its first `, not` and stays quiet on the rest, as in
+`a diff regression, not shared code, not a workaround`. A list whose own
+opening word is a bare `not`, as in "not in chat, not in a commit message, not
+in a body", keeps even its first `, not` quiet. A release automation body
+passes the post linter untouched, since the bot builds it from commit
+subjects and reads it back as machine input.
+
+When the sentence thins after the contrast comes out, the missing piece is
+evidence. Name it: the failing check, the log line, the measured number, the
+file and the line.
+
+## Where it is enforced
+
+| Surface | What runs |
+|---|---|
+| Authored Markdown in the repository | The staged policy lint's `contrast-framing` rule, on every changed file, graded against the file's prior text |
+| A pull request or issue title and body, and a comment | `scripts/durable_post_lint.py`, which every post passes through before it reaches GitHub |
+| A chat reply | The writer, reading the sentence back before sending |
+
+The pattern list lives in
+`scripts/dev_env_scripts_constants/contrast_framing_constants.py`, and both
+lints read that one list. A synchronization test requires a row in the table
+above for every form the list carries.
+
+A chat reply reaches no check, so the same list is what the writer reads the
+sentence against: a comma followed by `not`, a `rather than`, a `not just`, a
+ranking of one thing over another.
+
+## Sibling rules
+
+| Rule | Role |
+|---|---|
+| [`asd-ste100-language.md`](asd-ste100-language.md) | Plain word choice, sentence style, and tone |
+| [`correction-lens.md`](correction-lens.md) | Every correction becomes a control at the highest layer that can hold it |
+| [`research-mode.md`](research-mode.md) | A claim carries its source |

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

@@ -0,0 +1,44 @@
+# 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 and on every review event, 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 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.
+
+## 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, and on a review comment. Each run reports on the pull request's head commit, so a finding posted after the last push still turns the check red.
+
+`Echo-Visuals-Inc/python-automation` runs the same command from its own workflow, against the revision of this package that its workflow pins.
+
+## 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) | Draft first, 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 |

package/scripts/Invoke-PesterSuites.ps1

@@ -0,0 +1,42 @@
+#!/usr/bin/env pwsh
+<#
+.SYNOPSIS
+    Run every Pester suite under a tests directory and exit on its verdict.
+
+.DESCRIPTION
+    check.ps1 calls this script as a child process so Invoke-Tool reads a
+    process exit code the way it does for ruff, mypy and pytest. Pester is a
+    cmdlet and leaves $LASTEXITCODE alone, so running it in-process would
+    report every suite as passing.
+
+    A missing Pester module exits non-zero. A gate that cannot run its check
+    has not passed it, and a skip here would leave the suites reporting
+    nothing while the tree reads as covered.
+
+.PARAMETER TestsRoot
+    Directory holding the *.Tests.ps1 suites.
+
+.OUTPUTS
+    Pester's own detailed output. Exit code 0 when every suite passes.
+#>
+[CmdletBinding()]
+param(
+    [Parameter(Mandatory = $true)]
+    [string]$TestsRoot
+)
+
+$ErrorActionPreference = 'Stop'
+
+if (-not (Get-Module -ListAvailable -Name Pester)) {
+    Write-Error "Pester is not installed, so the suites under $TestsRoot cannot run."
+    exit 1
+}
+
+Import-Module Pester -MinimumVersion 5.0
+
+$suiteConfiguration = New-PesterConfiguration
+$suiteConfiguration.Run.Path = $TestsRoot
+$suiteConfiguration.Run.Exit = $true
+$suiteConfiguration.Output.Verbosity = 'Detailed'
+
+Invoke-Pester -Configuration $suiteConfiguration