Skip to content
Back to search

okto-pulse

Local-first, spec-driven SDLC workbench with governance gates, knowledge graphs, and MCP for AI coding agents.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/OktoLabsAI/okto-pulse with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/OktoLabsAI/okto-pulse'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/oktolabsai--okto-pulse/badge.svg)](/listings/oktolabsai--okto-pulse)

HTML

<a href="/listings/oktolabsai--okto-pulse"><img src="/api/listings/oktolabsai--okto-pulse/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 561 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Okto Pulse
  2. <div align="center">
  3. <h3><em>Spec-driven project management for AI-assisted development.</em></h3>
  4. </div>
  5. <p align="center">
  6. <strong>Okto Pulse turns ideas, refinements, specs, tasks, tests and bugs into a governed SDLC board that AI agents can operate through MCP.</strong>
  7. </p>
  8. <p align="center">
  9. <strong>Ship with AI. Stay in control.</strong>
  10. </p>
  11. <p align="center">
  12. <a href="https://pypi.org/project/okto-pulse/"><img src="https://img.shields.io/pypi/v/okto-pulse" alt="PyPI version"></a>
  13. <a href="https://pypi.org/project/okto-pulse/"><img src="https://img.shields.io/pypi/pyversions/okto-pulse" alt="Python versions"></a>
  14. <a href="./LICENSE"><img src="https://img.shields.io/badge/license-Elastic%202.0-blue" alt="License"></a>
  15. <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>
  16. </p>
  17. ---
  18. ## Table of Contents
  19. - [What is Okto Pulse?](#what-is-okto-pulse)
  20. - [Platform Surface](#platform-surface)
  21. - [Get Started](#get-started)
  22. - [Connect an AI Coding Agent](#connect-an-ai-coding-agent)
  23. - [Token Usage](#token-usage)
  24. - [Core Workflow](#core-workflow)
  25. - [Governance Gates](#governance-gates)
  26. - [Knowledge Graph](#knowledge-graph)
  27. - [Architecture](#architecture)
  28. - [CLI Reference](#cli-reference)
  29. - [Run with Docker](#run-with-docker)
  30. - [Data Storage](#data-storage)
  31. - [From Source](#from-source)
  32. - [Troubleshooting](#troubleshooting)
  33. - [Release Notes](#release-notes)
  34. - [License](#license)
  35. **Reference documents**
  36. | Document | Contents |
  37. | --- | --- |
  38. | [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) | Dependency owner matrix, adapter source map and the **port → adapter matrix** |
  39. | [`docs/RELEASE-NOTES.md`](docs/RELEASE-NOTES.md) | Full changeset per version |
  40. | [`docs/TOKEN-USAGE.md`](docs/TOKEN-USAGE.md) | Measured MCP context cost for agents |
  41. | [`docs/kg-health.md`](docs/kg-health.md) | Knowledge Graph health signals and triage |
  42. | [`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 |
  43. | [`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 |
  44. | [`docs/GRAFX_V005_ADOPTION.md`](docs/GRAFX_V005_ADOPTION.md) | Grafx 0.0.5 adoption, optional capability boundary, Settings and validation checkpoint |
  45. | [`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 |
  46. | [`docs/GRAFX_RECOVERY_BATCHING.md`](docs/GRAFX_RECOVERY_BATCHING.md) | Bounded Global recovery writes, rollback/fencing guarantees and remaining batch opportunities |
  47. ## What is Okto Pulse?
  48. 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.
  49. Instead of sending an agent straight from a prompt to code, Okto Pulse keeps the work explicit:
  50. ```text
  51. Stories -> Ideation -> Refinement -> Spec -> Tasks / Tests / Bugs
  52. ```
  53. 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.
  54. ## Platform Surface
  55. Current 0.4.0 implementation surface:
  56. | Surface | Count |
  57. | --- | ---: |
  58. | Governance gates | See the Core governance families and canonical gate contracts |
  59. | Core MCP tools | 285 |
  60. | Community-only MCP tools | 0 |
  61. | MCP tools exposed by `okto-pulse serve` | 285 |
  62. The community package materializes the full `okto-pulse-core` command catalog in
  63. its FastMCP host. That means installed community runtimes expose the complete
  64. core tool catalog while keeping the CLI, frontend and packaging layer separate
  65. from the core engine. The MCP count is measured from the transport-neutral Core
  66. catalog at implementation time;
  67. Community adds operational resources and adapters, not extra community-only MCP
  68. tools.
  69. ## Get Started
  70. ### 1. Install
  71. ```bash
  72. pip install okto-pulse
  73. ```
  74. Okto Pulse requires Python 3.11+.
  75. > [!NOTE]
  76. > 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.
  77. ### 2. Initialize a workspace
  78. Run this inside the project directory where your coding agent will work:
  79. ```bash
  80. okto-pulse init
  81. ```
  82. This creates:
  83. - the local data directory under `~/.okto-pulse/`
  84. - a default board and agent
  85. - a project-local `.mcp.json` that points your agent at the local MCP server
  86. ### 3. Start the app
  87. ```bash
  88. okto-pulse serve
  89. ```
  90. Default endpoints:
  91. | Endpoint | URL |
  92. | --- | --- |
  93. | Web UI + API | `http://localhost:8100` |
  94. | MCP server | `http://localhost:8101/mcp` |
  95. 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.
  96. ### 4. Open the UI
  97. Go to `http://localhost:8100`, select the default board and start with either:
  98. - a **Story**, when you want lightweight pre-ideation context grouped by topic
  99. - an **Ideation**, when the feature or problem is already ready to be discussed
  100. ## Connect an AI Coding Agent
  101. Most agent tools can discover the generated `.mcp.json` automatically when they run from the same directory.
  102. Community keeps its local REST identity deliberately human-only. Authenticated
  103. agent submissions use the Core MCP surface locally; a SaaS edition may inject
  104. an agent-aware `AuthenticationPort` into the same edition-neutral REST
  105. contract. Neither path makes Community acquire, clone, browse, probe or inspect
  106. source code: the external agent checks access and capabilities in its own
  107. environment and submits only the bounded result.
  108. | Agent or tool | Setup |
  109. | --- | --- |
  110. | Claude Code | Run it from the directory that contains `.mcp.json`. |
  111. | Claude Desktop | Copy the generated MCP server block into Claude Desktop settings. |
  112. | Codex | In **Menu → Agents**, create an agent or regenerate its key, then click **Codex (CLI)** and run the copied command in your terminal. |
  113. | Cursor | Add the MCP server URL in Cursor MCP settings. |
  114. | VS Code | Copy the server block into `.vscode/mcp.json`. |
  115. | Windsurf / Cline | Use the generated `.mcp.json` when supported. |
  116. The **Codex (CLI)** button copies `codex mcp add okto-pulse --url "<Pulse MCP URL with agent key>"`,
  117. using the runtime MCP address and the newly revealed API key. Install Codex CLI
  118. first. After rotating the key, copy and run the new command, then restart the
  119. Codex session; the old key stops working. Configuration copying is disabled when
  120. the reveal-once key is hidden. Keep the copied command private: it contains the
  121. key and can be saved in shell history and Codex's configuration. The command
  122. configures a connection; board access still needs to be granted in Pulse.
  123. See the [official Codex MCP documentation](https://developers.openai.com/codex/mcp/).
  124. Generated shape:
  125. ```json
  126. {
  127. "mcpServers": {
  128. "okto-pulse": {
  129. "url": "http://localhost:8101/mcp?api_key=dash_..."
  130. }
  131. }
  132. }
  133. ```
  134. If you change the MCP port, regenerate the file:
  135. ```bash
  136. okto-pulse init --agents
  137. ```
  138. ## Token Usage
  139. Connecting an agent over MCP has a fixed context cost (the tool catalogue) plus a variable cost
  140. (tool responses). Response projections — `summary`, `detail`, `full` — let you trade detail for
  141. tokens.
  142. **→ [Measured token usage](docs/TOKEN-USAGE.md)** — fixed cost per connection, on-demand resources,
  143. variable response cost and ballpark session profiles.
  144. ## Core Workflow
  145. Okto Pulse is intentionally workflow-first. Each stage answers a different question.
  146. | Stage | Purpose |
  147. | --- | --- |
  148. | **Stories** | Optional lightweight user-story inputs, grouped by topic, that can feed one or more ideations. |
  149. | **Ideation** | Capture the problem, assess ambiguity and collect Q&A before committing to a solution path. |
  150. | **Refinement** | Investigate code, constraints, prior decisions, mockups, architecture and knowledge entries. |
  151. | **Spec** | Define acceptance criteria, functional requirements, business rules, API contracts, tests and decisions. |
  152. | **Sprint** | Slice approved specs into reviewable implementation batches when the work is large. |
  153. | **Tasks / Tests / Bugs** | Execute implementation with linked tests, bug evidence, validation and conclusions. |
  154. The lineage graph keeps these relationships inspectable, including story-to-ideation and task-to-test/bug relationships.
  155. ## Governance Gates
  156. Okto Pulse protects the workflow with checks that run on status transitions.
  157. The platform currently has **17 named governance gates**:
  158. | Gate family | Gates |
  159. | --- | --- |
  160. | Resource readiness | Resource readiness; resource-to-task coverage |
  161. | Spec coverage | Scenario/test coverage; functional requirement/business rule coverage; technical requirement/task coverage; API contract/task coverage; active decision/task coverage |
  162. | Validation and evaluation | Spec validation; spec qualitative evaluation; task validation |
  163. | Execution quality | Task start/spec readiness; task conclusion; cognitive closeout; architecture-findings done; test evidence; bug test-first/traceability |
  164. | Sprint health | Sprint closure/evaluation |
  165. - Specs require coverage across acceptance criteria, functional requirements, business rules, API contracts, decisions and test scenarios.
  166. - Tasks cannot start until the parent spec has the required scenario coverage.
  167. - Tasks moving to `done` require a structured conclusion with completeness and drift assessment.
  168. - 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.
  169. - Test cards require evidence before they can be marked as automated, passed or failed.
  170. - Bug cards follow a test-first workflow and must remain traceable to the task and related test work.
  171. - Validation gates can require independent review before specs or tasks are considered complete.
  172. Board settings let teams tune thresholds without removing the traceability model.
  173. ## Knowledge Graph
  174. Okto Pulse maintains an embedded per-board Knowledge Graph for durable project memory.
  175. Agents use the graph to:
  176. - find related prior decisions
  177. - detect contradictions and superseded context
  178. - reuse lessons from previous bugs
  179. - query global discovery context across boards
  180. - consolidate specs, bugs and implementation conclusions into searchable knowledge
  181. Operational health is visible through:
  182. - the in-product KG view
  183. - MCP health tools
  184. - dead-letter and queue metrics
  185. - graph database runtime settings in the board settings panel
  186. GET /health is a constant-time liveness endpoint: it performs no storage
  187. scan and returns HTTP 200 with status "healthy" while the process can answer
  188. requests. Use application workflows or a verified backup/restore procedure
  189. for recovery; direct SQL repair is unsupported.
  190. ## Architecture
  191. Okto Pulse ships as two packages: **`okto-pulse-core`** owns the SDLC domain, the governance gates
  192. and the Knowledge Graph contracts as pure `Protocol` seams; **`okto-pulse`** (this package) owns
  193. every concrete mechanism — SQLite, Okto Grafx, the filesystem, the scheduler, telemetry state,
  194. the REST app and the MCP host.
  195. Core never imports Community. Community fills the ports at startup, and an unfilled slot **fails
  196. closed** rather than falling back to a silent default.
  197. **→ [Architecture in full](docs/ARCHITECTURE.md)** — dependency owner matrix (AF-05/AF40),
  198. registration flow, the adapter source map, and the **port → adapter matrix** showing which core
  199. contract each adapter module implements.
  200. ## CLI Reference
  201. | Command | Description |
  202. | --- | --- |
  203. | `okto-pulse init` | Initialize local data, seed the default board and generate `.mcp.json`. |
  204. | `okto-pulse init --agents` | Regenerate MCP agent configuration. |
  205. | `okto-pulse init --accept-terms` | Accept terms non-interactively. Also supported through `OKTO_PULSE_TERMS_ACCEPTED=1`. |
  206. | `okto-pulse serve` | Start API/UI and MCP in one Python process. |
  207. | `okto-pulse serve --api-port N --mcp-port M` | Override API/UI and MCP ports. |
  208. | `okto-pulse status` | Show service status, database path, size and board counts. |
  209. | `okto-pulse status --json` | Emit one status object; SQLite errors return exit 1 without an initialization hint. |
  210. | `okto-pulse code-traceability requests <board_id>` | List persisted code-investigation requests. |
  211. | `okto-pulse code-traceability receipts <board_id>` | List agent-attested execution receipts. |
  212. | `okto-pulse code-traceability inspect <board_id> <kind> <record_id>` | Inspect one persisted request or receipt. |
  213. | `okto-pulse code-traceability diagnose <board_id>` | Validate the persisted Code Traceability schema and board policy. |
  214. | `okto-pulse metrics status [--window-days N]` | Show local metrics state and aggregates; N is 1–400, default 30. |
  215. | `okto-pulse metrics enable-beacon --policy-version VERSION --yes` | Opt in to anonymous hourly aggregate metrics. |
  216. | `okto-pulse metrics disable` | Turn metrics off. |
  217. | `okto-pulse metrics export [--output PATH]` | Export local metrics as JSONL. |
  218. | `okto-pulse metrics purge-local --yes` | Delete local metrics files after explicit confirmation. |
  219. | `okto-pulse api-key --handoff-file PATH` | Atomically consume a reveal-once bootstrap API-key handoff. |
  220. The former `reset`, `verify-pipeline` and `kg` command group are no longer accepted,
  221. including their help/options. The CLI returns the standard unknown-command
  222. error (exit 2) before accessing data. Use `status` for local observation; it
  223. does not certify KG health or perform recovery. See [health observations](docs/kg-health.md)
  224. and the [historical CLI corrections](docs/CLI_ISSUE_CLOSEOUT_20260913.md).
  225. ## Run with Docker
  226. ### Published image
  227. ```bash
  228. docker run -d --name okto-pulse \
  229. -e HOST=0.0.0.0 \
  230. -e MCP_HOST=0.0.0.0 \
  231. -p 8100:8100 \
  232. -p 8101:8101 \
  233. -v okto-pulse-data:/data \
  234. ghcr.io/oktolabsai/okto-pulse:latest
  235. ```
  236. Then open `http://localhost:8100`. The first startup prints the newly created
  237. bootstrap API key once. Persisted keys cannot be recovered; regenerate a key
  238. through the UI/API if needed. Automation can use `init --bootstrap-key-handoff`
  239. and consume that explicit file with `api-key --handoff-file`.
  240. ### Compose
  241. Use the production compose file when you want a PyPI-based image:
  242. ```bash
  243. docker compose -f docker-compose.prod.yml build
  244. docker compose -f docker-compose.prod.yml up -d
  245. ```
  246. Use the local compose file when hacking on the community package together with a sibling `okto-pulse-core` checkout:
  247. ```bash
  248. docker compose build
  249. docker compose up -d
  250. ```
  251. ### Environment variables
  252. | Variable | Default | Purpose |
  253. | --- | --- | --- |
  254. | `HOST` | `127.0.0.1` | API/UI bind host. Use `0.0.0.0` in containers. |
  255. | `MCP_HOST` | `127.0.0.1` | MCP bind host. Use `0.0.0.0` in containers. |
  256. | `DATA_DIR` | `~/.okto-pulse` | SQLite database, uploads, graph storage and terms-acceptance root. Resolved from the explicit setting, then `DATA_DIR` in the environment or dotenv. |
  257. | `CORS_ORIGINS` | `*` | Comma-separated allowed browser origins, e.g. `https://one.example,https://two.example`. Explicit values are preserved. Not authentication or a firewall. |
  258. | `KG_BASE_DIR` | derived from `DATA_DIR` | Per-board graph database location. |
  259. | `KG_GRAFX_DESCRIPTOR_REVALIDATION` | `generation` | Grafx process-local descriptor policy: `generation` or `strict`. |
  260. | `HF_HOME` | `~/.cache/huggingface` | Sentence-transformers model cache. |
  261. | `MCP_TRACE_ENABLED` | unset | Set to `1` to record MCP calls for replay testing. |
  262. | `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. |
  263. | `MCP_ADMISSION_MAX_ACTIVE` | `4` | Maximum concurrent MCP tool calls. REST/UI and MCP session/stream transport stay outside this gate. |
  264. | `MCP_ADMISSION_MAX_ACTIVE_PER_SESSION` | `2` | Maximum concurrent MCP tool calls owned by one session. |
  265. | `MCP_ADMISSION_MAX_ACTIVE_WRITERS` | `1` | Fixed single-writer lane; values other than `1` are rejected to preserve embedded persistence ownership. |
  266. | `MCP_ADMISSION_MAX_QUEUED` | `16` | Maximum short-wait MCP tool calls across all sessions. |
  267. | `MCP_ADMISSION_MAX_QUEUED_PER_SESSION` | `4` | Maximum queued MCP tool calls owned by one session. |
  268. | `MCP_ADMISSION_WAIT_TIMEOUT_MS` | `250` | Maximum queue wait before a fail-fast saturation result. Set to `0` to reject instead of waiting. |
  269. | `MCP_ADMISSION_RETRY_AFTER_MS` | `500` | Retry delay advertised by a retryable `mcp_admission_saturated` result. |
  270. For Grafx, `generation` is the Pulse default. Pulse owns each managed generation directory and
  271. performs restore/generation replacement only with its handles closed, satisfying this policy's
  272. closed lifecycle. It amortizes descriptor identity proofs only for Grafx's canonical heap, catalog,
  273. index and WAL names; control and unknown names remain strict. This removes repeated namespace
  274. system calls from page-heavy graph reads without changing Grafx locking, WAL, OCC or snapshot
  275. rules. Keep it for the ordinary local Pulse runtime where no other tool mutates the live generation.
  276. `strict` proves the physical identity behind every cached descriptor hit. Select it when external
  277. tools may touch the database directory, during manual maintenance or forensics with uncertain
  278. directory provenance, on mixed-trust hosts, with live file replacement/replication that swaps
  279. names, or on an unsupported shared filesystem. Its advantage is detecting an out-of-protocol path
  280. replacement at the next physical operation; its cost is repeated namespace/descriptor calls on hot
  281. files. Conversely, `generation` can defer detection of that unsupported mutation until directed
  282. invalidation, generation advance or reopen. The policy is process-local and not persisted; it does
  283. not alter OCC, WAL, durability or multiwriter/multireader guarantees. Pulse fixes one policy per
  284. Grafx pool and refuses a handle whose observed effective mode differs from configuration. The full
  285. whitelist and transition matrix are specified in Okto Grafx's
  286. `docs/architecture/ST2_DESCRIPTOR_REVALIDATION.md`.
  287. MCP admission is intentionally scoped to tool execution. Saturated calls receive
  288. a bounded, retryable outcome with `next_action.rel=retry_after`; initialization,
  289. streaming, resources, prompts, and the API/UI listener do not enter this queue.
  290. ## Data Storage
  291. All default local state lives under `~/.okto-pulse/`:
  292. ```text
  293. ~/.okto-pulse/
  294. |-- data/
  295. | `-- pulse.db
  296. |-- boards/
  297. | `-- {board-id}/
  298. | |-- graph_backend_binding.json
  299. | `-- grafx/
  300. | `-- {generation}/
  301. |-- global/
  302. | |-- graph_backend_binding.json
  303. | `-- grafx/
  304. | `-- {generation}/
  305. |-- uploads/
  306. | `-- {board-id}/
  307. `-- mcp_traces/
  308. ```
  309. > [!WARNING]
  310. > Do not delete graph database directories to "fix" graph errors. Use the KG health and recovery tools so runtime issues remain diagnosable. Pulse 0.4.0 accepts only its current storage format; incompatible storage is refused without conversion or automatic deletion. Select a new storage location for a fresh installation.
  311. ## From Source
  312. Clone both repositories next to each other:
  313. ```bash
  314. git clone https://github.com/OktoLabsAI/okto-pulse-core.git
  315. git clone https://github.com/OktoLabsAI/okto-pulse.git
  316. cd okto-pulse
  317. ```
  318. Install both packages in editable mode:
  319. ```bash
  320. pip install -e ../okto-pulse-core -e .
  321. okto-pulse init
  322. okto-pulse serve
  323. ```
  324. Build the frontend before packaging:
  325. ```bash
  326. cd frontend
  327. npm install
  328. npm run build
  329. cd ..
  330. ```
  331. ## Troubleshooting
  332. <details>
  333. <summary>Embedding model did not download</summary>
  334. Restore network access and restart:
  335. ```bash
  336. okto-pulse serve
  337. ```
  338. </details>
  339. <details>
  340. <summary>AI agent cannot connect to MCP</summary>
  341. Check that the MCP port in `.mcp.json` matches the running server:
  342. ```bash
  343. okto-pulse serve --api-port 8100 --mcp-port 8101
  344. okto-pulse init --agents
  345. ```
  346. If running in Docker, expose the MCP listener with `MCP_HOST=0.0.0.0` and publish the port.
  347. </details>
  348. <details>
  349. <summary>Grafx reports lock, WAL or page-geometry errors</summary>
  350. First confirm that only one `okto-pulse serve` process is using the same data directory. Then open board settings and check:
  351. - configured Board and Global Discovery providers
  352. - Grafx page size (fixed for each existing generation)
  353. - Grafx descriptor revalidation mode (`generation` for Pulse-managed paths;
  354. `strict` for forensic or externally shared paths)
  355. - KG health and dead-letter metrics
  356. The DLQ Inspector in **Settings → Event Queue** can redrive an individual row or
  357. all accessible rows after their root cause is fixed. `Redrive all` requires an
  358. explicit UI confirmation and drains the board DLQ through bounded 200-row
  359. transactions. Both modes are permission-gated, idempotent and wake the
  360. consolidation worker.
  361. Use the contextual error message as the source of truth when reporting an issue.
  362. </details>
  363. ## Release Notes
  364. **In development: 0.4.3.** Core and Community use the matching `0.4.3` version.
  365. The release simplifies Spec validation and human task requirement decisions,
  366. with central and contextual Help. Startup continues to require the exact storage
  367. format; it never silently converts an existing database.
  368. An exact 0.4.2 database can be converted to a **new verified copy**:
  369. ```bash
  370. okto-pulse storage upgrade-copy --source-db ORIGINAL_DB --output-db NEW_DB --json
  371. ```
  372. The output file must not exist. The command preserves every source table's rows
  373. and historical receipts, adds the task requirement tables and guards, and advances
  374. the derived freshness fence. Its JSON receipt includes preservation hashes.
  375. The original database and active installation remain unchanged. Keep its associated
  376. graph, uploads and metrics directories; this command copies only SQLite storage.
  377. Unknown or modified formats are refused. The 0.4.0 boundary with pre-0.4.0 storage
  378. remains incompatible; this command does not convert those installations.
  379. **→ [Full release notes](docs/RELEASE-NOTES.md)** — 0.4.0, 0.3.3, 0.3.2, 0.3.1 and 0.3.0 changesets, plus 0.2.6, 0.2.5,
  380. 0.2.3, 0.2.2, 0.2.1 and 0.2.0.
  381. ## Graph storage
  382. See [Local/remote integration and recovery regression](docs/LOCAL_REMOTE_INTEGRATION_2026_09_14.md)
  383. for the preserved local changes and their integration with the Grafx-only runtime.
  384. See [Open PR review for 0.3.3](docs/PR_REVIEW_2026_09_14.md) for integration decisions,
  385. compatibility evidence and deferred dependency migrations.
  386. See [CLI, configuration and badge-refresh fixes (#84–#88)](docs/ISSUE_CLOSEOUT_84_88.md)
  387. for export error behavior, terms storage, CORS configuration and validation evidence.
  388. See [Delivery evidence: committed code and test-card verification](docs/DELIVERY_EVIDENCE.md)
  389. for the separate Spec completion gate, UI, REST/MCP contracts and audited exemptions.
  390. See [Code Evidence Matrix: associations and coverage](docs/CODE_EVIDENCE_MATRIX_PRESENTATION.md)
  391. for the distinction between contextual references and applicable evidence.
  392. See [Cognitive Action Center: review knowledge gaps](docs/COGNITIVE_ACTION_CENTER.md)
  393. for the human review workflow, waiver effects, failed-processing navigation and permissions.
  394. See [KG Health: observe, diagnose and recover](docs/KG_HEALTH_DASHBOARD.md)
  395. for the operations dashboard, contextual help, action impacts and recovery safeguards.
  396. Community uses **Okto Grafx only**, pinned to the published `okto-grafx[accel]==0.0.8` 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.
  397. ## SaaS Closure Audit
  398. 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.
  399. <!-- AF33-CAPSTONE-MATRIX:BEGIN -->
  400. | Surface | Core contract | Community/local adapter | SaaS swap target | Executable gates |
  401. | --- | --- | --- | --- | --- |
  402. | 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 |
  403. | 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 |
  404. | 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 |
  405. | 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 |
  406. | Scheduler/runtime effects | JobSpec, SchedulerControl and KG daily tick policy | APScheduler-backed SingletonSchedulerControl | APScheduler local runtime -> runtime scheduler adapter | SchedulerControlSymbolGate, scheduler_signal_conformance |
  407. | 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 |
  408. <!-- AF33-CAPSTONE-MATRIX:END -->
  409. <!-- F16-SAAS-CLOSURE:BEGIN -->
  410. | F16 executable surface | Owner | Observed | Terminal target |
  411. | --- | --- | ---: | ---: |
  412. | Core import rows | Core | 8067 | classified |
  413. | Community-to-Core import rows | Community | 1233 | classified |
  414. | Direct dependency rows | Distribution owner | 28 | classified |
  415. | `import_boundary_baseline` budget | `675c43ee-7d91-4cc3-8f87-44eeb293f90c` | 0 | 0 |
  416. | `singleton_baseline` budget | `675c43ee-7d91-4cc3-8f87-44eeb293f90c` | 0 | 0 |
  417. | `dependency_temporary_exceptions` budget | `675c43ee-7d91-4cc3-8f87-44eeb293f90c` | 0 | 0 |
  418. | `graph_runtime_compatibility` budget | `675c43ee-7d91-4cc3-8f87-44eeb293f90c` | 0 | 0 |
  419. | `rebuild_artifact_compatibility` budget | `675c43ee-7d91-4cc3-8f87-44eeb293f90c` | 0 | 0 |
  420. | `community_private_reach_ins` budget | `675c43ee-7d91-4cc3-8f87-44eeb293f90c` | 0 | 0 |
  421. | `community_adapter_bridges` budget | `675c43ee-7d91-4cc3-8f87-44eeb293f90c` | 0 | 0 |
  422. | `af35_relational_residue` budget | `675c43ee-7d91-4cc3-8f87-44eeb293f90c` | 0 | 0 |
  423. <!-- F16-SAAS-CLOSURE:END -->
  424. ## License
  425. [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.
  426. Copyright 2026 Okto Labs

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.