@tacuchi/agent-workflow-cli 21.0.0 → 21.3.0

package/skills/w/modules/PLAN-EXECUTION-BATCHES.md

@@ -26,27 +26,19 @@ The phase contracts, dependencies, risks and open questions are the reproducible
 
 ## Inference
 
-Choose the maximal consecutive `continuous` ranges. A range is eligible only when all of these
-are true:
+Choose the maximal consecutive `continuous` ranges: a range stays eligible while nothing observable
+breaks it. Anything else is `isolated`; if every phase is eligible, the whole plan is one batch.
 
-1. Every dependency is already satisfied or is an earlier phase in the same range.
-2. No phase result, proof, probe or human decision determines how a later phase must be built.
-3. There is no unresolved question, live blocker, operative handoff or irreversible external
-   action between its phases.
-4. No intermediate commit, release, review or deployment is a required recovery boundary.
-5. The combined change is coherent, recoverable and reviewable as one unit.
+> **Which facts break eligibility, and what one of them costs, is not this document's call:** the deterministic steps below are decided by the CLI (`aw flow advance`), not by this document. It emits the closed vocabulary of those facts at the boundary that asks for them.
 
-Anything else is `isolated`. If every phase is eligible, the whole plan is one batch. This is an
-AI inference from observable facts, not a preference question; planning writes it without asking.
-The PLAN gate fails when a phase is missing, duplicated, reordered or grouped across an
-ineligible boundary.
+This is an inference from observable facts, not a preference question. The PLAN gate fails when a
+phase is missing, duplicated, reordered or grouped across an ineligible boundary.
 
 ## Runtime authority
 
 Before editing, `plan-exec` repeats the inference over pending phases using the plan plus live
-dependencies, branches, working trees, blockers and risks.
-It may merge or split the declared batches without asking: current evidence wins.
-The declared section remains planning structure;
+dependencies, branches, working trees, blockers and risks: current evidence wins over the declared
+partition. The declared section remains planning structure;
 the effective batches and any difference are recorded in `CHECKPOINT`.
 
 A legacy plan without `## Execution batches` is valid. Execution infers effective batches and
@@ -54,20 +46,10 @@ records them in `CHECKPOINT`; it does not normalize the plan merely to add the s
 
 ## Continuous cycle
 
-For one effective batch:
-
-1. Verify every affected source and seed one batch intent before editing.
-2. Implement its phases in order. Mark local tasks done and set reached phases to `en ejecución`,
-   but run no phase proof, test runner, build, lint or closing review between them.
-3. After all implementation is written, run every phase proof in order, then the justified
-   focused/risk checks and applicable cross-cutting validations. The last pending batch also runs
-   the plan's final validation here, before Git.
-4. Fix failures autonomously and rerun the affected checks. Review the whole batch diff once.
-5. Only when every check, exit condition and review is green, flip all batch phases to `validada`,
-   update `CHECKPOINT`, and enter the Git step.
-
-This is the narrow exception to the chassis' per-phase artifact beat and clean-tree rule: the
-batch is the execution boundary. Task checkboxes and phase states keep it resumable.
+The batch — not the phase — is the execution boundary: implementation runs straight through, and
+every proof, check, review and state flip happens once at its close. This is the narrow exception to
+the chassis' per-phase artifact beat and clean-tree rule, and task checkboxes plus phase states are
+what keep it resumable. The order of those closing steps is the CLI's, per the note above.
 
 A real blocker or structural/functional deviation stops immediately. No unproven phase becomes
 `validada`; the combined changes remain uncommitted and the actual states plus the unblocking
@@ -75,10 +57,9 @@ action go to `CHECKPOINT`.
 
 ## Git authorization
 
-A green batch produces exactly one proposed commit per affected source. One consolidated approval
-covers all of those commits. If the user explicitly pre-authorized commits conditional on every
-batch check passing, record that authorization before editing and commit without another question.
-A failed or unrun check never satisfies the condition and never creates a commit. For the last
-pending batch, the same authorization also marks the fully validated plan `done` before committing,
-so that final plan write is included in the source's single commit; there is no second completion
-question or commit.
+A green batch produces exactly one proposed commit per affected source. Approving is not committing,
+and a check that never ran is not a green batch. For the last pending batch the same approval also
+covers marking the fully validated plan `done`, so that final write rides in the source's single
+commit instead of asking a second time.
+
+> **What proves the batch was green is not this document's call:** the deterministic steps below are decided by the CLI (`aw flow advance`), not by this document — positionally, behind the delegated validation and the review, neither of which a narration can pass.

