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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: requirements-as-code
-Version: 0.3.1
+Version: 0.4.2
 Summary: RAC — lint and diff product requirements written in Markdown.
 Author: tcballard
 License-Expression: MIT
@@ -419,14 +419,36 @@ Invalid Features (1)
   ./features/draft.md — missing-title, missing-requirements
 ```
 
-Counts span all parsed files; a feature with only *warnings* (e.g. no metrics)
-still counts as valid. Invalid files are listed at the end so they are never
-silently skipped.
+Counts span all parsed requirement files; a feature with only *warnings* (e.g. no
+metrics) still counts as valid. Invalid files are listed at the end so they are
+never silently skipped.
 
-Add `--json` for machine-readable output. `stats` exits `0` when the directory
-has at least one valid feature, `1` if none are valid, and `2` if the path is
-not a directory. (A `--strict` flag for failing on *any* invalid file — handy in
-CI — is planned.)
+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:
+
+```text
+Decisions
+=========
+
+Total: 17
+
+Status
+  - Accepted: 12
+  - Proposed: 3
+  - Superseded: 2
+
+Category
+  - Architecture: 8
+  - Product: 5
+  - 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.)
 
 ---
 
@@ -439,6 +461,7 @@ the result is a valid RAC artifact (that is the job of future `inspect` /
 
 ```bash
 rac ingest spec.docx              # print converted Markdown (preview)
+rac ingest spec.docx --stdout     # same, explicit (handy in pipelines)
 rac ingest spec.docx -o spec.md   # write it to a file
 rac ingest spec.docx -o spec.md --force   # overwrite an existing file
 rac ingest spec.docx --json       # { source, converter, output, markdown }
@@ -471,6 +494,128 @@ or an existing output file without `--force`).
 
 ---
 
+## Inspect
+
+Identify what kind of artifact a Markdown document is, and report which expected
+sections are present or missing. Inspection is **read-only and observational** —
+it answers *"what is this?"*, not *"how should I improve it?"* (that's a future
+`improve` command).
+
+```bash
+rac inspect bond-dashboard.md
+rac inspect bond-dashboard.md --json
+cat decision.md | rac inspect -          # read from stdin
+rac ingest prd.docx --stdout | rac inspect -   # ingest then inspect
+```
+
+Output:
+
+```text
+Artifact Type: Requirement
+Confidence: 71%
+
+Present Sections:
+  ✓ Problem
+  ✓ Requirements
+  ✓ Success Metrics
+
+Missing Sections:
+  ✗ Risks
+  ✗ Assumptions
+```
+
+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 }`.
+
+### Inspect a directory
+
+Point `inspect` at a directory to get a summary across many files (recursive by
+default; `--top-level` limits it to the directory's own files):
+
+```bash
+rac inspect planning/
+rac inspect planning/ --top-level
+rac inspect planning/ --json        # versioned summary + per-file array
+```
+
+```text
+Files Inspected: 23
+
+Requirements: 7
+Decisions: 3
+Unknown: 13
+```
+
+### Explain a classification (`--verbose`)
+
+```bash
+rac inspect bond-dashboard.md --verbose
+```
+
+```text
+Artifact Type: Requirement
+Confidence: 71%
+
+Required Matches:
+  ✓ Problem
+  ✓ Requirements
+
+Recommended Matches:
+  ✓ Success Metrics
+
+Missing:
+  ✗ Risks
+  ✗ Assumptions
+
+Score: 2 + 0.5 × 1 = 2.5 / 3.5 = 0.71
+```
+
+### Decision metadata
+
+Decision artifacts (ADRs) may carry lightweight, optional metadata. When present,
+`inspect` extracts it and `validate` checks the values:
+
+```markdown
+## Status
+
+Accepted
+
+## Category
+
+Architecture
+
+## Supersedes
+
+ADR-012
+```
+
+| Field | Supported values | Validated? |
+|------------|--------------------------------------------------------------|------------|
+| Status | Proposed, Accepted, Superseded, Deprecated | yes |
+| Category | Architecture, Product, Process, Technical, Other | yes |
+| Supersedes | any reference (free text) | no — metadata only |
+
+`inspect` surfaces these under a **Decision Metadata** block (and in `--json` as
+`status` / `category` / `supersedes`, present only when declared). Metadata is
+**optional**: a decision without it is still valid. Only an *unsupported* Status
+or Category value fails validation (`invalid-decision-status` /
+`invalid-decision-category`); values are matched case-insensitively.
+
+### Synonyms
+
+Common heading variants are recognized automatically (case-insensitive,
+deterministic) — e.g. `Success Criteria` and `KPIs` both count as Success Metrics,
+and `Alternatives` counts as Alternatives Considered.
+
+`inspect` exits `0` for any completed inspection (including Unknown) and `2` for
+usage errors (file not found, or a non-Markdown file — convert it with
+`rac ingest` first).
+
+---
+
 ## Review (Planned)
 
 AI-assisted product review.

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

@@ -379,14 +379,36 @@ Invalid Features (1)
   ./features/draft.md — missing-title, missing-requirements
 ```
 
-Counts span all parsed files; a feature with only *warnings* (e.g. no metrics)
-still counts as valid. Invalid files are listed at the end so they are never
-silently skipped.
+Counts span all parsed requirement files; a feature with only *warnings* (e.g. no
+metrics) still counts as valid. Invalid files are listed at the end so they are
+never silently skipped.
 
-Add `--json` for machine-readable output. `stats` exits `0` when the directory
-has at least one valid feature, `1` if none are valid, and `2` if the path is
-not a directory. (A `--strict` flag for failing on *any* invalid file — handy in
-CI — is planned.)
+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:
+
+```text
+Decisions
+=========
+
+Total: 17
+
+Status
+  - Accepted: 12
+  - Proposed: 3
+  - Superseded: 2
+
+Category
+  - Architecture: 8
+  - Product: 5
+  - 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.)
 
 ---
 
@@ -399,6 +421,7 @@ the result is a valid RAC artifact (that is the job of future `inspect` /
 
 ```bash
 rac ingest spec.docx              # print converted Markdown (preview)
+rac ingest spec.docx --stdout     # same, explicit (handy in pipelines)
 rac ingest spec.docx -o spec.md   # write it to a file
 rac ingest spec.docx -o spec.md --force   # overwrite an existing file
 rac ingest spec.docx --json       # { source, converter, output, markdown }
@@ -431,6 +454,128 @@ or an existing output file without `--force`).
 
 ---
 
+## Inspect
+
+Identify what kind of artifact a Markdown document is, and report which expected
+sections are present or missing. Inspection is **read-only and observational** —
+it answers *"what is this?"*, not *"how should I improve it?"* (that's a future
+`improve` command).
+
+```bash
+rac inspect bond-dashboard.md
+rac inspect bond-dashboard.md --json
+cat decision.md | rac inspect -          # read from stdin
+rac ingest prd.docx --stdout | rac inspect -   # ingest then inspect
+```
+
+Output:
+
+```text
+Artifact Type: Requirement
+Confidence: 71%
+
+Present Sections:
+  ✓ Problem
+  ✓ Requirements
+  ✓ Success Metrics
+
+Missing Sections:
+  ✗ Risks
+  ✗ Assumptions
+```
+
+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 }`.
+
+### Inspect a directory
+
+Point `inspect` at a directory to get a summary across many files (recursive by
+default; `--top-level` limits it to the directory's own files):
+
+```bash
+rac inspect planning/
+rac inspect planning/ --top-level
+rac inspect planning/ --json        # versioned summary + per-file array
+```
+
+```text
+Files Inspected: 23
+
+Requirements: 7
+Decisions: 3
+Unknown: 13
+```
+
+### Explain a classification (`--verbose`)
+
+```bash
+rac inspect bond-dashboard.md --verbose
+```
+
+```text
+Artifact Type: Requirement
+Confidence: 71%
+
+Required Matches:
+  ✓ Problem
+  ✓ Requirements
+
+Recommended Matches:
+  ✓ Success Metrics
+
+Missing:
+  ✗ Risks
+  ✗ Assumptions
+
+Score: 2 + 0.5 × 1 = 2.5 / 3.5 = 0.71
+```
+
+### Decision metadata
+
+Decision artifacts (ADRs) may carry lightweight, optional metadata. When present,
+`inspect` extracts it and `validate` checks the values:
+
+```markdown
+## Status
+
+Accepted
+
+## Category
+
+Architecture
+
+## Supersedes
+
+ADR-012
+```
+
+| Field | Supported values | Validated? |
+|------------|--------------------------------------------------------------|------------|
+| Status | Proposed, Accepted, Superseded, Deprecated | yes |
+| Category | Architecture, Product, Process, Technical, Other | yes |
+| Supersedes | any reference (free text) | no — metadata only |
+
+`inspect` surfaces these under a **Decision Metadata** block (and in `--json` as
+`status` / `category` / `supersedes`, present only when declared). Metadata is
+**optional**: a decision without it is still valid. Only an *unsupported* Status
+or Category value fails validation (`invalid-decision-status` /
+`invalid-decision-category`); values are matched case-insensitively.
+
+### Synonyms
+
+Common heading variants are recognized automatically (case-insensitive,
+deterministic) — e.g. `Success Criteria` and `KPIs` both count as Success Metrics,
+and `Alternatives` counts as Alternatives Considered.
+
+`inspect` exits `0` for any completed inspection (including Unknown) and `2` for
+usage errors (file not found, or a non-Markdown file — convert it with
+`rac ingest` first).
+
+---
+
 ## Review (Planned)
 
 AI-assisted product review.

requirements_as_code-0.4.2/planning/adr/adr-001-markdown-first.md

@@ -0,0 +1,21 @@
+# ADR-001 Markdown First
+
+## Status
+
+Accepted
+
+## Context
+
+RAC needs a single canonical source format for requirements and other artifacts.
+
+## Decision
+
+Markdown is the canonical source format.
+
+## Consequences
+
+### Positive
+
+- Human-readable
+- Git-friendly
+- Tool-independent

requirements_as_code-0.4.2/planning/adr/adr-002-ai-optional.md

@@ -0,0 +1,21 @@
+# ADR-002 AI Optional
+
+## Status
+
+Accepted
+
+## Context
+
+RAC should be useful on its own, with AI as an enhancement rather than a dependency.
+
+## Decision
+
+RAC must provide value without AI.
+
+## Consequences
+
+### Positive
+
+- Lower complexity
+- Easier testing
+- Works offline

requirements_as_code-0.4.2/planning/adr/adr-003-structured-outputs-first.md

@@ -0,0 +1,22 @@
+# ADR-003 Structured Outputs First
+
+## Status
+
+Accepted
+
+## Context
+
+RAC commands need to be consumable by scripts, SDKs, and future integrations — not just humans.
+
+## Decision
+
+Every command returns typed result models.
+
+## Consequences
+
+### Positive
+
+- JSON output becomes trivial
+- SDK usage becomes trivial
+- MCP integration becomes trivial
+- CI integration becomes trivial

requirements_as_code-0.4.2/planning/adr/adr-004-artifact-model.md

@@ -0,0 +1,24 @@
+# ADR-004 Artifact Model
+
+## Status
+
+Accepted
+
+## Context
+
+Not all documents are the same kind of knowledge. RAC needs a model that can grow beyond requirements.
+
+## Decision
+
+RAC analyzes typed artifacts rather than generic documents. Planned artifact types include Requirement, Decision, Roadmap, Prompt, and Meeting.
+
+## Consequences
+
+### Positive
+
+- Provides the bridge to v0.5+ artifact types
+- Each artifact type can have its own structure and validation
+
+### Negative
+
+- More modeling work as new artifact types are added

requirements_as_code-0.4.2/planning/adr/adr-005-cli-first.md

@@ -0,0 +1,30 @@
+# ADR-005 CLI First
+
+## Status
+
+Accepted
+
+## Context
+
+RAC needs a primary interface that ships quickly and automates well.
+
+## Decision
+
+The CLI is the primary interface.
+
+## Alternatives Considered
+
+### Web app / SaaS / Browser extension
+
+Cons:
+- Slower path to value
+- Harder to automate
+- Heavier infrastructure
+
+## Consequences
+
+### Positive
+
+- Fastest path to value
+- Easy automation
+- Easy AI integration later

requirements_as_code-0.4.2/planning/adr/adr-006-ingest-over-rewrite.md

@@ -0,0 +1,20 @@
+# ADR-006 Ingestion Over Rewrite
+
+## Status
+
+Accepted
+
+## Context
+
+People already have product knowledge in PDFs, Word docs, and Notion exports.
+
+## Decision
+
+Users should not have to rewrite existing documents; RAC should adapt to them via ingestion.
+
+## Consequences
+
+### Positive
+
+- Lower barrier to adoption
+- RAC meets users where their knowledge already lives

requirements_as_code-0.4.2/planning/adr/adr-007-json-contract-stability.md

@@ -0,0 +1,23 @@
+# ADR-007 JSON Contract Stability
+
+## Status
+
+Accepted
+
+## Context
+
+RAC's JSON output is consumed by scripts and will be consumed by future MCP integrations.
+
+## Decision
+
+JSON outputs are treated as public APIs. Field names (for example `features`) will not change to alternatives (for example `feature_count`) without explicit versioning.
+
+## Consequences
+
+### Positive
+
+- Stable contract for scripts and MCP integrations
+
+### Negative
+
+- Schema changes require a versioning strategy

requirements_as_code-0.4.2/planning/adr/adr-008-agent-ready-architecture.md

@@ -0,0 +1,40 @@
+# ADR-008 Agent Ready Architecture
+
+## Status
+
+Accepted
+
+## Context
+
+Future versions of RAC may be used by Claude, Codex, Cursor, and other AI systems.
+
+The architecture should avoid coupling business logic to the CLI.
+
+## Decision
+
+All RAC capabilities will be implemented in reusable service layers.
+
+The CLI will be a thin wrapper around those services.
+
+## Alternatives Considered
+
+### CLI-only Architecture
+
+Pros:
+- Simpler initially
+
+Cons:
+- Difficult to expose as SDK or MCP server
+
+## Consequences
+
+### Positive
+
+- Easy MCP support
+- Easy SDK support
+- Easier testing
+
+### Negative
+
+- Slightly more abstraction
+- Additional project structure