opencastle 0.32.5 → 0.32.6

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

@@ -5,68 +5,32 @@ description: "Git branching, PR workflow, delivery requirements, discovered issu
 
 # Git Workflow & Delivery
 
-## Git Workflow
+**NEVER push directly to `main`.** All changes go through a feature/fix branch → PR.
 
-**NEVER commit or push directly to the `main` branch.** All changes must go through a feature/fix branch and a pull request.
+## Branch & Commit Rules
 
-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
+| Rule | Detail |
+|------|--------|
+| Branch from `main` | `git checkout -b <type>/<ticket-id>-<slug>` |
+| Types | `fix`, `feat`, `chore`, `refactor`, `perf`, `docs` |
+| Commit messages | Must reference issue ID — `TAS-42: Fix token refresh` |
+| No force-push | Never `--force` or `--amend` on shared branches; `--force-with-lease` on personal only |
+| No secrets | No tokens/keys in commits, PR descriptions, or output (rotate immediately if leaked) |
 
-Branch naming convention: `<type>/<ticket-id>-<short-description>` where type is `fix`, `feat`, `chore`, `refactor`, `perf`, or `docs`.
+## Delivery Checklist (Every Task)
 
-**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
+1. Branch `<type>/<ticket-id>-<slug>` from `main`
+2. Atomic commits referencing issue ID
+3. Push branch to origin
+4. Open PR (do NOT merge): `GH_PAGER=cat gh pr create --base main --title "TAS-XX: …" --body "Resolves TAS-XX"`
+5. Update issue with PR URL
 
 ## 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 `.opencastle/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 `.opencastle/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.
+> Inherits: [discovered-issues-policy](../../snippets/discovered-issues-policy.md)
 
 ## 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:
+Tracked in the **task tracker** (`tracker-config.md`). Team Lead creates/updates issues via MCP. Load **task-management** skill for conventions.
 
-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
+**If MCP tools unavailable:** Document planned issues (title + AC) in output, use `"N/A"` (no tracker) or `"TAS-PENDING"` (tracker configured), proceed with work, update IDs when available.

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

@@ -3,123 +3,86 @@ name: memory-merger
 description: "Protocol for graduating mature lessons from LESSONS-LEARNED.md into permanent instruction and skill files. Closes the self-improvement loop by codifying validated knowledge at the source level."
 ---
 
-<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .opencastle/ directory instead. -->
+# Memory Merger
 
-# Skill: Memory Merger
-
-This skill automates the final step of the self-improvement cycle: promoting validated lessons into the instruction and skill files where they have structural, permanent impact.
-
-## Why Merge?
-
-`.opencastle/LESSONS-LEARNED.md` is a flatfile that grows over time. Lessons buried in a 400+ line file lose their impact — agents skim past them or miss relevant entries. The most valuable lessons should **graduate** into the instruction/skill files where they're encountered naturally during every task.
+Promotes validated lessons from `.opencastle/LESSONS-LEARNED.md` into instruction/skill files where they have permanent impact.
 
 ## When to Run
 
-Invoke a memory merge when:
-
-- **LESSONS-LEARNED.md exceeds 50 entries** — periodic cleanup
-- **A lesson has been cited 3+ times** — it's clearly a recurring pattern
-- **A lesson is older than 60 days** — mature enough to be considered stable
-- **After a major feature ships** — good checkpoint to extract patterns
-- **Team Lead's discretion** — any time the lessons file feels stale
+| Trigger | Threshold |
+|---------|-----------|
+| File size | >50 entries |
+| Citation count | Cited 3+ times |
+| Age | >60 days old |
+| Category cluster | 5+ lessons in same category |
+| Discretionary | Lessons file feels stale |
 
 ## Merge Protocol
 
-### Step 1: Scan for Merge Candidates
-
-Read `.opencastle/LESSONS-LEARNED.md` and identify lessons that meet any of these criteria:
+### 1 — Scan Candidates
 
 | Criterion | Signal |
 |-----------|--------|
-| **High frequency** | Cited or re-discovered 3+ times |
-| **High severity** | Marked `high` severity |
-| **Age** | Added more than 60 days ago and still relevant |
-| **Category concentration** | 5+ lessons in the same category → extract a pattern |
-| **Tool-specific** | Lesson about a specific MCP tool, codebase-tool command, or framework pattern |
-
-### Step 2: Map Lessons to Target Files
-
-Each lesson has a natural home in the instruction/skill hierarchy:
-
-| Lesson Category | Target File |
-|----------------|-------------|
-| `task-management` | The skill mapped by the `task-management` slot in the skill matrix |
-| `mcp-tools` | The corresponding agent file or skill that uses the tool |
-| `codebase-tool` | The skill mapped by the `codebase-tool` slot in the skill matrix |
-| `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 |
+| Frequency | Cited/re-discovered 3+ times |
+| Severity | Marked `high` |
+| Age | >60 days, still relevant |
+| Concentration | 5+ in same category → extract pattern |
+| Tool-specific | MCP tool, codebase-tool command, or framework pattern |
+
+### 2 — Map to Target File
+
+| Category | Target |
+|----------|--------|
+| `task-management` | skill-matrix `task-management` slot |
+| `mcp-tools` | agent/skill that uses the tool |
+| `codebase-tool` | skill-matrix `codebase-tool` slot |
+| `cms` / `database` | respective skill-matrix slots |
+| `browser-testing` | skill-matrix `e2e-testing` slot |
 | `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` |
+| `delegation` | `.github/agents/team-lead.agent.md` or `team-lead-reference` skill |
 | `testing` | `.github/skills/testing-workflow/SKILL.md` |
-| `ui` / `framework` | The skill mapped by the `framework` slot or the `react-development` direct skill |
-| Cross-cutting pattern | `.github/instructions/general.instructions.md` |
-
-### Step 3: Draft the Merge
+| `ui` / `framework` | `framework` slot or `react-development` skill |
+| Cross-cutting | `.github/instructions/general.instructions.md` |
 
-For each candidate lesson, draft a concrete edit to the target file:
+### 3 — Draft Edit
 
-```markdown
-**Lesson:** LES-XXX — [title]
-**Target:** [target file path]
-**Section:** [which section to add to or modify]
-**Edit:** [exact text to add or modify]
-**Rationale:** [why this belongs here rather than staying in lessons]
 ```
+Lesson: LES-XXX — [title]
+Target: [file path]
+Section: [section name]
+Edit: [exact text]
+```
+Strategies: add rule, add anti-pattern, add code example, expand existing rule, add table row.
 
-#### Merge Strategies
-
-- **Add a rule** — if the lesson reveals a new "always do X" or "never do Y", add it to the target file's rules section
-- **Add an anti-pattern** — if the lesson describes a common mistake, add it to an anti-patterns or "Common Mistakes" section
-- **Add a code example** — if the lesson includes a correct approach with a code block, add it as a documented pattern
-- **Expand existing rule** — if a rule already exists but the lesson adds nuance (edge case, exception), update the rule
-- **Add a table row** — if the target has a reference table, add the lesson as a new row
-
-### Step 4: Apply Edits
+### 4 — Apply & Attribute
 
-1. Edit each target file with the drafted changes
-2. Add a comment or note attributing the source: `<!-- Merged from LES-XXX -->`
-3. Verify the edit reads naturally in context (not just pasted in)
+Edit target file; add `<!-- Merged from LES-XXX -->` attribution inline.
 
-### Step 5: Archive the Merged Lessons
+### 5 — Archive
 
-Move merged lessons from the main body of `LESSONS-LEARNED.md` to an `## Archived (Merged)` section at the bottom of the file:
+Move merged lessons to `## Archived (Merged)` at the bottom of `LESSONS-LEARNED.md`:
 
 ```markdown
-## Archived (Merged)
-
-Lessons below have been merged into instruction/skill files. They are kept here for historical reference.
-
-### LES-XXX: [title] → Merged to `[target file]` on YYYY-MM-DD
+### LES-XXX: [title] → Merged to `[target]` on YYYY-MM-DD
 ```
 
-**Do NOT delete lessons.** Archive them so they remain searchable and traceable.
+**Never delete lessons** — archive for traceability.
 
-### Step 6: Update the Index
+### 6 — Update Index
 
-Update the `## Index by Category` table in `LESSONS-LEARNED.md` to reflect which lessons are now archived.
+Update `## Index by Category` in `LESSONS-LEARNED.md` to mark archived lessons.
 
 ## Quality Gates
 
-Before finalizing a merge:
-
-- [ ] The merged content reads naturally in the target file (not copy-pasted)
-- [ ] The target file's structure and tone are preserved
-- [ ] No duplicate information created (check if a similar rule already exists)
-- [ ] The archived lesson references the target file
-- [ ] The lesson's core insight is preserved — don't lose nuance when summarizing
+- [ ] Merged content reads naturally (not copy-pasted)
+- [ ] No duplicate rules created
+- [ ] Archived lesson references target file
+- [ ] Core insight preserved — no loss of nuance
 
 ## Anti-Patterns
 
-- **Don't merge too eagerly** — a lesson needs to prove itself (3+ citations or 60+ days) before graduating
-- **Don't copy verbatim** — lessons are written as incident reports; instruction files should read as rules/guidelines
-- **Don't merge conflicting lessons** — if two lessons contradict, resolve the conflict first
-- **Don't merge without context** — if the lesson only makes sense with the full story, either include enough context in the target file or keep it in LESSONS-LEARNED.md
-- **Don't create new files for merged content** — merge INTO existing files; only create new skills if a genuinely new domain emerges
-
-## Frequency
-
-- **Quarterly review** — schedule a full scan of LESSONS-LEARNED.md every ~3 months
-- **Post-feature review** — after major features ship, scan for relevant lessons
-- **Ad-hoc** — any time an agent notices "this lesson should be a permanent rule"
+- Merge too eagerly — must meet 3+ citations or 60+ day threshold
+- Copy verbatim — rewrite as rules/guidelines, not incident reports
+- Merge conflicting lessons — resolve conflict first
+- Create new files for merged content — merge INTO existing files only

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

@@ -5,125 +5,79 @@ description: "Session logging, delegation records, review/panel/dispute NDJSON l
 
 # Observability Logging
 
-## Observability Logging (Mandatory)
+> **⛔ HARD GATE.** Every agent MUST log every session to `events.ndjson` before responding. No exceptions. A session without logs is a failed session.
 
-> **⛔ 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.
+| File | Event types | Who | When |
+|------|------------|-----|------|
+| `events.ndjson` | `session`, `delegation`, `review`, `panel`, `dispute` | All agents / Team Lead / Panel runner | After each applicable event |
 
-**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.
+See `.opencastle/logs/README.md` for full schema.
 
-### What to log
+Use `opencastle log` CLI. One record per task; never batch-log retrospectively.
 
-| 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 `.opencastle/logs/README.md` for the full schema of each record type.
-
-### How to log
-
-Use the `opencastle log` CLI to append events to `.opencastle/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):
+**Session** (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**):
+**Delegation** (Team Lead — 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 .opencastle/logs/events.ndjson`
 
-> **`model` and `tier` must reflect the delegated agent's assignment from the agent registry** — not the Team Lead's own model.
+> `model` and `tier` must reflect the delegated agent's assignment from the agent registry.
 
-**Fast review record** (Team Lead, **immediately after each fast review**):
+**Review** (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 .opencastle/logs/events.ndjson`
 
-**Panel record** (Panel runner, **immediately after each panel majority vote**):
+**Panel** (Panel runner — immediately after each panel 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 .opencastle/logs/events.ndjson`
 
-**Dispute record** (Team Lead, **immediately after each dispute**):
+**Dispute** (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 .opencastle/logs/events.ndjson`
 
-### Pre-Response Logging Checklist
+Verify any append: `tail -1 .opencastle/logs/events.ndjson`
 
-**STOP before responding to the user.** Verify each applicable item:
+## Pre-Response Checklist
 
-- [ ] **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
+**⛔ STOP.** Verify before responding — fix any missing log NOW.
 
-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.
+- [ ] **Lessons read** — `.opencastle/LESSONS-LEARNED.md` read at session start
+- [ ] **Lessons captured** — new lesson added via **self-improvement** if any retry occurred
+- [ ] **Discovered issues tracked** — pre-existing bugs added to `KNOWN-ISSUES.md` or tracker
+- [ ] **Lint/type/test pass** — no new errors after code changes
+- [ ] **Session logged** — `events.ndjson` has a `session` record (ALWAYS)
+- [ ] **Delegations logged** — `delegation` record per delegation (Team Lead)
+- [ ] **Reviews logged** — `review` record per fast review (if any)
+- [ ] **Panels logged** — `panel` record per panel vote (if any)
+- [ ] **Disputes logged** — `dispute` record per dispute (if any)
 
 ## 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 `.opencastle/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 `.opencastle/logs/events.ndjson` after every session using `opencastle log --type session ...`. No exceptions. This is Constitution rule #6 — a blocking gate, not optional.
+1. **Never delegate** — complete own work; document cross-domain needs in output contract.
+2. **Follow Discovered Issues Policy** — See [discovered-issues-policy](../../snippets/discovered-issues-policy.md).
+3. **Read and update lessons** — Read `.opencastle/LESSONS-LEARNED.md` before starting; add lessons after retries via **self-improvement** skill.
+4. **Log every session** — See [logging-mandatory](../../snippets/logging-mandatory.md).
 
 ## 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 `.opencastle/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** — `.opencastle/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)
+> Inherits: [base-output-contract](../../snippets/base-output-contract.md)