@jjanczur/tyran 0.1.5 → 0.1.7

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.5",
14
+ "version": "0.1.7",
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.5",
3
+ "version": "0.1.7",
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,94 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.1.7 — 2026-08-07
4
+
5
+ ### The lease protocol nobody could follow
6
+
7
+ Iron rule 7 says a handoff BEGINS by taking a lease file — and the shipped
8
+ policy template had no rule for `.tyran/initiatives/<slug>/locks/`, so the
9
+ path fell to `default: GATED`, which denies every subagent unconditionally.
10
+ Measured twice in one adopted repo: implementers correctly refused to route
11
+ around the gate, and each occurrence cost a full dispatch round-trip before
12
+ the conductor took over lease-keeping by hand — exactly the relocation of
13
+ state into the lead's memory that the rule exists to prevent. The template now
14
+ carries a `locks/**` AUTO rule (gitignored, never history, blast radius one
15
+ stale file), a MATRIX test row pins it so a template edit cannot silently
16
+ reintroduce the gap, and the run skill names the journal-event fallback for
17
+ installs whose repo-local policy predates the rule.
18
+
19
+ ### GATED said "the prompt is the approval" — and then there was no prompt
20
+
21
+ Under `acceptEdits` — the mode agents actually run in — the main loop counts
22
+ as unsupervised, so a GATED write was denied with a message pointing at a main
23
+ session that refused the same way. The gate's docstring claimed the platform
24
+ offers only `deny` and silence; that claim is outdated. hook-io can now emit
25
+ the platform's third answer, an "ask", which renders the user's own permission
26
+ prompt even under `acceptEdits`, so GATED means what ADR-06 says wherever a
27
+ prompt can render. `bypassPermissions`, unknown modes, and every subagent
28
+ keep the hard deny: an ask a mode might not render must fail toward deny,
29
+ never toward approval.
30
+
31
+ ### Reviewers that never stop working, and ledger ids nothing can reference
32
+
33
+ A reviewer never files a `report` about itself — its verdict IS its
34
+ completion — so every reviewer spawned per iron rule 3 stayed in the "still
35
+ working" set until someone hand-ran `close-spawn` (measured: six-day-old
36
+ ghosts in a session-start probe). A `review` now closes its reviewer's
37
+ spawn, FIFO like a report, but only a spawn whose role is `reviewer`: the
38
+ review's `by` is a free string, and the first review round of this very
39
+ release proved a name collision could otherwise mark a working implementer as
40
+ reported with a verdict it never earned. `append` also issues a decision id
41
+ for an explicit `"id":""` now — a conductor recovering from `next-id`'s
42
+ usage error wrote three permanently blank ledger ids, with nothing objecting.
43
+
44
+ ### A gate that blocks reading its own subject
45
+
46
+ The hooks-path rule fired on ANY token containing the config key, so the
47
+ read-only query run mid-incident — to find out WHICH hook had just refused a
48
+ push — was itself refused. The same rule, one layer up, then refused the very
49
+ commit that fixed it, because the commit MESSAGE quoted the key. Only override
50
+ forms deny now, and the review of this release found and closed the bypass the
51
+ first narrowing opened: git stores a dash-prefixed value verbatim, so
52
+ `-evildir` was a value, not a flag. The code-review skill also gained the
53
+ "trace at least one test through the real producer" clause, paid for by a
54
+ three-state flag collapse that survived two full review rounds behind
55
+ hand-built fixtures.
56
+
57
+ ## 0.1.6 — 2026-08-06
58
+
59
+ ### A browser pass must follow the value to what got STORED
60
+
61
+ A column-mapping override shipped with a perfect `browser-check` measurement —
62
+ 15/15 columns visible, 0 console errors, the mapping visibly changed by hand —
63
+ and was completely inert. The server re-derived the source type from the
64
+ uploaded bytes, discarded the client's mapping, and answered `201` either way.
65
+ Nothing in the browser pass could have caught it, because it never inspected
66
+ what the server persisted; a reviewer reading the route did.
67
+
68
+ `browser-check` now says so: when the UI claims to change something the SERVER
69
+ acts on, a clean console and a `2xx` are not proof it arrived. Capture the
70
+ request body you actually sent, or read the value back with a second request or
71
+ a reload, and assert on THAT. The evidence contract already pinned the
72
+ execution MODE (dev server vs production build); it said nothing about
73
+ following a value past the response into storage.
74
+
75
+ ### A reviewer must never restore an uncommitted tree with git
76
+
77
+ Breaking the fix to watch its test fail is the right way to prove a guard is
78
+ real. The restore is the foot-gun: the work under review is UNCOMMITTED, so
79
+ `git checkout -- <file>`, `git restore` and `git stash` all revert to HEAD and
80
+ destroy the very thing the reviewer was sent to review. Measured in the field —
81
+ a reviewer did exactly this, caught it by re-diffing, and recovered only
82
+ because it had taken a backup first. Without the backup the author's work is
83
+ gone with no record of what was in it.
84
+
85
+ `agents/reviewer.md` now carries the procedure: copy to a scratch path, restore
86
+ from the copy, prove the restore with `diff`, then disclose the mutation in the
87
+ report. The agent already knew it had no edit tools "on purpose" and that
88
+ `Bash` can still write — what it lacked was the one sequence where its own
89
+ correct technique destroys the subject.
90
+
91
+
3
92
  ## 0.1.5 — 2026-08-03
