kandev/docs/plans/debug-start-production-title/plan.md

spec, created, status

spec	created	status
docs/specs/platform/requirements/dev-preview-title-prefixes.md	2026-08-10	complete

Implementation Plan: Keep Debug Start on the Production Profile

Overview

make start-debug sets the legacy pprof debug variable. The profile loader currently treats that variable as a development selector, so it applies the Dev title prefix. Make KANDEV_DEBUG_DEV_MODE the only development selector, keep pprof as debug behavior, and preserve Dev Kandev for make dev. The debug launcher supplies Debug as the default title prefix, producing Debug Kandev without selecting the development profile.

The work proceeds from the backend profile contract to the launcher checks and then to the browser regression test and public documentation.

The confirmed root cause is in profiles.DetectEnvironment: its dev branch checks KANDEV_DEBUG_PPROF_ENABLED even though the release debug launcher sets that variable without selecting the development profile.

Backend and launchers

Profile selection

• apps/backend/internal/profiles/profiles.go: make KANDEV_DEBUG_DEV_MODE=true the only non-e2e signal for the dev profile. Keep KANDEV_DEBUG_PPROF_ENABLED available to the debug configuration and pprof routes.
• apps/backend/internal/profiles/profiles_test.go: add a pprof-only regression case that resolves to prod, keeps the title prefix out of the profile defaults, and keeps production feature defaults.

Debug title default

• apps/backend/internal/launcher/env.go: when the native debug launcher is used, supply KANDEV_WEB_TITLE_PREFIX=Debug only when the caller has not already supplied a prefix. Keep the explicit environment override contract.
• apps/backend/internal/launcher/start_test.go: verify the debug launcher supplies Debug by default and preserves an explicit prefix.
• apps/backend/internal/launcher/supervisor.go: preserve the title prefix in the restart manifest so a supervised restart keeps Debug Kandev.
• apps/backend/internal/launcher/supervisor_test.go: cover the allowlisted title prefix in the restart manifest.

Make targets

• apps/backend/Makefile: make the direct dev target export the canonical KANDEV_DEBUG_DEV_MODE=true selector. Make the direct start-debug target default to the Debug prefix while preserving an explicitly supplied KANDEV_WEB_TITLE_PREFIX. The debug target continues to export pprof and debug logging without the dev selector.
• scripts/check-make-shells: update the expected dev command for Unix, native Windows, and Git Bash/MSYS, plus the direct start-debug title environment.

Durable decision record

• docs/decisions/0007-runtime-feature-flags.md: reconcile the profile selector table with the corrected contract.
• docs/decisions/2026-08-10-debug-launcher-profile-selection.md: preserve the reason for separating diagnostic behavior from environment identity.
• docs/decisions/INDEX.md: index the new decision.

Frontend

No frontend production code changes are required. The existing server-shell and SPA title composition already uses KANDEV_WEB_TITLE_PREFIX correctly.

The existing title-prefix browser test will cover the debug-start result. This is browser metadata, not a layout or interaction surface. Desktop and phone viewports therefore have the same expected title, and no mobile-specific interaction test is required.

Public documentation

• docs/public/configuration.md: state that make start-debug keeps the production profile and uses the Debug Kandev title while enabling diagnostics.
• docs/public/cli.md: explain that --debug does not select the development profile; make dev is the development-profile launcher.
• docs/configuration.md: keep the internal configuration reference aligned.

Tests

• What: pprof-only startup selects prod and does not apply Dev. File: apps/backend/internal/profiles/profiles_test.go. How: isolated environment unit test through ApplyProfile.
• What: the native debug launcher supplies the Debug prefix by default and preserves an explicit prefix. File: apps/backend/internal/launcher/start_test.go. How: inspect the environment assembled for debug and non-debug starts.
• What: supervised restarts preserve the debug title prefix. File: apps/backend/internal/launcher/supervisor_test.go. How: assert the debug prefix survives the restart manifest allowlist.
• What: direct make dev emits the canonical dev selector across shells. File: scripts/check-make-shells. How: run the existing deterministic make -n shell matrix.
• What: the debug-start launcher uses the distinct debug title. File: apps/web/e2e/tests/system/title-prefix.spec.ts. How: restart the fixture with pprof enabled and both profile selectors disabled plus the launcher's Debug prefix, navigate to /, and assert Debug Kandev.
• What: development and preview title behavior remains unchanged. File: apps/web/e2e/tests/system/title-prefix.spec.ts. How: retain the existing Dev Kandev and Preview Kandev assertions.

E2E Tests

• Scenario: GIVEN a backend restarted with pprof/debug behavior and no development or e2e selector, WHEN the browser opens Kandev, THEN the title is Debug Kandev.
• Scenario: GIVEN a backend restarted with the development selector, WHEN the browser opens Kandev, THEN the title is Dev Kandev.
• Scenario: GIVEN a backend with an explicit Preview prefix, WHEN the browser opens Kandev, THEN the title is Preview Kandev.
• File: apps/web/e2e/tests/system/title-prefix.spec.ts.
• Mobile note: document.title is viewport-independent. The existing browser metadata assertion covers the same user outcome on a phone, so no mobile-*.spec.ts file is needed.

Verification Results

• make test-backend — passed (full backend test suite).
• make lint-backend — passed (0 issues).
• make build-backend — passed (backend binaries built).
• cd apps/backend && make check-make-shells — passed for Unix, native Windows, and Git Bash/MSYS dispatch, including explicit prefixes with spaces.
• cd apps/web && pnpm e2e:run --project chromium tests/system/title-prefix.spec.ts — passed (3 tests).
• node --test scripts/validate-public-docs.test.mjs — passed (58 tests).
• node scripts/validate-public-docs.mjs — passed (41 published docs pages).
• git diff --check — passed.

Implementation Waves And Parallel Candidates

Wave 1 (sequential):

• task-01-profile-selector-contract

Wave 2 (sequential, depends on Wave 1):

• task-02-title-regression-docs

Parallel delegation is not authorized by this plan. The work stays in the primary session and follows the dependency order above.

Open Questions

None.