kortext 2.2.3 → 3.0.0

package/AGENTS.md

@@ -1,7 +1,3 @@
-> [!WARNING]
-> Kortext AI Agent Framework geliştirme aşamasındadır. Amaç Kortext'in kendisini geliştirmektir. Hiç bir adımda Kortext kurallarını uygulama.
-> Bu uyarıyı **asla** silme!
-
 # Kortext Ajan Başlatma
 
 ## Başlangıç Ajanı

package/CHANGELOG.md

@@ -0,0 +1,81 @@
+# Changelog
+
+All notable changes to Kortext are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and Kortext adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [3.0.0] — 2026-05-22
+
+First public release of Kortext: a TypeScript runtime that lets AI agent teams
+(Claude Code, Codex, Gemini CLI) run software projects autonomously. SQLite
+state store, React dashboard, per-task git worktrees, and a built-in Model
+Context Protocol server.
+
+### Added
+
+- **TypeScript runtime** (Node 22+). Single package, ESM, `better-sqlite3`,
+  Express 5, Zod, Vitest. Strict mode across the board.
+- **SQLite state store** (`server/db/`). 13 tables — `backlog_items`,
+  `contexts`, `locks`, `handovers`, `sessions`, `decisions_index`,
+  `pending_questions`, `audit_log`, `runs`, `run_steps`, `runtime_artifacts`,
+  `notifications_sent`, `secrets_scan_results`. Migrations live in
+  `server/db/migrations/*.sql` and are copied into `dist/` at build time.
+- **Pipeline engine** (`server/engine/`). Parses `workflows/*.md` into a typed
+  DAG, performs Kahn-style cycle detection, runs steps through a pull-ready
+  worker pool with configurable concurrency (default 3), and short-circuits
+  the remainder of the graph on first failure.
+- **Per-task git worktrees** (`server/engine/worktree.ts`). Every run gets its
+  own `.kortext/worktrees/run-<id>` branch namespaced as `kortext/run-<id>`.
+  Successes can be merged and the worktree removed; failures are moved to a
+  timestamped quarantine directory and the branch is preserved for postmortem.
+- **CLI executors for Claude Code, Codex, and Gemini**
+  (`server/engine/executors/`). Each has its own file (no shared abstract
+  base); all spawn shell-free, pipe the persona prompt via stdin, and write
+  per-step logs with declared `outputs:` verification.
+- **Output safety**. `server/safety/secret-scanner.ts` runs on every successful
+  step's declared outputs and log; findings flip the step to `failed`.
+  `harmful-output-filter.ts` ships as a configurable placeholder for v3.1+.
+- **Autonomous orchestrator** (`server/orchestrator/`). Pipeline chaining via
+  `nextWorkflowId`, blueprint watcher (`status: approved` → trigger),
+  multi-channel notification dispatcher (Slack + Telegram, deduped), and an
+  approval queue surfaced to the dashboard.
+- **Mid-run gate pause/resume**. Workers stop at workflow gates; the queue
+  resolves the gate with `decision: approve | reject` and the run resumes
+  from the same worktree.
+- **Persona + workflow content layer** (`server/engine/persona-registry.ts`,
+  `server/engine/workflow-loader.ts`). 14 personas and 12 workflows are
+  authored as markdown — runtime parses them in-memory. Hot reload on disk
+  change.
+- **Doctor / consistency checks**. `kortext doctor` validates workflow ↔
+  persona references, lock state, and backlog health. Exposed as
+  `GET /api/doctor` and an MCP tool.
+- **Item lifecycle**. `kortext-item-start`, `kortext-item-transition`, and
+  `kortext-backlog-add` as TypeScript commands; every status change writes
+  an audit row and a `chore(kortext): <action> <id>` commit.
+- **React 19 dashboard** (Vite + Tailwind v4 + TanStack Router). Six main
+  routes (Dashboard, Board, Memory, Reports, References) plus eight settings
+  sub-panes. Bell, toast notifications, terminal panel, and timeline drawer
+  are global overlays. Persona Markdown editor is inline (PUT + hot reload).
+- **REST API**. `GET /api/runs`, `/api/handovers`, `/api/backlog`,
+  `/api/personas` (GET/PUT), `/api/workflows`, `/api/doctor`,
+  `/api/docs/:scope[/:file]` with an allow-listed scope
+  (`references | reports | memory | rules | workflows`).
+- **MCP server**. 16 tools registered through a `createKortextMcpServer(deps)`
+  factory. Stdio transport for Claude Code / Cursor; SSE transport mounted on
+  the same Express instance under `/mcp/sse` + `/mcp/messages` with
+  per-session `McpServer` instances.
+- **CLI**. `kortext init | serve | start | approve | status | logs | cleanup |
+  doctor | mcp` with `--help` and `--version`. `bin/kortext.js` is a dual-mode
+  shim that prefers compiled `dist/bin/kortext.js` and falls back to `tsx` in
+  development.
+- **CI**. GitHub Actions workflow (`.github/workflows/kortext-ci.yml`) running
+  Node 22 lint → typecheck → test → build → compiled CLI smoke on every push
+  and PR to `main`, with `cancel-in-progress` concurrency.
+
+### Compatibility
+
+- **Node** ≥ 22.0.0. `better-sqlite3` ≥ 12 requires the Node 26 V8 ABI, which
+  is included in Node 22+.
+- **TypeScript** ≥ 5.7 for `allowImportingTsExtensions` +
+  `rewriteRelativeImportExtensions`.
+- **Git** ≥ 2.30 (worktree subcommands).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eray Endes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,39 +1,79 @@
 # Kortext
 