4
93
 
5
94
  ### The plugin loads again (0.1.4 did not)
@@ -31,6 +31,16 @@ that keeps you.
31
31
  - Warm up routes before a batch run; a cold compile reads as a failure.
32
32
  - Take heavy slots only through the lease protocol, and clean up your
33
33
  processes afterwards (SIGTERM, not `kill -9`).
34
+ - **To prove a guard is real, break the fix — but never restore with git.**
35
+ Neutering the change to watch its test fail is the right technique. The
36
+ restore is where it goes wrong: the work under review is UNCOMMITTED, so
37
+ `git checkout -- <file>`, `git restore` and `git stash` all revert to
38
+ HEAD and destroy the very thing you were sent to review. Copy the file to
39
+ a scratch path first, restore from that copy, and prove the restore with
40
+ `diff` before you carry on. Then DISCLOSE the mutation in your report.
41
+ Measured: a reviewer did exactly this, caught it by re-diffing, and
42
+ recovered only because it had taken the backup — the same sequence
43
+ without one loses the author's work with no record of what was in it.
34
44
  3. **Check the optimization section** — whether what the author claims is
35
45
  genuinely in the code, not just in the write-up.
36
46
  4. **The verdict is binary.** APPROVE, with minor notes routed to `NOTES.md`;
@@ -182,6 +182,34 @@ export function refusalPayload(event, reason) {
182
182
  return { decision: 'block', reason };
183
183
  }
184
184
 
185
+ /**
186
+ * The ask payload for `event` — a REAL question to the user, not a refusal.
187
+ *
188
+ * "ask" renders the user's own permission prompt even in a mode that
189
+ * auto-accepts edits, which is what lets a gate delegate one decision to the
190
+ * operator instead of choosing between deny and silence. It is only
191
+ * expressible where the platform models permissionDecision (PreToolUse);
192
+ * every other event refuses the registration the same way refusalPayload
193
+ * does, because an ask nobody can render would degrade to silence, and
194
+ * silence is a pass (ADR-19: an exclusion may never be quiet).
195
+ */
196
+ export function askPayload(event, reason) {
197
+ const meta = EVENTS[event];
198
+ if (meta === undefined || meta.refusal === null) {
199
+ throw new GateOnProbeEventError(String(event));
200
+ }
201
+ if (meta.refusal !== 'permissionDecision') {
202
+ throw new Error(`"ask" is only expressible where the platform models permissionDecision, not on ${String(event)}`);
203
+ }
204
+ return {
205
+ hookSpecificOutput: {
206
+ hookEventName: event,
207
+ permissionDecision: 'ask',
208
+ permissionDecisionReason: reason,
209
+ },
210
+ };
211
+ }
212
+
185
213
  /** The context-injection payload for `event`, or `{}` where it accepts none. */
