git:20260827.2442197 to git:20261024.e491978

15 added, 20 removed. Audit A to A.

# Click CLI

- The top-level `bernstein` command (`pyproject.toml` `[project.scripts]`

- maps it to `bernstein.cli.main:cli`). `main.py` builds the root click

- group and registers every subcommand; implementations live in

- `commands/` (one module per command or group).

+ The top-level `bernstein` command (`pyproject.toml` `[project.scripts]` maps it to `bernstein.cli.main:cli`). `main.py` builds the root click group and registers top-level commands and groups; implementations live in `commands/` (one module per command or group).

## Key files

| File | Purpose |

|---|---|

- | `main.py` | Root click group; all `cli.add_command(...)` registrations |

+ | `main.py` | Root click group; registers top-level commands and groups. Nested subcommands are registered on their parent group |

| `commands/` | Command and group implementations |

| `helpers.py` | Shared console and utility helpers |

| `run_cmd.py` | `bernstein run` entry; bootstrap/confirm split into siblings |

+ | `commands/governance_cmd.py` | The `bernstein govern` group: `verify`, `plan`, and the `audit`, `reconcile`, `inventory` and `lane` subcommands that live in `govern_*_cmd.py` |

+ | `commands/trust_cmd.py` | `bernstein trust`: the one sanctioned writer of `.sdd/runtime/workspace_trust.json` |

+ | `commands/verify_cmd.py`, `commands/verify_kinds.py` | `bernstein verify <artefact-path>` dispatches on the artefact's kind through a registry (#5103) |

+ | `commands/seal_cmd.py` | `bernstein seal`: anchors a run's sealed head outside this install (#4205) |

+ | `commands/identity_review_cmd.py` | `bernstein identity review` access review commands, registered by `commands/identity_cmd.py` |

| `commands/identity_attest_cmd.py` | `bernstein identity attest` run attestation CLI commands |

- | `commands/insights_cmd.py` | `bernstein insights`: analytics read out of task traces |

+ | `commands/insights_cmd.py` | Registered `bernstein insights` skeleton; echoes the requested window as text or JSON without computing analytics |

## Invariants

- - Keep heavy imports lazy inside command bodies so CLI startup stays

- fast; `commands/agents_md_cmd.py` documents the pattern.

- - Legacy flat import paths (`bernstein.cli.<module>`) are served by a

- meta-path finder in `__init__.py`; when moving a module, extend the

- redirect rather than leaving a shim file behind.

- - The CLI surface is tracked for reduction (issue #3147): prefer a

- subcommand on an existing group over a new top-level command.

- - Non-zero exit codes are operator contract; declare them as named

- constants and document them in the command docstring

- (`commands/resume_cmd.py` is the model).

+ - Keep heavy imports lazy inside command bodies so CLI startup stays fast; `commands/agents_md_cmd.py` documents the pattern.

+ - Legacy flat import paths (`bernstein.cli.<module>`) are served by a meta-path finder in `__init__.py`; when moving a module, extend the redirect rather than leaving a shim file behind.

+ - The CLI surface is tracked for reduction (issue #3147): prefer a subcommand on an existing group (`govern`, `identity`, `adapters`, `worktrees`) over a new top-level command.

+ - Non-zero exit codes are operator contract; declare them as named constants and document them in the command docstring (`commands/resume_cmd.py` is the model).

+ - Repository-authored commands (plugin and lifecycle hooks, workflow command nodes) run only in a trusted workspace. Nothing grants trust implicitly; only `bernstein trust` writes the record (`commands/trust_cmd.py`).

## Testing

- Single files only, e.g.

- `uv run pytest tests/unit/test_agents_md_cmd.py -x -q`; most commands

- have a matching `test_<name>_cmd.py` under `tests/unit/`.

+ Single files only, e.g. `uv run pytest tests/unit/test_agents_md_cmd.py -x -q`; most commands have a matching `test_<name>_cmd.py` under `tests/unit/`, and newer ones sit under `tests/unit/cli/`.

-

+