requirements-as-code 0.4.2__tar.gz → 0.5.2__tar.gz

{requirements_as_code-0.4.2/requirements_as_code.egg-info → requirements_as_code-0.5.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: requirements-as-code
-Version: 0.4.2
+Version: 0.5.2
 Summary: RAC — lint and diff product requirements written in Markdown.
 Author: tcballard
 License-Expression: MIT
@@ -616,6 +616,161 @@ usage errors (file not found, or a non-Markdown file — convert it with
 
 ---
 
+## Improve
+
+Where `inspect` tells you *what an artifact is*, `improve` tells you *what to add
+next* and how to think about completing it. It reports the required and
+recommended sections an artifact is missing, plus schema-defined guidance for
+those sections — **deterministically, from the schema, with no AI** (ADR-002).
+`improve` is **advisory and read-only**: it never modifies your files and never
+generates content beyond `_TODO_` placeholders and guidance comments.
+
+```bash
+rac improve requirement.md
+rac improve requirement.md --template     # Markdown skeletons for missing sections
+rac improve requirement.md --json
+cat requirement.md | rac improve -        # stdin
+rac ingest prd.docx --stdout | rac improve -
+```
+
+Default output:
+
+```text
+Artifact Type: Requirement
+
+Missing Required:
+  (none)
+
+Missing Recommended:
+  - Risks
+      • What could prevent successful delivery?
+      • What dependencies or unknowns exist?
+  - Assumptions
+      • What are you assuming to be true?
+      • What would change the approach if it turned out false?
+```
+
+`--template` turns the gaps into a ready-to-paste skeleton (required sections
+first, then recommended), with deterministic guidance comments per section:
+
+```markdown
+## Risks
+
+_TODO_
+
+<!-- What could prevent successful delivery? -->
+<!-- What dependencies or unknowns exist? -->
+```
+
+So you can go straight from `rac inspect requirement.md` to
+`rac improve requirement.md --template` without consulting any documentation.
+
+`--json` returns a stable contract (ADR-007):
+
+```json
+{
+  "type": "requirement",
+  "missing_required": [],
+  "missing_recommended": ["risks", "assumptions"],
+  "guidance": {
+    "risks": [
+      "What could prevent successful delivery?",
+      "What dependencies or unknowns exist?"
+    ],
+    "assumptions": [
+      "What are you assuming to be true?",
+      "What would change the approach if it turned out false?"
+    ]
+  }
+}
+```
+
+`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.
+
+Guidance is informational metadata only: it does not influence classification,
+validation, confidence scoring, statistics, or repository analysis.
+
+`improve` is advisory: it exits `0` for any completed analysis (with or without
+suggestions) and `2` for usage errors. The presence of suggestions never changes
+the exit code.
+
+---
+
+## Schema
+
+Inspect RAC's registered artifact schemas without creating a file.
+
+```bash
+rac schema --list
+rac schema --list --json
+rac schema requirement
+rac schema decision --json
+rac schema requirement --template
+```
+
+`rac schema <type>` shows the full schema reference: required, recommended, and
+optional sections; descriptions; guidance; and metadata values where applicable.
+
+```text
+Artifact Type: Decision
+
+Required Sections:
+  - Context
+  - Decision
+  - Consequences
+
+Recommended Sections:
+  - Status
+  - Category
+  - Alternatives Considered
+
+Optional Sections:
+  - Supersedes
+
+Metadata Fields:
+  - Status: Proposed | Accepted | Superseded | Deprecated
+  - Category: Architecture | Product | Process | Technical | Other
+```
+
+`--json` returns the same schema data as grouped arrays and maps:
+
+```json
+{
+  "type": "requirement",
+  "required": ["problem", "requirements"],
+  "recommended": ["success_metrics", "risks", "assumptions"],
+  "optional": [],
+  "descriptions": {},
+  "guidance": {},
+  "metadata": {}
+}
+```
+
+`--template` emits a structurally valid Markdown starter. Templates are useful
+starting points, not finished artifacts: users still replace TODO text with
+meaningful product knowledge.
+
+```bash
+rac schema requirement --template > requirement.md
+rac schema decision --template > decision.md
+```
+
+Generated templates are validation-safe:
+
+```bash
+rac schema requirement --template | rac validate -
+rac schema decision --template | rac validate -
+```
+
+Unknown schemas fail with exit code `2` and list available schemas. Only
+registered schemas are supported; custom schemas are out of scope.
+
+---
+
 ## Review (Planned)
 
 AI-assisted product review.

{requirements_as_code-0.4.2 → requirements_as_code-0.5.2}/README.md

@@ -576,6 +576,161 @@ usage errors (file not found, or a non-Markdown file — convert it with
 
 ---
 
+## Improve
+
+Where `inspect` tells you *what an artifact is*, `improve` tells you *what to add
+next* and how to think about completing it. It reports the required and
+recommended sections an artifact is missing, plus schema-defined guidance for
+those sections — **deterministically, from the schema, with no AI** (ADR-002).
+`improve` is **advisory and read-only**: it never modifies your files and never
+generates content beyond `_TODO_` placeholders and guidance comments.
+
+```bash
+rac improve requirement.md
+rac improve requirement.md --template     # Markdown skeletons for missing sections
+rac improve requirement.md --json
+cat requirement.md | rac improve -        # stdin
+rac ingest prd.docx --stdout | rac improve -
+```
+
+Default output:
+
+```text
+Artifact Type: Requirement
+
+Missing Required:
+  (none)
+
+Missing Recommended:
+  - Risks
+      • What could prevent successful delivery?
+      • What dependencies or unknowns exist?
+  - Assumptions
+      • What are you assuming to be true?
+      • What would change the approach if it turned out false?
+```
+
+`--template` turns the gaps into a ready-to-paste skeleton (required sections
+first, then recommended), with deterministic guidance comments per section:
+
+```markdown
+## Risks
+
+_TODO_
+
+<!-- What could prevent successful delivery? -->
+<!-- What dependencies or unknowns exist? -->
+```
+
+So you can go straight from `rac inspect requirement.md` to
+`rac improve requirement.md --template` without consulting any documentation.
+
+`--json` returns a stable contract (ADR-007):
+
+```json
+{
+  "type": "requirement",
+  "missing_required": [],
+  "missing_recommended": ["risks", "assumptions"],
+  "guidance": {
+    "risks": [
+      "What could prevent successful delivery?",
+      "What dependencies or unknowns exist?"
+    ],
+    "assumptions": [
+      "What are you assuming to be true?",
+      "What would change the approach if it turned out false?"
+    ]
+  }
+}
+```
+
+`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.
+
+Guidance is informational metadata only: it does not influence classification,
+validation, confidence scoring, statistics, or repository analysis.
+
+`improve` is advisory: it exits `0` for any completed analysis (with or without
+suggestions) and `2` for usage errors. The presence of suggestions never changes
+the exit code.
+
+---
+
+## Schema
+
+Inspect RAC's registered artifact schemas without creating a file.
+
+```bash
+rac schema --list
+rac schema --list --json
+rac schema requirement
+rac schema decision --json
+rac schema requirement --template
+```
+
+`rac schema <type>` shows the full schema reference: required, recommended, and
+optional sections; descriptions; guidance; and metadata values where applicable.
+
+```text
+Artifact Type: Decision
+
+Required Sections:
+  - Context
+  - Decision
+  - Consequences
+
+Recommended Sections:
+  - Status
+  - Category
+  - Alternatives Considered
+
+Optional Sections:
+  - Supersedes
+
+Metadata Fields:
+  - Status: Proposed | Accepted | Superseded | Deprecated
+  - Category: Architecture | Product | Process | Technical | Other
+```
+
+`--json` returns the same schema data as grouped arrays and maps:
+
+```json
+{
+  "type": "requirement",
+  "required": ["problem", "requirements"],
+  "recommended": ["success_metrics", "risks", "assumptions"],
+  "optional": [],
+  "descriptions": {},
+  "guidance": {},
+  "metadata": {}
+}
+```
+
+`--template` emits a structurally valid Markdown starter. Templates are useful
+starting points, not finished artifacts: users still replace TODO text with
+meaningful product knowledge.
+
+```bash
+rac schema requirement --template > requirement.md
+rac schema decision --template > decision.md
+```
+
+Generated templates are validation-safe:
+
+```bash
+rac schema requirement --template | rac validate -
+rac schema decision --template | rac validate -
+```
+
+Unknown schemas fail with exit code `2` and list available schemas. Only
+registered schemas are supported; custom schemas are out of scope.
+
+---
+
 ## Review (Planned)
 
 AI-assisted product review.
@@ -638,4 +793,4 @@ The project is intentionally focused on one goal:
 
 # License
 
-MIT
+MIT