@jjanczur/tyran 0.1.14 → 0.1.17

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.
@@ -11,7 +11,7 @@
11
11
  {
12
12
  "name": "tyran",
13
13
  "description": "A task conductor for Claude Code: multi-agent orchestration with an enforced evidence contract, repo-specific learning, and update-safe local evolution.",
14
- "version": "0.1.14",
14
+ "version": "0.1.17",
15
15
  "source": "./",
16
16
  "author": {
17
17
  "name": "Jacek Janczura",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "tyran",
3
- "version": "0.1.14",
3
+ "version": "0.1.17",
4
4
  "description": "A task conductor for Claude Code: multi-agent orchestration with an enforced evidence contract, repo-specific learning, and update-safe local evolution.",
5
5
  "author": {
6
6
  "name": "Jacek Janczura",
package/CHANGELOG.md CHANGED
@@ -1,5 +1,143 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.1.17 — 2026-08-14
4
+
5
+ ### A race test that picked a winner
6
+
7
+ `two apply runs at once cannot both close one ask` accepted only two of the
8
+ three exits its own race can produce. On a runner slow enough to serialise
9
+ the two spawns, the first closes the queue and the second finds it empty and
10
+ exits 1 — correct behaviour, asserted as a failure. It passed locally and in
11
+ the PR checks and failed in the publish job, which is where a timing
12
+ assumption usually surfaces, and it kept 0.1.15 and 0.1.16 off npm although
13
+ both are merged and tagged.
14
+
15
+ All three exits are now accepted, and the guarantee is asserted where it
16
+ holds regardless of who won: no ask closed twice and no question closed by
17
+ two gates, checked while the racing runs are the only writers, then
18
+ completeness after one sequential settling run. Dropping the sitting lock
19
+ still fails the test.
20
+
21
+ ## 0.1.16 — 2026-08-14
22
+
23
+ ### `cat hooks/…` was refused while `Read` handed you the same bytes
24
+
25
+ Measured on the shipped 0.1.15 gate, on one file under `hooks/**`: `Read` passes,
26
+ and `cat`, `grep -n`, `wc -l` and `node --check` on that same file all **deny**.
27
+ The bytes were one tool call away in every case, so the refusal protected
28
+ nothing — and it was not consistent with itself either: `git log --oneline --
29
+ hooks/` passed all along, because a bare directory token names no file to
30
+ classify, while `wc -l` on a file inside it did not. The cost was four
31
+ interrupted tool calls in one session for the author, every one of them while
32
+ reading the gate being worked on.
33
+
34
+ The rule this release encodes instead: **the shell must not become a second
35
+ route to something the `Read` tool already refuses.** For `.env` that symmetry
36
+ is load-bearing and is untouched — `Read` denies *and* `grep` denies, because
37
+ the measured incident behind that rule is a refused `Read .env` followed by
38
+ `Bash: grep` in the very next tool call. Where `Read` is allowed, refusing the
39
+ shell buys nothing.
40
+
41
+ So on `hooks/**` and `.tyran/policies/**` — and only there — a read-only shell
42
+ command now passes. "Read-only" is matched on the **program and its flags**,
43
+ never on the program alone, because read-shaped programs have write-shaped
44
+ modes: `node --check FILE` passes and `node FILE` denies; `git log` passes and
45
+ `git log --output=FILE` denies, which was a real hole found in an earlier review
46
+ of this gate; `tail -n 5` passes and `tail -f` does not. An unrecognised flag
47
+ refuses, so the enumeration's incompleteness costs a false refusal and never a
48
+ pass. `sed` and `awk` are not on the list at all: their script argument is a
49
+ program with its own write commands, and reading it would need a second parser.
50
+ The raw command may contain none of ``< > $ ` ( ) { } &``, which is every
51
+ redirection spelling, command substitution, subshell and `&&` at once — checked
52
+ on the raw text, because the shared lexer *consumes* those characters as
53
+ separators and by the time a token exists the `>` is gone. `|` and `;` are fine,
54
+ since each composed segment still has to be an allowed reader.
55
+
56
+ What did not change: every credential shape denies for reads and writes alike;
57
+ `.claude/settings.json` and `.claude/settings.local.json` stay refused from a
58
+ shell in every mode, which is a deliberate narrowing rather than a consequence —
59
+ `Read` passes on the registry too, so the principle alone would have admitted it,
60
+ and it is the one file from which every gate is switched off at once. One line
61
+ naming a readable path *and* a secret is still refused for the secret.
62
+
63
+ That last sentence needed a second check to stay true, and review found it out.
64
+ The exemption was decided on the **finding list**, which is computed from a
65
+ *stripped* copy of the command: `stripMessageArguments` removes a message-bearing
66
+ flag together with its argument, and non-literal tokens are dropped after that.
67
+ `-t` is `git commit --template` *and* a legal flag of `diff` and `cat`, so
68
+ `diff -t .env hooks/scripts/policy-gate.mjs` left a finding list naming only the
69
+ readable path, read as "read-only command on a readable path", and was exempted —
70
+ really publishing the file. Four shapes were measured deny-on-0.1.15 →
71
+ pass-before-the-fix: `diff -t SECRET FILE`, `grep --file=SECRET FILE`,
72
+ `grep -m SECRET FILE`, and `diff ~/SECRET FILE`, the last because a leading `~`
73
+ makes the token non-literal and it is dropped entirely. The exemption is now
74
+ refused when any word of the **raw** command is credential-shaped, tested with
75
+ the same `SECRET_READ_RULES` the findings use, and the refusal names that word
76
+ rather than offering a rewrite that cannot help. This is the invariant being
77
+ repaired, not a new capability: `diff -t .env src/app.js` publishes the same
78
+ bytes and always did, because it names no protected path at all. One false
79
+ refusal comes with it, in the safe direction — `git log --grep=.env -- FILE`
80
+ loses the exemption over a word in a search pattern.
81
+
82
+ The residual floor is stated in the refusal text and in `docs/policy-gate.md`
83
+ rather than implied: matching flags bounds what a command *says*, not what the
84
+ program *does*. An allowed reader can still be pointed at another program by
85
+ configuration this gate never reads — a `diff.external` driver or a pager in git
86
+ config, a `NODE_OPTIONS` carrying `--require`, a shell function shadowing `cat`.
87
+ That is the fifth entry in `SHELL_DECLARED_MISSES`. The sixth is one step
88
+ earlier: the program table is keyed on the **basename**, which is what makes
89
+ `/bin/cat` and `cat` one entry and also makes a repo-writable `src/cat` an
90
+ allowed reader. It is declared rather than closed, because closing it would
91
+ close nothing — a script with the path already inside it needs no allowed name
92
+ at all, which is the third entry.
93
+
94
+ ## 0.1.15 — 2026-08-14
95
+
96
+ ### Fifteen questions, ten minutes, and the swarm moves
97
+
98
+ An agent that hits a product decision no longer stops and waits for you. It
99
+ raises the question — `journal.mjs ask`, one command, which mints the id under
100
+ the journal's write lock so two agents asking at the same moment get two
101
+ questions rather than one — states what it recommends and what should ship if
102
+ nobody ever answers, and takes the next ticket. The question is a `gate` whose
103
+ `kind` IS its id, `Q-<n>`: the closed event set stays at 17, the board's
104
+ waiting-on-you queue already rendered it, and `answered` was already a pass
105
+ result. What was missing was an identity and a way in.
106
+
107
+ The way in is a text file. `tyran answer render` writes `.tyran/state/ANSWERS.md`
108
+ — every open question across every initiative, the ones with no recorded default
109
+ first, because those are the only ones where saying nothing has no safe outcome.
110
+ You type under `answer:`. **Blank accepts the recorded default**, verbatim, and
111
+ still records it as a decision; `-` leaves it for next time; anything else is your
112
+ answer in your own words. `tyran answer apply` folds them back as `decision` +
113
+ `gate result: answered` pairs — decision first, so a crash leaves a visible orphan
114
+ decision rather than a closed question whose answer was never written down — then
115
+ re-renders every projection and the board. It reads the question, the default and
116
+ the ticket back out of the journal, never out of the sheet, and it is
117
+ all-or-nothing: one unparseable block and nothing at all is appended, with the
118
+ line number.
119
+
120
+ Answering a question no longer needs the conductor to be awake. `SessionStart`
121
+ records the session id in `.tyran/state/conductor.json`, so `apply --resume` can
122
+ put the swarm back on it — and refuses while that session is still alive, because
123
+ two conductors on one journal is a hazard this repo has already paid for once.
124
+
125
+ One correction found while building it. Parking an asked ticket **hid** it: the
126
+ board checks a `ticket.status` override before the ask, so our own demo fixture
127
+ showed `waiting-operator (0)` with a question open — the fixture is corrected and
128
+ the skill now forbids the override.
129
+
130
+ Also: `question`, `recommendation`, `default` and `answer` are capped at 2000
131
+ codepoints (rejected, never truncated — historical oversizes stay warnings);
132
+ `STATE.md`'s open-gates table and the SessionStart probe now carry the question
133
+ text, so a resumed conductor sees *what* it asked and not merely that it is
134
+ waiting; doctor gains `ask-open` (info) and `ask-stale` (warning, 72 h); the gate
135
+ pass set has one spelling again, exported from `project.mjs` and imported by
136
+ `overnight.mjs` instead of hand-copied; `tiers` gains an advisory `conductor`
137
+ role with a `deep` floor, so the coordinator's model is named in the one file
138
+ where model names may live — and says on stderr that no plugin can change your
139
+ own session's model.
140
+
3
141
  ## 0.1.14 — 2026-08-14
4
142
 
5
143
  ### The repository remembers what went wrong — and eventually writes it into law
package/README.md CHANGED
@@ -359,13 +359,14 @@ Published on npm as [`@jjanczur/tyran`](https://www.npmjs.com/package/@jjanczur/
359
359
  command stays `tyran` either way; only the registry name is scoped, the same
360
360
  pattern as `@angular/cli` giving you `ng`. `bin/tyran.mjs` exposes the same
361
361
  scripts the plugin's hooks and skills already call — `doctor`, `scan-repo`,
362
- `tiers`, `journal`, `schema`, `knowledge`, `board`, `overnight`, `statusline`, `stop-check`,
362
+ `tiers`, `journal`, `schema`, `knowledge`, `board`, `answer`, `overnight`, `statusline`, `stop-check`,
363
363
  `scan-control-chars`, `desc-budget` — for a shell or a CI job with no Claude
364
364
  Code session. Zero dependencies; `--help` lists them.
365
365
 
366
366
  ```bash
367
367
  npx @jjanczur/tyran doctor --hooks # is any gate installed but unable to fire?
368
368
  npx @jjanczur/tyran scan-repo --dir . # what this repo looks like, with provenance
369
+ npx @jjanczur/tyran answer render # the sheet of questions waiting on you
369
370
  ```
370
371
 
371
372
  Exit codes propagate to the digit, so a CI step reddens exactly when the
@@ -48,9 +48,21 @@ commits and anything written to disk are in English.**
48
48
  the prediction written down first, and name the mechanism. A fix for a
49
49
  failure you never reproduced cannot be shown to have worked.
50
50
  - When the PR comes back with comments, follow `pr-feedback`.
51
- 3. **Decide technical questions yourself.** Stop only for product or visual
52
- decisions, or when something would cross a boundary the handoff named —
53
- then stop and ask the conductor. "Shall I continue?" is forbidden.
51
+ 3. **Decide technical questions yourself.** "Shall I continue?" is forbidden.
52
+ A product or visual decision, or one that would cross a boundary the handoff
53
+ named, is not yours to make — and it is also not a reason to sit still.
54
+ Raise it as an operator ask, in one command, against the MAIN checkout's
55
+ journal (the handoff carries its absolute path):
56
+ `node ${CLAUDE_PLUGIN_ROOT}/scripts/journal.mjs ask <abs-journal> <init>
57
+ --actor <you> --ticket <your ticket> --question '...' --recommendation '...'
58
+ --default '...'`. State both: what you would do, and what should ship if
59
+ nobody ever answers. Then **carry on under your own default** if the story
60
+ can proceed, or report and end if it cannot. The `Q-<n>` the command prints
61
+ goes in your report. Do **not** set `ticket.status` — the ask already moves
62
+ your ticket into the board's waiting-operator lane, and an override on top
63
+ of it hides the question. Ask the **conductor**, not the operator, for a
64
+ technical unblock: a lease, a corrected premise, a scope call inside the
65
+ handoff.
54
66
  4. **Shared zones are append-only**, per the manifest. `git add` takes an
55
67
  explicit list of paths — never `-A`, never `.`; they sweep in files
56
68
  belonging to other windows, and that has already put blobs on a remote
@@ -59,6 +59,13 @@ that keeps you.
59
59
  review.
60
60
  - When you find nothing, say so plainly. Manufacturing findings to look
61
61
  thorough wastes a round and trains the conductor to discount you.
62
+ - A blocker that is really a **product or visual decision** is not a review
63
+ verdict. Raise it as an operator ask —
64
+ `node ${CLAUDE_PLUGIN_ROOT}/scripts/journal.mjs ask <abs-journal> <init>
65
+ --actor <you> --ticket <the ticket> --question '...' --recommendation
66
+ '...' --default '...'` — name the `Q-<n>` in your review, and give a
67
+ verdict on everything else. Holding a whole review open on one question
68
+ the operator has not seen is how a queue becomes a stall.
62
69
  5. **Say what you did NOT check.** Platform you did not run on, concurrency
63
70
  you did not exercise, the input class you skipped. This section is a merge
64
71
  gate, not a courtesy: the conductor resolves every item as measured,
package/bin/tyran.mjs CHANGED
@@ -88,6 +88,10 @@ export const COMMANDS = {
88
88
  'board.mjs',
89
89
  'Render the cross-initiative kanban board — BOARD.md, board.json and the board.html dashboard — from the journals under .tyran/state/.',
90
90
  ],
91
+ answer: [
92
+ 'answer.mjs',
93
+ 'Write the sheet of questions waiting on you, then fold your answers back into the journal.',
94
+ ],
91
95
  'stop-check': [
92
96
  'stop-check.mjs',
93
97
  'Check the .tyran/STOP operator brake that halts a running initiative before its next spawn or merge.',