coulomb/issue-core
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

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

Browse source 
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
Download patch file Download diff file Expand all files Collapse all files

16
docs/uuid-external-id-mapping.md
View file

@ -11,13 +11,13 @@ kinds in `the-custodian/canon/standards/work-record-types_v0.1.md`
## Problem
When collaboration requires a third-party tracker (Forgejo/Gitea, GitHub,
When collaboration requires a third-party tracker (Forgejo, GitHub,
Jira, …), the fleet still needs a stable link between:
| Side | Identity today | Owner |
| --- | --- | --- |
| Internal work record | UUIDv7 written back as `state_hub_*_id` (workplan/task/intake/…) | repo file + state-hub |
| External issue | Backend issue id / number (+ URL) | Gitea, GitHub, … via issue-core |
| External issue | Backend issue id / number (+ URL) | Forgejo, GitHub, … via issue-core |
Without an explicit mapping:
@ -95,7 +95,7 @@ mapping:
work_record_uuid: <uuidv7> # primary internal key
work_record_id: "ISSUE-WP-0004-T01" # canonical name, optional denorm
work_record_kind: task # task | intake | workplan | …
backend: gitea # gitea | github | gitlab | jira | sqlite
backend: gitea # forgejo product; type string `gitea` | github | gitlab | jira | sqlite
external_id: "176" # backend-native issue id/number
external_url: "https://…/issues/176"
target_repo: "coulomb/example" # optional routing hint
@ -123,7 +123,7 @@ issue-core only:
```yaml
# on a task / intake YAML block (illustrative — exact key names TBD with canon)
external_tracker:
backend: gitea
backend: forgejo # product; stored type may be `gitea`
issue_id: "176"
issue_url: "https://…"
mapped_by: issue-core
@ -132,7 +132,7 @@ external_tracker:
Alternatively a single string field if canon prefers flat keys:
```text
issue_core_external_ref: "gitea:coulomb/example#176"
issue_core_external_ref: "forgejo:coulomb/example#176"
```
Canon PR owns the field name; issue-core owns the mapping authority.
@ -142,7 +142,7 @@ Canon PR owns the field name; issue-core owns the mapping authority.
Recommended v1:
1. **Local SQLite** table `work_record_issue_map` (even when primary CRUD
backend is Gitea) — mapping is fleet bookkeeping, not a Gitea concept.
backend is Forgejo) — mapping is fleet bookkeeping, not a Forgejo concept.
2. **Issue.sync_metadata.mapping** (or top-level) echo for convenience when
the issue is loaded:
```json
@ -154,7 +154,7 @@ Recommended v1:
}
}
```
3. Optional Gitea label / body footer for human visibility in the tracker UI
3. Optional Forgejo label / body footer for human visibility in the tracker UI
(non-authoritative).
### API / CLI (sketch only)
@ -255,7 +255,7 @@ increment. Until enabled, connector load is zero beyond idle process cost.
documenting multi-tracker projection is future work.
- **SQLite-only offline:** mapping table lives with local DB; sync of
issues and mappings to remote is coordinated (mapping rows are not
pushed as Gitea native objects).
pushed as Forgejo native objects).
## Implementation sketch (later workplan)