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>

steward/ansible/PLAYBOOK_CONVENTIONS.md

@@ -0,0 +1,39 @@
+# Steward playbook conventions (quick reference)
+
+What Steward reads from a playbook in this subsystem. Full guide:
+`docs/reference/playbook-authoring.md`. Parser:
+`steward/ansible/sources.py` — `discover_playbook_meta()` and
+`discover_playbook_variables()`.
+
+## Magic comments (metadata)
+
+```yaml
+---
+# description: One line on what this playbook does.   # shown on selection
+# steward:category: maintenance                       # grouping badge
+# steward:confirm: true                               # require confirm to run
+- name: …            # used as the description if no `# description:` comment
+  hosts: all         # Steward generates the inventory from the chosen target/group
+```
+
+- `# description:` — first match wins; case-insensitive; falls back to first
+  play `name:`.
+- `# steward:<key>: <value>` — namespaced metadata. Implemented keys:
+  - `category` — free-text grouping label (badge in browse + run form).
+  - `confirm` — `true`/`yes`/`1`/`on` → run form requires a confirmation tick.
+  - `description` — alias for `# description:` (unprefixed wins if both present).
+  - Unknown `# steward:*` keys are ignored (namespace reserved for future use).
+
+## Structural cues (no comments needed)
+
+- **`vars:` scalars** → editable run-time fields (default shown as placeholder;
+  blank = keep default; values sent as highest-precedence extra-vars).
+- **`vars_prompt:`** → run-time fields (required when no default; `private: true`
+  → masked).
+- **Secret naming** — a var whose name contains `password`/`passwd`/`secret`/
+  `token`/`api_key`/`private_key`/`credential` is masked **and not persisted**.
+- **`hosts: all`** — target via the run form's scope; don't hardcode hosts.
+- **Credentials** — never embed them. Steward connects as the managed `steward`
+  account (passwordless sudo; use `become: true`) or one-time bootstrap creds.
+
+Be idempotent — Steward re-runs playbooks (updates, schedules, retries).

steward/ansible/bundled/host_agent/install.yml

@@ -1,5 +1,6 @@
 ---
 # description: Install or re-enroll the Steward host agent on an already-provisioned host.
+# steward:category: host-agent
 # Install (or update) the Steward host agent on a target. Mirrors the
 # curl-based install.sh. Pass the per-host registration token as extra-vars:
 #   steward_url=https://steward.example  steward_token=<token from Host Agents>

steward/ansible/bundled/host_agent/provision.yml

@@ -1,5 +1,6 @@
 ---
 # description: Provision a fresh host — create the steward account + managed key + passwordless sudo, then install the agent.
+# steward:category: host-agent
 # First-contact provisioning: bring a fresh host under Steward management, then
 # install the host agent — all in one idempotent run.
 #

steward/ansible/bundled/host_agent/update.yml

@@ -1,5 +1,6 @@
 ---
 # description: Update the Steward host agent (refresh agent.py + restart) on hosts already running it.
+# steward:category: host-agent
 # Update an already-installed Steward host agent: refresh agent.py and restart.
 #
 # Deliberately does NOT touch the registration token or /etc/steward-agent.conf

steward/ansible/bundled/maintenance/docker_prune.yml

@@ -1,5 +1,7 @@
 ---
 # description: Reclaim disk on Docker / Swarm nodes by pruning unused images, containers, networks and build cache.
+# steward:category: maintenance
+# steward:confirm: true
 # Reclaim disk on Docker / Docker Swarm nodes by removing unused data.
 # Safe by default: prunes dangling images, stopped containers, unused networks
 # and build cache. Set extra-vars to widen scope:

steward/ansible/routes.py

@@ -50,7 +50,16 @@ async def browse():
     all_sources = _get_sources()
     source_data = []
     for source in all_sources:
-        playbooks = src_module.discover_playbooks(source["path"])
+        playbooks = []
+        for path in src_module.discover_playbooks(source["path"]):
+            contents = src_module.read_playbook(source["path"], path)
+            meta = (src_module.discover_playbook_meta(contents) if contents is not None
+                    else {"description": "", "category": ""})
+            playbooks.append({
+                "path": path,
+                "category": meta["category"],
+                "description": meta["description"],
+            })
         inventories = src_module.discover_inventories(source["path"])
         source_data.append({
             "source": source,
@@ -165,14 +174,15 @@ async def playbook_vars():
     playbook_path = (request.args.get("playbook_path", "") or "").strip()
     source = next((s for s in _get_sources() if s["name"] == source_name), None)
     variables: list = []
-    description = ""
+    meta: dict = {"description": "", "category": "", "confirm": False}
     if source and playbook_path:
         contents = src_module.read_playbook(source["path"], playbook_path)
         if contents is not None:
             variables = src_module.discover_playbook_variables(contents)
-            description = src_module.discover_playbook_description(contents)
+            meta = src_module.discover_playbook_meta(contents)
     return await render_template(
-        "ansible/_playbook_vars.html", variables=variables, description=description)
+        "ansible/_playbook_vars.html", variables=variables,
+        description=meta["description"], category=meta["category"], confirm=meta["confirm"])
 
 
 @ansible_bp.get("/run-form/<source_name>/<path:playbook_path>")
@@ -189,7 +199,7 @@ async def run_form(source_name: str, playbook_path: str):
     if contents is None:
         return "Playbook not found", 404
     variables = src_module.discover_playbook_variables(contents)
-    description = src_module.discover_playbook_description(contents)
+    meta = src_module.discover_playbook_meta(contents)
     inventories = src_module.discover_inventories(source["path"])
 
     async with current_app.db_sessionmaker() as db:
@@ -201,7 +211,8 @@ async def run_form(source_name: str, playbook_path: str):
     return await render_template(
         "ansible/_run_form.html",
         source_name=source_name, playbook_path=playbook_path,
-        variables=variables, description=description, targets=targets, groups=groups,
+        variables=variables, description=meta["description"], category=meta["category"],
+        confirm=meta["confirm"], targets=targets, groups=groups,
         inventories=inventories,
     )
 

steward/ansible/sources.py

@@ -20,6 +20,52 @@ _SECRET_VAR_RE = re.compile(
 # A playbook self-describes via a `# description:` magic comment (Ansible rejects
 # unknown play keys, so a comment is the portable place). First match wins.
 _DESCRIPTION_RE = re.compile(r"^\s*#\s*description:\s*(.+?)\s*$", re.I | re.M)
+# Namespaced metadata: `# steward:<key>: <value>` (category, confirm, …).
+_STEWARD_META_RE = re.compile(r"^\s*#\s*steward:(\w+):\s*(.+?)\s*$", re.I | re.M)
+_TRUTHY = {"1", "true", "yes", "on"}
+
+
+def _first_play_name(content: str) -> str:
+    import yaml
+    try:
+        plays = yaml.safe_load(content)
+    except yaml.YAMLError:
+        return ""
+    if isinstance(plays, list):
+        for play in plays:
+            if isinstance(play, dict) and play.get("name"):
+                return str(play["name"]).strip()
+    return ""
+
+
+def discover_playbook_meta(content: str) -> dict:
+    """Parse Steward's playbook metadata from magic comments.
+
+    Returns {description, category, confirm}. Sources:
+      - description: ``# description:`` (primary) or ``# steward:description:``;
+        falls back to the first play's ``name:``.
+      - category: ``# steward:category: <text>`` (free-text grouping label).
+      - confirm: ``# steward:confirm: true`` → require an explicit confirmation
+        in the run form before launching (for destructive playbooks).
+    First match wins for each key.
+    """
+    steward: dict[str, str] = {}
+    for km in _STEWARD_META_RE.finditer(content):
+        steward.setdefault(km.group(1).lower(), km.group(2).strip())
+
+    m = _DESCRIPTION_RE.search(content)
+    if m:
+        description = m.group(1).strip()
+    elif steward.get("description"):
+        description = steward["description"]
+    else:
+        description = _first_play_name(content)
+
+    return {
+        "description": description,
+        "category": steward.get("category", ""),
+        "confirm": str(steward.get("confirm", "")).strip().lower() in _TRUTHY,
+    }
 
 # Name of the always-present, read-only source of first-party playbooks shipped
 # inside the app (maintenance tasks, host-agent install). Not operator-editable.
@@ -200,25 +246,9 @@ def delete_playbook(source_path: str, relative_path: str) -> tuple[bool, str | N
 
 
 def discover_playbook_description(content: str) -> str:
-    """A human-readable description of what a playbook does.
-
-    Reads a ``# description: ...`` magic comment (first match), so any playbook
-    can self-describe without touching its YAML structure. Falls back to the
-    first play's ``name:``. Returns "" if neither is present.
-    """
-    m = _DESCRIPTION_RE.search(content)
-    if m:
-        return m.group(1).strip()
-    import yaml
-    try:
-        plays = yaml.safe_load(content)
-    except yaml.YAMLError:
-        return ""
-    if isinstance(plays, list):
-        for play in plays:
-            if isinstance(play, dict) and play.get("name"):
-                return str(play["name"]).strip()
-    return ""
+    """A human-readable description of what a playbook does (see
+    discover_playbook_meta). Returns "" if none can be determined."""
+    return discover_playbook_meta(content)["description"]
 
 
 def discover_playbook_variables(content: str) -> list[dict]: