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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: requirements-as-code
-Version: 0.4.2
+Version: 0.5.0
 Summary: RAC — lint and diff product requirements written in Markdown.
 Author: tcballard
 License-Expression: MIT
@@ -616,6 +616,67 @@ 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*. It reports the required and recommended sections an artifact is missing —
+**deterministically, from the schema, with no AI** (ADR-002) — and can emit
+Markdown templates for them. `improve` is **advisory and read-only**: it never
+modifies your files and never generates content beyond `_TODO_` placeholders.
+
+```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
+  - Assumptions
+```
+
+`--template` turns the gaps into a ready-to-paste skeleton (required sections
+first, then recommended), with a short guidance hint per section:
+
+```markdown
+## Risks
+
+_TODO_
+
+<!-- Potential implementation, delivery, or adoption risks -->
+```
+
+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"]
+}
+```
+
+v0.5.0 generates suggestions for **Requirement** artifacts. Other known types
+(e.g. Decision) and Unknown documents return a short explanatory message instead.
+`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.
+
+---
+
 ## Review (Planned)
 
 AI-assisted product review.

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

@@ -576,6 +576,67 @@ 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*. It reports the required and recommended sections an artifact is missing —
+**deterministically, from the schema, with no AI** (ADR-002) — and can emit
+Markdown templates for them. `improve` is **advisory and read-only**: it never
+modifies your files and never generates content beyond `_TODO_` placeholders.
+
+```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
+  - Assumptions
+```
+
+`--template` turns the gaps into a ready-to-paste skeleton (required sections
+first, then recommended), with a short guidance hint per section:
+
+```markdown
+## Risks
+
+_TODO_
+
+<!-- Potential implementation, delivery, or adoption risks -->
+```
+
+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"]
+}
+```
+
+v0.5.0 generates suggestions for **Requirement** artifacts. Other known types
+(e.g. Decision) and Unknown documents return a short explanatory message instead.
+`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.
+
+---
+
 ## Review (Planned)
 
 AI-assisted product review.

{requirements_as_code-0.4.2 → requirements_as_code-0.5.0}/planning/roadmap/v0.5.0-artifact-improvement.md

@@ -232,6 +232,11 @@ rac improve requirement.md --template
 
 without consulting documentation.
 
+### Completion
+
+A user can take a valid but incomplete Requirement and generate a complete
+RAC-compliant skeleton using only `rac improve --template`.
+
 ---
 
 ## Acceptance Criteria

{requirements_as_code-0.4.2 → requirements_as_code-0.5.0}/rac/artifacts.py

@@ -35,6 +35,10 @@ class ArtifactSpec:
     # A value present in one of these sections that is not in its allowed set is
     # a validation error; a missing section is not (metadata stays optional).
     metadata: dict[str, tuple[str, ...]] = field(default_factory=dict)
+    # Short authoring hints per normalized section name, surfaced by `rac improve
+    # --template` as guidance comments. Optional; sections without a hint render
+    # without one.
+    descriptions: dict[str, str] = field(default_factory=dict)
     # Synonyms: alternate normalized headings that map onto a canonical section
     # name (e.g. "success criteria" -> "success metrics"). Applied before
     # matching, so synonyms contribute to confidence. Matching is deterministic
