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

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:

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

Recommended repo bootstrap for Git-aware cases:

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:

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.