@openagentsy/hooks 0.0.0-stage → 0.2.1

package/dist/lessons/model.d.ts

@@ -0,0 +1,163 @@
+import type { EvalResult } from '../eval/types.js';
+export type { EvalResult };
+/**
+ * The lesson model.
+ *
+ * A lesson is a claim about behaviour that a person has not decided on yet.
+ * It starts as a candidate and it only becomes a fact through states, and
+ * every state is a gate:
+ *
+ * - a candidate cannot leave without a start packet that says what should
+ *   happen differently, what would show it, and who owns the change;
+ * - a validated lesson needs a passing eval result, because a claim with no
+ *   proof is an opinion;
+ * - an applied lesson needs an owner and a change reference, because a change
+ *   nobody owns is a change nobody can roll back.
+ */
+/** Every state a lesson can be in. */
+export declare const LESSON_STATES: readonly ["candidate", "validated", "applied", "rejected", "superseded", "rolled_back", "no_delta", "open_question"];
+export type LessonState = (typeof LESSON_STATES)[number];
+/**
+ * Who holds the change.
+ *
+ * The owner is the narrowest thing that can hold the lesson, in this order:
+ * a test or a validator, the owning skill or role file, the project
+ * instructions, a memory note. The last two are the ones that cannot be
+ * enforced in code, so they need a reason.
+ */
+export type Owner = `test:${string}` | `validator:${string}` | `skill:${string}` | `role:${string}` | 'instructions' | 'memory';
+/**
+ * The packet that says what a lesson asks for.
+ *
+ * It is what the person reads before deciding, so every field is a question
+ * that has an answer: what should happen differently, which task would show
+ * it, what is the evidence, who owns the change, which files may change and
+ * where the proof is.
+ */
+export interface StartPacket {
+    /** What the agent should do differently next time. */
+    futureBehavior: string;
+    /** One concrete scenario that should now succeed. */
+    representativeTask: string;
+    /** The ledger waste ids, the session ids, the failing test, the correction. */
+    evidence: string[];
+    /** Exactly one durable owner. */
+    owner: Owner;
+    /** Why code or a skill cannot hold the lesson. Needed for a weak owner. */
+    ownerJustification?: string;
+    /** The files the change may touch. */
+    writeBoundary: string[];
+    /** The path to an eval artifact, or to an evals/ suite. */
+    proof: string;
+}
+/** One decision, and the state it moved the lesson to. */
+export interface Transition {
+    from: LessonState;
+    to: LessonState;
+    /** Who decided. */
+    decidedBy: string;
+    /** Why. */
+    reason: string;
+    /** ISO 8601. */
+    ts: string;
+    /** The commit or the change the decision names. */
+    changeRef?: string;
+    /** Whether the eval result passed, when one was part of the decision. */
+    evalPassed?: boolean;
+}
+/**
+ * A lesson.
+ *
+ * The summary says what happened, the occurrences say how often, and the
+ * history says who decided what. A count is not evidence: a lesson that
+ * happened often is still a claim.
+ */
+export interface Lesson {
+    id: string;
+    state: LessonState;
+    summary: string;
+    occurrences: number;
+    packet: Partial<StartPacket>;
+    history: Transition[];
+    /** The waste kind the lesson came from. */
+    kind: string;
+    /** The detail of the waste, normalised into the shape it was compared by. */
+    detail: string;
+    /** The sessions the waste was seen in. */
+    sessions: string[];
+    /** ISO 8601. */
+    created_at: string;
+    /** ISO 8601. */
+    updated_at: string;
+}
+/**
+ * A decision about a lesson.
+ *
+ * The decision is the person's, and it says who made it: an agent may
+ * propose, but the map keeps it from deciding.
+ */
+export interface Decision {
+    decidedBy: string;
+    reason: string;
+    /** The proof, when the decision rests on one. */
+    evalResult?: EvalResult;
+    /** The change the decision names, when it applies one. */
+    changeRef?: string;
+}
+/**
+ * The error the lesson model raises.
+ *
+ * It carries a hint, like every other error here: the message says what
+ * happened, the hint says what to do next.
+ */
+export declare class LessonError extends Error {
+    readonly hint: string;
+    constructor(message: string, hint: string);
+}
+/**
+ * Whether a value names an owner.
+ */
+export declare function isOwner(value: unknown): value is Owner;
+/**
+ * Whether the owner is one that cannot hold the lesson in code.
+ */
+export declare function isWeakOwner(owner: Owner): boolean;
+/**
+ * Whether the packet says everything it has to say.
+ *
+ * A weak owner needs its reason: an instruction or a memory note holds a
+ * lesson that code cannot, and the person has to read why.
+ */
+export declare function packetComplete(packet: Partial<StartPacket>): boolean;
+/**
+ * The states a lesson may move to from where it is.
+ */
+export declare function nextStates(state: LessonState): LessonState[];
+/**
+ * Move a lesson to another state.
+ *
+ * The move throws in four cases, and only in these four:
+ *
+ * - the move is not one the lifecycle allows;
+ * - the move is not a rejection while the start packet is incomplete, so a
+ *   candidate cannot leave without saying what it asks for;
+ * - the move validates without a passing eval result;
+ * - the move applies without an owner and a change reference.
+ */
+export declare function transition(lesson: Lesson, to: LessonState, decision: Decision, now?: () => Date): Lesson;
+/**
+ * A text as the dedup sees it: lowercased, whitespace collapsed, and
+ * without the punctuation that carries no meaning.
+ *
+ * The summary of a lesson and the detail of a waste are both compared this
+ * way, so "Read the file." and "read the file" are one lesson.
+ */
+export declare function normalizeText(text: string): string;
+/**
+ * Whether a proof points at an evals/ suite rather than at an artifact.
+ *
+ * A suite runs through the safety suite's own runner, so it is judged by
+ * three runs instead of one.
+ */
+export declare function isSuiteProof(proof: string): boolean;
+//# sourceMappingURL=model.d.ts.map

