The governance and audit method I use to direct AI coding tools to build and operate real production software safely.
Portfolio exhibit. This is a sanitized public extract of a private system in daily use. The architecture and method are real; the data and identifiers are stand-ins, and the section below lists which is which.
With AI in the loop, code generation is the easy part; the discipline around it decides whether the result is safe to run against production. This repository documents that discipline. It has governed AI-assisted changes on a live production system I operate around the clock, for more than two months of continuous use.
The method lives in a plain Obsidian markdown vault and organizes work into two shapes: bounded efforts that open, run, and close, and standing domains that hold the invariants a system must never violate. Every material change is logged against its effort and domain with a link to the commit, a small set of actions is permanently off-limits to autonomous execution, and nothing is marked done until its acceptance criteria are actually exercised.
- Real: the method, and its two-plus months of continuous live use governing AI-assisted changes on a production system I operate around the clock.
- Sanitized: everything in this repository is a runnable sample. Every effort, domain, and log entry is invented (
refactor-config-loader,add-exchange-support,venue-beta,data-pipeline); no real work items, system internals, or operational specifics appear.
Live files from the sample-subsystem/ that ships here, excerpted.
| # | Title |
|---|---|
| 452 | 🔌 venue-beta connector against shared ingestion contract, UTC normalized at boundary |
| 451 | 🧱 Config loader onto versioned schema v2, legacy path preserved |
The audit index: every material change is a numbered, timestamped row generated from frontmatter, cross-linked to its effort, its domain, and its git commit. The full diff is one click away from any line.
# Refactor config loader
## Goal
Move the pipeline config loader onto an explicit, versioned schema so new venues
and stages can be added declaratively. Old config files must keep parsing.
## Acceptance
Written before the work; closure verifies against these.
- Schema v2 parses every existing config fixture without error.
- Old (unversioned) config files still parse through a backward-compat path.
- Loader rejects unknown top-level keys with a clear message.
## Tasks
### ✅ CFG-001 - introduce a `schema_version` field and a v2 parser
### ✅ CFG-002 - strict unknown-key rejection
### ▶️ CFG-003 - backward-compat path for legacy configs
### ❓ CFG-004 - migration helper to rewrite v1 files as v2 🚩An effort card: acceptance criteria written before the work, and a closure section filled only after the effort is verified against them.
Each decision below exists because the alternative failed in practice.
1. Two shapes for work. Efforts carry a Goal, an Acceptance section, tasks, and a Closure note, then they archive. Domains never close; they hold the rules a system must keep. A small recursive PARA structure under the outer knowledge base.
2. Acceptance is written before the work. Every non-trivial task carries validation criteria at creation, closing the most common failure of agentic work: marking something a success when the checks never ran.
3. Invariants gate new work. A soft overlap is flagged and proceeds; a hard conflict parks the work in a paused state with the violated rule cited inline and surfaced to a human. Invariants grow from real incidents.
4. Every change is logged. One LOG entry per material change: a UTC timestamp to the minute, cross-references to the effort, domain, and task, and a link to the commit. The body stays to a few sentences because the diff carries the detail.
5. A few actions are permanently off-limits to autonomy. Destructive operations, live-system mutations, and any change to monitoring or alerting always require a human. Acting first is allowed only when harm is imminent and the correct action is unambiguous.
6. Terminal states are honest. A seven-state task palette makes partial, failed, and killed visible and first-class.
| Glyph | State | Meaning |
|---|---|---|
| active | work in motion | |
| ✅ | verified | objective met, all validation exercised |
| ⏸️ | paused | transient block, will resume |
| ❓ | partial | shipped but incomplete, carry-forward stated |
| ❌ | failed | objective not achieved, accepted as a known limit |
| 🪦 | killed | explicit decision to abandon, with rationale |
| 🔁 | recurring | standing obligation, never terminal |
7. Closure is a sign-off. An effort closes after every task reaches a terminal state, an integration-level check runs when shared state was touched, goal and acceptance are reviewed against evidence with a human, and durable lessons are distilled into domain runbooks.
8. No finding disappears silently. An out-of-scope observation is flagged in the record, surfaced live, and re-surfaced at the next session start.
flowchart TB
subgraph WARM["Session warm-up (read before any work)"]
direction LR
C1[Subsystem card + rules]
C2[Strategic summary]
C3[Domains + invariants]
C4[Active efforts]
C5[Recent audit log]
end
REQ([Request from operator])
WARM --> REQ
REQ --> ROUTE{Scope of the request}
ROUTE -->|single concrete action| DIRECT[Direct path: plan one task]
ROUTE -->|strategic or multi-task| PLAN[Planning path: propose effort, tasks, acceptance]
DIRECT --> GATE
PLAN --> GATE
GATE{{Conflict check vs domain invariants}}
GATE -->|hard conflict| PAUSE[Pause work, surface violated invariant]
GATE -->|clear| LIMITS
LIMITS{{Hard-limit gate}}
LIMITS -->|destructive / live mutation / monitoring change| HUMAN[Human confirmation required]
LIMITS -->|within bounds| WORK
HUMAN --> WORK
WORK["Work the task<br/>validation written upfront"]
WORK --> LOG[("Per-change audit log<br/>UTC + cross-refs + git link")]
WORK --> FIND{Out-of-scope finding?}
FIND -->|yes| SAFETY["Flag in record + surface live<br/>+ re-surface next session"]
FIND -->|no| CLOSE
SAFETY --> CLOSE
LOG --> CLOSE
CLOSE["Closure ritual:<br/>terminal states, verify vs acceptance,<br/>distill lessons"]
CLOSE --> RUNBOOK[Domain runbooks and invariants grow]
RUNBOOK -.feeds next session.-> WARM
The actual tree of the sample. A subsystem carries more domains in real use; the sample instantiates one so the shape stays legible. A prose walkthrough lives in docs/pattern-overview.md.
sample-subsystem/ the demonstrated subsystem (a git repo root in real use)
├── CLAUDE.md subsystem-specific rules (auto-loaded at session start)
├── sample-subsystem.md the vault-facing card: the only surface the outer system reads
└── _dev/ the dev layer (private to the subsystem)
├── SUMMARY.md strategic state, kept short
├── LOG/ per-change audit trail (one entry per material change)
│ ├── LOG.md live index (Bases query over the entries)
│ ├── 0451-config-loader-schema-migration.md
│ └── 0452-add-venue-beta-connector.md
├── efforts/ bounded work that opens, runs, and closes
│ ├── efforts.md container index (soft cap: 4 active)
│ ├── refactor-config-loader/
│ └── add-exchange-support/
├── domains/ standing concerns that hold invariants
│ ├── domains.md container index
│ └── data-pipeline/
└── +inbox/ local capture, triaged later
Closed efforts and retired domains move to a dated _dev/_archive/ (empty here, since nothing has closed yet).
- Obsidian markdown vault: plain markdown files; greppable, diff-able, tool-independent.
- Folder-note convention: each container and each item folder carries its own note.
- Bases queries: render the LOG as a live, sortable audit index straight from frontmatter.
- Tasks plugin: recurrence math for standing obligations.
- Git: LOG entries cite commits, so the full diff sits one click from any audit line.
- An AI coding agent: the collaborator the method directs and constrains.
- Optional hooks in the live instance, such as a scheduled check that pings the operator when the audit log goes quiet for longer than expected; none ship in this sample.
- Acceptance upfront. A task is marked verified only when its criteria are actually exercised; otherwise it becomes partial, with the carry-forward stated in plain text.
- Status against evidence. Before closure reaches a human, the AI reconciles each task's status against its evidence and downgrades anything that does not hold; the human catches what the self-check missed.
- Integration verification. Substantial efforts get an end-to-end check across their deliverables before closing, beyond per-task validation.
- A replayable trail. Any change is reconstructable from the LOG plus git history, ordered to the minute, with the reasoning next to the diff.
- No multi-agent orchestration. One operator, one AI, one thread. No personas, no message bus.
- No packaged framework or CLI. A working method over markdown and git, framework-agnostic on purpose.
- No machine-enforced schema. The checking is cognitive and a human owns the boundary.
- No branch-per-task machinery. Single branch, one source of truth per task.
I work AI-first: I direct AI coding tools to do the mechanical build work, and this method is the frame that keeps that work auditable, honest about its own state, and safe to run against production.
PRODUCTION EXTRACT. A sanitized public cut of a private system in real use. The architecture and method are real; data, names and some components are stand-ins, and the README lists which is which.
This is one piece of a broader portfolio of production AI systems (agents, MCP servers, retrieval, and self-hosted platforms).
- Portfolio: github.com/janvrsinsky
- LinkedIn: linkedin.com/in/janvrsinsky
