@aragon-agent/cli 0.6.43 → 0.6.45

package/dist/governance/tools/lead-tools.js

@@ -0,0 +1,226 @@
+/**
+ * The Orchestrator's two tools, `gov_run` and `gov_dispatch` (governance-mode 7.2).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * THE SCHEMAS DECLARE SHAPE, NOT POLICY (the `plan-tools.ts` P0-4 lesson). `type`,
+ * `required` and `default` stay; every bound lives in the `description`, which is what the
+ * model reads, and is enforced by the engine's own validation. Putting `maxItems` or an
+ * `enum` in the schema would make behaviour depend on whether `ajv`, an OPTIONAL dependency
+ * of core, happened to install: with it a bad call is rejected by the executor as a tool
+ * ERROR (inviting an identical retry), without it the same call reaches the engine. One
+ * design, two behaviours.
+ *
+ * RESULTS ARE ALWAYS `textResult` (7.1 rule 2), aborts and partial failures included - an
+ * error result invites the most expensive possible reaction, a retry of the whole stage.
+ * The engine owns validation and the `NOT ACCEPTED:` / `NEXT:` vocabulary; these tools only
+ * route.
+ */
+import { textResult } from '@aragon-agent/core';
+import { GOV_LIMITS } from '../limits.js';
+/** The `gov_run` actions, in the order the description lists them. */
+export const GOV_RUN_ACTIONS = [
+    'start',
+    'status',
+    'resume',
+    'close',
+    'abandon',
+    'resolve',
+];
+const GOV_RUN_DESCRIPTION = 'Define and manage the governed run. action: ' +
+    '"start" (needs goal, spec, workPackages; optional contracts, integrationCommands, ' +
+    'profile) creates the run and the phase plan; "status" prints the board and the legal ' +
+    'next actions; "resume" (optional runId) reloads the latest unfinished run; "close" ' +
+    '(optional summary) finishes a fully integrated run; "abandon" (needs reason) gives up the ' +
+    'whole run; "resolve" (needs escalationId and ruling, optional favor and disposition) ' +
+    'records the user\'s decision on an ESCALATION and can dispose of the escalated object ' +
+    '(disposition: retry, accept_as_is, drop or accept_failing, matching the escalation kind). ' +
+    `Sizes: goal <= ${GOV_LIMITS.goalChars} chars, spec <= ${GOV_LIMITS.specChars} chars; ` +
+    `each work package: id <= ${GOV_LIMITS.wpIdChars} chars, title <= ${GOV_LIMITS.wpTitleChars}, ` +
+    `goal <= ${GOV_LIMITS.wpGoalChars}, <= ${GOV_LIMITS.wpFilesMax} files (include its test ` +
+    `paths), <= ${GOV_LIMITS.wpAcceptanceMax} acceptance criteria of <= ` +
+    `${GOV_LIMITS.wpAcceptanceChars} chars; <= ${GOV_LIMITS.contractsMax} contracts; <= ` +
+    `${GOV_LIMITS.integrationCommandsMax} integration commands; ruling <= ` +
+    `${GOV_LIMITS.rulingChars} chars. Work package and phase counts are capped (never more ` +
+    `than ${GOV_LIMITS.hardMaxWorkPackages} work packages or ${GOV_LIMITS.hardMaxPhases} ` +
+    'phases); a call over a limit is answered with NOT ACCEPTED and the limit that applies.';
+const GOV_DISPATCH_DESCRIPTION = 'Run ONE stage of the governed run with a team of agents and return a fixed-size ' +
+    'summary ending in NEXT. stage: dev, review, test, settle, integrate or fix. wps ' +
+    '(optional) narrows the stage to those work packages; omit it to take every eligible ' +
+    `one. notes maps a work package id to a short note (<= ${GOV_LIMITS.noteChars} chars) and ` +
+    'is accepted for dev and fix only; for other stages it is dropped and the result says so. ' +
+    'The engine builds every brief; do not relay review or test material. A stage can take ' +
+    'minutes. An illegal stage order is answered with NOT ACCEPTED and the legal NEXT calls.';
+const WORK_PACKAGE_SCHEMA = {
+    type: 'object',
+    properties: {
+        id: { type: 'string', description: 'Short slug, e.g. "auth-api".' },
+        title: { type: 'string' },
+        goal: { type: 'string', description: 'What this work package must deliver.' },
+        files: {
+            type: 'array',
+            items: { type: 'string' },
+            description: 'Owned files and globs, INCLUDING this work package\'s test paths.',
+        },
+        acceptance: {
+            type: 'array',
+            items: { type: 'string' },
+            description: 'Verifiable acceptance criteria.',
+        },
+        dependsOn: {
+            type: 'array',
+            items: { type: 'string' },
+            description: 'Ids of work packages that must be integrated first.',
+        },
+    },
+    required: ['id', 'title', 'goal', 'files', 'acceptance'],
+};
+const CONTRACT_SCHEMA = {
+    type: 'object',
+    properties: {
+        id: { type: 'string' },
+        name: { type: 'string' },
+        producer: { type: 'string', description: 'Work package id that provides the interface.' },
+        consumers: { type: 'array', items: { type: 'string' } },
+        definition: { type: 'string', description: 'Exact signature or data shape.' },
+    },
+    required: ['id', 'name', 'producer', 'consumers', 'definition'],
+};
+/** Text returned when the tool call's signal was already aborted at entry. */
+export const DISPATCH_ABORTED_AT_ENTRY = 'PAUSED: the call was interrupted before the stage started, so nothing was dispatched.\n' +
+    'NEXT: gov_run {action:"resume"} to continue, or gov_run {action:"abandon", reason:"..."} ' +
+    'to stop the run.';
+/** Text returned when a stage was aborted while the engine was running it. */
+function dispatchAbortedMidway() {
+    return ('PAUSED: the stage was interrupted. Completed submissions were kept.\n' +
+        'NEXT: gov_run {action:"resume"} to continue, or gov_run {action:"abandon", ' +
+        'reason:"..."} to stop the run.');
+}
+function recordOf(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : {};
+}
+function text(value) {
+    return typeof value === 'string' && value.trim() !== '' ? value.trim() : undefined;
+}
+function notAccepted(reason) {
+    return textResult(`NOT ACCEPTED: ${reason}`);
+}
+async function runAction(engine, action, params, signal) {
+    // The engine validates payload shape; `action` is routing only and must not leak into it.
+    const payload = { ...params };
+    delete payload.action;
+    switch (action) {
+        case 'start':
+            return textResult(await engine.start(payload, signal));
+        case 'status':
+            return textResult(engine.status());
+        case 'resume':
+            return textResult(await engine.resume(text(params.runId)));
+        case 'close':
+            return textResult(await engine.close(text(params.summary)));
+        case 'abandon': {
+            const reason = text(params.reason);
+            if (!reason)
+                return notAccepted('abandon needs a reason (a short sentence).');
+            return textResult(await engine.abandon(reason.slice(0, GOV_LIMITS.reasonChars)));
+        }
+        case 'resolve':
+            return textResult(await engine.resolve(payload));
+    }
+}
+/**
+ * `gov_run`: start, inspect, resume, close, abandon and resolve a governed run.
+ *
+ * An unknown `action` is a non-error `NOT ACCEPTED` that lists the valid ones: the model
+ * guessed a verb, and a list repairs that in one turn.
+ */
+export function makeGovRunTool(engine) {
+    return {
+        name: 'gov_run',
+        label: 'Governed run',
+        description: GOV_RUN_DESCRIPTION,
+        parameters: {
+            type: 'object',
+            properties: {
+                action: { type: 'string', description: GOV_RUN_ACTIONS.join(' | ') },
+                goal: { type: 'string', description: 'One-sentence goal (start).' },
+                spec: { type: 'string', description: 'The complete requirement or approved plan (start).' },
+                profile: { type: 'string', description: 'general | ml | product | api-security (start).' },
+                workPackages: { type: 'array', items: WORK_PACKAGE_SCHEMA, description: 'start only.' },
+                contracts: { type: 'array', items: CONTRACT_SCHEMA, description: 'Shared interfaces.' },
+                integrationCommands: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Test commands the inspector may run (start).',
+                },
+                runId: { type: 'string', description: 'resume: a specific run id.' },
+                summary: { type: 'string', description: 'close: closing note.' },
+                reason: { type: 'string', description: 'abandon: why.' },
+                escalationId: { type: 'string', description: 'resolve: the ESC id.' },
+                ruling: { type: 'string', description: 'resolve: the user\'s ruling.' },
+                favor: { type: 'string', description: 'resolve: whom the ruling favors.' },
+                disposition: {
+                    type: 'string',
+                    description: 'resolve: retry | accept_as_is | drop | accept_failing.',
+                },
+            },
+            required: ['action'],
+        },
+        async execute(_id, params, ctx) {
+            const args = recordOf(params);
+            const action = text(args.action)?.toLowerCase();
+            if (!action || !GOV_RUN_ACTIONS.includes(action)) {
+                return notAccepted(`unknown action ${JSON.stringify(args.action ?? null)}. Valid actions: ` +
+                    `${GOV_RUN_ACTIONS.join(', ')}.`);
+            }
+            return runAction(engine, action, args, ctx.signal);
+        },
+    };
+}
+/**
+ * `gov_dispatch`: run one stage.
+ *
+ * ABORT HANDLING (D-21). The executor timer is disabled for this tool (`gov_dispatch: 0`),
+ * which is safe ONLY because the tool honours `ctx.signal`: (1) a signal that is already
+ * aborted returns the paused text at once, without touching the engine; (2) the signal is
+ * handed to the engine so the stage can stop; (3) if the engine rejects after an abort, that
+ * is a pause, not a tool failure. Any other rejection is a real defect and propagates.
+ */
+export function makeGovDispatchTool(engine) {
+    return {
+        name: 'gov_dispatch',
+        label: 'Dispatch governed stage',
+        description: GOV_DISPATCH_DESCRIPTION,
+        parameters: {
+            type: 'object',
+            properties: {
+                stage: { type: 'string', description: 'dev | review | test | settle | integrate | fix' },
+                wps: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Work package ids to include. Omit for every eligible one.',
+                },
+                notes: {
+                    type: 'object',
+                    description: 'Map of work package id to a short note (dev and fix only).',
+                    additionalProperties: { type: 'string' },
+                },
+            },
+            required: ['stage'],
+        },
+        async execute(_id, params, ctx) {
+            if (ctx.signal?.aborted)
+                return textResult(DISPATCH_ABORTED_AT_ENTRY);
+            try {
+                return textResult(await engine.dispatchStage(recordOf(params), ctx.signal));
+            }
+            catch (err) {
+                if (ctx.signal?.aborted)
+                    return textResult(dispatchAbortedMidway());
+                throw err;
+            }
+        },
+    };
+}