package/dist/lessons/model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../../src/lessons/model.ts"],"names":[],"mappings":"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"}

package/dist/lessons/model.js

@@ -0,0 +1,181 @@
+/**
+ * The lesson model.
+ *
+ * A lesson is a claim about behaviour that a person has not decided on yet.
+ * It starts as a candidate and it only becomes a fact through states, and
+ * every state is a gate:
+ *
+ * - a candidate cannot leave without a start packet that says what should
+ *   happen differently, what would show it, and who owns the change;
+ * - a validated lesson needs a passing eval result, because a claim with no
+ *   proof is an opinion;
+ * - an applied lesson needs an owner and a change reference, because a change
+ *   nobody owns is a change nobody can roll back.
+ */
+/** Every state a lesson can be in. */
+export const LESSON_STATES = [
+    'candidate',
+    'validated',
+    'applied',
+    'rejected',
+    'superseded',
+    'rolled_back',
+    'no_delta',
+    'open_question',
+];
+/**
+ * The states each state may move to.
+ *
+ * The map is the whole of the lifecycle. A state with no entry in it is
+ * final: a rejected lesson, a rolled back one and a superseded one are
+ * history, and a history is not edited.
+ */
+const NEXT = {
+    candidate: ['validated', 'rejected', 'open_question', 'no_delta'],
+    open_question: ['candidate', 'rejected'],
+    validated: ['applied', 'rejected'],
+    applied: ['superseded', 'rolled_back'],
+    rejected: [],
+    superseded: [],
+    rolled_back: [],
+    no_delta: [],
+};
+/** The owners that cannot enforce anything, so they need a reason. */
+const WEAK_OWNERS = ['instructions', 'memory'];
+/**
+ * The error the lesson model raises.
+ *
+ * It carries a hint, like every other error here: the message says what
+ * happened, the hint says what to do next.
+ */
+export class LessonError extends Error {
+    hint;
+    constructor(message, hint) {
+        super(message);
+        this.name = 'LessonError';
+        this.hint = hint;
+    }
+}
+/**
+ * Whether a value names an owner.
+ */
+export function isOwner(value) {
+    if (typeof value !== 'string' || value.length === 0)
+        return false;
+    if (WEAK_OWNERS.includes(value))
+        return true;
+    return /^(test|validator|skill|role):\S+$/.test(value);
+}
+/**
+ * Whether the owner is one that cannot hold the lesson in code.
+ */
+export function isWeakOwner(owner) {
+    return WEAK_OWNERS.includes(owner);
+}
+/**
+ * Whether a value says something.
+ */
+function hasContent(value) {
+    return typeof value === 'string' && value.trim() !== '';
+}
+/**
+ * Whether a list holds something.
+ *
+ * An empty entry is nothing: a list of empty strings says no more than an
+ * empty list, and a packet that says no more than nothing is not complete.
+ */
+function hasItems(values) {
+    return Array.isArray(values) && values.length > 0 && values.every(hasContent);
+}
+/**
+ * Whether the packet says everything it has to say.
+ *
+ * A weak owner needs its reason: an instruction or a memory note holds a
+ * lesson that code cannot, and the person has to read why.
+ */
+export function packetComplete(packet) {
+    const owner = packet.owner;
+    if (!isOwner(owner))
+        return false;
+    if (!hasContent(packet.futureBehavior) || !hasContent(packet.representativeTask))
+        return false;
+    if (!hasItems(packet.evidence) || !hasItems(packet.writeBoundary))
+        return false;
+    if (!hasContent(packet.proof))
+        return false;
+    if (isWeakOwner(owner) && !hasContent(packet.ownerJustification))
+        return false;
+    return true;
+}
+/**
+ * The states a lesson may move to from where it is.
+ */
+export function nextStates(state) {
+    return NEXT[state];
+}
+/**
+ * Move a lesson to another state.
+ *
+ * The move throws in four cases, and only in these four:
+ *
+ * - the move is not one the lifecycle allows;
+ * - the move is not a rejection while the start packet is incomplete, so a
+ *   candidate cannot leave without saying what it asks for;
+ * - the move validates without a passing eval result;
+ * - the move applies without an owner and a change reference.
+ */
+export function transition(lesson, to, decision, now = () => new Date()) {
+    if (!NEXT[lesson.state].includes(to)) {
+        throw new LessonError(`illegal lesson transition ${lesson.state} → ${to}`, `a lesson can move to ${NEXT[lesson.state].join(', ') || 'nothing'}`);
+    }
+    if (to !== 'rejected' && to !== 'no_delta' && !packetComplete(lesson.packet)) {
+        throw new LessonError('the start packet is incomplete', 'a lesson needs a future behaviour, a representative task, evidence, an owner, a write boundary and a proof');
+    }
+    if (to === 'validated' && decision.evalResult?.passed !== true) {
+        throw new LessonError('validation needs a passing eval result for this lesson', 'run the proof and hand the result to the decision');
+    }
+    if (to === 'applied' && (!decision.changeRef || !lesson.packet.owner)) {
+        throw new LessonError('apply needs one owner and a change reference', 'name the commit or the change that carries the lesson, and the owner that holds it');
+    }
+    const stamp = now().toISOString();
+    const entry = {
+        from: lesson.state,
+        to,
+        decidedBy: decision.decidedBy,
+        reason: decision.reason,
+        ts: stamp,
+        ...(decision.changeRef === undefined ? {} : { changeRef: decision.changeRef }),
+        ...(decision.evalResult === undefined ? {} : { evalPassed: decision.evalResult.passed }),
+    };
+    return {
+        ...lesson,
+        state: to,
+        history: [...lesson.history, entry],
+        updated_at: stamp,
+    };
+}
+/**
+ * A text as the dedup sees it: lowercased, whitespace collapsed, and
+ * without the punctuation that carries no meaning.
+ *
+ * The summary of a lesson and the detail of a waste are both compared this
+ * way, so "Read the file." and "read the file" are one lesson.
+ */
+export function normalizeText(text) {
+    return text
+        .toLowerCase()
+        .replace(/[^a-z0-9\s]+/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+/**
+ * Whether a proof points at an evals/ suite rather than at an artifact.
+ *
+ * A suite runs through the safety suite's own runner, so it is judged by
+ * three runs instead of one.
+ */
+export function isSuiteProof(proof) {
+    const segments = proof.split(/[\\/]+/).filter((segment) => segment.length > 0);
+    return segments.includes('evals');
+}
+//# sourceMappingURL=model.js.map

package/dist/lessons/model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.js","sourceRoot":"","sources":["../../src/lessons/model.ts"],"names":[],"mappings":"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"}

package/dist/lessons/model.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=model.test.d.ts.map

package/dist/lessons/model.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.test.d.ts","sourceRoot":"","sources":["../../src/lessons/model.test.ts"],"names":[],"mappings":""}

package/dist/lessons/model.test.js

@@ -0,0 +1,178 @@
+import { describe, expect, it } from 'vitest';
+import { isSuiteProof, LESSON_STATES, normalizeText, packetComplete, transition, } from './model.js';
+/**
+ * The transition table, as the plan gives it.
+ *
+ * It is written as one string so the test does not copy the shape of the
+ * source: the table is the specification, and a test that reads the
+ * specification says what is allowed.
+ */
+const ALLOWED = 'candidate=validated,rejected,open_question,no_delta;' +
+    'open_question=candidate,rejected;' +
+    'validated=applied,rejected;' +
+    'applied=superseded,rolled_back';
+function allowedFrom(state) {
+    const entry = ALLOWED.split(';').find((part) => part.startsWith(`${state}=`));
+    if (entry === undefined)
+        return [];
+    return entry.slice(`${state}=`.length).split(',');
+}
+/** A packet that says everything it has to say. */
+function completePacket() {
+    return {
+        futureBehavior: 'read the file before writing to it',
+        representativeTask: 'the agent writes to a file that does not exist',
+        evidence: ['session-1'],
+        owner: 'test:missing-file',
+        writeBoundary: ['packages/hooks/src/**'],
+        proof: 'evals/missing-file.json',
+    };
+}
+/** A lesson in a state, with a packet that is complete unless told otherwise. */
+function lessonIn(state, packet) {
+    return {
+        id: 'oa-lesson-test0001',
+        state,
+        summary: 'the file was missing',
+        occurrences: 1,
+        packet: packet ?? completePacket(),
+        history: [],
+        kind: 'missing-file',
+        detail: 'the file was missing',
+        sessions: ['session-1'],
+        created_at: '2026-10-27T00:00:00.000Z',
+        updated_at: '2026-10-27T00:00:00.000Z',
+    };
+}
+/** A passing proof. */
+function passingResult(runs = 3) {
+    return {
+        schema_version: '1',
+        lesson_id: 'oa-lesson-test0001',
+        artifact_sha256: 'a'.repeat(64),
+        started_at: '2026-10-27T00:00:00.000Z',
+        finished_at: '2026-10-27T00:00:01.000Z',
+        passed: true,
+        runs,
+        scenarios: [],
+    };
+}
+/** A decision that satisfies the guard of the move it makes. */
+function decisionFor(to) {
+    return {
+        decidedBy: 'human',
+        reason: 'because',
+        ...(to === 'validated' ? { evalResult: passingResult() } : {}),
+        ...(to === 'applied' ? { changeRef: 'abc1234' } : {}),
+    };
+}
+describe('the transition table', () => {
+    for (const from of LESSON_STATES) {
+        for (const to of LESSON_STATES) {
+            it(`${from} to ${to} ${allowedFrom(from).includes(to) ? 'succeeds' : 'throws'}`, () => {
+                const lesson = lessonIn(from);
+                if (allowedFrom(from).includes(to)) {
+                    const moved = transition(lesson, to, decisionFor(to));
+                    expect(moved.state).toBe(to);
+                    expect(moved.history).toHaveLength(1);
+                    expect(moved.history[0]?.from).toBe(from);
+                    expect(moved.history[0]?.to).toBe(to);
+                    expect(moved.history[0]?.decidedBy).toBe('human');
+                }
+                else {
+                    expect(() => transition(lesson, to, decisionFor(to))).toThrow(/illegal lesson transition/);
+                }
+            });
+        }
+    }
+});
+describe('the start packet', () => {
+    it('is complete when it says everything it has to say', () => {
+        expect(packetComplete(completePacket())).toBe(true);
+    });
+    it('is incomplete without a future behaviour', () => {
+        expect(packetComplete({ ...completePacket(), futureBehavior: '  ' })).toBe(false);
+    });
+    it('is incomplete without a representative task', () => {
+        expect(packetComplete({ ...completePacket(), representativeTask: '' })).toBe(false);
+    });
+    it('is incomplete without evidence', () => {
+        expect(packetComplete({ ...completePacket(), evidence: [] })).toBe(false);
+    });
+    it('is incomplete without an owner', () => {
+        const { owner: _owner, ...packet } = completePacket();
+        expect(packetComplete(packet)).toBe(false);
+    });
+    it('is incomplete without a write boundary', () => {
+        expect(packetComplete({ ...completePacket(), writeBoundary: [] })).toBe(false);
+    });
+    it('is incomplete with an empty entry in a list', () => {
+        expect(packetComplete({ ...completePacket(), evidence: [''] })).toBe(false);
+        expect(packetComplete({ ...completePacket(), writeBoundary: ['   '] })).toBe(false);
+    });
+    it('is incomplete without a proof', () => {
+        expect(packetComplete({ ...completePacket(), proof: '' })).toBe(false);
+    });
+    it('needs a reason for an instructions owner', () => {
+        expect(packetComplete({ ...completePacket(), owner: 'instructions' })).toBe(false);
+        expect(packetComplete({
+            ...completePacket(),
+            owner: 'instructions',
+            ownerJustification: 'no test can hold this',
+        })).toBe(true);
+    });
+    it('needs a reason for a memory owner', () => {
+        expect(packetComplete({ ...completePacket(), owner: 'memory' })).toBe(false);
+    });
+});
+describe('the transition', () => {
+    it('does not let an incomplete packet leave a candidate', () => {
+        const candidate = lessonIn('candidate', { futureBehavior: 'read the file first' });
+        expect(() => transition(candidate, 'validated', decisionFor('validated'))).toThrow(/start packet is incomplete/);
+        expect(() => transition(candidate, 'open_question', decisionFor('open_question'))).toThrow(/start packet is incomplete/);
+    });
+    it('lets a candidate be rejected and marked as no delta without a packet', () => {
+        const candidate = lessonIn('candidate', {});
+        expect(transition(candidate, 'rejected', decisionFor('rejected')).state).toBe('rejected');
+        expect(transition(candidate, 'no_delta', decisionFor('no_delta')).state).toBe('no_delta');
+    });
+    it('does not validate without a passing eval result', () => {
+        const candidate = lessonIn('candidate');
+        expect(() => transition(candidate, 'validated', { decidedBy: 'human', reason: 'because' })).toThrow(/validation needs a passing eval result/);
+        expect(() => transition(candidate, 'validated', {
+            decidedBy: 'human',
+            reason: 'because',
+            evalResult: passingResult(),
+        })).not.toThrow();
+    });
+    it('does not apply without a change reference', () => {
+        const validated = lessonIn('validated');
+        expect(() => transition(validated, 'applied', { decidedBy: 'human', reason: 'because' })).toThrow(/apply needs one owner and a change reference/);
+    });
+    it('does not apply without an owner', () => {
+        const { owner: _owner, ...packet } = completePacket();
+        const validated = lessonIn('validated', packet);
+        expect(() => transition(validated, 'applied', { decidedBy: 'human', reason: 'because', changeRef: 'abc' })).toThrow();
+    });
+    it('keeps the history of the lesson', () => {
+        const candidate = lessonIn('candidate');
+        const validated = transition(candidate, 'validated', decisionFor('validated'));
+        const applied = transition(validated, 'applied', decisionFor('applied'));
+        expect(applied.history).toHaveLength(2);
+        expect(applied.history[1]?.changeRef).toBe('abc1234');
+        expect(applied.history[0]?.evalPassed).toBe(true);
+    });
+});
+describe('the normalised text', () => {
+    it('reads two spellings of the same thing as one', () => {
+        expect(normalizeText('The file was missing.')).toBe(normalizeText('the file was missing'));
+    });
+});
+describe('the proof', () => {
+    it('knows a suite from an artifact', () => {
+        expect(isSuiteProof('evals/missing-file.json')).toBe(true);
+        expect(isSuiteProof('packages/hooks/evals/suite')).toBe(true);
+        expect(isSuiteProof('lessons/missing-file.json')).toBe(false);
+    });
+});
+//# sourceMappingURL=model.test.js.map

package/dist/lessons/model.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.test.js","sourceRoot":"","sources":["../../src/lessons/model.test.ts"],"names":[],"mappings":"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"}

package/dist/lessons/permissions.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=permissions.test.d.ts.map

package/dist/lessons/permissions.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissions.test.d.ts","sourceRoot":"","sources":["../../src/lessons/permissions.test.ts"],"names":[],"mappings":""}

package/dist/lessons/permissions.test.js

@@ -0,0 +1,88 @@
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadRoles } from '@openagentsy/core';
+import { describe, expect, it } from 'vitest';
+/**
+ * The permission map and the Lead's recovery text.
+ *
+ * Both live in the roles file, which is the source of truth for every
+ * generated agent, so the check reads the real file rather than a fixture.
+ */
+/** The root of the repository the tests run in. */
+const repositoryRoot = fileURLToPath(new URL('../../../../', import.meta.url));
+/**
+ * The tools a person decides with, in both the name the map uses and the
+ * name the MCP server exposes them under.
+ */
+const HUMAN_ONLY_TOOLS = [
+    'oa_lesson_decide',
+    'openagentsy_lesson_decide',
+    'openagentsy_oa_lesson_decide',
+    'oa_quality_waive',
+    'openagentsy_quality_waive',
+    'openagentsy_oa_quality_waive',
+    'oa_memory_decide',
+    'openagentsy_memory_decide',
+    'openagentsy_oa_memory_decide',
+];
+/**
+ * The recovery text, from the Lead's guidance.
+ *
+ * The block is the last one in the guidance, so it runs from the marker to
+ * the end of the text.
+ */
+function recoveryText(guidance) {
+    const lines = guidance.split('\n');
+    const start = lines.findIndex((line) => line.trim().startsWith('Recovery loop:'));
+    if (start === -1)
+        return '';
+    return lines.slice(start).join(' ').trim();
+}
+/** The words of a text. A token is never shorter than a word. */
+function words(text) {
+    return text.split(/\s+/).filter((word) => word.length > 0);
+}
+describe('the permission map', () => {
+    it('denies the three human-only tools to every agent role, in every name', async () => {
+        const roles = await loadRoles(join(repositoryRoot, 'roles.yaml'));
+        expect(Object.keys(roles.roles).length).toBeGreaterThan(0);
+        for (const [name, role] of Object.entries(roles.roles)) {
+            for (const tool of HUMAN_ONLY_TOOLS) {
+                const rules = role.permissions[tool];
+                expect(rules, `${name} must carry ${tool}`).toBeDefined();
+                expect(rules?.[0]?.effect, `${name} must deny ${tool}`).toBe('deny');
+            }
+        }
+    });
+});
+describe('the Lead recovery text', () => {
+    it('is in the Lead guidance', async () => {
+        const roles = await loadRoles(join(repositoryRoot, 'roles.yaml'));
+        const lead = roles.roles.lead;
+        expect(lead).toBeDefined();
+        expect(recoveryText(lead?.guidance ?? '')).not.toBe('');
+    });
+    it('names the five stages in order', async () => {
+        const roles = await loadRoles(join(repositoryRoot, 'roles.yaml'));
+        const text = recoveryText(roles.roles.lead?.guidance ?? '');
+        const order = ['READ', 'RECOVER', 'DECIDE', 'PERSIST', 'REPORT'].map((stage) => text.indexOf(stage));
+        expect(order.every((index) => index >= 0)).toBe(true);
+        expect([...order].sort((a, b) => a - b)).toEqual(order);
+    });
+    it('says the report speaks only after the state was written', async () => {
+        const roles = await loadRoles(join(repositoryRoot, 'roles.yaml'));
+        const text = recoveryText(roles.roles.lead?.guidance ?? '');
+        expect(text).toMatch(/REPORT speaks only after PERSIST wrote the state/);
+    });
+    it('is under 120 tokens', async () => {
+        const roles = await loadRoles(join(repositoryRoot, 'roles.yaml'));
+        const text = recoveryText(roles.roles.lead?.guidance ?? '');
+        const count = words(text).length;
+        // A token is never shorter than a word, and a word is never shorter than
+        // about one and a half tokens in English, so the estimate is the count
+        // times 1.4.
+        expect(count).toBeLessThan(120);
+        expect(count * 1.4).toBeLessThan(120);
+    });
+});
+//# sourceMappingURL=permissions.test.js.map

package/dist/lessons/permissions.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissions.test.js","sourceRoot":"","sources":["../../src/lessons/permissions.test.ts"],"names":[],"mappings":"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"}