# Architecture

J4Agent is one DSH plugin with two internal modules. A J4Agent Project is exactly one DSH Workspace, with one workspace-local fact source.

## Mini Jira

Mini Jira owns Project, Work Item, workflow, binding, relation, collaboration, delivery and verification facts. SQLite is private infrastructure behind the `ProjectWorkReader` and `ProjectWorkCommands` ports.

## Task Graph

Task Graph reads Mini Jira Work Items and dependency facts. It derives task state, Ready Set and diagnostics without creating a second Task store. Dependency writes use graph revision compare-and-swap and reject cycles.

## Integration surfaces

The canonical Host surface is:

- `j4agentProjectWorkspace`: idempotently initializes a canonical workspace path and returns its Project Work, Task Graph, Activity, Journey and Overview handles
- `j4agentTaskGraph`, `j4agentTaskGraphReader`, `j4agentTaskGraphCommands`

Legacy `j4agentProjectWork*` services are registered only when an explicit legacy `databasePath` is configured. New Workforce integration must use `j4agentProjectWorkspace`.

The model runtime receives only:

- `j4agent_task_graph_read`
- `j4agent_task_graph_dependency`
- `j4agent_project_initialize_current`

The browser uses a loopback RPC projection and passes only a `workspaceId`; the Host resolves the path through DSH's Workspace Registry. Another Host plugin may pass an absolute workspace path directly to `ensureProject`. Neither surface can choose the SQLite path or local Actor identity.

## Skill capability contract

J4Agent registers `j4agent-development` as a global, model-invocable Runtime Skill only when the Host exposes the DSH Skill Registry. Skill consumption belongs to the Agent Preset scope: J4Agent neither enables root `tool-skill` nor forks or mutates DSH Presets. The compatibility projection examines only live Agents in the requested Workspace, using the Agent's actual scope to query the `skill` Tool and J4Agent Skill catalog. It is ephemeral runtime state, is not written to Mini Jira, and never exposes the Workspace path to the browser.

The projection reports `ready`, `unavailable`, or `unknown`. `ready` is an observed capability result, not a claim that a model has already loaded the Skill; `unknown` is returned when the catalog cannot be observed completely. DSH `0.1.2-alpha.1` adds a cold Session catalog for human-invocable Skills; the model-only J4Agent Skill intentionally does not rely on that API. A future model-catalog observation may only upgrade this runtime projection and must not change J4Agent's fact model.

## Ownership boundary

J4Agent owns workspace-local project-management facts and graph consistency. DSH owns Workspace identity, providers, credentials, model execution, Tools, Skills, Sessions and runtime approval. Workforce consumes the same DSH Workspace identity and owns durable Agent organization and work execution coordination. J4Agent does not schedule, claim or spawn Agents.