opencastle 0.10.7 → 0.12.0

package/src/orchestrator/instructions/general.instructions.md

@@ -13,7 +13,7 @@ applyTo: '**'
 3. **Leave code better than you found it** — fix adjacent issues when the cost is low.
 4. **Fail visibly** — surface errors clearly; never swallow exceptions silently.
 5. **Verify, don't trust** — confirm outcomes with tools (tests, lint, build) rather than assuming success.
-6. **Log every session** — append observability records to `.github/customizations/logs/` before yielding to the user. No exceptions. See § Observability Logging below.
+6. **Log every session** — append observability records to `.github/customizations/logs/` before yielding to the user. No exceptions. Load the **observability-logging** skill for details.
 
 ## Instruction Priority Hierarchy
 
@@ -66,40 +66,6 @@ Before starting multi-step work, decompose it into individually verifiable tasks
 - **Browser testing mandatory** for any UI change — verified at responsive breakpoints defined in `testing-config.md`
 - Load the **testing-workflow** skill for test patterns and the **browser-testing** skill for E2E automation
 
-## 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
-
 ## Build & Task Commands
 
 Use the project's configured task runner for all build, test, lint, and serve commands. **Never invoke test runners or linters directly** — always use the task runner wrapper.
@@ -120,182 +86,70 @@ Follow markdown formatting and documentation standards when writing docs. For te
 
 ## AI Optimization
 
-Follow prompt caching and batch processing best practices. See [AI Optimization Guide](ai-optimization.instructions.md) for details.
-
-## Discovered Issues Policy
+See [ai-optimization.instructions.md](ai-optimization.instructions.md) for batch processing, tool efficiency, and anti-patterns.
 
-> **⛔ 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.
+## Project Context
 
-Never assume a pre-existing issue is somebody else's problem. If it's not tracked, track it.
+For project-specific context (apps, libraries, tech stack, ports, URLs), see [project.instructions.md](../customizations/project.instructions.md).
 
-## Task Tracking
+## Git Workflow
 
-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.
+**NEVER commit or push directly to the `main` branch.** All changes go through a feature/fix branch and a pull request. Load the **git-workflow** skill for branch naming, PR rules, and the Delivery Outcome checklist.
 
-### When Task Tracker MCP Tools Are Unavailable
+## Discovered Issues Policy
 
-If task tracker MCP tools are not available in the current session, do NOT block on issue creation. Instead:
+> **⛔ No issue gets ignored.** Untracked bugs discovered during work are a quality gate failure.
 
-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
+When you encounter a bug unrelated to the current task: check if already tracked in `KNOWN-ISSUES.md` or the task tracker. If NOT tracked, track it (known issue entry or bug ticket). Never assume a pre-existing issue is somebody else's problem. See the **git-workflow** skill for the full procedure.
 
-## Observability Logging (Mandatory)
+## Observability Logging
 
 > **⛔ 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 | Who appends | When | Example command below |
-|------|------------|------|----------------------|
-| `sessions.ndjson` | **All agents** | After every session — always | ✅ |
-| `delegations.ndjson` | **Team Lead** | After each delegation to a specialist agent | ✅ |
-| `reviews.ndjson` | **Team Lead** (via fast-review skill) | After each fast review | ✅ |
-| `panels.ndjson` | **Panel runner** (via panel majority vote skill) | After each majority-vote review | ✅ |
-| `disputes.ndjson` | **Team Lead** (via dispute protocol) | After each dispute record | ✅ |
-
-See `.github/customizations/logs/README.md` for the full schema of each record.
-
-### How to log
-
-Append one JSON line per task using `echo '...' >> <file>`. 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):
-```bash
-echo '{"timestamp":"2026-03-01T14:00:00Z","agent":"Developer","model":"claude-opus-4-6","task":"Fix login redirect bug","outcome":"success","duration_min":15,"files_changed":3,"retries":0,"lessons_added":[],"discoveries":[]}' >> .github/customizations/logs/sessions.ndjson
-```
-
-**Delegation record** (Team Lead only, **immediately after each delegation — not at session end**):
-```bash
-echo '{"timestamp":"2026-03-01T14:00:00Z","session_id":"feat/prj-57","agent":"Developer","model":"gemini-3.1-pro","tier":"standard","mechanism":"sub-agent","tracker_issue":"PRJ-57","outcome":"success","retries":0,"phase":2,"file_partition":["src/components/"]}' >> .github/customizations/logs/delegations.ndjson
-```
-Verify: `tail -1 .github/customizations/logs/delegations.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**):
-```bash
-echo '{"timestamp":"2026-03-01T14: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}' >> .github/customizations/logs/reviews.ndjson
-```
-Verify: `tail -1 .github/customizations/logs/reviews.ndjson`
-
-**Panel record** (Panel runner, **immediately after each panel majority vote**):
-```bash
-echo '{"timestamp":"2026-03-01T15:00:00Z","panel_key":"auth-review","verdict":"pass","pass_count":2,"block_count":1,"must_fix":0,"should_fix":3,"reviewer_model":"claude-opus-4-6","weighted":false,"attempt":1,"tracker_issue":"PRJ-42","artifacts_count":5}' >> .github/customizations/logs/panels.ndjson
-```
-Verify: `tail -1 .github/customizations/logs/panels.ndjson`
-
-**Dispute record** (Team Lead, **immediately after each dispute**):
-```bash
-echo '{"timestamp":"2026-03-01T16:00:00Z","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,"est_tokens_spent":120000,"status":"pending","resolution_option_chosen":null,"resolved_at":null}' >> .github/customizations/logs/disputes.ndjson
-```
-Verify: `tail -1 .github/customizations/logs/disputes.ndjson`
-
-### Pre-Response Logging Checklist
-
-**STOP before responding to the user.** Verify each applicable item:
-
-- [ ] **Session logged** — `sessions.ndjson` has a new line for this session (ALWAYS required)
-- [ ] **Delegations logged** — `delegations.ndjson` has a line for **each** delegation (Team Lead only). Count delegations → count records → must match
-- [ ] **Reviews logged** — `reviews.ndjson` has a line for **each** fast review performed. Count reviews → count records → must match
-- [ ] **Panels logged** — `panels.ndjson` has a line for **each** panel review performed. Count panels → count records → must match
-- [ ] **Disputes logged** — `disputes.ndjson` has a line for **each** dispute created. Count disputes → count records → must match
-
-If ANY required log is missing, append it 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.
+**Every agent MUST log every session** to `.github/customizations/logs/events.ndjson`. No exceptions. No threshold. No "too small to log." Load the **observability-logging** skill for CLI commands, record schemas, and the full logging checklist.
 
 ## Self-Improvement Protocol
 
 > **⛔ HARD GATE — Lessons are the team's collective memory. Skipping them causes repeated failures.**
 
-**Every agent must learn from mistakes and share knowledge.** This prevents the same pitfalls from being repeated across sessions.
-
 1. **Before starting work:** Read `.github/customizations/LESSONS-LEARNED.md` — apply relevant lessons proactively. This is NOT optional.
-2. **During execution:** If any of these triggers occur, **immediately** add a lesson entry to `.github/customizations/LESSONS-LEARNED.md`:
-   - Retry with different approach that works
-   - Tool call fails unexpectedly (discover correct parameter format)
-   - Workaround needed for platform limitation
-   - Docs are misleading (reality differs from documentation)
-   - Configuration surprise (default behavior differs from expectation)
-   - Error message is unhelpful (real cause was something else)
-3. **Update source files:** If the lesson reveals a gap in instruction/skill files, update those files too
-4. **Update instructions:** Proactively suggest updates to `.github/instructions/` or `.github/skills/` files when:
-   - The user had to intervene or correct the agent's approach
-   - Multiple back-and-forth attempts were needed to get something right
-   - A change touched files you wouldn't have guessed from the task description
-   - Something worked differently than expected (API quirk, tool behavior, config side-effect)
-   - A recurring pattern should be codified (workaround, convention, tool quirk)
-
-   **When NOT to update:** Don't add obvious patterns, standard practices, or things easily discoverable by reading a few files. Instruction files capture *tribal knowledge* — what isn't obvious from the code.
-
-For the full protocol, load the **self-improvement** skill.
-
-## Project Context
-
-For project-specific context (apps, libraries, tech stack, ports, URLs), see [project.instructions.md](../customizations/project.instructions.md).
+2. **During execution:** If you retry with a different approach and it works, use the **self-improvement** skill to add a lesson immediately.
+3. **Update source files:** If the lesson reveals a gap in instruction/skill files, update those files too.
 
 ## 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 § Discovered Issues Policy above).
-3. **Read and update lessons** — Read `.github/customizations/LESSONS-LEARNED.md` before starting. If you retry anything with a different approach that works, add a lesson immediately.
-4. **Log every session** — Append to `.github/customizations/logs/sessions.ndjson` after every session. No exceptions. See § Observability Logging above. This is Constitution rule #6 — a blocking gate, not optional.
-
-## Base Output Contract
+1. **Never delegate** — Specialist agents complete their own work and return results. Never invoke the Team Lead or spawn sub-agents.
+2. **Follow the Discovered Issues Policy** — Track any pre-existing bugs found during your work (see above).
+3. **Read and update lessons** — See Self-Improvement Protocol above.
+4. **Log every session** — See Observability Logging above. This is Constitution rule #6 — a blocking gate, not optional.
 
-Every specialist agent's Output Contract MUST end with these standard items (in addition to domain-specific items above them):
+## Pre-Response Quality Gate
 
-- **Observability Logged** — Confirm ALL applicable log records were appended (Constitution rule #6):
-  - `sessions.ndjson` — ALWAYS (every agent, every session)
-  - `delegations.ndjson` — if delegations occurred (Team Lead only)
-  - `reviews.ndjson` — if fast reviews occurred
-  - `panels.ndjson` — if panel reviews occurred
-  - `disputes.ndjson` — 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
+> **⛔ STOP before responding to the user.** Run through this checklist. If ANY required item is missing, fix it NOW.
 
-Agents reference this contract with: `See **Base Output Contract** in general.instructions.md for the standard closing items.`
+- [ ] **Lessons read** — `LESSONS-LEARNED.md` was read at session start
+- [ ] **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 tracked (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 (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 (if any)
+- [ ] **Panels logged** — `events.ndjson` has a `panel` record for each panel review (if any)
 
-## Pre-Response Quality Gate
+Load the **observability-logging** skill for CLI commands, Base Output Contract, and detailed schemas.
 
-> **⛔ STOP before responding to the user.** Run through this checklist. If ANY required item is missing, fix it NOW.
+## Workflow & Governance Skills
 
-This is the single exit gate for every session. All items are mandatory unless marked conditional.
+These skills provide detailed procedures. Load when their phase is reached.
 
-- [ ] **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 to `LESSONS-LEARNED.md`
-- [ ] **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** — `sessions.ndjson` has a new line for this session (Constitution rule #6 — ALWAYS required)
-- [ ] **Delegations logged** — `delegations.ndjson` has a line for each delegation (Team Lead only)
-- [ ] **Reviews logged** — `reviews.ndjson` has a line for each fast review performed (if any)
-- [ ] **Panels logged** — `panels.ndjson` has a line for each panel review performed (if any)
-- [ ] **Disputes logged** — `disputes.ndjson` has a line for each dispute created (if any)
+| Concern | Skill |
+|---------|-------|
+| Branch naming, PR rules, delivery outcome, task tracking | **git-workflow** |
+| Log CLI commands, record schemas, output contracts | **observability-logging** |
+| Lesson writing CLI, categories, quality standards | **self-improvement** |
 
 <!-- End of Coding Standards -->

package/src/orchestrator/plugins/nx/SKILL.md

@@ -154,7 +154,7 @@ Before running any generator, complete these steps:
    - Read the error message carefully
    - Common causes: missing required options, invalid values, conflicting files, missing dependencies
    - Adjust options and retry
-   - Add a lesson to `.github/customizations/LESSONS-LEARNED.md` if the fix was non-obvious
+   - Use the **self-improvement** skill to add a lesson if the fix was non-obvious
 
 ### Phase 4: Post-Generation
 

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