Project Context Governor

Project Context Governor

Maintain useful project context without revalidating everything on every chat. Separate loading from verification, sample routine claims, and force checks only when risk or conflicting evidence requires them.

Principles

1. Prefer current code, Git state, tests, and runtime evidence over summaries or memories.
2. Use memory for navigation, never as proof.
3. Keep facts, interpretations, decisions, plans, and negative results distinct.
4. Supersede wrong records; never silently rewrite history or hide conflict.
5. Load context cheaply. Activation alone does not require verification.
6. Spend verification budget by risk, staleness, change impact, and reproducible sampling.
7. Respect scope. Status and review requests remain read-only unless state-file changes are authorized.

Select a workflow

• Bootstrap: Organize or onboard a repository. Reuse existing state systems before proposing new files.
• Orient: Resume substantial work. Load the smallest relevant context; normally do not verify it.
• Reconcile: After authorized meaningful changes, update only affected claims when context-file writes are in scope.
• Audit: Perform periodic, sampled, conflict-triggered, or requested validation.
• Repair context: Supersede a wrong claim and identify downstream claims needing review.

Bootstrap

1. Read applicable AGENTS.md plus existing architecture, status, plan, decision, and task artifacts.
2. Prefer configured code-graph tools for discovery. Index only when no usable index exists or audit policy selects refresh.
3. Reuse existing sources of truth. Do not create parallel documents.
4. If setup is authorized and no equivalent store exists, use .codex/project-context/ from references/state-schema.md.
5. Record the baseline revision and freshness. Do not claim a full audit unless one ran.

Orient cheaply

1. Load applicable instructions and compact current state.
2. State the last verified revision/date and known stale or disputed items.
3. Load only claims relevant to the requested outcome.
4. Apply references/audit-policy.md.
5. If no check is due, proceed and label material unverified assumptions.
6. If a check is due, verify only selected claims or affected areas unless a full audit is selected.

Reconcile

1. Capture outcome, affected scope, evidence, blockers, and next action.
2. Mark dependent claims stale when invalidation conditions match.
3. Never convert a chat assertion into confirmed fact.
4. Append superseding claim records instead of deleting contradicted history.
5. Keep AGENTS.md for durable rules, not progress.
6. If writes are not authorized, return a proposed state update.

Handle a context anomaly

When any material context conflict or suspected false premise appears:

1. Emit a CONTEXT_INTEGRITY_ALERT before continuing dependent development.
2. Quarantine the affected claim as DISPUTED or STALE; do not use it as a premise.
3. Find the earliest identifiable record, commit, diff, decision, or conversation that introduced the premise.
4. Review every directly dependent modification made since that point, including affected commits, files, tests, configuration, decisions, tasks, and derived claims.
5. Trace one additional dependency hop when a direct dependent changed public behavior, persisted state, authorization, deployment, or safety controls.
6. Bound the review to the dependency cone. Escalate to FULL only when the origin or blast radius cannot be bounded, multiple foundational claims conflict, or high-risk integrity is involved.
7. Separate context correction from business-code repair. Do not modify business code without authorization.
8. Preserve the original record and append a superseding correction with evidence.

Do not resume work that depends on a quarantined claim until it is confirmed, replaced, or the user explicitly accepts the uncertainty.

Verify and reflect

Run scripts/choose_verification.py for reproducible routine sampling. Seed decisions with project identity, revision, date bucket, risk, and policy version.

For selected claims ask:

1. Which assumptions support this claim?
2. What current evidence could disprove it?
3. Did relevant code, configuration, dependencies, or runtime state change?
4. Were plan, implementation, test, deployment, and authorization confused?
5. Do code, tests, docs, graph data, and runtime evidence conflict?
6. Would independent review reach the same conclusion without the stored summary?

Classify results as CONFIRMED, INFERRED, PROPOSED, DISPUTED, STALE, or INVALIDATED.

Detect changes and measure cost

Run scripts/detect_project_change.py before a polling audit. It hashes project content while excluding Git internals, generated caches, dependencies, and its own state file.

• On baseline-initialized or no-change, do not run a model audit.
• On project-status-change, run a focused orientation or audit according to the verification policy.
• Store only the detector state in .codex/project-context/watch-state.json; do not treat it as project evidence.
• Keep true event delivery separate from detection. A Codex scheduled task polls; a hook or watcher must invoke the detector for immediate delivery.

Run scripts/benchmark_context_cost.py to compare full-text orientation input with the compact governed context. Report file bytes and timings as measured values, token counts as estimates unless a model usage event was captured.

Boundaries

• Never edit business code merely to make memory correct.
• Never run broad tests or refresh expensive indexes only because the skill loaded.
• Never treat confidence as evidence.
• Never auto-edit governance, durable decisions, authorization, or promotion during unattended audits; propose changes for review.
• Prefer read-only scheduled audits and isolated worktrees when audits may produce changes.

Output

For routine use report: context source and freshness; verification decision and reason; current outcome; material stale/disputed items; and one next action.

For bootstrap, repair, or full audit also report evidence examined, claims superseded, residual uncertainty, and proposed state-file changes.

When an anomaly exists, report:

• CONTEXT_INTEGRITY_ALERT and severity: warning, high, or critical.
• Quarantined claim IDs and the conflicting evidence.
• Earliest known introduction point.
• Directly dependent modifications reviewed or still pending.
• Whether the blast radius is bounded.
• Safe next action and whether user authorization is required.