Terminal Zero Governance Control Plane
quant_current_scope is a local, script-driven AI engineering control plane.
Its job is simple:
- turn vague AI work into explicit, checkable work,
- run that work inside a bounded process,
- and leave behind evidence that another human or agent can trust.
This is not a hosted agent platform or consumer app. It is a repo-native governance system for running AI-assisted engineering work with explicit boundaries, closure, and handoff.
Release Status
- Current release: targeting 1.0
- This repository is the shipped product boundary for the control-plane surface.
- Root
SOP/docs remain canonical kernel/program/history docs for maintainers.
1.0 Release Boundary
Shipped:
sopCLI and subcommands (startup,run,validate,takeover,supervise,init)- Kernel templates for truth surfaces
- Startup → run → validate → takeover loop
- PyPI install path (
pip install terminal-zero-governance)
Supported platforms:
- Python 3.12+
- Windows, Linux
Not promised (future work):
- Hosted service
- npm/npx scaffolding
- GitHub Action
- VS Code extension
- Zero-human autopilot
What Problem This System Solves
Most AI engineering systems fail for one of six top-level reasons:
- the task is unclear,
- the authority boundary is unclear,
- execution happens in chat instead of in artifacts,
- “done” is asserted without verification,
- handoff is weak,
- or nobody can explain what happened afterward.
This repository solves those problems in a fixed order.
P0 to P5
Read this as a top-down PM map. Each level answers one question:
P0: what is allowed?P1: what exactly are we trying to do?P2: what is happening now?P3: is it actually ready?P4: what does the next person need?P5: what do we keep as long-term truth?
P0. Governance Boundary
Problem Category
- uncontrolled AI execution
Problem
- AI work is dangerous when nobody knows the goal, risk, owner, non-goals, or approval threshold.
Solution
- force every round to start inside an explicit execution boundary.
Concrete Layers
- entrypoint:
scripts/startup_codex_helper.py
- core artifacts:
docs/context/startup_intake_latest.jsondocs/context/startup_intake_latest.mddocs/context/init_execution_card_latest.mddocs/context/round_contract_seed_latest.md
What This Produces
- one explicit statement of intent
- one explicit risk lane
- one explicit done-when contract
PM Handoff
- check whether the round is solving the right problem
- check whether the declared risk lane matches the real business risk
- stop the round here if the goal, owner, or boundary is wrong
P1. Planning Truth
Problem Category
- vague work and drifting requirements
Problem
- AI systems often start coding before the task is decomposed into something reviewable.
Solution
- convert top-level intent into structured, inspectable planning truth.
Concrete Layers
- startup interrogation captures:
- scope
- non-goals
- interfaces
- owned files
- closure checks
- authoritative docs:
top_level_PM.mddocs/decision log.mddocs/loop_operating_contract.md
What This Produces
- a round starts from declared constraints instead of prompt residue
- planning truth is anchored to durable docs, not only the current chat
PM Handoff
- confirm the round is solving the correct business/system problem
- confirm what is intentionally out of scope
- decide whether the plan should proceed, narrow, or be reframed
P2. Execution Truth
Problem Category
- invisible work and context drift
Problem
- chat-only work is hard to resume, hard to audit, and easy to derail.
Solution
- run one bounded loop that refreshes working artifacts instead of hiding state in conversation history.
Concrete Layers
- entrypoint:
scripts/run_loop_cycle.py
- core artifacts:
docs/context/loop_cycle_summary_latest.jsondocs/context/loop_cycle_summary_latest.mddocs/context/exec_memory_packet_latest.jsondocs/context/exec_memory_packet_latest.md
What This Produces
- current execution state
- current advisory outputs
- current machine-readable memory for the next step
PM Handoff
- read this layer to understand what the system is actually doing now
- do not use it to redefine scope; use it to judge whether execution matches plan
- if execution drifts, redirect the round before closure
P3. Readiness Truth
Problem Category
- false completion
Problem
- AI systems can sound complete before the work is actually safe to escalate or ship.
Solution
- create an explicit readiness decision instead of relying on confidence or fluent narrative.
Concrete Layers
- entrypoint:
scripts/validate_loop_closure.py
- core artifacts:
docs/context/loop_closure_status_latest.jsondocs/context/loop_closure_status_latest.md
What This Produces
READY_TO_ESCALATE,NOT_READY, or infra/input failure- evidence tied back to current artifacts
PM Handoff
- this is the main “go / not yet” surface
- if
NOT_READY, the PM should ask what evidence is missing, not “why is the agent low confidence?” - if
READY_TO_ESCALATE, the PM still owns the decision to proceed
P4. Handoff Truth
Problem Category
- expensive restarts and weak continuity
Problem
- the next operator or agent often starts cold, redoes context gathering, or inherits unclear state.
Solution
- turn takeover into a deterministic readout instead of an oral tradition.
Concrete Layers
- entrypoint:
scripts/print_takeover_entrypoint.py
- core artifacts:
docs/context/next_round_handoff_latest.jsondocs/context/next_round_handoff_latest.md
- optional convenience mirrors:
- repo-root
*_LATEST.mdfiles when present
- repo-root
What This Produces
- a clean next-step view
- clear handoff artifacts
- lower restart cost for the next round
PM Handoff
- this is the minimum surface the next human should read before continuing
- if the handoff feels unclear, the system has not really closed the round
- use this layer to preserve continuity between planning, execution, and the next decision
P5. Evidence And Learning Truth
Problem Category
- no audit trail and repeated mistakes
Problem
- without evidence, you cannot audit the run; without learning, you repeat the same mistakes.
Solution
- preserve runtime evidence, optional supervision, and explicit lessons so the control plane improves over time.
Concrete Layers
- generated artifacts under
docs/context/ - optional supervision:
scripts/supervise_loop.py
- long-lived truth records:
docs/lessonss.mddocs/decision log.mddocs/ARTIFACT_POLICY.md
What This Produces
- traceable runs
- explicit mistakes and guardrails
- an improving control plane instead of one-off sessions
PM Handoff
- review this layer to improve the system, not to micromanage one round
- convert repeated misses into clearer guardrails
- use this layer to reduce human friction over time, especially for non-technical operators
In One Line
P0 defines the boundary.
P1 defines the work.
P2 shows what is happening.
P3 decides readiness.
P4 makes the next step legible.
P5 keeps evidence and learning alive.
PM View
If you are a non-technical PM or operator, you can read the system in this order:
P0— is this round allowed and correctly bounded?P1— are we solving the right problem?P3— is the work actually ready?P4— what should happen next?P5— what should we change in the system itself?
You usually do not need to inspect low-level scripts or generated machine artifacts unless something looks wrong.
Optimization Direction
The current direction for this control plane is:
- build on top of the existing kernel,
- do not do a large refactor unless the same truth is duplicated and conflicting,
- make the orchestrator more state-aware through better artifacts, not more prompt text,
- and reduce human effort to the smallest set of decisions that still preserve product truth.
In plain terms:
- the human should mostly guard the spec,
- judge boundary or priority changes,
- and watch system drift.
The human should not need to micromanage implementation steps if the control plane is doing its job.
What We Are Optimizing For
As systems grow, like Eureka and Quant, failure usually comes from one of these places:
- planning truth, execution truth, and PM/product truth drift apart,
- frontend/backend/data/ops become separate local loops instead of one system,
- approval becomes a slot machine around confidence rather than a decision about evidence and direction,
- technical optimization outruns product or PM feedback,
- status surfaces multiply until nobody knows which one matters,
- or the planner rereads too much of the repo and still misses the current bottleneck.
The optimization goal is therefore:
- minimal human friction,
- maximal state clarity,
- bounded execution,
- explicit planner bridge,
- and less guidance over time, not more.
Build-On-Top Principle
The default strategy is additive, not destructive.
Use this rule:
- keep the existing
startup -> loop -> closure -> takeoverkernel, - add thin integration artifacts on top,
- only refactor a subsystem after repeated evidence shows that the additive layer cannot resolve the conflict.
This follows Ockham's razor:
- if a thin bridge solves the problem, do not invent a new subsystem,
- if a small contract solves the drift, do not rebuild the workflow,
- if a simple artifact can make the system legible, do not add more prompts.
Human Role
The target human role is:
- guard the spec,
- approve changes to direction, scope, or boundary,
- decide priorities and tradeoffs,
- and observe overall system health.
The target human role is not:
- line-by-line code supervisor,
- manual status compiler,
- prompt babysitter,
- or the only entity that keeps documents honest.
See ../ENDGAME.md for the full endgame philosophy and target state.
Truth Model
The system stays coherent through four truth layers:
- Static Truth — long-lived intent and constraints
- Live Truth — what is active now
- Bridge Truth — what recent execution means for product/system and planner
- Evidence Truth — what actually happened and what proves it
The system becomes reliable when these layers stay thin, distinct, and connected.
See ../ENDGAME.md for detailed truth model, orchestrator state model, planner fresh-context model, and multi-stream coordination model.
Roadmap
See ../ROADMAP.md for the full delivery plan.
Current status: All roadmap waves (W0–W6) complete (2026-03-19). See ../ROADMAP.md for details.
What This Repository Is
This repository is primarily for:
- operators running the governance loop locally,
- engineers maintaining the loop scripts and artifact contracts,
- reviewers who need auditable startup, closure, and handoff outputs.
What This Repository Is Not
This repository is not:
- a hosted autonomous agent platform,
- a consumer chat product,
- a plugin marketplace,
- a zero-human autopilot,
- or a second authority plane outside the documented control flow.
Start Here
- Public/project orientation: this README
- Operational endgame:
../ENDGAME.md - Delivery roadmap:
../ROADMAP.md - Local operator flow:
OPERATOR_LOOP_GUIDE.md - Internal procedures:
docs/loop_operating_contract.md,docs/runbook_ops.md,docs/operator_reference.md
Entrypoints
Primary (sop CLI)
sop startup --repo-root . # Initialize a round
sop run --repo-root . # Execute one loop cycle
sop validate --repo-root . # Check closure readiness
sop takeover --repo-root . # Print takeover guidance
sop supervise --max-cycles 1 # Loop health monitoring
sop init <target-dir> # Bootstrap new governed repo
Install: pip install terminal-zero-governance
Compatibility (scripts)
For existing workflows or local development:
python scripts/startup_codex_helper.py --repo-root .
python scripts/run_loop_cycle.py --repo-root .
python scripts/validate_loop_closure.py --repo-root .
python scripts/print_takeover_entrypoint.py --repo-root .
python scripts/supervise_loop.py --repo-root .
These are preserved for backward compatibility. New users should prefer sop.
Quickstart
1. Install
pip install terminal-zero-governance
Or from source:
python -m venv .venv
.\.venv\Scripts\Activate.ps1 # Windows
pip install -e .
2. Verify
sop --help
sop version
3. Initialize a new governed repository
sop init my-project
cd my-project
4. Run the main loop
sop startup --repo-root .
sop run --repo-root . --skip-phase-end
sop validate --repo-root .
sop takeover --repo-root .
5. Optional supervision
sop supervise --max-cycles 1
6. Run tests (from source)
python -m pytest -q
New user? See USER_GUIDE.md for a complete walkthrough.
Platform Assumptions
- Python
3.12+ - Windows PowerShell examples by default
- repo-local
.venvpreferred - canonical dependency metadata in
pyproject.toml - pinned installs via
constraints.txtandconstraints-dev.txt
Repository Layout
scripts/— orchestration, validation, reporting, and takeover entrypointsdocs/— contracts, runbooks, policy docs, and planning docsdocs/context/— generated machine/human artifacts exchanged between loop stagestests/— control-plane and script coverage.github/workflows/— CI workflows
Documentation Routing
New Users (Start Here)
USER_GUIDE.md— complete walkthrough for new users
Public / External
README.md(this file)USER_GUIDE.mdCHANGELOG.mdRELEASING.mdCONTRIBUTING.mdSUPPORT.mdCODE_OF_CONDUCT.mdGOVERNANCE.mdSECURITY.md
Internal Operator
OPERATOR_LOOP_GUIDE.mddocs/runbook_ops.mddocs/operator_reference.mddocs/loop_operating_contract.mddocs/security.mddocs/ARTIFACT_POLICY.mddocs/context/workflow_status_latest.{json,md}when present
License
MIT. See LICENSE.
Metadata
Release files for terminal-zero-governance 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| terminal_zero_governance-0.1.0.tar.gz | 324.1 kB | With provenance | Details for terminal_zero_governance-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| terminal_zero_governance-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for terminal_zero_governance-0.1.0-py3-none-any.whl |
Total release size: 578.3 kB
Release files / terminal_zero_governance-0.1.0.tar.gz
| Download URL | terminal_zero_governance-0.1.0.tar.gz |
|---|---|
| Size | 324.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
51064962b077279fdea52eeb1e5d5112dce2f1673ac5bb37fbdd30360cd05474
|
|
BLAKE2b-256 checksum How to use checksums |
5fa4d7cdcb01ac694da35112078b75a61755151bbfbb7e73fda7c214446a3515
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Mar 20, 2026.
Transparency logRelease files / terminal_zero_governance-0.1.0-py3-none-any.whl
| Download URL | terminal_zero_governance-0.1.0-py3-none-any.whl |
|---|---|
| Size | 254.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
cb5c69ff8ab65afec699d81555a0eb97ac523b4091465cb579677bbed1bd365f
|
|
BLAKE2b-256 checksum How to use checksums |
c344c14dac27583b561057948a65aa30f627496a702804c5fa973477be8065ab
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Mar 20, 2026.
Transparency logSecurity for terminal-zero-governance 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for terminal_zero_governance-0.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Mar 20, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.