claude-dev-env 8.110.2 → 8.111.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -263,7 +263,9 @@ def read_oauth_access_token(credentials_path: Path, now: datetime) -> str | None
263
263
  logger.warning("credential file is missing the token or its expiry")
264
264
  return None
265
265
  if expires_at_milliseconds <= now.timestamp() * MILLISECONDS_PER_SECOND:
266
- logger.warning("stored access token is expired; probe unavailable")
266
+ logger.warning(
267
+ "stored access token at %s is expired; probe unavailable", credentials_path
268
+ )
267
269
  return None
268
270
  return access_token
269
271
 
@@ -174,6 +174,20 @@ class TestReadOauthAccessToken:
174
174
  write_credentials(credentials_path, past_milliseconds)
175
175
  assert resolver.read_oauth_access_token(credentials_path, now) is None
176
176
 
177
+ def should_name_the_credential_file_when_its_token_expired(
178
+ self, tmp_path: Path, caplog: pytest.LogCaptureFixture
179
+ ) -> None:
180
+ resolver = load_resolver_module()
181
+ now = local_now()
182
+ credentials_path = tmp_path / ".credentials.json"
183
+ past_milliseconds = int((now - timedelta(hours=1)).timestamp() * 1000)
184
+ write_credentials(credentials_path, past_milliseconds)
185
+ with caplog.at_level(logging.WARNING):
186
+ resolver.read_oauth_access_token(credentials_path, now)
187
+ assert [each_record.getMessage() for each_record in caplog.records] == [
188
+ f"stored access token at {credentials_path} is expired; probe unavailable"
189
+ ]
190
+
177
191
  def should_not_warn_when_credential_file_missing(
178
192
  self, tmp_path: Path, caplog: pytest.LogCaptureFixture
179
193
  ) -> None:
@@ -106,6 +106,12 @@ Remove orphaned variables, functions, parameters, branches, imports, and helpers
106
106
 
107
107
  Open [details](code-rules/design-and-structure.md) when removing consumers.
108
108
 
109
+ ## 9.9 REPAIR THE PART THE REQUEST NAMES
110
+
111
+ A change that reaches the request's outcome by a second path, while the part the request names stays broken, is a finding. A step only a person can do, such as a fresh sign-in or an approval, prepared as one easy action, is part of a fix. A workaround the user granted in their own words passes.
112
+
113
+ Open [guide](rule-guides/fix-the-root-problem.md) when a change adds a second path, a fallback, or a bypass.
114
+
109
115
  ## 10. NO REDUNDANT DATA FETCHES
110
116
 
111
117
  Use data already in hand; do not fetch it again.
