Context

Four medium-priority gaps remain in the engine layer. Individually small, they collectively affect daily usability and code quality. Bundled here because each is 2-4 hours and they share no dependencies.

Claude Code estimate: ~1-2h

Current State (verified 2026-04-04)

Quiet hours

• `User` type has `quietHoursStart?: string` and `quietHoursEnd?: string`
• Settings API accepts and persists these fields
• Not enforced: `PolicyEvaluator` never checks quiet hours before auto-execution

Policy CRUD

• `action_policies` table exists in schema
• `PolicyEvaluator` reads via `getAllPolicies()`
• No API endpoints for CRUD
• Users manage behavior through domain autonomy + escalation triggers, but cannot create custom action-level policies

Type safety

• `apps/api/src/routes/ask.ts` line 102: `policyRepositoryAdapter as never`
• Lines 105-106: `twinService as never` and `policyEvaluator as never`
• Root cause: port interface method names don't match DB repository method names

Structured logging

• All logging via `console.log/warn/error`
• No JSON output, log levels, request IDs, or correlation

Proposed Change

1. Quiet hours enforcement

Add check in `PolicyEvaluator.evaluate()`: if current time is within quiet hours and outcome is auto-execute, escalate to approval with reason "Quiet hours active." Handle midnight wrap-around (22:00 → 07:00). Urgent escalations (safety, spend limit) still fire.

2. Policy CRUD API

GET/POST/PUT/DELETE at `/api/policies/:userId`. Settings page: "Advanced → Custom Policies" section. Not the primary flow.

3. Type safety cleanup

Create proper adapters in `ask.ts`, remove all `as never` casts. Grep entire codebase to verify zero remain.

4. Structured logging

Add `pino` to `@skytwin/core`. `createLogger(name)` factory. JSON output with timestamp, level, service, request ID. Replace all console calls. Human-readable in dev via `pino-pretty`. Desktop app logs to `~/Library/Logs/SkyTwin/`.

Acceptance Criteria

1. User sets quiet hours 22:00–07:00 → action at 23:00 with `outcome: 'auto-execute'` → policy evaluator changes outcome to `'request-approval'` with reason containing "Quiet hours"
2. User sets quiet hours 22:00–07:00 → action at 06:59 → escalated to approval (midnight wrap-around works)
3. User sets quiet hours 22:00–07:00 → action at 07:01 → auto-executes normally (boundary correct)
4. User sets quiet hours 22:00–07:00 → spend limit breach at 23:00 → notification still fires (urgent escalations bypass quiet hours)
5. User with no quiet hours configured → no change in behavior (null-safe)
6. `POST /api/policies/:userId` with valid policy → returns 201 → `GET /api/policies/:userId` includes new policy
7. `PUT /api/policies/:userId/:policyId` with updated conditions → returns 200 → policy enforced on next decision
8. `DELETE /api/policies/:userId/:policyId` → returns 204 → policy no longer returned by GET → no longer enforced
9. `POST /api/policies/:userId` with missing required field `name` → returns 400 with field-level error
10. Created policy with `actionType: 'email-send'` and `conditions: { requireApproval: true }` → next email-send action requires approval regardless of trust tier
11. `grep -r "as never" apps/ packages/` returns 0 results
12. API request to any endpoint → structured JSON log line emitted with: `timestamp`, `level`, `service: "api"`, `requestId` (UUID), `method`, `path`, `status`, `durationMs`
13. Worker poll cycle → log lines include `userId` field for the user being polled
14. Desktop app → logs written to `~/Library/Logs/SkyTwin/skytwin.log` in JSON format
15. `NODE_ENV=development` → logs are human-readable (pino-pretty), not raw JSON
16. All 432 existing tests pass
17. PR passes `/review` before merge

Testing Plan

Effort Estimate

• Quiet hours: ~20min
• Policy CRUD: ~30min
• Type safety: ~15min
• Structured logging: ~30min

Total: ~1-2h Claude Code time

Files Reference

Out of Scope

• Per-domain quiet hours (single global window sufficient for v0.4)
• Policy templates / presets
• Log aggregation / shipping to external service

Related

• Live notification layer: SSE, approval expiry cron, push alerts #8 — Notification layer should respect quiet hours for non-urgent events
• Part of v0.4 epic (Epic: SkyTwin v0.4 — Local-First Product Completion (HN Launch Ready) #12)

Working Context Protocol

During implementation, maintain two sources of truth to survive context compaction:

1. Local context file: Write progress, decisions, and blockers to .context/issue-14-engine-gaps.md (gitignored). Update this file after each meaningful step. On compaction, re-read this file to restore state.
2. GitHub issue: Post progress comments on #14 at key milestones (subtask complete, blocker hit, design decision made). Reference the issue URL in your conversation so it persists across compaction: Engine gaps: quiet hours, policy CRUD, type safety, structured logging #14

This ensures no quality loss across compaction events — the local file has granular state, the GitHub issue has durable history.