opencastle 0.10.7 → 0.12.0

package/src/orchestrator/skills/observability-logging/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: observability-logging
+description: "Session logging, delegation records, review/panel/dispute NDJSON logging, pre-response checklists. Load before responding to verify all logs are written."
+---
+
+# Observability Logging
+
+## Observability Logging (Mandatory)
+
+> **⛔ HARD GATE — This is a blocking requirement, not a suggestion.**
+> Do NOT respond to the user until you have appended the required log records.
+> A session without log records is a failed session — regardless of code quality.
+
+**Every agent MUST log every session to the observability NDJSON files.** No exceptions. No threshold. No "too small to log." The dashboard depends on this data.
+
+### What to log
+
+| File | Event types | Who appends | When |
+|------|------------|------------|------|
+| `events.ndjson` | `session`, `delegation`, `review`, `panel`, `dispute` | All agents / Team Lead / Panel runner | After every applicable event — use `--type` to discriminate |
+
+See `.github/customizations/logs/README.md` for the full schema of each record type.
+
+### How to log
+
+Use the `opencastle log` CLI to append events to `.github/customizations/logs/events.ndjson`. When the Team Lead works directly, use the agent role that best describes the work (e.g., `--agent Developer`, `--agent "UI-UX Expert"`). If a single conversation involves multiple distinct tasks, log one record per task.
+
+**Session record** (ALL agents, EVERY session):
+```sh
+opencastle log --type session --agent Developer --model claude-opus-4-6 \
+  --task "Fix login redirect bug" --outcome success --duration_min 15 \
+  --files_changed 3 --retries 0
+```
+
+**Delegation record** (Team Lead only, **immediately after each delegation — not at session end**):
+```sh
+opencastle log --type delegation --session_id feat/prj-57 --agent Developer \
+  --model claude-sonnet-4-6 --tier quality --mechanism sub-agent \
+  --tracker_issue PRJ-57 --outcome success --retries 0 --phase 2 \
+  --file_partition "src/components/"
+```
+Verify: `tail -1 .github/customizations/logs/events.ndjson`
+
+> **`model` and `tier` must reflect the delegated agent's assignment from the agent registry** — not the Team Lead's own model.
+
+**Fast review record** (Team Lead, **immediately after each fast review**):
+```sh
+opencastle log --type review --tracker_issue PRJ-42 --agent Developer \
+  --reviewer_model gpt-5-mini --verdict pass --attempt 1 \
+  --issues_critical 0 --issues_major 0 --issues_minor 2 \
+  --confidence high --escalated false --duration_sec 45
+```
+Verify: `tail -1 .github/customizations/logs/events.ndjson`
+
+**Panel record** (Panel runner, **immediately after each panel majority vote**):
+```sh
+opencastle log --type panel --panel_key auth-review --verdict pass \
+  --pass_count 3 --block_count 0 --must_fix 0 --should_fix 3 \
+  --reviewer_model claude-opus-4-6 --weighted false --attempt 1 \
+  --tracker_issue PRJ-42 --artifacts_count 5
+```
+Verify: `tail -1 .github/customizations/logs/events.ndjson`
+
+**Dispute record** (Team Lead, **immediately after each dispute**):
+```sh
+opencastle log --type dispute --dispute_id DSP-001 --tracker_issue PRJ-42 \
+  --priority high --trigger panel-3x-block --implementing_agent Developer \
+  --reviewing_agents "Reviewer,Panel (3x)" --total_attempts 6 --status pending
+```
+Verify: `tail -1 .github/customizations/logs/events.ndjson`
+
+### Pre-Response Logging Checklist
+
+**STOP before responding to the user.** Verify each applicable item:
+
+- [ ] **Session logged** — `events.ndjson` has a new `session` record for this session (ALWAYS required)
+- [ ] **Delegations logged** — `events.ndjson` has a `delegation` record for **each** delegation (Team Lead only). Count delegations → count records → must match
+- [ ] **Reviews logged** — `events.ndjson` has a `review` record for **each** fast review performed. Count reviews → count records → must match
+- [ ] **Panels logged** — `events.ndjson` has a `panel` record for **each** panel review performed. Count panels → count records → must match
+- [ ] **Disputes logged** — `events.ndjson` has a `dispute` record for **each** dispute created. Count disputes → count records → must match
+
+If ANY required log is missing, run `opencastle log --type <type> ...` NOW before responding.
+
+### Rules
+
+- **Log before yielding to the user** — logging is the LAST action before responding. This is Constitution rule #6.
+- **Log per task**, not per conversation. Multiple tasks = multiple records.
+- **Never batch-log retrospectively** across sessions.
+- **Verify the append succeeded** — if unsure, `tail -1` the file to confirm.
+
+## Universal Agent Rules
+
+These rules apply to ALL specialist agents automatically. **Do not duplicate them in individual agent files.**
+
+1. **Never delegate** — Specialist agents complete their own work and return results. Never invoke the Team Lead or spawn sub-agents. If work requires another domain, document the need in your output contract.
+2. **Follow the Discovered Issues Policy** — Track any pre-existing bugs found during your work (see the **git-workflow** skill).
+3. **Read and update lessons** — Read `.github/customizations/LESSONS-LEARNED.md` before starting. If you retry anything with a different approach that works, use the **self-improvement** skill to add a lesson immediately.
+4. **Log every session** — Append to `.github/customizations/logs/events.ndjson` after every session using `opencastle log --type session ...`. No exceptions. This is Constitution rule #6 — a blocking gate, not optional.
+
+## Base Output Contract
+
+Every specialist agent's Output Contract MUST end with these standard items (in addition to domain-specific items above them):
+
+- **Observability Logged** — Confirm ALL applicable log records were appended to `events.ndjson` (Constitution rule #6):
+  - `--type session` — ALWAYS (every agent, every session)
+  - `--type delegation` — if delegations occurred (Team Lead only)
+  - `--type review` — if fast reviews occurred
+  - `--type panel` — if panel reviews occurred
+  - `--type dispute` — if disputes were created
+- **Discovered Issues** — Pre-existing bugs or anomalies found during work, with tracking action taken per the Discovered Issues Policy
+- **Lessons Applied** — Lessons from `.github/customizations/LESSONS-LEARNED.md` that influenced this work, and any new lessons added
+
+Agents reference this contract with: `See **Base Output Contract** in the observability-logging skill for the standard closing items.`
+
+## Pre-Response Quality Gate
+
+> **⛔ STOP before responding to the user.** Run through this checklist. If ANY required item is missing, fix it NOW.
+
+This is the single exit gate for every session. All items are mandatory unless marked conditional.
+
+- [ ] **Lessons read** — `.github/customizations/LESSONS-LEARNED.md` was read at session start (Self-Improvement Protocol)
+- [ ] **Lessons captured** — If any retry occurred, a new lesson was added via the **self-improvement** skill
+- [ ] **Discovered issues tracked** — Any pre-existing bugs found were added to `KNOWN-ISSUES.md` or a tracker ticket was created (Discovered Issues Policy)
+- [ ] **Lint/type/test pass** — No new errors introduced; verification ran after code changes (Constitution rule #5)
+- [ ] **Session logged** — `events.ndjson` has a new `session` record for this session (Constitution rule #6 — ALWAYS required)
+- [ ] **Delegations logged** — `events.ndjson` has a `delegation` record for each delegation (Team Lead only)
+- [ ] **Reviews logged** — `events.ndjson` has a `review` record for each fast review performed (if any)
+- [ ] **Panels logged** — `events.ndjson` has a `panel` record for each panel review performed (if any)
+- [ ] **Disputes logged** — `events.ndjson` has a `dispute` record for each dispute created (if any)

package/src/orchestrator/skills/orchestration-protocols/SKILL.md

@@ -122,7 +122,7 @@ Common failure modes and how to recover:
 ### Agent Stuck in Retry Loop
 
 **Symptom:** Agent retries the same failing command 3+ times without changing approach.
-**Recovery:** Intervene immediately. Read the error output, identify the root cause, and re-delegate with explicit fix instructions. Add a lesson to lessons learned.
+**Recovery:** Intervene immediately. Read the error output, identify the root cause, and re-delegate with explicit fix instructions. Use the **self-improvement** skill to add a lesson.
 
 ### MCP Tool Unavailable
 
@@ -137,7 +137,7 @@ Common failure modes and how to recover:
 ### Merge Conflict from Parallel Agents
 
 **Symptom:** Two background agents modified overlapping files.
-**Recovery:** (1) This should never happen if file partitioning was followed. (2) Accept one agent's changes first (the one with more complex work). (3) Re-delegate the simpler changes to adapt to the new state. (4) Add the conflict to your lessons learned.
+**Recovery:** (1) This should never happen if file partitioning was followed. (2) Accept one agent's changes first (the one with more complex work). (3) Re-delegate the simpler changes to adapt to the new state. (4) Use the **self-improvement** skill to add a lesson about the conflict.
 
 ### Context Window Exhausted
 

package/src/orchestrator/skills/panel-majority-vote/SKILL.md

@@ -82,13 +82,10 @@ The isolated runner subagent must:
 6. Print a concise summary to chat
   - Overall verdict + vote tally + path to `<panelDir>/<panelKey>.md`.
 
-7. Log the panel result
-  - Append a JSON line to `.github/customizations/logs/panels.ndjson` with the panel record schema (see `.github/customizations/logs/README.md`).
-  - Include: `timestamp`, `panel_key`, `verdict`, `pass_count`, `block_count`, `must_fix`, `should_fix`, `reviewer_model`, `weighted`, `attempt`, `tracker_issue`, `artifacts_count`, `report_path`.
-  - Example:
-    ```bash
-    echo '{"timestamp":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","panel_key":"instruction-refactoring","verdict":"pass","pass_count":3,"block_count":0,"must_fix":0,"should_fix":5,"reviewer_model":"claude-opus-4-6","weighted":false,"attempt":1,"artifacts_count":14,"report_path":".github/customizations/logs/panel/instruction-refactoring.md"}' >> .github/customizations/logs/panels.ndjson
-    ```
+7. Log the panel result **(⛔ hard gate — do NOT return the verdict or proceed until logged)**
+  - Log the panel result using the **observability-logging** skill's panel record command. An unlogged panel is a failed panel.
+  - Include: `panel_key`, `verdict`, `pass_count`, `block_count`, `must_fix`, `should_fix`, `reviewer_model`, `weighted`, `attempt`, `tracker_issue`, `artifacts_count`, `report_path`.
+  - The skill's panel record command includes a verify step.
 
 Finally: ensure whatever produced the claim being verified links the consolidated panel report as verification evidence.
 

package/src/orchestrator/skills/self-improvement/SKILL.md

@@ -21,41 +21,28 @@ This is the team's collective memory — a structured log of tool/command pitfal
 
 ## Protocol for All Agents
 
-The core protocol (read lessons → write on retry → log session) is defined in `general.instructions.md` § Self-Improvement Protocol. This skill provides the detailed reference material for writing lessons.
+The core protocol (read lessons → write on retry → log session) is referenced from `general.instructions.md` via the **Workflow & Governance** table. This skill provides the detailed reference material for writing lessons.
 
 ## How to Write a Lesson
 
-### Step 1: Determine the next lesson ID
+> **⛔ HARD GATE — Use the CLI to write lessons. Do NOT edit LESSONS-LEARNED.md directly.**
 
-Look at the last `LES-XXX` entry in `.github/customizations/LESSONS-LEARNED.md` and increment by 1.
+Use the `opencastle lesson` CLI command. It auto-increments the lesson ID, formats the entry, and updates the category index.
 
-### Step 2: Write the entry
-
-Add it **before** the `## Index by Category` section, following this template:
-
-```markdown
-### LES-XXX: Short descriptive title
-
-| Field | Value |
-|-------|-------|
-| **Category** | `category-name` |
-| **Added** | YYYY-MM-DD |
-| **Severity** | `high` / `medium` / `low` |
-
-**Problem:** What went wrong and what error/behavior was observed.
-
-**Wrong approach:** The obvious/intuitive approach that fails (with code block).
-
-**Correct approach:** The working solution (with code block).
-
-**Why:** Root cause explanation (if known).
+```sh
+opencastle lesson --title "Short descriptive title" --category general --severity high \
+  --problem "What went wrong and what error/behavior was observed" \
+  --wrong "The obvious/intuitive approach that fails" \
+  --correct "The working solution" \
+  --why "Root cause explanation"
 ```
 
-### Step 3: Update the index
+Required flags: `--title`, `--category`, `--severity`, `--problem`
+Optional flags: `--wrong`, `--correct`, `--why`
 
-Add the lesson ID to the appropriate category row in the `## Index by Category` table.
+Run `opencastle lesson --help` for full usage and valid category/severity values.
 
-### Step 4: Update related instruction files (if applicable)
+### After writing the lesson
 
 If the lesson reveals a gap in existing instruction/skill files, **also update those files** to include the correct approach. This prevents the pitfall at the source level, not just as a retroactive note.
 

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

@@ -234,7 +234,7 @@ When automated resolution is exhausted (panel 3x BLOCK, approach conflicts, or c
 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 disputes.ndjson** — Append a machine-readable record (see logs README)
+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
 
@@ -245,7 +245,7 @@ When a human resolves a dispute:
 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 `disputes.ndjson` (update the existing record or append a resolution event)
+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
 

package/src/orchestrator/customizations/logs/delegations.ndjson

@@ -1 +0,0 @@
-

package/src/orchestrator/customizations/logs/panels.ndjson

@@ -1 +0,0 @@
-

package/src/orchestrator/customizations/logs/sessions.ndjson

@@ -1 +0,0 @@
-