@aragon-agent/cli 0.6.43 → 0.6.45

package/dist/governance/prompts/refusals.js

@@ -0,0 +1,82 @@
+/**
+ * Refusal texts (governance-mode 6.5) - the ONE place these sentences are worded.
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * "REFUSAL AS TEACHING", like `planRefusal`: a gated tool is refused with the reason, the
+ * legal alternative and an instruction not to route around it. A bare "not allowed" makes
+ * the model probe for a bypass; a sentence that names the alternative makes it take it.
+ *
+ * ERROR VS TEXT. Every refusal here is delivered as a NON-error `textResult` by its caller
+ * EXCEPT `governRefusal`, which keeps the plan gate's `errorResult` so the pre-existing
+ * "a refused tool did not run" semantics hold for write tools. The others (`gov_run` in the
+ * plan phase, `submit_plan` before the interview is long enough, ...) are not a tool
+ * FAILURE: an error result invites the model to retry the identical call, whose only
+ * possible outcome is the same refusal (the reasoning `team_send` and `ask_user` already
+ * follow).
+ */
+/** The read-only research tools that stay available to the Orchestrator. */
+const READ_ONLY_RESEARCH = 'read_file / list_dir / glob / grep';
+/**
+ * Orchestrator tool refused while governance is on (`write_file`, `edit_file`, `bash`, ...).
+ *
+ * The `task` variant appends the pointer to the replacement fan-out: a model that is
+ * refused `task` otherwise tends to retry it with different arguments.
+ */
+export function governRefusal(tool) {
+    const base = `Governance mode is active, so ${tool} is refused: you are the Orchestrator and do not ` +
+        'change anything yourself. Use gov_run to define work and gov_dispatch to have the team ' +
+        `do it. Read-only research (${READ_ONLY_RESEARCH}) is still available. ` +
+        'Do not try to work around this.';
+    return tool === 'task' ? `${base} Use gov_dispatch instead of task.` : base;
+}
+/** `gov_run` / `gov_dispatch` while the gate mode is plan: suspended until approval. */
+export function govPlanPhaseRefusal() {
+    return ('Plan phase is active. gov_run and gov_dispatch are suspended until the user approves ' +
+        'your plan. Finish the interview and call submit_plan.');
+}
+/** `gov_run` / `gov_dispatch` after `/gov off` (the tools cannot be unregistered mid-session). */
+export function govOffRefusal() {
+    return 'Governance mode is off for this session. Do this work yourself, in order.';
+}
+/**
+ * The fixed interview topics, in the order the plan addendum asks about them. The wiring
+ * classifies answered questions against this list and passes the UNCOVERED ones to
+ * `govAskRoundsRefusal`, so the model is told what to ask instead of padding rounds with
+ * filler questions.
+ */
+export const PLAN_INTERVIEW_TOPICS = [
+    'goal and success criteria',
+    'scope (what is explicitly in and out)',
+    'constraints (stack, compatibility, performance, style, forbidden changes)',
+    'quality bar (required tests, security expectations, review strictness)',
+    'team shape and cost (parallel work packages, budget ceiling)',
+    'risks and dependencies found in the workspace',
+];
+/** How many uncovered topics the refusal lists. More reads as a questionnaire. */
+const REFUSAL_TOPIC_LIMIT = 3;
+function nonNegativeInt(value) {
+    return Number.isFinite(value) && value > 0 ? Math.floor(value) : 0;
+}
+/**
+ * `submit_plan` before the PLAN+GOVERN interview has enough ANSWERED rounds.
+ *
+ * `uncoveredTopics` is in interview order; only the first few are named. An empty list
+ * (every topic touched but the round count is still short) falls back to a generic ask.
+ */
+export function govAskRoundsRefusal(done, need, uncoveredTopics) {
+    const head = 'submit_plan is not accepted yet: PLAN+GOVERN requires at least ' +
+        `${nonNegativeInt(need)} answered question rounds and you have ${nonNegativeInt(done)}.`;
+    const topics = uncoveredTopics.slice(0, REFUSAL_TOPIC_LIMIT);
+    if (topics.length === 0)
+        return `${head} Ask what is still unclear before you plan.`;
+    return `${head} Ask about: ${topics.join('; ')}.`;
+}
+/**
+ * The `submit_plan` result when the user approved a plan while governance is on. It is
+ * authoritative for the rest of the run (the system prompt is captured by value and cannot
+ * be re-issued), so it states the new role and the first call explicitly.
+ */
+export const APPROVED_GOVERN_RESULT = 'Plan approved. Governance is now active and you are the Orchestrator. Do not implement ' +
+    'anything yourself. Call gov_run {action:"start"} (the approved plan is attached as the ' +
+    'specification automatically), then drive the team with gov_dispatch.';

package/dist/governance/prompts/role-blocks.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The `<governance_role>` block of a governed child's system prompt (governance-mode 6.4).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * STRUCTURE (6.4): identity line, persona prefix (profiles.ts), [predecessor notice],
+ * SCORING PROTOCOL (DEV/REV/TEST only: the inspector is not scored), role duties and
+ * prohibitions, information boundary, submission obligations, and the closing language line.
+ *
+ * WHAT THE PROSE IS FOR AND WHAT IT IS NOT. Everything a child MUST do is also enforced by a
+ * tool or the engine (the submission schema, the visibility matrix, the file-ownership
+ * signal). The text explains why and how; it is never the only guard. The scoring protocol
+ * is the reference SURVIVAL PROTOCOL with the theatre removed (D-20): it keeps the
+ * mechanisms that change behaviour (escrow, clawback, replacement, "conservatism fails",
+ * "isolation fails") and drops the "your existence depends on it" register.
+ *
+ * "GT" IS NOT AN LLM TOKEN (D-8). The protocol says so in its second sentence because the
+ * status bar already shows LLM token usage, and "you have 100 tokens left" is otherwise
+ * read as a context budget.
+ */
+import { GOVERNANCE_ROLE_BLOCK_VERSION } from '../limits.js';
+import type { GovernanceSpecExt } from '../types.js';
+export { GOVERNANCE_ROLE_BLOCK_VERSION };
+/** Inputs that are not part of `GovernanceSpecExt` itself. */
+export interface RoleBlockExtra {
+    /** The registered integration commands; only the inspector's block quotes them. */
+    integrationCommands?: readonly string[];
+}
+/** Closing line of every role block (6.1: reports follow the language of the request). */
+export declare const REPORT_LANGUAGE_LINE = "Write reports in the language of the original request.";
+/** The scoring protocol shared by DEV / REV / TEST. `tokens` is this agent's starting GT. */
+export declare function scoringProtocol(tokens: number): string;
+/**
+ * The full role block for one child. Pure: the same `(ext, extra)` always yields the same
+ * text, so the spec-builder tests can compare blocks byte for byte.
+ *
+ * The version line sits right after the identity line so that the block can END on
+ * `REPORT_LANGUAGE_LINE`, as 6.4 specifies.
+ */
+export declare function buildRoleBlock(ext: GovernanceSpecExt, extra?: RoleBlockExtra): string;

package/dist/governance/prompts/role-blocks.js

