@tacuchi/agent-workflow-cli 21.0.0 → 21.1.0

package/skills/w/schemas/capability-descriptor.schema.json

@@ -0,0 +1,260 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://workline.dev/schemas/capability-descriptor.schema.json",
+  "title": "Workline capability descriptor v1",
+  "description": "The cross-cutting contract an Agent Skill declares to become invocable by Workline. Not a design format and not part of the UI Design Package catalog: it says what a capability IS — operations, inputs, outputs, context, interaction, effects, floor, degradations, off policy and retirement — for any capability, design included.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "contract_version",
+    "name",
+    "purpose",
+    "exposure",
+    "default_operation",
+    "operations",
+    "floor",
+    "degradations",
+    "compatibility"
+  ],
+  "properties": {
+    "contract_version": {
+      "description": "Version of THIS contract, not of the skill. An unknown value stops validation before any field is read.",
+      "const": 1
+    },
+    "name": {
+      "description": "The capability's only public identity. There is no parallel role ID: the binding slot and the capability are one name.",
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"
+    },
+    "purpose": {
+      "description": "What the capability resolves, in one sentence. Discovery and generated help derive from here rather than restating it.",
+      "type": "string",
+      "minLength": 1
+    },
+    "exposure": {
+      "description": "Routes the capability opens. A skill declaring neither gets no Workline surface — installing a utility does not make it a capability.",
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": { "enum": ["direct", "compose"] }
+    },
+    "default_operation": {
+      "description": "Operation assumed when a caller names none. Null when every invocation must be explicit.",
+      "type": ["string", "null"],
+      "pattern": "^[a-z][a-z0-9_]*$"
+    },
+    "operations": {
+      "description": "The finite operation catalog. Anything outside it is refused, never improvised.",
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "name",
+          "summary",
+          "exposure",
+          "workspace",
+          "interaction",
+          "inputs",
+          "output",
+          "effects",
+          "off"
+        ],
+        "properties": {
+          "name": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9_]*$"
+          },
+          "summary": {
+            "type": "string",
+            "minLength": 1
+          },
+          "exposure": {
+            "description": "Routes this operation answers on. Always a subset of the capability's own exposure.",
+            "type": "array",
+            "minItems": 1,
+            "uniqueItems": true,
+            "items": { "enum": ["direct", "compose"] }
+          },
+          "workspace": {
+            "description": "Whether the operation needs a Workline workspace. Being outside one returns an explicit result and never initializes Workline implicitly.",
+            "enum": ["required", "optional", "standalone"]
+          },
+          "interaction": {
+            "description": "Whether one attempt is the whole conversation, or the operation may answer `needs_input` and continue.",
+            "enum": ["single_pass", "needs_input"]
+          },
+          "inputs": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["name", "kind", "required", "sensitivity", "schema"],
+              "properties": {
+                "name": {
+                  "type": "string",
+                  "pattern": "^[a-z][a-z0-9_]*$"
+                },
+                "kind": { "enum": ["text", "reference", "attachment", "selection"] },
+                "required": { "type": "boolean" },
+                "sensitivity": {
+                  "description": "Reading a sensitive source is never authorized by the invocation alone.",
+                  "enum": ["public", "sensitive"]
+                },
+                "schema": {
+                  "description": "Canonical format id when the input is schema-bearing, else null.",
+                  "type": ["string", "null"],
+                  "pattern": "^[a-z][a-z0-9.-]*/v[1-9][0-9]*$"
+                }
+              }
+            }
+          },
+          "output": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["kind", "schema", "completeness"],
+            "properties": {
+              "kind": {
+                "description": "A typed value, a durable reference, or both. Host prose is never the payload a flow consumes.",
+                "enum": ["value", "reference", "value_and_reference"]
+              },
+              "schema": {
+                "type": ["string", "null"],
+                "pattern": "^[a-z][a-z0-9.-]*/v[1-9][0-9]*$"
+              },
+              "completeness": {
+                "description": "Completeness values this operation may report. A dimension separate from the outcome: `completed` still requires the requested profile's completeness.",
+                "type": "array",
+                "minItems": 1,
+                "uniqueItems": true,
+                "items": { "enum": ["complete", "partial"] }
+              }
+            }
+          },
+          "effects": {
+            "description": "Every class of effect the operation may exercise. An undeclared effect is never exercised, so `read_only` is a declaration and not the absence of one.",
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["class", "idempotent", "authorization", "approval"],
+              "properties": {
+                "class": {
+                  "enum": [
+                    "read_only",
+                    "local_additive",
+                    "mutate_overwrite",
+                    "execute",
+                    "network_external",
+                    "destructive"
+                  ]
+                },
+                "idempotent": { "type": "boolean" },
+                "authorization": {
+                  "description": "Granted by the invocation itself, or by a preflight the human sees first.",
+                  "enum": ["invocation", "preflight"]
+                },
+                "approval": { "enum": ["none", "visible"] }
+              }
+            }
+          },
+          "off": {
+            "description": "What binding the capability `off` does to this operation. Never reverted by a host, a wrapper or a legacy name.",
+            "enum": ["blocked", "allowed"]
+          }
+        }
+      }
+    },
+    "floor": {
+      "description": "What runs with nothing installed. A capability a core gate needs carries its own implementation, so a missing external skill never blocks SPEC, PLAN or QUICK.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["builtin", "kind", "improvements"],
+      "properties": {
+        "builtin": { "type": "boolean" },
+        "kind": { "enum": ["core", "feature"] },
+        "improvements": {
+          "description": "`host_selected` means the host decides which compatible improvements contribute and in what order; Workline imposes no universal precedence.",
+          "enum": ["host_selected", "none"]
+        }
+      }
+    },
+    "degradations": {
+      "description": "The observable reasons a run may fall back, and what each one does. A cause not declared here is not a degradation, it is a failure.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["cause", "action"],
+        "properties": {
+          "cause": {
+            "enum": [
+              "opaque_selection",
+              "incompatible_improvement",
+              "invalid_binding",
+              "digest_changed"
+            ]
+          },
+          "action": { "enum": ["floor", "reject"] }
+        }
+      }
+    },
+    "compatibility": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "status",
+        "minimum_contract_version",
+        "improves",
+        "retired_names",
+        "retired_formats"
+      ],
+      "properties": {
+        "status": { "enum": ["active", "deprecated"] },
+        "minimum_contract_version": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "improves": {
+          "description": "What this descriptor improves, in its OWN words. Null when the descriptor IS the capability. Installed never implies compatible: the resolution verifies this claim against the capability being resolved before the improvement contributes or produces any effect.",
+          "type": ["object", "null"],
+          "additionalProperties": false,
+          "required": ["capability", "operations", "contract_version"],
+          "properties": {
+            "capability": {
+              "type": "string",
+              "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"
+            },
+            "operations": {
+              "type": "array",
+              "minItems": 1,
+              "items": {
+                "type": "string",
+                "pattern": "^[a-z][a-z0-9_]*$"
+              }
+            },
+            "contract_version": {
+              "type": "integer",
+              "minimum": 1
+            }
+          }
+        },
+        "retired_names": {
+          "description": "Names that are NOT aliases. A binding, invocation or descriptor using one fails with guidance to adopt the live name; it never resolves silently.",
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"
+          }
+        },
+        "retired_formats": {
+          "description": "Formats unsupported as a source: never read, imported, converted or migrated, and unable to satisfy a gate. The files themselves are left intact.",
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        }
+      }
+    }
+  }
+}