186
214
  export function contextPayload(event, additionalContext) {
187
215
  const meta = EVENTS[event];
@@ -458,9 +486,11 @@ function refusalText({ errorClass, message, fix }) {
458
486
  * platform's timeout kills the process and DISCARDS its output, so a
459
487
  * gate that is merely slow is a gate that approves.
460
488
  *
461
- * `handler(input)` returns `PASS` or `{ decision: 'deny', reason }`.
462
- * Anything else is treated as a bug and refuses — an unrecognised return
463
- * value must not be able to mean "allow".
489
+ * `handler(input)` returns `PASS`, `{ decision: 'deny', reason }` or —
490
+ * on events that model permissionDecision — `{ decision: 'ask', reason }`,
491
+ * which renders the user's own prompt for exactly this call. Anything else
492
+ * is treated as a bug and refuses — an unrecognised return value must not
493
+ * be able to mean "allow".
464
494
  *
465
495
  * ## What the deadline does and does not promise
466
496
  *
@@ -683,8 +713,16 @@ export async function runGate({ event, handler, deadlineMs, io = defaultIo() })
683
713
  emit(payload);
684
714
  return;
685
715
  }
716
+ if (verdict !== null && typeof verdict === 'object' && verdict.decision === 'ask') {
717
+ const { payload } = clampPayload(
718
+ (reason) => askPayload(outEvent, reason),
719
+ sanitizeForOutput(String(verdict.reason ?? 'asked without a stated reason')),
720
+ );
721
+ emit(payload);
722
+ return;
723
+ }
686
724
  throw new Error(
687
- `handler returned ${JSON.stringify(verdict)}; expected PASS or { decision: 'deny', reason }`,
725
+ `handler returned ${JSON.stringify(verdict)}; expected PASS or { decision: 'deny' | 'ask', reason }`,
688
726
  );
689
727
  } catch (err) {
690
728
  refuse(outEvent, describeError(err));
@@ -853,25 +853,31 @@ export function pathTargets(toolInput) {
853
853
  *
854
854
  * The full matrix, and every cell is a decision rather than a fall-through:
855
855
  *
856
- * | class | supervised main loop | unsupervised (subagent, or prompts off) |
857
- * |----------|----------------------|------------------------------------------|
858
- * | AUTO | pass | pass |
859
- * | GATED | pass — the platform's own prompt IS the approval | **deny** |
860
- * | KERNEL | **deny** | **deny** |
861
- * | unmatched| = the policy's `default:` (GATED in the shipped template) | |
856
+ * | class | supervised main loop | main, prompts off (askable) | subagent / other |
857
+ * |----------|----------------------|-----------------------------|------------------|
858
+ * | AUTO | pass | pass | pass |
859
+ * | GATED | pass — the platform's own prompt IS the approval | **ask** — the gate summons the prompt itself | **deny** |
860
+ * | KERNEL | **deny** | **deny** | **deny** |
861
+ * | unmatched| = the policy's `default:` (GATED in the shipped template) | | |
862
862
  *
863
- * The GATED row is the one worth arguing. On PreToolUse the platform offers
864
- * exactly two answers, `deny` and silence; there is no "ask" this runtime can
865
- * emit, and inventing one means editing hook-io, which is a different
866
- * decision than this story's. So GATED is delegated where an approval channel
867
- * already exists — the user's own permission prompt — and enforced where it
868
- * does not. That is why supervision, not just actor, is an axis: under
869
- * `acceptEdits` the main loop has no prompt either, and treating it as
870
- * supervised would have made the whole row decorative.
863
+ * The GATED row is the one worth arguing. hook-io can emit a third answer —
864
+ * an "ask" — which renders the user's own prompt even in a mode that
865
+ * auto-accepts edits, so GATED can mean what ADR-06 says it means wherever a
866
+ * prompt can render. `askable` is that fact as an argument: the caller sets
867
+ * it only for the MAIN loop under `acceptEdits`, the mode agents actually
868
+ * run in. It stays false under `bypassPermissions` and unknown modes — an
869
+ * ask a mode might not render must fail toward deny, never toward approval —
870
+ * and false for every subagent, whose calls have no prompt surface at all.
871
+ * Measured before this cell existed: under `acceptEdits` the operator's own
872
+ * conductor could not perform a GATED write anywhere, while the refusal text
873
+ * pointed at a main session that refused exactly the same way.
871
874
  */
872
- export function verdictForClass(cls, unsupervised) {
875
+ export function verdictForClass(cls, unsupervised, askable = false) {
873
876
  if (cls === 'KERNEL') return 'deny';
874
- if (cls === 'GATED') return unsupervised ? 'deny' : 'pass';
877
+ if (cls === 'GATED') {
878
+ if (!unsupervised) return 'pass';
879
+ return askable ? 'ask' : 'deny';
880
+ }
875
881
  if (cls === 'AUTO') return 'pass';
876
882
  // An unrecognised class cannot be resolved to a permission. validatePolicy
877
883
  // rejects one, so reaching here means the resolver and the validator
@@ -1032,6 +1038,10 @@ export async function decide({ input, runner = runChild, startedAt = Date.now(),
1032
1038
  const root = repoRootOf(input, env);
1033
1039
  const unsupervised = isUnsupervised(input);
1034
1040
  const actor = actorOf(input);
1041
+ // The one mode where an unsupervised main loop still renders an ask.
1042
+ // Deliberately not "any unsupervised main": bypassPermissions and unknown
1043
+ // modes must keep the hard deny — see verdictForClass's matrix.
1044
+ const askable = actor === 'main' && field(input, 'permission_mode') === 'acceptEdits';
1035
1045
 
1036
1046
  if (toolName === 'Bash') return await decideBash({ input, toolInput, root, runner, budget });
1037
1047
 
@@ -1146,7 +1156,7 @@ export async function decide({ input, runner = runChild, startedAt = Date.now(),
1146
1156
  if (normalized !== null && decidingRule(policy, normalized) === null && !isGoverned(normalized)) {
1147
1157
  continue;
1148
1158
  }
1149
- const verdict = verdictForClass(cls, unsupervised);
1159
+ const verdict = verdictForClass(cls, unsupervised, askable);
1150
1160
 
1151
1161
  // ADR-21, applied as a check rather than as a refactor: the rule this
1152
1162
  // refusal names and the class the resolver returned must agree. They are
@@ -1162,6 +1172,19 @@ export async function decide({ input, runner = runChild, startedAt = Date.now(),
1162
1172
  }
1163
1173
 
1164
1174
  if (verdict === 'pass') continue;
1175
+ if (verdict === 'ask') {
1176
+ return {
1177
+ decision: 'ask',
1178
+ reason:
1179
+ `tyran policy-gate: this write is GATED — your approval IS the gate. ` +
1180
+ `${describeTarget(target, normalized)}\n` +
1181
+ `class: ${safePolicyText(cls)} · actor: ${actor} · permission_mode: ` +
1182
+ `${safePolicyText(String(field(input, 'permission_mode') ?? '(absent)'))}\n` +
1183
+ `rule: ${quoteRule(policy, normalized, cls)}\n` +
1184
+ 'Approve to perform exactly this write, once. Decline and the agent is told to put ' +
1185
+ 'the change in its report instead.',
1186
+ };
1187
+ }
1165
1188
  return {
1166
1189
  decision: 'deny',
1167
1190
  reason:
@@ -694,11 +694,27 @@ export function planCommand(command, startDir) {
694
694
  break;
695
695
  }
696
696
  }
697
- if (raw.some((t) => t.toLowerCase().includes('core.hookspath'))) {
697
+ // Only the OVERRIDE forms disable hooks: `core.hooksPath=DIR` in any
698
+ // spelling, or `git config core.hooksPath DIR` (a following value). A bare
699
+ // query — `git config [--get] core.hooksPath` — reads the very state this
700
+ // rule protects, and refusing it was measured mid-incident: the command run
701
+ // to find out WHICH hook had just refused a push was itself refused. A gate
702
+ // that blocks reading its own subject teaches routing around, not caution.
703
+ const hooksPathOverride = raw.some((t, i) => {
704
+ const lower = t.toLowerCase();
705
+ if (!lower.includes('core.hookspath')) return false;
706
+ if (lower.includes('core.hookspath=')) return true;
707
+ if (!words.has('config')) return false;
708
+ // ANY following token can be the value: git stores "-evildir" verbatim
709
+ // rather than rejecting it as a flag (review finding, verified against
710
+ // real git). A query puts the key LAST, so key-then-anything is a set.
711
+ return raw[i + 1] !== undefined;
712
+ });
713
+ if (hooksPathOverride) {
698
714
  denials.push({
699
715
  code: DENIAL_CODES.HOOKS_PATH,
700
716
  detail: "`core.hooksPath` is being overridden, which disables git's hooks for this command",
701
- remedy: 'run the command without -c core.hooksPath=...',
717
+ remedy: 'run the command without -c core.hooksPath=... (a bare `git config core.hooksPath` query is fine)',
702
718
  });
703
719
  }
704
720
  if (gitCommit && tokens.some((t) => isShortCluster(t) && t.includes('n'))) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@jjanczur/tyran",
3
- "version": "0.1.5",
3
+ "version": "0.1.7",
4
4
  "description": "Command-line scripts for the Tyran task conductor (doctor, journal, schema, and repo tooling) for CI and terminals outside Claude Code. Installing this package does NOT install the Claude Code plugin — add that separately with `/plugin marketplace add jjanczur/tyran` inside Claude Code.",
5
5
  "type": "module",
6
6
  "engines": {
@@ -15,7 +15,7 @@
15
15
  * node journal.mjs validate <file>
16
16
  * node journal.mjs next-id <file> <prefix> # e.g. prefix D -> D-7
17
17
  * node journal.mjs tail <file> # last checkpoint + open items
18
- * node journal.mjs open-spawns <file> # agents with no report yet
18
+ * node journal.mjs open-spawns <file> # agents with no report or review yet
19
19
  * node journal.mjs close-spawn <file> <init> <agent> --reason R [--verdict V]
20
20
  * Exit: 0 ok · 1 validation/finding error · 2 usage/IO error
21
21
  */
@@ -179,7 +179,11 @@ export function agentNameProblem(name) {
179
179
 
180
180
  /**
181
181
  * Pair `spawn` events with `report` events by agent name, in file order:
182
- * a report closes the OLDEST still-open spawn of that name (FIFO). This is
182
+ * a report closes the OLDEST still-open spawn of that name (FIFO), and a
183
+ * `review` closes its reviewer the same way, correlated by `data.by` — but
184
+ * only a spawn whose `role` is `reviewer`: `by` is a free string, and a
185
+ * collision with a still-working implementer's name must not mark that
186
+ * implementer reported with a verdict it never earned. This is
183
187
  * the one and only pairing rule — `append` enforces that it can never be
184
188
  * ambiguous (ADR-18: at most one open spawn per name), so consumers such as
185
189
  * the projection generator implement a guarantee, not a heuristic.
@@ -210,10 +214,18 @@ export function pairSpawns(events) {
210
214
  */
211
215
  const ambiguous = new Map(); // agent -> the largest number of spawns open at once
212
216
  for (const e of events) {
213
- if (e?.ev !== 'spawn' && e?.ev !== 'report') continue;
214
- const agent = e.data?.agent;
217
+ if (e?.ev !== 'spawn' && e?.ev !== 'report' && e?.ev !== 'review') continue;
218
+ // A reviewer never files a `report` about itself — its verdict IS its
219
+ // completion. Measured in the field: reviewers spawned per iron rule 3
220
+ // stayed "still working" in the session-start probe for days, because
221
+ // only reports closed spawns. A review's correlator is `data.by`.
222
+ const isReview = e.ev === 'review';
223
+ const agent = isReview ? e.data?.by : e.data?.agent;
215
224
  const problem = agentNameProblem(agent);
216
225
  if (problem) {
226
+ // A review is a verdict record first; an uncorrelatable `by` is not an
227
+ // agent-lifecycle defect, so it stays out of the unusable set.
228
+ if (isReview) continue;
217
229
  badNames.set(JSON.stringify(agent ?? null), problem);
218
230
  unusable.push({ event: e, problem });
219
231
  continue; // unusable as a correlator; validate() reports it
@@ -225,17 +237,25 @@ export function pairSpawns(events) {
225
237
  if (depth > 1 && depth > (ambiguous.get(agent) ?? 0)) ambiguous.set(agent, depth);
226
238
  } else {
227
239
  const queue = open.get(agent);
228
- if (queue?.length) {
240
+ const closable = queue?.length && (!isReview || queue[0].data?.role === 'reviewer');
241
+ if (closable) {
229
242
  const spawn = queue.shift();
230
243
  pairs.push({ spawn, report: e });
231
244
  if (queue.length === 0) open.delete(agent);
245
+ } else if (isReview) {
246
+ // A review by a never-spawned (or already-closed) actor is ordinary —
247
+ // a verdict does not require a lifecycle to close.
248
+ } else if (e.data?.closed_by === 'close-spawn') {
249
+ // Journals written before reviews closed spawns carry a close-spawn
250
+ // report right after the review that now closes the same spawn:
251
+ // redundant, not orphaned — flagging it would fail history retroactively.
232
252
  } else orphanReports.push(e);
233
253
  }
234
254
  }
235
255
  return { open, orphanReports, badNames, pairs, unusable, ambiguous };
236
256
  }
237
257
 
238
- /** Agents whose `spawn` has no matching `report` yet — the "still working" set. */
258
+ /** Agents whose `spawn` has no matching `report` or `review` yet — the "still working" set. */
239
259
  export function openSpawns(file) {
240
260
  const { open } = pairSpawns(readJournal(file).events);
241
261
  return [...open.values()].flat().map((e) => ({
@@ -663,8 +683,11 @@ function main() {
663
683
  // the exact failure the rule names, with nothing objecting.
664
684
  //
665
685
  // A rule in prose loses to a mechanism that makes the mistake
666
- // impossible. This is that mechanism, and an explicit id still wins.
667
- if (ID_ISSUED_FOR[ev] !== undefined && data.id === undefined) {
686
+ // impossible. This is that mechanism, and an explicit id still wins —
687
+ // but `"id":""` is not explicit: a conductor recovering from next-id's
688
+ // usage error supplied exactly that, three times, and the ledger kept
689
+ // three permanently blank ids nothing can reference.
690
+ if (ID_ISSUED_FOR[ev] !== undefined && (data.id === undefined || data.id === '')) {
668
691
  data.id = nextId(file, ID_ISSUED_FOR[ev]);
669
692
  }
670
693
  const written = append(file, { ev, init, actor: flags.actor ?? 'conductor', data });
@@ -57,6 +57,18 @@ Return them as **counts plus the first few offenders**, then a single verdict
57
57
  line. A pass with `0` console errors is a fact; "the console was clean" is a
58
58
  recollection.
59
59
 
60
+ **When the UI claims to change something the SERVER acts on** — a mapping, a
61
+ setting, a value the next request depends on — a clean console and a `2xx` are
62
+ not proof it arrived. The evidence has to follow the value to what got STORED,
63
+ not stop at what got RENDERED: capture the request body you actually sent, or
64
+ read the value back with a second request or a reload, and assert on THAT. This
65
+ is not hypothetical. A column-mapping override shipped with a perfect browser
66
+ pass — 15/15 columns visible, 0 console errors, the mapping visibly changed by
67
+ hand — while the server re-derived the source type from the uploaded bytes and
68
+ discarded the mapping, answering `201` either way. Only a reviewer reading the
69
+ server route caught it; nothing in the browser measurement could have, because
70
+ it never inspected what the server persisted.
71
+
60
72
  ## Selectors that do not go blind
61
73
 
62
74
  Anchor on what the user sees — a role, a label, the text — not on a container
@@ -46,7 +46,15 @@ gap nobody notices.
46
46
  is broken? Delete a line of the implementation in your head and ask which
47
47
  test goes red — if the answer is none, the test asserts nothing. Watch for a
48
48
  test that pins the CURRENT output rather than the CORRECT one, which converts
49
- a bug into a requirement.
49
+ a bug into a requirement. And watch what the test's OWN inputs are made of:
50
+ a fixture that hand-builds a value another function normally derives (a
51
+ mapper, a parser, a coercion) exercises only the consumer of that value,
52
+ never the step that derives it, and can pin THAT step's defect as correct
53
+ without ever calling it. A three-state flag silently collapsed to two states
54
+ survived two review rounds this way — every guard test hand-built the
55
+ post-coercion object, and the only two tests that called the real producer
56
+ were themselves asserting the coerced, wrong value. Trace at least one test
57
+ through the real producer, not a stand-in for its output.
50
58
  - **Resource lifecycle.** What is opened, started, spawned or leased, and where
51
59
  it is closed — including on the path where an exception is thrown.
52
60
  - **The gate itself.** If the change touches a check, ask what that check can
@@ -143,8 +143,19 @@ open one.
143
143
  and **signals about the PROCESS itself**: what slowed the work, what the
144
144
  handoff was missing, what a gate let through — this is the raw material
145
145
  `tyran:retro` reads). After a compaction or restart, read these FIRST.
146
- - **IDs never come from memory** — `journal.mjs next-id` issues them.
147
- After a compaction, memory hands out the same number twice.
146
+ - **A file write is not a git commit.** `journal.mjs append` only ever
147
+ touches the working tree. Stage and commit `.tyran/state/<initiative>/**`
148
+ explicitly (never `-A`) at every merge, not only when the initiative
149
+ closes — a backstop that fires once, at the end, depends on whoever
150
+ closes the initiative both remembering to check and being permitted to
151
+ commit, and measured three times in one repository, neither held. An
152
+ initiative whose journal never reaches history is one `git clean -fd`
153
+ away from having never happened.
154
+ - **IDs never come from memory** — omit `id` from a `decision` event's
155
+ `--data` (or leave it empty) and `append` issues the next one itself.
156
+ `journal.mjs next-id <file> <prefix>` exists to preview a value ahead of
157
+ time (prefix `D` → `D-7`); it is not a required preliminary step before
158
+ `append`. After a compaction, memory hands out the same number twice.
148
159
  - **Authorizations and stops are `decision` events.** What you may do
149
160
  without asking, and the CLOSED list of situations where you halt, live
150
161
  in the journal with the date and the operator's own words. Outside that
@@ -279,6 +290,10 @@ open one.
279
290
  existing unexpired lease means the agent refuses to start and reports —
280
291
  and ENDS by releasing it. Assigning slots from your own memory is
281
292
  forbidden: the lead's memory is the least reliable store in the system.
293
+ If the policy gate refuses the lease write — an install whose repo-local
294
+ `autonomy.yaml` predates the `locks/**` AUTO rule — fall back to
295
+ `lease.acquired`/`lease.released` events in the journal, same holder,
296
+ purpose and expiry, conductor-written, rather than working unleased.
282
297
  - **Preflight a heavy slot** on acquisition: check free disk against a
283
298
  threshold, clear known caches above it, and reap the previous holder's
284
299
  orphaned processes with SIGTERM rather than `kill -9`.
@@ -322,6 +337,9 @@ open one.
322
337
  so is judging the work too small to be worth one. Either way, record a
323
338
  `retro.entry` — `kind: skipped` with a reason is a complete answer — and
324
339
  the gate is satisfied. You will not be blocked twice.
340
+ Dispatching the retro as a background agent? Record a `retro.entry` with
341
+ `kind: spawned` at dispatch time — the gate anchors on the entry, not the
342
+ agent, and will otherwise stop you once while the retro is still running.
325
343
  - **Leases you took, you release.** Before you finish, check the ledger for
326
344
  a lease still held by an agent that has already reported. An orphaned lease
327
345
  blocks the next initiative from a resource nobody is using, and the person
@@ -32,6 +32,28 @@ rules:
32
32
  class: AUTO
33
33
  reason: the execution journal is append-only and written by the conductor itself
34
34
 
35
+ # Measured on a real initiative: iron rule 7 says "a handoff BEGINS by taking
36
+ # the lease" and ENDS by releasing it — but leases live under
37
+ # `.tyran/initiatives/<slug>/locks/`, which matched NO rule here, so it fell
38
+ # through to `default: GATED`. A subagent is ALWAYS unsupervised, and
39
+ # `verdictForClass(GATED, unsupervised)` denies unconditionally. So the lease
40
+ # protocol the conductor skill mandates could not be satisfied by any
41
+ # implementer, in any repo, under the shipped template — the agent either
42
+ # reported the refusal (correct, and what happened) or quietly worked without
43
+ # the lease, which is the failure mode leases exist to prevent. The conductor
44
+ # had to write every lease itself, which puts the record of who holds a
45
+ # resource in the one place iron rule 7 says it must not live: the lead.
46
+ #
47
+ # AUTO is the safe class here precisely because these are not history: the
48
+ # repo's own .gitignore excludes `.tyran/initiatives/*/locks/`, so nothing
49
+ # under it is version-controlled and the blast radius of a bad write is a
50
+ # stale lock file, cleared by deleting it. Scoped to `locks/` deliberately
51
+ # rather than all of `.tyran/initiatives/**`, so anything else that comes to
52
+ # live under an initiative keeps the stricter default.
53
+ - path: .tyran/initiatives/*/locks/**
54
+ class: AUTO
55
+ reason: runtime worktree and heavy-slot leases, gitignored and not history; GATED denies every subagent unconditionally, which makes the take-your-own-lease protocol of iron rule 7 unsatisfiable
56
+
35
57
  # Was GATED. The cost was measured on a real install: setup had inferred
36
58
  # `pnpm test`, which in that repo is bare `vitest` — it never exits, so every
37
59
  # agent would have hung forever. The session that FOUND that could not fix it,