# Repo Memory Shared Test Conventions

## Purpose

This document captures shared assumptions used by multiple `repo-memory`
test-plan documents so command and workflow files can stay focused on behavior
instead of repeating setup boilerplate.

## Recommended Fixture Shape

Use an isolated temp workspace per case:

- database path: `TMPDIR/repo-memory.db`
- repository path: `TMPDIR/repo`
- optional second repository path: `TMPDIR/repo-b`
- default ingest path: `TMPDIR/repo/docs/ai`
- optional evidence file: `TMPDIR/repo/path/to/file`

Recommended bootstrap command:

```bash
repo-memory init --db TMPDIR/repo-memory.db
```

Recommended repo bootstrap for Git-aware cases:

```bash
git -C TMPDIR/repo init
git -C TMPDIR/repo config user.email test@example.com
git -C TMPDIR/repo config user.name Tester
git -C TMPDIR/repo add .
git -C TMPDIR/repo commit -m "init"
```

## Flag Model

`repo-memory` uses one subcommand-specific flag set per command. There is no
root `--json` mode and no shared global flag parser.

Common flags across multiple commands:

- `--db`: SQLite database path
- `--repo`: repository root or repo-path substring filter depending on command
- `--limit`: result limit on read commands

Case files should call out whether `--repo` is:

- a required absolute repo root for `add` and `ingest`
- an optional substring filter for `search` and `list`
- an optional absolute repo root selector for `verify`

## Text Output Contract

Successful output is plain text written to stdout.

Shared assertion guidance:

- assert stable prefixes or phrases, not timestamp values
- prefer checking identifiers, kinds, keys, statuses, and count summaries
- when output contains absolute repo paths, compare against the concrete fixture path used by the case

Representative success phrases:

- `initialized TMPDIR/repo-memory.db`
- `upserted entry 1 (term:AITask)`
- `ingested 1 docs from ABS_REPO`
- `linked #1 -[related_to]-> #2`
- `ABS_REPO: verified 1 entries, 1 downgraded, 0 stale`
- `no results`
- `no entries`
- `no repos`

## Exit Code Contract

The current CLI contract uses these exit codes:

| Exit Code | Meaning | Typical Trigger |
| --- | --- | --- |
| `0` | success | command completed normally, including empty-result text such as `no results` |
| `1` | command failure | invalid flags, missing required values, missing repo docs, unresolved entry, or store/runtime error |
| `2` | top-level usage failure | missing subcommand or unknown subcommand |

When a case expects failure, assert both the non-zero exit code and the human-readable stderr message.

## Schema Bootstrap Rules

Current command behavior is intentionally uneven and should be documented:

- `init` creates schema explicitly
- `add` and `ingest` call `Init` internally and can succeed on a fresh DB path
- `search`, `list`, `events`, `link`, `verify`, and `repos` assume schema already exists

If a case relies on automatic schema bootstrap in `add` or `ingest`, state that explicitly in `前置条件` and `断言结论`.

## Repo Fixture Rules

Cases covering `add`, `ingest`, or `verify` should state:

- whether the target repo is a real Git repo
- whether a HEAD commit already exists
- which file path is being used as evidence or dependency

`verify` behavior depends on Git state:

- if a repo has a readable HEAD commit, verification updates repo metadata and evaluates dependencies
- if a repo is missing Git state or has no HEAD, the command prints `skipped (not a git repo or no HEAD)` for that repo

## Markdown Ingest Rules

`ingest` scans markdown recursively under `docs/ai` by default.

Shared assertions for ingest cases:

- `.md` files are discovered recursively
- file base name influences imported key prefixes
- heading text influences imported `kind` classification and key slug
- an empty `docs/ai` tree fails with `no markdown files found under ...`

## Direct DB Inspection

Most cases should stay at the CLI contract level.

One exception is `link`: the CLI currently writes the relation but does not have
an inspection command for links. Link cases may use a read-only `sqlite3` query
to confirm persistence after the CLI call.

Typical example:

```bash
sqlite3 TMPDIR/repo-memory.db "SELECT relation FROM knowledge_links WHERE from_entry_id = 1 AND to_entry_id = 2;"
```

## Workflow Authoring Rule

If a case spans multiple commands, place the end-to-end narrative in
`workflows/README.md` first, then add narrower command-level cases only when
they are easier to reason about in isolation.