@@ -0,0 +1,255 @@
+/**
+ * The `<governance_role>` block of a governed child's system prompt (governance-mode 6.4).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * STRUCTURE (6.4): identity line, persona prefix (profiles.ts), [predecessor notice],
+ * SCORING PROTOCOL (DEV/REV/TEST only: the inspector is not scored), role duties and
+ * prohibitions, information boundary, submission obligations, and the closing language line.
+ *
+ * WHAT THE PROSE IS FOR AND WHAT IT IS NOT. Everything a child MUST do is also enforced by a
+ * tool or the engine (the submission schema, the visibility matrix, the file-ownership
+ * signal). The text explains why and how; it is never the only guard. The scoring protocol
+ * is the reference SURVIVAL PROTOCOL with the theatre removed (D-20): it keeps the
+ * mechanisms that change behaviour (escrow, clawback, replacement, "conservatism fails",
+ * "isolation fails") and drops the "your existence depends on it" register.
+ *
+ * "GT" IS NOT AN LLM TOKEN (D-8). The protocol says so in its second sentence because the
+ * status bar already shows LLM token usage, and "you have 100 tokens left" is otherwise
+ * read as a context budget.
+ */
+import { GOVERNANCE_ROLE_BLOCK_VERSION } from '../limits.js';
+import { getProfile, profilePrefix } from '../profiles.js';
+export { GOVERNANCE_ROLE_BLOCK_VERSION };
+/** Closing line of every role block (6.1: reports follow the language of the request). */
+export const REPORT_LANGUAGE_LINE = 'Write reports in the language of the original request.';
+const MAX_PENALTIES_LISTED = 5;
+const MAX_REASON_CHARS = 120;
+const MAX_COMMANDS_LISTED = 6;
+const REASON_TEXT = {
+    depleted: 'running out of confirmed GT',
+    tail: 'finishing last in its role for consecutive phases',
+    clawback: 'work that failed integration and had its escrowed GT clawed back',
+};
+/** The scoring protocol shared by DEV / REV / TEST. `tokens` is this agent's starting GT. */
+export function scoringProtocol(tokens) {
+    return [
+        'SCORING PROTOCOL',
+        `You hold ${tokens} GT (governance tokens). GT is a score for this run only and has nothing`,
+        'to do with LLM context tokens. Standings are public: call ledger_standings.',
+        '- Thorough, correct, integrated work earns GT (+5 to +20). Rejections, missed requirements,',
+        '  security flaws and incomplete work cost GT (-10 to -40).',
+        '- Positive GT is held in ESCROW (shown as P) until the phase\'s integration check passes. If',
+        '  integration fails because of your work, your escrowed GT is clawed back and you lose more.',
+        '- If your CONFIRMED GT reaches zero you are replaced, and your replacement is told why.',
+        'CONSERVATISM FAILS: stubs, TODO placeholders, skipped error handling and minimal-effort code',
+        'are treated as failures (-20 to -30). Doing less is never the safe choice.',
+        'ISOLATION FAILS: code that works alone but breaks when combined with your peers\' work is a',
+        'failure. Verify the interfaces you produce or consume against the contracts you were given,',
+        'and state how you verified them in your submission.',
+        'The safest strategy is: implement completely, verify contracts, test against what your',
+        'peers\' code will produce and expect, and report honestly. Honest reports of problems are',
+        'never penalized as heavily as hidden ones.',
+    ].join('\n');
+}
+function oneLine(text, max) {
+    const flat = text.replace(/\s+/g, ' ').trim();
+    return flat.length > max ? `${flat.slice(0, max - 3)}...` : flat;
+}
+/** The successor's briefing: who failed, why, what cost them, what to avoid (5.8). */
+function predecessorSection(analysis, tokens) {
+    const lines = [
+        `Your predecessor ${analysis.agentId} was terminated for ${REASON_TEXT[analysis.reason]}.`,
+        `You start with ${tokens} GT and inherit none of its code: read the workspace as it is.`,
+    ];
+    const penalties = analysis.topPenalties.slice(0, MAX_PENALTIES_LISTED);
+    if (penalties.length > 0) {
+        lines.push('Its largest penalties:');
+        for (const p of penalties) {
+            lines.push(`- ${p.code} (${p.delta}): ${oneLine(p.reason, MAX_REASON_CHARS)}`);
+        }
+    }
+    if (analysis.avoid.length > 0) {
+        lines.push('Avoid:');
+        for (const a of analysis.avoid)
+            lines.push(`- ${oneLine(a, MAX_REASON_CHARS * 2)}`);
+    }
+    return lines;
+}
+function assignmentSection(ext) {
+    if (ext.role === 'INSP')
+        return ['ASSIGNMENT', 'All work packages of this phase.'];
+    const list = ext.wpIds.length > 0 ? ext.wpIds.join(', ') : '(none listed)';
+    const many = ext.wpIds.length > 1;
+    return [
+        'ASSIGNMENT',
+        `Your work package${many ? 's, in this fixed order' : ''}: ${list}.`,
+    ];
+}
+// ---------------------------------------------------------------------------
+// Duties, boundaries and submission obligations per role
+// ---------------------------------------------------------------------------
+const DEV_DUTIES = [
+    'YOUR ROLE: DEVELOPMENT',
+    '- Implement only your assigned work package and change only the files it owns. Writes',
+    '  outside them are detected and reported to the Inspector.',
+    '- Be complete: no stubs, no TODO placeholders, real error handling. Run the checks that',
+    '  cover your files and read your own diff before you submit.',
+    '- Agree on shared interfaces with your DEV peers in this batch through team_send; keep',
+    '  messages short.',
+    '- Rework: you receive REQUIRED CHANGES from the reviewer. Address each one, or use your',
+    '  single appeal for that work package (gov_submit_work with appeal: findingIds and the',
+    '  argument) instead of reworking blindly.',
+    '- Do not read the governance store and do not try to see review or test internals.',
+    '  gov_view exists, but the policy usually refuses and every request is logged.',
+];
+const FIX_DUTIES = [
+    'YOUR ROLE: INTEGRATION FIX',
+    '- Integration failed. You hold the full root-cause analysis and both sides of the',
+    '  affected contracts. Your task is interface alignment: make producer and consumer agree',
+    '  on the contract, not merely turn the failing check green.',
+    '- Keep to the files named in the analysis unless the contract fix needs more. No stubs,',
+    '  no placeholders.',
+    '- Your submission must state, for every contract involved, how you verified both sides.',
+    '- Do not read the governance store and do not try to see review or test internals.',
+];
+const REV_DUTIES = [
+    'YOUR ROLE: REVIEW',
+    '- Review independently. You do not see test results and you must not look for them.',
+    '- Check every item and give evidence for each: correctness, code quality, security,',
+    '  integration compatibility, compliance with the work package acceptance criteria.',
+    '- You hold a veto: reject work that does not meet the bar. You may fix minor issues',
+    '  directly; list each file you changed in fixesApplied with the rationale.',
+    '- Feedback must be specific and actionable: file, location and the exact change required.',
+    '  Vague comments are penalized.',
+    '- integrationAssessment must cite concrete contract names or function signatures. With no',
+    '  cross-module contracts write: NOT_APPLICABLE: no cross-module contracts.',
+    '- When the developer appealed a rejection, answer every appealed finding with uphold or',
+    '  withdraw in appealResponses.',
+    '- You answer for false positives and for defects you let through.',
+    '- Do not read the governance store. Use gov_read for the material you may see.',
+];
+const TEST_DUTIES = [
+    'YOUR ROLE: TESTING',
+    '- Run all existing test suites and write the missing tests, including tests across module',
+    '  boundaries (set boundaryTestsWritten accordingly).',
+    '- Build a traceability row for every acceptance criterion and spec item: covered, gap or',
+    '  unverified, each with evidence.',
+    '- You know only the review conclusion (PASS or PASS_WITH_FIXES), never the review',
+    '  comments. This is deliberate.',
+    '- When you find a defect the review should have caught, raise a claim in claims with your',
+    '  justification. The Inspector rules on claims; abusing them costs GT.',
+    '- For stubs and placeholders use gov_scan for evidence and report skeletonRatio with',
+    '  skeletonEvidence.',
+    '- TEST FILE OWNERSHIP: you may create or modify only the test paths declared in the files',
+    '  of the work package you are testing, or tests/<wpId>/ when that work package registered',
+    '  that directory. Writes anywhere else are detected and reported to the Inspector as',
+    '  ownership violations.',
+    '- Do not read the governance store. Use gov_read for the material you may see.',
+];
+/** The INSP mandate (6.4), adopted verbatim apart from the line wrapping. */
+const INSP_DUTIES = [
+    'You are the Inspector: the fourth power. You are independent of development, review and',
+    'testing and you are NOT scored. Your mandate is impartial enforcement: fair accounting,',
+    'rule-based arbitration and objective findings. You have full visibility (gov_read with no',
+    'restrictions).',
+    '- The rule engine already booked every mechanical event (see the event log in your brief).',
+    '  Do not re-book them. You book only judgment events with ledger_apply, and EVERY one needs',
+    '  concrete evidence (files, lines, quotes). No evidence, no event.',
+    '- Rule on every open claim with ledger_rule. Ruling priority: spec text > charter and',
+    '  contracts > general engineering practice. Your ruling is final unless you escalate to the',
+    '  user.',
+    '- Escalate (ledger_settle.escalations) only for fundamental disputes you cannot settle from',
+    '  the spec.',
+    '- Settle stage: audit claims, check scope narrowing / rubber-stamp patterns the engine',
+    '  flagged, award or withhold discretionary bonuses, check each contract statically on both',
+    '  sides.',
+    '- Integrate stage: run the registered integration commands (bash is restricted to them),',
+    '  then call ledger_settle with the result. On failure include a structured RCA: failing',
+    '  checks, whether the failure is at a module boundary, attribution per agent (primary /',
+    '  contributing / oversight) and contract kind, and whether it is systemic. Attribute only',
+    '  what you can show in code.',
+    'You must finish with exactly one ledger_settle call. Be specific, be fair, be brief.',
+];
+const DEV_BOUNDARY = 'INFORMATION BOUNDARY: you see the specification excerpt, your work package, the contracts, ' +
+    'your own submissions and the REQUIRED CHANGES of a rejection. You do not see reviewer ' +
+    'identities, other review comments, test reports or other agents\' scores beyond the public ' +
+    'standings.';
+const REV_BOUNDARY = 'INFORMATION BOUNDARY: you see the specification excerpt, the work package, the contracts, ' +
+    'the submission under review and your own earlier reviews. You do not see test results.';
+const TEST_BOUNDARY = 'INFORMATION BOUNDARY: you see the specification excerpt, the work package, the contracts, ' +
+    'the developer\'s change list and the review verdict. You do not see review comments.';
+const INSP_BOUNDARY = 'INFORMATION BOUNDARY: you have full visibility of submissions, review comments, test ' +
+    'reports and the event log.';
+const DEV_SUBMIT = 'SUBMISSION: when you are done call gov_submit_work exactly once for your work package. ' +
+    'Include interfaceContracts for every interface you produce or consume and how you verified ' +
+    'it. A second submission for the same work package is not accepted. A NOT ACCEPTED answer ' +
+    'costs no GT: fix what it names and call again.';
+const REV_SUBMIT = 'SUBMISSION: for EACH work package assigned to you call gov_submit_review exactly once: one ' +
+    'call per work package, in the listed order. Do not merge work packages, do not skip one, ' +
+    'and never cite one work package\'s findings in another work package\'s review. A second ' +
+    'submission for the same work package is not accepted. A NOT ACCEPTED answer costs no GT: ' +
+    'fix what it names and call again.';
+const TEST_SUBMIT = 'SUBMISSION: for EACH work package assigned to you call gov_submit_test exactly once: one ' +
+    'call per work package, in the listed order. Do not merge work packages and do not skip ' +
+    'one. A second submission for the same work package is not accepted. A NOT ACCEPTED answer ' +
+    'costs no GT: fix what it names and call again.';
+function rolePartsFor(ext) {
+    switch (ext.role) {
+        case 'DEV':
+            return {
+                duties: ext.stage === 'fix' ? FIX_DUTIES : DEV_DUTIES,
+                boundary: DEV_BOUNDARY,
+                submit: DEV_SUBMIT,
+            };
+        case 'REV':
+            return { duties: REV_DUTIES, boundary: REV_BOUNDARY, submit: REV_SUBMIT };
+        case 'TEST':
+            return { duties: TEST_DUTIES, boundary: TEST_BOUNDARY, submit: TEST_SUBMIT };
+        case 'INSP':
+            return { duties: INSP_DUTIES, boundary: INSP_BOUNDARY, submit: null };
+    }
+}
+function commandsSection(commands) {
+    const listed = (commands ?? []).slice(0, MAX_COMMANDS_LISTED);
+    if (listed.length === 0) {
+        return [
+            'REGISTERED INTEGRATION COMMANDS: none. Report "no automated integration tests registered;',
+            'static verification only" and verify the contracts by reading code.',
+        ];
+    }
+    return ['REGISTERED INTEGRATION COMMANDS:', ...listed.map((c) => `- ${oneLine(c, 300)}`)];
+}
+function article(role) {
+    return role === 'INSP' ? 'an' : 'a';
+}
+/**
+ * The full role block for one child. Pure: the same `(ext, extra)` always yields the same
+ * text, so the spec-builder tests can compare blocks byte for byte.
+ *
+ * The version line sits right after the identity line so that the block can END on
+ * `REPORT_LANGUAGE_LINE`, as 6.4 specifies.
+ */
+export function buildRoleBlock(ext, extra = {}) {
+    const parts = rolePartsFor(ext);
+    const lines = [
+        '<governance_role>',
+        `You are ${ext.identity}, ${article(ext.role)} ${ext.role} agent in governed run ` +
+            `${ext.runId}, phase ${ext.phase}.`,
+        `Block version: ${GOVERNANCE_ROLE_BLOCK_VERSION}`,
+        profilePrefix(getProfile(ext.profile), ext.role),
+    ];
+    if (ext.predecessorAnalysis) {
+        lines.push(...predecessorSection(ext.predecessorAnalysis, ext.tokens));
+    }
+    if (ext.role !== 'INSP')
+        lines.push(scoringProtocol(ext.tokens));
+    lines.push(...assignmentSection(ext), ...parts.duties);
+    if (ext.role === 'INSP')
+        lines.push(...commandsSection(extra.integrationCommands));
+    lines.push(parts.boundary);
+    if (parts.submit)
+        lines.push(parts.submit);
+    lines.push(REPORT_LANGUAGE_LINE, '</governance_role>');
+    return lines.join('\n');
+}

