docs(ISSUE-WP-0006): Forgejo-only language and projection boundary
All checks were successful
CI Smoke / host-smoke (push) Successful in 0s
CI Smoke / container-smoke (push) Successful in 2s
Build and Publish Container Image / build-and-push (push) Successful in 34s

Prefer Forgejo as the self-hosted forge product. Keep Gitea only as the
Gitea-compatible API identifier (module backends/gitea, type string
gitea). FORGEJO_TOKEN is preferred; GITEA_* remains a deprecated alias.

INTENT/SCOPE quote ACT-ADR-005: issue-core is not the fleet ops claim
queue. Connector docs describe repo work record → hub index → optional
Forgejo projection, not activity-core → issue-core → harness.

Assistant: grok
Assistant-Session: 01a09dc6-3f0d-7c93-8b11-8e83c0623d49
This commit is contained in:
tegwick 2026-09-14 04:52:58 +02:00
parent f9d276dadf
commit ee9b85215d
34 changed files with 410 additions and 263 deletions

View file

@ -9,11 +9,12 @@ state-hub, under a closed kind registry (`workplan`, `task`, `intake`,
`the-custodian/canon/standards/work-record-types_v0.1.md` and the founder-
reviewed architecture draft (`WorkOrchestrationArchitectureDraft.md` v0.2).
External issue trackers (Forgejo / Gitea, GitHub, Jira, …) remain necessary
External issue trackers (Forgejo, GitHub, Jira, …) remain necessary
when a human counterparty, open-source workflow, or third-party process lives
there. They are **not** the fleet coordination substrate and are **not** a
work-record kind. Canon is explicit: *issue-core issues become external
projections only.*
projections only.* The self-hosted forge product is **Forgejo** only
(ACT-ADR-005); Gitea is not a supported second product or migration target.
issue-core exists so that, **when an external tracker is actually in use**,
the fleet has one backend-agnostic surface to project, query, and update
@ -32,9 +33,11 @@ calls with no stable back-reference to the work record.
issue-core was originally built and documented as a **task landing zone**: a
single place where humans, activity-core, and agents filed work via CLI /
REST, with Gitea as the default store. That framing contradicted file-first
work records and produced a live incident (`daily-todo-md-stale-review`
IssueSink → Forgejo issues that were never fleet work).
REST, with the self-hosted forge as the default store (product language then
said Gitea; the fleet forge is **Forgejo**). That framing contradicted
file-first work records and produced a live incident
(`daily-todo-md-stale-review` → IssueSink → Forgejo issues that were never
fleet work).
Architecture draft §4.2 and the work-record types standard (CUST-WP-0060)
retargeted purpose: **connector, not origin**. Capability (CRUD, backends,
@ -51,13 +54,16 @@ execution loop.
- **Tracker CRUD** on configured backends: create, read, update, close /
reopen, comment (and related label / assignee / milestone operations).
- **Backends:** local SQLite (offline store / cache), Gitea (Forgejo-
compatible in deployment). Further backends (GitHub, GitLab, Jira) are
product growth, not yet implemented.
- **Backends:** local SQLite (offline store / cache), **Forgejo** (Gitea-
compatible API; Python module `issue_core.backends.gitea`, backend type
string `gitea`). Further backends (GitHub, GitLab, Jira) are product
growth, not yet implemented. Gitea is not a second supported product.
- **CLI** (`issue` / `issue-core`) and **Python library** for direct backend use.
- **REST** (`issue serve`, optional `[api]` extra): intentional create
(`POST /issues/`), list/get/claim (`GET`/`PATCH /issues/`).
- **Backend↔backend sync** via CLI (e.g. Gitea ↔ SQLite) — *not* the same as
- **REST** (`issue serve`, optional `[api]` extra): intentional **external
tracker** create (`POST /issues/`), list/get (`GET`/`PATCH /issues/`).
REST claim/list is for tracker issues already on a backend — **not** the
fleet ops claim queue (see below).
- **Backend↔backend sync** via CLI (e.g. Forgejo ↔ SQLite) — *not* the same as
work-record boundary sync below.
- **Optional intentional ingestion** of TaskSpec payloads for clients that
deliberately create tracker issues (not the fleet path for internal findings).
@ -104,10 +110,23 @@ connector must add **no coordination load** to the internal loop.
Emitter policy: activity-core **ACTIVITY-WP-0022** (from ISSUE-WP-0004-T05 /
CUST-WP-0060).
- **Not the fleet ops claim queue.** Internal scheduled automation
(FI daily brief, Binky rhythm, mail intake, …) **claim and execute** via
activity-core **`ops_run`** ([ACT-ADR-005](../activity-core/docs/adr/adr-005-ops-runs-vs-dev-work-records.md)).
issue-core does **not** provide that queue. `POST /issues/` creates or
links an **external tracker** issue only. The default activity-core sink
remains state-hub progress + `ops_run`**not** REST to issue-core for
Binky/FI. Do not poll issue-core as the primary automation loop.
ACT-ADR-005: *issue-cores correct role is a connector facade over
external trackers (Forgejo, GitHub, Jira, …). It is not the origin of
work records and not the default internal ops queue. Gitea is out of
scope for this fleet; the self-hosted forge is Forgejo.*
- **Not a second autonomy or budget model.** `lane`, `tags`, and budgets live
on the work record. Projections carry only what external collab needs
(title, body, agreed labels); they must not invent parallel lane/budget
semantics on Gitea labels without explicit rules.
semantics on Forgejo labels without explicit rules.
- **Not a project manager, spawn audit trail, event bus, notification
system, or workflow engine.** Plans and dependencies are workplan tooling;
@ -151,8 +170,8 @@ cancel`) and tracker **`IssueState`** (`open` / `in_progress` / `blocked` /
+---+------+------+--+
| | |
v v v
Gitea/ SQLite GitHub
Forgejo cache (planned)
Forgejo SQLite GitHub
cache (planned)
```
**Primary fleet path (coordination):**
@ -205,3 +224,7 @@ cancel`) and tracker **`IssueState`** (`open` / `in_progress` / `blocked` /
connector decision.
- `the-custodian/canon/architecture/adr-001-workplans-as-repo-artefacts.md`.
- activity-core **ACTIVITY-WP-0022** — IssueSink default policy (emitter side).
- activity-core **ACT-ADR-005** — ops runs vs work records; issue-core is not
the ops claim queue.
- `workplans/ISSUE-WP-0006-forgejo-only-projection-boundary.md` — Forgejo-only
product language and projection boundary.