ai-workflow-skill/docs/tests/repo-memory/README.md

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:

<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 for init
• add_integration_test.go for add
• ingest_integration_test.go for ingest
• search_integration_test.go for search
• list_integration_test.go for list
• events_integration_test.go for events
• link_integration_test.go for link
• verify_integration_test.go for verify
• repos_integration_test.go for repos
• workflow_integration_test.go for the four documented workflow cases
• 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 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 synchronized with authored files and case slugs