@paths.design/caws-cli 11.1.6 → 11.1.8

package/dist/shell/register.js

@@ -15,6 +15,7 @@
 //     etc.) UNTOUCHED.
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerShellCommands = registerShellCommands;
+const command_metadata_1 = require("./command-metadata");
 const index_1 = require("./index");
 function parseDataOption(raw) {
     if (typeof raw !== 'string' || raw.length === 0)
@@ -35,6 +36,102 @@ function parseDataOption(raw) {
 function isEvidenceKind(value) {
     return value === 'test' || value === 'gate' || value === 'ac';
 }
+// ── Metadata-driven help wiring (CAWS-CLI-HELP-METADATA-AUTHORITY-001) ──────
+// register.ts no longer authors `.description()` / `.option()` string literals
+// for groups present in COMMAND_SURFACE_METADATA; it reads them from the typed
+// metadata so the help text has a single, lock-tested source. The `.action()`
+// handlers stay inline (they bind to the run*Command functions); only the
+// help/option surface is metadata-driven.
+/** Render an option's help string: prose, plus a derived "value list" when the
+ * option is enum-backed (allowedValues). The value list is the locked part —
+ * the lock test asserts it equals the kernel/schema enum. */
+function renderOptionDescription(opt) {
+    if (opt.allowedValues && opt.allowedValues.length > 0) {
+        return `${opt.description}: ${opt.allowedValues.join(' | ')}`;
+    }
+    return opt.description;
+}
+/** Commander value collector for repeatable string options — accumulates each
+ * occurrence into an array, verbatim caller order, no normalization. Shared by
+ * every `collect: true` metadata option (claim --paths, prepush --ack, waiver
+ * create --gate). */
+function collectOption(value, previous) {
+    return previous === undefined ? [value] : [...previous, value];
+}
+/** Apply one metadata option to a Commander command, choosing
+ * required/optional, supplying a collector for repeatable (`collect`) options,
+ * and passing a default value when declared. */
+function applyOptionMeta(cmd, opt) {
+    const description = renderOptionDescription(opt);
+    if (opt.collect === true) {
+        // Repeatable option: Commander needs the collector fn. Whether to seed an
+        // initial [] is preserved from the prior hand-written behavior and encoded
+        // in metadata as defaultValue: [] (e.g. prepush --ack, waiver --gate seed
+        // so the value is always an array; claim --paths omits the seed so an
+        // unsupplied option stays `undefined`).
+        const seed = opt.defaultValue !== undefined ? opt.defaultValue : undefined;
+        if (opt.required === true) {
+            cmd.requiredOption(opt.flag, description, collectOption, seed ?? []);
+        }
+        else if (seed !== undefined) {
+            cmd.option(opt.flag, description, collectOption, seed);
+        }
+        else {
+            cmd.option(opt.flag, description, collectOption);
+        }
+        return;
+    }
+    if (opt.required === true) {
+        cmd.requiredOption(opt.flag, description);
+        return;
+    }
+    if (opt.defaultValue !== undefined) {
+        cmd.option(opt.flag, description, opt.defaultValue);
+        return;
+    }
+    cmd.option(opt.flag, description);
+}
+/** Construct the `.command()` name string with the metadata's positional
+ * argument suffix (`<name>` required, `[name]` optional), e.g. "create <id>". */
+function leafCommandName(leaf) {
+    if (!leaf.argument)
+        return leaf.name;
+    const { name, required } = leaf.argument;
+    return required ? `${leaf.name} <${name}>` : `${leaf.name} [${name}]`;
+}
+/** Register a leaf subcommand from metadata: name(+arg), description, options.
+ * Returns the configured Command so the caller can attach `.action()`. */
+function defineLeaf(group, leaf) {
+    const cmd = group.command(leafCommandName(leaf)).description(leaf.description);
+    for (const opt of leaf.options) {
+        applyOptionMeta(cmd, opt);
+    }
+    return cmd;
+}
+/** Apply the group-level description from metadata to a Commander group. */
+function applyGroupMeta(group, meta) {
+    group.description(meta.description);
+}
+/** Register a FLAT top-level command from LeafCommandMeta (init/doctor/status/
+ * claim/prepush): name(+arg), description, options — all metadata-driven.
+ * Returns the configured Command so the caller can attach `.action()`. */
+function defineFlat(program, leaf) {
+    const cmd = program.command(leafCommandName(leaf)).description(leaf.description);
+    for (const opt of leaf.options) {
+        applyOptionMeta(cmd, opt);
+    }
+    return cmd;
+}
+/** Look up a leaf's metadata within a group by subcommand name. Throws if the
+ * metadata is missing — a wiring bug should fail loudly at registration, not
+ * silently register a command with no help. */
+function leafMeta(meta, name) {
+    const found = meta.subcommands.find((s) => s.name === name);
+    if (!found) {
+        throw new Error(`register.ts: no metadata for "${meta.name} ${name}" in COMMAND_SURFACE_METADATA`);
+    }
+    return found;
+}
 function registerShellCommands(program, options = {}) {
     const exit = options.exit ?? ((code) => process.exit(code));
     // -------------------------------------------------------------------
@@ -46,22 +143,7 @@ function registerShellCommands(program, options = {}) {
     // Replaces the legacy `caws init` registration removed from
     // src/index.js as part of slice 7b.
     // -------------------------------------------------------------------
-    program
-        .command('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.')
-        .option('--data', 'Show structured data block on diagnostics')
-        .option('--agent-surface <name>', '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.')
-        .option('--overwrite', 'For hook-pack install: replace drifted or unmanaged files at ' +
-        'managed pack paths. CAUTION: local edits to those files will ' +
-        'be lost.')
-        .option('--adopt', '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.')
+    defineFlat(program, command_metadata_1.INIT_COMMAND_META)
         .action((opts) => {
         // Commander hands back the raw string for agentSurface; the
         // runInitCommand validator rejects unknown values with exit 2.
@@ -84,10 +166,7 @@ function registerShellCommands(program, options = {}) {
     // -------------------------------------------------------------------
     // caws doctor
     // -------------------------------------------------------------------
-    program
-        .command('doctor')
-        .description('Run drift detection against the current .caws/ state')
-        .option('--data', 'Show structured data block on findings/diagnostics')
+    defineFlat(program, command_metadata_1.DOCTOR_COMMAND_META)
         .action((opts) => {
         const code = (0, index_1.runDoctorCommand)({
             showData: opts.data === true,
@@ -98,13 +177,9 @@ function registerShellCommands(program, options = {}) {
     // caws scope show <path>   /   caws scope check <path>
     // (replaces the legacy `scope` group entirely)
     // -------------------------------------------------------------------
-    const scopeCmd = program
-        .command('scope')
-        .description('Evaluate file paths against the bound spec scope');
-    scopeCmd
-        .command('show <path>')
-        .description('Explain the scope decision for <path>; always exits 0')
-        .option('--data', 'Show structured data block')
+    const scopeCmd = program.command('scope');
+    applyGroupMeta(scopeCmd, command_metadata_1.SCOPE_COMMAND_META);
+    defineLeaf(scopeCmd, leafMeta(command_metadata_1.SCOPE_COMMAND_META, 'show'))
         .action((p, opts) => {
         const code = (0, index_1.runScopeCommand)({
             path: p,
@@ -113,10 +188,7 @@ function registerShellCommands(program, options = {}) {
         });
         exit(code);
     });
-    scopeCmd
-        .command('check <path>')
-        .description('Enforce the scope decision for <path>; exits 0 on admit, 1 otherwise')
-        .option('--data', 'Show structured data block')
+    defineLeaf(scopeCmd, leafMeta(command_metadata_1.SCOPE_COMMAND_META, 'check'))
         .action((p, opts) => {
         const code = (0, index_1.runScopeCommand)({
             path: p,
@@ -128,10 +200,7 @@ function registerShellCommands(program, options = {}) {
     // -------------------------------------------------------------------
     // caws status — read-only dashboard (replaces legacy status)
     // -------------------------------------------------------------------
-    program
-        .command('status')
-        .description('Read-only dashboard: project, current context, claim, and doctor findings')
-        .option('--data', 'Show structured data block on rendered diagnostics')
+    defineFlat(program, command_metadata_1.STATUS_COMMAND_META)
         .action((opts) => {
         const code = (0, index_1.runStatusCommand)({
             showData: opts.data === true,
@@ -139,19 +208,14 @@ function registerShellCommands(program, options = {}) {
         exit(code);
     });
     // -------------------------------------------------------------------
-    // caws claim [--takeover]
+    // caws claim [--takeover] [--paths <path>...]
     // -------------------------------------------------------------------
-    program
-        .command('claim')
-        .description('Surface ownership of the current worktree; with --takeover, ' +
-        'acquire ownership from a foreign session (writes prior_owners audit).')
-        .option('--takeover', 'Forcibly take ownership of a foreign-owned worktree. Required when ' +
-        'the current owner is a different session.')
-        .option('--data', 'Show structured data block on diagnostics')
+    defineFlat(program, command_metadata_1.CLAIM_COMMAND_META)
         .action((opts) => {
         const code = (0, index_1.runClaimCommand)({
             takeover: opts.takeover === true,
             showData: opts.data === true,
+            ...(opts.paths !== undefined ? { paths: opts.paths } : {}),
         });
         exit(code);
     });
@@ -159,20 +223,26 @@ function registerShellCommands(program, options = {}) {
     // caws gates run --spec <id> [--context <ctx>]
     // (replaces the legacy `gates` group and `quality-gates` alias)
     // -------------------------------------------------------------------
-    const gatesCmd = program
-        .command('gates')
-        .description('Run quality gates against the current changes (policy-driven)');
-    gatesCmd
-        .command('run')
-        .description('Invoke quality-gates subprocess and apply policy.gates[gate].mode ' +
-        'to decide block/warn/skip. Appends one gate_evaluated event per ' +
-        'policy-declared gate.')
-        .requiredOption('--spec <id>', 'Spec id this gate run is about')
-        .option('--context <ctx>', 'Subprocess context: cli | commit | ci', 'cli')
-        .option('--data', 'Show structured data block on diagnostics')
+    const gatesCmd = program.command('gates');
+    applyGroupMeta(gatesCmd, command_metadata_1.GATES_COMMAND_META);
+    defineLeaf(gatesCmd, leafMeta(command_metadata_1.GATES_COMMAND_META, 'run'))
         .action((opts) => {
         const code = (0, index_1.runGatesRunCommand)({ specId: opts.spec }, {
-            subprocessArgs: [`--context=${opts.context}`],
+            showData: opts.data === true,
+        });
+        exit(code);
+    });
+    // -------------------------------------------------------------------
+    // caws prepush — MULTI-AGENT-PUSH-RANGE-GUARD-001
+    // -------------------------------------------------------------------
+    defineFlat(program, command_metadata_1.PREPUSH_COMMAND_META)
+        .action((opts) => {
+        const code = (0, index_1.runPrepushCommand)({
+            remote: opts.remote,
+            branch: opts.branch,
+            ...(opts.base !== undefined ? { base: opts.base } : {}),
+            ...(opts.spec !== undefined ? { specId: opts.spec } : {}),
+            ack: opts.ack,
             showData: opts.data === true,
         });
         exit(code);
@@ -180,17 +250,9 @@ function registerShellCommands(program, options = {}) {
     // -------------------------------------------------------------------
     // caws evidence record
     // -------------------------------------------------------------------
-    const evidenceCmd = program
-        .command('evidence')
-        .description('Record typed evidence events into .caws/events.jsonl');
-    evidenceCmd
-        .command('record')
-        .description('Append a typed evidence event (test|gate|ac)')
-        .requiredOption('--type <kind>', 'Evidence kind: test | gate | ac')
-        .requiredOption('--spec <id>', 'Spec id this evidence is about')
-        .requiredOption('--data <json>', 'Event payload as a JSON object string')
-        .option('--actor-kind <kind>', 'Actor kind: agent | human | system | automation', 'agent')
-        .option('--actor-id <id>', 'Override actor id (defaults to session id)')
+    const evidenceCmd = program.command('evidence');
+    applyGroupMeta(evidenceCmd, command_metadata_1.EVIDENCE_COMMAND_META);
+    defineLeaf(evidenceCmd, leafMeta(command_metadata_1.EVIDENCE_COMMAND_META, 'record'))
         .action((opts) => {
         // Parse --data here; pass already-typed shape to the command.
         let data;
@@ -219,25 +281,67 @@ function registerShellCommands(program, options = {}) {
         exit(code);
     });
     // -------------------------------------------------------------------
+    // caws events migrate / rotate / verify-archive
+    //
+    // v11.2 maintenance command surface for the event-log writer. See
+    // docs/architecture/caws-vnext-command-surface.md §6 invariant 14 and
+    // the Maintenance / control-plane subsection. Distinct semantics:
+    //
+    //   - migrate: v10→v11 chain migration (planner-driven; refuses
+    //              fully-unparseable, requires spec-scan).
+    //   - rotate:  lower-level maintenance rotation (admits fully-
+    //              unparseable as evidence quarantine).
+    //   - verify-archive: recompute archive sha256+line count vs the
+    //              most recent chain_rotated event.
+    // -------------------------------------------------------------------
+    const eventsCmd = program.command('events');
+    applyGroupMeta(eventsCmd, command_metadata_1.EVENTS_COMMAND_META);
+    defineLeaf(eventsCmd, leafMeta(command_metadata_1.EVENTS_COMMAND_META, 'migrate'))
+        .action((opts) => {
+        if (opts.from !== 'v10') {
+            process.stderr.write(`caws events migrate: only --from v10 is supported in v11.2; got ${JSON.stringify(opts.from)}.\n`);
+            exit(1);
+            return;
+        }
+        const code = (0, index_1.runEventsMigrateCommand)({
+            from: 'v10',
+            ...(opts.apply === true ? { apply: true } : {}),
+            ...(opts.reason !== undefined ? { reason: opts.reason } : {}),
+            ...(opts.actorKind !== undefined
+                ? { actorKind: opts.actorKind }
+                : {}),
+            ...(opts.actorId !== undefined ? { actorId: opts.actorId } : {}),
+            ...(opts.allowPartialUpgrade === true ? { allowPartialUpgrade: true } : {}),
+        });
+        exit(code);
+    });
+    defineLeaf(eventsCmd, leafMeta(command_metadata_1.EVENTS_COMMAND_META, 'rotate'))
+        .action((opts) => {
+        const code = (0, index_1.runEventsRotateCommand)({
+            reason: opts.reason,
+            ...(opts.actorKind !== undefined
+                ? { actorKind: opts.actorKind }
+                : {}),
+            ...(opts.actorId !== undefined ? { actorId: opts.actorId } : {}),
+            ...(opts.allowClean === true ? { allowClean: true } : {}),
+        });
+        exit(code);
+    });
+    defineLeaf(eventsCmd, leafMeta(command_metadata_1.EVENTS_COMMAND_META, 'verify-archive'))
+        .action(() => {
+        const code = (0, index_1.runEventsVerifyArchiveCommand)({});
+        exit(code);
+    });
+    // -------------------------------------------------------------------
     // caws waiver create / list / show / revoke
     //
     // Singular `waiver` is the vNext authority surface. The legacy plural
     // `waivers` group is removed in src/index.js as part of slice 7a.4 —
     // no compatibility alias, no feature flag.
     // -------------------------------------------------------------------
-    const waiverCmd = program
-        .command('waiver')
-        .description('Manage CAWS waivers (bounded exception records that suppress matching gate violations)');
-    waiverCmd
-        .command('create <id>')
-        .description('Create a new active waiver. Validates against the kernel before writing.')
-        .requiredOption('--title <title>', 'Short waiver title (≥5 chars)')
-        .requiredOption('--gate <gate>', 'Gate id this waiver covers; repeat for multiple gates', collectMulti, [])
-        .requiredOption('--reason <reason>', 'Justification for the waiver')
-        .requiredOption('--approved-by <id>', 'Approver identity')
-        .requiredOption('--expires-at <iso>', 'Expiry as an ISO-8601 datetime with timezone')
-        .option('--spec <id>', 'Optional spec id this waiver is scoped to (omit for project-wide)')
-        .option('--data', 'Show structured data block on diagnostics')
+    const waiverCmd = program.command('waiver');
+    applyGroupMeta(waiverCmd, command_metadata_1.WAIVER_COMMAND_META);
+    defineLeaf(waiverCmd, leafMeta(command_metadata_1.WAIVER_COMMAND_META, 'create'))
         .action((id, opts) => {
         const code = (0, index_1.runWaiverCreateCommand)({
             id,
@@ -251,12 +355,7 @@ function registerShellCommands(program, options = {}) {
         });
         exit(code);
     });
-    waiverCmd
-        .command('list')
-        .description('List waivers. By default excludes revoked and expired records.')
-        .option('--include-revoked', 'Include revoked waivers')
-        .option('--include-expired', 'Include expired waivers')
-        .option('--data', 'Show structured data block on diagnostics')
+    defineLeaf(waiverCmd, leafMeta(command_metadata_1.WAIVER_COMMAND_META, 'list'))
         .action((opts) => {
         const code = (0, index_1.runWaiverListCommand)({
             includeRevoked: opts.includeRevoked === true,
@@ -265,10 +364,7 @@ function registerShellCommands(program, options = {}) {
         });
         exit(code);
     });
-    waiverCmd
-        .command('show <id>')
-        .description('Show a waiver, including its derived effectiveness at now.')
-        .option('--data', 'Show structured data block on diagnostics')
+    defineLeaf(waiverCmd, leafMeta(command_metadata_1.WAIVER_COMMAND_META, 'show'))
         .action((id, opts) => {
         const code = (0, index_1.runWaiverShowCommand)({
             id,
@@ -276,12 +372,7 @@ function registerShellCommands(program, options = {}) {
         });
         exit(code);
     });
-    waiverCmd
-        .command('revoke <id>')
-        .description('Revoke a waiver. Writes a revocation record; refuses double-revoke.')
-        .option('--revoked-by <id>', 'Identity recorded in revocation.revoked_by')
-        .option('--reason <reason>', 'Reason recorded in revocation.reason (recommended for audit)')
-        .option('--data', 'Show structured data block on diagnostics')
+    defineLeaf(waiverCmd, leafMeta(command_metadata_1.WAIVER_COMMAND_META, 'revoke'))
         .action((id, opts) => {
         const code = (0, index_1.runWaiverRevokeCommand)({
             id,
@@ -299,31 +390,21 @@ function registerShellCommands(program, options = {}) {
     // Slice 4). The shell layer parses args + builds the actor envelope;
     // the writer owns YAML patching + event append.
     // -------------------------------------------------------------------
-    const specsCmd = program
-        .command('specs')
-        .description('Manage CAWS spec lifecycle (create/list/show/close/archive)');
-    specsCmd
-        .command('create <id>')
-        .description('Create a new spec in lifecycle_state: active.')
-        .requiredOption('--title <title>', 'Short spec title')
-        .requiredOption('--mode <mode>', 'Spec mode: feature | refactor | fix | doc | chore')
-        .requiredOption('--risk-tier <n>', 'Risk tier: 1, 2, or 3')
-        .option('--data', 'Show structured data block on diagnostics')
+    const specsCmd = program.command('specs');
+    applyGroupMeta(specsCmd, command_metadata_1.SPECS_COMMAND_META);
+    defineLeaf(specsCmd, leafMeta(command_metadata_1.SPECS_COMMAND_META, 'create'))
         .action((id, opts) => {
         const code = (0, index_1.runSpecsCreateCommand)({
             id,
-            title: opts.title,
-            mode: opts.mode,
-            riskTier: opts.riskTier,
+            ...(opts.title !== undefined ? { title: opts.title } : {}),
+            ...(opts.mode !== undefined ? { mode: opts.mode } : {}),
+            ...(opts.riskTier !== undefined ? { riskTier: opts.riskTier } : {}),
+            ...(opts.type !== undefined ? { legacyType: opts.type } : {}),
             showData: opts.data === true,
         });
         exit(code);
     });
-    specsCmd
-        .command('list')
-        .description('List specs. By default excludes archived specs.')
-        .option('--archived', 'Include archived specs in the listing')
-        .option('--data', 'Show structured data block on diagnostics')
+    defineLeaf(specsCmd, leafMeta(command_metadata_1.SPECS_COMMAND_META, 'list'))
         .action((opts) => {
         const code = (0, index_1.runSpecsListCommand)({
             includeArchived: opts.archived === true,
@@ -331,25 +412,42 @@ function registerShellCommands(program, options = {}) {
         });
         exit(code);
     });
-    specsCmd
-        .command('show <id>')
-        .description('Show a spec by id (searches active and archived locations).')
-        .option('--data', 'Show structured data block on diagnostics')
+    defineLeaf(specsCmd, leafMeta(command_metadata_1.SPECS_COMMAND_META, 'show'))
         .action((id, opts) => {
         const code = (0, index_1.runSpecsShowCommand)({
             id,
             showData: opts.data === true,
+            ...(opts.archived === true ? { archived: true } : {}),
+        });
+        exit(code);
+    });
+    defineLeaf(specsCmd, leafMeta(command_metadata_1.SPECS_COMMAND_META, 'recover'))
+        .action((id, opts) => {
+        const code = (0, index_1.runSpecsRecoverCommand)({
+            id,
+            showData: opts.data === true,
+            ...(typeof opts.out === 'string' && opts.out.length > 0 ? { outPath: opts.out } : {}),
+        });
+        exit(code);
+    });
+    defineLeaf(specsCmd, leafMeta(command_metadata_1.SPECS_COMMAND_META, 'retire-draft'))
+        .action((id, opts) => {
+        const code = (0, index_1.runSpecsRetireDraftCommand)({
+            id,
+            ...(opts.reason !== undefined ? { reason: opts.reason } : {}),
+            showData: opts.data === true,
         });
         exit(code);
     });
-    specsCmd
-        .command('close <id>')
-        .description('Close an active spec. Non-destructive raw-byte YAML patch; appends spec_closed event.')
-        .requiredOption('--resolution <r>', 'Resolution: completed | superseded | abandoned')
-        .option('--reason <text>', 'Closure notes recorded on the spec YAML and the spec_closed event')
-        .option('--merge-commit <sha>', 'Optional merge commit SHA (e.g., when closure follows a worktree merge)')
-        .option('--superseded-by <id>', 'Spec id that supersedes this one (use with --resolution superseded)')
-        .option('--data', 'Show structured data block on diagnostics')
+    defineLeaf(specsCmd, leafMeta(command_metadata_1.SPECS_COMMAND_META, 'activate'))
+        .action((id, opts) => {
+        const code = (0, index_1.runSpecsActivateCommand)({
+            id,
+            showData: opts.data === true,
+        });
+        exit(code);
+    });
+    defineLeaf(specsCmd, leafMeta(command_metadata_1.SPECS_COMMAND_META, 'close'))
         .action((id, opts) => {
         const code = (0, index_1.runSpecsCloseCommand)({
             id,
@@ -365,11 +463,7 @@ function registerShellCommands(program, options = {}) {
         });
         exit(code);
     });
-    specsCmd
-        .command('archive <id>')
-        .description('Archive a closed spec. Moves the YAML file to .caws/specs/.archive/; appends spec_archived event.')
-        .option('--reason <text>', 'Archive reason (advisory; spec_archived schema does not carry it)')
-        .option('--data', 'Show structured data block on diagnostics')
+    defineLeaf(specsCmd, leafMeta(command_metadata_1.SPECS_COMMAND_META, 'archive'))
         .action((id, opts) => {
         const code = (0, index_1.runSpecsArchiveCommand)({
             id,
@@ -378,6 +472,28 @@ function registerShellCommands(program, options = {}) {
         });
         exit(code);
     });
+    defineLeaf(specsCmd, leafMeta(command_metadata_1.SPECS_COMMAND_META, 'prune-archive'))
+        .action((opts) => {
+        const code = (0, index_1.runSpecsPruneArchiveCommand)({
+            ...(opts.apply === true ? { apply: true } : {}),
+            showData: opts.data === true,
+        });
+        exit(code);
+    });
+    defineLeaf(specsCmd, leafMeta(command_metadata_1.SPECS_COMMAND_META, 'migrate'))
+        .action((opts) => {
+        const code = (0, index_1.runSpecsMigrateCommand)({
+            from: opts.from,
+            apply: opts.apply === true,
+            partial: opts.partial === true,
+            ...(opts.lifecycleMapping !== undefined
+                ? { lifecycleMappingPath: opts.lifecycleMapping }
+                : {}),
+            json: opts.json === true,
+            showData: opts.data === true,
+        });
+        exit(code);
+    });
     // -------------------------------------------------------------------
     // caws worktree (CLI-WORKTREE-001)
     //
@@ -386,16 +502,9 @@ function registerShellCommands(program, options = {}) {
     // substrate from Slice 4 + applyRegistryPatch + specs-writer.closeSpec
     // for auto-close on merge).
     // -------------------------------------------------------------------
-    const worktreeCmd = program
-        .command('worktree')
-        .description('Manage CAWS worktrees (create/list/bind/destroy/merge). Worktrees are git worktrees bound to active specs.');
-    worktreeCmd
-        .command('create <name>')
-        .description('Create a new git worktree under .caws/worktrees/<name> bound to an active spec.')
-        .requiredOption('--spec <id>', 'Active spec id to bind the worktree to')
-        .option('--base-branch <branch>', 'Base branch to start from (default: current branch)')
-        .option('--branch <branch>', 'New branch name (default: worktree name)')
-        .option('--data', 'Show structured data block on diagnostics')
+    const worktreeCmd = program.command('worktree');
+    applyGroupMeta(worktreeCmd, command_metadata_1.WORKTREE_COMMAND_META);
+    defineLeaf(worktreeCmd, leafMeta(command_metadata_1.WORKTREE_COMMAND_META, 'create'))
         .action((name, opts) => {
         const code = (0, index_1.runWorktreeCreateCommand)({
             name,
@@ -406,19 +515,12 @@ function registerShellCommands(program, options = {}) {
         });
         exit(code);
     });
-    worktreeCmd
-        .command('list')
-        .description('List registered worktrees with branch, spec binding, and owner.')
-        .option('--data', 'Show structured data block on diagnostics')
+    defineLeaf(worktreeCmd, leafMeta(command_metadata_1.WORKTREE_COMMAND_META, 'list'))
         .action((opts) => {
         const code = (0, index_1.runWorktreeListCommand)({ showData: opts.data === true });
         exit(code);
     });
-    worktreeCmd
-        .command('bind <name>')
-        .description('Repair bidirectional binding between a worktree and a spec (one-sided → bound).')
-        .requiredOption('--spec <id>', 'Spec id to bind the worktree to')
-        .option('--data', 'Show structured data block on diagnostics')
+    defineLeaf(worktreeCmd, leafMeta(command_metadata_1.WORKTREE_COMMAND_META, 'bind'))
         .action((name, opts) => {
         const code = (0, index_1.runWorktreeBindCommand)({
             name,
@@ -427,11 +529,7 @@ function registerShellCommands(program, options = {}) {
         });
         exit(code);
     });
-    worktreeCmd
-        .command('destroy <name>')
-        .description('Destroy a worktree. Non-forceful: refuses foreign ownership, dirty checkout, unmerged branch (use --abandon-unmerged to override branch check only).')
-        .option('--abandon-unmerged', 'Destroy even when the branch is not merged into base. Still respects ownership and clean working tree.')
-        .option('--data', 'Show structured data block on diagnostics')
+    defineLeaf(worktreeCmd, leafMeta(command_metadata_1.WORKTREE_COMMAND_META, 'destroy'))
         .action((name, opts) => {
         const code = (0, index_1.runWorktreeDestroyCommand)({
             name,
@@ -440,12 +538,7 @@ function registerShellCommands(program, options = {}) {
         });
         exit(code);
     });
-    worktreeCmd
-        .command('merge <name>')
-        .description('Merge a worktree branch into its base. Auto-closes the bound spec via caws specs close.')
-        .option('--dry-run', 'Validate prerequisites only; no git, no file writes, no events')
-        .option('--message <text>', 'Custom merge commit message (default: merge(worktree): <name>)')
-        .option('--data', 'Show structured data block on diagnostics')
+    defineLeaf(worktreeCmd, leafMeta(command_metadata_1.WORKTREE_COMMAND_META, 'merge'))
         .action((name, opts) => {
         const code = (0, index_1.runWorktreeMergeCommand)({
             name,
@@ -455,10 +548,102 @@ function registerShellCommands(program, options = {}) {
         });
         exit(code);
     });
-}
-/** Commander value collector for repeatable string options. */
-function collectMulti(value, prev) {
-    prev.push(value);
-    return prev;
+    defineLeaf(worktreeCmd, leafMeta(command_metadata_1.WORKTREE_COMMAND_META, 'migrate-registry'))
+        .action((opts) => {
+        const code = (0, index_1.runWorktreeMigrateRegistryCommand)({
+            ...(opts.dryRun === true ? { dryRun: true } : {}),
+            showData: opts.data === true,
+        });
+        exit(code);
+    });
+    defineLeaf(worktreeCmd, leafMeta(command_metadata_1.WORKTREE_COMMAND_META, 'repair-sparse'))
+        .action((name, opts) => {
+        const code = (0, index_1.runWorktreeRepairSparseCommand)({
+            name,
+            showData: opts.data === true,
+        });
+        exit(code);
+    });
+    // ─── caws agents (MULTI-AGENT-ACTIVITY-REGISTRY-001) ────────────────────
+    const agentsCmd = program.command('agents');
+    applyGroupMeta(agentsCmd, command_metadata_1.AGENTS_COMMAND_META);
+    defineLeaf(agentsCmd, leafMeta(command_metadata_1.AGENTS_COMMAND_META, 'register'))
+        .action((opts) => {
+        const code = (0, index_1.runAgentsRegisterCommand)({
+            ...(opts.sessionId !== undefined ? { sessionId: opts.sessionId } : {}),
+            ...(opts.platform !== undefined ? { platform: opts.platform } : {}),
+            ...(opts.reason !== undefined ? { reason: opts.reason } : {}),
+            json: opts.json === true,
+            includeActiveSummary: opts.includeActiveSummary === true,
+            showData: opts.data === true,
+        });
+        exit(code);
+    });
+    defineLeaf(agentsCmd, leafMeta(command_metadata_1.AGENTS_COMMAND_META, 'heartbeat'))
+        .action((opts) => {
+        const throttleMs = opts.throttle !== undefined ? Number(opts.throttle) : 0;
+        const code = (0, index_1.runAgentsHeartbeatCommand)({
+            ...(opts.sessionId !== undefined ? { sessionId: opts.sessionId } : {}),
+            ...(opts.platform !== undefined ? { platform: opts.platform } : {}),
+            ...(opts.reason !== undefined ? { reason: opts.reason } : {}),
+            throttleMs: Number.isFinite(throttleMs) && throttleMs > 0 ? throttleMs : 0,
+            json: opts.json === true,
+            includeActiveSummary: opts.includeActiveSummary === true,
+            showData: opts.data === true,
+        });
+        exit(code);
+    });
+    defineLeaf(agentsCmd, leafMeta(command_metadata_1.AGENTS_COMMAND_META, 'stop'))
+        .action((opts) => {
+        const code = (0, index_1.runAgentsStopCommand)({
+            ...(opts.sessionId !== undefined ? { sessionId: opts.sessionId } : {}),
+            ...(opts.platform !== undefined ? { platform: opts.platform } : {}),
+            json: opts.json === true,
+            showData: opts.data === true,
+        });
+        exit(code);
+    });
+    defineLeaf(agentsCmd, leafMeta(command_metadata_1.AGENTS_COMMAND_META, 'list'))
+        .action((opts) => {
+        const ttl = opts.staleTtlMs !== undefined ? Number(opts.staleTtlMs) : undefined;
+        const code = (0, index_1.runAgentsListCommand)({
+            includeStale: opts.includeStale === true,
+            includeStopped: opts.includeStopped === true,
+            activeOnly: opts.active === true,
+            ...(ttl !== undefined && Number.isFinite(ttl) ? { staleTtlMs: ttl } : {}),
+            json: opts.json === true,
+            showData: opts.data === true,
+        });
+        exit(code);
+    });
+    defineLeaf(agentsCmd, leafMeta(command_metadata_1.AGENTS_COMMAND_META, 'show'))
+        .action((id, opts) => {
+        const code = (0, index_1.runAgentsShowCommand)({
+            id,
+            json: opts.json === true,
+            showData: opts.data === true,
+        });
+        exit(code);
+    });
+    defineLeaf(agentsCmd, leafMeta(command_metadata_1.AGENTS_COMMAND_META, 'prune'))
+        .action((opts) => {
+        const status = opts.status === 'stopped' || opts.status === 'stale' ? opts.status : null;
+        const olderThanMs = Number(opts.olderThanMs);
+        if (status === null || !Number.isFinite(olderThanMs)) {
+            process.stderr.write('caws agents prune: --status must be stopped|stale and --older-than-ms must be a number.\n');
+            exit(1);
+            return;
+        }
+        const staleTtl = opts.staleTtlMs !== undefined ? Number(opts.staleTtlMs) : undefined;
+        const code = (0, index_1.runAgentsPruneCommand)({
+            status,
+            olderThanMs,
+            ...(staleTtl !== undefined && Number.isFinite(staleTtl) ? { staleTtlMs: staleTtl } : {}),
+            apply: opts.apply === true,
+            json: opts.json === true,
+            showData: opts.data === true,
+        });
+        exit(code);
+    });
 }
 //# sourceMappingURL=register.js.map