requirements-as-code 0.6.2__tar.gz → 0.6.3__tar.gz

{requirements_as_code-0.6.2/requirements_as_code.egg-info → requirements_as_code-0.6.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: requirements-as-code
-Version: 0.6.2
+Version: 0.6.3
 Summary: RAC — lint and diff product requirements written in Markdown.
 Author: tcballard
 License-Expression: MIT
@@ -423,9 +423,12 @@ Counts span all parsed requirement files; a feature with only *warnings* (e.g. n
 metrics) still counts as valid. Invalid files are listed at the end so they are
 never silently skipped.
 
-Decision artifacts are aggregated **separately** so they never distort the
-requirement totals or averages. When a directory contains decisions, a
-`Decisions` section reports the count plus a status and category breakdown:
+Non-requirement artifacts are aggregated **separately** so they never distort the
+requirement totals or averages. Decisions report metadata breakdowns; Roadmaps,
+Prompts, and Designs use lightweight count/valid/invalid summaries.
+
+When a directory contains decisions, a `Decisions` section reports the count plus
+a status and category breakdown:
 
 ```text
 Decisions
@@ -444,11 +447,24 @@ Category
   - Process: 4
 ```
 
-Add `--json` for machine-readable output (a `decisions` block is included only
-when decisions are present). `stats` exits `0` when the directory has at least
-one valid feature or decision, `1` if none, and `2` if the path is not a
-directory. (A `--strict` flag for failing on *any* invalid file — handy in CI —
-is planned.)
+When a directory contains Design artifacts, a lightweight section is shown:
+
+```text
+Designs
+=======
+
+Total: 4
+Valid: 3
+
+Invalid Designs (1)
+  ./planning/design/draft.md — missing-constraints
+```
+
+Add `--json` for machine-readable output. Artifact-specific blocks such as
+`decisions`, `roadmaps`, `prompts`, and `designs` are included only when those
+artifacts are present. `stats` exits `0` when the directory has at least one
+valid known artifact, `1` if none, and `2` if the path is not a directory. (A
+`--strict` flag for failing on *any* invalid file — handy in CI — is planned.)
 
 ---
 
@@ -525,10 +541,10 @@ Missing Sections:
 ```
 
 RAC classifies the document against known artifact schemas (no AI) and reports a
-confidence score. v0.4 recognizes **Requirement** and **Decision** artifacts;
-anything that doesn't fit well is reported as **Unknown** (a valid, successful
-result — not an error). `--json` emits `{ type, confidence, present_sections,
-missing_sections }`.
+confidence score. RAC recognizes **Requirement**, **Decision**, **Roadmap**,
+**Prompt**, and **Design** artifacts; anything that doesn't fit well is reported
+as **Unknown** (a valid, successful result — not an error). `--json` emits
+`{ type, confidence, present_sections, missing_sections }`.
 
 ### Inspect a directory
 
@@ -546,7 +562,10 @@ Files Inspected: 23
 
 Requirements: 7
 Decisions: 3
-Unknown: 13
+Roadmaps: 2
+Prompts: 4
+Designs: 1
+Unknown: 6
 ```
 
 ### Explain a classification (`--verbose`)
@@ -686,10 +705,10 @@ So you can go straight from `rac inspect requirement.md` to
 ```
 
 `improve` generates suggestions for artifact types with complete schema guidance
-coverage. Today that means **Requirement** and **Decision** artifacts. Unknown
-documents return a short explanatory message instead. Future artifact types do
-not become improvable until their schemas define guidance for every required and
-recommended section.
+coverage. Today that means **Requirement**, **Decision**, **Roadmap**, **Prompt**,
+and **Design** artifacts. Unknown documents return a short explanatory message
+instead. Future artifact types do not become improvable until their schemas
+define guidance for every required and recommended section.
 
 Guidance is informational metadata only: it does not influence classification,
 validation, confidence scoring, statistics, or repository analysis.
@@ -709,11 +728,15 @@ rac schema --list
 rac schema --list --json
 rac schema requirement
 rac schema decision --json
+rac schema design
 rac schema requirement --template
+rac schema design --template
 ```
 
 `rac schema <type>` shows the full schema reference: required, recommended, and
 optional sections; descriptions; guidance; and metadata values where applicable.
+Supported schemas are `requirement`, `decision`, `roadmap`, `prompt`, and
+`design`.
 
 ```text
 Artifact Type: Decision
@@ -757,6 +780,7 @@ meaningful product knowledge.
 ```bash
 rac schema requirement --template > requirement.md
 rac schema decision --template > decision.md
+rac schema design --template > design.md
 ```
 
 Generated templates are validation-safe:
@@ -764,6 +788,7 @@ Generated templates are validation-safe:
 ```bash
 rac schema requirement --template | rac validate -
 rac schema decision --template | rac validate -
+rac schema design --template | rac validate -
 ```
 
 Unknown schemas fail with exit code `2` and list available schemas. Only

{requirements_as_code-0.6.2 → requirements_as_code-0.6.3}/README.md

@@ -383,9 +383,12 @@ Counts span all parsed requirement files; a feature with only *warnings* (e.g. n
 metrics) still counts as valid. Invalid files are listed at the end so they are
 never silently skipped.
 
-Decision artifacts are aggregated **separately** so they never distort the
-requirement totals or averages. When a directory contains decisions, a
-`Decisions` section reports the count plus a status and category breakdown:
+Non-requirement artifacts are aggregated **separately** so they never distort the
+requirement totals or averages. Decisions report metadata breakdowns; Roadmaps,
+Prompts, and Designs use lightweight count/valid/invalid summaries.
+
+When a directory contains decisions, a `Decisions` section reports the count plus
+a status and category breakdown:
 
 ```text
 Decisions
@@ -404,11 +407,24 @@ Category
   - Process: 4
 ```
 
-Add `--json` for machine-readable output (a `decisions` block is included only
-when decisions are present). `stats` exits `0` when the directory has at least
-one valid feature or decision, `1` if none, and `2` if the path is not a
-directory. (A `--strict` flag for failing on *any* invalid file — handy in CI —
-is planned.)
+When a directory contains Design artifacts, a lightweight section is shown:
+
+```text
+Designs
+=======
+
+Total: 4
+Valid: 3
+
+Invalid Designs (1)
+  ./planning/design/draft.md — missing-constraints
+```
+
+Add `--json` for machine-readable output. Artifact-specific blocks such as
+`decisions`, `roadmaps`, `prompts`, and `designs` are included only when those
+artifacts are present. `stats` exits `0` when the directory has at least one
+valid known artifact, `1` if none, and `2` if the path is not a directory. (A
+`--strict` flag for failing on *any* invalid file — handy in CI — is planned.)
 
 ---
 
@@ -485,10 +501,10 @@ Missing Sections:
 ```
 
 RAC classifies the document against known artifact schemas (no AI) and reports a
-confidence score. v0.4 recognizes **Requirement** and **Decision** artifacts;
-anything that doesn't fit well is reported as **Unknown** (a valid, successful
-result — not an error). `--json` emits `{ type, confidence, present_sections,
-missing_sections }`.
+confidence score. RAC recognizes **Requirement**, **Decision**, **Roadmap**,
+**Prompt**, and **Design** artifacts; anything that doesn't fit well is reported
+as **Unknown** (a valid, successful result — not an error). `--json` emits
+`{ type, confidence, present_sections, missing_sections }`.
 
 ### Inspect a directory
 
@@ -506,7 +522,10 @@ Files Inspected: 23
 
 Requirements: 7
 Decisions: 3
-Unknown: 13
+Roadmaps: 2
+Prompts: 4
+Designs: 1
+Unknown: 6
 ```
 
 ### Explain a classification (`--verbose`)
@@ -646,10 +665,10 @@ So you can go straight from `rac inspect requirement.md` to
 ```
 
 `improve` generates suggestions for artifact types with complete schema guidance
-coverage. Today that means **Requirement** and **Decision** artifacts. Unknown
-documents return a short explanatory message instead. Future artifact types do
-not become improvable until their schemas define guidance for every required and
-recommended section.
+coverage. Today that means **Requirement**, **Decision**, **Roadmap**, **Prompt**,
+and **Design** artifacts. Unknown documents return a short explanatory message
+instead. Future artifact types do not become improvable until their schemas
+define guidance for every required and recommended section.
 
 Guidance is informational metadata only: it does not influence classification,
 validation, confidence scoring, statistics, or repository analysis.
@@ -669,11 +688,15 @@ rac schema --list
 rac schema --list --json
 rac schema requirement
 rac schema decision --json
+rac schema design
 rac schema requirement --template
+rac schema design --template
 ```
 
 `rac schema <type>` shows the full schema reference: required, recommended, and
 optional sections; descriptions; guidance; and metadata values where applicable.
+Supported schemas are `requirement`, `decision`, `roadmap`, `prompt`, and
+`design`.
 
 ```text
 Artifact Type: Decision
@@ -717,6 +740,7 @@ meaningful product knowledge.
 ```bash
 rac schema requirement --template > requirement.md
 rac schema decision --template > decision.md
+rac schema design --template > design.md
 ```
 
 Generated templates are validation-safe:
@@ -724,6 +748,7 @@ Generated templates are validation-safe:
 ```bash
 rac schema requirement --template | rac validate -
 rac schema decision --template | rac validate -
+rac schema design --template | rac validate -
 ```
 
 Unknown schemas fail with exit code `2` and list available schemas. Only

{requirements_as_code-0.6.2 → requirements_as_code-0.6.3}/rac/artifacts.py

@@ -9,11 +9,12 @@ there is a single source of truth.
 Section names are normalized (stripped + casefolded) for matching; ``display``
 holds the human-facing label.
 
-Four artifact types have a concrete schema today: Requirement (RAC's own format /
+Five artifact types have a concrete schema today: Requirement (RAC's own format /
 validator), Decision (the ADR format used in this repository), Roadmap (outcome- and
 initiative-focused knowledge, added in v0.6.0), and Prompt (structured AI prompts as
-knowledge, added in v0.6.2). Meeting is intentionally deferred until its schema is
-formalized — see planning/roadmap/.
+knowledge, added in v0.6.2), and Design (UX and interaction knowledge, added in
+v0.6.3). Meeting is intentionally deferred until its schema is formalized — see
+planning/roadmap/.
 """
 
 from __future__ import annotations
@@ -241,6 +242,76 @@ ARTIFACT_SPECS: tuple[ArtifactSpec, ...] = (
             "input specification": "input",
         },
     ),
+    ArtifactSpec(
+        name="design",
+        display="Design",
+        required=("context", "user need", "design", "constraints"),
+        recommended=(
+            "rationale",
+            "alternatives",
+            "accessibility",
+            "style guidance",
+            "open questions",
+        ),
+        # Relationship sections are recognized but never scored or templated; they
+        # let a Design reference other artifacts as text without RAC analyzing
+        # those links (relationship analysis is v0.7.x).
+        optional=(
+            "related requirements",
+            "related decisions",
+            "related roadmaps",
+            "related prompts",
+        ),
+        descriptions={
+            "context": "The product area, situation, or experience this design addresses",
+            "user need": "The user, audience, task, pain point, or goal this design supports",
+            "design": "The proposed experience, interaction, layout, flow, or behavior",
+            "constraints": "Technical, product, accessibility, platform, or implementation constraints",
+            "rationale": "Why this design approach was chosen",
+            "alternatives": "Other approaches considered and why they were not chosen",
+            "accessibility": "Accessibility needs and expectations for the design",
+            "style guidance": "Visual, tone, layout, or interaction style guidance",
+            "open questions": "Unresolved design questions to validate or decide later",
+        },
+        guidance={
+            "context": (
+                "What situation, product area, or user experience does this design address?",
+                "Why is this design needed now?",
+            ),
+            "user need": (
+                "Who is the user or audience?",
+                "What task, pain point, or goal does this design support?",
+            ),
+            "design": (
+                "What is the proposed design?",
+                "How should the experience work?",
+            ),
+            "constraints": (
+                "What constraints shape this design?",
+                "What must the design respect or avoid?",
+            ),
+            "rationale": (
+                "Why is this the preferred approach?",
+                "What trade-offs does this design make?",
+            ),
+            "alternatives": (
+                "What other approaches were considered?",
+                "Why were they not chosen?",
+            ),
+            "accessibility": (
+                "What accessibility needs should this design support?",
+                "Are there keyboard, contrast, readability, or screen-reader considerations?",
+            ),
+            "style guidance": (
+                "What visual or interaction style should be followed?",
+                "What patterns should remain consistent?",
+            ),
+            "open questions": (
+                "What still needs to be decided?",
+                "What should be validated or explored further?",
+            ),
+        },
+    ),
 )
 
 

{requirements_as_code-0.6.2 → requirements_as_code-0.6.3}/rac/cli.py

@@ -11,8 +11,8 @@ Commands:
 
 Exit codes:
     0  success (incl. inspect/improve reporting Unknown)
-    1  validate: errors found; stats: no valid features or decisions;
-       ingest: conversion failed
+    1  validate: errors found; stats: no valid known artifacts; ingest:
+       conversion failed
     2  usage / IO error (file not found, not a directory, unsupported type,
        refuse-to-overwrite)
 """
@@ -90,14 +90,15 @@ def cmd_stats(args: argparse.Namespace) -> int:
     else:
         print(outputs.render_stats_human(stats))
     # Success as long as the portfolio has analysable content: at least one valid
-    # feature, one decision, one valid roadmap, or one valid prompt. Invalid files
-    # are reported but don't fail the run on their own. (A future --strict flag will
-    # fail the run if *any* file is invalid, for CI use.)
+    # feature, one decision, one valid roadmap, one valid prompt, or one valid
+    # design. Invalid files are reported but don't fail the run on their own. (A
+    # future --strict flag will fail the run if *any* file is invalid, for CI use.)
     has_content = (
         stats.valid_features > 0
         or stats.decision_count > 0
         or stats.valid_roadmaps > 0
         or stats.valid_prompts > 0
+        or stats.valid_designs > 0
     )
     return EXIT_OK if has_content else EXIT_VALIDATION_FAILED
 
@@ -368,7 +369,7 @@ def build_parser() -> argparse.ArgumentParser:
     p_schema.add_argument(
         "schema",
         nargs="?",
-        help="Schema name, e.g. requirement, decision, roadmap, or prompt.",
+        help="Schema name, e.g. requirement, decision, roadmap, prompt, or design.",
     )
     p_schema.add_argument(
         "--list",

{requirements_as_code-0.6.2 → requirements_as_code-0.6.3}/rac/outputs.py

@@ -263,6 +263,24 @@ def render_stats_human(s: PortfolioStats) -> str:
                 reasons = ", ".join(p.error_codes) or "unknown"
                 lines.append(f"  {_red(p.path)} — {reasons}")
 
+    # Designs are reported separately and lightly (count + invalid only); the
+    # section is omitted entirely when there are none.
+    if s.designs:
+        lines += [
+            "",
+            _bold("Designs"),
+            "=======",
+            "",
+            f"Total: {s.design_count}",
+            f"Valid: {s.valid_designs}",
+        ]
+        invalid_designs = s.invalid_designs
+        if invalid_designs:
+            lines += ["", _bold(f"Invalid Designs ({len(invalid_designs)})")]
+            for d in invalid_designs:
+                reasons = ", ".join(d.error_codes) or "unknown"
+                lines.append(f"  {_red(d.path)} — {reasons}")
+
     return "\n".join(lines)
 
 
@@ -320,6 +338,16 @@ def render_stats_json(s: PortfolioStats) -> str:
                 {"file": p.path, "errors": p.error_codes} for p in s.invalid_prompts
             ],
         }
+    # Additive: only present when the portfolio contains designs. Lightweight by
+    # design — count and validity only (no design quality or rendering metrics).
+    if s.designs:
+        payload["designs"] = {
+            "count": s.design_count,
+            "valid": s.valid_designs,
+            "invalid": [
+                {"file": d.path, "errors": d.error_codes} for d in s.invalid_designs
+            ],
+        }
     return json.dumps(payload, indent=2)
 
 

{requirements_as_code-0.6.2 → requirements_as_code-0.6.3}/rac/schema.py

@@ -115,6 +115,8 @@ def _starter_body(
         return _metadata_default(section, metadata_values)
     if ref.type == "requirement" and section == "requirements":
         return "- [REQ-001] TODO: describe a required system behaviour."
+    if ref.type == "design":
+        return _design_free_text_todo(section)
     return _free_text_todo(section)
 
 
@@ -163,5 +165,30 @@ def _free_text_todo(section: str) -> str:
     return messages.get(section, f"TODO: describe {section}.")
 
 
+def _design_free_text_todo(section: str) -> str:
+    messages = {
+        "context": "TODO: describe the design context and why this design exists.",
+        "user need": (
+            "TODO: describe who this design is for and what they need to accomplish."
+        ),
+        "design": (
+            "TODO: describe the proposed experience, interaction, layout, flow, "
+            "or system behavior."
+        ),
+        "constraints": (
+            "TODO: describe technical, product, accessibility, platform, or "
+            "implementation constraints."
+        ),
+        "rationale": "TODO: explain why this design approach was chosen.",
+        "alternatives": "TODO: describe alternatives that were considered.",
+        "accessibility": "TODO: describe accessibility considerations.",
+        "style guidance": (
+            "TODO: describe visual, tone, layout, or interaction style guidance."
+        ),
+        "open questions": "TODO: list unresolved design questions.",
+    }
+    return messages.get(section, _free_text_todo(section))
+
+
 def _snake(section: str) -> str:
     return section.replace(" ", "_")

{requirements_as_code-0.6.2 → requirements_as_code-0.6.3}/rac/stats.py

@@ -4,10 +4,10 @@
 each one, and aggregates the results. Like the rest of RAC, it works on the
 Product AST: every `.md` is parsed into a :class:`~rac.models.Product`.
 
-Requirement, Decision, Roadmap, and Prompt artifacts are aggregated separately so
+Requirement, Decision, Roadmap, Prompt, and Design artifacts are aggregated separately so
 that one never distorts another: requirement totals/averages span only requirement
 files, decisions get their own status/category breakdown, and roadmaps and prompts
-each get a lightweight count of how many exist and how many are valid.
+and designs each get a lightweight count of how many exist and how many are valid.
 
 Counting basis: requirement totals, averages, and the per-feature breakdown span
 *all* parsed requirement files (including ones that fail validation). A file
@@ -79,6 +79,20 @@ class PromptStat:
     error_codes: list[str]
 
 
+@dataclass
+class DesignStat:
+    """Per-file result for a Design artifact (kept separate from features).
+
+    Lightweight by design (v0.6.3): identity plus validity and error codes only.
+    No section-completeness, visual, or design-system metrics.
+    """
+
+    path: str
+    name: str  # the design title, or the filename stem if it has none
+    valid: bool
+    error_codes: list[str]
+
+
 @dataclass
 class PortfolioStats:
     """Aggregate view over all discovered requirement files."""
@@ -88,6 +102,7 @@ class PortfolioStats:
     decisions: list[DecisionStat] = field(default_factory=list)
     roadmaps: list[RoadmapStat] = field(default_factory=list)
     prompts: list[PromptStat] = field(default_factory=list)
+    designs: list[DesignStat] = field(default_factory=list)
 
     # --- counts (requirement features) ---
     @property
@@ -198,6 +213,19 @@ class PortfolioStats:
     def invalid_prompts(self) -> list[PromptStat]:
         return [p for p in self.prompts if not p.valid]
 
+    # --- designs ---
+    @property
+    def design_count(self) -> int:
+        return len(self.designs)
+
+    @property
+    def valid_designs(self) -> int:
+        return sum(1 for d in self.designs if d.valid)
+
+    @property
+    def invalid_designs(self) -> list[DesignStat]:
+        return [d for d in self.designs if not d.valid]
+
 
 def _bucket(decisions: list[DecisionStat], attr: str, metadata_key: str) -> dict[str, int]:
     """Count ``decisions`` by ``attr`` in the artifact spec's declared order."""
@@ -224,7 +252,7 @@ def _neg_name(name: str) -> tuple[int, ...]:
 def collect_stats(directory: str) -> PortfolioStats:
     """Parse and classify every Markdown file under ``directory``.
 
-    Decisions, roadmaps, and prompts are each routed to their own aggregate;
+    Decisions, roadmaps, prompts, and designs are each routed to their own aggregate;
     everything else is treated as a requirement feature (preserving prior behavior
     for requirement repositories).
     """
@@ -268,6 +296,18 @@ def collect_stats(directory: str) -> PortfolioStats:
                 )
             )
             continue
+        if result.type == "design":
+            issues = validate(product)
+            error_codes = [i.code for i in issues if i.severity == "error"]
+            stats.designs.append(
+                DesignStat(
+                    path=str(path),
+                    name=name,
+                    valid=not error_codes,
+                    error_codes=error_codes,
+                )
+            )
+            continue
         issues = validate(product)
         error_codes = [i.code for i in issues if i.severity == "error"]
         stats.features.append(

{requirements_as_code-0.6.2 → requirements_as_code-0.6.3}/rac/validate.py

@@ -45,6 +45,8 @@ def validate(product: Product) -> list[Issue]:
         return _validate_roadmap(product)
     if artifact_type == "prompt":
         return _validate_prompt(product)
+    if artifact_type == "design":
+        return _validate_design(product)
     return _validate_requirement(product)
 
 
@@ -187,6 +189,43 @@ def _validate_prompt(product: Product) -> list[Issue]:
     return issues
 
 
+def _validate_design(product: Product) -> list[Issue]:
+    """Validate a Design artifact (v0.6.3).
+
+    Required sections (Context, User Need, Design, Constraints) must be present;
+    missing recommended/optional sections never fail or warn. Designs carry no
+    metadata and are knowledge artifacts, not UI renderings or component systems.
+    """
+    spec = spec_for("design")
+    assert spec is not None  # the design spec always exists
+    issues: list[Issue] = []
+
+    if not product.title:
+        issues.append(Issue("error", "missing-title", "File has no top-level # title."))
+
+    if product.extra_title_lines:
+        issues.append(
+            Issue(
+                "error",
+                "multiple-titles",
+                "File has more than one top-level # title; expected exactly one.",
+                product.extra_title_lines[0],
+            )
+        )
+
+    for section in spec.required:
+        if section not in product.sections:
+            issues.append(
+                Issue(
+                    "error",
+                    f"missing-{section.replace(' ', '-')}",
+                    f"Design is missing a ## {section.title()} section.",
+                )
+            )
+
+    return issues
+
+
 def _validate_requirement(product: Product) -> list[Issue]:
     """Check ``product`` and return all structural and quality findings."""
     issues: list[Issue] = []