opencastle 0.32.5 → 0.32.6

package/src/orchestrator/skills/session-checkpoints/SKILL.md

@@ -3,25 +3,19 @@ name: session-checkpoints
 description: "Protocol for saving and restoring session state across agent sessions. Enables replay, fork, and resume of interrupted work — inspired by Sandcastle Run Time Machine."
 ---
 
-<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .opencastle/ directory instead. -->
-
 # Skill: Session Checkpoints
 
-Use this skill when working on multi-session features or when a session may be interrupted. Checkpoints allow any future session to resume work without re-analyzing the entire codebase.
-
 ## When to Checkpoint
 
-Create a checkpoint:
-
-- **Before delegation** — After decomposition but before first agent delegation
-- **After each phase** — When a group of parallel tasks completes
-- **Before risky work** — Before DB migrations, large refactors, or security changes
-- **On session end** — Always checkpoint before ending a session with incomplete work
-- **On interruption** — If context is running low, checkpoint immediately
-
-## Checkpoint Format
+| Trigger | Action |
+|---------|--------|
+| Before first delegation | After decomposition, before agents start |
+| After each phase | When a parallel batch completes |
+| Before risky work | DB migrations, large refactors, security changes |
+| Session end | Any session with incomplete work |
+| Context running low | Checkpoint immediately |
 
-Create or update the file `.opencastle/SESSION-CHECKPOINT.md` with this structure:
+## Checkpoint Format (`.opencastle/SESSION-CHECKPOINT.md`)
 
 ```markdown
 # Session Checkpoint
@@ -29,105 +23,69 @@ Create or update the file `.opencastle/SESSION-CHECKPOINT.md` with this structur
 **Last Updated:** YYYY-MM-DD HH:MM
 **Feature:** Short feature name
 **Branch:** git branch name
-**Tracker Issues:** TAS-XX, TAS-YY, TAS-ZZ
+**Tracker Issues:** TAS-XX, TAS-YY
 
 ## Current Phase
 
-Phase N of M — Brief description of what this phase does
-
 ## Completed Work
 
 | Task | Tracker | Agent | Status | Files |
 |------|---------|-------|--------|-------|
-| Description | TAS-XX | Agent Name | ✅ Done | file1.ts, file2.ts |
-| Description | TAS-YY | Agent Name | ✅ Done | file3.ts |
+| Description | TAS-XX | Agent | ✅ Done | file1.ts |
 
 ## In Progress
 
 | Task | Tracker | Agent | Status | Notes |
 |------|---------|-------|--------|-------|
-| Description | TAS-ZZ | Agent Name | 🔄 In Progress | What's been done so far |
+| Description | TAS-ZZ | Agent | 🔄 In Progress | what's done |
 
 ## Remaining Work
 
 | Task | Tracker | Agent | Dependencies | Files |
 |------|---------|-------|-------------|-------|
-| Description | TAS-AA | Agent Name | TAS-ZZ | file4.ts, file5.ts |
+| Description | TAS-AA | Agent | TAS-ZZ | file4.ts |
 
 ## Pending Approvals
 
-Approval requests posted to the messaging provider that haven't been answered yet.
-The `on-session-start` hook checks for replies when a new session begins.
-
 | Provider | Channel | Thread ID | Question | Posted At |
 |----------|---------|-----------|----------|-----------|
 | slack | C0AHAQFJ7C1 | 1772393542.345149 | Run migration on production? | 2026-03-01 14:30 |
 
-If the user answered in the VS Code chat during the previous session, remove
-the row from this table — the approval was already resolved.
-
-## Key Decisions Made
-
-- Decision 1: Why this approach was chosen
-- Decision 2: Why alternative X was rejected
+Remove row once answered (VS Code chat reply also counts as resolved).
 
-## Blockers & Issues
+## Decisions & Blockers
 
-- Blocker 1: Description and what's needed to unblock
-- Issue found: DLQ-XXX reference if logged
+- Decision: rationale
+- Blocker: what's needed to unblock
 
 ## Delegation Cost Log
 
-Track each delegation to monitor budget and optimize future model assignments:
-
 | # | Agent | Tracker | Model Tier | Est. Tokens | Duration | Status |
-|---|-------|--------|------------|-------------|----------|--------|
+|---|-------|---------|------------|-------------|----------|--------|
 | 1 | Content Engineer | TAS-XX | Standard | ~20K | 8 min | ✅ Done |
-| 2 | DB Engineer | TAS-YY | Standard | ~25K | 12 min | ✅ Done |
-| 3 | UI Expert | TAS-ZZ | Standard | ~30K | ❌ Failed → retry |
-
-**Running totals:** 3 delegations / ~75K tokens / 0 panel reviews
 
 ## File Partitions
 
 ```
 Agent A: dir1/, dir2/
-Agent B: dir3/, dir4/
-Agent C: .opencastle/
+Agent B: dir3/
 ```
 
 ## Resume Instructions
 
-Step-by-step instructions for a new session to pick up where this one left off:
-
 1. Check out branch `feat/xxx`
-2. Read tracker issues TAS-XX, TAS-YY for context
+2. Read tracker issues TAS-XX for context
 3. Start Phase N+1: [specific instructions]
 ```
 
-## Resuming from a Checkpoint
-
-When starting a new session:
-
-1. **Check for checkpoint** — Read `.opencastle/SESSION-CHECKPOINT.md` if it exists
-2. **Verify state** — Run `git status`, check branch, verify files match checkpoint
-3. **Check tracker** — List in-progress and todo issues for current feature
-4. **Follow resume instructions** — Execute the specific steps listed in the checkpoint
-5. **Update checkpoint** — After resuming, update the checkpoint with current progress
-
-## Cleanup
-
-After a feature is fully complete (all tracker issues Done):
+## Resuming
 
-1. Archive the checkpoint content to the relevant tracker issue comments
-2. Delete `.opencastle/SESSION-CHECKPOINT.md` to keep the workspace clean
-3. The next feature starts with a fresh checkpoint
+Read checkpoint → `git status` → check tracker → follow resume instructions → update progress.
 
-## Integration with Team Lead
+## Cleanup & Team Lead
 
-The Team Lead should:
+When all issues Done: archive to tracker, delete `.opencastle/SESSION-CHECKPOINT.md`.
 
-- Create a checkpoint after Step 2 (Decompose & Partition) of the Decomposition Flow
-- Update the checkpoint after each verification pass
-- Include checkpoint reading in session resume workflow
-- Reference the checkpoint file in delegation prompts for context
+- Checkpoint after decomposition (Step 2 of Decomposition Flow)
+- Update after each verification pass
+- Reference checkpoint in delegation prompts

package/src/orchestrator/skills/team-lead-reference/SKILL.md

@@ -3,206 +3,100 @@ name: team-lead-reference
 description: "Reference data for Team Lead orchestration — model routing, pre-delegation checks, cost tracking template, and DLQ format. Load when starting a delegation session."
 ---
 
-<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .opencastle/ directory instead. -->
-
 # Team Lead Reference
 
 For the specialist agent registry and model assignments, see [agent-registry.md](../../.opencastle/agents/agent-registry.md).
 
 ## Cost-Aware Model Routing
 
-Choose models deliberately based on task complexity. Not every task needs the most expensive model.
-
-### Model Cost Tiers
-
 | Tier | Cost | Use For |
 |------|------|---------|
 | **Premium** | $$$$ | Team Lead orchestration, highest-stakes decisions |
-| **Quality** | $$$ | Feature implementation, UI/frontend, security audits, architecture, complex reasoning |
-| **Standard** | $$ | Large-scale analysis, schema design, cost-efficient coding, repo-level exploration |
+| **Quality** | $$$ | Feature implementation, UI/frontend, security, architecture, complex reasoning |
+| **Standard** | $$ | Large-scale analysis, schema design, cost-efficient coding, repo exploration |
 | **Fast** | $$ | Terminal-heavy tasks, E2E tests, data pipelines, agentic workflows |
-| **Economy** | $ | Documentation, simple config changes, formatting, boilerplate |
+| **Economy** | $ | Docs, simple config, formatting, boilerplate |
 
-### Selection Rules
-
-1. **Default to the agent's assigned model** — the registry maps tasks to appropriate tiers
-2. **Downgrade when possible** — If a task is pure docs/config with no reasoning needed, prefer Economy tier
-3. **Upgrade for ambiguity** — If the task involves security, architecture decisions, or complex tradeoffs, use Quality/Premium
-4. **Never use Premium/Quality for boilerplate** — Writing test scaffolding, updating docs, or config changes should use Economy/Fast/Standard
-5. **Parallel sub-agents are cost multipliers** — When firing 3+ parallel sub-agents, prefer Economy/Fast/Standard unless precision is critical
+**Selection:** Default to agent's assigned tier. Downgrade pure docs/config → Economy. Upgrade security/architecture ambiguity → Quality/Premium. Never Premium/Quality for boilerplate. 3+ parallel agents → prefer Economy/Fast/Standard.
 
 ## Complexity-Based Task Scoring
 
-During decomposition, assign a **complexity score** (Fibonacci: 1, 2, 3, 5, 8, 13) to each subtask. The score determines which model tier handles the task.
-
-### Scoring Criteria
-
-| Factor | Low (1-2) | Medium (3-5) | High (8-13) |
-|--------|-----------|--------------|-------------|
-| **Files touched** | 1-2 files | 3-5 files | 6+ files or cross-library |
-| **Reasoning depth** | Mechanical / boilerplate | Pattern matching, moderate logic | Architecture decisions, security, tradeoffs |
-| **Ambiguity** | Clear spec, obvious approach | Some judgment calls | Multiple valid approaches, needs exploration |
-| **Risk** | No data loss, easily reversible | Moderate impact, testable | DB migrations, auth changes, breaking changes |
-| **Dependencies** | None | 1-2 upstream tasks | Complex dependency chain |
-
-### Score to Model Tier Mapping
+| Factor | Low → High |
+|--------|------------|
+| **Files touched** | 1–2 → 3–5 → 6+ / cross-library |
+| **Reasoning depth** | Boilerplate → pattern matching → architecture/security/tradeoffs |
+| **Ambiguity** | Clear spec → some judgment → multiple valid approaches |
+| **Risk** | Reversible → moderate impact → DB/auth/breaking |
+| **Dependencies** | None → 1–2 upstream → complex chain |
 
 | Score | Tier | Examples |
 |-------|------|----------|
-| **1-2** | Economy/Fast | Docs update, config tweak, rename, simple test |
-| **3-5** | Standard/Quality | Component build, CMS query, API route, migration |
-| **8** | Quality | Architecture decision, security audit, complex refactor |
-| **13** | Quality + Panel | DB migration with data transform, auth flow redesign |
-
-### Override Rules
+| 1–2 | Economy/Fast | Docs update, config tweak, rename, simple test |
+| 3–5 | Standard/Quality | Component, CMS query, API route, migration |
+| 8 | Quality | Architecture decision, security audit, complex refactor |
+| 13 | Quality + Panel | DB migration with data transform, auth flow redesign |
 
-- **Blocker tasks** (blocking 2+ downstream tasks): Upgrade one tier regardless of score
-- **Security-touching tasks**: Always Quality or higher, regardless of score
-- **Pure documentation**: Always Economy, regardless of estimated scope
-- The agent registry default model takes precedence unless the task complexity clearly warrants an upgrade/downgrade
+**Overrides:** Blocker (blocking 2+ downstream) → upgrade one tier. Security-touching → Quality+. Pure docs → Economy. Registry default takes precedence unless complexity clearly warrants change.
 
 ## Deepen-Plan Protocol
 
-After initial decomposition, **enrich the plan** with concrete codebase evidence before delegating. This prevents agents from wasting time on discovery that the Team Lead can do upfront.
-
-### When to Deepen
-
 | Plan Complexity | Action |
 |----------------|--------|
-| 1-2 subtasks, familiar area | Skip — proceed directly to delegation |
-| 3-5 subtasks, mixed familiarity | Quick deepen — single Researcher sub-agent |
-| 6+ subtasks, unfamiliar area | Full deepen — parallel Researcher sub-agents |
-
-### Quick Deepen (Single Researcher)
+| 1–2 subtasks, familiar | Skip — delegate directly |
+| 3–5 subtasks, mixed | Quick deepen — single Researcher sub-agent |
+| 6+ subtasks, unfamiliar | Full deepen — parallel Researcher sub-agents |
 
