Code-implementation skill should document harness host_files execution order constraints

[fullsend-ai-retro]

What happened

On PR #1075, the code agent created a host_files entry in harness/code.yaml pointing to /tmp/jira-issue-context.json as a host_files.src path. This file is created by the Jira pre-script (pre-code-jira.sh), but the harness loader validates host_files entries at config load time — before pre-scripts execute. The harness loader rejected the entire coder agent before trigger evaluation even began.

@ralphbean discovered this during live dispatch testing on Aug 29 (comment): the Jira overlay declares the file as a remote-base host_files.src, so the harness loader rejects the whole coder agent. He made 5 manual commits between Aug 29 11:48–19:41 UTC to fix the context handoff: switching to ${RUNNER_TEMP} dynamic paths, marking the entry as optional: true, generalizing external tracker identity, and requiring prefetched context.

The review agent ran 13 cycles on this PR but never flagged the host_files timing issue. All 13 review cycles focused on code-level analysis (injection, variable naming, documentation, API contracts) while missing the fundamental infrastructure feasibility problem.

What could go better

The code agent had no guidance about the harness execution lifecycle. The code-implementation skill describes how to write harness config entries but does not explain the order in which the harness processes them:

1. Config load + validation — harness YAML is parsed, host_files entries are validated for existence
2. Pre-scripts execute — runner-side scripts run, can create files
3. Sandbox setup — host_files are copied into the sandbox
4. Agent execution — Claude runs inside the sandbox

Without this context, the code agent reasonably assumed the pre-script would create the file before it was needed. The fix was to mark pre-script-generated host_files entries as optional: true and use dynamic paths (${RUNNER_TEMP}/...) instead of hardcoded /tmp paths.

I am confident this is the root cause of the multi-day delay and 5 manual human commits. The code agent's structural approach was correct (pre-script creates file, host_files copies it to sandbox), but the timing assumption was wrong. This is a systematic gap — any future PR that adds a pre-script-generated host_files entry will hit the same loader rejection.

Proposed change

In skills/code-implementation/SKILL.md, add a section documenting harness execution order constraints. Specifically:

1. Add a subsection (e.g., under the harness configuration guidance) explaining the execution lifecycle: config load → pre-script → sandbox setup → agent execution.
2. Document that host_files entries are validated at config load time. Files created by pre-scripts must be marked with optional: true to avoid loader rejection.
3. Document that host_files paths should use dynamic variables like ${RUNNER_TEMP} rather than hardcoded paths like /tmp.
4. Include an example showing the correct pattern for pre-script-generated context files:

   host_files:
     - src: ${RUNNER_TEMP}/context.json
       dst: /sandbox/workspace/.context.json
       optional: true

Also consider adding a brief note in docs/code.md (the code agent operator documentation) referencing this constraint for harness config authors.

Validation criteria

On the next 3 PRs where the code agent adds or modifies host_files entries in a harness config that reference files created by pre-scripts: (1) the code agent marks those entries as optional: true in its initial commit, (2) the code agent uses dynamic path variables instead of hardcoded paths, and (3) no human intervention is required to fix harness loader rejection errors. A secondary signal: review agent findings should not include host_files timing issues on these PRs.

---

Generated by retro agent from #1075

[fullsend-ai-triage]

🤖 Finished Triage · ✅ Success · Started 5:29 PM UTC · Completed 5:34 PM UTC

Commit: 4851188 · View workflow run →

Runtime: claude · Model: opus → claude-opus-4-6 · Effort: high · Cost: $0.76

[fullsend-ai-triage]

Triage summary

Severity: medium — systematic documentation gap that has already caused a multi-day incident on PR #1075 and will recur.

Root cause: The code-implementation skill (skills/code-implementation/SKILL.md) currently contains no guidance on harness execution lifecycle ordering. The file covers harness config syntax but not the timing relationship between config loading, pre-scripts, and sandbox setup.

Scope of change:

• Primary: Add a subsection to skills/code-implementation/SKILL.md documenting the execution lifecycle and host_files constraints
• Secondary (optional): Add a cross-reference in docs/code.md

Related issues:

• Review correctness sub-agent should validate harness config field values, not just file existence #763 (review agent harness config field validation) — tangentially related but targets the review agent, not code-implementation skill docs
• Review agent should check for harness-provided alternatives when reviewing .fullsend/ scripts #743 (review agent harness-provided alternatives) — same distinction

Proposed test case:

Verify the updated SKILL.md contains:
1. Harness execution lifecycle: config load → pre-script → sandbox setup → agent execution
2. Guidance: pre-script-generated host_files entries require optional: true
3. Guidance: use ${RUNNER_TEMP} instead of hardcoded /tmp paths
4. A YAML example showing the correct pattern:
   host_files:
     - src: ${RUNNER_TEMP}/context.json
       dst: /sandbox/workspace/.context.json
       optional: true

---

Labels: Documentation improvement to the code-implementation skill, generated by the retro agent from PR #1075.

---

Next steps:

• /fs-code — agent creates a PR to implement this issue
• /fs-code <your instruction> — agent implements with your specific guidance

[fullsend-ai-coder]

🤖 Finished Code · ✅ Success · Started 5:35 PM UTC · Completed 5:42 PM UTC

Commit: 4851188 · View workflow run →

Runtime: claude · Model: opus → claude-opus-4-6 · Effort: high · Cost: $2.58