@tacuchi/agent-workflow-cli 20.25.0 → 21.0.0

package/skills/w/schemas/design/design-review.v1.schema.json

@@ -0,0 +1,72 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://workline.dev/schemas/design-review.v1.schema.json",
+  "title": "Workline design review record v1",
+  "description": "An external review of one exact baseline revision. It lives OUTSIDE the baseline it reviews, so no digest is self-referential, and it never grants anything to a later revision.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema",
+    "id",
+    "target",
+    "target_digest",
+    "author",
+    "date",
+    "decision",
+    "evidence",
+    "digest"
+  ],
+  "properties": {
+    "schema": {
+      "const": "workline.design-review/v1"
+    },
+    "id": {
+      "type": "string",
+      "pattern": "^REV-(?:[0-9]{3}|[1-9][0-9]{3,})$"
+    },
+    "target": {
+      "description": "The exact baseline this record decides on.",
+      "$ref": "#/$defs/baselineRef"
+    },
+    "target_digest": {
+      "description": "The digest that baseline had. A record decides on BYTES, not on a name.",
+      "$ref": "#/$defs/digest"
+    },
+    "author": {
+      "description": "Who decided, or the role that did.",
+      "type": "string",
+      "minLength": 1
+    },
+    "date": {
+      "type": "string",
+      "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$"
+    },
+    "decision": {
+      "description": "`proposed` is the state a baseline is born in; only `approved` grants anything.",
+      "enum": ["proposed", "approved", "rejected"]
+    },
+    "evidence": {
+      "description": "Optional: where the decision was taken. Never a substitute for the decision.",
+      "type": "array",
+      "uniqueItems": true,
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "digest": {
+      "description": "SHA-256 of this record's canonical JSON WITHOUT this field.",
+      "$ref": "#/$defs/digest"
+    }
+  },
+  "$defs": {
+    "baselineRef": {
+      "type": "string",
+      "pattern": "^DES-(?:[0-9]{3}|[1-9][0-9]{3,})@r[1-9][0-9]{0,5}$"
+    },
+    "digest": {
+      "type": "string",
+      "pattern": "^sha256:[0-9a-f]{64}$"
+    }
+  }
+}

package/skills/w/schemas/design/design-revocation.v1.schema.json

@@ -0,0 +1,54 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://workline.dev/schemas/design-revocation.v1.schema.json",
+  "title": "Workline design revocation record v1",
+  "description": "An explicit, audited block on one exact baseline revision. The ONLY thing that forbids executing against a published revision.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "id", "target", "target_digest", "author", "date", "reason", "digest"],
+  "properties": {
+    "schema": {
+      "const": "workline.design-revocation/v1"
+    },
+    "id": {
+      "type": "string",
+      "pattern": "^RVK-(?:[0-9]{3}|[1-9][0-9]{3,})$"
+    },
+    "target": {
+      "description": "The exact baseline this record decides on.",
+      "$ref": "#/$defs/baselineRef"
+    },
+    "target_digest": {
+      "description": "The digest that baseline had. A record decides on BYTES, not on a name.",
+      "$ref": "#/$defs/digest"
+    },
+    "author": {
+      "description": "Who decided, or the role that did.",
+      "type": "string",
+      "minLength": 1
+    },
+    "date": {
+      "type": "string",
+      "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$"
+    },
+    "reason": {
+      "description": "Why this revision must not be executed. Not optional: a block without a reason is not auditable.",
+      "type": "string",
+      "minLength": 1
+    },
+    "digest": {
+      "description": "SHA-256 of this record's canonical JSON WITHOUT this field.",
+      "$ref": "#/$defs/digest"
+    }
+  },
+  "$defs": {
+    "baselineRef": {
+      "type": "string",
+      "pattern": "^DES-(?:[0-9]{3}|[1-9][0-9]{3,})@r[1-9][0-9]{0,5}$"
+    },
+    "digest": {
+      "type": "string",
+      "pattern": "^sha256:[0-9a-f]{64}$"
+    }
+  }
+}

package/skills/w/schemas/design/ui-flow.v1.schema.json

