opencastle 0.7.0 → 0.8.1

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

@@ -123,7 +123,9 @@ CONFIDENCE: low | medium | high
 **Auto-PASS conditions (skip reviewer):**
 - The delegation was pure research/exploration with no code changes
 - The delegation only modified documentation files (`.md`)
-- All deterministic gates already passed AND the change is ≤10 lines across ≤2 files
+- All deterministic gates already passed AND the change is ≤10 lines across ≤2 files AND **no sensitive files were touched** (see validation-gates Gate 3 sensitive file list)
+
+> **Sensitive file override:** Changes to auth/middleware files, database migrations, RLS policies, security headers, CSP configuration, environment variable schemas, or CI/CD configuration **always** require a reviewer — even for 1-line changes. Auto-PASS never applies to these files.
 
 ### Step 4: Handle Verdict
 
@@ -247,14 +249,23 @@ Fast review sits between the agent's output and the Team Lead's acceptance:
 Agent completes work
        │
        ▼
-Deterministic checks (lint, test, build)  ← validation-gates Gate 1
+Secret Scanning                           ← validation-gates Gate 1
+       │
+       ▼
+Deterministic checks (lint, test, build)  ← validation-gates Gate 2
+       │
+       ▼
+Blast Radius Check                        ← validation-gates Gate 3
+       │
+       ▼
+Dependency Audit (if packages changed)    ← validation-gates Gate 4
        │
        ▼
-Fast Review (this skill)                  ← validation-gates Gate 1.5
+Fast Review (this skill)                  ← validation-gates Gate 5
        │
        ├── PASS → Accept, move to next task
        ├── FAIL → Retry loop (up to 2x)
-       └── 3x FAIL → Escalate to Panel (Gate 5)
+       └── 3x FAIL → Escalate to Panel (Gate 9)
 ```
 
 ### Relationship to on-post-delegate Hook

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

@@ -50,7 +50,7 @@ A lesson MUST be written when **any** of these triggers occur:
    echo '{"timestamp":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","agent":"Agent Name","model":"model-id","task":"Short description","outcome":"success","files_changed":N,"retries":0}' >> .github/customizations/logs/sessions.ndjson
    ```
 
-   This is **mandatory** — session logging fuels the metrics dashboard (`metrics-report` prompt).
+   This is **mandatory** — session logging fuels the observability dashboard (`npx opencastle dashboard`).
 
 ## How to Write a Lesson
 

package/src/orchestrator/skills/validation-gates/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: validation-gates
-description: "Shared validation gates for all orchestration workflows — deterministic checks, browser testing, cache management, regression checks. Referenced by prompt templates to maintain single source of truth."
+description: "Shared validation gates for all orchestration workflows — secret scanning, deterministic checks, blast radius analysis, dependency auditing, browser testing, cache management, regression checks, and final smoke tests. Referenced by prompt templates to maintain single source of truth."
 ---
 
 <!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .github/customizations/ directory instead. -->
@@ -9,7 +9,57 @@ description: "Shared validation gates for all orchestration workflows — determ
 
 Canonical reference for validation gates shared across all orchestration workflows. Prompt templates reference this skill to avoid duplication.
 
-## Gate 1: Deterministic Checks
+**Gate summary:**
+
+| Gate | Name | Runs When |
+|------|------|-----------|
+| 1 | Secret Scanning | Every delegation |
+| 2 | Deterministic Checks | Every delegation |
+| 3 | Blast Radius Check | Every delegation |
+| 4 | Dependency Audit | When `package.json` or lockfiles change |
+| 5 | Fast Review | Every delegation (with auto-PASS exceptions) |
+| 6 | Cache Clearing | Before browser testing |
+| 7 | Browser Testing | UI changes |
+| 8 | Regression Testing | Every delegation |
+| 9 | Panel Review | High-stakes changes only |
+| 10 | Final Smoke Test | Feature completion (after all tasks Done) |
+
+---
+
+## Gate 1: Secret Scanning
+
+> **HARD GATE — Constitution rule #1.** No tokens, keys, passwords, or connection strings in code, logs, commits, or terminal output.
+
+Scan every diff **before** any other gate. A secret leak caught after merge is exponentially more expensive than one caught at review time.
+
+### What to scan
+
+Run a regex scan of all changed files for patterns that match common secret formats:
+
+```bash
+# Scan staged/changed files for common secret patterns
+grep -rn -E '(AKIA[0-9A-Z]{16}|sk-[a-zA-Z0-9]{20,}|ghp_[a-zA-Z0-9]{36}|glpat-[a-zA-Z0-9\-]{20}|xox[bpors]-[a-zA-Z0-9\-]+|eyJ[a-zA-Z0-9]{10,}\.[a-zA-Z0-9]{10,}|-----BEGIN (RSA |EC |DSA )?PRIVATE KEY-----|mongodb(\+srv)?://[^\s]+|postgres(ql)?://[^\s]+|mysql://[^\s]+|redis://[^\s]+)' <changed-files>
+```
+
+Also check for:
+- Hardcoded `password`, `secret`, `api_key`, `apiKey`, `token` assignments (not just references)
+- `.env` file contents copied into source files
+- Base64-encoded secrets (common obfuscation attempt)
+
+### On detection
+
+- **BLOCK immediately** — do not proceed to Gate 2
+- Flag the specific file and line number
+- Re-delegate to the agent with explicit instruction to use environment variables instead
+- If a secret was already committed, **rotate it immediately** — git history is permanent
+
+### Exceptions
+
+- Test fixtures with obviously fake values (e.g., `sk-test-1234567890`)
+- Documentation examples with placeholder values (e.g., `YOUR_API_KEY_HERE`)
+- Pattern matches inside comments that are clearly explanatory
+
+## Gate 2: Deterministic Checks
 
 Run for every affected project (resolve exact commands via the **codebase-tool** skill):
 
@@ -19,31 +69,84 @@ Run for every affected project (resolve exact commands via the **codebase-tool**
 
 All must pass with zero errors. Run for **every** project that consumed modified files, not just the primary project.
 
-## Gate 1.5: Fast Review (MANDATORY)
+## Gate 3: Blast Radius Check
+
+Assess the scope of changes to catch scope creep and ensure reviewers can evaluate the diff effectively.
+
+### Thresholds
+
+| Metric | Normal | Warning | Escalate |
+|--------|--------|---------|----------|
+| Lines changed | ≤200 | 201–500 | >500 |
+| Files changed | ≤5 | 6–10 | >10 |
+| Projects affected | ≤1 | 2 | >2 |
+
+### Actions
+
+- **Normal** — proceed to Gate 4
+- **Warning** — log a note in the delegation record. Ask: *"Was this scope expected?"* If yes, proceed. If unexpected, investigate whether the agent drifted from the partition
+- **Escalate** — **STOP.** The Team Lead must review the diff before proceeding:
+  1. Verify all changed files are within the agent's assigned partition
+  2. Check whether the task should have been split into smaller subtasks
+  3. If scope creep: revert extra changes, re-delegate with tighter scope
+  4. If legitimately large: proceed, but **always run fast review** (no auto-PASS) and consider panel review
+
+### Sensitive files
+
+Changes to these file categories always trigger Warning regardless of line count:
+
+- Auth/middleware files (e.g., `middleware.ts`, `auth.ts`, `**/auth/**`)
+- Database migrations, RLS policies
+- Security headers, CSP configuration (`next.config.*`, `vercel.json`)
+- Environment variable schemas (`.env.example`, `env.ts`)
+- CI/CD configuration (`.github/workflows/**`)
+- Package manager configs (`package.json`, lockfiles) — also triggers Gate 4
+
+## Gate 4: Dependency Audit
+
+> Runs only when `package.json`, `yarn.lock`, `package-lock.json`, `pnpm-lock.yaml`, or similar lockfiles are modified.
+
+When agents add, remove, or update npm packages, verify:
+
+1. **Vulnerability scan** — Run `npm audit` (or the project's equivalent). No new `high` or `critical` vulnerabilities
+2. **License compatibility** — New packages must use MIT, Apache-2.0, BSD-2-Clause, BSD-3-Clause, or ISC licenses. Flag any copyleft (GPL, LGPL, AGPL) or proprietary licenses for human review
+3. **Bundle size impact** — For frontend packages, note the minified + gzipped size. Flag packages >50KB gzipped that have lighter alternatives
+4. **Duplicate functionality** — Check whether the new dependency overlaps with an existing one (e.g., adding `moment` when `date-fns` is already installed)
+5. **Maintenance health** — Flag packages with no updates in >2 years or <100 weekly downloads
+
+### On failure
+
+- **Vulnerability:** BLOCK. Re-delegate with instruction to use a patched version or alternative package
+- **License concern:** Flag for human review. Do not block, but document in the PR description
+- **Size/duplicate:** Flag as SHOULD-FIX in the fast review. Not blocking unless egregious (>200KB)
+
+## Gate 5: Fast Review (MANDATORY)
 
 > **HARD GATE:** Every agent delegation output must pass fast review before acceptance. This is non-negotiable — even for overnight/unattended runs. Load the **fast-review** skill for the full procedure.
 
-After deterministic checks (Gate 1) pass:
+After gates 1–4 pass:
 
 1. **Spawn a single reviewer sub-agent** with the review prompt from the fast-review skill
 2. **On PASS** — proceed to remaining gates
 3. **On FAIL** — re-delegate to the same agent with reviewer feedback (up to 2 retries)
-4. **On 3x FAIL** — escalate to panel review (Gate 5)
+4. **On 3x FAIL** — escalate to panel review (Gate 9)
 
 The reviewer validates: acceptance criteria met, file partition respected, no regressions, type safety, error handling, security basics, and edge cases.
 
 **Auto-PASS conditions** (skip the reviewer sub-agent):
 - Pure research/exploration with no code changes
 - Only `.md` files were modified
-- All deterministic gates passed AND the change is ≤10 lines across ≤2 files
+- All deterministic gates passed AND the change is ≤10 lines across ≤2 files AND **no sensitive files were touched** (see Gate 3 sensitive file list)
 
-## Gate 2: Cache Clearing (BEFORE Browser Testing)
+> **Sensitive file override:** If any changed file falls into the sensitive file categories listed in Gate 3 (auth, migrations, security headers, env schemas, CI/CD), auto-PASS is **never** applied — even for 1-line changes. These files always get a human-quality review.
+
+## Gate 6: Cache Clearing (BEFORE Browser Testing)
 
 **Always clear before testing.** Testing stale code wastes time and produces false results.
 
 Clear framework caches and task runner caches before starting the dev server for browser testing. See the **codebase-tool** skill for cache-clearing commands.
 
-## Gate 3: Browser Testing (MANDATORY for UI Changes)
+## Gate 7: Browser Testing (MANDATORY for UI Changes)
 
 > **HARD GATE:** A task with UI changes is NOT done until you have screenshots in Chrome proving the feature works. "The code looks correct" is not proof. "Tests pass" is not proof. Only a screenshot of the working UI in Chrome is proof.
 
@@ -59,7 +162,7 @@ Clear framework caches and task runner caches before starting the dev server for
 
 Load the **browser-testing** skill for Chrome MCP commands, breakpoint details, and reporting format.
 
-## Gate 4: Regression Testing
+## Gate 8: Regression Testing
 
 New features must not break existing functionality:
 
@@ -68,7 +171,7 @@ New features must not break existing functionality:
 3. **Verify navigation** — Ensure routing, links, and back-button behavior still work
 4. **Check shared components** — If a component from a shared library was modified, test it in all apps that consume it
 
-## Gate 5: Panel Review (High-Stakes Only)
+## Gate 9: Panel Review (High-Stakes Only)
 
 Use the **panel-majority-vote** skill for:
 
@@ -79,16 +182,50 @@ Use the **panel-majority-vote** skill for:
 
 If the panel returns BLOCK, extract MUST-FIX items, re-delegate to the same agent, and re-run the panel. Never skip, never halt. Max 3 attempts, then escalate to Architect.
 
+## Gate 10: Final Smoke Test (Feature-Level)
+
+> Runs once after ALL tasks in a feature are Done — not per-task.
+
+Individual tasks pass gates 1–9 independently. But the combined result may have integration issues that per-task testing misses. This gate verifies the feature as a cohesive unit.
+
+### Steps
+
+1. **Full build** — Build all affected projects from clean state (not incremental)
+2. **Full test suite** — Run tests across all projects that consumed any changed files
+3. **End-to-end browser walkthrough** — Navigate the complete user flow from start to finish:
+   - Verify all states: loading, empty, populated, error, partial
+   - Test every state transition end-to-end (not just individual screens)
+   - Confirm data flows correctly between pages/components
+   - Test the happy path AND at least one error path
+4. **Cross-task integration check** — Verify that outputs from different tasks (e.g., DB migration + component + page) compose correctly
+5. **Smoke test at all breakpoints** — If the feature has UI, one final responsive sweep
+
+### When to skip
+
+- Non-UI features with comprehensive test coverage (e.g., pure backend/data pipeline work where tests verify integration)
+- Single-task features (Gate 8 already covers regression)
+
+### On failure
+
+Re-delegate the specific failing integration point to the agent responsible for that layer. Do NOT re-run the entire feature implementation.
+
+---
+
 ## Universal Completion Checklist
 
 Use this checklist for any orchestration workflow:
 
-- [ ] Lint, test, and build pass for all affected projects
-- [ ] **Fast review passed** (mandatory — load **fast-review** skill)
-- [ ] Dev server started with **clean cache** (clear framework + task runner caches — see the **codebase-tool** skill)
-- [ ] UI changes verified in Chrome with screenshots at all breakpoints
+- [ ] **No secrets in diff** (Gate 1)
+- [ ] Lint, test, and build pass for all affected projects (Gate 2)
+- [ ] Blast radius assessed — scope is expected (Gate 3)
+- [ ] Dependency audit passed if packages changed (Gate 4)
+- [ ] **Fast review passed** (mandatory — load **fast-review** skill) (Gate 5)
+- [ ] Dev server started with **clean cache** (Gate 6)
+- [ ] UI changes verified in Chrome with screenshots at all breakpoints (Gate 7)
 - [ ] Every acceptance criteria item visually confirmed — not just "page loads"
-- [ ] No regressions in adjacent functionality
+- [ ] No regressions in adjacent functionality (Gate 8)
+- [ ] Panel review passed for high-stakes changes (Gate 9)
+- [ ] **Final smoke test passed** for multi-task features (Gate 10)
 - [ ] Shared code changes tested across all consuming apps
 - [ ] No duplicated code — shared logic extracted to libraries
 - [ ] Lessons learned captured if any retries occurred

package/src/orchestrator/prompts/metrics-report.prompt.md

@@ -1,144 +0,0 @@
----
-description: 'Collect and report metrics from agent logs, GitHub PRs, tracker issues, and deployments'
-agent: Researcher
----
-
-<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .github/customizations/ directory instead. -->
-
-# Metrics Report
-
-Generate a comprehensive metrics dashboard from all project data sources.
-
-## Data Sources
-
-Collect data from ALL of these sources. Run collections in parallel where possible.
-
-### 1. Agent Session Logs (local)
-
-Read `.github/customizations/logs/sessions.ndjson` and `.github/customizations/logs/delegations.ndjson`.
-
-Compute:
-- **Total sessions** and **sessions per agent**
-- **Success rate** — `outcome` field breakdown (success / partial / failed)
-- **Retries per session** — average and total
-- **Lessons added** — count and which agents contribute most
-- **Delegation stats** — mechanism (sub-agent vs background), tier distribution, success rate per agent
-- **Model usage** — which models used how often
-- **Activity timeline** — sessions per day/week
-
-### 2. GitHub PRs and Commits
-
-Use `gh` CLI commands (always prefix with `GH_PAGER=cat`):
-
-```bash
-# All PRs (open + closed + merged)
-GH_PAGER=cat gh pr list --state all --limit 100 --json number,title,state,createdAt,mergedAt,closedAt,author,additions,deletions,changedFiles,labels,headRefName
-
-# Recent commits on main
-GH_PAGER=cat gh api repos/{owner}/{repo}/commits --paginate -q '.[0:50] | .[] | {sha: .sha[0:7], date: .commit.author.date, message: .commit.message}' 2>/dev/null || git --no-pager log main --oneline -50
-```
-
-Compute:
-- **PR count** — total, open, merged, closed-without-merge 
-- **Merge rate** — merged / (merged + closed-without-merge)
-- **Time to merge** — median and average (createdAt → mergedAt)
-- **PR size** — average additions, deletions, changedFiles
-- **Commit frequency** — commits per day/week on main
-- **Bogus/closed PRs** — PRs closed without merge (potential failed agent work)
-
-### 3. Tracker Issues
-
-Use tracker MCP tools (`list_issues`, `search_issues`):
-
-```
-list_issues with status filter for each state: Backlog, Todo, In Progress, Done, Cancelled
-```
-
-Compute:
-- **Issue count by status** — Backlog, Todo, In Progress, Done, Cancelled
-- **Completion rate** — Done / (Done + Cancelled + In Progress + Todo)
-- **Issues by label** — which areas have the most work
-- **Issues by priority** — distribution across Urgent/High/Medium/Low
-- **Cycle time** — average time from In Progress → Done (if dates available)
-- **Stale issues** — In Progress for >7 days without updates
-
-### 4. Deployments
-
-Use deployment platform tools (if available via MCP or CLI):
-
-Query deployments for all configured apps (see `project.instructions.md` for the app inventory).
-
-Compute:
-- **Total deployments** — count over last 30 days
-- **Deployment success rate** — ready / (ready + error + cancelled)
-- **Failure rate** — error / total
-- **Build times** — average, median, p95
-- **Deployments per day** — activity timeline
-- **Failed deployment details** — which commits/branches failed and why
-
-### 5. Panel Reviews (local)
-
-Read `.github/customizations/logs/panels.ndjson`.
-
-Compute:
-- **Total reviews** — count of panel runs
-- **Pass rate** — pass / total
-- **Must-fix vs should-fix** — average counts per review
-- **Retry rate** — reviews with attempt > 1
-- **Model usage** — which reviewer models used
-- **Reviews by panel key** — what gets reviewed most
-
-### 6. Agent Failures (DLQ)
-
-Read `.github/customizations/AGENT-FAILURES.md`.
-
-Compute:
-- **Total failures** — count of DLQ entries
-- **Failures by agent** — which agents fail most
-- **Failure status** — pending vs resolved
-- **Common root causes** — categorize failure reasons
-
-## Report Format
-
-Present the report as a structured markdown summary with these sections:
-
-```markdown
-# Project Metrics Dashboard
-> Generated: {date}  |  Period: Last 30 days
-
-## Executive Summary
-- X agent sessions, Y% success rate
-- Z PRs merged, W% merge rate  
-- N deployments, M% success rate
-- P tracker issues completed
-
-## Agent Activity
-{sessions table, success rates, model usage}
-
-## Delegation Performance  
-{per-agent delegation stats, tier distribution}
-
-## GitHub
-{PR stats, merge rates, commit frequency}
-
-## Task Board
-{issue distribution, completion rate, stale issues}
-
-## Deployments
-{success rate, failure rate, build times}
-
-## Panel Reviews
-{pass rate, retry rate, must-fix/should-fix stats}
-
-## Agent Failures (DLQ)
-{failure count, pending items}
-
-## Trends & Recommendations
-{observations, areas for improvement}
-```
-
-## Usage
-
-Run this prompt periodically (weekly recommended) to track project health. Compare with previous reports to identify trends.
-
-If session logs are empty (no data yet), still collect GitHub/tracker/deployment data and note that agent logging has just been enabled.