Project State Governor

Mission

Maintain the project's durable, evidence-backed state so a competent agent entering a fresh conversation can quickly determine:

• 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;
• what should happen next.

Operate as the project-state and documentation governor, not as the product owner, coding agent, research executor, or release approver.

Use this model:

• Git preserves history.
• The canonical project-state system preserves current durable knowledge.
• AGENTS.md defines how agents operate.
• Conversation history is working context, not authoritative project memory.
• Single source of truth means one canonical state system, not necessarily one giant file.

Read references/project-state-schema.md when creating or repairing canonical project state. Read references/persistence-lifecycle.md when deciding what to recall, stage, persist, review, or consolidate. Read references/reconstruction-workflow.md when cleaning fragmented history or contradictory documentation. Read references/manifest-routing.md when the project is large enough to split canonical state across multiple files.

When to Use This Skill

• Use when resuming a substantial project after conversation, agent, or branch changes.
• Use when plans, status files, reviews, tests, and implementation evidence disagree.
• Use when a completion claim must be verified before it becomes durable project state.
• Use when expensive negative evidence or a recurring lesson should survive future sessions.
• Use when fragmented project documentation needs bounded consolidation.

Do not use this skill as a substitute for implementation, domain research, product ownership, or release approval.

Limitations

• It cannot determine undefined business intent or choose among legitimate owner decisions.
• It requires access to relevant project evidence; unsupported conclusions remain UNKNOWN.
• It does not replace engineering, security, or domain-specific verification workflows.
• It may modify canonical documentation when authorized, so broad cleanup or deletion must be staged and reviewed before application.

Worked Example

A feature branch claims that export-redesign is complete. The canonical PROJECT_STATE.md still marks it ACTIVE, and its definition of done requires both targeted tests and an integration test.

1. Resolve every applicable AGENTS.md for the canonical state file and the evidence paths before reading or changing them.
2. Verify that the branch was merged and that targeted tests passed.
3. Record that the required integration test has not run; classify this as an evidence gap rather than inferring success from the merge.
4. Preserve export-redesign: ACTIVE, record the missing integration evidence, and identify running that test as the next authoritative step.

The durable result is a minimal state delta, not a rewritten history:

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 transition to DONE.

1. Authority hierarchy

Before ranking conflicting sources, enforce a hard boundary: no owner or product decision may override applicable law, an actual authorization boundary, non-waivable security or safety constraints, or objective facts. Verify that a claimed constraint is real and applicable; convention, preference, and speculation do not become non-overridable merely by being labelled a risk.

Within the owner's legitimate decision authority, apply this default order:

1. current explicit owner decision;
2. current approved requirements and acceptance criteria;
3. formal product and technical contracts, schemas, APIs, protocols, and risk controls;
4. tests traceable to authoritative requirements;
5. current verified implementation behavior;
6. current canonical project-state records;
7. historical documentation;
8. historical review reports;
9. historical AI conversations, summaries, suggestions, or speculation.

Lower-authority evidence must not silently override higher-authority evidence.

Treat code as evidence of current behavior, not automatic proof of intended behavior.

…