package/dist/governance/tools/normalize-util.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Coercion helpers shared by every governance tool normalizer (governance-mode 5.9, 7.1).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned). Pure: no I/O, no clock.
+ *
+ * REPAIR FIRST, REJECT SECOND (the `normalizeQuestions` discipline). A value the model got
+ * slightly wrong - an upper-case verdict, a status spelled `n/a`, a single path where a list
+ * was expected, an over-long summary - is fixed and accepted, with a NOTE saying what was
+ * changed. Only what cannot be repaired is an ERROR, and every error is collected before the
+ * answer is built, so one `NOT ACCEPTED:` text names ALL the problems (one round trip, not
+ * one per mistake).
+ *
+ * A REJECTED SUBMISSION IS NEVER A PENALTY (D-15): a tool-layer mistake is not a character
+ * flaw. It is also never an error result - that invites an identical retry loop.
+ */
+/** Marker appended to any clipped field. Stable: tests and models rely on it. */
+export declare const TRUNCATION_MARK = "[truncated]";
+/**
+ * Per-field bounds for submissions. STRUCTURAL (what the store and the digests can carry),
+ * enforced by clipping here and never declared in a schema (7.1 rule 3). The worst-case sum
+ * is far above `GOV_LIMITS.submissionBytes`, which is re-checked on the normalized result.
+ */
+export declare const SUBMIT_LIMITS: {
+    readonly summaryChars: 2000;
+    readonly evidenceChars: 800;
+    readonly issueChars: 800;
+    readonly rationaleChars: 600;
+    readonly argumentChars: 1200;
+    readonly pathChars: 300;
+    readonly commandChars: 300;
+    readonly resultChars: 600;
+    readonly shortChars: 200;
+    readonly idChars: 40;
+    readonly filesMax: 200;
+    readonly contractsMax: 24;
+    readonly commandsMax: 20;
+    readonly findingsMax: 30;
+    readonly fixesMax: 30;
+    readonly responsesMax: 30;
+    readonly traceMax: 60;
+    readonly issuesMax: 30;
+    readonly claimsMax: 5;
+    readonly findingIdsMax: 30;
+};
+/** How many problems one NOT ACCEPTED answer lists (the rest are counted, not printed). */
+export declare const ERRORS_SHOWN = 8;
+export type Normalized<T> = {
+    ok: true;
+    value: T;
+    notes: string[];
+} | {
+    ok: false;
+    errors: string[];
+};
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+/** Clip to `max` characters, marker included, so the result never exceeds `max`. */
+export declare function clipText(text: string, max: number): {
+    text: string;
+    clipped: boolean;
+};
+/** `true` / `false` or their string spellings; anything else is "not given". */
+export declare function readBool(raw: unknown): boolean | undefined;
+/** An integer, or a string of digits read as one; anything else is "not given". */
+export declare function readInteger(raw: unknown): number | undefined;
+export interface OneOfOptions<T extends string> {
+    /** Extra spellings, keyed by their `enumKey` form (lower case, underscores). */
+    aliases?: Readonly<Record<string, T>>;
+    required?: boolean;
+}
+/** Collects what cannot be repaired (`errors`) and what was repaired (`notes`). */
+export declare class Issues {
+    readonly errors: string[];
+    readonly notes: string[];
+    fail(message: string): void;
+    note(message: string): void;
+    /**
+     * Close the collection: the value on success, every error on failure. The serialized size
+     * is re-checked here because the per-field clips alone do not bound the whole.
+     */
+    result<T>(value: T): Normalized<T>;
+    /**
+     * A text field. Numbers and booleans are stringified (a model that sends `exit: 0` where
+     * text was expected means 0); objects and arrays are not text and are rejected.
+     */
+    str(raw: unknown, label: string, max: number, required?: boolean): string;
+    /**
+     * A work package id: letters, digits, `.`, `_`, `-`, at most `GOV_LIMITS.wpIdChars`.
+     * Never clipped (a clipped id names a different work package); an unusable one is an error.
+     */
+    wpId(raw: unknown, label?: string, required?: boolean): string;
+    /** A list of short strings. A single string is a list (newline-separated: several). */
+    list(raw: unknown, label: string, maxItems: number, maxChars: number): string[];
+    /** A list of records. A single object is a one-item list; anything else is an error. */
+    items(raw: unknown, label: string, maxItems: number): unknown[];
+    /** One member of `allowed`, matched leniently (case, camelCase, spaces, hyphens, aliases). */
+    oneOf<T extends string>(raw: unknown, label: string, allowed: readonly T[], options?: OneOfOptions<T>): T | undefined;
+}
+/** `NOT ACCEPTED:` text for a failed normalization. Never an error result, never a penalty. */
+export declare function formatNotAccepted(tool: string, errors: readonly string[]): string;
+/** Append the repair notes (what was clipped, rescaled, renumbered) to an engine answer. */
+export declare function withNotes(text: string, notes: readonly string[]): string;

package/dist/governance/tools/normalize-util.js

@@ -0,0 +1,230 @@
+/**
+ * Coercion helpers shared by every governance tool normalizer (governance-mode 5.9, 7.1).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned). Pure: no I/O, no clock.
+ *
+ * REPAIR FIRST, REJECT SECOND (the `normalizeQuestions` discipline). A value the model got
+ * slightly wrong - an upper-case verdict, a status spelled `n/a`, a single path where a list
+ * was expected, an over-long summary - is fixed and accepted, with a NOTE saying what was
+ * changed. Only what cannot be repaired is an ERROR, and every error is collected before the
+ * answer is built, so one `NOT ACCEPTED:` text names ALL the problems (one round trip, not
+ * one per mistake).
+ *
+ * A REJECTED SUBMISSION IS NEVER A PENALTY (D-15): a tool-layer mistake is not a character
+ * flaw. It is also never an error result - that invites an identical retry loop.
+ */
+import { GOV_LIMITS } from '../limits.js';
+/** Marker appended to any clipped field. Stable: tests and models rely on it. */
+export const TRUNCATION_MARK = '[truncated]';
+/**
+ * Per-field bounds for submissions. STRUCTURAL (what the store and the digests can carry),
+ * enforced by clipping here and never declared in a schema (7.1 rule 3). The worst-case sum
+ * is far above `GOV_LIMITS.submissionBytes`, which is re-checked on the normalized result.
+ */
+export const SUBMIT_LIMITS = {
+    summaryChars: 2_000,
+    evidenceChars: 800,
+    issueChars: 800,
+    rationaleChars: 600,
+    argumentChars: 1_200,
+    pathChars: 300,
+    commandChars: 300,
+    resultChars: 600,
+    shortChars: 200,
+    idChars: 40,
+    filesMax: 200,
+    contractsMax: 24,
+    commandsMax: 20,
+    findingsMax: 30,
+    fixesMax: 30,
+    responsesMax: 30,
+    traceMax: 60,
+    issuesMax: 30,
+    claimsMax: 5,
+    findingIdsMax: 30,
+};
+const WP_ID_PATTERN = /^[A-Za-z0-9._-]+$/;
+/** How many problems one NOT ACCEPTED answer lists (the rest are counted, not printed). */
+export const ERRORS_SHOWN = 8;
+export function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+/** Clip to `max` characters, marker included, so the result never exceeds `max`. */
+export function clipText(text, max) {
+    if (text.length <= max)
+        return { text, clipped: false };
+    const keep = Math.max(0, max - TRUNCATION_MARK.length - 1);
+    return { text: `${text.slice(0, keep)} ${TRUNCATION_MARK}`, clipped: true };
+}
+/** `true` / `false` or their string spellings; anything else is "not given". */
+export function readBool(raw) {
+    if (typeof raw === 'boolean')
+        return raw;
+    if (typeof raw === 'string') {
+        const t = raw.trim().toLowerCase();
+        if (t === 'true' || t === 'yes')
+            return true;
+        if (t === 'false' || t === 'no')
+            return false;
+    }
+    return undefined;
+}
+/** An integer, or a string of digits read as one; anything else is "not given". */
+export function readInteger(raw) {
+    if (typeof raw === 'number' && Number.isInteger(raw))
+        return raw;
+    if (typeof raw === 'string' && /^-?\d+$/.test(raw.trim()))
+        return Number(raw.trim());
+    return undefined;
+}
+/** Case-, camelCase-, space-, slash- and hyphen-insensitive key for enum matching. */
+function enumKey(text) {
+    return text
+        .trim()
+        .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+        .toLowerCase()
+        .replace(/[\s\-/]+/g, '_');
+}
+/** Collects what cannot be repaired (`errors`) and what was repaired (`notes`). */
+export class Issues {
+    errors = [];
+    notes = [];
+    fail(message) {
+        this.errors.push(message);
+    }
+    note(message) {
+        this.notes.push(message);
+    }
+    /**
+     * Close the collection: the value on success, every error on failure. The serialized size
+     * is re-checked here because the per-field clips alone do not bound the whole.
+     */
+    result(value) {
+        if (this.errors.length > 0)
+            return { ok: false, errors: this.errors };
+        const bytes = Buffer.byteLength(JSON.stringify(value), 'utf8');
+        if (bytes > GOV_LIMITS.submissionBytes) {
+            return {
+                ok: false,
+                errors: [
+                    `the submission is ${bytes} bytes; the limit is ${GOV_LIMITS.submissionBytes}. ` +
+                        'Shorten summaries, evidence and lists.',
+                ],
+            };
+        }
+        return { ok: true, value, notes: this.notes };
+    }
+    /**
+     * A text field. Numbers and booleans are stringified (a model that sends `exit: 0` where
+     * text was expected means 0); objects and arrays are not text and are rejected.
+     */
+    str(raw, label, max, required = false) {
+        let text = '';
+        let wrongType = false;
+        if (typeof raw === 'string')
+            text = raw.trim();
+        else if (typeof raw === 'number' || typeof raw === 'boolean')
+            text = String(raw);
+        else if (raw !== undefined && raw !== null)
+            wrongType = true;
+        if (wrongType)
+            this.fail(`${label} must be text.`);
+        else if (text === '' && required) {
+            this.fail(`${label} ${raw === undefined || raw === null ? 'is required' : 'is empty'}.`);
+        }
+        const clipped = clipText(text, max);
+        if (clipped.clipped)
+            this.note(`${label} was truncated to ${max} characters.`);
+        return clipped.text;
+    }
+    /**
+     * A work package id: letters, digits, `.`, `_`, `-`, at most `GOV_LIMITS.wpIdChars`.
+     * Never clipped (a clipped id names a different work package); an unusable one is an error.
+     */
+    wpId(raw, label = 'wpId', required = true) {
+        const id = this.str(raw, label, 200, required);
+        if (id === '')
+            return id;
+        if (id.length > GOV_LIMITS.wpIdChars || !WP_ID_PATTERN.test(id)) {
+            this.fail(`${label} "${id.slice(0, 40)}" is not a work package id: use the id from your ` +
+                `assignment (letters, digits, . _ -; at most ${GOV_LIMITS.wpIdChars} characters).`);
+        }
+        return id;
+    }
+    /** A list of short strings. A single string is a list (newline-separated: several). */
+    list(raw, label, maxItems, maxChars) {
+        if (raw === undefined || raw === null)
+            return [];
+        let items;
+        if (Array.isArray(raw))
+            items = raw;
+        else if (typeof raw === 'string')
+            items = raw.split(/\r?\n/);
+        else {
+            this.fail(`${label} must be a list of strings.`);
+            return [];
+        }
+        const out = [];
+        for (const item of items) {
+            const text = typeof item === 'string' ? item.trim() : '';
+            if (text !== '' && !out.includes(text))
+                out.push(clipText(text, maxChars).text);
+        }
+        if (out.length > maxItems) {
+            this.note(`${label} keeps the first ${maxItems} of ${out.length} entries.`);
+            out.length = maxItems;
+        }
+        return out;
+    }
+    /** A list of records. A single object is a one-item list; anything else is an error. */
+    items(raw, label, maxItems) {
+        if (raw === undefined || raw === null)
+            return [];
+        let items;
+        if (Array.isArray(raw))
+            items = raw;
+        else if (isRecord(raw))
+            items = [raw];
+        else {
+            this.fail(`${label} must be a list.`);
+            return [];
+        }
+        if (items.length > maxItems) {
+            this.note(`${label} keeps the first ${maxItems} of ${items.length} entries.`);
+            return items.slice(0, maxItems);
+        }
+        return items;
+    }
+    /** One member of `allowed`, matched leniently (case, camelCase, spaces, hyphens, aliases). */
+    oneOf(raw, label, allowed, options = {}) {
+        if (raw === undefined || raw === null || raw === '') {
+            if (options.required)
+                this.fail(`${label} is required (${allowed.join(' | ')}).`);
+            return undefined;
+        }
+        const key = enumKey(String(raw));
+        const aliases = options.aliases;
+        const aliased = aliases && Object.prototype.hasOwnProperty.call(aliases, key) ? aliases[key] : undefined;
+        const found = allowed.find((a) => enumKey(a) === key) ?? aliased;
+        if (found === undefined) {
+            this.fail(`${label} must be one of ${allowed.join(', ')} (got "${String(raw)}").`);
+        }
+        return found;
+    }
+}
+/** `NOT ACCEPTED:` text for a failed normalization. Never an error result, never a penalty. */
+export function formatNotAccepted(tool, errors) {
+    const shown = errors.slice(0, ERRORS_SHOWN);
+    const lines = [`NOT ACCEPTED: ${tool} was not recorded.`, ...shown.map((e) => `- ${e}`)];
+    if (errors.length > shown.length)
+        lines.push(`- ...and ${errors.length - shown.length} more.`);
+    lines.push(`Fix ${errors.length === 1 ? 'this' : 'these'} and call ${tool} again.`);
+    lines.push('Nothing was recorded and no GT was deducted.');
+    return lines.join('\n');
+}
+/** Append the repair notes (what was clipped, rescaled, renumbered) to an engine answer. */
+export function withNotes(text, notes) {
+    if (notes.length === 0)
+        return text;
+    return `${text}\nNOTE: ${notes.slice(0, ERRORS_SHOWN).join(' ')}`;
+}

