Epic 02: Canonical GitHub Stars Automation Hardening

[primeinc]

Goal

Take primeinc/github-stars from brittle/failing Actions automation to a canonical, evidence-verified, self-validating pipeline.

Scope

• Inventory canonical repo sources and ../refs if present in the execution environment.
• Capture latest failed GitHub Actions logs and bind root cause to direct evidence.
• Reconcile workflow topology between docs and actual .github/workflows/* files.
• Harden token/secret behavior for star fetching.
• Replace implicit repo-state handoff with explicit artifact/job handoff.
• Gate manifest/schema validation.
• Gate web build validation.
• Canonicalize generated data flow from GitHub stars to published site output.
• Repair stale agent/planning docs.
• Improve workflow summaries and proof artifacts.
• Define one final acceptance run proving the system works.

Direct Evidence Already Known

• AGENTS.md describes this as a GitHub Actions-based automation system and says core logic lives in .github/workflows/*.yml.
• AGENTS.md documents numbered workflows: 01-fetch-stars, 02-sync-stars, and 03-curate-stars.
• .github/workflows/01-fetch-stars.yml exists and fetches starred repositories, writes .github-stars/data/fetched-stars-graphql.json, uploads an artifact, and commits results.
• .github/workflows/02-sync-stars.yml exists and fails if .github-stars/data/fetched-stars-graphql.json is absent.
• web/package.json exposes build/lint scripts.
• web/vite.config.js builds to ../docs.
• web/src/App.jsx loads data.json and sorts by user_starred_at.

Known Gaps / Blockers

• Latest failed Actions run logs must be captured before exact root cause is claimed.
• ../refs must be inventoried before any claim that it was used canonically.
• The documented third workflow must be confirmed as present, renamed, deleted, or stale documentation.

Acceptance Criteria

• All sub-issues are completed with proof artifacts.
• Every material claim is labeled as Direct evidence, Weak inference, Unsupported, Blocked, or Contradicted.
• No issue is closed from checklist text alone.
• Final successful Actions run proves fetch, sync, validation, build, and generated outputs.
• Docs match actual workflow/source topology.
• Missing or unavailable sources are explicitly marked instead of guessed.

Child Issues

Child issues will be linked here after creation.

Definition of Done

The repo has a documented, reproducible, validated pipeline with clear failure diagnostics and one final proof-backed acceptance run.

[primeinc]

Child Issue Index

• 02A: Inventory Canonical Sources and ../refs #43 — 02A: Inventory Canonical Sources and ../refs
• 02B: Capture Latest Failed GitHub Actions Run Logs #44 — 02B: Capture Latest Failed GitHub Actions Run Logs
• 02C: Reconcile Workflow Topology with Source and Docs #45 — 02C: Reconcile Workflow Topology with Source and Docs
• 02D: Make Star-Fetch Authentication Explicit and Fail-Fast #46 — 02D: Make Star-Fetch Authentication Explicit and Fail-Fast
• 02E: Replace Implicit Repo-State Handoff with Explicit Artifact Handoff #47 — 02E: Replace Implicit Repo-State Handoff with Explicit Artifact Handoff
• 02F: Enforce Manifest Schema Validation as a Hard Gate #48 — 02F: Enforce Manifest Schema Validation as a Hard Gate
• 02G: Add Deterministic Web Build and Lint Validation #49 — 02G: Add Deterministic Web Build and Lint Validation
• 02H: Canonicalize Generated Data Flow from Stars to Site #50 — 02H: Canonicalize Generated Data Flow from Stars to Site
• 02I: Repair Stale Agent Instructions and Planning Docs #51 — 02I: Repair Stale Agent Instructions and Planning Docs
• 02J: Harden Commit, Push, Concurrency, and Rerun Behavior #52 — 02J: Harden Commit, Push, Concurrency, and Rerun Behavior
• 02K: Add Proof-Rich Workflow Summaries and Diagnostics #53 — 02K: Add Proof-Rich Workflow Summaries and Diagnostics
• 02L: Run Final Bulletproof Acceptance Validation #54 — 02L: Run Final Bulletproof Acceptance Validation

Dependency path:
02A -> 02B/02C -> 02D/02E -> 02F/02G/02H -> 02I/02J/02K -> 02L

Evidence rule for this epic: no child issue closes without proof artifacts. Checklist text is not validation.