# cortex-cli

A TypeScript CLI for managing software project artifacts — sprints, kanban boards, knowledge graphs, documents, reviews, and traceability — backed by SQLite with safe concurrent multi-process access.

[![npm version](https://img.shields.io/npm/v/@lwelliott/cortex-cli.svg)](https://www.npmjs.com/package/@lwelliott/cortex-cli) [![license](https://img.shields.io/npm/l/@lwelliott/cortex-cli.svg)](https://github.com/lwelliot/cortex-cli/blob/main/LICENSE)

> **Latest release:** v1.0.8 — [Release notes](releases/release-notes-1.0.8.md)

## Installation

### From npm (recommended)

```bash
npm install -g @lwelliott/cortex-cli
```

### From source

```bash
git clone https://github.com/lwelliot/cortex-cli.git
cd cortex-cli
npm install
npm run build
```

### Verify installation

```bash
cortex-cli --version
cortex-cli --help
```

## Quick Start

```bash
# Initialize a project
cortex-cli project init my-project

# Create and start a sprint
cortex-cli --project my-project sprint init sprint-001 --name "My Sprint"
cortex-cli --project my-project sprint set-status sprint-001 --status "IN EXECUTION"

# Add and manage tasks
cortex-cli --project my-project task add --sprint sprint-001 --content-file /tmp/task.md --owner captain
cortex-cli --project my-project task move 0001 --to "In Progress" --stage Implementation --owner coder
cortex-cli --project my-project task move 0001 --to "In Review" --owner master

# Validate the board
cortex-cli --project my-project validate board --sprint sprint-001

# Close sprint
cortex-cli --project my-project sprint set-status sprint-001 --status CLOSED
```

## Project Resolution

Every command requires an explicit project. Resolution follows this priority order:

1. `--project <name>` flag — highest priority; if specified but the name is not found in the registry, the command fails immediately (short-circuit — no fall-through to CWD match)
2. Current working directory match — if the CWD is within a registered project directory, that project is used
3. If neither method resolves a project, the command fails with an error instructing the user to use `--project <name>` or run from a registered project directory

There is no longer a default project concept.

## Commands

### Project Management

| Command | Description |
|---------|-------------|
| `project init <name>` | Initialize a new project with SQLite database |
| `project info <name>` | Display project overview and sprint summary |
| `project list` | List all registered projects |
| `project remove <name>` | Remove a project |

### Sprint Lifecycle

| Command | Description |
|---------|-------------|
| `sprint init <id>` | Create a new sprint (PLANNING state) |
| `sprint set-status <id>` | Transition sprint status (PLANNING, IN EXECUTION, CLOSING, CLOSED) |
| `sprint overview [id]` | Display sprint overview and task breakdown |
| `sprint update [id]` | Update sprint name or goal |
| `sprint list` | List all sprints |

### Task Management

| Command | Description |
|---------|-------------|
| `task add [id]` | Add task to sprint (content via `--content-file`) |
| `task move <id>` | Move task status/stage (requires `--to`, `--stage`, `--owner`) |
| `task move <id> --dry-run` | Preview move without committing |
| `task update <id>` | Update task metadata |
| `task remove <id>` | Permanently delete a task |
| `task show <id>` | Display task details |
| `task list` | List tasks in a sprint |

### Document Registry

| Command | Description |
|---------|-------------|
| `doc add <id> --type --title` | Register documents (inline or file-based content) |
| `doc list [--type]` | List documents with pagination and sorting |
| `doc show <id>` | Display document details |
| `doc search <query>` | FTS5 full-text search with ranking |
| `doc update <id>` / `doc remove <id>` | Modify or remove document registrations |

### Knowledge Graph

| Command | Description |
|---------|-------------|
| `graph validate` | Check graph integrity |
| `graph status` | Show graph schema status |
| `graph entity create/get/query/update/delete` | Entity CRUD |
| `graph relation relate/unrelate/related` | Relation management |
| `graph export` | Export graph data |
| `graph migrate [--phase]` | Run schema migration |

Schema is auto-initialized from `project-schema.yaml` during `project create` with 18 relation types and entity types derived from doc types.

### Audit & Traceability

| Command | Description |
|---------|-------------|
| `audit` | Run all 11 audit checks (4 integrity + 7 traceability) |
| `audit --checks <name,...>` | Run specific checks |
| `audit --fix` | Auto-fix supported issues |
| `audit --fix-dry-run` | Preview fixes without applying |

**Traceability checks:**
- `us-to-fr-nfr` — US→FR/NFR traceability
- `fr-nfr-to-fs-nfs` — FR/NFR→FS/NFS traceability
- `fs-nfs-to-sad-ad-qa` — FS/NFS→SAD/AD/QA traceability
- `fs-nfs-to-ts` — FS/NFS→TS traceability
- `ts-to-tc` — TS→TC traceability
- `sad-ad-qa-tc-to-src` — SAD/AD/QA/TC→SRC traceability
- `src-filesystem-only` — SRC files exist on filesystem

### Review & Reporting

| Command | Description |
|---------|-------------|
| `review add <id>` | Create reviews with positional ID |
| `review list [--sprint]` / `review show <id>` | Browse review records |
| `review remove <id>` | Permanently delete a review |
| `test-report add <id>` | Record test execution results |
| `test-report list` / `test-report show <id>` | Browse test reports |
| `test-report remove <id>` | Permanently delete a test report |
| `lesson update` | Record and update lessons learned |

### Board Validation

| Command | Description |
|---------|-------------|
| `validate board` | Check board shape, integrity, and state fields |
| `validate spawn --sprint --task --stage --role` | Validate spawn legality |

## Output Formats

All commands support multiple output formats:

```bash
cortex-cli --project my-project project info my-project --format json
cortex-cli --project my-project task list --format table
cortex-cli --project my-project task show 0001 --format markdown
cortex-cli --project my-project task list --quiet
cortex-cli --project my-project task list --json
```

Precedence: `--quiet` > `--format` > `--json`

## Kanban States

**Sprint lifecycle:**

```
PLANNING → IN EXECUTION → CLOSING → CLOSED
```

**Task stages (6 consolidated stages):**

```
Planning → Requirement+Specification → Design → Implementation → Testing → Release
```

**Task status lifecycle (restricted transitions):**

```
Backlog → To Do → In Progress → In Review → Done
   ↕        ↕         ↕             ↕          ↕
  To Do   Backlog    To Do         To Do    In Progress
Dropped  Dropped   In Review    In Progress  In Review
                    Dropped       Dropped     Dropped
```

- All stage, status, and role names are case-insensitive
- Stage transitions are free (forward, backward, and same-stage all allowed)
- Dropped tasks can be recovered (Dropped → Backlog or To Do)

## Global Options

| Option | Description |
|--------|-------------|
| `-p, --project <name>` | Target a specific project (required unless CWD is in a registered project directory) |
| `--sprint <id>` | Scope to a sprint |
| `--format <type>` | Output format: table, json, markdown, quiet |
| `--json` | Shorthand for `--format json` |
| `--quiet` | Minimal output |
| `--dry-run` | Preview task move without committing |
| `-V, --version` | Print version |
| `-h, --help` | Display help |

## Development

```bash
npm install            # Install dependencies
npm run build          # TypeScript compilation
npm run build:release  # Build single-file release binary
npm test               # Run test suite (1065 tests)
npm run lint            # Type-check only
```

## License

[MIT](https://github.com/lwelliot/cortex-cli/blob/main/LICENSE)