@@ -0,0 +1,211 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://workline.dev/schemas/design/ui-flow.v1.schema.json",
+  "title": "Workline UI Design Package v1 — Flow Specification frontmatter",
+  "description": "Machine-readable half of a User Flow / Task Flow. Identity, graph, dependencies and traceability resolve from here alone: nothing normative may require reading the Markdown body.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema",
+    "id",
+    "revision",
+    "maturity",
+    "supersedes",
+    "purpose",
+    "platform",
+    "actors",
+    "entry",
+    "nodes",
+    "edges",
+    "dependencies",
+    "trace",
+    "unknowns",
+    "not_applicable",
+    "external"
+  ],
+  "properties": {
+    "schema": {
+      "const": "workline.ui-flow/v1"
+    },
+    "id": {
+      "description": "Qualified identity WITHOUT the revision — the revision is its own field.",
+      "type": "string",
+      "pattern": "^DES-(?:[0-9]{3}|[1-9][0-9]{3,})/FLW-(?:[0-9]{3}|[1-9][0-9]{3,})$"
+    },
+    "revision": {
+      "$ref": "#/$defs/revision"
+    },
+    "maturity": {
+      "$ref": "#/$defs/maturity"
+    },
+    "supersedes": {
+      "description": "An EARLIER revision of this same flow, or null. Currentness is derived from it.",
+      "type": ["string", "null"],
+      "pattern": "^DES-(?:[0-9]{3}|[1-9][0-9]{3,})/FLW-(?:[0-9]{3}|[1-9][0-9]{3,})@r[1-9][0-9]{0,5}$"
+    },
+    "purpose": {
+      "type": "string",
+      "minLength": 1
+    },
+    "platform": {
+      "type": "string",
+      "minLength": 1
+    },
+    "actors": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "uniqueItems": true
+    },
+    "entry": {
+      "description": "The screen STATE the flow starts at. Must also appear in `nodes`.",
+      "$ref": "#/$defs/stateRef"
+    },
+    "nodes": {
+      "description": "Every screen state the flow visits, by exact reference.",
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/stateRef"
+      },
+      "uniqueItems": true
+    },
+    "edges": {
+      "description": "Transitions. Both endpoints must be declared nodes, so the graph closes on itself.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["from", "trigger", "action", "condition", "to"],
+        "properties": {
+          "from": {
+            "$ref": "#/$defs/stateRef"
+          },
+          "trigger": {
+            "type": "string",
+            "minLength": 1
+          },
+          "action": {
+            "type": ["string", "null"],
+            "minLength": 1
+          },
+          "condition": {
+            "type": ["string", "null"],
+            "minLength": 1
+          },
+          "to": {
+            "$ref": "#/$defs/stateRef"
+          }
+        }
+      }
+    },
+    "dependencies": {
+      "description": "Rules and tokens the flow itself depends on, by exact reference.",
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/artifactRef"
+      },
+      "uniqueItems": true
+    },
+    "trace": {
+      "$ref": "#/$defs/trace"
+    },
+    "unknowns": {
+      "$ref": "#/$defs/unknowns"
+    },
+    "not_applicable": {
+      "$ref": "#/$defs/notApplicable"
+    },
+    "external": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": {
+        "$ref": "#/$defs/externalDesignSystem"
+      }
+    }
+  },
+  "$defs": {
+    "revision": {
+      "type": "integer",
+      "minimum": 1
+    },
+    "maturity": {
+      "enum": ["outline", "handoff"]
+    },
+    "artifactRef": {
+      "type": "string",
+      "pattern": "^DES-(?:[0-9]{3}|[1-9][0-9]{3,})/(?:FLW|SCR|RUL|TOK|VIS)-(?:[0-9]{3}|[1-9][0-9]{3,})@r[1-9][0-9]{0,5}(#[A-Za-z0-9][A-Za-z0-9_-]*)?$"
+    },
+    "stateRef": {
+      "description": "A screen state: `DES-001/SCR-002@r2#empty`. The anchor is required.",
+      "type": "string",
+      "pattern": "^DES-(?:[0-9]{3}|[1-9][0-9]{3,})/SCR-(?:[0-9]{3}|[1-9][0-9]{3,})@r[1-9][0-9]{0,5}#[A-Za-z0-9][A-Za-z0-9_-]*$"
+    },
+    "trace": {
+      "description": "Acceptance criteria this artifact answers to. Emptiness is the maturity profile's business, not this schema's.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["criterion", "source"],
+        "properties": {
+          "criterion": {
+            "type": "string",
+            "minLength": 1
+          },
+          "source": {
+            "type": ["string", "null"],
+            "minLength": 1
+          }
+        }
+      }
+    },
+    "unknowns": {
+      "description": "Open questions, explicit. `blocking: true` is what a handoff gate refuses.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["question", "blocking"],
+        "properties": {
+          "question": {
+            "type": "string",
+            "minLength": 1
+          },
+          "blocking": {
+            "type": "boolean"
+          }
+        }
+      }
+    },
+    "notApplicable": {
+      "description": "Conditional section → reason. Only conditional sections may appear, and a reason is never empty. Essential sections cannot be waived at all.",
+      "type": "object",
+      "additionalProperties": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "externalDesignSystem": {
+      "description": "Where foreign rules, tokens or assets came from. A `handoff` that depends on someone else's design system pins it and keeps the subset locally (AC-PKG-09).",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["provider", "revision", "digest"],
+      "properties": {
+        "provider": {
+          "type": "string",
+          "pattern": "^DES-(?:[0-9]{3}|[1-9][0-9]{3,})$"
+        },
+        "revision": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "digest": {
+          "type": "string",
+          "pattern": "^sha256:[0-9a-f]{64}$"
+        }
+      }
+    }
+  }
+}

