csd-intent 0.4.0__tar.gz

csd_intent-0.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rafael Pires
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

csd_intent-0.4.0/PKG-INFO

@@ -0,0 +1,148 @@
+Metadata-Version: 2.4
+Name: csd-intent
+Version: 0.4.0
+Summary: Cross-runtime audit tool for CSD intent specifications. Validates intent.yaml against CSD-INTENT-01 and verifies each claim is attested by at least one test across pytest, vitest, Playwright, or any other runner using the standard intent() marker.
+Author: Rafael Pires
+License: MIT
+Project-URL: Homepage, https://github.com/PSA-Department-of-Engineering/csd-library
+Project-URL: Documentation, https://github.com/PSA-Department-of-Engineering/csd-library#readme
+Project-URL: CSD methodology, https://github.com/PSA-Department-of-Engineering/cognitive-software-delivery
+Keywords: csd,intent,testing,specification,audit,cross-language
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Dynamic: license-file
+
+# csd-intent
+
+Cross-runtime audit tool for CSD intent specifications. Validates `intent.yaml`
+against [CSD-INTENT-01](https://github.com/PSA-Department-of-Engineering/cognitive-software-delivery) and confirms every
+claim is attested by at least one test marker across **any** test runner -
+pytest, vitest, Playwright, Jest, or anything that uses the standard `intent()`
+/ `@intent()` marker shape.
+
+This tool is **standalone**. It does not run inside your project's test suite; it
+is invoked separately (CLI, CI step, or pre-commit hook).
+
+## Why it exists
+
+`pytest-intent`, `vitest-intent`, and `playwright-intent` provide the test-side
+marker helpers - they let a test declare which intent claim it attests. They
+deliberately know nothing about other runtimes, schema validation, or whether a
+claim is unattested.
+
+`csd-intent` owns the cross-runtime auditing: it walks every test file in the
+project (Python via AST, TS/JS via regex), reads `intent.yaml`, and answers:
+
+1. **Schema** - does every claim match CSD-INTENT-01?
+2. **Orphan** - does every test marker reference a real claim?
+3. **Coverage** - does every claim have at least one attesting test, anywhere?
+
+## Install
+
+```bash
+# From PyPI:
+pip install csd-intent
+
+# Local dev against a csd-library checkout:
+pip install -e path/to/csd-library/csd-intent
+```
+
+## Use
+
+```bash
+# Audit the current directory (expects intent.yaml at the root):
+csd-intent
+
+# Audit a specific project:
+csd-intent /path/to/project
+
+# Audit but tolerate unattested claims (the "intent before test" workflow):
+csd-intent --fail-on schema
+
+# Constrain the scan to specific directories:
+csd-intent --tests-dir backend/tests --tests-dir frontend/src --tests-dir e2e
+
+# Quiet summary only:
+csd-intent --quiet
+```
+
+Exit code is `0` on a clean audit, `1` when any violation falls into the
+configured `--fail-on` set (`any` by default).
+
+## Output
+
+```
+intent.yaml (/path/to/project/intent.yaml): 24 claims, 2 violation(s).
+
+UNATTESTED (2):
+  [unattested] INT-SB-018: no @intent / intent() marker references this claim
+  [unattested] INT-SB-029: no @intent / intent() marker references this claim
+```
+
+## What it scans
+
+- **Python**: any file matching `test_*.py` or `*_test.py`, walked via AST for
+  `@intent("INT-...")` decorators on functions starting with `test_`.
+- **JS/TS**: any file matching `*.test.{ts,tsx,js,jsx,mts,cts}` or
+  `*.spec.{ts,...}`, scanned by regex for `intent('INT-...', 'name', fn)` calls
+  (single-ID and array-of-IDs forms both supported).
+- **Excluded directories**: `node_modules`, `.venv`, `venv`, `dist`, `build`,
+  `.git`, `__pycache__`, `.pytest_cache`, `.mypy_cache`, `.ruff_cache`, `.tox`.
+
+## CSD-INTENT-01 conformance
+
+The schema check validates each claim against the canonical fields per
+[CSD-INTENT-01 §4.1](https://github.com/PSA-Department-of-Engineering/cognitive-software-delivery):
+
+```yaml
+INT-NNN:
+  version: 1.0.0
+  status: active                # draft | active | deprecated
+  statement: "..."              # >= 10 chars, RFC 2119 language
+  rationale: "..."              # optional but recommended
+  test:
+    scope: integration          # unit | integration | e2e
+    component: SwitchFlow
+    type: behavior              # invariant | behavior | contract
+  criticality: critical         # critical | high | medium | low
+```
+
+For projects still on the legacy flat-`scope:` shape, the tool accepts it (with
+no warning) - that's a migration concession, not a recommendation.
+
+### Duplicate keys are refused
+
+`intent.yaml` is parsed with a loader that raises on a repeated key rather than
+resolving it last-wins. A claim id reused by accident would otherwise delete the
+earlier claim before any check could see it - and every marker written for that
+claim would silently start attesting the survivor, with the audit still printing
+`CLEAN`. The duplicate is reported as a schema violation naming both lines:
+
+```
+SCHEMA (1):
+  [schema] intent.yaml: duplicate key `INT-GATE-006` (first declared on line 42,
+  declared again on line 187); YAML would silently keep only the last one
+```
+
+Merge keys still work: `<<: *base` plus an explicit override is not a duplicate.
+
+## License
+
+MIT.

csd_intent-0.4.0/README.md

@@ -0,0 +1,117 @@
+# csd-intent
+
+Cross-runtime audit tool for CSD intent specifications. Validates `intent.yaml`
+against [CSD-INTENT-01](https://github.com/PSA-Department-of-Engineering/cognitive-software-delivery) and confirms every
+claim is attested by at least one test marker across **any** test runner -
+pytest, vitest, Playwright, Jest, or anything that uses the standard `intent()`
+/ `@intent()` marker shape.
+
+This tool is **standalone**. It does not run inside your project's test suite; it
+is invoked separately (CLI, CI step, or pre-commit hook).
+
+## Why it exists
+
+`pytest-intent`, `vitest-intent`, and `playwright-intent` provide the test-side
+marker helpers - they let a test declare which intent claim it attests. They
+deliberately know nothing about other runtimes, schema validation, or whether a
+claim is unattested.
+
+`csd-intent` owns the cross-runtime auditing: it walks every test file in the
+project (Python via AST, TS/JS via regex), reads `intent.yaml`, and answers:
+
+1. **Schema** - does every claim match CSD-INTENT-01?
+2. **Orphan** - does every test marker reference a real claim?
+3. **Coverage** - does every claim have at least one attesting test, anywhere?
+
+## Install
+
+```bash
+# From PyPI:
+pip install csd-intent
+
+# Local dev against a csd-library checkout:
+pip install -e path/to/csd-library/csd-intent
+```
+
+## Use
+
+```bash
+# Audit the current directory (expects intent.yaml at the root):
+csd-intent
+
+# Audit a specific project:
+csd-intent /path/to/project
+
+# Audit but tolerate unattested claims (the "intent before test" workflow):
+csd-intent --fail-on schema
+
+# Constrain the scan to specific directories:
+csd-intent --tests-dir backend/tests --tests-dir frontend/src --tests-dir e2e
+
+# Quiet summary only:
+csd-intent --quiet
+```
+
+Exit code is `0` on a clean audit, `1` when any violation falls into the
+configured `--fail-on` set (`any` by default).
+
+## Output
+
+```
+intent.yaml (/path/to/project/intent.yaml): 24 claims, 2 violation(s).
+
+UNATTESTED (2):
+  [unattested] INT-SB-018: no @intent / intent() marker references this claim
+  [unattested] INT-SB-029: no @intent / intent() marker references this claim
+```
+
+## What it scans
+
+- **Python**: any file matching `test_*.py` or `*_test.py`, walked via AST for
+  `@intent("INT-...")` decorators on functions starting with `test_`.
+- **JS/TS**: any file matching `*.test.{ts,tsx,js,jsx,mts,cts}` or
+  `*.spec.{ts,...}`, scanned by regex for `intent('INT-...', 'name', fn)` calls
+  (single-ID and array-of-IDs forms both supported).
+- **Excluded directories**: `node_modules`, `.venv`, `venv`, `dist`, `build`,
+  `.git`, `__pycache__`, `.pytest_cache`, `.mypy_cache`, `.ruff_cache`, `.tox`.
+
+## CSD-INTENT-01 conformance
+
+The schema check validates each claim against the canonical fields per
+[CSD-INTENT-01 §4.1](https://github.com/PSA-Department-of-Engineering/cognitive-software-delivery):
+
+```yaml
+INT-NNN:
+  version: 1.0.0
+  status: active                # draft | active | deprecated
+  statement: "..."              # >= 10 chars, RFC 2119 language
+  rationale: "..."              # optional but recommended
+  test:
+    scope: integration          # unit | integration | e2e
+    component: SwitchFlow
+    type: behavior              # invariant | behavior | contract
+  criticality: critical         # critical | high | medium | low
+```
+
+For projects still on the legacy flat-`scope:` shape, the tool accepts it (with
+no warning) - that's a migration concession, not a recommendation.
+
+### Duplicate keys are refused
+
+`intent.yaml` is parsed with a loader that raises on a repeated key rather than
+resolving it last-wins. A claim id reused by accident would otherwise delete the
+earlier claim before any check could see it - and every marker written for that
+claim would silently start attesting the survivor, with the audit still printing
+`CLEAN`. The duplicate is reported as a schema violation naming both lines:
+
+```
+SCHEMA (1):
+  [schema] intent.yaml: duplicate key `INT-GATE-006` (first declared on line 42,
+  declared again on line 187); YAML would silently keep only the last one
+```
+
+Merge keys still work: `<<: *base` plus an explicit override is not a duplicate.
+
+## License
+
+MIT.

csd_intent-0.4.0/csd_intent/__init__.py

@@ -0,0 +1,46 @@
+"""csd-intent - cross-runtime auditor for CSD intent specifications.
+
+Validates intent.yaml against CSD-INTENT-01 (schema check), confirms every
+@intent / intent() marker references a real claim (orphan check), and reports
+unattested claims by walking every test file in the project (coverage check).
+
+Nested projects: a repo may contain nested intent projects (a subdirectory with its
+own intent.yaml). ``audit_tree()`` discovers and audits each as its own project, so a
+nested project's markers are checked against its own intent.yaml rather than orphaning
+against the outer project's claims.
+
+Public API:
+    audit(project_dir, intent_path=None, test_dirs=None) -> AuditReport
+    audit_tree(project_dir) -> list[AuditReport]
+    AuditReport, AuditViolation
+    parse_intent_yaml(path)  # raises DuplicateKeyError on a repeated key
+    check_schema(claims)
+    collect_attestations(test_dirs)
+    find_nested_intent_projects(root)
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .audit import AuditReport, AuditViolation, audit, audit_tree
+from .schema import DuplicateKeyError, check_schema, parse_intent_yaml
+from .walker import collect_attestations, find_nested_intent_projects
+
+try:
+    __version__ = version("csd-intent")
+except PackageNotFoundError:
+    __version__ = "0.0.0+unknown"
+
+__all__ = [
+    "AuditReport",
+    "AuditViolation",
+    "DuplicateKeyError",
+    "__version__",
+    "audit",
+    "audit_tree",
+    "check_schema",
+    "collect_attestations",
+    "find_nested_intent_projects",
+    "parse_intent_yaml",
+]

csd_intent-0.4.0/csd_intent/audit.py

@@ -0,0 +1,194 @@
+"""Orchestrates schema + orphan + coverage checks into a single audit report."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from pathlib import Path
+
+from .schema import DuplicateKeyError, check_schema, parse_intent_yaml, top_level_keys
+from .walker import collect_attestations, find_nested_intent_projects
+
+__all__ = [
+    "AuditReport",
+    "AuditViolation",
+    "ViolationKind",
+    "audit",
+    "audit_tree",
+]
+
+
+class ViolationKind(str, Enum):
+    SCHEMA = "schema"
+    ORPHAN = "orphan"
+    UNATTESTED = "unattested"
+
+
+@dataclass(frozen=True)
+class AuditViolation:
+    kind: ViolationKind
+    claim_id: str | None
+    message: str
+
+    def __str__(self) -> str:
+        prefix = self.claim_id or "intent.yaml"
+        return f"[{self.kind.value}] {prefix}: {self.message}"
+
+
+@dataclass
+class AuditReport:
+    """The result of a project audit. Empty `violations` = clean."""
+
+    intent_path: Path
+    claim_count: int
+    attested_claims: set[str] = field(default_factory=set)
+    orphan_refs: dict[str, list[str]] = field(default_factory=dict)
+    violations: list[AuditViolation] = field(default_factory=list)
+
+    @property
+    def ok(self) -> bool:
+        return not self.violations
+
+    @property
+    def unattested(self) -> list[str]:
+        return sorted(
+            v.claim_id
+            for v in self.violations
+            if v.kind == ViolationKind.UNATTESTED and v.claim_id
+        )
+
+    def format(self) -> str:
+        if self.ok:
+            return (
+                f"intent.yaml ({self.intent_path}): {self.claim_count} claims, "
+                f"{len(self.attested_claims)} attested. CLEAN."
+            )
+        by_kind: dict[ViolationKind, list[AuditViolation]] = {}
+        for v in self.violations:
+            by_kind.setdefault(v.kind, []).append(v)
+        lines = [
+            f"intent.yaml ({self.intent_path}): {self.claim_count} claims, "
+            f"{len(self.violations)} violation(s)."
+        ]
+        for kind in (ViolationKind.SCHEMA, ViolationKind.ORPHAN, ViolationKind.UNATTESTED):
+            items = by_kind.get(kind, [])
+            if not items:
+                continue
+            lines.append(f"\n{kind.value.upper()} ({len(items)}):")
+            for v in items:
+                lines.append(f"  {v}")
+        return "\n".join(lines)
+
+
+def audit(
+    project_dir: Path,
+    intent_path: Path | None = None,
+    test_dirs: list[Path] | None = None,
+) -> AuditReport:
+    """Audit a project's intent spec + test attestations.
+
+    Args:
+        project_dir: project root (used to resolve defaults).
+        intent_path: explicit intent.yaml location; defaults to ``project_dir/intent.yaml``.
+        test_dirs:   directories to scan for @intent / intent() markers; defaults to
+                     ``[project_dir]`` (the walker handles exclude rules).
+    """
+    project_dir = project_dir.resolve()
+    intent_path = (intent_path or project_dir / "intent.yaml").resolve()
+    test_dirs = test_dirs or [project_dir]
+
+    report = AuditReport(intent_path=intent_path, claim_count=0)
+
+    if not intent_path.exists():
+        report.violations.append(
+            AuditViolation(ViolationKind.SCHEMA, None, f"intent.yaml not found at {intent_path}")
+        )
+        return report
+
+    # A repeated key resolves last-wins in YAML itself, so the earlier claim is gone
+    # before any check runs and its markers now attest the survivor. Nothing further
+    # in this audit would be true of the spec its author wrote, so stop here (#12).
+    try:
+        claims = parse_intent_yaml(intent_path)
+    except DuplicateKeyError as exc:
+        report.violations.append(AuditViolation(ViolationKind.SCHEMA, None, str(exc)))
+        return report
+
+    report.claim_count = len(claims)
+
+    # A file present with nothing the parser recognises is schema drift, not an
+    # empty-but-valid project: report it loudly rather than a silent CLEAN (#5).
+    if not claims:
+        keys = top_level_keys(intent_path)
+        found = f"found keys: {', '.join(keys)}" if keys else "the file has no top-level keys"
+        report.violations.append(
+            AuditViolation(
+                ViolationKind.SCHEMA,
+                None,
+                f"intent.yaml has no top-level INT-* claims; {found}",
+            )
+        )
+
+    # Schema
+    for msg in check_schema(claims):
+        cid = msg.split(":", 1)[0] if ":" in msg else None
+        rest = msg.split(":", 1)[1].strip() if ":" in msg else msg
+        report.violations.append(AuditViolation(ViolationKind.SCHEMA, cid, rest))
+
+    # Attestations across all test dirs
+    attestations = collect_attestations(test_dirs)
+    claim_ids = set(claims.keys())
+    attested_ids = set(attestations.keys())
+    report.attested_claims = claim_ids & attested_ids
+
+    # Orphans: marker references a claim that does not exist
+    for cid in sorted(attested_ids - claim_ids):
+        refs = attestations.get(cid, [])
+        report.orphan_refs[cid] = refs
+        report.violations.append(
+            AuditViolation(
+                ViolationKind.ORPHAN,
+                cid,
+                f"test marker references unknown claim ({len(refs)} ref(s): {refs[:3]}{'...' if len(refs) > 3 else ''})",
+            )
+        )
+
+    # Unattested: claim has no marker anywhere.
+    # Only enforce for ACTIVE claims. Deprecated claims document a behaviour
+    # that no longer holds (no tests expected). Draft claims are pre-implementation
+    # placeholders (tests may not yet exist) - surface as informational but don't
+    # treat as a failing violation.
+    for cid in sorted(claim_ids - attested_ids):
+        status = str(claims[cid].get("status", "active"))
+        if status == "deprecated":
+            continue
+        if status == "draft":
+            continue
+        report.violations.append(
+            AuditViolation(
+                ViolationKind.UNATTESTED, cid, "no @intent / intent() marker references this claim"
+            )
+        )
+
+    return report
+
+
+def audit_tree(project_dir: Path) -> list[AuditReport]:
+    """Discover and audit every intent project at or below ``project_dir``.
+
+    The starting ``project_dir`` is audited as the root project (its marker scan is
+    bounded by any nested project subtrees). Each subdirectory that carries its own
+    ``intent.yaml`` is then audited as an independent project against the markers in
+    its own subtree (bounded, in turn, by any still-deeper nested projects). The result
+    is a complete, non-overlapping partition of the tree into projects.
+
+    Returns one :class:`AuditReport` per project, root first, then nested projects in a
+    deterministic (sorted) order. This is the auto-discovery path used by the CLI when no
+    explicit ``--intent`` / ``--tests-dir`` override is given. For the explicit
+    single-project case, call :func:`audit` directly.
+    """
+    project_dir = project_dir.resolve()
+    reports = [audit(project_dir)]
+    for nested in find_nested_intent_projects(project_dir):
+        reports.append(audit(nested))
+    return reports

csd_intent-0.4.0/csd_intent/cli.py

@@ -0,0 +1,158 @@
+"""CLI entry point for csd-intent.
+
+Usage:
+  csd-intent [PROJECT_DIR]
+             [--intent PATH]
+             [--tests-dir DIR]...
+             [--fail-on schema|orphan|unattested|any|none]
+             [--quiet]
+             [--version]
+
+Default ``PROJECT_DIR`` is the cwd. Default ``--fail-on`` is ``any`` (exit non-zero
+on any violation). Use ``--fail-on schema`` to only fail on schema problems and
+treat coverage gaps as warnings (matches the "intent before test" CSD workflow).
+
+Nested projects: when PROJECT_DIR contains nested intent projects (subdirectories with
+their own intent.yaml), each is discovered and audited as its own project against the
+markers in its own subtree. A per-project summary is printed and the process exits
+non-zero if *any* project has a failing violation. Passing ``--intent`` or
+``--tests-dir`` switches to an explicit single-project audit (no auto-discovery).
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from .audit import AuditReport, ViolationKind, audit, audit_tree
+
+_FAIL_MAP = {
+    "schema": {ViolationKind.SCHEMA},
+    "orphan": {ViolationKind.ORPHAN},
+    "unattested": {ViolationKind.UNATTESTED},
+    "any": {ViolationKind.SCHEMA, ViolationKind.ORPHAN, ViolationKind.UNATTESTED},
+    "none": set(),
+}
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="csd-intent",
+        description="Audit a CSD intent project: schema + orphan + coverage checks.",
+    )
+    parser.add_argument(
+        "project_dir",
+        nargs="?",
+        default=".",
+        type=Path,
+        help="Project root (default: cwd).",
+    )
+    parser.add_argument(
+        "--intent",
+        type=Path,
+        default=None,
+        help=(
+            "Path to intent.yaml; a relative path is anchored to PROJECT_DIR "
+            "(default: PROJECT_DIR/intent.yaml)."
+        ),
+    )
+    parser.add_argument(
+        "--tests-dir",
+        dest="tests_dirs",
+        action="append",
+        type=Path,
+        default=None,
+        help=(
+            "Directory to scan for test markers; a relative path is anchored to "
+            "PROJECT_DIR (repeatable; default: PROJECT_DIR)."
+        ),
+    )
+    parser.add_argument(
+        "--fail-on",
+        choices=tuple(_FAIL_MAP.keys()),
+        default="any",
+        help="Which violation kinds cause a non-zero exit (default: any).",
+    )
+    parser.add_argument(
+        "--quiet",
+        action="store_true",
+        help="Suppress the per-violation report; only print the summary line.",
+    )
+    parser.add_argument("--version", action="store_true", help="Print version and exit.")
+    return parser
+
+
+def _print_report(report: AuditReport, quiet: bool) -> None:
+    if quiet:
+        print(
+            f"{report.intent_path}: {report.claim_count} claims, "
+            f"{len(report.violations)} violation(s)."
+        )
+    else:
+        print(report.format())
+
+
+def _has_failing_violation(report: AuditReport, fail_kinds: set[ViolationKind]) -> bool:
+    return any(v.kind in fail_kinds for v in report.violations)
+
+
+def _anchored(project_dir: Path, path: Path) -> Path:
+    """Anchor a relative path to the project root rather than the caller's cwd."""
+    return path if path.is_absolute() else project_dir / path
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _build_parser().parse_args(argv)
+
+    if args.version:
+        from . import __version__
+
+        print(__version__)
+        return 0
+
+    fail_kinds = _FAIL_MAP[args.fail_on]
+
+    # Explicit single-project mode: --intent / --tests-dir disables auto-discovery.
+    if args.intent is not None or args.tests_dirs is not None:
+        report = audit(
+            project_dir=args.project_dir,
+            intent_path=(
+                None if args.intent is None else _anchored(args.project_dir, args.intent)
+            ),
+            test_dirs=(
+                None
+                if args.tests_dirs is None
+                else [_anchored(args.project_dir, d) for d in args.tests_dirs]
+            ),
+        )
+        _print_report(report, args.quiet)
+        return 1 if _has_failing_violation(report, fail_kinds) else 0
+
+    # Auto-discovery mode: audit the root project plus any nested intent projects.
+    reports = audit_tree(args.project_dir)
+
+    # Backward-compatible single-project output when there is no nesting: identical
+    # to the pre-nesting behaviour (one report, no per-project banner).
+    if len(reports) == 1:
+        _print_report(reports[0], args.quiet)
+        return 1 if _has_failing_violation(reports[0], fail_kinds) else 0
+
+    # Multiple projects: per-project report plus an aggregate summary.
+    failed = 0
+    for i, report in enumerate(reports):
+        if i:
+            print()
+        _print_report(report, args.quiet)
+        if _has_failing_violation(report, fail_kinds):
+            failed += 1
+
+    clean = len(reports) - failed
+    print(
+        f"\n{len(reports)} project(s) audited: {clean} clean, {failed} with violation(s)."
+    )
+    return 1 if failed else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())