@jjanczur/tyran 0.1.6 → 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.
- package/.claude-plugin/marketplace.json +1 -1
- package/.claude-plugin/plugin.json +1 -1
- package/CHANGELOG.md +54 -0
- package/hooks/scripts/hook-io.mjs +42 -4
- package/hooks/scripts/policy-gate.mjs +40 -17
- package/hooks/scripts/secrets-gate.mjs +18 -2
- package/package.json +1 -1
- package/scripts/journal.mjs +31 -8
- package/skills/code-review/SKILL.md +9 -1
- package/skills/run/SKILL.md +20 -2
- package/templates/policies/autonomy.yaml +22 -0
|
@@ -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
|
+
"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.
|
|
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,59 @@
|
|
|
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
|
+
|
|
3
57
|
## 0.1.6 — 2026-08-06
|
|
4
58
|
|
|
5
59
|
### A browser pass must follow the value to what got STORED
|
|
@@ -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
|
|
462
|
-
*
|
|
463
|
-
*
|
|
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 |
|
|
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.
|
|
864
|
-
*
|
|
865
|
-
*
|
|
866
|
-
*
|
|
867
|
-
*
|
|
868
|
-
*
|
|
869
|
-
*
|
|
870
|
-
*
|
|
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')
|
|
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
|
-
|
|
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.
|
|
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": {
|
package/scripts/journal.mjs
CHANGED
|
@@ -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)
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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 });
|
|
@@ -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
|
package/skills/run/SKILL.md
CHANGED
|
@@ -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
|
-
- **
|
|
147
|
-
|
|
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,
|