feat: add use-log-helpers rule to ARCH-002

Extend ARCH-002 to enforce centralized logging in helper and engine
files. The new `use-log-helpers` rule flags direct console.log/warn/info
calls, requiring logInfo/logWarn/logDebug from helpers/log.ts instead.

Command files are exempt (I/O layer), along with log.ts (canonical
implementation), reporter.ts (check output system), and login-flow.ts
(interactive device flow UI).

Author: rhuanbarreto

.archgate/adrs/ARCH-002-error-handling.md

@@ -54,6 +54,7 @@ Use three exit codes with clear semantics:
 - Don't catch and swallow unexpected errors — let them propagate
 - Don't show stack traces for user errors
 - Don't use `console.error()` directly — use `logError()` for consistent formatting
+- Don't use `console.log()` or `console.warn()` directly in helper or engine files — use `logInfo()` or `logWarn()` (command files are the I/O layer and may use console directly)
 - Don't exit with code 0 when an operation fails
 - Don't use exit codes other than 0, 1, or 2
 
@@ -122,7 +123,7 @@ try {
 ### Risks
 
 - **Swallowed errors in async code** — Async functions that catch errors without re-throwing can silently fail. Unhandled promise rejections in Bun terminate the process with a non-zero exit code, which provides a safety net, but the error message may be unclear.
-  - **Mitigation:** The `logError()` convention makes explicit error handling visible in code review. The `use-log-error` automated rule flags direct `console.error()` usage, nudging developers toward the standard pattern.
+  - **Mitigation:** The log helper convention makes explicit error handling visible in code review. The `use-log-error` rule flags direct `console.error()` usage, and the `use-log-helpers` rule flags direct `console.log()`/`console.warn()` in helper and engine files, nudging developers toward the standard pattern.
 - **Exit code 2 masking real issues** — If an unexpected error occurs in a rule file, the CLI exits with code 2 ("internal error") rather than code 1 ("violations"). This could confuse CI systems that only check for non-zero exit.
   - **Mitigation:** The check engine wraps rule execution with timeout and error boundaries, reporting rule errors separately from violations. The `--verbose` flag shows which rules errored.
 
@@ -131,6 +132,7 @@ try {
 ### Automated Enforcement
 
 - **Archgate rule** `ARCH-002/use-log-error`: Scans all source files (excluding `helpers/log.ts` and test files) for `console.error()` usage and flags violations. Severity: `error`.
+- **Archgate rule** `ARCH-002/use-log-helpers`: Scans helper and engine files for direct `console.log()`, `console.warn()`, or `console.info()` usage. Excludes `helpers/log.ts` (canonical implementation), `engine/reporter.ts` (check output system), `helpers/login-flow.ts` (interactive device flow UI), and test files. Command files are exempt since they are the I/O layer. Severity: `error`.
 - **Archgate rule** `ARCH-002/exit-code-convention`: Scans all source files for `process.exit()` calls and verifies the exit code is 0, 1, or 2. Severity: `error`.
 
 ### Manual Enforcement

.archgate/adrs/ARCH-002-error-handling.rules.ts

@@ -24,6 +24,34 @@ export default defineRules({
       }
     },
   },
+  "use-log-helpers": {
+    description:
+      "Use log helpers instead of console.log/warn/info in helper and engine files",
+    async check(ctx) {
+      const files = ctx.scopedFiles.filter(
+        (f) =>
+          (f.includes("helpers/") || f.includes("engine/")) &&
+          !f.endsWith("helpers/log.ts") &&
+          !f.endsWith("engine/reporter.ts") &&
+          !f.endsWith("helpers/login-flow.ts") &&
+          !f.includes("tests/")
+      );
+      const matches = await Promise.all(
+        files.map((file) => ctx.grep(file, /console\.(log|warn|info)\s*\(/))
+      );
+      for (const fileMatches of matches) {
+        for (const m of fileMatches) {
+          ctx.report.violation({
+            message:
+              "Use logInfo/logWarn/logDebug from helpers/log.ts instead of direct console output",
+            file: m.file,
+            line: m.line,
+            fix: "Import { logInfo, logWarn } from '../helpers/log' and use logInfo() or logWarn()",
+          });
+        }
+      }
+    },
+  },
   "exit-code-convention": {
     description: "Process.exit should use codes 0, 1, or 2 only",
     async check(ctx) {

CLAUDE.md

@@ -82,7 +82,7 @@ Bun 1.3.9, Node LTS, npm 11.11.0. Minimum user-facing Bun: `>=1.2.21` (enforced
 ## Self-Governance ADRs (`.archgate/adrs/`)
 
 - `ARCH-001` — Command structure (register pattern, no business logic)
-- `ARCH-002` — Error handling (exit codes, logError)
+- `ARCH-002` — Error handling (exit codes, log helpers)
 - `ARCH-003` — Output formatting (styleText, --json, no emoji)
 - `ARCH-004` — No barrel files (direct imports only)
 - `ARCH-005` — Testing standards (Bun test, fixtures, 80% coverage)