opencastle 0.10.7 → 0.11.0

package/src/orchestrator/prompts/bootstrap-customizations.prompt.md

@@ -142,11 +142,9 @@ Files are organized into subdirectories by domain:
 ├── project/                   # Project management config
 │   ├── docs-structure.md
 │   └── <tracker>-config.md    # e.g. linear-config.md, jira-config.md
-└── logs/                      # Append-only NDJSON session logs
+└── logs/                      # Append-only NDJSON event log
     ├── README.md
-    ├── sessions.ndjson
-    ├── delegations.ndjson
-    └── panels.ndjson
+    └── events.ndjson
 ```
 
 #### Root Files (always create)
@@ -241,10 +239,8 @@ Files are organized into subdirectories by domain:
 
 #### `logs/` — Session Logs (always create)
 
-16. **`logs/README.md`** — Schema documentation for the NDJSON log files
-17. **`logs/sessions.ndjson`** — Empty file for structured session log entries
-18. **`logs/delegations.ndjson`** — Empty file for delegation log entries
-19. **`logs/panels.ndjson`** — Empty file for panel review log entries
+16. **`logs/README.md`** — Schema documentation for the unified NDJSON event log
+17. **`logs/events.ndjson`** — Empty file for all structured event log entries (sessions, delegations, reviews, panels, disputes)
 
 ### Phase 3: Cross-Reference Verification
 

package/src/orchestrator/prompts/bug-fix.prompt.md

@@ -93,7 +93,7 @@ Delegate to the appropriate specialist agent via **sub-agent** (inline). For bug
 - **File paths** — Exact files to read and modify
 - **Reproduction steps** — So the agent can verify the fix
 - **Boundaries** — "Only modify files listed above. Fix the bug, do not refactor surrounding code."
-- **Self-improvement reminder** — include per `general.instructions.md` § Self-Improvement Protocol
+- **Self-improvement reminder** — include per the **self-improvement** skill
 
 #### Implementation Rules
 
@@ -121,13 +121,13 @@ Every bug fix must pass ALL applicable gates:
 
 ### 6. Delivery
 
-Follow the **Delivery Outcome** defined in `general.instructions.md` — commit, push, open PR (not merged), and link to the tracker.
+Follow the **Delivery Outcome** defined in the **git-workflow** skill — commit, push, open PR (not merged), and link to the tracker.
 
 ### 7. Wrap Up
 
 1. **Move tracker issue to Done** — Only after all validation passes
 2. **Update Known Issues** — If this was a documented known issue, remove or update the entry in `.github/customizations/KNOWN-ISSUES.md`
-3. **Capture lessons** — If the root cause reveals a pattern that other agents should know about, add it to `.github/customizations/LESSONS-LEARNED.md`
+3. **Capture lessons** — If the root cause reveals a pattern that other agents should know about, use the **self-improvement** skill to add a lesson
 4. **Note prevention** — If this class of bug could be caught earlier (by a lint rule, test, or type check), note that in the tracker issue as a follow-up suggestion
 
 ### 8. Completion Criteria
@@ -142,7 +142,7 @@ The bug fix is complete when:
 - [ ] Bug verified fixed in the browser
 - [ ] No regressions in adjacent functionality
 - [ ] Both apps checked if shared code was modified
-- [ ] Delivery Outcome completed (see `general.instructions.md`) — branch pushed, PR opened (not merged), tracker linked
+- [ ] Delivery Outcome completed (see the **git-workflow** skill) — branch pushed, PR opened (not merged), tracker linked
 - [ ] Tracker issue moved to Done
 - [ ] Known issues updated if applicable
 - [ ] Lessons learned captured if any retries occurred

package/src/orchestrator/prompts/implement-feature.prompt.md

@@ -64,7 +64,7 @@ Every subtask must be tracked. **No issue = no implementation.** This step produ
 
 #### Self-Improvement
 
-Include the self-improvement reminder in every delegation prompt (see `general.instructions.md` § Self-Improvement Protocol).
+Include the self-improvement reminder in every delegation prompt (see the **self-improvement** skill).
 
 #### Visual Consistency
 
@@ -91,7 +91,7 @@ Every subtask must pass ALL gates before being marked Done:
 
 ### 5. Delivery
 
-Follow the **Delivery Outcome** defined in `general.instructions.md` — commit, push, open PR (not merged), and link to the tracker.
+Follow the **Delivery Outcome** defined in the **git-workflow** skill — commit, push, open PR (not merged), and link to the tracker.
 
 ### 6. Documentation & Traceability
 
@@ -127,5 +127,5 @@ The roadmap task is complete when:
 - [ ] Documentation updated (roadmap, known issues, decisions)
 - [ ] Panel review passed for any high-stakes changes
 - [ ] Roadmap item marked complete in `.github/customizations/project/roadmap.md`
-- [ ] Delivery Outcome completed (see `general.instructions.md`) — branch pushed, PR opened (not merged), tracker linked
+- [ ] Delivery Outcome completed (see the **git-workflow** skill) — branch pushed, PR opened (not merged), tracker linked
 - [ ] Lessons learned captured if any retries occurred

package/src/orchestrator/prompts/quick-refinement.prompt.md

@@ -84,7 +84,7 @@ Delegate to the appropriate specialist agent(s). Since follow-ups are scoped and
 - **Where** — exact file paths to read and modify
 - **How to verify** — what the result should look like or how to test it
 - **Boundaries** — "Only modify files listed above. Do not refactor unrelated code."
-- **Self-improvement reminder** — include per `general.instructions.md` § Self-Improvement Protocol
+- **Self-improvement reminder** — include per the **self-improvement** skill
 
 #### Implementation Rules
 
@@ -110,7 +110,7 @@ Every follow-up, no matter how small, must pass these gates:
 
 ### 6. Delivery
 
-If triage determined this follow-up needs tracker tracking, follow the **Delivery Outcome** defined in `general.instructions.md` — commit, push, open PR (not merged), and link to the tracker.
+If triage determined this follow-up needs tracker tracking, follow the **Delivery Outcome** defined in the **git-workflow** skill — commit, push, open PR (not merged), and link to the tracker.
 
 If triage determined no tracker tracking is needed (pure cosmetic/isolated/trivial), commit the changes to the current working branch. A dedicated branch and PR are not required because the Team Lead will include these changes in the parent task's existing PR — the "every change goes through a PR" rule is still satisfied via the parent PR.
 
@@ -138,6 +138,6 @@ The follow-up is complete when:
 - [ ] **Visual changes verified in Chrome with screenshot taken as proof**
 - [ ] No regressions in adjacent functionality
 - [ ] Shared component changes tested across all consuming apps
-- [ ] Delivery Outcome completed if tracked (see `general.instructions.md`) — branch pushed, PR opened (not merged), tracker linked
+- [ ] Delivery Outcome completed if tracked (see the **git-workflow** skill) — branch pushed, PR opened (not merged), tracker linked
 - [ ] Lessons learned captured if any retries occurred
 - [ ] Known issues updated if a new limitation was discovered

package/src/orchestrator/prompts/resolve-pr-comments.prompt.md

@@ -113,4 +113,4 @@ After resolving comments, report:
 - **Preserve the reviewer's intent** — don't just technically satisfy the comment, address the underlying concern
 - **Don't over-fix** — resolve only what was commented on. Save unrelated improvements for a separate PR
 - **Respond to every comment** — nothing should be silently ignored
-- **Self-improvement** — Follow `general.instructions.md` § Self-Improvement Protocol
+- **Self-improvement** — Follow the **self-improvement** skill

package/src/orchestrator/skills/agent-hooks/SKILL.md

@@ -53,13 +53,13 @@ Load relevant skills before writing code.
 
 **When:** Before the agent yields control back to the user — every time, unconditionally.
 
-> **⛔ HARD GATE — Run the Pre-Response Quality Gate checklist from `general.instructions.md` before responding.**
+> **⛔ HARD GATE — Run the Pre-Response Quality Gate checklist from the **observability-logging** skill before responding.**
 > A session without log records is a failed session. A session without lessons captured after retries is a failed session.
 
 ### Actions
 
 1. **Call Session Guard** (Team Lead only) — Delegate to the **Session Guard** agent with a session summary (delegations, retries, discoveries, files changed). Execute any fix commands it returns. This replaces the manual Pre-Response Quality Gate checklist — the guard runs it automatically with a fresh context window.
-2. **For specialist agents** (not Team Lead) — Run the Pre-Response Quality Gate checklist from `general.instructions.md` manually. Specialist agents don't have access to the Session Guard.
+2. **For specialist agents** (not Team Lead) — Run the Pre-Response Quality Gate checklist from the **observability-logging** skill manually. Specialist agents don't have access to the Session Guard.
 3. **Save checkpoint** (Team Lead only) — If work is incomplete, write `.github/customizations/SESSION-CHECKPOINT.md` with current state so the next session can resume. Load **session-checkpoints** skill for format.
 4. **Memory merge check** — If `LESSONS-LEARNED.md` has grown significantly (5+ new entries this session), flag for memory merge consideration.
 5. **Clean up** — Remove any temporary files created during the session (e.g., test fixtures, debug outputs).
@@ -67,9 +67,9 @@ Load relevant skills before writing code.
 ### Template for Delegation Prompts
 
 ```
-**Session End:** Run the Pre-Response Quality Gate from general.instructions.md:
-- Log your session to `.github/customizations/logs/sessions.ndjson` (Constitution rule #6)
-- If you retried anything with a different approach that worked, add a lesson to `.github/customizations/LESSONS-LEARNED.md`
+**Session End:** Run the Pre-Response Quality Gate from the **observability-logging** skill:
+- Log your session using the observability-logging skill's session record command (Constitution rule #6)
+- If you retried anything with a different approach that worked, use the **self-improvement** skill to add a lesson
 - Track any discovered issues in KNOWN-ISSUES.md or a tracker ticket
 - Clean up temp files
 ```
@@ -92,26 +92,26 @@ Run the 5-point Pre-Delegation Checks from the Team Lead agent file: (1) Tracker
 
 ### Actions
 
-0. **Log the delegation** — Append a record to `.github/customizations/logs/delegations.ndjson` **before** proceeding to review or verification.
-   Use the delegation echo command template from the Team Lead agent file § Delegation.
-1. **Fast review (mandatory)** — Run the `fast-review` skill against the agent's output. This is a **non-skippable gate**. See the fast-review skill for the full procedure (single reviewer sub-agent, automatic retry, escalation). Log the review to `reviews.ndjson` immediately after. Only after the fast review passes do you proceed to the remaining post-delegate actions below.
+0. **Log the delegation (⛔ hard gate)** — Use the **observability-logging** skill's delegation record command. Do NOT proceed to review or any other action until the delegation is logged and verified.
+1. **Fast review (mandatory)** — Run the `fast-review` skill against the agent's output. This is a **non-skippable gate**. See the fast-review skill for the full procedure (single reviewer sub-agent, automatic retry, escalation). **Log the review (⛔ hard gate)** using the **observability-logging** skill's review record command immediately after — do NOT proceed until logged. Only after both the fast review passes and the review is logged do you proceed to the remaining post-delegate actions below.
 2. **Verify output** — Read changed files. Check that changes stay within the agent's file partition.
 2. **Run verification** — Execute appropriate checks: lint, type-check, tests, or visual inspection.
 3. **Check acceptance criteria** — Compare output against the tracker issue's acceptance criteria. Each criterion must be independently verified.
 4. **Discovered issues tracked** — Verify the agent followed the Discovered Issues Policy. If they found issues, check that they're in KNOWN-ISSUES.md or a new tracker ticket.
-5. **Lessons captured** — If the agent retried anything, verify a lesson was added to LESSONS-LEARNED.md.
+5. **Lessons captured** — If the agent retried anything, verify a lesson was added via the **self-improvement** skill.
 6. **Update tracker** — Move the issue to Done (if passing) or add failure notes and re-delegate (if failing).
 
 ### Quick Checklist
 
 ```
 Post-Delegate:
-☐ Delegation logged to delegations.ndjson (before review — verify with tail -1)
+☐ ⛔ Delegation logged (observability-logging skill — verify with tail -1) — BLOCKING
 ☐ Changed files reviewed
 ☐ Files within partition
 ☐ Lint/test/build passes
 ☐ Fast review PASS (mandatory — load fast-review skill)
-☐ Review logged to reviews.ndjson (verify with tail -1)
+☐ ⛔ Review logged (observability-logging skill — verify with tail -1) — BLOCKING
+☐ ⛔ Panel logged if escalated (observability-logging skill — verify with tail -1) — BLOCKING
 ☐ Acceptance criteria met
 ☐ Discovered issues tracked (not ignored)
 ☐ Lessons captured (if retries occurred)

package/src/orchestrator/skills/decomposition/SKILL.md

@@ -70,7 +70,7 @@ Return a structured summary with:
 **Note:** Follow the Structured Output Contract from the team-lead-reference skill. Include all standard fields plus agent-specific extensions.
 
 ### Self-Improvement
-Read `.github/customizations/LESSONS-LEARNED.md` before starting. If you retry any command/tool with a different approach that works, immediately add a lesson to that file.
+Read `.github/customizations/LESSONS-LEARNED.md` before starting. If you retry any command/tool with a different approach that works, use the **self-improvement** skill to add a lesson immediately.
 ```
 
 For simpler tasks (score 1-3), the existing prompt format (objective + files + criteria) is sufficient. Don't over-engineer delegation for trivial work.

package/src/orchestrator/skills/fast-review/SKILL.md

@@ -221,24 +221,9 @@ CONFIDENCE: low | medium | high
 
 ## Logging
 
-Append a JSON line to `.github/customizations/logs/reviews.ndjson` after each fast review:
-
-```json
-{
-  "timestamp": "2026-02-28T14:30:00Z",
-  "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
-}
-```
+> **⛔ HARD GATE — Do NOT proceed to the next task or accept the review result until the review is logged.**
+
+After each fast review, log the result using the **observability-logging** skill's review record command. See the skill for the exact CLI syntax, required fields, and verify step. An unlogged review is a failed review.
 
 ## Integration with Existing Workflow
 
@@ -326,7 +311,7 @@ For autonomous overnight sessions, fast review is the primary quality gate. Addi
 
 ## Metrics & Continuous Improvement
 
-Track these metrics from `reviews.ndjson` to optimize the review process:
+Track these metrics from `events.ndjson` (filter by `"type":"review"`) to optimize the review process:
 
 | Metric | Target | Action if Off-Target |
 |--------|--------|---------------------|

package/src/orchestrator/skills/git-workflow/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: git-workflow
+description: "Git branching, PR workflow, delivery requirements, discovered issues policy, and task tracking conventions. Load when committing, pushing, or opening PRs."
+---
+
+# Git Workflow & Delivery
+
+## Git Workflow
+
+**NEVER commit or push directly to the `main` branch.** All changes must go through a feature/fix branch and a pull request.
+
+1. **Create a branch** from `main` before making any changes: `git checkout -b <type>/<ticket-id>-<short-description>` (e.g., `fix/tas-21-places-redirect-loop`, `feat/tas-15-new-filter`)
+2. **Commit to the branch** — never to `main`. Reference the task tracker issue ID in every commit message (e.g., `TAS-42: Fix token refresh logic`)
+3. **Push the branch** and open a pull request on GitHub. **Do NOT merge** — PRs are opened for review only
+4. **Link the PR to the task tracker** — Update the issue description with the PR URL so progress is traceable
+5. **Merge via PR** — the only way code reaches `main`, and only after review/approval
+
+Branch naming convention: `<type>/<ticket-id>-<short-description>` where type is `fix`, `feat`, `chore`, `refactor`, `perf`, or `docs`.
+
+**This rule has NO exceptions.** Not for "small fixes", not for "just config changes", not for urgent hotfixes. Every change goes through a PR.
+
+### PR Safety Rules
+
+- **Never** use `git push --force` or `git commit --amend` on shared branches
+- **Never** expose secrets in commits, PR descriptions, or terminal output (per Constitution #1)
+- Use `git push --force-with-lease` only when explicitly asked and on personal branches
+- If a secret is accidentally committed, immediately rotate it — git history is permanent
+
+### Delivery Outcome (Required for Every Task)
+
+Every task that produces code changes — whether a roadmap feature, bug fix, follow-up, data pipeline, or refactor — must deliver:
+
+1. **Dedicated branch** — `<type>/<ticket-id>-<short-description>` created from `main`
+2. **Atomic commits** — Each commit references the issue ID (e.g., `TAS-42: Add filter component`)
+3. **Pushed branch** — Branch pushed to origin
+4. **Open PR** — Use `gh` CLI to create the PR. **Do NOT merge** — PRs are opened for review only:
+   ```bash
+   GH_PAGER=cat gh pr create --base main --title "TAS-XX: Short description" --body "Resolves TAS-XX"
+   ```
+5. **Task tracker linkage** — The issue is updated with the PR URL, and the PR description references the issue ID
+
+## Discovered Issues Policy
+
+> **⛔ No issue gets ignored.** Untracked bugs discovered during work are a quality gate failure.
+
+When you encounter a bug, error, or unexpected behavior that is unrelated to the current task:
+
+1. **Check if already tracked:**
+   - Search `.github/customizations/KNOWN-ISSUES.md` for a matching entry
+   - If you have task tracker tools available, also search for open bugs (use `search_issues` or `list_issues` with bug label)
+2. **If found tracked** — skip it, continue with your current work
+3. **If NOT tracked** — you must act:
+   - **Unfixable limitation** (third-party constraint, platform restriction, upstream dependency) → add it to `.github/customizations/KNOWN-ISSUES.md` with: Issue ID, Status, Severity, Evidence, Root Cause, Solution Options
+   - **Fixable bug** → if you have task tracker tools, create a ticket with label `bug`, appropriate priority, and a clear description of the symptoms, reproduction steps, and affected files. If you do NOT have task tracker tools, add a `**Discovered Issues**` section to your output listing the bug details so the Team Lead can track it.
+
+Never assume a pre-existing issue is somebody else's problem. If it's not tracked, track it.
+
+## Task Tracking
+
+Feature work is tracked in the **task tracker** (see `tracker-config.md` for project details). The Team Lead agent creates and updates issues via MCP. For conventions, load the **task-management** skill.
+
+### When Task Tracker MCP Tools Are Unavailable
+
+If task tracker MCP tools are not available in the current session, do NOT block on issue creation. Instead:
+
+1. **Document planned issues** in your output with the title, description, and acceptance criteria you would have used
+2. **Proceed with implementation** — the work is still valuable without a ticket number
+3. **Placeholder value for `tracker_issue`:**
+   - **No tracker configured** (no `task-management` slot bound in `skill-matrix.json`) → use `"N/A"`
+   - **Tracker configured but tools unavailable** → use the project prefix + `PENDING` (e.g., `"TAS-PENDING"`)
+4. **Ask the user** to create the issues manually if tracking is critical for the task
+5. After implementation, update commit messages and PR descriptions when issue IDs become available

package/src/orchestrator/skills/memory-merger/SKILL.md

@@ -49,7 +49,7 @@ Each lesson has a natural home in the instruction/skill hierarchy:
 | `cms` | The skill mapped by the `cms` slot in the skill matrix |
 | `database` | The skill mapped by the `database` slot in the skill matrix |
 | `browser-testing` | The skill mapped by the `e2e-testing` slot in the skill matrix |
-| `git-workflow` | `.github/instructions/general.instructions.md` |
+| `git-workflow` | `.github/skills/git-workflow/SKILL.md` |
 | `deployment` | `.github/skills/deployment-infrastructure/SKILL.md` |
 | `delegation` | `.github/agents/team-lead.agent.md` or `.github/skills/team-lead-reference/SKILL.md` |
 | `testing` | `.github/skills/testing-workflow/SKILL.md` |

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 @@
-