docs(02-config-overlays): create phase plan

2026-02-09 20:44:03 -08:00
parent d72a04ef99
commit 00b1716418
3 changed files with 368 additions and 2 deletions
@@ -0,0 +1,121 @@
+---
+phase: 02-config-overlays
+plan: 02
+type: execute
+wave: 2
+depends_on: ["02-01"]
+files_modified:
+  - src/cli/doctor.ts
+autonomous: true
+
+must_haves:
+  truths:
+    - "Running flynn doctor with FLYNN_ENV=staging (no staging.yaml) reports a clear error identifying the missing overlay file"
+    - "Running flynn doctor without FLYNN_ENV shows no overlay-related check (or passes silently)"
+    - "Running flynn doctor with FLYNN_ENV=docker and docker.yaml present shows overlay check passing"
+  artifacts:
+    - path: "src/cli/doctor.ts"
+      provides: "checkOverlayExists check for FLYNN_ENV overlay validation"
+      contains: "checkOverlay"
+  key_links:
+    - from: "src/cli/doctor.ts"
+      to: "src/cli/shared.ts"
+      via: "imports resolveOverlayPath to determine overlay path"
+      pattern: "resolveOverlayPath"
+---
+
+<objective>
+Add overlay file validation to `flynn doctor` — when FLYNN_ENV is set, verify the corresponding overlay YAML file exists.
+
+Purpose: Give operators clear diagnostic feedback when their environment overlay is misconfigured, rather than a cryptic file-not-found error at startup.
+
+Output: New doctor check in the existing checks array.
+</objective>
+
+<execution_context>
+@/home/will/.config/opencode/get-shit-done/workflows/execute-plan.md
+@/home/will/.config/opencode/get-shit-done/templates/summary.md
+</execution_context>
+
+<context>
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@.planning/STATE.md
+@.planning/phases/02-config-overlays/02-01-SUMMARY.md
+
+@src/cli/doctor.ts
+@src/cli/shared.ts
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Add checkOverlayExists to doctor.ts</name>
+  <files>src/cli/doctor.ts</files>
+  <action>
+Import `resolveOverlayPath` from `./shared.js` (add to existing import line).
+
+Create a new check function following the existing pattern:
+
+```typescript
+const checkOverlayExists: Check = async (ctx) => {
+  const overlayPath = resolveOverlayPath(ctx.configPath);
+  if (!overlayPath) {
+    return { status: 'skip', label: 'Config overlay', detail: '(FLYNN_ENV not set)' };
+  }
+  const env = process.env.FLYNN_ENV;
+  if (existsSync(overlayPath)) {
+    return { status: 'pass', label: 'Config overlay', detail: `(${env}.yaml found)` };
+  }
+  return { status: 'fail', label: 'Config overlay', detail: `FLYNN_ENV=${env} but ${overlayPath} not found` };
+};
+```
+
+Insert `checkOverlayExists` into the `allChecks` array — place it right after `checkConfigExists` and before `checkConfigParses`. This is the natural position: first check the base config exists, then check the overlay exists, then parse/validate the merged result.
+
+The updated array should be:
+```typescript
+const allChecks: Check[] = [
+  checkConfigExists,
+  checkOverlayExists,  // <-- NEW
+  checkConfigParses,
+  checkConfigValidates,
+  checkEnvVars,
+  checkDataDir,
+  checkSessionDb,
+  checkModelConnectivity,
+  checkTelegram,
+  checkMcpServers,
+  checkSkills,
+  checkTailscale,
+];
+```
+
+Note: `existsSync` is already imported at the top of doctor.ts. `resolveOverlayPath` needs to be added to the import from `./shared.js`.
+
+Run `pnpm test:run` to verify no regressions. Run `pnpm typecheck` for type safety.
+  </action>
+  <verify>Run `pnpm typecheck` — no type errors. Run `pnpm test:run` — full suite passes (1077+ tests).</verify>
+  <done>checkOverlayExists added to doctor.ts checks array. When FLYNN_ENV is set, doctor reports pass/fail for overlay file existence with the overlay path in the detail. When FLYNN_ENV is not set, the check is skipped. Full test suite passes.</done>
+</task>
+
+</tasks>
+
+<verification>
+1. `pnpm typecheck` — no type errors
+2. `pnpm test:run` — full suite passes (1077+ tests)
+3. Manual: `FLYNN_ENV=nonexistent pnpm start -- doctor` should show FAIL for Config overlay
+4. Manual: `pnpm start -- doctor` (no FLYNN_ENV) should show SKIP for Config overlay
+</verification>
+
+<success_criteria>
+- checkOverlayExists is in the doctor checks array after checkConfigExists
+- FLYNN_ENV=staging with no staging.yaml → doctor reports FAIL with "FLYNN_ENV=staging but /path/to/staging.yaml not found"
+- No FLYNN_ENV → doctor skips the overlay check
+- FLYNN_ENV=docker with docker.yaml present → doctor reports PASS
+- Full test suite passes with zero regressions
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/02-config-overlays/02-02-SUMMARY.md`
+</output>