@paths.design/caws-cli 11.1.7 → 11.1.8

package/dist/shell/command-metadata.js

@@ -0,0 +1,687 @@
+"use strict";
+// Single-source command metadata for the v11 CLI surface
+// (CAWS-CLI-HELP-METADATA-AUTHORITY-001).
+//
+// PROBLEM this solves: every `.description()` / `.argument()` / `.option()`
+// in register.ts is a hand-authored string literal with no binding to the
+// command's actual behavior. They drift (e.g. `specs archive --help` said
+// "moves the YAML to .archive/" long after archive became a tombstone). This
+// module makes the help metadata a typed, single-authority object that
+// register.ts consumes, so:
+//   - description prose lives co-located with the handler it describes
+//     (each commands/<group>.ts exports its own *_COMMAND_META),
+//   - enum-backed option values (--mode, --resolution, ...) are DERIVED from
+//     the kernel enum arrays (SPEC_MODES, etc.) rather than re-typed, and a
+//     lock test asserts they equal the kernel/schema enums,
+//   - a lock test asserts the metadata group set equals
+//     REGISTERED_COMMAND_GROUPS and that register.ts carries no inline
+//     description/option string literals.
+//
+// STAGING (this is slice 1): this module defines the interfaces and exports
+// an EMPTY frozen COMMAND_SURFACE_METADATA. register.ts is NOT yet refactored
+// to consume it (that is slices 2-3, group by group). The interface shapes
+// are stable; later slices only ADD entries.
+//
+// What is machine-derivable vs. hand-authored:
+//   - DERIVABLE (lock-tested against the kernel/schema): option `allowedValues`
+//     for enum flags, the group-name set, option required-ness.
+//   - HAND-AUTHORED (no schema source; co-located with the handler): the
+//     behavioral description prose ("tombstone, not move"; "does NOT run git
+//     push"). The lock test cannot verify prose accuracy — co-location +
+//     same-slice scope.in is the discipline that keeps it honest.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.COMMAND_SURFACE_METADATA = exports.AGENTS_COMMAND_META = exports.WAIVER_COMMAND_META = exports.EVENTS_COMMAND_META = exports.EVIDENCE_COMMAND_META = exports.GATES_COMMAND_META = exports.SCOPE_COMMAND_META = exports.PREPUSH_COMMAND_META = exports.CLAIM_COMMAND_META = exports.STATUS_COMMAND_META = exports.DOCTOR_COMMAND_META = exports.INIT_COMMAND_META = exports.WORKTREE_COMMAND_META = exports.SPECS_COMMAND_META = void 0;
+const caws_kernel_1 = require("@paths.design/caws-kernel");
+/**
+ * The `--data` option appears on every leaf command in the surface. Declaring
+ * it once keeps the per-command metadata focused on what is distinctive.
+ */
+const DATA_OPTION = {
+    flag: '--data',
+    description: 'Show structured data block on diagnostics',
+};
+// ─── specs group (CLI-SPECS-001) ──────────────────────────────────────────
+// Co-located authority for `caws specs` help. The descriptions here are the
+// single source consumed by register.ts; the option `allowedValues` derive
+// from the kernel enum arrays (SPEC_MODES / SPEC_RESOLUTIONS / RISK_TIERS) so
+// --mode/--resolution/--risk-tier help cannot drift from the validation enums.
+exports.SPECS_COMMAND_META = {
+    kind: 'group',
+    name: 'specs',
+    description: 'Manage CAWS spec lifecycle (create/list/show/recover/retire-draft/activate/close/archive/prune-archive/migrate)',
+    subcommands: [
+        {
+            kind: 'leaf',
+            name: 'create',
+            argument: { name: 'id', required: true, description: 'Spec id to create' },
+            description: 'Create a new spec in lifecycle_state: active.',
+            // W3: --title/--mode/--risk-tier are functionally required, but the
+            // handler (runSpecsCreateCommand) owns the missing-args check so it can
+            // emit rich guidance (usage block + --type hint) that Commander's
+            // .requiredOption() pre-validation would degrade. So we mark them
+            // "(required)" in prose and keep them .option() — help states the
+            // requirement; the handler enforces it.
+            options: [
+                { flag: '--title <title>', description: 'Short spec title (required)' },
+                {
+                    flag: '--mode <mode>',
+                    description: 'Spec mode (required)',
+                    allowedValues: caws_kernel_1.SPEC_MODES,
+                },
+                {
+                    flag: '--risk-tier <n>',
+                    description: 'Risk tier (required)',
+                    allowedValues: caws_kernel_1.RISK_TIERS,
+                },
+                {
+                    flag: '--type <type>',
+                    description: 'Removed v10 alias; use --mode <feature|refactor|fix|doc|chore> instead',
+                },
+                DATA_OPTION,
+            ],
+        },
+        {
+            kind: 'leaf',
+            name: 'list',
+            description: 'List specs. By default excludes archived specs.',
+            options: [
+                { flag: '--archived', description: 'Include archived specs in the listing' },
+                DATA_OPTION,
+            ],
+        },
+        {
+            kind: 'leaf',
+            name: 'show',
+            argument: { name: 'id', required: true, description: 'Spec id to show' },
+            description: 'Show a spec by id. Defaults to active specs only; pass --archived to recover an archived spec body from the event log + git history.',
+            options: [
+                DATA_OPTION,
+                {
+                    flag: '--archived',
+                    description: 'Recover an archived spec body via the event log + git show <blob_sha>. The body is NOT loaded from .caws/specs/.archive/ (which the post-CAWS-ARCHIVE-AS-TOMBSTONE-001 archive flow does not write).',
+                },
+            ],
+        },
+        {
+            kind: 'leaf',
+            name: 'recover',
+            argument: { name: 'id', required: true, description: 'Archived spec id to recover' },
+            description: 'Recover an archived spec body via the event log + git show <blob_sha>. Topology-independent (works with merge commits, rebases, cherry-picks). Reads .caws/events.jsonl for the spec_archived event, validates the blob_sha, runs git show, prints to stdout (or --out <path>). Does NOT mutate .caws/specs/.',
+            options: [
+                DATA_OPTION,
+                {
+                    flag: '--out <path>',
+                    description: 'Write the recovered body to this path instead of stdout',
+                },
+            ],
+        },
+        {
+            kind: 'leaf',
+            name: 'retire-draft',
+            argument: { name: 'id', required: true, description: 'Draft spec id to retire' },
+            description: 'Retire a never-activated DRAFT spec via tombstone. Refuses active (use close), closed (use archive), and archived specs. Deletes the draft YAML and appends a recoverable spec_retired event (recover via caws specs show <id> --archived). The governed alternative to raw git rm.',
+            options: [
+                { flag: '--reason <text>', description: 'Optional human-readable retirement note' },
+                DATA_OPTION,
+            ],
+        },
+        {
+            kind: 'leaf',
+            name: 'activate',
+            argument: { name: 'id', required: true, description: 'Draft spec id to activate' },
+            description: 'Activate a pre-authored draft spec. Draft-only: patches lifecycle_state to active and appends spec_activated.',
+            options: [DATA_OPTION],
+        },
+        {
+            kind: 'leaf',
+            name: 'close',
+            argument: { name: 'id', required: true, description: 'Active spec id to close' },
+            description: 'Close an active spec. Non-destructive raw-byte YAML patch; appends spec_closed event.',
+            options: [
+                {
+                    flag: '--resolution <r>',
+                    description: 'Resolution',
+                    allowedValues: caws_kernel_1.SPEC_RESOLUTIONS,
+                    defaultValue: 'completed',
+                },
+                {
+                    flag: '--reason <text>',
+                    description: 'Closure notes recorded on the spec YAML and the spec_closed event',
+                },
+                {
+                    flag: '--merge-commit <sha>',
+                    description: 'Optional merge commit SHA (e.g., when closure follows a worktree merge)',
+                },
+                {
+                    flag: '--superseded-by <id>',
+                    description: 'Spec id that supersedes this one (use with --resolution superseded)',
+                },
+                DATA_OPTION,
+            ],
+        },
+        {
+            kind: 'leaf',
+            name: 'archive',
+            argument: { name: 'id', required: true, description: 'Closed spec id to archive' },
+            description: 'Archive a closed spec (tombstone, not a move): deletes the spec YAML and appends a recoverable spec_archived event carrying its blob_sha. Recover the body with caws specs show <id> --archived or caws specs recover <id>.',
+            options: [
+                {
+                    flag: '--reason <text>',
+                    description: 'Archive reason (advisory; the spec_archived schema does not carry it)',
+                },
+                DATA_OPTION,
+            ],
+        },
+        {
+            kind: 'leaf',
+            name: 'prune-archive',
+            description: 'Migrate legacy .caws/specs/.archive/<id>.yaml bodies (CAWS-ARCHIVE-AS-TOMBSTONE-001). Dry-run by default — pass --apply to execute. Recoverable bodies (reachable via git log --follow) are removed from the working tree; unrecoverable bodies are QUARANTINED to .caws/specs/.archive/.unrecoverable/ (never silently deleted, no override flag). Emits one spec_archive_pruned event per id on --apply.',
+            options: [
+                { flag: '--apply', description: 'Execute the migration. Default is dry-run.' },
+                DATA_OPTION,
+            ],
+        },
+        {
+            kind: 'leaf',
+            name: 'migrate',
+            description: 'v10→v11 spec YAML migrator (CAWS-MIGRATE-V10-SPECS-001). Default is dry-run; --apply opts into mutation. --apply without --partial refuses if any spec hits a "refused" verdict. --apply --partial writes migratable specs, skips refused, emits a durable JSON report under .caws/migrations/v10-specs/.',
+            options: [
+                {
+                    flag: '--from <version>',
+                    required: true,
+                    description: 'Source schema version (only v10 is supported in v11.2)',
+                },
+                { flag: '--apply', description: 'Write migrated YAMLs to disk (default: dry-run)' },
+                {
+                    flag: '--partial',
+                    description: 'Allow apply to proceed even when some specs are refused (only meaningful with --apply)',
+                },
+                {
+                    flag: '--lifecycle-mapping <path>',
+                    description: 'Path to a JSON file mapping spec ids to v11 lifecycle values, for v10 lifecycles outside the v11 enum (superseded/proven/frozen). Operator-owned; the transformer never auto-defaults.',
+                },
+                { flag: '--json', description: 'Emit machine-readable JSON output instead of human text' },
+                DATA_OPTION,
+            ],
+        },
+    ],
+};
+// ─── worktree group (CLI-WORKTREE-001) ────────────────────────────────────
+// Co-located authority for `caws worktree` help. The group description here
+// enumerates EVERY subcommand (create/list/bind/destroy/merge/migrate-registry/
+// repair-sparse), unlike the prior inline string that omitted the last two.
+exports.WORKTREE_COMMAND_META = {
+    kind: 'group',
+    name: 'worktree',
+    description: 'Manage CAWS worktrees (create/list/bind/destroy/merge/migrate-registry/repair-sparse). Worktrees are git worktrees bound to active specs.',
+    subcommands: [
+        {
+            kind: 'leaf',
+            name: 'create',
+            argument: { name: 'name', required: true, description: 'Worktree name' },
+            description: 'Create a new git worktree under .caws/worktrees/<name> bound to an active spec.',
+            options: [
+                { flag: '--spec <id>', required: true, description: 'Active spec id to bind the worktree to' },
+                {
+                    flag: '--base-branch <branch>',
+                    description: 'Base branch to start from (default: current branch)',
+                },
+                { flag: '--branch <branch>', description: 'New branch name (default: worktree name)' },
+                DATA_OPTION,
+            ],
+        },
+        {
+            kind: 'leaf',
+            name: 'list',
+            description: 'List registered worktrees with branch, spec binding, and owner.',
+            options: [DATA_OPTION],
+        },
+        {
+            kind: 'leaf',
+            name: 'bind',
+            argument: { name: 'name', required: true, description: 'Worktree name' },
+            description: 'Repair bidirectional binding between a worktree and a spec (one-sided → bound).',
+            options: [
+                { flag: '--spec <id>', required: true, description: 'Spec id to bind the worktree to' },
+                DATA_OPTION,
+            ],
+        },
+        {
+            kind: 'leaf',
+            name: 'destroy',
+            argument: { name: 'name', required: true, description: 'Worktree name' },
+            description: 'Destroy a worktree. Non-forceful: refuses foreign ownership, dirty checkout, unmerged branch (use --abandon-unmerged to override branch check only).',
+            options: [
+                {
+                    flag: '--abandon-unmerged',
+                    description: 'Destroy even when the branch is not merged into base. Still respects ownership and clean working tree.',
+                },
+                DATA_OPTION,
+            ],
+        },
+        {
+            kind: 'leaf',
+            name: 'merge',
+            argument: { name: 'name', required: true, description: 'Worktree name' },
+            description: 'Merge a worktree branch into its base. Auto-closes the bound spec via caws specs close.',
+            options: [
+                { flag: '--dry-run', description: 'Validate prerequisites only; no git, no file writes, no events' },
+                {
+                    flag: '--message <text>',
+                    description: 'Custom merge commit message (default: merge(worktree): <name>)',
+                },
+                DATA_OPTION,
+            ],
+        },
+        {
+            kind: 'leaf',
+            name: 'migrate-registry',
+            description: 'Convert v10.2 legacy-envelope .caws/worktrees.json into the v11 flat-map shape. Destroyed records are omitted iff no spec claims them and their path is absent; refuses otherwise. Idempotent on already-flat files.',
+            options: [
+                { flag: '--dry-run', description: 'Classify and report what would happen; do not write.' },
+                DATA_OPTION,
+            ],
+        },
+        {
+            kind: 'leaf',
+            name: 'repair-sparse',
+            argument: { name: 'name', required: true, description: 'Worktree name' },
+            description: 'Restore the .caws/specs sparse-checkout invariant on a linked worktree. Idempotent and non-destructive: refuses if .caws/specs/ has dirty or untracked content rather than stashing, cleaning, resetting, or deleting it. Use this after a `git sparse-checkout disable` has materialized canonical spec files into the worktree.',
+            options: [DATA_OPTION],
+        },
+    ],
+};
+// ─── flat top-level commands (init/doctor/status/claim/prepush) ───────────
+// These are registered directly on `program` (no subcommand layer); they are
+// LeafCommandMeta entries at the top of COMMAND_SURFACE_METADATA. register.ts
+// consumes them via the defineFlat helper.
+exports.INIT_COMMAND_META = {
+    kind: 'leaf',
+    name: 'init',
+    description: 'Bootstrap the canonical vNext .caws/ project state (idempotent; refuses to overwrite legacy single-spec layout). With --agent-surface, also installs the corresponding hook pack.',
+    options: [
+        DATA_OPTION,
+        {
+            flag: '--agent-surface <name>',
+            description: 'Install a hook pack for an agent harness (claude-code | cursor | windsurf | none). When omitted, init attempts filesystem detection and skips hook install when ambiguous.',
+        },
+        {
+            flag: '--overwrite',
+            description: 'For hook-pack install: replace drifted or unmanaged files at managed pack paths. CAUTION: local edits to those files will be lost.',
+        },
+        {
+            flag: '--adopt',
+            description: 'For hook-pack install: leave drifted or unmanaged files in place without enforcing pack contents. CAUTION: pack drift is no longer tracked for those paths.',
+        },
+    ],
+};
+exports.DOCTOR_COMMAND_META = {
+    kind: 'leaf',
+    name: 'doctor',
+    description: 'Run drift detection against the current .caws/ state',
+    options: [{ flag: '--data', description: 'Show structured data block on findings/diagnostics' }],
+};
+exports.STATUS_COMMAND_META = {
+    kind: 'leaf',
+    name: 'status',
+    description: 'Read-only dashboard: project, current context, claim, and doctor findings',
+    options: [{ flag: '--data', description: 'Show structured data block on rendered diagnostics' }],
+};
+exports.CLAIM_COMMAND_META = {
+    kind: 'leaf',
+    name: 'claim',
+    description: "Surface ownership of the current worktree; with --takeover, acquire ownership from a foreign session (writes prior_owners audit). With --paths, declare working-tree ownership metadata on the current session's lease (SESSION-OWNERSHIP-METADATA-001).",
+    options: [
+        {
+            flag: '--takeover',
+            description: 'Forcibly take ownership of a foreign-owned worktree. Required when the current owner is a different session.',
+        },
+        {
+            flag: '--paths <path>',
+            description: 'Declare a path as claimed by the current session. Repeatable; order preserved; strings stored verbatim. Refused with no write if no lease exists for the current session.',
+            collect: true,
+        },
+        DATA_OPTION,
+    ],
+};
+exports.PREPUSH_COMMAND_META = {
+    kind: 'leaf',
+    name: 'prepush',
+    description: 'Classify the outgoing commit range before publish and refuse commits not attributable to the current slice. Diagnose/decide only — does NOT run git push.',
+    options: [
+        { flag: '--remote <remote>', description: 'Push remote', defaultValue: 'origin' },
+        { flag: '--branch <branch>', description: 'Push branch', defaultValue: 'main' },
+        { flag: '--base <ref>', description: 'Base ref override (default <remote>/<branch>)' },
+        { flag: '--spec <id>', description: 'Current session active spec id (for slice-match)' },
+        {
+            flag: '--ack <sha>',
+            description: 'Acknowledge an unexpected commit by SHA (repeatable)',
+            collect: true,
+            // Seed []: the prepush handler reads opts.ack as an array unconditionally.
+            defaultValue: [],
+        },
+        DATA_OPTION,
+    ],
+};
+// ─── scope group ──────────────────────────────────────────────────────────
+exports.SCOPE_COMMAND_META = {
+    kind: 'group',
+    name: 'scope',
+    description: 'Evaluate file paths against the bound spec scope',
+    subcommands: [
+        {
+            kind: 'leaf',
+            name: 'show',
+            argument: { name: 'path', required: true, description: 'File path to evaluate' },
+            description: 'Explain the scope decision for <path>; always exits 0',
+            options: [{ flag: '--data', description: 'Show structured data block' }],
+        },
+        {
+            kind: 'leaf',
+            name: 'check',
+            argument: { name: 'path', required: true, description: 'File path to enforce' },
+            description: 'Enforce the scope decision for <path>; exits 0 on admit, 1 otherwise',
+            options: [{ flag: '--data', description: 'Show structured data block' }],
+        },
+    ],
+};
+// ─── gates group (W4: exit-code contract documented) ──────────────────────
+exports.GATES_COMMAND_META = {
+    kind: 'group',
+    name: 'gates',
+    description: 'Run quality gates against the current changes (policy-driven)',
+    subcommands: [
+        {
+            kind: 'leaf',
+            name: 'run',
+            description: 'Run CAWS-local policy evaluators and apply policy.gates[gate].mode to decide block/warn/skip. Appends one gate_evaluated event per policy-declared gate. Exit codes: 0/1 on gate disposition; 2 on hard composition error (no policy / subprocess-contract failure); 3 on evidence-integrity failure (a gate_evaluated event failed to append or validate).',
+            options: [
+                { flag: '--spec <id>', required: true, description: 'Spec id this gate run is about' },
+                {
+                    flag: '--context <ctx>',
+                    description: 'Compatibility no-op retained from the former quality-gates subprocess path',
+                    defaultValue: 'cli',
+                },
+                DATA_OPTION,
+            ],
+        },
+    ],
+};
+// ─── evidence group ───────────────────────────────────────────────────────
+exports.EVIDENCE_COMMAND_META = {
+    kind: 'group',
+    name: 'evidence',
+    description: 'Record typed evidence events into .caws/events.jsonl',
+    subcommands: [
+        {
+            kind: 'leaf',
+            name: 'record',
+            description: 'Append a typed evidence event (test|gate|ac)',
+            options: [
+                { flag: '--type <kind>', required: true, description: 'Evidence kind: test | gate | ac' },
+                { flag: '--spec <id>', required: true, description: 'Spec id this evidence is about' },
+                { flag: '--data <json>', required: true, description: 'Event payload as a JSON object string' },
+                {
+                    flag: '--actor-kind <kind>',
+                    description: 'Actor kind: agent | human | system | automation',
+                    defaultValue: 'agent',
+                },
+                { flag: '--actor-id <id>', description: 'Override actor id (defaults to session id)' },
+            ],
+        },
+    ],
+};
+// ─── events group ─────────────────────────────────────────────────────────
+exports.EVENTS_COMMAND_META = {
+    kind: 'group',
+    name: 'events',
+    description: 'Maintenance commands for .caws/events.jsonl (rotate, migrate, verify-archive)',
+    subcommands: [
+        {
+            kind: 'leaf',
+            name: 'migrate',
+            description: 'Migrate a v10-shape events.jsonl to a v11 chain via chain_rotated rotation. Dry-run by default; --apply executes.',
+            options: [
+                {
+                    flag: '--from <version>',
+                    required: true,
+                    description: 'Source schema version (only v10 supported in v11.2)',
+                },
+                { flag: '--apply', description: 'Execute the rotation (default is dry-run)' },
+                {
+                    flag: '--reason <text>',
+                    description: 'Operator reason recorded into the chain_rotated payload (required with --apply)',
+                },
+                {
+                    flag: '--actor-kind <kind>',
+                    description: 'Actor kind: agent | human | system | automation',
+                    defaultValue: 'agent',
+                },
+                { flag: '--actor-id <id>', description: 'Override actor id (defaults to session id)' },
+                {
+                    flag: '--allow-partial-upgrade',
+                    description: 'Allow rotation when v10 specs are still present (off by default; see CAWS-MIGRATE-V10-SPECS-001)',
+                },
+            ],
+        },
+        {
+            kind: 'leaf',
+            name: 'rotate',
+            description: 'Rotate events.jsonl: archive existing chain, start fresh chain with chain_rotated genesis event. Distinct from migrate — admits fully-unparseable logs.',
+            options: [
+                {
+                    flag: '--reason <text>',
+                    required: true,
+                    description: 'Operator reason recorded into the chain_rotated payload',
+                },
+                {
+                    flag: '--actor-kind <kind>',
+                    description: 'Actor kind: agent | human | system | automation',
+                    defaultValue: 'agent',
+                },
+                { flag: '--actor-id <id>', description: 'Override actor id (defaults to session id)' },
+                { flag: '--allow-clean', description: 'Allow rotation of a clean v11 chain (friction flag)' },
+            ],
+        },
+        {
+            kind: 'leaf',
+            name: 'verify-archive',
+            description: 'Verify that the archive file named in the most recent chain_rotated event byte-matches its committed digest + line count.',
+            options: [],
+        },
+    ],
+};
+// ─── waiver group ─────────────────────────────────────────────────────────
+exports.WAIVER_COMMAND_META = {
+    kind: 'group',
+    name: 'waiver',
+    description: 'Manage CAWS waivers (bounded exception records that suppress matching gate violations)',
+    subcommands: [
+        {
+            kind: 'leaf',
+            name: 'create',
+            argument: { name: 'id', required: true, description: 'Waiver id to create' },
+            description: 'Create a new active waiver. Validates against the kernel before writing.',
+            options: [
+                { flag: '--title <title>', required: true, description: 'Short waiver title (≥5 chars)' },
+                {
+                    flag: '--gate <gate>',
+                    required: true,
+                    description: 'Gate id this waiver covers; repeat for multiple gates',
+                    collect: true,
+                },
+                { flag: '--reason <reason>', required: true, description: 'Justification for the waiver' },
+                { flag: '--approved-by <id>', required: true, description: 'Approver identity' },
+                {
+                    flag: '--expires-at <iso>',
+                    required: true,
+                    description: 'Expiry as an ISO-8601 datetime with timezone',
+                },
+                {
+                    flag: '--spec <id>',
+                    description: 'Optional spec id this waiver is scoped to (omit for project-wide)',
+                },
+                DATA_OPTION,
+            ],
+        },
+        {
+            kind: 'leaf',
+            name: 'list',
+            description: 'List waivers. By default excludes revoked and expired records.',
+            options: [
+                { flag: '--include-revoked', description: 'Include revoked waivers' },
+                { flag: '--include-expired', description: 'Include expired waivers' },
+                DATA_OPTION,
+            ],
+        },
+        {
+            kind: 'leaf',
+            name: 'show',
+            argument: { name: 'id', required: true, description: 'Waiver id to show' },
+            description: 'Show a waiver, including its derived effectiveness at now.',
+            options: [DATA_OPTION],
+        },
+        {
+            kind: 'leaf',
+            name: 'revoke',
+            argument: { name: 'id', required: true, description: 'Waiver id to revoke' },
+            description: 'Revoke a waiver. Writes a revocation record; refuses double-revoke.',
+            options: [
+                { flag: '--revoked-by <id>', description: 'Identity recorded in revocation.revoked_by' },
+                {
+                    flag: '--reason <reason>',
+                    description: 'Reason recorded in revocation.reason (recommended for audit)',
+                },
+                DATA_OPTION,
+            ],
+        },
+    ],
+};
+// ─── agents group ─────────────────────────────────────────────────────────
+exports.AGENTS_COMMAND_META = {
+    kind: 'group',
+    name: 'agents',
+    description: 'Agent liveness substrate: register/heartbeat/stop/list/show/prune. Operational cache only — NEVER authority. CAWS-native JSON; never Claude Code hook envelope.',
+    subcommands: [
+        {
+            kind: 'leaf',
+            name: 'register',
+            description: 'Register this session in .caws/leases/. Hook-invoked at SessionStart.',
+            options: [
+                {
+                    flag: '--session-id <id>',
+                    description: 'Explicit session id (required for hook-invoked usage; overrides resolveSession)',
+                },
+                { flag: '--platform <p>', description: 'Platform tag (e.g., claude-code, cursor, manual)' },
+                { flag: '--reason <r>', description: 'session_start | pre_tool_use | manual_register | claim | status' },
+                { flag: '--json', description: 'Emit CAWS-native JSON to stdout (never hookSpecificOutput)' },
+                {
+                    flag: '--include-active-summary',
+                    description: 'Include active_agent_count + active_agents in JSON output',
+                },
+                DATA_OPTION,
+            ],
+        },
+        {
+            kind: 'leaf',
+            name: 'heartbeat',
+            description: "Refresh this session's lease. Hook-invoked at PreToolUse. Throttle-aware.",
+            options: [
+                { flag: '--session-id <id>', description: 'Explicit session id (required for hook-invoked usage)' },
+                { flag: '--platform <p>', description: 'Platform tag' },
+                { flag: '--reason <r>', description: 'pre_tool_use | claim | status | manual_register' },
+                {
+                    flag: '--throttle <ms>',
+                    description: 'Skip write if last_active within this many ms (default: 0 — no throttle)',
+                },
+                { flag: '--json', description: 'Emit CAWS-native JSON to stdout' },
+                {
+                    flag: '--include-active-summary',
+                    description: 'Include active_agent_count + active_agents in JSON output',
+                },
+                DATA_OPTION,
+            ],
+        },
+        {
+            kind: 'leaf',
+            name: 'stop',
+            description: "Mark this session's lease stopped. Hook-invoked at Stop. Warn no-op if no prior lease.",
+            options: [
+                { flag: '--session-id <id>', description: 'Explicit session id' },
+                { flag: '--platform <p>', description: 'Platform tag' },
+                { flag: '--json', description: 'Emit CAWS-native JSON to stdout' },
+                DATA_OPTION,
+            ],
+        },
+        {
+            kind: 'leaf',
+            name: 'list',
+            description: 'List active / stale / stopped agents. Read-only.',
+            options: [
+                { flag: '--include-stale', description: 'Include stale (active-but-TTL-expired) records' },
+                { flag: '--include-stopped', description: 'Include stopped records' },
+                {
+                    flag: '--active',
+                    description: 'Active-only (overrides --include-* flags); TTL-classified active, not raw status field',
+                },
+                { flag: '--stale-ttl-ms <ms>', description: 'TTL for stale classification (default: 1800000 = 30m)' },
+                { flag: '--json', description: 'Emit CAWS-native JSON to stdout' },
+                DATA_OPTION,
+            ],
+        },
+        {
+            kind: 'leaf',
+            name: 'show',
+            argument: { name: 'id', required: true, description: 'Session id of the lease to show' },
+            description: 'Show one lease by session id. Read-only.',
+            options: [
+                { flag: '--json', description: 'Emit CAWS-native JSON to stdout' },
+                DATA_OPTION,
+            ],
+        },
+        {
+            kind: 'leaf',
+            name: 'prune',
+            description: 'Operator-invoked cleanup. Defaults to dry-run; pass --apply to actually delete. Never invoked by hooks.',
+            options: [
+                { flag: '--status <s>', required: true, description: 'stopped | stale' },
+                { flag: '--older-than-ms <ms>', required: true, description: 'Retention threshold in milliseconds' },
+                {
+                    flag: '--stale-ttl-ms <ms>',
+                    description: 'TTL for stale classification (used with --status stale; default 30m)',
+                },
+                { flag: '--apply', description: 'Actually delete (default: dry-run)' },
+                { flag: '--json', description: 'Emit CAWS-native JSON to stdout' },
+                DATA_OPTION,
+            ],
+        },
+    ],
+};
+/**
+ * The complete v11 command-surface metadata — the single authority for every
+ * `.description()` / `.argument()` / `.option()` in register.ts.
+ *
+ * SLICE 3: all thirteen surface entries are populated and consumed by
+ * register.ts — the five flat top-level commands (init/doctor/status/claim/
+ * prepush) as LeafCommandMeta, and eight groups (scope/gates/evidence/events/
+ * waiver/agents/specs/worktree). The lock test enforces full set-equality with
+ * REGISTERED_COMMAND_GROUPS (L1), enum/value-list parity (L3), non-empty
+ * descriptions (L4), and the global no-inline-strings invariant on register.ts
+ * (L5).
+ */
+exports.COMMAND_SURFACE_METADATA = Object.freeze([
+    exports.INIT_COMMAND_META,
+    exports.DOCTOR_COMMAND_META,
+    exports.STATUS_COMMAND_META,
+    exports.SCOPE_COMMAND_META,
+    exports.CLAIM_COMMAND_META,
+    exports.GATES_COMMAND_META,
+    exports.EVIDENCE_COMMAND_META,
+    exports.EVENTS_COMMAND_META,
+    exports.WAIVER_COMMAND_META,
+    exports.SPECS_COMMAND_META,
+    exports.WORKTREE_COMMAND_META,
+    exports.AGENTS_COMMAND_META,
+    exports.PREPUSH_COMMAND_META,
+]);
+//# sourceMappingURL=command-metadata.js.map