docs: align issue-core with work-record connector role (ISSUE-WP-0004)
Retarget INTENT, SCOPE, README, ROADMAP, and agent docs from "task landing zone" to external-tracker connector per work-record canon and architecture draft §4.2. Add UUID↔external-id mapping design; mark ISSUE-WP-0004 finished and cross-file activity-core ACTIVITY-WP-0022 for IssueSink policy.
This commit is contained in:
parent
5e556028ab
commit
d60175c354
9 changed files with 760 additions and 226 deletions
156
SCOPE.md
156
SCOPE.md
|
|
@ -3,12 +3,18 @@
|
|||
Concrete in-scope / out-of-scope decisions for issue-core. Paired with `INTENT.md`,
|
||||
which explains *why*; this file states *what* and *what not*.
|
||||
|
||||
**Fleet framing (2026-07-20):** issue-core is a **connector** to external
|
||||
issue trackers and the home of the **UUID ↔ external-id mapping** concept.
|
||||
Work records originate as repo files (ADR-001 / work-record canon). See
|
||||
`INTENT.md` and `docs/uuid-external-id-mapping.md`.
|
||||
|
||||
## In scope
|
||||
|
||||
### Task CRUD across backends
|
||||
### External-issue CRUD across backends
|
||||
|
||||
- **Create** issues with title, description, labels, priority, type, milestone,
|
||||
assignee, due date.
|
||||
assignee, due date — when a tracker projection or direct tracker use is
|
||||
intentional.
|
||||
- **Read** individual issues and lists with filters (state, labels, priority,
|
||||
assignee, text search).
|
||||
- **Update** any mutable field on existing issues.
|
||||
|
|
@ -25,8 +31,8 @@ which explains *why*; this file states *what* and *what not*.
|
|||
|
||||
### Backends shipped today
|
||||
|
||||
- **Local SQLite** — offline source of truth.
|
||||
- **Gitea** — REST API integration.
|
||||
- **Local SQLite** — offline cache / source of truth for disconnected work.
|
||||
- **Gitea** — REST API integration (Forgejo-compatible in deployment).
|
||||
|
||||
### Backends planned
|
||||
|
||||
|
|
@ -34,15 +40,34 @@ which explains *why*; this file states *what* and *what not*.
|
|||
- **GitLab** — Issues.
|
||||
- **JIRA** — issues with story-points.
|
||||
|
||||
### Ingestion surfaces
|
||||
### UUID ↔ external-id mapping (target shape)
|
||||
|
||||
- **CLI** (`issue` / `issue-core`) for humans and agents on a shell.
|
||||
- **REST** (`POST /issues/`) for automation — primarily activity-core's
|
||||
`IssueSink`, but open to any well-authenticated client.
|
||||
- **REST worker surface** (`GET/PATCH /issues/`) for executors (agent-harness):
|
||||
list open issues by label/state, claim (`in_progress` + assignee), close.
|
||||
- **NATS subscriber** (design stub only — implementation deferred until
|
||||
activity-core migrates from REST to NATS, see `docs/nats-task-ingestion.md`).
|
||||
Primary *fleet* responsibility of issue-core going forward — design only in
|
||||
this repo until stage-3 work-record architecture lands; see
|
||||
`docs/uuid-external-id-mapping.md`.
|
||||
|
||||
| Concept | Meaning |
|
||||
| --- | --- |
|
||||
| Internal id | Work-record UUID (UUIDv7, hub-assigned / written back to source file as `state_hub_*_id`-style fields) |
|
||||
| External id | Backend issue id / number + backend identity (`gitea`, `github`, …) |
|
||||
| Mapping row | Durable association: which work record projects to which external issue |
|
||||
| Direction | Create projection outward; optional two-way sync of status/comments at the boundary |
|
||||
|
||||
Named here so scope and design agree before implementation.
|
||||
|
||||
### Operator / automation surfaces
|
||||
|
||||
- **CLI** (`issue` / `issue-core`) for humans and agents on a shell — direct
|
||||
backend use.
|
||||
- **REST** (`POST /issues/`) for **intentional** external-issue creation by
|
||||
authenticated clients. Remains useful; is **not** the primary fleet path for
|
||||
originating work.
|
||||
- **REST worker surface** (`GET/PATCH /issues/`) for executors that operate on
|
||||
external issues when a tracker is in the loop: list, claim
|
||||
(`in_progress` + assignee), close.
|
||||
- **NATS subscriber** (design stub only — see `docs/nats-task-ingestion.md`).
|
||||
Any NATS path must respect the same rule: external projection only when
|
||||
explicitly configured, never silent origin of fleet work.
|
||||
|
||||
### Synchronization
|
||||
|
||||
|
|
@ -53,29 +78,47 @@ which explains *why*; this file states *what* and *what not*.
|
|||
|
||||
### State Hub integration
|
||||
|
||||
- Registered as a custodian-domain repo.
|
||||
- Emits `add_progress_event()` calls on significant task lifecycle moments.
|
||||
- Surfaces blocked tasks via the hub's `list_blocked_tasks()` view.
|
||||
- Registered as a custodian-domain / infotech repo.
|
||||
- May emit `add_progress_event()` on significant *connector* lifecycle moments
|
||||
(e.g. projection created, mapping updated) when wired.
|
||||
- Does **not** replace work-record indexing; state-hub remains the fleet read
|
||||
model for work records.
|
||||
|
||||
## Out of scope
|
||||
|
||||
### Origin of fleet work
|
||||
|
||||
Creating workplans, tasks, intake items, decisions, or engagements. Those
|
||||
originate as repo files (or schema-valid blocks in context) and are indexed by
|
||||
`fix-consistency` / state-hub. issue-core may **project** an existing work
|
||||
record to a tracker; it does not birth the work record.
|
||||
|
||||
### Default sink for internal automation findings
|
||||
|
||||
activity-core (and similar) must not treat `POST /issues/` as the always-on
|
||||
default for every matched rule. That product decision lives in the emitter;
|
||||
issue-core will keep accepting authenticated POSTs but will not redefine itself
|
||||
as the landing zone. Follow-up: activity-core IssueSink policy (filed from
|
||||
ISSUE-WP-0004-T05).
|
||||
|
||||
### Project management
|
||||
|
||||
Phases, campaigns, milestones-as-plans, dependency graphs between tasks,
|
||||
gantt-style scheduling, OKR linkage. **That is `project-core` (planned).**
|
||||
issue-core operates on individual tasks. A milestone field exists for
|
||||
gantt-style scheduling, OKR linkage. **That is workplan / project tooling.**
|
||||
issue-core operates on individual external issues. A milestone field exists for
|
||||
flat grouping, not for multi-stage plans.
|
||||
|
||||
### Spawn audit trail
|
||||
|
||||
When activity-core's IssueSink files a task here, the *spawn event* (who fired
|
||||
the rule, against which activity definition, on which triggering event) is
|
||||
recorded in **activity-core's `task_spawn_log`**. issue-core stores the resulting
|
||||
task and a back-reference (`triggering_event_id`) — nothing more.
|
||||
When an emitter files an issue here, the *spawn event* (who fired, which rule,
|
||||
which triggering event) is recorded by the **emitter** (e.g. activity-core's
|
||||
`task_spawn_log`). issue-core stores the resulting issue and traceability
|
||||
fields (`triggering_event_id` today; work-record UUID in the mapping design) —
|
||||
nothing more.
|
||||
|
||||
Symmetrically: issue-core does not push status updates back to activity-core.
|
||||
Lifecycle updates stay here; activity-core does not care what happens to a task
|
||||
it spawned.
|
||||
Symmetrically: issue-core does not push fleet work-record status updates back
|
||||
to activity-core. Lifecycle of external issues stays here; lifecycle of work
|
||||
records stays in repo files + hub.
|
||||
|
||||
### Event bus / message broker
|
||||
|
||||
|
|
@ -86,8 +129,7 @@ between other services.
|
|||
### Notifications
|
||||
|
||||
Telling a human "your task changed" is the job of the relevant UI, digest,
|
||||
chatbot, or notification service — not issue-core. issue-core emits progress
|
||||
events; downstream consumers decide what to do with them.
|
||||
chatbot, or notification service — not issue-core.
|
||||
|
||||
### Workflow / approval engine
|
||||
|
||||
|
|
@ -104,28 +146,40 @@ itself is not on the roadmap.
|
|||
### Identity / access management
|
||||
|
||||
Authentication relies on backend credentials (Gitea tokens, GitHub tokens) and
|
||||
on a service-level API key for the REST ingestion endpoint. issue-core is not a
|
||||
on a service-level API key for the REST endpoint. issue-core is not a
|
||||
user directory.
|
||||
|
||||
## Integration boundaries
|
||||
|
||||
### Upstream emitters
|
||||
### Fleet primary path (work records)
|
||||
|
||||
| Emitter | Transport | Payload | Notes |
|
||||
|----------------|----------------------|--------------------------|-------|
|
||||
| Human CLI | local process call | CLI args | The classic path. |
|
||||
| activity-core | REST `POST /issues/` | `TaskSpec` (see below) | Primary integration; planned NATS migration. |
|
||||
| Agents | REST or CLI | `TaskSpec` or CLI args | Same surfaces as humans/automation. |
|
||||
| Step | Owner | Notes |
|
||||
| --- | --- | --- |
|
||||
| Author / promote work record | Repo files + tools | ADR-001 / work-record canon |
|
||||
| Index + UUID write-back | state-hub `fix-consistency` | Hub is read model |
|
||||
| Claim / execute | Humans, agents, harness | On work records, not on Forgejo by default |
|
||||
| Optional external projection | **issue-core** | Mapping table + backend CRUD |
|
||||
|
||||
### Surfaces into issue-core
|
||||
|
||||
| Client | Transport | Payload | Role |
|
||||
| --- | --- | --- | --- |
|
||||
| Human CLI | local process | CLI args | Direct tracker use / admin |
|
||||
| Agents | REST or CLI | issue fields or CLI args | Tracker ops when in the loop |
|
||||
| activity-core IssueSink | REST `POST /issues/` | `TaskSpec` | **Optional, intentional** external issues only — not default for internal findings |
|
||||
| Future mapping API | REST/CLI (TBD) | work_record_uuid + project request | Primary fleet connector path once designed |
|
||||
|
||||
### Downstream consumers
|
||||
|
||||
| Consumer | Mechanism | Notes |
|
||||
|----------------------|------------------------------------|-------|
|
||||
| Humans / agents | `issue list`, web UI, backend UI | Standard task pickup. |
|
||||
| state-hub | `add_progress_event()` calls | Lifecycle visibility. |
|
||||
| Backend remote (e.g. Gitea) | direct backend write | Pass-through for the storage layer. |
|
||||
| Consumer | Mechanism | Notes |
|
||||
| --- | --- | --- |
|
||||
| Humans / external collab | backend UI, `issue list` | Third-party tracker collaboration |
|
||||
| state-hub | work-record index; optional progress events | Fleet orientation |
|
||||
| Backend remote (e.g. Gitea) | direct backend write | Storage / projection layer |
|
||||
|
||||
### `TaskSpec` payload (from activity-core's IssueSink)
|
||||
### `TaskSpec` payload (activity-core IssueSink — retained contract)
|
||||
|
||||
Still accepted for backward compatibility and intentional emits:
|
||||
|
||||
```json
|
||||
{
|
||||
|
|
@ -148,6 +202,12 @@ emissions that do not have a concrete event row may send a stable source key
|
|||
such as `scheduled`; issue-core stores the value verbatim in ingestion
|
||||
metadata for traceability.
|
||||
|
||||
**Relation to mapping design:** `triggering_event_id` is emitter-side
|
||||
traceability, not a work-record UUID. The mapping surface will add an explicit
|
||||
work-record identity field (and durable mapping rows). See
|
||||
`docs/uuid-external-id-mapping.md` — extend rather than overload
|
||||
`triggering_event_id`.
|
||||
|
||||
### `POST /issues/` response
|
||||
|
||||
```json
|
||||
|
|
@ -158,15 +218,17 @@ metadata for traceability.
|
|||
}
|
||||
```
|
||||
|
||||
The `issue_id` is the canonical back-reference activity-core stores in its
|
||||
`task_spawn_log`. It is owned and managed by issue-core; activity-core does not
|
||||
mutate it.
|
||||
The `issue_id` is the external-issue back-reference an intentional emitter may
|
||||
store (e.g. activity-core `task_spawn_log`). It is owned by issue-core's
|
||||
backend; it is not a work-record UUID.
|
||||
|
||||
## See also
|
||||
|
||||
- `INTENT.md` — why issue-core exists and how it fits in the Coulomb org.
|
||||
- `INTENT.md` — why issue-core exists and the connector pivot.
|
||||
- `ROADMAP.md` — feature trajectory.
|
||||
- `workplans/ISSC-WP-0001-rename-and-task-ingestion.md` — current rename +
|
||||
ingestion workplan.
|
||||
- activity-core `docs/adr/adr-001-event-bridge-architecture.md` — the upstream
|
||||
side of the IssueSink contract.
|
||||
- `docs/uuid-external-id-mapping.md` — mapping design (not yet implemented).
|
||||
- `workplans/ISSUE-WP-0004-align-with-work-record-canon.md` — alignment work.
|
||||
- `the-custodian/canon/standards/work-record-types_v0.1.md` — work-record kinds;
|
||||
task kind notes that issue-core issues are external projections only.
|
||||
- activity-core `docs/adr/adr-001-event-bridge-architecture.md` — IssueSink
|
||||
contract (emitter side; policy follow-up separate).
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue