Metadata-Version: 2.5
Name: okto-pulse
Version: 0.3.3
Summary: Okto Pulse — spec-driven project management with AI agents via MCP. Local-first, single command setup.
Project-URL: Homepage, https://github.com/OktoLabsAI/okto-pulse
Project-URL: Documentation, https://github.com/OktoLabsAI/okto-pulse#readme
Project-URL: Repository, https://github.com/OktoLabsAI/okto-pulse
Project-URL: Issues, https://github.com/OktoLabsAI/okto-pulse/issues
Project-URL: Changelog, https://github.com/OktoLabsAI/okto-pulse/blob/main/CHANGELOG.md
Author-email: Okto Labs <dev@oktolabs.ai>
License: Elastic-2.0
License-File: LICENSE
Keywords: ai-agents,claude,cursor,developer-tools,kanban,mcp,project-management,spec-driven,windsurf
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Scheduling
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.11
Requires-Dist: aiosqlite<1.0.0,>=0.19.0
Requires-Dist: anyio<5.0.0,>=4.0.0
Requires-Dist: apscheduler<4.0.0,>=3.10.0
Requires-Dist: authlib<1.7.0,>=1.6.5
Requires-Dist: chardet<6.0.0,>=3.0.2
Requires-Dist: fastapi!=0.137.0,<1.0.0,>=0.109.0
Requires-Dist: fastmcp<3.0.0,>=2.0.0
Requires-Dist: filelock<4.0.0,>=3.16.0
Requires-Dist: httpx<1.0.0,>=0.27.0
Requires-Dist: mcp<2.0.0,>=1.20.0
Requires-Dist: okto-grafx[accel]==0.0.7
Requires-Dist: okto-pulse-core<1.0.0,>=0.3.3
Requires-Dist: pydantic-settings<3.0.0,>=2.1.0
Requires-Dist: pydantic<2.14,>=2.12.0
Requires-Dist: python-multipart<1.0.0,>=0.0.6
Requires-Dist: requests<3.0.0,>=2.32.0
Requires-Dist: sentence-transformers<6.0.0,>=2.5.0
Requires-Dist: sqlalchemy[asyncio]==2.0.49
Requires-Dist: starlette<2.0.0,>=0.35.0
Requires-Dist: uvicorn[standard]<1.0.0,>=0.27.0
Requires-Dist: wsproto<2.0.0,>=1.2.0
Provides-Extra: dev
Requires-Dist: build<2.0.0,>=1.2.0; extra == 'dev'
Requires-Dist: pytest-asyncio<2.0.0,>=0.24.0; extra == 'dev'
Requires-Dist: pytest<10.0.0,>=8.0.0; extra == 'dev'
Requires-Dist: uv<1.0.0,>=0.8.0; extra == 'dev'
Description-Content-Type: text/markdown

# Okto Pulse

<div align="center">
  <h3><em>Spec-driven project management for AI-assisted development.</em></h3>
</div>

<p align="center">
  <strong>Okto Pulse turns ideas, refinements, specs, tasks, tests and bugs into a governed SDLC board that AI agents can operate through MCP.</strong>
</p>

<p align="center">
  <strong>Ship with AI. Stay in control.</strong>
</p>

<p align="center">
  <a href="https://pypi.org/project/okto-pulse/"><img src="https://img.shields.io/pypi/v/okto-pulse" alt="PyPI version"></a>
  <a href="https://pypi.org/project/okto-pulse/"><img src="https://img.shields.io/pypi/pyversions/okto-pulse" alt="Python versions"></a>
  <a href="./LICENSE"><img src="https://img.shields.io/badge/license-Elastic%202.0-blue" alt="License"></a>
  <a href="https://github.com/OktoLabsAI/okto-pulse-core"><img src="https://img.shields.io/badge/core-okto--pulse--core-6f42c1" alt="Core repository"></a>
</p>

---

## Table of Contents

- [What is Okto Pulse?](#what-is-okto-pulse)
- [Platform Surface](#platform-surface)
- [Get Started](#get-started)
- [Connect an AI Coding Agent](#connect-an-ai-coding-agent)
- [Token Usage](#token-usage)
- [Core Workflow](#core-workflow)
- [Governance Gates](#governance-gates)
- [Knowledge Graph](#knowledge-graph)
- [Architecture](#architecture)
- [CLI Reference](#cli-reference)
- [Run with Docker](#run-with-docker)
- [Data Storage](#data-storage)
- [From Source](#from-source)
- [Troubleshooting](#troubleshooting)
- [Release Notes](#release-notes)
- [License](#license)

**Reference documents**

| Document | Contents |
| --- | --- |
| [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) | Dependency owner matrix, adapter source map and the **port → adapter matrix** |
| [`docs/RELEASE-NOTES.md`](docs/RELEASE-NOTES.md) | Full changeset per version |
| [`docs/TOKEN-USAGE.md`](docs/TOKEN-USAGE.md) | Measured MCP context cost for agents |
| [`docs/kg-health.md`](docs/kg-health.md) | Knowledge Graph health signals and triage |
| [`docs/KG_SOURCE_NAVIGATION.md`](docs/KG_SOURCE_NAVIGATION.md) | Open owning artifacts from KG nodes and Global Discovery; provenance resolution, permissions and read-only API |
| [`docs/DIAGRAM_CANVAS_AND_LINEAGE_UI.md`](docs/DIAGRAM_CANVAS_AND_LINEAGE_UI.md) | Architecture canvas margins, explicit lineage connection handles, status colors and isolated browser validation |
| [`docs/GRAFX_V005_ADOPTION.md`](docs/GRAFX_V005_ADOPTION.md) | Grafx 0.0.5 adoption, optional capability boundary, Settings and validation checkpoint |
| [`docs/GRAFX_ADVANCED_ADOPTION_0_0_6.md`](docs/GRAFX_ADVANCED_ADOPTION_0_0_6.md) | Grafx 0.0.6 adoption: composed reads, ranked search, independent Global readers, history/provenance and analytics; API/configuration contracts and validation evidence |
| [`docs/GRAFX_RECOVERY_BATCHING.md`](docs/GRAFX_RECOVERY_BATCHING.md) | Bounded Global recovery writes, rollback/fencing guarantees and remaining batch opportunities |

## What is Okto Pulse?

Okto Pulse is a local-first SDLC workbench built for teams that use AI coding agents but still want traceability, quality gates and durable project memory.

Instead of sending an agent straight from a prompt to code, Okto Pulse keeps the work explicit:

```text
Stories -> Ideation -> Refinement -> Spec -> Sprint -> Tasks / Tests / Bugs
```

Every stage has structured artifacts, lineage, status transitions and validation rules. Agents can create and update those artifacts through MCP tools, while humans can inspect and steer the same work in the web UI.

## Platform Surface

Current 0.3.3 surface:

| Surface | Count |
| --- | ---: |
| Governance gates | 18 |
| Core MCP tools | 340 |
| Community-only MCP tools | 0 |
| MCP tools exposed by `okto-pulse serve` | 340 |

The community package materializes the full `okto-pulse-core` command catalog in
its FastMCP host. That means installed community runtimes expose the complete
core tool catalog while keeping the CLI, frontend and packaging layer separate
from the core engine. The MCP count is measured from the transport-neutral Core
catalog at implementation time;
Community adds operational resources and adapters, not extra community-only MCP
tools.

## Get Started

### 1. Install

```bash
pip install okto-pulse
```

Okto Pulse requires Python 3.11+.

> [!NOTE]
> On first run, Okto Pulse downloads the `all-MiniLM-L6-v2` sentence-transformers model into the Hugging Face cache. This powers semantic search in the Knowledge Graph. If the model cannot be downloaded, the app still starts in deterministic stub mode and the Settings view reports that semantic search is disabled.

### 2. Initialize a workspace

Run this inside the project directory where your coding agent will work:

```bash
okto-pulse init
```

This creates:

- the local data directory under `~/.okto-pulse/`
- a default board and agent
- a project-local `.mcp.json` that points your agent at the local MCP server

### 3. Start the app

```bash
okto-pulse serve
```

Default endpoints:

| Endpoint | URL |
| --- | --- |
| Web UI + API | `http://localhost:8100` |
| MCP server | `http://localhost:8101/mcp` |

Both listeners run in one Python process. This keeps the embedded graph database under a single writer while still exposing independent API/UI and MCP ports.

### 4. Open the UI

Go to `http://localhost:8100`, select the default board and start with either:

- a **Story**, when you want lightweight pre-ideation context grouped by topic
- an **Ideation**, when the feature or problem is already ready to be discussed

## Connect an AI Coding Agent

Most agent tools can discover the generated `.mcp.json` automatically when they run from the same directory.

Community keeps its local REST identity deliberately human-only. Authenticated
agent submissions use the Core MCP surface locally; a SaaS edition may inject
an agent-aware `AuthenticationPort` into the same edition-neutral REST
contract. Neither path makes Community acquire, clone, browse, probe or inspect
source code: the external agent checks access and capabilities in its own
environment and submits only the bounded result.

| Agent or tool | Setup |
| --- | --- |
| Claude Code | Run it from the directory that contains `.mcp.json`. |
| Claude Desktop | Copy the generated MCP server block into Claude Desktop settings. |
| Codex | In **Menu → Agents**, create an agent or regenerate its key, then click **Codex (CLI)** and run the copied command in your terminal. |
| Cursor | Add the MCP server URL in Cursor MCP settings. |
| VS Code | Copy the server block into `.vscode/mcp.json`. |
| Windsurf / Cline | Use the generated `.mcp.json` when supported. |

The **Codex (CLI)** button copies `codex mcp add okto-pulse --url "<Pulse MCP URL with agent key>"`,
using the runtime MCP address and the newly revealed API key. Install Codex CLI
first. After rotating the key, copy and run the new command, then restart the
Codex session; the old key stops working. Configuration copying is disabled when
the reveal-once key is hidden. Keep the copied command private: it contains the
key and can be saved in shell history and Codex's configuration. The command
configures a connection; board access still needs to be granted in Pulse.
See the [official Codex MCP documentation](https://developers.openai.com/codex/mcp/).

Generated shape:

```json
{
  "mcpServers": {
    "okto-pulse": {
      "url": "http://localhost:8101/mcp?api_key=dash_..."
    }
  }
}
```

If you change the MCP port, regenerate the file:

```bash
okto-pulse init --agents
```

## Token Usage

Connecting an agent over MCP has a fixed context cost (the tool catalogue) plus a variable cost
(tool responses). Response projections — `summary`, `detail`, `full` — let you trade detail for
tokens.

**→ [Measured token usage](docs/TOKEN-USAGE.md)** — fixed cost per connection, on-demand resources,
variable response cost and ballpark session profiles.

## Core Workflow

Okto Pulse is intentionally workflow-first. Each stage answers a different question.

| Stage | Purpose |
| --- | --- |
| **Stories** | Optional lightweight user-story inputs, grouped by topic, that can feed one or more ideations. |
| **Ideation** | Capture the problem, assess ambiguity and collect Q&A before committing to a solution path. |
| **Refinement** | Investigate code, constraints, prior decisions, mockups, architecture and knowledge entries. |
| **Spec** | Define acceptance criteria, functional requirements, business rules, API contracts, tests and decisions. |
| **Sprint** | Slice approved specs into reviewable implementation batches when the work is large. |
| **Tasks / Tests / Bugs** | Execute implementation with linked tests, bug evidence, validation and conclusions. |

The lineage graph keeps these relationships inspectable, including story-to-ideation and task-to-test/bug relationships.

## Governance Gates

Okto Pulse protects the workflow with checks that run on status transitions.

The platform currently has **17 named governance gates**:

| Gate family | Gates |
| --- | --- |
| Resource readiness | Resource readiness; resource-to-task coverage |
| Spec coverage | Scenario/test coverage; functional requirement/business rule coverage; technical requirement/task coverage; API contract/task coverage; active decision/task coverage |
| Validation and evaluation | Spec validation; spec qualitative evaluation; task validation |
| Execution quality | Task start/spec readiness; task conclusion; cognitive closeout; architecture-findings done; test evidence; bug test-first/traceability |
| Sprint health | Sprint closure/evaluation |

- Specs require coverage across acceptance criteria, functional requirements, business rules, API contracts, decisions and test scenarios.
- Tasks cannot start until the parent spec has the required scenario coverage.
- Tasks moving to `done` require a structured conclusion with completeness and drift assessment.
- Done transitions are also held while unresolved cognitive-consolidation items remain (cognitive closeout), and active architecture warnings block a spec or card from reaching `done` (architecture-findings gate). Both moved from defined to enforced in 0.2.3.
- Test cards require evidence before they can be marked as automated, passed or failed.
- Bug cards follow a test-first workflow and must remain traceable to the task and related test work.
- Validation gates can require independent review before specs or tasks are considered complete.

Board settings let teams tune thresholds without removing the traceability model.

## Knowledge Graph

Okto Pulse maintains an embedded per-board Knowledge Graph for durable project memory.

Agents use the graph to:

- find related prior decisions
- detect contradictions and superseded context
- reuse lessons from previous bugs
- query global discovery context across boards
- consolidate specs, bugs and implementation conclusions into searchable knowledge

Operational health is visible through:

- the in-product KG view
- MCP health tools
- dead-letter and queue metrics
- graph database runtime settings in the board settings panel

`GET /health` is a constant-time liveness endpoint: it performs no storage
scan and keeps the backward-compatible HTTP 200 and `status: "healthy"`
contract while the process can answer requests. Relational integrity is
available on the explicit, read-only `GET /health/integrity` diagnostic through
`integrity_status` and `findings.sprint_origin_integrity`; do not use that
storage-backed route as a recurring liveness probe. A missing sprint lineage
foreign key with clean data is `degraded`; an invalid lineage row or a probe
failure is `critical`. Direct SQL repair is unsupported; use application
workflows or a verified backup/restore procedure.

## Architecture

Okto Pulse ships as two packages: **`okto-pulse-core`** owns the SDLC domain, the governance gates
and the Knowledge Graph contracts as pure `Protocol` seams; **`okto-pulse`** (this package) owns
every concrete mechanism — SQLite, Okto Grafx, the filesystem, the scheduler, telemetry state,
the REST app and the MCP host.

Core never imports Community. Community fills the ports at startup, and an unfilled slot **fails
closed** rather than falling back to a silent default.

**→ [Architecture in full](docs/ARCHITECTURE.md)** — dependency owner matrix (AF-05/AF40),
registration flow, the adapter source map, and the **port → adapter matrix** showing which core
contract each of the 156 adapter modules implements.

## CLI Reference

| Command | Description |
| --- | --- |
| `okto-pulse init` | Initialize local data, seed the default board and generate `.mcp.json`. |
| `okto-pulse init --agents` | Regenerate MCP agent configuration. |
| `okto-pulse init --accept-terms` | Accept terms non-interactively. Also supported through `OKTO_PULSE_TERMS_ACCEPTED=1`. |
| `okto-pulse serve` | Start API/UI and MCP in one Python process. |
| `okto-pulse serve --api-port N --mcp-port M` | Override API/UI and MCP ports. |
| `okto-pulse status` | Show service status, database path, size and board counts. |
| `okto-pulse status --json` | Emit one status object; SQLite errors return exit 1 without an initialization hint. |
| `okto-pulse code-traceability requests <board_id>` | List persisted code-investigation requests. |
| `okto-pulse code-traceability receipts <board_id>` | List agent-attested execution receipts. |
| `okto-pulse code-traceability inspect <board_id> <kind> <record_id>` | Inspect one persisted request or receipt. |
| `okto-pulse code-traceability diagnose <board_id>` | Validate the persisted Code Traceability schema and board policy. |
| `okto-pulse metrics status [--window-days N]` | Show local metrics state and aggregates; N is 1–400, default 30. |
| `okto-pulse metrics enable-beacon --policy-version VERSION --yes` | Opt in to anonymous hourly aggregate metrics. |
| `okto-pulse metrics disable` | Turn metrics off. |
| `okto-pulse metrics export [--output PATH]` | Export local metrics as JSONL. |
| `okto-pulse metrics purge-local --yes` | Delete local metrics files after explicit confirmation. |
| `okto-pulse api-key [--handoff-file PATH]` | Atomically consume a reveal-once bootstrap API-key handoff. |
| `okto-pulse reset [-y]` | Delete SQLite, uploads and SQLite-owned board graph directories, then re-seed; offline and explicitly destructive. |
| `okto-pulse verify-pipeline <board_id>` | Check all five Kanban-KG pipeline layers for a board. |
| `okto-pulse kg dedup-entities <board_id>` | Run the idempotent KG entity deduplication migration for a board. |
| `okto-pulse kg migrate-schema (--board <board_id> or --all-boards)` | Apply graph schema migrations manually. The runtime also auto-heals supported legacy schemas. |
| `okto-pulse kg backfill <board_id> [--apply]` | Re-extract deterministic KG nodes and edges; dry-run by default. |
| `okto-pulse kg proposals <board_id>` | List pending KG curation proposals. |
| `okto-pulse kg unmerge <board_id> <record_id>` | Logically reverse a dedup equivalence record without re-pointing edges. |
| `okto-pulse kg export <board_id> --output PATH` | Export a deterministic JSON-LD graph. |
| `okto-pulse kg subtype declare <node_type> <kind_of>` | Declare a governed KG subtype. |
| `okto-pulse kg restore <quarantine_id> [--apply]` | Plan or apply restoration of a quarantined KG snapshot. |

For exact JSON/error, graph-reset ownership and migration admission contracts,
see [CLI corrections and safety](docs/CLI_ISSUE_CLOSEOUT_20260913.md).

## Run with Docker

### Published image

```bash
docker run -d --name okto-pulse \
  -e HOST=0.0.0.0 \
  -e MCP_HOST=0.0.0.0 \
  -p 8100:8100 \
  -p 8101:8101 \
  -v okto-pulse-data:/data \
  ghcr.io/oktolabsai/okto-pulse:latest
```

Then open `http://localhost:8100` and retrieve the bootstrap API key:

```bash
docker exec okto-pulse okto-pulse api-key
```

### Compose

Use the production compose file when you want a PyPI-based image:

```bash
docker compose -f docker-compose.prod.yml build
docker compose -f docker-compose.prod.yml up -d
```

Use the local compose file when hacking on the community package together with a sibling `okto-pulse-core` checkout:

```bash
docker compose build
docker compose up -d
```

### Environment variables

| Variable | Default | Purpose |
| --- | --- | --- |
| `HOST` | `127.0.0.1` | API/UI bind host. Use `0.0.0.0` in containers. |
| `MCP_HOST` | `127.0.0.1` | MCP bind host. Use `0.0.0.0` in containers. |
| `DATA_DIR` | `~/.okto-pulse` | SQLite database, uploads, graph storage and terms-acceptance root. Takes precedence over legacy `OKTO_PULSE_HOME` in the environment. |
| `CORS_ORIGINS` | `*` | Comma-separated allowed browser origins, e.g. `https://one.example,https://two.example`. Explicit values are preserved. Not authentication or a firewall. |
| `KG_BASE_DIR` | derived from `DATA_DIR` | Per-board graph database location. |
| `KG_GRAFX_DESCRIPTOR_REVALIDATION` | `generation` | Grafx process-local descriptor policy: `generation` or `strict`. |
| `HF_HOME` | `~/.cache/huggingface` | Sentence-transformers model cache. |
| `MCP_TRACE_ENABLED` | unset | Set to `1` to record MCP calls for replay testing. |
| `MCP_TRACE_DIR` | `${KG_BASE_DIR}/mcp_traces` | Trace output directory when tracing is enabled; falls back to `./mcp_traces` when `KG_BASE_DIR` is unset. |
| `MCP_ADMISSION_MAX_ACTIVE` | `4` | Maximum concurrent MCP tool calls. REST/UI and MCP session/stream transport stay outside this gate. |
| `MCP_ADMISSION_MAX_ACTIVE_PER_SESSION` | `2` | Maximum concurrent MCP tool calls owned by one session. |
| `MCP_ADMISSION_MAX_ACTIVE_WRITERS` | `1` | Fixed single-writer lane; values other than `1` are rejected to preserve embedded persistence ownership. |
| `MCP_ADMISSION_MAX_QUEUED` | `16` | Maximum short-wait MCP tool calls across all sessions. |
| `MCP_ADMISSION_MAX_QUEUED_PER_SESSION` | `4` | Maximum queued MCP tool calls owned by one session. |
| `MCP_ADMISSION_WAIT_TIMEOUT_MS` | `250` | Maximum queue wait before a fail-fast saturation result. Set to `0` to reject instead of waiting. |
| `MCP_ADMISSION_RETRY_AFTER_MS` | `500` | Retry delay advertised by a retryable `mcp_admission_saturated` result. |

For Grafx, `generation` is the Pulse default. Pulse owns each managed generation directory and
performs restore/generation replacement only with its handles closed, satisfying this policy's
closed lifecycle. It amortizes descriptor identity proofs only for Grafx's canonical heap, catalog,
index and WAL names; control and unknown names remain strict. This removes repeated namespace
system calls from page-heavy graph reads without changing Grafx locking, WAL, OCC or snapshot
rules. Keep it for the ordinary local Pulse runtime where no other tool mutates the live generation.

`strict` proves the physical identity behind every cached descriptor hit. Select it when external
tools may touch the database directory, during manual maintenance or forensics with uncertain
directory provenance, on mixed-trust hosts, with live file replacement/replication that swaps
names, or on an unsupported shared filesystem. Its advantage is detecting an out-of-protocol path
replacement at the next physical operation; its cost is repeated namespace/descriptor calls on hot
files. Conversely, `generation` can defer detection of that unsupported mutation until directed
invalidation, generation advance or reopen. The policy is process-local and not persisted; it does
not alter OCC, WAL, durability or multiwriter/multireader guarantees. Pulse fixes one policy per
Grafx pool and refuses a handle whose observed effective mode differs from configuration. The full
whitelist and transition matrix are specified in Okto Grafx's
`docs/architecture/ST2_DESCRIPTOR_REVALIDATION.md`.

One-shot schema-migration and rollout builders continue to open their separate, unbound candidate
paths with Grafx's `strict` default and close them before activation. They do not share the live
pool or its path, so this conservative choice neither changes nor weakens the configured policy of
the active Pulse database.

MCP admission is intentionally scoped to tool execution. Saturated calls receive
a bounded, retryable outcome with `next_action.rel=retry_after`; initialization,
streaming, resources, prompts, and the API/UI listener do not enter this queue.

## Data Storage

All default local state lives under `~/.okto-pulse/`:

```text
~/.okto-pulse/
|-- data/
|   `-- pulse.db
|-- boards/
|   `-- {board-id}/
|       `-- graph.lbug
|-- global/
|   `-- discovery.lbug
|-- uploads/
|   `-- {board-id}/
`-- mcp_traces/
```

> [!WARNING]
> Do not delete graph database directories to "fix" graph errors. Use the KG migration and health tools so schema or runtime issues remain diagnosable.

## From Source

Clone both repositories next to each other:

```bash
git clone https://github.com/OktoLabsAI/okto-pulse-core.git
git clone https://github.com/OktoLabsAI/okto-pulse.git
cd okto-pulse
```

Install both packages in editable mode:

```bash
pip install -e ../okto-pulse-core -e .
okto-pulse init
okto-pulse serve
```

Build the frontend before packaging:

```bash
cd frontend
npm install
npm run build
cd ..
```

## Troubleshooting

<details>
<summary>Embedding model did not download</summary>

Restore network access and restart:

```bash
okto-pulse serve
```

You can also smoke-test the embedder from a source checkout:

```bash
python scripts/smoke_embedding.py
```

</details>

<details>
<summary>AI agent cannot connect to MCP</summary>

Check that the MCP port in `.mcp.json` matches the running server:

```bash
okto-pulse serve --api-port 8100 --mcp-port 8101
okto-pulse init --agents
```

If running in Docker, expose the MCP listener with `MCP_HOST=0.0.0.0` and publish the port.

</details>

<details>
<summary>Grafx reports lock, WAL or page-geometry errors</summary>

First confirm that only one `okto-pulse serve` process is using the same data directory. Then open board settings and check:

- configured Board and Global Discovery providers
- Grafx page size (fixed for each existing generation)
- Grafx descriptor revalidation mode (`generation` for Pulse-managed paths;
  `strict` for forensic or externally shared paths)
- KG health and dead-letter metrics

The DLQ Inspector in **Settings → Event Queue** can redrive an individual row or
all accessible rows after their root cause is fixed. `Redrive all` requires an
explicit UI confirmation and drains the board DLQ through bounded 200-row
transactions. Both modes are permission-gated, idempotent and wake the
consolidation worker.

Use the contextual error message as the source of truth when reporting an issue.

</details>

## Release Notes

**Current: 0.3.3** — Community delivers actionable semantic-guideline evidence,
agent-mediated Code Traceability, governed lifecycle validation, resilient KG
recovery, canonical Analytics dashboards and full-graph dependency lineage in a
human-first UI.

**→ [Full release notes](docs/RELEASE-NOTES.md)** — 0.3.3, 0.3.2, 0.3.1 and 0.3.0 changesets, plus 0.2.6, 0.2.5,
0.2.3, 0.2.2, 0.2.1 and 0.2.0.

## Graph storage

See [Local/remote integration and recovery regression](docs/LOCAL_REMOTE_INTEGRATION_2026_09_14.md)
for the preserved local changes and their integration with the Grafx-only runtime.

See [Open PR review for 0.3.3](docs/PR_REVIEW_2026_09_14.md) for integration decisions,
compatibility evidence and deferred dependency migrations.

See [CLI, configuration and badge-refresh fixes (#84–#88)](docs/ISSUE_CLOSEOUT_84_88.md)
for export error behavior, terms storage, CORS configuration and validation evidence.

See [Delivery evidence: committed code and test-card verification](docs/DELIVERY_EVIDENCE.md)
for the separate Spec completion gate, UI, REST/MCP contracts and audited exemptions.

See [Code Evidence Matrix: associations and coverage](docs/CODE_EVIDENCE_MATRIX_PRESENTATION.md)
for the distinction between contextual references and applicable evidence.

See [Cognitive Action Center: review knowledge gaps](docs/COGNITIVE_ACTION_CENTER.md)
for the human review workflow, waiver effects, failed-processing navigation and permissions.

See [KG Health: observe, diagnose and recover](docs/KG_HEALTH_DASHBOARD.md)
for the operations dashboard, contextual help, action impacts and recovery safeguards.

Community uses **Okto Grafx only**, pinned to the published `okto-grafx[accel]==0.0.7` release. `uv.lock` resolves Grafx from the official PyPI artifacts. See [Grafx-only runtime, settings, retirement and data preservation](docs/GRAFX_ONLY_COMMUNITY.md). The Core remains storage-agnostic.

## SaaS Closure Audit

The executable ownership matrix is generated by `okto-pulse-saas-closure`. Every transitional budget must remain zero; the command fails closed on import, dependency, adapter, wheel, or documentation drift.

<!-- AF33-CAPSTONE-MATRIX:BEGIN -->
| Surface | Core contract | Community/local adapter | SaaS swap target | Executable gates |
| --- | --- | --- | --- | --- |
| Relational runtime | repository/UoW and schema lifecycle ports; no ad-hoc dialect or engine/session factory bypass | SQLite/SQLAlchemy adapters in community.adapters.sqlalchemy_* and relational_schema_lifecycle | SQLite -> Aurora/Postgres | run_relational_residue_gate, audit_dependency_conformance, audit_community_core_import_boundary |
| KG graph runtime | KG interfaces, policies and adapter-neutral schema compatibility helpers | edition-owned graph adapters behind Community routed composition | edition graph adapters -> remote graph provider | audit_dependency_conformance, ImportBoundaryGate, audit_community_core_import_boundary |
| Durable files and artifacts | StorageProvider, RebuildAuditArtifactStore and CognitivePendingWorkProvider contracts | filesystem storage, upload_dir, rebuild audit storage and cognitive-pending providers | filesystem -> S3 | run_rebuild_audit_storage_gate, run_core_settings_defaults_gate, run_public_config_stability_gate |
| Telemetry effects | TelemetryPort contracts, event schema and privacy policy | local JSONL store, state files, beacon sender and product telemetry adapters | local telemetry files/API -> AWS telemetry API | run_telemetry_store_ownership_gate, run_telemetry_sender_ownership_gate, run_telemetry_product_ownership_gate |
| Scheduler/runtime effects | JobSpec, SchedulerControl and KG daily tick policy | APScheduler-backed SingletonSchedulerControl | APScheduler local runtime -> runtime scheduler adapter | SchedulerControlSymbolGate, scheduler_signal_conformance |
| MCP resources and versions | MCP instruction/resource/version provider ports and stable public catalog | Community resource catalog, capability descriptors and package version wiring | local catalog/version reads -> deployment provider | run_public_config_stability_gate, register_instruction_provider, register_package_version_provider |
<!-- AF33-CAPSTONE-MATRIX:END -->

<!-- F16-SAAS-CLOSURE:BEGIN -->
| F16 executable surface | Owner | Observed | Terminal target |
| --- | --- | ---: | ---: |
| Core import rows | Core | 7327 | classified |
| Community-to-Core import rows | Community | 1222 | classified |
| Direct dependency rows | Distribution owner | 25 | classified |
| `import_boundary_baseline` budget | `675c43ee-7d91-4cc3-8f87-44eeb293f90c` | 0 | 0 |
| `singleton_baseline` budget | `675c43ee-7d91-4cc3-8f87-44eeb293f90c` | 0 | 0 |
| `dependency_temporary_exceptions` budget | `675c43ee-7d91-4cc3-8f87-44eeb293f90c` | 0 | 0 |
| `graph_runtime_compatibility` budget | `675c43ee-7d91-4cc3-8f87-44eeb293f90c` | 0 | 0 |
| `rebuild_artifact_compatibility` budget | `675c43ee-7d91-4cc3-8f87-44eeb293f90c` | 0 | 0 |
| `community_private_reach_ins` budget | `675c43ee-7d91-4cc3-8f87-44eeb293f90c` | 0 | 0 |
| `community_adapter_bridges` budget | `675c43ee-7d91-4cc3-8f87-44eeb293f90c` | 0 | 0 |
| `af35_relational_residue` budget | `675c43ee-7d91-4cc3-8f87-44eeb293f90c` | 0 | 0 |
<!-- F16-SAAS-CLOSURE:END -->

## License

[Elastic License 2.0](./LICENSE) - free for personal and commercial use. You may not provide this software to third parties as a hosted or managed service.

Copyright 2026 Okto Labs