package/dist/governance/report-reader.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Read-only report lookup for `/gov report` (governance-mode-v1-1 7.2, V-7).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * WHAT IT READS. Files the engine already wrote, in a fixed order of preference: the final
+ * report (`reports/final.md`, written at close or abandon), else the newest phase report
+ * (`reports/phase-<n>.md`), else the `board.md` projection. It never regenerates anything -
+ * a historical run has no live engine to ask - and it takes no lock and changes no state,
+ * which is why it is safe in any session and any posture.
+ *
+ * THE FILE NAMES NEVER COME FROM THE USER. Only the run id does, and it is checked against
+ * `RUN_ID_PATTERN` BEFORE the store is touched (the store re-validates: two doors, one
+ * rule), because that id is the one caller-influenced segment of the path.
+ */
+import type { RunStore } from './store/run-store.js';
+export type RunReportResult = {
+    kind: 'ok';
+    runId: string;
+    file: string;
+    text: string;
+    path: string;
+} | {
+    kind: 'missing';
+    runId: string;
+} | {
+    kind: 'bad_id';
+};
+type ReportStore = Pick<RunStore, 'readRunFile' | 'listRunDir' | 'runDir'>;
+export declare function readRunReport(store: ReportStore, runId: string): Promise<RunReportResult>;
+export {};

package/dist/governance/report-reader.js

@@ -0,0 +1,57 @@
+/**
+ * Read-only report lookup for `/gov report` (governance-mode-v1-1 7.2, V-7).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * WHAT IT READS. Files the engine already wrote, in a fixed order of preference: the final
+ * report (`reports/final.md`, written at close or abandon), else the newest phase report
+ * (`reports/phase-<n>.md`), else the `board.md` projection. It never regenerates anything -
+ * a historical run has no live engine to ask - and it takes no lock and changes no state,
+ * which is why it is safe in any session and any posture.
+ *
+ * THE FILE NAMES NEVER COME FROM THE USER. Only the run id does, and it is checked against
+ * `RUN_ID_PATTERN` BEFORE the store is touched (the store re-validates: two doors, one
+ * rule), because that id is the one caller-influenced segment of the path.
+ */
+import { join } from 'node:path';
+import { RUN_ID_PATTERN } from './limits.js';
+const PHASE_REPORT = /^phase-(\d+)\.md$/;
+/** The newest `reports/phase-<n>.md` name, or null. */
+async function newestPhaseReport(store, runId) {
+    const entries = await store.listRunDir(runId, 'reports').catch(() => []);
+    let best = null;
+    for (const entry of entries) {
+        const match = PHASE_REPORT.exec(entry.name);
+        if (!match || entry.isDirectory)
+            continue;
+        const n = Number(match[1]);
+        if (best === null || n > best.n)
+            best = { n, name: entry.name };
+    }
+    return best === null ? null : `reports/${best.name}`;
+}
+/** The file's text when it exists and says something, else null. */
+async function readNonEmpty(store, runId, rel) {
+    const text = await store.readRunFile(runId, rel);
+    return text === null || text.trim() === '' ? null : text;
+}
+export async function readRunReport(store, runId) {
+    if (!RUN_ID_PATTERN.test(runId))
+        return { kind: 'bad_id' };
+    const found = (file, text) => ({
+        kind: 'ok',
+        runId,
+        file,
+        text,
+        path: join(store.runDir(runId), ...file.split('/')),
+    });
+    const final = await readNonEmpty(store, runId, 'reports/final.md');
+    if (final !== null)
+        return found('reports/final.md', final);
+    const phaseFile = await newestPhaseReport(store, runId);
+    const phase = phaseFile === null ? null : await readNonEmpty(store, runId, phaseFile);
+    if (phaseFile !== null && phase !== null)
+        return found(phaseFile, phase);
+    const board = await readNonEmpty(store, runId, 'board.md');
+    return board === null ? { kind: 'missing', runId } : found('board.md', board);
+}