package/dist/governance/tools/scan-incomplete.d.ts

@@ -0,0 +1,79 @@
+/**
+ * `gov_scan`: a deterministic scan for incomplete implementations (governance-mode 5.9).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * EVIDENCE, NEVER A VERDICT. The scan is a line-and-brace heuristic over several languages,
+ * not a parser. It returns `file:line:kind` hits plus a suspected-skeleton ratio, and
+ * NOTHING in the engine deducts GT from it: a heuristic that scores would turn every false
+ * positive (a deliberate empty `catch`, a trivial constant getter) into an unfair penalty.
+ * Reviewers, testers and the inspector cite it as evidence and still read the code.
+ *
+ * READ-ONLY AND CONFINED. Paths resolve against the working directory and are refused when
+ * the REAL path (after symlinks) leaves it; sizes, file counts and depth are bounded so a
+ * hostile or huge tree cannot stall a stage. Binary files are skipped, not decoded.
+ *
+ * The pure core, `scanText`, is exported separately so the heuristics are unit-tested on
+ * fixtures without touching a disk.
+ */
+import { type AgentTool } from '@aragon-agent/core';
+export type ScanKind = 'todo' | 'not_implemented' | 'empty_catch' | 'bare_pass' | 'placeholder_return';
+export interface ScanFinding {
+    line: number;
+    kind: ScanKind;
+    /** The offending line, trimmed and clipped. */
+    text: string;
+}
+export interface TextScan {
+    findings: ScanFinding[];
+    /** Function-like declarations seen. */
+    functions: number;
+    /** Of those, the ones whose whole body is a placeholder. */
+    skeletonFunctions: number;
+}
+/**
+ * Scan one file's text. Pure and deterministic: the same input always yields the same hits,
+ * in ascending line order, at most one per line and kind.
+ */
+export declare function scanText(text: string): TextScan;
+export interface ScanOptions {
+    cwd: string;
+    paths: readonly string[];
+    /** Files larger than this are skipped, not truncated. */
+    maxFileBytes?: number;
+    /** Total files scanned across all paths. */
+    maxFiles?: number;
+}
+export interface ScannedFinding extends ScanFinding {
+    file: string;
+}
+export interface ScanSkip {
+    path: string;
+    reason: string;
+}
+export interface ScanReport {
+    files: number;
+    findings: ScannedFinding[];
+    skipped: ScanSkip[];
+    functions: number;
+    skeletonFunctions: number;
+    /** `skeletonFunctions / functions`, 0 when no function was seen. */
+    skeletonRatio: number;
+    /** True when the file cap or the path cap cut the scan short. */
+    truncated: boolean;
+}
+/**
+ * Scan files and directories under `cwd`. Directories are walked (bounded depth, known code
+ * extensions, build and vendor trees skipped); explicit files are scanned whatever their
+ * extension. Only the first `GOV_LIMITS.scanPathsMax` paths are used; the rest are counted
+ * as truncation.
+ */
+export declare function scanPaths(options: ScanOptions): Promise<ScanReport>;
+/** The text the model reads. The first line is `OK:` (7.1 rule 2). */
+export declare function formatScanReport(report: ScanReport): string;
+export interface ScanToolContext {
+    /** Read LIVE: the workspace the child works in. */
+    getCwd: () => string;
+}
+/** `gov_scan`: REV, TEST and INSP. Read-only. */
+export declare function makeScanTool(ctx: ScanToolContext): AgentTool;