@jjanczur/tyran 0.1.40 → 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.
- package/.claude-plugin/marketplace.json +1 -1
- package/.claude-plugin/plugin.json +1 -1
- package/CHANGELOG.md +210 -0
- package/README.md +5 -2
- package/agents/implementer.md +5 -2
- package/agents/retro.md +9 -6
- package/agents/reviewer.md +3 -1
- package/agents/scout.md +2 -1
- package/agents/verifier.md +2 -1
- package/bin/tyran.mjs +1 -1
- package/package.json +4 -1
- package/scripts/board-html.mjs +264 -19
- package/scripts/board.mjs +134 -6
- package/scripts/doctor.mjs +116 -4
- package/scripts/journal.mjs +17 -1
- package/scripts/knowledge.mjs +219 -20
- package/scripts/project.mjs +9 -1
- package/scripts/schema.mjs +37 -2
- package/skills/retro/SKILL.md +26 -0
- package/skills/run/SKILL.md +4 -2
- package/templates/knowledge.yaml +5 -0
package/scripts/doctor.mjs
CHANGED
|
@@ -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.
|
|
769
|
-
`${report.budget}-codepoint budget; ${report.unreachable} cannot.${detail} The store
|
|
770
|
-
'by every retrospective and read through that budget, so what does not fit is not
|
|
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
|
//
|
package/scripts/journal.mjs
CHANGED
|
@@ -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
|
-
|
|
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,
|
package/scripts/knowledge.mjs
CHANGED
|
@@ -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
|
-
|
|
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 {
|
|
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 = [...
|
|
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 =
|
|
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:
|
|
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:
|
|
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:
|
|
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
|
-
//
|
|
323
|
-
//
|
|
324
|
-
//
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
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;
|
package/scripts/project.mjs
CHANGED
|
@@ -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),
|
package/scripts/schema.mjs
CHANGED
|
@@ -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
|
-
|
|
459
|
-
|
|
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
|
package/skills/retro/SKILL.md
CHANGED
|
@@ -66,6 +66,32 @@ here, at close, in the one place licensed to write these files. Keep entries
|
|
|
66
66
|
under the size `doctor --state` warns about (`knowledge-entry-oversized`,
|
|
67
67
|
4 000 codepoints); an oversized entry crowds every brief it matches.
|
|
68
68
|
|
|
69
|
+
**Then consolidate — by APPENDING, never by editing.** Read the audit:
|
|
70
|
+
|
|
71
|
+
```bash
|
|
72
|
+
node "${CLAUDE_PLUGIN_ROOT}/scripts/knowledge.mjs" audit --dir .tyran/knowledge
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
It names the retirement candidates the counters have written off, and — if it
|
|
76
|
+
says no entry carries counter evidence — that the fold above is not actually
|
|
77
|
+
happening, which is the finding to act on first.
|
|
78
|
+
|
|
79
|
+
Deciding that two entries say the same thing is YOUR judgement; no script
|
|
80
|
+
scores it. Recording that decision is mechanical: write a **new** file,
|
|
81
|
+
`.tyran/knowledge/<slug>-merged.yaml`, whose entry states the fact once and
|
|
82
|
+
carries `supersedes:` naming every id it replaces, plus the union of their
|
|
83
|
+
`provenance`. **Do not touch the files holding the originals.** They keep
|
|
84
|
+
their bytes and the counters they earned over months, and stop reaching briefs
|
|
85
|
+
because `supersedes` retires them at read time. An entry the counters have
|
|
86
|
+
written off with nothing to replace it is a plain deletion — git holds the
|
|
87
|
+
bytes, and the counters are the argument.
|
|
88
|
+
|
|
89
|
+
Re-run the audit. Superseded should be up, `live` down, reachability up, and
|
|
90
|
+
**dangling zero** — a `supersedes` naming an id that is not in the store means
|
|
91
|
+
the retirement silently did not happen and the merge only made the store
|
|
92
|
+
bigger. Undo, if the merge was wrong, is deleting that one file: every entry
|
|
93
|
+
it retired comes back whole.
|
|
94
|
+
|
|
69
95
|
Write what a competent newcomer would get wrong, not what the code already
|
|
70
96
|
says. "The test suite takes 9 minutes, so do not run it per file" is worth an
|
|
71
97
|
entry. "This is a Next.js app" is not: the next agent can see that.
|