-Fire one **Researcher** sub-agent with this prompt:
-
-```
-Research the following planned subtasks and enrich each with:
-1. Exact file paths and line numbers for code that will change
-2. Existing patterns to follow (with file:line examples)
-3. Related lessons from .opencastle/LESSONS-LEARNED.md
-4. Risks or blockers (missing dependencies, known issues)
-
-Subtasks:
-- [Subtask 1 description]
-- [Subtask 2 description]
-- ...
-
-Return a structured report per subtask.
-```
-
-### Full Deepen (Parallel Researchers)
-
-For large plans, split research by domain and fire parallel Researcher sub-agents. See [agent-registry.md](../../.opencastle/agents/agent-registry.md) for project-specific scope examples.
-
-### What Deepening Produces
-
-After deepening, each subtask in the plan should have:
+**Quick deepen:** Fire one Researcher for exact file paths & line numbers, patterns to follow (file:line examples), relevant lessons from `LESSONS-LEARNED.md`, and risks/blockers per subtask.
+**Full deepen:** Split by domain into parallel Researchers. See [agent-registry.md](../../.opencastle/agents/agent-registry.md) for scope examples.
 
 | Field | Before Deepen | After Deepen |
-|-------|--------------|--------------|
-| **Files** | "some component" | Exact file path with line range |
-| **Pattern** | "follow existing style" | Specific file:line reference to follow |
+|-------|--------------|------------------|
+| **Files** | "some component" | Exact path + line range |
+| **Pattern** | "follow existing style" | Specific file:line reference |
 | **Risks** | unknown | Known issues identified |
 | **Lessons** | unchecked | Relevant lessons applied |
 | **Dependencies** | assumed | Verified with exact imports |
 
-### Integrating Results
+## Agent Output Status Handling
 
-Take the Researcher output and update delegation prompts with concrete file paths, patterns, and lessons. This transforms vague prompts into precise instructions that agents can execute without discovery overhead.
+| Status | Action |
+|--------|--------|
+| Complete | All AC addressed → fast review |
+| Complete with concerns | Resolve correctness/scope before review |
+| Needs context | Provide info, re-dispatch same agent |
+| Blocked | Provide context/upgrade model/escalate; never re-dispatch unchanged |
 
 ## Pre-Delegation Policy Checks
 
