Update docs and minor code visibility for consistency

Standardize capitalization in documentation files (README.md, SPEC.md, TODO.md, CONTRIBUTING.md, and sources/common-shell-perf/README.md) for section headers and terminology. Change BenchMetricsRecorder.metricDescriptors from internal to fileprivate for improved encapsulation.

Author: rismay

CONTRIBUTING.md

@@ -2,14 +2,14 @@
 
 Thanks for your interest in contributing!
 
-## Development setup
+## Development Setup
 
 - Swift toolchain: 6.1
 - Platforms: Linux (CI) and macOS (local).
 - Build: `swift build -c release`
 - Test: `swift test --parallel`
 
-## Coding guidelines
+## Coding Guidelines
 
 - Prefer explicit, long-form flags and option names.
 - No `Foundation.Process` at call sites; use CommonProcess/CommonShell runners.
@@ -22,13 +22,13 @@ Thanks for your interest in contributing!
 - Support: WrkstrmLog, WrkstrmFoundation, WrkstrmPerformance
 - Argument parsing: Apple Swift Argument Parser
 
-## Opening issues and PRs
+## Opening Issues and PRs
 
 - Include a concise summary and reproduction steps for bugs.
 - For features, describe the use case and acceptance criteria.
 - Keep PRs focused with clear rationale and tests where applicable.
 
-## License and conduct
+## License and Conduct
 
 By contributing, you agree that your contributions will be licensed under the
 MIT License (see `LICENSE`) and that you will abide by the `CODE_OF_CONDUCT.md`.

README.md

@@ -1,4 +1,4 @@
-# CommonShell – process execution wrapper
+# CommonShell – Process Execution Wrapper
 
 | GitHub Actions | Status |
 | -------------- | ------ |
@@ -48,7 +48,7 @@ Instrumentation├──────────────────▶ │
 - Runners (`ProcessRunnerKind`) handle the actual execution surface (Subprocess/Foundation/TSCBasic/Native).
 - Instrumentation and metrics tag invocations automatically (host kind propagates via `ProcessLogOptions.tags`).
 
-## CommandSpec-first model
+## CommandSpec-first Model
 
 ```swift
 public struct CommandSpec: Codable, Sendable {
@@ -75,7 +75,7 @@ public struct CommandSpec: Codable, Sendable {
 - Built-in keys: `.noop`, `.metrics` (via `ProcessMetricsRecorder`).
 - `ProcessLogOptions.tags["executionHost"]` records the host label automatically.
 
-## Running commands
+## Running Commands
 
 ```swift
 var shell = CommonShell(executable: .name("git"))
@@ -97,7 +97,7 @@ Low-level entry point:
 
 - `run(host:executable:arguments:runnerKind:)` — explicitly supply the host transform and executable identity.
 
-## Route planning & benchmarking
+## Route Planning & Benchmarking
 
 - `ShellRouteKind` still enumerates runners (`.auto`, `.native`, `.subprocess(kind)`).
 - Bench helpers (`BenchRoutes`, `BenchSupport`) now operate over `(host: ExecutionHostKind, executable: Executable, arguments: [String]) × [ShellRouteKind]`.

SPEC.md

@@ -1,4 +1,4 @@
-# CommonShell API Spec (v0.1 – planning)
+# CommonShell API Spec (V0.1 – Planning)
 
 ## Goal
 
@@ -12,7 +12,7 @@
   - Target `CommonProcess`: process abstraction (protocols + minimal types)
   - Target `CommonShell`: shell adapter built on CommonProcess
 
-## CommonProcess (target)
+## CommonProcess (Target)
 
 - `enum ExecutableReference` (name|path)
 - `struct Executable`
@@ -31,7 +31,7 @@
 - `struct ProcessError: Error, CustomStringConvertible` (from CommonProcessRunners)
   - `status: Int?`, `error: String`
 
-## CommonShell (target)
+## CommonShell (Target)
 
 - `struct CommonShell`
   - Properties
@@ -82,7 +82,7 @@
   - Use `Executable.name(_:)` / `Executable.path(_:)` for identity.
   - Construct `CommandSpec(executable: Executable, args: ...)` and let runners resolve.
 
-### Wrappers and PATH resolution
+### Wrappers and PATH Resolution
 
 - Wrappers transform identity (name/path) into a finalized command using unified `Executable`:
   - `direct(path)`: set `Executable.path(path)`, prepend `options`, append call‑site args.
@@ -113,12 +113,12 @@ let pwd = sh.withExec(reference: .path("/bin/pwd"))
 print(try await pwd.run(args: []))
 ```
 
-## Out of Scope (v0.1)
+## Out of Scope (V0.1)
 
 - Streaming/PTY, interactive input, line‑by‑line coalescing.
 - Global registries, environment mutation, or policy.
 
-## Implementation Notes (source reference only)
+## Implementation Notes (Source Reference Only)
 
 - Use the existing CommonShell codebase as a reference to port minimal process‑running logic into `CommonProcess`/`CommonShell`. Do not depend on or re‑export CommonShell.
 - Implement the smallest surface required by current call sites (blocking run + buffered output). Extend incrementally for streaming/interactive later.

TODO.md

@@ -1,11 +1,11 @@
-# TODO — CommonShell improvements
+# TODO — CommonShell Improvements
 
-### Typed host options
+### Typed Host Options
 <!-- id:common-shell-typed-host-options owner:platform-tooling priority:P2 labels:common-shell,api,status:planned epic:exec-layer estimate:4x7.5m -->
 - Replace raw `[String]` options for `.shell/.env/.npm/.npx` with typed enums/option sets.
 - Add documentation and examples; migrate internal call sites.
 
-### Timeout & cancellation
+### Timeout & Cancellation
 <!-- id:common-shell-timeout-cancel owner:platform-tooling priority:P1 labels:common-shell,api,status:in-progress epic:exec-layer estimate:3x7.5m -->
 - Add `timeout:` parameter to run APIs; guarantee cooperative cancellation semantics.
 - Surface `timedOut/cancelled` flags in structured results where appropriate.

sources/common-shell-bench/BenchMetricsRecorder.swift

@@ -78,7 +78,7 @@ final class BenchMetricsRecorder: ProcessMetricsRecorder, @unchecked Sendable {
   private static let metricDescriptorLookup: [String: MetricDescriptor] =
     Dictionary(uniqueKeysWithValues: metricDescriptorList.map { ($0.key, $0) })
 
-  static var metricDescriptors: [MetricDescriptor] { metricDescriptorList }
+  fileprivate static var metricDescriptors: [MetricDescriptor] { metricDescriptorList }
 
   private let queue = DispatchQueue(
     label: "wrkstrm.common-shell.bench.metrics",

sources/common-shell-perf/README.md

@@ -4,7 +4,7 @@ Opt‑in perf helpers for CommonShell that delegate to WrkstrmPerformance. The h
 the CommonShell package as a separate library product so callers can link them without pulling the
 extra dependency into the core target.
 
-## Add dependency
+## Add Dependency
 
 In a package that already depends on `CommonShell`: