rqmd 0.1.0rc2__tar.gz

rqmd-0.1.0rc2/PKG-INFO

@@ -0,0 +1,758 @@
+Metadata-Version: 2.4
+Name: rqmd
+Version: 0.1.0rc2
+Summary: Requirements Markdown manager CLI tool, `rqmd`. GitHub Copilot AI integration supported via `rqmd-ai init`.
+Author: RQMD Contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/example/rqmd
+Project-URL: Repository, https://github.com/example/rqmd
+Project-URL: Issues, https://github.com/example/rqmd/issues
+Project-URL: Changelog, https://github.com/example/rqmd/blob/main/CHANGELOG.md
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: click>=8.1.0
+Requires-Dist: tabulate>=0.9.0
+Requires-Dist: PyYAML>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-timeout>=2.3.1; extra == "dev"
+Provides-Extra: speedups
+Requires-Dist: orjson>=3.10.0; extra == "speedups"
+
+# rqmd
+
+Reusable requirements and acceptance-requirements workflow CLI.
+
+rqmd: Human-readable + AI-readable requirements for Requirements Driven Development (RDD).
+
+Project links:
+- GitHub: https://github.com/example/rqmd
+- PyPI: https://pypi.org/project/rqmd/
+
+This package extracts the markdown status-tracking workflow used in this repository into a portable Python package that can be copied to other projects and eventually published to PyPI.
+
+## What this tool does
+
+- Scans requirement markdown files in a requirements directory.
+- Uses `README.md` inside that directory as the requirements index.
+- When `--docs-dir` is omitted, auto-detects the nearest viable requirement index from the current working path.
+- Normalizes `- **Status:** ...` lines to canonical statuses.
+- Parses requirement headers such as `### AC-FOO-001: Title` or `### R-FOO-001: Title`.
+- Regenerates per-file summary blocks:
+
+```md
+<!-- acceptance-status-summary:start -->
+Summary: 10💡 2🔧 3✅ 0⚠️ 0⛔ 1🗑️
+<!-- acceptance-status-summary:end -->
+```
+
+- Supports interactive status editing with keyboard navigation.
+- Supports non-interactive updates for automation/agents.
+
+Requirement bodies can be as short as a title plus status line, or include richer detail under the same heading. When both are useful, prefer pairing a short user story (`As a ...`, `I want ...`, `So that ...`) with Given/When/Then acceptance bullets.
+
+## Status model
+
+The built-in default status and priority catalogs ship as packaged YAML resources under `src/rqmd/resources/catalogs/`, so changing the shipped defaults no longer requires touching multiple Python tables.
+
+- `💡 Proposed`
+- `🔧 Implemented`
+- `✅ Verified`
+- `⚠️ Janky`
+- `⛔ Blocked`
+- `🗑️ Deprecated`
+
+## Priority model (optional field)
+
+Requirements can optionally include a `**Priority:**` line alongside the status line. When present, priority metadata supports sorting, filtering, and priority-aware summaries.
+
+Default priority levels:
+
+- `🔴 P0 - Critical`
+- `🟠 P1 - High`
+- `🟡 P2 - Medium`
+- `🟢 P3 - Low`
+
+Example requirement with priority:
+
+```md
+### AC-FEATURE-001: Core API endpoint
+- **Status:** 🔧 Implemented
+- **Priority:** 🔴 P0 - Critical
+```
+
+Priority is optional; requirements without a priority line parse successfully with `priority: None`.
+
+Priority values are normalized case-insensitively, so `p0`, `P0`, `critical`, and `CRITICAL` all map to `🔴 P0 - Critical`.
+
+Project config can still override these built-ins with `.rqmd.yml`, `.rqmd.json`, or standalone status/priority catalog files.
+
+## Install (local development)
+
+From this folder:
+
+```bash
+uv sync
+```
+
+Install test dependencies:
+
+```bash
+uv sync --extra dev
+```
+
+Install optional native JSON acceleration:
+
+```bash
+uv sync --extra speedups
+```
+
+When `orjson` is installed through the `speedups` extra, rqmd and rqmd-ai use it for JSON export and audit-log serialization while preserving the existing JSON schema and a pure-Python fallback when the extra is absent.
+
+Then run:
+
+```bash
+rqmd --help
+```
+
+`reqmd` and `reqmd-ai` remain available as compatibility aliases, but the canonical commands are `rqmd` and `rqmd-ai`.
+
+Module entrypoint:
+
+```bash
+python -m rqmd --help
+```
+
+Pre-release alias plan:
+
+- `rqmd` remains the canonical package name and primary command for now.
+- `reqmd` and `reqmd-ai` are shipped as compatibility aliases so teams can trial the shorter branding before any package regname decision.
+- Any future package-name rename should happen only after a manual PyPI availability check and a documented compatibility window for existing `rqmd` users.
+
+## Shell completion
+
+rqmd uses Click dynamic completion and supports shell activation without maintaining static completion files.
+Completion candidates stay in sync with live requirement docs, including positional target tokens (domain names, requirement IDs, and subsection names) plus positional status/priority filter values such as `Proposed` and `P1`.
+
+zsh activation (add to `~/.zshrc`):
+
+```bash
+eval "$(_RQMD_COMPLETE=zsh_source rqmd)"
+```
+
+bash activation (add to `~/.bashrc`):
+
+```bash
+eval "$(_RQMD_COMPLETE=bash_source rqmd)"
+```
+
+fish activation (add to `~/.config/fish/config.fish`):
+
+```fish
+_RQMD_COMPLETE=fish_source rqmd | source
+```
+
+If you are running from a local clone during development without installing the console script, use `python -m rqmd`; completion is provided by the installed `rqmd` console entrypoint.
+
+Troubleshooting completion cache refresh:
+
+- zsh: `rm -f ~/.zcompdump* && exec zsh`
+- bash: open a new shell session after updating rc files
+- fish: `exec fish` after updating config
+
+## Core commands
+
+Check summaries only:
+
+```bash
+rqmd --verify-summaries
+```
+
+Interactive mode:
+
+```bash
+rqmd
+```
+
+Open a specific domain file directly (absolute or repo-root-relative path):
+
+```bash
+rqmd docs/requirements/interactive-ux.md
+```
+
+In non-interactive modes, a positional domain file path scopes operations to that file:
+
+```bash
+rqmd docs/requirements/interactive-ux.md --update AC-EXAMPLE-001=verified
+```
+
+Interactive file and requirement menus now support:
+
+- `j` and `k` for next/previous vertical movement alongside arrow keys
+- `gg` to jump to the first visible list position and `G` to jump to the last
+- `Ctrl-U` and `Ctrl-D` for deterministic half-page movement in paged menus
+- `/` and `?` to search forward or backward within the current interactive list
+- `n` and `N` to repeat the last list search in the same or opposite direction
+- compact default footers with `:=help` instead of always showing the full key legend inline
+- `:` to open the full help surface from interactive menus
+- invalid or unmapped keys to playfully toggle the help surface open and closed without losing context
+- `s` to cycle sort columns
+- `d` to toggle ascending/descending
+- `r` to refresh/rescan while preserving the active sort
+- `z` to undo the last recorded history step from a requirement action menu
+- `y` to redo the next recorded history step from a requirement action menu
+- `h` to open the paged history browser from a requirement action menu
+
+Inside the history browser, selecting an entry opens a detail view where you can:
+
+- press `c` to checkout the selected entry's branch
+- press `l` to save a human-readable label for the selected entry's branch
+- press `x` to discard the selected entry's alternate branch, with an option to save a label first
+- press `p` to cherry-pick the selected commit onto the current branch
+- press `r` to replay the selected entry's branch onto the current branch
+- press `g` to run history gc with confirmation
+- press `G` to run history gc with immediate prune
+
+Both interactive gc actions can optionally save a human-readable label on the current history branch before maintenance runs.
+
+History retention now uses a conservative default policy of retaining the last 1000 entries or the last 90 days of history metadata before running pack/prune maintenance. You can override that policy in project or user config with a top-level `history_retention` object:
+
+```json
+{
+	"history_retention": {
+		"retain_last": 500,
+		"retain_days": 30,
+		"max_size_kib": 2048
+	}
+}
+```
+
+`retain_last` and `retain_days` decide which persisted history entries remain navigable after `--history-gc`; `max_size_kib` records when the hidden history repo has crossed a size threshold so maintenance reports can surface it alongside the pack/prune result.
+
+Long options also accept unique prefixes, so invocations such as `--proj`, `--docs`, and `--as-j` work when they resolve unambiguously.
+
+History operations available in non-interactive mode include:
+
+- `rqmd --history`
+- `rqmd --timeline`
+- `rqmd --undo`
+- `rqmd --redo`
+- `rqmd --history-label-branch <branch-name> --history-branch-label <label>`
+- `rqmd --history-discard-branch <branch-name> --history-discard-save-label <label> --force-yes`
+- `rqmd --history-gc --history-gc-save-label <label> --force-yes`
+- `rqmd --history-gc --force-yes`
+- `rqmd --history-gc --history-prune-now --force-yes`
+- `rqmd --history-checkout-branch <branch-name>`
+- `rqmd --history-cherry-pick <entry-index-or-ref> [--history-target-branch <branch-name>]`
+- `rqmd --history-replay-branch <branch-name> [--history-target-branch <branch-name>]`
+
+`--history-gc` requires explicit confirmation because it runs maintenance against the hidden `.rqmd/history/rqmd-history` repository. Add `--history-prune-now` to expire reflogs and prune immediately instead of using Git's default grace period.
+
+File lists now default to the `name` sort in descending order.
+
+You can select a named sort strategy catalog for interactive mode:
+
+```bash
+rqmd --sort-profile standard
+rqmd --sort-profile status-focus
+rqmd --sort-profile alpha-asc
+```
+
+Start rqmd in a new project with the default chat-first flow:
+
+```bash
+rqmd init
+```
+
+`rqmd init` prints a copy/paste handoff prompt for your AI chat. That chat then runs `rqmd-ai init --chat --json`, asks the grouped interview questions, previews the generated files, and applies the bootstrap only after confirmation.
+
+Direct scaffold compatibility path:
+
+```bash
+rqmd init --scaffold
+```
+
+`rqmd init --scaffold` is the direct starter scaffold path when you want immediate docs without the chat-first onboarding flow.
+Scaffold content is sourced from repository-managed templates in `src/rqmd/resources/init/README.md` and `src/rqmd/resources/init/domain-example.md`.
+
+Allocate the next sequential numeric requirement ID for the active namespace:
+
+```bash
+rqmd --id-namespace TEAM --next-id
+rqmd --id-namespace TEAM --next-id --json
+```
+
+`--next-id` respects the active key prefix, uses at least 3 digits of zero-padding by default, and continues past `999` as `1000`, `1001`, and higher.
+
+Set one requirement non-interactively:
+
+```bash
+rqmd --update-id AC-EXAMPLE-001 --update-status implemented
+```
+
+Update priorities non-interactively:
+
+```bash
+rqmd --update-priority AC-EXAMPLE-001=p0
+rqmd --update-priority AC-EXAMPLE-001=critical --update-priority AC-EXAMPLE-002=medium
+```
+
+Batch updates can include `priority` fields, or combine `status` and `priority` in one row:
+
+```json
+{"id":"AC-EXAMPLE-001","priority":"p0"}
+{"id":"AC-EXAMPLE-002","status":"implemented","priority":"medium"}
+```
+
+Use positional filters for fast narrowing without explicit flags:
+
+```bash
+rqmd all
+rqmd P1 Proposed --json --no-walk --no-table
+rqmd Proposed core-engine
+```
+
+`rqmd all` opens a whole-catalog overview ordered by newest requirement ID first. When positional status and priority filters are combined, rqmd narrows across both families, so `rqmd P1 Proposed` returns only proposed P1 requirements. Remaining positional tokens are then resolved as requirement IDs, domain tokens, or subsection tokens.
+
+Interactive entry panels can start in priority mode:
+
+```bash
+rqmd --focus-priority
+```
+
+Within an entry panel, press `t` to cycle status, priority, and flagged editing.
+
+When the entry panel is on status, rqmd also shows a right-hand priority column so the current priority and available shifted number-row shortcuts such as `!`/`@`/`#`/`$`/`%`/`^`/`&`/`*` stay visible while you review statuses. That column is rendered as its own aligned block, and its current-priority highlight remains separate from the active status-row highlight so both states stay readable at once. Those shortcuts set the first configured priorities immediately and keep focus on the current requirement until you explicitly move on with down arrow or `j`.
+
+From any requirement detail panel, press `o` to inspect linked local requirement references that rqmd can resolve from the current entry. Selecting one opens that linked requirement in a nested detail view, and pressing `u` there returns you to the originating requirement.
+
+From the same detail panel, press `v` to open the current requirement in VS Code at the requirement heading line. If the `code` launcher is unavailable, rqmd reports that cleanly and keeps you in the current interactive context.
+
+Regenerate summary blocks with priority aggregates included:
+
+```bash
+rqmd --priority-rollup --no-walk
+```
+
+Filter by priority in tree, JSON, or interactive walk modes:
+
+```bash
+rqmd --priority critical --as-tree
+rqmd --priority p1 --json --no-walk
+```
+
+Filter by subsection name with case-insensitive prefix matching:
+
+```bash
+rqmd --sub-domain query --as-tree
+rqmd --sub-domain api --json --no-walk
+```
+
+Combine filters for slicing/dicing requirements:
+
+- OR across different filter flags (`--status`, `--priority`, `--flagged`/`--no-flag`, `--has-link`/`--no-link`, `--sub-domain`)
+- AND within the same flag when repeated
+
+```bash
+rqmd --status proposed --priority p0 --as-tree
+rqmd --no-flag --json --no-walk
+rqmd --has-link --json --no-walk
+rqmd --status proposed --status implemented --json --no-walk
+rqmd --sub-domain query --sub-domain api --json --no-walk
+```
+
+Target an explicit worklist from CLI tokens or a reusable file:
+
+```bash
+rqmd demo "Query API"
+rqmd --targets-file tmp/focus.txt --json --no-walk
+```
+
+`--targets-file` accepts `.txt`, `.conf`, or `.md` files with one-per-line or whitespace/comma-separated tokens, and supports `#` comments.
+
+Interactive file and requirement menus also expose `priority` as a sortable column via `s` / `d`.
+
+Use a different ID prefix:
+
+```bash
+rqmd --id-namespace R --update-id R-EXAMPLE-001 --update-status implemented
+```
+
+Bulk set by repeated flags:
+
+```bash
+rqmd --update AC-EXAMPLE-001=implemented --update AC-EXAMPLE-002=verified
+```
+
+## AI CLI (rqmd-ai)
+
+`rqmd-ai` is a companion command for AI-oriented workflows. It is read-only by default and supports prompt-context export, plan previews, and guarded apply mode.
+
+Recommended AI change loop for brainstorm-driven work:
+
+1. Export focused context first with `rqmd-ai --json` or a targeted `--dump-*` command.
+2. Update tracked requirement docs, the requirement index, and `CHANGELOG.md` before code when the brainstorm changes product behavior or workflow.
+3. Review the read-only plan preview from `rqmd-ai --update ...`.
+4. Apply explicitly with `--write` only after the preview matches the intended requirement/doc changes.
+5. Finish with `rqmd --verify-summaries` and the test suite so requirement docs and shipped behavior stay aligned.
+
+Guidance mode:
+
+```bash
+rqmd-ai --json
+rqmd-ai --json --workflow-mode brainstorm
+rqmd-ai --json --workflow-mode implement
+rqmd-ai init --chat --json
+rqmd-ai --json --workflow-mode init --show-guide
+```
+
+`--workflow-mode brainstorm` emits requirement-first planning guidance for turning notes into ranked proposals. `--workflow-mode implement` emits the execution loop for working the highest-priority proposed 1-3 items at a time, then re-checking `rqmd`, summaries, tests, changelog, and remaining priorities before the next batch. `rqmd-ai init --chat` is the preferred onboarding entrypoint: it routes between starter scaffold mode and legacy-style repository seeding, emits a copy/paste AI handoff prompt, and keeps `--workflow-mode init-legacy` available only as a compatibility surface.
+
+By default, `rqmd-ai --json` now includes the packaged skill and agent definitions from `resources/bundle` when the rqmd bundle is not installed in the workspace. If the bundle is already installed, the guide payload stays concise and reports the active local definition files instead of duplicating the packaged content.
+
+Brainstorm mode can read `docs/brainstorm.md` by default or a custom markdown note file via `--brainstorm-file`, then emit ranked read-only proposal suggestions with recommended target requirement docs, suggested IDs, canonical `💡 Proposed` status, and inferred priorities.
+
+Export context for prompts:
+
+```bash
+rqmd-ai --json --dump-status proposed
+rqmd-ai --json --dump-id RQMD-CORE-001 --include-requirement-body
+rqmd-ai --json --dump-file ai-cli.md --include-domain-markdown --max-domain-markdown-chars 2000
+```
+
+Plan first, then apply explicitly:
+
+```bash
+rqmd-ai --json --update RQMD-CORE-001=implemented
+rqmd-ai --json --write --update RQMD-CORE-001=implemented
+```
+
+Install a standard AI agent/skill instruction bundle (minimal or full preset):
+
+```bash
+rqmd-ai --json --install-agent-bundle --bundle-preset minimal --dry-run
+rqmd-ai --json --install-agent-bundle --bundle-preset full
+rqmd-ai --json --install-agent-bundle --bundle-preset full --overwrite-existing
+```
+
+Bundle installs are idempotent by default and preserve existing customized instruction files unless `--overwrite-existing` is explicitly passed.
+
+Bundle install also scaffolds project-local `.github/skills/dev/SKILL.md` and `.github/skills/test/SKILL.md` files based on detected repository commands. Treat those as a starting point: review and tighten the generated build, smoke, and validation commands so future `rqmd-dev` runs can rely on them instead of guessing.
+
+Bundle installation can also be driven through a structured chat-style preview with `rqmd-ai install --json --bundle-preset minimal --chat --dry-run`. That payload now includes grouped interview questions, multi-select command suggestions, custom-answer prompts, skip support, detected command sources, recommended choices, safe defaults, and preview content for the generated `/dev` and `/test` skills. Repeat `--answer FIELD=VALUE` to select multiple suggestions or add custom commands before writing.
+
+New-project flow: run `rqmd init`, paste the output into your AI chat, let that chat drive `rqmd-ai init --chat --json`, review the generated requirements catalog and any suggested bundle skill setup, and then start refining the resulting requirements docs.
+
+Legacy-style repository seeding can still be previewed with `rqmd-ai init --chat --json --legacy`. The grouped interview covers catalog setup, developer workflows, repository understanding, backlog handling, and review notes, and its options include recommended choices, detected-from hints, and safe defaults. The generated starter catalog seeds a requirements index, developer workflow requirements, repository-area seed files, and an issue backlog file when `gh issue list` succeeds.
+
+The installed bundle now includes Copilot skills for `/rqmd-brainstorm`, `/rqmd-triage`, `/rqmd-export-context`, `/rqmd-implement`, `/rqmd-init`, `/rqmd-init-legacy`, `/rqmd-status-maintenance`, `/rqmd-doc-sync`, `/rqmd-history`, `/rqmd-bundle`, and `/rqmd-verify` so teams can reuse the core planning, backlog selection, context export, implementation, unified init, compatibility legacy bootstrap, docs-sync, history, bundle-management, and verification loops without rewriting those instructions in every workspace. Those skills help with discovery and consistency, but they do not auto-approve terminal commands or bypass Copilot tool approval prompts.
+
+The full bundle preset also installs specialized agents for requirement maintenance, docs sync, history investigation, and bundle maintenance so future agents can stay narrow and workflow-aware instead of overloading the single core agent with every repo-management task.
+
+Bundle workflows assume the core lifecycle states remain representable in your status catalog. Custom labels are fine, but if you want `rqmd-ai` guidance, examples, and installed skills to work well out of the box, keep lifecycle equivalents for `💡 Proposed`, `🔧 Implemented`, `✅ Verified`, `⛔ Blocked`, and `🗑️ Deprecated`.
+
+When apply mode runs, rqmd-ai appends a structured audit event to the local shared history backend at `.rqmd/history/rqmd-history/audit.jsonl`.
+
+Batch set from file:
+
+```bash
+rqmd --update-file tmp/ac-updates.jsonl
+```
+
+Allow custom prefixes such as `REQ-` in a repo:
+
+```bash
+rqmd --id-namespace REQ --status proposed --as-tree
+```
+
+Filter walk:
+
+```bash
+rqmd --status proposed
+```
+
+Filtered walk resume behavior (enabled by default):
+
+- Uses persisted state so reruns continue at the last visited requirement.
+- Disable with `--no-resume-walk`.
+- Control storage location with `--session-state-dir`.
+
+Examples:
+
+```bash
+rqmd --status implemented --session-state-dir system-temp
+rqmd --status implemented --session-state-dir project-local
+rqmd --status implemented --session-state-dir .rqmd/state
+rqmd --status implemented --no-resume-walk
+```
+
+Filter tree only:
+
+```bash
+rqmd --status proposed --as-tree
+```
+
+Filter as JSON for automation/AI parsing:
+
+```bash
+rqmd --status proposed --json
+```
+
+Filter JSON includes requirement body content and line metadata by default:
+
+```bash
+rqmd --status proposed --json
+```
+
+Use compact output without bodies:
+
+```bash
+rqmd --status proposed --json --no-requirement-body
+```
+
+Summary/check/set JSON examples:
+
+```bash
+rqmd --json --no-walk
+rqmd --verify-summaries --json --no-walk
+rqmd --update-id AC-EXAMPLE-001 --update-status verified --json
+rqmd --totals --json --no-walk
+```
+
+### JSON contract (stable keys)
+
+When `--json` is used, top-level keys are stable by mode.
+All JSON payloads include `schema_version` (current value: `1.0.0`) and follow semantic versioning (`major.minor.patch`).
+
+- `summary`: `mode`, `schema_version`, `criteria_dir`, `changed_files`, `totals`, `files`, `ok`
+- `check`: `mode`, `schema_version`, `criteria_dir`, `changed_files`, `totals`, `files`, `ok`
+- `set` / `set-priority` / `set-flagged`: `mode`, `schema_version`, `criteria_dir`, `changed_files`, `totals`, `files`, `updates`
+- `filter-status`: `mode`, `schema_version`, `status`, `criteria_dir`, `total`, `files`
+- `filter-priority`: `mode`, `schema_version`, `priority`, `criteria_dir`, `total`, `files`
+- `filter-flagged`: `mode`, `schema_version`, `flagged`, `criteria_dir`, `total`, `files`
+- `filter-sub-domain`: `mode`, `schema_version`, `sub_domain`, `criteria_dir`, `total`, `files`
+- `filter-combined`: `mode`, `schema_version`, `filters`, `criteria_dir`, `total`, `files`
+- `filter-targets`: `mode`, `schema_version`, `targets`, `criteria_dir`, `total`, `files`
+- `rollup`: `mode`, `schema_version`, `criteria_dir`, `file_count`, `totals`, optional `rollup_source`, optional `rollup_columns`
+- `init`: `mode`, `schema_version`, `criteria_dir`, `starter_prefix`, `created_files`, `created_count`
+- `init-priorities`: `mode`, `schema_version`, `criteria_dir`, `default_priority`, `changed_files`, `changed_count`
+
+Filter payloads return `files` ordered by path and requirement entries ordered by requirement ID.
+By default, filter JSON includes `body.markdown` and line metadata; pass `--no-requirement-body` to omit bodies.
+Each requirement entry includes `sub_domain` (string or `null`), and each file entry includes `sub_sections` with subsection names and requirement counts.
+
+### Exit codes
+
+RQMD uses this exit-code matrix for automation:
+
+- `0`: Success (including successful no-op runs)
+- `1`: Validation or contract failure (for example `--verify-summaries` found out-of-sync summaries, invalid input, missing docs, ambiguity, or other `ClickException` errors)
+- `130`: Interrupted by user (`Ctrl+C`)
+
+Explicit global roll-up totals:
+
+```bash
+rqmd --totals --no-walk
+```
+
+Custom roll-up columns from CLI equations:
+
+```bash
+rqmd --totals --totals-map "C1=I+V" --totals-map "C2=P" --no-walk
+```
+
+Custom roll-up columns from config (`.json`, `.yml`, `.yaml`):
+
+```bash
+rqmd --totals --totals-config .rqmd.yml --json --no-walk
+```
+
+Example project config for a repo that defines a custom status catalog and wants RQMD-ROLLUP-007 roll-up buckets:
+
+```yaml
+# .rqmd.yml
+statuses:
+	- name: Proposed
+		shortcode: P
+		emoji: "💡"
+	- name: Implemented
+		shortcode: I
+		emoji: "🔧"
+	- name: Desktop-Verified
+		shortcode: DV
+		emoji: "💻"
+	- name: VR-Verified
+		shortcode: VV
+		emoji: "🎮"
+	- name: Done
+		shortcode: D
+		emoji: "✅"
+	- name: Blocked
+		shortcode: B
+		emoji: "⛔"
+	- name: Deprecated
+		shortcode: X
+		emoji: "🗑️"
+
+rollup_map:
+	Proposed: [proposed]
+	Build-Ready: [implemented, desktop-verified]
+	Complete: [vr-verified, done]
+	Parked: [blocked, deprecated]
+```
+
+That example yields these roll-up families:
+
+- `Blocked + Deprecated` roll up together in `Parked`
+- `Implemented + Desktop-Verified` roll up together in `Build-Ready`
+- `VR-Verified + Done` roll up together in `Complete`
+
+When no CLI map/config is passed, rqmd resolves roll-up mappings with this precedence:
+
+1. `--totals-map` CLI equations
+2. project config (`.rqmd.yml|.rqmd.yaml` in `--project-root`)
+3. user config (`~/.config/rqmd/rollup.json|yaml|yml`)
+4. built-in canonical status totals
+
+## Tests
+
+Run full pytest suite from this folder:
+
+```bash
+uv run --extra dev pytest
+```
+
+Run a specific test module:
+
+```bash
+uv run --extra dev pytest tests/test_core_engine.py
+```
+
+One-command shell smoke check (no make required):
+
+```bash
+bash scripts/local-smoke.sh
+```
+
+The test suite is organized to validate implemented acceptance-requirements behavior for:
+- core engine parsing and summary sync
+- interactive menu/color behavior
+- non-interactive automation flows
+- portability and packaging contracts
+
+Detailed coverage mapping is documented in `docs/testing.md`.
+
+## Changelog
+
+Notable project changes are tracked in `CHANGELOG.md` using the Keep a Changelog format.
+
+## CI
+
+This package includes GitHub Actions workflows:
+
+- `.github/workflows/pytest.yml`
+- Triggers on push and pull_request.
+- Installs project dependencies with `uv sync --extra dev`.
+- Runs `bash scripts/local-smoke.sh --skip-install`.
+
+- `.github/workflows/publish-pypi.yml`
+- Triggers when a GitHub release is published.
+- Validates that the release tag is a stable semver tag or `rc` prerelease tag matching `project.version`.
+- Builds with `python -m build` and publishes with GitHub Actions trusted publishing.
+
+## Project portability
+
+By default, rqmd auto-discovers `--project-root` by searching from the current working directory upward.
+The nearest ancestor with a supported marker wins.
+
+Marker priority within each directory is deterministic:
+
+1. `.rqmd.yml`, `.rqmd.yaml`, `.rqmd.json`
+2. `docs/requirements/`
+3. `requirements/`
+
+If no marker is found, rqmd falls back to current working directory.
+When auto-discovery is used, rqmd reports the discovered root and source marker.
+
+Passing explicit `--project-root` bypasses auto-discovery.
+
+When `--docs-dir` is omitted, rqmd auto-detects requirement docs by scanning from the current working path.
+
+Auto-detect preference is deterministic:
+
+1. `docs/requirements/README.md`
+2. `requirements/README.md`
+
+You can override both:
+
+```bash
+rqmd --project-root /path/to/project --docs-dir docs/requirements
+```
+
+`--docs-dir` can be absolute or relative to `--project-root`.
+When auto-detection is used, rqmd reports which index path it selected.
+
+Filtered walkthrough resume state is configurable with `--session-state-dir`:
+
+- `system-temp` (default): OS temp directory.
+- `project-local`: `<repo-root>/tmp/rqmd`.
+- custom path: absolute or relative to `--project-root`.
+
+Requirement header prefixes are configurable with `--id-namespace`.
+When omitted, rqmd auto-detects prefixes by reading the selected `README.md` requirements index and linked domain docs when available.
+If no prefixes are discovered, it falls back to `AC-`, `R-`, and `RQMD-`.
+
+### Project configuration file
+
+To avoid repeating CLI flags across team members, use a single project config file at the project root: `.rqmd.yml` (preferred).
+Accepted extensions are `.rqmd.yml`, `.rqmd.yaml`, or `.rqmd.json`.
+`rqmd init --scaffold` and `rqmd-ai init --write` now create `.rqmd.yml` by default so the repository's requirements path, ID prefix, and canonical status/priority catalogs are explicit from day one.
+
+Example:
+
+```yaml
+{
+	requirements_dir: docs/requirements
+	id_prefix: PROJ
+	sort_strategy: status-focus
+	state_dir: project-local
+}
+```
+
+Supported keys:
+
+- `requirements_dir`: Default requirements directory (relative to repo root)
+- `id_prefix`: Default ID prefix for requirement headers
+- `sort_strategy`: Default sort strategy for interactive mode (standard, status-focus, alpha-asc)
+- `state_dir`: Default state directory for filtered walk resume (system-temp, project-local, or custom path)
+
+CLI flags always override config file values. When `.rqmd.yml` (or `.rqmd.yaml` / `.rqmd.json`) is present, rqmd loads it automatically; no additional flag is needed.
+
+## Recommended docs recipe for projects
+
+1. Keep an index doc at `docs/requirements/README.md` or `requirements/README.md`.
+2. Keep domain files in that same directory.
+3. Ensure each requirement has exactly one status line directly under the `### <PREFIX>-...` header.
+4. Run `rqmd --verify-summaries` in CI to prevent stale summary blocks.
+5. Use non-interactive `--update`/`--update-file` in automation.
+
+## Packaging notes
+
+- Package name: `rqmd`
+- Console script entrypoint: `rqmd`
+- Source package: `src/rqmd`
+
+When ready for PyPI:
+
+1. Follow semantic versioning policy in `docs/SEMVER.md`.
+2. Follow the release checklist in `docs/releasing.md`.
+3. Create and publish a GitHub Release with a matching tag such as `v0.1.0` or `v0.1.0rc1`.
+4. Let `.github/workflows/publish-pypi.yml` publish through trusted publishing.