@aragon-agent/cli 0.6.43 → 0.6.45

package/dist/governance/posture-transition.js

@@ -0,0 +1,44 @@
+/**
+ * The posture transition rule (governance-mode 4.2, D-23) as a pure function.
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned). No React, no I/O.
+ *
+ * It is the governance twin of `AgentController.setAgentMode`'s "tighten at once, loosen
+ * later" rule, extended with the one case the two-state mode never had: a governed STAGE in
+ * flight. Children read the lead's LIVE gate mode, so tightening to plan mid-stage would
+ * deny every running child its next write (RV-2); any change is therefore deferred until
+ * the stage ends, and Esc is the only way to stop it now.
+ */
+import { composePosture, splitPosture } from './posture.js';
+export function decidePostureTransition(input) {
+    const { current, target } = input;
+    const want = splitPosture(target);
+    const stay = (pending, why) => ({
+        mode: current.mode,
+        governOn: current.governOn,
+        pending,
+        deferredBecause: why,
+    });
+    if (want.mode === current.mode && want.governance === current.governOn) {
+        return stay(null, null);
+    }
+    // D-23: a governed stage is in flight - defer EVERY change, tightening included.
+    if (current.governOn && input.stageRunning)
+        return stay(target, 'stage');
+    const adopt = () => ({
+        mode: want.mode,
+        governOn: want.governance,
+        pending: null,
+        deferredBecause: null,
+    });
+    // Tightening to plan is always safe and immediate.
+    if (want.mode === 'plan')
+        return adopt();
+    if (input.force || !input.running)
+        return adopt();
+    return stay(target, 'running');
+}
+/** The posture a (mode, governOn) pair denotes; re-exported so callers import one module. */
+export function postureOf(mode, governOn) {
+    return composePosture(mode, governOn);
+}

