GitHop/docs/product-blueprint.md

HopWeb product blueprint

Product position

HopWeb is not "Gitea with AI buttons." It is a forge whose source of truth is a causal record of intent and verified outcomes, with Git underneath for universal tool compatibility.

The core screen should answer four questions without reconstructing them from a commit history:

1. What outcome was requested?
2. Who or what tried to produce it?
3. What exact result was checked, and what passed?
4. Which outcome became shared truth, and why?

Concept mapping

Conventional forge	HopWeb primary concept	Notes
Issue	Task	Outcome plus its evolving prompt history
Branch/worktree	Attempt	Isolated work by a human, agent, or team
Commit	Checkpoint/state	Immutable tree plus causal parents and metadata
CI status	Evidence	Bound to the exact checkpoint that was tested
Pull request	Proposal	Candidate outcome with intent, evidence, and diff
Merge	Accept/land	Advances the accepted state after validation
Commit graph	State graph	Includes prompts, checkpoints, proposals, and outcomes
Contributor	Actor	Human or agent identity with attribution and policy

Git branches, commits, and pull requests remain available as compatibility views. They should not dictate the Hop-native experience.

System shape

flowchart LR
    UI["Hop-native web UI"] --> API["Hop control-plane API"]
    API --> HDB["Hop state and evidence store"]
    API --> ORCH["Attempt orchestrator"]
    ORCH --> RUN["Isolated agent runners"]
    API --> GAPI["Gitea API and webhooks"]
    GAPI --> GIT["Git repositories"]
    GAPI --> FORGE["Identity, permissions, issues, Actions, packages"]
    RUN --> GIT
    RUN --> HDB

Ownership boundary

Gitea owns repositories, Git protocol, blob storage, users, organizations, teams, baseline authorization, webhooks, Actions, releases, and packages.

Hop owns tasks, prompts, attempts, state graph edges, agent sessions, checkpoints, evidence, proposals, acceptance policy, and orchestration.

The Hop UI composes both. A user should experience one product even when the data comes from two services.

Integration strategy

Start from an unmodified, pinned Gitea release and integrate through its API, webhooks, OAuth, custom templates, and custom assets. This lets us validate the workflow while preserving straightforward upstream upgrades.

Maintain a shallow source fork only when a required experience cannot be built cleanly through those seams—for example, a first-class state graph inside every repository route or authorization decisions that must be transactional with Git writes. Every fork patch must be small, isolated, tested, and documented with an upstream issue or a reason it is intentionally Hop-specific.

Do not put Hop's domain tables directly into Gitea's database. Services may share stable identifiers, but each service owns its schema and migrations.

Primary experience

Repository home

Lead with active tasks, recent accepted outcomes, running attempts, and failing evidence. Files and commits remain one click away, not the default narrative.

Task page

Show the current requested outcome, prompt history, constraints, linked issues, all attempts, and the policy required for acceptance.

Attempt page

Stream agent activity and expose the evolving state graph, working diff, checkpoints, check results, cost/runtime metadata, and interventions from humans.

Proposal review

Review by outcome first: summary, behavioral changes, evidence, risks, then file diff. Let reviewers compare multiple proposals for the same task side by side.

Acceptance

Acceptance is a named product event. It advances the repository's accepted Hop state, records the actor and policy decision, and materializes the corresponding Git change atomically or fails without advancing either view.

Initial domain model

• repositories: link a Hop repository to its Gitea repository identifier.
• tasks: requested outcome, status, creator, and acceptance policy.
• states: immutable typed nodes with tree identity, digest, actor, and time.
• state_edges: ordered, role-labelled causal relationships between states.
• attempts: isolated execution contexts associated with a task and base state.
• checks: commands or policies evaluated against an immutable checkpoint.
• evidence: normalized results, logs, artifacts, and provenance for checks.
• proposals: frozen candidate outcomes and their review status.
• acceptances: atomic record linking a proposal, accepted state, and Git ref.
• actors: human, service, and agent identities plus attestable metadata.

Use opaque, sortable IDs and repository-scoped uniqueness. Treat all mutable status fields as projections of an append-only event history where auditability matters.

Delivery sequence

Milestone 0 — foundation

• Pin and run Gitea locally with PostgreSQL and object storage boundaries.
• Add a Hop control-plane service and database.
• Establish Gitea OAuth/API authentication and webhook verification.
• Link Hop repositories to Gitea repositories.
• Define upgrade policy and an automated upstream rebase test.

Milestone 1 — task to accepted outcome

• Create tasks and capture prompt states.
• Launch isolated attempts through a runner interface.
• Ingest checkpoints and checkpoint-bound check evidence.
• Freeze proposals and display their diffs.
• Accept a validated proposal and advance the Git default branch.

Milestone 2 — native collaboration

• Multiple concurrent attempts and proposal comparison.
• Human intervention and prompt follow-ups within an attempt.
• Review policies, approvals, protected accepted state, and audit history.
• Notifications and task/attempt dashboards.

Milestone 3 — ecosystem

• Public repositories and discoverability.
• Agent marketplace and reusable execution profiles.
• Organization policy, billing, usage controls, and hosted runners.
• GitHub/GitLab import and bidirectional compatibility workflows.

Non-negotiable invariants

• A prompt is captured before project effects begin.
• Evidence always identifies the immutable checkpoint it evaluated.
• A proposal never changes after it is frozen.
• Acceptance never silently includes unrelated workspace effects.
• Human and agent actions are distinguishable and attributable.
• Git operations remain possible with standard Git clients.
• Hop state can be exported without requiring the HopWeb service forever.

Decisions still to make

• Hosted SaaS, self-hosted distribution, or both for the first release.
• Runner isolation boundary: container, microVM, or pluggable backends.
• Whether accepted Hop state is encoded into Git refs/notes in addition to the Hop database for portability and disaster recovery.
• The first authentication path: Gitea as OAuth provider or a shared external identity provider.
• Product name: retain HopWeb internally or choose a public forge name.