Repository navigation
docs(#5579): add harness field integration checklist - #5581
fullsend-ai-coder[bot] wants to merge 1 commit into
Conversation
Add docs/contributing/harness-fields.md covering the four pipeline stages that new harness schema fields must be wired into: expansion (os.Expand + checkVarRefs), environment construction (RunnerEnv merge via envToList/childScriptEnv), composition carry-forward (all three merge sites in compose.go and forge.go), and security pipeline (resolveBaseScripts/resolveBaseResources/resolveBaseHostFiles with validateBaseRelPath and auditBaseFetch). Each section lists the current fields wired through that stage and provides guidance on when and how to add new fields. Update AGENTS.md topic-specific guidance table with the trigger "Adding or modifying fields in the harness schema structs." Closes #5579
Site previewPreview: https://2867a65a-site.fullsend-ai.workers.dev Commit: |
|
🤖 Finished Review · ✅ Success · Started 4:48 PM UTC · Completed 5:00 PM UTC |
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
ReviewFindingsMedium
Labels: PR adds a new contributor guide under docs/contributing/ covering harness schema field integration, and updates AGENTS.md with a table entry for it. |
| | [Design Decisions](docs/contributing/design-decisions.md) | Understanding architectural principles and key decisions | | ||
| | [Vouch System](docs/contributing/vouch-system.md) | Working with the contributor vouch gate or PR workflows | | ||
| | [Tier Conventions](docs/contributing/tier-conventions.md) | Using the term "tier" in code or docs — covers the three distinct tier contexts | | ||
| | [Harness Fields](docs/contributing/harness-fields.md) | Adding or modifying fields in the harness schema structs — covers expansion, environment, composition, and security pipelines | |
There was a problem hiding this comment.
[medium] protected-path
This PR modifies AGENTS.md, which is a protected governance file. The change adds a table entry pointing to the new docs/contributing/harness-fields.md contributor guide. The linked issue (#5579) provides clear context and authorization for this modification. Human approval is always required for protected-path changes, regardless of context.
|
This pull request has been automatically marked as stale because it has not had any activity in the last month. It will be closed in 2 weeks if no further activity occurs. Remove the |
|
No one taking care of this, closing. |
|
🤖 Finished Retro · ✅ Success · Started 7:09 AM UTC · Completed 7:29 AM UTC Commit: Runtime: claude · Model: opus → claude-opus-4-6 · Effort: high · Cost: $3.28 |
Retro: PR #5581 — docs(#5579): add harness field integration checklistTimeline
Workflow quality assessmentAgent pipeline performed well. The full triage → code → review chain completed in under 30 minutes. The code agent's output was high quality — it covered all 4 required categories (expansion, environment, composition, security) with concrete function references, tables of currently wired fields, and a bonus quick-reference grep section. The review agent correctly identified the only procedural concern (protected-path on AGENTS.md). All CI passed. The failure was entirely in the human review stage. This is a retro-of-a-retro. Issue #5579 was itself created by the retro agent analyzing PR #5192, where 4/6 review gaps traced to the absence of this exact documentation. The code agent faithfully implemented the retro's proposal, but the resulting PR was wasted because no human reviewed it. The original retro's validation criteria ("next 3 harness-field PRs should have review coverage ≥3/4 categories") remain unevaluable because the document was never merged. Evidence for existing issues (no new proposals needed)All candidate improvement areas are already well-covered by existing open issues:
ConclusionThe agent pipeline executed correctly at every stage. The failure mode — a high-quality PR dying from lack of human review — is a known systemic issue with extensive tracking. No new proposals are warranted; the evidence from this PR strengthens the case for the existing issues listed above, particularly #5315 (auto-close retro issues on PR close) and #6152 (throttle on unreviewed backlog). |
Summary
Add
docs/contributing/harness-fields.md— a contributor checklist covering the four implicit integration points that new harness schema struct fields must be wired into. This addresses the gap identified in retro analysis of PR #5192, where 4 of 6 review findings traced to undocumented conventions visible only by tracing sibling fields through the codebase.Related Issue
Closes #5579
Changes
docs/contributing/harness-fields.md— covers:os.Expandrouting inrun.goandcheckVarRefsregistration inValidateRunnerEnvWith, with a table of all currently wired fieldsRunnerEnvmerge viaenvToList/childScriptEnvwith a table of all call sitesmergeBaseIntoChild,mergeForgeConfigInto,mergeForgeConfig) with their per-type merge rulesresolveBaseScripts,resolveBaseResources,resolveBaseHostFiles,validateBaseRelPath, andauditBaseFetchAGENTS.md— added table entry with trigger: Adding or modifying fields in the harness schema structsTesting
docs/contributing/harness-fields.mdexists with all 4 sectionsgetMarkdownFiles("contributing", ...)— auto-discovers the new file, no config change neededChecklist
!for breaking changes)Closes #5579
Post-script verification
agent/5579-harness-field-checklist)f473cd512233268c5da72773be7e1e21042b3408..HEAD)