package/skills/w/schemas/design/ui-screen.v1.schema.json

@@ -0,0 +1,214 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://workline.dev/schemas/design/ui-screen.v1.schema.json",
+  "title": "Workline UI Design Package v1 — Screen Specification frontmatter",
+  "description": "Machine-readable half of a Screen Specification. Identity, states, dependencies and traceability resolve from here alone: nothing normative may require reading the Markdown body.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema",
+    "id",
+    "revision",
+    "maturity",
+    "supersedes",
+    "title",
+    "purpose",
+    "platform",
+    "default_state",
+    "states",
+    "flow_refs",
+    "dependencies",
+    "trace",
+    "unknowns",
+    "not_applicable",
+    "external"
+  ],
+  "properties": {
+    "schema": {
+      "const": "workline.ui-screen/v1"
+    },
+    "id": {
+      "description": "Qualified identity WITHOUT the revision — the revision is its own field.",
+      "type": "string",
+      "pattern": "^DES-(?:[0-9]{3}|[1-9][0-9]{3,})/SCR-(?:[0-9]{3}|[1-9][0-9]{3,})$"
+    },
+    "revision": {
+      "$ref": "#/$defs/revision"
+    },
+    "maturity": {
+      "$ref": "#/$defs/maturity"
+    },
+    "supersedes": {
+      "description": "An EARLIER revision of this same screen, or null. Currentness is derived from it.",
+      "type": ["string", "null"],
+      "pattern": "^DES-(?:[0-9]{3}|[1-9][0-9]{3,})/SCR-(?:[0-9]{3}|[1-9][0-9]{3,})@r[1-9][0-9]{0,5}$"
+    },
+    "title": {
+      "type": "string",
+      "minLength": 1
+    },
+    "purpose": {
+      "type": "string",
+      "minLength": 1
+    },
+    "platform": {
+      "type": "string",
+      "minLength": 1
+    },
+    "default_state": {
+      "description": "Anchor of the base state. Must be one of the declared `states`.",
+      "type": "string",
+      "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$"
+    },
+    "states": {
+      "description": "Observable states. The anchor is what flows, tasks and renditions address, so it is unique WITHIN this revision.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["anchor", "purpose"],
+        "properties": {
+          "anchor": {
+            "type": "string",
+            "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$"
+          },
+          "purpose": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      }
+    },
+    "flow_refs": {
+      "description": "Flows this screen participates in, by exact reference.",
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^DES-(?:[0-9]{3}|[1-9][0-9]{3,})/FLW-(?:[0-9]{3}|[1-9][0-9]{3,})@r[1-9][0-9]{0,5}$"
+      },
+      "uniqueItems": true
+    },
+    "dependencies": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["rules", "tokens", "assets"],
+      "properties": {
+        "rules": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^DES-(?:[0-9]{3}|[1-9][0-9]{3,})/RUL-(?:[0-9]{3}|[1-9][0-9]{3,})@r[1-9][0-9]{0,5}$"
+          },
+          "uniqueItems": true
+        },
+        "tokens": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^DES-(?:[0-9]{3}|[1-9][0-9]{3,})/TOK-(?:[0-9]{3}|[1-9][0-9]{3,})@r[1-9][0-9]{0,5}$"
+          },
+          "uniqueItems": true
+        },
+        "assets": {
+          "description": "Content-addressed: an asset is depended on by digest, never by name.",
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^sha256:[0-9a-f]{64}$"
+          },
+          "uniqueItems": true
+        }
+      }
+    },
+    "trace": {
+      "$ref": "#/$defs/trace"
+    },
+    "unknowns": {
+      "$ref": "#/$defs/unknowns"
+    },
+    "not_applicable": {
+      "$ref": "#/$defs/notApplicable"
+    },
+    "external": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": {
+        "$ref": "#/$defs/externalDesignSystem"
+      }
+    }
+  },
+  "$defs": {
+    "revision": {
+      "type": "integer",
+      "minimum": 1
+    },
+    "maturity": {
+      "enum": ["outline", "handoff"]
+    },
+    "trace": {
+      "description": "Acceptance criteria this artifact answers to. Emptiness is the maturity profile's business, not this schema's.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["criterion", "source"],
+        "properties": {
+          "criterion": {
+            "type": "string",
+            "minLength": 1
+          },
+          "source": {
+            "type": ["string", "null"],
+            "minLength": 1
+          }
+        }
+      }
+    },
+    "unknowns": {
+      "description": "Open questions, explicit. `blocking: true` is what a handoff gate refuses.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["question", "blocking"],
+        "properties": {
+          "question": {
+            "type": "string",
+            "minLength": 1
+          },
+          "blocking": {
+            "type": "boolean"
+          }
+        }
+      }
+    },
+    "notApplicable": {
+      "description": "Conditional section → reason. Only conditional sections may appear, and a reason is never empty. Essential sections cannot be waived at all.",
+      "type": "object",
+      "additionalProperties": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "externalDesignSystem": {
+      "description": "Where foreign rules, tokens or assets came from. A `handoff` that depends on someone else's design system pins it and keeps the subset locally (AC-PKG-09).",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["provider", "revision", "digest"],
+      "properties": {
+        "provider": {
+          "type": "string",
+          "pattern": "^DES-(?:[0-9]{3}|[1-9][0-9]{3,})$"
+        },
+        "revision": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "digest": {
+          "type": "string",
+          "pattern": "^sha256:[0-9a-f]{64}$"
+        }
+      }
+    }
+  }
+}

