102 lines
4.6 KiB
Markdown
102 lines
4.6 KiB
Markdown
## ADDED Requirements
|
|
|
|
### Requirement: JSON output format for search
|
|
The system SHALL output search results as JSON when `--format json` is used (this is the default). The JSON schema SHALL include: `query`, `results` array, `total_matches`, and `returned` count. Each result SHALL include: `chunk_id`, `score`, `score_breakdown` (with `fts` and `vector` sub-scores), `text`, and `source` object.
|
|
|
|
#### Scenario: JSON search output
|
|
- **WHEN** user runs `kb search "install git" --format json`
|
|
- **THEN** the output is valid JSON matching this structure:
|
|
```json
|
|
{
|
|
"query": "install git",
|
|
"results": [
|
|
{
|
|
"chunk_id": 1423,
|
|
"score": 0.031,
|
|
"score_breakdown": {"fts": 0.016, "vector": 0.015},
|
|
"text": "To install the latest version...",
|
|
"source": {
|
|
"document_id": 42,
|
|
"title": "Git Admin Guide",
|
|
"path": "/home/user/docs/git-admin.pdf",
|
|
"type": "pdf",
|
|
"page": 12,
|
|
"chunk_index": 3,
|
|
"total_chunks": 28,
|
|
"tags": ["git", "admin"]
|
|
}
|
|
}
|
|
],
|
|
"total_matches": 47,
|
|
"returned": 10
|
|
}
|
|
```
|
|
|
|
#### Scenario: Score breakdown in FTS-only mode
|
|
- **WHEN** user runs `kb search "test" --fts-only --format json`
|
|
- **THEN** `score_breakdown` contains `{"fts": <score>, "vector": null}`
|
|
|
|
#### Scenario: Score breakdown in vector-only mode
|
|
- **WHEN** user runs `kb search "test" --vec-only --format json`
|
|
- **THEN** `score_breakdown` contains `{"fts": null, "vector": <score>}`
|
|
|
|
### Requirement: Human-readable output format
|
|
The system SHALL support human-readable output via `--format human`. This format SHALL show: query, match count, and for each result: rank, score, title, page/section (if applicable), type, tags, and a text preview.
|
|
|
|
#### Scenario: Human-readable search output
|
|
- **WHEN** user runs `kb search "install git" --format human`
|
|
- **THEN** output is formatted for terminal reading:
|
|
```
|
|
Search: "install git" (47 matches, showing top 10)
|
|
|
|
1. [0.031] Git Admin Guide (p.12) [pdf] [git, admin]
|
|
To install the latest version of git from source...
|
|
|
|
2. [0.025] setup-notes.md §Installation [markdown] [git]
|
|
First, add the PPA repository for the latest git...
|
|
```
|
|
|
|
### Requirement: JSON output for list and tags commands
|
|
The system SHALL support `--format json` for `kb list`, `kb tags`, `kb info`, and `kb status` commands. JSON output SHALL be valid and parseable by the skill wrapper.
|
|
|
|
#### Scenario: List documents as JSON
|
|
- **WHEN** user runs `kb list --format json`
|
|
- **THEN** output is a JSON array of document objects with `id`, `title`, `type`, `tags`, `chunk_count`, `created_at`
|
|
|
|
#### Scenario: Tags as JSON
|
|
- **WHEN** user runs `kb tags --format json`
|
|
- **THEN** output is a JSON array: `[{"name": "git", "count": 15}, ...]`
|
|
|
|
#### Scenario: Status as JSON
|
|
- **WHEN** user runs `kb status --format json`
|
|
- **THEN** output is a JSON object with `documents` (counts by type), `total_chunks`, `db_size_bytes`, `model_name`, `embedding_dim`, `schema_version`
|
|
|
|
### Requirement: JSON schema stability
|
|
The JSON output schema SHALL be treated as a public contract. Fields MAY be added to JSON objects in future versions. Fields SHALL NOT be removed or renamed. The skill wrapper MUST be able to rely on the presence and type of all documented fields.
|
|
|
|
#### Scenario: Forward compatibility
|
|
- **WHEN** a future version adds a `language` field to search results
|
|
- **THEN** all existing fields remain present and unchanged, the new field is additive only
|
|
|
|
### Requirement: Exit codes
|
|
The system SHALL use consistent exit codes: 0 for success, 1 for user errors (bad arguments, missing files), 2 for system errors (database corruption, model failure). JSON error output SHALL include an `error` field with a human-readable message.
|
|
|
|
#### Scenario: Successful operation
|
|
- **WHEN** any command completes successfully
|
|
- **THEN** exit code is 0
|
|
|
|
#### Scenario: User error with JSON output
|
|
- **WHEN** user runs `kb search` with no query argument
|
|
- **THEN** exit code is 1 and stderr contains a clear error message
|
|
|
|
#### Scenario: System error
|
|
- **WHEN** the SQLite database is corrupted
|
|
- **THEN** exit code is 2 and stderr contains the error details
|
|
|
|
### Requirement: Skill definition file
|
|
The project SHALL include a `SKILL.md` file that defines how an LLM tool (e.g. Claude Code) should invoke and interpret `kb` commands. The skill file SHALL document: when to use the tool, available commands, output format, how to cite sources, and how to handle low-confidence results.
|
|
|
|
#### Scenario: Skill file exists
|
|
- **WHEN** the project is built
|
|
- **THEN** a `SKILL.md` file exists at the project root describing the skill interface for LLM consumption
|