feat(reflector): bootstrap pass-based organization discovery audit engine

.github/audits/2026-06-26T024532Z/organization.audit.json

@@ -0,0 +1,85 @@
+{
+  "metadata": {
+    "engine": "reflector.audit",
+    "output_directory": ".github/audits/2026-06-26T024532Z",
+    "passes": [
+      "00_discovery"
+    ],
+    "read_only": true,
+    "timestamp_local": "2026-06-26T02:45:32.706374+00:00",
+    "timestamp_utc": "2026-06-26T02:45:32.706370+00:00",
+    "version": "0.1.0"
+  },
+  "organization": {
+    "default_branch": "main",
+    "description": "Organization-wide standards, templates, and developer experience",
+    "name": "egohygiene"
+  },
+  "policy": {
+    "analysis_goals": [
+      "Observe repository documentation and structure quality",
+      "Capture technology manifests and metadata"
+    ],
+    "name": "documentation",
+    "optimization_priorities": [
+      "coverage",
+      "reusability",
+      "read_only"
+    ],
+    "output": {
+      "formats": [
+        "md",
+        "json"
+      ],
+      "include_repository_audits": true
+    },
+    "recommendation_style": "disabled",
+    "repository_selection": {
+      "exclude": [],
+      "include": [
+        "*"
+      ]
+    }
+  },
+  "repositories": [
+    {
+      "architectural_observations": [
+        "Repository appears to be organized with top-level directories: .github, profile, reflector",
+        "Discovery pass is read-only and did not modify repository content"
+      ],
+      "detected_technologies": [],
+      "documentation_files": [
+        "README.md",
+        "profile/README.md",
+        "reflector/README.md"
+      ],
+      "documentation_quality": "good",
+      "exists": true,
+      "github_metadata": {
+        "issue_templates": [],
+        "workflows": []
+      },
+      "metrics": {
+        "documentation_count": 3,
+        "file_count": 10,
+        "manifest_count": 0
+      },
+      "name": ".github",
+      "notable_questions": [
+        "Are project manifests intentionally absent for this repository type?"
+      ],
+      "notable_strengths": [
+        "Documentation entry points are present"
+      ],
+      "path": ".",
+      "primary_concepts": [
+        ".github",
+        "profile",
+        "reflector"
+      ],
+      "project_manifests": [],
+      "purpose": "Organization profile, standards, and shared defaults",
+      "safe_name": ".github"
+    }
+  ]
+}

.github/audits/2026-06-26T024532Z/organization.audit.md

@@ -0,0 +1,9 @@
+# Organization Audit
+
+- Organization: egohygiene
+- Policy: documentation
+- UTC Timestamp: 2026-06-26T02:45:32.706370+00:00
+- Local Timestamp: 2026-06-26T02:45:32.706374+00:00
+
+## Repositories
+- .github: docs=good, tech=none

.github/audits/2026-06-26T024532Z/repositories/.github.audit.json

@@ -0,0 +1,39 @@
+{
+  "architectural_observations": [
+    "Repository appears to be organized with top-level directories: .github, profile, reflector",
+    "Discovery pass is read-only and did not modify repository content"
+  ],
+  "detected_technologies": [],
+  "documentation_files": [
+    "README.md",
+    "profile/README.md",
+    "reflector/README.md"
+  ],
+  "documentation_quality": "good",
+  "exists": true,
+  "github_metadata": {
+    "issue_templates": [],
+    "workflows": []
+  },
+  "metrics": {
+    "documentation_count": 3,
+    "file_count": 10,
+    "manifest_count": 0
+  },
+  "name": ".github",
+  "notable_questions": [
+    "Are project manifests intentionally absent for this repository type?"
+  ],
+  "notable_strengths": [
+    "Documentation entry points are present"
+  ],
+  "path": ".",
+  "primary_concepts": [
+    ".github",
+    "profile",
+    "reflector"
+  ],
+  "project_manifests": [],
+  "purpose": "Organization profile, standards, and shared defaults",
+  "safe_name": ".github"
+}

.github/audits/2026-06-26T024532Z/repositories/.github.audit.md

@@ -0,0 +1,21 @@
+# Repository Audit: .github
+
+- Purpose: Organization profile, standards, and shared defaults
+- Path: .
+- Documentation Quality: good
+- Detected Technologies: none
+
+## Primary Concepts
+- .github
+- profile
+- reflector
+
+## Architectural Observations
+- Repository appears to be organized with top-level directories: .github, profile, reflector
+- Discovery pass is read-only and did not modify repository content
+
+## Notable Strengths
+- Documentation entry points are present
+
+## Notable Questions
+- Are project manifests intentionally absent for this repository type?

.gitignore

@@ -0,0 +1,2 @@
+__pycache__/
+*.pyc

reflector/README.md

@@ -0,0 +1,19 @@
+# Reflector
+
+Pass-based organization analysis scaffold.
+
+## Layout
+
+- `engines/audit/` — audit engine entrypoint
+- `passes/00_discovery/` — read-only organization discovery pass
+- `policies/` — reusable audit policies
+- `specs/organization.spec` — organization source-of-truth specification
+- `outputs/` — reserved for future derived outputs
+
+## Run
+
+```bash
+python reflector/engines/audit/engine.py
+```
+
+This writes timestamped artifacts to `.github/audits/<UTC timestamp>/`.

reflector/engines/audit/engine.py

@@ -0,0 +1,118 @@
+from __future__ import annotations
+
+import argparse
+import json
+from datetime import datetime, timezone
+from importlib.util import module_from_spec, spec_from_file_location
+from pathlib import Path
+from typing import Any
+
+
+
+def _load_json(path: Path) -> dict[str, Any]:
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+
+def _load_discovery_module(root_dir: Path):
+    pass_path = root_dir / "reflector" / "passes" / "00_discovery" / "discovery.py"
+    spec = spec_from_file_location("reflector_discovery_pass", pass_path)
+    if spec is None or spec.loader is None:
+        raise RuntimeError("Unable to load discovery pass")
+    module = module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+
+def _write(path: Path, content: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content, encoding="utf-8")
+
+
+
+def _organization_markdown(payload: dict[str, Any]) -> str:
+    metadata = payload["metadata"]
+    lines = [
+        "# Organization Audit",
+        "",
+        f"- Organization: {payload['organization']['name']}",
+        f"- Policy: {payload['policy']['name']}",
+        f"- UTC Timestamp: {metadata['timestamp_utc']}",
+        f"- Local Timestamp: {metadata['timestamp_local']}",
+        "",
+        "## Repositories",
+    ]
+
+    for repo in payload["repositories"]:
+        lines.append(f"- {repo['name']}: docs={repo.get('documentation_quality', 'unknown')}, tech={', '.join(repo.get('detected_technologies', [])) or 'none'}")
+
+    return "\n".join(lines) + "\n"
+
+
+
+def run(spec_path: Path) -> Path:
+    root_dir = Path.cwd()
+    spec = _load_json(spec_path)
+    policy_name = spec["enabled_policies"][0]
+    policy_path = root_dir / "reflector" / "policies" / f"{policy_name}.policy.json"
+    policy = _load_json(policy_path)
+
+    now_utc = datetime.now(timezone.utc)
+    now_local = datetime.now().astimezone()
+    timestamp_folder = now_utc.strftime("%Y-%m-%dT%H%M%SZ")
+
+    output_root = root_dir / spec["audit"]["output_root"] / timestamp_folder
+    repositories_dir = output_root / "repositories"
+    repositories_dir.mkdir(parents=True, exist_ok=True)
+
+    discovery = _load_discovery_module(root_dir)
+
+    repository_audits: list[dict[str, Any]] = []
+    for repository in spec.get("repositories", []):
+        audit = discovery.run(repository, root_dir)
+        repository_audits.append(audit)
+
+        safe_name = audit.get("safe_name", audit["name"]) or "repository"
+        _write(repositories_dir / f"{safe_name}.audit.md", discovery.markdown_report(audit))
+        _write(repositories_dir / f"{safe_name}.audit.json", discovery.json_report(audit))
+
+    organization_payload = {
+        "metadata": {
+            "engine": spec["audit"]["engine"],
+            "version": spec["audit"]["version"],
+            "timestamp_utc": now_utc.isoformat(),
+            "timestamp_local": now_local.isoformat(),
+            "output_directory": str(output_root.relative_to(root_dir)),
+            "passes": spec["audit"].get("passes", []),
+            "read_only": True,
+        },
+        "organization": spec["organization"],
+        "policy": policy,
+        "repositories": repository_audits,
+    }
+
+    _write(output_root / "organization.audit.json", json.dumps(organization_payload, indent=2, sort_keys=True) + "\n")
+    _write(output_root / "organization.audit.md", _organization_markdown(organization_payload))
+
+    return output_root
+
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Run Reflector organization audit")
+    parser.add_argument(
+        "--spec",
+        default="reflector/specs/organization.spec",
+        help="Path to organization specification",
+    )
+    args = parser.parse_args()
+
+    output_path = run(Path(args.spec))
+    print(f"audit generated: {output_path}")
+    return 0
+
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())