# Repo Memory Markdown Test Plan

## Purpose

This directory contains the human-readable Markdown test plan for the
`repo-memory` CLI.

It complements package-level Go tests. The goal is to preserve the user-visible
command contract in a form that can be reviewed, extended, and replayed without
re-deriving behavior from implementation code.

## Directory Rules

- one folder per `repo-memory` command or shared area
- each folder keeps a `README.md` entrypoint
- command folders use `README.md` as an index only
- each command test case lives in its own Markdown file named after the case slug
- no numeric test IDs
- each command case is identified by its concrete file path

Case file naming pattern:

```text
<case-slug>.md
```

## Authoring Principles

- focus on externally visible CLI behavior rather than store internals
- prefer stable command sequences that a new agent can replay against a temp repo and SQLite DB
- document both success contracts and failure boundaries
- reuse scenarios from existing Go tests before inventing new cases
- keep terminology consistent with the CLI: repo, entry, alias, dependency, event, verify, stale, and needs_review

## Common Execution Model

Most cases in this directory assume the same baseline:

1. create an isolated temporary directory
2. create a Git repository fixture such as `TMPDIR/repo`
3. choose a database path such as `TMPDIR/repo-memory.db`
4. run `repo-memory init --db TMPDIR/repo-memory.db`
5. run the target command sequence against that database and repository

Unless a case says otherwise:

- assertions should check both exit code and human-readable stdout or stderr
- repo-scoped cases should use an actual Git repo so `verified_on_commit` and repo registration are meaningful
- `add` and `ingest` may bootstrap schema automatically, but most read commands assume `init` already ran

## Folder Map

- `README.md`: global conventions and glossary
- `ROADMAP.md`: document progress, planned case backlog, and authored-case register
- `_shared/README.md`: reusable fixtures, output assertions, exit-code rules, and repo conventions
- `workflows/README.md`: cross-command end-to-end scenarios
- per-command folders: command-specific index `README.md` files plus one case document per test case

## Glossary

- `repo`: one tracked repository root stored in the memory database
- `entry`: one durable knowledge record keyed by repo, kind, key, and optional scope
- `alias`: an alternate search term attached to one entry
- `dependency`: a file, dir, or glob evidence locator used during verification
- `event`: a historical record such as `created`, `updated`, `downgraded`, or `marked_stale`
- `needs_review`: knowledge that may still be useful but should be re-checked
- `stale`: knowledge that no longer has valid hard evidence and should not be treated as current

## Relationship To Automated Tests

The current executable references are:

- [init_integration_test.go](../../../packages/repo-memory-runtime/cmd/repo-memory/init_integration_test.go) for `init`
- [add_integration_test.go](../../../packages/repo-memory-runtime/cmd/repo-memory/add_integration_test.go) for `add`
- [ingest_integration_test.go](../../../packages/repo-memory-runtime/cmd/repo-memory/ingest_integration_test.go) for `ingest`
- [search_integration_test.go](../../../packages/repo-memory-runtime/cmd/repo-memory/search_integration_test.go) for `search`
- [list_integration_test.go](../../../packages/repo-memory-runtime/cmd/repo-memory/list_integration_test.go) for `list`
- [events_integration_test.go](../../../packages/repo-memory-runtime/cmd/repo-memory/events_integration_test.go) for `events`
- [link_integration_test.go](../../../packages/repo-memory-runtime/cmd/repo-memory/link_integration_test.go) for `link`
- [verify_integration_test.go](../../../packages/repo-memory-runtime/cmd/repo-memory/verify_integration_test.go) for `verify`
- [repos_integration_test.go](../../../packages/repo-memory-runtime/cmd/repo-memory/repos_integration_test.go) for `repos`
- [workflow_integration_test.go](../../../packages/repo-memory-runtime/cmd/repo-memory/workflow_integration_test.go) for the four documented workflow cases
- [store_test.go](../../../packages/repo-memory-runtime/internal/store/store_test.go) for import, search, alias, dependency, link, and verification-state transitions
- [load_test.go](../../../packages/repo-memory-runtime/internal/documents/load_test.go) for markdown parsing
- [main_test.go](../../../packages/repo-memory-runtime/cmd/repo-memory/main_test.go) for verify downgrade heuristics

These tests do not replace the Markdown plan. They are the executable companion
to it.

When this Markdown plan expands:

- prefer matching an existing automated scenario first
- record any additional manual-only CLI contract coverage explicitly in the relevant command case file
- keep [ROADMAP.md](./ROADMAP.md) synchronized with authored files and case slugs