package/dist/governance/roles.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Identities, roster sizing and work-package assignment (governance-mode 5.2).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned). Pure: no I/O, no clock, no randomness, so a
+ * resumed run recomputes exactly the same roster.
+ *
+ * IDENTITIES ARE LEDGER ENTITIES, NOT PROCESSES (5.2). Every dispatch builds a fresh
+ * `Agent`; continuity comes from the ledger and the artifact store. The id is also the
+ * subagent `label`, so it must satisfy the label rule `[a-z0-9-]{1,12}` AND must never be
+ * the reserved aggregate label `team` (a child labelled `team` would be addressed by
+ * `team_send {to:"team"}` as a broadcast). Ids here are `<prefix><slot>` and
+ * `<id>-r<generation>`, which cannot spell `team` by construction.
+ *
+ * "THE WRITER NEVER REVIEWS THEMSELF" IS STRUCTURAL: DEV, REV and TEST ids come from three
+ * disjoint prefixes, so no assignment function can hand a work package's author the review
+ * of it.
+ */
+import type { GovRole, ScoredRole } from './types.js';
+/** The subagent label rule every identity satisfies. */
+export declare const IDENTITY_ID_PATTERN: RegExp;
+/** The single inspector's id. Never scored, never respawned. */
+export declare const INSPECTOR_ID = "insp";
+export interface ParsedIdentity {
+    role: GovRole;
+    /** 1-based roster slot (the number in `dev2`); 0 for the inspector. */
+    slot: number;
+    /** 0 = original, n = n-th respawn. */
+    generation: number;
+}
+/** The roster id of slot `slot` (1-based) of a scored role: `dev1`, `rev2`, `tst1`. */
+export declare function makeIdentityId(role: ScoredRole, slot: number): string;
+/** `dev2` -> `dev2-r1`; `dev2-r1` -> `dev2-r2`. The base slot never changes. */
+export declare function respawnIdentityId(predecessorId: string): string;
+/** Inverse of `makeIdentityId` / `respawnIdentityId`; `null` for anything else. */
+export declare function parseIdentityId(id: string): ParsedIdentity | null;
+/** The ids `dev1..devN` for `count` slots of `role`. */
+export declare function rosterIds(role: ScoredRole, count: number): string[];
+export interface RosterSizes {
+    dev: number;
+    rev: number;
+    test: number;
+}
+/**
+ * Roster size for `wpCount` work packages (5.2): `DEV = K`, `REV = TEST =
+ * clamp(ceil(K/2), 1, 3)`. `stageWidthCap` (the user's `team.maxSubagents`, D-24) bounds the
+ * REV / TEST counts, because those are exactly the identities that run side by side in one
+ * review / test stage. DEV is NOT bounded: the engine splits a wide dev stage into chunks
+ * (the `NEXT` it prints is already chunked), so the roster may exceed one dispatch.
+ */
+export declare function rosterSizes(wpCount: number, stageWidthCap: number): RosterSizes;
+export interface RoleAssignment {
+    identity: string;
+    /** Work packages in the order the prompt lists them. */
+    wpIds: string[];
+}
+export interface AssignOptions {
+    /** The work packages to assign this stage, in plan order. */
+    wpIds: readonly string[];
+    /** Active identities of ONE role, in roster order. Must not be empty. */
+    identities: readonly string[];
+    /**
+     * `wpId -> identity` that handled this WP at an earlier attempt. Sticky: the reviewer of a
+     * reworked WP must be the same reviewer (appeal responses and "same problem" fingerprints
+     * need continuity, 5.2).
+     */
+    sticky?: Readonly<Record<string, string>>;
+    /** `eliminatedId -> successorId`; a respawned identity takes over its predecessor's WPs. */
+    takeover?: Readonly<Record<string, string>>;
+}
+/**
+ * Assign work packages to identities.
+ *
+ * 1. A WP with a sticky preference goes to that identity - or to its successor if it was
+ *    replaced - as long as the result is an active identity.
+ * 2. Every other WP goes to the identity with the fewest WPs so far, ties broken by roster
+ *    order. With no stickiness this is exactly "WP i goes to identity i mod M" (5.2); with
+ *    stickiness it keeps the load level instead of piling every new WP on the identity that
+ *    happens to come next in a fixed rotation.
+ *
+ * Identities that receive nothing are omitted, so the caller dispatches no idle child.
+ * Deterministic: the same input always yields the same output.
+ */
+export declare function assignRoundRobin(options: AssignOptions): RoleAssignment[];