Rules (non-negotiable)

• Zero console.log/error/warn/debug in source code — use logger.ts only
• DEBUG_MODE=false in production — enforced by check-env.js
• Every phase MUST create an INDEX.json entry before starting
• Every async error path MUST log via logger.error
• Log files are append-only — never overwrite
• Filesystem MCP MUST be used for running enforcement scripts (like check-shared-ui or check-boundaries) and to perform log file writes in ops/logs.

Patterns

logger.ts API (packages/shared/src/utils/logger.ts)

typescript
1import { logger } from '@/lib/logger'         // web-app
2import { logger } from '@/lib/logger'         // extension (re-export from shared)
3
4logger.debug('ModuleName', 'Short message', { context: data })
5logger.info('ModuleName', 'Something happened')
6logger.warn('ModuleName', 'Possible issue', details)
7logger.error('ModuleName', 'Failed to do X', error)

logger.ts implementation

typescript
1// packages/shared/src/utils/logger.ts
2const DEBUG = typeof process !== 'undefined'
3  ? process.env['DEBUG_MODE'] === 'true'
4  : false
5
6type Level = 'debug' | 'info' | 'warn' | 'error'
7
8function log(level: Level, module: string, message: string, data?: unknown): void {
9  if (level === 'debug' && !DEBUG) return
10  const entry = { ts: new Date().toISOString(), level, module, message, ...(data ? { data } : {}) }
11  if (level === 'error') {
12    // In production: send to telemetry (Sentry etc.)
13    // In development: console.error is allowed only here
14    if (DEBUG) console.error(JSON.stringify(entry))
15  } else {
16    if (DEBUG) console.log(JSON.stringify(entry))
17  }
18}
19
20export const logger = {
21  debug: (m: string, msg: string, d?: unknown) => log('debug', m, msg, d),
22  info:  (m: string, msg: string, d?: unknown) => log('info', m, msg, d),
23  warn:  (m: string, msg: string, d?: unknown) => log('warn', m, msg, d),
24  error: (m: string, msg: string, d?: unknown) => log('error', m, msg, d),
25}

Phase logging — ops/logs/INDEX.json schema

json
1{
2  "version": "1.0",
3  "last_updated": "ISO timestamp",
4  "logs": [
5    {
6      "id": "LOG-001",
7      "name": "monorepo-scaffold",
8      "phase": "PHASE-1",
9      "file": "ops/logs/LOG-001-monorepo-scaffold.log",
10      "status": "running",
11      "started_at": "ISO timestamp",
12      "completed_at": null,
13      "summary": null,
14      "mcp_gate": null
15    }
16  ]
17}

mcp_gate when applicable:

json
1"mcp_gate": { "result": "pass", "notes": "Extension syncs to Web App", "timestamp": "ISO" }

update-log.js commands

bash
1node scripts/update-log.js start    LOG-001 "monorepo-scaffold" "PHASE-1"
2node scripts/update-log.js log      LOG-001 info "Creating pnpm-workspace.yaml"
3node scripts/update-log.js log      LOG-001 warn "Node version mismatch, continuing"
4node scripts/update-log.js finish   LOG-001 "7 packages created, 0 errors"
5node scripts/update-log.js fail     LOG-001 "pnpm install failed — missing peer dep"
6node scripts/update-log.js mcp-gate LOG-001 "pass" "Auth verified in real browser"
7node scripts/update-log.js status   # human-readable phase overview

Log file format

[2026-03-18T10:00:00Z] [START] PHASE-1 monorepo-scaffold
[2026-03-18T10:00:01Z] [INFO] Creating pnpm-workspace.yaml
[2026-03-18T10:00:05Z] [WARN] Node version mismatch — continuing
[2026-03-18T10:00:08Z] [SUCCESS] pnpm install — 0 errors
[2026-03-18T10:00:11Z] [COMPLETE] monorepo-scaffold — 7 packages, 0 errors

Levels: START INFO WARN ERROR SUCCESS COMPLETE SKIP

Anti-patterns (forbidden)

typescript
1❌ console.log('data:', data)           // use logger.info
2❌ console.error('failed:', err)        // use logger.error
3❌ console.debug(...)                   // use logger.debug
4❌ // skipping log entry for a phase    // always update-log.js start first
5❌ catch (_) {}                         // always logger.error in catch

Verification checklist

• Zero console.* calls in source (run pnpm check:boundaries)
• logger.ts imported from @brainbox/shared or @/lib/logger
• Every phase has update-log.js start called before work begins
• Every async error path has logger.error call
• DEBUG_MODE=false in .env.production