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

{requirements_as_code-0.7.1/requirements_as_code.egg-info → requirements_as_code-0.7.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: requirements-as-code
-Version: 0.7.1
+Version: 0.7.3
 Summary: RAC — lint and diff product requirements written in Markdown.
 Author: tcballard
 License-Expression: MIT
@@ -935,6 +935,153 @@ Notes:
 
 ---
 
+## Portfolio
+
+A single-command repository intelligence summary: artifact counts, validation
+health, completeness, relationship integrity, actionable attention items, and an
+overall health score — without manually combining output from multiple commands.
+
+```bash
+rac portfolio ./docs
+rac portfolio ./docs --json
+rac portfolio ./docs --top-level   # don't recurse into subdirectories
+```
+
+```text
+Repository Summary
+==================
+
+Directory:  ./docs
+Artifacts:  42
+
+By Type
+-------
+
+  Requirement    18
+  Decision       12
+  Roadmap        5
+  Prompt         4
+  Design         2
+  Unknown        1
+
+Validation
+----------
+
+  Valid:    40
+  Invalid:  2
+
+Completeness
+------------
+
+  78% (94 / 120 recommended slots filled)
+
+Relationships
+-------------
+
+  Total:    65
+  Valid:    63
+  Broken:   2
+  Orphaned: 4
+  Coverage: 71%
+
+Attention (4 items)
+----------
+
+  ✗ search
+      Validation errors: missing-requirements
+  ! adr-004
+      Missing recommended sections: Alternatives Considered
+  ! q3-roadmap
+      Related Requirements references missing artifact: REQ-999
+  ! req-041
+      Missing recommended sections: Risks
+
+Health Score
+------------
+
+  87 / 100
+```
+
+`--json` returns the stable machine contract (all fields present regardless of
+content, versioned with `schema_version`):
+
+```json
+{
+  "schema_version": "1",
+  "directory": "./docs",
+  "recursive": true,
+  "artifacts": {
+    "total": 42,
+    "by_type": {
+      "requirement": 18,
+      "decision": 12,
+      "roadmap": 5,
+      "prompt": 4,
+      "design": 2,
+      "unknown": 1
+    }
+  },
+  "validation": { "valid": 40, "invalid": 2 },
+  "completeness": { "recommended_slots": 120, "filled": 94, "ratio": 0.7833 },
+  "relationships": {
+    "total": 65,
+    "valid": 63,
+    "broken": 2,
+    "orphaned": 4,
+    "coverage": 0.7143
+  },
+  "attention": [
+    {
+      "path": "requirements/search.md",
+      "identifier": "search",
+      "severity": "error",
+      "code": "invalid-artifact",
+      "message": "Validation errors: missing-requirements"
+    },
+    {
+      "path": "roadmaps/q3-roadmap.md",
+      "identifier": "q3-roadmap",
+      "severity": "warning",
+      "code": "broken-relationship",
+      "message": "Related Requirements references missing artifact: REQ-999"
+    }
+  ],
+  "health": { "score": 87 }
+}
+```
+
+**Health score formula** (deterministic, no AI):
+
+```
+score = round(100 × (0.5 × validity + 0.25 × completeness + 0.25 × rel_integrity))
+```
+
+where each sub-score is a simple ratio that defaults to `1.0` when its
+denominator is zero, so an empty repository always scores 100.
+
+Notes:
+
+- **Advisory command.** `rac portfolio` always exits `0` when a summary is
+  produced (`2` for usage errors — not a directory). For CI hard gates, use
+  `rac relationships --validate` (exits `1` on broken refs).
+- **Attention severity.** `error` means the artifact is structurally invalid;
+  `warning` means it is valid but needs attention (missing recommended sections
+  or a stale relationship reference). Items are ordered errors-first, then by
+  path, then by code — deterministically.
+- **`identifier`** is the artifact's canonical identifier (the same one
+  `rac relationships --validate` resolves against): an explicit `## ID`, else a
+  recognised `TYPE-NNN` filename prefix, else the filename stem.
+- **`rac stats` vs `rac portfolio`.** `rac stats` provides per-feature
+  requirement and metric breakdowns for requirement-focused portfolios.
+  `rac portfolio` provides a whole-repository intelligence rollup across all
+  artifact types.
+- **Orphaned** means no other artifact holds a resolved inbound reference to
+  it — the artifact may still declare outbound relationships.
+- **Coverage** is the fraction of known (non-unknown) artifacts that declare
+  at least one outbound relationship section.
+
+---
+
 ## Review (Planned)
 
 AI-assisted product review.

{requirements_as_code-0.7.1 → requirements_as_code-0.7.3}/README.md

@@ -895,6 +895,153 @@ Notes:
 
 ---
 
+## Portfolio
+
+A single-command repository intelligence summary: artifact counts, validation
+health, completeness, relationship integrity, actionable attention items, and an
+overall health score — without manually combining output from multiple commands.
+
+```bash
+rac portfolio ./docs
+rac portfolio ./docs --json
+rac portfolio ./docs --top-level   # don't recurse into subdirectories
+```
+
+```text
+Repository Summary
+==================
+
+Directory:  ./docs
+Artifacts:  42
+
+By Type
+-------
+
+  Requirement    18
+  Decision       12
+  Roadmap        5
+  Prompt         4
+  Design         2
+  Unknown        1
+
+Validation
+----------
+
+  Valid:    40
+  Invalid:  2
+
+Completeness
+------------
+
+  78% (94 / 120 recommended slots filled)
+
+Relationships
+-------------
+
+  Total:    65
+  Valid:    63
+  Broken:   2
+  Orphaned: 4
+  Coverage: 71%
+
+Attention (4 items)
+----------
+
+  ✗ search
+      Validation errors: missing-requirements
+  ! adr-004
+      Missing recommended sections: Alternatives Considered
+  ! q3-roadmap
+      Related Requirements references missing artifact: REQ-999
+  ! req-041
+      Missing recommended sections: Risks
+
+Health Score
+------------
+
+  87 / 100
+```
+
+`--json` returns the stable machine contract (all fields present regardless of
+content, versioned with `schema_version`):
+
+```json
+{
+  "schema_version": "1",
+  "directory": "./docs",
+  "recursive": true,
+  "artifacts": {
+    "total": 42,
+    "by_type": {
+      "requirement": 18,
+      "decision": 12,
+      "roadmap": 5,
+      "prompt": 4,
+      "design": 2,
+      "unknown": 1
+    }
+  },
+  "validation": { "valid": 40, "invalid": 2 },
+  "completeness": { "recommended_slots": 120, "filled": 94, "ratio": 0.7833 },
+  "relationships": {
+    "total": 65,
+    "valid": 63,
+    "broken": 2,
+    "orphaned": 4,
+    "coverage": 0.7143
+  },
+  "attention": [
+    {
+      "path": "requirements/search.md",
+      "identifier": "search",
+      "severity": "error",
+      "code": "invalid-artifact",
+      "message": "Validation errors: missing-requirements"
+    },
+    {
+      "path": "roadmaps/q3-roadmap.md",
+      "identifier": "q3-roadmap",
+      "severity": "warning",
+      "code": "broken-relationship",
+      "message": "Related Requirements references missing artifact: REQ-999"
+    }
+  ],
+  "health": { "score": 87 }
+}
+```
+
+**Health score formula** (deterministic, no AI):
+
+```
+score = round(100 × (0.5 × validity + 0.25 × completeness + 0.25 × rel_integrity))
+```
+
+where each sub-score is a simple ratio that defaults to `1.0` when its
+denominator is zero, so an empty repository always scores 100.
+
+Notes:
+
+- **Advisory command.** `rac portfolio` always exits `0` when a summary is
+  produced (`2` for usage errors — not a directory). For CI hard gates, use
+  `rac relationships --validate` (exits `1` on broken refs).
+- **Attention severity.** `error` means the artifact is structurally invalid;
+  `warning` means it is valid but needs attention (missing recommended sections
+  or a stale relationship reference). Items are ordered errors-first, then by
+  path, then by code — deterministically.
+- **`identifier`** is the artifact's canonical identifier (the same one
+  `rac relationships --validate` resolves against): an explicit `## ID`, else a
+  recognised `TYPE-NNN` filename prefix, else the filename stem.
+- **`rac stats` vs `rac portfolio`.** `rac stats` provides per-feature
+  requirement and metric breakdowns for requirement-focused portfolios.
+  `rac portfolio` provides a whole-repository intelligence rollup across all
+  artifact types.
+- **Orphaned** means no other artifact holds a resolved inbound reference to
+  it — the artifact may still declare outbound relationships.
+- **Coverage** is the fraction of known (non-unknown) artifacts that declare
+  at least one outbound relationship section.
+
+---
+
 ## Review (Planned)
 
 AI-assisted product review.

{requirements_as_code-0.7.1 → requirements_as_code-0.7.3}/planning/adr/adr-016-relationships-as-structural-references.md

@@ -506,3 +506,5 @@ Review after the first v0.7.x relationship implementation, or before introducing
 * Explorer relationship visualisation
 * workflow-like dependency management
 * relationship scoring
+
+**v0.7.3 note:** `rac portfolio` introduces a health score that includes relationship integrity as one of four weighted factors (0.25 weight). This is the first instance of relationship scoring in RAC Core. The formula is fully deterministic, documented in `rac/portfolio.py`, and uses only counts already produced by `summarize_relationships`. This ADR was reviewed before v0.7.3 implementation; no architectural objections were raised.

requirements_as_code-0.7.3/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.3/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.3/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.3/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.3/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.3}/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, ...]: