tegwick 058b1b96f6

CI Smoke / host-smoke (push) Successful in 0s

Details

CI Smoke / container-smoke (push) Successful in 3s

Details

docs: align INTENT with work-record framework; propose ISSUE-WP-0005

Rewrite INTENT for UUIDv7+canonical identity, file-first topology, dual
lifecycles, intake+promotion findings path, and shipped vs target connector
surface. Add ISSUE-WP-0005 to implement mapping/store/CLI and close SCOPE
gaps; mark alignment-review remediation done.

2026-07-22 00:03:40 +02:00

10 KiB

Raw Blame History

INTENT — issue-core

Why it exists

The Coulomb org coordinates work through work records: identified, lifecycle-bearing artefacts authored as repo files (ADR-001), indexed by state-hub, under a closed kind registry (workplan, task, intake, decision, engagement, register-entry). That framework is defined in 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 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.

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 tracker issues — and (target) a durable mapping between:

Side	Identity
Internal work record	UUIDv7 (bookkeeping / mapping key) + canonical name for humans and agents (`ISSUE-WP-0005-T01`, …)
External issue	`(backend, external_id)` (+ URL)

Without a connector layer, external-tracker access fragments across per-repo API clients, ad hoc gh/glab/curl, agent-local integrations, and SaaS calls with no stable back-reference to the work record.

Honest history (pivot, 2026-07-20)

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).

Architecture draft §4.2 and the work-record types standard (CUST-WP-0060) retargeted purpose: connector, not origin. Capability (CRUD, backends, REST, backend-to-backend sync) stays; product north star is projection and mapping at the boundary.

What it is

A connector framework to external issue-tracking systems, with a pluggable-backend architecture. Issue-core is not part of the internal execution loop.

Shipped today

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.
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 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).

Target connector (stage-3 work-record architecture)

Mapping store: durable work-record UUIDv7 ↔ (backend, external_id), resolvable also by canonical work-record id; design in docs/uuid-external-id-mapping.md.
Project / link CLI and API: project an existing work record outward, or link an existing external issue; idempotent on active mapping.
Boundary sync (when enabled): optional two-way, transclusion-like sync at the boundary for fields needed by external collab. Zero load when no mapping/integration is configured.
Extend TaskSpec with optional work_record_uuid (and kind/id denorm); do not overload triggering_event_id (activity lineage only).
Optional work-record file back-reference (canon-owned field names), mirroring hub state_hub_*_id write-back patterns.

Until an external integration is switched on for a given workflow, the connector must add no coordination load to the internal loop.

What it is NOT

Not the origin of work records. Work records originate as repo files (or schema-valid blocks in context) per ADR-001 and the work-record types standard. issue-core does not create workplans, tasks, intake items, decisions, engagements, or register entries as fleet artefacts.
Not a work-record kind. Tracker issues are not registered in work-record-types. Unmapped backend issues sit outside the work-record spine; they are external artefacts for tracker UI collaboration until mapped to a work-record UUID.
Not the internal execution / coordination loop. Humans and agents claim and execute on work records (harness / NATS / activity-core as feeds). Fleet orientation is state-hub views over indexed files — not Forgejo issue lists. (Avoid calling this “intake” when you mean claim/execute; intake is a work-record kind for sparks/findings.)
Not the default home for automation findings. Internal findings belong as kind: intake (then promotion to task / workplan / decision / engagement). They must not silently become Forgejo issues via IssueSink. Emitter policy: activity-core ACTIVITY-WP-0022 (from ISSUE-WP-0004-T05 / CUST-WP-0060).
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.
Not a project manager, spawn audit trail, event bus, notification system, or workflow engine. Plans and dependencies are workplan tooling; spawn audit stays with emitters; NATS/hub own inter-service events; notifications and approval chains live elsewhere. Tracker state machine stays small (open / in_progress / blocked / closed).

Boundary sync discipline

Fleet work-record status (e.g. task wait → todo → progress → done | cancel) and tracker IssueState (open / in_progress / blocked / closed) are distinct vocabularies. They must not be merged casually.

Outward / inward projection uses explicit mapping rules.
Inward changes never silently mutate ADR-001 work-record files without a defined writer (see mapping design open questions).
Backend↔backend CLI sync is orthogonal to work-record boundary sync.

How it fits

  Repo files (ADR-001 / work-record kinds)     External collaboration
  workplan · task · intake · decision ·        Counterparty, OSS, Jira, …
  engagement · register-entry
           │
           │ fix-consistency: register, UUIDv7 write-back
           v
  +------------------+
  |  state-hub       |   read model + generated views  (not mapping authority)
  +------------------+
           │
           │ optional project / link when a tracker is switched on
           v
  +------------------+     UUIDv7 (+ canonical id)     +------------------+
  |  work-record     | <---- mapping (target) ------> |  issue-core      |
  |  source (+ opt.  |     ↔ (backend, external_id)   |  (connector)     |
  |  back-ref)       |                                 +--------+---------+
  +------------------+                                          |
                                                      +---------+----------+
                                                      |  Backend router    |
                                                      +---+------+------+--+
                                                          |      |      |
                                                          v      v      v
                                                     Gitea/  SQLite  GitHub
                                                     Forgejo  cache   (planned)

Primary fleet path (coordination):

Author or promote a work record in a repo file (kind from the closed registry; findings enter as intake, then promote).
fix-consistency indexes the record and write-backs UUIDv7.
Claim / execute against the work record (and hub views).
Optionally, issue-core projects or links the record to an external tracker and records the mapping (target).

Secondary path (direct tracker use):

Humans/agents use CLI/REST when deliberately operating on a backend (tracker admin, pure external collab).
Authenticated POST /issues/ only when the product decision is “create an external issue,” not “spawn fleet work.”
Unmapped issues remain outside the work-record spine.

Downstream:

Backend native UIs for external collaboration.
state-hub for fleet lifecycle of work records, not of every issue-core row.

Success looks like

External trackers usable through one CLI/API without per-platform clients.
When a work record is projected, UUIDv7 ↔ external-id mapping is durable and resolvable by canonical name (once implemented).
Fleet status and tracker state stay cleanly separated under explicit rules.
Internal automation does not open Forgejo issues for findings that belong as intake / promoted work records.
Unmapped tracker issues are not mistaken for fleet work records.
With no integration switched on, the connector adds no load to the internal loop.
Offline SQLite backend sync still works for tracker data when connectivity returns.

10 KiB Raw Blame History