@tacuchi/agent-workflow-cli 25.1.2 → 25.3.0

package/dist/application/flow/submit.js

@@ -25,12 +25,12 @@ import { authorizeEffects, touchesTheWorld, } from "../../domain/capability/effe
 import { AttemptLedger } from "../../domain/capability/protocol.js";
 import { DEFAULT_CORE_DOCS_CANON, coreDocumentKindForPath } from "../../domain/docs-canon.js";
 import { claimedSeal, parseFlowAnswer, spendsAttempt, } from "../../domain/flow/answer.js";
-import { FIX_PREVIEW_TRANSITION, actionOf, alternativesOf, approvalGrantOf, effectsOf, internalActionOf, isRouteEvaluation, proposalContractOf, publishApprovalOf, routeControlOf, scopesSources, } from "../../domain/flow/authority.js";
+import { FIX_PREVIEW_TRANSITION, SETTLEMENT_READINGS, actionOf, alternativesOf, approvalGrantOf, effectsOf, internalActionOf, isRouteEvaluation, proposalContractOf, publishApprovalOf, routeControlOf, scopesSources, } from "../../domain/flow/authority.js";
 import { effectApprovalDigest } from "../../domain/flow/authorization.js";
 import { PAUSE_LABEL, STOP_LABEL, stepOf, } from "../../domain/flow/directive.js";
 import { executionVerdict } from "../../domain/flow/execution-result.js";
 import { ROUTE_ACCEPT_LABEL, ROUTE_ADJUST_LABEL, isRouteDisposition, } from "../../domain/flow/route.js";
-import { applyTransition, checkAgainstJourney, currentBatchIteration, restatesLastEvent, withApproval, withAttempt, withBoundary, withContinuation, withDecisionPreparation, withEvent, withFixPreview, withHandoff, withObservation, withPlanExecBatchStageForTransition, withProposal, withRouteDecisions, withRouteProposal, withScope, withSelectedChoice, } from "../../domain/flow/run-state.js";
+import { applyTransition, checkAgainstJourney, currentBatchIteration, restatesLastEvent, settlementAmbiguous, withApproval, withAttempt, withBoundary, withContinuation, withDecisionPreparation, withEvent, withFixPreview, withHandoff, withObservation, withPlanExecBatchStageForTransition, withProposal, withRouteDecisions, withRouteProposal, withScope, withSelectedChoice, withSettlementDeclarations, } from "../../domain/flow/run-state.js";
 import { withSpecBaseline } from "../../domain/lineage.js";
 import { destinationsOf, observedEffects, sealProposal } from "../../domain/proposal.js";
 import { baseDigest } from "../../domain/proposal.js";
@@ -44,7 +44,7 @@ import { resolveWorkspaceRootFrom } from "../paths-service.js";
 import { commitStoredPlanExecDecision, preparePlanExecDecision, } from "../plan-exec-decision-service.js";
 import { semanticDigest } from "../semantic-operation/protocol.js";
 import { resolveSessionTarget } from "../session-resolver.js";
-import { sourceAliasesOfPlan, validatePlanSourceBoundary, } from "../source-boundary-policy.js";
+import { sourceAliasesOfPlan, validatePlanSourceBoundary, validateSourceBoundedSemantics, } from "../source-boundary-policy.js";
 import { actionDigest, advanceFlowRun, directiveFor, effectsOfTransition, resolveBoundary, } from "./advance.js";
 import { observeCheckout, withObservedCheckouts } from "./checkout-observation.js";
 import { resolveCheckoutCandidates } from "./checkout-observation.js";
@@ -123,6 +123,7 @@ async function observe(fs, paths, raw, session, git) {
         root,
         destinations: await observeDestinations(fs, paths, raw),
         scope: await observeScope(fs, paths, raw),
+        plans: await observePlanEvidence(fs, paths, raw),
         checkouts: await observeCheckouts(fs, paths, session, git),
         baselines: await observeSpecBaselines(fs, paths, raw),
     };
@@ -198,6 +199,71 @@ async function observeSpecBaselines(fs, paths, raw) {
     }
     return out;
 }
+/**
+ * Run the source-boundary policy over the plan bytes a proposal is carrying.
+ *
+ * The same judgment the execution entry makes, one moment earlier — over the
+ * artifact's content instead of a file on disk — so a plan accepted when it
+ * closes cannot be rejected for the same cause when somebody tries to run it.
+ * Nothing is read when the payload carries no artifact.
+ *
+ * When the WORKSPACE block cannot be read, only the SEMANTIC half runs. The
+ * clause-level judgment needs no alias table, and answering an unreadable block
+ * with "that alias does not exist" would reject a plan for something the plan
+ * did not do.
+ */
+async function observePlanEvidence(fs, paths, raw) {
+    const proposed = proposedArtifacts(raw);
+    if (proposed.length === 0)
+        return [];
+    const canon = await resolveCoreDocsCanon(fs, paths);
+    // An unreadable canon cannot tell a plan from anything else, and judging a
+    // spec's prose by the plan's closure rule would reject what it never promised.
+    if (!canon.ok)
+        return [];
+    const root = await resolveWorkspaceRootFrom(fs, paths);
+    const block = await readWorkspaceBlock(fs, root, paths.blockMarkers());
+    const declared = block === null ? null : block.fuentes.map((source) => source.alias);
+    const out = [];
+    for (const artifact of proposed) {
+        if (!checkSafeRelativePath(artifact.path).ok)
+            continue;
+        if (coreDocumentKindForPath(artifact.path, canon.canon) !== "plan")
+            continue;
+        out.push({
+            path: artifact.path,
+            failures: declared === null
+                ? validateSourceBoundedSemantics(artifact.content)
+                : validatePlanSourceBoundary(artifact.content, declared),
+        });
+    }
+    return out;
+}
+/** The `path`/`content` pairs a payload proposes, read as data and judged by nobody. */
+function proposedArtifacts(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return [];
+    }
+    const artifacts = parsed?.artifacts;
+    if (!Array.isArray(artifacts))
+        return [];
+    const out = [];
+    for (const entry of artifacts) {
+        const path = entry?.path;
+        const content = entry?.content;
+        if (typeof path !== "string" || typeof content !== "string")
+            continue;
+        const relative = path.trim();
+        if (relative.length === 0 || out.some((artifact) => artifact.path === relative))
+            continue;
+        out.push({ path: relative, content });
+    }
+    return out;
+}
 /**
  * The workspace's declared aliases and the named plan's text, when the payload
  * declares a scope at all.
@@ -433,6 +499,13 @@ async function decide(fs, paths, state, input, snapshot) {
     if ("failure" in scoped) {
         return reject(state, resolved, scoped.failure.message, { code: scoped.failure.code, action: scoped.failure.action }, cost);
     }
+    // The closure-evidence gate runs over the proposed bytes BEFORE the seal: a
+    // plan whose validation names no observable check of the checkout is refused
+    // while it is being written, not when somebody tries to execute it.
+    const evidence = planEvidenceFrom(resolved.stopped, parsed.answer, snapshot.plans);
+    if (evidence !== null) {
+        return reject(state, resolved, evidence.failure.message, { code: evidence.failure.code, action: evidence.failure.action }, cost);
+    }
     const sealed = sealFrom(scoped.state, resolved.stopped, parsed.answer, snapshot.destinations, snapshot.baselines);
     if ("failure" in sealed) {
         return reject(state, resolved, sealed.failure.message, { code: sealed.failure.code, action: sealed.failure.action }, cost);
@@ -440,8 +513,11 @@ async function decide(fs, paths, state, input, snapshot) {
     const preparedForGate = await prepareDecisionForGate(fs, sealed.state, snapshot, parsed.answer, resolved, cost);
     if (!preparedForGate.ok)
         return preparedForGate.decision;
+    const settlement = recordSettlement(preparedForGate.state, parsed.answer, resolved, cost);
+    if (!settlement.ok)
+        return settlement.decision;
     const granted = resolved.kind === "authorization" ? (resolved.authorization?.planned ?? []) : [];
-    const approved = grantOf(preparedForGate.state, resolved, parsed.answer, granted, journey);
+    const approved = grantOf(settlement.state, resolved, parsed.answer, granted, journey);
     // All pure scope/proposal checks have now passed. A durable decision is a
     // material write, so it must never land when a later validation of the same
     // answer would refuse the boundary and leave its cursor standing.
@@ -821,7 +897,7 @@ function scopeFrom(state, stopped, answer, snapshot) {
             failure: {
                 code: structural.code,
                 message: structural.message,
-                action: "el plan no cumple el límite checkout: abrilo con /w:plan-refine y declará las fuentes por fase y tarea",
+                action: planBoundaryAction(structural.code, "execution-entry"),
             },
         };
     }
@@ -843,6 +919,186 @@ function scopeFrom(state, stopped, answer, snapshot) {
     }
     return { state: withScope(state, { plan, sources }) };
 }
+const SETTLEMENT_OUTCOMES = SETTLEMENT_READINGS.map((reading) => reading.outcome);
+/** The reading each label of the question stands for — from the row's own table. */
+const SETTLEMENT_BY_LABEL = new Map(SETTLEMENT_READINGS.map((reading) => [reading.label, reading.outcome]));
+function recordSettlement(state, answer, resolved, cost) {
+    const id = resolved.stopped?.id;
+    if (id === "plan-exec.settlement-authoring") {
+        return recordSettlementAuthoring(state, answer, resolved, cost);
+    }
+    if (id === "plan-exec.settlement-question") {
+        return recordSettlementAnswer(state, answer, resolved, cost);
+    }
+    return { ok: true, state };
+}
+/**
+ * The agent's declaration, checked against what the plan actually owes.
+ *
+ * Every live compensation, exactly once: a declaration that skips one would let
+ * the closure publish a settlement silently missing an obligation, and one that
+ * names an obligation nobody owes would decide about work that is not there.
+ *
+ * `pending` is read two ways, and the difference is the whole design. On an
+ * obligation with a single reading it means the work is NOT DONE, and the
+ * closure stops here until it is — the boundary stays open and the refusal costs
+ * no attempt, because telling the truth must not spend the run's retries. On an
+ * ambiguous one it is a PROPOSAL, and the next row is where a person settles it.
+ */
+function recordSettlementAuthoring(state, answer, resolved, cost) {
+    const declared = readDeclarations(answer.decisions.settlement);
+    const refusal = checkDeclarations(state, declared);
+    if (refusal !== null) {
+        return { ok: false, decision: reject(state, resolved, refusal.message, refusal, cost) };
+    }
+    return { ok: true, state: withSettlementDeclarations(state, declared ?? []) };
+}
+/** Every way a declaration can fail to answer for what the plan owes. */
+function checkDeclarations(state, declared) {
+    const owed = state.settlement?.compensations ?? [];
+    if (declared === null) {
+        return {
+            code: "FLOW_SETTLEMENT_INVALID",
+            message: "la declaración de saldo no es una lista de { note, index, outcome, evidence? }",
+            action: `declará una entrada por cada compensación vigente: ${owed.map((o) => `${o.note}[${o.index}]`).join(", ") || "ninguna"}`,
+        };
+    }
+    const missing = owed.filter((obligation) => matching(declared, obligation).length !== 1);
+    if (missing.length > 0) {
+        return {
+            code: "FLOW_SETTLEMENT_INCOMPLETE",
+            message: `falta declarar exactamente una vez: ${missing.map((o) => `${o.note}[${o.index}] ${o.text}`).join("; ")}`,
+            action: "cada compensación vigente lleva una declaración y sólo una: saltear una publicaría un saldo al que le falta trabajo",
+        };
+    }
+    const foreign = declared.filter((declaration) => !owed.some((obligation) => obligation.note === declaration.note && obligation.index === declaration.index));
+    if (foreign.length > 0) {
+        return {
+            code: "FLOW_SETTLEMENT_INVALID",
+            message: `se declara sobre obligaciones que el plan no debe: ${foreign.map((d) => `${d.note}[${d.index}]`).join(", ")}`,
+            action: "el saldo alcanza a las compensaciones vigentes que el tablero enumera, y a ninguna otra",
+        };
+    }
+    const undone = owed.filter((obligation) => !obligation.legacy && matching(declared, obligation)[0]?.outcome === "pending");
+    if (undone.length === 0)
+        return null;
+    return {
+        code: "PLAN_EXEC_SETTLEMENT_PENDING",
+        message: `queda compensación sin saldar: ${undone.map((o) => `${o.note}: ${o.text}`).join("; ")}`,
+        action: `hacé ese trabajo y volvé con 'aw flow advance --code ${state.session}' para declararla cumplida con su evidencia; el cierre espera acá`,
+    };
+}
+/** The obligations of `declared` that name this exact one. */
+function matching(declared, obligation) {
+    return declared.filter((declaration) => declaration.note === obligation.note && declaration.index === obligation.index);
+}
+/**
+ * The person's reading, applied to every ambiguous obligation at once.
+ *
+ * One answer for all of them, which is the degradation the plan declared before
+ * this was built: repeating a row is the batch loop's mechanism and it is keyed
+ * to the loop's own transitions. What the answer may NOT do is discharge work
+ * with no evidence behind it — "cumplida" over an obligation nobody proved is
+ * the one reading this boundary must refuse, and it refuses for free.
+ */
+function recordSettlementAnswer(state, answer, resolved, cost) {
+    const outcome = SETTLEMENT_BY_LABEL.get(answer.choice ?? "");
+    if (outcome === undefined)
+        return { ok: true, state };
+    const ambiguous = settlementAmbiguous(state);
+    const declared = state.settlement?.declared ?? [];
+    // The row's own consequence says the run stays here, and this is what makes
+    // that true: choosing "still pending" is choosing NOT to close, so advancing
+    // would contradict the sentence the person read before answering.
+    if (outcome === "pending") {
+        return {
+            ok: false,
+            decision: reject(state, resolved, `queda como compensación vigente: ${ambiguous.map((o) => `${o.note}: ${o.text}`).join("; ")}`, {
+                code: "PLAN_EXEC_SETTLEMENT_PENDING",
+                action: `hacé ese trabajo y volvé con 'aw flow advance --code ${state.session}': el cierre espera en la frontera de saldo`,
+            }, cost),
+        };
+    }
+    if (outcome === "settled") {
+        const unproven = ambiguous.filter((obligation) => matching(declared, obligation)[0]?.evidence === undefined);
+        if (unproven.length > 0) {
+            return {
+                ok: false,
+                decision: reject(state, resolved, `no hay evidencia declarada para: ${unproven.map((o) => `${o.note}: ${o.text}`).join("; ")}`, {
+                    code: "PLAN_EXEC_SETTLEMENT_PENDING",
+                    action: "una obligación se salda con lo que lo prueba: volvé a la frontera anterior y declará la evidencia, o elegí otra lectura",
+                }, cost),
+            };
+        }
+    }
+    return {
+        ok: true,
+        state: withSettlementDeclarations(state, declared.map((declaration) => ambiguous.some((obligation) => obligation.note === declaration.note && obligation.index === declaration.index)
+            ? ratified(declaration, outcome)
+            : declaration)),
+    };
+}
+/**
+ * The person's reading, applied — and the agent's evidence dropped with it.
+ *
+ * The class the person ratifies REPLACES the one the run proposed, and evidence
+ * belongs to the proposal it came with: evidence accredits a settlement, so on a
+ * handoff it is evidence of work this lineage did not do. Carrying it across the
+ * ratification was a dead end with no exit — `checkSettlements` refuses an
+ * obligation that brings evidence without being declared settled, so a run whose
+ * agent proposed "done, here is the proof" and whose person answered "that was
+ * somebody else's" could never publish its settlement and never close: the plan
+ * stayed neither executable nor closable, which is the incident this whole plan
+ * exists to end. The proposal is not lost — it is in the run's own trace.
+ */
+function ratified(declaration, outcome) {
+    return outcome === "settled"
+        ? { ...declaration, outcome }
+        : { note: declaration.note, index: declaration.index, outcome };
+}
+function readDeclarations(value) {
+    if (!Array.isArray(value))
+        return null;
+    const out = [];
+    for (const entry of value) {
+        const read = readDeclaration(entry);
+        if (read === null)
+            return null;
+        out.push(read);
+    }
+    return out;
+}
+/**
+ * One declaration, or `null` when it is not one.
+ *
+ * Evidence and outcome are checked together on purpose: "cumplida" without what
+ * proves it is not a slightly worse declaration, it is a discharge nobody can
+ * audit — and evidence attached to work that was NOT declared done is evidence
+ * of nothing, filed where somebody would later read it as a settlement.
+ */
+function readDeclaration(entry) {
+    if (typeof entry !== "object" || entry === null || Array.isArray(entry))
+        return null;
+    const raw = entry;
+    if (typeof raw.note !== "string" || raw.note.length === 0)
+        return null;
+    if (!Number.isInteger(raw.index))
+        return null;
+    if (!SETTLEMENT_OUTCOMES.includes(raw.outcome))
+        return null;
+    const outcome = raw.outcome;
+    const evidence = typeof raw.evidence === "string" ? raw.evidence.trim() : "";
+    if (outcome === "settled" && evidence.length === 0)
+        return null;
+    if (outcome !== "settled" && evidence.length > 0)
+        return null;
+    return {
+        note: raw.note,
+        index: raw.index,
+        outcome,
+        ...(outcome === "settled" ? { evidence } : {}),
+    };
+}
 /**
  * Prepare the complete decision view one boundary BEFORE the human choice.
  *
@@ -985,7 +1241,7 @@ async function registerSelectedDecision(fs, paths, state, snapshot, resolved, co
             }, cost),
         };
     }
-    const committed = await commitStoredPlanExecDecision(fs, paths, snapshot.root, preparation);
+    const committed = await commitStoredPlanExecDecision(fs, paths, snapshot.root, preparation, state.scope?.plan);
     if (!committed.ok) {
         return {
             ok: false,
@@ -1066,6 +1322,64 @@ function withStandaloneGuidance(decision, record) {
 function invalidScope(message, action) {
     return { code: "FLOW_SCOPE_INVALID", message, action };
 }
+/**
+ * What to do about a source-boundary failure, said at the moment it was found.
+ *
+ * One generic sentence used to answer all five codes, and it was wrong twice
+ * over: it sent somebody to declare sources that were already declared, and it
+ * sent a sentence of prose to a refinement. Structure goes to the refinement
+ * that owns it; a clause that names no observable check is a phrase to fix where
+ * it is being written, and at a save proposal nothing is even saved yet.
+ */
+function planBoundaryAction(code, moment) {
+    const then = moment === "proposal"
+        ? "corregilo en los bytes y volvé a proponer la vista previa"
+        : "corregilo con /w:plan-refine antes de volver a entrar a ejecución";
+    switch (code) {
+        case "PLAN_SOURCE_BOUNDARY_MISSING":
+            return `falta la declaración estructural: '> Límite de ejecución: checkout' bajo el título y '> Fuentes:' en cada fase — ${then}`;
+        case "PLAN_SOURCE_UNKNOWN":
+            return `ese alias no está en la tabla Fuentes del bloque WORKSPACE: declaralo ahí, o usá uno de los que ya están — ${then}`;
+        case "PLAN_TASK_SOURCE_OUTSIDE_PHASE":
+            return `la fuente de una tarea es un subconjunto de la de su fase: ajustá una de las dos — ${then}`;
+        case "PLAN_SOURCE_EXTERNAL_CLOSURE":
+            return `una cláusula de cierre no puede apoyarse en una superficie externa: llevá esa comprobación a '## Handoff operativo' y dejá en la cláusula una del checkout — ${then}`;
+        case "PLAN_SOURCE_LOCAL_PROOF_MISSING":
+            return moment === "proposal"
+                ? "nombrá en esa cláusula el comando, el archivo o la ruta que produce la comprobación, y volvé a proponer la vista previa"
+                : "es una frase del documento y no su estructura: nombrá en esa cláusula el comando, el archivo o la ruta que produce la comprobación";
+        default:
+            return then;
+    }
+}
+/**
+ * The closure-evidence gate, run BEFORE the preview is sealed.
+ *
+ * Position is the whole rule: the rejection has to arrive while the plan is
+ * still being written, so nobody is asked to approve a document the execution
+ * entry would refuse. The judgment is literally the same function, which is what
+ * makes the two moments impossible to disagree.
+ */
+function planEvidenceFrom(stopped, answer, observed) {
+    if (proposalContractOf(stopped) === null || answer.artifacts.length === 0)
+        return null;
+    const proposed = new Set(answer.artifacts.map((artifact) => artifact.path.trim()));
+    for (const plan of observed) {
+        if (!proposed.has(plan.path))
+            continue;
+        const failure = plan.failures[0];
+        if (failure === undefined)
+            continue;
+        return {
+            failure: {
+                code: failure.code,
+                message: `'${plan.path}': ${failure.message}`,
+                action: planBoundaryAction(failure.code, "proposal"),
+            },
+        };
+    }
+    return null;
+}
 /**
  * Seat the proposal an authoring answer just handed over — sealed, not believed.
  *
@@ -1618,7 +1932,16 @@ function attemptIdentity(state, input, seal, transition) {
     const batchIteration = currentBatchIteration(state, transition);
     const prior = state.attempts.filter((past) => past.invocation_id === seal);
     const twin = prior.find((past) => past.request_digest === digest);
-    const attempt = twin?.attempt ?? prior.length + 1;
+    // The next ordinal, asked with the SAME expression `AttemptLedger.record`
+    // validates it against. Counting rows instead is a second reading of one fact,
+    // and the two part the moment a resend is persisted: a recognized resend is
+    // re-evaluated and its row kept wearing the twin's ordinal — deliberately, so
+    // it still counts toward the cap — so the rows say two while the highest
+    // ordinal says one, and the next answer arrives as attempt 3 where the ledger
+    // accepts only 2. Nobody can answer that boundary, and `recover` reads the
+    // chain as coherent because replaying two identical rows never fails.
+    const highest = Math.max(0, ...prior.map((past) => past.attempt));
+    const attempt = twin?.attempt ?? highest + 1;
     const parent = attempt === 1
         ? null
         : (prior.find((past) => past.attempt === attempt - 1)?.request_digest ?? null);