kurihada/ai-workflow-skill

Fork 0

Files

T

kurihada 9915e12a30 Add repo-memory integration tests

2026-03-20 16:01:48 +08:00

19 KiB

Raw Blame History

Repo Memory Test Documentation Roadmap

Purpose

This roadmap tracks the human-readable Markdown test plan for repo-memory.

It exists so a new agent can immediately answer four questions without re-reading the whole codebase:

which test-plan documents already exist
which cases have already been written down
which cases are still missing
what file should be updated next

This roadmap is for the Markdown test-plan set under docs/tests/repo-memory/. It is not a replacement for automated Go tests.

Current Snapshot

Snapshot date:

2026-03-20

Current state:

repo-memory CLI is implemented for init, add, ingest, search, list, events, link, verify, and repos
package-local automated Go tests now cover every currently documented repo-memory command case and workflow case through dedicated CLI integration tests, plus the existing markdown parser and store-level tests
this roadmap now exists under docs/tests/repo-memory/ROADMAP.md
all planned global, shared, workflow, command-index, and command-case Markdown documents in the current repo-memory test-plan set have been authored
each implemented repo-memory command folder now uses README.md as an index plus one Markdown file per planned case
docs/tests/repo-memory-skill/ can now stay focused on skill-forward behavior while docs/tests/repo-memory/ owns direct CLI contract coverage
a follow-up edge audit on 2026-03-20 identified seven additional boundary cases, and those cases are now authored in the Markdown plan
verify automation also exposed and fixed a store-level deadlock in ListVerifyCandidates, so the documented verify workflows now execute end-to-end in tests

Progress summary for planned test-plan documents, excluding ROADMAP.md:

planned document files: 39
authored document files: 39
planned case slugs in this roadmap: 31
authored case slugs in this roadmap: 31

Scope

In scope:

repo-memory init
repo-memory add
repo-memory ingest
repo-memory search
repo-memory list
repo-memory events
repo-memory link
repo-memory verify
repo-memory repos
cross-command workflows
shared test conventions for text output, exit codes, temp repos, repo fixtures, and read-only DB inspection where the CLI has no inspection surface

Out of scope:

skills/repo-memory/ forward execution behavior except as a related reference
implementation details that are not visible through the repo-memory CLI contract
future commands that are not currently implemented

Tracking Rules

Directory model:

one folder per command or shared area
each folder keeps a README.md entrypoint
command folders use README.md as an index only
each command case lives in its own Markdown file named after the case slug
cross-command workflow cases remain grouped in docs/tests/repo-memory/workflows/README.md

Case identity:

do not use numeric IDs
identify each command case by its concrete file path
identify each workflow case by path + case slug
command case file naming pattern:

<case-slug>.md

workflow case heading pattern:

## case: add-search-events-roundtrip

Per-case structure inside the case document:

用例意义
前置条件
输入
预期输出
断言结论

How to update this roadmap when a new case is written:

if it is a command case, create or update the target <case-slug>.md file under the relevant command folder
if it is a command case, add or update the entry in that folder README.md index
if it is a workflow case, add or update the case inside docs/tests/repo-memory/workflows/README.md
move the case slug from Pending Case Backlog to Authored Case Register
update the authored counts in Current Snapshot
if a new Markdown file is created, update Document Progress

Allowed status values in this roadmap:

pending
in_progress
done
deferred

Existing Automated Coverage Reference

The Markdown test-plan set starts from explicit CLI contract docs, but these automated tests already exist and should be used as source material when writing the docs:

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 documented workflow cases
store_test.go TestImportDocumentAndSearch
store_test.go TestUpsertEntryWithAliasesAndDependencies
store_test.go TestApplyVerificationResult
load_test.go TestParseFile
main_test.go TestVerifyCandidateDetectsFileChange
main_test.go TestVerifyCandidateMarksMissingDependencyStale

These tests do not remove the need for the Markdown plan. They only reduce discovery work.

Planned Directory Tree

docs/tests/repo-memory/
  ROADMAP.md
  README.md
  _shared/
    README.md
  workflows/
    README.md
  init/
    README.md
    <case-slug>.md
  add/
    README.md
    <case-slug>.md
  ingest/
    README.md
    <case-slug>.md
  search/
    README.md
    <case-slug>.md
  list/
    README.md
    <case-slug>.md
  events/
    README.md
    <case-slug>.md
  link/
    README.md
    <case-slug>.md
  verify/
    README.md
    <case-slug>.md
  repos/
    README.md
    <case-slug>.md

Document Progress

Path	Purpose	Planned Cases	Authored Cases	Status
`docs/tests/repo-memory/README.md`	Global testing conventions and glossary	0	0	done
`docs/tests/repo-memory/_shared/README.md`	Shared fixtures, output assertions, exit codes, and repo rules	0	0	done
`docs/tests/repo-memory/workflows/README.md`	Cross-command scenarios	4	4	done
`docs/tests/repo-memory/init/README.md`	`init` command case index	0	0	done
`docs/tests/repo-memory/init/init-creates-schema-on-empty-db.md`	`init` command case	1	1	done
`docs/tests/repo-memory/init/init-is-idempotent-on-existing-db.md`	`init` command case	1	1	done
`docs/tests/repo-memory/add/README.md`	`add` command case index	0	0	done
`docs/tests/repo-memory/add/add-registers-repo-and-entry.md`	`add` command case	1	1	done
`docs/tests/repo-memory/add/add-updates-existing-entry-on-same-kind-and-key.md`	`add` command case	1	1	done
`docs/tests/repo-memory/add/add-failed-validation-still-registers-repo.md`	`add` command case	1	1	done
`docs/tests/repo-memory/ingest/README.md`	`ingest` command case index	0	0	done
`docs/tests/repo-memory/ingest/ingest-imports-docs-ai-markdown.md`	`ingest` command case	1	1	done
`docs/tests/repo-memory/ingest/ingest-rejects-when-no-markdown-found.md`	`ingest` command case	1	1	done
`docs/tests/repo-memory/ingest/ingest-imports-headingless-markdown-as-single-entry.md`	`ingest` command case	1	1	done
`docs/tests/repo-memory/search/README.md`	`search` command case index	0	0	done
`docs/tests/repo-memory/search/search-returns-matching-entry-snippet.md`	`search` command case	1	1	done
`docs/tests/repo-memory/search/search-matches-alias-with-repo-filter.md`	`search` command case	1	1	done
`docs/tests/repo-memory/search/search-returns-no-results-when-empty.md`	`search` command case	1	1	done
`docs/tests/repo-memory/search/search-rejects-missing-query.md`	`search` command case	1	1	done
`docs/tests/repo-memory/list/README.md`	`list` command case index	0	0	done
`docs/tests/repo-memory/list/list-filters-by-kind-and-status.md`	`list` command case	1	1	done
`docs/tests/repo-memory/list/list-returns-no-entries-when-empty.md`	`list` command case	1	1	done
`docs/tests/repo-memory/events/README.md`	`events` command case index	0	0	done
`docs/tests/repo-memory/events/events-reads-history-by-id.md`	`events` command case	1	1	done
`docs/tests/repo-memory/events/events-resolves-entry-by-repo-kind-key.md`	`events` command case	1	1	done
`docs/tests/repo-memory/events/events-rejects-missing-entry-selector.md`	`events` command case	1	1	done
`docs/tests/repo-memory/link/README.md`	`link` command case index	0	0	done
`docs/tests/repo-memory/link/link-creates-relation-between-entries.md`	`link` command case	1	1	done
`docs/tests/repo-memory/link/link-rejects-missing-relation.md`	`link` command case	1	1	done
`docs/tests/repo-memory/link/link-rejects-when-entry-id-missing.md`	`link` command case	1	1	done
`docs/tests/repo-memory/verify/README.md`	`verify` command case index	0	0	done
`docs/tests/repo-memory/verify/verify-downgrades-changed-file-dependency.md`	`verify` command case	1	1	done
`docs/tests/repo-memory/verify/verify-marks-missing-hard-dependency-stale.md`	`verify` command case	1	1	done
`docs/tests/repo-memory/verify/verify-prints-no-repos-when-empty.md`	`verify` command case	1	1	done
`docs/tests/repo-memory/verify/verify-skips-explicit-repo-without-git-head.md`	`verify` command case	1	1	done
`docs/tests/repo-memory/verify/verify-downgrades-entry-missing-verified-on-commit.md`	`verify` command case	1	1	done
`docs/tests/repo-memory/repos/README.md`	`repos` command case index	0	0	done
`docs/tests/repo-memory/repos/repos-lists-tracked-repositories.md`	`repos` command case	1	1	done
`docs/tests/repo-memory/repos/repos-prints-no-repos-when-empty.md`	`repos` command case	1	1	done

Authoring Order

Recommended order:

docs/tests/repo-memory/README.md
docs/tests/repo-memory/_shared/README.md
docs/tests/repo-memory/workflows/README.md
docs/tests/repo-memory/add/README.md plus its linked case files
docs/tests/repo-memory/ingest/README.md plus its linked case files
docs/tests/repo-memory/search/README.md plus its linked case files
docs/tests/repo-memory/verify/README.md plus its linked case files
the remaining command indexes and case files

Reason:

the workflow file captures the highest-value repo-memory lifecycle behavior first
command documents can then reuse shared conventions and already-fixed terminology

Edge Audit Notes

Per-command review status after auditing the current CLI source and authored docs:

init: current coverage is sufficient for now; no additional high-value boundary was found beyond ordinary filesystem failure paths
add: now covers both normal upsert flow and the surprising zero-entry repo side effect on failed validation
ingest: now covers both ordinary section import and the headingless fallback-entry parser path
search: now covers both positive lookup behavior and the required --query failure contract
list: current coverage is acceptable for now; remaining gaps are mostly lower-priority default-limit behavior and shared uninitialized-schema behavior
events: now covers both selector styles and the missing-selector failure contract
link: now covers both successful relation writes and missing-input rejection for ids and relation
verify: now covers changed-file downgrade, missing-hard-dependency stale, empty-repo set, explicit skip without Git HEAD, and missing verified_on_commit
repos: current coverage is acceptable for now; the zero-entry repo side effect is intentionally documented from the add boundary case

Authored Case Register

Path	Case Slug	Coverage Note	Status
`docs/tests/repo-memory/workflows/README.md`	`add-search-events-roundtrip`	end-to-end write, search, and history roundtrip for one durable entry	done
`docs/tests/repo-memory/workflows/README.md`	`ingest-search-list-across-sections`	markdown ingest surfaces multiple imported entries through search and list	done
`docs/tests/repo-memory/workflows/README.md`	`add-link-and-resolve-related-entry`	two entries are linked and the relation is persisted	done
`docs/tests/repo-memory/workflows/README.md`	`verify-downgrades-after-repo-change`	repo changes propagate into downgraded or stale durable knowledge	done
`docs/tests/repo-memory/init/init-creates-schema-on-empty-db.md`	`init-creates-schema-on-empty-db`	initializes an empty database path and prints the initialized path	done
`docs/tests/repo-memory/init/init-is-idempotent-on-existing-db.md`	`init-is-idempotent-on-existing-db`	repeated init succeeds on the same database path	done
`docs/tests/repo-memory/add/add-registers-repo-and-entry.md`	`add-registers-repo-and-entry`	auto-bootstraps schema, registers the repo, and creates one durable entry	done
`docs/tests/repo-memory/add/add-updates-existing-entry-on-same-kind-and-key.md`	`add-updates-existing-entry-on-same-kind-and-key`	repeated upsert reuses the same entry id and records an update event	done
`docs/tests/repo-memory/add/add-failed-validation-still-registers-repo.md`	`add-failed-validation-still-registers-repo`	failed validation still leaves a zero-entry repo row visible through `repos`	done
`docs/tests/repo-memory/ingest/ingest-imports-docs-ai-markdown.md`	`ingest-imports-docs-ai-markdown`	imports markdown sections under `docs/ai` as confirmed knowledge entries	done
`docs/tests/repo-memory/ingest/ingest-rejects-when-no-markdown-found.md`	`ingest-rejects-when-no-markdown-found`	rejects an empty scan tree with a stable error message	done
`docs/tests/repo-memory/ingest/ingest-imports-headingless-markdown-as-single-entry.md`	`ingest-imports-headingless-markdown-as-single-entry`	headingless markdown falls back to one imported entry instead of being skipped	done
`docs/tests/repo-memory/search/search-returns-matching-entry-snippet.md`	`search-returns-matching-entry-snippet`	returns a ranked text result with status and snippet lines	done
`docs/tests/repo-memory/search/search-matches-alias-with-repo-filter.md`	`search-matches-alias-with-repo-filter`	matches alias terms while narrowing by repo substring	done
`docs/tests/repo-memory/search/search-returns-no-results-when-empty.md`	`search-returns-no-results-when-empty`	prints `no results` for an empty search result set	done
`docs/tests/repo-memory/search/search-rejects-missing-query.md`	`search-rejects-missing-query`	rejects empty search invocation without `--query`	done
`docs/tests/repo-memory/list/list-filters-by-kind-and-status.md`	`list-filters-by-kind-and-status`	narrows entries by repo substring, kind, and status	done
`docs/tests/repo-memory/list/list-returns-no-entries-when-empty.md`	`list-returns-no-entries-when-empty`	prints `no entries` when the filtered result set is empty	done
`docs/tests/repo-memory/events/events-reads-history-by-id.md`	`events-reads-history-by-id`	prints newest-first history for one entry id	done
`docs/tests/repo-memory/events/events-resolves-entry-by-repo-kind-key.md`	`events-resolves-entry-by-repo-kind-key`	resolves an entry without `--id` when repo, kind, and key are provided	done
`docs/tests/repo-memory/events/events-rejects-missing-entry-selector.md`	`events-rejects-missing-entry-selector`	rejects calls that omit both `--id` and `--repo+--kind+--key`	done
`docs/tests/repo-memory/link/link-creates-relation-between-entries.md`	`link-creates-relation-between-entries`	persists one directed relation between two existing entries	done
`docs/tests/repo-memory/link/link-rejects-missing-relation.md`	`link-rejects-missing-relation`	rejects empty relation input before write	done
`docs/tests/repo-memory/link/link-rejects-when-entry-id-missing.md`	`link-rejects-when-entry-id-missing`	rejects link requests without both entry ids	done
`docs/tests/repo-memory/verify/verify-downgrades-changed-file-dependency.md`	`verify-downgrades-changed-file-dependency`	downgrades a confirmed entry to `needs_review` when a tracked file changed	done
`docs/tests/repo-memory/verify/verify-marks-missing-hard-dependency-stale.md`	`verify-marks-missing-hard-dependency-stale`	marks a confirmed entry `stale` when a hard dependency disappears	done
`docs/tests/repo-memory/verify/verify-prints-no-repos-when-empty.md`	`verify-prints-no-repos-when-empty`	prints `no repos` when the initialized DB has no tracked repositories	done
`docs/tests/repo-memory/verify/verify-skips-explicit-repo-without-git-head.md`	`verify-skips-explicit-repo-without-git-head`	explicit repo verification reports a skip when the repo is not a Git repo or has no HEAD	done
`docs/tests/repo-memory/verify/verify-downgrades-entry-missing-verified-on-commit.md`	`verify-downgrades-entry-missing-verified-on-commit`	entries created without `verified_on_commit` downgrade to `needs_review` once the repo becomes verifiable	done
`docs/tests/repo-memory/repos/repos-lists-tracked-repositories.md`	`repos-lists-tracked-repositories`	lists every tracked repository with entry counts and update timestamps	done
`docs/tests/repo-memory/repos/repos-prints-no-repos-when-empty.md`	`repos-prints-no-repos-when-empty`	prints `no repos` for an initialized but unused database	done

Pending Case Backlog

No pending case slugs remain in the current plan.

When a new CLI contract or workflow needs coverage:

if it is a command case, create a new <case-slug>.md file under the relevant command folder and add it to that folder README.md index
if it is a workflow case, add it to docs/tests/repo-memory/workflows/README.md
add the new slug to Authored Case Register
update Current Snapshot and Document Progress

Definition Of Done

This roadmap is complete only when all of the following are true:

every implemented repo-memory command has a corresponding document folder
each planned command index and case document exists
each pending case slug has been either authored or explicitly deferred
the authored-case register matches the actual Markdown files on disk
a new agent can pick any pending case and know exactly where it should be written

19 KiB Raw Blame History