@jjanczur/tyran 0.1.44 → 0.1.46

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.
@@ -1,5 +1,5 @@
1
1
  ---
2
- description: The depth half of a review - the dimensions a diff is read against (correctness, boundaries, concurrency, failure paths, secrets, test quality) and the rule that a finding is refuted before it is reported. The verdict stays with the reviewer agent. Use when reviewing a diff or a pull request.
2
+ description: The depth half of a review - the dimensions a diff is read against (correctness, boundaries, concurrency, failure paths, secrets, data access, structure, test quality) and the rule that a finding is refuted before it is reported. The verdict stays with the reviewer agent. Use when reviewing a diff or a pull request, or when asked about N+1 queries or wasted round trips.
3
3
  ---
4
4
 
5
5
  # Code review — reading depth
@@ -57,6 +57,34 @@ gap nobody notices.
57
57
  through the real producer, not a stand-in for its output.
58
58
  - **Resource lifecycle.** What is opened, started, spawned or leased, and where
59
59
  it is closed — including on the path where an exception is thrown.
60
+ - **Data access and wasted work.** Count the round trips one request makes
61
+ and how the count moves with the rows. A query, fetch or RPC inside a loop
62
+ or an awaited per-item `map` is 1 + N; one query over the set (a join, an
63
+ `IN`, a loader) is the shape. Awaits with no data dependency between them
64
+ run together, fan-out bounded — unbounded over a pool or a rate limit, a
65
+ slow request becomes a failed one. The same pure computation over the same
66
+ inputs runs once per request. A cache comes AFTER those, never instead: a
67
+ cache over a query that should not have run is a defect with a warm cache,
68
+ and one the diff adds or touches must say what invalidates it and why the
69
+ TTL is that number — a TTL is the staleness the product agreed to, and a
70
+ number with no reason is the first stale read filed in advance. None of this
71
+ shows in the diff alone: a helper that runs one query is correct where it is
72
+ written and N+1 where a loop calls it, so follow the new call up to the
73
+ request that triggers it. Rank by the path — a query on every page load is
74
+ a finding, a nightly job over twelve rows is a `NOTES.md` line. The finding
75
+ is a count, "N+1 queries for N rows, expected 1": an input and an expected
76
+ result, so it pins as a test against the query log.
77
+ - **Structure.** A thousand-line file is built one reasonable addition at a
78
+ time, so the question is about THIS addition: does it give a module a second
79
+ reason to change, or grow the largest file in its area? A new concern is a
80
+ new module, and the simplest change that meets the criteria is the bar — a
81
+ layer, an option or a generic helper introduced for the one caller the story
82
+ has is the opposite failure, not the cure; `deslop` already names it as
83
+ slop. This finding is a location, not a counterexample: the file, the two
84
+ responsibilities it now carries, the seam between them. It is the story's
85
+ finding only when the story made the tangle; a giant the story merely
86
+ touched is a `NOTES.md` debt, and splitting it here is the work nobody asked
87
+ for.
60
88
  - **The gate itself.** If the change touches a check, ask what that check can
61
89
  no longer see. A loosened tolerance, a narrowed selector, a broadened
62
90
  try/catch and a skipped test all keep the run green while removing its
@@ -64,7 +64,10 @@ fixed, the deleted test is the reason.
64
64
 
65
65
  **Keep behaviour unchanged unless you are fixing a defect you can name.** If the
66
66
  pass uncovers a real bug, that is a finding for the report and usually a
67
- separate change, not something to quietly correct inside a cleanup.
67
+ separate change, not something to quietly correct inside a cleanup. The same
68
+ goes for a slow data path — a query in a loop, awaits that could run together:
69
+ that is `code-review`'s data-access dimension, its fix usually adds lines, and
70
+ it belongs in the self-review before this pass, not inside it.
68
71
 
69
72
  ## Skill-file mode
70
73
 
@@ -404,11 +404,17 @@ open one.
404
404
  re-litigated after every compaction; a question written as a bare `kind` of
405
405
  your own invention collides with the next one that shares it, and the older
406
406
  question is lost with nothing objecting anywhere.
407
- - **Always record a `default`** — what ships if nobody ever answers. It is
408
- what the operator accepts by leaving an answer blank, and it is the only
409
- reason a queue of fifteen questions takes ten minutes instead of an hour.
410
- An ask with no default is a question the operator must stop and think
411
- about; spend that budget deliberately.
407
+ - **Always record a `recommendation`** — what you would do. It becomes the
408
+ `default` when you name no other, so an ask that carries one is a
409
+ question with a safe outcome rather than a stop. An ask carrying NEITHER
410
+ is a question the operator must wake up and think about; spend that
411
+ budget deliberately, and expect it to hold its ticket until they do.
412
+ Record a separate `default` only when the safe answer differs from your
413
+ advice — "per-seat" recommended, "keep flat fee" if nobody rules.
414
+ - **`--blocking` is for the ones that must wake them.** Irreversible,
415
+ visible outside the repo, or spending money. It is the only thing that
416
+ survives `unattended.mode: on`, so use it exactly there and nowhere else:
417
+ a run whose every question is blocking is a run that stops.
412
418
  - **Do not park an asked ticket.** An ask that names a ticket already puts
413
419
  it in the board's `waiting-operator` lane. A `ticket.status` override on
414
420
  top of it **overrules** that lane and hides the question's own ticket —
@@ -421,6 +427,14 @@ open one.
421
427
  operator answers you in chat instead, append that pair yourself — same
422
428
  `kind`, `result: answered`, plus a `decision` whose text begins
423
429
  `Q-<n>: ` — and say in your next report that you did.
430
+ - **Under `unattended: mode: on`, sweep after you raise.** Run
431
+ `node ${CLAUDE_PLUGIN_ROOT}/scripts/answer.mjs auto --dir .tyran`, which
432
+ closes every ask that carries a recommendation and is not `--blocking`,
433
+ recording `answer_mode: unattended`. The operator went to sleep expecting
434
+ shipped work; a queue nobody read is a night spent parked. It is a SWEEP
435
+ rather than a rule you apply yourself — the same command runs on the
436
+ board's own timer, so an ask you raise and then die on still gets ruled.
437
+ Say in your report which questions were answered without them.
424
438
  **Check the brake before every spawn and every merge:**
425
439
  `node ${CLAUDE_PLUGIN_ROOT}/scripts/stop-check.mjs` — exit 1 means the
426
440
  operator created `.tyran/STOP`. Halt, report where you got to, and do not
@@ -72,10 +72,13 @@ boundaries:
72
72
  prompts: ask
73
73
 
74
74
  # Overnight mode — pause autonomous work near the subscription usage limits
75
- # and resume after the window resets (https://jjanczur.github.io/tyran/overnight/). Requires the
76
- # operator-installed statusline helper (scripts/statusline.mjs), which is the
77
- # only place the platform exposes usage telemetry; without it the gate is
78
- # silent and doctor says so.
75
+ # and resume after the window resets (https://jjanczur.github.io/tyran/overnight/).
76
+ # Telemetry is read from three places in order: the statusline helper if you
77
+ # installed one, the platform's usage cache in ~/.claude.json, and — when
78
+ # neither reports a percentage — the wall itself, read back out of the session
79
+ # transcript. The third only fires AFTER the limit is hit, so it cannot stop
80
+ # you early; what it restores is the clean wind-down and the scheduled resume.
81
+ # Doctor says so when none of the three can see anything.
79
82
  #
80
83
  # mode: off | warn | pause warn surfaces, never denies; pause winds down
81
84
  # wait_max_hours: 5 reset further away than this = a LONG pause:
@@ -96,6 +99,29 @@ limits:
96
99
  resume_margin_minutes: 5
97
100
  keep_awake: false # a real boolean, so the bare-off trap above cannot apply
98
101
 
102
+ # Unattended delivery — what an open question does when nobody is awake.
103
+ #
104
+ # With mode: on, an ask is answered by the agent's own recommendation the
105
+ # moment it is raised, and the run keeps going. That is the point of an
106
+ # overnight run: you went to sleep expecting shipped work, and a queue of
107
+ # questions nobody read is a night spent parked.
108
+ #
109
+ # Two refusals are mechanical, and they are what make this safe to switch on:
110
+ # an ask with no recommendation is a real question and stays open, and an ask
111
+ # raised with `--blocking` (the irreversible, the outward-facing, the ones that
112
+ # spend money) always waits for you. Everything taken automatically is
113
+ # journalled as `answer_mode: unattended` with its decision text prefixed
114
+ # `(auto-accepted overnight)`, so the morning is one scan of the ledger.
115
+ #
116
+ # `.tyran/STOP` still outranks all of it.
117
+ #
118
+ # mode: off | on bare on/off are fine here — both spellings work
119
+ # answer: recommendation what an ask resolves to: the agent's advice,
120
+ # | default or the conservative fallback it recorded
121
+ unattended:
122
+ mode: 'off'
123
+ answer: recommendation
124
+
99
125
  # The dashboard. Unlike everything above, this defaults ON: the board is where
100
126
  # a journal, a projection and a spend report become something a person can
101
127
  # read, and an install where nobody starts it is an install where none of that