@tacuchi/agent-workflow-cli 25.2.0 → 25.3.1

package/dist/domain/settlement.js

@@ -0,0 +1,129 @@
+/**
+ * The successor of one carrier note, or `null` when it would change nothing.
+ *
+ * Everything but the settled obligations crosses over: the decision, its reason,
+ * the assertions it amends, its scope, its consumers and its evidence. What the
+ * settlement adds is the evidence each discharge produced — evidence that still
+ * counts is exactly what `evidence_preserved` is for — and what it removes is
+ * the obligations somebody actually did.
+ *
+ * `null` and not an empty note: publishing a successor identical in force to its
+ * predecessor would grow the chain by one record per attempt and say nothing.
+ */
+export function deriveSettlementNote(carrier, settlements, at) {
+    const mine = settlements.filter((settlement) => settlement.note === carrier.id);
+    const failures = checkSettlements(carrier, mine);
+    if (failures.length > 0)
+        return { ok: false, failures };
+    const byIndex = new Map(mine.map((settlement) => [settlement.index, settlement]));
+    const kept = [];
+    const classified = [];
+    const settled = [];
+    const evidence = [];
+    for (const [index, obligation] of carrier.obligations.entries()) {
+        const settlement = byIndex.get(index);
+        if (settlement !== undefined && settlement.outcome === "settled") {
+            settled.push(obligation.text);
+            if (settlement.evidence !== undefined)
+                evidence.push(settlement.evidence);
+            continue;
+        }
+        const held = settlement?.outcome === "handoff" ? reclassified(obligation, "handoff") : obligation;
+        kept.push(held);
+        // Anything still unclassed leaves carrying the reading the board already
+        // reported FOR THAT POSITION — that is what "clasifica lo que queda" means,
+        // and without it the successor could not be appended at all. The position is
+        // the carrier's, never the survivors': dropping one shifts the rest.
+        classified.push(held.declared ? held : reclassified(held, at.resolved.get(index) ?? held.kind));
+    }
+    if (settled.length === 0 && sameObligations(carrier.obligations, classified)) {
+        return { ok: true, draft: null, settled: [] };
+    }
+    return {
+        ok: true,
+        settled,
+        draft: {
+            schema: carrier.schema,
+            lineage: {
+                spec: carrier.lineage.spec,
+                plan: carrier.lineage.plan,
+                // The settling run when there is one; the carrier's own when `aw settle`
+                // acts on a plan whose run is long closed. Either way it is a real
+                // session and a real phase, never a placeholder.
+                execution: { session: at.session, phase: at.phase },
+            },
+            decision: carrier.decision,
+            reason: carrier.reason,
+            supersedes_assertions: [...carrier.supersedes_assertions],
+            supersedes_note: carrier.id,
+            scope: carrier.scope,
+            consumers: [...carrier.consumers],
+            evidence_preserved: [...carrier.evidence_preserved, ...evidence],
+            evidence_invalidated: [...carrier.evidence_invalidated],
+            obligations: classified,
+            resume_point: carrier.resume_point,
+            date: at.date,
+        },
+    };
+}
+function reclassified(obligation, kind) {
+    return { text: obligation.text, kind, declared: true };
+}
+function sameObligations(before, after) {
+    return (before.length === after.length &&
+        before.every((obligation, index) => {
+            const other = after[index];
+            return (other !== undefined &&
+                other.text === obligation.text &&
+                other.kind === obligation.kind &&
+                other.declared === obligation.declared);
+        }));
+}
+/**
+ * Every way a settlement can fail to name real work, each with its own code.
+ *
+ * A settlement that points at an obligation the note does not carry, or that
+ * claims work is done without saying what proves it, is not a slightly worse
+ * settlement: it is a discharge nobody can audit, and the chain would record it
+ * as authoritative.
+ */
+function checkSettlements(carrier, settlements) {
+    const failures = [];
+    const seen = new Set();
+    for (const settlement of settlements) {
+        const obligation = carrier.obligations[settlement.index];
+        if (obligation === undefined) {
+            failures.push({
+                code: "SETTLEMENT_OBLIGATION_ABSENT",
+                message: `${carrier.id} no tiene una obligación en la posición ${settlement.index}`,
+                action: `esa nota carga ${carrier.obligations.length} obligación(es): saldá una que exista`,
+            });
+            continue;
+        }
+        if (seen.has(settlement.index)) {
+            failures.push({
+                code: "SETTLEMENT_OBLIGATION_REPEATED",
+                message: `${carrier.id} recibe dos saldos para la misma obligación: ${obligation.text}`,
+                action: "una obligación se salda una vez; decidí cuál de las dos lecturas vale",
+            });
+            continue;
+        }
+        seen.add(settlement.index);
+        if (settlement.outcome === "settled" && (settlement.evidence ?? "").trim().length === 0) {
+            failures.push({
+                code: "SETTLEMENT_EVIDENCE_MISSING",
+                message: `se declara cumplida '${obligation.text}' sin decir qué lo prueba`,
+                action: "declará la evidencia del saldo: un comando corrido, una prueba o una inspección; sin eso no es un saldo, es una afirmación",
+            });
+        }
+        if (settlement.outcome !== "settled" && settlement.evidence !== undefined) {
+            failures.push({
+                code: "SETTLEMENT_EVIDENCE_UNEXPECTED",
+                message: `'${obligation.text}' no se declara cumplida y aun así trae evidencia`,
+                action: "la evidencia acredita un saldo: sacala, o declará la obligación cumplida",
+            });
+        }
+    }
+    return failures;
+}
+//# sourceMappingURL=settlement.js.map

package/dist/domain/settlement.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"settlement.js","sourceRoot":"","sources":["../../src/domain/settlement.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tacuchi/agent-workflow-cli",
-  "version": "25.2.0",
+  "version": "25.3.1",
   "description": "Runtime CLI for Workline — the stages + loops + artifacts system for agent work. Bundles the universal `w` skill set under `skills/w/` (slash commands `/w:*`: spec-new/spec-refine, plan-new/plan-exec, quick, persist, workspace-init, export-*); `self install --target <host>` copies SKILL + commands + hooks into the host. Pluggable capability skills resolve through `.workflow/skills.toml`. Namespace auto-detected from any `.<ns>/sessions/` dir in CWD; default `workflow`.",
   "type": "module",
   "bin": {

package/skills/w/commands/resume.md

@@ -32,10 +32,10 @@ No target → **every** pending item as `candidates` in the CLI's order, `propos
 
 ## What the CLI decides (do not re-derive)
 
-- **Priority**: unrefined spec → refined spec with no plan → plan not `done`; started first. A loose session is a notice, never a candidate.
+- **Priority**: unrefined spec → refined spec with no plan → plan not `done` → live handoff; started first. A loose session is a notice, never a candidate.
 - **Ties**: equal priority and progress → no single recommendation; date never splits.
 - **Spec→plan link**: `Derived from` or `## Origin`, never the slug; unproven stays unplanned.
-- **The route**: `/w:spec-refine`, `/w:plan-new`, `/w:plan-exec`, `aw session-resume --reopen`.
+- **The route**: `/w:spec-refine`, `/w:plan-new`, `/w:plan-exec`, `aw settle prepare`, `aw session-resume --reopen`.
 
 > A plan is not finished because its boxes are ticked: re-entry is the first phase not `validada`, a `bloqueada` phase with its declared reason, or — phases green, plan never closed — the final validation. One declaring `done` over open work comes back as inconsistent. An obligation leaving it neither runnable nor closable is said before its percentage.
 

package/skills/w/loops/plan-exec-loop/LOOP.md

@@ -151,6 +151,37 @@ run stops at it: declaring a deviation no longer carries on to the commit by its
 
 > **How an affirmation is addressed:** a decision note names the criteria it amends as `S{NNN}/AC-nn` — `NNN` from the spec file's number, `AC-nn` the label the criterion carries in the spec's checklist. The CLI **derives** that id from the label plus the file number, so the readable form the spec template writes is already addressable (a criterion that spells the full id is read the same way, never counted twice). A note amending a criterion the spec does not state **at all** is refused with `CONTRACT_ASSERTION_ABSENT`, and the exit is the spec stating it (`spec-refine`), never a second spelling of the id here.
 
+### Obligations — the two classes, and how each one is settled
+
+A note may leave work behind, and it declares **which of two classes** each piece is. A
+**compensation** is work this lineage owes: it holds the plan's closure shut until it is settled. A
+**handoff** is work somebody outside the run took on: it stays listed, it stays visible after the plan
+closes, and it blocks nothing — a run that cannot discharge it could never close. Nothing historical
+moves: the boxes and the phase states record what happened, and the obligation is new work of the
+effective contract.
+
+The class is the agent's to state while drafting the note, and the person sees it in the sealed
+preview before registering it; a new note leaving work without saying which class is refused. A note
+published before the class existed is read tolerantly — an undeclared obligation is a **compensation**
+unless the plan itself enumerates that exact work as a handoff — and every surface marks that as a
+reading somebody supplied, never as the note's own word. The class is revocable: the
+settlement boundary may declare a live compensation a handoff after all. So **when in doubt,
+compensation** — the only error a later boundary still catches.
+
+Settling one is publishing a note that **supersedes** the one carrying it without carrying it forward;
+there is no second ledger of discharged obligations: one recorded outside the chain
+could disagree with it. The closure does this by itself: between the last `batch-close` and
+the final validation the run declares, per compensation, whether it is done and with what evidence,
+and the CLI derives and publishes the settlement note. A compensation still pending leaves that
+boundary open with an executable action and costs the run no attempt. With **no** open run — a plan
+blocked today whose run closed long ago — the exit is `aw settle`: it lists what is owed, previews the
+note, and publishes it against an approval.
+
+**The split between scaffolding and content**, in three lines. A gap with a **single** reading is
+repaired by the run itself, and the repair is recorded. A gap with **more than one** reading is asked
+**once for all of them**, with the run's own reading offered as the recommendation. Everything else
+is **content**, and content is the person's.
+
 **Eligibility is closure, never size.** The composable exit opens only when the four close: the
 divergence stays in the **same functional lineage**; its **intent is settled**, so nothing further has
 to be elicited; its **transitive impact can be enumerated**, every consumer nameable; and its