How we solved the human approval gate for weekly status publishing - Google Docs integration for Agentics Beyond Code

[chrizbo]

The problem

Every week, our team runs a workflow that aggregates status data from GitHub and generates a draft Google Doc — formatted, filled in, ready for human review. But "ready for review" and "ready to publish" are different things. We needed a way for a human to explicitly say "this is good to go" without introducing a separate tool, a form, a Slack bot, or a process that lives outside the document itself.

The naive approaches all had the same failure mode: the signal is disconnected from the artifact. You could miss a Slack message. You could forget to flip a status in a spreadsheet. You could publish before anyone actually read it.

What we built

The answer was to use the document itself as the interface. When the draft is created, the workflow posts a finalization gate comment directly on the Google Doc. It's labeled with the lifecycle key for that week (weekly-status:2026-06-08) so it's unambiguous. The instructions live right in the doc:

When the report is ready, find the finalization gate comment in the Comments panel and resolve it to trigger publishing.

Resolving that comment is the signal. An hourly poller checks all open draft docs for resolved gate comments and, when it finds one, kicks off the finalization workflow — staged publishing, archiving, notifications.

There's also an escape hatch: commenting /finalize-status on the source Discussion does the same thing, for cases where the editor prefers to stay in GitHub.

How the workflow runs end to end

The whole chain starts from a structured GitHub Discussion — the weekly status data lives there as markdown. When the aggregation workflow runs, it triggers the draft dispatch workflow, which:

1. Validates and parses the Discussion content
2. Copies the Google Doc template, fills in all 18 placeholders
3. Posts the finalization gate comment
4. Sends a Slack notification to the team with a direct link to the draft

The source Discussion that feeds it:

The team gets a Slack message as soon as the draft is ready — so the review process can start immediately without anyone needing to check a folder or watch for an email:

You can see this week's notification in Slack. Not in the workspace yet? Join here.

The custom safe output

One of the less obvious pieces of the architecture is how the agent hands off work to the execution layer. Rather than having the AI model directly manipulate Google Drive, the dispatch workflow uses a custom safe output — a structured, validated JSON payload that declares what should happen before anything actually does.

In this case, the model produces a google_docs_create_collaboration_draft operation — the lifecycle key, proposed document title, source Discussion URL, and all 18 placeholder values resolved from the Discussion content. That payload is validated first (are all required sections present? do the counts parse correctly?) and only then executed: template copied, placeholders filled, gate comment posted.

This matters for the same reason the finalization gate matters: it keeps the agent in the proposal seat and humans (or validated logic) in the execution seat. The audit trail is right there in the run summary — template ID, destination folder, gate comment ID, write result. Nothing is implicit.

Why this fits the philosophy

Agentics Beyond Code is built on a specific belief: AI agents should do the operational work so humans can do the judgment work. The finalization gate and the safe output are both expressions of that.

The safe output means the agent can't go rogue on document creation — it proposes a structured operation that gets validated before anything touches Google Drive. The finalization gate means publishing can't happen until a human explicitly signs off — in the document, not in a side channel. The agent does the drafting work and then stops and waits, clearly, in a place the human is already working.

The signal is durable, traceable, and lives with the artifact.

A Google Drive API quirk we found along the way

While building this, we discovered that the Google Drive API's comments.create endpoint always shows "Original content deleted" on comments in Google Docs — even when no anchor or quotedFileContent field is provided at all. This is a known limitation: Google Docs requires an internal kix.PARAGRAPH_ID for true inline anchoring, and those IDs are generated by Google's Kix editor engine and aren't exposed via any public API. There's no workaround via Drive API v3 or v2.

The comment is still fully functional (it appears in the Comments panel and has a working resolve button), but the label is confusing. We filed our findings on the existing GitHub issue — specifically the new data point that the label appears even with a completely anchor-free request, which hadn't been documented before.