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

{requirements_as_code-0.7.1/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.1
+Version: 0.7.2
 Summary: RAC — lint and diff product requirements written in Markdown.
 Author: tcballard
 License-Expression: MIT

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.1 → 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, ...]:

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

@@ -8,13 +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> [--json] [--top-level]
+    rac relationships <dir | file.md> [--validate] [--json] [--top-level]
 
 Exit codes:
     0  success (incl. inspect/improve reporting Unknown; relationships found or
-       not)
+       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)
 """
@@ -36,6 +37,8 @@ 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
@@ -244,10 +247,10 @@ def cmd_schema(args: argparse.Namespace) -> int:
 
 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():
-        # --recursive is the default; --top-level disables it. If both are given,
-        # --top-level wins (mirrors `rac inspect`).
-        report = build_relationship_report(args.path, recursive=not args.top_level)
+        is_dir = True
     elif path.is_file():
         if path.suffix.lower() not in (".md", ".markdown"):
             print(
@@ -256,11 +259,28 @@ def cmd_relationships(args: argparse.Namespace) -> int:
                 file=sys.stderr,
             )
             raise SystemExit(EXIT_USAGE)
-        report = build_relationship_report_file(args.path)
+        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:
@@ -432,6 +452,12 @@ def build_parser() -> argparse.ArgumentParser:
     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",

{requirements_as_code-0.7.1 → requirements_as_code-0.7.2}/rac/outputs.py

@@ -16,7 +16,14 @@ from .improve import ImprovementResult
 from .ingest import IngestResult
 from .inspect import DirectoryInspection, InspectionResult
 from .models import Diff, Issue, Product
-from .relationships import RelationshipReport
+from .relationships import (
+    ISSUE_DUPLICATE_IDENTIFIER,
+    ISSUE_SELF_REFERENCE,
+    ISSUE_TARGET_AMBIGUOUS,
+    ISSUE_TARGET_NOT_FOUND,
+    RelationshipReport,
+    RelationshipValidation,
+)
 from .schema import SchemaReference, template_sections
 from .stats import PortfolioStats
 
@@ -679,6 +686,63 @@ def render_relationships_json(report: RelationshipReport) -> str:
     return json.dumps(payload, indent=2)
 
 
+# --- relationship validation -------------------------------------------------
+
+# Suffix shown after a broken reference, per issue code.
+_REF_ISSUE_SUFFIX = {
+    ISSUE_TARGET_NOT_FOUND: "not found",
+    ISSUE_TARGET_AMBIGUOUS: "ambiguous",
+    ISSUE_SELF_REFERENCE: "self-reference",
+}
+
+
+def render_relationship_validation_human(report: RelationshipValidation) -> str:
+    lines = [
+        _bold("Relationship Validation"),
+        "",
+        f"Relationships Checked: {report.relationships_checked}",
+        f"Validation Issues: {report.validation_issues}",
+    ]
+
+    duplicates = [i for i in report.issues if i.code == ISSUE_DUPLICATE_IDENTIFIER]
+    references = [i for i in report.issues if i.code != ISSUE_DUPLICATE_IDENTIFIER]
+
+    if duplicates:
+        lines += ["", _bold("Duplicate Identifiers")]
+        for issue in duplicates:
+            count = len(issue.paths or [])
+            lines.append(_red(f"✗ {issue.identifier} ({count} files)"))
+            lines.extend(f"  - {p}" for p in issue.paths or [])
+
+    if references:
+        lines += ["", _bold("Broken Relationships")]
+        current_source = None
+        current_section = None
+        for issue in references:
+            if issue.source_path != current_source:
+                current_source = issue.source_path
+                current_section = None
+                lines += ["", issue.source_path or "<input>"]
+            if issue.relationship != current_section:
+                current_section = issue.relationship
+                lines.append(f"  {_relationship_label(issue.relationship or '')}:")
+            suffix = _REF_ISSUE_SUFFIX.get(issue.code, issue.code)
+            lines.append(_red(f"  ✗ {issue.target} {suffix}"))
+
+    return "\n".join(lines)
+
+
+def render_relationship_validation_json(report: RelationshipValidation) -> str:
+    payload = {
+        "directory": report.directory,
+        "recursive": report.recursive,
+        "relationships_checked": report.relationships_checked,
+        "validation_issues": report.validation_issues,
+        "issues": [issue.to_dict() for issue in report.issues],
+    }
+    return json.dumps(payload, indent=2)
+
+
 # --- ingest ------------------------------------------------------------------