@gurupanguji

Scheduled Post Deploy And Social Gating Design

Goal

Make scheduled blog posts reliably go live before social snippets publish, and prevent dead-link social posts when the site is not yet updated.

Problem

The current system treats _posts/ and _snippets/ as parallel tracks:

• Jekyll/GitHub Pages builds the site when main changes.
• publish_social.yml posts snippets every day at 22:00 UTC.

That leaves a gap for future-dated posts. A post can exist on main and still be excluded from the built site until its publish timestamp passes. Because there is no scheduled rebuild at publish time, the site can stay stale while social still posts the snippet.

Design

1. Add an explicit scheduled site rebuild workflow

Add a workflow that runs daily after the expected publish window for scheduled posts.

• Trigger time: 12:10 UTC
• Intent: catch posts scheduled for 12:00 UTC, which is 05:00 PT during daylight saving time
• Behavior:
  • check out main
  • set up Ruby and Bundler
  • run a Jekyll production build
  • force a no-content rebuild commit only when a rebuild marker changes

This keeps the site deployment model simple and works with the current GitHub Pages style push-based setup.

2. Add a hard preflight gate before social publishing

Extend scripts/publish_social.py so it can verify the post URL before posting.

Checks:

• fetch canonical_url
• require HTTP 200
• require either:
  • HTML <title> contains the expected post title, or
  • og:title matches the snippet/post title

If the page is not live, the script must exit non-zero and publish nothing.

3. Add bounded retries to the preflight gate

The social workflow should tolerate a late deploy without posting too early.

Defaults:

• interval: 300 seconds
• attempts: 12
• total wait budget: 60 minutes

The workflow should wait and recheck until the URL is live or the retry budget is exhausted.

4. Add deploy-window validation

Extend scripts/validate_posts.py so it validates scheduled-post timing against the operational window.

Rules:

• for posts dated on or after 2026-03-23, require the front matter timestamp to equal 12:00:00 +0000
• fail validation if a future post for this scheduled pipeline uses a different timestamp
• keep existing filename-date and snippet consistency checks

This turns the “05:00 PT” publishing expectation into an enforced repository rule instead of tribal knowledge.

5. Normalize future scheduled posts

Update all future posts from 2026-03-23 onward so their front matter date uses 12:00:00 +0000.

This aligns:

• post publish time
• scheduled rebuild window
• social preflight assumptions

File Changes

New

• .github/workflows/rebuild_scheduled_posts.yml
• docs/superpowers/specs/2026-03-22-scheduled-post-deploy-and-social-gating-design.md
• docs/superpowers/plans/2026-03-22-scheduled-post-deploy-and-social-gating-implementation-plan.md

Modify

• .github/workflows/publish_social.yml
• scripts/publish_social.py
• scripts/validate_posts.py
• _posts/2026-03-23-*.md and later scheduled post files that need timestamp normalization

Operational Notes

• The social workflow must remain safe under workflow_dispatch. URL verification should still run unless a future explicit bypass flag is added. This change does not add such a bypass.
• The rebuild workflow must not touch social posting code or secrets.
• The rebuild workflow should create at most one small commit per run, only when needed to trigger deployment.

Risks

Scheduled rebuild depends on repository write access

If GitHub Actions cannot push a rebuild marker commit to main, the workflow will fail. In that case, the fallback remains the social preflight gate, which stops dead-link posting.

URL checks can fail on transient network errors

Retries reduce false negatives, but the workflow should still fail loudly when the page never becomes live.

Daylight saving time drift

This design targets the current 05:00 PT == 12:00 UTC policy and encodes that explicitly. If the policy changes, the workflow cron and validator constant must change together.

Acceptance Criteria

1. A post scheduled for 2026-03-23 12:00:00 +0000 is included in a rebuild that runs at 12:10 UTC.
2. Social publishing refuses to post when the page returns non-200 or the title check fails.
3. Social publishing waits up to one hour for a delayed deploy, then fails without posting if the page never goes live.
4. Validation fails when a future scheduled post uses the wrong publish timestamp.
5. Future posts from March 23 onward are normalized to 12:00:00 +0000.