@multileaf/ai-workflow 0.10.0 → 0.11.0

package/CHANGELOG.md

@@ -4,6 +4,17 @@ All notable changes to this project are documented in this file. The format foll
 
 ## [Unreleased]
 
+## [0.11.0] - 2026-10-31
+
+### Added
+
+- `aiw workflow abandon --reason=<why>` archives an obsolete active workflow: the session (with `status: abandoned` and the recorded reason) and the approval ledger move under `.aiw/checkpoints/`, the active slot is freed, and a new workflow can start immediately. Reason is required and audited.
+- Typed blocking reasons for workflow lifecycle: `workflow_still_active` (starting over an active workflow now names `aiw workflow complete` **or** `aiw workflow abandon --reason=...` as the way out — previously a prose-only dead end found during field testing), `workflow_not_active`, and `workflow_complete`.
+
+### Fixed
+
+- Release automation now actually releases: the Auto-tag workflow creates the version tag **and invokes the Release workflow directly** (reusable-workflow call). Previously the tag was created through the API with the default `GITHUB_TOKEN`, whose events do not trigger other workflows — so merging a version bump silently published nothing. This swallowed the v0.9.1 release (never published to npm) and delayed v0.10.0 until a manual tag re-push.
+
 ## [0.10.0] - 2026-10-30
 
 ### Added

package/dist/blocking-reasons.d.ts

@@ -7,7 +7,7 @@
  * command resolves the block it was printed for. See ADR-001 and
  * docs/opportunities/OPP-004-exact-continuation-commands.md.
  */
-export declare const BLOCKING_REASON_CODES: readonly ["gate_evidence_missing", "gate_incomplete", "stage_prerequisite_pending", "stage_prerequisite_unresolved", "stage_awaiting_approval", "stage_already_approved", "approval_evidence_missing", "approval_stale", "approval_gate_missing", "lane_escalation_required", "light_evidence_missing"];
+export declare const BLOCKING_REASON_CODES: readonly ["gate_evidence_missing", "gate_incomplete", "stage_prerequisite_pending", "stage_prerequisite_unresolved", "stage_awaiting_approval", "stage_already_approved", "approval_evidence_missing", "approval_stale", "approval_gate_missing", "lane_escalation_required", "light_evidence_missing", "workflow_still_active", "workflow_not_active", "workflow_complete"];
 export type BlockingReasonCode = (typeof BLOCKING_REASON_CODES)[number];
 /** How the user or agent gets past a block. Exactly one of three kinds. */
 export type BlockingContinuation = 

package/dist/blocking-reasons.js

@@ -19,6 +19,9 @@ export const BLOCKING_REASON_CODES = [
     "approval_gate_missing",
     "lane_escalation_required",
     "light_evidence_missing",
+    "workflow_still_active",
+    "workflow_not_active",
+    "workflow_complete",
 ];
 function command(commandText) {
     return { kind: "command", command: commandText };
@@ -112,6 +115,21 @@ export const BLOCKING_REASON_INVENTORY = {
         description: "A light-lane workflow cannot complete without at least one recorded validation entry.",
         continuation: () => action("Run `aiw task evidence --validation=<command and result>` at least once, then `aiw workflow complete`."),
     },
+    workflow_still_active: {
+        code: "workflow_still_active",
+        description: "A workflow is already active; finish or archive it before starting another.",
+        continuation: () => action("Run `aiw workflow complete` once every stage resolves, or archive an obsolete one with `aiw workflow abandon --reason=<why>`."),
+    },
+    workflow_not_active: {
+        code: "workflow_not_active",
+        description: "No SDD workflow is active for this command to operate on.",
+        continuation: () => command("aiw workflow start"),
+    },
+    workflow_complete: {
+        code: "workflow_complete",
+        description: "This workflow is already complete; start a new workflow to continue working.",
+        continuation: () => command("aiw workflow start"),
+    },
 };
 export function getBlockingReasonDefinition(code) {
     const definition = BLOCKING_REASON_INVENTORY[code];

package/dist/human-approval.d.ts

@@ -20,7 +20,7 @@ export type ApprovalLedger = {
 export type WorkflowSession = {
     schema: 1;
     workflowId: string;
-    status: "active" | "complete";
+    status: "active" | "complete" | "abandoned";
     startedAt: string;
     updatedAt: string;
     ticket?: string;
@@ -32,6 +32,8 @@ export type WorkflowSession = {
     /** Presence means the workflow escalated to the full lane (effective lane: full). */
     laneEscalatedAt?: string;
     laneEscalationReason?: string;
+    /** Set when the workflow is archived via `aiw workflow abandon`. */
+    abandonedReason?: string;
 };
 /** The lane that currently governs stage commands: escalation moves light → full. */
 export declare function effectiveLane(session: WorkflowSession): "full" | "light";

package/dist/human-approval.js

@@ -42,6 +42,7 @@ const SESSION_KEYS = new Set([
     "laneReason",
     "laneEscalatedAt",
     "laneEscalationReason",
+    "abandonedReason",
 ]);
 export function createApprovalLedger(workflowId, options = {}) {
     assertWorkflowId(workflowId);
@@ -72,8 +73,8 @@ export function parseWorkflowSession(content) {
             throw new Error(`Workflow session has unknown field: ${key}.`);
     if (typeof value.workflowId !== "string")
         throw new Error("Workflow session requires a workflowId.");
-    if (value.status !== "active" && value.status !== "complete")
-        throw new Error("Workflow session status must be active or complete.");
+    if (value.status !== "active" && value.status !== "complete" && value.status !== "abandoned")
+        throw new Error("Workflow session status must be active, complete, or abandoned.");
     if (typeof value.startedAt !== "string" || typeof value.updatedAt !== "string")
         throw new Error("Workflow session requires start and update timestamps.");
     if (value.ticket !== undefined && typeof value.ticket !== "string")
@@ -96,6 +97,9 @@ export function parseWorkflowSession(content) {
     const laneEscalationReason = value.laneEscalationReason;
     if (laneEscalationReason !== undefined && typeof laneEscalationReason !== "string")
         throw new Error("Workflow session lane escalation reason must be a string.");
+    const abandonedReason = value.abandonedReason;
+    if (abandonedReason !== undefined && typeof abandonedReason !== "string")
+        throw new Error("Workflow session abandonment reason must be a string.");
     const session = {
         schema: 1,
         workflowId: value.workflowId,
@@ -108,6 +112,7 @@ export function parseWorkflowSession(content) {
         ...(laneReason === undefined ? {} : { laneReason }),
         ...(laneEscalatedAt === undefined ? {} : { laneEscalatedAt }),
         ...(laneEscalationReason === undefined ? {} : { laneEscalationReason }),
+        ...(abandonedReason === undefined ? {} : { abandonedReason }),
     };
     validateWorkflowSession(session);
     return session;
@@ -266,8 +271,10 @@ function validateWorkflowSession(session) {
     if (session.schema !== 1)
         throw new Error("Workflow session schema must be version 1.");
     assertWorkflowId(session.workflowId);
-    if (session.status !== "active" && session.status !== "complete")
-        throw new Error("Workflow session status must be active or complete.");
+    if (session.status !== "active" &&
+        session.status !== "complete" &&
+        session.status !== "abandoned")
+        throw new Error("Workflow session status must be active, complete, or abandoned.");
     assertTimestamp(session.startedAt);
     assertTimestamp(session.updatedAt);
     if (session.lane !== undefined && session.lane !== "light")
@@ -281,6 +288,8 @@ function validateWorkflowSession(session) {
         if (!session.laneEscalationReason)
             throw new Error("Lane escalation requires a reason.");
     }
+    if (session.status === "abandoned" && !session.abandonedReason)
+        throw new Error("Abandoned sessions require an abandonment reason.");
 }
 function withStage(ledger, stage, record) {
     return {

package/dist/workflow.js

@@ -79,10 +79,9 @@ function beginWorkflowSession(fs, aiw, options) {
     if (fs.exists(sessionPath)) {
         const previous = parseWorkflowSession(fs.read(sessionPath));
         if (previous.status === "active")
-            return {
-                exitCode: 1,
-                error: `Workflow ${previous.workflowId} is still active. Complete it before starting another.`,
-            };
+            throw new BlockingError(describeBlockingReason("workflow_still_active", {
+                detail: `Workflow ${previous.workflowId} is still active. Complete it before starting another.`,
+            }));
         if (!fs.exists(ledgerPath))
             return { exitCode: 1, error: "Completed workflow is missing its approval ledger." };
         const archive = join(aiw, `checkpoints/workflow-${previous.workflowId}-approvals.yml`);
@@ -307,7 +306,7 @@ export async function runCommand(args, root, fs, services = {}) {
             const action = args[1];
             const sessionPath = join(aiw, "workflow.yml");
             if (action === "start") {
-                const options = parseNamedOptions(args.slice(2), ["id"]);
+                const options = parseNamedOptions(args.slice(2).filter((argument) => argument !== "--json"), ["id"]);
                 if (!options)
                     return { exitCode: 1, error: "Usage: aiw workflow start [--id=workflow-id]" };
                 return beginWorkflowSession(fs, aiw, { id: options.id });
@@ -322,6 +321,46 @@ export async function runCommand(args, root, fs, services = {}) {
                     output: `Workflow ${session.workflowId} (${session.status})\n${stages.join("\n")}\n${workflowNextAction(ledger)}`,
                 };
             }
+            if (action === "abandon") {
+                const options = parseNamedOptions(args.slice(2), ["reason"]);
+                if (!options?.reason)
+                    return { exitCode: 1, error: "Usage: aiw workflow abandon --reason=why-obsolete" };
+                if (options.reason.length > 500 || /[\r\n]/.test(options.reason))
+                    return {
+                        exitCode: 1,
+                        error: "--reason must be a single line of at most 500 bytes.",
+                    };
+                if (!fs.exists(sessionPath))
+                    return {
+                        exitCode: 1,
+                        error: "No SDD workflow is active; start one with `aiw workflow start` or `aiw task start --ticket=TEAM-123`. [reason: workflow_not_active] Terminal: no automatic continuation beyond starting a workflow.",
+                    };
+                const { session } = readActiveWorkflow(aiw, fs);
+                const ledgerPath = join(aiw, "approvals.yml");
+                const sessionArchive = join(aiw, "checkpoints", `workflow-${session.workflowId}-session.yml`);
+                const ledgerArchive = join(aiw, "checkpoints", `workflow-${session.workflowId}-approvals.yml`);
+                fs.mkdir(join(aiw, "checkpoints"));
+                const now = new Date().toISOString();
+                const archivedSession = {
+                    ...session,
+                    status: "abandoned",
+                    abandonedReason: options.reason,
+                    updatedAt: now,
+                };
+                fs.write(sessionArchive, serializeWorkflowSession(archivedSession));
+                if (fs.exists(ledgerPath))
+                    fs.write(ledgerArchive, fs.read(ledgerPath));
+                fs.remove?.(sessionPath);
+                if (fs.exists(ledgerPath))
+                    fs.remove?.(ledgerPath);
+                return {
+                    exitCode: 0,
+                    output: `Workflow ${session.workflowId} abandoned (${options.reason}).\n` +
+                        `Session archived: ${sessionArchive}\n` +
+                        (fs.exists(ledgerArchive) ? `Approval ledger archived: ${ledgerArchive}\n` : "") +
+                        "Start a new one when ready.",
+                };
+            }
             if (action === "complete") {
                 const { session, ledger } = readActiveWorkflow(aiw, fs);
                 if (effectiveLane(session) === "light") {
@@ -2704,7 +2743,9 @@ function readWorkflowState(aiw, fs, requireActive = true) {
     if (session.workflowId !== ledger.workflowId)
         throw new Error("Workflow session and approval ledger IDs do not match; run doctor.");
     if (requireActive && session.status !== "active")
-        throw new Error(`Workflow ${session.workflowId} is complete; start a new workflow first.`);
+        throw new BlockingError(describeBlockingReason("workflow_complete", {
+            detail: `Workflow ${session.workflowId} is complete; start a new workflow first.`,
+        }));
     const changed = APPROVAL_STAGES.find((stage) => {
         const record = ledger.stages[stage];
         if (!record?.artifactHash || !["pending-human", "approved"].includes(record.status))

package/docs/architecture.md

@@ -45,7 +45,7 @@ Project analysis is hybrid: deterministic detectors establish observable facts,
 
 ## Human workflow approvals
 
-Workflows run in one of two lanes. The **full lane** (default, and the only non-interactive default) is the staged approval sequence below. The **light lane** (`aiw task start --lane=light --lane-reason=...`, human-chosen via the resume test — work is small when it could be resumed from the request plus `git diff`) skips durable spec/plan artifacts: validation evidence is recorded per entry (`aiw task evidence`), completion requires at least one entry, and the lane plus rationale are written into the session and approval ledger for audit. Stage commands in the light lane block with a `lane_escalation_required` reason until `aiw task escalate --reason=...` moves the workflow to the full lane; recorded evidence is preserved and linked. Escalation is one-way; the full lane then runs the complete approval sequence.
+Workflows run in one of two lanes. The **full lane** (default, and the only non-interactive default) is the staged approval sequence below. The **light lane** (`aiw task start --lane=light --lane-reason=...`, human-chosen via the resume test — work is small when it could be resumed from the request plus `git diff`) skips durable spec/plan artifacts: validation evidence is recorded per entry (`aiw task evidence`), completion requires at least one entry, and the lane plus rationale are written into the session and approval ledger for audit. Stage commands in the light lane block with a `lane_escalation_required` reason until `aiw task escalate --reason=...` moves the workflow to the full lane; recorded evidence is preserved and linked. Escalation is one-way; the full lane then runs the complete approval sequence. An obsolete active workflow is archived with `aiw workflow abandon --reason=...`: session and ledger move under `.aiw/checkpoints/` with `status: abandoned`, freeing the active slot.
 
 ## Current flow
 

package/docs/continuation-inventory.md

@@ -19,3 +19,6 @@ Every blocking `aiw` exit carries a stable reason code plus either an exact runn
 | `approval_gate_missing`         | No passing quality gate is recorded for this stage; gate it before approving.                 | runnable command |
 | `lane_escalation_required`      | Light-lane workflows do not author stage artifacts; escalate to the full lane to continue.    | explicit action  |
 | `light_evidence_missing`        | A light-lane workflow cannot complete without at least one recorded validation entry.         | explicit action  |
+| `workflow_still_active`         | A workflow is already active; finish or archive it before starting another.                   | explicit action  |
+| `workflow_not_active`           | No SDD workflow is active for this command to operate on.                                     | runnable command |
+| `workflow_complete`             | This workflow is already complete; start a new workflow to continue working.                  | runnable command |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@multileaf/ai-workflow",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Portable spec-driven development workflow for AI coding agents",
   "license": "MIT",
   "repository": {