opencodekit 0.20.6 → 0.20.7

package/dist/index.js

@@ -20,7 +20,7 @@ var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
 //#endregion
 //#region package.json
-var version = "0.20.6";
+var version = "0.20.7";
 
 //#endregion
 //#region src/utils/license.ts

package/dist/template/.opencode/command/compound.md

@@ -8,10 +8,17 @@ agent: build
 
 Capture what was learned. This is the flywheel step — each cycle makes the next cycle faster.
 
-> **Workflow:** `/plan` → `/ship` → `/review` → **`/compound`** → `/pr`
+> **Workflow:** `/plan` → `/ship` → **`/compound`** → `/pr`
 >
 > Run after every completed task, review, or PR merge. The value compounds over time.
 
+## Load Skills
+
+```typescript
+skill({ name: "memory-system" });
+skill({ name: "verification-before-completion" });
+```
+
 ## What This Does
 
 Extracts learnings from the just-completed work and stores them as structured observations in memory,
@@ -47,7 +54,7 @@ For each finding, assign a type:
 | `pattern`   | A reusable approach confirmed to work in this codebase     | "Always use X pattern for Y type of component"  |
 | `bugfix`    | A non-obvious bug and its root cause                       | "Bun doesn't support X, use Y instead"          |
 | `decision`  | An architectural or design choice with rationale           | "Chose JWT over sessions because..."            |
-| `gotcha`    | A footgun, constraint, or thing that looks wrong but isn't | "Don't modify dist/ directly, build overwrites" |
+| `warning`   | A footgun, constraint, or thing that looks wrong but isn't | "Don't modify dist/ directly, build overwrites" |
 | `discovery` | A non-obvious fact about the codebase or its dependencies  | "Build copies .opencode/ to dist/template/"     |
 | `warning`   | Something that will break if not followed                  | "Always run lint:fix before commit"             |
 
@@ -60,19 +67,60 @@ For each learning worth keeping, create an observation:
 
 ```typescript
 observation({
-  type: "pattern", // or bugfix, decision, gotcha, discovery, warning
+  type: "pattern", // or bugfix, decision, discovery, warning, learning
   title: "[Concise, searchable title — what someone would search for]",
   narrative: "[What happened, why it matters, how to apply it]",
   facts: "[comma, separated, key, facts]",
   concepts: "[searchable, keywords, for, future, retrieval]",
   files_modified: "[relevant/file.ts if applicable]",
   confidence: "high", // high=verified, medium=likely, low=speculative
+  // ByteRover-inspired quality fields:
+  subtitle: "[One-line semantic summary — WHY this matters for future work]",
 });
 ```
 
 **Minimum viable:** title + narrative. Everything else is bonus.
 
-## Phase 4: Check AGENTS.md / Skill Updates
+**Quality enrichment:** Add `subtitle` (WHY it matters) for high-impact observations. Skip for routine findings.
+
+## Phase 4: Structural Loss Prevention
+
+When superseding an older observation, prevent accidental knowledge loss.
+
+**Trigger:** Only runs when `supersedes: "ID"` is set on a new observation.
+
+### Step 1: Read the old observation
+
+```typescript
+const old = memory_get({ ids: "<superseded-id>" });
+```
+
+### Step 2: Detect structural loss
+
+Compare the new observation against the old one:
+
+| Field            | Loss Detection                                                  |
+| ---------------- | --------------------------------------------------------------- |
+| `facts`          | Old facts not present in new facts (comma-separated comparison) |
+| `concepts`       | Old concepts not present in new concepts                        |
+| `narrative`      | New narrative significantly shorter than old (< 50% length)     |
+| `files_modified` | Old file paths not present in new list                          |
+
+### Step 3: Auto-merge if loss detected
+
+- **Array fields** (facts, concepts): Union merge — keep all old items, add new items, deduplicate
+- **Scalar fields** (narrative): If new is shorter, append `\n\n[Preserved from superseded observation #ID:]\n` + old narrative section
+- **File paths**: Union merge all paths
+
+### Step 4: Flag for review if high-impact
+
+If the old observation had `confidence: "high"` and the new one has `confidence: "medium"` or `confidence: "low"`, flag with a warning:
+
+> ⚠️ Confidence downgrade detected: superseding a high-confidence observation (#ID) with lower confidence. Verify this is intentional.
+
+**Principle:** Knowledge should accumulate, not be replaced. Merging is safer than overwriting.
+
+## Phase 5: Check AGENTS.md / Skill Updates
 
 Ask: does this learning belong as a permanent rule?
 
@@ -88,18 +136,18 @@ If MAYBE (it's a pattern, not a rule):
 
 **Rule:** AGENTS.md changes require user confirmation. Observations are automatic.
 
-## Phase 5: Update Living Documentation
+## Phase 6: Update Living Documentation
 
 Check if the shipped work changed architecture, APIs, conventions, or tech stack. If so, update the relevant project docs.
 
 **Check each:**
 
-| Doc | Update When | What to Update |
-| --- | --- | --- |
-| `tech-stack.md` | New dependency added, build tool changed, runtime updated | Dependencies list, build tools, constraints |
-| `project.md` | Architecture changed, new key files, success criteria met | Architecture section, key files table, phase status |
-| `gotchas.md` | New footgun discovered, constraint found | Add the gotcha with context |
-| `AGENTS.md` (project) | New convention established, boundary rule needed | Boundaries, gotchas, code example sections |
+| Doc                   | Update When                                               | What to Update                                      |
+| --------------------- | --------------------------------------------------------- | --------------------------------------------------- |
+| `tech-stack.md`       | New dependency added, build tool changed, runtime updated | Dependencies list, build tools, constraints         |
+| `project.md`          | Architecture changed, new key files, success criteria met | Architecture section, key files table, phase status |
+| `gotchas.md`          | New footgun discovered, constraint found                  | Add the gotcha with context                         |
+| `AGENTS.md` (project) | New convention established, boundary rule needed          | Boundaries, gotchas, code example sections          |
 
 ```typescript
 // Check what changed
@@ -110,7 +158,8 @@ memory_update({ file: "project/gotchas", content: "...", mode: "append" });
 ```
 
 **Rule:** Only update docs when the change is structural (new pattern, new dep, new constraint). Don't update for routine bug fixes or small features. Ask user before modifying `AGENTS.md`.
-## Phase 6: Search for Related Past Observations
+
+## Phase 7: Search for Related Past Observations
 
 ```typescript
 // Check if this updates or supersedes an older observation
@@ -128,24 +177,48 @@ observation({
 });
 ```
 
-## Phase 7: Output Summary
+## Phase 8: Output Summary
 
-Report what was codified:
+Present extracted learnings for user review before finalizing:
 
 ```
-## Compound Summary
+## Compound Review
 
 **Work reviewed:** [brief description]
-**Learnings captured:** [N] observations
+**Learnings extracted:** [N] observations
+
+| # | Type | Title | Impact | Action |
+|---|------|-------|--------|--------|
+| 1 | pattern | ... | high | ✅ Store |
+| 2 | warning | ... | medium | ✅ Store |
+| 3 | bugfix | ... | low | ⏭️ Skip (routine) |
+```
+
+```typescript
+question({
+  questions: [
+    {
+      header: "Approve Learnings",
+      question: "Review extracted learnings. Store all approved observations?",
+      options: [
+        { label: "Store all (Recommended)", description: "Persist all marked ✅" },
+        { label: "Let me adjust", description: "I'll modify before storing" },
+        { label: "Skip compound", description: "Nothing worth persisting" },
+      ],
+    },
+  ],
+});
+```
+
+**After approval:** Store observations and report final summary:
 
-| # | Type      | Title                        | Concepts               |
-|---|-----------|------------------------------|------------------------|
-| 1 | pattern   | ...                          | auth, jwt              |
-| 2 | gotcha    | ...                          | node, build            |
-| 3 | bugfix    | ...                          | typecheck, strict-mode |
+```
+## Compound Summary
 
+**Observations stored:** [N]
+**Superseded:** [N] older observations updated
 **AGENTS.md updates suggested:** [yes/no - describe if yes]
-**Next recommended:** /pr  (or /plan <next-bead-id>)
+**Next recommended:** /pr (or /plan <next-bead-id>)
 ```
 
 ## When Nothing to Compound
@@ -158,9 +231,10 @@ Don't force observations. Quality over quantity.
 
 ## Related Commands
 
-| Need                   | Command   |
-| ---------------------- | --------- |
-| Full chain             | `/lfg`    |
-| Review before compound | `/review` |
-| Ship the work          | `/ship`   |
-| Create PR              | `/pr`     |
+| Need            | Command            |
+| --------------- | ------------------ |
+| Full chain      | `/lfg`             |
+| Review codebase | `/review-codebase` |
+| Ship the work   | `/ship`            |
+| Curate memory   | `/curate`          |
+| Create PR       | `/pr`              |

package/dist/template/.opencode/command/curate.md

@@ -0,0 +1,299 @@
+---
+description: Organize, deduplicate, and curate knowledge in project memory
+argument-hint: "[--scope recent|all] [--auto-merge]"
+agent: build
+---
+
+# Curate: $ARGUMENTS
+
+Organize accumulated knowledge. Surface conflicts, merge duplicates, archive stale observations.
+
+> **Workflow:** `/ship` → `/compound` → **`/curate`** → `/pr`
+>
+> Run periodically (weekly or after major work) to keep memory sharp. Inspired by ByteRover's structured curation pipeline.
+
+## Load Skills
+
+```typescript
+skill({ name: "memory-system" });
+skill({ name: "verification-before-completion" });
+```
+
+## Parse Arguments
+
+| Argument       | Default  | Description                                      |
+| -------------- | -------- | ------------------------------------------------ |
+| `--scope`      | `recent` | `recent` = last 30 days, `all` = entire memory   |
+| `--auto-merge` | false    | Auto-merge exact duplicates without confirmation |
+
+## Phase 1: Inventory
+
+Take stock of current memory state:
+
+```typescript
+memory_admin({ operation: "status" });
+memory_admin({ operation: "capture-stats" });
+```
+
+Report:
+
+```
+## Memory Inventory
+
+| Metric | Count |
+|--------|-------|
+| Total observations | [N] |
+| Recent (30 days) | [N] |
+| By type | pattern: N, decision: N, bugfix: N, ... |
+| Confidence distribution | high: N, medium: N, low: N |
+```
+
+## Phase 2: Domain Detection
+
+Analyze observations to extract semantic domains — groups of related knowledge.
+
+```typescript
+// Get memory status for inventory
+memory_admin({ operation: "status" });
+
+// Search by common concept categories to build domain map
+const domains = [];
+for (const concept of ["build", "test", "memory", "git", "agent", "auth", "ui", "config"]) {
+  const results = memory_search({ query: concept, limit: 20 });
+  // Group results by concept affinity
+}
+```
+
+Categorize observations into domains based on their `concepts` and `title` fields:
+
+| Domain         | Example Concepts                   | Observation Count |
+| -------------- | ---------------------------------- | ----------------- |
+| `build_system` | build, tsdown, rsync, dist         | [N]               |
+| `testing`      | vitest, test, TDD, coverage        | [N]               |
+| `memory`       | observation, FTS5, sqlite, handoff | [N]               |
+| `git_workflow` | commit, branch, push, PR           | [N]               |
+| `agent_system` | subagent, delegation, skills       | [N]               |
+
+**Domain naming rules:**
+
+- snake_case, 1-3 words
+- Semantically meaningful (not just "misc")
+- Maximum 10 domains (merge small groups)
+
+## Phase 3: Conflict & Duplicate Detection
+
+### 3a. Exact Duplicates
+
+```typescript
+memory_admin({ operation: "lint" });
+```
+
+Flag observations with identical or near-identical titles and narratives. Present for merge:
+
+```
+### Duplicates Found
+
+| Obs A | Obs B | Similarity | Recommended Action |
+|-------|-------|------------|-------------------|
+| #12 "Use JWT for auth" | #45 "JWT chosen for auth" | 95% title match | MERGE → keep #45 (newer) |
+| #8 "Build copies .opencode/" | #33 "Build copies .opencode/" | 100% title match | MERGE → keep #33 (newer) |
+```
+
+### 3b. Contradictions
+
+Search for observations where:
+
+- Same concepts but different decisions
+- Same file paths but conflicting patterns
+- Confidence downgrade without supersedes link
+
+```
+### Contradictions Found
+
+| Obs A | Obs B | Conflict | Recommended Action |
+|-------|-------|----------|-------------------|
+| #5 "Always use X pattern" | #29 "Avoid X pattern" | Opposite recommendations | RESOLVE — ask user which is current |
+```
+
+### 3c. Stale Observations
+
+Flag observations where:
+
+- Referenced files no longer exist
+- Referenced patterns no longer appear in codebase
+- Over 90 days old with no related recent activity
+
+```
+### Stale Observations
+
+| Obs | Age | Reason | Recommended Action |
+|-----|-----|--------|-------------------|
+| #3 "src/old-file.ts pattern" | 120 days | File deleted | ARCHIVE |
+| #7 "Use moment.js for dates" | 95 days | Dependency removed | ARCHIVE |
+```
+
+## Phase 4: Present Curation Plan
+
+Compile all findings into a review table:
+
+```
+## Curation Plan
+
+### Actions Required
+
+| # | Observation | Action | Reason |
+|---|------------|--------|--------|
+| 1 | #12 + #45 | MERGE | Duplicate — keep newer |
+| 2 | #5 vs #29 | RESOLVE | Contradicting patterns |
+| 3 | #3 | ARCHIVE | Referenced file deleted |
+| 4 | #7 | ARCHIVE | Dependency removed |
+| 5 | #18 | UPDATE | Low confidence → verify |
+```
+
+```typescript
+question({
+  questions: [
+    {
+      header: "Curation Plan",
+      question: "Review the curation plan. Proceed with all actions?",
+      options: [
+        { label: "Execute all (Recommended)", description: "Apply all actions above" },
+        { label: "Let me cherry-pick", description: "I'll approve individually" },
+        { label: "Skip curation", description: "No changes to memory" },
+      ],
+    },
+  ],
+});
+```
+
+## Phase 5: Execute Curation
+
+For each approved action:
+
+### MERGE (duplicates)
+
+```typescript
+// Read both observations
+const older = memory_get({ ids: "<older-id>" });
+const newer = memory_get({ ids: "<newer-id>" });
+
+// Union-merge: combine comma-separated lists, deduplicate (case-insensitive), existing items first
+// Example: older.facts="auth, jwt" + newer.facts="jwt, session" → "auth, jwt, session"
+
+// Create merged observation (newer as base, merge fields from older)
+observation({
+  type: newer.type,
+  title: newer.title,
+  narrative: newer.narrative,
+  // Manually combine comma-separated fields: keep all unique items from both
+  facts: "[combined unique facts from older + newer]",
+  concepts: "[combined unique concepts from older + newer]",
+  files_modified: "[combined unique file paths from older + newer]",
+  confidence: newer.confidence, // Newer confidence wins
+  supersedes: "<older-id>",
+  subtitle: "Merged from #<older-id> + #<newer-id>",
+});
+```
+
+**Union merge rule:** Combine comma-separated lists, deduplicate (case-insensitive), existing items first.
+
+### RESOLVE (contradictions)
+
+Present the conflicting observations side-by-side:
+
+```
+### Contradiction: #5 vs #29
+
+**#5 (older, high confidence):**
+> Always use X pattern for Y components
+
+**#29 (newer, medium confidence):**
+> Avoid X pattern — causes Z issues
+
+Which is the current truth?
+```
+
+```typescript
+question({
+  questions: [
+    {
+      header: "Resolve Conflict",
+      question: "Which observation reflects the current codebase reality?",
+      options: [
+        { label: "#5 (older) is correct", description: "Archive #29, keep #5" },
+        { label: "#29 (newer) is correct", description: "Supersede #5 with #29" },
+        { label: "Both partially correct", description: "I'll write a reconciled version" },
+      ],
+    },
+  ],
+});
+```
+
+### ARCHIVE (stale)
+
+```typescript
+// Verify staleness by checking codebase
+// If file doesn't exist or pattern not found:
+observation({
+  type: "warning",
+  title: "Archived: [original title]",
+  narrative: "Archived during curation — [reason]. Original observation #<id>.",
+  supersedes: "<stale-id>",
+  confidence: "low",
+});
+```
+
+### UPDATE (low confidence → verify)
+
+```typescript
+// Search codebase for evidence
+// If evidence found → upgrade confidence
+// If evidence not found → archive
+```
+
+## Phase 6: Compile Knowledge Index
+
+After curation, regenerate the knowledge index:
+
+```typescript
+memory_admin({ operation: "compile" });
+memory_admin({ operation: "index" });
+```
+
+## Phase 7: Report
+
+```
+## Curation Summary
+
+**Scope:** [recent / all]
+**Observations reviewed:** [N]
+**Domains identified:** [N]
+
+| Action | Count | Details |
+|--------|-------|---------|
+| Merged | [N] | [list merged pairs] |
+| Resolved | [N] | [list resolved conflicts] |
+| Archived | [N] | [list archived observations] |
+| Updated | [N] | [list confidence changes] |
+| No change | [N] | |
+
+**Memory health:** [Healthy / Needs attention: describe]
+**Next recommended:** /pr or continue work
+```
+
+## When Nothing to Curate
+
+If all observations are clean, well-organized, and non-conflicting:
+
+> "Memory is clean. No duplicates, contradictions, or stale observations found. [N] observations across [M] domains."
+
+Don't force curation. Quality memory means less curation needed.
+
+## Related Commands
+
+| Need                    | Command                        |
+| ----------------------- | ------------------------------ |
+| Extract learnings first | `/compound`                    |
+| Full chain              | `/lfg`                         |
+| Check memory health     | `/health`                      |
+| Search memory           | Use `memory-search()` directly |

package/dist/template/.opencode/command/lfg.md

@@ -61,6 +61,7 @@ Execute the plan:
 
 ```typescript
 skill({ name: "executing-plans" });
+skill({ name: "reflection-checkpoints" }); // Phase transition + mid-point checks
 // Load plan.md, execute wave-by-wave
 // Per-task commits after each task passes verification
 ```

package/dist/template/.opencode/command/ship.md

@@ -19,6 +19,7 @@ skill({ name: "beads" });
 skill({ name: "memory-grounding" });
 skill({ name: "workspace-setup" });
 skill({ name: "verification-before-completion" });
+skill({ name: "reflection-checkpoints" }); // Mid-point + completion checks during execution
 ```
 
 ## Determine Input Type

package/dist/template/.opencode/skill/reflection-checkpoints/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: reflection-checkpoints
+description: >
+  Use when executing long-running commands (/ship, /lfg) to add self-assessment
+  checkpoints that detect scope drift, stalled progress, and premature completion claims.
+  Inspired by ByteRover's reflection prompt architecture.
+version: 1.0.0
+tags: [workflow, quality, autonomous]
+dependencies: [verification-before-completion]
+---
+
+# Reflection Checkpoints
+
+## When to Use
+
+- During `/ship` execution after completing 50%+ of tasks
+- During `/lfg` at each phase transition (Plan→Work→Review→Compound)
+- When a task takes significantly longer than estimated
+- When context usage exceeds 60% of budget
+
+## When NOT to Use
+
+- Simple, single-task work (< 3 tasks)
+- Pure research or exploration commands
+- When user explicitly requests fast execution without checkpoints
+
+## Overview
+
+Long-running autonomous execution drifts silently. By the time you notice, you've burned context on the wrong thing. Reflection checkpoints force self-assessment at critical moments — catching drift before it compounds.
+
+**Core principle:** Pause to assess, don't just assess to pause.
+
+## The Four Reflection Types
+
+### 1. Mid-Point Check
+
+**Trigger:** After completing ~50% of planned tasks (e.g., 3 of 6 tasks done)
+
+```
+## 🔍 Mid-Point Reflection
+
+**Progress:** [N/M] tasks complete
+**Context used:** ~[X]% estimated
+
+### Scope Check
+- [ ] Am I still solving the original problem?
+- [ ] Have I introduced any unplanned work?
+- [ ] Are remaining tasks still correctly scoped?
+
+### Quality Check
+- [ ] Do completed tasks actually work (not just "done")?
+- [ ] Any verification steps I deferred?
+- [ ] Any TODO/FIXME I left that needs addressing?
+
+### Efficiency Check
+- [ ] Am I spending context on the right things?
+- [ ] Should remaining tasks be parallelized?
+- [ ] Any tasks that should be deferred to a follow-up bead?
+
+**Assessment:** [On track / Drifting / Blocked]
+**Adjustment:** [None needed / Describe change]
+```
+
+### 2. Completion Check
+
+**Trigger:** Before claiming any task or phase is complete
+
+```
+## ✅ Completion Check
+
+**Claiming complete:** [task/phase name]
+
+### Evidence Audit
+- [ ] Verification command was run (not assumed)
+- [ ] Output confirms the claim (not inferred)
+- [ ] No stub patterns in modified files
+- [ ] Imports/exports are wired (not just declared)
+
+### Goal-Backward Check
+- [ ] Does this task achieve its stated end-state?
+- [ ] Would a user see the expected behavior?
+- [ ] If tested manually, would it work?
+
+**Verdict:** [Complete / Needs work: describe what]
+```
+
+### 3. Near-Limit Warning
+
+**Trigger:** When context usage exceeds ~70% or step count approaches limit
+
+```
+## ⚠️ Near-Limit Warning
+
+**Context pressure:** [High / Critical]
+**Remaining tasks:** [N]
+
+### Triage
+1. What MUST be done before stopping? [list critical tasks]
+2. What CAN be deferred? [list deferrable tasks]
+3. What should be handed off? [list with context needed]
+
+### Action
+- [ ] Compress completed work
+- [ ] Prioritize remaining tasks ruthlessly
+- [ ] Prepare handoff if needed
+
+**Decision:** [Continue (enough budget) / Compress and continue / Handoff now]
+```
+
+### 4. Phase Transition Check
+
+**Trigger:** At `/lfg` phase boundaries (Plan→Work, Work→Review, Review→Compound)
+
+```
+## 🔄 Phase Transition: [Previous] → [Next]
+
+### Previous Phase Assessment
+- **Objective met?** [Yes / Partially / No]
+- **Artifacts produced:** [list]
+- **Open issues carried forward:** [list or "none"]
+
+### Next Phase Readiness
+- [ ] Prerequisites satisfied
+- [ ] Context is clean (no stale noise)
+- [ ] Correct skills loaded for next phase
+
+**Proceed:** [Yes / Need to resolve: describe]
+```
+
+## Integration Points
+
+### In `/ship` (Phase 3 task loop)
+
+After every ceil(totalTasks / 2) tasks, run **Mid-Point Check**:
+
+```typescript
+const midpoint = Math.ceil(totalTasks / 2);
+if (completedTasks === midpoint) {
+  // Run mid-point reflection
+  // Log assessment to .beads/artifacts/$BEAD_ID/reflections.md
+}
+```
+
+Before each task completion claim, run **Completion Check** (lightweight — just the evidence audit).
+
+### In `/lfg` (phase transitions)
+
+At each step boundary (Plan→Work, Work→Review, Review→Compound), run **Phase Transition Check**.
+
+### Context pressure monitoring
+
+When context usage estimate exceeds 70%, run **Near-Limit Warning** regardless of task position.
+
+## Reflection Log
+
+Append all reflections to `.beads/artifacts/$BEAD_ID/reflections.md` (or session-level if no bead):
+
+```markdown
+## Reflection Log
+
+### [timestamp] Mid-Point Check
+
+Assessment: On track
+Context: ~45% used
+Adjustment: None
+
+### [timestamp] Completion Check — Task 3
+
+Verdict: Complete
+Evidence: typecheck pass, test pass (12/12)
+
+### [timestamp] Near-Limit Warning
+
+Decision: Compress and continue
+Deferred: Task 6 (cosmetic cleanup) → follow-up bead
+```
+
+## Gotchas
+
+- **Don't over-reflect** — these are quick self-checks, not long analyses. Each should take < 30 seconds of reasoning.
+- **Don't block on minor drift** — if drift is cosmetic (variable naming, style), note it and continue. Only pause for scope drift.
+- **Context cost** — each reflection adds ~200-400 tokens. Budget accordingly. Skip mid-point check for < 4 tasks.
+- **Not a replacement for verification** — reflections assess trajectory, not correctness. Always run actual verification commands.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "opencodekit",
-	"version": "0.20.6",
+	"version": "0.20.7",
 	"description": "CLI tool for bootstrapping and managing OpenCodeKit projects",
 	"keywords": [
 		"agents",