docs: Clean up bits around GH Agentic Workflows

[cgwalters]

Several docs (landscape.md, platform-nativeness.md) cited a GitHub blog post's "developers will always own the merge button" line as though it were an enforced product/platform constraint. It isn't: GitHub Apps and bot accounts can call the merge API with write access today, and GitHub's own auto-merge and merge queue features already merge PRs without a human clicking anything. The blog post is one team's editorial stance, not something the platform technically enforces.

Reword the four spots making this claim to distinguish the stated position from an actual restriction, so the comparison with gh-aw doesn't overstate why it stops short of autonomous merge.

Assisted-by: https://github.com/cgwalters/cgwalters#llms

[github-actions]

Thank you for your interest in contributing to fullsend, @cgwalters.

This project uses a vouch system for first-time contributors. Before submitting a pull request, you need to be vouched by a maintainer.

To get vouched:

1. Open a Vouch Request discussion.
2. Describe what you want to change and why.
3. Write in your own words — do not have an AI generate the request.
4. A maintainer will comment /vouch if approved.
5. Once vouched, open a new PR (preferred) or reopen this one.

See CONTRIBUTING.md for details.

[github-actions]

E2E tests did not run

E2E tests run automatically for org/repo members and collaborators on pull requests.

For other contributors, a maintainer must add the ok-to-test label after the latest push.

See E2E testing guide for details.

[qodo-code-review]

PR Summary by Qodo

Docs: clarify GitHub “merge button” stance vs platform enforcement (gh-aw)

📝 Documentation 🕐 10-20 Minutes

AI Description

• Remove/soften claims that GitHub enforces “humans must merge” as a platform constraint.
• Update the landscape and platform-nativeness comparisons to treat it as editorial/product stance.
• Expand notes on how autonomous merge could be implemented via GitHub APIs even with gh-aw.

Diagram

graph TD
  D1["docs/landscape.md"] --> GHAW["GitHub Agentic Workflows (gh-aw)"] --> API[["GitHub merge APIs"]]
  D2["docs/problems/platform-nativeness.md"] --> GHAW --> API
  D1 --> BLOG(["GitHub blog post (editorial)"])
  D2 --> BLOG
  subgraph Legend
    direction LR
    _doc["Doc page"] ~~~ _ext(["External source"]) ~~~ _api[["API surface"]]
  end

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Add a short “Merge authority” doc section with API citations

• ➕ Centralizes the nuance (editorial stance vs technical capability) in one canonical place
• ➕ Allows linking directly to GitHub REST/GraphQL docs and auto-merge/merge-queue docs
• ➖ More doc restructuring than this PR’s targeted cleanup
• ➖ May be overkill if the confusion only exists in these two pages

2. Keep prior wording but add an explicit footnote/aside

• ➕ Minimal churn; preserves original narrative flow
• ➕ Still corrects the factual overstatement
• ➖ Footnotes are easy to miss; the main text would still imply enforcement
• ➖ Continues to anchor reasoning to a blog post rather than capabilities

3. Reframe comparisons around “default product posture” instead of “constraints” everywhere

• ➕ More consistently separates technical limits from governance/product choices
• ➕ Avoids repeating the merge-button claim across documents
• ➖ Requires broader editorial pass across multiple docs beyond this PR’s scope

Recommendation: The PR’s approach (rewording the four overstatements in-place) is the right scope: it directly fixes the misleading implication without forcing a larger documentation reorg. If this topic keeps resurfacing, consider a small canonical “merge authority” section with concrete API/feature citations and link to it from both pages.

Files changed (2) +9 / -13

Documentation (2) +9 / -13

landscape.mdRemove enforced “merge button” claim; refresh Copilot/gh-aw framing +5/-9

Remove enforced “merge button” claim; refresh Copilot/gh-aw framing

• Replaces the opening “industry consensus” framing with a broader statement that there is no single consensus. Renames and rewrites the GitHub Copilot section to remove reliance on the blog-post claim and instead focus on Copilot’s relevance and its relationship to gh-aw. Removes language implying gh-aw is constrained by GitHub product limitations against autonomous merging, and tightens the Actions-runtime trade-off list accordingly.

docs/landscape.md

platform-nativeness.mdClarify autonomous-merge limits are defaults; note merge APIs are available +4/-4

Clarify autonomous-merge limits are defaults; note merge APIs are available

• Rewords the autonomous-merge judgment section to distinguish gh-aw’s default design choices from GitHub platform enforcement, while preserving the broader judgment/governance argument. Updates product-dependency and philosophical-opposition sections to describe the “humans merge” position as an editorial stance that influences upstream direction, not a hard technical block. Expands the safe-outputs discussion with concrete examples of implementing merge via standard GitHub workflow triggers and merge endpoints, and frames the open question as upstream formalization vs adopter bolt-ons.

docs/problems/platform-nativeness.md

[cgwalters]

#5200

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (2) 📘 Rule violations (0) 📜 Skill insights (0)

Context used

✅ Compliance rules (platform): 54 rules

✅ Skills: writing-user-docs, writing-adrs

1. Overbroad merge feasibility claim 🐞 Bug ≡ Correctness

Description

docs/problems/platform-nativeness.md states “Nothing technical blocks” autonomous merging via a
standalone workflow calling merge APIs, but merges still depend on workflow token permissions plus
branch protection/rulesets (required checks, required reviews, merge queue prerequisites). This can
mislead readers into assuming an approval/check event alone is sufficient or that protections can be
bypassed.

Code

docs/problems/platform-nativeness.md[136]

+- **Can gh-aw's safe-outputs model be extended for autonomous merge?** Nothing technical blocks this today — a plain workflow job triggered on `pull_request_review` (approved) or a passing check suite can call the merge REST endpoint or the merge-queue GraphQL mutation with a token that has write access, entirely outside gh-aw's safe-outputs system. The open question is whether gh-aw's maintainers formalize this as an official safe-output type (gated by required checks and a confidence threshold), which would make it a first-class, auditable primitive instead of something every adopter bolts on themselves. Given their stated editorial position, that seems unlikely to come from upstream — but it doesn't stop fullsend or anyone else from building it as an unofficial follow-up job today.

Relevance

⭐⭐⭐ High

Team often accepts doc corrections that qualify technical claims and avoid misleading feasibility
statements.

PR-#601
PR-#3903
PR-#2773

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The referenced paragraph makes an unqualified claim about technical feasibility without noting the
gating conditions (token permission + repo merge policy) that still apply to API-based merges.

docs/problems/platform-nativeness.md[132-137]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The doc uses an absolute statement ("Nothing technical blocks") when the described approach only works if repository policy and token permissions allow it (branch protection/rulesets, required checks/reviews, merge-queue configuration, workflow permissions). This should be qualified to avoid implying merges can bypass protections.

## Issue Context
This section is used to reason about whether gh-aw’s limitations are design choices vs. platform constraints. Overstating feasibility can send implementers down an incorrect path or create confusion when automation fails under common protections.

## Fix Focus Areas
- docs/problems/platform-nativeness.md[136-136]

## Suggested change
Reword to something like: “GitHub exposes APIs for programmatic merging, but success is still subject to the workflow token’s permissions and repository rules/branch protections (required checks/reviews, rulesets, merge queue prerequisites).”

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Uncited infrastructure reuse claim 🐞 Bug ⚙ Maintainability

Description

docs/landscape.md asserts that GitHub Copilot “backend infrastructure” is reused by GitHub Agentic
Workflows, but provides no citation and the terms are ambiguous (what components, what kind of
reuse). This reads as a factual dependency claim without support.

Code

docs/landscape.md[84]

+Very relevant to fullsend: has code review and also supports having background agents steered interactively. Backend infrastructure here is reused by GitHub Agentic Workflows (see below).

Relevance

⭐⭐ Medium

Mixed history on tightening/citing factual docs claims; many clarity fixes accepted, but some
citation/accuracy tweaks rejected.

PR-#3903
PR-#2009
PR-#1017

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The sentence is introduced as a statement of fact without any accompanying reference or
clarification of scope.

docs/landscape.md[80-85]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The doc makes a concrete factual claim about shared infrastructure between Copilot and gh-aw, but does not cite a source and is vague about what is shared.

## Issue Context
Landscape docs are used as a reference; ambiguous/uncited claims are hard to validate and easy to contest later.

## Fix Focus Areas
- docs/landscape.md[84-84]

## Suggested change
Either (a) add an authoritative citation supporting the reuse claim, and/or (b) rephrase to be specific and qualified (e.g., “gh-aw appears to build on similar agent runtime primitives as Copilot, based on <source>”).

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

[qodo-code-review]

1. Overbroad merge feasibility claim 🐞 Bug ≡ Correctness

docs/problems/platform-nativeness.md states “Nothing technical blocks” autonomous merging via a
standalone workflow calling merge APIs, but merges still depend on workflow token permissions plus
branch protection/rulesets (required checks, required reviews, merge queue prerequisites). This can
mislead readers into assuming an approval/check event alone is sufficient or that protections can be
bypassed.

Agent Prompt

## Issue description
The doc uses an absolute statement ("Nothing technical blocks") when the described approach only works if repository policy and token permissions allow it (branch protection/rulesets, required checks/reviews, merge-queue configuration, workflow permissions). This should be qualified to avoid implying merges can bypass protections.

## Issue Context
This section is used to reason about whether gh-aw’s limitations are design choices vs. platform constraints. Overstating feasibility can send implementers down an incorrect path or create confusion when automation fails under common protections.

## Fix Focus Areas
- docs/problems/platform-nativeness.md[136-136]

## Suggested change
Reword to something like: “GitHub exposes APIs for programmatic merging, but success is still subject to the workflow token’s permissions and repository rules/branch protections (required checks/reviews, rulesets, merge queue prerequisites).”

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

[qodo-code-review]

2. Uncited infrastructure reuse claim 🐞 Bug ⚙ Maintainability

docs/landscape.md asserts that GitHub Copilot “backend infrastructure” is reused by GitHub Agentic
Workflows, but provides no citation and the terms are ambiguous (what components, what kind of
reuse). This reads as a factual dependency claim without support.

Agent Prompt

## Issue description
The doc makes a concrete factual claim about shared infrastructure between Copilot and gh-aw, but does not cite a source and is vague about what is shared.

## Issue Context
Landscape docs are used as a reference; ambiguous/uncited claims are hard to validate and easy to contest later.

## Fix Focus Areas
- docs/landscape.md[84-84]

## Suggested change
Either (a) add an authoritative citation supporting the reuse claim, and/or (b) rephrase to be specific and qualified (e.g., “gh-aw appears to build on similar agent runtime primitives as Copilot, based on <source>”).

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools