Maintain authoritative project state across AI agent sessions

Project State Governor maintains a project's durable, evidence-backed state so that a competent agent entering a fresh conversation can quickly tell why the project exists, what is authoritative now, what is active, blocked, deferred or done, what failed and should not be repeated, which decisions and constraints govern future work, and what should happen next. It is a community skill from Ghost011118/project-state-governor under the Apache-2.0 license. The agent acts as the project-state and documentation governor, not as the product owner, coding agent, research executor or release approver. The model is that Git preserves history, a canonical project-state system preserves current durable knowledge, AGENTS.md defines how agents operate, and conversation history is working context, never authoritative memory. A single source of truth means one canonical system, not necessarily one giant file.

Authority hierarchy. No owner or product decision may override applicable law, real authorization boundaries, non-waivable security or safety constraints, or objective facts. Within the owner's authority the default order is: the current explicit owner decision, current approved requirements and acceptance criteria, formal contracts, schemas, APIs and risk controls, tests traceable to requirements, current verified implementation behavior, current canonical state records, historical documentation, historical review reports, and finally historical AI conversation or speculation. Lower-authority evidence never silently overrides higher. Code shows current behavior, not intended behavior; reviewer findings are hypotheses until verified; and only the smallest unresolved owner decision is escalated.

State modes. Compact mode uses AGENTS.md plus PROJECT_STATE.md, with sections for mission, success criteria, phase, workstreams, milestones, tasks, research, decisions, constraints, blockers, deferred work, negative evidence and lessons. Scaled mode, for large projects, uses .project/ with MANIFEST.md (a short routing index), STATE.md, DECISIONS.md, CONSTRAINTS.md, NEGATIVE_EVIDENCE.md and areas/ files for independent subsystems. Splitting must improve retrieval, facts are not duplicated across files, and progress, roadmap, TODOs and review conclusions are not scattered across ad hoc files. Independent technical documents such as README, API specs, architecture, security policies and runbooks may stay separate.

Intent types. Every persisted item is classified: MISSION, SUCCESS_CRITERION (never invented just to make a mission measurable), WORKSTREAM, MILESTONE, TASK, RESEARCH_HYPOTHESIS (a failed hypothesis does not fail the mission), DECISION, CONSTRAINT, BLOCKER, DEFERRED, QUESTION (only if unresolved status affects future work) or LESSON. Completion is hierarchical: session, task, milestone, workstream and mission each have their own definition of done, and a child finishing never implies its parent finished.

Recall. When repository access exists, read the root AGENTS.md, resolve the full AGENTS.md scope of each candidate path (including nested files for recursive operations), detect compact or scaled mode, read the manifest and current state first, check the Git branch and working tree, inspect recent commits, code, tests and contracts as needed, and load only task-relevant files. Missing state is reconstructed from repository evidence, not from conversation alone.

Provenance and confidence. Durable facts that matter carry concise provenance (an owner decision or issue ID, a commit SHA, a test result, a schema path, an experiment ID) and labels of CONFIRMED, INFERRED or UNKNOWN. Inference is never persisted as settled fact.

Semantic State Diff. After meaningful work, the question is whether a durable fact was created, removed, invalidated, completed, clarified or materially modified. Only then is anything written; conversations, file inspection, command runs, debugging theories, AI suggestions, unverified reviewer concerns and wording changes never justify a write. Conversations become semantic results, not transcripts.

Lifecycle. The flow is RECALL, PROPOSE, VERIFY, APPLY, CONSOLIDATE, expressed as old state plus verified new facts minus invalidated facts equals new state. Low-risk, deterministic, evidence-backed, reversible updates within authorized scope can be applied. Owner review is required before redefining the mission or success criteria, choosing between legitimate business outcomes, deleting documentation of uncertain value, mass cleanup beyond authorized scope, turning an inference into an owner commitment, or accepting release, research, security, legal or operational risk. Default status vocabularies exist for tasks (PROPOSED, ACTIVE, BLOCKED, DONE, CANCELLED, DEFERRED), research hypotheses (including SUPPORTED, REJECTED, INCONCLUSIVE, INVALIDATED, FORWARD_ONLY) and workstreams (PLANNED, ACTIVE, BLOCKED, COMPLETED, PAUSED, CANCELLED).

Repository reconstruction has its own workflow. Scope and authority come first, including each candidate path's full instruction chain, and then every document is classified as AUTHORITATIVE, CURRENT_SUPPORTING, HISTORICAL, DUPLICATE, STALE, CONTRADICTORY, GENERATED_TEMPORARY or UNKNOWN. Only material claims are extracted (mission, completion claims, active work, decisions, blockers, research state, rejected directions and branch assumptions) and each is classed as CURRENT_CONFIRMED, CURRENT_INFERRED, SUPERSEDED, FALSE, CONFLICTED or UNKNOWN. Conflicts are typed: OBSOLETE_HISTORY (keep only current state), IMPLEMENTATION_DRIFT (decide which side violates higher authority), UNRESOLVED_BUSINESS_CONFLICT (escalate the smallest owner decision), FALSE_OR_UNSUPPORTED_HISTORY (never preserve as truth) and BRANCH_DIVERGENCE (keep branches distinct until merged). A staged cleanup set assigns each old document KEEP, MERGE_THEN_DELETE, DELETE or OWNER_DECISION, and deletion never comes before reconciliation. Verification checks internal consistency, that active tasks are really open, that completion claims match the right level, that decisions, constraints and negative evidence survived, that stale status documents no longer compete as sources of truth, and that no secrets were copied. Scaled mode is considered when agents must read large irrelevant sections, decisions outgrow active state, unrelated streams compete for context, or the file is hard to scan or safely edit, never by line count alone. The manifest is a stable map, STATE.md is the cold-start brief, each routed file states what question it answers, and routes are removed when files are merged. Compact state also keeps terminal tasks and workstreams long enough to preserve their verified transition and compresses them into milestone history later, with Git as the historical archive.

Use it when resuming a substantial project after conversation, agent or branch changes, when plans, status files, reviews, tests and implementation evidence disagree, when a completion claim must be verified before becoming durable state, when expensive negative evidence or a recurring lesson should survive future sessions, or when fragmented documentation needs bounded consolidation. A repository reconstruction mode handles cleanup of conflicting reviews, plans and status notes by classifying documents, resolving historical conflicts and staging cleanup without losing unique information.

Do not use it as a substitute for implementation, domain research, product ownership or release approval. It cannot decide undefined business intent, unsupported conclusions stay UNKNOWN, and it does not replace engineering, security or domain verification workflows. Broad cleanup or deletion is staged and reviewed before application. It never persists secrets, authentication material or unnecessary sensitive personal data, keeps branch-local state branch-local until merged, and treats engineering and research governors' verified outputs as evidence.

A worked example: a branch claims export-redesign is complete, but the canonical state marks it ACTIVE and its definition of done requires targeted tests and an integration test. The governor verifies the merge and the passing targeted tests, records that the integration test has not run as an evidence gap rather than inferring success, and preserves ACTIVE. The durable result is a minimal delta:

Status: ACTIVE (unchanged)
Verified: implementation merged; targeted tests passed
Missing evidence: required integration test
Next step: run and evaluate the integration test

Only after that test satisfies the approved definition of done may the task move to DONE. Completion claims are accepted only after identifying the right level of done, the authoritative acceptance criteria and appropriate build, test or integration evidence, with dependencies resolved. Final reports contain only project state changes, current focus, remaining blockers or decisions, documentation actions and evidence notes, and say so briefly when no durable state changed.

Anti-patterns to avoid include dumping conversations into docs, creating a new status file after every session, assuming code defines intent, trusting reviewer findings, keeping obsolete status files for reference when Git preserves them, deleting conflicting documents before extracting unique value, loading every memory file for every task, and treating cleanup as permission to rewrite unrelated code. The aim is minimum sufficient, high-confidence, continuously maintained knowledge, not maximum documentation.

It works with Git, AGENTS.md files and agent tools including Claude, Cursor, Gemini, Codex, Copilot and OpenCode.

It suits teams and solo developers who run agents across many sessions and branches and need one trustworthy, compact record of project state that resists drift and unsupported claims.