package/skills/w/artifacts/artifacts-design/SPEC.md

@@ -1,42 +0,0 @@
-# NNN-SPEC-<SLUG>.md — design SPEC (UI)
-
-> What it is: the **design specification of ONE screen** (modal, dashboard, form, …), produced by composing the **`ui-design`** capability (built-in default [`ui-spec`](../../roles/ui-spec/ROLE.md)) when the **plan includes UI**. It is a **session artifact** of the PLAN loops (`plan-new-loop` · `plan-refine-loop`) — process-facing, internal — and `plan-exec-loop` reads it as the **design reference** when implementing the UI tasks.
->
-> **It is NOT the spec.** The requirement-spec (`docs/specs/NNN-spec-<slug>.md`) and the plan remain **documents** (invariant 3). The design SPEC is a different thing: the per-screen UI design detail, ephemeral and process-facing, living inside the session. Spelling disambiguates: `SPEC` (UPPERCASE, artifact) vs `spec` (lowercase, document).
-
-## Naming
-
-`NNN-SPEC-<SLUG>.md`, all UPPERCASE (session-artifact convention):
-
-- `NNN` — sequence **local to the session** (001, 002, … in creation order). Numbered by **the loop**; the CLI is not involved (do not confuse with the global session `NNN` from `aw session-create`, nor with `aw next-number` for `docs/`).
-- `SLUG` — short screen name in UPPER-KEBAB (`[A-Z0-9-]`, ≤ ~4 words).
-- **One screen per file.** Several screens = several SPECs.
-
-Examples: `001-SPEC-MODAL-EXPORT.md` · `002-SPEC-ADMIN-DASHBOARD.md`.
-
-## Schema
-
-Trace header (blockquote) + the [`ui-spec`](../../roles/ui-spec/ROLE.md) Markdown render (same structure, vocabulary and exact render rules; **a single screen**):
-
-```markdown
-> Design SPEC · generated via the ui-design capability
-> Origin: docs/plans/PPP-plan-<slug>.md (· docs/specs/NNN-spec-<slug>.md § UI spec, if present)
-> Design options: material3 · light · es
-> Tasks: T3.2 · T3.3
-
-# Modal Export
-**Tipo**: modal | **Plataforma**: web
-
-## Componentes
-- **Formato** (select)
-- **Rango de fechas** (datePicker)
-- **Exportar** (button)
-- **Cancelar** (link)
-```
-
-## Rules
-
-1. Authored by the **`ui-design`** capability (rebindable via `.workflow/skills.toml`; `off` → the UI gap degrades to human / `Open questions`, like any disabled capability).
-2. The **plan-doc references** the path of the governing SPEC (in its UI Tasks / `Solution`): that reference is the **source of truth** for which SPEC governs each screen. A re-refine that changes a screen produces the updated SPEC **in its own session** (each loop manages the artifacts of ITS session) and re-points the plan reference.
-3. **Derives** from the spec's `## UI spec` section when present: splits it per screen and elevates it to executable detail; a SPEC↔`## UI spec` contradiction is a **gap** (plan↔spec drift). If the spec has no `## UI spec`, it is authored from the `Requirement` via structured-choice (design system, theme, screen ambiguities).
-4. Ephemeral and internal like every artifact: promotion to `docs/` happens **only** via `export-*` (never automatically by the loop).

