@tiangong-lca/cli 0.0.21 → 0.0.22

package/README.md

@@ -17,14 +17,16 @@ checkPaths:
   - bin/**
   - src/cli.ts
   - src/main.ts
-lastReviewedAt: 2026-06-29
-lastReviewedCommit: 695e6d6fe718cb92d499f3ce8be2dc24c3f6ce29
+lastReviewedAt: 2026-07-12
+lastReviewedCommit: 192ce9cb233af85b8bcf50136d37fd08d4ae8292
 ---
 
 # TianGong LCA CLI
 
 Package: `@tiangong-lca/cli` Executable: `tiangong-lca` Node: `24.x`
 
+Review note, 2026-07-12: `dataset maintenance plan/apply/verify` provides current-user RLS-scoped exact-row maintenance with immutable plans, explicit approval, per-action logs, platform audit correlation, and independent readback. `merge-support-aliases` now runs only in `target_mode=owner_draft`: source/target support and all changed rows stay private `state_code=0`; publication is a separate future workflow.
+
 ## Run
 
 One-off published run:
@@ -273,7 +275,9 @@ tiangong-lca dataset curation-queue verify --queue-dir /abs/path/to/curation-que
 tiangong-lca dataset evidence-search plan --query "中国2026年电力结构数据" --out-dir /abs/path/to/evidence-search --json
 tiangong-lca dataset evidence-search run --input ./evidence-search.request.json --results ./search-results.json --out-dir /abs/path/to/evidence-search --json
 tiangong-lca dataset references rewrite --input ./rows.jsonl --from flow:<old-id>@<old-version> --to flow:<new-id>@<new-version> --out-dir /abs/path/to/dataset-rewrite --json
-tiangong-lca dataset maintenance plan --scope ./maintenance-scope.json --operation redo-import --out-dir /abs/path/to/dataset-maintenance
+tiangong-lca dataset maintenance plan --scope ./maintenance-scope.json --operation redo-import --out-dir /abs/path/to/dataset-maintenance --page-size 1000 --timeout-ms 10000 --json
+tiangong-lca dataset maintenance apply --plan /abs/path/to/dataset-maintenance/maintenance-plan.json --commit --approve-plan <sha256> --confirm <current-account-email> --timeout-ms 10000 --json
+tiangong-lca dataset maintenance verify --plan /abs/path/to/dataset-maintenance/maintenance-plan.json --out-dir /abs/path/to/dataset-maintenance/verify --page-size 1000 --timeout-ms 10000 --json
 tiangong-lca lifecyclemodel auto-build --input ./examples/lifecyclemodel-auto-build.request.json --out-dir /abs/path/to/lifecyclemodel-run --json
 tiangong-lca lifecyclemodel validate-build --run-dir /abs/path/to/lifecyclemodel-run --json
 tiangong-lca lifecyclemodel publish-build --run-dir /abs/path/to/lifecyclemodel-run --json
@@ -316,7 +320,52 @@ For `dataset curation-queue build/next/verify`, the CLI owns entity-level Foundr
 
 For `dataset references rewrite`, `--commit` executes the state-aware save-draft path for patched process and lifecyclemodel rows; without `--commit`, the command only writes local rewrite artifacts.
 
-For `dataset maintenance plan/apply/verify`, the planned command family owns RLS-scoped delete/redo workflows for bad imports. The contract requires a frozen scope manifest, current-user visible snapshot, protected rows list, reference impact report, dry-run report, explicit commit report, and readback verification. Foundry and skills may orchestrate it, but they must not add private Supabase delete logic.
+## Dataset Maintenance
+
+`dataset maintenance plan/apply/verify` is the row-level cleanup surface for bad imports and the fixed BAFU private alias rewrite. It runs as the currently authenticated user and relies on RLS for visibility and ownership enforcement.
+
+```bash
+tiangong-lca dataset maintenance plan \
+  --scope ./maintenance-scope.json \
+  --operation merge-support-aliases \
+  --out-dir ./dataset-maintenance \
+  --page-size 1000 \
+  --timeout-ms 10000 \
+  --json
+
+tiangong-lca dataset maintenance apply \
+  --plan ./dataset-maintenance/maintenance-plan.json \
+  --commit \
+  --approve-plan <sha256> \
+  --confirm <current-account-email> \
+  --timeout-ms 10000 \
+  --json
+
+tiangong-lca dataset maintenance verify \
+  --plan ./dataset-maintenance/maintenance-plan.json \
+  --out-dir ./dataset-maintenance/verify \
+  --page-size 1000 \
+  --timeout-ms 10000 \
+  --json
+```
+
+The scope is intentionally narrow:
+
+- Each requested row must name its table, exact `id`, exact `version`, expected current owner, and draft `state_code=0` state.
+- `--operation` accepts `delete`, `retire`, `redo-import`, `repair-references`, or `merge-support-aliases`; it records the operator's maintenance intent and does not broaden the eligible row actions.
+- Only current-user `contacts`, `sources`, `flows`, and `processes` can become `save_draft` or `delete` actions.
+- `merge-support-aliases` requires top-level `target_mode: "owner_draft"` and accepts only two named batches, `time` and `length_time`. The scope must bind reviewed current-owner draft source and target FP/UG exact ids/versions to 52 `update_json_ordered` actions: 25 time rows (1 FP, 10 flows, 14 processes) and 27 length-time rows (1 FP, 13 flows, 13 processes). Process actions freeze every selected exchange index, internal id, flow id/version, direction, before hash, and both amount strings.
+- The alias factors are exact decimal strings: `0.00011415525114155251` for time and `1000` for length-time. Planning requires exactly 20 and 39 selected exchanges, preserves exactly 309 other exchanges in the affected processes, and proves the fixed source-zero/target-reference postconditions. The transformation changes references and the selected `meanAmount`/`resultingAmount`; it does not delete the source FP/UG rows.
+- Source alias support, target FP/UG, and every changed flow/process must all belong to the authenticated account at `state_code=0`. Public/shared, foreign-owner, mixed-visibility, non-draft, lifecyclemodel, and unsupported action/table rows remain protected.
+- The CLI classifies and executes an operator-authored scope; it does not decide whether rows are semantically duplicates, canonical replacements, or safe business-level cleanup targets.
+
+`plan` writes the frozen `maintenance-scope.json`, `rls-visible-snapshot.json`, `protected-rows.jsonl`, `reference-impact-report.json`, `maintenance-plan.json`, and `dry-run-report.json`. Alias plans additionally write `exchange-rewrite-plan.jsonl`, freeze current-owner state-0 target FP, target UG, and source UG snapshots for each batch, derive schema-valid desired payloads with matching embedded UUID/version, and include the exact closure, `modified_at`, hashes, conversion evidence, and postconditions in the approved plan. The plan SHA-256 is the approval identity; do not edit or recompute the plan after review.
+
+`apply` is write-disabled unless all three commit guards are present: `--commit`, `--approve-plan <sha256>`, and `--confirm <current-account-email>`. Before the first write it re-checks the whole plan for drift and persists `approval-record.json`. Ordinary draft updates/deletes use their platform paths. The ordered `time` plus `length_time` alias request is sent once to `cmd_dataset_alias_plan_guarded` with `target_visibility=owner_draft`; the CLI has neither a per-dimension fallback nor a 52-write sequential fallback. The RPC locks and validates the complete 52-row/59-exchange closure before both dimensions commit, so a second-dimension failure rolls back the first. It checks actor ownership, state 0, exact payload/timestamp locks and embedded UUID/version, rejects missing or phantom flow/exchange references, and returns one plan summary audit id plus both batch and per-row audit proofs. The CLI writes `alias-plan-progress.jsonl` together with plan-bound per-batch, per-row, and per-exchange ledgers. A lost response or incomplete derived ledger is repaired only by replaying the same whole plan and matching every returned plan and batch proof.
+
+`verify` performs a fresh remote readback rather than trusting the apply report and writes `readback-verify-report.json` in its own output directory. For alias plans it also requires both successful batch records, all 52 correlated row records, all 59 unique exchange records, unchanged support snapshots, and exact desired row payloads. It validates the RPC-returned audit ids against the local proof chain; it does not independently query `public.command_audit_log`.
+
+Foundry and skills may prepare the scope, invoke these commands, and retain their artifacts. They must not replace the CLI with direct SQL, service-role access, raw REST mutation, or private Supabase delete/update code.
 
 ## More Docs
 

package/dist/src/cli.js

@@ -54,6 +54,9 @@ import { runDatasetPatchApply, } from './lib/dataset-patch.js';
 import { runDatasetSaveDraft, } from './lib/dataset-save-draft-run.js';
 import { runDatasetClassificationApply, runDatasetClassificationAudit, runDatasetClassificationChildren, runDatasetClassificationPath, } from './lib/dataset-classification.js';
 import { runDatasetMaintenanceClearAccount, } from './lib/dataset-maintenance-clear-account.js';
+import { runDatasetMaintenancePlan } from './lib/dataset-maintenance-plan.js';
+import { runDatasetMaintenanceApply } from './lib/dataset-maintenance-apply.js';
+import { runDatasetMaintenanceVerify } from './lib/dataset-maintenance-verify.js';
 import { runDatasetSourceUploadAttachments, } from './lib/dataset-source-upload-attachments.js';
 function renderMainHelp(dotEnvStatus) {
     return `TianGong LCA CLI
@@ -74,7 +77,7 @@ Implemented Commands:
   doctor     show environment diagnostics
   search     flow | process | lifecyclemodel
   process    get | list | identity-preflight | build-plan | scope-statistics | dedup-review | auto-build | resume-build | publish-build | complete-required-fields | save-draft | batch-build | refresh-references | verify-rows
-  dataset    contract get | context-pack | classification children/path/audit/apply | curation-queue build/next/verify | import-lca convert | author | patch apply | save-draft | source upload-attachments | validate | verify-remote | bilingual extract/apply/validate | evidence-search plan/run | references rewrite/refresh-remote | maintenance clear-account
+  dataset    contract get | context-pack | classification children/path/audit/apply | curation-queue build/next/verify | import-lca convert | author | patch apply | save-draft | source upload-attachments | validate | verify-remote | bilingual extract/apply/validate | evidence-search plan/run | references rewrite/refresh-remote | maintenance clear-account/plan/apply/verify
   flow       get | list | identity-preflight | build-plan | fetch-rows | materialize-decisions | remediate | publish-version | publish-reviewed-data | build-alias-map | scan-process-flow-refs | plan-process-flow-repairs | apply-process-flow-repairs | regen-product | validate-processes
   lifecyclemodel auto-build | validate-build | publish-build | save-draft | graph | build-resulting-process | publish-resulting-process | orchestrate
   qa         process | flow | lifecyclemodel
@@ -85,7 +88,6 @@ Implemented Commands:
 Planned Surface (not implemented yet):
   auth       whoami | doctor-auth
   job        get | wait | logs
-  dataset maintenance plan | apply | verify
 
 Planned commands currently print an explicit "not implemented yet" message and exit with code 2.
 
@@ -128,7 +130,7 @@ Examples:
   tiangong-lca dataset evidence-search run --input ./evidence-search.request.json --results ./search-results.json --out-dir ./evidence-search
   tiangong-lca dataset references rewrite --input ./rows.jsonl --from flow:<old-id>@<old-version> --to flow:<new-id>@<new-version> --out-dir /abs/path/to/dataset-rewrite
   tiangong-lca dataset maintenance clear-account --out-dir /abs/path/to/account-clear --json
-  tiangong-lca dataset maintenance plan --scope ./maintenance-scope.json --operation redo-import --out-dir /abs/path/to/dataset-maintenance
+  tiangong-lca dataset maintenance plan --scope ./maintenance-scope.json --operation merge-support-aliases --out-dir /abs/path/to/dataset-maintenance
   tiangong-lca lifecyclemodel auto-build --input ./lifecyclemodel-auto-build.request.json --out-dir /abs/path/to/lifecyclemodel-run
   tiangong-lca lifecyclemodel validate-build --run-dir /abs/path/to/lifecyclemodel-run
   tiangong-lca lifecyclemodel publish-build --run-dir /abs/path/to/lifecyclemodel-run
@@ -279,9 +281,9 @@ Implemented Subcommands:
   references rewrite   Rewrite flow references in local process and lifecyclemodel rows
   references refresh-remote Refresh local TIDAS reference versions to latest reachable remote rows
   maintenance clear-account Dry-run or clear current authenticated account-owned dataset rows through RLS
-
-Planned Subcommands:
-  maintenance plan/apply/verify Plan, execute, and verify RLS-scoped dataset delete/redo maintenance
+  maintenance plan    Build an immutable, RLS-visible row-level maintenance plan
+  maintenance apply   Execute an explicitly approved maintenance plan through current-user RLS
+  maintenance verify  Read back affected rows and references against the immutable plan
 
 Examples:
   tiangong-lca dataset contract get --type process --include schema,methodology,ruleset --out-dir ./contract --help
@@ -307,25 +309,23 @@ Examples:
   tiangong-lca dataset references rewrite --input ./rows.jsonl --from flow:<old-id>@<old-version> --to flow:<new-id>@<new-version> --out-dir ./dataset-rewrite --help
   tiangong-lca dataset references refresh-remote --input ./rows.jsonl --out ./rows.refreshed.jsonl --out-dir ./dataset-reference-refresh --help
   tiangong-lca dataset maintenance clear-account --out-dir ./account-clear --json --help
-  tiangong-lca dataset maintenance plan --scope ./maintenance-scope.json --operation redo-import --out-dir ./dataset-maintenance --help
+  tiangong-lca dataset maintenance plan --scope ./maintenance-scope.json --operation merge-support-aliases --out-dir ./dataset-maintenance --help
 `.trim();
 }
 function renderDatasetMaintenanceHelp() {
     return `Usage:
   tiangong-lca dataset maintenance <clear-account|plan|apply|verify> [options]
 
-Status:
-  clear-account is implemented for current authenticated account cleanup.
-  plan/apply/verify remain reserved for row-level RLS-scoped cleanup and redo workflows and currently exit with code 2 for executable actions.
-
-Implemented Actions:
+Actions:
   clear-account Dry-run or delete current authenticated account-owned lifecyclemodels, processes, flows, sources, and contacts.
-
-Planned Actions:
   plan    Build an immutable maintenance plan from a scope manifest, visible remote snapshot, dependency impact report, and intended operation.
   apply   Execute an approved plan through current-user RLS and platform dataset command paths; never bypass RLS or delete rows outside the visible scope.
   verify  Re-fetch affected rows and references, then prove that deleted, updated, skipped, protected, and redone rows match the plan.
 
+Safety:
+  plan and verify are read-only.
+  apply is commit-only and requires --commit, the exact plan SHA-256 via --approve-plan, and the current account email via --confirm.
+
 Required Artifact Contract:
   - maintenance-plan.json
   - rls-visible-snapshot.json
@@ -338,11 +338,66 @@ Required Artifact Contract:
 Examples:
   tiangong-lca dataset maintenance clear-account --out-dir ./account-clear --json
   tiangong-lca dataset maintenance clear-account --commit --confirm user@example.com --out-dir ./account-clear
-  tiangong-lca dataset maintenance plan --scope ./maintenance-scope.json --operation redo-import --out-dir ./dataset-maintenance
-  tiangong-lca dataset maintenance apply --plan ./dataset-maintenance/maintenance-plan.json --commit
+  tiangong-lca dataset maintenance plan --scope ./maintenance-scope.json --operation merge-support-aliases --out-dir ./dataset-maintenance
+  tiangong-lca dataset maintenance apply --plan ./dataset-maintenance/maintenance-plan.json --commit --approve-plan <sha256> --confirm user@example.com
   tiangong-lca dataset maintenance verify --plan ./dataset-maintenance/maintenance-plan.json --out-dir ./dataset-maintenance/verify
 `.trim();
 }
+function renderDatasetMaintenancePlanHelp() {
+    return `Usage:
+  tiangong-lca dataset maintenance plan --scope <file> --operation <operation> --out-dir <dir> [options]
+
+Operations:
+  delete | retire | redo-import | repair-references | merge-support-aliases
+
+Options:
+  --scope <file>       Maintenance scope manifest
+  --operation <value> Intended row-level maintenance operation
+  --out-dir <dir>      Artifact directory
+  --page-size <n>      Snapshot page size
+  --timeout-ms <n>     Request timeout in milliseconds
+  --json               Print compact JSON
+  -h, --help
+
+Outputs written under --out-dir include the immutable maintenance-plan.json, visible snapshot,
+protected-row ledger, reference-impact report, and dry-run report.
+`.trim();
+}
+function renderDatasetMaintenanceApplyHelp() {
+    return `Usage:
+  tiangong-lca dataset maintenance apply --plan <file> --commit --approve-plan <sha256> --confirm <email> [options]
+
+Behavior:
+  Commit-only. The command rejects dry-run mode, a missing --commit flag, a plan hash mismatch,
+  or a confirmation email that does not match the current authenticated account.
+
+Options:
+  --plan <file>          Immutable maintenance-plan.json
+  --commit               Execute the approved plan
+  --approve-plan <sha256> Exact SHA-256 recorded for the plan
+  --confirm <email>      Current authenticated account email
+  --timeout-ms <n>       Request timeout in milliseconds
+  --json                 Print compact JSON
+  -h, --help
+
+Outputs include approval-record.json and commit-report.json alongside an append-only action ledger.
+`.trim();
+}
+function renderDatasetMaintenanceVerifyHelp() {
+    return `Usage:
+  tiangong-lca dataset maintenance verify --plan <file> [options]
+
+Options:
+  --plan <file>       Immutable maintenance-plan.json
+  --out-dir <dir>     Optional verification artifact directory
+  --page-size <n>     Readback page size
+  --timeout-ms <n>    Request timeout in milliseconds
+  --json              Print compact JSON
+  -h, --help
+
+Outputs include readback-verify-report.json with affected-row and reference checks.
+`.trim();
+}
 function renderDatasetMaintenanceClearAccountHelp() {
     return `Usage:
   tiangong-lca dataset maintenance clear-account [options]
@@ -2966,6 +3021,130 @@ function parseDatasetMaintenanceClearAccountFlags(args) {
         confirm: typeof values.confirm === 'string' ? values.confirm : null,
     };
 }
+function parseDatasetMaintenancePositiveInteger(value, flagName) {
+    if (typeof value !== 'string') {
+        return undefined;
+    }
+    if (!/^\d+$/u.test(value.trim()) || Number.parseInt(value.trim(), 10) <= 0) {
+        throw new CliError(`${flagName} must be a positive integer.`, {
+            code: 'DATASET_MAINTENANCE_INTEGER_INVALID',
+            exitCode: 2,
+            details: { flag: flagName, value },
+        });
+    }
+    return Number.parseInt(value.trim(), 10);
+}
+function parseDatasetMaintenancePlanFlags(args) {
+    let values;
+    try {
+        ({ values } = parseArgs({
+            args,
+            allowPositionals: false,
+            strict: true,
+            options: {
+                help: { type: 'boolean', short: 'h' },
+                json: { type: 'boolean' },
+                scope: { type: 'string' },
+                operation: { type: 'string' },
+                'out-dir': { type: 'string' },
+                'page-size': { type: 'string' },
+                'timeout-ms': { type: 'string' },
+            },
+        }));
+    }
+    catch (error) {
+        throw new CliError(String(error), {
+            code: 'INVALID_ARGS',
+            exitCode: 2,
+        });
+    }
+    const rawOperation = typeof values.operation === 'string' ? values.operation : null;
+    if (rawOperation !== null &&
+        !['delete', 'retire', 'redo-import', 'repair-references', 'merge-support-aliases'].includes(rawOperation)) {
+        throw new CliError("--operation must be 'delete', 'retire', 'redo-import', 'repair-references', or 'merge-support-aliases'.", {
+            code: 'DATASET_MAINTENANCE_OPERATION_INVALID',
+            exitCode: 2,
+            details: rawOperation,
+        });
+    }
+    return {
+        help: Boolean(values.help),
+        json: Boolean(values.json),
+        scopePath: typeof values.scope === 'string' ? values.scope : '',
+        operation: rawOperation,
+        outDir: typeof values['out-dir'] === 'string' ? values['out-dir'] : '',
+        pageSize: parseDatasetMaintenancePositiveInteger(values['page-size'], '--page-size'),
+        timeoutMs: parseDatasetMaintenancePositiveInteger(values['timeout-ms'], '--timeout-ms'),
+    };
+}
+function parseDatasetMaintenanceApplyFlags(args) {
+    let values;
+    try {
+        ({ values } = parseArgs({
+            args,
+            allowPositionals: false,
+            strict: true,
+            options: {
+                help: { type: 'boolean', short: 'h' },
+                json: { type: 'boolean' },
+                plan: { type: 'string' },
+                commit: { type: 'boolean' },
+                'approve-plan': { type: 'string' },
+                confirm: { type: 'string' },
+                'timeout-ms': { type: 'string' },
+                'dry-run': { type: 'boolean' },
+            },
+        }));
+    }
+    catch (error) {
+        throw new CliError(String(error), {
+            code: 'INVALID_ARGS',
+            exitCode: 2,
+        });
+    }
+    return {
+        help: Boolean(values.help),
+        json: Boolean(values.json),
+        planPath: typeof values.plan === 'string' ? values.plan : '',
+        commit: Boolean(values.commit),
+        approvePlan: typeof values['approve-plan'] === 'string' ? values['approve-plan'] : '',
+        confirm: typeof values.confirm === 'string' ? values.confirm : '',
+        timeoutMs: parseDatasetMaintenancePositiveInteger(values['timeout-ms'], '--timeout-ms'),
+        dryRun: Boolean(values['dry-run']),
+    };
+}
+function parseDatasetMaintenanceVerifyFlags(args) {
+    let values;
+    try {
+        ({ values } = parseArgs({
+            args,
+            allowPositionals: false,
+            strict: true,
+            options: {
+                help: { type: 'boolean', short: 'h' },
+                json: { type: 'boolean' },
+                plan: { type: 'string' },
+                'out-dir': { type: 'string' },
+                'page-size': { type: 'string' },
+                'timeout-ms': { type: 'string' },
+            },
+        }));
+    }
+    catch (error) {
+        throw new CliError(String(error), {
+            code: 'INVALID_ARGS',
+            exitCode: 2,
+        });
+    }
+    return {
+        help: Boolean(values.help),
+        json: Boolean(values.json),
+        planPath: typeof values.plan === 'string' ? values.plan : '',
+        outDir: typeof values['out-dir'] === 'string' ? values['out-dir'] : undefined,
+        pageSize: parseDatasetMaintenancePositiveInteger(values['page-size'], '--page-size'),
+        timeoutMs: parseDatasetMaintenancePositiveInteger(values['timeout-ms'], '--timeout-ms'),
+    };
+}
 function parseIdentityPreflightFlags(args) {
     let values;
     try {
@@ -4711,6 +4890,9 @@ export async function executeCli(argv, deps) {
         const datasetClassificationAuditImpl = deps.runDatasetClassificationAuditImpl ?? runDatasetClassificationAudit;
         const datasetClassificationApplyImpl = deps.runDatasetClassificationApplyImpl ?? runDatasetClassificationApply;
         const datasetMaintenanceClearAccountImpl = deps.runDatasetMaintenanceClearAccountImpl ?? runDatasetMaintenanceClearAccount;
+        const datasetMaintenancePlanImpl = deps.runDatasetMaintenancePlanImpl ?? runDatasetMaintenancePlan;
+        const datasetMaintenanceApplyImpl = deps.runDatasetMaintenanceApplyImpl ?? runDatasetMaintenanceApply;
+        const datasetMaintenanceVerifyImpl = deps.runDatasetMaintenanceVerifyImpl ?? runDatasetMaintenanceVerify;
         const datasetSourceUploadAttachmentsImpl = deps.runDatasetSourceUploadAttachmentsImpl ?? runDatasetSourceUploadAttachments;
         if (flags.version) {
             return { exitCode: 0, stdout: `${loadCliPackageVersion(import.meta.url)}\n`, stderr: '' };
@@ -5320,13 +5502,141 @@ export async function executeCli(argv, deps) {
                     stderr: '',
                 };
             }
-            if (!['plan', 'apply', 'verify'].includes(action)) {
-                throw new CliError("dataset maintenance action must be 'clear-account', 'plan', 'apply', or 'verify'.", {
-                    code: 'DATASET_MAINTENANCE_ACTION_INVALID',
-                    exitCode: 2,
+            if (action === 'plan') {
+                const datasetFlags = parseDatasetMaintenancePlanFlags(commandArgs.slice(1));
+                if (datasetFlags.help) {
+                    return {
+                        exitCode: 0,
+                        stdout: `${renderDatasetMaintenancePlanHelp()}\n`,
+                        stderr: '',
+                    };
+                }
+                if (!datasetFlags.scopePath) {
+                    throw new CliError('dataset maintenance plan requires --scope.', {
+                        code: 'DATASET_MAINTENANCE_SCOPE_REQUIRED',
+                        exitCode: 2,
+                    });
+                }
+                if (!datasetFlags.operation) {
+                    throw new CliError('dataset maintenance plan requires --operation.', {
+                        code: 'DATASET_MAINTENANCE_OPERATION_REQUIRED',
+                        exitCode: 2,
+                    });
+                }
+                if (!datasetFlags.outDir) {
+                    throw new CliError('dataset maintenance plan requires --out-dir.', {
+                        code: 'DATASET_MAINTENANCE_OUT_DIR_REQUIRED',
+                        exitCode: 2,
+                    });
+                }
+                const report = await datasetMaintenancePlanImpl({
+                    scopePath: datasetFlags.scopePath,
+                    operation: datasetFlags.operation,
+                    outDir: datasetFlags.outDir,
+                    pageSize: datasetFlags.pageSize,
+                    timeoutMs: datasetFlags.timeoutMs,
+                    env: deps.env,
+                    fetchImpl: deps.fetchImpl,
+                });
+                return {
+                    exitCode: report.status === 'blocked' ? 1 : 0,
+                    stdout: stringifyJson(report, datasetFlags.json),
+                    stderr: '',
+                };
+            }
+            if (action === 'apply') {
+                const datasetFlags = parseDatasetMaintenanceApplyFlags(commandArgs.slice(1));
+                if (datasetFlags.help) {
+                    return {
+                        exitCode: 0,
+                        stdout: `${renderDatasetMaintenanceApplyHelp()}\n`,
+                        stderr: '',
+                    };
+                }
+                if (!datasetFlags.planPath) {
+                    throw new CliError('dataset maintenance apply requires --plan.', {
+                        code: 'DATASET_MAINTENANCE_PLAN_REQUIRED',
+                        exitCode: 2,
+                    });
+                }
+                if (datasetFlags.commit && datasetFlags.dryRun) {
+                    throw new CliError('Cannot pass both --commit and --dry-run.', {
+                        code: 'DATASET_MAINTENANCE_APPLY_MODE_CONFLICT',
+                        exitCode: 2,
+                    });
+                }
+                if (datasetFlags.dryRun) {
+                    throw new CliError('dataset maintenance apply is commit-only; use dataset maintenance plan for a dry run.', {
+                        code: 'DATASET_MAINTENANCE_APPLY_COMMIT_ONLY',
+                        exitCode: 2,
+                    });
+                }
+                if (!datasetFlags.commit) {
+                    throw new CliError('dataset maintenance apply requires --commit.', {
+                        code: 'DATASET_MAINTENANCE_APPLY_COMMIT_REQUIRED',
+                        exitCode: 2,
+                    });
+                }
+                if (!datasetFlags.approvePlan) {
+                    throw new CliError('dataset maintenance apply requires --approve-plan <sha256>.', {
+                        code: 'DATASET_MAINTENANCE_APPROVAL_REQUIRED',
+                        exitCode: 2,
+                    });
+                }
+                if (!datasetFlags.confirm) {
+                    throw new CliError('dataset maintenance apply requires --confirm <email>.', {
+                        code: 'DATASET_MAINTENANCE_CONFIRM_REQUIRED',
+                        exitCode: 2,
+                    });
+                }
+                const report = await datasetMaintenanceApplyImpl({
+                    planPath: datasetFlags.planPath,
+                    commit: datasetFlags.commit,
+                    approvePlan: datasetFlags.approvePlan,
+                    confirm: datasetFlags.confirm,
+                    timeoutMs: datasetFlags.timeoutMs,
+                    env: deps.env,
+                    fetchImpl: deps.fetchImpl,
                 });
+                return {
+                    exitCode: report.status === 'completed_with_failures' ? 1 : 0,
+                    stdout: stringifyJson(report, datasetFlags.json),
+                    stderr: '',
+                };
             }
-            return plannedCommand('dataset', `maintenance ${action}`);
+            if (action === 'verify') {
+                const datasetFlags = parseDatasetMaintenanceVerifyFlags(commandArgs.slice(1));
+                if (datasetFlags.help) {
+                    return {
+                        exitCode: 0,
+                        stdout: `${renderDatasetMaintenanceVerifyHelp()}\n`,
+                        stderr: '',
+                    };
+                }
+                if (!datasetFlags.planPath) {
+                    throw new CliError('dataset maintenance verify requires --plan.', {
+                        code: 'DATASET_MAINTENANCE_PLAN_REQUIRED',
+                        exitCode: 2,
+                    });
+                }
+                const report = await datasetMaintenanceVerifyImpl({
+                    planPath: datasetFlags.planPath,
+                    outDir: datasetFlags.outDir,
+                    pageSize: datasetFlags.pageSize,
+                    timeoutMs: datasetFlags.timeoutMs,
+                    env: deps.env,
+                    fetchImpl: deps.fetchImpl,
+                });
+                return {
+                    exitCode: report.status === 'failed' ? 1 : 0,
+                    stdout: stringifyJson(report, datasetFlags.json),
+                    stderr: '',
+                };
+            }
+            throw new CliError("dataset maintenance action must be 'clear-account', 'plan', 'apply', or 'verify'.", {
+                code: 'DATASET_MAINTENANCE_ACTION_INVALID',
+                exitCode: 2,
+            });
         }
         if (command === 'lifecyclemodel' && !subcommand) {
             return { exitCode: 0, stdout: `${renderLifecyclemodelHelp()}\n`, stderr: '' };