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:

<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:

create an isolated temporary directory
create a Git repository fixture such as TMPDIR/repo
choose a database path such as TMPDIR/repo-memory.db
run repo-memory init --db TMPDIR/repo-memory.db
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:

store_test.go for import, search, alias, dependency, link, and verification-state transitions
load_test.go for markdown parsing
main_test.go for verify downgrade heuristics

These tests do not replace the Markdown plan. They only reduce discovery work.

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 synchronized with authored files and case slugs