@jjanczur/tyran 0.1.18 → 0.1.20
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 +114 -0
- package/README.md +182 -425
- package/package.json +1 -1
- package/scripts/board-html.mjs +335 -188
- package/scripts/doctor.mjs +118 -4
- package/skills/retro/SKILL.md +1 -1
- package/skills/run/SKILL.md +22 -1
- package/skills/setup/SKILL.md +1 -1
- package/templates/config.yaml +2 -2
package/scripts/doctor.mjs
CHANGED
|
@@ -206,6 +206,12 @@ export const SEVERITY_BY_CODE = Object.freeze(
|
|
|
206
206
|
'state-stray-file': 'warning',
|
|
207
207
|
'state-legacy-initiatives-dir': 'warning',
|
|
208
208
|
'lease-file-tracked': 'warning',
|
|
209
|
+
// the ledger in git. `uncommitted` is INFO on purpose: every append
|
|
210
|
+
// produces that state within seconds, and a warning that is on during
|
|
211
|
+
// normal operation is a warning people learn to scroll past.
|
|
212
|
+
'initiative-untracked': 'warning',
|
|
213
|
+
'initiative-ignored': 'warning',
|
|
214
|
+
'initiative-uncommitted': 'info',
|
|
209
215
|
// the mistakes ledger. `mistakes-unreadable` is a WARNING, not the `error`
|
|
210
216
|
// that `knowledge-unreadable` and `config-unreadable` carry: nothing
|
|
211
217
|
// mechanical consumes MISTAKES.md at write time, so an unreadable one
|
|
@@ -1162,6 +1168,98 @@ export function untrackedTyranDir(repoRoot, run, tyranDirName = '.tyran') {
|
|
|
1162
1168
|
return run(['ls-files', '--', tyranDirName]).trim() === '';
|
|
1163
1169
|
}
|
|
1164
1170
|
|
|
1171
|
+
/**
|
|
1172
|
+
* Which initiative ledgers git has never seen, and which carry local changes.
|
|
1173
|
+
*
|
|
1174
|
+
* `untrackedTyranDir` above is all-or-nothing: one tracked file anywhere under
|
|
1175
|
+
* `.tyran/` and the whole directory reports healthy. That is the wrong
|
|
1176
|
+
* granularity for what iron rule 1 actually asks for. Measured on a real
|
|
1177
|
+
* install whose `.tyran/` had been tracked for weeks: one initiative directory
|
|
1178
|
+
* of six files — its plan, and the gate event recording two production
|
|
1179
|
+
* database migrations — had NEVER been committed, and a second was 33 events
|
|
1180
|
+
* behind its committed copy. The directory-level check passed on both.
|
|
1181
|
+
* `journal.mjs append` writes the working tree and nothing else, so an
|
|
1182
|
+
* initiative nobody committed is one `git clean -fd` from having never
|
|
1183
|
+
* happened.
|
|
1184
|
+
*
|
|
1185
|
+
* Three states, because the same loss needs three different sentences:
|
|
1186
|
+
*
|
|
1187
|
+
* - `untracked` — git has never seen this ledger. Wrong at any moment.
|
|
1188
|
+
* - `ignored` — a rule in some `.gitignore` covers it. The same loss, but
|
|
1189
|
+
* `git add` on a path git is ignoring is a SILENT no-op, so the advice the
|
|
1190
|
+
* untracked case gives would look like it worked and change nothing.
|
|
1191
|
+
* - `uncommitted` — tracked, with local changes. What an initiative in
|
|
1192
|
+
* flight looks like ten seconds after any append, so it is worth saying
|
|
1193
|
+
* only at a merge boundary, and never worth failing a check over.
|
|
1194
|
+
*
|
|
1195
|
+
* Two git invocations for the whole tree rather than two per initiative: the
|
|
1196
|
+
* listings are read once and classified by path prefix in JS. A repo can hold
|
|
1197
|
+
* dozens of initiatives and this runs behind the SessionStart deadline. The
|
|
1198
|
+
* prefix is built in git's own output convention (repo-relative, forward
|
|
1199
|
+
* slashes) for the same reason `trackedLeaseFiles` filters in JS instead of
|
|
1200
|
+
* trusting pathspec globbing.
|
|
1201
|
+
*
|
|
1202
|
+
* No second `rev-parse`: the caller reaches this only when `untrackedTyranDir`
|
|
1203
|
+
* returned a boolean rather than null, which is already the answer to whether
|
|
1204
|
+
* git can answer.
|
|
1205
|
+
*/
|
|
1206
|
+
export function initiativeGitStates(run, tyranDirName, names) {
|
|
1207
|
+
const lines = (out) => out.split('\n').filter((line) => line !== '');
|
|
1208
|
+
const tracked = lines(run(['ls-files', '--', tyranDirName]));
|
|
1209
|
+
// `--ignored` costs nothing on a call being made anyway and is the whole
|
|
1210
|
+
// difference between "you forgot" and "a rule you wrote is hiding it".
|
|
1211
|
+
// Porcelain v1 is `XY<space>path`; git collapses a wholly untracked or
|
|
1212
|
+
// ignored DIRECTORY into a single entry, so a recorded path can be shorter
|
|
1213
|
+
// than the prefix as well as longer — hence the check in both directions.
|
|
1214
|
+
const status = lines(run(['status', '--porcelain', '--ignored', '--', tyranDirName]));
|
|
1215
|
+
const paths = (keep) => status.filter((l) => l.startsWith('!! ') === keep).map((l) => l.slice(3));
|
|
1216
|
+
const ignored = paths(true);
|
|
1217
|
+
const dirty = paths(false);
|
|
1218
|
+
const covers = (entries, prefix) =>
|
|
1219
|
+
entries.some((path) => path.startsWith(prefix) || prefix.startsWith(path));
|
|
1220
|
+
const states = new Map();
|
|
1221
|
+
for (const name of names) {
|
|
1222
|
+
const prefix = `${tyranDirName}/state/${name}/`;
|
|
1223
|
+
if (tracked.some((path) => path.startsWith(prefix))) {
|
|
1224
|
+
states.set(name, covers(dirty, prefix) ? 'uncommitted' : 'committed');
|
|
1225
|
+
} else {
|
|
1226
|
+
states.set(name, covers(ignored, prefix) ? 'ignored' : 'untracked');
|
|
1227
|
+
}
|
|
1228
|
+
}
|
|
1229
|
+
return states;
|
|
1230
|
+
}
|
|
1231
|
+
|
|
1232
|
+
/** The finding for one non-`committed` ledger state, or null for `committed`. */
|
|
1233
|
+
function ledgerFinding(state, path, name, gitPath) {
|
|
1234
|
+
if (state === 'untracked') {
|
|
1235
|
+
return finding(
|
|
1236
|
+
'initiative-untracked',
|
|
1237
|
+
show(path),
|
|
1238
|
+
'git has never seen this ledger — `journal.mjs append` writes the working tree and nothing ' +
|
|
1239
|
+
'else, so an initiative nobody committed is one `git clean -fd` from having never happened, ' +
|
|
1240
|
+
'and a worktree carries tracked files only, so the agents working in one never read it',
|
|
1241
|
+
`git add ${sq(gitPath)} && git commit -m ${sq(`chore(tyran): record the ${name} ledger`)}`,
|
|
1242
|
+
);
|
|
1243
|
+
}
|
|
1244
|
+
if (state === 'ignored') {
|
|
1245
|
+
return finding(
|
|
1246
|
+
'initiative-ignored',
|
|
1247
|
+
show(path),
|
|
1248
|
+
'a .gitignore rule covers this ledger, so nothing under it can be committed — the journal is ' +
|
|
1249
|
+
'the copy that is supposed to outlive the session, and this one exists on one machine only',
|
|
1250
|
+
`git check-ignore -v ${sq(`${gitPath}/journal.jsonl`)} # the rule doing it; ` +
|
|
1251
|
+
'`git add` alone is a silent no-op on an ignored path',
|
|
1252
|
+
);
|
|
1253
|
+
}
|
|
1254
|
+
return finding(
|
|
1255
|
+
'initiative-uncommitted',
|
|
1256
|
+
show(path),
|
|
1257
|
+
'the ledger has uncommitted changes — ordinary mid-initiative, a gap at a merge boundary: ' +
|
|
1258
|
+
'rule 1 asks for the ledger to travel with the work, not to be committed once at the end',
|
|
1259
|
+
`git add ${sq(gitPath)} && git commit -m ${sq(`chore(tyran): ${name} ledger`)}`,
|
|
1260
|
+
);
|
|
1261
|
+
}
|
|
1262
|
+
|
|
1165
1263
|
/**
|
|
1166
1264
|
* Lease files committed to git. A lease records who holds a worktree or a
|
|
1167
1265
|
* heavy slot RIGHT NOW; committing one makes every parallel merge conflict on
|
|
@@ -1258,7 +1356,7 @@ export function mistakesFindings(repoRoot) {
|
|
|
1258
1356
|
show(claudePath),
|
|
1259
1357
|
`${lawEntries} entr${lawEntries === 1 ? 'y' : 'ies'} in ${MISTAKES_FILE} ` +
|
|
1260
1358
|
`claim${lawEntries === 1 ? 's' : ''} status \`law\`, and ${why}`,
|
|
1261
|
-
`node scripts/mistakes.mjs repeats --file ${sq(path)} # see
|
|
1359
|
+
`node scripts/mistakes.mjs repeats --file ${sq(path)} # see https://jjanczur.github.io/tyran/self-improvement/ for the fence`,
|
|
1262
1360
|
),
|
|
1263
1361
|
);
|
|
1264
1362
|
}
|
|
@@ -1371,7 +1469,7 @@ export function overnightFindings(dir, { now = null, configDoc = null } = {}) {
|
|
|
1371
1469
|
show(sidecarPath),
|
|
1372
1470
|
`limits.mode is "${show(limits.mode)}" but the usage telemetry sidecar is ${sidecar === null ? 'absent' : 'over a day old'} — ` +
|
|
1373
1471
|
'the gate fails open without it, so the configured pause protects nothing. The statusline ' +
|
|
1374
|
-
'helper is operator-installed; see
|
|
1472
|
+
'helper is operator-installed; see https://jjanczur.github.io/tyran/overnight/',
|
|
1375
1473
|
`node scripts/statusline.mjs --sidecar-only # wired into the user-settings statusLine command`,
|
|
1376
1474
|
),
|
|
1377
1475
|
);
|
|
@@ -1506,6 +1604,18 @@ export function runStateChecks({ dir = '.tyran', now = null, staleHours = DEFAUL
|
|
|
1506
1604
|
finding('state-unreadable', show(stateDir), `cannot list state/ (${errText(err)})`),
|
|
1507
1605
|
);
|
|
1508
1606
|
}
|
|
1607
|
+
// Only when `.tyran/` as a whole IS tracked. Under a wholly untracked
|
|
1608
|
+
// directory every initiative would repeat the finding above, each time
|
|
1609
|
+
// with narrower advice than the one that already covers it, and a check
|
|
1610
|
+
// that says the same thing N+1 times is a check people learn to skip.
|
|
1611
|
+
const gitStates =
|
|
1612
|
+
untracked === false
|
|
1613
|
+
? initiativeGitStates(
|
|
1614
|
+
gitRun,
|
|
1615
|
+
basename(root),
|
|
1616
|
+
sortedNames(names).filter((name) => isDirectory(join(stateDir, name))),
|
|
1617
|
+
)
|
|
1618
|
+
: null;
|
|
1509
1619
|
for (const name of sortedNames(names)) {
|
|
1510
1620
|
const path = join(stateDir, name);
|
|
1511
1621
|
if (!isDirectory(path)) {
|
|
@@ -1526,6 +1636,10 @@ export function runStateChecks({ dir = '.tyran', now = null, staleHours = DEFAUL
|
|
|
1526
1636
|
}
|
|
1527
1637
|
const result = checkInitiative(stateDir, name, { now, staleHours });
|
|
1528
1638
|
findings.push(...result.findings);
|
|
1639
|
+
const ledger = gitStates?.get(name) ?? 'committed';
|
|
1640
|
+
if (ledger !== 'committed') {
|
|
1641
|
+
findings.push(ledgerFinding(ledger, path, name, `${basename(root)}/state/${name}`));
|
|
1642
|
+
}
|
|
1529
1643
|
initiatives.push(`${show(name)} (${result.events} event(s))`);
|
|
1530
1644
|
}
|
|
1531
1645
|
}
|
|
@@ -1542,7 +1656,7 @@ export function runStateChecks({ dir = '.tyran', now = null, staleHours = DEFAUL
|
|
|
1542
1656
|
'legacy layout — initiative files (PLAN.md, NOTES.md, RETRO.md, locks/) live under ' +
|
|
1543
1657
|
'state/<initiative>/ since 0.1.9. Mechanical consumers read only state/, so anything ' +
|
|
1544
1658
|
'kept here is invisible to the projections, the retrospective and the session summary',
|
|
1545
|
-
`ls -la ${sq(legacyDir)} # relocate the contents by hand, one initiative directory at a time, into ${sq(join(dir, 'state'))} — see
|
|
1659
|
+
`ls -la ${sq(legacyDir)} # relocate the contents by hand, one initiative directory at a time, into ${sq(join(dir, 'state'))} — see https://jjanczur.github.io/tyran/journal/`,
|
|
1546
1660
|
),
|
|
1547
1661
|
);
|
|
1548
1662
|
}
|
|
@@ -1564,7 +1678,7 @@ export function runStateChecks({ dir = '.tyran', now = null, staleHours = DEFAUL
|
|
|
1564
1678
|
`${trackedLeases.length} lease file(s) committed to git — a lease records who holds a resource ` +
|
|
1565
1679
|
'RIGHT NOW, so a committed one conflicts on every parallel merge and resurrects as a phantom ' +
|
|
1566
1680
|
'holder on every checkout',
|
|
1567
|
-
`git ls-files -- ${sq(basename(root))} # list them; keep 'state/*/locks/' in .tyran/.gitignore and un-track the files by hand — see
|
|
1681
|
+
`git ls-files -- ${sq(basename(root))} # list them; keep 'state/*/locks/' in .tyran/.gitignore and un-track the files by hand — see https://jjanczur.github.io/tyran/configuration/`,
|
|
1568
1682
|
),
|
|
1569
1683
|
);
|
|
1570
1684
|
}
|
package/skills/retro/SKILL.md
CHANGED
|
@@ -101,7 +101,7 @@ node "${CLAUDE_PLUGIN_ROOT}/scripts/mistakes.mjs" repeats
|
|
|
101
101
|
It prints one line per signature that has crossed a graduation threshold,
|
|
102
102
|
ending in what that signature has earned. Act on that recommendation — the
|
|
103
103
|
thresholds themselves, and why they are where they are, live in
|
|
104
|
-
|
|
104
|
+
https://jjanczur.github.io/tyran/self-improvement/.
|
|
105
105
|
|
|
106
106
|
- **`promote to .tyran/knowledge/`** — write the rule into
|
|
107
107
|
`.tyran/knowledge/<topic>.yaml`, scoped with `applies_to` so it reaches only
|
package/skills/run/SKILL.md
CHANGED
|
@@ -70,6 +70,13 @@ English regardless.
|
|
|
70
70
|
server start vanish on restart, so restarts stop being deterministic;
|
|
71
71
|
- probe the toolchain with `command -v` for every tool the plan names, and
|
|
72
72
|
confirm your own file-writing path works before you rely on it;
|
|
73
|
+
- **probe for interactive aliases** — `alias cp mv rm 2>/dev/null` — because
|
|
74
|
+
an agent's shell is started from the user's profile, so `alias cp='cp -i'`
|
|
75
|
+
turns a copy into a question with nobody to answer it and the call burns
|
|
76
|
+
its whole timeout. Put `command cp` in the handoff when one is set. The
|
|
77
|
+
symptom is a timeout, which points at the machine rather than the alias,
|
|
78
|
+
so it is rediscovered every time: measured three times in one session, in
|
|
79
|
+
three different agents, and again in a later one that had read this file;
|
|
73
80
|
- **dry-run every automaton** for one no-op iteration before you trust it
|
|
74
81
|
with unattended work. Trust dialogs and missing dependencies surface
|
|
75
82
|
then, not at 3am.
|
|
@@ -227,6 +234,15 @@ open one.
|
|
|
227
234
|
carries an explicit **"NO INDEPENDENT REVIEW"** stamp; staying quiet about
|
|
228
235
|
it is forbidden. Tests for every non-trivial change. Repo validation per
|
|
229
236
|
the project configuration. You merge, sequentially.
|
|
237
|
+
- **A `Test timed out` measured while another heavy phase was running is
|
|
238
|
+
not evidence of a defect.** Re-run it serially, report the serial result,
|
|
239
|
+
and say the first run was concurrent. The hardware ceiling bounds AGENT
|
|
240
|
+
count, not concurrent heavy phases, so an agent can respect it and still
|
|
241
|
+
produce a red only the machine caused — five such failures in one session,
|
|
242
|
+
all green on a serial re-run.
|
|
243
|
+
- **An agent that dies on a terminal API error is RESUMED, not respawned.**
|
|
244
|
+
Its context, its corrected premises and its uncommitted diff all survive
|
|
245
|
+
the death; a fresh agent on the same handoff redoes work already on disk.
|
|
230
246
|
- **How a diff is read is the `code-review` skill**; what the verdict looks
|
|
231
247
|
like stays in `tyran:reviewer`. The part you enforce as conductor is that
|
|
232
248
|
a finding arrives as an input and an expected result — anything vaguer
|
|
@@ -345,6 +361,11 @@ open one.
|
|
|
345
361
|
manifest and lockfile are already a SHARED ZONE nobody may edit, so the
|
|
346
362
|
dependencies are guaranteed identical, and a per-worktree install is how
|
|
347
363
|
a lockfile drifts. Say in the handoff which directory you linked.
|
|
364
|
+
**Gitignored environment files are missing for the same reason, and they
|
|
365
|
+
fail QUIETER**: a missing dependency exits 127, a missing `.env` makes the
|
|
366
|
+
gated specs SKIP — so the worktree reports a *cleaner* baseline than the
|
|
367
|
+
repo has and the difference reads as good news. Link those too, and name
|
|
368
|
+
them in the handoff.
|
|
348
369
|
- **`.tyran/state/**` lives in the main checkout only.** An agent told to
|
|
349
370
|
append to `NOTES.md` from inside a worktree must use the absolute
|
|
350
371
|
main-repo path, or it writes into a copy nobody reads.
|
|
@@ -437,6 +458,6 @@ open one.
|
|
|
437
458
|
stop. Never route around the allowlist: the point of pausing at 97% is
|
|
438
459
|
that the last 3% pays for a clean checkpoint instead of a corpse. The
|
|
439
460
|
scheduler resumes the session after the reset (or notifies and holds on a
|
|
440
|
-
long, weekly-shaped wait —
|
|
461
|
+
long, weekly-shaped wait — https://jjanczur.github.io/tyran/overnight/); a resumed session starts
|
|
441
462
|
from the `usage-limit-pause` checkpoint and first closes the open
|
|
442
463
|
usage-limit gate with `result: passed`.
|
package/skills/setup/SKILL.md
CHANGED
|
@@ -164,7 +164,7 @@ copies of the config. Stage explicit paths until this commit exists.
|
|
|
164
164
|
|
|
165
165
|
## 7. Offer overnight mode — and say plainly what the operator must do
|
|
166
166
|
|
|
167
|
-
Overnight mode (
|
|
167
|
+
Overnight mode (https://jjanczur.github.io/tyran/overnight/) pauses autonomous work near the
|
|
168
168
|
subscription usage limit and resumes after the window resets. It is OFF by
|
|
169
169
|
default because its telemetry is a statusline the plugin cannot install:
|
|
170
170
|
`.claude/settings.json` in user scope is the operator's file, and the policy
|
package/templates/config.yaml
CHANGED
|
@@ -11,7 +11,7 @@
|
|
|
11
11
|
#
|
|
12
12
|
# Validate after editing: node scripts/schema.mjs validate config .tyran/config.yaml
|
|
13
13
|
|
|
14
|
-
# Cost mode: eco | balanced | full (see
|
|
14
|
+
# Cost mode: eco | balanced | full (see https://jjanczur.github.io/tyran/configuration/)
|
|
15
15
|
profile: balanced
|
|
16
16
|
|
|
17
17
|
# Deployment autonomy: P1 branch-only · P2 staging · P3 merge to main.
|
|
@@ -44,7 +44,7 @@ validation:
|
|
|
44
44
|
shared_zones: []
|
|
45
45
|
|
|
46
46
|
# Overnight mode — pause autonomous work near the subscription usage limits
|
|
47
|
-
# and resume after the window resets (
|
|
47
|
+
# and resume after the window resets (https://jjanczur.github.io/tyran/overnight/). Requires the
|
|
48
48
|
# operator-installed statusline helper (scripts/statusline.mjs), which is the
|
|
49
49
|
# only place the platform exposes usage telemetry; without it the gate is
|
|
50
50
|
# silent and doctor says so.
|