@@ -57,6 +61,13 @@ ARTIFACT_SPECS: tuple[ArtifactSpec, ...] = (
         display="Requirement",
         required=("problem", "requirements"),
         recommended=("success metrics", "risks", "assumptions"),
+        descriptions={
+            "problem": "The user or business problem this addresses",
+            "requirements": "Numbered requirement statements, e.g. [REQ-001] ...",
+            "success metrics": "How success will be measured",
+            "risks": "Potential implementation, delivery, or adoption risks",
+            "assumptions": "Assumptions this artifact depends on",
+        },
         synonyms={
             "success criteria": "success metrics",
             "kpis": "success metrics",

{requirements_as_code-0.4.2 → requirements_as_code-0.5.0}/rac/classification.py

@@ -47,16 +47,38 @@ class Classification:
     missing_sections: list[str]
 
 
+def _mapped(product: Product, spec) -> set[str]:
+    """The document's ``##`` headings, with this spec's synonyms applied.
+
+    The single source of synonym-aware section matching, shared by scoring
+    (:func:`score_artifacts`) and the scoring-independent :func:`missing_sections`.
+    """
+    return {spec.synonyms.get(h, h) for h in product.sections}
+
+
+def missing_sections(product: Product, spec) -> tuple[list[str], list[str]]:
+    """Return ``(missing_required, missing_recommended)`` for ``spec``.
+
+    Synonym-aware and in schema declaration order. Independent of confidence
+    scoring (no :class:`TypeScore`) so callers like ``improve`` depend only on the
+    schema, not on classification internals.
+    """
+    mapped = _mapped(product, spec)
+    return (
+        [s for s in spec.required if s not in mapped],
+        [s for s in spec.recommended if s not in mapped],
+    )
+
+
 def score_artifacts(product: Product) -> list[TypeScore]:
     """Score the document against every artifact type, best fit first.
 
     Synonyms (e.g. "success criteria" -> "success metrics") are applied before
     matching, so they contribute to the score deterministically.
     """
-    headings = list(product.sections)
     scores: list[TypeScore] = []
     for spec in ARTIFACT_SPECS:
-        mapped = {spec.synonyms.get(h, h) for h in headings}
+        mapped = _mapped(product, spec)
         matched_required = [s for s in spec.required if s in mapped]
         matched_recommended = [s for s in spec.recommended if s in mapped]
         missing = [s for s in spec.expected if s not in mapped]

{requirements_as_code-0.4.2 → requirements_as_code-0.5.0}/rac/cli.py

@@ -6,9 +6,10 @@ Commands:
     rac stats <directory> [--json]
     rac ingest <file> [-o OUT | --stdout] [--force] [--json]
     rac inspect <file.md | -> [--json]
+    rac improve <file.md | -> [--json | --template]
 
 Exit codes:
-    0  success (incl. inspect reporting Unknown)
+    0  success (incl. inspect/improve reporting Unknown)
     1  validate: errors found; stats: no valid features or decisions;
        ingest: conversion failed
     2  usage / IO error (file not found, not a directory, unsupported type,
@@ -26,6 +27,7 @@ from . import outputs
 from .diff import diff as diff_asts
 from .ingest import ConversionError, UnsupportedDocument, ingest
 from .classification import score_artifacts
+from .improve import improve_product
 from .inspect import build_inspection, inspect_directory
 from .parser import parse, parse_file
 from .stats import collect_stats
@@ -126,8 +128,8 @@ def cmd_ingest(args: argparse.Namespace) -> int:
     return EXIT_OK
 
 
-def _read_inspect_input(target: str) -> str:
-    """Read inspect input from a Markdown file or stdin (``-``)."""
+def _read_markdown_input(target: str, command: str) -> str:
+    """Read a Markdown file or stdin (``-``) for ``command`` (inspect/improve)."""
     if target == "-":
         return sys.stdin.read()
     path = Path(target)
@@ -136,7 +138,7 @@ def _read_inspect_input(target: str) -> str:
         raise SystemExit(EXIT_USAGE)
     if path.suffix.lower() not in (".md", ".markdown"):
         print(
-            f"rac: inspect expects a Markdown file; "
+            f"rac: {command} expects a Markdown file; "
             f"convert it first with: rac ingest {target}",
             file=sys.stderr,
         )
@@ -160,7 +162,7 @@ def cmd_inspect(args: argparse.Namespace) -> int:
         return EXIT_OK
 
     # Single file (or stdin).
-    text = _read_inspect_input(args.file)
+    text = _read_markdown_input(args.file, "inspect")
     product = parse(text)
     result = build_inspection(product)
     if args.verbose and not args.json:
@@ -173,6 +175,19 @@ def cmd_inspect(args: argparse.Namespace) -> int:
     return EXIT_OK
 
 
+def cmd_improve(args: argparse.Namespace) -> int:
+    text = _read_markdown_input(args.file, "improve")
+    result = improve_product(parse(text))
+    if args.json:
+        print(outputs.render_improve_json(result))
+    elif args.template:
+        print(outputs.render_improve_template(result))
+    else:
+        print(outputs.render_improve_human(result))
+    # Advisory: a completed analysis always succeeds, with or without suggestions.
+    return EXIT_OK
+
+
 def build_parser() -> argparse.ArgumentParser:
     version_str = f"rac {__version__}"
 
@@ -276,7 +291,26 @@ def build_parser() -> argparse.ArgumentParser:
     )
     p_inspect.set_defaults(func=cmd_inspect)
 
-    # Future command (rac improve <file>) will register here.
+    p_improve = sub.add_parser(
+        "improve",
+        help="Suggest missing sections (and templates) for an artifact.",
+        parents=[version_parent],
+    )
+    p_improve.add_argument(
+        "file",
+        help="A Markdown file, or '-' to read from stdin.",
+    )
+    improve_mode = p_improve.add_mutually_exclusive_group()
+    improve_mode.add_argument(
+        "--json", action="store_true", help="Emit JSON instead of human-readable text."
+    )
+    improve_mode.add_argument(
+        "--template",
+        action="store_true",
+        help="Emit Markdown templates for the missing sections.",
+    )
+    p_improve.set_defaults(func=cmd_improve)
+
     return parser
 
 

requirements_as_code-0.5.0/rac/improve.py

@@ -0,0 +1,84 @@
+"""Artifact improvement — deterministic, schema-driven guidance (ADR-002).
+
+`rac improve <file>` is RAC's first *advisory* capability: it reports which
+required and recommended sections an artifact is missing and can emit Markdown
+templates for them. It is strictly read-only (REQ-004) and generates no content
+beyond schema-derived placeholders — no AI, no rewriting.
+
+Improvement depends only on the artifact *type* and a *schema comparison*
+(:func:`rac.classification.missing_sections`); it never reaches into classification
+confidence internals. v0.5.0 produces suggestions for Requirement artifacts only;
+other known types and Unknown return no suggestions (the renderers explain why).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .artifacts import spec_for
+from .classification import classify, missing_sections
+from .models import Product
+from .parser import parse, parse_file
+
+# The single artifact type that v0.5.0 generates suggestions for. Written as a
+# constant (not hard-coded throughout) so widening scope later is a one-line change.
+SUPPORTED_TYPE = "requirement"
+
+
+@dataclass
+class ImprovementResult:
+    """Typed improvement analysis for one artifact (ADR-003).
+
+    Section names are stored normalized (e.g. ``"success metrics"``); renderers
+    format them. ``to_dict`` is the stable JSON contract (ADR-007):
+    ``{type, missing_required, missing_recommended}``.
+    """
+
+    type: str  # classified artifact type, or "unknown"
+    missing_required: list[str]
+    missing_recommended: list[str]
+    # Reserved for future Unknown handling (e.g. "closest match" guidance). Always
+    # None in v0.5.0 and intentionally not serialized yet — additive later (ADR-007).
+    closest_type: str | None = None
+
+    @property
+    def supported(self) -> bool:
+        """True when this is a type ``improve`` generates suggestions for."""
+        return self.type == SUPPORTED_TYPE
+
+    def to_dict(self) -> dict:
+        return {
+            "type": self.type,
+            "missing_required": [_snake(s) for s in self.missing_required],
+            "missing_recommended": [_snake(s) for s in self.missing_recommended],
+        }
+
+
+def _snake(section: str) -> str:
+    return section.replace(" ", "_")
+
+
+def improve_product(product: Product) -> ImprovementResult:
+    """Analyze a parsed ``product`` and return improvement guidance."""
+    artifact_type = classify(product).type
+    if artifact_type != SUPPORTED_TYPE:
+        # Decision / other known types and Unknown: no suggestions in v0.5.0.
+        return ImprovementResult(
+            type=artifact_type, missing_required=[], missing_recommended=[]
+        )
+    spec = spec_for(SUPPORTED_TYPE)
+    assert spec is not None  # the requirement spec always exists
+    missing_required, missing_recommended = missing_sections(product, spec)
+    return ImprovementResult(
+        type=artifact_type,
+        missing_required=missing_required,
+        missing_recommended=missing_recommended,
+    )
+
+
+def improve_text(text: str) -> ImprovementResult:
+    return improve_product(parse(text))
+
+
+def improve_file(path: str) -> ImprovementResult:
+    return improve_product(parse_file(path))

{requirements_as_code-0.4.2 → requirements_as_code-0.5.0}/rac/outputs.py

@@ -10,8 +10,9 @@ import json
 import sys
 from dataclasses import asdict
 
-from .artifacts import ARTIFACT_SPECS
+from .artifacts import ARTIFACT_SPECS, spec_for
 from .classification import CONFIDENCE_THRESHOLD, TypeScore
+from .improve import ImprovementResult
 from .ingest import IngestResult
 from .inspect import DirectoryInspection, InspectionResult
 from .models import Diff, Issue, Product
@@ -374,6 +375,75 @@ def render_dir_inspect_json(d: DirectoryInspection) -> str:
     return json.dumps(payload, indent=2)
 
 
+# --- improve -----------------------------------------------------------------
+
+# Shown when guidance cannot be produced. Ordering everywhere is required-first,
+# then recommended (schema declaration order within each).
+_UNKNOWN_MESSAGE = (
+    "Unable to generate improvement guidance.\n"
+    "Artifact type could not be determined."
+)
+
+
+def _unsupported_message(result: ImprovementResult) -> str:
+    """Generic guidance for a known but unsupported artifact type (e.g. Decision)."""
+    return (
+        f"Artifact Type: {result.type.title()}\n\n"
+        "Improvement guidance is not currently available for this artifact type."
+    )
+
+
+def render_improve_human(result: ImprovementResult) -> str:
+    if result.type == "unknown":
+        return _UNKNOWN_MESSAGE
+    if not result.supported:
+        return _unsupported_message(result)
+
+    lines = [_bold(f"Artifact Type: {result.type.title()}"), ""]
+    if not result.missing_required and not result.missing_recommended:
+        lines.append("Nothing to improve — all expected sections present.")
+        return "\n".join(lines)
+
+    def block(title: str, names: list[str]) -> None:
+        lines.extend([_bold(title)])
+        if names:
+            lines.extend(f"  - {s.title()}" for s in names)
+        else:
+            lines.append("  (none)")
+        lines.append("")
+
+    block("Missing Required:", result.missing_required)
+    block("Missing Recommended:", result.missing_recommended)
+    return "\n".join(lines).rstrip()
+
+
+def render_improve_json(result: ImprovementResult) -> str:
+    return json.dumps(result.to_dict(), indent=2)
+
+
+def render_improve_template(result: ImprovementResult) -> str:
+    """Emit Markdown templates for missing sections (required first)."""
+    if result.type == "unknown":
+        return _UNKNOWN_MESSAGE
+    if not result.supported:
+        return _unsupported_message(result)
+
+    missing = result.missing_required + result.missing_recommended
+    if not missing:
+        return "# Nothing to add — all expected sections present."
+
+    spec = spec_for(result.type)
+    descriptions = spec.descriptions if spec else {}
+    blocks: list[str] = []
+    for section in missing:
+        block = f"## {section.title()}\n\n_TODO_"
+        hint = descriptions.get(section)
+        if hint:
+            block += f"\n\n<!-- {hint} -->"
+        blocks.append(block)
+    return "\n\n".join(blocks) + "\n"
+
+
 # --- ingest ------------------------------------------------------------------
 
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: requirements-as-code
-Version: 0.4.2
+Version: 0.5.0
 Summary: RAC — lint and diff product requirements written in Markdown.
 Author: tcballard
 License-Expression: MIT
@@ -616,6 +616,67 @@ 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*. It reports the required and recommended sections an artifact is missing —
+**deterministically, from the schema, with no AI** (ADR-002) — and can emit
+Markdown templates for them. `improve` is **advisory and read-only**: it never
+modifies your files and never generates content beyond `_TODO_` placeholders.
+
+```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
+  - Assumptions
+```
+
+`--template` turns the gaps into a ready-to-paste skeleton (required sections
+first, then recommended), with a short guidance hint per section:
+
+```markdown
+## Risks
+
+_TODO_
+
+<!-- Potential implementation, delivery, or adoption risks -->
+```
+
+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"]
+}
+```
+
+v0.5.0 generates suggestions for **Requirement** artifacts. Other known types
+(e.g. Decision) and Unknown documents return a short explanatory message instead.
+`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.
+
+---
+
 ## Review (Planned)
 
 AI-assisted product review.

{requirements_as_code-0.4.2 → requirements_as_code-0.5.0}/requirements_as_code.egg-info/SOURCES.txt

@@ -45,6 +45,7 @@ rac/classification.py
 rac/cli.py
 rac/diff.py
 rac/fs.py
+rac/improve.py
 rac/ingest.py
 rac/inspect.py
 rac/models.py
@@ -62,6 +63,7 @@ tests/conftest.py
 tests/test_cli.py
 tests/test_decision_metadata.py
 tests/test_diff.py
+tests/test_improve.py
 tests/test_ingest.py
 tests/test_inspect.py
 tests/test_parser.py

requirements_as_code-0.5.0/tests/test_improve.py

@@ -0,0 +1,213 @@
+"""Tests for artifact improvement (`rac improve`, v0.5.0).
+
+Advisory, deterministic, schema-driven, read-only. Requirement artifacts get
+missing-section suggestions; other known types and Unknown get explanatory
+guidance. Exit code is always 0 for a completed analysis, 2 for usage errors.
+"""
+
+from __future__ import annotations
+
+import io
+import json
+from pathlib import Path
+
+import pytest
+
+from rac.cli import main
+from rac.improve import improve_file, improve_text
+
+from conftest import fixture_path
+
+# A requirement missing a *required* section (Requirements) but still classifying
+# as a requirement — it keeps enough recommended sections to clear the threshold.
+NO_REQUIREMENTS = (
+    "# Feature\n\n## Problem\n\np\n\n## Success Metrics\n\n- m\n\n## Risks\n\n- r\n"
+)
+
+
+# --- service layer ----------------------------------------------------------
+
+
+def test_requirement_reports_missing_recommended():
+    result = improve_file(fixture_path("inspect", "requirement.md"))
+    assert result.type == "requirement"
+    assert result.missing_required == []
+    assert "risks" in result.missing_recommended
+    assert "assumptions" in result.missing_recommended
+
+
+def test_requirement_reports_missing_required():
+    result = improve_text(NO_REQUIREMENTS)
+    assert result.type == "requirement"
+    assert result.missing_required == ["requirements"]
+    assert result.missing_recommended == ["assumptions"]
+
+
+def test_complete_requirement_has_nothing_missing():
+    complete = (
+        "# Feature\n\n## Problem\n\np\n\n## Requirements\n\n[REQ-001] x\n\n"
+        "## Success Metrics\n\n- m\n\n## Risks\n\n- r\n\n## Assumptions\n\n- a\n"
+    )
+    result = improve_text(complete)
+    assert result.type == "requirement"
+    assert result.missing_required == []
+    assert result.missing_recommended == []
+
+
+def test_unknown_artifact_yields_no_suggestions():
+    result = improve_file(fixture_path("inspect", "ambiguous.md"))
+    assert result.type == "unknown"
+    assert result.missing_required == []
+    assert result.missing_recommended == []
+
+
+def test_decision_is_out_of_scope_for_v050():
+    result = improve_file(fixture_path("decision", "with_metadata.md"))
+    assert result.type == "decision"
+    assert not result.supported
+    assert result.missing_required == []
+
+
+def test_improve_does_not_depend_on_typescore():
+    # Decoupling guard: improvement must not reach into classification scoring.
+    import inspect as _inspect
+
+    import rac.improve as improve_mod
+
+    src = _inspect.getsource(improve_mod)
+    assert "TypeScore" not in src
+    assert "score_artifacts" not in src
+
+
+# --- JSON contract (ADR-007) ------------------------------------------------
+
+
+def test_json_shape_is_stable(capsys):
+    rc = main(["improve", fixture_path("inspect", "requirement.md"), "--json"])
+    assert rc == 0
+    payload = json.loads(capsys.readouterr().out)
+    assert set(payload) == {"type", "missing_required", "missing_recommended"}
+    assert payload["type"] == "requirement"
+    # closest_type is reserved on the model but not serialized in v0.5.0.
+    assert "closest_type" not in payload
+
+
+def test_json_uses_snake_cased_section_names(capsys):
+    # "success metrics" -> "success_metrics" when missing.
+    text = "# F\n\n## Problem\n\np\n\n## Requirements\n\n[REQ-001] x\n"
+    monkey_stdin(text)
+    rc = main(["improve", "-", "--json"])
+    assert rc == 0
+    payload = json.loads(capsys.readouterr().out)
+    assert "success_metrics" in payload["missing_recommended"]
+
+
+def test_json_unknown_has_empty_arrays(capsys):
+    rc = main(["improve", fixture_path("inspect", "ambiguous.md"), "--json"])
+    assert rc == 0
+    payload = json.loads(capsys.readouterr().out)
+    assert payload["type"] == "unknown"
+    assert payload["missing_required"] == []
+    assert payload["missing_recommended"] == []
+
+
+# --- template (REQ-003) -----------------------------------------------------
+
+
+def test_template_emits_todo_and_guidance(capsys):
+    rc = main(["improve", fixture_path("inspect", "requirement.md"), "--template"])
+    assert rc == 0
+    out = capsys.readouterr().out
+    assert "## Risks" in out
+    assert "_TODO_" in out
+    assert "<!--" in out  # schema guidance comment
+
+
+def test_template_orders_required_before_recommended(capsys):
+    monkey_stdin(NO_REQUIREMENTS)
+    rc = main(["improve", "-", "--template"])
+    assert rc == 0
+    out = capsys.readouterr().out
+    assert out.index("## Requirements") < out.index("## Assumptions")
+
+
+# --- human output -----------------------------------------------------------
+
+
+def test_human_output_lists_missing(capsys):
+    rc = main(["improve", fixture_path("inspect", "requirement.md")])
+    assert rc == 0
+    out = capsys.readouterr().out
+    assert "Artifact Type: Requirement" in out
+    assert "Missing Recommended:" in out
+    assert "Risks" in out
+
+
+def test_human_unknown_message(capsys):
+    rc = main(["improve", fixture_path("inspect", "ambiguous.md")])
+    assert rc == 0
+    out = capsys.readouterr().out
+    assert "Unable to generate improvement guidance." in out
+    assert "could not be determined" in out
+
+
+def test_human_decision_is_generic_not_requirement_worded(capsys):
+    rc = main(["improve", fixture_path("decision", "with_metadata.md")])
+    assert rc == 0
+    out = capsys.readouterr().out
+    assert "Artifact Type: Decision" in out
+    assert "not currently available for this artifact type" in out
+    assert "Requirement" not in out  # no hard-coded requirement wording
+
+
+# --- pipelines (ADR-011) ----------------------------------------------------
+
+
+def monkey_stdin(text: str) -> None:
+    import sys
+
+    sys.stdin = io.StringIO(text)
+
+
+def test_stdin_matches_file(monkeypatch, capsys):
+    text = Path(fixture_path("inspect", "requirement.md")).read_text()
+    monkeypatch.setattr("sys.stdin", io.StringIO(text))
+    rc = main(["improve", "-", "--json"])
+    assert rc == 0
+    from_stdin = json.loads(capsys.readouterr().out)
+    assert from_stdin == improve_text(text).to_dict()
+
+
+# --- usage errors (exit 2) --------------------------------------------------
+
+
+def test_missing_file_exits_two():
+    with pytest.raises(SystemExit) as exc:
+        main(["improve", fixture_path("inspect", "does_not_exist.md")])
+    assert exc.value.code == 2
+
+
+def test_non_markdown_file_exits_two(tmp_path):
+    bad = tmp_path / "notes.txt"
+    bad.write_text("hello")
+    with pytest.raises(SystemExit) as exc:
+        main(["improve", str(bad)])
+    assert exc.value.code == 2
+
+
+def test_json_and_template_are_mutually_exclusive():
+    with pytest.raises(SystemExit):  # argparse mutually-exclusive error
+        main(["improve", fixture_path("inspect", "requirement.md"), "--json", "--template"])
+
+
+# --- read-only (REQ-004) ----------------------------------------------------
+
+
+def test_improve_does_not_modify_the_file(tmp_path):
+    f = tmp_path / "req.md"
+    original = "# F\n\n## Problem\n\np\n\n## Requirements\n\n[REQ-001] x\n"
+    f.write_text(original)
+    before = f.stat().st_mtime_ns
+    main(["improve", str(f), "--template"])
+    assert f.read_text() == original
+    assert f.stat().st_mtime_ns == before