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

{requirements_as_code-0.7.0/requirements_as_code.egg-info → requirements_as_code-0.7.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: requirements-as-code
-Version: 0.7.0
+Version: 0.7.2
 Summary: RAC — lint and diff product requirements written in Markdown.
 Author: tcballard
 License-Expression: MIT
@@ -863,6 +863,78 @@ registered schemas are supported; custom schemas are out of scope.
 
 ---
 
+## Relationships
+
+Inspect the explicit [relationship metadata](#relationship-metadata) declared
+across a repository — a deterministic, read-only view of how artifacts reference
+one another, without opening every file.
+
+```bash
+rac relationships planning/
+rac relationships planning/ --json
+rac relationships planning/ --top-level     # don't recurse into subdirectories
+rac relationships requirements/search.md    # a single file works too
+```
+
+```text
+Relationships
+
+Files Inspected: 24
+Artifacts With Relationships: 8
+Relationships Found: 14
+
+By Type:
+- Related Requirements: 4
+- Related Decisions: 6
+- Related Roadmaps: 2
+- Related Prompts: 1
+- Supersedes: 1
+
+requirements/search.md
+  Related Decisions:
+  - ADR-004
+```
+
+`--json` returns structured data for automation and future viewers (ADR-015 —
+relationship intelligence lives in RAC Core, not the UI):
+
+```json
+{
+  "directory": "planning",
+  "recursive": true,
+  "total_files": 24,
+  "artifacts_with_relationships": 8,
+  "relationship_count": 14,
+  "counts": { "related_decisions": 6, "related_requirements": 4 },
+  "artifacts": [
+    {
+      "path": "requirements/search.md",
+      "type": "requirement",
+      "relationships": { "related_decisions": ["ADR-004"] }
+    }
+  ]
+}
+```
+
+Notes:
+
+- **Counts are individual references.** `relationship_count` equals
+  `sum(counts.values())`; an artifact listing two decisions contributes two.
+- **`total_files`** counts every Markdown file considered — including files with
+  no relationships and Unknown artifacts.
+- **Supersedes is a relationship here.** Unlike `rac inspect` (where `supersedes`
+  is a top-level scalar), this command reports it alongside the `related_*`
+  sections, in both `counts` and per-artifact `relationships`.
+- **Spec-driven.** Extraction is keyed off each artifact type's declared sections.
+  Unknown artifacts are counted but contribute no relationships (and never appear
+  in `artifacts`); RAC does not scan arbitrary Markdown.
+- **Read-only and exit `0`.** The command never modifies files and exits `0`
+  whether or not relationships are found (`2` only for a missing path or a
+  non-Markdown file). It does **not** resolve or validate targets — broken-link
+  detection is a later release.
+
+---
+
 ## Review (Planned)
 
 AI-assisted product review.

{requirements_as_code-0.7.0 → requirements_as_code-0.7.2}/README.md

@@ -823,6 +823,78 @@ registered schemas are supported; custom schemas are out of scope.
 
 ---
 
+## Relationships
+
+Inspect the explicit [relationship metadata](#relationship-metadata) declared
+across a repository — a deterministic, read-only view of how artifacts reference
+one another, without opening every file.
+
+```bash
+rac relationships planning/
+rac relationships planning/ --json
+rac relationships planning/ --top-level     # don't recurse into subdirectories
+rac relationships requirements/search.md    # a single file works too
+```
+
+```text
+Relationships
+
+Files Inspected: 24
+Artifacts With Relationships: 8
+Relationships Found: 14
+
+By Type:
+- Related Requirements: 4
+- Related Decisions: 6
+- Related Roadmaps: 2
+- Related Prompts: 1
+- Supersedes: 1
+
+requirements/search.md
+  Related Decisions:
+  - ADR-004
+```
+
+`--json` returns structured data for automation and future viewers (ADR-015 —
+relationship intelligence lives in RAC Core, not the UI):
+
+```json
+{
+  "directory": "planning",
+  "recursive": true,
+  "total_files": 24,
+  "artifacts_with_relationships": 8,
+  "relationship_count": 14,
+  "counts": { "related_decisions": 6, "related_requirements": 4 },
+  "artifacts": [
+    {
+      "path": "requirements/search.md",
+      "type": "requirement",
+      "relationships": { "related_decisions": ["ADR-004"] }
+    }
+  ]
+}
+```
+
+Notes:
+
+- **Counts are individual references.** `relationship_count` equals
+  `sum(counts.values())`; an artifact listing two decisions contributes two.
+- **`total_files`** counts every Markdown file considered — including files with
+  no relationships and Unknown artifacts.
+- **Supersedes is a relationship here.** Unlike `rac inspect` (where `supersedes`
+  is a top-level scalar), this command reports it alongside the `related_*`
+  sections, in both `counts` and per-artifact `relationships`.
+- **Spec-driven.** Extraction is keyed off each artifact type's declared sections.
+  Unknown artifacts are counted but contribute no relationships (and never appear
+  in `artifacts`); RAC does not scan arbitrary Markdown.
+- **Read-only and exit `0`.** The command never modifies files and exits `0`
+  whether or not relationships are found (`2` only for a missing path or a
+  non-Markdown file). It does **not** resolve or validate targets — broken-link
+  detection is a later release.
+
+---
+
 ## Review (Planned)
 
 AI-assisted product review.

requirements_as_code-0.7.2/planning/prompt/rac-agent-compression.md

@@ -0,0 +1,12 @@
+Create a compact handoff for a fresh coding session.
+
+Include only:
+- goal
+- approved scope
+- files changed or likely touched
+- architecture constraints
+- tests required
+- commands to run
+- unresolved questions
+
+Do not include conversation history.

requirements_as_code-0.7.2/planning/prompt/rac-agent-instructions.md

@@ -0,0 +1,24 @@
+# RAC Agent Instructions
+
+Before coding:
+- Refresh from origin/main unless told otherwise.
+- Read the target roadmap file and relevant ADRs.
+- Produce a plan before implementation.
+- Do not expand release scope beyond the roadmap.
+
+Release discipline:
+- Work on a feature branch, not main.
+- Do not include Claude attribution in commits.
+- After GitHub merge, refresh local main.
+- Prune merged branches when asked.
+
+Architecture:
+- Prefer schema-driven artifact behavior.
+- Do not add artifact-specific validation paths if a generic path can handle it.
+- Keep classification separate from validation.
+- Invalid but recognizable artifacts may still classify as their artifact type.
+
+Testing:
+- Add negative boundary tests for each new artifact type.
+- Test that adjacent artifact types do not misclassify as each other.
+- Run pytest before commit.

requirements_as_code-0.7.2/planning/prompt/rac-agent-release-gate-major.md

@@ -0,0 +1,261 @@
+We are preparing a major release for RAC.
+
+Your job is to run a release gate review, not to implement changes yet.
+
+Context:
+- RAC is a Markdown-first CLI for requirements-as-code.
+- The system supports typed product artifacts such as Requirements, Decisions, Roadmaps, Designs, and related schema/template/improve/inspect/stats behavior.
+- The product goal is deterministic artifact recognition, structural validation, useful CLI feedback, and stable JSON contracts.
+- The release must not drift into project management, UI rendering, semantic scoring, AI interpretation, collaboration workflows, databases, accounts, or web-app behavior unless explicitly approved.
+
+Review the current repository against these gates:
+
+## 1. Product scope gate
+
+Identify anything in this release that exceeds the intended product boundary.
+
+Check for:
+- behavior that interprets artifact quality instead of validating structure
+- workflow/project-management behavior
+- semantic relationship analysis
+- UI/design-token/rendering behavior
+- hidden AI-like inference
+- new concepts not documented in roadmap, ADRs, or release notes
+- CLI behavior that surprises the user
+
+Return:
+- PASS / BLOCK
+- exact files or commands involved
+- required scope cuts before release
+
+## 2. Architecture consistency gate
+
+Review whether the artifact model is still coherent.
+
+Check:
+- whether classification, validation, stats, schema, templates, inspect, and improve use shared artifact metadata where possible
+- whether any artifact has special-case logic that should be generalized
+- whether Roadmap, Design, Decision, and Requirement behavior follow the same architectural pattern
+- whether new code duplicates existing artifact handling
+- whether any module is becoming too large or too coupled
+- whether public contracts are separated from implementation details
+
+Return:
+- PASS / BLOCK
+- duplicated paths
+- special cases that should be removed
+- proposed simplification before release
+
+## 3. Duplication and deletion gate
+
+This is a hard simplification review.
+
+Answer these directly:
+
+- What code became obsolete during this release?
+- What can be deleted before release?
+- What logic was copied instead of shared?
+- Which artifact-specific branches can be collapsed into generic artifact-spec-driven behavior?
+- Did any file grow past a size where it should be split?
+- Are there old fixtures, examples, or docs that now contradict the current model?
+- Are there stale branches, stale roadmap files, or stale TODOs that should be cleaned up?
+
+Return:
+- required deletions
+- optional cleanup
+- changes that should wait until after release
+
+## 4. CLI contract gate
+
+Review every public command affected by this release.
+
+Commands to check:
+- rac validate
+- rac diff
+- rac stats
+- rac inspect
+- rac improve
+- rac schema
+- rac ingest, if touched
+
+For each affected command, verify:
+- human output is stable and understandable
+- JSON output is stable and documented
+- exit codes are intentional
+- invalid input behavior is clear
+- warnings vs errors are consistent
+- unsupported artifact behavior is explicit
+- examples in README/docs still work
+
+Return a table:
+
+Command | Changed? | Human output ok? | JSON ok? | Exit codes ok? | Docs ok? | Blockers
+
+## 5. Classification boundary gate
+
+Review artifact classification behavior.
+
+Check:
+- Requirements do not classify as Design
+- Designs do not classify as Requirements
+- Roadmaps classify by approved structure, not loose title matching alone except where explicitly intended
+- UI/design-themed titles alone do not classify as Design
+- invalid but recognizable artifacts classify correctly, then fail validation separately
+- incomplete artifacts behave according to the spec
+- mixed documents do not produce surprising classifications
+- negative fixtures exist for adjacent artifact types
+
+Return:
+- PASS / BLOCK
+- missing boundary tests
+- risky classification rules
+- recommended fixture additions
+
+## 6. Validation and schema gate
+
+Check that validation behavior and schema output agree.
+
+Verify:
+- required sections match the artifact specs
+- recommended and optional sections are consistent across schema, templates, validation, and docs
+- metadata vocabularies are enforced consistently
+- missing required sections produce clear errors
+- invalid metadata values produce clear errors
+- schema JSON is stable and documented
+- template output follows canonical section order
+
+Return:
+- mismatches
+- missing tests
+- release blockers
+
+## 7. Test and verification gate
+
+Do not accept “tests pass” as enough.
+
+Run or identify the exact commands needed to verify the release.
+
+Check:
+- unit tests for changed behavior
+- CLI smoke tests
+- classification boundary tests
+- negative fixtures
+- JSON output snapshots or equivalent assertions
+- docs examples manually or automatically verified
+- packaging/build check
+- import check from a clean environment, if practical
+
+Return:
+- exact commands run
+- exact commands still needed
+- failures
+- missing test files
+- blockers
+
+If tests are missing for new behavior, mark the release BLOCKED.
+
+## 8. Documentation gate
+
+Review documentation from a new user’s point of view.
+
+Check:
+- README reflects current commands
+- artifact docs match implementation
+- examples use current output
+- release notes or changelog entry exists
+- ADRs are not contradicted
+- roadmap item is updated or marked complete
+- install/publish instructions are still accurate
+- known limitations are explicit
+
+Return:
+- stale docs
+- missing docs
+- docs that overpromise behavior
+
+## 9. Release hygiene gate
+
+Check repository and release state.
+
+Verify:
+- working tree is clean
+- release branch is based on current origin/main
+- merged branches are pruned or listed for pruning
+- version number is updated consistently
+- package metadata is correct
+- no generated Claude attribution appears in commits, PR text, release notes, or docs
+- CI is green
+- build artifacts are not accidentally committed
+- no credentials or local paths leaked
+
+Return:
+- PASS / BLOCK
+- exact commands to confirm state
+- required cleanup
+
+## 10. Backward compatibility and migration gate
+
+Identify anything that could break existing users.
+
+Check:
+- command names
+- arguments and flags
+- JSON field names
+- exit codes
+- artifact classification behavior
+- validation strictness
+- package extras
+- import paths
+- documented examples
+
+Return:
+- breaking changes
+- whether each breaking change is intentional
+- migration note required
+- release blocker if undocumented
+
+## Output format
+
+Return the review in this structure:
+
+# Major Release Gate Review
+
+## Decision
+PASS or BLOCK
+
+## Release blockers
+List only issues that must be fixed before release.
+
+## Required simplifications
+List duplication, deletion, or extraction work required before release.
+
+## Test evidence
+List commands run and results. If not run, say NOT RUN.
+
+## Product scope issues
+List any behavior that exceeds the intended boundary.
+
+## Architecture issues
+List duplicated or inconsistent implementation paths.
+
+## CLI contract issues
+List command/output/JSON/exit-code problems.
+
+## Documentation issues
+List stale, missing, or overpromising docs.
+
+## Release hygiene issues
+List branch/version/CI/commit/publishing concerns.
+
+## Safe to defer
+List cleanup that is real but not release-blocking.
+
+## Exact next actions
+Give a short checklist of the next changes to make.
+
+Important rules:
+- Do not implement anything in this pass.
+- Do not invent test results. If you did not run a command, mark it NOT RUN.
+- Cite exact files and commands.
+- Treat missing tests for new public behavior as a blocker.
+- Treat duplicated artifact-specific

requirements_as_code-0.7.2/planning/prompt/rac-agent-release-gate-minor.md

@@ -0,0 +1,23 @@
+# Minor Release Gate
+
+Before completing any 0.x.n release:
+
+## Duplication
+- Did this release add artifact-specific classification logic?
+- Did it duplicate validation, schema, template, stats, or improve behavior?
+- Can new behavior be expressed through ArtifactSpec instead?
+- Are there two sources of truth for sections, metadata, or guidance?
+
+## Simplification
+- What code became obsolete?
+- What branch or special case can be removed?
+- Did any file grow past the agreed limit?
+- Should a helper be extracted?
+- Did this release increase the number of artifact-specific conditionals?
+
+## Verification
+- Are there negative classification tests?
+- Are adjacent artifact types tested against each other?
+- Are incomplete-but-recognizable artifacts tested?
+- Are CLI human and JSON outputs tested?
+- Was pytest run before commit?

requirements_as_code-0.7.2/planning/prompt/rac-agent-session-start.md

@@ -0,0 +1,23 @@
+We are working on RAC, a Python CLI for requirements-as-code.
+
+RAC models product-management Markdown artifacts as deterministic, typed artifacts.
+Current artifact families include Requirements, Decisions, Roadmaps, Prompts, and Design.
+
+Core principles:
+- Markdown-first.
+- Deterministic classification.
+- Structural validation, not semantic scoring unless explicitly planned.
+- CLI contracts matter: human output, JSON output, exit codes, and templates must be specified.
+- Version numbers are scope fences.
+- Prefer schema/artifact-spec-driven behavior over artifact-specific branches.
+- Invalid but recognizable artifacts may still classify as their artifact type, then fail validation.
+
+Before coding:
+1. Refresh from `origin/main`.
+2. Confirm branch state.
+3. Read the relevant roadmap item.
+4. Check against ADRs.
+5. Produce an implementation contract.
+6. Wait for approval.
+
+Do not implement until I approve the plan.

{requirements_as_code-0.7.0 → requirements_as_code-0.7.2}/rac/artifacts.py

@@ -50,6 +50,12 @@ class ArtifactSpec:
     # matching, so synonyms contribute to confidence. Matching is deterministic
     # (dict lookup) and case-insensitive (headings are normalized first).
     synonyms: dict[str, str] = field(default_factory=dict)
+    # Canonical-identifier section (v0.7.2 relationship validation): the normalized
+    # section name whose value is this artifact type's identifier, consulted by
+    # ``rac.relationships.artifact_identifier`` before falling back to the filename
+    # stem. A forward hook — no spec sets it today; relationship resolution works
+    # from the ``## ID`` section and filename stem until a type opts in.
+    id_field: str | None = None
 
     @property
     def expected(self) -> tuple[str, ...]:
@@ -68,23 +74,11 @@ class ArtifactSpec:
 # extracted, but never scored, never templated, never reported as missing
 # (REQ-002). v0.7.0 treats them as metadata only — RAC extracts and counts the
 # references but does not resolve, validate, or graph them.
-
-# The cross-artifact "Related X" sections. These populate the ``relationships``
-# dict in ``rac inspect`` output. ``related designs`` is included so every peer
-# artifact type can be referenced.
-RELATED_SECTIONS: tuple[str, ...] = (
-    "related requirements",
-    "related decisions",
-    "related roadmaps",
-    "related prompts",
-    "related designs",
-)
-
-# The full relationship-section vocabulary, including ``supersedes``. ``stats``
-# counts presence across all of these. ``supersedes`` is the one exception that
-# does *not* appear in the inspect ``relationships`` dict: it remains a top-level
-# scalar field for backwards compatibility (see rac.inspect / ADR-007).
-RELATIONSHIP_SECTIONS: tuple[str, ...] = RELATED_SECTIONS + ("supersedes",)
+#
+# The relationship-section vocabulary and its canonical ordering live in
+# :mod:`rac.relationships` (the module that owns relationship logic). This module
+# only owns the human-facing ``descriptions`` for those sections, which the specs
+# below consume.
 
 # One-line descriptions for every relationship section, surfaced by `rac schema`.
 # Relationship sections deliberately carry no ``guidance`` — guidance gates

{requirements_as_code-0.7.0 → requirements_as_code-0.7.2}/rac/cli.py

@@ -8,11 +8,14 @@ Commands:
     rac inspect <file.md | -> [--json]
     rac improve <file.md | -> [--json | --template]
     rac schema [--list] [type] [--json | --template]
+    rac relationships <dir | file.md> [--validate] [--json] [--top-level]
 
 Exit codes:
-    0  success (incl. inspect/improve reporting Unknown)
+    0  success (incl. inspect/improve reporting Unknown; relationships found or
+       not; --validate with all references resolved)
     1  validate: errors found; stats: no valid known artifacts; ingest:
-       conversion failed
+       conversion failed; relationships --validate: broken/ambiguous/self
+       references or duplicate identifiers found
     2  usage / IO error (file not found, not a directory, unsupported type,
        refuse-to-overwrite)
 """
@@ -31,6 +34,12 @@ from .classification import score_artifacts
 from .improve import improve_product
 from .inspect import build_inspection, inspect_directory
 from .parser import parse, parse_file
+from .relationships import (
+    build_relationship_report,
+    build_relationship_report_file,
+    validate_relationships,
+    validate_relationships_file,
+)
 from .schema import available_schemas, schema_reference
 from .stats import collect_stats
 from .validate import has_errors, validate
@@ -236,6 +245,51 @@ def cmd_schema(args: argparse.Namespace) -> int:
     return EXIT_OK
 
 
+def cmd_relationships(args: argparse.Namespace) -> int:
+    path = Path(args.path)
+    # --recursive is the default; --top-level disables it. If both are given,
+    # --top-level wins (mirrors `rac inspect`).
+    if path.is_dir():
+        is_dir = True
+    elif path.is_file():
+        if path.suffix.lower() not in (".md", ".markdown"):
+            print(
+                f"rac: relationships expects a Markdown file or directory; "
+                f"convert it first with: rac ingest {args.path}",
+                file=sys.stderr,
+            )
+            raise SystemExit(EXIT_USAGE)
+        is_dir = False
+    else:
+        print(f"rac: path not found: {args.path}", file=sys.stderr)
+        raise SystemExit(EXIT_USAGE)
+
+    if args.validate:
+        if is_dir:
+            report = validate_relationships(args.path, recursive=not args.top_level)
+        else:
+            report = validate_relationships_file(args.path)
+        if args.json:
+            print(outputs.render_relationship_validation_json(report))
+        else:
+            print(outputs.render_relationship_validation_human(report))
+        # Validation-style exit codes (REQ-007): 0 when everything resolves, 1 when
+        # any issue is found, 2 (above) for usage errors.
+        return EXIT_OK if report.ok else EXIT_VALIDATION_FAILED
+
+    if is_dir:
+        report = build_relationship_report(args.path, recursive=not args.top_level)
+    else:
+        report = build_relationship_report_file(args.path)
+    if args.json:
+        print(outputs.render_relationships_json(report))
+    else:
+        print(outputs.render_relationships_human(report))
+    # A completed inspection always succeeds — finding no relationships is a valid
+    # outcome, not an error (REQ-010).
+    return EXIT_OK
+
+
 def build_parser() -> argparse.ArgumentParser:
     version_str = f"rac {__version__}"
 
@@ -387,6 +441,35 @@ def build_parser() -> argparse.ArgumentParser:
     )
     p_schema.set_defaults(func=cmd_schema)
 
+    p_relationships = sub.add_parser(
+        "relationships",
+        help="Inspect explicit relationships across a directory (or single file).",
+        parents=[version_parent],
+    )
+    p_relationships.add_argument(
+        "path", help="A directory to scan, or a single Markdown file."
+    )
+    p_relationships.add_argument(
+        "--json", action="store_true", help="Emit JSON instead of human-readable text."
+    )
+    p_relationships.add_argument(
+        "--validate",
+        action="store_true",
+        help="Resolve references against discovered artifacts; exit 1 if any are "
+        "broken, ambiguous, self-referencing, or have duplicate identifiers.",
+    )
+    p_relationships.add_argument(
+        "--top-level",
+        action="store_true",
+        help="When inspecting a directory, only its top-level files (no recursion).",
+    )
+    p_relationships.add_argument(
+        "--recursive",
+        action="store_true",
+        help="Recurse into subdirectories (the default; accepted for clarity).",
+    )
+    p_relationships.set_defaults(func=cmd_relationships)
+
     return parser