3squaredcircles/vestigo repository overview

Visit https://docs.3squaredcircles.com⁠ for a deep dive into configuration.

Quick start: mount the directory of your .git directory to /app/work . Add interactive as a command arg. To read complete documentation run command arg serve-docs then you can go to localhost:{your mapped port}, docs will be served as html page.

Feedback welcomed at https://www.linkedin.com/company/3-squared-circles/⁠

⁠3SC Vestigo

The Early Warning System for Your Software Projects.

3SC Vestigo is a powerful analytics engine that moves beyond traditional code quality metrics to provide a forward-looking assessment of project risk. It analyzes your Git history to identify areas of high churn, low knowledge distribution ("bus factor"), and high co-change correlation, and combines these factors into a single, quantifiable Risk Score.

This tool is not just a linter; it's a project management radar. It identifies the hidden "hotspots" in your codebase; the fragile, complex modules that are most likely to be the source of future bugs, incidents, and project delays.

⁠A Note on the Name

Vestigo is a Latin verb meaning "to track," "to trace," or "to investigate." This name was chosen because the tool acts as a forensic investigator for your project, tracing the "footprints" left behind in your Git history: churn, coupling, and knowledge concentration to find the hidden risks and predict future problem areas.

---

⁠For the Manager & Executive

As a leader, you are constantly balancing the push for new features with the need for stability and predictability. You often have to make high-stakes decisions about resource allocation and project timelines based on incomplete or subjective information. Vestigo replaces guesswork with data.

Vestigo answers your critical questions:

• "Which parts of our codebase are the biggest liabilities that we're not talking about?"
• "Are we allocating our senior engineering talent to the areas of highest risk, or are we wasting them on low-impact work?"
• "Can we get an early warning if a critical part of our system is becoming fragile or dependent on a single developer?"
• "What is the quantifiable ROI of a proposed refactoring effort before we invest a single engineering hour?"

⁠Key Business Values:

• Data-Driven Resource Allocation: The Risk Cockpit's dashboard provides a ranked "Top Hotspots" list, showing you exactly where the risk is concentrated in your codebase. This allows you to proactively assign your best engineers to stabilize these critical areas before they cause a production incident.
• Predict and Prevent Project Delays: High-risk modules are a leading indicator of future bugs and missed deadlines. By monitoring risk trends, you can get an early warning that a key part of your application is becoming unstable, allowing you to intervene before it impacts a release.
• Justify and Measure Refactoring ROI: The Simulator allows architects to model a refactoring plan and see a concrete calculation of the projected risk reduction. This transforms a subjective "we should clean this up" conversation into a data-backed business case.
• Improve Project Predictability: By making technical debt and project risk visible and quantifiable, the tool provides a new layer of data for more accurate project estimation and timeline forecasting.

---

⁠For the Architect & Team Lead

As a technical leader, you are responsible for the long-term health and strategic direction of the codebase. You need tools that allow you to not only analyze the current state but also to simulate and plan future architectural changes. The Risk Cockpit, Vestigo's interactive UI, is a powerful workbench designed for exactly this purpose.

The Risk Cockpit is your architectural sandbox.

⁠Key Technical Values & Features:

• Deep-Dive with the Impact Assessor: Select any module from the dashboard to launch the Impact Assessor. This screen provides a rich, multi-faceted view of a specific architectural hotspot, including its dependency graph, historical trends, and file-level details.
• Simulate Refactoring: The "Re-Architect" workbench allows you to virtually refactor a module by adding, deleting, and moving files and sub-modules via drag-and-drop. The Risk Score updates in real-time, giving you immediate feedback on whether your proposed changes are actually reducing complexity and risk.
• Integrate with Scrutari: The simulator can overlay data from 3SC Scrutari. You can drag and drop components directly from the Scrutari tree into your simulation, allowing you to model changes like moving a specific class from one project to another.
• Create and Export Auditable Plans: Save your virtual refactoring as a JSON plan. This artifact can be checked into source control to document and communicate your design intent.

---

⁠For the Platform Engineer (DevOps, SRE)

As an operator, you are responsible for integrating automated quality and governance gates into the CI/CD pipeline. Vestigo provides a quantifiable risk score that can be used to make automated decisions.

⁠Execution Modes:

• execute The headless mode for your pipeline. It analyzes the Git history, calculates risk scores, and compares them against thresholds to return a Pass (0), Alert (70), or Fail (71) exit code. (License Required for CI/CD runs)
• interactive: Starts the "Risk Cockpit," a local web server that serves the interactive UI for deep analysis and simulation.
• serve-docs: Starts a lightweight server to display embedded tool documentation.

⁠Verifying Image Signatures

All published images are signed with Cosign. To verify:

1. Install cosign: https://docs.sigstore.dev/cosign/system_config/installation/⁠
2. Download our public key: curl -O https://www.3squaredsquaredcircles.com/keys/3squaredcircles.pub
3. Verify: cosign verify --key 3squaredcircles.pub 3squaredcircles/vestigo:latest

⁠The Risk Cockpit Dashboard