feat: add targeted and JSON output to basectl workspace update

[codeforester]

Context

The core basectl workspace update command is already implemented and was previously closed as completed. It currently:

• walks manifest repositories in order;
• runs git pull --ff-only for present repositories;
• continues after individual failures;
• skips missing optional repositories and treats missing required repositories as failures;
• supports --dry-run;
• reports planned, updated, unchanged, skipped, and failed results in text.

This issue is reopened for the remaining targeting and automation enhancements.

Goal

Add two complementary capabilities to basectl workspace update:

1. select a subset of manifest repositories with --repos;
2. emit the existing result model as machine-readable JSON with --format json.

Proposed interface

basectl workspace update
basectl workspace update --repos base,base-cli
basectl workspace update --repos base,base-cli --dry-run
basectl workspace update --format json
basectl workspace update --repos base,base-cli --format json

Requirements

--repos

• Accept a comma-separated list of manifest repository names.
• Update only the selected repositories.
• Preserve manifest order in both text and JSON output.
• Validate the selection before any Git operation:
  • reject empty names and names not present in the manifest;
  • reject duplicate names.
• Keep the current all-repositories behavior when --repos is omitted.
• Preserve the existing required/optional and containment safety behavior for selected repositories.

--format json

• Keep text as the default output format.
• Emit exactly one JSON document to stdout and diagnostics only to stderr.
• Use a versioned document with schema_version: 1.
• Include workspace and manifest metadata, whether this was a dry run, the selected repositories, per-repository results, and aggregate counts.
• Per-repository records should expose the existing result semantics: repository name, path, required status, action, status, detail when available, and Git exit code when available.
• Represent dry-run work as planned without invoking Git.
• Preserve existing success/failure exit-code semantics.

Acceptance criteria

• --repos <name[,name...]> filters updates without changing the default behavior.
• Repository selection is validated before mutation and preserves manifest order.
• --format json emits the documented versioned schema.
• JSON output supports normal runs, dry runs, skipped repositories, and failures.
• Text output remains backward-compatible.
• Tests cover filtering, ordering, unknown/invalid selections, JSON schema and statuses, dry-run no-Git behavior, and aggregate exit codes.
• Command help, command reference, workspace-manifest documentation, AI context, and stability-tier/schema documentation are updated.

Non-goals

• Do not change the current git pull --ff-only strategy.
• Do not add automatic rebase, force-reset, conflict recovery, or dirty-tree mutation behavior here.
• Do not change manifest contents or clone missing repositories.

Those behaviors can be proposed separately if needed after this focused enhancement is shipped.

[codeforester]

Closing as completed: Base already ships basectl workspace update. The command is wired through the workspace dispatcher, documented in the command/help surfaces, covered by focused tests, and currently runs git pull --ff-only across manifest repositories while reporting updated, unchanged, skipped, and failed results.

Implementation history: #1919 introduced workspace-wide repository update, #1923 normalized its output, and #2099 added workspace-root containment hardening. The original proposal's additional --repos, JSON output, rebase, and conflict-specific behavior are separate enhancement opportunities rather than blockers to the core feature.

[codeforester]

Reopened for the agreed enhancement scope.

Recommendation: implement --repos and --format json together. They share the existing workspace-update result model, and the combination supports both safe targeted maintenance and CI/automation.

The issue now narrows the work to:

• validated comma-separated repository selection with manifest-order output;
• a versioned JSON envelope exposing per-repository statuses and aggregate counts;
• unchanged text-default and exit-code behavior;
• dry-run JSON with no Git operations.

The current git pull --ff-only behavior remains unchanged. Rebase, dirty-tree detection, conflict recovery, and force-reset behavior are explicitly non-goals for this slice.