opencode-skills-collection 4.0.41 → 4.0.42

package/bundled-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?

package/bundled-skills/project-state-governor/references/project-state-schema.md

@@ -0,0 +1,173 @@
+# 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 | PAUSED | 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/
+    <subsystem>.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, current workstreams and tasks, recent terminal transitions, 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, current workstreams, milestones,
+current tasks, recent terminal transitions, blockers, and next direction. Keep
+it sufficient for a fast cold start.
+
+Apply the compact-mode terminal retention rules in scaled mode too. Keep
+verified `COMPLETED` or `CANCELLED` workstreams and `DONE` or `CANCELLED`
+tasks until consolidation can compress them into decision-relevant milestone
+or project history without losing information that still affects future work.
+
+### `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.

package/bundled-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 their complete instruction scope: include the candidate itself when it is an existing directory, otherwise stop at its parent; for recursive directory operations, discover every nested `AGENTS.md` in the affected subtree before inspecting or mutating it;
+- 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.