package/skills/w/modules/PLAN-DESIGN-SPECS.md

@@ -1,12 +0,0 @@
-# PLAN-DESIGN-SPECS — per-screen design SPECs when the plan includes UI
-
-Loaded when the plan includes UI (signal `ui`).
-
-## Delta 4 — Design SPECs (when the plan includes UI)
-
-The **UI without design SPEC** gap is resolved by **composing** the **`ui-design`** capability (built-in default [`ui-spec`](../roles/ui-spec/ROLE.md); rebindable via `.workflow/skills.toml`; `off` → degrades to human / `Open questions`):
-
-- It authors **one design SPEC per screen** as a session artifact: `NNN-SPEC-<SLUG>.md` (numbering local to the session — see [`SPEC.md`](../artifacts/artifacts-design/SPEC.md)).
-- It **derives** from the spec's `## UI spec` section when present (splits it per screen and raises it to executable detail); otherwise it authors from the `Requirement` (design system/theme/ambiguities via *structured-choice*, counts in the batch).
-- The plan's **UI Tasks reference** their SPEC's path — that reference is the **source of truth** — and `plan-exec-loop` reads them as the design reference.
-- It is the chassis' composed-capability resolution mode (next to *research*, *probe* and *human*).

package/skills/w/modules/PLAN-REFINE-DESIGN-SPECS.md

@@ -1,7 +0,0 @@
-# PLAN-REFINE-DESIGN-SPECS — design SPECs for the screens a refine touches
-
-Loaded when the refine touches UI (signal `ui`).
-
-## Delta 4 — Design SPECs (when the refine touches UI)
-
-Same mechanism as [`plan-new-loop`](../loops/plan-new-loop/LOOP.md) (§ *Delta 4*: the **`ui-design`** capability → per-screen `NNN-SPEC-<SLUG>.md`, see [`SPEC.md`](../artifacts/artifacts-design/SPEC.md)), **scoped to the delta**: only the screens **new or changed** by the refine get a design SPEC. The updated SPEC is written in **plan-refine's own session** (each loop manages ITS session's artifacts — it never edits plan-new's) and the plan **re-points** the UI Task reference to the current SPEC. Untouched screens keep their original SPEC.