feat(ansible): steward:category + steward:confirm playbook metadata

Extend the playbook metadata convention with a namespaced `# steward:<key>:`
comment block:

- steward:category — free-text grouping label, shown as a badge in the browse
  list and on the run form.
- steward:confirm — true/yes/1/on marks a playbook destructive; the run form
  then requires a confirmation tick (required checkbox in the shared vars
  fragment) before it can launch.

sources.discover_playbook_meta() parses description + category + confirm (first
match per key; `# description:` still primary, `# steward:description:` alias).
discover_playbook_description() now delegates to it. The browse list reads
per-playbook meta to show category badges + descriptions; the run-form and
playbook-vars fragments render the badge + confirm gate.

Bundled playbooks tagged: docker_prune → category maintenance + confirm true;
provision/install/update → category host-agent.

Docs: docs/reference/playbook-authoring.md updated (keys now implemented) and a
quick reference added next to the code at steward/ansible/PLAYBOOK_CONVENTIONS.md.
Tests added for category/confirm/alias parsing.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

docs/reference/playbook-authoring.md

@@ -124,6 +124,8 @@ re-runs are safe.
 |---|---|
 | `# description: <text>` comment | Description shown on selection (first match) |
 | first play `name:` | Description fallback |
+| `# steward:category: <text>` | Grouping badge in the browse list + run form |
+| `# steward:confirm: true` | Requires a confirmation tick before the run launches |
 | `vars:` scalar entries | Run-time fill-in fields (placeholder = default) |
 | `vars_prompt:` entries | Run-time fields (required if no default) |
 | secret-looking var name / `private: true` | Field masked + value not persisted |
@@ -132,16 +134,36 @@ re-runs are safe.
 Everything else (SSH user/key, become password, the inventory, `steward_token`
 etc. for the agent playbooks) is injected by Steward at run time.
 
-## Metadata convention & extensibility
+## Metadata comments
 
-Today the **only comment-based metadata** Steward parses is `# description:`.
-Everything else is *structural* (`vars`, `vars_prompt`, `hosts`, the play
-`name`). If we add more comment metadata later, it will use a reserved
-**`# steward:<key>: <value>`** namespace (e.g. `# steward:category: maintenance`,
-`# steward:confirm: true` for a run-confirmation gate) so it can't collide with
-ordinary comments. **These extra keys are not implemented yet** — only
-`# description:` is. Don't author playbooks that depend on `# steward:*` keys
-until this doc says they're live.
+Steward reads metadata from magic comments (Ansible rejects unknown play keys,
+so comments are the portable place). Two forms:
+
+- `# description: <text>` — the description (see §1).
+- `# steward:<key>: <value>` — the namespaced metadata block. First match per
+  key wins; keys are case-insensitive.
+
+**Implemented `# steward:` keys:**
+
+| Key | Example | Effect |
+|---|---|---|
+| `category` | `# steward:category: maintenance` | Free-text grouping label. Shown as a badge in the browse list and on the run form. Purely organizational. |
+| `confirm` | `# steward:confirm: true` | Marks the playbook as significant/destructive. The run form then requires an explicit confirmation tick before it can be launched. Use for data-loss-capable plays (prune with volumes, resets, etc.). Truthy values: `true`/`yes`/`1`/`on`. |
+| `description` | `# steward:description: ...` | Alias for `# description:` (the unprefixed form takes precedence if both exist). |
+
+```yaml
+---
+# description: Reclaim disk on Docker/Swarm nodes by pruning unused data.
+# steward:category: maintenance
+# steward:confirm: true
+- name: Docker system prune
+  hosts: all
+  ...
+```
+
+Other `# steward:<key>:` keys are simply ignored today — the namespace is
+reserved, so it's safe to add ones Steward doesn't yet understand without
+breaking anything, but only `category`, `confirm`, and `description` do something.
 
 ## Minimal annotated example