package/skills/w/schemas/design/design-render-bundle.v1.schema.json

@@ -0,0 +1,191 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://workline.dev/schemas/design/design-render-bundle.v1.schema.json",
+  "title": "Workline UI Design Package v1 — Render Context Bundle",
+  "description": "The single exchange payload every renderer and adapter receives. Deterministic for a baseline, a selection and an adapter profile: the digest is taken over canonical JSON without `digest` and without `generated`, so two equivalent runs seal the same bytes. It carries context, never authority — an integration transforms it over its own copy and the package stays untouched.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema",
+    "package",
+    "baseline",
+    "baseline_digest",
+    "adapter",
+    "roots",
+    "closure",
+    "assets",
+    "data_classification",
+    "accessibility",
+    "losses",
+    "digest",
+    "generated"
+  ],
+  "properties": {
+    "schema": {
+      "const": "workline.design-render-bundle/v1"
+    },
+    "package": {
+      "description": "The package this bundle was cut from.",
+      "type": "string",
+      "pattern": "^DES-(?:[0-9]{3}|[1-9][0-9]{3,})$"
+    },
+    "baseline": {
+      "description": "The published revision the selection was read at.",
+      "$ref": "#/$defs/revision"
+    },
+    "baseline_digest": {
+      "$ref": "#/$defs/digest"
+    },
+    "adapter": {
+      "description": "Which profile, at which version, this bundle was cut for. Determinism is a promise PER profile version: a profile that changes what it needs produces a different bundle.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["profile", "version"],
+      "properties": {
+        "profile": {
+          "type": "string",
+          "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
+        },
+        "version": {
+          "type": "integer",
+          "minimum": 1
+        }
+      }
+    },
+    "roots": {
+      "description": "The selection, sorted. A selection is a set, so the order it was typed in is not part of the bundle. An anchor is allowed here: a root may ask for one state.",
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": {
+        "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_-]*)?$"
+      }
+    },
+    "closure": {
+      "description": "Every revision the selection reaches, ordered by reference, with the content type and the digest of the bytes found on disk.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["ref", "kind", "path", "content_type", "sha256", "states"],
+        "properties": {
+          "ref": {
+            "description": "The revision, never anchored: the states demanded travel in `states`.",
+            "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}$"
+          },
+          "kind": {
+            "enum": ["flow", "screen", "rule", "token", "rendition"]
+          },
+          "path": {
+            "description": "Package-relative path. Never absolute and never escaping the package.",
+            "type": "string",
+            "minLength": 1
+          },
+          "content_type": {
+            "description": "Declared, not sniffed: a renderer decides how to read a member from this field.",
+            "type": "string",
+            "minLength": 1
+          },
+          "sha256": {
+            "$ref": "#/$defs/digest"
+          },
+          "states": {
+            "description": "State anchors the selection asked for. Empty means the whole revision.",
+            "type": "array",
+            "uniqueItems": true,
+            "items": {
+              "type": "string",
+              "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$"
+            }
+          }
+        }
+      }
+    },
+    "assets": {
+      "description": "The assets this bundle is allowed to hand over — only bytes the package custodies.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["digest", "path", "content_type"],
+        "properties": {
+          "digest": {
+            "$ref": "#/$defs/digest"
+          },
+          "path": {
+            "type": "string",
+            "pattern": "^assets/"
+          },
+          "content_type": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      }
+    },
+    "data_classification": {
+      "description": "How the material was prepared. `synthetic` is the default; `real` is an authorization somebody had to give.",
+      "enum": ["synthetic", "redacted", "real"]
+    },
+    "accessibility": {
+      "description": "The accessibility obligations the selected revisions state. A design states them; a rendition never discharges them.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["ref", "statement"],
+        "properties": {
+          "ref": {
+            "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_-]*)?$"
+          },
+          "statement": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      }
+    },
+    "losses": {
+      "description": "What this profile cannot represent, enumerated instead of omitted. A loss is part of the result, not a defect.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["subject", "why"],
+        "properties": {
+          "subject": {
+            "description": "What is lost: `capability:pull`, `section:localization`, `medium:motion`.",
+            "type": "string",
+            "minLength": 1
+          },
+          "why": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      }
+    },
+    "digest": {
+      "description": "Over canonical JSON of this object WITHOUT `digest` and WITHOUT `generated`. That exclusion is the determinism boundary made checkable.",
+      "$ref": "#/$defs/digest"
+    },
+    "generated": {
+      "description": "YYYY-MM-DD. Outside the seal: a date is not part of what was selected.",
+      "type": "string",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
+    }
+  },
+  "$defs": {
+    "revision": {
+      "type": "integer",
+      "minimum": 1
+    },
+    "digest": {
+      "type": "string",
+      "pattern": "^sha256:[0-9a-f]{64}$"
+    }
+  }
+}

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

@@ -0,0 +1,232 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://workline.dev/schemas/design/design-rendition.v1.schema.json",
+  "title": "Workline UI Design Package v1 — Design Rendition",
+  "description": "What a picture of a design knows about itself. Three separations never collapse here: fidelity is a property of the picture and never moves the screen's maturity; staleness against the source is DERIVED (`source_digest` is recomputable from the sources' bytes) while sync with the provider is a claim and lives inside `provider`; and a locator locates without ever identifying — it never replaces the Workline id, revision or digest, and never carries a credential.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema",
+    "id",
+    "revision",
+    "supersedes",
+    "purpose",
+    "medium",
+    "fidelity",
+    "tool",
+    "format",
+    "context",
+    "sources",
+    "source_digest",
+    "coverage",
+    "files",
+    "provider",
+    "access",
+    "interaction_evidence",
+    "data_classification"
+  ],
+  "properties": {
+    "schema": {
+      "const": "workline.design-rendition/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,})/VIS-(?:[0-9]{3}|[1-9][0-9]{3,})$"
+    },
+    "revision": {
+      "type": "integer",
+      "minimum": 1
+    },
+    "supersedes": {
+      "description": "An EARLIER revision of this same rendition, or null.",
+      "type": ["string", "null"],
+      "pattern": "^DES-(?:[0-9]{3}|[1-9][0-9]{3,})/VIS-(?:[0-9]{3}|[1-9][0-9]{3,})@r[1-9][0-9]{0,5}$"
+    },
+    "purpose": {
+      "type": "string",
+      "minLength": 1
+    },
+    "medium": {
+      "description": "What kind of artifact it is. Only `prototype` and `storyboard` can sustain interaction evidence — a still frame cannot show a transition.",
+      "enum": ["static_image", "document", "interactive_html", "prototype", "storyboard"]
+    },
+    "fidelity": {
+      "description": "How polished the PICTURE is. Deliberately not sharing vocabulary with maturity: raising fidelity never promotes a screen.",
+      "enum": ["low", "medium", "high"]
+    },
+    "tool": {
+      "description": "The tool that produced it, as a human would name it.",
+      "type": "string",
+      "minLength": 1
+    },
+    "format": {
+      "description": "Closed so it can be cross-checked against the file actually on disk.",
+      "enum": ["svg", "png", "jpeg", "webp", "pdf", "html"]
+    },
+    "context": {
+      "description": "The same design looks different depending on where it was rendered.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["platform", "viewport", "theme", "locale", "variants"],
+      "properties": {
+        "platform": {
+          "type": "string",
+          "minLength": 1
+        },
+        "viewport": {
+          "description": "`1280x800`, `390x844`, or a named breakpoint.",
+          "type": "string",
+          "minLength": 1
+        },
+        "theme": {
+          "type": "string",
+          "minLength": 1
+        },
+        "locale": {
+          "type": "string",
+          "minLength": 1
+        },
+        "variants": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      }
+    },
+    "sources": {
+      "description": "The exact revisions this rendition was produced from, with the bytes it saw. An anchor is meaningful here: a preview of one state is a preview of one state.",
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["ref", "sha256"],
+        "properties": {
+          "ref": {
+            "type": "string",
+            "pattern": "^DES-(?:[0-9]{3}|[1-9][0-9]{3,})/(?:FLW|SCR|RUL|TOK)-(?:[0-9]{3}|[1-9][0-9]{3,})@r[1-9][0-9]{0,5}(?:#[A-Za-z0-9][A-Za-z0-9_-]*)?$"
+          },
+          "sha256": {
+            "$ref": "#/$defs/digest"
+          }
+        }
+      }
+    },
+    "source_digest": {
+      "description": "One digest over the canonical list of `sources`. Recomputable from the package as it stands right now — that is what makes obsolescence detectable instead of asserted.",
+      "$ref": "#/$defs/digest"
+    },
+    "coverage": {
+      "description": "What this rendition demonstrates, in the screen's own vocabulary. The reverse direction of the screen's classification matrix; the handoff gate crosses the two.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["criteria", "states"],
+      "properties": {
+        "criteria": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "pattern": "^S\\d{3}/AC-(?:[A-Z]+-)?\\d+$"
+          }
+        },
+        "states": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$"
+          }
+        }
+      }
+    },
+    "files": {
+      "description": "The local evidence, relative to the rendition's OWN directory. Never empty: a rendition with no local file is exactly the evidence that disappears when the provider does.",
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["path", "sha256"],
+        "properties": {
+          "path": {
+            "description": "`preview.svg` — relative to this rendition's folder, never escaping it.",
+            "type": "string",
+            "minLength": 1
+          },
+          "sha256": {
+            "$ref": "#/$defs/digest"
+          }
+        }
+      }
+    },
+    "provider": {
+      "description": "The external object, when there is one. `sync` lives in here because it only means something once a provider copy exists.",
+      "type": ["object", "null"],
+      "additionalProperties": false,
+      "required": ["name", "locator", "version", "sync"],
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1
+        },
+        "locator": {
+          "description": "Provider-shaped keys (`file_key`, `node_id`, `project_id`, `artifact`, …). The key set is the adapter profile's business, not this schema's. Never a credential.",
+          "type": "object",
+          "minProperties": 1,
+          "additionalProperties": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "version": {
+          "description": "The provider's own version identity, or null when it has no stable one.",
+          "type": ["string", "null"],
+          "minLength": 1
+        },
+        "sync": {
+          "description": "A CLAIM about the provider's copy, not a derivation. `unknown` is the honest answer without consulting it.",
+          "enum": ["in_sync", "diverged", "unknown"]
+        }
+      }
+    },
+    "access": {
+      "description": "Who can reach the editable original, as a class. `local_only` is what keeps working when the provider does not.",
+      "enum": ["local_only", "public", "link_shared", "team", "private"]
+    },
+    "interaction_evidence": {
+      "description": "A trigger, a transition and an outcome — what a still frame cannot show. Null for a static rendition.",
+      "type": ["object", "null"],
+      "additionalProperties": false,
+      "required": ["trigger", "transition", "outcome"],
+      "properties": {
+        "trigger": {
+          "type": "string",
+          "minLength": 1
+        },
+        "transition": {
+          "type": "string",
+          "minLength": 1
+        },
+        "outcome": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "data_classification": {
+      "description": "How the material shown was prepared. `synthetic` is the default; `real` is an authorization somebody had to give.",
+      "enum": ["synthetic", "redacted", "real"]
+    }
+  },
+  "$defs": {
+    "digest": {
+      "type": "string",
+      "pattern": "^sha256:[0-9a-f]{64}$"
+    }
+  }
+}