Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 22 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

**A live software-delivery product—and a case study in making coding agents accountable for verified work.**

[Explore the hosted product](https://forgeloop.hookerhillstudios.com) · [View the source](https://github.com/JRH89/ForgeLoop)
[Explore the hosted product](https://forgeloop.codefrontlabs.com) · [View the source](https://github.com/JRH89/ForgeLoop)

ForgeLoop takes GitHub issues or feature specifications through planning, bounded agent work, integration, verification, and human review. Its central design principle is simple: an agent saying “done” is not evidence. A run becomes reviewable only when its configured checks and acceptance criteria have supporting results.

Expand All @@ -18,7 +18,7 @@ Coding agents can produce patches, but reliable software delivery also needs saf
2. A planner turns the request into a validated dependency graph of bounded tasks.
3. Runners claim compatible work and execute it in isolated Git worktrees, using locally configured model credentials.
4. Changes are integrated, then repository-policy checks, acceptance criteria, and an independent review produce evidence.
5. Failed checks can route into a limited repair cycle. Passing work reaches a human approval boundary before GitHub publication; auto-merge is opt-in and checks the reviewed commit.
5. Failed checks can route into a limited repair cycle. Passing work follows the configured human-approval policy before GitHub publication; auto-merge is opt-in and checks the verified commit.

Administrators can also manually ask a runner to scan a repository snapshot for evidence-backed issue proposals. Scans are read-only, may incur provider charges, and never create GitHub issues without an explicit review action.

Expand All @@ -32,7 +32,7 @@ Administrators can also manually ask a runner to scan a repository snapshot for
| ForgeLoop runner | Java desktop/CLI process near the repository; uses Git worktrees and Docker for execution, MCP for approved context/tools, and runner-local provider credentials. |
| External services | GitHub App and OAuth for identity/repository events; configured hosted or local model providers for agent work. |

The control plane coordinates work; the runner handles repository checkout and execution. Repository context goes from the runner to the configured model provider, not through the control-plane database. The service stores workflow records, findings, usage, and evidence metadata. Provider data handling still applies to context sent to a selected model.
The control plane coordinates work; the runner handles checkout, execution, and model calls. The hosted service stores workflow records, issue text, findings, usage, and verification evidence. Optional detailed run records can also upload prompts, provider responses, and repository context as artifacts. Local execution is not an offline-only or zero-data-transfer promise; provider data handling still applies.

## Engineering decisions

Expand Down Expand Up @@ -72,13 +72,17 @@ This is an evolving portfolio product, not a claim that every production launch

## Delivery checklist

Checklist reviewed October 15, 2026. Checked items are implemented or have the
specific evidence stated; they do not imply every production validation is complete.

### Product and control plane

- [x] GitHub sign-in and self-service account provisioning with organization-scoped membership and roles.
- [x] GitHub App installation, signed webhook validation, idempotent deliveries, repository synchronization, and configurable issue-label intake.
- [x] Optional per-repository label bypass and Issue Chat label application with explicit paid-work warnings.
- [x] Optional issue-assignment gate for any assignee or a specified GitHub login; read-only intake diagnostics.
- [x] Manual repository analysis proposals with bounded/redacted context, runner-local model calls, usage estimates, and administrator-approved issue creation.
- [x] AI issue chat with editable specifications, explicit issue publication, optional intake-label application, and conversation deletion.
- [x] Persisted runs, task graphs, gates, acceptance criteria, audit history, approval, cancellation, bounded retries, and queue archive/restore.
- [x] Organization policies for budgets, concurrency, allowed providers, human approval, and optional verified-check auto-merge.
- [x] Usage views for model/provider spend estimates, tokens, run costs, pricing coverage, and comparisons.
Expand All @@ -92,20 +96,30 @@ This is an evolving portfolio product, not a claim that every production launch
- [x] Docker verification with pinned images, time/output limits, and policy-controlled network access.
- [x] Permissioned MCP context/tool routing with runner-side command controls.
- [x] Redacted lifecycle logs, provider usage records, checksummed verification evidence, screenshots, and filesystem/S3-compatible artifact storage.
- [x] Independent review and criterion-level evidence before a run reaches human review.
- [x] Independent review and criterion-level evidence before delivery, with human approval required only when configured.
- [x] GitHub check and pull-request publication; guarded auto-merge is opt-in and validates checks and the expected commit.

### Product experience and engineering quality

- [x] Responsive dashboard and public product pages, user documentation, SEO/social metadata, and structured data.
- [x] Cross-platform desktop preview packaging and GitHub Release download discovery with SHA-256 verification.
- [x] Runner 1.0.12 preview published for Windows/macOS x64 and ARM64, plus Linux DEB, RPM, Arch, and portable archives for both architectures; all twelve package digests verified.
- [x] Navy-and-teal desktop redesign, rounded native icons, HiDPI branding, and local preview/window-control regression coverage.
- [x] Consolidated Settings, persistent repository expansion/banner preferences, concise download guidance, and OS-specific download selectors.
- [x] Automated CI for Java modules, frontend checks, MCP checks, Windows setup, and disposable end-to-end workflows.
- [x] Live public downloads/release-feed smoke check for 1.0.12, separate from installer signing.
- [x] Linux server Compose deployment with loopback diagnostic ports and server-hosted Cloudflare ingress; physical reboot recovery remains unverified.

### Remaining validation
### Live validation and remaining launch gates

- [x] Complete a second-repository unattended issue-to-merge run ([October 9 evidence](docs/second-repository-validation-2026-10-09.md)); this does not close the operational production gates below.
- [x] Complete a live verified delivery and merge test: project-hub issue #6 / PR #7 merged after manual approval ([October 9 evidence](docs/second-repository-validation-2026-10-09.md#completion-and-unattended-follow-up)).
- [x] Complete a second-repository unattended issue-to-merge test: project-hub issue #10 / PR #11 merged automatically with human approval disabled ([successful validation](docs/second-repository-validation-2026-10-09.md#successful-unattended-validation)). Both delivery tests are complete; operational launch gates remain separate.
- [ ] Validate a physical workstation/server reboot, tunnel recovery, runner heartbeat, and authenticated access.
- [ ] Configure encrypted off-host backup retention and complete a restore drill on another host, including evidence objects.
- [ ] Complete staging burn-in, external alert delivery, and an explicit production go/no-go review.
- [ ] Sign Windows/macOS installers, notarize macOS packages, and verify published release assets in a public smoke test.
- [ ] Complete staging burn-in.
- [ ] Verify external alert delivery.
- [ ] Record an explicit production go/no-go review after the operational checks above.
- [ ] Sign Windows/macOS installers and notarize macOS packages; published previews remain unsigned.
- [ ] Publish the canonical-domain SEO migration and new authorization article, then verify live redirects, sitemap, canonical/social URLs, and images. Implementation and local checks alone do not close this item.
- [ ] Verify the new domain in Google Search Console and submit its canonical sitemap; search indexing and ranking are not established by build checks.
- [ ] Enable and verify support email notifications.
30 changes: 15 additions & 15 deletions docs/cloudflare-tunnel.md
Original file line number Diff line number Diff line change
@@ -1,10 +1,11 @@
# Linux server deployment with Cloudflare Tunnel

This guide deploys the current single-host Docker Compose stack at
`https://forgeloop.hookerhillstudios.com`, with
`https://forgeloop.codefrontlabs.com` as an additional hostname on the same
Cloudflare Tunnel. The Hooker Hill Studios hostname remains the configured
canonical URL. Cloudflare Tunnel is the only public ingress. PostgreSQL, the
`https://forgeloop.codefrontlabs.com`, the canonical public URL. The legacy
`https://forgeloop.hookerhillstudios.com` hostname remains on the same tunnel
for existing runner and authentication connections; public GET/HEAD pages
redirect to the canonical host after the SEO configuration is deployed.
Cloudflare Tunnel is the only public ingress. PostgreSQL, the
control-plane API, and the web UI publish diagnostic ports on loopback only; they
are not directly reachable from the LAN or Internet.

Expand Down Expand Up @@ -103,7 +104,7 @@ tunnel's internal service addresses do not change.

```dotenv
FORGELOOP_SECURITY_MODE=github
FORGELOOP_PUBLIC_BASE_URL=https://forgeloop.hookerhillstudios.com
FORGELOOP_PUBLIC_BASE_URL=https://forgeloop.codefrontlabs.com
CLOUDFLARED_CREDENTIALS_FILE=/etc/forgeloop/secrets/credentials.json
```

Expand All @@ -122,14 +123,13 @@ tunnel's internal service addresses do not change.
not need.

The GitHub OAuth callback is
`https://forgeloop.hookerhillstudios.com/login/oauth2/code/github`. The GitHub
`https://forgeloop.codefrontlabs.com/login/oauth2/code/github`. The GitHub
App setup callback is
`https://forgeloop.hookerhillstudios.com/api/github/app/callback`; its webhook
URL is `https://forgeloop.hookerhillstudios.com/api/github/webhooks`. These
URLs do not change during the server move. Never commit `.env` or print its
`https://forgeloop.codefrontlabs.com/api/github/app/callback`; its webhook
URL is `https://forgeloop.codefrontlabs.com/api/github/webhooks`. Never commit `.env` or print its
resolved contents with `docker compose config` when sharing diagnostics.
The Codefront Labs hostname is an alternate ingress. Add its OAuth callback
URL to the GitHub App configuration before signing in through that hostname.
Register the canonical callback before using it. Retain any legacy callback
still needed by existing sessions; public-page redirects do not rewrite OAuth or runner endpoints.

4. Install the tunnel credential with restrictive host permissions. Transfer it
over SSH/SCP or retrieve it from your secret manager; do not put it in the Git
Expand Down Expand Up @@ -233,9 +233,9 @@ multi-host deployment.
From the server:

```bash
curl -fsSI https://forgeloop.hookerhillstudios.com/
curl -sSI https://forgeloop.hookerhillstudios.com/oauth2/authorization/github
curl -i -X POST https://forgeloop.hookerhillstudios.com/api/github/webhooks \
curl -fsSI https://forgeloop.codefrontlabs.com/
curl -sSI https://forgeloop.codefrontlabs.com/oauth2/authorization/github
curl -i -X POST https://forgeloop.codefrontlabs.com/api/github/webhooks \
-H 'Content-Type: application/json' -d '{}'
sudo ss -lnt
```
Expand Down Expand Up @@ -296,7 +296,7 @@ The GitHub App helper preserves the webhook secret and does not print it:

```powershell
node .\scripts\Update-GithubAppWebhook.mjs `
https://forgeloop.hookerhillstudios.com/api/github/webhooks
https://forgeloop.codefrontlabs.com/api/github/webhooks
node .\scripts\Update-GithubAppWebhook.mjs --deliveries
```

Expand Down
3 changes: 2 additions & 1 deletion docs/deferred-launch-checks.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
# Deferred launch checks

Agreed on 2026-09-26; updated with October 9 validation evidence. Unchecked items
Agreed on 2026-09-26; reviewed October 15 against the October 9 merge and
second-repository validation evidence. Both delivery checks are complete. Unchecked items
remain open; deferral is not a passing result.

- [ ] **Off-host backup and restore — deferred.** Select encrypted, access-controlled
Expand Down
2 changes: 1 addition & 1 deletion docs/deployment-prerequisites.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ The GitHub App install entry point is implemented. Before enabling live reposito

These values are deployment secrets and must be supplied through the deployment secret manager, never committed to this repository.

For the current public deployment, configure the GitHub App setup URL as `https://forgeloop.hookerhillstudios.com/api/github/app/callback` and webhook URL as `https://forgeloop.hookerhillstudios.com/api/github/webhooks`. ForgeLoop signs the installation state for ten minutes and records the resulting installation only after the callback validates that state. Subscribe to `issues`, `pull_request`, `check_run`, and `check_suite` events. Pull request `closed` events with `merged: true` synchronize human merges into the run state. ForgeLoop also accepts GitHub's installation lifecycle deliveries to synchronize repository selection changes. Auto-merge has a scheduled reconciliation sweep as a fallback, but check events provide immediate response.
For the current public deployment, configure the GitHub App setup URL as `https://forgeloop.codefrontlabs.com/api/github/app/callback` and webhook URL as `https://forgeloop.codefrontlabs.com/api/github/webhooks`. ForgeLoop signs the installation state for ten minutes and records the resulting installation only after the callback validates that state. Subscribe to `issues`, `pull_request`, `check_run`, and `check_suite` events. Pull request `closed` events with `merged: true` synchronize human merges into the run state. ForgeLoop also accepts GitHub's installation lifecycle deliveries to synchronize repository selection changes. Auto-merge has a scheduled reconciliation sweep as a fallback, but check events provide immediate response.

Use least-privilege repository permissions: **Contents — read/write**, **Checks — read/write**, **Issues — read/write**, **Pull requests — read/write**, and **Commit statuses — read-only**. GitHub adds **Metadata — read-only** automatically. Issues write is used to create AI-proposed issues and explicitly close an issue after its verified pull request merges; failed close attempts remain pending and are retried. After changing App permissions, repository owners must approve the updated installation before those operations can succeed. Auto-merge cannot operate without pull-request write access and cannot establish the full success boundary without check and commit-status read access.

Expand Down
2 changes: 1 addition & 1 deletion docs/desktop-preview-release-notes.md
Original file line number Diff line number Diff line change
Expand Up @@ -60,4 +60,4 @@ For updates, pause the runner, wait for current work to finish, close the app,
and install the new version. Runner identity, settings and provider keys are
stored outside the installation directory and are preserved during upgrades.

Downloads and setup: https://forgeloop.hookerhillstudios.com/app/runner-downloads
Downloads and setup: https://forgeloop.codefrontlabs.com/app/runner-downloads
2 changes: 1 addition & 1 deletion docs/github-user-authentication.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

ForgeLoop uses one GitHub App for two separate trust relationships. Installation tokens authorize repository automation; the GitHub web OAuth flow authenticates human operators. A repository installation never creates an authenticated browser session.

Configure the GitHub App callback URL as `https://forgeloop.hookerhillstudios.com/login/oauth2/code/github`, with wildcard matching, device flow, and authorization-during-installation disabled. Supply `FORGELOOP_GITHUB_CLIENT_ID` and `FORGELOOP_GITHUB_CLIENT_SECRET` through the deployment secret manager. The Client ID is not the App ID.
Configure the GitHub App callback URL as `https://forgeloop.codefrontlabs.com/login/oauth2/code/github`, with wildcard matching, device flow, and authorization-during-installation disabled. Supply `FORGELOOP_GITHUB_CLIENT_ID` and `FORGELOOP_GITHUB_CLIENT_SECRET` through the deployment secret manager. The Client ID is not the App ID.

The public root does not load tenant data. **Sign in with GitHub** redirects through GitHub with OAuth state managed by Spring Security, exchanges the code only on the server, resolves GitHub's immutable numeric user ID, and stores authentication in an HTTP-only, Secure, SameSite cookie. ForgeLoop never uses a GitHub username as an authorization identifier.

Expand Down
15 changes: 14 additions & 1 deletion docs/public-website.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,14 +26,27 @@ browser checks verify that closing gap as well.
- Existing landing-page headlines, paragraphs, capability descriptions, and CTAs
are retained. Additional explanatory sections and FAQs follow the original copy.
- `/about`, `/features`, `/how-it-works`, `/security`, `/docs`, `/contact`, `/blog`.
- Eleven original engineering articles live in `frontend/src/public/articles.ts`.
- Twelve engineering articles live in `frontend/src/public/articles.ts`.
Publication dates reflect the actual publication date, not invented history.
No fabricated customer stories, traffic claims, benchmarks, reviews, or ratings.
The September 27 field note targets the specific question of recovering a
self-hosted AI coding runner after a restart; it cites Docker and GitHub
documentation and distinguishes tested reconnect behavior from deferred reboot proof.
The October 15 article covers GitHub App versus fine-grained PAT authorization
for AI coding agents, with official GitHub sources and a rollout checklist.

The canonical public origin is `https://forgeloop.codefrontlabs.com`, centralized
in `content.ts` for canonical tags, social URLs, JSON-LD, robots, and sitemap.
Legacy-host public GET/HEAD pages redirect permanently on deployment; runner,
API, OAuth, and pairing endpoints remain compatible. Regression checks reject
the old origin in generated public HTML. See [the October 15 SEO audit](seo-audit-2026-10-15.md)
for findings, deployment boundaries, and Search Console follow-up.

- Shared header/footer links cover desktop and mobile. Every public page and the
404 page has a decorative image-backed hero. Informational text remains HTML.
- Public navbar branding uses a 50px mark and 28px wordmark (44px/25px on mobile).
Above 760px, footer navigation groups are centered within their grid columns,
with left-aligned headings/links. Console and mobile-footer styling is unchanged.
- Each page and article now has unique artwork, responsive derivatives, and a
matching social preview. See [hero prompts and asset map](public-hero-prompts.md).
- All hero templates (including 404) apply a dark navy overlay below 1440px,
Expand Down
8 changes: 7 additions & 1 deletion docs/second-repository-validation-2026-10-09.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,12 @@
# Second-repository live validation — 2026-10-09

Status: BLOCKED; the end-to-end test did not pass.
Status: VALIDATED on October 9. Verified delivery merged as PR #7; the subsequent
unattended issue #10 / PR #11 test passed without a human approval action. See
[successful unattended validation](#successful-unattended-validation) for the
final outcome. The blocked attempts below are retained as the debugging history,
not the current status.

## Initial attempt — blocked

- Target: `JRH89/project-hub`, issue #6 (trim whitespace in file searches).
- Run: `440074fe-e140-4c56-a5db-2209b69e4457`.
Expand Down
Loading
Loading