-See the Team Lead agent file § Pre-Delegation Checks for the mandatory 5-point checklist (tracker issue, file partition, dependencies, prompt specifics, self-improvement reminder).
-
-**Additional checks for feature work:** (6) Known issues reviewed, (7) Architecture docs read, (8) Existing code searched.
-
-**Additional checks for high-risk work:** (9) Panel review planned, (10) Rollback path identified.
-
-## Cost Tracking Convention
-
-After completing a feature (all tracker issues Done), add a cost summary to the roadmap update:
-
-```markdown
-**Cost Summary:**
-| Metric | Value |
-|--------|-------|
-| Sub-agent delegations | X |
-| Background agent delegations | X |
-| Panel reviews | X |
-| Model tiers used | Premium: X, Standard: X, Utility: X, Economy: X |
-| Upgrades/downgrades | [reason if any] |
-| Est. total tokens | ~XXK |
+See Team Lead agent § Pre-Delegation Checks for the mandatory 5-point checklist.
+- **Feature work** adds: (6) Known issues reviewed, (7) Architecture docs read, (8) Existing code searched.
+- **High-risk work** adds: (9) Panel review planned, (10) Rollback path identified.
+
+## Compact Delegation Envelope
+
+```json
+{
+  "tracker": "TAS-XX",
+  "agent": "Agent Name",
+  "objective": "One sentence: what to do and why.",
+  "files": ["path/to/file.ts", "path/to/other.ts"],
+  "acceptance_criteria": ["AC 1", "AC 2"],
+  "constraints": "Only modify listed files. Read LESSONS-LEARNED.md first.",
+  "output_contract": "Return: files changed, lint/type/test pass/fail, discovered issues."
+}
 ```
 
-This data helps optimize future model assignments. If no meaningful data was collected, skip the summary.
-
-During execution, maintain a running delegation log in the session checkpoint (see the **session-checkpoints** skill § Delegation Cost Log). Update it after each delegation completes or fails.
+`tracker` required; `acceptance_criteria` verbatim from tracker; `files` = exact resolved paths (not globs); `output_contract` = agent's Base Output Contract. Maintain running delegation log in session checkpoint (see **session-checkpoints** skill).
 
 ## Context Source Tagging
 
-When collecting results from multiple sub-agents or background agents, **tag each result by its source** to prevent context confusion:
-
-```markdown
-### [Content Engineer] TAS-42 Schema
-- Created `schemas/review.ts` with star rating field
-- Deployed to CMS studio
-- Verification: lint ✅, type-check ✅
-
-### [DB Engineer] TAS-43 Migration
-- Created migration file for reviews table
-- RLS policies for authenticated users
-- Verification: migration applied ✅, tests ✅
-```
-
-**Rules:**
-- Prefix each agent's output summary with `### [Agent Name] TAS-XX Description`
-- Never merge outputs from different agents into a single undifferentiated block
-- When referencing prior agent output in a delegation prompt, cite the source: *"The Content Engineer created `schemas/review.ts` — follow that pattern"*
-- In the session checkpoint "Completed Work" table, always include the Agent column
-
-This prevents the Team Lead from confusing which agent produced what, especially after 5+ delegations when context is dense.
+Prefix each agent's output summary `### [Agent Name] TAS-XX Description`. Never merge outputs from different agents. Cite source agent when referencing prior output. Include Agent column in checkpoint "Completed Work" tables.
 
 ## Dead Letter Queue Format
 
-Log to `.opencastle/AGENT-FAILURES.md` when:
-- A delegated agent fails to complete its task after 2+ attempts
-- A background agent produces output that fails all verification gates
-- An agent encounters an unrecoverable error (e.g., MCP server down, tool unavailable)
-
-> **Note:** When a panel review BLOCKs 3 times, create a **dispute record** instead of a DLQ entry. See § Dispute Protocol below.
-
-### Failure Entry Format
-
-```markdown
-### DLQ-XXX: Short description
-
-| Field | Value |
-|-------|-------|
-| **Date** | YYYY-MM-DD |
-| **Agent** | Agent name |
-| **Tracker Issue** | TAS-XX (if applicable) |
-| **Failure Type** | `verification-fail` / `tool-error` / `panel-block` / `timeout` / `scope-creep` |
-| **Attempts** | Number of attempts before logging |
-| **Est. Tokens Spent** | ~XXK across all attempts |
-| **Model Tier** | Economy / Utility / Standard / Premium |
-
-**Task:** What was the agent supposed to do?
-
-**Failure Details:** What went wrong? Include error messages, failed checks, or panel BLOCK reasons.
+Log to `.opencastle/AGENT-FAILURES.md` when agent fails 2+ attempts, background output fails all gates, or unrecoverable error occurs. Panel 3x BLOCK → create dispute instead.
 
-**Root Cause:** Why did it fail? (if known)
-
-**Resolution:** How was it eventually resolved? (or "pending" if unresolved)
-```
-
-### Review Cadence
-
-At the start of each session, scan the agent failures doc for:
-- **Pending failures** that need retry
-- **Patterns** — same agent failing repeatedly may indicate a prompt or skill issue
-- **Tool issues** — MCP servers or external dependencies that need attention
+Entry (`DLQ-XXX: Short description`): **Date**, **Agent**, **Tracker Issue**, **Failure Type** (`verification-fail` / `tool-error` / `panel-block` / `timeout` / `scope-creep`), **Attempts**, **Task**, **Failure Details**, **Resolution**. Scan DLQ for pending retries at session start.
 
 ## Error Recovery
 
@@ -210,56 +104,22 @@ For common failure modes and recovery procedures, load the **orchestration-proto
 
 ## Dispute Protocol
 
