@tacuchi/agent-workflow-cli 21.6.0 → 21.7.0

package/dist/domain/flow/authority.js

@@ -31,6 +31,14 @@ export const CHASSIS_SCOPE = "chassis";
 export const COMMAND_SCOPE_PREFIX = "cmd:";
 /** The four migration tranches the plan cuts over one at a time. */
 export const FLOW_TRANCHES = ["quick", "spec", "plan", "chassis"];
+/** The proposal contract of an authoring row, or `null` when it proposes nothing. */
+export function proposalContractOf(decision) {
+    return decision.proposes ?? null;
+}
+/** The approve label of a row that decides a standing proposal, or `null`. */
+export function publishApprovalOf(decision) {
+    return decision.publishes?.approve ?? null;
+}
 /** A decision computes a verdict; writing is the exception that declares itself. */
 export const DEFAULT_TRANSITION_EFFECTS = ["read_only"];
 /** What applying this transition does. */
@@ -46,10 +54,75 @@ export function effectsOf(decision) {
  * folder and its correlative — and both are facts the engine owns.
  */
 export const RUN_PLACEHOLDERS = ["{session}", "{code}"];
+/**
+ * The Workline operations this CLI materializes inside its own process.
+ *
+ * A CLOSED union, and closed is the whole point of it. An action executed
+ * internally is one nobody read as a command line first, so what may run that way
+ * has to be enumerable, auditable and impossible to widen with data: the row names
+ * an operation, never a program. `invocation.program` and `invocation.args` are
+ * NEVER interpreted — they stay as the equivalent command a person would run to
+ * obtain the same reading, which is what keeps the two comparable.
+ *
+ * The four members are exactly the deterministic surface the plan names: the
+ * board, the sessions' own artifacts (their reading and their seeding), the close
+ * and the publication of an already approved proposal. Everything that runs code,
+ * touches git or produces a judgment is deliberately NOT here.
+ *
+ * Publishing is the one that writes documents the engine does not author, and it
+ * is admissible for a reason the others do not need: it writes NOTHING of its own
+ * — only the exact bytes a person approved, under the seal they approved them by.
+ */
+export const INTERNAL_ACTION_OPERATIONS = [
+    /** Project the workspace board — what `aw status --json` returns. */
+    "workspace.board",
+    /** Read, and where the command seeds them, a session's own artifacts. */
+    "session.artifacts",
+    /** Close the session and upsert its HISTORY row. */
+    "session.close",
+    /** Write the run's approved proposal, all of it or none of it. */
+    "proposal.publish",
+];
+/**
+ * The effect classes each internal operation can really apply.
+ *
+ * Read by the guard, not by the runtime: at runtime the executor reports what it
+ * ACTUALLY applied and the same `executionVerdict` that judges an external result
+ * refuses anything short of the row's declared effects. This table is what makes
+ * the mismatch a failing test instead of a run that discovers it — a row declaring
+ * `mutate_overwrite` while its operation only reads can never be satisfied, and
+ * finding that out at the boundary is finding it out too late.
+ */
+export const INTERNAL_OPERATION_EFFECTS = {
+    "workspace.board": ["read_only"],
+    "session.artifacts": ["read_only", "local_additive"],
+    "session.close": ["read_only", "local_additive", "mutate_overwrite"],
+    // Creating and replacing, both real — and which of the two happens is decided
+    // by the proposal, not by the row: what the row declares here is the ceiling.
+    "proposal.publish": ["local_additive", "mutate_overwrite"],
+};
 /** The delegated action of a transition, or `null` when the engine applies it itself. */
 export function actionOf(decision) {
     return decision.action ?? null;
 }
+/**
+ * What this transition runs in-process, or `null` when whoever called it must.
+ *
+ * One predicate for every caller — the walk, the driver and the guard — so none of
+ * them can answer "does the CLI run this itself?" differently from the others.
+ *
+ * An action with no `execution` at all cannot happen through the type, and it is
+ * still read defensively: the answer for a malformed row is "not the CLI's", which
+ * fails closed. Throwing instead would take down every caller that merely ASKS the
+ * question — and asking it is now on the path of every boundary.
+ */
+export function internalActionOf(decision) {
+    const action = actionOf(decision);
+    if (action === null || action.execution?.kind !== "internal")
+        return null;
+    const { kind: _internal, ...plan } = action.execution;
+    return plan;
+}
 /** What makes this transition happen at all, or `null` when it always does. */
 export function conditionOf(decision) {
     return decision.condition ?? null;
@@ -397,9 +470,14 @@ export const FLOW_DECISIONS = [
         // judged. `quick` has none because it has no document to write it into, and
         // the two plan-authoring flows converge on a document they hand to the next
         // flow rather than on one they mark green.
+        //
+        // SPEC's used to be a promotion of its own, `status: ready-for-plan` written
+        // after the save. It is now the publication: the stamp travels inside the
+        // approved bytes, so the row that marks the criteria green is the row that
+        // writes them — one document, one write.
         realized_by: {
             kind: "transitions",
-            ids: ["spec-refine.status-promotion", "plan-exec.plan-done"],
+            ids: ["spec-refine.publication", "plan-exec.plan-done"],
         },
     },
     {
@@ -459,6 +537,7 @@ export const FLOW_DECISIONS = [
                 target: ".",
                 input: null,
             },
+            execution: { kind: "internal", operation: "session.close" },
             evidence: ["chassis.sesion-cerrada"],
             idempotent: true,
             recovery: "una sesión que no cerró deja la corrida abierta: no la marques finalizada — reparás la fila del registro con 'aw history-update' y volvés a cerrar",
@@ -519,6 +598,7 @@ export const FLOW_DECISIONS = [
         // "I looked". Read-only, so it never stops to be authorized.
         action: {
             invocation: { program: "aw", args: ["status", "--json"], target: ".", input: null },
+            execution: { kind: "internal", operation: "workspace.board" },
             evidence: ["quick.board-listed"],
             idempotent: true,
             recovery: "volvé a correr 'aw status --json' y devolvé su salida real; si el tablero no se puede leer, resolvé eso antes de seguir",
@@ -576,6 +656,7 @@ export const FLOW_DECISIONS = [
                 target: SESSION_TARGET,
                 input: null,
             },
+            execution: { kind: "internal", operation: "session.artifacts" },
             evidence: ["quick.session-present"],
             idempotent: true,
             recovery: "creá la sesión con 'aw session-create --type quick --name <slug>-quick --objetivo \"<objetivo>\"' y volvé a devolver la lectura",
@@ -625,6 +706,11 @@ export const FLOW_DECISIONS = [
                 target: SESSION_TARGET,
                 input: null,
             },
+            execution: {
+                kind: "internal",
+                operation: "session.artifacts",
+                dump: ["objetivo", "checkpoint"],
+            },
             evidence: [
                 "quick.objetivo-sembrado",
                 "quick.criterios-sembrados",
@@ -646,6 +732,10 @@ export const FLOW_DECISIONS = [
         // --source resolves no target and passes unconditionally.
         action: {
             invocation: { program: "aw", args: ["sources", "--verbose"], target: ".", input: null },
+            execution: {
+                kind: "external",
+                reason: "la rama esperada de cada fuente es un veredicto sobre git, y un workspace sin fuentes declaradas no lo tiene: leerlo desde adentro diría 'verificada' donde no hay nada que verificar",
+            },
             evidence: ["quick.rama-verificada"],
             idempotent: true,
             recovery: "resolvé la rama de la fuente que no coincide y volvé a leer las fuentes: nunca limpies ni cambies de rama sin confirmación",
@@ -699,6 +789,7 @@ export const FLOW_DECISIONS = [
                 target: SESSION_TARGET,
                 input: null,
             },
+            execution: { kind: "internal", operation: "session.artifacts", dump: ["scripts"] },
             evidence: ["quick.scripts-derivados"],
             idempotent: true,
             recovery: "escribí el DDL o DML en el SCRIPTS.sql de la sesión y volvé a devolver el dump; ejecutarlo no es una alternativa que este contrato admita",
@@ -745,6 +836,10 @@ export const FLOW_DECISIONS = [
                 target: SESSION_TARGET,
                 input: null,
             },
+            execution: {
+                kind: "external",
+                reason: "los criterios verdes exigen haber CORRIDO la prueba del entregable, y correr código nunca es una operación interna",
+            },
             evidence: ["quick.criterios-verdes"],
             idempotent: true,
             recovery: "arreglá lo que el criterio reprobó y volvé a correr sus validaciones: la transición sigue pendiente hasta que su salida real vuelva en verde",
@@ -809,6 +904,7 @@ export const FLOW_DECISIONS = [
                 target: SESSION_TARGET,
                 input: null,
             },
+            execution: { kind: "internal", operation: "session.artifacts" },
             evidence: ["spec.session-present"],
             idempotent: true,
             recovery: "creá la sesión con 'aw session-create --type refine --name <slug>-spec-refine --objetivo \"<objetivo>\"' y volvé a devolver la lectura",
@@ -1025,15 +1121,37 @@ export const FLOW_DECISIONS = [
                 target: SESSION_TARGET,
                 input: null,
             },
+            execution: {
+                kind: "external",
+                reason: "el checklist de ready-for-plan es un juicio sobre lo que dice la spec, no la lectura del artefacto que lo contiene",
+            },
             evidence: ["spec.ready-for-plan-checklist"],
             idempotent: true,
             recovery: "lo que el checklist reprobó vuelve al loop como gap: resolvelo y volvé a evaluar el gate con su estado real",
         },
     },
+    {
+        id: "spec-refine.save-proposal",
+        scope: "spec-refine",
+        title: "entregar los bytes exactos de la spec refinada, con su status ya sellado",
+        authority: "agent",
+        ownership: "cli-owned",
+        document: SPEC_LOOP,
+        attribution: SPEC_ATTRIBUTION,
+        // The stamp travels INSIDE these bytes, and that is the whole reason the
+        // separate promotion row is gone: `status: ready-for-plan` is a projection of
+        // the same save, so writing it apart made the person confirm one half and
+        // authorize the other. One document, one proposal, one write.
+        proposes: {
+            destinations: ["docs/specs"],
+            effects: ["local_additive", "mutate_overwrite"],
+            limits: { maxArtifacts: 8, maxArtifactBytes: 256 * 1024 },
+        },
+    },
     {
         id: "spec-refine.save-confirmation",
         scope: "spec-refine",
-        title: "confirmar la sobreescritura de la spec",
+        title: "aprobar la vista previa de la spec y guardarla",
         authority: "human",
         ownership: "cli-owned",
         document: SPEC_LOOP,
@@ -1042,37 +1160,35 @@ export const FLOW_DECISIONS = [
         // was promoting the status and asking for the overwrite afterwards, so the
         // person would have been confirming a write that already happened. The
         // doctrine's own line is `edit_in_place_with_confirm(spec) + stamp`.
+        publishes: { approve: "Aprobar y guardar" },
         alternatives: [
             {
-                label: "Guardar especificación refinada",
-                consequence: "la spec se sobrescribe en su lugar y queda sellada como ready-for-plan",
+                label: "Aprobar y guardar",
+                consequence: "se escriben exactamente los archivos de la vista previa —la spec en su lugar, sellada como ready-for-plan— y no se vuelve a preguntar por esos efectos",
                 recommended: true,
             },
             {
-                label: "Preguntar algo más",
-                consequence: "el refinamiento sigue abierto y la spec queda como está",
+                label: "Refinar",
+                consequence: "el refinamiento sigue abierto, no se escribe nada y la spec queda como está",
                 recommended: false,
             },
         ],
     },
     {
-        id: "spec-refine.status-promotion",
+        id: "spec-refine.publication",
         scope: "spec-refine",
-        title: "promover el status de la spec a ready-for-plan",
+        title: "publicar la propuesta aprobada de la spec en un solo acto",
         authority: "cli",
         ownership: "cli-owned",
         document: SPEC_LOOP,
         attribution: SPEC_ATTRIBUTION,
-        effects: ["mutate_overwrite"],
-        // The stamp is a write on a document the engine does not edit, so what it
-        // demands back is the board's own reading of that document's status. The
-        // effect is not self-authorizable: the run stops to be authorized before this
-        // invocation is ever named.
+        effects: ["local_additive", "mutate_overwrite"],
         action: {
-            invocation: { program: "aw", args: ["status", "--json"], target: ".", input: null },
-            evidence: ["spec.status-ready-for-plan"],
+            invocation: { program: "aw", args: ["flow", "advance"], target: ".", input: null },
+            execution: { kind: "internal", operation: "proposal.publish" },
+            evidence: ["spec.propuesta-publicada"],
             idempotent: true,
-            recovery: "sellá 'status: ready-for-plan' en la spec y volvé a devolver la lectura del tablero; si el sello no está, la transición sigue pendiente",
+            recovery: "la publicación es todo-o-nada: si falló, nada quedó escrito y se reintenta el mismo contenido sin volver a aprobar; si la base cambió, volvé a redactar la propuesta sobre el documento vigente",
         },
     },
     // ── PLAN — new ────────────────────────────────────────────────────────────
@@ -1094,6 +1210,7 @@ export const FLOW_DECISIONS = [
         // that somebody looked. Suggesting is the outcome; it never blocks.
         action: {
             invocation: { program: "aw", args: ["status", "--json"], target: ".", input: null },
+            execution: { kind: "internal", operation: "workspace.board" },
             evidence: ["plan.spec-status-leido"],
             idempotent: true,
             recovery: "volvé a correr 'aw status --json' y devolvé su salida real; sin el status de la spec no hay nada que sugerir ni que dar por listo",
@@ -1115,6 +1232,7 @@ export const FLOW_DECISIONS = [
                 target: SESSION_TARGET,
                 input: null,
             },
+            execution: { kind: "internal", operation: "session.artifacts" },
             evidence: ["plan.session-present"],
             idempotent: true,
             recovery: "creá la sesión con 'aw session-create --type refine --name <slug>-plan-new --objetivo \"<objetivo>\"' y volvé a devolver la lectura",
@@ -1248,32 +1366,72 @@ export const FLOW_DECISIONS = [
                 target: SESSION_TARGET,
                 input: null,
             },
+            execution: {
+                kind: "external",
+                reason: "la coherencia del plan es un juicio sobre lo que dice, no la lectura del artefacto que lo contiene",
+            },
             evidence: ["plan.coherence-checklist"],
             idempotent: true,
             recovery: "lo que el checklist reprobó vuelve al loop como gap: resolvelo y volvé a evaluar el gate con su estado real",
         },
     },
+    {
+        id: "plan-new.save-proposal",
+        scope: "plan-new",
+        title: "entregar los bytes exactos del plan y de los hermanos que se extraigan",
+        authority: "agent",
+        ownership: "cli-owned",
+        document: PLAN_NEW_LOOP,
+        attribution: PLAN_ATTRIBUTION,
+        // The generation used to write with NO effect row at all: the person confirmed
+        // and the document appeared, with the engine crediting nothing. The proposal
+        // is what makes that write visible — enumerated, weighed and sealed before it
+        // is approved.
+        proposes: {
+            destinations: ["docs/plans"],
+            effects: ["local_additive"],
+            limits: { maxArtifacts: 8, maxArtifactBytes: 256 * 1024 },
+        },
+    },
     {
         id: "plan-new.save-confirmation",
         scope: "plan-new",
-        title: "confirmar la escritura del plan o de sus hermanos",
+        title: "aprobar la vista previa del plan y guardarlo",
         authority: "human",
         ownership: "cli-owned",
         document: PLAN_NEW_LOOP,
         attribution: PLAN_ATTRIBUTION,
+        publishes: { approve: "Aprobar y guardar" },
         alternatives: [
             {
-                label: "Guardar plan",
-                consequence: "el plan se escribe en docs/plans, y si el split fue aceptado se escriben también sus hermanos",
+                label: "Aprobar y guardar",
+                consequence: "se escriben exactamente los archivos de la vista previa en docs/plans, hermanos incluidos si el split fue aceptado",
                 recommended: true,
             },
             {
-                label: "Preguntar algo más",
+                label: "Refinar",
                 consequence: "la generación sigue abierta y no se escribe ningún documento",
                 recommended: false,
             },
         ],
     },
+    {
+        id: "plan-new.publication",
+        scope: "plan-new",
+        title: "publicar la propuesta aprobada del plan en un solo acto",
+        authority: "cli",
+        ownership: "cli-owned",
+        document: PLAN_NEW_LOOP,
+        attribution: PLAN_ATTRIBUTION,
+        effects: ["local_additive"],
+        action: {
+            invocation: { program: "aw", args: ["flow", "advance"], target: ".", input: null },
+            execution: { kind: "internal", operation: "proposal.publish" },
+            evidence: ["plan.propuesta-publicada"],
+            idempotent: true,
+            recovery: "la publicación es todo-o-nada: si falló, no quedó ningún documento a medias y se reintenta el mismo contenido sin volver a aprobar",
+        },
+    },
     {
         id: "plan-new.adoption",
         scope: "plan-new",
@@ -1300,6 +1458,7 @@ export const FLOW_DECISIONS = [
                 target: SESSION_TARGET,
                 input: null,
             },
+            execution: { kind: "internal", operation: "session.artifacts" },
             evidence: ["plan.session-present"],
             idempotent: true,
             recovery: "creá o reabrí la sesión con 'aw session-create' o 'aw session-resume --code <NNN> --reopen' y volvé a devolver la lectura",
@@ -1384,75 +1543,89 @@ export const FLOW_DECISIONS = [
                 target: SESSION_TARGET,
                 input: null,
             },
+            execution: {
+                kind: "external",
+                reason: "la forma ejecutable del plan es un juicio sobre lo que dice, no la lectura del artefacto que lo contiene",
+            },
             evidence: ["plan.executability-checklist"],
             idempotent: true,
             recovery: "lo que el checklist reprobó vuelve al loop como gap: resolvelo y volvé a evaluar el gate con su estado real",
         },
     },
+    {
+        id: "plan-refine.split-in-place",
+        scope: "plan-refine",
+        title: "reducir el plan original y extraer los hermanos sin mover trabajo completado",
+        authority: "agent",
+        ownership: "cli-owned",
+        document: PLAN_REFINE_SPLIT,
+        attribution: PLAN_ATTRIBUTION,
+        // It used to be a delegated WRITE after the confirmation, which is what made
+        // the refinement ask twice: once to confirm the plan and again to authorize
+        // the siblings. Reducing the original and extracting the siblings is drafting
+        // — it decides what the bytes are — so it happens BEFORE the proposal and its
+        // result is visible where it belongs, as files enumerated in the preview.
+        // Nothing is credited here: this row no longer claims a write happened.
+        condition: {
+            threshold: splitThreshold("plan-refine.split-signal"),
+            otherwise: "el umbral de dos señales no disparó: el plan conserva su número y su alcance, y no se extrae ningún hermano",
+        },
+    },
+    {
+        id: "plan-refine.save-proposal",
+        scope: "plan-refine",
+        title: "entregar los bytes exactos del plan refinado, ya normalizado, sin bloques condicionales vacíos y sin tocar estados ni casillas",
+        authority: "agent",
+        ownership: "cli-owned",
+        document: PLAN_REFINE_LOOP,
+        attribution: PLAN_ATTRIBUTION,
+        // The normalization rule lives in this row's own contract now, and that is the
+        // merge that removes a write: normalizing the form is not a second edit of the
+        // plan, it is what the drafted bytes already are. A separate row for it wrote
+        // the same document twice and asked to be authorized for the second half.
+        proposes: {
+            destinations: ["docs/plans"],
+            effects: ["local_additive", "mutate_overwrite"],
+            limits: { maxArtifacts: 8, maxArtifactBytes: 256 * 1024 },
+        },
+    },
     {
         id: "plan-refine.save-confirmation",
         scope: "plan-refine",
-        title: "confirmar la sobreescritura del plan refinado",
+        title: "aprobar la vista previa del plan refinado y guardarlo",
         authority: "human",
         ownership: "cli-owned",
         document: PLAN_REFINE_LOOP,
         attribution: PLAN_ATTRIBUTION,
+        publishes: { approve: "Aprobar y guardar" },
         alternatives: [
             {
-                label: "Guardar plan refinado",
-                consequence: "el plan se edita en su lugar con su traza de refinamiento, y si el split fue aceptado se escriben los hermanos extraídos",
+                label: "Aprobar y guardar",
+                consequence: "se escriben exactamente los archivos de la vista previa —el plan en su lugar y los hermanos extraídos, si los hay— y no se vuelve a preguntar por esos efectos",
                 recommended: true,
             },
             {
-                label: "Preguntar algo más",
-                consequence: "el refinamiento sigue abierto y el plan queda como está",
+                label: "Refinar",
+                consequence: "el refinamiento sigue abierto, no se escribe nada y el plan queda como está",
                 recommended: false,
             },
         ],
     },
     {
-        id: "plan-refine.split-in-place",
-        scope: "plan-refine",
-        title: "reducir el plan original y extraer los hermanos sin mover trabajo completado",
-        authority: "cli",
-        ownership: "cli-owned",
-        document: PLAN_REFINE_SPLIT,
-        attribution: PLAN_ATTRIBUTION,
-        effects: ["local_additive", "mutate_overwrite"],
-        // AFTER the confirmation, and the doctrine's own sequence is why: the save
-        // branch reads `Guardar planes → edit original reduced (confirmation) + write
-        // extracted siblings`. The registry had both writes ahead of the gate and of
-        // the confirmation — the same defect the SPEC tranche found in its stamp, so
-        // the order moved to where the document puts it.
-        action: {
-            invocation: { program: "aw", args: ["status", "--json"], target: ".", input: null },
-            evidence: ["plan.hermanos-extraidos"],
-            idempotent: true,
-            recovery: "reducí el original en su lugar, escribí los hermanos extraídos y volvé a devolver la lectura; una tarea ya marcada nunca se muda a un hermano",
-        },
-        condition: {
-            threshold: splitThreshold("plan-refine.split-signal"),
-            otherwise: "el umbral de dos señales no disparó: el plan conserva su número y su alcance, y no se extrae ningún hermano",
-        },
-    },
-    {
-        id: "plan-refine.normalize-on-write",
+        id: "plan-refine.publication",
         scope: "plan-refine",
-        title: "normalizar la forma sin escribir bloques condicionales vacíos ni tocar estados",
+        title: "publicar la propuesta aprobada del plan refinado en un solo acto",
         authority: "cli",
         ownership: "cli-owned",
         document: PLAN_REFINE_LOOP,
         attribution: PLAN_ATTRIBUTION,
-        effects: ["mutate_overwrite"],
-        // A write on a document the engine does not edit, so it is delegated like
-        // every other one. It had neither action nor evidence, which meant the run
-        // recorded "normalized" for something nothing performed — the phantom
-        // confirmation this whole contract exists to refuse.
+        effects: ["local_additive", "mutate_overwrite"],
         action: {
-            invocation: { program: "aw", args: ["status", "--json"], target: ".", input: null },
-            evidence: ["plan.forma-normalizada"],
+            invocation: { program: "aw", args: ["flow", "advance"], target: ".", input: null },
+            execution: { kind: "internal", operation: "proposal.publish" },
+            evidence: ["plan.propuesta-publicada"],
             idempotent: true,
-            recovery: "normalizá la forma sin tocar estados ni casillas y volvé a devolver la lectura; normalizar de nuevo lo ya normalizado no rompe nada",
+            recovery: "la publicación es todo-o-nada: el original reducido y sus hermanos entran juntos o no entra ninguno; si la base cambió, volvé a redactar la propuesta sobre el plan vigente",
         },
     },
     // ── PLAN — exec ───────────────────────────────────────────────────────────
@@ -1472,6 +1645,7 @@ export const FLOW_DECISIONS = [
                 target: SESSION_TARGET,
                 input: null,
             },
+            execution: { kind: "internal", operation: "session.artifacts" },
             evidence: ["plan.session-present"],
             idempotent: true,
             recovery: "creá la sesión con 'aw session-create --type exec --name <slug>-plan-exec --objetivo \"<objetivo>\"' y volvé a devolver la lectura",
@@ -1491,6 +1665,10 @@ export const FLOW_DECISIONS = [
         // the gate's finding, not a detail to wave through.
         action: {
             invocation: { program: "aw", args: ["status", "--json"], target: ".", input: null },
+            execution: {
+                kind: "external",
+                reason: "la forma ejecutable del plan es un juicio sobre lo que dice, no la lectura del tablero que lo lista",
+            },
             evidence: ["plan.forma-ejecutable"],
             idempotent: true,
             recovery: "volvé a correr 'aw status --json' y devolvé su salida real; si el plan no se puede leer, eso ES el hallazgo del gate",
@@ -1615,6 +1793,10 @@ export const FLOW_DECISIONS = [
         // its current branch, the expected one and whether they match.
         action: {
             invocation: { program: "aw", args: ["sources", "--verbose"], target: ".", input: null },
+            execution: {
+                kind: "external",
+                reason: "la rama esperada de cada fuente es un veredicto sobre git, y un workspace sin fuentes declaradas no lo tiene",
+            },
             evidence: ["plan.rama-verificada"],
             idempotent: true,
             recovery: "resolvé la rama de la fuente que no coincide y volvé a leer las fuentes: nunca limpies ni cambies de rama sin confirmación",
@@ -1698,6 +1880,10 @@ export const FLOW_DECISIONS = [
         // ticked boxes. "I marked it" is the one thing this contract will not take.
         action: {
             invocation: { program: "aw", args: ["status", "--json"], target: ".", input: null },
+            execution: {
+                kind: "external",
+                reason: "marcar la casilla reescribe el plan-doc, y este motor no lo edita",
+            },
             evidence: ["plan.casillas-marcadas"],
             idempotent: true,
             recovery: "marcá la casilla de la tarea cuyo trabajo local terminó y volvé a devolver la lectura del tablero; marcar de nuevo lo ya marcado no rompe nada",
@@ -1719,6 +1905,10 @@ export const FLOW_DECISIONS = [
         // when a state and its boxes disagree.
         action: {
             invocation: { program: "aw", args: ["status", "--json"], target: ".", input: null },
+            execution: {
+                kind: "external",
+                reason: "escribir el '> Estado:' de la fase reescribe el plan-doc, y este motor no lo edita",
+            },
             evidence: ["plan.estado-de-fase-aplicado"],
             idempotent: true,
             recovery: "escribí el '> Estado:' que la fase realmente tiene —con su '> Bloqueo:' si quedó bloqueada— y volvé a devolver la lectura; una fase sin su prueba corrida no pasa a validada",
@@ -1745,6 +1935,10 @@ export const FLOW_DECISIONS = [
                 target: SESSION_TARGET,
                 input: null,
             },
+            execution: {
+                kind: "external",
+                reason: "correr las pruebas de fase es ejecutar código, nunca una operación interna",
+            },
             evidence: ["plan.validaciones-de-fase-verdes"],
             idempotent: true,
             recovery: "arreglá lo que la validación reprobó y volvé a correr las pruebas afectadas: la transición sigue pendiente hasta que su salida real vuelva en verde",
@@ -1787,6 +1981,10 @@ export const FLOW_DECISIONS = [
         // so it is read, not asserted.
         action: {
             invocation: { program: "aw", args: ["status", "--json"], target: ".", input: null },
+            execution: {
+                kind: "external",
+                reason: "la validación final es el gate de convergencia del recorrido: darlo por verde desde una lectura sería aprobarlo sin correrlo",
+            },
             evidence: ["plan.validacion-final-verde"],
             idempotent: true,
             recovery: "un chequeo diferido nunca cuenta como aprobado: deja su fase bloqueada y el plan abierto, así que corré lo que falte y volvé a leer el tablero",
@@ -1845,6 +2043,10 @@ export const FLOW_DECISIONS = [
         },
         action: {
             invocation: { program: "aw", args: ["status", "--json"], target: ".", input: null },
+            execution: {
+                kind: "external",
+                reason: "sellar el done reescribe el plan-doc, y este motor no lo edita",
+            },
             evidence: ["plan.estado-done-sellado"],
             idempotent: true,
             recovery: "escribí '> Estado: done' y su '> Cierre:' en la línea de abajo y volvé a devolver la lectura; si el tablero no lo lee cerrado, la transición sigue pendiente",
@@ -1873,6 +2075,10 @@ export const FLOW_DECISIONS = [
         // clean or explicitly acknowledged").
         action: {
             invocation: { program: "aw", args: ["sources", "--verbose"], target: ".", input: null },
+            execution: {
+                kind: "external",
+                reason: "crear un commit es un efecto sobre git que este ejecutor no aplica",
+            },
             evidence: ["plan.commits-por-fuente"],
             idempotent: false,
             recovery: "una fuente que quedó con cambios sin commitear deja el batch SIN commitear: registralo así en CHECKPOINT y BACKLOG en vez de commitear a medias",