feat: specsmith architect command (#49), audit --fix generates missing docs

tbitcs · oz-agent · tbitcs · commit 5b7ad9c38340 · 2026-04-02T12:50:04.000-04:00
New 'specsmith architect' command: - Scans project for modules, languages, deps, git history, existing docs - Interactive interview: components, purposes, interfaces, data flow, deployment - Generates rich docs/architecture.md with all detected + user-provided info - References existing architecture docs in non-standard locations - --non-interactive flag for auto-generation without prompts Enhanced audit --fix: - Missing docs/architecture.md: auto-generates from project scan - Missing docs/REQUIREMENTS.md: creates stub with REQ-CORE-001 - Missing docs/TEST_SPEC.md: creates stub - All recommended files now marked as fixable in audit output Also fixes: audit now finds architecture docs in subdirectories (e.g. docs/architecture/DESIGN.md) Closes #49 Co-Authored-By: Oz <oz-agent@warp.dev>
diff --git a/src/specsmith/architect.py b/src/specsmith/architect.py
@@ -0,0 +1,154 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 BitConcepts, LLC. All rights reserved.
+"""Architect — scan project and generate architecture documentation."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def scan_project_structure(root: Path) -> dict[str, object]:  # noqa: C901
+    """Scan a project and extract architecture-relevant information.
+
+    Returns a dict with modules, entry_points, languages, dependencies,
+    git_summary, and existing_docs.
+    """
+    from specsmith.importer import (
+        _extract_git_commits,
+        _extract_git_contributors,
+        _extract_readme_summary,
+        _parse_dependencies,
+        detect_project,
+    )
+
+    result = detect_project(root)
+    commits = _extract_git_commits(root)
+    contributors = _extract_git_contributors(root)
+    readme = _extract_readme_summary(root)
+    deps = _parse_dependencies(root)
+
+    # Find existing architecture docs
+    existing_arch: list[str] = []
+    docs_dir = root / "docs"
+    if docs_dir.is_dir():
+        for p in docs_dir.rglob("*"):
+            if p.is_file() and "architecture" in p.name.lower():
+                existing_arch.append(str(p.relative_to(root)))
+
+    return {
+        "name": root.name,
+        "languages": result.languages,
+        "primary_language": result.primary_language,
+        "secondary_languages": result.secondary_languages,
+        "build_system": result.build_system,
+        "test_framework": result.test_framework,
+        "modules": result.modules,
+        "entry_points": result.entry_points,
+        "dependencies": deps,
+        "readme_summary": readme,
+        "recent_commits": commits[:10],
+        "contributors": contributors,
+        "existing_arch_docs": existing_arch,
+        "file_count": result.file_count,
+        "inferred_type": result.inferred_type.value if result.inferred_type else "unknown",
+    }
+
+
+def generate_architecture(
+    root: Path,
+    *,
+    components: list[dict[str, str]] | None = None,
+    data_flow: str = "",
+    deployment: str = "",
+    scan: dict[str, object] | None = None,
+) -> Path:
+    """Generate docs/architecture.md from scan data + user input.
+
+    Returns the path to the generated file.
+    """
+    if scan is None:
+        scan = scan_project_structure(root)
+
+    name = str(scan.get("name", root.name))
+    langs: dict[str, int] = dict(scan.get("languages", {}) or {})  # type: ignore[call-overload]
+    primary = str(scan.get("primary_language", "unknown"))
+    secondary: list[str] = list(scan.get("secondary_languages", []) or [])  # type: ignore[call-overload]
+    lang_list = [primary] + secondary
+    lang_display = ", ".join(str(l) for l in lang_list if l)  # noqa: E741
+
+    doc = f"# Architecture — {name}\n\n"
+
+    # Overview
+    doc += "## Overview\n\n"
+    readme = scan.get("readme_summary", "")
+    if readme:
+        doc += f"{readme}\n\n"
+    doc += f"- **Languages**: {lang_display}\n"
+    doc += f"- **Build system**: {scan.get('build_system', 'not detected')}\n"
+    doc += f"- **Test framework**: {scan.get('test_framework', 'not detected')}\n"
+    doc += f"- **Project type**: {scan.get('inferred_type', 'unknown')}\n"
+    doc += f"- **Files**: {scan.get('file_count', 0)}\n\n"
+
+    # Components
+    if components:
+        doc += "## Components\n\n"
+        for comp in components:
+            doc += f"### {comp.get('name', 'unnamed')}\n"
+            if comp.get("purpose"):
+                doc += f"- **Purpose**: {comp['purpose']}\n"
+            if comp.get("interfaces"):
+                doc += f"- **Interfaces**: {comp['interfaces']}\n"
+            if comp.get("dependencies"):
+                doc += f"- **Dependencies**: {comp['dependencies']}\n"
+            doc += "\n"
+    elif scan.get("modules"):
+        doc += "## Modules\n\n"
+        for mod in list(scan.get("modules", []) or []):  # type: ignore[call-overload]
+            doc += f"### {mod}\n- **Purpose**: [Describe {mod} purpose]\n\n"
+
+    # Data flow
+    if data_flow:
+        doc += f"## Data Flow\n\n{data_flow}\n\n"
+    else:
+        doc += "## Data Flow\n\n[Describe how data flows between components]\n\n"
+
+    # Dependencies
+    deps: list[str] = list(scan.get("dependencies", []) or [])  # type: ignore[call-overload]
+    if deps:
+        doc += "## External Dependencies\n\n"
+        for dep in deps[:30]:
+            doc += f"- `{dep}`\n"
+        doc += "\n"
+
+    # Entry points
+    eps: list[str] = list(scan.get("entry_points", []) or [])  # type: ignore[call-overload]
+    if eps:
+        doc += "## Entry Points\n\n"
+        for ep in eps:
+            doc += f"- `{ep}`\n"
+        doc += "\n"
+
+    # Language distribution
+    if langs and len(langs) > 1:
+        doc += "## Language Distribution\n\n"
+        for lang_name, count in sorted(langs.items(), key=lambda x: -x[1]):
+            doc += f"- {lang_name}: {count} files\n"
+        doc += "\n"
+
+    # Deployment
+    if deployment:
+        doc += f"## Deployment\n\n{deployment}\n\n"
+
+    # Existing architecture references
+    existing: list[str] = list(scan.get("existing_arch_docs", []) or [])  # type: ignore[call-overload]
+    if existing:
+        doc += "## Related Documents\n\n"
+        for ref in existing:
+            doc += f"- [{ref}]({ref})\n"
+        doc += "\n"
+
+    # Write
+    arch_path = root / "docs" / "architecture.md"
+    arch_path.parent.mkdir(parents=True, exist_ok=True)
+    arch_path.write_text(doc, encoding="utf-8")
+    return arch_path
diff --git a/src/specsmith/auditor.py b/src/specsmith/auditor.py
@@ -132,6 +132,7 @@ def check_governance_files(root: Path) -> list[AuditResult]:
                 name=f"recommended:{f}",
                 passed=found,
                 message=f"Recommended file {f} {'exists' if found else 'missing'}",
+                fixable=not found,
             )
         )
 
@@ -565,4 +566,42 @@ def run_auto_fix(root: Path, report: AuditReport) -> list[str]:
                 except Exception:  # noqa: BLE001
                     pass  # Best-effort
 
+        # Fix missing recommended files
+        elif result.name == "recommended:docs/architecture.md" and not result.passed:
+            from specsmith.architect import generate_architecture
+
+            try:
+                generate_architecture(root)
+                fixed.append("Generated docs/architecture.md from project scan")
+            except Exception:  # noqa: BLE001
+                # Fallback stub
+                path = root / "docs" / "architecture.md"
+                path.parent.mkdir(parents=True, exist_ok=True)
+                path.write_text(
+                    f"# Architecture — {root.name}\n\n"
+                    "[Run `specsmith architect` to populate]\n",
+                    encoding="utf-8",
+                )
+                fixed.append("Created stub docs/architecture.md")
+
+        elif result.name == "recommended:docs/REQUIREMENTS.md" and not result.passed:
+            path = root / "docs" / "REQUIREMENTS.md"
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_text(
+                "# Requirements\n\nNo requirements defined yet.\n\n"
+                "## REQ-CORE-001\n- **Component**: core\n"
+                "- **Status**: Draft\n- **Description**: [Define]\n",
+                encoding="utf-8",
+            )
+            fixed.append("Created stub docs/REQUIREMENTS.md")
+
+        elif result.name == "recommended:docs/TEST_SPEC.md" and not result.passed:
+            path = root / "docs" / "TEST_SPEC.md"
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_text(
+                "# Test Specification\n\nNo tests defined yet.\n",
+                encoding="utf-8",
+            )
+            fixed.append("Created stub docs/TEST_SPEC.md")
+
     return fixed
diff --git a/src/specsmith/cli.py b/src/specsmith/cli.py
@@ -646,6 +646,68 @@ def _run_guided_architecture(cfg: ProjectConfig, target: Path) -> list[Path]:
     return created
 
 
+@main.command()
+@click.option("--project-dir", type=click.Path(exists=True), default=".", help="Project root.")
+@click.option("--non-interactive", is_flag=True, default=False, help="Skip prompts, auto-generate.")
+def architect(project_dir: str, non_interactive: bool) -> None:
+    """Generate or enrich architecture documentation.
+
+    Scans the project for modules, languages, dependencies, git history,
+    then optionally interviews you about components and data flow.
+    """
+    from specsmith.architect import generate_architecture, scan_project_structure
+
+    root = Path(project_dir).resolve()
+    console.print(f"[bold]Scanning[/bold] {root}...\n")
+    scan = scan_project_structure(root)
+
+    modules: list[str] = list(scan.get("modules", []) or [])  # type: ignore[call-overload]
+    deps_list: list[str] = list(scan.get("dependencies", []) or [])  # type: ignore[call-overload]
+    eps_list: list[str] = list(scan.get("entry_points", []) or [])  # type: ignore[call-overload]
+    existing: list[str] = list(scan.get("existing_arch_docs", []) or [])  # type: ignore[call-overload]
+
+    console.print(f"  Languages: {scan.get('primary_language', '?')}")
+    console.print(f"  Modules: {', '.join(modules) or 'none'}")
+    console.print(f"  Dependencies: {len(deps_list)}")
+    console.print(f"  Entry points: {', '.join(eps_list) or 'none'}")
+    if existing:
+        console.print(f"  Existing arch docs: {', '.join(existing)}")
+    console.print()
+
+    components: list[dict[str, str]] | None = None
+    data_flow = ""
+    deployment = ""
+
+    if not non_interactive:
+        console.print("[bold]Architecture Interview[/bold]\n")
+        comp_str = click.prompt(
+            "Major components (comma-separated)",
+            default=", ".join(modules or ["core"]),
+        )
+        components = []
+        for name in [c.strip() for c in comp_str.split(",") if c.strip()]:
+            purpose = click.prompt(f"  {name} purpose", default="")
+            interfaces = click.prompt(f"  {name} interfaces", default="")
+            components.append({"name": name, "purpose": purpose, "interfaces": interfaces})
+
+        data_flow = click.prompt("\nData flow description", default="")
+        deployment = click.prompt("Deployment notes", default="")
+
+    path = generate_architecture(
+        root, components=components, data_flow=data_flow, deployment=deployment, scan=scan
+    )
+    rel = path.relative_to(root)
+    console.print(f"\n[green]\u2713[/green] Generated {rel}")
+    if existing:
+        console.print(
+            f"  [yellow]Note:[/yellow] Existing docs at {', '.join(existing)} "
+            "are referenced but not merged. Review manually."
+        )
+    console.print(
+        "  [dim]Run \"specsmith audit --project-dir .\" to verify governance health.[/dim]"
+    )
+
+
 # ---------------------------------------------------------------------------
 # Ledger subcommands
 # ---------------------------------------------------------------------------
