Sync accepted GitHop state and prompt records

2026-07-12 01:57:25 +00:00
parent e5bb6a5600
commit b780eadd33
164 changed files with 4811 additions and 12224 deletions
@@ -0,0 +1,69 @@
+# ADR 0001: Use Gitea as the forge foundation
+
+- Status: Accepted
+- Date: 2026-07-11
+
+## Context
+
+HopWeb needs reliable Git hosting, repository permissions, users and
+organizations, review primitives, webhooks, CI integration, packages, releases,
+and administration. Rebuilding this foundation would delay the Hop-native
+workflow and create a large security and maintenance burden.
+
+Gitea is a mature, MIT-licensed, Go-based forge with a REST API, OAuth2 provider,
+webhooks, Git LFS, package registries, and a production-capable Actions system.
+It supports custom assets, themes, templates, and repository tabs, which are
+enough to prototype a unified Hop experience without immediately carrying a
+large source fork.
+
+## Decision
+
+Use a pinned upstream Gitea release as the forge substrate. Build Hop as a
+separate control-plane service and Hop-native web experience that integrates
+with Gitea through stable APIs, webhooks, OAuth, and Git protocols.
+
+Adopt a staged customization policy:
+
+1. configuration, branding, templates, assets, and API integration;
+2. small upstreamable extension points where integration seams are missing;
+3. a shallow maintained fork only for essential Hop-native behavior.
+
+Hop domain data will live outside the Gitea schema. Cross-service operations
+will use stable IDs, idempotency keys, and explicit reconciliation rather than
+distributed database writes.
+
+## Consequences
+
+### Positive
+
+- The team can focus on Hop's state model and collaboration experience.
+- Standard Git clients and familiar forge features work from the beginning.
+- Gitea security fixes and features can be consumed from upstream.
+- A separable control plane makes the Hop model portable to another Git host.
+
+### Costs and risks
+
+- A visually unified product must compose two service boundaries.
+- Some acceptance operations need careful compensation and reconciliation.
+- Template overrides are version-sensitive.
+- A deep fork would make upstream upgrades expensive.
+- Public multi-tenant runners require a stronger isolation model than Gitea's
+  default trusted-runner assumptions.
+
+## Guardrails
+
+- Pin exact Gitea versions and test upgrades in automation.
+- Keep a patch ledger for every source-level deviation from upstream.
+- Never edit vendored Gitea code for branding alone.
+- Prefer contributing generic extension points upstream.
+- Keep the Hop control plane independently testable and deployable.
+- Threat-model Git hooks, webhooks, runner registration, job tokens, and
+  untrusted repository content before supporting public execution.
+
+## Revisit when
+
+- Gitea's architecture prevents a core Hop invariant;
+- the source patch set grows beyond a routinely rebaseable size;
+- transactional acceptance cannot be made reliable across the boundary; or
+- operating two services costs more than owning a cohesive fork.
+
@@ -0,0 +1,64 @@
+# ADR 0002: Preserve Gitea's design and replace its collaboration semantics
+
+- Status: Accepted
+- Date: 2026-07-11
+
+## Context
+
+HopWeb needs to become Hop-native without spending early product effort on a
+new visual shell or maintaining broad Gitea template forks. Gitea already has a
+coherent, accessible component system and familiar repository navigation.
+
+The first product distinction is conceptual rather than visual. Hop users work
+with tasks, attempts, checkpoints, proposals, evidence, and accepted outcomes.
+Gitea exposes closely related infrastructure as issues, branches, commits, pull
+requests, Actions, and merges.
+
+## Decision
+
+Keep Gitea's existing layout, typography, color, spacing, icons, responsive
+behavior, and component states unchanged.
+
+Load a small same-origin semantic adapter through Gitea's supported custom
+footer template. The adapter changes visible labels and matching accessibility
+metadata while preserving the underlying routes and behavior:
+
+| Gitea element | Hop meaning |
+| --- | --- |
+| Code | Files |
+| Issues | Tasks |
+| Branches | Attempts |
+| Commits | Checkpoints |
+| Pull Requests | Proposals |
+| Actions | Evidence |
+| Merge Pull Request | Accept Proposal |
+
+On repository home pages, add a compact `Hop workflow` summary using Gitea's
+existing sidebar classes and the live navigation links and counts already
+rendered by Gitea. Do not add custom CSS.
+
+Set the application name to `Hop`, while retaining Gitea attribution and its
+standard administrative and Git compatibility surfaces.
+
+## Consequences
+
+- Existing Gitea behavior, responsiveness, themes, and accessibility remain
+  available.
+- The first Hop experience ships without a deep template fork.
+- URLs and APIs remain Gitea-compatible even when their visible names change.
+- DOM selectors and English labels are version-sensitive and require a smoke
+  test when upgrading Gitea.
+- As Hop gains distinct task and state behavior, individual semantic elements
+  can move from adapted Gitea routes to native server-backed routes without a
+  simultaneous visual redesign.
+
+## Guardrails
+
+- Do not add CSS to the semantic adapter.
+- Never rename an element unless its behavior is meaningfully compatible with
+  the corresponding Hop concept.
+- Keep accessible names and tooltips synchronized with visible labels.
+- Scope text replacement to navigation, headings, menus, labels, breadcrumbs,
+  and buttons. Never rewrite repository content or user-authored prose.
+- Verify the adapter against the pinned Gitea version before every upgrade.
+