feat: rename to issue-core and add task ingestion endpoint

Renames the package, distribution, CLI alias, Makefile targets, and
working directory from issue-facade to issue-core, signalling its
role as the authoritative task lifecycle manager for the Coulomb org
(peer to activity-core, rules-core, project-core).

Adds POST /issues/ ingestion endpoint for activity-core's IssueSink,
under a new optional [api] extra. The endpoint is served by `issue
serve`, authenticates via the ISSUE_CORE_API_KEY env var (Bearer or
X-API-Key header), and routes the TaskSpec payload to the configured
default backend with full traceability metadata embedded in
sync_metadata.

- T01: Python package issue_tracker -> issue_core, dir rename
- T02: registered in state hub under custodian domain
- T03: INTENT.md (what it is, what it isn't, how it fits)
- T04: SCOPE.md (in/out-of-scope, integration boundaries)
- T05: POST /issues/ via FastAPI + Uvicorn, 9 unit tests
- T06: docs/nats-task-ingestion.md design stub

Closes ISSC-WP-0001.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
2026-05-17 05:16:27 +02:00
parent 99ea1fbc45
commit b605d970e3
38 changed files with 1324 additions and 361 deletions

View File

@@ -1,10 +1,10 @@
# Issue Facade - Agent Coordination via Issue Tracking
# Issue Core - Agent Coordination via Issue Tracking
**A unified interface for autonomous coding agents to coordinate project implementation through issue tracking systems.**
## Purpose
The **Issue Facade** provides a standardized abstraction layer for coding agents to interact with issue tracking backends (Gitea, GitHub, GitLab, local SQLite). Instead of each agent implementing platform-specific API integrations, they use one consistent interface that works across all backends.
The **Issue Core** provides a standardized abstraction layer for coding agents to interact with issue tracking backends (Gitea, GitHub, GitLab, local SQLite). Instead of each agent implementing platform-specific API integrations, they use one consistent interface that works across all backends.
### Why Issue Tracking for Agent Coordination?
@@ -40,10 +40,25 @@ Issue tracking provides natural coordination primitives for multi-agent software
### Installation
```bash
cd capabilities/issue-facade
pip install -e .
cd capabilities/issue-core
pip install -e . # CLI only
pip install -e ".[api]" # CLI + REST ingestion server
```
### REST Ingestion Server
issue-core exposes `POST /issues/` for upstream emitters (primarily
activity-core's `IssueSink`). Launch with:
```bash
export ISSUE_CORE_API_KEY="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"
issue serve --host 0.0.0.0 --port 8765
```
Clients authenticate with `Authorization: Bearer <key>` or `X-API-Key: <key>`.
See `SCOPE.md` "TaskSpec payload" for the request schema, or visit
`http://<host>:<port>/docs` once the server is running for live OpenAPI docs.
### Configuration (One-Time Setup)
**For Gitea-backed projects:**
@@ -67,7 +82,7 @@ issue backend test myproject
```bash
issue backend add local-work local
# Prompts for: database path (.issue-facade/issues.db)
# Prompts for: database path (.issue-core/issues.db)
issue backend set-default local-work
```
@@ -108,8 +123,8 @@ issue close 42 --comment="Ready for review"
Quick example:
```python
from issue_tracker.backends.gitea import GiteaBackend
from issue_tracker.core.interfaces import IssueFilter
from issue_core.backends.gitea import GiteaBackend
from issue_core.core.interfaces import IssueFilter
# Initialize
backend = GiteaBackend()
@@ -281,20 +296,20 @@ make test-unit
```bash
# Run linter
make issue-facade-lint
make issue-core-lint
# Format code
black issue_tracker/ tests/
black issue_core/ tests/
# Type check
mypy issue_tracker/
mypy issue_core/
```
### Project Structure
```
issue-facade/
├── issue_tracker/
issue-core/
├── issue_core/
│ ├── core/ # Domain models and interfaces
│ │ ├── models.py # Issue, Label, User, etc.
│ │ └── interfaces.py # IssueBackend, SyncableBackend
@@ -351,7 +366,7 @@ issue-facade/
## Comparison with Platform CLIs
| Feature | Issue Facade | gh (GitHub) | glab (GitLab) |
| Feature | Issue Core | gh (GitHub) | glab (GitLab) |
|---------|--------------|-------------|---------------|
| Multi-backend support | ✅ Yes | ❌ GitHub only | ❌ GitLab only |
| Offline capability | ✅ Local SQLite | ❌ No | ❌ No |
@@ -362,7 +377,7 @@ issue-facade/
## Contributing
The Issue Facade is designed to be extensible:
The Issue Core is designed to be extensible:
**To add a new backend:**
1. Implement the `IssueBackend` interface (see `core/interfaces.py`)