@aragon-agent/cli 0.6.44 → 0.6.45

package/dist/config/env.js

@@ -21,7 +21,8 @@
  *     ARAGON_COMPACTION_ARCHIVE,
  *     ARAGON_JOBS_ENABLED, ARAGON_JOBS_WAIT_SECONDS, ARAGON_JOBS_STALL_SECONDS,
  *     ARAGON_JOBS_PERSIST_LOG, ARAGON_JOBS_NOTICE_STEER,
- *     ARAGON_PROMPTS (the quick-prompt library's `enabled` switch, and only that).
+ *     ARAGON_PROMPTS (the quick-prompt library's `enabled` switch, and only that),
+ *     ARAGON_GOVERNANCE (a KILL switch: `0` disables governance mode, nothing enables it).
  *
  * READ ELSEWHERE, ON PURPOSE: `ARAGON_UPDATE_REGISTRY` and `npm_config_registry`
  * are resolved by `update/registry.ts::resolveRegistryUrl`, NOT here, because
@@ -41,6 +42,7 @@ import process from 'node:process';
 import dotenv from 'dotenv';
 import { registerSecretsFrom } from '../logging/secret-registry.js';
 import { clampLogLevel } from '../logging/levels.js';
+import { isGovernanceEnvDisabled } from './governance-config.js';
 import { clampContextWindow, clampMaxTokens, clampTheme, clampThinkingLevel, isAutoToken, parseThresholdInput, } from './schema.js';
 /**
  * Load a project `.env` from the given directory into `process.env` (existing
@@ -318,6 +320,13 @@ export function readEnvConfig() {
             enabled: prompts === '1' || prompts === 'true' || prompts === 'on' || prompts === 'yes',
         };
     }
+    // ARAGON_GOVERNANCE=0 is the governance-mode KILL switch (governance-mode 11.1): it can only
+    // switch `enabled` OFF, and it outranks the config file (the layers merge file < env). It is
+    // deliberately not a toggle - `ARAGON_GOVERNANCE=1` writes nothing, so an environment can
+    // never re-enable what the user's config or `--no-governance` turned off.
+    if (isGovernanceEnvDisabled(process.env)) {
+        partial.governance = { enabled: false };
+    }
     // ARAGON_TASK_SUMMARY is the header label's kill switch
     // (tui-shortcut-drawer-and-task-summary §4.8 / P2-7), and it maps `enabled` and
     // NOTHING ELSE - the same wording and the same reason as the block above. A

package/dist/config/governance-config.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Governance-mode configuration (governance-mode sections 11.1 / 13.2).
+ *
+ * LIVES IN ITS OWN FILE, NOT IN `schema.ts`: that file is far past the repo's
+ * 1000-line limit, and a section whose clamp depends on nothing else in it has no
+ * reason to grow it. `schema.ts` imports and re-exports everything below, so every
+ * importer still reaches the section through `config/schema.js`.
+ *
+ * SELF-CONTAINED ON PURPOSE. The integer/boolean helpers in `schema.ts` are private,
+ * and importing back from it would make a cycle (`schema.ts` re-exports this file).
+ * The two helpers here are four lines each.
+ *
+ * ASCII ONLY: `src/config/**` is inside the glyph scanner's scope.
+ */
+import type { Posture } from '../governance/posture.js';
+import { type ProfileId } from '../governance/types.js';
+export interface GovernanceConfig {
+    /** `false` => the feature is absent: no tools, no prompt blocks, no posture. */
+    enabled: boolean;
+    /** `false` => Shift+Tab stays BUILD<->PLAN; `/gov` still works. */
+    shiftTab: boolean;
+    /** `false` => the status chip only, no legion panel. */
+    panel: boolean;
+    /** Domain profile that names the roles' focus areas. */
+    profile: ProfileId;
+    /** 1..8. Work packages per run. */
+    maxWorkPackages: number;
+    /** 1..6. Phases per run. */
+    maxPhases: number;
+    /** 1..5. Rework rounds per work package. */
+    maxRework: number;
+    /** 1..5. Fix cycles per phase. */
+    maxFixCycles: number;
+    /** 0..5. Question rounds before PLAN+GOVERN may submit a plan. */
+    minAskRounds: number;
+    /** 0..1_000_000_000. Token budget per run; `0` = unlimited. */
+    budgetTokens: number;
+    /** `true` => the user approves the run charter before any dispatch. */
+    confirmCharter: boolean;
+}
+export declare const DEFAULT_GOVERNANCE_CONFIG: GovernanceConfig;
+type NumericKey = 'maxWorkPackages' | 'maxPhases' | 'maxRework' | 'maxFixCycles' | 'minAskRounds' | 'budgetTokens';
+/** The numeric keys, in display order; shared with the settings and `config` surfaces. */
+export declare const GOVERNANCE_NUMERIC_KEYS: readonly NumericKey[];
+/** The inclusive range a numeric key is clamped to. */
+export declare function governanceRangeOf(key: NumericKey): {
+    min: number;
+    max: number;
+};
+/**
+ * THE single gate for every governance-config read AND write, mirroring
+ * `clampTeamConfig` for the reason that one records: hardening only the read path
+ * leaves a bad value on disk that the read path then rewrites on every launch, which
+ * presents to the user as "my setting won't stick". Unknown keys are dropped.
+ */
+export declare function clampGovernanceConfig(raw: unknown): GovernanceConfig;
+/**
+ * `ARAGON_GOVERNANCE=0` is a KILL switch, not a toggle: it can only disable. Any other
+ * value (including `1`) is ignored, so an environment can never switch a feature ON that
+ * the user's config or a `--no-governance` flag turned off.
+ *
+ * Takes the env as a parameter so tests and `doctor` do not touch `process.env`.
+ */
+export declare function isGovernanceEnvDisabled(env?: Readonly<Record<string, string | undefined>>): boolean;
+/**
+ * The config-level reasons governance can be unavailable. A SUBSET of the
+ * `GovernanceUnavailableReason` vocabulary in `governance/copy.ts` (the controller adds
+ * `no_api_key`, `headless`, `restart_required` at runtime); the codes are spelled
+ * identically so the integration can unify the two without renaming anything.
+ */
+export type GovernanceConfigUnavailableReason = 'disabled_config' | 'disabled_env' | 'team_off';
+export type GovernanceConfigAvailability = {
+    ok: true;
+} | {
+    ok: false;
+    reason: GovernanceConfigUnavailableReason;
+};
+/**
+ * Config-only availability, in precedence order: the environment kill switch first (it is
+ * the strongest), then the config key, then the team dependency. Pure: no I/O.
+ */
+export declare function describeGovernanceConfigAvailability(config: {
+    governance?: Pick<GovernanceConfig, 'enabled'>;
+    team: {
+        enabled: boolean;
+    };
+}, env?: Readonly<Record<string, string | undefined>>): GovernanceConfigAvailability;
+/**
+ * Merge the `governance` section across the layers (defaults > file > env > flag).
+ *
+ * The environment and `--no-governance` layers can ONLY switch `enabled` off (they are kill
+ * switches), and they are applied last so nothing in the file can outvote them. The flag is a
+ * launch-only override: it is resolved here into the in-memory config and never reaches the
+ * store, which is what "not persisted" means.
+ */
+export declare function resolveGovernanceConfig(layers: {
+    file?: unknown;
+    env?: unknown;
+    disableForLaunch?: boolean;
+}): GovernanceConfig;
+export interface InitialPostureInput {
+    /** `--govern`. */
+    govern?: boolean;
+    /** `--plan-govern`. Wins over `govern` if a programmatic caller passes both. */
+    planGovern?: boolean;
+    /** The already-resolved `--plan` / `planModeDefault` result (unchanged by governance). */
+    startInPlanMode: boolean;
+    governance: Pick<GovernanceConfig, 'enabled'>;
+    teamEnabled: boolean;
+}
+export interface InitialPostureResolution {
+    posture: Posture;
+    /** Set when a governance posture was requested but could not be honoured. */
+    degradedReason?: GovernanceConfigUnavailableReason;
+}
+/**
+ * The posture the session starts in. Governance flags win over `--plan` / `planModeDefault`
+ * (a user who asked for a governed run did not ask for a plain one); when governance is
+ * unavailable at the CONFIG level the request degrades to the classic posture the same launch
+ * would have had, and the reason is returned so the caller can say so instead of silently
+ * dropping the flag. Without a governance flag this is exactly `startInPlanMode ? 'plan' :
+ * 'build'`, so `--plan` behaviour is untouched.
+ */
+export declare function resolveInitialPosture(input: InitialPostureInput, env?: Readonly<Record<string, string | undefined>>): InitialPostureResolution;
+export {};

package/dist/config/governance-config.js

@@ -0,0 +1,164 @@
+/**
+ * Governance-mode configuration (governance-mode sections 11.1 / 13.2).
+ *
+ * LIVES IN ITS OWN FILE, NOT IN `schema.ts`: that file is far past the repo's
+ * 1000-line limit, and a section whose clamp depends on nothing else in it has no
+ * reason to grow it. `schema.ts` imports and re-exports everything below, so every
+ * importer still reaches the section through `config/schema.js`.
+ *
+ * SELF-CONTAINED ON PURPOSE. The integer/boolean helpers in `schema.ts` are private,
+ * and importing back from it would make a cycle (`schema.ts` re-exports this file).
+ * The two helpers here are four lines each.
+ *
+ * ASCII ONLY: `src/config/**` is inside the glyph scanner's scope.
+ */
+import process from 'node:process';
+import { GOV_LIMITS } from '../governance/limits.js';
+import { PROFILE_IDS } from '../governance/types.js';
+export const DEFAULT_GOVERNANCE_CONFIG = {
+    enabled: true,
+    shiftTab: true,
+    panel: true,
+    profile: 'general',
+    maxWorkPackages: 4,
+    maxPhases: 3,
+    maxRework: 3,
+    maxFixCycles: 3,
+    minAskRounds: 2,
+    budgetTokens: 0,
+    confirmCharter: false,
+};
+/**
+ * Inclusive range per numeric key. The upper bounds of the four structural keys are
+ * `GOV_LIMITS.hardMax*` (NOT repeated here), so the clamp and the engine can never
+ * disagree: a hand-edited `config.json` cannot exceed what the engine enforces.
+ */
+const NUMERIC_RANGES = {
+    maxWorkPackages: { min: 1, max: GOV_LIMITS.hardMaxWorkPackages },
+    maxPhases: { min: 1, max: GOV_LIMITS.hardMaxPhases },
+    maxRework: { min: 1, max: GOV_LIMITS.hardMaxRework },
+    maxFixCycles: { min: 1, max: GOV_LIMITS.hardMaxFixCycles },
+    minAskRounds: { min: 0, max: 5 },
+    budgetTokens: { min: 0, max: 1_000_000_000 },
+};
+/** The numeric keys, in display order; shared with the settings and `config` surfaces. */
+export const GOVERNANCE_NUMERIC_KEYS = Object.keys(NUMERIC_RANGES);
+/** The inclusive range a numeric key is clamped to. */
+export function governanceRangeOf(key) {
+    return NUMERIC_RANGES[key];
+}
+/**
+ * Only a real, finite INTEGER survives. A float, NaN, a string ("2") or null is
+ * REPAIRED TO THE DEFAULT, not rounded or coerced: a hand-edited `maxRework: 2.5` has no
+ * defensible reading, and "typo changes nothing" is the discipline every sibling clamp
+ * follows. Out-of-range integers are clamped, not rejected.
+ */
+function clampRangedInt(value, key) {
+    const range = NUMERIC_RANGES[key];
+    const fallback = DEFAULT_GOVERNANCE_CONFIG[key];
+    if (typeof value !== 'number' || !Number.isInteger(value))
+        return fallback;
+    return Math.min(range.max, Math.max(range.min, value));
+}
+function pickBool(value, fallback) {
+    return typeof value === 'boolean' ? value : fallback;
+}
+function pickProfile(value) {
+    return typeof value === 'string' && PROFILE_IDS.includes(value)
+        ? value
+        : DEFAULT_GOVERNANCE_CONFIG.profile;
+}
+/**
+ * THE single gate for every governance-config read AND write, mirroring
+ * `clampTeamConfig` for the reason that one records: hardening only the read path
+ * leaves a bad value on disk that the read path then rewrites on every launch, which
+ * presents to the user as "my setting won't stick". Unknown keys are dropped.
+ */
+export function clampGovernanceConfig(raw) {
+    const src = (raw && typeof raw === 'object' && !Array.isArray(raw) ? raw : {});
+    const defaults = DEFAULT_GOVERNANCE_CONFIG;
+    return {
+        enabled: pickBool(src.enabled, defaults.enabled),
+        shiftTab: pickBool(src.shiftTab, defaults.shiftTab),
+        panel: pickBool(src.panel, defaults.panel),
+        profile: pickProfile(src.profile),
+        maxWorkPackages: clampRangedInt(src.maxWorkPackages, 'maxWorkPackages'),
+        maxPhases: clampRangedInt(src.maxPhases, 'maxPhases'),
+        maxRework: clampRangedInt(src.maxRework, 'maxRework'),
+        maxFixCycles: clampRangedInt(src.maxFixCycles, 'maxFixCycles'),
+        minAskRounds: clampRangedInt(src.minAskRounds, 'minAskRounds'),
+        budgetTokens: clampRangedInt(src.budgetTokens, 'budgetTokens'),
+        confirmCharter: pickBool(src.confirmCharter, defaults.confirmCharter),
+    };
+}
+// ---------------------------------------------------------------------------
+// Environment kill switch + availability (config-level part)
+// ---------------------------------------------------------------------------
+/** The spellings of "off" the kill switch accepts, matching the other ARAGON_* switches. */
+const ENV_OFF_VALUES = new Set(['0', 'false', 'off', 'no']);
+/**
+ * `ARAGON_GOVERNANCE=0` is a KILL switch, not a toggle: it can only disable. Any other
+ * value (including `1`) is ignored, so an environment can never switch a feature ON that
+ * the user's config or a `--no-governance` flag turned off.
+ *
+ * Takes the env as a parameter so tests and `doctor` do not touch `process.env`.
+ */
+export function isGovernanceEnvDisabled(env = process.env) {
+    const value = env.ARAGON_GOVERNANCE?.trim().toLowerCase();
+    return value !== undefined && ENV_OFF_VALUES.has(value);
+}
+/**
+ * Config-only availability, in precedence order: the environment kill switch first (it is
+ * the strongest), then the config key, then the team dependency. Pure: no I/O.
+ */
+export function describeGovernanceConfigAvailability(config, env = process.env) {
+    if (isGovernanceEnvDisabled(env))
+        return { ok: false, reason: 'disabled_env' };
+    if (config.governance?.enabled === false)
+        return { ok: false, reason: 'disabled_config' };
+    if (!config.team.enabled)
+        return { ok: false, reason: 'team_off' };
+    return { ok: true };
+}
+// ---------------------------------------------------------------------------
+// Launch resolution (load.ts calls these; kept here so load.ts barely grows)
+// ---------------------------------------------------------------------------
+/**
+ * Merge the `governance` section across the layers (defaults > file > env > flag).
+ *
+ * The environment and `--no-governance` layers can ONLY switch `enabled` off (they are kill
+ * switches), and they are applied last so nothing in the file can outvote them. The flag is a
+ * launch-only override: it is resolved here into the in-memory config and never reaches the
+ * store, which is what "not persisted" means.
+ */
+export function resolveGovernanceConfig(layers) {
+    return clampGovernanceConfig({
+        ...DEFAULT_GOVERNANCE_CONFIG,
+        ...(isPlainObject(layers.file) ? layers.file : {}),
+        ...(isPlainObject(layers.env) ? layers.env : {}),
+        ...(layers.disableForLaunch === true ? { enabled: false } : {}),
+    });
+}
+function isPlainObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+/**
+ * The posture the session starts in. Governance flags win over `--plan` / `planModeDefault`
+ * (a user who asked for a governed run did not ask for a plain one); when governance is
+ * unavailable at the CONFIG level the request degrades to the classic posture the same launch
+ * would have had, and the reason is returned so the caller can say so instead of silently
+ * dropping the flag. Without a governance flag this is exactly `startInPlanMode ? 'plan' :
+ * 'build'`, so `--plan` behaviour is untouched.
+ */
+export function resolveInitialPosture(input, env = process.env) {
+    const classic = input.startInPlanMode ? 'plan' : 'build';
+    const requested = input.planGovern === true
+        ? 'plan_govern'
+        : input.govern === true ? 'govern' : null;
+    if (requested === null)
+        return { posture: classic };
+    const availability = describeGovernanceConfigAvailability({ governance: input.governance, team: { enabled: input.teamEnabled } }, env);
+    return availability.ok
+        ? { posture: requested }
+        : { posture: classic, degradedReason: availability.reason };
+}

package/dist/config/governance-launch.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Command-line validation for the governance flags (governance-mode 11.2).
+ *
+ * PURE, AND OUT OF `cli.tsx` ON PURPOSE: that file is far past the size limit, and these four
+ * rules are exactly the kind that regress silently (a missing one lets `-p --govern` start a
+ * run that can never reach a human). `cli.tsx` only gathers the facts and prints the message.
+ *
+ * ASCII ONLY: `src/config/**` is inside the glyph scanner's scope.
+ */
+export interface GovernanceLaunchInput {
+    /** `--govern`. */
+    govern?: boolean;
+    /** `--plan-govern`. */
+    planGovern?: boolean;
+    /** `--plan` (`true` only when passed; `--no-plan` and silence are both falsy here). */
+    plan?: boolean;
+    /** `--no-team`. */
+    noTeam?: boolean;
+    /** `--no-governance`. */
+    noGovernance?: boolean;
+    /**
+     * The run cannot reach a human: `-p/--print`, the `exec` subcommand, piped stdin or a
+     * non-TTY stdout. Governance needs `ask_user` and the review overlays, which headless
+     * runs deny wholesale.
+     */
+    headless: boolean;
+}
+export type GovernanceLaunchCheck = {
+    ok: true;
+} | {
+    ok: false;
+    message: string;
+};
+export declare const GOVERNANCE_EXCLUSIVE_MESSAGE = "--govern, --plan-govern and --plan are mutually exclusive. Pass only one of them.";
+export declare const GOVERNANCE_HEADLESS_MESSAGE: string;
+export declare const GOVERNANCE_NO_TEAM_MESSAGE: string;
+export declare const GOVERNANCE_NO_GOVERNANCE_MESSAGE: string;
+/**
+ * The first violated rule, or `{ ok: true }`. ORDER IS THE CONTRACT: the exclusivity error
+ * is the one a user typing three flags needs to see first, and the headless rule outranks
+ * `--no-team` because it is the one that cannot be fixed by dropping a second flag.
+ * Nothing is checked unless a governance posture was actually requested.
+ */
+export declare function validateGovernanceLaunch(input: GovernanceLaunchInput): GovernanceLaunchCheck;
+/** The root-level options the rules read, as commander materialises them. */
+export interface GovernanceRootOptions {
+    govern?: boolean;
+    planGovern?: boolean;
+    plan?: boolean;
+    /** `--team` / `--no-team`: only an explicit `false` is a refusal. */
+    team?: boolean;
+    /** `--no-governance` is declared alone, so this is `true` when absent and `false` when given. */
+    governance?: boolean;
+    print?: boolean;
+}
+export interface GovernanceCommandContext {
+    /** The command about to run: `exec`, `config`, or the root command's own name. */
+    commandName: string;
+    /** `true` for the root command's own action (the TUI / `-p` entry), not a subcommand. */
+    isRootAction: boolean;
+    stdinIsTty: boolean;
+    stdoutIsTty: boolean;
+}
+/**
+ * The `preAction` hook's decision. `exec` is always headless; the root action is headless
+ * when `-p` was given or either stream is not a terminal (the TUI would refuse to start
+ * anyway, but it would do so AFTER a governance run had been promised). Other subcommands
+ * (`config`, `logs`, ...) never start a governed run, so only the flag-combination rules
+ * apply to them.
+ */
+export declare function checkGovernanceCommandLine(options: GovernanceRootOptions, context: GovernanceCommandContext): GovernanceLaunchCheck;

package/dist/config/governance-launch.js

@@ -0,0 +1,58 @@
+/**
+ * Command-line validation for the governance flags (governance-mode 11.2).
+ *
+ * PURE, AND OUT OF `cli.tsx` ON PURPOSE: that file is far past the size limit, and these four
+ * rules are exactly the kind that regress silently (a missing one lets `-p --govern` start a
+ * run that can never reach a human). `cli.tsx` only gathers the facts and prints the message.
+ *
+ * ASCII ONLY: `src/config/**` is inside the glyph scanner's scope.
+ */
+export const GOVERNANCE_EXCLUSIVE_MESSAGE = '--govern, --plan-govern and --plan are mutually exclusive. Pass only one of them.';
+export const GOVERNANCE_HEADLESS_MESSAGE = 'Governance mode needs an interactive terminal. It cannot be combined with -p/--print, '
+    + 'the exec subcommand or piped input.';
+export const GOVERNANCE_NO_TEAM_MESSAGE = '--govern and --plan-govern run their roles as team subagents, so they cannot be '
+    + 'combined with --no-team. Remove --no-team to use governance mode.';
+export const GOVERNANCE_NO_GOVERNANCE_MESSAGE = '--no-governance disables governance mode for this launch, so it cannot be combined with '
+    + '--govern or --plan-govern.';
+/**
+ * The first violated rule, or `{ ok: true }`. ORDER IS THE CONTRACT: the exclusivity error
+ * is the one a user typing three flags needs to see first, and the headless rule outranks
+ * `--no-team` because it is the one that cannot be fixed by dropping a second flag.
+ * Nothing is checked unless a governance posture was actually requested.
+ */
+export function validateGovernanceLaunch(input) {
+    const requested = input.govern === true || input.planGovern === true;
+    const exclusive = [input.govern === true, input.planGovern === true, input.plan === true];
+    if (exclusive.filter(Boolean).length > 1) {
+        return { ok: false, message: GOVERNANCE_EXCLUSIVE_MESSAGE };
+    }
+    if (!requested)
+        return { ok: true };
+    if (input.noGovernance === true)
+        return { ok: false, message: GOVERNANCE_NO_GOVERNANCE_MESSAGE };
+    if (input.headless)
+        return { ok: false, message: GOVERNANCE_HEADLESS_MESSAGE };
+    if (input.noTeam === true)
+        return { ok: false, message: GOVERNANCE_NO_TEAM_MESSAGE };
+    return { ok: true };
+}
+/**
+ * The `preAction` hook's decision. `exec` is always headless; the root action is headless
+ * when `-p` was given or either stream is not a terminal (the TUI would refuse to start
+ * anyway, but it would do so AFTER a governance run had been promised). Other subcommands
+ * (`config`, `logs`, ...) never start a governed run, so only the flag-combination rules
+ * apply to them.
+ */
+export function checkGovernanceCommandLine(options, context) {
+    const headless = context.commandName === 'exec'
+        || (context.isRootAction
+            && (options.print === true || !context.stdinIsTty || !context.stdoutIsTty));
+    return validateGovernanceLaunch({
+        govern: options.govern,
+        planGovern: options.planGovern,
+        plan: options.plan,
+        noTeam: options.team === false,
+        noGovernance: options.governance === false,
+        headless,
+    });
+}

package/dist/config/load.d.ts

@@ -240,6 +240,21 @@ export interface CliFlags {
     compaction?: boolean;
     /** `--compaction-threshold <0..1|N%>` — session override for `threshold`. */
     compactionThreshold?: string;
+    /**
+     * `--govern` / `--plan-govern` (governance-mode 11.2). Plain booleans: they only ever ask
+     * for a starting posture and are persisted nowhere, so unlike the pairs above there is no
+     * stored value for a commander default to overwrite. `cli.tsx` rejects the combinations
+     * (mutually exclusive, headless, `--no-team`) before this layer sees them.
+     */
+    govern?: boolean;
+    planGovern?: boolean;
+    /**
+     * `--no-governance`, carried as `false` ONLY. A lone negative flag makes commander default
+     * its option to `true`, so `cli.tsx` forwards `undefined` for that case and nothing here can
+     * mistake silence for an override. Launch-only: it lands in the resolved `CliConfig` and is
+     * never written to the store.
+     */
+    governance?: boolean;
     /**
      * `--resume <id|path>` - continue a saved session under a NEW id
      * (tui-session-id-resume 4).

package/dist/config/load.js

@@ -15,6 +15,7 @@ import { getConfigPath } from './app-paths.js';
 import { setHistoryEnabled } from './prompt-history.js';
 import { setEntryRetain } from '../agent/entry-limits.js';
 import { readSubmitCount } from './ui-state.js';
+import { resolveGovernanceConfig, resolveInitialPosture } from './governance-config.js';
 import { getLogger } from '../logging/logger.js';
 import { registerSecret, registerSecretsFrom } from '../logging/secret-registry.js';
 import { detectCapabilities, resolveTuiCapabilities } from '../ui/capabilities.js';
@@ -710,6 +711,28 @@ export function loadConfig(flags = {}, options = {}) {
     // `viewReducer` is pure and takes no config, so the resolved ring cap reaches
     // it through the same module-singleton channel `setHistoryEnabled` uses.
     setEntryRetain(transcriptRetain);
+    // Governance: file < env (kill switch) < `--no-governance`, clamped like every section. The
+    // initial posture is resolved against the SAME team value the config carries, and a request
+    // that cannot be honoured degrades to the classic posture with a log record, never silently.
+    const governance = resolveGovernanceConfig({
+        file: file.governance,
+        env: env.partial.governance,
+        disableForLaunch: flags.governance === false,
+    });
+    const team = resolveTeamConfig(flags, env.partial, file);
+    const posture = resolveInitialPosture({
+        govern: flags.govern,
+        planGovern: flags.planGovern,
+        startInPlanMode,
+        governance,
+        teamEnabled: team.enabled,
+    });
+    const initialPosture = posture.posture;
+    if (posture.degradedReason !== undefined) {
+        getLogger().warn('config', 'governance_initial_posture_degraded', {
+            reason: posture.degradedReason,
+        });
+    }
     const config = {
         modelProfiles: projection.issues.length ? undefined : file.modelProfiles,
         provider,
@@ -768,7 +791,7 @@ export function loadConfig(flags = {}, options = {}) {
                 : {}),
         },
         log: resolveLogConfig(flags, env.partial, file),
-        team: resolveTeamConfig(flags, env.partial, file),
+        team,
         todo: resolveTodoConfig(flags, env.partial, file),
         retry: resolveRetryConfig(flags, env.partial, file),
         fast: resolveFastConfig(flags, env.partial, file),
@@ -790,6 +813,8 @@ export function loadConfig(flags = {}, options = {}) {
         // `taskSummary.enabled: false` cannot arrive as two different shapes.
         taskSummary: clampTaskSummaryConfig({ ...DEFAULT_CONFIG.taskSummary,
             ...(env.partial.taskSummary ?? {}), ...(file.taskSummary ?? {}) }),
+        governance,
+        initialPosture,
         cwd,
         color,
         colorLevel,

package/dist/config/model-profile-store.d.ts

@@ -1,12 +1,14 @@
 import { type ModelProfilesConfig, type ModelRole, type ProfileValidationIssue } from './model-profiles.js';
 import type { SessionKitState } from './model-kits.js';
-import type { CliConfig, CompactionConfig, FastConfig, LogConfig, PersistedConfig, TeamConfig } from './schema.js';
-export interface ModelSettingsPatch extends Partial<Omit<PersistedConfig, 'modelProfiles' | 'fast' | 'compaction' | 'log' | 'team'>> {
+import type { CliConfig, CompactionConfig, FastConfig, GovernanceConfig, LogConfig, PersistedConfig, TeamConfig } from './schema.js';
+export interface ModelSettingsPatch extends Partial<Omit<PersistedConfig, 'modelProfiles' | 'fast' | 'compaction' | 'log' | 'team' | 'governance'>> {
     fast?: Partial<FastConfig>;
     compaction?: Partial<CompactionConfig>;
     log?: Partial<LogConfig>;
     /** The subagent-model picker writes here (subagent-model D-5/I-5): draft-only until Save. */
     team?: Partial<TeamConfig>;
+    /** Governance writers (`config set`, `/gov budget`) send single keys; the store clamps. */
+    governance?: Partial<GovernanceConfig>;
 }
 export interface ModelSettingsDraft {
     profiles?: ModelProfilesConfig;

package/dist/config/schema.d.ts

@@ -7,7 +7,10 @@
  */
 import { type RetryPolicy, type ThinkingLevel } from '@aragon-agent/core';
 import { type LogLevelName } from '../logging/levels.js';
+import { type GovernanceConfig } from './governance-config.js';
+import type { Posture } from '../governance/posture.js';
 import type { FollowThroughMode } from '../todo/types.js';
+export { clampGovernanceConfig, DEFAULT_GOVERNANCE_CONFIG, type GovernanceConfig, } from './governance-config.js';
 /**
  * `ModelRegistry` seeds builtin lists for five providers, but `initProviders()`
  * registers only three adapters. Running a model whose provider has no adapter
@@ -1146,6 +1149,8 @@ export interface PersistedConfig {
     prompts: PromptsConfig;
     /** The header task label. The THIRTEENTH; two scalars (see TaskSummaryConfig). */
     taskSummary: TaskSummaryConfig;
+    /** Governance mode. The FOURTEENTH; scalars only (see GovernanceConfig). */
+    governance: GovernanceConfig;
 }
 export declare const DEFAULT_CONFIG: PersistedConfig;
 /**
@@ -1534,6 +1539,23 @@ export interface CliConfig {
      * switched-off feature.
      */
     taskSummary?: TaskSummaryConfig;
+    /**
+     * Governance mode (governance-mode 11.1). The FOURTEENTH nested object; scalars only.
+     *
+     * OPTIONAL HERE FOR THE SAME REASON AS `prompts` / `taskSummary` ABOVE: `CliConfig` is built
+     * by hand in many fixtures, `loadConfig` always fills it, and readers treat a missing
+     * section as the documented defaults. `enabled` here (after env kill switch and
+     * `--no-governance`) decides whether governance tools are REGISTERED, once at construction.
+     */
+    governance?: GovernanceConfig;
+    /**
+     * The posture the session starts in (governance-mode 11.2): `--plan` / `planModeDefault`
+     * still decide `startInPlanMode` exactly as before, and `--govern` / `--plan-govern` win over
+     * them when governance is available. Optional on this shape for the fixture reason above;
+     * `loadConfig` always fills it. Without a governance flag it is `'plan'` when
+     * `startInPlanMode`, else `'build'`.
+     */
+    initialPosture?: Posture;
     /**
      * Lifetime submit count driving the composer hint fade (`HINT_FADE_AFTER`).
      *

package/dist/config/schema.js

@@ -9,6 +9,9 @@ import { isAbsolute } from 'node:path';
 import { ABSOLUTE_MAX_OUTPUT_TOKENS, DEFAULT_MAX_OUTPUT_TOKENS, DEFAULT_RETRY_POLICY, MIN_MAX_OUTPUT_TOKENS, RETRY_LIMITS, } from '@aragon-agent/core';
 import { clampLogLevel } from '../logging/levels.js';
 import { TEAM_LIMITS } from '../team/limits.js';
+import { DEFAULT_GOVERNANCE_CONFIG } from './governance-config.js';
+// Governance mode (governance-mode 11.1): defined in its own file so this one does not grow.
+export { clampGovernanceConfig, DEFAULT_GOVERNANCE_CONFIG, } from './governance-config.js';
 // ---------------------------------------------------------------------------
 // Provider set — only the adapter-backed providers are usable at run time (R5).
 // ---------------------------------------------------------------------------
@@ -1194,6 +1197,9 @@ export const DEFAULT_CONFIG = {
     // `config list`, so the file would report a section it never wrote. One line
     // here, like the seven above it.
     taskSummary: DEFAULT_TASK_SUMMARY_CONFIG,
+    // And one section later again. Without this line a `config.json` predating governance
+    // resolves `governance` to `undefined`; every reader would then disagree with `config list`.
+    governance: DEFAULT_GOVERNANCE_CONFIG,
 };
 /**
  * Runtime state that used to be stored in `config.json` by mistake

package/dist/config/store.js

@@ -17,7 +17,7 @@ import { getConfigPath, getSessionsDir } from './app-paths.js';
 import { registerProfileSecrets, registerSecretsFrom } from '../logging/secret-registry.js';
 import { adaptLegacyConnectionPatch, ModelProfileConfigError, readModelSettingsDisk } from './model-profile-store.js';
 import { normalizeModelProfiles } from './model-profiles.js';
-import { clampBashConfig, clampJobsConfig, clampPromptsConfig, clampTaskSummaryConfig, CONFIG_VERSION, DEFAULT_CONFIG, clampCompactionConfig, clampFastConfig, clampLogConfig, clampMaxTokens, clampRetryConfig, clampSkillsConfig, clampTeamConfig, clampTodoConfig, clampContextWindow, clampUpdateConfig, isAutoToken, stripLegacyStateKeys, stripRetiredConfigKeys, } from './schema.js';
+import { clampBashConfig, clampJobsConfig, clampPromptsConfig, clampTaskSummaryConfig, CONFIG_VERSION, DEFAULT_CONFIG, clampCompactionConfig, clampFastConfig, clampGovernanceConfig, clampLogConfig, clampMaxTokens, clampRetryConfig, clampSkillsConfig, clampTeamConfig, clampTodoConfig, clampContextWindow, clampUpdateConfig, isAutoToken, stripLegacyStateKeys, stripRetiredConfigKeys, } from './schema.js';
 /**
  * Normalize `maxTokens` for both directions of the config file.
  *
@@ -213,6 +213,13 @@ export function normalizePersistedConfig(input) {
             ...DEFAULT_CONFIG.taskSummary,
             ...(partial.taskSummary ?? {}),
         }),
+        // And the fourteenth. The READ half supplies a whole section to every user whose
+        // `config.json` predates governance, and clamps a hand-edited one: the file cannot
+        // carry a `maxRework` the engine would refuse.
+        governance: clampGovernanceConfig({
+            ...DEFAULT_CONFIG.governance,
+            ...(partial.governance ?? {}),
+        }),
     };
 }
 /**
@@ -334,6 +341,12 @@ export function mergePersistedConfig(current, patch) {
         // that must never happen is a FAILED summary call landing on "show nothing"
         // because a switch the user never touched defaulted away.
         taskSummary: clampTaskSummaryConfig({ ...current.taskSummary, ...(patch.taskSummary ?? {}) }),
+        // The fourteenth section, and the ninth time this file records the same trap.
+        // `aragon config set governance.maxRework 9` sends `{ governance: { maxRework: 9 } }`;
+        // without this merge the shallow spread REPLACES the section and `enabled` is written
+        // absent, and without the clamp 9 reaches the disk and the engine's ceiling is the
+        // only thing that stops it. The WRITE half of the two-direction gate.
+        governance: clampGovernanceConfig({ ...current.governance, ...(patch.governance ?? {}) }),
     };
     return merged;
 }