opencode-swarm 6.48.0 → 6.50.0

package/README.md

@@ -30,7 +30,7 @@ Most AI coding tools let one model write code and ask that same model whether th
 - 🔒 **Gated pipeline** — code never ships without reviewer + test engineer approval (bypassed in turbo mode)
 - 🔄 **Phase completion gates** — completion-verify and drift verifier gates enforced before phase completion (bypassed in turbo mode)
 - 🔁 **Resumable sessions** — all state saved to `.swarm/`; pick up any project any day
-- 🌐 **11 languages** — TypeScript, Python, Go, Rust, Java, Kotlin, C#, C/C++, Swift, Dart, Ruby
+- 🌐 **12 languages** — TypeScript, Python, Go, Rust, Java, Kotlin, C#, C/C++, Swift, Dart, Ruby, PHP
 - 🛡️ **Built-in security** — SAST, secrets scanning, dependency audit per task
 - 🆓 **Free tier** — works with OpenCode Zen's free model roster
 - ⚙️ **Fully configurable** — override any agent's model, disable agents, tune guardrails
@@ -69,16 +69,26 @@ All project state lives in `.swarm/`:
 
 ```text
 .swarm/
-├── plan.md              # Project roadmap with phases and tasks
-├── plan.json            # Structured plan data
-├── context.md           # Technical decisions and SME guidance
-├── events.jsonl         # Event stream for diagnostics
-├── evidence/            # Review/test evidence bundles per task
-├── telemetry.jsonl      # Session observability events (JSONL)
-├── curator-summary.json # Curator system state (if enabled)
-└── drift-report-phase-N.json  # Plan-vs-reality drift reports
+├── plan.md                        # Projected plan (generated from ledger)
+├── plan.json                      # Projected plan data (generated from ledger)
+├── plan-ledger.jsonl              # Durable append-only ledger — authoritative source of truth (v6.44)
+├── SWARM_PLAN.md                  # Export checkpoint artifact written on save_plan / phase_complete / close
+├── SWARM_PLAN.json                # Export checkpoint artifact (importable via importCheckpoint)
+├── context.md                     # Technical decisions and SME guidance
+├── spec.md                        # Feature specification (written by /swarm specify)
+├── close-summary.md               # Written by /swarm close with project summary
+├── close-lessons.md               # Optional: explicit session lessons for /swarm close to curate
+├── doc-manifest.json              # Documentation index built by doc_scan tool
+├── events.jsonl                   # Event stream for diagnostics
+├── evidence/                      # Review/test evidence bundles per task
+├── telemetry.jsonl                # Session observability events (JSONL)
+├── curator-summary.json           # Curator system state
+├── curator-briefing.md            # Curator init briefing injected at session start
+└── drift-report-phase-N.json      # Plan-vs-reality drift reports (Curator)
 ```
 
+> **Plan durability (v6.44):** `plan-ledger.jsonl` is the authoritative source of truth for plan state. `plan.json` and `plan.md` are projections derived from the ledger — if they are missing or stale, `loadPlan()` auto-rebuilds them from the ledger. `SWARM_PLAN.md` / `SWARM_PLAN.json` are export-only checkpoint artifacts written automatically — use `SWARM_PLAN.json` to restore if both `plan.json` and the ledger are lost.
+
 Swarm is resumable by design. If `.swarm/` already exists, the architect goes straight into **RESUME** → **EXECUTE** instead of repeating discovery.
 
 ---
@@ -312,6 +322,7 @@ When a task requires multiple coder attempts (e.g., reviewer rejections), Swarm
 | `/swarm diagnose` | Health check for swarm state, including config parsing, grammar files, checkpoint manifest, events stream integrity, and steering directive staleness |
 | `/swarm evidence 2.1` | Show review/test results for a specific task |
 | `/swarm history` | What's been completed so far |
+| `/swarm close [--prune-branches]` | Idempotent session close-out: writes retrospectives, curates lessons (reads `.swarm/close-lessons.md` if present), archives evidence, resets `context.md`, cleans config-backup files, optionally prunes merged branches |
 | `/swarm reset --confirm` | Start over (clears all swarm state) |
 
 ---
@@ -336,9 +347,9 @@ Agent roles (see [Agent Categories](#agent-categories) for classification refere
 | `architect` | Coordinates the workflow, writes plans, enforces gates | Always |
 | `explorer` | Scans the codebase and gathers context | Before planning, after phase wrap |
 | `sme` | Provides domain guidance | During planning / consultation |
-| `critic` | Reviews the plan before execution | Before coding starts |
-| `critic_sounding_board` | Pre-escalation pushback before user contact | When architect hits impasse |
-| `critic_drift_verifier` | Phase completion verifier (implementation matches plan) | Before phase_complete |
+| `critic` | Reviews the plan before execution and blocks coding until approved | Before coding starts (CRITIC-GATE mode) |
+| `critic_sounding_board` | Pre-escalation pushback — the architect consults this before contacting the user; returns UNNECESSARY / REPHRASE / APPROVED / RESOLVE | When architect hits an impasse |
+| `critic_drift_verifier` | **Phase-close drift detector**: verifies that the completed implementation still matches the original plan spec. Returns APPROVED or NEEDS_REVISION. When NEEDS_REVISION is returned, the phase is **blocked** — the architect must address deviations before calling `phase_complete`. After receiving the verdict, the architect calls `write_drift_evidence` to record the gate result. Bypassed in turbo mode. | Before `phase_complete` (PHASE-WRAP mode) |
 | `coder` | Implements one task at a time | During execution |
 | `reviewer` | Reviews correctness and security | After each task |
 | `test_engineer` | Writes and runs tests | After each task |
@@ -405,6 +416,9 @@ MODE: EXECUTE (per task)
 ├── 5j. @test_engineer (verification tests + coverage ≥70%)
 ├── 5k. @test_engineer (adversarial tests)
 ├── 5l. architect regression sweep (scope:"graph" to find cross-task test regressions)
+├── 5l-ter. test drift detection (conditional — fires when changes involve command behaviour,
+│         parsing/routing logic, user-visible output, public contracts, assertion-heavy areas,
+│         or helper lifecycle changes; validates tests still align with current behaviour)
 ├── 5m. ⛔ Pre-commit checklist (all 4 items required, no override)
 └── 5n. Task marked complete, evidence written
 ```
@@ -419,12 +433,12 @@ The architect moves through these modes automatically:
 |---|---|
 | `RESUME` | Existing `.swarm/` state was found, so Swarm continues where it left off |
 | `CLARIFY` | Swarm asks for missing information it cannot infer |
-| `DISCOVER` | Explorer scans the codebase |
+| `DISCOVER` | Explorer scans the codebase; co-change dark matter analysis runs automatically to detect hidden file couplings (v6.41) |
 | `CONSULT` | SME agents provide domain guidance |
 | `PLAN` | Architect writes or updates the phased plan (includes CODEBASE REALITY CHECK on brownfield projects) |
 | `CRITIC-GATE` | Critic reviews the plan before execution |
 | `EXECUTE` | Tasks are implemented one at a time through the QA pipeline |
-| `PHASE-WRAP` | A phase closes out, docs are updated, retrospective is written, and phase completion gates are enforced |
+| `PHASE-WRAP` | A phase closes out, including: explorer rescan, docs update, `context.md` update, `write_retro`, evidence check, `sbom_generate`, **`@critic_drift_verifier` delegation** (drift check — blocking gate), `write_drift_evidence` call with verdict, mandatory gate evidence verification (`completion-verify.json` + `drift-verifier.json` both required), then `phase_complete` |
 
 > **CODEBASE REALITY CHECK (v6.29.2):** Before any planning, the Architect dispatches Explorer to verify the current state of every referenced item. Produces a CODEBASE REALITY REPORT with statuses: NOT STARTED, PARTIALLY DONE, ALREADY COMPLETE, or ASSUMPTION INCORRECT. This prevents planning against stale assumptions. Skipped for greenfield projects with no existing codebase references.
 
@@ -491,6 +505,8 @@ Every completed task writes structured evidence to `.swarm/evidence/`:
 | diff | Files changed, additions/deletions |
 | retrospective | Phase metrics, lessons learned, error taxonomy classification (injected into next phase) |
 | secretscan | Secret scan results: findings count, files scanned, skipped files (v6.33) |
+| completion-verify | Deterministic gate: verifies plan task identifiers exist in source files (written automatically by `completion-verify` tool; required before `phase_complete`) |
+| drift-verifier | Phase-close drift gate: `critic_drift_verifier` verdict (APPROVED/NEEDS_REVISION) and summary (written by architect via `write_drift_evidence`; required before `phase_complete`) |
 
 ### telemetry.jsonl: Session Observability
 
@@ -832,7 +848,7 @@ To disable entirely, set `context_budget.enabled: false` in your swarm config.
 
 | Tool | What It Does |
 |------|-------------|
-| syntax_check | Tree-sitter validation across 11 languages |
+| syntax_check | Tree-sitter validation across 12 languages |
 | placeholder_scan | Catches TODOs, FIXMEs, stubs, placeholder text |
 | sast_scan | Offline security analysis, 63+ rules, 9 languages |
 | sbom_generate | CycloneDX dependency tracking, 8 ecosystems |
@@ -1119,6 +1135,7 @@ Control how tool outputs are summarized for LLM context.
 | `/swarm benchmark` | Performance benchmarks |
 | `/swarm retrieve [id]` | Retrieve auto-summarized tool outputs (supports offset/limit pagination) |
 | `/swarm reset --confirm` | Clear swarm state files |
+| `/swarm reset-session` | Clear session state files in `.swarm/session/` (preserves plan and context) |
 | `/swarm preflight` | Run phase preflight checks |
 | `/swarm config doctor [--fix]` | Config validation with optional auto-fix |
 | `/swarm doctor tools` | Tool registration coherence and binary readiness check |
@@ -1126,6 +1143,18 @@ Control how tool outputs are summarized for LLM context.
 | `/swarm specify [description]` | Generate or import a feature specification |
 | `/swarm clarify [topic]` | Clarify and refine an existing feature specification |
 | `/swarm analyze` | Analyze spec.md vs plan.md for requirement coverage gaps |
+| `/swarm close [--prune-branches]` | Idempotent session close-out: retrospectives, lesson curation, evidence archive, context.md reset, config-backup cleanup, optional branch pruning |
+| `/swarm write-retro` | Write a phase retrospective manually |
+| `/swarm handoff` | Generate a handoff summary for context-budget-critical sessions |
+| `/swarm simulate` | Simulate plan execution without writing code |
+| `/swarm promote` | Promote swarm-scoped knowledge to hive (global) knowledge |
+| `/swarm evidence summary` | Generate a summary across all evidence bundles with completion ratio and blockers |
+| `/swarm knowledge` | List knowledge entries |
+| `/swarm knowledge migrate` | Migrate knowledge entries to the current format |
+| `/swarm knowledge quarantine [id]` | Move a knowledge entry to quarantine |
+| `/swarm knowledge restore [id]` | Restore a quarantined knowledge entry |
+| `/swarm turbo` | Enable turbo mode for the current session (bypasses QA gates) |
+| `/swarm checkpoint` | Save a git checkpoint for the current state |
 
 </details>
 
@@ -1139,11 +1168,11 @@ Swarm limits which tools each agent can access based on their role. This prevent
 
 | Agent | Tools | Count | Rationale |
 |-------|-------|:---:|-----------|
-| **architect** | All 23 tools | 23 | Orchestrator needs full visibility |
-| **reviewer** | diff, imports, lint, pkg_audit, pre_check_batch, secretscan, symbols, complexity_hotspots, retrieve_summary, extract_code_blocks, test_runner | 11 | Security-focused QA |
-| **coder** | diff, imports, lint, symbols, extract_code_blocks, retrieve_summary | 6 | Write-focused, minimal read tools |
-| **test_engineer** | test_runner, diff, symbols, extract_code_blocks, retrieve_summary, imports, complexity_hotspots, pkg_audit | 8 | Testing and verification |
-| **explorer** | complexity_hotspots, detect_domains, extract_code_blocks, gitingest, imports, retrieve_summary, schema_drift, symbols, todo_extract | 9 | Discovery and analysis |
+| **architect** | All registered tools | — | Orchestrator needs full visibility |
+| **reviewer** | diff, imports, lint, pkg_audit, pre_check_batch, secretscan, symbols, complexity_hotspots, retrieve_summary, extract_code_blocks, test_runner, suggest_patch, batch_symbols | 13 | Security-focused QA |
+| **coder** | diff, imports, lint, symbols, extract_code_blocks, retrieve_summary, search | 7 | Write-focused, minimal read tools |
+| **test_engineer** | test_runner, diff, symbols, extract_code_blocks, retrieve_summary, imports, complexity_hotspots, pkg_audit, search | 9 | Testing and verification |
+| **explorer** | complexity_hotspots, detect_domains, extract_code_blocks, gitingest, imports, retrieve_summary, schema_drift, symbols, todo_extract, search, batch_symbols | 11 | Discovery and analysis |
 | **sme** | complexity_hotspots, detect_domains, extract_code_blocks, imports, retrieve_summary, schema_drift, symbols | 7 | Domain expertise research |
 | **critic** | complexity_hotspots, detect_domains, imports, retrieve_summary, symbols | 5 | Plan review, minimal toolset |
 | **docs** | detect_domains, doc_extract, doc_scan, extract_code_blocks, gitingest, imports, retrieve_summary, schema_drift, symbols, todo_extract | 10 | Documentation synthesis and discovery |
@@ -1203,8 +1232,10 @@ The following tools can be assigned to agents via overrides:
 
 | Tool | Purpose |
 |------|---------|
+| `batch_symbols` | Extract exported symbols from multiple files in a single call; per-file error isolation; 75–98% call reduction vs sequential (v6.45); registered for architect, explorer, reviewer |
 | `checkpoint` | Save/restore git checkpoints |
 | `check_gate_status` | Read-only query of task gate status |
+| `co_change_analyzer` | Scan git history for files that co-change frequently; generates dark matter architecture knowledge entries during DISCOVER mode (v6.41); architect-only |
 | `complexity_hotspots` | Identify high-risk code areas |
 | `declare_scope` | Pre-declare the file scope for the next coder delegation (architect-only); violations trigger warnings |
 | `detect_domains` | Detect SME domains from text |
@@ -1220,14 +1251,17 @@ The following tools can be assigned to agents via overrides:
 | `pkg_audit` | Security audit of dependencies |
 | `pre_check_batch` | Parallel pre-checks (lint, secrets, SAST, quality) |
 | `retrieve_summary` | Retrieve summarized tool outputs |
+| `save_plan` | Persist plan to `.swarm/plan.json`, `plan.md`, and ledger; also writes `SWARM_PLAN.md` / `SWARM_PLAN.json` checkpoint artifacts; requires explicit `working_directory` parameter |
 | `schema_drift` | Detect OpenAPI/schema drift |
+| `search` | Workspace-scoped ripgrep-style structured text search; literal and regex modes, glob filtering, result limits (v6.45); registered for architect, coder, reviewer, explorer, test_engineer |
 | `secretscan` | Scan for secrets in code |
+| `suggest_patch` | Generate contextual diff hunks without modifying files; read-only patch suggestions for reviewer→coder handoff (v6.45); registered for reviewer and architect |
 | `symbols` | Extract exported symbols |
 | `test_runner` | Run project tests |
 | `update_task_status` | Mark plan tasks as pending/in_progress/completed/blocked; track phase progress; acquires lock on `plan.json` before writing |
 | `todo_extract` | Extract TODO/FIXME comments |
 | `write_retro` | Document phase retrospectives via the phase_complete workflow; capture lessons learned |
-| `write_drift_evidence` | Write drift verification evidence after critic_drift_verifier completes |
+| `write_drift_evidence` | Write drift verification evidence after critic_drift_verifier completes; architect calls this after receiving the verifier’s verdict — the critic does not write files directly |
 
 ---
 
@@ -1236,8 +1270,34 @@ The following tools can be assigned to agents via overrides:
 
 > For the complete version history, see [CHANGELOG.md](CHANGELOG.md) or [docs/releases/](docs/releases/).
 
-### v6.41.0 — Drift Evidence Tool
+### v6.47.0 — `/swarm close` Full Session Close-Out
+
+- **`/swarm close` expanded**: Now performs complete close-out: resets `context.md`, deletes stale `config-backup-*.json` files, supports plan-free sessions (PR reviews, investigations), and accepts `--prune-branches` to delete local branches whose remote tracking ref is `gone` (merged/deleted upstream).
+- **Lesson injection**: If `.swarm/close-lessons.md` exists when `/swarm close` runs, the architect’s explicit lessons are curated into the knowledge base before the file is deleted.
+
+### v6.45.0 — New Search, Patch, and Batch Tools
+
+- **`search` tool**: Workspace-scoped ripgrep-style structured search with literal/regex modes and glob filtering. Registered for architect, coder, reviewer, explorer, test_engineer.
+- **`suggest_patch` tool**: Reviewer-safe context-anchored patch suggestion. Generates diff hunks without writing files. Registered for reviewer and architect.
+- **`batch_symbols` tool**: Batched symbol extraction from multiple files in one call; per-file error isolation; 75–98% call reduction vs sequential single-file calls. Registered for architect, explorer, reviewer.
+- **Step 5l-ter**: Test drift detection step added to the EXECUTE pipeline. Fires conditionally when changes involve command behaviour, parsing/routing logic, user-visible output, public contracts, assertion-heavy areas, or helper lifecycle changes.
+
+### v6.44.0 — Durable Plan Ledger
+
+- **`plan-ledger.jsonl`**: Append-only JSONL ledger is now the authoritative source of truth for plan state. `plan.json` and `plan.md` are projections derived from the ledger. `loadPlan()` auto-rebuilds projections from the ledger on hash mismatch.
+- **Checkpoint artifacts**: `writeCheckpoint()` writes `SWARM_PLAN.md` and `SWARM_PLAN.json` at the project root on every `save_plan`, `phase_complete`, and `/swarm close`. Use `SWARM_PLAN.json` to restore after data loss.
+- **Auto-generated tool lists**: Architect prompt `YOUR TOOLS` and `Available Tools` sections are now generated from `AGENT_TOOL_MAP.architect` — no more hand-maintained lists that drift.
+- See [docs/plan-durability.md](docs/plan-durability.md) for migration notes.
 
+### v6.42.0 — Curator LLM Delegation Wired
+
+- **Curator now performs real LLM analysis**: Previously the LLM delegation was scaffolded but never connected — every call fell through to data-only mode. All three call sites now invoke the Explorer agent with curator-specific system prompts.
+- **`curator.enabled` now defaults to `true`**: The curator falls back gracefully to data-only mode when no SDK client is available (e.g., in unit tests). If you relied on the previous `false` default, set `"curator": { "enabled": false }` explicitly.
+
+### v6.41.0 — Dark Matter Detection + `/swarm close` + Drift Evidence Tool
+
+- **Dark matter detection pipeline**: During DISCOVER mode, automatically scans git history for files that frequently co-change. Results are stored as `architecture` knowledge entries and the architect is guided to consider co-change partners when declaring scope. Silently skips repos with fewer than 20 commits or no git history.
+- **`/swarm close` command**: New idempotent close command. Writes retrospectives for in-progress phases, curates session lessons via the knowledge pipeline, archives evidence, marks phases/tasks as `closed`, writes `.swarm/close-summary.md`, and cleans state.
 - **`write_drift_evidence` tool**: New architect tool for persisting drift verification evidence after critic_drift_verifier delegation
   - Accepts phase number, verdict (APPROVED/NEEDS_REVISION), and summary
   - Normalizes verdict automatically (APPROVED → approved, NEEDS_REVISION → rejected)
@@ -1291,7 +1351,7 @@ The following tools can be assigned to agents via overrides:
 
 This release adds the optional Curator system for phase-level intelligence and fixes session snapshot persistence for task workflow states.
 
-- **Curator system**: New optional background analysis system (`curator.enabled = false` by default). After each phase, collects events, checks compliance, and writes drift reports to `.swarm/drift-report-phase-N.json`. Three integration points: init on first phase, phase analysis after each phase, and drift injection into architect context at phase start.
+- **Curator system**: Background analysis system (`curator.enabled = false` by default in v6.22; **changed to `true` in v6.42**). After each phase, collects events, checks compliance, and writes drift reports to `.swarm/drift-report-phase-N.json`. Three integration points: init on first phase, phase analysis after each phase, and drift injection into architect context at phase start.
 - **Drift reports**: `runCriticDriftCheck` compares planned vs. actual decisions and writes structured drift reports with alignment scores (`ALIGNED` / `MINOR_DRIFT` / `MAJOR_DRIFT` / `OFF_SPEC`). Latest drift summary is prepended to the architect's knowledge context each phase.
 - **Issue #81 fix — taskWorkflowStates persistence**: Session snapshots now correctly serialize and restore the per-task state machine. Invalid state values are filtered to `idle` on deserialization. `reconcileTaskStatesFromPlan` seeds task states from `plan.json` on snapshot load (completed → `tests_run`, in-progress → `coder_delegated`).
 
@@ -1423,7 +1483,7 @@ bun test
 
 ## Supported Languages
 
-OpenCode Swarm v6.16+ ships with language profiles for 11 languages across three quality tiers. All tools use graceful degradation — if a binary is not on PATH, the tool skips with a soft warning rather than a hard failure.
+OpenCode Swarm v6.46+ ships with language profiles for 12 languages across three quality tiers. All tools use graceful degradation — if a binary is not on PATH, the tool skips with a soft warning rather than a hard failure.
 
 | Language | Tier | Syntax | Build | Test | Lint | Audit | SAST |
 |---|:---:|:---:|:---:|:---:|:---:|:---:|:---:|
@@ -1438,6 +1498,9 @@ OpenCode Swarm v6.16+ ships with language profiles for 11 languages across three
 | Swift | 2 | ✅ | ✅ swift build | ✅ swift test | ✅ swiftlint | — | 🔶 Semgrep exp. |
 | Dart / Flutter | 3 | ✅ | ✅ dart pub | ✅ dart test | ✅ dart analyze | ✅ dart pub outdated | — |
 | Ruby | 3 | ✅ | — | ✅ RSpec / minitest | ✅ RuboCop | ✅ bundle-audit | 🔶 Semgrep exp. |
+| PHP / Laravel | 3 | ✅ | ✅ Composer install | ✅ PHPUnit / Pest / artisan test | ✅ Pint / PHP-CS-Fixer | ✅ composer audit | ✅ 10+ native rules |
+
+> **PHP + Laravel baseline**: PHP v6.49+ ships with deterministic Laravel project detection (multi-signal: `artisan` file, `laravel/framework` dependency, `config/app.php`). When detected, commands are automatically overridden to `php artisan test`, Pint formatting, and PHPStan static analysis. Laravel-specific SAST rules cover SQL injection via raw queries, mass-assignment vulnerabilities, and destructive migrations without rollback. `.blade.php` files are included in all scanning pipelines.
 
 **Tier definitions:**
 - **Tier 1** — Full pipeline: all tools integrated and tested end-to-end.
@@ -1450,9 +1513,11 @@ OpenCode Swarm v6.16+ ships with language profiles for 11 languages across three
 
 ## Curator
 
-The Curator is an optional background analysis system that runs after each phase. It is **disabled by default** (`curator.enabled = false`) and never blocks execution — all Curator operations are wrapped in try/catch.
+The Curator is a background analysis system that runs after each phase. It is **enabled by default** as of v6.42 (`curator.enabled = true`) and never blocks execution — all Curator operations are wrapped in try/catch. It falls back gracefully to data-only mode when no SDK client is available.
+
+Since v6.42, the Curator performs real LLM analysis by delegating to the Explorer agent with curator-specific prompts. Before v6.42, the LLM delegation was scaffolded but never wired.
 
-To enable, set `"curator": { "enabled": true }` in your config. When enabled, it writes `.swarm/curator-summary.json` and `.swarm/drift-report-phase-N.json` files.
+To disable, set `"curator": { "enabled": false }` in your config. When enabled, it writes `.swarm/curator-summary.json`, `.swarm/curator-briefing.md`, and `.swarm/drift-report-phase-N.json` files.
 
 ### What the Curator Does
 
@@ -1470,7 +1535,7 @@ Add a `curator` block to `.opencode/opencode-swarm.json`:
 ```json
 {
   "curator": {
-    "enabled": false,
+    "enabled": true,
     "init_enabled": true,
     "phase_enabled": true,
     "max_summary_tokens": 2000,
@@ -1484,7 +1549,7 @@ Add a `curator` block to `.opencode/opencode-swarm.json`:
 
 | Field | Default | Description |
 |-------|---------|-------------|
-| `enabled` | `false` | Master switch. Set to `true` to activate the Curator pipeline. |
+| `enabled` | `true` | Master switch. Set to `false` to disable the Curator pipeline. |
 | `init_enabled` | `true` | Initialize curator summary on first phase (requires `enabled: true`). |
 | `phase_enabled` | `true` | Run phase analysis and knowledge updates after each phase. |
 | `max_summary_tokens` | `2000` | Maximum token budget for curator knowledge summaries. |
@@ -1533,6 +1598,7 @@ Run `/swarm reset --confirm`.
 - [Getting Started](docs/getting-started.md)
 - [Architecture Deep Dive](docs/architecture.md)
 - [Design Rationale](docs/design-rationale.md)
+- [Plan Durability & Ledger](docs/plan-durability.md)
 - [Installation Guide](docs/installation.md)
 - [Linux + Docker Desktop Install Guide](docs/installation-linux-docker.md)
 - [LLM Operator Installation Guide](docs/installation-llm-operator.md)

package/dist/agents/explorer.d.ts

@@ -1,5 +1,5 @@
 import type { AgentDefinition } from './architect';
-export declare const CURATOR_INIT_PROMPT = "## IDENTITY\nYou are Explorer in CURATOR_INIT mode. You consolidate prior session knowledge into an architect briefing.\nDO NOT use the Task tool to delegate. You ARE the agent that does the work.\n\nINPUT FORMAT:\nTASK: CURATOR_INIT\nPRIOR_SUMMARY: [JSON or \"none\"]\nKNOWLEDGE_ENTRIES: [JSON array of high-confidence entries]\nPROJECT_CONTEXT: [context.md excerpt]\n\nACTIONS:\n- Read the prior summary to understand session history\n- Cross-reference knowledge entries against project context\n- Identify contradictions (knowledge says X, project state shows Y)\n- Produce a concise briefing for the architect\n\nRULES:\n- Output under 2000 chars\n- No code modifications\n- Flag contradictions explicitly with CONTRADICTION: prefix\n- If no prior summary exists, state \"First session \u2014 no prior context\"\n\nOUTPUT FORMAT:\nBRIEFING:\n[concise summary of prior session state, key decisions, active blockers]\n\nCONTRADICTIONS:\n- [entry_id]: [description] (or \"None detected\")\n\nKNOWLEDGE_STATS:\n- Entries reviewed: [N]\n- Prior phases covered: [N]\n";
-export declare const CURATOR_PHASE_PROMPT = "## IDENTITY\nYou are Explorer in CURATOR_PHASE mode. You consolidate a completed phase into a digest.\nDO NOT use the Task tool to delegate. You ARE the agent that does the work.\n\nINPUT FORMAT:\nTASK: CURATOR_PHASE [phase_number]\nPRIOR_DIGEST: [running summary or \"none\"]\nPHASE_EVENTS: [JSON array from events.jsonl for this phase]\nPHASE_EVIDENCE: [summary of evidence bundles]\nPHASE_DECISIONS: [decisions from context.md]\nAGENTS_DISPATCHED: [list]\nAGENTS_EXPECTED: [list from config]\n\nACTIONS:\n- Extend the prior digest with this phase's outcomes (do NOT regenerate from scratch)\n- Identify workflow deviations: missing reviewer, missing retro, skipped test_engineer\n- Recommend knowledge updates: entries to promote, archive, or flag as contradicted\n- Summarize key decisions and blockers resolved\n\nRULES:\n- Output under 2000 chars\n- No code modifications\n- Compliance observations are READ-ONLY \u2014 report, do not enforce\n- Extend the digest, never replace it\n\nOUTPUT FORMAT:\nPHASE_DIGEST:\nphase: [N]\nsummary: [what was accomplished]\nagents_used: [list]\ntasks_completed: [N]/[total]\nkey_decisions: [list]\nblockers_resolved: [list]\n\nCOMPLIANCE:\n- [type]: [description] (or \"No deviations observed\")\n\nKNOWLEDGE_UPDATES:\n- [action] new: [reason] (or \"No recommendations\")\nNOTE: Always use \"new\" as the token \u2014 existing entry IDs (UUID v4) are not available in this context. Any non-UUID token is treated as \"new\" by the parser. Only \"promote new:\" creates a new entry; \"archive new:\" and \"flag_contradiction new:\" are silently skipped because those actions require an existing entry to operate on.\n\nEXTENDED_DIGEST:\n[the full running digest with this phase appended]\n";
+export declare const CURATOR_INIT_PROMPT = "## IDENTITY\nYou are Explorer in CURATOR_INIT mode. You consolidate prior session knowledge into an architect briefing.\nDO NOT use the Task tool to delegate. You ARE the agent that does the work.\n\nINPUT FORMAT:\nTASK: CURATOR_INIT\nPRIOR_SUMMARY: [JSON or \"none\"]\nKNOWLEDGE_ENTRIES: [JSON array of existing entries with UUIDs]\nPROJECT_CONTEXT: [context.md excerpt]\n\nACTIONS:\n- Read the prior summary to understand session history\n- Cross-reference knowledge entries against project context\n- Identify contradictions (knowledge says X, project state shows Y)\n- Recommend rewrites for verbose or stale lessons\n- Produce a concise briefing for the architect\n\nRULES:\n- Output under 2000 chars\n- No code modifications\n- Flag contradictions explicitly with CONTRADICTION: prefix\n- If no prior summary exists, state \"First session \u2014 no prior context\"\n\nOUTPUT FORMAT:\nBRIEFING:\n[concise summary of prior session state, key decisions, active blockers]\n\nCONTRADICTIONS:\n- [entry_id]: [description] (or \"None detected\")\n\nKNOWLEDGE_UPDATES:\n- promote <uuid>: <reason>       (boost confidence, mark hive_eligible)\n- archive <uuid>: <reason>       (mark as archived \u2014 no longer injected)\n- rewrite <uuid>: <new lesson text>  (replace verbose/stale lesson with tighter version, max 280 chars)\n- flag_contradiction <uuid>: <reason>  (tag as contradicted)\n- promote new: <new lesson text>   (add a brand-new entry)\nUse the UUID from KNOWLEDGE_ENTRIES when archiving, rewriting, or flagging an existing entry. Use \"new\" only when recommending a brand-new entry.\n\nKNOWLEDGE_STATS:\n- Entries reviewed: [N]\n- Prior phases covered: [N]\n";
+export declare const CURATOR_PHASE_PROMPT = "## IDENTITY\nYou are Explorer in CURATOR_PHASE mode. You consolidate a completed phase into a digest.\nDO NOT use the Task tool to delegate. You ARE the agent that does the work.\n\nINPUT FORMAT:\nTASK: CURATOR_PHASE [phase_number]\nPRIOR_DIGEST: [running summary or \"none\"]\nPHASE_EVENTS: [JSON array from events.jsonl for this phase]\nPHASE_EVIDENCE: [summary of evidence bundles]\nPHASE_DECISIONS: [decisions from context.md]\nAGENTS_DISPATCHED: [list]\nAGENTS_EXPECTED: [list from config]\nKNOWLEDGE_ENTRIES: [JSON array of existing entries with UUIDs]\n\nACTIONS:\n- Extend the prior digest with this phase's outcomes (do NOT regenerate from scratch)\n- Identify workflow deviations: missing reviewer, missing retro, skipped test_engineer\n- Recommend knowledge updates: entries to promote, archive, rewrite, or flag as contradicted\n- Summarize key decisions and blockers resolved\n\nRULES:\n- Output under 2000 chars\n- No code modifications\n- Compliance observations are READ-ONLY \u2014 report, do not enforce\n- Extend the digest, never replace it\n\nOUTPUT FORMAT:\nPHASE_DIGEST:\nphase: [N]\nsummary: [what was accomplished]\nagents_used: [list]\ntasks_completed: [N]/[total]\nkey_decisions: [list]\nblockers_resolved: [list]\n\nCOMPLIANCE:\n- [type]: [description] (or \"No deviations observed\")\n\nKNOWLEDGE_UPDATES:\n- promote <uuid>: <reason>       (boost confidence, mark hive_eligible)\n- archive <uuid>: <reason>       (mark as archived \u2014 no longer injected)\n- rewrite <uuid>: <new lesson text>  (replace verbose/stale lesson with tighter version, max 280 chars)\n- flag_contradiction <uuid>: <reason>  (tag as contradicted)\n- promote new: <new lesson text>   (add a brand-new entry)\nUse the UUID from KNOWLEDGE_ENTRIES when archiving, rewriting, or flagging an existing entry. Use \"new\" only when recommending a brand-new entry.\n\nEXTENDED_DIGEST:\n[the full running digest with this phase appended]\n";
 export declare function createExplorerAgent(model: string, customPrompt?: string, customAppendPrompt?: string): AgentDefinition;
 export declare function createExplorerCuratorAgent(model: string, mode: 'CURATOR_INIT' | 'CURATOR_PHASE', customAppendPrompt?: string): AgentDefinition;

package/dist/background/plan-sync-worker.d.ts

@@ -8,7 +8,7 @@
 export interface PlanSyncWorkerOptions {
     /** Directory containing .swarm folder (defaults to cwd) */
     directory?: string;
-    /** Debounce delay in ms (default: 300ms) */
+    /** Debounce delay in ms (default: 500ms) */
     debounceMs?: number;
     /** Polling interval in ms when fs.watch fails (default: 2000ms) */
     pollIntervalMs?: number;

package/dist/cli/index.js

@@ -16517,25 +16517,33 @@ async function loadPlan(directory) {
         if (await ledgerExists(directory)) {
           const planHash = computePlanHash(validated);
           const ledgerHash = await getLatestLedgerHash(directory);
-          if (ledgerHash !== "" && planHash !== ledgerHash) {
-            const currentPlanId = `${validated.swarm}-${validated.title}`.replace(/[^a-zA-Z0-9-_]/g, "_");
-            const ledgerEvents = await readLedgerEvents(directory);
-            const firstEvent = ledgerEvents.length > 0 ? ledgerEvents[0] : null;
-            if (firstEvent && firstEvent.plan_id !== currentPlanId) {
-              warn(`[loadPlan] Ledger identity mismatch (ledger: ${firstEvent.plan_id}, plan: ${currentPlanId}) \u2014 skipping ledger rebuild (migration detected). Use /swarm reset-session to reinitialize the ledger.`);
-            } else {
-              warn("[loadPlan] plan.json is stale (hash mismatch with ledger) \u2014 rebuilding from ledger. If this recurs, run /swarm reset-session to clear stale session state.");
-              try {
-                const rebuilt = await replayFromLedger(directory);
-                if (rebuilt) {
-                  await rebuildPlan(directory, rebuilt);
-                  warn("[loadPlan] Rebuilt plan from ledger. Checkpoint available at SWARM_PLAN.md if it exists.");
-                  return rebuilt;
+          const resolvedWorkspace = path8.resolve(directory);
+          if (!startupLedgerCheckedWorkspaces.has(resolvedWorkspace)) {
+            startupLedgerCheckedWorkspaces.add(resolvedWorkspace);
+            if (ledgerHash !== "" && planHash !== ledgerHash) {
+              const currentPlanId = `${validated.swarm}-${validated.title}`.replace(/[^a-zA-Z0-9-_]/g, "_");
+              const ledgerEvents = await readLedgerEvents(directory);
+              const firstEvent = ledgerEvents.length > 0 ? ledgerEvents[0] : null;
+              if (firstEvent && firstEvent.plan_id !== currentPlanId) {
+                warn(`[loadPlan] Ledger identity mismatch (ledger: ${firstEvent.plan_id}, plan: ${currentPlanId}) \u2014 skipping ledger rebuild (migration detected). Use /swarm reset-session to reinitialize the ledger.`);
+              } else {
+                warn("[loadPlan] plan.json is stale (hash mismatch with ledger) \u2014 rebuilding from ledger. If this recurs, run /swarm reset-session to clear stale session state.");
+                try {
+                  const rebuilt = await replayFromLedger(directory);
+                  if (rebuilt) {
+                    await rebuildPlan(directory, rebuilt);
+                    warn("[loadPlan] Rebuilt plan from ledger. Checkpoint available at SWARM_PLAN.md if it exists.");
+                    return rebuilt;
+                  }
+                } catch (replayError) {
+                  warn(`[loadPlan] Ledger replay failed during hash-mismatch rebuild: ${replayError instanceof Error ? replayError.message : String(replayError)}. Returning stale plan.json. To recover: check SWARM_PLAN.md for a checkpoint, or run /swarm reset-session.`);
                 }
-              } catch (replayError) {
-                warn(`[loadPlan] Ledger replay failed during hash-mismatch rebuild: ${replayError instanceof Error ? replayError.message : String(replayError)}. Returning stale plan.json. To recover: check SWARM_PLAN.md for a checkpoint, or run /swarm reset-session.`);
               }
             }
+          } else if (ledgerHash !== "" && planHash !== ledgerHash) {
+            if (process.env.DEBUG_SWARM) {
+              console.warn(`[loadPlan] Ledger hash mismatch during active session for ${resolvedWorkspace} \u2014 skipping rebuild (startup check already performed).`);
+            }
           }
         }
         return validated;
@@ -17028,11 +17036,13 @@ function migrateLegacyPlan(planContent, swarmId) {
   };
   return plan;
 }
+var startupLedgerCheckedWorkspaces;
 var init_manager2 = __esm(() => {
   init_plan_schema();
   init_utils2();
   init_utils();
   init_ledger();
+  startupLedgerCheckedWorkspaces = new Set;
 });
 
 // src/services/config-doctor.ts
@@ -18665,6 +18675,8 @@ var KnowledgeConfigSchema = exports_external.object({
   hive_max_entries: exports_external.number().min(1).max(1e5).default(200),
   auto_promote_days: exports_external.number().min(1).max(3650).default(90),
   max_inject_count: exports_external.number().min(0).max(50).default(5),
+  inject_char_budget: exports_external.number().min(200).max(1e4).default(2000),
+  max_lesson_display_chars: exports_external.number().min(40).max(280).default(120),
   dedup_threshold: exports_external.number().min(0).max(1).default(0.6),
   scope_filter: exports_external.array(exports_external.string()).default(["global"]),
   hive_enabled: exports_external.boolean().default(true),
@@ -35627,37 +35639,80 @@ LANGUAGE_REGISTRY.register({
   id: "php",
   displayName: "PHP",
   tier: 3,
-  extensions: [".php", ".phtml"],
+  extensions: [".php", ".phtml", ".blade.php"],
   treeSitter: { grammarId: "php", wasmFile: "tree-sitter-php.wasm" },
   build: {
     detectFiles: ["composer.json"],
-    commands: []
+    commands: [
+      {
+        name: "Composer Install",
+        cmd: "composer install --no-interaction --prefer-dist",
+        detectFile: "composer.json",
+        priority: 1
+      }
+    ]
   },
   test: {
-    detectFiles: ["phpunit.xml", "phpunit.xml.dist"],
+    detectFiles: ["Pest.php", "phpunit.xml", "phpunit.xml.dist"],
     frameworks: [
+      {
+        name: "Pest",
+        detect: "Pest.php",
+        cmd: "vendor/bin/pest",
+        priority: 1
+      },
       {
         name: "PHPUnit",
         detect: "phpunit.xml",
         cmd: "vendor/bin/phpunit",
-        priority: 1
+        priority: 3
+      },
+      {
+        name: "PHPUnit",
+        detect: "phpunit.xml.dist",
+        cmd: "vendor/bin/phpunit",
+        priority: 4
       }
     ]
   },
   lint: {
-    detectFiles: [".php-cs-fixer.php", "phpcs.xml"],
+    detectFiles: [
+      "phpstan.neon",
+      "phpstan.neon.dist",
+      "pint.json",
+      ".php-cs-fixer.php",
+      "phpcs.xml"
+    ],
     linters: [
+      {
+        name: "PHPStan",
+        detect: "phpstan.neon",
+        cmd: "vendor/bin/phpstan analyse",
+        priority: 1
+      },
+      {
+        name: "PHPStan",
+        detect: "phpstan.neon.dist",
+        cmd: "vendor/bin/phpstan analyse",
+        priority: 2
+      },
+      {
+        name: "Pint",
+        detect: "pint.json",
+        cmd: "vendor/bin/pint --test",
+        priority: 3
+      },
       {
         name: "PHP-CS-Fixer",
         detect: ".php-cs-fixer.php",
         cmd: "vendor/bin/php-cs-fixer fix --dry-run --diff",
-        priority: 1
+        priority: 4
       }
     ]
   },
   audit: {
     detectFiles: ["composer.lock"],
-    command: "composer audit --format=json",
+    command: "composer audit --locked --format=json",
     outputFormat: "json"
   },
   sast: { nativeRuleSet: "php", semgrepSupport: "ga" },
@@ -35666,13 +35721,25 @@ LANGUAGE_REGISTRY.register({
       "Follow PSR-12 coding standards",
       "Use strict types declaration: declare(strict_types=1)",
       "Prefer type hints and return type declarations on all functions",
-      "Use dependency injection over static methods and singletons"
+      "Use dependency injection over static methods and singletons",
+      "Prefer named constructors and value objects over primitive obsession"
     ],
     reviewerChecklist: [
       "Verify no user input reaches SQL queries without parameterised binding",
       "Check for XSS \u2014 all output must be escaped with htmlspecialchars()",
       "Confirm no eval(), exec(), or shell_exec() with user-controlled input",
-      "Validate proper error handling \u2014 no bare catch blocks that swallow errors"
+      "Validate proper error handling \u2014 no bare catch blocks that swallow errors",
+      "Challenge any PHP/Laravel documentation or README claim that exceeds what is implemented and CI-verified in v6.49.0 (composer build, PHPUnit/Pest/artisan test, Pint/PHP-CS-Fixer lint, PHPStan static analysis, composer audit, Laravel detection, Blade scanning, 3 Laravel SAST rules). If a PR adds docs claiming broader support, verify it is backed by tests."
+    ],
+    testConstraints: [
+      "Prefer feature tests for HTTP, middleware, and authentication flows \u2014 use Laravel RefreshDatabase or DatabaseTransactions traits",
+      "Use unit tests for isolated business logic classes that do not require the full Laravel application container",
+      "Pest and PHPUnit coexist in many Laravel repos \u2014 php artisan test runs both; do not assume PHPUnit-only",
+      "Use .env.testing for test environment configuration; run php artisan config:clear when environment changes affect tests",
+      "For database tests, prefer RefreshDatabase over manual setUp/tearDown to avoid state leakage between tests",
+      "Run php artisan config:clear and php artisan cache:clear before running tests if environment variables changed",
+      "Use separate .env.testing file for test-specific configuration; never rely on .env for CI test runs",
+      "For parallel testing with php artisan test --parallel, ensure database connections use separate databases per worker (APP_ENV=testing + test database suffix pattern)"
     ]
   }
 });
@@ -35813,6 +35880,17 @@ var ECOSYSTEMS = [
       { command: "make", priority: 1 },
       { command: "cmake -B build && cmake --build build", priority: 2 }
     ]
+  },
+  {
+    ecosystem: "php-composer",
+    buildFiles: ["composer.json"],
+    toolchainCommands: ["composer"],
+    commands: [
+      {
+        command: "composer install --no-interaction --prefer-dist",
+        priority: 1
+      }
+    ]
   }
 ];
 var PROFILE_TO_ECOSYSTEM_NAMES = {
@@ -35826,7 +35904,8 @@ var PROFILE_TO_ECOSYSTEM_NAMES = {
   cpp: ["cpp"],
   swift: ["swift"],
   dart: ["dart"],
-  ruby: []
+  ruby: [],
+  php: ["php-composer"]
 };
 var toolchainCache = new Map;
 function isCommandAvailable(command) {

package/dist/config/schema.d.ts

@@ -415,6 +415,8 @@ export declare const KnowledgeConfigSchema: z.ZodObject<{
     hive_max_entries: z.ZodDefault<z.ZodNumber>;
     auto_promote_days: z.ZodDefault<z.ZodNumber>;
     max_inject_count: z.ZodDefault<z.ZodNumber>;
+    inject_char_budget: z.ZodDefault<z.ZodNumber>;
+    max_lesson_display_chars: z.ZodDefault<z.ZodNumber>;
     dedup_threshold: z.ZodDefault<z.ZodNumber>;
     scope_filter: z.ZodDefault<z.ZodArray<z.ZodString>>;
     hive_enabled: z.ZodDefault<z.ZodBoolean>;
@@ -778,6 +780,8 @@ export declare const PluginConfigSchema: z.ZodObject<{
         hive_max_entries: z.ZodDefault<z.ZodNumber>;
         auto_promote_days: z.ZodDefault<z.ZodNumber>;
         max_inject_count: z.ZodDefault<z.ZodNumber>;
+        inject_char_budget: z.ZodDefault<z.ZodNumber>;
+        max_lesson_display_chars: z.ZodDefault<z.ZodNumber>;
         dedup_threshold: z.ZodDefault<z.ZodNumber>;
         scope_filter: z.ZodDefault<z.ZodArray<z.ZodString>>;
         hive_enabled: z.ZodDefault<z.ZodBoolean>;

package/dist/hooks/curator-types.d.ts

@@ -36,7 +36,7 @@ export interface ComplianceObservation {
     severity: 'info' | 'warning';
 }
 export interface KnowledgeRecommendation {
-    action: 'promote' | 'archive' | 'flag_contradiction';
+    action: 'promote' | 'archive' | 'flag_contradiction' | 'rewrite';
     entry_id?: string;
     lesson: string;
     reason: string;

package/dist/hooks/knowledge-types.d.ts

@@ -65,6 +65,10 @@ export interface KnowledgeConfig {
     auto_promote_days: number;
     /** Maximum knowledge entries to inject per architect message. Default: 5 */
     max_inject_count: number;
+    /** Maximum total chars for the entire injection block. Default: 2000 */
+    inject_char_budget?: number;
+    /** Maximum display chars per lesson at injection time. Default: 120 */
+    max_lesson_display_chars?: number;
     /** Jaccard bigram similarity threshold for deduplication. Default: 0.6 */
     dedup_threshold: number;
     /** Scope filters to apply when reading knowledge. Default: ['global'] */