@aragon-agent/cli 0.6.44 → 0.6.46

package/dist/governance/engine/start-input.js

@@ -0,0 +1,111 @@
+/**
+ * `gov_run start` argument normalization (governance-mode 7.2).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * REPAIR FIRST, REJECT SECOND, and never create anything on a rejection: a malformed
+ * `start` must leave no run directory, no ledger and no lock behind, because the model's
+ * natural response to `NOT ACCEPTED` is to call `start` again with a corrected payload.
+ * Every problem is listed at once - a model that learns about one defect per call burns a
+ * round trip per defect, and each round trip is an LLM turn.
+ *
+ * The schema in `lead-tools.ts` declares SHAPE only (plan-tools.ts P0-4: `ajv` is an
+ * optional dependency, so a numeric bound in the schema would behave differently depending
+ * on whether it installed). Every bound is enforced HERE, deterministically.
+ */
+import { GOV_LIMITS } from '../limits.js';
+import { isProfileId } from '../profiles.js';
+import { Issues, isRecord } from '../tools/normalize-util.js';
+function normalizeWorkPackage(issues, raw, index) {
+    const label = `workPackages[${index}]`;
+    if (!isRecord(raw)) {
+        issues.fail(`${label} must be an object.`);
+        return null;
+    }
+    const id = issues.str(raw.id, `${label}.id`, GOV_LIMITS.wpIdChars * 4, true).toLowerCase();
+    const title = issues.str(raw.title, `${label}.title`, GOV_LIMITS.wpTitleChars, true);
+    const goal = issues.str(raw.goal, `${label}.goal`, GOV_LIMITS.wpGoalChars, true);
+    const files = issues.list(raw.files, `${label}.files`, GOV_LIMITS.wpFilesMax, 200);
+    const acceptance = issues.list(raw.acceptance, `${label}.acceptance`, GOV_LIMITS.wpAcceptanceMax, GOV_LIMITS.wpAcceptanceChars);
+    if (acceptance.length === 0) {
+        issues.fail(`${label} (${id || index}) needs at least one acceptance criterion.`);
+    }
+    const dependsOn = issues
+        .list(raw.dependsOn, `${label}.dependsOn`, 16, GOV_LIMITS.wpIdChars * 4)
+        .map((d) => d.toLowerCase());
+    return { id, title, goal, files, acceptance, ...(dependsOn.length > 0 ? { dependsOn } : {}) };
+}
+function normalizeContract(issues, raw, index) {
+    const label = `contracts[${index}]`;
+    if (!isRecord(raw)) {
+        issues.fail(`${label} must be an object.`);
+        return null;
+    }
+    const id = issues.str(raw.id, `${label}.id`, 40, true);
+    const name = issues.str(raw.name, `${label}.name`, GOV_LIMITS.contractNameChars, true);
+    const producer = issues.str(raw.producer, `${label}.producer`, 80, true).toLowerCase();
+    const consumers = issues
+        .list(raw.consumers, `${label}.consumers`, 8, 80)
+        .map((c) => c.toLowerCase());
+    if (consumers.length === 0)
+        issues.fail(`${label} (${id}) needs at least one consumer.`);
+    const definition = issues.str(raw.definition, `${label}.definition`, GOV_LIMITS.contractDefinitionChars, true);
+    return { id, name, producer, consumers, definition };
+}
+function duplicates(values) {
+    const seen = new Set();
+    const dup = new Set();
+    for (const v of values) {
+        if (seen.has(v))
+            dup.add(v);
+        seen.add(v);
+    }
+    return [...dup];
+}
+/** Validate a raw `gov_run start` payload. Pure; never throws. */
+export function normalizeStartInput(raw) {
+    const issues = new Issues();
+    const args = isRecord(raw) ? raw : {};
+    const goal = issues.str(args.goal, 'goal', GOV_LIMITS.goalChars, true);
+    // The spec is allowed to be empty when a PLAN+GOVERN snapshot supplies it; the lifecycle
+    // decides that, so it is not required here.
+    const spec = issues.str(args.spec, 'spec', GOV_LIMITS.specChars);
+    let profile;
+    if (args.profile !== undefined && args.profile !== null && args.profile !== '') {
+        if (isProfileId(args.profile))
+            profile = args.profile;
+        else
+            issues.fail(`profile must be one of general, ml, product, api-security.`);
+    }
+    const wpRaw = issues.items(args.workPackages, 'workPackages', GOV_LIMITS.hardMaxWorkPackages * 4);
+    if (wpRaw.length === 0)
+        issues.fail('workPackages needs at least one work package.');
+    const workPackages = [];
+    wpRaw.forEach((item, i) => {
+        const wp = normalizeWorkPackage(issues, item, i);
+        if (wp)
+            workPackages.push(wp);
+    });
+    const dupIds = duplicates(workPackages.map((w) => w.id));
+    if (dupIds.length > 0)
+        issues.fail(`duplicate work package id(s): ${dupIds.join(', ')}.`);
+    const contractRaw = issues.items(args.contracts, 'contracts', GOV_LIMITS.contractsMax);
+    const contracts = [];
+    contractRaw.forEach((item, i) => {
+        const c = normalizeContract(issues, item, i);
+        if (c)
+            contracts.push(c);
+    });
+    const dupContracts = duplicates(contracts.map((c) => c.id));
+    if (dupContracts.length > 0)
+        issues.fail(`duplicate contract id(s): ${dupContracts.join(', ')}.`);
+    const integrationCommands = issues.list(args.integrationCommands, 'integrationCommands', GOV_LIMITS.integrationCommandsMax, GOV_LIMITS.integrationCommandChars);
+    return issues.result({
+        goal,
+        spec,
+        ...(profile !== undefined ? { profile } : {}),
+        workPackages,
+        ...(contracts.length > 0 ? { contracts } : {}),
+        ...(integrationCommands.length > 0 ? { integrationCommands } : {}),
+    });
+}