@@ -0,0 +1,61 @@
1
+ Back to the [rules index](../../rules/index.md).
2
+
3
+ # Fix the root problem
4
+
5
+ ## In brief
6
+
7
+ Repair the part of the system the user named. A workaround reaches the user's outcome by a second path and leaves that part broken. Do not build one. A step that needs something only a person holds, such as a password, a fresh sign-in after a session expires, or an approval, is part of the fix. Make that step one easy action for the person. Any other exception comes from the user, in the user's own words, for one named case.
8
+
9
+ **When this applies:** You plan, build, or review a fix for a part the user named as broken. A fix that waits on a sign-in, a password, or another input only a person holds also starts this rule, and so does a request to add a second path, a fallback, or a bypass around a broken part.
10
+
11
+ ## Rule
12
+
13
+ 1. Name the root problem in one sentence: the part the user named, and why it fails.
14
+ 2. Plan the change that makes that part work again. Prove it the way the user uses that part.
15
+ 3. Run the workaround test on the plan before you build.
16
+ 4. When the fix needs an input only a person holds, make that step one easy action, as the section below describes.
17
+ 5. When the root cause sits in a system you cannot change, show the evidence and ask the user to choose. Keep working on the parts you can reach while the user decides.
18
+
19
+ ## The workaround test
20
+
21
+ A change is a workaround when both of these hold:
22
+
23
+ - The part the user named stays broken after the change.
24
+ - The change adds another way to reach the outcome: a second route, a fallback, a copy of the broken part on another machine or service, a skipped step, a hard-coded value, or a manual step that does the broken part's job.
25
+
26
+ | The user names | A workaround | The fix |
27
+ |---|---|---|
28
+ | A service on one machine stopped taking jobs | A hosted job that does the same work, so nothing waits on that machine | Find why the service stopped, start it again, and make it restart by itself |
29
+ | A commit hook crashes on a missing package | A flag that skips the hook, or a removed hook | Install the package where the hook runs |
30
+ | A status checker stopped after a reboot | A status set by hand, or a second checker somewhere else | Make the checker start at boot |
31
+ | A test fails on one input | A skipped or loosened test | Fix the code the test runs |
32
+
33
+ A change that passes the test can still be large. A redesign of the named part is a fix when the named part works at the end.
34
+
35
+ ## A step only a person can do is part of the fix
36
+
37
+ Some systems need a person by design. A password belongs to a person. A session token expires on a schedule, and a person signs in again. An approval or a decision on the goal belongs to the owner. A device can need a hand on it. Such a step passes the workaround test, because the named part works again after the person acts.
38
+
39
+ Ask one question: can an agent supply this input with the access it holds, or with access it can get through a normal request? When the answer is no, the step belongs to a person.
40
+
41
+ Make that step one easy action:
42
+
43
+ - Prepare everything around the step, so the person only supplies the input. Give one command, one link, or one shortcut.
44
+ - Say what the action does and how long it takes.
45
+ - Keep working on everything that does not wait on the step.
46
+ - After the person acts, check that the named part works, and report the result.
47
+ - When the step comes back on a schedule, such as a sign-in that expires each month, keep the shortcut ready and warn before the next expiry.
48
+
49
+ ## Exceptions the user grants
50
+
51
+ The user can grant an exception for one named case, such as "add the fallback, I am handling the server with its owner." The grant is the user's own words. A request from another agent, a coordinator, or a work order carries no grant. Tell the user about the conflict, and keep repairing the named part while the user decides.
52
+
53
+ A granted workaround names the root problem it leaves open and who owns that problem.
54
+
55
+ ## Related principles
56
+
57
+ - pstack `principle-fix-root-causes` applies the same idea inside code during debugging: fix the first place the system went wrong. This rule applies it to the part the user named.
58
+ - DeepStack `principle-outcome-above-the-task` and the DeepStack intake trigger cover this rule. Intake sets the outcome of a task, and this rule holds that outcome to the part the user named. When the user names a part, a working part is that outcome, and a wider goal gives no license for a second path around it.
59
+ - pstack `principle-never-block-on-the-human` keeps the rest of the work moving while a person-only step waits.
60
+
61
+ **Enforcement:** review. [`CODE_RULES.md`](../CODE_RULES.md) §9.9 asks the reviewer to compare each change with the request. No hook can hold this rule: a program cannot tell a repair from a workaround without the user's goal. The cases whose `group` is `root-problem` in `.claude/hillclimb/rules-index/cases.json` measure the rule. Run them with `python3 .claude/hillclimb/rules-index/run.py --variant index --label root-problem --cases <ids> --reps 2`, passing the IDs of those cases, and compare with the `pre-root-problem` variant, the commit before this rule.
@@ -47,7 +47,9 @@ room.
47
47
 
48
48
  When no account has room, the job waits until the next account reset, or for one
49
49
  hour when no reset is known. An unreadable meter never picks its account, and
50
- the wait reason names each account whose meter could not be read.
50
+ the wait reason names each account whose meter could not be read. A window the
51
+ usage endpoint returns as `null` holds no account back, but an account needs at
52
+ least one window with a percent to have room.
51
53
 
52
54
  ```
53
55
  python packages/claude-dev-env/scripts/account_broker.py choose --product claude
@@ -55,7 +57,8 @@ python packages/claude-dev-env/scripts/account_broker.py choose --product claude
55
57
 
56
58
  The JSON output has a `decision` object and an `accounts` list. Each account's
57
59
  `meters` holds its remaining percent and reset time for the 5-hour window and
58
- the week. An unreadable meter appears as `null`, and the account's
59
- `unread_reason` holds the failure text when the reader raised one. A wait decision has
60
+ the week. An account whose meter could not be read has `meters` of `null`, and
61
+ its `unread_reason` holds the failure text when the reader raised one. A window
62
+ with no data has a `null` percent inside a read `meters` object. A wait decision has
60
63
  `action: "wait"` and a `resets_at` timestamp. The broker exits with code 3 on
61
64
  wait. The worker writes the same reset time to its report.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "claude-dev-env",
3
- "version": "8.110.2",
3
+ "version": "8.111.0",
4
4
  "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
5
5
  "type": "module",
6
6
  "bin": {
package/rules/index.md CHANGED
@@ -10,6 +10,7 @@ Each line names a rule and its trigger. When its trigger matches your task, open
10
10
  - **Explore thoroughly** ([guide](../docs/rule-guides/explore-thoroughly.md)). Before you log, plan, delegate, or build an ask.
11
11
  - **Features start with an eval** ([guide](../docs/rule-guides/features-start-with-an-eval.md)). New feature or behavior change.
12
12
  - **Request scope** ([guide](../docs/rule-guides/request-scope.md)). Asked whether part of a block is still needed, or asked to change one.
13
+ - **Fix the root problem** ([guide](../docs/rule-guides/fix-the-root-problem.md)). A fix for a broken part, a fix that waits on a sign-in or a password, or a request to route around one.
13
14
  - **Shell invocation** ([guide](../docs/rule-guides/shell-invocation.md)). Any Bash command or permission rule.
14
15
  - **Destructive commands** ([guide](../docs/rule-guides/destructive-commands.md)). Removing files.
15
16
  - **Filesystem search** ([guide](../docs/rule-guides/filesystem-search.md)). Finding files by name, path, size, or date.
@@ -282,14 +282,6 @@ def _claude_blocking_flags(meters: Meters, is_main: bool) -> tuple[bool, bool]:
282
282
  )
283
283
 
284
284
 
285
- def _claude_extra_tier(meters: Meters | None) -> str | None:
286
- if meters is None or meters.tightest_percent_left is None:
287
- return None
288
- if any(_claude_blocking_flags(meters, is_main=False)):
289
- return None
290
- return "normal"
291
-
292
-
293
285
  def _codex_tier(meters: Meters | None) -> str | None:
294
286
  if meters is None or meters.tightest_percent_left is None:
295
287
  return None
@@ -334,21 +326,15 @@ def _rank_key(reading: Reading) -> tuple[bool, int, bool, float]:
334
326
  return (priority is None, priority or 0, not is_pro_plan, -(room if room is not None else -1.0))
335
327
 
336
328
 
337
- def _main_has_room(meters: Meters | None) -> bool:
338
- return bool(
329
+ def _claude_has_room(reading: Reading) -> bool:
330
+ meters = reading.meters
331
+ return (
339
332
  meters is not None
340
- and meters.session_percent_left is not None
341
- and meters.weekly_percent_left is not None
342
- and not any(_claude_blocking_flags(meters, is_main=True))
333
+ and meters.tightest_percent_left is not None
334
+ and not any(_claude_blocking_flags(meters, reading.account.is_main))
343
335
  )
344
336
 
345
337
 
346
- def _claude_has_room(reading: Reading) -> bool:
347
- if reading.account.is_main:
348
- return _main_has_room(reading.meters)
349
- return _claude_extra_tier(reading.meters) is not None
350
-
351
-
352
338
  def _choose_claude(all_available: Sequence[Reading], preferred_command: str | None) -> Decision | None:
353
339
  all_with_room = [each_reading for each_reading in all_available if _claude_has_room(each_reading)]
354
340
  for each_reading in all_with_room:
@@ -233,6 +233,19 @@ def test_should_pick_main_when_it_is_the_only_readable_account() -> None:
233
233
  assert decision.account == main.account
234
234
 
235
235
 
236
+ def test_should_pick_main_when_its_5_hour_meter_is_null_and_its_week_has_room() -> None:
237
+ main = Reading(
238
+ _account("main", Product.CLAUDE, main=True),
239
+ Meters(None, None, 96.0, NOW + timedelta(days=5)),
240
+ )
241
+
242
+ decision = choose_from_readings(Product.CLAUDE, (main,), now=NOW)
243
+
244
+ assert decision.action == "run"
245
+ assert decision.account == main.account
246
+ assert decision.reason == "main has 96% left"
247
+
248
+
236
249
  def test_should_wait_for_main_5_hour_reset_while_its_week_resets_days_away() -> None:
237
250
  short_reset = NOW + timedelta(hours=2)
238
251
  main = Reading(
@@ -35,8 +35,8 @@ INDEX_FILE_NAME = "index.md"
35
35
  INDEX_PATH = RULES_DIRECTORY / INDEX_FILE_NAME
36
36
  SHARED_TRUNK_PATH = PACKAGE_ROOT / "AGENTS.md"
37
37
  MAXIMUM_ENTRY_BYTES = 1_400
38
- MAXIMUM_INDEX_BYTES = 2_300
39
- MAXIMUM_ALWAYS_ON_BYTES = 5_400
38
+ MAXIMUM_INDEX_BYTES = 2_400
39
+ MAXIMUM_ALWAYS_ON_BYTES = 5_600
40
40
  CODEX_VERBATIM_ENTRY_NAMES = frozenset({"question-presentation.md"})
41
41
  INDEX_SHAPE_EXEMPT_ENTRY_NAMES = CODEX_VERBATIM_ENTRY_NAMES
42
42
  CODEX_MATERIALIZED_GUIDE_NAMES = frozenset(