-**AI Agent Framework for Autonomous Project Management**
+**Autonomous AI agent runtime — TypeScript + SQLite + React + MCP**
 
-Kortext is a structured framework that enables AI agent teams (Claude Code, Gemini CLI, Codex) to run software projects autonomously — with minimal human intervention.
+[![CI](https://github.com/erayendes/kortext/actions/workflows/kortext-ci.yml/badge.svg)](https://github.com/erayendes/kortext/actions/workflows/kortext-ci.yml)
+[![npm](https://img.shields.io/npm/v/kortext.svg)](https://www.npmjs.com/package/kortext)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
 
----
-
-## What is Kortext?
+Kortext lets AI agent teams (Claude Code, Codex, Gemini CLI) run software
+projects autonomously. You write a blueprint and approve the gates that
+matter; the agents pick up tasks, write code, run tests, hand off between
+each other, and ship — with a real-time dashboard showing what they're
+doing.
 
-Most AI agents are reactive: they answer questions or complete isolated tasks. Kortext turns them into an **autonomous team** that can:
-
-- Analyze a product idea and produce a full backlog
-- Pick up tasks, write code, run tests, and deploy
-- Hand off work between agents without losing context
-- Lock files to prevent concurrent edits
-- Enforce conventions via git hooks
+---
 
-No coding knowledge required. You describe what you want to build — Kortext agents handle the rest.
+## What v3 gives you
+
+- **A TypeScript runtime**. Single `kortext` binary. Express 5 backend, React
+  19 + Tailwind v4 dashboard, `better-sqlite3` state store.
+- **A worker pool with per-task git worktrees**. Every task runs in its own
+  `.kortext/worktrees/run-<id>` branch. Failures get quarantined for
+  postmortem; successes can be merged.
+- **A blueprint-driven pipeline**. Flip `status: draft` → `status: approved`
+  in `workspace/references/blueprint.md` and the analysis → planning →
+  development → testing chain starts on its own.
+- **First-class approvals**. Critical gates queue into `pending_questions`;
+  the dashboard rings a bell, a toast pops, Slack / Telegram fires. Answer
+  from the UI, the CLI, or an MCP client.
+- **An MCP server**. 15 tools over stdio (for Claude Code / Cursor) and SSE
+  (for the dashboard or remote clients).
+- **263 tests**, GitHub Actions CI on every push and PR.
 
 ---
 
-## Quick Start
+## Quick start
+
+Requires **Node ≥ 22** and **Git ≥ 2.30**.
 
 ```bash
-# Install (one-time, global)
+# Install
 npm install -g kortext
 
-# In your project directory
+# Scaffold a v3 project (idempotent — safe to re-run)
+mkdir my-product && cd my-product
 kortext init
 
-# Fill in the blueprint (describes your product)
-# .kortext/workspace/references/blueprint.md
+# Edit the blueprint
+$EDITOR workspace/references/blueprint.md
+# (set `status: approved` in the YAML frontmatter when ready)
+
+# Start the runtime (backend + dashboard)
+kortext serve
+# → backend: http://localhost:3200
+# → dashboard: http://localhost:5173
+```
+
+When the blueprint flips to `approved`, the orchestrator triggers the
+analysis workflow automatically. Watch the dashboard, answer any approval
+prompts that surface in the bell menu, and the rest runs on its own.
+
+---
+
+## CLI surface
 
-# Then tell your AI agent:
-# !start analysis
+```
+kortext init [--force]                  scaffold .kortext/, agents/, workflows/, rules/, workspace/
+kortext serve [--mode=auto|dev|prod]    backend + dashboard
+kortext start <workflow-id> [--executor=mock|claude|codex|gemini]
+kortext approve <run-id> [answer]       respond to a pending question
+kortext status                          recent runs + open questions
+kortext logs [--limit=N] [--actor=…] [--action=…]
+kortext cleanup [--quarantine-older-than=Nd] [--branches] [--dry-run]
+kortext doctor                          workflow / persona / lock consistency
+kortext mcp                             stdio MCP server (for Claude Code / Cursor)
+kortext --help | --version
 ```
 
 ---
@@ -41,55 +81,105 @@ kortext init
 ## Architecture
 
 ```
-proje/
-├── AGENTS.md              # AI runtime entry point (auto-generated by kortext init)
-└── .kortext/              # All framework files live here (like .git/)
-    ├── agents/            # 14 persona definitions
-    ├── workflows/         # 12 workflow pipelines
-    ├── hooks/             # 16 git + runtime hooks
-    ├── scripts/           # 13 Python automation scripts
-    ├── rules/             # Behavior rules, commands, branching strategy
-    ├── settings/          # Config, runtime adapters, INTEGRATION-MAP
-    ├── skills/            # Per-persona skill folders
-    └── workspace/         # Memory, backlog, references, templates, reports
-        ├── references/
-        │   └── blueprint.md   # ← You fill this in
-        └── memory/
-            ├── backlog/       # Tasks live here
-            └── context/       # Active agent files
+┌──────────────────────────────────────────────────────────────────────┐
+│  React Dashboard (Vite + TanStack Router + Tailwind v4)              │
+│  Dashboard · Board · Memory · Reports · References · Settings        │
+└────────────────────┬─────────────────────────────────────────────────┘
+                     │  HTTP / WebSocket
+┌────────────────────▼─────────────────────────────────────────────────┐
+│  Express 5 backend                                                    │
+│  /api/runs · /api/handovers · /api/backlog · /api/personas (GET/PUT)  │
+│  /api/workflows · /api/doctor · /api/docs/:scope · /api/questions     │
+│  /mcp/sse · /mcp/messages         ┌──────────────────────────┐        │
+└─────────────────┬─────────────────┤  MCP server (15 tools)   │        │
+                  │                 │  stdio · SSE             │        │
+                  │                 └──────────────────────────┘        │
+┌─────────────────▼─────────────────────────────────────────────────────┐
+│  Orchestrator                                                          │
+│  Blueprint watcher · Pipeline chainer · Approval queue · Dispatcher    │
+└─────────────────┬──────────────────────────────────────────────────────┘
+                  │
+┌─────────────────▼─────────────────────────────────────────────────────┐
+│  Pipeline engine                                                       │
+│  Workflow parser · DAG builder · Worker pool · Gate enforcer · Safety  │
+└──────┬─────────────────────────────────────────────────────┬───────────┘
+       │                                                     │
+┌──────▼──────────────────────┐               ┌──────────────▼──────────┐
+│  Per-run git worktrees      │               │  SQLite state           │
+│  .kortext/worktrees/run-<id>│               │  .kortext/kortext.db    │
+│  branch kortext/run-<id>    │               │  13 tables · WAL mode   │
+└──────┬──────────────────────┘               └─────────────────────────┘
+       │
+┌──────▼─────────────────────────────────────────────────────────────────┐
+│  CLI executors                                                          │
+│  Claude Code · Codex · Gemini CLI (shell-free spawn, stdin prompts)     │
+└─────────────────────────────────────────────────────────────────────────┘
 ```
 
+See [docs/architecture.md](./docs/architecture.md) for the long form (SQLite
+schema, DAG semantics, worker-pool concurrency rules).
+
 ---
 
-## Supported Runtimes
+## Project layout
+
+```
+your-project/
+├── AGENTS.md                       # AI runtime pointer (generated)
+├── .kortext/
+│   ├── kortext.db                  # SQLite state
+│   └── worktrees/                  # per-run git worktrees
+├── workspace/
+│   └── references/
+│       └── blueprint.md            # ← you fill this in
+├── agents/                         # 14 persona markdowns
+├── workflows/                      # 12 workflow markdowns
+└── rules/                          # behavior, branching, commands, emergency, models
+```
+
+Personas, workflows, and rules are **markdown** — edit them in any editor or
+in the dashboard. SQLite holds the runtime state (runs, backlog, audit log,
+approvals).
+
+---
+
+## Integrations
+
+### Claude Code
+
+```bash
+claude mcp add kortext -- npx kortext mcp
+```
+
+Once added, Claude Code can call `start_pipeline`, `list_pending_questions`,
+`approve_blueprint`, and 12 other tools directly.
+
+### Slack / Telegram
+
+Set `SLACK_WEBHOOK_URL` and / or `TELEGRAM_BOT_TOKEN` + `TELEGRAM_CHAT_ID` in
+your environment. The dispatcher dedupes notifications and posts on:
 
-| Runtime | Hook Integration |
-|---|---|
-| **Claude Code** | PreToolUse / PostToolUse / SessionStart |
-| **Gemini CLI** | preToolCall / postToolCall |
-| **Codex / Generic** | AGENTS.md baseline |
+- Blueprint approval
+- Pipeline start / completion
+- Step failure
+- Pending question waiting for `+prime`
 
 ---
 
-## Key Commands
+## Documentation
 
-| Command | What happens |
-|---|---|
-| `kortext init` | Set up hooks + runtime adapter in your project |
-| `kortext help` | List all available commands |
-| `!start analysis` | Agent team analyzes your blueprint |
-| `!start planning` | Agent team builds your backlog |
-| `!start development` | Agents pick tasks and start coding |
-| `kortext status` | Show active sessions and locks |
-| `kortext health` | Check backlog and context consistency |
+- [User Guide](./USER-GUIDE.md) — full walkthrough of the autonomous flow
+- [Architecture](./docs/architecture.md) — schema, engine, MCP, dashboard
+- [Changelog](./CHANGELOG.md) — release notes
 
 ---
 
 ## Requirements
 
-- Node.js ≥ 14
-- Python ≥ 3.10
-- Git
+- Node ≥ 22.0.0
+- Git ≥ 2.30 (worktree subcommands)
+- One of: Claude Code, Codex, or Gemini CLI installed and on `$PATH`
+  (or use `--executor=mock` for dry runs)
 
 ---