package/dist/governance/posture.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Posture - the user-visible composite of (gate mode, governance on)
+ * (governance-mode section 4.1).
+ *
+ * Pure: no React, no I/O, no `node:*`. ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * WHY A COMPOSITE AND NOT A THIRD/FOURTH `AgentMode` (D-1). `AgentMode` is
+ * `'build' | 'plan'` and 25+ sites key off that pair (`=== 'plan'`,
+ * `Record<AgentMode, ...>`, the plan gate, the subagent `getMode`). Widening it needs a
+ * silent-failure audit of every one of them (a miss means "writable when it should be
+ * read-only"). Two orthogonal dimensions leave every existing path untouched.
+ */
+import type { AgentMode } from '../agent/agent-mode.js';
+export type Posture = 'build' | 'plan' | 'govern' | 'plan_govern';
+/** Full Shift+Tab cycle: BUILD -> PLAN -> GOVERN -> PLAN+GOVERN -> BUILD. */
+export declare const POSTURES_FULL: readonly Posture[];
+/** The classic two-state cycle, used whenever governance is unavailable or switched off. */
+export declare const POSTURES_CLASSIC: readonly Posture[];
+export declare const POSTURE_LABEL: Record<Posture, string>;
+/** Lower-case spelling for the `shift+tab <next>` hint clause. */
+export declare function postureHintWord(posture: Posture): string;
+/** (gate mode, governance on) -> posture. Exhaustive; the one place the mapping lives. */
+export declare function composePosture(mode: AgentMode, governanceOn: boolean): Posture;
+/** posture -> (gate mode, governance on). Inverse of `composePosture`. */
+export declare function splitPosture(posture: Posture): {
+    mode: AgentMode;
+    governance: boolean;
+};
+/** True when the posture has governance switched on. */
+export declare function isGovernancePosture(posture: Posture): boolean;
+/**
+ * The next posture in `cycle`. A `current` outside the cycle (e.g. `govern` while the
+ * cycle is classic) advances to `'build'` - never throws, never loops on itself.
+ */
+export declare function nextPosture(current: Posture, cycle: readonly Posture[]): Posture;

package/dist/governance/posture.js

@@ -0,0 +1,59 @@
+/**
+ * Posture - the user-visible composite of (gate mode, governance on)
+ * (governance-mode section 4.1).
+ *
+ * Pure: no React, no I/O, no `node:*`. ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * WHY A COMPOSITE AND NOT A THIRD/FOURTH `AgentMode` (D-1). `AgentMode` is
+ * `'build' | 'plan'` and 25+ sites key off that pair (`=== 'plan'`,
+ * `Record<AgentMode, ...>`, the plan gate, the subagent `getMode`). Widening it needs a
+ * silent-failure audit of every one of them (a miss means "writable when it should be
+ * read-only"). Two orthogonal dimensions leave every existing path untouched.
+ */
+/** Full Shift+Tab cycle: BUILD -> PLAN -> GOVERN -> PLAN+GOVERN -> BUILD. */
+export const POSTURES_FULL = ['build', 'plan', 'govern', 'plan_govern'];
+/** The classic two-state cycle, used whenever governance is unavailable or switched off. */
+export const POSTURES_CLASSIC = ['build', 'plan'];
+export const POSTURE_LABEL = {
+    build: 'BUILD',
+    plan: 'PLAN',
+    govern: 'GOVERN',
+    plan_govern: 'PLAN+GOVERN',
+};
+/** Lower-case spelling for the `shift+tab <next>` hint clause. */
+export function postureHintWord(posture) {
+    return POSTURE_LABEL[posture].toLowerCase();
+}
+/** (gate mode, governance on) -> posture. Exhaustive; the one place the mapping lives. */
+export function composePosture(mode, governanceOn) {
+    if (mode === 'plan')
+        return governanceOn ? 'plan_govern' : 'plan';
+    return governanceOn ? 'govern' : 'build';
+}
+/** posture -> (gate mode, governance on). Inverse of `composePosture`. */
+export function splitPosture(posture) {
+    switch (posture) {
+        case 'build':
+            return { mode: 'build', governance: false };
+        case 'plan':
+            return { mode: 'plan', governance: false };
+        case 'govern':
+            return { mode: 'build', governance: true };
+        case 'plan_govern':
+            return { mode: 'plan', governance: true };
+    }
+}
+/** True when the posture has governance switched on. */
+export function isGovernancePosture(posture) {
+    return posture === 'govern' || posture === 'plan_govern';
+}
+/**
+ * The next posture in `cycle`. A `current` outside the cycle (e.g. `govern` while the
+ * cycle is classic) advances to `'build'` - never throws, never loops on itself.
+ */
+export function nextPosture(current, cycle) {
+    const index = cycle.indexOf(current);
+    if (index < 0)
+        return 'build';
+    return cycle[(index + 1) % cycle.length];
+}

package/dist/governance/profiles.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Domain profiles (governance-mode 6.6): the persona prefix each governed child opens with.
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * NAMED BY DOMAIN, NOT BY EMPLOYER (N3). The reference `team-profiles.md` casts each team
+ * as engineers of a named company; shipping that would imply an affiliation that does not
+ * exist, for the same reason `palettes.ts` names themes by hue. What carries over is the
+ * ROLE POSITIONING: what a reviewer of that domain checks first, what a tester of that
+ * domain refuses to take on faith. The persona sentence is a nudge, not an identity claim.
+ *
+ * Each of `developer` / `reviewer` / `tester` is bounded by `PROFILE_PREFIX_MAX_CHARS` so a
+ * profile can never crowd out the scoring protocol and the brief inside the child prompt;
+ * `governance-prompts.test.ts` pins the bound for every profile.
+ */
+import type { GovRole, ProfileId } from './types.js';
+/** Upper bound for every persona prefix (6.6). */
+export declare const PROFILE_PREFIX_MAX_CHARS = 600;
+export interface GovernanceProfile {
+    id: ProfileId;
+    /** Short name for settings and `/gov` output. */
+    label: string;
+    /** One line: what the profile is for. */
+    description: string;
+    developer: string;
+    reviewer: string;
+    tester: string;
+}
+/**
+ * Shared by every profile: the inspector is domain-independent and there is exactly one per
+ * run (6.6). It states the mandate that 6.4 repeats in operational form.
+ */
+export declare const INSPECTOR_PREFIX: string;
+/** True when `value` names a shipped profile. */
+export declare function isProfileId(value: unknown): value is ProfileId;
+/**
+ * The profile for `id`; anything unknown (including `undefined`) resolves to `general`.
+ *
+ * Falling back instead of throwing is deliberate: the id arrives from a persisted run or a
+ * config file, and an unreadable profile must not take a whole stage down. The engine
+ * validates the orchestrator's `profile` argument at `start` and rejects bad values loudly
+ * THERE; this function only has to be safe for data that already passed that gate.
+ */
+export declare function getProfile(id: ProfileId | string | undefined): GovernanceProfile;
+/** All shipped profiles, in the order the settings UI lists them. */
+export declare function listProfiles(): GovernanceProfile[];
+/** The persona prefix for one role of one profile. */
+export declare function profilePrefix(profile: GovernanceProfile, role: GovRole): string;

package/dist/governance/profiles.js

@@ -0,0 +1,140 @@
+/**
+ * Domain profiles (governance-mode 6.6): the persona prefix each governed child opens with.
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * NAMED BY DOMAIN, NOT BY EMPLOYER (N3). The reference `team-profiles.md` casts each team
+ * as engineers of a named company; shipping that would imply an affiliation that does not
+ * exist, for the same reason `palettes.ts` names themes by hue. What carries over is the
+ * ROLE POSITIONING: what a reviewer of that domain checks first, what a tester of that
+ * domain refuses to take on faith. The persona sentence is a nudge, not an identity claim.
+ *
+ * Each of `developer` / `reviewer` / `tester` is bounded by `PROFILE_PREFIX_MAX_CHARS` so a
+ * profile can never crowd out the scoring protocol and the brief inside the child prompt;
+ * `governance-prompts.test.ts` pins the bound for every profile.
+ */
+/** Upper bound for every persona prefix (6.6). */
+export const PROFILE_PREFIX_MAX_CHARS = 600;
+/**
+ * Shared by every profile: the inspector is domain-independent and there is exactly one per
+ * run (6.6). It states the mandate that 6.4 repeats in operational form.
+ */
+export const INSPECTOR_PREFIX = 'You are the independent Inspector in a three-powers governance system. You are the ' +
+    'fourth power, separate from development, review and testing. Your mandate is impartial ' +
+    'enforcement: fair token accounting, rule-based arbitration and objective findings. You ' +
+    'have full visibility into all agent outputs. You are not subject to GT evaluation. You ' +
+    'operate strictly by the rules you are given.';
+const GENERAL = {
+    id: 'general',
+    label: 'General',
+    description: 'General-purpose software: services, libraries, tooling, infrastructure.',
+    developer: 'You are a senior software engineer with 10+ years of production experience. You ' +
+        'follow disciplined engineering practice: a clear design before code, readable and ' +
+        'maintainable structure, comprehensive tests, clean abstractions. You write ' +
+        'production-grade code with proper error handling, logging and monitoring hooks.',
+    reviewer: 'You are a senior code reviewer who enforces strict readability and maintainability ' +
+        'standards: every change must be readable, well tested and honest about its limits. ' +
+        'You check adherence to the project style, abstraction boundaries, meaningful naming ' +
+        'and complete error handling. You reject code that would not survive a rigorous ' +
+        'readability review. Your reviews are specific, actionable and cite concrete practice.',
+    tester: 'You are a senior test engineer. You test at the right level (unit, integration, end ' +
+        'to end), aim for meaningful coverage rather than line counts, and keep tests fast, ' +
+        'reliable and maintainable. Your tests serve as living documentation. You verify edge ' +
+        'cases, error paths and boundary conditions, and you trace every spec requirement to ' +
+        'at least one test.',
+};
+const ML = {
+    id: 'ml',
+    label: 'ML / data',
+    description: 'Machine learning systems, data pipelines, algorithm-heavy features.',
+    developer: 'You are a senior engineer specializing in AI and ML systems. You bring research rigor ' +
+        'to production code: reproducible experiments, documented model assumptions, efficient ' +
+        'data pipelines, and careful handling of numerical precision and edge cases.',
+    reviewer: 'You are a senior ML code reviewer. You focus on numerical correctness, ' +
+        'reproducibility and scientific rigor. You verify that model assumptions are ' +
+        'documented, random seeds are controlled, data transformations preserve semantics, and ' +
+        'pipeline stages handle edge cases (empty batches, NaN values, shape mismatches). You ' +
+        'enforce a clean separation between experiment configuration and implementation.',
+    tester: 'You are a senior ML test engineer. You design tests for ML systems: deterministic ' +
+        'unit tests with fixed seeds, property-based tests for mathematical invariants, ' +
+        'integration tests for data pipelines, and validation tests that keep model outputs ' +
+        'inside expected distributions. You check numerical stability, data leakage between ' +
+        'train and test splits, and regression in model behavior.',
+};
+const PRODUCT = {
+    id: 'product',
+    label: 'Product',
+    description: 'Consumer products, real-time features, React-style frontends, mobile-first.',
+    developer: 'You are a senior engineer experienced in high-scale distributed systems and consumer ' +
+        'products. You prioritize rapid iteration, user-facing quality, real-time performance ' +
+        'and mobile-first design, and you build on scalable data layers and component-based ' +
+        'frontends.',
+    reviewer: 'You are a senior code reviewer focused on performance at scale and user experience. ' +
+        'You check for unnecessary re-renders, inefficient queries, missing loading and error ' +
+        'states, accessibility violations and responsiveness problems. You enforce ' +
+        'ship-fast-but-safely: code must be functional, performant and user-friendly even in ' +
+        'rapid iteration cycles.',
+    tester: 'You are a senior QA engineer. You test real-world user scenarios at scale: ' +
+        'concurrent users, flaky networks, diverse device sizes, and edge cases such as empty ' +
+        'feeds, blocked users and rate limits. You write automated tests and manual test ' +
+        'plans, and verify component rendering, response handling and real-time update ' +
+        'propagation.',
+};
+const API_SECURITY = {
+    id: 'api-security',
+    label: 'API / security',
+    description: 'API platforms, payment-like flows, developer tools, security-critical code.',
+    developer: 'You are a senior engineer focused on API design excellence and security-first ' +
+        'development. You write bulletproof error handling, keep strict backward ' +
+        'compatibility, produce clear API documentation, and treat every input as potentially ' +
+        'malicious.',
+    reviewer: 'You are a senior API reviewer. You enforce high API quality standards: consistent ' +
+        'naming, idempotency keys, proper status codes, structured error objects with ' +
+        'actionable messages, backward compatibility, and input validation that assumes ' +
+        'hostile input. You reject any change that would break existing integrations or ' +
+        'expose sensitive data, and you verify that every error path returns a structured, ' +
+        'developer-friendly response.',
+    tester: 'You are a senior QA engineer for security-critical systems with zero tolerance for ' +
+        'silent errors. You test idempotency behavior, races between concurrent requests, ' +
+        'invalid and malicious inputs, graceful degradation under partial failure, and exact ' +
+        'money arithmetic (never floating point). You cover every error code and verify API ' +
+        'versioning behavior and sensitive-data handling.',
+};
+const PROFILES = {
+    general: GENERAL,
+    ml: ML,
+    product: PRODUCT,
+    'api-security': API_SECURITY,
+};
+/** True when `value` names a shipped profile. */
+export function isProfileId(value) {
+    return typeof value === 'string' && Object.prototype.hasOwnProperty.call(PROFILES, value);
+}
+/**
+ * The profile for `id`; anything unknown (including `undefined`) resolves to `general`.
+ *
+ * Falling back instead of throwing is deliberate: the id arrives from a persisted run or a
+ * config file, and an unreadable profile must not take a whole stage down. The engine
+ * validates the orchestrator's `profile` argument at `start` and rejects bad values loudly
+ * THERE; this function only has to be safe for data that already passed that gate.
+ */
+export function getProfile(id) {
+    return isProfileId(id) ? PROFILES[id] : GENERAL;
+}
+/** All shipped profiles, in the order the settings UI lists them. */
+export function listProfiles() {
+    return [GENERAL, ML, PRODUCT, API_SECURITY];
+}
+/** The persona prefix for one role of one profile. */
+export function profilePrefix(profile, role) {
+    switch (role) {
+        case 'DEV':
+            return profile.developer;
+        case 'REV':
+            return profile.reviewer;
+        case 'TEST':
+            return profile.tester;
+        case 'INSP':
+            return INSPECTOR_PREFIX;
+    }
+}

package/dist/governance/prompts/orchestrator-block.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The Orchestrator's `<governance_mode>` system-prompt block (governance-mode 6.2).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * THE PROSE IS THE SPEC'S, ADOPTED VERBATIM; the numbers are not. Every figure the model
+ * reads here (work-package ceiling, phases, rework rounds, fix cycles, budget) is passed in
+ * by the caller from the LIVE config clamped against `GOV_LIMITS`, never written as a
+ * literal: a prompt that says "4 WPs" while the engine allows 6 makes the model refuse work
+ * the engine would accept (the `planModeMaxAskRounds` lesson, 6.1).
+ *
+ * THE PLAN-PHASE VARIANT. In PLAN+GOVERN the block is spliced in BEFORE the plan is
+ * approved. The system prompt is captured by value, so it cannot be re-issued at approval;
+ * the full block therefore ships from the start, preceded by one paragraph that says the
+ * tools are suspended and that `task` stays available for read-only research (the gate
+ * refuses `task` only when the gate mode is `build`, 6.1).
+ */
+import { type Posture } from '../posture.js';
+import { GOVERNANCE_BLOCK_VERSION } from '../limits.js';
+export { GOVERNANCE_BLOCK_VERSION };
+/** The live policy values the block quotes. All are clamped here against `GOV_LIMITS`. */
+export interface OrchestratorLimits {
+    maxWorkPackages: number;
+    maxPhases: number;
+    maxRework: number;
+    maxFixCycles: number;
+    /** Team token budget; 0 or absent means unlimited. */
+    budgetTokens?: number;
+}
+export interface OrchestratorBlockOptions {
+    posture: Posture;
+    limits: OrchestratorLimits;
+}
+/** The single paragraph that prefixes the full block while the plan is still being made. */
+export declare const PLAN_PHASE_NOTICE: string;
+/**
+ * The block for a governance posture; `''` for `build` / `plan` (the caller then splices
+ * nothing, which is what keeps the governance-off system prompt byte-identical).
+ */
+export declare function buildOrchestratorBlock(options: OrchestratorBlockOptions): string;

package/dist/governance/prompts/orchestrator-block.js

@@ -0,0 +1,128 @@
+/**
+ * The Orchestrator's `<governance_mode>` system-prompt block (governance-mode 6.2).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * THE PROSE IS THE SPEC'S, ADOPTED VERBATIM; the numbers are not. Every figure the model
+ * reads here (work-package ceiling, phases, rework rounds, fix cycles, budget) is passed in
+ * by the caller from the LIVE config clamped against `GOV_LIMITS`, never written as a
+ * literal: a prompt that says "4 WPs" while the engine allows 6 makes the model refuse work
+ * the engine would accept (the `planModeMaxAskRounds` lesson, 6.1).
+ *
+ * THE PLAN-PHASE VARIANT. In PLAN+GOVERN the block is spliced in BEFORE the plan is
+ * approved. The system prompt is captured by value, so it cannot be re-issued at approval;
+ * the full block therefore ships from the start, preceded by one paragraph that says the
+ * tools are suspended and that `task` stays available for read-only research (the gate
+ * refuses `task` only when the gate mode is `build`, 6.1).
+ */
+import { isGovernancePosture } from '../posture.js';
+import { GOV_LIMITS, GOVERNANCE_BLOCK_VERSION } from '../limits.js';
+export { GOVERNANCE_BLOCK_VERSION };
+/** The single paragraph that prefixes the full block while the plan is still being made. */
+export const PLAN_PHASE_NOTICE = 'GOVERNANCE MODE is ON but PLAN mode is active: gov_run and gov_dispatch are suspended ' +
+    'until your plan is approved. Plan for execution by a governed team (see <plan_mode>). ' +
+    'After approval you become the Orchestrator and the rules of this block apply. Until ' +
+    'then the task tool stays available for read-only research (this overrides the task ' +
+    'refusal listed below).';
+function clampInt(value, min, max) {
+    const n = Number.isFinite(value) ? Math.floor(value) : min;
+    return Math.min(max, Math.max(min, n));
+}
+/** "2-4 WPs" under the default ceiling; never advertises more than the ceiling allows. */
+function preferredRange(maxWorkPackages) {
+    if (maxWorkPackages < 2)
+        return '1 WP';
+    return `2-${Math.min(4, maxWorkPackages)} WPs`;
+}
+function limitsLines(limits) {
+    const wps = clampInt(limits.maxWorkPackages, 1, GOV_LIMITS.hardMaxWorkPackages);
+    const phases = clampInt(limits.maxPhases, 1, GOV_LIMITS.hardMaxPhases);
+    const rework = clampInt(limits.maxRework, 1, GOV_LIMITS.hardMaxRework);
+    const fixes = clampInt(limits.maxFixCycles, 1, GOV_LIMITS.hardMaxFixCycles);
+    const budget = clampInt(limits.budgetTokens ?? 0, 0, Number.MAX_SAFE_INTEGER);
+    const budgetText = budget > 0
+        ? `The team token budget is ${budget} LLM tokens (team spend only).`
+        : 'No team token budget is set.';
+    return [
+        `Limits: up to ${wps} work packages and ${phases} phases per run. A work package may be`,
+        `reworked ${rework} times and a phase gets ${fixes} integration fix cycles before the engine`,
+        `escalates to the user; at most ${GOV_LIMITS.hardMaxDispatches} gov_dispatch calls per run.`,
+        budgetText,
+    ];
+}
+function powersSection() {
+    return [
+        'GOVERNANCE MODE is ON. You are the Orchestrator of a governed engineering team.',
+        'You do not write code.',
+        '',
+        'The team follows a separation of powers:',
+        '- DEV (development): implements one work package each.',
+        '- REV (review): reviews independently; may reject, or fix minor issues directly.',
+        '- TEST (testing): verifies behavior and traces every requirement to evidence.',
+        '- INSP (inspector): the fourth power. Arbitrates disputes, verifies integration, and rules on',
+        '  scoring claims. It is not scored.',
+        'Agents hold GT (governance tokens): a score for this run, unrelated to LLM context tokens.',
+        'The rule engine awards and deducts GT automatically from structured verdicts. You cannot',
+        'edit scores and you never need to.',
+        '',
+        'Your tools: gov_run, gov_dispatch, ask_user, todo_write, and every tool that only reads',
+        '(read_file, list_dir, glob, grep, skill, skill_find, bash_output, job_wait, job_list).',
+        'write_file, edit_file, bash, bash_kill, skill_install, skill_create and task are refused in',
+        'this mode on purpose: all implementation happens through dispatched agents.',
+    ];
+}
+function startSteps(maxWorkPackages) {
+    const wps = clampInt(maxWorkPackages, 1, GOV_LIMITS.hardMaxWorkPackages);
+    return [
+        '1. Understand the request. Read just enough of the workspace to define work packages (WPs).',
+        '   Ask the user only when a blocking decision cannot be settled by reading. If the user only',
+        '   asks a question, answer it directly and do not start a run.',
+        '2. Call gov_run {action:"start"} with: goal; spec (the user\'s requirement, or the approved',
+        '   plan, complete and verbatim); workPackages (id, title, goal, owned files, acceptance',
+        '   criteria, dependsOn); contracts (every interface two WPs share: producer, consumers,',
+        '   exact signature or data shape); integrationCommands (test commands the inspector may',
+        '   run); profile.',
+        '   - One WP = one agent. Two WPs that can run in the same phase must not own the same file.',
+        "   - List each WP's test paths among its owned files too: testers may write only there.",
+        `   - Prefer ${preferredRange(wps)}. Do not split work that is only a few lines.`,
+    ];
+}
+function driveSteps() {
+    return [
+        '3. Drive the run with gov_dispatch. Every gov_run and gov_dispatch result ends with NEXT: the',
+        '   legal next actions. Follow it; the engine refuses illegal stage orders.',
+        '4. Each phase runs: dev -> review -> test -> settle -> integrate (and fix, then integrate',
+        '   again, if integration fails). Rework loops are automatic: a rejected WP returns to dev',
+        '   with its required changes attached by the engine.',
+        '5. Do not write briefs for review, test, settle or integrate: the engine builds them so each',
+        '   role sees only what it is allowed to see. For dev and fix you may add a short note per WP.',
+        '6. Never relay review comments, test reports or scores between roles.',
+        '7. When a result reports an ESCALATION, put the question to the user with ask_user, then',
+        '   call gov_run {action:"resolve"} with the user\'s ruling.',
+        '8. When every phase is integrated, call gov_run {action:"close"} and report to the user:',
+        '   what was built, what was verified, the final standings, and anything unresolved.',
+    ];
+}
+/**
+ * The block for a governance posture; `''` for `build` / `plan` (the caller then splices
+ * nothing, which is what keeps the governance-off system prompt byte-identical).
+ */
+export function buildOrchestratorBlock(options) {
+    if (!isGovernancePosture(options.posture))
+        return '';
+    const lines = [
+        '<governance_mode>',
+        ...powersSection(),
+        '',
+        'How to work:',
+        ...startSteps(options.limits.maxWorkPackages),
+        ...driveSteps(),
+        ...limitsLines(options.limits),
+        'Limits and budget are printed in every result. If a run is paused, call gov_run',
+        '{action:"resume"}.',
+        `Version: ${GOVERNANCE_BLOCK_VERSION}`,
+        '</governance_mode>',
+    ];
+    const block = lines.join('\n');
+    return options.posture === 'plan_govern' ? `${PLAN_PHASE_NOTICE}\n\n${block}` : block;
+}

package/dist/governance/prompts/plan-addendum.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The PLAN+GOVERN addendum to the `<plan_mode>` block (governance-mode 6.3).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * WHY THE PLAN IS "THE SPECIFICATION". After `submit_plan` is approved a governed team
+ * executes it and the reviewers and testers judge their work AGAINST it. A plan written as
+ * a loose outline therefore produces arguments later, at the most expensive stage, so the
+ * interview that precedes it is front-loaded and the plan's step shape is prescribed.
+ *
+ * THE NUMBER COMES FROM THE LIVE CONFIG (6.1). `minRounds` is `governance.minAskRounds`,
+ * the same value `beforeSubmit` enforces; a literal here would let the prompt and the
+ * refusal disagree (the `planModeMaxAskRounds` lesson).
+ */
+import { GOVERNANCE_PLAN_ADDENDUM_VERSION } from '../limits.js';
+export { GOVERNANCE_PLAN_ADDENDUM_VERSION };
+/**
+ * The text appended after the `<plan_mode>` block while the posture is PLAN+GOVERN.
+ *
+ * Ends with a version line (the block has no tag of its own to carry an attribute).
+ */
+export declare function buildPlanGovernAddendum(minRounds: number): string;

package/dist/governance/prompts/plan-addendum.js

@@ -0,0 +1,60 @@
+/**
+ * The PLAN+GOVERN addendum to the `<plan_mode>` block (governance-mode 6.3).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * WHY THE PLAN IS "THE SPECIFICATION". After `submit_plan` is approved a governed team
+ * executes it and the reviewers and testers judge their work AGAINST it. A plan written as
+ * a loose outline therefore produces arguments later, at the most expensive stage, so the
+ * interview that precedes it is front-loaded and the plan's step shape is prescribed.
+ *
+ * THE NUMBER COMES FROM THE LIVE CONFIG (6.1). `minRounds` is `governance.minAskRounds`,
+ * the same value `beforeSubmit` enforces; a literal here would let the prompt and the
+ * refusal disagree (the `planModeMaxAskRounds` lesson).
+ */
+import { GOVERNANCE_PLAN_ADDENDUM_VERSION } from '../limits.js';
+export { GOVERNANCE_PLAN_ADDENDUM_VERSION };
+const TOPIC_LIST = [
+    '  1. Goal and success criteria: what must be true when this is done?',
+    '  2. Scope: what is explicitly in and out?',
+    '  3. Constraints: stack, compatibility, performance, style, forbidden changes.',
+    '  4. Quality bar: required tests, security expectations, review strictness.',
+    '  5. Team shape and cost: how many parallel work packages are acceptable; any budget ceiling.',
+    '  6. Risks and dependencies you found in the workspace that the user must decide on.',
+];
+const PLAN_SHAPE = [
+    'Skip nothing the workspace already answers; read first. In the plan: each step is a',
+    'candidate work package with its owned files, acceptance criteria and dependencies in the',
+    'detail; list shared interfaces under risks or detail with exact signatures; put the',
+    'integration test commands in filesTouched-adjacent detail. Do not implement anything.',
+];
+function interviewSentence(rounds) {
+    if (rounds <= 0) {
+        return ('Before you plan, interview the user as far as the request needs (no minimum number ' +
+            'of rounds is enforced). Batch 1-5 questions per round and cover, in this order:');
+    }
+    return ('Before you plan, interview the user. You must complete at least ' +
+        `${rounds} answered ask_user round${rounds === 1 ? '' : 's'} ` +
+        '(submit_plan is refused until you do). Batch 1-5 questions per round and cover, in ' +
+        'this order:');
+}
+/** Clamp to a non-negative integer; the config clamp already did, this is the last line. */
+function sanitizeRounds(minRounds) {
+    return Number.isFinite(minRounds) && minRounds > 0 ? Math.floor(minRounds) : 0;
+}
+/**
+ * The text appended after the `<plan_mode>` block while the posture is PLAN+GOVERN.
+ *
+ * Ends with a version line (the block has no tag of its own to carry an attribute).
+ */
+export function buildPlanGovernAddendum(minRounds) {
+    return [
+        'PLAN+GOVERN. After you submit_plan and the user approves, a governed team will execute',
+        'this plan and the reviewers and testers will judge their work AGAINST IT, so the plan is',
+        'the specification.',
+        interviewSentence(sanitizeRounds(minRounds)),
+        ...TOPIC_LIST,
+        ...PLAN_SHAPE,
+        `Governance addendum version: ${GOVERNANCE_PLAN_ADDENDUM_VERSION}`,
+    ].join('\n');
+}

package/dist/governance/prompts/refusals.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 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).
+ */
+/**
+ * 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 declare function governRefusal(tool: string): string;
+/** `gov_run` / `gov_dispatch` while the gate mode is plan: suspended until approval. */
+export declare function govPlanPhaseRefusal(): string;
+/** `gov_run` / `gov_dispatch` after `/gov off` (the tools cannot be unregistered mid-session). */
+export declare function govOffRefusal(): string;
+/**
+ * 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 declare const PLAN_INTERVIEW_TOPICS: readonly string[];
+/**
+ * `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 declare function govAskRoundsRefusal(done: number, need: number, uncoveredTopics: readonly string[]): string;
+/**
+ * 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 declare const APPROVED_GOVERN_RESULT: string;