docs(#6099): document code/fix image and policy sync guidance

[fullsend-ai-coder]

Summary

Documents how code and fix agents relate for image, policy, and provider configuration — including the supported per-repo harness pattern for teams that want one shared configuration.

Closes #6099. Relates to fullsend-ai/agents#532.

Companion change: fullsend-ai/agents#766 fixes #532 and updates the policies/fix.yaml header comment so it no longer says "Identical to the code agent policy."

Changes

• Add Image and network policy synchronization under Configuration on docs/agents/code.md and docs/agents/fix.md
• Document default overlap between upstream policies/code.yaml and policies/fix.yaml, with room for intentional divergence (e.g. Jira on fix only)
• Document recommended per-repo pattern: same policy:, providers:, and image: overrides in both .fullsend/harness/code.yaml and .fullsend/harness/fix.yaml
• Use policies/base.yaml naming consistent with other guides; reference ADR 0065 for provider-backed network access
• Add ADR 0065 Notes annotation for the revised fix policy header (Context quote left as historical record)

Testing

• Markdown link checker passes
• Pre-commit hooks pass (including ADR lint)
• Documentation only — no production code changes

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 6:00 PM UTC · Completed 6:12 PM UTC

Commit: b957eb6 · View workflow run →

[github-actions]

Site preview

Preview: https://f887d3b8-site.fullsend-ai.workers.dev

Commit: ce480e377259a81f5ab3799b0dcb8ee516d2b46d

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[fullsend-ai-review]

Looks good to me

Previous run

Looks good to me

Previous run (2)

Review

Findings

Low

• [scope-creep] docs/agents/code.md — Issue docs: add admonition for image and network policy synchronization between code and fix agents #6099 requested warning admonitions for image and network policy synchronization. The PR delivers a warning admonition (in scope) plus a "Recommended configuration" subsection with full YAML examples and provider composition explanation that extends beyond the issue's admonition scope. The YAML content is contextually specific to the synchronization scenario, reducing the overlap with the general customizing-agents.md guide. The same applies to the identical section in docs/agents/fix.md.
  Remediation: Consider shortening the "Recommended configuration" subsection or replacing it with a link to the existing customizing-agents guide, keeping the warning admonition and context paragraphs that are within issue scope.

• [scope-creep] docs/ADRs/0065-provider-backed-policy-composition.md — Issue docs: add admonition for image and network policy synchronization between code and fix agents #6099 requested admonitions in agent documentation (code.md, fix.md). The PR adds a Notes section to ADR 0065 clarifying that a quoted policy comment is outdated and referencing upstream changes. While this is routine ADR maintenance to prevent reader confusion, it is outside the issue's authorization scope.
  Remediation: Consider filing this ADR update as a separate housekeeping change, or amend issue docs: add admonition for image and network policy synchronization between code and fix agents #6099's scope to explicitly include ADR maintenance related to the synchronization topic.

• [intent-misalignment] docs/agents/code.md:49 — The section title "Image and network policy synchronization" could be read as implying mandatory synchronization, though the body text correctly distinguishes intentional divergence from accidental drift ("you can override each independently when their needs diverge"). The title matches the issue's own terminology (docs: add admonition for image and network policy synchronization between code and fix agents #6099), so this is a minor polish opportunity rather than a misalignment.

• [technical documentation accuracy] docs/agents/code.md:91 — The recommended configuration YAML example shows policy: policies/base.yaml alongside providers: in the harness file. Per ADR 0065, policy files define only non-network sandbox restrictions (filesystem, landlock, process), while network access comes through providers. The example is technically correct, but the prose does not explain that policies/base.yaml should contain only non-network rules — a reader unfamiliar with ADR 0065 might put network rules into the shared policy file.

Previous run (3)

Review

Findings

Medium

• [scope-creep] docs/agents/code.md — Issue docs: add admonition for image and network policy synchronization between code and fix agents #6099 requested warning admonitions for image and network policy synchronization. The PR delivers a warning admonition (in scope) plus a "Recommended configuration" subsection with full YAML examples and provider composition explanation that extends beyond the issue's admonition scope. The YAML tutorial content overlaps with docs/guides/user/customizing-agents.md, which already covers harness YAML structure including image, policy, and providers fields. The same applies to the identical section in docs/agents/fix.md.
  Remediation: Consider shortening the "Recommended configuration" subsection or replacing it with a link to the existing customizing-agents guide, keeping the warning admonition and context paragraphs that are within issue scope.

Low

• [intent-misalignment] docs/agents/code.md:49 — The section title "Image and network policy synchronization" could be read as implying mandatory synchronization, though the body text correctly distinguishes intentional divergence from accidental drift ("you can override each independently when their needs diverge"). The title matches the issue's own terminology (docs: add admonition for image and network policy synchronization between code and fix agents #6099), so this is a minor polish opportunity rather than a misalignment.
  Remediation: Consider retitling to "Image and network policy coordination" or "Shared configuration with the fix agent" for clarity.

Previous run (4)

Review

Findings

Medium

• [harness-path-convention] docs/agents/code.md:64 — The YAML example places harness override files directly at .fullsend/code.yaml and .fullsend/fix.yaml, with comments (register as source: code.yaml in config.yaml). The established convention across all other documentation — architecture.md, customizing-agents.md, bring-your-own-agent.md, ADR 0045, and building-custom-agents.md — is .fullsend/harness/ (e.g., .fullsend/harness/my-code.yaml) with source: harness/my-code.yaml. A user following this example would create a layout inconsistent with every other documented example.
  Remediation: Change paths to .fullsend/harness/code.yaml and .fullsend/harness/fix.yaml, and update comments to (register as source: harness/code.yaml in config.yaml).

• [harness-path-convention] docs/agents/fix.md:164 — Same harness file path convention issue as code.md. The YAML example uses .fullsend/code.yaml and .fullsend/fix.yaml file paths, contradicting the documented .fullsend/harness/ convention.
  Remediation: Update paths to .fullsend/harness/code.yaml and .fullsend/harness/fix.yaml with matching source: registration comments.

Low

• [adr-context-accuracy] docs/ADRs/0065-provider-backed-policy-composition.md:43 — The original text directly quotes the fix.yaml policy comment as "Identical to the code agent policy,". The PR replaces this with a paraphrase that softens the claim from "identical" to "overlapping with intentional divergence". Modifying a direct quote in an accepted ADR's Context section changes the historical record — consider whether the new paraphrase accurately reflects the current state of the fix.yaml policy header in fullsend-ai/agents.

Previous run (5)

Review

Findings

Medium

• [architectural-incoherence] docs/agents/code.md:65 — The recommended configuration pattern directs users to synchronize network access by pointing policy: at a shared file, but ADR 0065 (Provider-backed policy composition) establishes that network access is controlled through providers: profiles — policy files cover filesystem, landlock, and process restrictions only. Users following this example may believe they have synchronized network access when they have not. The old-style approach still functions (ADR 0065 describes it as best practice, not enforcement), but the guidance is architecturally misleading for the project's current direction. The same issue applies to docs/agents/fix.md:165.
  Remediation: Add providers: to the example YAML (showing the providers list shared across both harnesses) and clarify that policy: controls sandbox restrictions while providers: controls network access.

• [naming-convention-drift] docs/agents/code.md:71 — The example uses policies/coding.yaml as the shared policy file name, but every other guide in the repository (customizing-agents.md, bring-your-own-agent.md, ADR 0065) uses policies/base.yaml. The name coding.yaml appears nowhere else in the codebase and will confuse users cross-referencing other documentation. The same issue applies to docs/agents/fix.md:171.
  Remediation: Change policies/coding.yaml to policies/base.yaml in both files.

Low

• [content-duplication] docs/agents/code.md:49 — The new 37-line section is duplicated verbatim in docs/agents/fix.md. This is consistent with issue docs: add admonition for image and network policy synchronization between code and fix agents #6099's chosen approach (option 1: direct admonitions over shared section), but creates a maintenance surface — future edits must be synchronized manually.

Previous run

Review

Findings

Low

• [incomplete-doc] docs/guides/user/customizing-agents.md:286 — The "Extending the sandbox image" section references ghcr.io/fullsend-ai/fullsend-code:latest as an alternative parent image but does not mention the synchronization requirement between code and fix agents that this PR documents. Users extending the sandbox image for one agent may not realize they need to apply the same changes to the other. This gap predates this PR — the new admonitions in the agent-specific docs address the sync requirement at the point of configuration.
  Remediation: Consider adding a brief note in the "Extending the sandbox image" section referencing the synchronization warning in the code and fix agent documentation pages.

Previous run (6)

Review

Findings

Low

• [section-organization] docs/agents/code.md:52 — The 'Image and network policy synchronization' section breaks the established ordering pattern. In all other agent docs (triage.md, review.md, retro.md, prioritize.md), the 'Source' section immediately follows the 'Variables' subsection under 'Configuration and extension'. Inserting a new top-level section between them creates inconsistency across the six agent reference pages.
  Remediation: Move the synchronization warning into the 'Configuration and extension' section as a subsection (### Image and network policy synchronization) before the 'Variables' subsection, or place it as a top-level section before 'Configuration and extension' if it's not configuration-specific.

• [section-organization] docs/agents/fix.md:152 — Same pattern break as above in the fix agent documentation.

---

Labels: PR modifies code agent and fix agent documentation pages

Previous run (7)

Review

Findings

Medium

• [architectural-incoherence] docs/agents/code.md:65 — The recommended configuration pattern directs users to synchronize network access by pointing policy: at a shared file, but ADR 0065 (Provider-backed policy composition) establishes that network access is controlled through providers: profiles — policy files cover filesystem, landlock, and process restrictions only. Users following this example may believe they have synchronized network access when they have not. The old-style approach still functions (ADR 0065 describes it as best practice, not enforcement), but the guidance is architecturally misleading for the project's current direction. The same issue applies to docs/agents/fix.md:165.
  Remediation: Add providers: to the example YAML (showing the providers list shared across both harnesses) and clarify that policy: controls sandbox restrictions while providers: controls network access.

• [naming-convention-drift] docs/agents/code.md:71 — The example uses policies/coding.yaml as the shared policy file name, but every other guide in the repository (customizing-agents.md, bring-your-own-agent.md, ADR 0065) uses policies/base.yaml. The name coding.yaml appears nowhere else in the codebase and will confuse users cross-referencing other documentation. The same issue applies to docs/agents/fix.md:171.
  Remediation: Change policies/coding.yaml to policies/base.yaml in both files.

Low

• [content-duplication] docs/agents/code.md:49 — The new 37-line section is duplicated verbatim in docs/agents/fix.md. This is consistent with issue docs: add admonition for image and network policy synchronization between code and fix agents #6099's chosen approach (option 1: direct admonitions over shared section), but creates a maintenance surface — future edits must be synchronized manually.

Previous run (8)

Review

Findings

Low

• [incomplete-doc] docs/guides/user/customizing-agents.md:286 — The "Extending the sandbox image" section references ghcr.io/fullsend-ai/fullsend-code:latest as an alternative parent image but does not mention the synchronization requirement between code and fix agents that this PR documents. Users extending the sandbox image for one agent may not realize they need to apply the same changes to the other. This gap predates this PR — the new admonitions in the agent-specific docs address the sync requirement at the point of configuration.
  Remediation: Consider adding a brief note in the "Extending the sandbox image" section referencing the synchronization warning in the code and fix agent documentation pages.

Previous run (9)

Review

Findings

Low

• [section-organization] docs/agents/code.md:52 — The 'Image and network policy synchronization' section breaks the established ordering pattern. In all other agent docs (triage.md, review.md, retro.md, prioritize.md), the 'Source' section immediately follows the 'Variables' subsection under 'Configuration and extension'. Inserting a new top-level section between them creates inconsistency across the six agent reference pages.
  Remediation: Move the synchronization warning into the 'Configuration and extension' section as a subsection (### Image and network policy synchronization) before the 'Variables' subsection, or place it as a top-level section before 'Configuration and extension' if it's not configuration-specific.

• [section-organization] docs/agents/fix.md:152 — Same pattern break as above in the fix agent documentation.

---

Labels: PR modifies code agent and fix agent documentation pages

[ascerra]

/fs-fix

[fullsend-ai-coder]

🤖 Finished Fix · ✅ Success · Started 11:06 AM UTC · Completed 11:16 AM UTC

Commit: b957eb6 · View workflow run →

[fullsend-ai-coder]

🔧 Fix agent — iteration 1 (human-triggered)

Addressed both section-organization findings. Moved the sync warning admonition from a standalone ## section to a ### subsection within 'Configuration and extension' in both code.md and fix.md, restoring the standard section ordering pattern used across all agent doc pages.

Fixed (2):

1. section-organization in docs/agents/code.md: Moved 'Image and network policy synchronization' from a standalone ## section into the 'Configuration and extension' section as a ### subsection, placed before '### Variables'. This matches the established ordering pattern across all other agent doc pages (triage, review, retro, prioritize) where 'Source' immediately follows 'Configuration and extension'.
2. section-organization in docs/agents/fix.md: Applied the same structural fix as code.md — demoted the sync warning to a ### subsection under 'Configuration and extension', placed before '### Variables'.

Tests: passed

Next steps:

• /fs-review — request a re-review of the changes
• /fs-fix <your instruction> — run another fix pass with specific guidance
• Push commits directly — review re-runs automatically on push
  _{Updated by fullsend fix agent}

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 11:17 AM UTC · Completed 11:31 AM UTC

Commit: a222a59 · View workflow run →

[fullsend-ai-review]

🤖 Review · ⚠️ Cancelled · Started 11:38 AM UTC · Ended 11:43 AM UTC

Commit: 3771bb8 · View workflow run →

[fullsend-ai-review]

🤖 Review · ⚠️ Cancelled · Started 11:44 AM UTC · Ended 11:47 AM UTC

Commit: be00053 · View workflow run →

[fullsend-ai-review]

🤖 Review · ⚠️ Cancelled · Started 11:48 AM UTC · Ended 11:50 AM UTC

Commit: da3e526 · View workflow run →

[fullsend-ai-review]

🤖 Review · ⚠️ Cancelled · Started 11:51 AM UTC · Ended 11:52 AM UTC

Commit: 8b938c1 · View workflow run →

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 11:44 AM UTC · Completed 12:03 PM UTC

Commit: e5c996f · View workflow run →

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 4:17 PM UTC · Completed 4:32 PM UTC

Commit: ad91b2b · View workflow run →

[ascerra]

/fs-fix

[fullsend-ai-coder]

🤖 Finished Fix · ✅ Success · Started 6:49 PM UTC · Completed 6:55 PM UTC

Commit: ad91b2b · View workflow run →

[fullsend-ai-coder]

🔧 Fix agent — iteration 3 (human-triggered)

Addressed 1 of 4 review findings. Fixed the technical documentation accuracy concern by clarifying that the shared policy file covers non-network sandbox restrictions only, while network access comes through providers: profiles. Both code.md and fix.md updated identically. Disagreed with 3 findings: two scope-creep observations (human approved the content as-is) and one intent-misalignment (human explicitly said 'ignore').

Fixed (1):

1. technical documentation accuracy in policy/providers clarification (docs/agents/code.md): Clarified that policies/base.yaml defines non-network sandbox restrictions only (filesystem access, landlock, process identity), and that network access is controlled through providers: profiles. Applied the same clarification to docs/agents/fix.md. A reader unfamiliar with ADR 0065 could otherwise place network rules in the shared policy file.

Disagreed (3):

1. scope-creep on Recommended configuration subsection in code.md and fix.md: The PR author (ascerra) approved the PR with this content and applied the ready-for-merge label. The Recommended configuration YAML examples are contextually specific to the code/fix synchronization scenario and reduce overlap with the general customizing-agents guide. Scope decisions are the author's prerogative.
2. scope-creep on ADR 0065 Notes section: The ADR Notes section was explicitly added by the PR author and approved. It prevents reader confusion about the outdated Context quote — routine ADR maintenance that the author judged worth including in this PR.
3. intent-misalignment on section title naming: The PR author explicitly replied 'ignore' to this inline comment. The title 'Image and network policy synchronization' matches the terminology used in issue docs: add admonition for image and network policy synchronization between code and fix agents #6099, and the body text correctly distinguishes intentional divergence from accidental drift.

Tests: passed

Next steps:

• /fs-review — request a re-review of the changes
• /fs-fix <your instruction> — run another fix pass with specific guidance
• Push commits directly — review re-runs automatically on push
  _{Updated by fullsend fix agent}

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 6:56 PM UTC · Completed 7:09 PM UTC

Commit: 8a34c52 · View workflow run →

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 8:03 PM UTC · Completed 8:15 PM UTC

Commit: ce480e3 · View workflow run →

[fullsend-ai-retro]

🤖 Finished Retro · ✅ Success · Started 8:37 PM UTC · Completed 8:59 PM UTC

Commit: ce480e3 · View workflow run →

[fullsend-ai-retro]

Retro: PR #6111 — document code/fix image and policy sync guidance

Outcome: Merged after 6 days, 11 commits, 33 agent workflow runs (1 triage, 1 code, 3 fix, 25 review, 3 retro). The review agent caught several genuinely useful issues — section ordering, naming convention drift (policies/coding.yaml vs policies/base.yaml), architectural incoherence (policy vs providers per ADR 0065), and harness path convention (.fullsend/ vs .fullsend/harness/). All medium-severity findings were valid and improved the final documentation quality.

Timeline: The code agent delivered a correct initial implementation meeting the issue's acceptance criteria (warning admonitions cross-referencing code and fix agent docs). The human (ascerra) then expanded the scope significantly — adding detailed harness configuration examples, providers documentation, and per-repo pattern guidance — via 5 manual commits using Cursor. Each expansion triggered review cycles that surfaced real convention violations in the new content. Three /fs-fix iterations addressed mechanical issues (section ordering, harness paths, policy scope clarification) while the human handled the substantive content decisions.

Assessment: The workflow performed well overall. The review agent's findings were consistently valid and caught issues the human might have missed (naming drift, path convention, architectural coherence with ADR 0065). The high iteration count (11 commits, 25 review dispatches) was driven by human-initiated scope expansion beyond the original acceptance criteria, not by agent failure. The code agent met the original requirements; the review agent caught real problems in evolving content; the fix agent addressed the mechanical findings it was invoked for.

No new proposals — all improvement opportunities are covered by existing open issues:

• Finding re-raising after human dismissal: ascerra replied "ignore" to the [low] intent-misalignment finding at 16:14 UTC on Aug 14; 18 minutes later, the review agent re-raised the identical finding in a new review cycle triggered by the human's APPROVED event. This is direct evidence for #1672, #4682, and the umbrella #2816.

• Incremental finding discovery: The initial review found only [low] section-organization issues. After content changes, subsequent reviews discovered [medium] architectural-incoherence, naming-convention-drift, and harness-path-convention — though in this case the new findings were about genuinely new content added by the human, making the incremental discovery appropriate. Still relevant evidence for #4970.

• Review dispatch volume: 25 review dispatches (19 successful, 6 cancelled) for a 113-line docs PR. The cancellation mechanism (concurrency groups) worked for rapid successive pushes, but 7 review runs on Aug 12 alone (during the human's rapid manual editing session) represents avoidable cost. Evidence for #1014 and #4069.

• Review triggered by APPROVED event: The re-review at Aug 14 16:32 UTC was triggered by the human's pull_request_review APPROVED event, not by any code change. This is evidence for #5967 (filter pull_request_review events to changes_requested state).

• Code agent convention adherence: The code agent's initial output was correctly scoped to the acceptance criteria and did not require ADR consultation. The convention violations (naming, paths, architectural coherence) were introduced in the human's manual expansion, not the code agent's output. No new evidence for #2571 from this PR.

Agents repo: fullsend-ai/agents at commit 693ed83bbd5289e1ef13d6c7a3772f61efc43c86.