feat(cli): simplify identity diagnostics (#124)

* feat(cli): simplify identity diagnostics

Make status and doctor concise, with --verbose for full diagnostic detail.
Keep actual push destinations, distinct warnings and one actionable next step.
Preserve short/JSON contracts, exits and offline behavior; add no prompts or dependencies.

Verified build, docs, 358 unit, 54 E2E and 138 release-workflow tests;
252 captured observations cover machine compatibility and effect boundaries.
Two Fish tests and one optional installation test skipped. Live authentication
and native screen-reader qualification were not performed.

* test(auth): wait for descendant termination before heartbeat checks

Use a bounded, identity-checked observation helper before sampling the
heartbeat. Keep the overall cleanup deadline and first-signal exits.
Add deterministic ordering and survivor controls, plus synthetic TAP
diagnostics for termination, timing and heartbeat observations.

No production runtime, public UX/schema, version or release changes.

Validation: build, unit (360 pass, 2 environment skips), E2E (54 pass,
1 optional install skip), release (138 pass), docs, auth (27 pass),
help/version and diff checks passed. Independent mutation controls
rejected missing observation and exceeded cleanup bounds.

Author: saraeloop

README.md

@@ -70,6 +70,14 @@ Use your actual username. `add` replaces the profile; include any other fields y
 
 For SSH prerequisites and a full walkthrough, read [Use the right Git identity for this repo](https://docs.gitrole.dev/guides/use-the-right-git-identity-for-this-repo/).
 
+Human `status` and `doctor` output is concise. Each diagnostic warning appears
+once; doctor lists every push destination, counts ok checks and keeps warn/info.
+Its `next` action is the same in both modes and never runs automatically. Use
+`gitrole status --verbose` or `gitrole doctor --verbose` for full explanations.
+Add `--offline` to keep diagnosis local. Verbosity does not add checks or change
+verdicts. `status --short` and `doctor --json` retain their exact machine output
+and exit behavior, including when combined with `--verbose`.
+
 ## Interpret results
 
 | Command | Purpose |

completions/_gitrole

@@ -146,6 +146,7 @@ case $state in
       status)
         _arguments \
           '--short[show machine-friendly one-line status output]' \
+          '--verbose[show full human-readable diagnostic details]' \
           '--offline[skip the live SSH githubUser probe and use local checks only]' \
           '(- :)'{-h,--help}'[print help]' \
           && ret=0
@@ -154,6 +155,7 @@ case $state in
         _arguments \
           '--json[write the diagnostic result as JSON]' \
           '--offline[skip all SSH execution and use local checks only]' \
+          '--verbose[show full human-readable diagnostic details]' \
           '(- :)'{-h,--help}'[print help]' \
           && ret=0
         ;;

completions/gitrole.bash

@@ -188,12 +188,12 @@ _gitrole() {
       ;;
     status)
       if [[ "$cur" == -* ]]; then
-        _gitrole_comp_words "--short --offline --help -h"
+        _gitrole_comp_words "--short --offline --verbose --help -h"
       fi
       ;;
     doctor)
       if [[ "$cur" == -* ]]; then
-        _gitrole_comp_words "--json --offline --help -h"
+        _gitrole_comp_words "--json --offline --verbose --help -h"
       fi
       ;;
     current|list)

completions/gitrole.fish

@@ -58,3 +58,5 @@ complete -c gitrole -f -n '__fish_seen_subcommand_from help' -a 'add import use
 
 complete -c gitrole -f -n '__fish_use_subcommand' -a auth -d 'Explicit authentication checks'
 complete -c gitrole -f -n '__fish_seen_subcommand_from auth; and not __fish_seen_subcommand_from test' -a test -d 'Observe SSH accounts'
+
+complete -c gitrole -f -n '__fish_seen_subcommand_from status doctor' -l verbose -d 'Show full human-readable diagnostic details'

docs/commands.md

@@ -123,3 +123,39 @@ Key loading passes `--` before the path. This follows OpenSSH argument parsing
 `GITROLE_SSH_ADD_BIN` executables must accept the same argument convention;
 arbitrary wrappers are not qualified. This does not guarantee that a key exists
 or that loading it will succeed.
+
+### Human diagnostic detail
+
+`gitrole status` shows the role, effective identity, scope and check outcomes.
+`gitrole doctor` lists every push destination in both modes, counts successful
+checks, and shows each warning and informational check. Verbose also lists every
+successful check; counts describe checks, not verified accounts or destinations.
+Multiline explanations stay indented beneath their check.
+
+Both modes give the same next action, ordered by missing/unobservable destination,
+history, identity/policy, then auth; remaining host/transport warnings follow.
+History advice requires resolving identity/policy warnings before making a commit.
+Outside a repository, enter the intended repository first. Policy conflicts ask
+you to review the effective identity and `.gitrole` allowed/default roles.
+For supported SSH destinations, auth advice offers the existing deliberate
+`gitrole auth test`, with its network/command/state effects and future-push limits.
+Unsupported transport warnings never imply an equivalent plain SSH command.
+The suggested action is never executed automatically. Unknown diagnostic errors
+keep their original detail rather than being guessed into an authentication cause.
+
+Use `gitrole status --verbose` or `gitrole doctor --verbose` for full reasons.
+Doctor also expands repository and configuration context. `--verbose` changes
+presentation only: no extra Git/SSH checks, writes or interactive prompts.
+Combine it with `--offline` to keep the existing zero-SSH boundary.
+
+Machine modes take precedence: `status --short --verbose` is identical to
+`status --short`; `doctor --json --verbose` is identical to `doctor --json`.
+Exits and report streams are unchanged. Human reports (including check warnings)
+are on stdout; operational errors remain on stderr. Use machine modes for scripts.
+
+A missing destination remains unverified; configure your intended push destination
+before retrying. `remote set` rewrites an existing origin, not creates one. An
+expected account is not an observed account. Offline/skipped and HTTPS-not-applicable
+authentication do not verify an account or a future push. In an unborn repository,
+status may exit 0 while doctor exits 2 for its history warning; verbosity preserves
+that distinction. Guided setup and a full-screen TUI are not part of this change.

docs/guides/troubleshoot-identity-warnings.md

@@ -74,3 +74,20 @@ Check `gitrole --version` and `command -v gitrole`, then read <a href="{{ '/guid
 <h2 id="limits">An aligned result still cannot establish push success</h2>
 
 A check does not prove refspec readiness or repository authorization. It observes current identity and default destinations. A later explicit `git push` target, `git commit --author`, or changed environment/configuration falls outside that snapshot.
+
+## Read concise output and expand details
+
+Start with `gitrole status` for check outcomes, or `gitrole doctor` for the
+warnings and every push destination. Default doctor counts ok checks; verbose
+lists them. Warn/info checks remain visible in both modes. Each warning is shown once. The `next` line is advice, not an
+automatic repair. Use `gitrole doctor --verbose` for complete reasons and context;
+use `gitrole doctor --offline --verbose` when SSH execution is not appropriate.
+
+With no default push destination, choose and configure the intended destination
+before retrying; gitrole won't guess the URL. Next-action priority is destination,
+then history, identity/policy, then auth, and does not change with verbosity.
+Resolve identity/policy warnings before making the first commit. A matching local identity can
+coexist with unverified authentication. Do not change SSH settings merely to clear
+a warning. An explicit `gitrole auth test` remains a separate deliberate action;
+it may prompt, run configured commands or change SSH state, and its connection
+observation does not clear doctor's verdict or prove a future push.

src/application/alignment.ts

@@ -329,10 +329,11 @@ export function buildPushAlignmentChecks(input: {
 }
 
 /** Condenses a probe-owned reason message for human output, preserving the full message for JSON. */
-export function summarizeSshMessage(message: string): string {
+export function summarizeSshMessage(message: string, verbose = false): string {
+  if (verbose) return message;
   const match = /^SSH account unverified:\n((?:- [^\n]+\n)+)\n([\s\S]*)$/.exec(message);
   if (!match) return message;
   const reasons = match[1].trimEnd().split('\n').map((line) => line.slice(2));
-  const more = reasons.length > 1 ? ' (and other differences; see gitrole doctor --json).' : '';
-  return `SSH account unverified: ${reasons[0]}${more} ${match[2]}`;
+  const more = reasons.length > 1 ? ` (and ${reasons.length - 1} other differences)` : '';
+  return `SSH account unverified: ${reasons[0]}${more}`;
 }

src/application/use-cases/status.ts

@@ -15,6 +15,8 @@ import { collectObservedState, type ObservedState } from '../observed-state.js';
 import { evaluateRepoPolicy, loadOptionalRepoPolicy } from '../repo-policy.js';
 
 export interface StatusOptions {
+  /** Include full human explanations without changing observations or verdicts. */
+  verbose?: boolean;
   /**
    * Skip the live SSH githubUser probe.
    * SSH `auth` is `na`. HTTPS pin checks still use the saved role and `.gitrole`.
@@ -48,7 +50,7 @@ export async function getStatus(
   return {
     roleName: role?.name ?? UNMATCHED_ROLE_NAME,
     commitIdentity,
-    pushAuth: formatPushAuth(role, observedState, httpsAuth, offline),
+    pushAuth: formatPushAuth(role, observedState, httpsAuth, offline, options.verbose === true),
     scope: observedState.scope.effective,
     localOverride: observedState.scope.hasLocalOverride,
     lastNonMergeCommit,
@@ -106,15 +108,16 @@ function formatPushAuth(
     sshAuth?: DoctorResult['sshAuth'];
   },
   httpsAuth?: HttpsAuthDescription,
-  offline = false
+  offline = false,
+  verbose = false
 ): string | undefined {
   if (observedState.repository.push) {
     const push = observedState.repository.push;
     if (push.targets.length === 1 && push.targets[0].remote.protocol === 'https' && httpsAuth) return formatHttpsPushAuth(httpsAuth);
     if (push.message || !push.targets.length) return push.message ?? 'push destination unverified';
     return push.targets.map(({ remote, sshAuth, message }) =>
       sshAuth?.ok && sshAuth.githubUser ? `${sshAuth.githubUser} via ${remote.host}` :
-      `${remote.name} ${remote.url} (${offline && remote.protocol === 'ssh' ? 'SSH authentication skipped (--offline); local checks only. An online check may connect and run configured SSH commands or change SSH state.' : message ?? (sshAuth?.message ? summarizeSshMessage(sshAuth.message) : 'authentication unverified')})`
+      `${remote.name} ${remote.url} (${offline && remote.protocol === 'ssh' ? 'SSH authentication skipped (--offline); local checks only. An online check may connect and run configured SSH commands or change SSH state.' : message ?? (sshAuth?.message ? summarizeSshMessage(sshAuth.message, verbose) : 'authentication unverified')})`
     ).join('; ');
   }
   if (observedState.sshAuth?.githubUser) {

src/cli/index.ts

@@ -342,6 +342,7 @@ Examples:
     .command('status')
     .description('check whether the current repo is aligned for commit and push')
     .option('--short', 'show machine-friendly one-line status output')
+    .option('--verbose', 'show full human-readable diagnostic details')
     .option('--offline', 'skip the live SSH githubUser probe and use local checks only')
     .addHelpText(
       'after',
@@ -362,6 +363,8 @@ HTTPS auth is unchanged, because it uses the saved role and .gitrole, not the ne
 
 Use this when you want to know whether the repo looks ready to commit or push.
 Use 'gitrole current' when you only want to know which saved role matches the active commit identity.
+Human output is concise; use --verbose for full explanations. --short takes
+precedence over --verbose and keeps its exact machine contract.
 Use 'gitrole status --short --offline' for a shell prompt. It does not open SSH.
 
 Policy:
@@ -391,9 +394,9 @@ Shell prompt:
   It is opt-in. It does not switch roles.
 `
     )
-    .action(async (options: { short?: boolean; offline?: boolean }) => {
-      const result = await getStatus(dependencies, { offline: options.offline === true });
-      io.stdout(options.short ? renderShortStatus(result) : renderStatus(result));
+    .action(async (options: { short?: boolean; offline?: boolean; verbose?: boolean }) => {
+      const result = await getStatus(dependencies, { offline: options.offline === true, verbose: !options.short && options.verbose === true });
+      io.stdout(options.short ? renderShortStatus(result) : renderStatus(result, options));
       commandExitCode = result.overall === 'aligned' ? 0 : 2;
     });
 
@@ -418,12 +421,18 @@ Failures write reasons to stderr. This command never changes roles or Git config
   program
     .command('doctor')
     .description('diagnose identity, remote, and SSH auth alignment')
+    .option('--verbose', 'show full human-readable diagnostic details')
     .option('--json', 'write the diagnostic result as JSON')
     .option('--offline', 'skip all SSH execution and use local checks only')
     .addHelpText(
       'after',
       `
 
+Human output lists every push destination, counts ok checks and keeps warn/info
+checks. --verbose expands all checks and context without additional checks.
+Both modes give the same next action: destination, history, identity/policy, then auth. --json takes precedence over
+--verbose and keeps the same full result and exit code.
+
 Checks:
   - effective git identity
   - repository context and branch
@@ -455,9 +464,9 @@ Offline:
   configured commands, contact the network or change SSH state.
 `
     )
-    .action(async (options: { json?: boolean; offline?: boolean }) => {
+    .action(async (options: { json?: boolean; offline?: boolean; verbose?: boolean }) => {
       const result = await doctor(dependencies, { offline: options.offline === true });
-      io.stdout(options.json ? JSON.stringify(result, null, 2) : renderDoctor(result));
+      io.stdout(options.json ? JSON.stringify(result, null, 2) : renderDoctor(result, 'doctor', options));
       commandExitCode = getDoctorExitCode(result);
     });