[processes] Feature: Agent tasks that edit shell scripts must include full file content in context, not just a file path pointer

[rogelsm]

Feature Description

Agent tasks that modify shell scripts should be required (or strongly guided) to include the full file content in the agent prompt context object, not just a file path pointer.

Currently, process authors pass a file path (e.g., healthScript: ~/.local/bin/health-monitor.sh) and instruct the agent to "read and edit this file". This leads to agents editing functions in isolation without understanding the full script context, missing critical interactions between functions — a phenomenon we call "blind spot editing".

The fix is for process creation guidelines to mandate (and optionally lint) that any agent task whose purpose involves editing a shell script passes the full file content via fullScriptContent: $(cat $SCRIPT_PATH) in its context object.

Real-World Evidence

In the trip-planner project, the fix-stale-sync process passed healthScript: ~/.local/bin/health-monitor.sh as context and told the agent to add a check_sync_freshness() function. The agent added the function and wired it to call sync_project() — without knowing that sync_project() contains rm -rf $DEV_DIR (a full directory deletion). The result: 5 consecutive process runs, 5 failures, each time triggering a destructive wipe. Had the process template required fullScriptContent: $(cat ~/.local/bin/health-monitor.sh), the agent would have seen the destructive implementation and added a server-running guard.

Use Cases

Primary

• A process adds check_sync_freshness() to health-monitor.sh. With full content, the agent sees sync_project() is destructive and adds a guard. Without it, rm -rf $DEV_DIR runs unchecked.
• A babysitter infra process appends a cron-management function to a deploy script. With full content, the agent avoids duplicating logic or calling the wrong helper.
• A process adds rotation logic to a backup script. With full content, the agent sees existing globals and writes compatible code instead of shadowing them.
• A process adds logging to a script. With full content, the agent places the log call after the existing logger initialization, not before it.

Secondary

• Auditability: the pre-edit script content is preserved in task inputs, providing an automatic snapshot before destructive changes.
• Debugging: when a failed run is investigated, the full-script context shows exactly what the agent was working with.
• Lint: a static-analysis pass can detect context fields matching /[Ss]cript|[Pp]ath/ whose values are file-path strings without a paired content field and emit a warning.

User Stories

• As a process author, I want guidelines that require me to pass full script content (not just file paths) in agent task contexts so that the agent has full visibility before making edits.
• As a babysitter user, I want agent tasks that edit shell scripts to never cause destructive side-effects from missing context so that my infrastructure remains safe.
• As a process library maintainer, I want a lint warning when a script-editing agent task context only contains a path string (no file content) so that process authors are guided to the correct pattern.

Impact Analysis

• Breaking changes: No
• Complexity: Low
• Community contributable: Yes
• Estimated effort: Small — primarily a documentation/guidelines update with an optional low-complexity lint addition
• Risks:
  • Large scripts passed as context may increase token consumption; mitigated by the fact that the benefit (preventing destructive edits) outweighs the cost, and most infra scripts are under a few hundred lines.
  • Process authors may forget to update existing processes; a lint warning at process-load time would surface these gaps.
  • Shell quoting/newline handling when embedding script content in JSON context objects requires care — the guideline should include a concrete, tested example.

Acceptance Criteria

• Process creation guidelines state that any agent task whose purpose involves editing a shell script MUST pass the full file content (not just a path) in the context object.
• An example template showing fullScriptContent: $(cat $SCRIPT_PATH) is provided in the process-library documentation.
• A lint/validation step warns (or errors) when a script-editing agent task context contains a field ending in Script or Path that holds a file-path string but no corresponding content field.
• The fix-stale-sync process (and similar infra processes) are updated to pass full script content as a reference implementation.
• At least one test process in the test suite validates that agent tasks receive and use full script content.

Implementation Approach

1. Update the process-library agent-task guidelines document to add a "Script-Editing Agent Tasks" section mandating fullScriptContent in the context object.
2. Provide a canonical template snippet showing how to capture content at runtime.
3. Optionally add a lint rule in the process validator detecting context fields matching /[Ss]cript|[Pp]ath/ whose values are file-path strings without a paired content field.
4. Update fix-stale-sync and similar affected processes as reference implementations.

Additional Context

• Related issue (distinct problem): Infra fix processes declare success too early: single-curl snapshot check passes against pre-fix server state, masking bugs that only manifest on next system cycle #123 — Infra fix processes declare success too early — both are about infra process reliability gaps but address different failure modes.
• Discovered via retrospective analysis of trip-planner project runs (2026-03-31 through 2026-04-05).