Epic: Hosted Alpha Loop for 24/7 repo stewardship with human feedback loops

[bradtaylorsf]

Goal

Build hosted Alpha Loop as a policy-constrained, repo-scoped autonomous worker that can run continuously for a website or web application repo, triage incoming work, execute safe issues, pause for human input, emit lifecycle events, ingest feedback, resume paused sessions, and hand off QA through tool-agnostic integrations.

Non-Technical Summary

A team should be able to add Alpha Loop to a repo, run it on a server, and let teammates submit website/app changes through GitHub, Slack, a website form, or another tool. Alpha Loop keeps GitHub organized, works only inside explicit guardrails, opens PRs with preview/QA context, asks humans for clarification when needed, and resumes the same issue/session when feedback arrives.

This is not a generic all-powerful agent. It is a long-running repo steward with durable state, clear authority boundaries, GitHub as the source of truth, and adapters for whatever communication tools a team uses.

Why This Matters

• Makes Alpha Loop useful as a 24/7 worker for real repos instead of only an attended local command.
• Lets non-engineering teammates request content, copy, visual, SEO, and small app changes without learning the full development workflow.
• Keeps humans in the loop for QA, clarification, scope expansion, and risky operations.
• Avoids hard-coding Slack or any one team's workflow by using events, hooks, and a feedback ingestion contract.
• Creates a safe first hosted path for sites like Aging Sidekick while remaining general enough for other web apps.

Architecture Observations

• Alpha Loop already has isolated worktrees, GitHub issue/PR state, test/retry, verify/review/learn, session PRs, crash recovery, epic execution, and multi-epic queues.
• alpha-loop run --epic <N> and alpha-loop run --epics <ids> exist, but targeted run --issue <N> is needed for feedback-specific resume and precise hosted execution.
• Existing session history needs to become durable enough to preserve paused issue state, branch/worktree identity, prompt/transcript metadata, and external event ids.
• GitHub should remain the canonical record for issue state and human feedback; Slack, Teams, Discord, email, and web forms should be adapters.
• Hosted mode needs policy enforcement before work starts, before commands run, and after diffs are produced.
• Events should be typed lifecycle payloads delivered to configured destinations, not one-off product-specific hooks.
• Epic: Multi-epic execution queues and PR coordination #217 is complete and provides queue execution/coordination foundations this epic can build on.

Ordered Sub-Issues

• feat: add targeted single-issue execution #283 - Add targeted single-issue execution with alpha-loop run --issue <N>.
• feat: persist resumable session state for paused work #284 - Persist resumable session state for paused and waiting work.
• feat: add human feedback session state machine #285 - Add a human feedback session state machine.
• feat: resume paused issues after human feedback #286 - Resume paused issues after human feedback with alpha-loop resume --issue <N>.
• feat: add feedback ingestion contract and adapter CLI #287 - Add a feedback ingestion contract and adapter CLI.
• feat: emit lifecycle events and configurable destinations #269 - Emit lifecycle events and configurable destinations.
• feat: add automation policy guardrails for hosted mode #288 - Add automation policy guardrails for hosted mode.
• feat: add hosted daemon mode #289 - Add hosted daemon mode.
• feat: add web app verification and QA handoff profile #290 - Add a web app verification and QA handoff profile.
• docs: add hosted Alpha Loop setup guide for websites and apps #291 - Document hosted Alpha Loop setup for websites and apps.
• docs: add Aging Sidekick hosted pilot blueprint #292 - Add an Aging Sidekick hosted pilot blueprint.

Acceptance Criteria

• Alpha Loop can run exactly one requested issue via alpha-loop run --issue <N>.
• Sessions have durable manifests that preserve issue, branch, worktree, PR, stage, status, prompt, transcript, and event metadata.
• Sessions can pause for human input or QA, allow other eligible work to continue, and resume later from the same issue/session context.
• External feedback can be ingested idempotently and associated with the correct GitHub issue, PR, session, and source thread/message.
• Lifecycle events can be delivered to logs, webhooks, and local commands with JSON, Slack, Teams, and Discord formatting.
• Event payloads include harness metadata such as agent, model, command, prompt text/path/hash, transcript path, and session logs, with redaction controls.
• Hosted daemon mode can triage, poll feedback, select safe work, execute, pause, resume, and shut down gracefully.
• Automation policy blocks unsafe work before execution and records clear reasons in GitHub/session history.
• Web/app verification captures build/test/browser/preview/QA handoff artifacts for sites like Astro/Sanity apps.
• Documentation makes setup clear for another website or web app repo, including Slack/Teams/Discord/custom service examples.
• Aging Sidekick-style workflow is documented as a concrete reference implementation.

Dependencies and Sequencing

1. feat: add targeted single-issue execution #283 comes first because hosted feedback and daemon workflows need precise issue targeting.
2. feat: persist resumable session state for paused work #284 establishes durable session state used by all pause/resume/event work.
3. feat: add human feedback session state machine #285 defines the state transitions for human input, QA, feedback, and resume.
4. feat: resume paused issues after human feedback #286 uses the session state and state machine to resume one issue after feedback.
5. feat: add feedback ingestion contract and adapter CLI #287 defines inbound feedback from Slack/websites/custom services into GitHub/session state.
6. feat: emit lifecycle events and configurable destinations #269 defines outbound lifecycle events and destination delivery.
7. feat: add automation policy guardrails for hosted mode #288 adds the policy guardrails required before unattended daemon execution.
8. feat: add hosted daemon mode #289 ties targeting, session state, feedback, events, and policy into a long-running daemon.
9. feat: add web app verification and QA handoff profile #290 makes the first hosted web/app use case practical with browser verification and QA handoff.
10. docs: add hosted Alpha Loop setup guide for websites and apps #291 and docs: add Aging Sidekick hosted pilot blueprint #292 should land with or immediately after the implementation work so hosted setup is usable by others.

Some later docs work can begin early, but final examples should reflect the shipped config and CLI names.

Verification Expectations

• Unit and command tests for new CLI flags, session manifests, feedback ingestion, event delivery, policy enforcement, and daemon scheduling.
• Fake-timer tests for daemon intervals and hosted scheduling behavior.
• Mocked GitHub tests for issue comments, labels, PR updates, feedback markers, and resume behavior.
• Event delivery tests for webhook, command, log, Slack, Teams, Discord, redaction, retry, and failure paths.
• Web/app verification tests for screenshot plans, preview URL handling, QA payloads, and PR body output.
• Documentation tests or link checks for hosted setup references.
• Final manual/fixture verification with a small Astro-style website repo flow: request -> issue -> run -> PR/preview -> QA event -> feedback ingest -> resume.

Related

• Completed foundation: Epic: Multi-epic execution queues and PR coordination #217
• Lifecycle events child: feat: emit lifecycle events and configurable destinations #269
• Future adjacent QA depth: Epic: Autonomous QA Pipeline — Punchlist-driven agent verification loop #166
• Intended first downstream pilot: Aging Sidekick marketing site.