feat: add inst_023 - background process lifecycle management

Added comprehensive governance rule for managing dev servers, file
watchers, and daemon processes across session boundaries.

Key requirements:
- Document process intent before spawning background processes
- Kill non-essential processes before session handoff
- Check for orphaned processes at session start
- Prefer foreground dev servers to avoid port conflicts

Prevents EADDRINUSE errors and resource leaks across sessions.

Related: inst_006 (session management)
Trigger: User observed npm start processes causing port conflicts

Stats: OPERATIONAL quadrant count updated from 6 to 7
This commit is contained in:
TheFlow 2025-10-11 17:44:06 +13:00
parent aa381e3b5f
commit 7fc834e0bd

View file

@ -427,14 +427,40 @@
"related_instructions": ["inst_020"],
"active": true,
"notes": "RECURRING DEPLOYMENT ISSUE 2025-10-11 - Despite inst_020 requiring permission validation, /public/koha/ directory had 0700 permissions (same pattern as /public/admin/ in previous session). Root cause: rsync creates directories with restrictive umask defaults, and inst_020 focuses on reactive validation rather than proactive automation. This shifts from 'MUST ensure permissions' (principle) to 'USE --chmod flag or automated fix' (automation requirement). Prevents manual permission fixing after discovering 403 errors."
},
{
"id": "inst_023",
"text": "Background processes spawned during development sessions (dev servers, file watchers, daemons) MUST be explicitly managed: (1) Document process intent and expected lifetime before spawning, (2) Kill non-essential background processes before session handoff unless explicitly marked 'session-persistent' with justification, (3) When starting sessions, check for orphaned processes from previous sessions before spawning new ones, (4) Development servers should run in foreground when possible to avoid port conflicts and resource leaks across session boundaries.",
"timestamp": "2025-10-11T17:40:00Z",
"quadrant": "OPERATIONAL",
"persistence": "HIGH",
"temporal_scope": "PERMANENT",
"verification_required": "MANDATORY",
"explicitness": 1.0,
"source": "user",
"session_id": "2025-10-11-admin-deployment",
"parameters": {
"trigger_conditions": ["run_in_background parameter", "npm start/dev commands", "daemon spawning", "session handoff creation"],
"cleanup_protocol": {
"before_handoff": "List background processes via /bashes or BashOutput, kill non-essential",
"session_start": "Check lsof -ti:PORT for orphaned processes",
"exception": "Production services (systemd-managed) are separate from dev sessions"
},
"common_culprits": ["npm start", "npm run dev", "npm run watch", "nodemon", "file watchers"],
"verification_commands": ["lsof -ti:9000", "ps aux | grep npm"],
"cleanup_example": "KillShell <shell_id> then kill <pid> for orphaned processes"
},
"related_instructions": ["inst_006"],
"active": true,
"notes": "IDENTIFIED 2025-10-11 - User observed background npm start processes running throughout session (shells 9c58f4 and 44704b). Shell 9c58f4 failed with EADDRINUSE (port 9000 occupied), shell 44704b ran successfully for 2.5 hours. This creates: (1) Resource consumption across session boundaries, (2) Port conflicts in subsequent sessions, (3) Confusion about system state, (4) Unclear handoff expectations. User specifically asked: 'should we contemplate a rule to manage daemons/spawns on development and ensure we do not compromise session handovers'. Cleanup performed: Killed shell 44704b and orphaned processes before creating this instruction. Production server (systemd tractatus.service) is separate and intentionally persistent."
}
],
"stats": {
"total_instructions": 22,
"active_instructions": 22,
"total_instructions": 23,
"active_instructions": 23,
"by_quadrant": {
"STRATEGIC": 6,
"OPERATIONAL": 6,
"OPERATIONAL": 7,
"TACTICAL": 1,
"SYSTEM": 9,
"STOCHASTIC": 0