2026-05-28 23:12:46 -04:00
4 changed files with 21 additions and 21 deletions
@@ -3,8 +3,8 @@
 Short, durable records of decisions — one file per decision. This is a
 lightweight [Architecture Decision Record](https://adr.github.io/)
 practice: capture *what was decided and why* in a versioned file so the
-reasoning lives in the clone, not in a forge issue thread or a chat log
-that disappears when the provider does.
+reasoning lives in the clone, not in a Gitea issue thread or a chat log
+that disappears when the host does.

 See `docs/research/issue-tracking-vs-in-repo-decision-history.md` for
 the rationale behind keeping decision history in-repo, and
@@ -34,7 +34,7 @@ What we decided, stated plainly.
 What follows — the good, and the costs/trade-offs accepted.

 ## Links
-PRDs, research notes, issues/PRs. Forge links are convenience
+PRDs, research notes, issues/PRs. Gitea links are convenience
 pointers; the reasoning above must stand without them.
 ```

@@ -1,7 +1,7 @@
 # Product requirement docs

 One PRD per feature: what to build, why, and how it's scoped. The PRD
-is the durable spec — it should stand on its own without a forge issue
+is the durable spec — it should stand on its own without a Gitea issue
 thread (see [`../README.md`](../README.md) for when a PRD is the right
 document vs. a research note or a decision record).

@@ -60,4 +60,4 @@ doesn't need (a small change rarely needs Scope or Implementation
 chunks) and add others where they help (e.g. Testing strategy,
 Alternatives considered, References). Keep the rationale self-contained
 — inline the reasoning rather than linking out to an issue thread, so
-the PRD survives a forge migration.
+the PRD survives a move off Gitea.
@@ -37,6 +37,6 @@ In practice most notes share a loose shape:
 Keep the reasoning self-contained and grounded: cite sources, link
 files and PRDs, and prefer concrete evidence from this repo over
 generic claims — a note should stand on its own without a chat log or a
-forge thread. When a note's recommendation gets acted on, capture the
+Gitea thread. When a note's recommendation gets acted on, capture the
 resulting decision in a PRD or a decision record; the note stays as the
 "why we looked into it," not the system of record for the choice.
@@ -5,12 +5,12 @@ decision-making around them) as Gitea issues, given that the project
 already records specs in-repo as PRDs (`docs/prds/`) and rationale as
 research notes (`docs/research/`). The stated constraint is that the
 *history of why we decided things* should be durable and portable —
-not locked into a single forge (Gitea today, conceivably GitHub or
-something else tomorrow).
+not locked into a single hosting provider (Gitea today, conceivably
+GitHub or something else tomorrow).

 ## Summary

-Keep using issues, but demote them. The repository — not the forge — is
+Keep using issues, but demote them. The repository — not Gitea — is
 the system of record for any decision you would be unhappy to lose.
 Issues are an excellent **inbox and coordination surface** (cheap
 capture, triage, async discussion, notifications, auto-linking) and a
@@ -25,8 +25,8 @@ it is closed.** PRDs already do this for features; the gap is (a) small
 requests that never merit a PRD and (b) decisions that aren't features
 at all (e.g. "we merge with rebase," "author identity is claimed-not-
 vouched"). Close that gap with a lightweight in-repo decision log. Then
-issues can be as disposable as the forge makes them, and migrating
-forges costs you triage state, not history.
+issues can be as disposable as Gitea makes them, and migrating off
+Gitea costs you triage state, not history.

 ## Why this even comes up here

@@ -46,9 +46,9 @@ But the issue layer has quietly become load-bearing in places:
 - PR #89's description links `…/didericis/claude-bottle/issues/88` —
  the **pre-rename** repo path (the project was Codex-bottle/claude-
  bottle before the bot-bottle rebrand). That link is already
-  half-dead: a concrete demonstration that forge URLs rot under the
+  half-dead: a concrete demonstration that Gitea URLs rot under the
  most routine event imaginable, a rename.
- Issue/PR numbers (`#88`, `#90`, `#94`, `#95`) are **forge-assigned
+- Issue/PR numbers (`#88`, `#90`, `#94`, `#95`) are **Gitea-assigned
  from a shared sequence**. They cannot be reconstructed from a clone,
  and they collide/renumber on import into a different tracker.

@@ -65,10 +65,10 @@ producing references that don't survive a rename, let alone a migration.
 | Auto-linking (`Closes #N`, PR↔issue, commit↔issue) | Native | Manual cross-reference |
 | Version control of the content | None — lives in Gitea's DB | Full — diff, blame, branch, revert |
 | Travels with `git clone` | No | Yes |
-| Survives forge migration | Degrades (export/import; threads, authors, timestamps, refs lossy) | Unaffected |
-| Survives forge outage | Inaccessible | Local clone has it |
+| Survives a move off Gitea | Degrades (export/import; threads, authors, timestamps, refs lossy) | Unaffected |
+| Survives a Gitea outage | Inaccessible | Local clone has it |
 | Greppable offline / by tooling | Only via API | `grep docs/` |
-| Reproducible identifiers | Forge-assigned numbers | Filenames you control (`0027-…`) |
+| Reproducible identifiers | Gitea-assigned numbers | Filenames you control (`0027-…`) |

 The split is clean: **issues win on the live, social, coordination axes;
 the repo wins on every durability and portability axis.** Nothing about
@@ -82,7 +82,7 @@ don't let the durable thing depend on the ephemeral one."
   emerges in a thread and dies there unless someone copies it into the
   spec. PRD 0025 is already in this state.
 2. **Reference rot.** `Closes #88` / "see issue #90" are meaningful only
-   against one forge instance at one point in time. A rename already
+   against one Gitea instance at one point in time. A rename already
   broke one such link; a migration would break all of them and
   silently renumber the survivors.
 3. **Two sources of truth.** A PRD carries `Status: Draft`; the issue
@@ -162,7 +162,7 @@ Options, cheapest first:
 3. **Periodic issue export.** Belt-and-suspenders: a scheduled job hits
   the Gitea API and dumps open/closed issues + comments to JSON under
   `docs/issues-archive/`, committed. Preserves the raw thread against
-   forge loss without changing daily workflow. Mechanical, not a
+   losing Gitea without changing daily workflow. Mechanical, not a
   substitute for reifying rationale (a JSON dump of a thread is
   evidence, not a decision).

@@ -172,7 +172,7 @@ These compose: ADRs/journal for the *decision*, optional export for the
 ## Recommendation

 1. **Keep Gitea issues for intake, triage, and discussion.** Don't fight
-   the forge on the things it's good at.
+   Gitea on the things it's good at.
 2. **Make the repo the system of record.** Adopt the rule: no decision
   is "done" until its rationale exists in a versioned file (PRD,
   research note, or decision log). The issue is a pointer, never the
@@ -182,7 +182,7 @@ These compose: ADRs/journal for the *decision*, optional export for the
   back-filling the few decisions already made only in threads or chat
   (rebase-merge policy; the agent-identity trust call from PRD 0027).
 4. **Retrofit PRD 0025** to inline its #88 rationale, removing the one
-   existing hard dependency on a forge thread.
+   existing hard dependency on a Gitea thread.
 5. **Treat issue numbers as disposable.** When a PRD/commit cites an
   issue, ensure the cited content is mirrored in-repo so the citation
   degrades to a dead-but-harmless link, not lost information. (The
@@ -192,5 +192,5 @@ These compose: ADRs/journal for the *decision*, optional export for the

 Net: issues stay, because the alternative to issues is chat, which is
 worse. But the project's durable memory must live where the project
-already lives — in the clone — so that switching forges, or losing one,
+already lives — in the clone — so that moving off Gitea, or losing it,
 costs you a backlog you can rebuild, never a history you can't.