-When automated resolution is exhausted (panel 3x BLOCK, approach conflicts, or criteria contradictions), create a **formal dispute record** in `.opencastle/DISPUTES.md`. Inspired by the [Steroids CLI](https://github.com/UnlikeOtherAI/steroids-cli) dispute/escalation pattern.
-
-### When to Create a Dispute (vs. DLQ Entry)
-
 | Scenario | Action |
 |----------|--------|
-| Tool error, timeout, MCP failure | DLQ entry |
+| Tool error / timeout / MCP failure | DLQ entry |
 | Scope creep | DLQ entry + redirect |
 | Agent fails 2+ times (simple) | DLQ entry |
-| Panel BLOCKs 3 times | **Dispute record** |
-| Agent and reviewer fundamentally disagree | **Dispute record** |
-| Acceptance criteria contradict each other | **Dispute record** |
-| Multiple valid approaches, agents can't converge | **Dispute record** |
-| Fix requires external/human action | **Dispute record** |
-
-### Dispute Creation Procedure
-
-1. **Number the dispute** — Increment from the last `DSP-XXX` ID in the Index table
-2. **Set priority** — Use the priority guidelines in DISPUTES.md (critical/high/medium/low)
-3. **Document both perspectives** — Agent's position AND reviewer's position with specific file/code references
-4. **Build attempt history** — List every fast review and panel attempt with one-line verdict summaries
-5. **Present resolution options** — At least 2 concrete options with rationale and risk for each
-6. **Recommend an action** — Which option the Team Lead thinks is best, with specific next steps
-7. **Link artifacts** — Panel reports, review logs, changed files, DLQ entries
-8. **Log to events.ndjson** — Use the **observability-logging** skill's dispute record command
-9. **Update the tracker issue** — Add the dispute ID and link to the dispute record
-10. **Update the Index table** — Add the new dispute to the bottom of the Index
-
-### After Human Resolution
-
-When a human resolves a dispute:
-1. Update the dispute `Status` → `resolved` or `deferred`
-2. Record which option was chosen and any additional instructions
-3. If `resolved` → re-delegate the task with the human's decision as an explicit constraint
-4. If `deferred` → create a follow-up tracker issue and continue with other work
-5. Log the resolution in `events.ndjson` using the **observability-logging** skill's dispute record command (update or append a resolution event)
-
-### Session Start: Check Disputes
-
-At the start of each session, after checking the DLQ, also check `DISPUTES.md` for:
-- **Pending disputes** that a human has resolved since the last session → act on the resolution
-- **Critical/high disputes** that are still pending → flag to the user before proceeding
-- **Patterns** — recurring disputes may indicate a skill gap, ambiguous instructions, or a need for a new validation gate
-
-## Background Agent Git Merge Strategy
-
-Background agents work in isolated Git worktrees. When merging their output:
-
-1. **Merge order matters:** Merge the most foundational changes first (DB migrations -> queries -> components -> pages -> tests -> docs)
-2. **Test after each merge:** Run affected tests after merging each agent's work
-3. **Resolve conflicts immediately:** Don't accumulate multiple agent outputs before merging
-4. **Discard stale worktrees:** If an agent's output is no longer compatible with the main branch (due to other agents' changes merging first), re-delegate rather than force-merge
-5. **Atomic merge preference:** Use `git merge --no-ff` to keep agent work traceable in history
+| Panel 3x BLOCK / agent-reviewer disagreement / criteria contradictions / no convergence / needs human | Dispute record |
+
+Create in `.opencastle/DISPUTES.md` (inspired by [Steroids CLI](https://github.com/UnlikeOtherAI/steroids-cli)):
+
+1. Number (`DSP-XXX`) and set priority (critical/high/medium/low)
+2. Document both perspectives with file/code references
+3. Build attempt history with one-line verdict summaries
+4. Present ≥2 options with rationale/risk; note recommended action
+5. Link panel reports, review logs, changed files, DLQ entries
+6. Log with **observability-logging** dispute command; add ID to tracker and Index
+
+**After human resolution:** Set `Status` → `resolved`/`deferred`. Record chosen option. Resolved → re-delegate with decision as explicit constraint. Deferred → create follow-up issue. Log in `events.ndjson`.
+
+