diff --git a/docs/README.skills.md b/docs/README.skills.md index aa492a833..a40ee4323 100644 --- a/docs/README.skills.md +++ b/docs/README.skills.md @@ -327,6 +327,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-skills) for guidelines on how to | [pr-screenshots](../skills/pr-screenshots/SKILL.md)
`gh skills install github/awesome-copilot pr-screenshots` | Embed before/after screenshots and annotated images in pull request descriptions. Covers PR description patterns, image upload for Azure DevOps and GitHub, and sizing best practices. | None | | [prd](../skills/prd/SKILL.md)
`gh skills install github/awesome-copilot prd` | Generate high-quality Product Requirements Documents (PRDs) for software systems and AI-powered features. Includes executive summaries, user stories, technical specifications, and risk analysis. | None | | [premium-frontend-ui](../skills/premium-frontend-ui/SKILL.md)
`gh skills install github/awesome-copilot premium-frontend-ui` | A comprehensive guide for GitHub Copilot to craft immersive, high-performance web experiences with advanced motion, typography, and architectural craftsmanship. | None | +| [project-state-governor](../skills/project-state-governor/SKILL.md)
`gh skills install github/awesome-copilot project-state-governor` | Maintain evidence-backed project state across conversations, branches, reviews, and research cycles. Use when an AI coding agent must reconstruct or consolidate fragmented project documentation, reconcile conflicting history against code/tests/contracts/Git, classify active and completed work, verify completion claims, preserve durable decisions or negative evidence, prevent status-document sprawl, or identify the next authoritative project step. | `references/manifest-routing.md`
`references/persistence-lifecycle.md`
`references/project-state-schema.md`
`references/reconstruction-workflow.md` | | [project-workflow-analysis-blueprint-generator](../skills/project-workflow-analysis-blueprint-generator/SKILL.md)
`gh skills install github/awesome-copilot project-workflow-analysis-blueprint-generator` | Comprehensive technology-agnostic prompt generator for documenting end-to-end application workflows. Automatically detects project architecture patterns, technology stacks, and data flow patterns to generate detailed implementation blueprints covering entry points, service layers, data access, error handling, and testing approaches across multiple technologies including .NET, Java/Spring, React, and microservices architectures. | None | | [prompt-optimizer](../skills/prompt-optimizer/SKILL.md)
`gh skills install github/awesome-copilot prompt-optimizer` | Turn any rough prompt, half-formed idea, or task description into a finished, ready-to-send prompt optimized for any LLM model inside a chat interface — NOT the API. Use this skill whenever the user wants to write, rewrite, optimize, improve, sharpen, or polish a prompt for chat. Trigger phrases include "rewrite this prompt", "make this a better prompt", "optimize this prompt", "turn this into a prompt", "help me prompt this", "draft a prompt that...", "I want to ask...", or whenever the user pastes a draft prompt and asks for improvements. Also trigger when the user describes a task they plan to send to an LLM model and clearly wants a reusable, well-structured prompt rather than a direct answer. The output is always a single, copy-pasteable prompt in a code block that the user sends as-is — never a template with placeholders. | None | | [publish-to-pages](../skills/publish-to-pages/SKILL.md)
`gh skills install github/awesome-copilot publish-to-pages` | Publish presentations and web content to GitHub Pages. Converts PPTX, PDF, HTML, or Google Slides to a live GitHub Pages URL. Handles repo creation, file conversion, Pages enablement, and returns the live URL. Use when the user wants to publish, deploy, or share a presentation or HTML file via GitHub Pages. | `scripts/convert-pdf.py`
`scripts/convert-pptx.py`
`scripts/publish.sh` | diff --git a/skills/project-state-governor/SKILL.md b/skills/project-state-governor/SKILL.md new file mode 100644 index 000000000..ac000aed9 --- /dev/null +++ b/skills/project-state-governor/SKILL.md @@ -0,0 +1,478 @@ +--- +name: project-state-governor +description: Maintain evidence-backed project state across conversations, branches, reviews, and research cycles. Use when an AI coding agent must reconstruct or consolidate fragmented project documentation, reconcile conflicting history against code/tests/contracts/Git, classify active and completed work, verify completion claims, preserve durable decisions or negative evidence, prevent status-document sprawl, or identify the next authoritative project step. +license: MIT +metadata: + author: Ghost011118 + version: "1.0.1" + compatibility: Designed for filesystem- and Git-capable coding agents, including GitHub Copilot, Codex, and Claude Code. + source: https://github.com/Ghost011118/project-state-governor +--- + +# 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. + +## 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. +Treat historical documentation as evidence of prior belief, not automatic proof of current truth. +Treat reviewer findings as hypotheses until verified. +Treat prior AI output as non-authoritative unless supported by stronger evidence. + +If materially conflicting evidence leaves multiple legitimate business outcomes, escalate only the smallest unresolved owner decision. + +## 2. Canonical state modes + +Use the smallest structure that stays clear. + +### Compact mode + +Prefer for small and medium projects: + +```text +AGENTS.md +PROJECT_STATE.md +``` + +### Scaled mode + +Use when `PROJECT_STATE.md` becomes too large, mixes unrelated subsystems, or repeatedly forces irrelevant context loading: + +```text +AGENTS.md +.project/ + MANIFEST.md + STATE.md + DECISIONS.md + CONSTRAINTS.md + NEGATIVE_EVIDENCE.md + areas/ + .md +``` + +The files together form one canonical state system. +Do not split merely for aesthetics. +Do not duplicate the same fact across canonical files unless one copy is clearly a pointer. + +Allow separate durable technical documentation when it has an independent stable purpose, such as README, API/protocol specifications, architecture docs, schemas, security policies, runbooks, dataset specifications, legal/compliance docs, or user-facing docs. + +Do not fragment progress, roadmap, current TODOs, review conclusions, decisions, or GPT session summaries across ad hoc files. + +## 3. Classify intent before persisting + +Use the smallest fitting type. + +- `MISSION`: long-lived reason the project exists. +- `SUCCESS_CRITERION`: durable definition of meaningful success; never invent one merely to make a mission measurable. +- `WORKSTREAM`: coherent multi-task initiative with a meaningful end or pause condition. +- `MILESTONE`: bounded intermediate outcome spanning multiple tasks. +- `TASK`: bounded work with a recognizable closure condition. +- `RESEARCH_HYPOTHESIS`: falsifiable proposition requiring evidence; rejection does not fail the mission. +- `DECISION`: owner-approved or objectively established choice that constrains future work. +- `CONSTRAINT`: technical, business, risk, authorization, compatibility, data, research-integrity, or operational rule. +- `BLOCKER`: confirmed condition preventing meaningful progress. +- `DEFERRED`: real work intentionally postponed. +- `QUESTION`: unresolved issue whose status materially affects future work. +- `LESSON`: validated pitfall or correction worth retaining to prevent an expensive repeated mistake. + +## 4. Closure and hierarchy + +Classify goals using this default test: + +- one clear code/configuration change can finish it -> `TASK`; +- multiple tasks are required but a bounded intermediate finish exists -> `MILESTONE` or `WORKSTREAM`; +- it is an ongoing strategic objective across many iterations -> `MISSION` or long-term `WORKSTREAM`; +- experimentation is required to determine truth -> `RESEARCH_HYPOTHESIS`. + +Use hierarchical completion rather than one global `DONE` claim: + +- `SESSION_DOD`: what this execution session promised to complete; +- `TASK_DOD`: acceptance and verification required for the bounded task; +- `MILESTONE_DOD`: required child outcomes for the milestone; +- `WORKSTREAM_DOD`: conditions for the initiative to complete or pause; +- `MISSION_SUCCESS`: owner-defined project success criteria. + +Never infer that a parent is complete merely because a child completed. + +Example: + +```text +session DONE != task DONE +task DONE != milestone DONE +milestone DONE != workstream DONE +workstream DONE != mission success +``` + +## 5. Session bootstrap and recall + +When repository access exists and project-level conclusions are required: + +1. read the repository-root `AGENTS.md` when present; +2. identify candidate paths that may be inspected, written, moved, or deleted; +3. before acting on each candidate path, discover and read every applicable `AGENTS.md` from the repository root through that path's parent; deeper rules govern only their subtree; +4. detect compact or scaled canonical-state mode; +5. in scaled mode, read `.project/MANIFEST.md` first; +6. read current state/brief before historical material; +7. identify current Git branch and working tree; +8. inspect relevant recent commits, code, tests, configuration, and contracts; +9. load domain-specific governance files when applicable; +10. load only task-relevant canonical area files; +11. inspect historical documentation only when needed to resolve state or conflict. + +Use progressive retrieval. Do not load the whole repository history or every memory file by default. + +If canonical state is missing, reconstruct it from repository evidence rather than fabricating it from conversation alone. + +## 6. Provenance and confidence + +For durable facts whose reliability materially matters, capture concise provenance and confidence. + +Preferred provenance includes: + +- owner decision or issue ID; +- commit SHA; +- test name/result; +- contract/schema path; +- experiment/candidate/manifest ID; +- authoritative file path and section. + +Use confidence labels only when they add value: + +- `CONFIRMED`: directly supported by authoritative evidence; +- `INFERRED`: best current interpretation, but not directly authoritative; +- `UNKNOWN`: unresolved or insufficiently supported. + +Never persist `INFERRED` as if it were settled fact. +Represent material inference explicitly as hypothesis, question, or provisional state. + +Do not add provenance noise to obvious low-impact facts. + +## 7. Semantic State Diff + +After meaningful work, ask: + +> Did this work create, remove, invalidate, complete, clarify, or materially modify a durable project fact? + +Persist when one or more occurred: + +- mission or owner-defined success criteria changed; +- a workstream/milestone began, ended, paused, blocked, or materially changed; +- a task changed lifecycle state; +- a durable decision was made; +- an important invariant or constraint was discovered; +- a blocker appeared or was removed; +- a research hypothesis changed validated state; +- negative evidence changed future direction; +- project phase or roadmap priority materially changed; +- meaningful debt was explicitly deferred; +- a historical project belief was proven obsolete; +- a validated recurring pitfall or owner correction should become a `LESSON`. + +Do not persist merely because: + +- a conversation occurred; +- code or files were inspected; +- commands were run; +- an intermediate debugging theory appeared; +- an AI suggested an idea; +- a reviewer raised an unverified concern; +- wording changed without semantic consequence; +- a known fact was repeated. + +No durable state change means no canonical-state write. + +## 8. Persistence lifecycle and write gate + +Use the lifecycle in `references/persistence-lifecycle.md`: + +```text +RECALL -> PROPOSE -> VERIFY -> APPLY -> CONSOLIDATE +``` + +Never jump from conversation directly to permanent state when material uncertainty exists. + +For low-risk deterministic updates, apply after evidence verification and a semantic-diff self-check. + +Require owner review or explicit prior authorization before applying changes that: + +- redefine mission or success criteria; +- choose among legitimate business outcomes; +- delete documentation with uncertain unique value; +- perform broad/mass cleanup outside previously authorized scope; +- convert an inferred state into an owner commitment; +- accept release, research-integrity, security, legal, or operational risk. + +When reconstruction or broad cleanup is requested but deletion authority is unclear, stage the cleanup set and report the proposed diff rather than deleting. + +## 9. Convert conversations into semantic state, not transcripts + +Never archive raw conversation history by default. + +Do not persist chronology such as: + +> User asked X, GPT suggested Y, then we considered Z. + +Persist only the durable semantic result. + +If a long discussion ends in a verified rejection of an expensive research direction, preserve the concise rejection, reason, and evidence reference. +If the discussion produced no durable lesson, store nothing. + +## 10. Status transitions + +Use these defaults unless the project defines authoritative alternatives. + +- Tasks: `PROPOSED`, `ACTIVE`, `BLOCKED`, `DONE`, `CANCELLED`, `DEFERRED`. +- Research hypotheses: `PROPOSED`, `ACTIVE`, `SUPPORTED`, `REJECTED`, `INCONCLUSIVE`, `INVALIDATED`, `FORWARD_ONLY`. +- Workstreams: `PLANNED`, `ACTIVE`, `BLOCKED`, `COMPLETED`, `PAUSED`, `CANCELLED`. + +Do not invent new status vocabularies unless necessary. + +## 11. Completion claims + +Never mark a task `DONE` merely because code was written or an agent says it is finished. + +Before accepting a completion claim: + +1. identify the relevant DoD level; +2. identify authoritative acceptance criteria; +3. verify implementation/build/test/integration evidence appropriate to the task; +4. verify required decisions/dependencies are resolved; +5. ensure no child-only completion is being promoted to a parent-level claim; +6. record only the resulting durable state transition. + +If verification is incomplete, keep the item `ACTIVE` or `BLOCKED`. + +## 12. Documentation hygiene + +Classify project-status documents as: + +- `AUTHORITATIVE` +- `CURRENT_SUPPORTING` +- `HISTORICAL` +- `DUPLICATE` +- `STALE` +- `CONTRADICTORY` +- `GENERATED_TEMPORARY` +- `UNKNOWN` + +Do not delete based on filename alone. +Before removing a document, determine whether it contains unique durable information. + +Do not concatenate old documents into one giant archive. Reconstruct current state. + +Avoid creating ad hoc status files such as `review-final-v2.md`, `todo-new.md`, `implementation-summary.md`, `current-progress.md`, `gpt-review.md`, `fix-report.md`, or `next-steps.md` unless a distinct external deliverable is explicitly required. + +## 13. Branch awareness + +Different branches may legitimately represent different implementation states. + +Before reconciling branch conflicts: + +- identify current branch and relevant ancestry; +- determine whether changes were merged; +- determine which branch is authoritative for the task; +- distinguish abandoned branch state from current branch state; +- keep branch-local completion branch-local until merged or accepted under project rules. + +Mission and durable owner decisions may be global while implementation progress remains branch-specific. + +Never silently blend incompatible branch state. + +## 14. Historical conflict categories + +Classify conflicts before editing canonical state. + +### OBSOLETE_HISTORY +A statement was once valid but later superseded. Keep current state; Git retains history. + +### IMPLEMENTATION_DRIFT +Documentation and implementation differ. Determine which violates higher-authority evidence. + +### UNRESOLVED_BUSINESS_CONFLICT +Multiple legitimate intended behaviors remain. Escalate the smallest owner decision. + +### FALSE_OR_UNSUPPORTED_HISTORY +A historical review or AI-generated claim was never established. Do not preserve it as truth. + +### BRANCH_DIVERGENCE +Branches represent different states. Keep them distinct until merge/authority is resolved. + +## 15. Negative evidence and lessons + +Preserve failures or lessons when they are expensive to reproduce, strategically important, likely to be retried, necessary for research integrity, or necessary to prevent repeated agent mistakes. + +Keep records concise: + +- what failed or was corrected; +- why; +- supporting evidence; +- whether the result is permanent or conditional. + +Do not preserve every failed debug attempt. + +## 16. Consolidation and forgetting + +Canonical state must not become an append-only diary. + +Periodically consolidate when one or more are true: + +- active sections contain completed/cancelled items; +- duplicate facts appear; +- old milestones no longer affect decisions; +- negative evidence can be compressed without losing its warning value; +- area files overlap; +- state loading repeatedly pulls irrelevant content; +- the canonical system has grown enough to impair fast comprehension. + +During consolidation: + +- deduplicate facts; +- remove obsolete low-value state; +- compress completed history into only decision-relevant milestones; +- preserve critical decisions, constraints, negative evidence, and lessons; +- migrate to scaled mode only when it improves retrieval; +- never remove information whose significance is materially uncertain without review. + +Git remains the low-level historical archive. + +## 17. Security and sensitive-state hygiene + +Do not persist secrets, tokens, passwords, private keys, session cookies, raw credentials, or other authentication material in canonical project state. + +Do not persist sensitive personal data merely because it appeared in conversation or logs. +When a useful durable fact can be recorded without sensitive detail, store the minimum necessary abstraction. + +Do not copy secrets from code/config into state documents while documenting a finding. + +## 18. Coordination with engineering governors + +When `engineering-decision-governor` or equivalent exists, this governor owns reconstruction, goal hierarchy, persistent status, documentation hygiene, durable transitions, and cross-session continuity. The engineering governor owns task boundaries, defect classification, deterministic fixes, engineering verification, scope control, and release-risk classification. Consume its verified outputs as evidence; repeat engineering work only when evidence is missing or contradictory. + +## 19. Coordination with research governors + +When a domain research governor exists, it owns research protocol and stage authorization, experiment execution, contamination/OOS rules, candidate acceptance or rejection, and research evidence requirements. Project State Governor owns how research fits the mission, the active workstream, persistent high-level research state, durable negative evidence, and the current next direction. + +Never bypass research stage gates. +Never turn invalid/rejected research into project success. +Never reinterpret evidence merely to make project status appear advanced. + +## 20. Owner authority boundary + +Autonomously: + +- classify evidence; +- identify duplicate status docs; +- identify objectively obsolete information; +- update lifecycle state when completion is objectively verified; +- compress redundant state; +- reconcile deterministic factual conflicts; +- remove clearly redundant generated status docs when deletion is already authorized. + +Do not autonomously: + +- redefine mission; +- redefine product semantics; +- invent acceptance criteria; +- accept unresolved release/research/security/legal risk; +- choose among multiple legitimate business outcomes; +- erase uniquely valuable history when significance is uncertain; +- treat prior AI output as authoritative because an AI wrote it. + +Escalate only the smallest unresolved owner decision. + +## 21. Repository reconstruction mode + +When asked to clean, repair, consolidate, or reconstruct a repository with fragmented history, enter `REPOSITORY_STATE_RECONSTRUCTION` and follow `references/reconstruction-workflow.md`. + +Do not use reconstruction as justification for unrelated feature work. + +## 22. State update equation + +Before applying canonical state, compute: + +```text +OLD_STATE ++ VERIFIED_NEW_FACTS +- INVALIDATED_FACTS += NEW_STATE +``` + +For material updates, make the proposed semantic delta explicit before applying it. +Distinguish `CONFIRMED`, `INFERRED`, and `UNKNOWN` where reliability matters. + +## 23. Final reporting + +After meaningful governance work, report only: + +- **Project State Changes:** durable state transitions applied. +- **Current Focus:** active mission, workstream, milestone, task, or research direction. +- **Remaining Blockers / Decisions:** genuine unresolved blockers or owner decisions. +- **Documentation Actions:** canonical docs changed, staged, consolidated, or removed. +- **Evidence Notes:** provenance or confidence caveats that materially affect trust. + +If no durable state changed, say so briefly and do not manufacture an update. + +## 24. Anti-patterns + +Never: + +- dump conversations into project docs; +- create a new status/review/TODO file after each session; +- assume code automatically defines intended behavior; +- assume reviewer findings are automatically true; +- persist unsupported inference as settled fact; +- accumulate completed/cancelled/duplicate TODOs indefinitely; +- confuse session, task, milestone, workstream, and mission completion; +- declare `DONE` without required verification; +- keep obsolete status files merely "for reference" when Git already preserves them; +- delete conflicting docs before extracting unique durable information; +- load every memory file for every task; +- use documentation cleanup as permission to rewrite unrelated code. + +The objective is not maximum documentation. +The objective is minimum sufficient, high-confidence, continuously maintained project knowledge. diff --git a/skills/project-state-governor/references/manifest-routing.md b/skills/project-state-governor/references/manifest-routing.md new file mode 100644 index 000000000..3be257f9e --- /dev/null +++ b/skills/project-state-governor/references/manifest-routing.md @@ -0,0 +1,47 @@ +# Manifest Routing for Large Projects + +Use scaled mode only when a single `PROJECT_STATE.md` is no longer efficient. + +## Trigger conditions + +Consider scaled mode when one or more are repeatedly true: + +- agents must read large irrelevant sections to work on one subsystem; +- decisions/constraints substantially outgrow active-state information; +- unrelated research and engineering streams compete for context; +- negative evidence is important but rarely needed; +- the canonical state file is becoming difficult to scan or safely edit. + +Do not split based on line count alone. + +## Routing principle + +`MANIFEST.md` is the stable map. +`STATE.md` is the fast cold-start brief. +Other files are loaded only when relevant. + +Default load path: + +```text +AGENTS.md + -> .project/MANIFEST.md + -> .project/STATE.md + -> only task-relevant routed files +``` + +## Routing rules + +- Put global mission, current phase, active workstreams, blockers, and next steps in `STATE.md`. +- Put durable choices in `DECISIONS.md`. +- Put non-negotiable rules in `CONSTRAINTS.md`. +- Put expensive failures and repeated pitfalls in `NEGATIVE_EVIDENCE.md`. +- Put subsystem-specific state in `areas/.md` only when the subsystem is large enough to justify independent loading. +- Keep global facts out of area files unless represented as pointers. +- Do not create one file per task, conversation, or day. + +## MANIFEST quality rules + +Keep MANIFEST concise and navigational. +Every routed file should state what question it answers. +Remove routes when files are merged or deleted. +Do not let MANIFEST become a second project summary. diff --git a/skills/project-state-governor/references/persistence-lifecycle.md b/skills/project-state-governor/references/persistence-lifecycle.md new file mode 100644 index 000000000..ea689a9af --- /dev/null +++ b/skills/project-state-governor/references/persistence-lifecycle.md @@ -0,0 +1,93 @@ +# Persistence Lifecycle + +Use this lifecycle for durable project knowledge: + +```text +RECALL -> PROPOSE -> VERIFY -> APPLY -> CONSOLIDATE +``` + +## 1. RECALL + +Load only enough canonical state to understand the task. + +- compact mode: read `PROJECT_STATE.md`; +- scaled mode: read `.project/MANIFEST.md`, then `STATE.md`, then only relevant routed files; +- inspect Git/code/tests/contracts only as needed; +- do not load historical docs unless a conflict or reconstruction requires them. + +## 2. PROPOSE + +After meaningful work, compute a semantic state delta. + +Represent only changes such as: + +- lifecycle transition; +- new verified decision/constraint; +- new blocker or resolved blocker; +- new/rejected research hypothesis; +- material negative evidence; +- durable owner correction/lesson; +- superseded historical belief. + +Do not propose transcript summaries. + +## 3. VERIFY + +Before persistence: + +- check authority hierarchy; +- verify completion claims against the correct DoD level; +- verify branch scope; +- distinguish `CONFIRMED`, `INFERRED`, and `UNKNOWN`; +- ensure the update does not silently redefine business intent; +- ensure no secret, credential, token, or unnecessary sensitive personal data is being persisted; +- ensure the same fact is not already represented canonically. + +## 4. APPLY + +### Auto-apply is allowed when + +- the state transition is deterministic and evidence-backed; +- scope is already authorized; +- no owner/business semantics are being created; +- no uncertain unique history is being deleted; +- the change is low-risk and reversible through Git. + +### Stage for owner review when + +- mission or success criteria would change; +- multiple legitimate business outcomes remain; +- deletion scope is broad or uncertain; +- unique historical significance is uncertain; +- an `INFERRED` state would become an owner commitment; +- release, research-integrity, security, legal, or operational risk would be accepted. + +A staged proposal should show the semantic delta, not a long prose recap. + +## 5. CONSOLIDATE + +Run consolidation when canonical state becomes noisy or repetitive. + +Actions: + +- deduplicate facts; +- remove stale active items; +- compress completed milestones; +- preserve only high-value negative evidence; +- merge overlapping lessons; +- remove low-value chronology; +- split into scaled mode only when retrieval improves; +- update MANIFEST routes after splits/merges. + +Do not perform lossy consolidation when significance is uncertain. + +## Persistence quality test + +Before finishing, ask: + +1. Would a fresh agent understand what changed? +2. Is every persisted claim useful for future decisions? +3. Is each high-impact claim supported or explicitly provisional? +4. Did we avoid storing conversation noise? +5. Did we avoid duplicating the same fact? +6. Is the canonical state now easier, not harder, to load? diff --git a/skills/project-state-governor/references/project-state-schema.md b/skills/project-state-governor/references/project-state-schema.md new file mode 100644 index 000000000..2999bcfc3 --- /dev/null +++ b/skills/project-state-governor/references/project-state-schema.md @@ -0,0 +1,166 @@ +# Canonical Project-State Schema + +Use the smallest structure that remains easy to load and reason about. + +## Compact mode: `PROJECT_STATE.md` + +```markdown +# Project State + +## Mission +[Why the project exists. Long-lived.] + +## Success Criteria +[Owner-defined durable criteria for meaningful project success.] + +## Current Phase +[Current engineering/product/research phase.] + +## Active Workstreams +### [Workstream ID or name] +- Status: PLANNED | ACTIVE | BLOCKED | PAUSED | COMPLETED | CANCELLED +- Goal: ... +- DoD / exit condition: ... +- Current state: ... +- Next: ... + +Keep terminal workstream records long enough to preserve verified `COMPLETED` +or `CANCELLED` transitions. During consolidation, compress old terminal +workstreams into decision-relevant milestone or project history only when their +detailed record no longer affects future work. + +## Milestones +### [Milestone ID or name] +- Status: PROPOSED | ACTIVE | BLOCKED | DONE | DEFERRED +- Goal: ... +- DoD: ... +- Parent: ... +- Next: ... + +## Current Tasks +### [Task ID or name] +- Status: PROPOSED | ACTIVE | BLOCKED | DEFERRED | DONE | CANCELLED +- Goal: ... +- Task DoD: ... +- Parent: ... +- Evidence: ... [only when useful] +- Confidence: CONFIRMED | INFERRED | UNKNOWN [only when useful] + +Keep terminal task records long enough to preserve the verified lifecycle transition. During consolidation, compress old `DONE` or `CANCELLED` tasks into decision-relevant milestone history when their detailed record no longer affects future work. + +## Active Research / Experiments +### [Hypothesis or candidate ID] +- Status: PROPOSED | ACTIVE | SUPPORTED | REJECTED | INCONCLUSIVE | INVALIDATED | FORWARD_ONLY +- Hypothesis: ... +- Protocol / stage: ... +- Current evidence: ... +- Provenance: ... [experiment/manifest ID when material] +- Next authorized step: ... + +## Decisions +### [Decision ID or concise title] +- Decision: ... +- Rationale: ... +- Authority / provenance: ... [when material] + +## Constraints / Invariants +- ... + +## Known Issues / Blockers +- ... + +## Deferred Work +- ... + +## Negative Evidence / Rejected Directions +- [what] — [why] — [evidence] — [permanent or conditional] + +## Lessons / Pitfalls +- [validated recurring mistake or owner correction worth preserving] + +## Recent Milestones +- [date/commit only when useful] ... +``` + +## Scaled mode + +Use only when compact mode causes context bloat or unrelated subsystem loading. + +```text +.project/ + MANIFEST.md + STATE.md + DECISIONS.md + CONSTRAINTS.md + NEGATIVE_EVIDENCE.md + areas/ + .md +``` + +### `.project/MANIFEST.md` +Keep it short. It is the routing index, not a summary dump. + +```markdown +# Project Memory Manifest + +## Read First +- STATE.md — mission, phase, active workstreams, active tasks, blockers, next actions + +## Read When Relevant +- DECISIONS.md — durable owner/project decisions +- CONSTRAINTS.md — technical/business/research invariants +- NEGATIVE_EVIDENCE.md — costly rejected directions and important lessons +- areas/execution.md — execution subsystem state +- areas/research.md — research subsystem state +``` + +### `.project/STATE.md` +Contain mission, success criteria, phase, active workstreams, milestones, active tasks, blockers, and next direction. Keep it sufficient for a fast cold start. + +### `DECISIONS.md` +Store only durable decisions that materially constrain future work. + +### `CONSTRAINTS.md` +Store only constraints/invariants future agents must respect. + +### `NEGATIVE_EVIDENCE.md` +Store concise costly failures, rejected directions, and validated lessons likely to prevent repeated work. + +### `areas/*.md` +Use only for large independent subsystems. Do not duplicate global mission or global decisions inside area files. + +## Provenance rule + +Add provenance only when it materially improves trust. Prefer concise references: + +- owner decision / issue ID; +- commit SHA; +- test name/result; +- contract/schema path; +- experiment or manifest ID. + +## Confidence rule + +Use: + +- `CONFIRMED` for directly supported authoritative facts; +- `INFERRED` for provisional interpretation; +- `UNKNOWN` when evidence is insufficient. + +Do not represent `INFERRED` as settled truth. + +## Completion hierarchy + +Track completion at the correct level: + +- Session DoD +- Task DoD +- Milestone DoD +- Workstream DoD +- Mission success criteria + +A child completing does not automatically complete its parent. + +## Compression rule + +When state grows, remove or compress detail that is no longer decision-relevant. Git is the historical archive. diff --git a/skills/project-state-governor/references/reconstruction-workflow.md b/skills/project-state-governor/references/reconstruction-workflow.md new file mode 100644 index 000000000..9e07637b1 --- /dev/null +++ b/skills/project-state-governor/references/reconstruction-workflow.md @@ -0,0 +1,183 @@ +# Repository State Reconstruction Workflow + +Use this workflow when a repository contains conflicting historical reviews, plans, TODOs, status notes, GPT summaries, branch-specific docs, or unclear progress. + +## 1. Establish scope and authority + +Identify: + +- repository and target branch; +- owner-requested cleanup boundary; +- candidate paths and every applicable `AGENTS.md` from the repository root through each path's parent; +- compact vs scaled canonical-state mode; +- whether deletion is explicitly authorized or only recommendations are allowed. + +Do not expand into unrelated feature work. + +Before inspecting, writing, moving, or deleting a candidate path, resolve its full `AGENTS.md` chain. Apply deeper rules only to their governed subtree, and do not let a repository-level cleanup instruction override a more specific local constraint. + +## 2. Inventory candidate state documents + +Find files likely to contain project state: + +- plans/TODOs; +- reviews/audits; +- implementation summaries; +- status/progress/handoff docs; +- research manifests and decision records; +- GPT-generated summaries; +- branch-specific notes. + +Do not assume every Markdown file is status documentation. + +Classify each file initially as: + +- `AUTHORITATIVE`; +- `CURRENT_SUPPORTING`; +- `HISTORICAL`; +- `DUPLICATE`; +- `STALE`; +- `CONTRADICTORY`; +- `GENERATED_TEMPORARY`; +- `UNKNOWN`. + +## 3. Extract claims, not prose + +Extract only material claims affecting current state: + +- mission/success criteria; +- completion claims and DoD; +- active tasks/workstreams; +- decisions/constraints; +- blockers; +- research state/results; +- rejected directions/lessons; +- branch assumptions. + +Ignore rhetorical explanation and conversation chronology unless needed as provenance. + +## 4. Verify each material claim + +Inspect only the code, tests, contracts, commits, configuration, and history necessary to evaluate claims. + +Classify claims: + +- `CURRENT_CONFIRMED`: supported by authoritative evidence; +- `CURRENT_INFERRED`: plausible but not directly authoritative; +- `SUPERSEDED`: once true, now replaced; +- `FALSE`: contradicted by higher-authority evidence; +- `CONFLICTED`: multiple legitimate interpretations remain; +- `UNKNOWN`: insufficient evidence. + +Never use current code as automatic proof of intended semantics. +Never promote `CURRENT_INFERRED` to settled truth without justification. + +## 5. Verify completion at the correct level + +For each completion claim, distinguish: + +- session completion; +- task completion; +- milestone completion; +- workstream completion; +- mission success. + +Reject parent-level completion claims supported only by child-level evidence. + +## 6. Resolve conflict type + +### OBSOLETE_HISTORY +Statement was once valid but superseded. Keep only current canonical state. + +### IMPLEMENTATION_DRIFT +Code and intended requirement differ. Determine which violates higher authority. + +### UNRESOLVED_BUSINESS_CONFLICT +Multiple legitimate outcomes remain. Escalate the smallest owner decision. + +### FALSE_OR_UNSUPPORTED_HISTORY +Review/AI output was never established. Do not preserve as truth. + +### BRANCH_DIVERGENCE +Branches reflect different states. Keep them distinct until merge/authority is resolved. + +## 7. Rebuild canonical state + +Use `project-state-schema.md`. + +Rules: + +- preserve current durable state only; +- preserve concise high-value negative evidence and lessons; +- represent unresolved ambiguity explicitly; +- attach provenance/confidence only where material; +- do not copy whole historical documents; +- do not create an append-only archive; +- choose compact mode unless scaled routing clearly improves retrieval. + +## 8. Build a staged cleanup set + +For each old document choose: + +- `KEEP`: independent stable purpose remains; +- `MERGE_THEN_DELETE`: unique durable content must enter canonical state first; +- `DELETE`: redundant/stale/generated with no unique required content; +- `OWNER_DECISION`: significance or deletion authority is genuinely uncertain. + +Never delete first and reconcile later. + +If broad deletion was not explicitly authorized, present this cleanup set for owner review before applying destructive changes. + +## 9. Apply authorized cleanup + +When authorized: + +- update canonical state; +- remove obsolete redundant status files; +- preserve legitimate technical/public docs; +- avoid unrelated code edits; +- keep branch-specific facts branch-specific; +- ensure secrets/sensitive data are not copied into canonical state. + +## 10. Consolidate + +After reconstruction: + +- remove duplicate canonical facts; +- compress low-value completed history; +- retain important decisions, constraints, negative evidence, and lessons; +- update MANIFEST if scaled mode is used. + +## 11. Verify + +Before declaring reconstruction complete, verify: + +- canonical state is internally consistent; +- active tasks are actually open; +- completion claims match the correct DoD level; +- key decisions/constraints are represented; +- meaningful negative evidence is preserved; +- stale status docs no longer compete as sources of truth; +- no unique required information was lost; +- branch scope is represented correctly; +- provenance/confidence caveats are accurate; +- canonical state contains no exposed secrets copied during cleanup. + +## 12. Report + +Return only: + +### Project State Changes +What became canonical or changed status. + +### Current Focus +Resulting active workstream/task/research direction. + +### Remaining Blockers / Decisions +Only unresolved items requiring action. + +### Documentation Actions +Files kept, staged, merged/deleted, or awaiting owner review. + +### Evidence Notes +Only material provenance/confidence caveats.