feat(reflector): bootstrap pass-based organization discovery audit engine - #7
Merged
szmyty merged 2 commits intoJun 26, 2026
Conversation
Copilot
AI
changed the title
[WIP] Add initial version of organization analysis engine
feat(reflector): bootstrap pass-based organization discovery audit engine
Jun 26, 2026
szmyty
marked this pull request as ready for review
June 26, 2026 04:37
szmyty
approved these changes
Jun 26, 2026
szmyty
deleted the
copilot/feat-reflector-bootstrap-organization-analysis-eng
branch
June 26, 2026 04:40
Pull Request Summary by devActivityMetrics
Achievements
|
There was a problem hiding this comment.
Pull request overview
This PR bootstraps a new “Reflector” audit subsystem that can run a discovery pass over an organization’s repository inventory and emit structured, timestamped audit artifacts under .github/audits/<UTC_TIMESTAMP>/.
Changes:
- Added a minimal audit engine entrypoint (
reflector/engines/audit/engine.py) that loads an organization spec + policy, runs discovery, and writes org/repo audit artifacts. - Added the initial discovery pass (
reflector/passes/00_discovery/discovery.py) to collect repo structure, docs/manifests, and GitHub metadata, with MD/JSON renderers. - Added policy/spec scaffolding plus a first committed sample output set under
.github/audits/2026-06-26T024532Z/.
Reviewed changes
Copilot reviewed 9 out of 10 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| reflector/specs/organization.spec | Defines organization metadata, repository inventory, enabled policies, and audit engine configuration. |
| reflector/README.md | Documents the Reflector layout and how to run the audit engine. |
| reflector/policies/documentation.policy.json | Introduces a reusable policy describing discovery goals and output configuration. |
| reflector/passes/00_discovery/discovery.py | Implements the read-only discovery pass and MD/JSON reporting for per-repo audits. |
| reflector/engines/audit/engine.py | Provides the audit engine bootstrap that loads spec/policy, runs the pass, and writes artifacts. |
| .gitignore | Adds basic Python bytecode/cache ignores. |
| .github/audits/2026-06-26T024532Z/repositories/.github.audit.md | Sample generated per-repository Markdown artifact. |
| .github/audits/2026-06-26T024532Z/repositories/.github.audit.json | Sample generated per-repository JSON artifact. |
| .github/audits/2026-06-26T024532Z/organization.audit.md | Sample generated organization-level Markdown artifact. |
| .github/audits/2026-06-26T024532Z/organization.audit.json | Sample generated organization-level JSON artifact. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+95
to
+105
| repo_name = repository["name"] | ||
| repo_path = (root_dir / repository["path"]).resolve() | ||
|
|
||
| if not repo_path.exists(): | ||
| return { | ||
| "name": repo_name, | ||
| "path": repository["path"], | ||
| "purpose": repository.get("purpose", ""), | ||
| "exists": False, | ||
| "error": "Repository path does not exist", | ||
| } |
Comment on lines
+26
to
+33
| def _find_files(repo_path: Path) -> list[Path]: | ||
| files: list[Path] = [] | ||
| for path in repo_path.rglob("*"): | ||
| if ".git" in path.parts: | ||
| continue | ||
| if path.is_file(): | ||
| files.append(path) | ||
| return files |
Comment on lines
+55
to
+60
| 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) | ||
|
|
Comment on lines
+69
to
+79
| 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)) | ||
|
|
Comment on lines
+95
to
+96
| _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)) |
6 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This PR introduces the first Reflector foundation for organization-wide analysis: a compiler-style, pass-based audit engine driven by reusable policy and specification inputs. Scope is intentionally limited to read-only organization discovery and structured artifact generation for downstream passes.
Engine bootstrap
reflector/engines/audit/engine.pyas the audit entrypoint.organization.spec, resolves enabled policy, executes discovery pass(es), and writes timestamped artifacts under.github/audits/<UTC_TIMESTAMP>/.organization.audit.md/json) and per-repository outputs (repositories/<repo>.audit.md/json).Pass architecture:
00_discoveryreflector/passes/00_discovery/discovery.pyas a standalone read-only discovery pass.Policy system
reflector/policies/documentation.policy.json.Organization source of truth
reflector/specs/organization.specfor organization metadata, repository inventory, audit configuration, enabled policies, and extension points for future passes/policy overrides.Initial generated artifacts
.github/audits/2026-06-26T024532Z/to establish artifact format and directory contract.