ln-629-runtime-lifecycle-config-auditor

What this skill does

> **Paths:** File paths (`references/`, `../ln-*`) are relative to this skill directory.

# Runtime Lifecycle & Config Auditor (L3 Worker)

**Type:** L3 Worker

Specialized worker auditing runtime readiness, lifecycle, and startup configuration validation.

## Purpose & Scope

- Audit **runtime lifecycle and config validation** (Category 12: Medium Priority)
- Check bootstrap, shutdown, signal handling, probes, resource cleanup, env/config sync, and fail-fast startup validation
- Emit `FIX_BOOTSTRAP`, `ADD_CONFIG_VALIDATION`, or `FIX_SHUTDOWN`
- Calculate compliance score (X/10)

## Inputs

**MANDATORY READ:** Load `references/audit_worker_core_contract.md`.
Tool policy: follow host AGENTS.md MCP preferences; load `references/mcp_tool_preferences.md` and `references/mcp_integration_patterns.md` only when host policy is absent or MCP behavior is unclear.

Receives `contextStore` with tech stack, deployment type, codebase root, output_dir.

Use `hex-graph` first when lifecycle tracing materially improves confidence. Use `hex-line` first for local code reads when available. If MCP is unavailable, unsupported, or not indexed, continue with built-in `Read/Grep/Glob/Bash` and state the fallback in the report.

## Workflow

Detection policy: use two-layer detection (candidate scan, then context verification); load `references/two_layer_detection.md` only when the verification method is ambiguous.

1) Parse context + output_dir
2) Check lifecycle and config validation patterns (Layer 1: grep for SIGTERM, shutdown handlers, probes, env reads, settings validation)
3) Analyze context per candidate (Layer 2):
   - Bootstrap order: read main file -- trace actual init sequence, verify dependencies satisfied before use
   - Graceful shutdown: read signal handlers -- do they actually close all resources? Or just log and exit?
   - Resource cleanup: read shutdown handler -- are ALL opened resources (DB, Redis, queues) closed?
   - Probes: check deployment config (Dockerfile, k8s manifests) -- is this containerized?
   - Config validation: are required env/config values validated at startup, before serving traffic?
4) Collect confirmed findings
5) Calculate score
6) **Write Report:** Build full markdown report in memory per `references/templates/audit_worker_report_template.md`, write to `{output_dir}/ln-629--global.md` in single Write call
7) **Return Summary:** Return minimal summary

## Audit Rules

### 1. Bootstrap Initialization Order
**Detection:**
- Check main/index file for initialization sequence
- Verify dependencies loaded before usage (DB before routes)

**Severity:**
- **HIGH:** Incorrect order causes startup failures

**Recommendation:** Initialize in correct order: config -> DB -> routes -> server

**Effort:** M (refactor startup)

### 2. Graceful Shutdown
**Detection:**
- Grep for `SIGTERM`, `SIGINT` handlers
- Check `process.on('SIGTERM')` (Node.js)
- Check `signal.Notify` (Go)

**Severity:**
- **HIGH:** No shutdown handler (abrupt termination)

**Recommendation:** Add SIGTERM handler, close connections gracefully

**Effort:** M (add shutdown logic)

### 3. Resource Cleanup on Exit
**Detection:**
- Check if DB connections closed on shutdown
- Verify file handles released
- Check worker threads stopped

**Severity:**
- **MEDIUM:** Resource leaks on shutdown

**Recommendation:** Close all resources in shutdown handler

**Effort:** S-M (add cleanup calls)

### 4. Signal Handling
**Detection:**
- Check handlers for SIGTERM, SIGINT, SIGHUP
- Verify proper signal propagation to child processes

**Severity:**
- **MEDIUM:** Missing signal handlers

**Recommendation:** Handle all standard signals

**Effort:** S (add signal handlers)

### 5. Liveness/Readiness Probes
**Detection (for containerized apps):**
- Check for `/live`, `/ready` endpoints
- Verify Kubernetes probe configuration

**Severity:**
- **MEDIUM:** No probes (Kubernetes can't detect health)

**Recommendation:** Add `/live` (is running) and `/ready` (ready for traffic)

**Effort:** S (add endpoints)

### 6. Startup Config Validation
**Detection:**
- Find env/config reads in startup path
- Check for validation frameworks or explicit fail-fast checks
- Compare required runtime vars from code with documented startup config when available

**Severity:**
- **HIGH:** Required config can be missing while app still starts
- **MEDIUM:** Defaults/desync can make local, CI, and deployed startup differ

**Recommendation:** Validate required config at boot and fail before accepting traffic

**Effort:** M

## Scoring Algorithm

**MANDATORY READ:** Load `references/audit_scoring.md`.

## Output Format

**MANDATORY READ:** Load `references/templates/audit_worker_report_template.md`.

Write JSON summary per `references/audit_summary_contract.md`. In managed mode the caller passes both `runId` and `summaryArtifactPath`; in standalone mode the worker generates its own run-scoped artifact path per shared contract.

Write report to `{output_dir}/ln-629--global.md` with `category: "Runtime Lifecycle & Config"` and checks: bootstrap_order, graceful_shutdown, resource_cleanup, signal_handling, probes, startup_config_validation.

Return summary per `references/audit_summary_contract.md`.

When `summaryArtifactPath` is absent, write the standalone runtime summary under `.hex-skills/runtime-artifacts/runs/{run_id}/evaluation-worker/{worker}--{identifier}.json` and optionally echo the same summary in structured output.
```
Report written: .hex-skills/runtime-artifacts/runs/{run_id}/audit-report/ln-629--global.md
Score: X.X/10 | Issues: N (C:N H:N M:N L:N)
```

## Reference Files

- **Audit output schema:** `references/audit_output_schema.md`

## Critical Rules

Apply the already-loaded `references/audit_worker_core_contract.md`.

- **Do not auto-fix:** Report only, lifecycle changes risk downtime
- **Deployment-aware:** Adapt probe checks to deployment type (Kubernetes = probes required, bare metal = optional)
- **Effort realism:** S = <1h, M = 1-4h, L = >4h
- **Exclusions:** Skip CLI tools and scripts (no long-running lifecycle), skip serverless functions (platform-managed lifecycle)
- **Initialization order matters:** Flag DB usage before DB init as HIGH regardless of context
- **Unique angle:** Audit runtime readiness and startup config validation only. Do not audit configuration architecture boundaries, package health, or diagnostic telemetry.
- **Action required:** Every finding uses `FIX_BOOTSTRAP`, `ADD_CONFIG_VALIDATION`, or `FIX_SHUTDOWN`.

## Definition of Done

Apply the already-loaded `references/audit_worker_core_contract.md`.

- [ ] contextStore parsed (deployment type, output_dir)
- [ ] All 6 checks completed (bootstrap order, graceful shutdown, resource cleanup, signal handling, probes, startup config validation)
- [ ] Findings collected with severity, location, effort, action, recommendation
- [ ] Score calculated per `references/audit_scoring.md`
- [ ] Report written to `{output_dir}/ln-629--global.md` (atomic single Write call)
- [ ] Summary written per contract

---
**Version:** 3.0.0
**Last Updated:** 2025-12-23