package/dist/governance/engine/state-machine.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Stage legality, `NEXT` generation and escalation handling (governance-mode 8.2, I-G6).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned). Pure apart from the explicitly named
+ * mutators (`recordRework`, `markBlocked`, `openEscalation`, `closeEscalation`,
+ * `applyResolveDisposition`), which edit the `RunState` they are handed IN PLACE and do
+ * no I/O, so the engine can replay or persist around them.
+ *
+ * WHY A TABLE AND NOT TRUST. The orchestrator is an LLM; "do not skip review" in a prompt
+ * drifts over a multi-hour run. Here the stage order is a hard fact: `checkStage` is the
+ * only gate `gov_dispatch` passes through, and every refusal teaches (it names the
+ * blocking WPs and ends with the legal next calls) so a refused call is one cheap
+ * correction, not a dead end. Refusals are plain text, never errors (D-15).
+ *
+ * The current phase is the FIRST phase with `integrated === false`; stages only ever act
+ * on it. `dropped` and `integrated` WPs never block anything.
+ */
+import { type Escalation, type PhaseState, type ResolveDisposition, type RunState, type StageKind, type WorkPackage } from '../types.js';
+export declare const NOT_ACCEPTED = "NOT ACCEPTED:";
+export interface StageCheckOptions {
+    /** `min(team.maxSubagents, hardMaxSubagents)`; defaults to the structural maximum. */
+    teamCeiling?: number;
+}
+export type StageCheck = {
+    ok: true;
+    phase: number;
+    wpIds: string[];
+} | {
+    ok: false;
+    message: string;
+};
+/** Index of the first phase that is not integrated, or null when all are. */
+export declare function currentPhaseIndex(run: RunState): number | null;
+export declare function currentPhase(run: RunState): PhaseState | null;
+export declare function wpsInPhase(run: RunState, phase: PhaseState): WorkPackage[];
+/** `maxRework` plus L3 grants for one WP, never above the structural ceiling. */
+export declare function reworkLimit(run: RunState, wp: WorkPackage): number;
+/** Fix cycles allowed in a phase: `maxFixCycles + extraFixGrants`, capped structurally. */
+export declare function fixCycleLimit(run: RunState, phase: PhaseState): number;
+/**
+ * The last integrate failed, every allowed fix has been spent, and no newer integrate
+ * attempt is pending: the engine must open an `integration_exhausted` escalation.
+ */
+export declare function isIntegrationExhausted(run: RunState, phase: PhaseState): boolean;
+/** `gov_run close` precondition: every phase integrated (accepted failing counts). */
+export declare function canClose(run: RunState): boolean;
+/** "WPs awaiting review: a, b; pending: c" over the not-yet-finished WPs of a phase. */
+export declare function describePhaseStatus(run: RunState, phase: PhaseState): string;
+/** Number of children a stage over `wpCount` WPs launches. */
+export declare function stageWidth(stage: StageKind, wpCount: number): number;
+/** Most WPs one call may carry so that `stageWidth` stays within `ceiling`. */
+export declare function stageChunkSize(stage: StageKind, ceiling: number): number;
+/** `gov_dispatch {"stage":"dev","wps":["a","b"]}` */
+export declare function dispatchCall(stage: StageKind, wps?: readonly string[]): string;
+/** Render actions as the trailing `NEXT:` block every `gov_*` result ends with (D-16). */
+export declare function formatNext(actions: readonly string[]): string;
+/**
+ * Ordered legal next calls for the run's current state. Pure. Stage width beyond
+ * `teamCeiling` is split into chunk calls (D-24), each independently legal.
+ */
+export declare function nextActions(run: RunState, options?: StageCheckOptions): string[];
+/**
+ * The single legality gate for `gov_dispatch` (I-G6). `wps` omitted means "every eligible
+ * WP of the current phase". On success `wpIds` is the validated list the stage will run.
+ */
+export declare function checkStage(run: RunState, stage: StageKind, wps?: readonly string[], options?: StageCheckOptions): StageCheck;
+/** Stages that are legal right now (ignores `teamCeiling`; chunking is not legality). */
+export declare function legalStages(run: RunState): StageKind[];
+export declare function nextEscalationId(run: RunState): string;
+export interface ReworkOutcome {
+    outcome: 'rework' | 'blocked';
+    reworkCount: number;
+    limit: number;
+    /** Not yet added to the run: the engine persists it, then calls `openEscalation`. */
+    escalation: Escalation | null;
+}
+/**
+ * Count one rejection against `wpId`. Beyond `maxRework + reworkGrants` the WP becomes
+ * `blocked` (retry stage `dev`, where the rework would have run) and an L3 escalation is
+ * proposed; otherwise it goes to `rework`.
+ */
+export declare function recordRework(run: RunState, wpId: string): ReworkOutcome;
+/** A stage produced no submission for this WP: block it at that stage, no penalty. */
+export declare function markBlocked(run: RunState, wpId: string, stage: StageKind): void;
+export declare function openEscalation(run: RunState, escalation: Escalation): void;
+/** Mark resolved; the run leaves `escalated` once no escalation remains open. */
+export declare function closeEscalation(run: RunState, escalation: Escalation, ruling: string): void;
+export type ResolveApplyResult = {
+    ok: true;
+    message: string;
+    affectedDependents: string[];
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * Apply the user's `disposition` for an escalation (spec 7.2 table). Mismatched or
+ * over-cap dispositions are refused with a reason; no disposition changes nothing.
+ * Mutates `run`; does NOT mark the escalation resolved (`closeEscalation` does).
+ */
+export declare function applyResolveDisposition(run: RunState, escalation: Escalation, disposition?: ResolveDisposition): ResolveApplyResult;