diff --git a/SCOPE.md b/SCOPE.md index d6a96ca..834a1d2 100644 --- a/SCOPE.md +++ b/SCOPE.md @@ -84,18 +84,22 @@ Auth: shared secret `ISSUE_CORE_API_KEY` via `Authorization: Bearer …` or | Method | Path | Purpose | | --- | --- | --- | | `GET` | `/healthz` | Liveness | -| `POST` | `/issues/` | Create issue from **TaskSpec** (intentional external emit) | +| `POST` | `/issues/` | Create issue from **TaskSpec**; optional `work_record_uuid` upserts mapping (idempotent) | | `GET` | `/issues/` | List (filter: state, label, limit) | | `GET` | `/issues/{issue_id}` | Get one (id or numeric fallback) | | `PATCH` | `/issues/{issue_id}` | Claim / update state and assignee | +No dedicated `GET/POST /mappings/` routes yet — use CLI `project` / `map`, or +optional fields on `POST /issues/`. + **Routing today:** single **default backend** from CLI config. `target_repo` is stored in `sync_metadata.ingestion` and labels (`repo:…`); it does **not** yet select a per-repo backend. **Ingestion metadata stored on create:** `target_repo`, `source_type`, `source_id`, `triggering_event_id`, `activity_definition_id`, `ingested_at`, -optional `due_at` derived from `due_in_days`. +optional `due_at` derived from `due_in_days`. When `work_record_uuid` is set, +also `sync_metadata.mapping` and a row in `mappings.db`. ### 1.6 Synchronization (CLI) @@ -112,7 +116,8 @@ optional `due_at` derived from `due_in_days`. | `docs/argocd-gitops.md` | Operator runbook for that deploy | | `docs/package-release.md` | Release notes for packaging | | `registry/` + `CAPABILITY-issue-tracking.yaml` | Reuse-surface / capability federation metadata | -| Tests | `tests/` unit coverage for models, CLI, backends, API ingest/query | +| Tests | `tests/` unit coverage for models, CLI, backends, API ingest/query, mapping | +| Policy docs | `docs/boundary-sync-and-status-mapping.md`, `docs/uuid-external-id-mapping.md` | | Examples | `examples/agents/` programmatic patterns | ### 1.8 What is *not* shipped in the runtime (despite docs/plans) @@ -210,7 +215,7 @@ only. Emitters record who/what spawned an external issue (e.g. activity-core `task_spawn_log`). issue-core stores the issue plus traceability fields -(`triggering_event_id` today; work-record UUID when mapping lands). +(`triggering_event_id`; optional `work_record_uuid` + mapping row). ### 3.6 Event bus, notifications, workflow engine, IdP, UI @@ -233,17 +238,17 @@ Emitters record who/what spawned an external issue (e.g. activity-core | Author / promote work record | Repo files + tools (ADR-001 / work-record canon) | | Index + UUID write-back | state-hub `fix-consistency` | | Claim / execute | Humans, agents, harness on work records | -| Optional external projection | **issue-core** (CRUD today; mapping when implemented) | +| Optional external projection | **issue-core** (CRUD + mapping store + `project`/`map` CLI) | ### 4.2 Clients of this repo | Client | Transport | Role today | | --- | --- | --- | -| Human / agent shell | CLI | Direct tracker admin and ops | -| Library consumers | Python API | Same backends without shell | +| Human / agent shell | CLI | Tracker admin; `project` / `map` for work-record links | +| Library consumers | Python API + `MappingService` | Same backends + mapping store without shell | | Workers (e.g. harness) | REST GET/PATCH | List / claim / close external issues when in the loop | -| activity-core IssueSink | REST POST | **Optional, intentional** external issues only — not default for internal findings | -| Future mapping clients | REST/CLI TBD | Project/link work-record UUID ↔ external id | +| activity-core IssueSink | REST POST | **Optional, intentional** external issues only — not default for internal findings; may pass `work_record_uuid` | +| Mapping-aware emitters | CLI or POST `/issues/` with UUID | Project/link work-record UUID ↔ external id | ### 4.3 TaskSpec contract (`POST /issues/`) @@ -301,14 +306,14 @@ Do not message ops-warden for API keys; do not commit secrets. ``` issue_core/ - core/ # models, IssueBackend ABC, factory + core/ # models, IssueBackend ABC, factory, MappingService backends/ - local/ # SQLite + local/ # SQLite issue store gitea/ # Gitea/Forgejo REST - cli/ # Click: issue, backend, sync, serve + cli/ # Click: issue, project, map, backend, sync, serve api/ # FastAPI: ingest + query (+ auth, schemas) tests/ -docs/ # gitops, nats design, mapping design, release +docs/ # gitops, nats stub, mapping design, boundary-sync policy k8s/railiance/ # deploy manifests workplans/ # ADR-001 work items for this repo ``` @@ -319,7 +324,8 @@ workplans/ # ADR-001 work items for this repo | CLI | Click | | HTTP | FastAPI + Pydantic v2 + uvicorn (`[api]` extra) | | HTTP client (Gitea) | requests | -| Local store | SQLite | +| Issue store (local) | SQLite (`issues.db`) | +| Mapping store | SQLite (`mappings.db`, separate file) | | Tests | pytest | --- @@ -327,15 +333,16 @@ workplans/ # ADR-001 work items for this repo ## 6. See also - `INTENT.md` — why the connector role exists (work-record-aligned rewrite 2026-07-22) -- `README.md` — operator quick start -- `ROADMAP.md` — phased growth (auto-config, mapping implementation, backends) -- `docs/uuid-external-id-mapping.md` — mapping design (not implemented) +- `README.md` — operator quick start (includes `project` / `map`) +- `ROADMAP.md` — phased growth (auto-config, further backends, inward sync) +- `docs/uuid-external-id-mapping.md` — mapping design (store/CLI implemented; REST `/mappings/` not yet) +- `docs/boundary-sync-and-status-mapping.md` — dual-lifecycle outward policy (v1) - `docs/intent-work-record-alignment-review.md` — INTENT vs work-record audit - `docs/nats-task-ingestion.md` — NATS design stub - `docs/argocd-gitops.md` — railiance01 deploy - `AGENT_INTEGRATION.md` — library patterns for tracker ops - `workplans/ISSUE-WP-0004-align-with-work-record-canon.md` — initial framing pivot -- `workplans/ISSUE-WP-0005-connector-alignment-implementation.md` — implement mapping + close scope gaps +- `workplans/ISSUE-WP-0005-connector-alignment-implementation.md` — **finished**: mapping + scope gaps - `the-custodian/canon/standards/work-record-types_v0.1.md` — work-record kinds (issue-core issues = external projections only) - `the-custodian/research/WorkOrchestrationArchitectureDraft.md` §4.2