package/skills/w/modules/PLAN-INPUT.md

@@ -5,12 +5,14 @@ Loaded when the input is not plainly a `ready-for-plan` spec (signal `input`).
 ## plan-new — four modes
 
 1. **Ready spec** (`docs/specs/NNN-spec-<slug>.md` whose frontmatter declares `status: ready-for-plan`) → ideal. Proceed straight to the loop.
-2. **Spec not ready** (`status: draft` / `refining`, or no mark at all) → **soft-suggest** running `/w:spec-refine` first. It is a suggestion, **never a block**: the user may proceed. Questions the spec left with destination `PLAN` are this flow's **input**, not a reason to send it back.
+2. **Spec not ready** (`status: draft` / `refining`, or no mark at all) → **soft-suggest** running `/w:spec-refine` first, **never a block**. Questions the spec left with destination `PLAN` are this flow's **input**, not a reason to send it back.
 3. **Prompt** (no spec referenced) → propose the SPEC flow; **by default launch `/w:spec-new`** with that prompt and continue the natural flow from there.
-4. **External plan content** — the argument carries an **already-built plan** (host plan mode, hand-written, another agent's) → **adopt it**. Single pass, **NO RESEARCH**: materialize as `docs/plans/PPP-plan-<slug>.md` (`aw next-number docs/plans`), normalized to the rich-plan schema with only what the source provides. `## Origin` = "adopted from <source>" + attribution (host · model · date). Then offer `/w:plan-refine` or `/w:plan-exec`. Anti-duplicate: a plan whose `## Origin` matches this objective → recommend resuming it, never a second one. Adoption **never regenerates over** an existing plan-doc.
+4. **External plan content** — the argument carries an **already-built plan** (host plan mode, hand-written, another agent's) → **adopt it**. Single pass, **NO RESEARCH**: materialize as `docs/plans/PPP-plan-<slug>.md`, normalized to the rich-plan schema with only what the source provides. `## Origin` = "adopted from <source>" + attribution (host · model · date). Then offer `/w:plan-refine` or `/w:plan-exec`. Anti-duplicate: a plan whose `## Origin` matches this objective is resumed, never duplicated. Adoption **never regenerates over** an existing plan-doc.
 
 > **Mode 3 vs 4:** a prompt that *describes a wish* → SPEC (mode 3); content that *already is a plan* → adopt (mode 4).
 
+> **What adoption may do once the mode is settled is not this document's call:** the deterministic steps below are decided by the CLI (`aw flow advance`), not by this document.
+
 > **Ready vs not** is read from the spec's frontmatter `status`, never from the filename. **Legacy compat:** a spec with no frontmatter that carries `## Refinement decisions` — or the older `## Q&A traceability` — counts as ready the same way.
 
 ## plan-refine — three modes
@@ -23,4 +25,4 @@ Loaded when the input is not plainly a `ready-for-plan` spec (signal `input`).
 
 ## Numbering
 
-The plan is named `docs/plans/PPP-plan-<slug>.md`. `aw next-number docs/plans` returns JSON (field `next` = `PPP`); the slug is short kebab-case from the Requirement (`[a-z0-9-]`, ≤ ~5 words / ≤ 40 chars). It does **not inherit the spec's `NNN`** — the link is established by reference in `## Origin`, never by number.
+The plan is named `docs/plans/PPP-plan-<slug>.md`; `aw next-number docs/plans` mints `PPP` and the slug comes from the Requirement. It does **not inherit the spec's `NNN`** — the link is established by reference in `## Origin`, never by number.

package/skills/w/modules/PLAN-REFINE-SPLIT.md

@@ -9,4 +9,6 @@ The gate itself — signals, offer, anti-duplicate, sibling contract, partition
 - The original plan **keeps its number/path**: it is rewritten **reduced** to its remaining tranche (in place, with confirmation). The extracted tranches become newly minted sibling plans (`aw next-number docs/plans` immediately before each write); their `## Origin` records "split from `docs/plans/PPP-plan-<slug>.md`" + the source spec + the siblings by path.
 - The gate also fires on **partially executed** plans. **Completed tasks (`- [x]`) never move to a sibling** — execution history stays anchored to the original path (plan-exec sessions' `## Origin` keep resolving); only pending work is extracted.
 - The split is recorded in `## Refinement decisions` (what moved where + why); original + siblings together keep the **complete, disjoint partition** of the spec criteria (spec-less: the Delta 2 degradation applies).
-- **Closing action** on the split branch: `Guardar planes` (edit the original reduced + write the extracted siblings); the normal branch keeps `Guardar plan refinado`.
+- **Closing action** on the split branch edits the original reduced and writes the extracted siblings — after the confirmation, never before it.
+
+> **When the cut fires, and that the write follows the confirmation, is not this document's call:** the deterministic steps below are decided by the CLI (`aw flow advance`), not by this document. The offer's alternatives are its too.

package/skills/w/modules/PLAN-SPLIT-GATE.md

@@ -4,11 +4,13 @@ Loaded when the plan may have to become more than one document (signal `split`).
 
 ## Split gate (multi-plan)
 
-Resolves the **Plan splittable** gap (Delta 2) — the canonical definition for **both** plan loops (`plan-refine-loop` references it, never redefines it). It fires **only on clear signals** (≥2 of: tranches independently executable/deliverable · no shared deps/risk between tranches · different requested moments/priorities · the plan far exceeds S-complexity phases · the user asked for staging); borderline → **one plan, no question**. It can be assessed during decomposition or at the coherence gate, always **before** `Guardar`.
+Resolves the **Plan splittable** gap (Delta 2) — the canonical definition for **both** plan loops (`plan-refine-loop` references it, never redefines it). It fires **only on clear signals** of independently deliverable tranches, and never on a borderline plan.
 
-- **The offer** enters the batch as a **content question** (counts in the ≤3): the body shows the proposed cut in the **user's language** — per sibling, a name + slug, a 1-line scope, the phase mapping and the order. Labels: `Dividir en varios planes` (recommended when the signals hold) | `Un solo plan`. Declining marks the gap **exhausted** (no re-offer this run); a free-form answer adjusts the cut. The accepted cut is seeded into `CHECKPOINT` — a resume does **not** re-ask.
-- **Anti-duplicate** (the `create_or_resume` spirit): if sibling plans whose `## Origin` references this same spec/split already exist, the recommended option becomes resuming them (`/w:plan-refine` / `/w:plan-exec` semantics) — never a second set.
-- **On acceptance** — same run, same session (one session per run, one HISTORY row): **all N siblings are elaborated complete** in this run — each gets the full Delta 1 schema and is immediately executable (`plan-exec` runs any plan; a seed without `## Tasks` would break that contract). Context pressure is absorbed by self-regulation (chassis § *Compact / resume*). Numbering: `aw next-number docs/plans` **immediately before each write** — numbers come out consecutive, so every sibling path is known after the first mint.
+> **Which signals count, how many it takes, and therefore whether the offer appears at all, is not this document's call:** the deterministic steps below are decided by the CLI (`aw flow advance`), not by this document. Recognizing a signal is judgment; counting them is a rule.
+
+- **The offer** enters the batch as a **content question** (counts in the ≤3): the body shows the proposed cut in the **user's language** — per sibling, a name + slug, a 1-line scope, the phase mapping and the order. Declining marks the gap **exhausted** (no re-offer this run); a free-form answer adjusts the cut. The accepted cut is seeded into `CHECKPOINT` — a resume does **not** re-ask.
+- **Anti-duplicate** (the `create_or_resume` spirit): sibling plans whose `## Origin` references this same spec/split are resumed, never minted a second time.
+- **On acceptance** — same run, same session (one session per run, one HISTORY row): **all N siblings are elaborated complete** in this run — each gets the full Delta 1 schema and is immediately executable (`plan-exec` runs any plan; a seed without `## Tasks` would break that contract). Context pressure is absorbed by self-regulation (chassis § *Compact / resume*). Numbering follows [`PLAN-INPUT`](PLAN-INPUT.md) § *Numbering*, minted immediately before each write.
 - **Sibling contract**: each `## Origin` records the shared source spec + `split (part i/N)` + the **siblings by path** + the order; `## Dependencies` (the existing optional section) carries the inter-plan order — **acyclic and advisory** (`plan-exec` does not enforce it; it only orients what to attack first).
 - **Coherence gate, re-framed**: every spec acceptance criterion traces to **exactly one** sibling — a **complete, disjoint partition**; each sibling's Final behavior block (in `## Solution`) covers its subset; the union covers the spec. Spec-less plans anchor the partition to their own Final behavior block / `Validations`.
-- **Closing action** on the split branch: `Guardar planes` (the single-plan branch keeps `Guardar plan`).
+- **Closing action** on the split branch writes every sibling in the same run; the single-plan branch writes one document. Both are the same confirmation step, and its alternatives are the CLI's.

package/skills/w/modules/PROMPT-CONTINUITY.md

@@ -10,4 +10,6 @@ Loaded when a bare prompt continues an existing work line (signal `resume`).
 2. `"second prompt"` (**no command**, related work) → does **not** create another session: **continues/reopens the most recent one** (from step 1) and appends the new scripts to **that same** `SCRIPTS.sql`.
 3. `/w:quick "third prompt"` (**command** again) → **new** session, new loop.
 
-> The **command** signals "new work line"; a **bare prompt** means "same line" → by default continue/reopen the most recent session (the *last started*). Clearly unrelated → offer choosing (`continuar NNN` | `trabajo nuevo`) or fall to the **no-flow** branch (write into `docs/` by convention + numbering). No workspace → **vanilla** behavior.
+> **Which line a prompt joins is not this document's call:** a command opens a new one through `aw session-create`, a bare prompt continues the most recent through `aw resume`. Both fire **before** a run exists, so no journey has a step for them. The reason stays: the **command** is the signal for "new work line", so nobody loses a thread by not typing one, or forks one by typing it twice.
+
+Whether a prompt really belongs to the open line is judgment. Clearly unrelated → offer choosing (`continuar NNN` | `trabajo nuevo`) or fall to the **no-flow** branch (`docs/` by convention + numbering). No workspace → **vanilla** behavior.

package/skills/w/modules/SPEC-CHANGE-SHAPE.md

@@ -8,14 +8,14 @@ Loaded when the investigation may have changed the spec shape (signal `shape`).
 
 | Finding | What it asks | What it writes |
 |---|---|---|
-| **`split`** — independent functional outcomes discovered | `Dividir en varias specs` \| `Una sola spec` | the original, rewritten reduced, **plus** one new file per extracted outcome |
+| **`split`** — independent functional outcomes discovered | cardinality: one spec, or several siblings | the original, rewritten reduced, **plus** one new file per extracted outcome |
 | **`replace`** — the purpose itself changed | `Crear una nueva spec` \| `Reformular esta spec` | `Crear` → one **new** file, this spec untouched · `Reformular` → **no new file**: this same file, same number, same path |
 
 ## Change-shape gate
 
-Runs once the baseline exists and **before** closing details: the investigation can reveal the draft's shape was wrong. Does the spec still carry **one** functional outcome, did its purpose survive, can the delivery be accepted as a unit? The verdict is **one of three shapes** — `same` | `split` | `replace` — each with its own branch; only the last two ask anything.
+The investigation can reveal the draft's shape was wrong. Does the spec still carry **one** functional outcome, did its purpose survive, can the delivery be accepted as a unit? The verdict is **one of three shapes** — `same` | `split` | `replace` — each with its own branch; only the last two ask anything.
 
-> **Resolved before the gap loop starts, never carried into it (hard rule).** A `split` or a `replace` is asked, answered and applied **immediately** — its own structured-choice, in its own step, between the baseline and the first gap batch. It never travels in `pending_human`: that collection is rebuilt on every iteration and is reserved for questions about functional, technical or scope **gaps**, so a shape decision parked there is erased by the next batch — or never asked at all, because a spec with no blocking gap breaks out of the loop before the batch is built. The resolution lands in `CHECKPOINT` **before** anything else runs, so a resume re-enters with the shape already decided and never re-asks it.
+> **When it runs, and that it never travels inside the gap loop, is not this document's call:** the deterministic steps below are decided by the CLI (`aw flow advance`), not by this document. Why it matters: a shape decision parked among the gap questions is erased by the next batch — or never asked at all, because a spec with no blocking gap leaves the loop before a batch is built.
 
 - same outcome — more clarity, or more technical components → **`same`**: no shape question, keep refining this spec;
 - independent functional outcomes discovered → **`split`** (below);
@@ -25,7 +25,7 @@ Runs once the baseline exists and **before** closing details: the investigation
 
 **Split criterion** — the one `spec-new` already uses ([`SPLIT-GATE.md`](SPLIT-GATE.md), `spec-new`'s `split` module), never a different one: divide **only** when each part can be refined, accepted and planned on its own. Repos, technologies, layers or teams are **secondary evidence**, never the reason.
 
-**Split semantics (in place).** The offer enters the batch as a content question — `Dividir en varias specs` | `Una sola spec`; declining marks it **exhausted** for the run. On acceptance: the original **keeps its number/path**, rewritten reduced to its remaining outcome; each extracted outcome is minted with `aw next-number docs/specs` right before its write and is born **`status: draft`**. Siblings are **not** elaborated here — unlike the multi-plan gate, where `plan-exec` would break on a plan with no `## Tasks`; a draft spec is legitimate input to this very loop — so the run keeps refining the **reduced original** and reports `/w:spec-refine` as each sibling's next step. Every `## Origin` records "split from `docs/specs/NNN-spec-<slug>.md`" + the siblings **by path**. Closing action on this branch: `Guardar specs`.
+**Split semantics (in place).** The offer enters the batch as a content question. On acceptance: the original **keeps its number/path**, rewritten reduced to its remaining outcome; each extracted outcome is minted with `aw next-number docs/specs` right before its write and is born **`status: draft`**. Siblings are **not** elaborated here — unlike the multi-plan gate, where `plan-exec` would break on a plan with no `## Tasks`; a draft spec is legitimate input to this very loop — so the run keeps refining the **reduced original** and reports `/w:spec-refine` as each sibling's next step. Every `## Origin` records "split from `docs/specs/NNN-spec-<slug>.md`" + the siblings **by path**. Closing action on this branch: `Guardar specs`.
 
 **Replace semantics.** Its offer is its own — `Crear una nueva spec` | `Reformular esta spec`, **never** the split labels: what gets decided is which identity carries the new purpose. Recommend **a new spec** when the main functional outcome or the actor/consumer changed; **reformulating** when the user confirms this file is still the same unit of work and wants to keep its identity.
 

package/skills/w/roles/README.md

@@ -51,6 +51,8 @@ built-in default
 2. **Role with no binding at any level** → use the built-in default (table above). No config needed for the common case.
 3. **`off`** → capability disabled. The loop continues without it; if the task required it, the loop reports why it cannot proceed or asks the human.
 
+**A role whose skill declares a capability descriptor is stricter**, because there the binding decides what RUNS and not just which name is written: unset or the canonical name enables the built-in floor plus whatever compatible improvements the host selected; `off` applies the descriptor's per-operation policy and no host, wrapper or legacy name reverts it; anything else is `misconfigured` — a replacement binding does not select an improvement, and the file is never rewritten for you. Existing workspaces are not migrated: `aw skills --detail` explains the reclassification and the owner adopts unset, the canonical name or `off`.
+
 ---
 
 ## skills.toml format

package/skills/w/roles/design/CONTRACT.md

@@ -0,0 +1,80 @@
+# design — invocation contract
+
+The single authority for **how** `design` is invoked. The installed wrapper
+(`design/SKILL.md`) and [`ROLE.md`](ROLE.md) both point here instead of
+restating it: two descriptions of one contract disagree the day either changes.
+
+The machine-readable form is the descriptor published next to the wrapper
+(`workline-capability.json`, schema `../../schemas/capability-descriptor.schema.json`).
+This file is what a person or a loop reads.
+
+## One door, four stages
+
+```
+aw capability prepare  --capability design --operation <op> [--input k=v ...]
+aw capability continue                                       # stdin: {"parent": <request>}
+aw capability validate                                       # stdin: {"request": …, "answer": …}
+aw capability apply --approval <digest>                      # stdin: {"request": …, "plan": …}
+```
+
+The verbs are **stages**, never operations: the operation travels in the
+envelope. Every attempt returns `outcome`, `output` and `receipt`. A
+`needs_input` is answered with `continue`, which builds the NEXT attempt of the
+same `invocation_id` — it never reuses the previous request.
+
+## What each caller may invoke
+
+| Caller | Operations | Then |
+|---|---|---|
+| direct wrapper | all five | converses in the host; opens no flow session or document |
+| SPEC REFINE | `create` · `update` · `validate` | keeps its own questions, gate and publication |
+| PLAN NEW · PLAN REFINE | `update` · `validate` | closes its plan over the revision it references |
+| PLAN EXEC · QUICK | `validate` | **consumes** the package inside its own lifecycle |
+
+There is no sixth `consume` operation: consuming is what a flow DOES with a
+validated package, not something it asks the capability to do. An operation
+outside its row is refused, never improvised. A flow may add gates of its own and
+may never lower one the capability already failed; a durable output produced
+through the direct route is adopted later **by exact reference** — same identity,
+revision and digest — with no recreation and no format conversion.
+
+## Sources, and what an omission costs
+
+The v1 catalog: Markdown or text, images and screenshots, PDF, DOCX, PPTX, host
+context or attachments, an existing package, and provider locators. Binary
+documents are read by the **host's** multimodal capability — no parser ships in
+the CLI — so what the catalog declares is what the domain can account for.
+
+Every source ends in one of five dispositions, and each one that is not `used`
+carries its reason: `used` · `skipped` (a decision) · `unsupported` (a format v1
+never promised, every retired UI format included) · `unavailable` (it should
+have been readable and was not) · `redacted` (withheld on purpose).
+
+The consequence is fail-closed: a source that did not contribute blocks
+`handoff` unless someone states, in writing, why the design does not need it. A
+run that silently dropped a requirements document and still declared itself
+ready for implementation is the failure this exists to prevent. Original
+documents are never copied into the package unless a person names them, and
+never when they are sensitive.
+
+## Where the output lands
+
+Inside a workspace the package defaults to `docs/designs/` and is discoverable
+by the index — which is what lets a spec or a plan reference it later without it
+ever having had a relationship with those flows. Outside a workspace the caller
+must name an explicit root; the result is still a conformant, portable package,
+and it is simply not indexed. What never happens is a guess: no root declared,
+nothing written.
+
+## What the direct route does not do
+
+- Never creates, advances, closes or publishes a SPEC, PLAN or QUICK session or
+  document.
+- Never initializes a workspace: an operation that needs one and does not find
+  it returns an explicit result.
+- Never exercises an effect the descriptor does not declare, nor one that
+  requires approval without asking for it first.
+
+`off` is decided per operation by the descriptor and no host, wrapper or legacy
+name reverts it. `aw skills --detail` reports the live state, its evidence and
+the next action.

package/skills/w/roles/design/ROLE.md

@@ -164,6 +164,13 @@ validators and completeness. Where the two meet, Spec 014 decides the envelope
 and this one decides the payload. Duplicating either side is the failure mode
 being avoided.
 
+### How it is invoked
+
+Both routes reach the same dispatcher and each caller has a fixed row of
+operations it may ask for. That contract is stated once, in
+[`CONTRACT.md`](CONTRACT.md) — the same file the installed wrapper points at.
+Nothing about invocation is restated here.
+
 ## CLI ↔ agent split
 
 Explicit, and it is the whole point of the handshake:

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 }
+        }
+      }
+    }
+  }
+}