style(docs): de-slop JSDoc on report folding, hang threshold, silenceMs

Drop em dashes, announcement openers ("Default false:"), and
anthropomorphism ("carries the actionable punchline").

Author: sitapix

src/domain/ports/process-runner.ts

@@ -42,9 +42,9 @@ export interface ProcessOutput {
    * Milliseconds between the child's last stdout/stderr emission and the
    * process exit (or kill). Undefined when the runner did not track it.
    *
-   * Generic timing signal: callers can use it to distinguish "still emitting
-   * output at exit" from "went silent before exit". Interpretation (what
-   * counts as long, what action to recommend) is the caller's responsibility.
+   * Callers use this to tell "still emitting output at exit" from "went
+   * silent before exit". The caller decides what counts as long and what
+   * action to recommend.
    */
   readonly silenceMs?: number;
 }

src/interface/cli/format-report.ts

@@ -36,12 +36,10 @@ const SHOW_FIRST = 3;
 
 export interface FormatReportOptions {
   /**
-   * Expand info-severity groups (show example rows + collapse summary like
-   * warnings and errors). Default false: info groups render as header-only
-   * because info is background context, not a punch list, and showing every
-   * row inflates the report on info-heavy sites without changing what the
-   * user has to do. Errors and warnings ignore this flag — both are always
-   * fully rendered.
+   * Expand info-severity groups so they render rows + collapse summary like
+   * warnings and errors. Defaults to false. Info diagnostics are background
+   * context; rendering every row inflates the report without surfacing new
+   * actions. Errors and warnings ignore this flag and always render rows.
    */
   readonly verbose?: boolean;
 }
@@ -206,10 +204,10 @@ function formatGroupHeader(ruleId: string, items: ReadonlyArray<TaggedDiagnostic
 }
 
 /**
- * One-line teaser for a folded info group: first sentence of the first
- * message, dim and indented. Carries the actionable punchline ("Install
- * starlight-openapi") without re-expanding every row. Returns null if the
- * group is empty.
+ * Build a one-line teaser for a folded info group: the first sentence of
+ * the group's first message, dim and indented. The user still sees the
+ * action signal ("Install starlight-openapi") without --verbose. Returns
+ * null if the group is empty.
  */
 function formatTeaser(first: TaggedDiagnostic | undefined): string | null {
   if (first === undefined) return null;

src/use-cases/validate-output/run-astro-check.ts

@@ -92,10 +92,9 @@ function looksLikeNotInstalled(stdout: string, stderr: string): boolean {
 }
 
 /**
- * Threshold past which stdout silence before kill is interpreted as "hung",
- * not "slow". 30s is conservative: astro check on a 2k-page site still emits
- * progress more often than that, so longer gaps signal a tight loop in the
- * language server rather than honest forward progress.
+ * Threshold past which we call a silent gap a hang instead of slow progress.
+ * 30s is conservative: astro check on a 2k-page site emits progress more
+ * often than that. Longer gaps point at a tight loop in the language server.
  */
 const HANG_SILENCE_MS = 30_000;