kandev/docs/plans/docs-catalog-discovery/task-01-build-catalog-command.md

id, title, status, wave, depends_on, plan, requirements, acceptance_criteria, system_design

id	title	status	wave	depends_on	plan	requirements	acceptance_criteria	system_design
01-build-catalog-command	Build the documentation catalog command	done	1		plan.md

Task 01: Build the documentation catalog command

Summary

Add one tested Python command that discovers architecture decisions and specifications from repository source files.

In scope

• Add scripts/list-docs.py with decisions, specs, and validate subcommands.
• Add decision filters for status, area, and case-insensitive text.
• Add specification filters for system, kind, status, and case-insensitive text.
• Add Markdown, path-only, and JSON output.
• Add deterministic sorting and actionable validation errors.
• Add focused tests in scripts/list-docs.test.py.

Out of scope

• Editing any tracked documentation catalog.
• Changing the metadata format of existing documents.
• Adding a Python package dependency.

Implementation details

Use only the Python standard library. Accept an internal root override in tests so fixtures use temporary directories. Keep repository paths relative in all output and errors.

Decision parsing must support metadata forms already present in the repository. Use the filename stem as the identifier. Use the first ADR heading as the title. Read status, date, and area from the metadata block. Filter status by its leading class, such as accepted, while displaying the complete value.

Specification parsing derives system and kind from the path. Recognized kinds are system, glossary, requirement, system-design, product, and legacy. Both the catalog and the specification linter use scripts/spec_metadata.py for path classification, frontmatter parsing, and status sets.

The JSON output contains a top-level schema version and an ordered documents array. Each item contains the common path, title, and type fields plus the type-specific metadata. Empty filters return an empty successful result.

Acceptance

• The command finds every valid decision and specification source file.
• Repeated runs on the same tree produce byte-identical output.
• Every documented filter works alone and with other filters.
• Each output format represents the same ordered result set.
• Invalid metadata returns a nonzero exit status and identifies the file.
• Tests cover existing ADR metadata variants, every specification source kind, and specification frontmatter errors.

Verification

python3 scripts/list-docs.test.py
python3 scripts/list-docs.py validate
python3 scripts/list-docs.py decisions --status accepted --format markdown
python3 scripts/list-docs.py specs --system ui --kind requirement --format paths

Files likely touched

• scripts/list-docs.py
• scripts/list-docs.test.py
• scripts/spec_metadata.py
• scripts/lint-spec-files.py

Dependencies

None.

Risks

• Loose ADR parsing can hide malformed files. Keep accepted variants explicit and reject ambiguous metadata.
• Markdown titles can contain table delimiters. Escape cells in the formatter.

Parallelism

sequential

Inputs

• docs/decisions/*.md
• docs/specs/**/*.md
• scripts/lint-spec-files.py
• docs/decisions/2026-09-07-on-demand-document-catalogs.md

Results

Done. The catalog command discovers every supported decision and specification source kind. Product documents and valid glossaries are not legacy sources. Malformed system README metadata fails validation with the source path. The focused tests, repository validation, and documented filter examples pass.