@deftai/directive-content 0.59.0 → 0.61.0

package/scripts/triage_help.py

@@ -1,1685 +0,0 @@
-# ruff: noqa: E501  -- registry literal carries long usage/example strings
-# that are easier to read on one line than wrapped. The 100-char ceiling is
-# enforced everywhere else in this file (it is the rest of the codebase's
-# default); the registry block is the documented exception.
-"""triage_help.py -- categorized verb-help surface (#1150 / N10).
-
-This module is the single source of truth for the *user-facing* help text
-of every ``triage:*`` and ``scope:*`` task. It powers three surfaces:
-
-1. ``task triage`` (bare invocation) -- categorized verb list grouped by
-   role (Session-start / State verbs / Read verbs / Lifecycle /
-   Subscription mutation / Archive-rotation).
-2. ``task scope`` (bare invocation) -- categorized verb list grouped by
-   role (Promote / demote, Activate / complete, Reversibility).
-3. ``<verb> --help`` -- structured per-verb help with description,
-   flags + defaults, 2-3 examples and cross-references to related verbs
-   + umbrella children. Verb scripts call :func:`intercept_help` early
-   in ``main()`` so the structured renderer wins over argparse default.
-
-Adding a new ``triage:*`` / ``scope:*`` verb is one dict-insert under
-:data:`REGISTRY` plus a single entry in :data:`CATEGORIES_TRIAGE` or
-:data:`CATEGORIES_SCOPE`. See ``CONTRIBUTING.md`` § "Adding a new
-triage / scope verb" for the contributor walkthrough.
-
-Forward-looking placeholders ("coming in <child>") are intentionally
-listed for D17 (metrics) / D19 (archive rotation) / D20 (audit-log
-rotation) so the verb-space catalog is stable across the umbrella's
-remaining children -- a fresh contributor sees the *shape* of the
-surface even when a verb has not yet landed.
-
-Programmatic API
-----------------
-
-* :class:`VerbHelp` -- frozen registry entry shape.
-* :data:`REGISTRY` -- ``{verb_name: VerbHelp}`` lookup.
-* :data:`CATEGORIES_TRIAGE` / :data:`CATEGORIES_SCOPE` -- ordered
-  ``[(category_label, [verb_names])]`` for the bare-list renderers.
-* :data:`SCRIPT_SUBCOMMAND_MAP` -- ``{script_module: {subcommand: verb}}``
-  used by :func:`intercept_help` to resolve a verb from argv at runtime.
-* :func:`render_category_list` -- pure text renderer for the bare
-  invocation surface.
-* :func:`render_verb_help` -- pure text renderer for the ``--help``
-  surface.
-* :func:`intercept_help` -- ``main()`` shim that prints structured help
-  and returns ``0`` when ``--help`` / ``-h`` is in ``argv``; returns
-  ``None`` otherwise.
-
-CLI
----
-
-``python -m scripts.triage_help <category>`` prints the bare-list for
-``triage`` or ``scope``. ``python -m scripts.triage_help help <verb>``
-prints the structured per-verb help. ``python -m scripts.triage_help
-list`` dumps every registered verb for tooling discovery.
-
-Refs
-----
-
-* Umbrella: #1119.
-* This child: #1150 / N10.
-* Reciprocal child for ``task slice:record-existing``: #1147 / N7 (verb
-  space outside the triage/scope namespaces; intentionally NOT
-  registered here so the registry boundary stays sharp).
-"""
-
-from __future__ import annotations
-
-import contextlib
-import sys
-from collections.abc import Sequence
-from dataclasses import dataclass, field
-
-# UTF-8 self-reconfigure -- the help renderer prints arrows / em-dashes
-# / ⚠ glyphs that cp1252 cannot encode (#814).
-for _stream in (sys.stdout, sys.stderr):
-    if hasattr(_stream, "reconfigure"):
-        with contextlib.suppress(AttributeError, ValueError):
-            _stream.reconfigure(encoding="utf-8", errors="replace")
-
-
-# ---------------------------------------------------------------------------
-# Registry data shape
-# ---------------------------------------------------------------------------
-
-
-@dataclass(frozen=True)
-class VerbHelp:
-    """Structured help metadata for a single ``triage:*`` / ``scope:*`` verb.
-
-    Attributes
-    ----------
-    name:
-        Canonical verb name as the user invokes it (``triage:queue``,
-        ``scope:promote``). Matches the Taskfile task name.
-    summary:
-        One-line description used in the bare-list category renderer.
-        Keep <= 70 chars so the category list stays scannable.
-    refs:
-        Bracketed cross-ref tag printed alongside ``summary`` in the
-        category renderer (e.g. ``"(D11)"`` or ``"(D19, coming)"``).
-    description:
-        Full prose description printed as the first paragraph of the
-        ``--help`` surface. May be multi-line.
-    usage:
-        Synopsis line (e.g.
-        ``"task triage:queue [--limit=N] [--state=<filter>]"``).
-    flags:
-        List of ``(flag, default, description)`` triples. ``default``
-        is rendered verbatim -- use ``"(required)"`` for required
-        flags, ``"(none)"`` for unset defaults.
-    examples:
-        2-3 example invocations. Rendered as a fenced indented block.
-    see_also:
-        Verb names and umbrella-child references to surface at the
-        bottom of the ``--help`` output. Use plain verb names
-        (``"task triage:show"``) or umbrella IDs (``"#1119 / D11"``).
-    placeholder:
-        True for not-yet-landed verbs (e.g. D17 metrics / D19 archive
-        rotation). The renderer adds a ``"(not yet implemented)"``
-        note so the operator knows the verb is forward-looking.
-    """
-
-    name: str
-    summary: str
-    refs: str
-    description: str
-    usage: str
-    flags: Sequence[tuple[str, str, str]] = field(default_factory=tuple)
-    examples: Sequence[str] = field(default_factory=tuple)
-    see_also: Sequence[str] = field(default_factory=tuple)
-    placeholder: bool = False
-
-
-# ---------------------------------------------------------------------------
-# Registry -- single source of truth for every triage:* / scope:* verb
-# ---------------------------------------------------------------------------
-
-
-def _entry(*args, **kwargs) -> VerbHelp:
-    """Convenience constructor so the registry literal stays compact."""
-    return VerbHelp(*args, **kwargs)
-
-
-REGISTRY: dict[str, VerbHelp] = {
-    # --- Session-start cross-namespace surfaces --------------------------
-    "task triage:summary": _entry(
-        name="task triage:summary",
-        summary="One-line state for session-start ritual",
-        refs="(D2 / #1122)",
-        description=(
-            "Emit the one-line triage state consumed by the session-start "
-            "ritual. Always exits 0 (status surface, not a gate); appends "
-            "a JSONL record to vbrief/.eval/summary-history.jsonl for "
-            "observability."
-        ),
-        usage="task triage:summary [-- --json] [--no-history]",
-        flags=(
-            ("--json", "(off)", "Emit the structured record as JSON instead of the one-liner."),
-            ("--no-history", "(off)", "Suppress the history sidecar append (test-only)."),
-            ("--project-root PATH", "(cwd)", "Project root override (Taskfile threads USER_WORKING_DIR)."),
-        ),
-        examples=(
-            "task triage:summary",
-            "task triage:summary -- --json | jq",
-        ),
-        see_also=(
-            "task triage:queue",
-            "task verify:cache-fresh",
-            "#1119 / D2",
-        ),
-    ),
-    "task verify:cache-fresh": _entry(
-        name="task verify:cache-fresh",
-        summary="Pre-start_agent freshness gate",
-        refs="(D5 / #1127)",
-        description=(
-            "Detection-bound gate that refuses dispatch when the local "
-            "cache is stale or the target issue is outside the active "
-            "subscription. Exit 0 = clear, 1 = blocked (stale / outside "
-            "scope / wrong decision), 2 = config error (cache missing)."
-        ),
-        usage="task verify:cache-fresh [-- --for-issue N] [--allow-stale]",
-        flags=(
-            ("--for-issue N", "(none)", "Gate on a specific upstream issue number."),
-            ("--allow-stale", "(off)", "Operator-audited override; logged to stderr."),
-        ),
-        examples=(
-            "task verify:cache-fresh",
-            "task verify:cache-fresh -- --for-issue 1150",
-        ),
-        see_also=(
-            "task triage:bootstrap",
-            "task cache:fetch-all",
-            "#1119 / D5",
-        ),
-    ),
-    # --- State verbs (mutate audit log) ----------------------------------
-    "task triage:accept": _entry(
-        name="task triage:accept",
-        summary="Mark issue accepted; chains into scope:promote w/ flag",
-        refs="(D18 / #845)",
-        description=(
-            "Record an `accept` audit entry against an issue. With the "
-            "D18 reciprocity flag, chains into scope:promote --from-issue "
-            "so the upstream cache and the vBRIEF lifecycle stay in sync."
-        ),
-        usage="task triage:accept -- --issue N --repo owner/name [--actor STR]",
-        flags=(
-            ("--issue N", "(required)", "Issue number."),
-            ("--repo owner/name", "(required)", "Upstream repo."),
-            ("--actor STR", "(env DEFT_TRIAGE_ACTOR)", "Override the audit actor field."),
-        ),
-        examples=(
-            "task triage:accept -- --issue 42 --repo deftai/directive",
-        ),
-        see_also=(
-            "task triage:status",
-            "task scope:promote",
-            "#1119 / D18",
-        ),
-    ),
-    "task triage:defer": _entry(
-        name="task triage:defer",
-        summary="Defer with reason + optional resume-on condition",
-        refs="(D3 / #1123)",
-        description=(
-            "Record a `defer` audit entry against an issue. --reason is "
-            "required (replaces free-text defer per D3). --resume-on "
-            "accepts the v1 grammar (ref:closed:#N | ref:merged:#N | "
-            "date:>=YYYY-MM-DD | pending-count:>=N | pending-count:<=N, "
-            "joined by AND/OR)."
-        ),
-        usage="task triage:defer -- --issue N --repo owner/name --reason 'why' [--resume-on EXPR] [--actor STR]",
-        flags=(
-            ("--issue N", "(required)", "Issue number."),
-            ("--repo owner/name", "(required)", "Upstream repo."),
-            ("--reason 'why'", "(required)", "Structured rationale (D3 enforced)."),
-            ("--resume-on EXPR", "(none)", "Resume-condition expression."),
-            ("--actor STR", "(env DEFT_TRIAGE_ACTOR)", "Override the audit actor field."),
-        ),
-        examples=(
-            "task triage:defer -- --issue 42 --repo deftai/directive --reason 'waiting on upstream'",
-            "task triage:defer -- --issue 42 --repo deftai/directive --reason 'needs PR 99' --resume-on 'ref:merged:#99'",
-        ),
-        see_also=(
-            "task triage:status",
-            "task triage:history",
-            "task triage:bulk-defer",
-            "#1119 / D3",
-        ),
-    ),
-    "task triage:reject": _entry(
-        name="task triage:reject",
-        summary="Close upstream with comment + label",
-        refs="(#845)",
-        description=(
-            "Close the upstream issue, apply the `triage-rejected` label, "
-            "and record a `reject` audit entry. Rolls audit back on gh "
-            "failure so the cache and upstream stay consistent."
-        ),
-        usage="task triage:reject -- --issue N --repo owner/name --reason 'why' [--actor STR]",
-        flags=(
-            ("--issue N", "(required)", "Issue number."),
-            ("--repo owner/name", "(required)", "Upstream repo."),
-            ("--reason 'why'", "(required)", "Reason recorded on the close comment."),
-            ("--actor STR", "(env DEFT_TRIAGE_ACTOR)", "Override the audit actor field."),
-        ),
-        examples=(
-            "task triage:reject -- --issue 42 --repo deftai/directive --reason 'out of scope'",
-        ),
-        see_also=(
-            "task triage:bulk-reject",
-            "task triage:reset",
-            "#1119 / #845",
-        ),
-    ),
-    "task triage:needs-ac": _entry(
-        name="task triage:needs-ac",
-        summary="Post comment requesting AC",
-        refs="(#845)",
-        description=(
-            "Mark an issue as needing acceptance criteria and post an "
-            "AC-request comment upstream. Records a `needs-ac` audit "
-            "entry against the cache."
-        ),
-        usage="task triage:needs-ac -- --issue N --repo owner/name [--comment STR] [--actor STR]",
-        flags=(
-            ("--issue N", "(required)", "Issue number."),
-            ("--repo owner/name", "(required)", "Upstream repo."),
-            ("--comment STR", "(canned)", "Override the AC-request comment text."),
-            ("--actor STR", "(env DEFT_TRIAGE_ACTOR)", "Override the audit actor field."),
-        ),
-        examples=(
-            "task triage:needs-ac -- --issue 42 --repo deftai/directive",
-        ),
-        see_also=(
-            "task triage:bulk-needs-ac",
-            "task triage:status",
-            "#1119 / #845",
-        ),
-    ),
-    "task triage:mark-duplicate": _entry(
-        name="task triage:mark-duplicate",
-        summary="Link as duplicate of another (validated)",
-        refs="(#845)",
-        description=(
-            "Link an issue as a duplicate of another cached issue. The "
-            "target issue must already exist in the unified cache; the "
-            "audit entry is rejected otherwise."
-        ),
-        usage="task triage:mark-duplicate -- --issue N --of M --repo owner/name [--actor STR]",
-        flags=(
-            ("--issue N", "(required)", "Issue number to mark as duplicate."),
-            ("--of M", "(required)", "Canonical issue number (validated against the cache)."),
-            ("--repo owner/name", "(required)", "Upstream repo."),
-            ("--actor STR", "(env DEFT_TRIAGE_ACTOR)", "Override the audit actor field."),
-        ),
-        examples=(
-            "task triage:mark-duplicate -- --issue 42 --of 17 --repo deftai/directive",
-        ),
-        see_also=(
-            "task triage:history",
-            "#1119 / #845",
-        ),
-    ),
-    "task triage:reset": _entry(
-        name="task triage:reset",
-        summary="Undo prior decision (Layer 5 reversibility)",
-        refs="(#845)",
-        description=(
-            "Append a `reset` audit entry that references the prior "
-            "decision. Does NOT delete history -- the audit log is "
-            "append-only by design; reset is the supported reversibility "
-            "primitive."
-        ),
-        usage="task triage:reset -- --issue N --repo owner/name [--actor STR]",
-        flags=(
-            ("--issue N", "(required)", "Issue number."),
-            ("--repo owner/name", "(required)", "Upstream repo."),
-            ("--actor STR", "(env DEFT_TRIAGE_ACTOR)", "Override the audit actor field."),
-        ),
-        examples=(
-            "task triage:reset -- --issue 42 --repo deftai/directive",
-        ),
-        see_also=(
-            "task triage:history",
-            "task scope:undo",
-            "#1119 / #845",
-        ),
-    ),
-    "task triage:status": _entry(
-        name="task triage:status",
-        summary="Print latest triage decision (read-only)",
-        refs="(#845)",
-        description=(
-            "Print the latest triage decision for an issue from the "
-            "append-only audit log. Read-only; no mutations, no "
-            "subprocess calls."
-        ),
-        usage="task triage:status -- --issue N --repo owner/name",
-        flags=(
-            ("--issue N", "(required)", "Issue number."),
-            ("--repo owner/name", "(required)", "Upstream repo."),
-        ),
-        examples=(
-            "task triage:status -- --issue 42 --repo deftai/directive",
-        ),
-        see_also=(
-            "task triage:history",
-            "task triage:show",
-            "#1119 / #845",
-        ),
-    ),
-    "task triage:history": _entry(
-        name="task triage:history",
-        summary="Print full triage timeline (read-only)",
-        refs="(#845)",
-        description=(
-            "Print the full triage timeline for an issue ordered by "
-            "timestamp ascending. Read-only."
-        ),
-        usage="task triage:history -- --issue N --repo owner/name",
-        flags=(
-            ("--issue N", "(required)", "Issue number."),
-            ("--repo owner/name", "(required)", "Upstream repo."),
-        ),
-        examples=(
-            "task triage:history -- --issue 42 --repo deftai/directive",
-        ),
-        see_also=(
-            "task triage:status",
-            "task triage:audit",
-            "#1119 / #845",
-        ),
-    ),
-    # --- Read verbs ------------------------------------------------------
-    "task triage:queue": _entry(
-        name="task triage:queue",
-        summary="Ranked candidate list",
-        refs="(D11 / #1128)",
-        description=(
-            "Print the ranked triage queue from the local cache. Groups "
-            "(display order): [ORPHAN] -> [RESUME] -> [URGENT] -> untriaged "
-            "-> other -> [BLOCKED]. Within-group default = updated_at desc; "
-            "consumer plan.policy.triageRankingLabels[] re-orders within-group "
-            "by matched-label declared order. Items whose linked vBRIEF is "
-            "blocked (status:blocked / unresolved depends_on) are demoted into "
-            "[BLOCKED] unless --include-blocked is passed (#1286)."
-        ),
-        usage="task triage:queue [-- --limit=N] [--include-blocked] [--repo=owner/name]",
-        flags=(
-            ("--limit N", "10", "Max rows to print."),
-            ("--include-blocked", "(off)", "Re-surface blocked items into their natural group (#1286)."),
-            ("--repo owner/name", "(git remote)", "Explicit repo override."),
-        ),
-        examples=(
-            "task triage:queue",
-            "task triage:queue -- --limit=20 --state=accept",
-            "task triage:queue -- --format=json | jq '.[] | select(.score > 5)'",
-        ),
-        see_also=(
-            "task triage:show",
-            "task triage:audit",
-            "#1119 / D11",
-        ),
-    ),
-    "task triage:audit": _entry(
-        name="task triage:audit",
-        summary="Session-summary view + slice-aware audit flags",
-        refs="(D11/D13 / #1128, #1180)",
-        description=(
-            "Audit-log surface used by D2 (#1122) for triage:summary "
-            "integration and by D4 (#1124) for cap-reached error "
-            "messages. --vbrief-staleness flags audit entries that "
-            "reference vBRIEFs newer than their last decision."
-        ),
-        usage="task triage:audit [-- --format=text|json] [--vbrief-staleness] [--since=<window>] [--action=<verb>]",
-        flags=(
-            ("--format text|json", "text", "Output shape."),
-            ("--vbrief-staleness", "(off)", "Flag entries referencing newer vBRIEFs."),
-            ("--since WINDOW", "(all)", "Time window (e.g. '24h', '7d')."),
-            ("--action VERB", "(all)", "Filter by audit verb."),
-            ("--repo owner/name", "(git remote)", "Explicit repo override."),
-        ),
-        examples=(
-            "task triage:audit",
-            "task triage:audit -- --format=json --since=7d",
-        ),
-        see_also=(
-            "task triage:queue",
-            "task triage:history",
-            "#1119 / D11",
-        ),
-    ),
-    "task triage:show": _entry(
-        name="task triage:show",
-        summary="Per-issue detail with optional drift diff",
-        refs="(D11 / #1128)",
-        description=(
-            "Per-issue read-only detail (cached upstream payload + "
-            "latest triage decision + audit timeline). Useful before "
-            "running triage:accept / triage:defer to confirm context."
-        ),
-        usage="task triage:show -- <N> [--repo=owner/name]",
-        flags=(
-            ("<N>", "(required)", "Issue number (positional)."),
-            ("--repo owner/name", "(git remote)", "Explicit repo override."),
-        ),
-        examples=(
-            "task triage:show -- 42",
-            "task triage:show -- 42 --repo deftai/directive",
-        ),
-        see_also=(
-            "task triage:queue",
-            "task triage:status",
-            "#1119 / D11",
-        ),
-    ),
-    "task triage:scope": _entry(
-        name="task triage:scope",
-        summary="Active subscription inspection",
-        refs="(D12 / #1131, D14 / #1133, D14c / #1182)",
-        description=(
-            "Inspect / mutate / diff the typed plan.policy.triageScope[] "
-            "subscription and the triageScopeIgnores[] companion list. "
-            "Defaults to read-only --list."
-        ),
-        usage="task triage:scope -- [--list] [--add-label=L | --add-milestone=M | --ignore-label=L] [--diff-from-upstream --repo OWNER/NAME] [--refresh-denominator --repo OWNER/NAME --count N]",
-        flags=(
-            ("--list", "(default)", "Print the active subscription rules."),
-            ("--add-label L", "(none)", "Append a label rule to the subscription."),
-            ("--add-milestone M", "(none)", "Append a milestone rule."),
-            ("--ignore-label L", "(none)", "Append a label to triageScopeIgnores[]."),
-            ("--diff-from-upstream", "(off)", "Diff cached scope vs live upstream."),
-            ("--repo owner/name", "(git remote)", "Required for --diff-from-upstream."),
-        ),
-        examples=(
-            "task triage:scope",
-            "task triage:scope -- --add-label='area:swarm'",
-        ),
-        see_also=(
-            "task triage:subscribe",
-            "task triage:scope-drift",
-            "#1119 / D12",
-        ),
-    ),
-    "task triage:scope-drift": _entry(
-        name="task triage:scope-drift",
-        summary="Detect labels/milestones outside subscription",
-        refs="(D14 / #1133)",
-        description=(
-            "Detect subscription drift: labels / milestones that appear "
-            "on cached open issues but are NOT in plan.policy.triageScope. "
-            "Suggests `task triage:subscribe` follow-ups or explicit "
-            "ignore-list mutations."
-        ),
-        usage="task triage:scope-drift [-- --ignore-label=L | --ignore-milestone=M]",
-        flags=(
-            ("--ignore-label L", "(none)", "Append label to triageScopeIgnores[]."),
-            ("--ignore-milestone M", "(none)", "Append milestone to triageScopeIgnores[]."),
-        ),
-        examples=(
-            "task triage:scope-drift",
-            "task triage:scope-drift -- --ignore-label='wontfix'",
-        ),
-        see_also=(
-            "task triage:scope",
-            "task triage:subscribe",
-            "#1119 / D14",
-        ),
-    ),
-    "task triage:classify": _entry(
-        name="task triage:classify",
-        summary="Inspect / validate auto-classification surface",
-        refs="(D10 / #1129)",
-        description=(
-            "Inspect or validate the auto-classification rule set. "
-            "--list renders effective rules (framework universal first, "
-            "consumer overrides next). --validate exits non-zero on a "
-            "malformed plan.policy.triageAutoClassify."
-        ),
-        usage="task triage:classify -- [--list | --validate]",
-        flags=(
-            ("--list", "(default)", "Print effective rules + hold markers."),
-            ("--validate", "(off)", "Validate plan.policy.triageAutoClassify."),
-        ),
-        examples=(
-            "task triage:classify -- --list",
-            "task triage:classify -- --validate",
-        ),
-        see_also=(
-            "task triage:bootstrap",
-            "task triage:queue",
-            "#1119 / D10",
-        ),
-    ),
-    # --- Lifecycle -------------------------------------------------------
-    "task triage:bootstrap": _entry(
-        name="task triage:bootstrap",
-        summary="Populate cache + auto-classify",
-        refs="(D10 / #845 Story 6)",
-        description=(
-            "Idempotent bootstrap installer: populates the unified cache "
-            "via cache:fetch-all, runs auto-classification, and emits a "
-            "structured recap. --json emits one object per step for "
-            "scripted consumers."
-        ),
-        usage="task triage:bootstrap [-- --repo owner/name] [--state STR] [--limit N] [--batch-size N] [--delay-ms N] [--fetch-timeout-s S] [--quiet] [--json]",
-        flags=(
-            ("--repo owner/name", "(git remote)", "Upstream repo to populate."),
-            ("--state STR", "open", "Issue state filter forwarded to cache:fetch-all."),
-            ("--limit N", "(none)", "Cap on issues fetched."),
-            ("--fetch-timeout-s S", "(env, 300)", "Watchdog wall-clock cap (#952)."),
-            ("--quiet", "(off)", "Suppress per-step progress lines."),
-            ("--json", "(off)", "Structured JSON output."),
-        ),
-        examples=(
-            "task triage:bootstrap",
-            "task triage:bootstrap -- --repo deftai/directive --limit 50",
-        ),
-        see_also=(
-            "task triage:welcome",
-            "task triage:classify",
-            "task cache:fetch-all",
-            "#1119 / D10",
-        ),
-    ),
-    "task triage:welcome": _entry(
-        name="task triage:welcome",
-        summary="Single-entry-point upgrade ritual",
-        refs="(N3 / #1143)",
-        description=(
-            "6-phase onboarding ritual: detect prior state, prompt for "
-            "subscription scope, run triage:bootstrap, prompt for "
-            "wipCap, offer WIP relief, print triage:summary. Idempotent "
-            "on re-run; safe entrypoint for fresh consumers."
-        ),
-        usage="task triage:welcome [-- --no-subprocess]",
-        flags=(
-            ("--no-subprocess", "(off)", "Dry-mode: don't shell out to sibling tasks."),
-        ),
-        examples=(
-            "task triage:welcome",
-        ),
-        see_also=(
-            "task triage:bootstrap",
-            "task triage:summary",
-            "#1119 / N3",
-        ),
-    ),
-    "task triage:reconcile": _entry(
-        name="task triage:reconcile",
-        summary="Self-heal audit log from on-disk vBRIEFs",
-        refs="(#1468)",
-        description=(
-            "Idempotent repair verb: derive missing `accept` decisions "
-            "for proposed/pending/active vBRIEFs that carry an "
-            "x-vbrief/github-issue reference but have no entry in "
-            "vbrief/.eval/candidates.jsonl. Recovers triage state after "
-            "the gitignored audit log is reset/lost (#1464) without a "
-            "full cache re-fetch. Never overrides an existing decision, "
-            "so a re-run is a no-op."
-        ),
-        usage="task triage:reconcile [-- --repo owner/name] [--dry-run] [--json]",
-        flags=(
-            ("--repo owner/name", "(ref URI / git remote)", "Fallback repo for refs lacking owner/name."),
-            ("--dry-run", "(off)", "Report what would be restored without writing."),
-            ("--json", "(off)", "Structured JSON output."),
-        ),
-        examples=(
-            "task triage:reconcile -- --dry-run",
-            "task triage:reconcile -- --repo deftai/directive",
-        ),
-        see_also=(
-            "task triage:summary",
-            "task triage:bootstrap",
-            "#1119 / #1468",
-        ),
-    ),
-    # --- Bulk variants (#845 Story 4) ------------------------------------
-    "task triage:bulk-accept": _entry(
-        name="task triage:bulk-accept",
-        summary="Bulk accept cached candidates by filter",
-        refs="(#845 Story 4 / #915)",
-        description=(
-            "Bulk-accept every cached candidate matching the supplied "
-            "filters. Terminal records (accept/reject/mark-duplicate) "
-            "ALWAYS short-circuit. Add --re-action to act on issues "
-            "whose LATEST audit record is defer/needs-ac."
-        ),
-        usage="task triage:bulk-accept -- --repo OWNER/NAME [--label L] [--author A] [--age-days N] [--cluster C] [--re-action]",
-        flags=(
-            ("--repo OWNER/NAME", "(required)", "Upstream repo."),
-            ("--label L", "(none)", "Filter: only issues carrying this label."),
-            ("--author A", "(none)", "Filter: only issues by this author."),
-            ("--age-days N", "(none)", "Filter: only issues older than N days."),
-            ("--cluster C", "(none)", "Filter: only issues tagged cluster:<C>."),
-            ("--re-action", "(off)", "Re-action defer/needs-ac records."),
-        ),
-        examples=(
-            "task triage:bulk-accept -- --repo deftai/directive --label good-first-issue",
-        ),
-        see_also=(
-            "task triage:accept",
-            "task triage:bulk-defer",
-            "#1119 / #845",
-        ),
-    ),
-    "task triage:bulk-reject": _entry(
-        name="task triage:bulk-reject",
-        summary="Bulk reject cached candidates by filter",
-        refs="(#845 Story 4 / #915)",
-        description=(
-            "Bulk-reject every cached candidate matching the filters. "
-            "--reason is required and is recorded both in the audit log "
-            "and on the upstream close comment."
-        ),
-        usage="task triage:bulk-reject -- --repo OWNER/NAME --reason 'why' [--label L] [--author A] [--age-days N] [--cluster C] [--re-action]",
-        flags=(
-            ("--repo OWNER/NAME", "(required)", "Upstream repo."),
-            ("--reason 'why'", "(required)", "Reason recorded on close comments."),
-            ("--label L", "(none)", "Filter: only issues with this label."),
-            ("--re-action", "(off)", "Re-action defer/needs-ac records."),
-        ),
-        examples=(
-            "task triage:bulk-reject -- --repo deftai/directive --reason 'no longer relevant' --age-days 365",
-        ),
-        see_also=(
-            "task triage:reject",
-            "task triage:bulk-accept",
-            "#1119 / #845",
-        ),
-    ),
-    "task triage:bulk-defer": _entry(
-        name="task triage:bulk-defer",
-        summary="Bulk defer cached candidates by filter",
-        refs="(#845 Story 4 / #915)",
-        description=(
-            "Bulk-defer every cached candidate matching the filters. "
-            "Use --re-action to re-action issues whose latest record "
-            "is already defer/needs-ac."
-        ),
-        usage="task triage:bulk-defer -- --repo OWNER/NAME [--label L] [--author A] [--age-days N] [--cluster C] [--re-action]",
-        flags=(
-            ("--repo OWNER/NAME", "(required)", "Upstream repo."),
-            ("--label L", "(none)", "Filter: only issues with this label."),
-            ("--re-action", "(off)", "Re-action defer/needs-ac records."),
-        ),
-        examples=(
-            "task triage:bulk-defer -- --repo deftai/directive --label needs-design",
-        ),
-        see_also=(
-            "task triage:defer",
-            "task triage:bulk-accept",
-            "#1119 / #845",
-        ),
-    ),
-    "task triage:bulk-needs-ac": _entry(
-        name="task triage:bulk-needs-ac",
-        summary="Bulk needs-ac cached candidates by filter",
-        refs="(#845 Story 4 / #915)",
-        description=(
-            "Bulk-needs-ac every cached candidate matching the filters; "
-            "posts the canned AC-request comment upstream on each."
-        ),
-        usage="task triage:bulk-needs-ac -- --repo OWNER/NAME [--label L] [--author A] [--age-days N] [--cluster C] [--re-action]",
-        flags=(
-            ("--repo OWNER/NAME", "(required)", "Upstream repo."),
-            ("--label L", "(none)", "Filter: only issues with this label."),
-            ("--re-action", "(off)", "Re-action defer/needs-ac records."),
-        ),
-        examples=(
-            "task triage:bulk-needs-ac -- --repo deftai/directive --age-days 30",
-        ),
-        see_also=(
-            "task triage:needs-ac",
-            "#1119 / #845",
-        ),
-    ),
-    "task triage:refresh-active": _entry(
-        name="task triage:refresh-active",
-        summary="Pre-swarm freshness gate for vbrief/active/",
-        refs="(#845 Story 4)",
-        description=(
-            "Detect drift between cached and live `gh issue view` for "
-            "every issue referenced from vbrief/active/*.vbrief.json. "
-            "Interactive prompts on each drift: proceed-with-stale, "
-            "refresh-and-update-local, or defer-from-this-batch."
-        ),
-        usage="task triage:refresh-active [-- --project-root PATH]",
-        flags=(
-            ("--project-root PATH", "(cwd)", "Project root containing vbrief/active/."),
-        ),
-        examples=(
-            "task triage:refresh-active",
-        ),
-        see_also=(
-            "task verify:cache-fresh",
-            "task triage:audit",
-            "#1119 / #845",
-        ),
-    ),
-    "task triage:smoketest": _entry(
-        name="task triage:smoketest",
-        summary="End-to-end synthetic smoketest (hermetic)",
-        refs="(N6 / #1146)",
-        description=(
-            "End-to-end synthetic test of the cache-as-operator-"
-            "working-set surface. Runs the full triage lifecycle against "
-            "the bundled fixture and asserts the expected audit-log "
-            "shape at every stage. Exit 0 on PASS, 1 on first failure."
-        ),
-        usage="task triage:smoketest [-- --verbose] [--keep-tempdir] [--cache-only]",
-        flags=(
-            ("--verbose", "(off)", "Print each assertion to stderr as it runs."),
-            ("--keep-tempdir", "(off)", "Don't clean up the temp working dir on exit."),
-            ("--cache-only", "(off)", "Skip vBRIEF-mutating stages (faster)."),
-        ),
-        examples=(
-            "task triage:smoketest",
-            "task triage:smoketest -- --cache-only --verbose",
-        ),
-        see_also=(
-            "task triage:bootstrap",
-            "#1119 / N6",
-        ),
-    ),
-    # --- Subscription mutation ------------------------------------------
-    "task triage:subscribe": _entry(
-        name="task triage:subscribe",
-        summary="Add label/milestone/issue to subscription",
-        refs="(D14 / #1133)",
-        description=(
-            "Subscribe to a label / milestone / issue by appending a "
-            "rule to plan.policy.triageScope[]. Emits a JSONL audit "
-            "record to vbrief/.eval/subscription-history.jsonl."
-        ),
-        usage="task triage:subscribe -- (--label=L | --milestone=M | --issue=N)",
-        flags=(
-            ("--label L", "(none)", "Subscribe to a label."),
-            ("--milestone M", "(none)", "Subscribe to a milestone."),
-            ("--issue N", "(none)", "Subscribe to a single issue."),
-        ),
-        examples=(
-            "task triage:subscribe -- --label='area:swarm'",
-            "task triage:subscribe -- --milestone='v0.32.0'",
-        ),
-        see_also=(
-            "task triage:unsubscribe",
-            "task triage:scope",
-            "#1119 / D14",
-        ),
-    ),
-    "task triage:unsubscribe": _entry(
-        name="task triage:unsubscribe",
-        summary="Remove label/milestone/issue from subscription",
-        refs="(D14 / #1133)",
-        description=(
-            "Unsubscribe a label / milestone / issue by removing the "
-            "matching rule from plan.policy.triageScope[]. Idempotent "
-            "(no-op on already-missing entries). Emits a JSONL audit "
-            "record."
-        ),
-        usage="task triage:unsubscribe -- (--label=L | --milestone=M | --issue=N)",
-        flags=(
-            ("--label L", "(none)", "Unsubscribe a label."),
-            ("--milestone M", "(none)", "Unsubscribe a milestone."),
-            ("--issue N", "(none)", "Unsubscribe a single issue."),
-        ),
-        examples=(
-            "task triage:unsubscribe -- --label='area:swarm'",
-        ),
-        see_also=(
-            "task triage:subscribe",
-            "task triage:scope",
-            "#1119 / D14",
-        ),
-    ),
-    # --- Archive / rotation (forward-looking placeholders) --------------
-    "task triage:audit:prune": _entry(
-        name="task triage:audit:prune",
-        summary="Operator-invoked archive of closed-terminal entries",
-        refs="(D19, coming)",
-        description=(
-            "Move closed-terminal audit entries (accept/reject/"
-            "mark-duplicate after the upstream issue is closed) into "
-            "the archive sidecar so the live cache stays focused on "
-            "open work."
-        ),
-        usage="task triage:audit:prune [-- --dry-run] [--older-than-days N]",
-        flags=(
-            ("--dry-run", "(off)", "Preview eligible entries without writing."),
-            ("--older-than-days N", "30", "Age threshold."),
-        ),
-        examples=(
-            "task triage:audit:prune -- --dry-run",
-        ),
-        see_also=(
-            "task triage:archive-list",
-            "task triage:restore-from-archive",
-            "#1119 / D19",
-        ),
-        placeholder=True,
-    ),
-    "task triage:archive-list": _entry(
-        name="task triage:archive-list",
-        summary="List archived entries",
-        refs="(D19, coming)",
-        description=(
-            "Read-only listing of archived audit entries from the "
-            "archive sidecar. Useful before restoring an entry."
-        ),
-        usage="task triage:archive-list [-- --since=WINDOW]",
-        flags=(
-            ("--since WINDOW", "(all)", "Time window (e.g. '30d', '6mo')."),
-        ),
-        examples=(
-            "task triage:archive-list",
-        ),
-        see_also=(
-            "task triage:audit:prune",
-            "#1119 / D19",
-        ),
-        placeholder=True,
-    ),
-    "task triage:restore-from-archive": _entry(
-        name="task triage:restore-from-archive",
-        summary="Restore archived entry to live cache",
-        refs="(D19, coming)",
-        description=(
-            "Move an archived entry back to the live audit log so it "
-            "becomes visible to triage:queue / triage:audit again."
-        ),
-        usage="task triage:restore-from-archive -- <N>",
-        flags=(
-            ("<N>", "(required)", "Archived entry number to restore."),
-        ),
-        examples=(
-            "task triage:restore-from-archive -- 42",
-        ),
-        see_also=(
-            "task triage:archive-list",
-            "#1119 / D19",
-        ),
-        placeholder=True,
-    ),
-    "task triage:audit-log:rotate": _entry(
-        name="task triage:audit-log:rotate",
-        summary="Rotate candidates.jsonl when bounded",
-        refs="(D20, coming)",
-        description=(
-            "Rotate vbrief/.eval/candidates.jsonl when it exceeds the "
-            "configured bound. Compacts terminal entries and preserves "
-            "the open-work tail."
-        ),
-        usage="task triage:audit-log:rotate [-- --max-lines N]",
-        flags=(
-            ("--max-lines N", "(consumer default)", "Bound at which rotation fires."),
-        ),
-        examples=(
-            "task triage:audit-log:rotate -- --max-lines 10000",
-        ),
-        see_also=(
-            "task triage:audit:prune",
-            "#1119 / D20",
-        ),
-        placeholder=True,
-    ),
-    "task triage:metrics": _entry(
-        name="task triage:metrics",
-        summary="Trend lines from summary-history.jsonl",
-        refs="(D17, coming)",
-        description=(
-            "Print trend lines computed from "
-            "vbrief/.eval/summary-history.jsonl: decisions-per-day, "
-            "defer/accept ratio, stale-defer drift, etc."
-        ),
-        usage="task triage:metrics [-- --window=7d] [--format=text|json]",
-        flags=(
-            ("--window WINDOW", "7d", "Time window over which to aggregate."),
-            ("--format text|json", "text", "Output shape."),
-        ),
-        examples=(
-            "task triage:metrics -- --window 30d",
-        ),
-        see_also=(
-            "task triage:summary",
-            "#1119 / D17",
-        ),
-        placeholder=True,
-    ),
-    # --- Scope lifecycle verbs (#845, D1, D15, D18) ----------------------
-    "task scope:promote": _entry(
-        name="task scope:promote",
-        summary="proposed/ -> pending/ (set status pending)",
-        refs="(#845, D18 / #1119)",
-        description=(
-            "Promote a vBRIEF scope from vbrief/proposed/ to "
-            "vbrief/pending/ and set plan.status='pending'. D18 adds "
-            "--from-issue=N for cache-reciprocity-checked promotion."
-        ),
-        usage="task scope:promote -- <file> [--force] | task scope:promote -- --from-issue=N",
-        flags=(
-            ("<file>", "(required)", "Path to vBRIEF (relative resolved against project root)."),
-            ("--from-issue=N", "(none)", "Promote with cache-reciprocity check (D18)."),
-            ("--force", "(off)", "Override the WIP cap (#1124 / D4); records audit entry."),
-            ("--project-root PATH", "(detected)", "Consumer project root override."),
-        ),
-        examples=(
-            "task scope:promote -- vbrief/proposed/2026-05-19-foo.vbrief.json",
-            "task scope:promote -- --from-issue=1150",
-        ),
-        see_also=(
-            "task scope:demote",
-            "task scope:activate",
-            "task vbrief:activate",
-            "#1119 / D18",
-        ),
-    ),
-    "task scope:demote": _entry(
-        name="task scope:demote",
-        summary="pending/ -> proposed/ (set status proposed)",
-        refs="(D1 / #1121)",
-        description=(
-            "Demote a vBRIEF scope from vbrief/pending/ back to "
-            "vbrief/proposed/ and append a structured audit entry "
-            "(including a demote_meta block) to "
-            "vbrief/.eval/scope-lifecycle.jsonl. Supports single-file "
-            "and --batch (cohort shrink / cap relief) modes."
-        ),
-        usage="task scope:demote -- <file> [--reason TEXT] | task scope:demote -- --batch [--older-than-days N]",
-        flags=(
-            ("<file>", "(required for single)", "Path to vBRIEF."),
-            ("--batch", "(off)", "Batch mode: demote every pending older than --older-than-days."),
-            ("--older-than-days N", "45", "Batch-mode age threshold."),
-            ("--reason TEXT", "operator-requested", "Free-text reason for single-demote."),
-            ("--actor STR", "operator", "Actor identity recorded in the audit entry."),
-        ),
-        examples=(
-            "task scope:demote -- vbrief/pending/2026-05-19-foo.vbrief.json",
-            "task scope:demote -- --batch --older-than-days 60",
-        ),
-        see_also=(
-            "task scope:undo",
-            "task scope:promote",
-            "#1119 / D1",
-        ),
-    ),
-    "task scope:activate": _entry(
-        name="task scope:activate",
-        summary="pending/ -> active/ (set status running)",
-        refs="(#845)",
-        description=(
-            "Activate a pending vBRIEF: move to vbrief/active/ and set "
-            "plan.status='running'. Required step before "
-            "vbrief:preflight will exit 0 (the #810 implementation "
-            "intent gate)."
-        ),
-        usage="task scope:activate -- <file>",
-        flags=(
-            ("<file>", "(required)", "Path to vBRIEF."),
-            ("--project-root PATH", "(detected)", "Consumer project root override."),
-        ),
-        examples=(
-            "task scope:activate -- vbrief/pending/2026-05-19-foo.vbrief.json",
-        ),
-        see_also=(
-            "task vbrief:activate",
-            "task scope:complete",
-            "#1119 / #845",
-        ),
-    ),
-    "task scope:complete": _entry(
-        name="task scope:complete",
-        summary="active/ -> completed/ (set status completed)",
-        refs="(#845)",
-        description=(
-            "Mark an active vBRIEF complete and move it to "
-            "vbrief/completed/. Terminal transition; use scope:undo if "
-            "you need reversibility (refused on terminal actions per "
-            "D15)."
-        ),
-        usage="task scope:complete -- <file>",
-        flags=(
-            ("<file>", "(required)", "Path to vBRIEF."),
-            ("--project-root PATH", "(detected)", "Consumer project root override."),
-        ),
-        examples=(
-            "task scope:complete -- vbrief/active/2026-05-19-foo.vbrief.json",
-        ),
-        see_also=(
-            "task scope:fail",
-            "task scope:cancel",
-            "#1119 / #845",
-        ),
-    ),
-    "task scope:fail": _entry(
-        name="task scope:fail",
-        summary="active/ -> completed/ (set status failed)",
-        refs="(#845, #614)",
-        description=(
-            "Terminal failed transition. Mirrors scope:complete but "
-            "sets plan.status='failed'. Use when a scope was attempted "
-            "but could not be completed (external blocker, "
-            "infeasibility, exhausted retries) and should NOT be "
-            "cancelled."
-        ),
-        usage="task scope:fail -- <file>",
-        flags=(
-            ("<file>", "(required)", "Path to vBRIEF."),
-            ("--project-root PATH", "(detected)", "Consumer project root override."),
-        ),
-        examples=(
-            "task scope:fail -- vbrief/active/2026-05-19-foo.vbrief.json",
-        ),
-        see_also=(
-            "task scope:complete",
-            "task scope:cancel",
-            "#1119 / #845",
-        ),
-    ),
-    "task scope:cancel": _entry(
-        name="task scope:cancel",
-        summary="any -> cancelled/ (set status cancelled)",
-        refs="(#845)",
-        description=(
-            "Cancel a vBRIEF from any folder. Use when the scope is no "
-            "longer wanted / superseded / obsolete (vs scope:fail which "
-            "means \"tried and failed\")."
-        ),
-        usage="task scope:cancel -- <file>",
-        flags=(
-            ("<file>", "(required)", "Path to vBRIEF."),
-            ("--project-root PATH", "(detected)", "Consumer project root override."),
-        ),
-        examples=(
-            "task scope:cancel -- vbrief/pending/2026-05-19-foo.vbrief.json",
-        ),
-        see_also=(
-            "task scope:restore",
-            "task scope:undo",
-            "#1119 / #845",
-        ),
-    ),
-    "task scope:restore": _entry(
-        name="task scope:restore",
-        summary="cancelled/ -> proposed/ (set status proposed)",
-        refs="(#845)",
-        description=(
-            "Restore a cancelled vBRIEF back to vbrief/proposed/ "
-            "(status='proposed'). Use to re-enter the lifecycle after a "
-            "scope:cancel."
-        ),
-        usage="task scope:restore -- <file>",
-        flags=(
-            ("<file>", "(required)", "Path to vBRIEF."),
-            ("--project-root PATH", "(detected)", "Consumer project root override."),
-        ),
-        examples=(
-            "task scope:restore -- vbrief/cancelled/2026-05-19-foo.vbrief.json",
-        ),
-        see_also=(
-            "task scope:cancel",
-            "task scope:promote",
-            "#1119 / #845",
-        ),
-    ),
-    "task scope:block": _entry(
-        name="task scope:block",
-        summary="stays in active/ (set status blocked)",
-        refs="(#845)",
-        description=(
-            "Mark an active scope as blocked without moving it out of "
-            "active/. Use when waiting on an external dependency."
-        ),
-        usage="task scope:block -- <file>",
-        flags=(
-            ("<file>", "(required)", "Path to vBRIEF."),
-            ("--project-root PATH", "(detected)", "Consumer project root override."),
-        ),
-        examples=(
-            "task scope:block -- vbrief/active/2026-05-19-foo.vbrief.json",
-        ),
-        see_also=(
-            "task scope:unblock",
-            "#1119 / #845",
-        ),
-    ),
-    "task scope:unblock": _entry(
-        name="task scope:unblock",
-        summary="stays in active/ (set status running)",
-        refs="(#845)",
-        description=(
-            "Clear a blocked status on an active scope, returning it "
-            "to plan.status='running'."
-        ),
-        usage="task scope:unblock -- <file>",
-        flags=(
-            ("<file>", "(required)", "Path to vBRIEF."),
-            ("--project-root PATH", "(detected)", "Consumer project root override."),
-        ),
-        examples=(
-            "task scope:unblock -- vbrief/active/2026-05-19-foo.vbrief.json",
-        ),
-        see_also=(
-            "task scope:block",
-            "#1119 / #845",
-        ),
-    ),
-    "task scope:undo": _entry(
-        name="task scope:undo",
-        summary="Undo demote/cancel/restore via audit-log id",
-        refs="(D15 / #1134)",
-        description=(
-            "Reverse a scope-lifecycle audit entry by decision_id or "
-            "every entry tagged with batch_id. Terminal actions "
-            "(complete / fail) are REFUSED -- use a fresh scope:promote "
-            "instead. Supports --dry-run preview and --latest "
-            "convenience selector."
-        ),
-        usage="task scope:undo -- <decision_id> | --decision-id=<uuid> | --batch-id=<uuid> | --latest [--dry-run]",
-        flags=(
-            ("<decision_id>", "(one of)", "Positional decision_id (shorthand for --decision-id)."),
-            ("--decision-id UUID", "(one of)", "Decision id of a single audit entry to undo."),
-            ("--batch-id UUID", "(one of)", "Reverse every entry tagged with this batch_id."),
-            ("--latest", "(one of)", "Reverse the most-recent reversible entry."),
-            ("--dry-run", "(off)", "Preview the reversal without writing."),
-            ("--actor STR", "operator", "Actor identity recorded on the new undo entry."),
-        ),
-        examples=(
-            "task scope:undo -- --latest --dry-run",
-            "task scope:undo -- --batch-id=00000000-0000-0000-0000-000000000001",
-        ),
-        see_also=(
-            "task scope:demote",
-            "task triage:reset",
-            "#1119 / D15",
-        ),
-    ),
-    "task scope:decompose": _entry(
-        name="task scope:decompose",
-        summary="Apply/check an approved epic story decomposition",
-        refs="(deft-directive-decompose skill)",
-        description=(
-            "Validate or apply an approved epic/phase -> story "
-            "decomposition draft. The draft is a temporary proposal "
-            "artifact, not a vBRIEF. Writes pending child vBRIEFs and "
-            "wires references back into the parent epic."
-        ),
-        usage="task scope:decompose -- <parent> --draft <draft> [--check] [--date YYYY-MM-DD]",
-        flags=(
-            (
-                "<parent>",
-                "(conditional)",
-                "Parent epic/phase vBRIEF path; required with --draft, omit only for --check no-op.",
-            ),
-            (
-                "--draft PATH",
-                "(required)",
-                "Approved decomposition JSON draft; prefer vbrief/.eval/decompositions/<parent-slug>.json.",
-            ),
-            ("--check", "(off)", "Validate only; do not write."),
-            ("--date YYYY-MM-DD", "today", "Creation date for generated child filenames."),
-        ),
-        examples=(
-            "task scope:decompose -- vbrief/active/epic.vbrief.json --draft vbrief/.eval/decompositions/epic.json --check",
-        ),
-        see_also=(
-            "task scope:promote",
-            "skills/deft-directive-decompose/SKILL.md",
-        ),
-    ),
-}
-
-
-# ---------------------------------------------------------------------------
-# Category structure for bare-list rendering
-# ---------------------------------------------------------------------------
-
-
-CATEGORIES_TRIAGE: list[tuple[str, list[str]]] = [
-    (
-        "Session-start",
-        [
-            "task triage:summary",
-            "task verify:cache-fresh",
-        ],
-    ),
-    (
-        "State verbs (mutate audit log)",
-        [
-            "task triage:accept",
-            "task triage:defer",
-            "task triage:reject",
-            "task triage:needs-ac",
-            "task triage:mark-duplicate",
-            "task triage:reset",
-            "task triage:status",
-            "task triage:history",
-        ],
-    ),
-    (
-        "Read verbs",
-        [
-            "task triage:queue",
-            "task triage:audit",
-            "task triage:show",
-            "task triage:scope",
-            "task triage:scope-drift",
-            "task triage:classify",
-        ],
-    ),
-    (
-        "Lifecycle",
-        [
-            "task triage:bootstrap",
-            "task triage:welcome",
-            "task triage:reconcile",
-        ],
-    ),
-    (
-        "Bulk variants",
-        [
-            "task triage:bulk-accept",
-            "task triage:bulk-reject",
-            "task triage:bulk-defer",
-            "task triage:bulk-needs-ac",
-            "task triage:refresh-active",
-            "task triage:smoketest",
-        ],
-    ),
-    (
-        "Subscription mutation",
-        [
-            "task triage:subscribe",
-            "task triage:unsubscribe",
-        ],
-    ),
-    (
-        "Archive / rotation",
-        [
-            "task triage:audit:prune",
-            "task triage:archive-list",
-            "task triage:restore-from-archive",
-            "task triage:audit-log:rotate",
-            "task triage:metrics",
-        ],
-    ),
-]
-
-
-CATEGORIES_SCOPE: list[tuple[str, list[str]]] = [
-    (
-        "Promote / demote",
-        [
-            "task scope:promote",
-            "task scope:demote",
-        ],
-    ),
-    (
-        "Activate / complete",
-        [
-            "task scope:activate",
-            "task scope:complete",
-            "task scope:fail",
-            "task scope:cancel",
-            "task scope:block",
-            "task scope:unblock",
-        ],
-    ),
-    (
-        "Reversibility",
-        [
-            "task scope:undo",
-            "task scope:restore",
-        ],
-    ),
-    (
-        "Decomposition",
-        [
-            "task scope:decompose",
-        ],
-    ),
-]
-
-
-# ---------------------------------------------------------------------------
-# Script -> (subcommand -> verb) mapping for the intercept_help shim
-# ---------------------------------------------------------------------------
-#
-# Each verb script is expected to call ``intercept_help(<script_name>, argv)``
-# at the very top of its ``main()``. The shim looks up the script under
-# ``SCRIPT_SUBCOMMAND_MAP`` to resolve which verb the user is running:
-#
-# * If the script has only ``{"__default__": "task triage:X"}``, the verb
-#   is fixed and we print help unconditionally on --help/-h.
-# * If the script declares subcommand entries, the shim inspects argv for
-#   the first positional non-flag arg and looks it up. The fallback when
-#   no positional matches is the ``__default__`` key (if present); otherwise
-#   ``--help`` is delegated to argparse so the user still gets *some* help.
-
-
-SCRIPT_SUBCOMMAND_MAP: dict[str, dict[str, str]] = {
-    "triage_actions": {
-        "accept": "task triage:accept",
-        "reject": "task triage:reject",
-        "defer": "task triage:defer",
-        "needs-ac": "task triage:needs-ac",
-        "mark-duplicate": "task triage:mark-duplicate",
-        "status": "task triage:status",
-        "reset": "task triage:reset",
-        "history": "task triage:history",
-    },
-    "triage_bootstrap": {"__default__": "task triage:bootstrap"},
-    "triage_bulk": {
-        "accept": "task triage:bulk-accept",
-        "reject": "task triage:bulk-reject",
-        "defer": "task triage:bulk-defer",
-        "needs-ac": "task triage:bulk-needs-ac",
-    },
-    "triage_refresh": {"__default__": "task triage:refresh-active"},
-    "triage_classify": {"__default__": "task triage:classify"},
-    "triage_scope": {"__default__": "task triage:scope"},
-    "triage_scope_drift": {"__default__": "task triage:scope-drift"},
-    # ``triage_subscribe`` is the ONLY multi-subcommand entry that also
-    # declares ``__default__``. The Taskfile (``tasks/triage-subscribe.yml``)
-    # always passes the positional (``subscribe`` or ``unsubscribe``) as the
-    # first arg, so under the documented user-facing surface the fallback
-    # never fires. The fallback exists for two off-Taskfile paths:
-    #   (1) direct invocations like ``python scripts/triage_subscribe.py --help``
-    #       (no positional) -- the operator sees ``task triage:subscribe`` help,
-    #       which is the canonical/primary verb in the subscribe<->unsubscribe
-    #       pair (you subscribe first; unsubscribe is the inverse).
-    #   (2) a hypothetical alternate Taskfile that drops the positional --
-    #       same behaviour, documented contract.
-    # Pinned by ``test_intercept_help_triage_subscribe_*`` in
-    # ``tests/test_triage_help.py``; Greptile finding 3267953653 on PR #1227.
-    # Refs #1228 (this PR's docs/coverage gap).
-    "triage_subscribe": {
-        "subscribe": "task triage:subscribe",
-        "unsubscribe": "task triage:unsubscribe",
-        "__default__": "task triage:subscribe",
-    },
-    "triage_summary": {"__default__": "task triage:summary"},
-    "triage_reconcile": {"__default__": "task triage:reconcile"},
-    "triage_queue": {
-        "queue": "task triage:queue",
-        "show": "task triage:show",
-        "audit": "task triage:audit",
-    },
-    "triage_welcome": {"__default__": "task triage:welcome"},
-    "triage_smoketest": {"__default__": "task triage:smoketest"},
-    "scope_lifecycle": {
-        "promote": "task scope:promote",
-        "activate": "task scope:activate",
-        "complete": "task scope:complete",
-        "fail": "task scope:fail",
-        "cancel": "task scope:cancel",
-        "restore": "task scope:restore",
-        "block": "task scope:block",
-        "unblock": "task scope:unblock",
-    },
-    "scope_demote": {"__default__": "task scope:demote"},
-    "scope_undo": {"__default__": "task scope:undo"},
-    "scope_decompose": {"__default__": "task scope:decompose"},
-}
-
-
-# ---------------------------------------------------------------------------
-# Renderers
-# ---------------------------------------------------------------------------
-
-
-def _format_category_row(verb: str, entry: VerbHelp, *, summary_col: int = 60) -> str:
-    """Render a single line in the bare-list category view.
-
-    ``verb`` is the user-facing form (``task triage:queue``); ``summary_col``
-    pads the summary so the cross-ref tag right-aligns.
-    """
-    prefix = f"  {verb:<28s}"
-    middle = f"{entry.summary}"
-    middle = middle if len(middle) <= summary_col else middle[: summary_col - 1] + "…"
-    padded = f"{middle:<{summary_col}s}"
-    return f"{prefix}{padded} {entry.refs}"
-
-
-def render_category_list(category: str) -> str:
-    """Render the bare-invocation categorized verb list.
-
-    ``category`` is ``"triage"`` or ``"scope"``. Raises ``ValueError`` on
-    any other value.
-    """
-    if category == "triage":
-        title = "Task triage — operator-facing cache verbs"
-        sections = CATEGORIES_TRIAGE
-        suffix = (
-            "Run any verb with --help for usage examples (e.g. "
-            "`task triage:queue --help`)."
-        )
-    elif category == "scope":
-        title = "Task scope — vBRIEF lifecycle verbs"
-        sections = CATEGORIES_SCOPE
-        suffix = (
-            "Run any verb with --help for usage examples (e.g. "
-            "`task scope:promote --help`)."
-        )
-    else:
-        raise ValueError(
-            f"unknown category {category!r}; expected 'triage' or 'scope'"
-        )
-
-    lines: list[str] = [title, ""]
-    for label, verbs in sections:
-        lines.append(f"{label}:")
-        for verb in verbs:
-            entry = REGISTRY.get(verb)
-            if entry is None:
-                # Defensive -- if a category references a verb that is
-                # not yet in the registry, surface the gap loudly.
-                lines.append(f"  {verb:<28s}(missing registry entry)")
-                continue
-            lines.append(_format_category_row(verb, entry))
-        lines.append("")
-    lines.append(suffix)
-    return "\n".join(lines)
-
-
-def render_verb_help(verb: str) -> str:
-    """Render the structured ``--help`` output for a single verb.
-
-    Raises ``KeyError`` if ``verb`` is not registered.
-    """
-    entry = REGISTRY.get(verb)
-    if entry is None:
-        raise KeyError(
-            f"unknown verb {verb!r}; not in scripts/triage_help.py REGISTRY. "
-            "Run `task triage` or `task scope` to see the catalog."
-        )
-
-    lines: list[str] = []
-    header = f"{entry.name} -- {entry.summary} {entry.refs}".rstrip()
-    lines.append(header)
-    if entry.placeholder:
-        lines.append("  (not yet implemented -- placeholder entry; see refs)")
-    lines.append("")
-    lines.append(entry.description)
-    lines.append("")
-    lines.append("Usage:")
-    lines.append(f"  {entry.usage}")
-    if entry.flags:
-        lines.append("")
-        lines.append("Flags:")
-        # Width-align the flag column for scannability.
-        flag_width = max(len(f) for f, _, _ in entry.flags)
-        flag_width = min(flag_width, 32)
-        for flag, default, desc in entry.flags:
-            head = f"  {flag:<{flag_width}s}"
-            tail = f"{desc} (default: {default})" if default else desc
-            lines.append(f"{head}  {tail}")
-    if entry.examples:
-        lines.append("")
-        lines.append("Examples:")
-        for ex in entry.examples:
-            lines.append(f"  {ex}")
-    if entry.see_also:
-        lines.append("")
-        lines.append("See also:")
-        for ref in entry.see_also:
-            lines.append(f"  {ref}")
-    return "\n".join(lines)
-
-
-# ---------------------------------------------------------------------------
-# Intercept helper used by verb scripts
-# ---------------------------------------------------------------------------
-
-
-HELP_FLAGS = ("--help", "-h")
-
-
-def _argv_or_default(argv: list[str] | None) -> list[str]:
-    return list(argv) if argv is not None else list(sys.argv[1:])
-
-
-def _has_help_flag(argv: list[str]) -> bool:
-    return any(arg in HELP_FLAGS for arg in argv)
-
-
-def _resolve_verb_from_argv(
-    script_name: str, argv: list[str]
-) -> str | None:
-    """Look up the verb for ``script_name`` based on argv.
-
-    Returns the canonical verb (e.g. ``"task triage:queue"``) or ``None``
-    if the script is unmapped or no matching subcommand was found.
-    """
-    sub_map = SCRIPT_SUBCOMMAND_MAP.get(script_name)
-    if sub_map is None:
-        return None
-    # Single-verb scripts: just take the default.
-    if "__default__" in sub_map and len(sub_map) == 1:
-        return sub_map["__default__"]
-    # Multi-subcommand scripts: find the first positional non-flag arg.
-    for arg in argv:
-        if not arg.startswith("-"):
-            verb = sub_map.get(arg)
-            if verb is not None:
-                return verb
-    # No matching positional; fall back to default if present.
-    return sub_map.get("__default__")
-
-
-def intercept_help(
-    script_name: str,
-    argv: list[str] | None = None,
-    *,
-    out: object | None = None,
-) -> int | None:
-    """Print structured help and return 0 if ``--help`` / ``-h`` is in argv.
-
-    Verb scripts call this at the top of ``main()``::
-
-        def main(argv=None):
-            rc = intercept_help("triage_queue", argv)
-            if rc is not None:
-                return rc
-            ...
-
-    Returns ``None`` when no help flag was found (caller proceeds with
-    argparse). Returns ``0`` after printing structured help; the caller
-    should propagate that exit code so argparse never runs.
-
-    ``out`` is for tests -- defaults to ``sys.stdout``. Anything with a
-    ``write`` method works.
-    """
-    args = _argv_or_default(argv)
-    if not _has_help_flag(args):
-        return None
-
-    verb = _resolve_verb_from_argv(script_name, args)
-    sink = out if out is not None else sys.stdout
-    if verb is None or verb not in REGISTRY:
-        # Unmapped script or unknown subcommand: print the appropriate
-        # category catalog hint and let argparse take over by returning
-        # None. (We intentionally do NOT swallow --help for scripts that
-        # are outside our registry; the existing argparse --help should
-        # still run.)
-        return None
-    try:
-        sink.write(render_verb_help(verb) + "\n")
-    except (KeyError, ValueError) as exc:  # pragma: no cover -- defensive
-        sink.write(f"triage_help: {exc}\n")
-        return 2
-    return 0
-
-
-# ---------------------------------------------------------------------------
-# CLI entrypoint -- python -m scripts.triage_help <category|help|list>
-# ---------------------------------------------------------------------------
-
-
-_USAGE = (
-    "usage: python -m scripts.triage_help <triage|scope|help <verb>|list>\n"
-    "\n"
-    "  triage              Print the categorized triage verb list.\n"
-    "  scope               Print the categorized scope verb list.\n"
-    "  help <verb>         Print structured help for a single verb.\n"
-    "                      Accepts both 'task triage:queue' and 'triage:queue'.\n"
-    "  list                Print every registered verb (tooling discovery).\n"
-)
-
-
-def _normalize_verb_arg(raw: str) -> str:
-    """Accept both ``triage:queue`` and ``task triage:queue`` forms."""
-    raw = raw.strip()
-    if raw.startswith("task "):
-        return raw
-    return f"task {raw}"
-
-
-def main(argv: list[str] | None = None) -> int:  # noqa: PLR0911
-    args = _argv_or_default(argv)
-    if not args:
-        sys.stderr.write(_USAGE)
-        return 2
-    head, *rest = args
-    if head in ("-h", "--help"):
-        sys.stdout.write(_USAGE)
-        return 0
-    if head == "triage":
-        sys.stdout.write(render_category_list("triage") + "\n")
-        return 0
-    if head == "scope":
-        sys.stdout.write(render_category_list("scope") + "\n")
-        return 0
-    if head == "list":
-        for verb in sorted(REGISTRY):
-            entry = REGISTRY[verb]
-            tag = " [coming]" if entry.placeholder else ""
-            sys.stdout.write(f"{verb}{tag}\n")
-        return 0
-    if head == "help":
-        if not rest:
-            sys.stderr.write(
-                "triage_help: missing <verb> argument for `help`.\n"
-            )
-            sys.stderr.write(_USAGE)
-            return 2
-        verb = _normalize_verb_arg(rest[0])
-        if verb not in REGISTRY:
-            sys.stderr.write(
-                f"triage_help: unknown verb {verb!r}. "
-                "Run `python -m scripts.triage_help list` to see all "
-                "registered verbs.\n"
-            )
-            return 2
-        sys.stdout.write(render_verb_help(verb) + "\n")
-        return 0
-    sys.stderr.write(f"triage_help: unknown command {head!r}.\n")
-    sys.stderr.write(_USAGE)
-    return 2
-
-
-if __name__ == "__main__":
-    sys.exit(main())