docs(#3862): remove ADR links from user-facing documentation

[fullsend-ai-coder]

Summary

User-facing documentation linked to internal Architecture Decision Records (ADRs) as primary references for end-user tasks. ADRs are internal architectural decisions written for contributors — directing end users and LLMs to ADRs creates confusion and a poor onboarding experience.

This PR removes all ADR links from user-facing guides and replaces them with inline explanations or links to existing user-facing documentation. ADR references in contributor-facing dev docs are preserved.

Changes

• Removed ADR links from 14 user-facing documentation files across docs/guides/user/, docs/guides/infrastructure/, and docs/guides/getting-started/
• Replaced ADR references on deprecated features with links to the recommended user-facing guide (Bring Your Own Agent)
• Added inline explanations where ADR links were the sole source of context (e.g., integrity hash requirements, pre-commit security rationale)
• Preserved ADR references in contributor-facing docs (docs/guides/dev/) and the guides index navigation

Testing

• Verified zero ADR references remain in docs/guides/user/, docs/guides/infrastructure/, and docs/guides/getting-started/ via grep
• Verified ADR references in docs/guides/dev/ (contributor docs) are untouched
• No code changes — documentation only

---

Closes #3862

Post-script verification

• Branch is not main/master (agent/3862-docs-remove-adr-links)
• Secret scan passed (gitleaks — c088a3c72eabffcc350196a71b6351fb7d6af659..HEAD)
• PR body secret scan passed (gitleaks — no-git)
• Pre-commit hooks passed (authoritative run on runner)
• Tests ran inside sandbox

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 1:24 PM UTC · Completed 1:42 PM UTC
Commit: e32aa73 · View workflow run →

[github-actions]

Site preview

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

Commit: 223d0881fc0a4837b142b036180665c21102d9d9

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[fullsend-ai-review]

Review

Findings

Low

• [visual correctness] docs/guides/user/customizing-agents.md:150 — The replacement text in the ASCII box header is 2 display characters wider than the box border. The box top/bottom borders have a display width of 64 columns, but the content line │ Configuration Layering (deprecated — use base: composition) │ has a display width of 66 columns, breaking visual alignment in monospace rendering. Shorten the text by 2 characters (e.g., Configuration Layering (deprecated; use base: instead)) or widen the entire box by 2 characters.
• [conflicting-with-documented-decision] — This PR removes ADR links from user-facing guides, which is in tension with ADR 0023 writing rule Use AI to help formalise intent after rapid local prototyping #4 ("Link, don't restate"). The PR is backed by issue Documentation shouldn't link to ADRs #3862, representing an intentional editorial policy change. Consider updating ADR 0023's writing rule Use AI to help formalise intent after rapid local prototyping #4 to note that user-facing guides should provide inline context rather than linking to ADRs, per the policy established in Documentation shouldn't link to ADRs #3862.

Previous run

Review

Findings

Medium

• [conflicting-with-documented-decision] Multiple user-facing doc files — This PR removes ADR links from user-facing documentation, which is in tension with ADR 0023 writing rule Use AI to help formalise intent after rapid local prototyping #4 ("Link, don't restate. Reference ADRs, normative specs, and docs/architecture.md for architectural context."). The PR is backed by issue Documentation shouldn't link to ADRs #3862, which represents an intentional editorial policy change to remove ADR links from user-facing guides. Consider writing a brief ADR or updating ADR 0023 with an annotation noting that issue Documentation shouldn't link to ADRs #3862 established the policy of omitting ADR links from user-facing guides.

Low

• [Documentation completeness] docs/guides/infrastructure/distributed-tracing.md:108 — Replacement text "documents the planned contract" changes the semantic emphasis from "decided" (finalized) to "planned" (tentative). The preceding callout already states "Planned: Level 3 content capture is not yet implemented", so "planned contract" is contextually coherent, but "documents the telemetry contract" would be slightly cleaner.
• [Comment clarity] docs/guides/user/bring-your-own-agent.md:186 — Inline YAML comment "Optional CEL expression over normevent" removes the ADR-0061 reference. The term "normevent" is not explained locally, though as an inline YAML comment in a reference section this is a minor gap.
• [Comment clarity] docs/guides/user/bring-your-own-agent.md:196 — Inline YAML comment "Network access via provider profiles" removes the ADR-0065 reference. The comment still describes the field's purpose adequately.

---

Labels: PR modifies only documentation files under docs/guides/

[waynesun09]

Review-squad pass (3 independent agents: Claude x2, Grok). This is a clean, well-scoped docs-only change — dangling-link checks, cross-reference targets, and the dev-docs/ADR-index preservation policy all came back correct across all 14 touched files. Two MEDIUM+ issues surfaced where a removed ADR link left a term undefined or the replacement text made an inaccurate claim; see inline comments. Everything else raised (diagram alignment, a couple of dropped citations) was LOW/INFO and not included here.

[rh-hemartin]

@waynesun09 how @deboer-tim should proceed to fix these issues you and the bot mention? I don't think he would be able to push to this branch, as he lacks write permissions. Any recommendation?

[rh-hemartin]

/fs-fix address the comments on the PR and rebase resolving conflicts.

[fullsend-ai-coder]

🤖 Finished Fix · ✅ Success · Started 8:43 AM UTC · Completed 8:51 AM UTC
Commit: e32aa73 · View workflow run →

[fullsend-ai-coder]

🔧 Fix agent — iteration 1 (human-triggered)

Rebased PR onto current main (resolving 3 merge conflicts in org-mode.md, bring-your-own-agent.md, and customizing-with-agents-md.md). Addressed all review findings: fixed HIGH (undefined SaaS term) by adding inline explanation, fixed MEDIUM (hash-pinning misattribution) by correcting the claim, fixed LOW (planned contract phrasing). Disagreed with 3 findings: ADR 0023 conflict is out of scope, normevent issue was resolved by conflict resolution, and providers comment was adequate as-is.

Fixed (6):

1. SaaS installation profile term left undefined (docs/guides/infrastructure/advanced-setup.md): Added inline explanation tying 'SaaS installation profile' back to the Managed model taxonomy already defined on the same page, as suggested by the reviewer.
2. Replacement text misattributes hash-pinning to agent add CLI (docs/guides/user/customizing-agents.md): Removed the incorrect claim that 'fullsend agent add' computes hashes for provider/profile URLs. Replaced with accurate statement that the hash is checked on every resolution.
3. Planned contract semantic emphasis (docs/guides/infrastructure/distributed-tracing.md): Changed 'documents the planned contract' to 'documents the telemetry contract' for cleaner phrasing, as suggested by the reviewer.
4. Merge conflicts with main branch (docs/guides/getting-started/org-mode.md): Resolved merge conflict by adopting main's updated deprecation notice (which already omits the ADR link and uses improved wording with migration instructions).
5. Merge conflicts with main branch (docs/guides/user/bring-your-own-agent.md): Resolved two merge conflicts: (1) preserved main's new introductory paragraphs while keeping ADR link removal from PR; (2) adopted main's updated trigger comment using 'NormalizedEvent' with CEL Triggers Reference link, which also resolves the bot's LOW finding about 'normevent' being unexplained.
6. Merge conflicts with main branch (docs/guides/user/customizing-with-agents-md.md): Resolved merge conflict in deprecation notice wording, using em-dash style consistent with the rest of the PR.

Disagreed (3):

1. ADR 0023 writing rule conflict: The bot flagged that removing ADR links conflicts with ADR 0023 writing rule Use AI to help formalise intent after rapid local prototyping #4. This PR implements issue Documentation shouldn't link to ADRs #3862, which represents an intentional editorial policy change. Writing or updating ADR 0023 is a separate task outside the scope of this documentation PR.
2. Comment clarity - normevent term unexplained: Resolved by the merge conflict resolution: main already updated this YAML comment to use 'NormalizedEvent' with a cross-reference to the CEL Triggers Reference guide.
3. Comment clarity - ADR-0065 reference removed from providers comment: The reviewer noted the comment 'still describes the field's purpose adequately' without the ADR reference. No change needed.

Tests: passed

_{Updated by fullsend fix agent}

[rh-hemartin]

/fs-fix

[fullsend-ai-coder]

🤖 Finished Fix · ✅ Success · Started 12:56 PM UTC · Completed 1:05 PM UTC
Commit: 78423bf · View workflow run →

[fullsend-ai-coder]

🔧 Fix agent — iteration 1 (human-triggered)

Rebased PR branch onto current main. After rebase, 5 ADR references remained in user-facing docs (introduced by files created/modified on main after the original PR). Removed all 5 to restore the PR's stated invariant of zero ADR links in docs/guides/user/, docs/guides/infrastructure/, and docs/guides/getting-started/.

Fixed (5):

1. ADR 0054 reference in dispatch diagram (bring-your-own-agent.md) (docs/guides/user/bring-your-own-agent.md): Removed ADR 0054 parenthetical from the ASCII dispatch diagram. The step label 'Authorize' is self-explanatory without the ADR number.
2. ADR 0054 inline link in cel-triggers-reference.md (docs/guides/user/cel-triggers-reference.md): Removed ADR 0054 link from the Authorize step description. This file was created on main (split from bring-your-own-agent.md) after the original PR, introducing new ADR references.
3. ADR 0058 inline link in cel-triggers-reference.md (docs/guides/user/cel-triggers-reference.md): Removed ADR 0058 link from the Enumerate step description. The text still explains scaffold discovery adequately without the ADR cross-reference.
4. ADR 0044 inline link in repo-management.md (docs/guides/getting-started/repo-management.md): Removed ADR 0044 parenthetical from the per-org migration section. The context ('migrating from per-org mode') is self-explanatory.
5. ADR 0057 reference in repo-management.md See Also section (docs/guides/getting-started/repo-management.md): Removed ADR 0057 reference link from the See Also section. ADR links in reference sections of user-facing docs are out of scope per issue Documentation shouldn't link to ADRs #3862.

Tests: passed

Decision points

• Rebased branch onto current main before making fixes, since the branch was behind by 20+ commits (alternatives: Skip rebase and only fix new ADR references, Merge main instead of rebase; rationale: Rebase keeps the commit history linear and is consistent with the first fix iteration's approach. The rebase resolved cleanly with no conflicts.)

_{Updated by fullsend fix agent}

[rh-hemartin]

/fs-review

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 9:54 AM UTC · Completed 10:13 AM UTC
Commit: 653b2d4 · View workflow run →

[rh-hemartin]

/fs-fix rebase

[fullsend-ai-coder]

🤖 Finished Fix · ❌ Failure · Started 3:46 PM UTC · Completed 3:51 PM UTC
Commit: 653b2d4 · View workflow run →

[fullsend-ai-coder]

⚠️ Post-fix script failed — Structured output processing failed (exit code 1)

The fix agent completed, but the post-fix script failed before finishing.

Workflow run: https://github.com/fullsend-ai/.fullsend/actions/runs/30467439563

Details:
process-fix-result.py failed with exit code 1 (bad input) for PR #5413 in fullsend-ai/fullsend
Please check the workflow logs for full details and retry with /fs-fix if appropriate.

[rh-hemartin]

/fs-fix

[fullsend-ai-coder]

🤖 Finished Fix · ❌ Failure · Started 6:49 AM UTC · Completed 6:57 AM UTC
Commit: 7f2d7e8 · View workflow run →

[fullsend-ai-coder]

⚠️ Post-fix script failed — Structured output processing failed (exit code 1)

The fix agent completed, but the post-fix script failed before finishing.

Workflow run: https://github.com/fullsend-ai/.fullsend/actions/runs/30520752125

Details:
process-fix-result.py failed with exit code 1 (bad input) for PR #5413 in fullsend-ai/fullsend
Please check the workflow logs for full details and retry with /fs-fix if appropriate.

[fullsend-ai-retro]

🤖 Finished Retro · ✅ Success · Started 7:19 AM UTC · Completed 7:31 AM UTC
Commit: 223d088 · View workflow run →

[fullsend-ai-retro]

Retro: PR #5413 — docs(#3862): remove ADR links from user-facing documentation

Timeline: Issue #3862 filed → triage (4 min) → code agent (12 min) → PR #5413 opened (July 21) → initial bot review (19 min, COMMENT verdict) → human review-squad pass by waynesun09 (July 22, found HIGH + MEDIUM issues) → 5-day wait → 2 successful /fs-fix runs (July 27) → bot re-review APPROVED (July 28) → 2 failed /fs-fix runs (July 29–30, post-fix script crash) → human approval → merged (July 30). Total: 9 days, 9 agent runs (1 triage, 1 code, 2 review, 4 fix, 1 retro).

Outcome: The docs-only PR was well-scoped (+43/−54 across 15 files). The code agent produced a clean initial implementation. Two fix iterations were needed to address legitimate review findings and branch drift. Two additional fix iterations failed due to a known platform bug. Human merged after manual approval.

Key findings — all map to existing open issues

1. Post-fix script crash (agents#534). Both failed fix runs (30467439563, 30520752125) failed because process-fix-result.py uses __file__-relative paths (../schemas/fix-result.schema.json) to locate its schema, but the content-addressed cache stores scripts/ and schemas/ in separate SHA-keyed directories. This is the exact bug described in agents#534. This retro provides a second data point confirming the bug is actively blocking users — rh-hemartin had to trigger /fs-fix twice before giving up and manually approving.

2. Challenger dismissed valid HIGH finding (fullsend#1972). The review sub-agents detected a HIGH-severity finding ("authorization tier mismatch") on the initial review, but the challenger pass classified it as a "category error" and dismissed it. The human review-squad pass (waynesun09, 3 independent agents across 2 model families) independently confirmed the underlying issue: removing the ADR 0033 link left the "SaaS installation profile" term completely undefined, with no local explanation or link to the page's own taxonomy. This supports fullsend#1972 (require evidence before dismissing findings as false positives).

3. Correctness sub-agent missed factual inaccuracy (fullsend#2199). The correctness sub-agent (opus) reported zero findings, but the human review found that replacement text in customizing-agents.md misattributed hash-pinning computation to fullsend agent add — a claim not supported by the referenced ADR or any documented CLI behavior. This is a documentation fact-checking gap consistent with fullsend#2199 (review agent should fact-check technical claims in documentation PRs).

4. Finding too abstract to survive challenger (fullsend#5264). The sub-agent's finding was titled "authorization tier mismatch" — an abstract architectural label. A concrete finding like "SaaS installation profile term left undefined after ADR link removal, no definition exists elsewhere in docs/guides/" would have been harder for the challenger to dismiss. This supports fullsend#5264 (correctness sub-agent should construct concrete impact examples).

What went well

• Triage → code → review pipeline completed in under 40 minutes with no human intervention.
• Fix agent successfully rebased across 20+ commits, resolved 3 merge conflicts, addressed review findings with clear reasoning, and correctly disagreed with out-of-scope findings (ADR 0023 update).
• Review agent correctly identified the ADR 0023 tension as a policy question rather than a blocking defect, and the second review correctly approved after fixes were applied.
• No new proposals filed — all findings map to existing open issues. Filing duplicates would add noise.