Inspiration
Providence began as a tool for my own scrambled, cross-connected way of working. My projects accumulate plans, decisions, abandoned paths, changed conditions, and new possibilities across files and conversations. I wanted one view that could show what I originally intended, what actually exists now, how the two relate, and what the available evidence still leaves open. If that can help me unscramble my own projects, perhaps it can also help larger teams where the left hand does not always know what the right hand is doing.
What it does
Providence is a Codex plugin that compiles repository and bounded Git evidence into one Project Context Map:
Past: Desires, plans, proposals, decisions, attempts, and blockers.
Present: Actual implementation, behavior, constraints, and verification.
Relationships and gaps: Differences, continuities, contradictions, missing evidence, and unresolved questions.
Future possibility space: Recorded possibilities, newly reopened paths, changed conditions, and stronger conceivable directions.
Providence presents evidence and possibility space without secretly deciding whether the project is aligned, whether a divergence is desirable, or what should happen next. A human or AI may add a separately labeled interpretation, but every interpretation claim must cite evidence returned by the map.
The supplied PulseStream demonstration recovers one legible thread: the project wanted progressive streaming; production still returns one atomic response; integrated ordering, cancellation, backpressure, and fallback proof is missing; and Transport v2 changed the capability boundary that caused the original deferral.
How we built it
I defined the decisive product model and corrected an early tendency to collapse the idea into a recommendation-shaped slice. GPT-5.6 in Codex carried that correction through the schema, historical scanner, deterministic compiler, evidence relationships, self-contained report, MCP tools, tests, release packages, and visual demonstration.
Providence captures before-and-after repository witnesses, scans current files and bounded Git history, recovers relevant rewritten or deleted evidence, assigns stable evidence IDs, constructs multi-witness relationships, and renders provenance-bound JSON and HTML. The Codex plugin exposes doctor, compile, and finalize tools.
Codex accelerated the build by tracing one semantic correction across every product surface, exposing historical evidence leaking into Present, finding compiler self-ingestion, repairing evidence navigation, challenging release archives, and repeatedly executing the full verification loop. At runtime, GPT-5.6 is an optional consumer above the deterministic map. In the demonstrated run it produced four separately labeled, citation-validated claims.
Challenges we ran into
The hardest problem was semantic fidelity. It is easy to make a tool that retrieves old text or generates a plausible summary. It is much harder to preserve the difference between recorded evidence, deterministic grouping, multi-witness relationships, missing evidence, and an intelligence's judgment.
Historical files initially leaked into Present, timestamps tempted false causal stories, generated reports could be re-ingested as source evidence, and relationship cards did not always open their witnesses. We repaired each boundary: current-state facets require current witnesses, reopened paths require Git ancestry, generated outputs are excluded, and every important placement, relationship, and interpretation opens an exact evidence anchor.
Accomplishments that we're proud of
- A complete, coherent Codex plugin experience rather than a mockup.
- The exact four-column map and all 19 canonical facets.
- A deterministic five-commit PulseStream repository that judges can run immediately.
- Two independent installed-plugin runs with the same 31 witnesses and 10 relationships.
- Zero unresolved evidence links and unchanged source through compile and finalize.
- Four citation-validated GPT-5.6 interpretation claims, visibly separate from the map.
- 53 automated tests and cross-artifact release verification.
- A results-first narrated film showing the context map, repeatable run receipt, exact witnesses, Codex and GPT-5.6 partnership, and Documentation Garden horizon.
What we learned
That with Providence the location, time, relationship, and epistemic status of evidence determine what an intelligence may honestly conclude from it. A compelling context product needs two scales at once: one representative thread that becomes legible in seconds, and the complete evidence map behind it so nothing important is hidden by the story.
What's next for Providence
The submitted implementation compiles evidence already present in a repository and Git history. A future Documentation Garden could continuously preserve richer events, decisions, authority changes, and cross-tool relationships as work happens. That would improve recall for weakly documented projects without changing Providence's central contract: present the Past, Present, Relationships and gaps, and Future possibility space so an intelligence can understand before it decides.
Log in or sign up for Devpost to join the conversation.