requirements-as-code 0.7.2__tar.gz → 0.7.13__tar.gz

requirements_as_code-0.7.13/.github/workflows/ci.yml

@@ -0,0 +1,20 @@
+name: CI
+
+# Run the test suite only when changes land on main (a merged PR or a direct
+# push). Tests intentionally do NOT run on pull requests — see ADR-027 for the
+# trigger policy and its post-merge-feedback tradeoff. workflow_dispatch allows
+# running the full battery grid manually (e.g. to check a branch before merge).
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+# Serialize runs on the same ref. Don't cancel an in-progress run: every merge
+# to main should be fully tested, since these runs are what gate releases.
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  tests:
+    uses: ./.github/workflows/tests.yml

{requirements_as_code-0.7.2 → requirements_as_code-0.7.13}/.github/workflows/python-publish.yml

@@ -16,7 +16,13 @@ permissions:
   contents: read
 
 jobs:
+  test:
+    # Gate the release on the full test suite (reusable workflow). Tests must
+    # pass before anything is built or published.
+    uses: ./.github/workflows/tests.yml
+
   release-build:
+    needs: test
     runs-on: ubuntu-latest
 
     steps:

requirements_as_code-0.7.13/.github/workflows/tests.yml

@@ -0,0 +1,78 @@
+name: Tests
+
+# Reusable workflow — the single definition of how RAC's test suite runs.
+# Called by ci.yml (push to main) and by python-publish.yml (release gate),
+# so the test steps live in one place rather than being duplicated.
+#
+# Tests are split into one "battery" per .py service (plus grouped core / cli /
+# artifacts) and run across every supported Python version, so the Actions UI
+# names the service + version that failed (e.g. "relationships (py3.11)")
+# instead of a single opaque "pytest (3.11)". See ADR-027.
+
+on:
+  workflow_call:
+
+permissions:
+  contents: read
+
+jobs:
+  pytest:
+    name: ${{ matrix.battery.name }} (py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+        # One battery per .py service, plus grouped core / cli / artifacts.
+        # Every tests/test_*.py belongs to exactly one battery (no orphans).
+        battery:
+          - name: core
+            paths: "tests/test_validate.py tests/test_parser.py tests/test_schema.py tests/test_identity.py"
+          - name: cli
+            paths: "tests/test_cli.py"
+          - name: artifacts
+            paths: "tests/test_design.py tests/test_roadmap.py tests/test_prompt.py tests/test_decision_metadata.py"
+          - name: diff
+            paths: "tests/test_diff.py"
+          - name: improve
+            paths: "tests/test_improve.py"
+          - name: index
+            paths: "tests/test_index.py"
+          - name: ingest
+            paths: "tests/test_ingest.py"
+          - name: inspect
+            paths: "tests/test_inspect.py"
+          - name: portfolio
+            paths: "tests/test_portfolio.py"
+          - name: relationships
+            paths: "tests/test_relationships.py tests/test_relationships_cmd.py tests/test_relationship_validation.py"
+          - name: review
+            paths: "tests/test_review.py"
+          - name: stats
+            paths: "tests/test_stats.py"
+          # Trust gates (v0.7.9): dogfood validates RAC's own rac/ corpus,
+          # golden pins CLI stdout byte-for-byte against committed files.
+          - name: dogfood
+            paths: "tests/test_dogfood.py"
+          - name: golden
+            paths: "tests/test_golden.py"
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # setuptools-scm derives the version from git tags; fetch them so the
+          # editable install can resolve a version (mirrors python-publish.yml).
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install package with dev/test extras
+        run: |
+          python -m pip install --upgrade pip
+          # The dev extra pulls pytest plus the document libraries that
+          # tests/test_ingest.py uses to generate fixtures.
+          python -m pip install -e .[dev]
+
+      - name: Run ${{ matrix.battery.name }} battery
+        run: python -m pytest -q ${{ matrix.battery.paths }}

{requirements_as_code-0.7.2 → requirements_as_code-0.7.13}/.gitignore

@@ -1,3 +1,6 @@
+# macOS
+.DS_Store
+
 # Virtual environments
 .venv/
 venv/

requirements_as_code-0.7.13/.rac/config.yaml

@@ -0,0 +1 @@
+repository_key: RAC

requirements_as_code-0.7.13/CHANGELOG.md

@@ -0,0 +1,173 @@
+# Changelog
+
+User-visible changes to RAC, by release. Follows the spirit of
+[Keep a Changelog](https://keepachangelog.com/): user impact over implementation
+details, release history over commit history.
+
+## Unreleased
+
+### Added
+
+- `rac migrate metadata <directory>` — migrate existing recognized artifacts
+  onto canonical frontmatter identity: idempotent, byte-preserving, with
+  `--dry-run` preview; unrecognized documents are reported, never guessed at
+  (v0.7.13).
+
+- `rac resolve <ID>` — resolve any artifact ID (canonical or legacy alias) to
+  its type, title, and path; duplicates are reported with every path, never
+  silently resolved (v0.7.12).
+- `rac find <query>` — deterministic artifact search by ID, title, filename,
+  or path, with `--type` filtering and JSON output (v0.7.12).
+- `rac relationships` human output resolves references to human-friendly
+  labels — `Title (type · ID)` — while JSON keeps stored references unchanged
+  (v0.7.12).
+- `rac index` entries gain an additive `aliases` field: every identifier an
+  artifact answers to, canonical first (v0.7.12).
+
+- `rac init` — establish the repository identity namespace
+  (`.rac/config.yaml` with a `repository_key`); idempotent, and an
+  established key is never silently changed (v0.7.11).
+- Hybrid artifact metadata: a leading YAML frontmatter block
+  (`schema_version`, `id`, `type`, `relationships`) is parsed, strictly
+  schema-validated, and exposed as canonical machine-operational metadata;
+  artifacts without frontmatter remain fully supported (v0.7.11).
+- System-assigned opaque artifact IDs (e.g. `RAC-01JY4M8X2QZ7`): branch-safe,
+  offline, stable across renames, moves, and type changes; `rac new` assigns
+  one automatically and `rac index` reports it (v0.7.11).
+- Identity validation: conflicting frontmatter/legacy identity and duplicate
+  canonical IDs are deterministic errors — RAC never silently picks one
+  (v0.7.11).
+- Relationship references resolve against legacy identity aliases (`## ID`
+  values, filename prefixes, stems), so adopting canonical IDs does not break
+  existing human-readable references; RAC's own corpus now carries canonical
+  frontmatter identity (v0.7.11).
+- `rac new <type> <output-path>` — create a valid artifact from its canonical
+  bundled template; deterministic, AI-free, and never overwrites an existing
+  file (v0.7.10).
+- `rac templates` — list the canonical artifact templates available to
+  `rac new`, with `--json` for tools (v0.7.10).
+- `rac validate <directory>` — validate every recognized artifact in a tree in
+  one command; unrecognized documents are skipped, not failed.
+- `rac review <directory>` — full repository review: validation, relationship
+  integrity, and completeness as one prioritized worklist (invalid artifacts
+  first, then broken relationships, then advisory findings), each finding with
+  a concrete suggested action. Exits `1` only on blocking issues.
+- CI trust gates: RAC's own `rac/` corpus must pass `rac validate`,
+  `rac relationships --validate`, and `rac review` (dogfood battery), and CLI
+  output is pinned byte-for-byte by golden tests.
+- README build badge, "How RAC earns trust" section, CHANGELOG.md, and
+  CONTRIBUTING.md.
+- `rac portfolio --json` now lists `artifacts.unknown_paths` (additive).
+- `rac index` — flat artifact inventory (id, type, title, path) for tools and
+  agents (v0.7.5).
+
+### Changed
+
+- Documentation restructured around task-focused guides under `docs/`
+  (quickstart, CLI reference, artifacts, relationships, repository workflow,
+  testing); README simplified to an overview (v0.7.6–v0.7.7).
+
+### Fixed
+
+- RAC's own planning corpus now passes its own validation: one invalid roadmap
+  repaired and all cross-artifact references resolve.
+
+## v0.7.3 — 2026-06-06
+
+### Added
+
+- `rac portfolio` — one-screen repository intelligence: counts by type,
+  validity, completeness, relationship coverage, attention list, health score.
+
+## v0.7.2 — 2026-06-06
+
+### Added
+
+- `rac relationships --validate` — resolve every cross-artifact reference and
+  report broken, ambiguous, self-referencing, or duplicate-identifier findings.
+
+## v0.7.1 — 2026-06-06
+
+### Added
+
+- `rac relationships` — discover and report the explicit references artifacts
+  declare to each other.
+
+## v0.7.0 — 2026-06-06
+
+### Added
+
+- Relationship metadata: artifacts can declare `## Related Requirements`,
+  `## Related Decisions`, and similar sections that RAC recognizes and counts.
+
+## v0.6.3 — 2026-06-05
+
+### Added
+
+- Design artifact type: validate and inspect product-design documents.
+
+## v0.6.2 — 2026-06-05
+
+### Added
+
+- Prompt artifact type: validate and inspect reusable AI prompts.
+
+## v0.6.1 — 2026-06-05
+
+### Added
+
+- Guided improvement for roadmaps (`rac improve` understands roadmap sections).
+
+## v0.6.0 — 2026-06-05
+
+### Added
+
+- Roadmap artifact type: validate and inspect roadmap documents.
+
+## v0.5.2 — 2026-06-05
+
+### Added
+
+- `rac schema` — show the expected structure of any artifact type, with
+  `--template` to emit a starting document.
+
+## v0.5.0 — 2026-06-05
+
+### Added
+
+- `rac improve` — actionable suggestions (and templates) for incomplete
+  artifacts.
+
+## v0.4.2 — 2026-06-05
+
+### Added
+
+- Decision (ADR) artifact type with status/category metadata.
+- `rac inspect` — classify a document and report its completeness.
+
+## v0.3.1 — 2026-06-04
+
+### Added
+
+- More ingest formats (HTML, PPTX, XLSX).
+
+## v0.3.0 — 2026-06-03
+
+### Added
+
+- `rac ingest` — convert DOCX/PDF documents into RAC-compatible Markdown.
+
+## v0.2.0 — 2026-06-02
+
+### Added
+
+- `rac stats` — summarize a directory of artifacts: counts, quality signals,
+  missing recommended sections.
+
+## v0.1.0 – v0.1.3 — 2026-06-01
+
+### Added
+
+- Initial release: `rac validate` and `rac diff` for requirement documents,
+  human and `--json` output, stable exit codes (`0` ok, `1` validation failed,
+  `2` usage error).

requirements_as_code-0.7.13/CONTRIBUTING.md

@@ -0,0 +1,78 @@
+# Contributing to RAC
+
+Thanks for your interest in improving RAC. The project is early and evolving
+quickly — contributions, ideas, and experiments are welcome.
+
+## Local setup
+
+Requires **Python 3.11+**.
+
+```bash
+git clone https://github.com/tcballard/requirements-as-code.git
+cd requirements-as-code
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e '.[dev]'
+```
+
+## Verify a change
+
+Three commands; all must pass before you open a pull request:
+
+```bash
+pytest
+
+rac validate rac/
+
+rac relationships rac/ --validate
+```
+
+- `pytest` runs the full suite, including the **dogfood gate** (RAC's own
+  planning corpus under `rac/` must pass RAC) and **golden output tests**
+  (CLI output is pinned byte-for-byte).
+- If you intentionally changed what the CLI prints, refresh the goldens and
+  commit the diff — it will be reviewed as a product change:
+
+  ```bash
+  RAC_UPDATE_GOLDEN=1 python -m pytest tests/test_golden.py
+  ```
+
+See [docs/testing.md](docs/testing.md) for test layout, fixtures, and useful
+pytest variations.
+
+## Documentation expectations
+
+- `docs/` is the public documentation: quickstart, CLI reference, artifact
+  types, relationships, repository workflow. If your change alters a command's
+  behavior, flags, output, or exit codes, update [docs/cli.md](docs/cli.md) in
+  the same pull request.
+- User-visible changes get a line in [CHANGELOG.md](CHANGELOG.md) under
+  **Unreleased** — user impact over implementation details.
+- JSON output is a stable, versioned contract: field changes must be additive
+  and `schema_version`-gated (see `rac/decisions/`).
+
+## RAC artifact expectations
+
+The `rac/` directory is RAC's own product knowledge — requirements, decisions
+(ADRs), roadmaps, prompts, and designs — maintained with the same care as code:
+
+- Behavior changes that reflect a product decision should trace to an artifact
+  under `rac/` (a roadmap initiative or an ADR).
+- Artifacts you add or edit must keep the corpus green: `rac validate rac/`,
+  `rac relationships rac/ --validate`, and `rac review rac/` all run in CI.
+
+## Commit conventions
+
+Follow [`rac/prompts/rac-agent-commit-guidelines.md`](rac/prompts/rac-agent-commit-guidelines.md):
+
+```text
+<type>(<area>): <imperative summary> [roadmap:vX.Y.Z]
+```
+
+with `type` one of `feat`, `fix`, `test`, `docs`, `refactor`, `chore`. Keep
+commits small and single-purpose.
+
+## License
+
+By contributing you agree your contributions are licensed under the
+[MIT License](LICENSE).

requirements_as_code-0.7.13/PKG-INFO

@@ -0,0 +1,138 @@
+Metadata-Version: 2.4
+Name: requirements-as-code
+Version: 0.7.13
+Summary: RAC — lint and diff product requirements written in Markdown.
+Author: tcballard
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/tcballard/requirements-as-code
+Project-URL: Repository, https://github.com/tcballard/requirements-as-code
+Project-URL: Issues, https://github.com/tcballard/requirements-as-code/issues
+Keywords: requirements,product-management,markdown,linter,cli,diff
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Documentation
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: markdown-it-py>=3.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: ingest
+Requires-Dist: markitdown[docx]; extra == "ingest"
+Provides-Extra: ingest-pdf
+Requires-Dist: markitdown[pdf]; extra == "ingest-pdf"
+Provides-Extra: ingest-office
+Requires-Dist: markitdown[pptx,xls,xlsx]; extra == "ingest-office"
+Provides-Extra: ingest-all
+Requires-Dist: markitdown[docx,pdf,pptx,xls,xlsx]; extra == "ingest-all"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: markitdown[docx,pdf,pptx,xls,xlsx]; extra == "dev"
+Requires-Dist: python-docx; extra == "dev"
+Requires-Dist: python-pptx; extra == "dev"
+Requires-Dist: openpyxl; extra == "dev"
+Requires-Dist: reportlab; extra == "dev"
+Dynamic: license-file
+
+# Requirements as Code
+
+[![CI](https://github.com/tcballard/requirements-as-code/actions/workflows/ci.yml/badge.svg)](https://github.com/tcballard/requirements-as-code/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/requirements-as-code)](https://pypi.org/project/requirements-as-code/)
+
+> **Treat product knowledge like source code.**
+
+RAC is a command-line tool for managing requirements, decisions, roadmaps, prompts,
+and design artifacts as plain Markdown, right inside your Git repository.
+
+```bash
+pip install requirements-as-code
+```
+
+## What is RAC?
+
+The code is structured, the tests are automated, the infrastructure is versioned —
+but the *reasoning* behind what you build is scattered across documents, tickets,
+chats, and AI conversations. RAC brings that knowledge back into the repository.
+
+You write product thinking in Markdown; RAC validates it, inspects it, and connects
+it — so it stays durable, reviewable, and usable as context for both humans and AI.
+No proprietary formats, no hosted platform, no lock-in.
+
+## Who is it for?
+
+- **Software and product teams** who want the *why* behind their software versioned
+  alongside the code.
+- **AI-native teams** who need structured, durable context instead of more scattered
+  chat history.
+
+## Install
+
+Requires Python 3.11+.
+
+```bash
+pip install requirements-as-code
+# or
+uv tool install requirements-as-code
+```
+
+## Quick Start
+
+```bash
+rac validate requirement.md   # check one artifact
+rac validate rac/             # check every artifact in a directory
+rac inspect requirement.md    # see its type and completeness
+rac stats rac/                # summarize a directory of artifacts
+rac review rac/               # full repository review, worst problems first
+```
+
+New to RAC? Walk through your first artifact in five minutes:
+**[docs/quickstart.md](docs/quickstart.md)**.
+
+## Supported Artifact Types
+
+- **Requirements** — what needs to exist
+- **Decisions** — why choices were made (ADRs)
+- **Roadmaps** — where the product is heading
+- **Prompts** — reusable AI collaboration patterns
+- **Designs** — product experience thinking
+
+Everything stays plain Markdown — see **[docs/artifacts.md](docs/artifacts.md)**.
+
+## Documentation
+
+- [Quickstart](docs/quickstart.md) — install and try RAC in five minutes
+- [CLI reference](docs/cli.md) — every command, flag, and exit code
+- [Artifact types](docs/artifacts.md) — the five types and their sections
+- [Relationships](docs/relationships.md) — link artifacts and validate the links
+- [Repository workflow](docs/repo-workflow.md) — organize a repo with RAC
+- [Testing & contributing](docs/testing.md) — local setup and verification
+- [Examples](docs/examples.md) — small, realistic artifacts
+
+## How RAC earns trust
+
+RAC asks you to trust it with your product knowledge, so it holds itself to the
+same standard it applies to your repository:
+
+- **It dogfoods itself.** RAC's own planning corpus under [`rac/`](rac/) is
+  validated by RAC in CI (`rac validate rac/`, `rac relationships rac/ --validate`,
+  `rac review rac/`) — if the tool's rules break the tool's own artifacts, the
+  build fails.
+- **Output is a contract.** Golden tests pin the CLI's human and JSON output
+  byte-for-byte; any change to what RAC prints is reviewed as a product change.
+- **JSON is versioned.** Machine-readable output carries a `schema_version` and
+  only changes additively.
+
+## Project Status
+
+RAC is early and evolving quickly. A terminal Explorer for browsing your knowledge
+base is planned. Contributions, ideas, and experiments are welcome — see
+[CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT

requirements_as_code-0.7.13/README.md

@@ -0,0 +1,97 @@
+# Requirements as Code
+
+[![CI](https://github.com/tcballard/requirements-as-code/actions/workflows/ci.yml/badge.svg)](https://github.com/tcballard/requirements-as-code/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/requirements-as-code)](https://pypi.org/project/requirements-as-code/)
+
+> **Treat product knowledge like source code.**
+
+RAC is a command-line tool for managing requirements, decisions, roadmaps, prompts,
+and design artifacts as plain Markdown, right inside your Git repository.
+
+```bash
+pip install requirements-as-code
+```
+
+## What is RAC?
+
+The code is structured, the tests are automated, the infrastructure is versioned —
+but the *reasoning* behind what you build is scattered across documents, tickets,
+chats, and AI conversations. RAC brings that knowledge back into the repository.
+
+You write product thinking in Markdown; RAC validates it, inspects it, and connects
+it — so it stays durable, reviewable, and usable as context for both humans and AI.
+No proprietary formats, no hosted platform, no lock-in.
+
+## Who is it for?
+
+- **Software and product teams** who want the *why* behind their software versioned
+  alongside the code.
+- **AI-native teams** who need structured, durable context instead of more scattered
+  chat history.
+
+## Install
+
+Requires Python 3.11+.
+
+```bash
+pip install requirements-as-code
+# or
+uv tool install requirements-as-code
+```
+
+## Quick Start
+
+```bash
+rac validate requirement.md   # check one artifact
+rac validate rac/             # check every artifact in a directory
+rac inspect requirement.md    # see its type and completeness
+rac stats rac/                # summarize a directory of artifacts
+rac review rac/               # full repository review, worst problems first
+```
+
+New to RAC? Walk through your first artifact in five minutes:
+**[docs/quickstart.md](docs/quickstart.md)**.
+
+## Supported Artifact Types
+
+- **Requirements** — what needs to exist
+- **Decisions** — why choices were made (ADRs)
+- **Roadmaps** — where the product is heading
+- **Prompts** — reusable AI collaboration patterns
+- **Designs** — product experience thinking
+
+Everything stays plain Markdown — see **[docs/artifacts.md](docs/artifacts.md)**.
+
+## Documentation
+
+- [Quickstart](docs/quickstart.md) — install and try RAC in five minutes
+- [CLI reference](docs/cli.md) — every command, flag, and exit code
+- [Artifact types](docs/artifacts.md) — the five types and their sections
+- [Relationships](docs/relationships.md) — link artifacts and validate the links
+- [Repository workflow](docs/repo-workflow.md) — organize a repo with RAC
+- [Testing & contributing](docs/testing.md) — local setup and verification
+- [Examples](docs/examples.md) — small, realistic artifacts
+
+## How RAC earns trust
+
+RAC asks you to trust it with your product knowledge, so it holds itself to the
+same standard it applies to your repository:
+
+- **It dogfoods itself.** RAC's own planning corpus under [`rac/`](rac/) is
+  validated by RAC in CI (`rac validate rac/`, `rac relationships rac/ --validate`,
+  `rac review rac/`) — if the tool's rules break the tool's own artifacts, the
+  build fails.
+- **Output is a contract.** Golden tests pin the CLI's human and JSON output
+  byte-for-byte; any change to what RAC prints is reviewed as a product change.
+- **JSON is versioned.** Machine-readable output carries a `schema_version` and
+  only changes additively.
+
+## Project Status
+
+RAC is early and evolving quickly. A terminal Explorer for browsing your knowledge
+base is planned. Contributions, ideas, and experiments are welcome — see
+[CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT