@jjanczur/tyran 0.1.39 → 0.1.42

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.
@@ -205,6 +205,7 @@ export const SEVERITY_BY_CODE = Object.freeze(
205
205
  'config-invalid': 'error',
206
206
  'config-unreadable': 'error',
207
207
  'knowledge-invalid': 'error',
208
+ 'knowledge-duplicate-id': 'error',
208
209
  'knowledge-unreadable': 'error',
209
210
  'knowledge-not-a-directory': 'warning',
210
211
  'knowledge-entry-oversized': 'warning',
@@ -258,6 +259,7 @@ export const SEVERITY_BY_CODE = Object.freeze(
258
259
  // improvised key would be red on every healthy repo.
259
260
  'journal-key-near-miss': 'warning',
260
261
  'journal-key-unread': 'info',
262
+ 'finding-no-command': 'info',
261
263
  'claude-md-fence-missing': 'info',
262
264
  // overnight mode
263
265
  'limit-pause-active': 'info',
@@ -554,6 +556,7 @@ function checkInitiative(stateDir, name, { now, staleHours }) {
554
556
  };
555
557
  guard('journal integrity', () => journalIntegrity(journalPath, at, read));
556
558
  guard('data keys nothing reads', () => unreadKeyFindings(at, events));
559
+ guard('findings without a command', () => findingCommandFindings(at, events));
557
560
  guard('one initiative per file', () => initiativeScope(journalPath, at, name, events));
558
561
  guard('open spawns', () => spawnFindings(journalPath, at, name, events, reference, staleHours));
559
562
  guard('operator asks', () => askFindings(journalPath, at, read, reference));
@@ -735,6 +738,49 @@ function closeSpawnHint(journalPath, init, agent) {
735
738
  : `node scripts/journal.mjs close-spawn ${sq(journalPath)} ${sq(slug)} ${sq(agent)} --reason "<why>"`;
736
739
  }
737
740
 
741
+ /**
742
+ * The same entry id in two files.
743
+ *
744
+ * `validateKnowledge` allocates its `seen` set per DOCUMENT and runs once per
745
+ * file, so only the loop that assembles the whole store can see this — which
746
+ * is `loadEntries`, and it reports it through the channel `brief` and `audit`
747
+ * already refuse on. Doctor has to ask separately, or it reports "healthy"
748
+ * about a store no brief will read.
749
+ *
750
+ * It matters more since `supersedes` became the retirement mechanism: that
751
+ * field names an id, and an ambiguous one retires whichever entry the loop
752
+ * reached first.
753
+ */
754
+ function knowledgeDuplicateIds(knowledgeDir) {
755
+ let invalid;
756
+ try {
757
+ if (!isDirectory(knowledgeDir)) return [];
758
+ ({ invalid } = loadKnowledgeEntries(knowledgeDir));
759
+ } catch {
760
+ return [];
761
+ }
762
+ const findings = [];
763
+ for (const { file, errors } of invalid ?? []) {
764
+ for (const error of errors) {
765
+ // Only the collisions: a file that fails its SCHEMA is already reported
766
+ // by `checkSchemaFile`, and saying it twice is the defect this repo
767
+ // names ADR-21.
768
+ if (!/^duplicate id /.test(String(error))) continue;
769
+ findings.push(
770
+ finding(
771
+ 'knowledge-duplicate-id',
772
+ show(file),
773
+ `${error} — ids must be unique across the whole store, not merely within one file. ` +
774
+ '`knowledge.mjs brief` refuses a store that does not validate, so every handoff ' +
775
+ 'that asks for a brief gets nothing until one of the two is renamed',
776
+ `node scripts/knowledge.mjs audit --dir ${sq(knowledgeDir)} # names both files`,
777
+ ),
778
+ );
779
+ }
780
+ }
781
+ return findings;
782
+ }
783
+
738
784
  /**
739
785
  * Is the knowledge store actually READABLE, as a whole?
740
786
  *
@@ -761,14 +807,23 @@ function knowledgeReachability(knowledgeDir) {
761
807
  ? ''
762
808
  : ` ${stuck.length} of them cannot appear in ANY brief even alone (widest: ` +
763
809
  `${show(stuck[0].id)} at ${stuck[0].cost}), so no budget a caller passes will reach them.`;
810
+ // The denominator is LIVE entries, because `reachable` is measured over
811
+ // them — pairing it with the on-disk total would print "1 of 3 can reach a
812
+ // brief; 0 cannot", which does not add up. The superseded count is named
813
+ // separately so the two numbers still reconcile against the files on disk
814
+ // rather than looking like entries that went missing.
815
+ const retired =
816
+ report.superseded === 0
817
+ ? ''
818
+ : ` (${report.entries} on disk; ${report.superseded} superseded and deliberately retired)`;
764
819
  return [
765
820
  finding(
766
821
  'knowledge-store-unreachable',
767
822
  show(knowledgeDir),
768
- `${report.reachable} of ${report.entries} knowledge entries can reach one brief at the ` +
769
- `${report.budget}-codepoint budget; ${report.unreachable} cannot.${detail} The store is written ` +
770
- 'by every retrospective and read through that budget, so what does not fit is not merely ' +
771
- 'crowded — it reaches nobody',
823
+ `${report.reachable} of ${report.live} live knowledge entries can reach one brief at the ` +
824
+ `${report.budget}-codepoint budget; ${report.unreachable} cannot${retired}.${detail} The store ` +
825
+ 'is written by every retrospective and read through that budget, so what does not fit is not ' +
826
+ 'merely crowded — it reaches nobody',
772
827
  `node scripts/knowledge.mjs audit --dir ${sq(knowledgeDir)} # the full list, widest first`,
773
828
  ),
774
829
  ];
@@ -829,6 +884,57 @@ function unreadKeyFindings(at, events) {
829
884
  return findings;
830
885
  }
831
886
 
887
+ /** How many command-less findings are named before the rest are counted. */
888
+ const MAX_NAMED_FINDINGS = 12;
889
+
890
+ /**
891
+ * Findings whose proof is prose alone — no command to re-run.
892
+ *
893
+ * A `finding` carries `claim` + `proof`, and `proof` is a SENTENCE about what
894
+ * an agent saw. That is a claim standing where evidence should be, which is
895
+ * the shape this repo removes everywhere else: the evidence gate already
896
+ * refuses an implementer's report for exactly it. `command` and `exit_code`
897
+ * are the fix, and their value is that a reader can RE-RUN them — a stored
898
+ * output would be a snapshot that rots, a command gets better with age.
899
+ *
900
+ * `info`, and the severity is the whole argument for this check being
901
+ * shippable. Measured before it was written: 34 findings across 388 real
902
+ * journals, NONE of them carrying a command, because the keys did not exist
903
+ * until now. At `warning` this would turn every install red on upgrade day —
904
+ * the reasoning `board-absent` already records, and a check that goes red
905
+ * during normal operation is a check people learn to skip.
906
+ *
907
+ * A finding with nothing to run is legitimate and stays legitimate: reading
908
+ * code, a contradiction between two documents, an operator correction with
909
+ * `area: process`. So this is never a refusal — `journal.mjs` still requires
910
+ * only `area` + `claim`. It states a ratio, once, so that "a finding someone
911
+ * ran something for" and "a finding someone wrote a sentence about" stay
912
+ * distinguishable.
913
+ */
914
+ function findingCommandFindings(at, events) {
915
+ const findings = events.filter((e) => e.ev === 'finding');
916
+ if (findings.length === 0) return [];
917
+ const bare = findings.filter((e) => {
918
+ const command = e.data?.command;
919
+ return typeof command !== 'string' || command.trim() === '';
920
+ });
921
+ if (bare.length === 0) return [];
922
+ const ids = bare.map((e, i) => show(e.data?.id ?? `(no id, #${i + 1})`));
923
+ const shown = ids.slice(0, MAX_NAMED_FINDINGS).join(', ');
924
+ return [
925
+ finding(
926
+ 'finding-no-command',
927
+ at,
928
+ `${bare.length} of ${findings.length} finding(s) name no command: ${shown}` +
929
+ (ids.length > MAX_NAMED_FINDINGS ? ` (+${ids.length - MAX_NAMED_FINDINGS} more)` : '') +
930
+ '. Their proof is prose, so nobody can re-run it. A finding produced by running something ' +
931
+ 'should carry `command` and `exit_code` alongside `proof`; one produced by reading code ' +
932
+ 'legitimately carries neither, which is why this is stated rather than refused',
933
+ `node scripts/journal.mjs query ${sq(at)} --ev finding # the journal is append-only, so past findings keep their prose`,
934
+ ),
935
+ ];
936
+ }
937
+
832
938
  /** How long a self-reported `blocked` may stand before it is a finding. */
833
939
  export const DEFAULT_BLOCKED_HOURS = 1;
834
940
 
@@ -1843,6 +1949,12 @@ export function runStateChecks({
1843
1949
  );
1844
1950
  }
1845
1951
  }
1952
+ // A duplicate id ACROSS files, which no per-file check can see: the
1953
+ // validator allocates its id set per document. `knowledge.mjs brief`
1954
+ // refuses the whole store over this, so without a finding here doctor would
1955
+ // report a healthy repo while every handoff's brief exited 1 — a gate that
1956
+ // cannot fire is exactly what this command exists to catch.
1957
+ findings.push(...knowledgeDuplicateIds(join(dir, 'knowledge')));
1846
1958
  checked.push(`knowledge/: ${knowledge.files.length} file(s)`);
1847
1959
  // The AGGREGATE, which the per-entry warning above cannot show.
1848
1960
  //
@@ -129,7 +129,14 @@ export const DATA_KNOWN = Object.freeze({
129
129
  // that has ever answered a question or run a retrospective report its own
130
130
  // normal operation back at itself.
131
131
  decision: Object.freeze(['id', 'text', 'ask', 'ticket', 'signature', 'occurrences', 'path']),
132
- finding: Object.freeze(['area', 'claim', 'proof', 'id', 'ticket', 'confidence']),
132
+ // `command`/`exit_code` are the finding's proof as a POINTER rather than a
133
+ // copy: the command that produced the claim, and what it exited with. The
134
+ // prompts asked for this before the schema had anywhere to put it —
135
+ // `agents/implementer.md` tells an implementer to journal each dead
136
+ // hypothesis "with the command output that killed it", and the verifier's
137
+ // whole report is `command · exit code · counts`. Without these keys that
138
+ // lands inside `proof` as prose, where nothing can query it.
139
+ finding: Object.freeze(['area', 'claim', 'proof', 'command', 'exit_code', 'id', 'ticket', 'confidence']),
133
140
  // The expiry spellings doctor reads, plus the human description agents
134
141
  // attach. Measured across every journal on a real machine, agents wrote
135
142
  // `expiry` 33 times, `purpose` 28, `story` 21, `text` 21 — none of them
@@ -229,6 +236,15 @@ export const CAPPED_DATA_KEYS = Object.freeze({
229
236
  detail: 2000,
230
237
  claim: 2000,
231
238
  proof: 2000,
239
+ // A finding's `command` is capped an order of magnitude tighter than the
240
+ // prose keys, and the number is measured rather than chosen: across
241
+ // `skills/`, `docs/`, `agents/`, CONTRIBUTING.md and CLAUDE.md this repo
242
+ // documents 86 shell commands — median 74 codepoints, p90 88, longest 123.
243
+ // 500 is four times the longest real command, so no genuine pipeline is
244
+ // refused; and it is far too small to hold pasted OUTPUT, which is the
245
+ // thing this key exists to keep out. A command is a pointer to evidence.
246
+ // Paste the output into the report, not into the journal.
247
+ command: 500,
232
248
  // The ask fields. They reach BOARD.md, board.html and the answer sheet, so
233
249
  // an uncapped one is a document-sized cell in three artefacts at once.
234
250
  question: 2000,
@@ -26,6 +26,15 @@
26
26
  * matches when either side's glob matches the other side as a literal. One
27
27
  * line of generosity instead of a second glob engine.
28
28
  *
29
+ * `supersedes` is the retirement mechanism, and the reason a store that only
30
+ * ever grows is not the only option. An entry named by any other entry's
31
+ * `supersedes` is dropped from every brief — so a merge is an APPEND: write
32
+ * the entry that says it better, name the ones it replaces, and touch nothing
33
+ * else. The replaced entries keep their bytes, their provenance and the
34
+ * counters they earned over months, which is what makes a bad merge cost one
35
+ * `git rm` instead of a history. Nothing in this file decides WHICH entries
36
+ * say the same thing; that is a judgement, and it stays the retro's.
37
+ *
29
38
  * CLI:
30
39
  * node knowledge.mjs brief [<path>...] [--dir .tyran/knowledge]
31
40
  * [--kinds fact,convention,gotcha,command,decision]
@@ -35,13 +44,25 @@
35
44
  import { existsSync, readdirSync, statSync, realpathSync } from 'node:fs';
36
45
  import { join, resolve } from 'node:path';
37
46
  import { fileURLToPath } from 'node:url';
38
- import { validateFile, globMatches, normalizePath, KNOWLEDGE_KINDS } from './schema.mjs';
47
+ import { validateFile, globMatches, normalizePath, supersededIds, KNOWLEDGE_KINDS } from './schema.mjs';
39
48
  import { escapeInvisible, jsonEscapeInvisible } from './invisible.mjs';
40
49
  import { wantsHelp } from './cli-args.mjs';
41
50
 
42
51
  export const DEFAULT_DIR = join('.tyran', 'knowledge');
43
52
  export const DEFAULT_BUDGET = 4000;
44
53
 
54
+ /**
55
+ * How many deliveries an entry gets before "never reported helpful" is
56
+ * evidence rather than absence of it.
57
+ *
58
+ * Deliberately NOT `mistakes.mjs`'s `KNOWLEDGE_THRESHOLD`, which is also 3:
59
+ * that one counts occurrences of a failure before a rule is earned, this one
60
+ * counts deliveries before silence is damning. Two numbers that happen to
61
+ * agree are not one constant, and importing it would mean tuning either
62
+ * changes the other.
63
+ */
64
+ export const RETIREMENT_THRESHOLD = 3;
65
+
45
66
  class UsageError extends Error {}
46
67
 
47
68
  /** Untrusted YAML value on its way into a terminal or a handoff: one line, visible. */
@@ -67,17 +88,49 @@ export function knowledgeFiles(dir) {
67
88
  export function loadEntries(dir) {
68
89
  const entries = [];
69
90
  const invalid = [];
91
+ // Ids are unique per FILE by the validator, which sees one document at a
92
+ // time. Only this loop ever sees the whole store, so a `K-12` in two files
93
+ // is a collision nothing else can catch — and `supersedes` names an id, so
94
+ // an ambiguous one silently retires whichever entry the loop reached first.
95
+ // Reported through `invalid` rather than a finding code of its own: both
96
+ // callers already refuse loudly on that channel.
97
+ const idOwner = new Map();
70
98
  for (const file of knowledgeFiles(dir)) {
71
99
  const result = validateFile('knowledge', file);
72
100
  if (!result.ok) {
73
101
  invalid.push({ file, errors: result.errors });
74
102
  continue;
75
103
  }
76
- for (const entry of result.doc.entries) entries.push({ ...entry, file });
104
+ const collisions = [];
105
+ for (const entry of result.doc.entries) {
106
+ const first = idOwner.get(entry.id);
107
+ if (first === undefined) idOwner.set(entry.id, file);
108
+ else collisions.push(`duplicate id "${entry.id}" — already defined in ${first}`);
109
+ entries.push({ ...entry, file });
110
+ }
111
+ if (collisions.length > 0) invalid.push({ file, errors: collisions });
77
112
  }
78
113
  return { entries, invalid };
79
114
  }
80
115
 
116
+ /**
117
+ * The ids no brief may carry: every id named by any entry's `supersedes`.
118
+ *
119
+ * Computed over the WHOLE store, never over a filtered subset. Scoped to the
120
+ * query instead, an entry retired by a narrowly-scoped superseder comes back
121
+ * from the dead on any brief whose paths miss that superseder — the store
122
+ * would then disagree with itself about what is retired, depending on what
123
+ * was asked. One flat set also resolves chains for free: C→A and A→B hides
124
+ * both A and B with no walk.
125
+ */
126
+ export function supersededSet(entries) {
127
+ const hidden = new Set();
128
+ for (const entry of entries) {
129
+ for (const id of supersededIds(entry)) hidden.add(id);
130
+ }
131
+ return hidden;
132
+ }
133
+
81
134
  /** Does this entry apply to any of the given repo paths? */
82
135
  export function entryMatches(entry, paths) {
83
136
  const globs = Array.isArray(entry.applies_to) ? entry.applies_to.filter((g) => typeof g === 'string') : [];
@@ -91,8 +144,14 @@ export function entryMatches(entry, paths) {
91
144
  * the same paths produce the same brief, byte for byte.
92
145
  */
93
146
  export function selectEntries(entries, { paths = [], kinds = null, limit = Infinity } = {}) {
147
+ const hidden = supersededSet(entries);
94
148
  const ranked = entries
95
149
  .map((entry, index) => ({ entry, index }))
150
+ // Before the kind and path filters, and computed from the full store —
151
+ // see `supersededSet`. This is what makes a merge non-destructive: the
152
+ // retired entry keeps its bytes and its counters on disk and simply
153
+ // stops being delivered.
154
+ .filter(({ entry }) => !hidden.has(entry.id))
96
155
  .filter(({ entry }) => kinds === null || kinds.includes(entry.kind))
97
156
  .filter(({ entry }) => (paths.length === 0 ? !Array.isArray(entry.applies_to) || entry.applies_to.length === 0 : entryMatches(entry, paths)))
98
157
  .sort((a, b) => (b.entry.confidence - a.entry.confidence) || (a.index - b.index))
@@ -167,15 +226,35 @@ export function renderBrief(selected, matched, { budget = DEFAULT_BUDGET, dir =
167
226
  * `alone` is the diagnostic that matters most: an entry that does not fit the
168
227
  * budget even as the ONLY entry can never appear in any brief, under any
169
228
  * paths, ever. It is not competing for space — it is unreachable.
229
+ *
230
+ * Every budget figure here counts LIVE entries only. `entries` still counts
231
+ * the whole store, because that is the number a reader can check against the
232
+ * files on disk; `live`/`superseded` is the split. An audit that charged the
233
+ * budget for entries no brief can deliver would under-report reachability
234
+ * exactly as consolidation started to work.
170
235
  */
171
236
  export function auditEntries(entries, { budget = DEFAULT_BUDGET } = {}) {
237
+ const hidden = supersededSet(entries);
238
+ const present = new Set(entries.map((e) => e.id));
172
239
  const sized = entries.map((entry) => {
173
240
  const cost = Array.from(entryLine(entry)).length + 1;
174
- return { id: entry.id, kind: entry.kind, confidence: entry.confidence, cost, alone: cost > budget };
241
+ return {
242
+ id: entry.id,
243
+ kind: entry.kind,
244
+ confidence: entry.confidence,
245
+ cost,
246
+ alone: cost > budget,
247
+ superseded: hidden.has(entry.id),
248
+ };
175
249
  });
250
+ // Every measurement against the budget is over LIVE entries only. Charging
251
+ // the budget for entries no brief can deliver would report a reachability
252
+ // that is fiction — and this number is the one `doctor --state` prints.
253
+ const live = sized.filter((e) => !e.superseded);
254
+ const retired = sized.filter((e) => e.superseded);
176
255
  // Ranked the way `brief` ranks, so "would reach a brief" means what a brief
177
256
  // would actually do rather than what this function finds convenient.
178
- const ranked = [...sized].sort((a, b) => (b.confidence ?? 0) - (a.confidence ?? 0));
257
+ const ranked = [...live].sort((a, b) => (b.confidence ?? 0) - (a.confidence ?? 0));
179
258
  let used = 0;
180
259
  let reachable = 0;
181
260
  for (const entry of ranked) {
@@ -183,21 +262,99 @@ export function auditEntries(entries, { budget = DEFAULT_BUDGET } = {}) {
183
262
  used += entry.cost;
184
263
  reachable += 1;
185
264
  }
186
- const total = sized.reduce((sum, e) => sum + e.cost, 0);
265
+ const total = live.reduce((sum, e) => sum + e.cost, 0);
266
+ // A `supersedes` naming an id nowhere in the store is the one mechanical
267
+ // way this whole design fails: the typo means the intended retirement did
268
+ // not happen, so the old entry keeps competing and the new one adds to the
269
+ // total. Silent, and in the direction of growth.
270
+ const dangling = [];
271
+ for (const entry of entries) {
272
+ for (const id of supersededIds(entry)) {
273
+ if (!present.has(id)) dangling.push({ id: entry.id, missing: id });
274
+ }
275
+ }
276
+ // A→B and B→A validates (neither supersedes itself) and hides BOTH, which
277
+ // empties two entries out of every brief at once. Named here rather than
278
+ // guarded in the selector.
279
+ const mutual = [];
280
+ for (const entry of entries) {
281
+ for (const id of supersededIds(entry)) {
282
+ const other = entries.find((e) => e.id === id);
283
+ if (other && supersededIds(other).includes(entry.id) && entry.id < id) {
284
+ mutual.push({ a: entry.id, b: id });
285
+ }
286
+ }
287
+ }
187
288
  return {
188
289
  budget,
290
+ // The whole store, so this still matches the file count on disk.
189
291
  entries: sized.length,
292
+ live: live.length,
293
+ superseded: retired.length,
294
+ supersededCost: retired.reduce((sum, e) => sum + e.cost, 0),
190
295
  // How many a single widest-possible brief could carry.
191
296
  reachable,
192
- unreachable: sized.length - reachable,
297
+ unreachable: live.length - reachable,
193
298
  // Entries too large to appear even alone — the ones pruning must address
194
299
  // first, because no budget any caller passes will rescue them.
195
- aloneTooBig: sized.filter((e) => e.alone).map((e) => ({ id: e.id, cost: e.cost })),
300
+ aloneTooBig: live.filter((e) => e.alone).map((e) => ({ id: e.id, cost: e.cost })),
301
+ danglingSupersedes: dangling,
302
+ mutualSupersedes: mutual,
303
+ ...retirementReport(entries, entries.filter((e) => !hidden.has(e.id))),
196
304
  totalCost: total,
197
- widest: sized.slice().sort((a, b) => b.cost - a.cost).slice(0, 5).map((e) => ({ id: e.id, cost: e.cost })),
305
+ widest: live.slice().sort((a, b) => b.cost - a.cost).slice(0, 5).map((e) => ({ id: e.id, cost: e.cost })),
198
306
  };
199
307
  }
200
308
 
309
+ /**
310
+ * Which live entries the COUNTERS have written off — the first thing that
311
+ * ever reads `used`/`helpful`/`outdated_reports`.
312
+ *
313
+ * Three surfaces already tell an agent to retire entries on this evidence
314
+ * (`agents/retro.md`, `skills/retro/SKILL.md`, and the audit's own trailing
315
+ * line), and nothing computed it. Same defect class as the consolidation
316
+ * promise corrected in 0.1.35, one field over.
317
+ *
318
+ * The degenerate case decides whether any of it means anything. The counters
319
+ * are maintained only by a model hand-editing YAML at retro close; if that
320
+ * fold is not happening every entry reads `helpful: 0` and the rule below
321
+ * would flag the entire store — confidently, and on no evidence at all. So a
322
+ * store with no counter evidence reports THAT and flags nothing: it is the
323
+ * more useful finding, and it is the true one.
324
+ */
325
+ export function retirementReport(all, live, { threshold = RETIREMENT_THRESHOLD } = {}) {
326
+ const n = (v) => (Number.isInteger(v) && v >= 0 ? v : 0);
327
+ // Evidence is asked of the WHOLE store, candidates only of the live part.
328
+ // Scoped to live alone, consolidating a counter-bearing entry away would
329
+ // flip this to "the fold is not happening" — a strong claim, and false:
330
+ // the fold plainly did happen, the entry it happened to is just retired
331
+ // now. The question this answers is whether the repo folds at all.
332
+ const hasEvidence = all.some(
333
+ (e) => n(e.used) > 0 || n(e.helpful) > 0 || n(e.outdated_reports) > 0,
334
+ );
335
+ if (!hasEvidence) return { counterEvidence: false, retirementCandidates: [] };
336
+ const candidates = [];
337
+ for (const entry of live) {
338
+ const used = n(entry.used);
339
+ const helpful = n(entry.helpful);
340
+ const wrong = n(entry.outdated_reports);
341
+ // Reported wrong more often than it helped: the strongest evidence there
342
+ // is, and the remedy may be to correct it rather than retire it.
343
+ if (wrong > helpful) {
344
+ candidates.push({ id: entry.id, reason: 'reported-wrong', used, helpful, outdated_reports: wrong });
345
+ continue;
346
+ }
347
+ // Delivered enough times to have had its chance, and never once helped.
348
+ // The threshold is the whole point: `used: 1, helpful: 0` is an entry
349
+ // nobody has had the opportunity to find useful, which is not evidence
350
+ // of anything.
351
+ if (used >= threshold && helpful === 0) {
352
+ candidates.push({ id: entry.id, reason: 'never-helpful', used, helpful, outdated_reports: wrong });
353
+ }
354
+ }
355
+ return { counterEvidence: true, retirementCandidates: candidates };
356
+ }
357
+
201
358
  // ---------------------------------------------------------------- CLI
202
359
 
203
360
  const VALUE_FLAGS = ['dir', 'kinds', 'limit', 'budget'];
@@ -302,10 +459,48 @@ function main() {
302
459
  }
303
460
  const out = [
304
461
  `knowledge audit (${escapeInvisible(flags.dir)})`,
305
- ` ${report.entries} entries, ${report.totalCost} codepoints total`,
462
+ ` ${report.entries} entries on disk, ${report.live} live, ${report.totalCost} codepoints total`,
306
463
  ` ${report.reachable} could reach one brief at the ${report.budget}-codepoint budget; ` +
307
464
  `${report.unreachable} could not`,
308
465
  ];
466
+ if (report.superseded > 0) {
467
+ // The whole prune feature, as a line of output. Once an entry is
468
+ // invisible to briefs, deleting it has provably zero behavioural
469
+ // effect — so a prune SUBCOMMAND would be building the destructive
470
+ // operation this design exists to avoid, to save one `git rm`.
471
+ out.push(
472
+ ` ${report.superseded} superseded (${report.supersededCost} codepoints) — retired from every ` +
473
+ 'brief, still on disk with their counters; delete them whenever you like',
474
+ );
475
+ }
476
+ if (report.danglingSupersedes.length > 0) {
477
+ out.push(' supersedes naming an id that is not in this store — the retirement did NOT happen:');
478
+ for (const d of report.danglingSupersedes) {
479
+ out.push(` ${escapeInvisible(d.id)} -> ${escapeInvisible(d.missing)}`);
480
+ }
481
+ }
482
+ if (report.mutualSupersedes.length > 0) {
483
+ out.push(' mutually superseding pairs — BOTH are hidden from every brief:');
484
+ for (const m of report.mutualSupersedes) {
485
+ out.push(` ${escapeInvisible(m.a)} <-> ${escapeInvisible(m.b)}`);
486
+ }
487
+ }
488
+ if (!report.counterEvidence) {
489
+ out.push(
490
+ ' no entry carries counter evidence — the fold at retro close is not happening,',
491
+ );
492
+ out.push(
493
+ ' so nothing here can be retired on evidence yet (see skills/retro/SKILL.md)',
494
+ );
495
+ } else if (report.retirementCandidates.length > 0) {
496
+ out.push(' retirement candidates, on the counters rather than on taste:');
497
+ for (const c of report.retirementCandidates) {
498
+ const why = c.reason === 'reported-wrong'
499
+ ? `reported wrong ${c.outdated_reports}x against ${c.helpful} helpful`
500
+ : `delivered ${c.used}x, never once reported helpful`;
501
+ out.push(` ${escapeInvisible(c.id)} — ${why}`);
502
+ }
503
+ }
309
504
  if (report.aloneTooBig.length > 0) {
310
505
  const n = report.aloneTooBig.length;
311
506
  out.push(` ${n} entr${n === 1 ? 'y' : 'ies'} cannot appear in ANY brief, even alone:`);
@@ -317,18 +512,22 @@ function main() {
317
512
  }
318
513
  // A measurement, never an edit: which of two overlapping entries is the
319
514
  // true one is a judgement, and a script that guessed would delete the
320
- // hard-won detail this exists to protect.
515
+ // hard-won detail this exists to protect. That has not changed — nothing
516
+ // below scores similarity or picks a winner.
517
+ //
518
+ // What HAS changed is that the merge now has a mechanism to be performed
519
+ // WITH. These lines named a consolidation step that did not exist until
520
+ // 0.1.35 corrected them; they may name one again only because
521
+ // `selectEntries` genuinely suppresses a superseded id, which the guard
522
+ // test in tests/unit/knowledge.test.mjs now checks by running a brief
523
+ // rather than by grepping for an export name.
321
524
  //
322
- // This line used to promise that `/tyran:retro` consolidates, writing a
323
- // new file for review. It does not, and never has: grep the skill and the
324
- // agent and there is no consolidation step in either. What the retro
325
- // really does to this store is COUNTER upkeep — folding each report's
326
- // brief verdicts in, retiring an entry the counters have written off, and
327
- // splitting one `doctor` calls oversized. Merging two overlapping entries
328
- // is nobody's job yet. Saying so is the point: a tool that names a
329
- // downstream step by name is the last place a reader will doubt it.
330
- out.push(' This reports; it never edits. Nothing merges overlapping entries yet — /tyran:retro');
331
- out.push(' keeps the counters, retires what stopped earning its keep, and splits what is oversized.');
525
+ // The shape is what makes it safe to state plainly: consolidation APPENDS
526
+ // an entry naming the ones it replaces. No existing file is edited, the
527
+ // retired entries keep their counters, and the undo is deleting one file.
528
+ out.push(' This reports; it never edits. Consolidation is a /tyran:retro judgement, performed by');
529
+ out.push(' APPENDING an entry whose supersedes: names the ones it replaces — the originals keep');
530
+ out.push(' their bytes and counters, and deleting that one file brings them all back.');
332
531
  process.stdout.write(out.join('\n') + '\n');
333
532
  process.exitCode = 0;
334
533
  return;
@@ -571,6 +571,12 @@ export function fold({ events = [], truncatedTail = false, badLines = [] } = {})
571
571
  area: data.area ?? null,
572
572
  claim: data.claim ?? null,
573
573
  proof: data.proof ?? null,
574
+ // The command that produced the claim, and what it exited with. Kept
575
+ // beside `proof` rather than folded into it: a reader can re-RUN a
576
+ // command, which is the one thing a sentence about a command can
577
+ // never offer.
578
+ command: data.command ?? null,
579
+ exit_code: data.exit_code ?? null,
574
580
  ticket: data.ticket ?? null,
575
581
  confidence: data.confidence ?? null,
576
582
  ts,
@@ -1247,12 +1253,14 @@ function renderState(state) {
1247
1253
  parts.push('\n## Findings\n\n');
1248
1254
  parts.push(
1249
1255
  table(
1250
- ['Id', 'Area', 'Claim', 'Proof', 'Ticket', 'By', 'At'],
1256
+ ['Id', 'Area', 'Claim', 'Proof', 'Command', 'Exit', 'Ticket', 'By', 'At'],
1251
1257
  state.findings.map((f) => [
1252
1258
  inline(f.id),
1253
1259
  inline(f.area),
1254
1260
  inline(f.claim),
1255
1261
  inline(f.proof),
1262
+ inline(f.command),
1263
+ inline(f.exit_code),
1256
1264
  inline(f.ticket),
1257
1265
  inline(f.actor),
1258
1266
  inline(f.ts),
@@ -455,13 +455,48 @@ export function validateKnowledge(doc) {
455
455
  if ('applies_to' in entry && !Array.isArray(entry.applies_to)) {
456
456
  errors.push(`${at}.applies_to: must be a list of path globs`);
457
457
  }
458
- if ('supersedes' in entry && !isNonEmptyString(entry.supersedes)) {
459
- errors.push(`${at}.supersedes: must be an entry id`);
458
+ // A LIST as well as a scalar, because consolidation is many-to-one by
459
+ // definition: a merged entry that could retire only one predecessor
460
+ // cannot express the merge it was written to record. The scalar form
461
+ // stays legal — every entry written before this read as one id.
462
+ if ('supersedes' in entry) {
463
+ const ids = entry.supersedes;
464
+ if (isNonEmptyString(ids)) {
465
+ if (ids === entry.id) errors.push(`${at}.supersedes: an entry cannot supersede itself`);
466
+ } else if (Array.isArray(ids)) {
467
+ if (ids.length === 0) {
468
+ errors.push(`${at}.supersedes: must name at least one entry id`);
469
+ }
470
+ ids.forEach((id, j) => {
471
+ if (!isNonEmptyString(id)) errors.push(`${at}.supersedes[${j}]: must be an entry id`);
472
+ else if (id === entry.id) errors.push(`${at}.supersedes[${j}]: an entry cannot supersede itself`);
473
+ });
474
+ } else {
475
+ errors.push(`${at}.supersedes: must be an entry id, or a list of entry ids`);
476
+ }
460
477
  }
461
478
  });
462
479
  return errors;
463
480
  }
464
481
 
482
+ /**
483
+ * The ids an entry retires, whatever spelling it used. One home for the
484
+ * string-or-list branch: `selectEntries` and `auditEntries` both need it, and
485
+ * a second hand-rolled `Array.isArray` check is how the two would drift into
486
+ * disagreeing about which entries a brief may carry.
487
+ *
488
+ * Self-supersede is a validator error rather than something callers filter,
489
+ * so this never has to defend against the one-entry cycle. A MUTUAL pair
490
+ * (A→B, B→A) still validates and is reported by `knowledge.mjs audit` — a
491
+ * cheap named line beats teaching the selector graph theory.
492
+ */
493
+ export function supersededIds(entry) {
494
+ const ids = entry?.supersedes;
495
+ if (typeof ids === 'string') return ids.trim() === '' ? [] : [ids];
496
+ if (Array.isArray(ids)) return ids.filter((id) => typeof id === 'string' && id.trim() !== '');
497
+ return [];
498
+ }
499
+
465
500
  /**
466
501
  * The size above which a knowledge entry stops being a brief-able fact and
467
502
  * starts being a document. `knowledge.mjs brief` selects entries into a
@@ -1,5 +1,5 @@
1
1
  ---
2
- description: Drive a real browser and come back with a MEASUREMENT rather than an impression - deterministic waits instead of sleeps, console errors and >=400 responses as counts, computed styles dumped to JSON when appearance is disputed. Use when work touches UI, when a review must verify one, or when fidelity-gate asks for its measurement.
2
+ description: Drive a real browser and come back with a MEASUREMENT rather than an impression - console errors and >=400 responses as counts, computed styles as JSON when appearance is disputed. Use when work touches UI, when a review must verify one, or when fidelity-gate asks for its measurement.
3
3
  ---
4
4
 
5
5
  # Browser check — proving a UI works, in numbers
@@ -1,5 +1,5 @@
1
1
  ---
2
- description: The depth half of a review - the dimensions a diff is read against (correctness, boundaries, concurrency, failure paths, secrets, test quality, lifecycle) and the rule that a finding is refuted before it is reported. The verdict itself stays with the reviewer agent. Use when reviewing a diff or a pull request.
2
+ description: The depth half of a review - the dimensions a diff is read against (correctness, boundaries, concurrency, failure paths, secrets, test quality) and the rule that a finding is refuted before it is reported. The verdict stays with the reviewer agent. Use when reviewing a diff or a pull request.
3
3
  ---
4
4
 
5
5
  # Code review — reading depth
@@ -1,5 +1,5 @@
1
1
  ---
2
- description: The optimization pass, defined - delete before you add, one smell class per pass, behaviour pinned by a test that ran BEFORE the edit and again after. Lints a SKILL.md and prose by the same instinct. Use for the per-story optimization pass, before promoting a skill, or when code has grown noisy without growing capable.
2
+ description: The optimization pass, defined - delete before you add, one smell class per pass, behaviour pinned by a test that ran BEFORE the edit. Lints a SKILL.md and prose by the same instinct. Use for the per-story optimization pass or when code has grown noisy without growing capable.
3
3
  ---
4
4
 
5
5
  # Deslop — the pass that removes rather than adds
@@ -1,5 +1,5 @@
1
1
  ---
2
- description: Build a UI against a frozen visual reference without drift. An inventory extracted from the reference before any code, a relics list for what exists but should not, and a gate that MEASURES rather than judges - computed styles on a fixture carrying the reference's own data. Use when a mockup, design spec or screenshot is the contract.
2
+ description: Build a UI against a frozen visual reference without drift - an inventory extracted before any code, a relics list, and a gate that MEASURES computed styles on a fixture carrying the reference's own data. Use when a mockup, design spec or screenshot is the contract.
3
3
  ---
4
4
 
5
5
  # Fidelity gate — building against a frozen visual reference