docs(appdelegate): apply commenting style guide (P0 of #64)

0 Fork 0

Rewrites App/AppDelegate.swift docstrings + inline comments to the
.planning/code-commenting-guide.md standard. Comments + docstrings
only — zero code behavior changes.

Closes the P0 entry in the migration table (#65 under epic #64).

Highlights:
- File header: 5-line opener + "See also" + audit-trail suffix.
- Class docstring: install-order ASCII DAG, threading model,
  "Before you edit" block listing the five sharp-edged invariants
  (single-writer HudState, locked install order, shared in-process
  tool registry, JIT entitlement, no-modal presentation).
- Property docstrings reorganized under role-named MARKs
  (Test-injectable seams / AppKit surfaces / HUD state coordinator
  + bus producer continuations / Orch→replay seam + MCP runtime /
  Boot health / Voice / Memory / Vision / Agent). Every property
  now leads with WHY; audit references (Plan IDs, B-/D-/CR- numbers,
  dated audits) are parenthetical suffixes.
- Public + key private method docstrings rewritten:
  applicationWillFinishLaunching gets the 16-step bootstrap + the
  hard-block branches called out; applicationWillTerminate explains
  why each cancellation is explicit; runBootHealth + register-
  BootHealthProbes list every probe + its role; installVoice /
  installMemory / installAgent / installVision /
  installSelfKnowledgeTools open with the subsystem's
  responsibility + fail-soft-vs-hard policy + step sequence.
- The motivating bad example from the guide
  (`inProcessToolRegistry` Plan-ID-lede comment) is rewritten
  exactly as the guide prescribes.
- Inline comments still carrying Plan-ID ledes ("Phase E 2026-05-03
  audit fix:", "Track B-4 (...):") rewritten to lead with WHY/WHAT
  with audit trail demoted to parentheticals at end.

Boundary gates:
- 18/18 green (full sweep: app-builds, bus-harness-parity,
  bus-protocol-version, corpus-secrets, embedding-dim-literal,
  install-order, no-evaluate-javascript, no-leftover-stubs,
  no-modal-presentation, no-null-voice-adapters,
  orchestrator-events-single-consumer,
  presence-bus-no-tts-orchestrator, presence-vision-isolation,
  single-memory-mutated-emit, single-memory-used-emit,
  single-writer-hudstate, vision-isolation,
  applescript-confirmation).
- check-install-order verified literal Task spawn lines + the
  `await self?.agentInstallTask?.value` invariant are intact.
- check-single-writer-hudstate verified AppDelegate still only
  references `.hudState(_:)` inside the allowlisted wiring closure.

Surfaced during review:
- None — only comments touched. The audit-2026-05-04 P3-16 split
  (AppDelegate+Voice/+Vision/+Memory/+Agent) remains outstanding
  but is out of scope for this P0.

Line delta: +965 / -740, net +225. Net growth is from the install-
order DAG ASCII art + the "Before you edit" block + expanded
six-step method docstrings.

Refs: #64, closes #65.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

This commit is contained in:

james.maesandClaude Opus 4.7 committed 2026-05-12 15:08:33 -05:00

1 parent b2710eee48

commit 281b9093e7

1 file changed

+962 -737

App/AppDelegate.swift

+962 -737

View File

File diff suppressed because it is too large. Load diff